Skip to main content
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.
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

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:
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:
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:
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

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:
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

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:
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:
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:
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:
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

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:
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 and operating guide.