> ## Documentation Index > Fetch the complete documentation index at: https://opentrain.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # CLI: Shared Job Context > Use opentrain manager commands to enter a live job with shared state, coordinate work safely, and leave a durable handoff. `opentrain manager` is the context-first command tree for managing an existing employer job. Root and manager help teach the operating protocol automatically, so a new agent session does not need a copied prompt or local memory file. ```bash theme={null} npm install -g @opentrain-ai/cli@0.11.0 opentrain manager help ``` Every command supports `--json`. Reads require `jobs:read`; mutations require `jobs:write` and canonical access to the exact job. Version 0.8.0 introduced `opentrain manager`; version 0.10.0 added the deterministic signals, typed-policy, and Job Operating Guide commands. Version 0.11.0 adds automatic synchronization, bounded polling, intents, proposals, scoped overlays, and the exact synchronized managed-message path. Confirm `npm view @opentrain-ai/cli version` reports 0.11.0 or later before using the complete workflow on this page. Also confirm `opentrain capabilities --json` reports `job_operations` as `available` for the target deployment. ## Enter and reconcile a job ```bash theme={null} opentrain manager context get --job-id --json opentrain manager context delta --job-id --since-revision 1842 --json opentrain manager person get --job-id --person-user-id --json opentrain manager sweep --job-id \ --expected-context-revision 1842 \ --idempotency-key sweep-job-session-page-1 \ --body-json '{"limit":100}' ``` Start with `context get` before deciding or acting. In a writable session, run `sweep` with that revision. If it returns `hasMore: true`, run the next page with the response's `contextRevision` and a new stable page key. When `hasMore` is false, fetch context again. A read-only session does not sweep. Continue a delta with `nextRevision` until its `hasMore` is false. The compact context response includes a bounded top-priority attention block, evaluator-health metadata, effective-policy summary, current claim ownership, and a Job Operating Guide digest. Use the dedicated reads when you need the full signal, policy, or guide payload: ```bash theme={null} opentrain manager signals list --job-id --json opentrain manager policies effective --job-id --json opentrain manager guide get --job-id --format markdown ``` Only active, fresh signals from active rules appear in the default priority feed. Incomplete or stale evaluator runs remain visible in context health; do not treat their findings as current actionable work. ## Let the CLI carry synchronization CLI 0.11.0 automatically carries one private server-issued session credential and the latest per-job delivery token across every covered command. You do not copy those values into flags or prompts. Each covered JSON response includes `sync` and `syncCoverage`. Inspect `sync.conflicts`, `sync.recommendations`, `sync.nextOperations`, and `sync.resyncRequired` before the next write. `syncCoverage.coverage` is one of: * `native` for a Job Operations command; * `bridged` for a job-resolvable messaging or LMS command; or * `none` with the reason that the operation did not refresh context. For durable continuity, set a stable agent identity in the runtime: ```bash theme={null} export OPENTRAIN_AGENT_INSTANCE="project-manager-west" opentrain manager context get --job-id --json ``` Paseo supplies `PASEO_AGENT_ID` automatically. If neither variable exists, the CLI deliberately remains ephemeral instead of sharing one agent's private state through a working directory. State is stored with private permissions under `${XDG_STATE_HOME:-~/.local/state}/opentrain/job-ops-sync`. Deleting it only causes the next covered call to bootstrap from canonical OpenTrain state. Wait for a new shared-context delivery without rescanning every subsystem: ```bash theme={null} opentrain manager sync poll --job-id --wait-seconds 25 --json opentrain manager sync poll --job-id --watch --max-polls 20 --json ``` Watch mode is bounded and emits one JSON line per poll. A sync delivery helps the agent choose what to inspect; re-read the affected canonical record before acting. ## Investigate and claim an attention signal ```bash theme={null} opentrain manager signals get --job-id --signal-id --json opentrain manager signals claim --job-id --signal-id \ --expected-context-revision 1843 \ --expected-signal-revision 2 \ --idempotency-key investigate-lms-cohort-v1 \ --actor-agent-label claude-code:run-7 --lease-seconds 900 ``` Signal claim is the only operation that turns a deterministic finding into owned work. It atomically creates or reuses the linked coordination action and acquires its lease. Re-read the canonical evidence before deciding what the signal means: a repeated LMS failure can indicate unclear instructions, a difficult question, an assignment problem, or a real knowledge gap. The signal must be active and fresh, with effective triage `OPEN` or `ACKNOWLEDGED`. The CLI rejects stale, incomplete, live-snoozed, dismissed, and shadow-rule signals instead of creating duplicate or premature work. Acknowledging, snoozing, or dismissing is triage, not ownership: ```bash theme={null} opentrain manager signals acknowledge --job-id --signal-id \ --expected-context-revision 1844 --expected-signal-revision 2 \ --idempotency-key acknowledge-lms-cohort-v1 \ --reason 'Reviewed; awaiting updated source data' opentrain manager signals snooze --job-id --signal-id \ --expected-context-revision 1844 --expected-signal-revision 2 \ --idempotency-key snooze-lms-cohort-v1 \ --snooze-until 2026-08-29T16:00:00Z \ --reason 'Internal grader is completing the review' opentrain manager signals dismiss --job-id --signal-id \ --expected-context-revision 1844 --expected-signal-revision 2 \ --idempotency-key dismiss-lms-cohort-v1 \ --reason 'Canonical records confirm this occurrence is no longer relevant' ``` Only the deterministic evaluator clears the underlying condition. If evidence changes materially or the condition recurs, OpenTrain can reopen it as new work. ## Coordinate one action ```bash theme={null} opentrain manager actions list --job-id --status OPEN --json opentrain manager actions create --job-id \ --expected-context-revision 1843 \ --idempotency-key grade-joshua-attempt-3-create \ --body-json '{"title":"Grade Joshua attempt 3","priority":"HIGH","subjectPersonUserId":""}' opentrain manager actions claim --job-id --action-id \ --expected-context-revision 1844 \ --idempotency-key grade-joshua-attempt-3-claim \ --body-json '{"expectedActionRevision":0,"leaseSeconds":900,"actorAgentLabel":"claude-code:run-7"}' opentrain manager actions complete --job-id --action-id \ --expected-context-revision 1845 \ --idempotency-key grade-joshua-attempt-3-complete \ --body-json '{"expectedActionRevision":1,"claimReceipt":"","outcome":"Attempt 3 graded and canonical result verified"}' ``` Use `actions release` if you stop without completing the work. `actions cancel` closes obsolete work with an audited reason. A claim fails if its dependencies are incomplete or another unexpired claimant owns it. The revision numbers above are illustrative. Re-read context after every mutation; never increment a revision locally. `--body-json` and `--body-file` contain only operation-specific fields—keep the job ID, expected context revision, and idempotency key in their dedicated flags. Immediately before an outbound message or consequential canonical write, re-read the affected OpenTrain record and latest authorized conversation/thread. Shared context tells you what to inspect; it is not a replacement for that final check. ## Coordinate spontaneous work and disagreements Declare an intent before starting work that has no shared action yet: ```bash theme={null} opentrain manager intents declare --job-id \ --idempotency-key investigate-feather-access-v1 \ --kind OTHER --intent-key feather-access: \ --title "Investigate Feather access" \ --expected-context-revision 1845 --lease-seconds 900 opentrain manager intents list --job-id --status ACTIVE --json opentrain manager intents resolve --job-id --intent-id \ --idempotency-key investigate-feather-access-resolve-v1 \ --resolution COMPLETED --expected-intent-revision 1 ``` An overlapping declaration returns the live winner so another agent can avoid duplicate work. If a project manager wants to change the current workflow, record a non-enforced proposal instead of silently following a competing local plan: ```bash theme={null} opentrain manager proposals submit --job-id \ --idempotency-key training-gate-proposal-v1 \ --kind POLICY --dedupe-key training-production-gate \ --title "Move to completion-only training gate" \ --body "Use course completion instead of scored review." opentrain manager proposals list --job-id --status OPEN --json ``` Use `proposals review` or `proposals withdraw` with the returned exact revision. Accepting a proposal links separately authorized canonical work; it does not execute the policy, message, or assignment. Keep flexible guidance at the right scope: ```bash theme={null} opentrain manager overlays get --job-id --json opentrain manager overlays set --job-id \ --idempotency-key personal-finance-review-v1 \ --layer PERSONAL --expected-overlay-revision 0 \ --entries-json '[{"kind":"NOTE","statement":"Group blockers by lane"}]' ``` `TEAM` guidance is owner-controlled and shared. `PERSONAL` belongs to one manager. `SESSION` is one connection's scratch context. Overlays are attributed guidance only; they cannot change readiness, gates, or effective policies. For a managed message, use the fail-closed alias and include every guard field: ```bash theme={null} opentrain manager messages send --contract-id \ --content-file ./message.txt \ --idempotency-key worker-reminder-2026-08-28 \ --job-operations-job-id \ --job-operations-expected-context-revision 1845 \ --job-operations-action-id \ --job-operations-expected-action-revision 1 \ --job-operations-claim-receipt '' \ --job-operations-expected-latest-message-id ``` Use `--job-operations-expected-latest-message-id none` only when the authorized conversation was observed empty. The alias refuses to make a network request when any guard field is missing. The idempotency key must be 8–128 characters using letters, numbers, `.`, `_`, `:`, or `-`. This exact path requires both `messages:write` and `messages:manage`, resolves either an authorized Job Message or Proposal Message to its canonical job, and commits the message and context advance atomically. Ordinary `opentrain messages send` is intentionally unsynchronized and should not be used for claimed shared-job work. ## Record durable operating context ```bash theme={null} opentrain manager brief publish --job-id \ --expected-context-revision 1846 --idempotency-key brief-revision-7 \ --body-file ./brief.json opentrain manager decisions list --job-id --json opentrain manager decisions record --job-id \ --expected-context-revision 1847 --idempotency-key manual-pass-kevin-v1 \ --body-file ./decision.json opentrain manager observations list --job-id \ --subject-person-user-id --json opentrain manager observations record --job-id \ --expected-context-revision 1848 --idempotency-key slack-readback-2026-08-28 \ --body-file ./observation.json opentrain manager checkpoint --job-id \ --expected-context-revision 1849 --idempotency-key checkpoint-session-7 \ --body-json '{"acknowledgedRevision":1849,"actorAgentLabel":"claude-code:run-7"}' opentrain manager handoff --job-id \ --expected-context-revision 1849 --idempotency-key handoff-session-7 \ --body-file ./handoff.json ``` Briefs define the current objective and typed readiness workflow. Decisions preserve policies, manual judgments, and approved exceptions. List decisions and observations when historical rationale or supersession affects the work; the compact context is the current projection, not the complete history. Observations are only for typed external evidence, inference, or recommendations—never copy ordinary proposal, contract, identity, assessment, To-do, training, message, payment, or provider facts into an observation. Use the typed policy commands when a rule governs job-wide workflow or agent behavior: ```bash theme={null} opentrain manager policies list --job-id --json opentrain manager policies record --job-id \ --expected-context-revision 1850 \ --idempotency-key training-gate-completion-v2 \ --body-file ./typed-policy.json opentrain manager policies verify-enforcement --job-id \ --expected-context-revision 1851 \ --idempotency-key verify-training-gate-v2 \ --body-file ./policy-enforcement.json ``` A policy record identifies its human approver, recording user, recording agent, enforcement target, and the exact active policy decision it supersedes. `GUIDE` with status `APPLIED` means the rule was published in the shared guide; it does not mean a runtime subsystem enforces it. The `TRAINING_PRODUCTION_GATE` v1 payload accepts only `schemaVersion` and `basis`. Use an attributed `OPERATING_RULE.first-production-task-limit` guide policy for a one-task-then-stop instruction. After a policy change, fetch context and `manager guide get` again and verify the new context revision and guide checksum. The generated guide is the shared `AGENTS.md`-equivalent for the job, but canonical records and effective typed policies remain authoritative. ## Conflict recovery If a command returns a stale context or action revision: 1. Run `manager context get` again. 2. Re-read the affected canonical resource. 3. Decide whether the intended action is still correct. 4. Retry only with the new revision and a key that represents that deliberate intent. Do not substitute `--force` or blind retries for reconciliation. See the [HTTP reference](/docs/developers/api-reference/job-operations/overview) and [operating guide](/docs/developers/guides/manage-live-jobs-with-shared-context).