nexus

When several tasks must be done and you want proof that each one was done, the Nexus agent can keep them in a durable run. The nexus command is that run’s ledger. You describe the tasks in a JSON plan; each task owns a folder or file it may write (its scope), and a list of check commands that decide whether its result is acceptable. The ledger records who tried what (an attempt), keeps the state across crashes, runs the checks itself, and only then lets you accept the task. A worker saying “done” is never evidence: the checks are. This page is for people who drive Nexus by hand, from CI, or who want to know what the agent does under the hood.

Synopsis#

npx bmad-plus nexus create --plan <file> [--json] [-d <path>]
npx bmad-plus nexus inspect [run] [--json] [-d <path>]
npx bmad-plus nexus recover-lock --input <file> [--json] [-d <path>]
npx bmad-plus nexus <start|launch|collect|record|reconcile|verify|retry|cancel|accept> <run> <task> [--input <file>] [--json] [-d <path>]

The actions#

Execution, verification, acceptance#

Nexus keeps three questions apart. Execution: did the worker finish? A host reports it with record, or the foreground supervisor collects the real exit of the process it started. Verification: does the work pass the plan’s checks? Nexus runs them itself, with literal arguments and no shell, and compares the declared artifacts and the whole write scope before and after. Acceptance: is the current workspace still the one that passed? accept rechecks artifact hashes, protected resources and the accepted state of every dependency. A failed check prevents acceptance even if the worker succeeded. Nexus never commits, merges, copies files or deploys.

The plan file#

{
  "id": "example",
  "maxParallel": 1,
  "config": { "language": "English" },
  "tasks": [
    {
      "id": "result",
      "objective": "Produce the requested result in work/result.txt.",
      "acceptance": ["The result satisfies the independent check."],
      "dependsOn": [],
      "scope": ["work"],
      "artifacts": ["work/result.txt"],
      "resources": ["checks/check-result.cjs"],
      "checks": [
        {
          "id": "result-content",
          "command": "node",
          "args": ["checks/check-result.cjs"],
          "cwd": ".",
          "timeoutMs": 30000
        }
      ],
      "maxAttempts": 2,
      "deadlineMs": 3600000,
      "idempotent": true,
      "authorizations": ["Edit work/ and run the listed local check."]
    }
  ]
}

Backends: host or process#

By default a task is host-owned: your assistant does the work with its own tools, and tells Nexus the outcome with record. Nexus then verifies. Adding an execution object to a task makes it a process task instead: launch starts the program in the foreground, waits for it, and stores a checksummed receipt of what really happened. There are two adapters.

Limits#

What it reads and writes#

• State: .bmad-plus/nexus/runs/<run-id>.json, a checksummed envelope written through a flushed temporary file and an atomic rename.
• Locks: .bmad-plus/nexus/writer.lock (one mutation at a time) and, during an exceptional recovery, .bmad-plus/nexus/recovery.lock. A removed lock is archived under .bmad-plus/nexus/lock-recovery/.
• inspect writes nothing and keeps working while a verification runs. All other actions except create change an existing run; create makes it.
• Reads your plan and input files, the declared resources and artifacts, and snapshots the write scopes. Verification runs your check commands; launch runs the task’s process. Those are the only processes Nexus starts, and only when you invoke them.
• Check commands get a minimal environment (PATH, SYSTEMROOT, WINDIR, TEMP, TMP, TMPDIR plus fixed locale C and timezone UTC). Credentials and NODE_OPTIONS are not forwarded. Put no secret in arguments or in output.

Exit codes#

Reading the output#

The shortest complete run needs three small files next to nexus-plan.json. The verifier is the one the plan declares as a resource; host.json is the identity your assistant gives to start; rec.json is the outcome it reports to record, with the attempt id that start printed.

const fs = require("node:fs");
const text = fs.readFileSync("work/result.txt", "utf8");
if (!text.includes("done")) {
  console.error("work/result.txt must contain done");
  process.exit(1);
}

{ "backend": { "kind": "host", "id": "my-assistant", "sessionId": "session-1" } }

{
  "attemptId": "c3bbafd1-62ef-4b8b-ac72-0d9b09932427",
  "backend": { "kind": "host", "id": "my-assistant", "sessionId": "session-1" },
  "outcome": "completed",
  "summary": "Wrote work/result.txt."
}

$ npx bmad-plus nexus create --plan nexus-plan.json
Nexus run example — durable task coordination
result: not started; verification=pending; acceptance=pending
Use inspect --json for recorded evidence and reconciliation observations.
$ npx bmad-plus nexus start example result --input host.json
Nexus run example — durable task coordination
result: running; verification=pending; acceptance=pending
  Attempt: c3bbafd1-62ef-4b8b-ac72-0d9b09932427; host: my-assistant/session-1
Use inspect --json for recorded evidence and reconciliation observations.
$ npx bmad-plus nexus record example result --input rec.json
Nexus run example — durable task coordination
result: completed; verification=pending; acceptance=pending
  Attempt: c3bbafd1-62ef-4b8b-ac72-0d9b09932427; host: my-assistant/session-1
Use inspect --json for recorded evidence and reconciliation observations.
$ npx bmad-plus nexus verify example result
Nexus run example — durable task coordination
result: completed; verification=passed; acceptance=pending
  Attempt: c3bbafd1-62ef-4b8b-ac72-0d9b09932427; host: my-assistant/session-1
Use inspect --json for recorded evidence and reconciliation observations.
$ npx bmad-plus nexus accept example result
Nexus run example — durable task coordination
result: completed; verification=passed; acceptance=accepted
  Attempt: c3bbafd1-62ef-4b8b-ac72-0d9b09932427; host: my-assistant/session-1
Use inspect --json for recorded evidence and reconciliation observations.
$ npx bmad-plus nexus inspect example
Nexus run example — durable task coordination
result: completed; verification=passed; acceptance=accepted
  Attempt: c3bbafd1-62ef-4b8b-ac72-0d9b09932427; host: my-assistant/session-1
  Accept only after rechecking current artifacts and resources.
Use inspect --json for recorded evidence and reconciliation observations.
# The words after “acceptance=” and the extra hint lines depend on the run state; read them with inspect --json.

Running verify right after create is refused, because nothing has been recorded yet: Nexus: Nexus: Verification requires completed, unaccepted, reconciled work. Start and record first, as above. Note the doubled prefix: the runtime’s own messages already begin with Nexus:, and the command adds its own.

Each task line reads <task>: <execution>; verification=<status>; acceptance=<state>, followed by the last attempt with its backend. inspect --json adds, per task, resourcesCurrent, evidenceEligible, stale, staleReason and overdue, so an old accepted record cannot claim that files edited later still pass. In JSON mode, errors are printed as {"schemaVersion":1,"status":"error","error":"..."}.

Interruptions, cancellation, retries#

• An interrupted or disconnected attempt keeps its capacity until reconcile settles it. The observation needs ownerStopped: true, a statement from you that you checked, not telemetry. For a task that is not idempotent, a retry also needs retrySafe: true.
• cancel only records a request. For a host task, the host stops its own work; for a process task, only the original foreground supervisor may signal the child it created. Nexus never kills a saved PID.
• retry (or launch with {"retry":true}) opens a new attempt and consumes maxAttempts. A new backend session does not reset the limit.
• A verification that times out is recorded as ambiguous, because descendants of the check could still have effects. Inspect before retrying.
• recover-lock takes the exact lock hash from inspect, ownerStopped: true and a non-empty note. A live local writer blocks it. Age alone never authorises removal.

Errors and what to do#

Errors are printed as Nexus: <message> on the error stream. The runtime’s own messages already start with Nexus:, so most errors show the prefix twice (Nexus: Nexus: Run ID must use ...).

Examples#

Nexus, split the approved work into independent tasks, each with its own write folder and a check command I can run. Create a durable run with `bmad-plus nexus create`, start one attempt per task, and do not accept anything until `bmad-plus nexus verify` has passed for it.

Nexus, inspect the run `release-prep` with `bmad-plus nexus inspect release-prep --json`. Tell me which attempts are unresolved and what I must check before you reconcile them. Do not retry anything on your own.