dispatch-cli

The human dispatcher CLI for docs/plan/dispatch-production (and any other plan-state-machine dag.json). This is a published, npx-invocable command-line tool — package.json declares bin: { "dispatch-cli": "./dist/bin/cli.js" }, and npm run build compiles the hand-written bin/cli.ts fallback into the dist/bin/cli.js executable that ships with the package.

The CLI wraps src/api.ts, a plain, JSDoc'd TypeScript functions surface where all commands are defined. The published binary (dist/bin/cli.js) is the compiled-to-JavaScript version of bin/cli.ts, which is a hand-written Commander wrapper over the same api.ts contract.

Commands

| Command | Reads/writes | What it does | |---|---|---| | validate --dag-path <p> | read-only | @adhd/dispatch-base-spec's structural validator over the dag file. | | snapshot --dag-path <p> | read-only | Real DagClient + @adhd/dispatch-core-optimizer's snapshot(), cold-start B/context-window defaults. | | optimize --dag-path <p> | read-only | Snapshot + the greedy optimize() — the next batch of DispatchUnits that would be packed. | | eligible --dag-path <p> | read-only | DagClient.getEligibleMilestones() — milestone slugs whose deps are complete per dispatch_log. | | status --dag-path <p> | read-only | Per-milestone { status, loggedOperationIds, tokensEstimated, tokensActual }. A milestone whose sessioned task suspended for human input reports status: "awaiting_input" plus awaitingInput: { taskId, resumeToken } — resume it with agent-mcp's task_resume, then run a cycle, which reconciles the resumed task back into the DAG (re-runs the guard, marks the milestone complete — 48b14ec1). | | run --dag-path <p> [--dry-run] [--allow-fs <actions>] [--tools-root <path>] | writes the dag | Runs exactly one @adhd/dispatch-orchestrator scheduling cycle. | | agents import <dir> | writes the agent-mcp registry | Imports Claude Code subagent personas (*.md) via the real agent_create/agent_update. Stores no provider — an imported agent is un-welded from any provider, so a task with no session/global binding fails closed (NO_PROVIDER_SELECTED; bind one with session_update). The persona's model (e.g. sonnet, a Claude Code alias) is not written as a provider model; it is reported in the result's warnings. | | calibrate --model-tier <Haiku\|Sonnet\|Opus> | writes ~/.adhd/dispatch-calibration.json | Fires a null-task dispatch to measure a baseline per-tier token cost ("B"). |

Run the CLI

After installation and build, invoke the compiled binary directly:

npx dispatch-cli eligible --dag-path docs/plan/dispatch-production/dag.json

In development (in-repo), build the compiled binary first:

npx nx run dispatch-cli:build-bin
npx dispatch-cli eligible --dag-path docs/plan/dispatch-production/dag.json

Or use tsx directly against the hand-written bin/cli.ts fallback:

npx tsx --tsconfig tsconfig.base.json \
  bin/cli.ts \
  eligible --dag-path docs/plan/dispatch-production/dag.json

(No root tsconfig.json exists in this repo — --tsconfig tsconfig.base.json is required so tsx resolves @adhd/* workspace imports.)

The fail-closed fs.* permission gate — run --allow-fs / --tools-root

Breaking change (FEAT-DISPATCH-GOVERNANCE-001 / FEAT-DISPATCH-CAPFLOOR-002): run's @adhd/dispatch-orchestrator cycle can dispatch destructive filesystem tool-call ops (fs.move, fs.delete, fs.scaffold, and the surgical-edit fs.edit). Previously every one of these executed unconditionally the moment a dag.json scheduled it — regardless of --dry-run. As of this fix, run is fail-closed by default: an fs.move/fs.delete/fs.scaffold/fs.edit op is now denied with { ok: false, error: "... denied by policy ..." } (and the filesystem is never touched) unless its exact OperationAction is explicitly allowlisted.

• --allow-fs <actions> — comma-separated OperationAction values permitted to actually execute this cycle (e.g. --allow-fs fs.delete,fs.edit). Default: empty string, i.e. every destructive fs.* action is denied. An unknown action name is rejected up front (before the runner or filesystem are ever touched).
• --tools-root <path> — the filesystem root a relative fs.* path arg is resolved against. A path that would escape this root — by .., by an absolute path, or via an existing symlink whose real target lands outside it — is rejected as a failed op (escapes tools root …) and never executed; a path that resolves to the root itself is likewise refused, so fs.delete { path: '.', recursive: true } cannot wipe the root. (A dangling symlink under the root — one whose target does not exist yet — is a known, tracked residual, not part of this existing-target guarantee: see backlog item 64aa2b9b.) Default: process.cwd() — the directory dispatch-cli was invoked from, NOT the directory containing --dag-path's dag.json.

An existing consumer that relied on the prior unconditional-execution behavior will see previously-silent fs.* ops start failing with a denied by policy error the first time they run run after upgrading — pass --allow-fs (and, if the dag.json's fs.* paths are relative to something other than the invocation directory, --tools-root) to restore the intended effect under the new, explicit opt-in.

The paid boundary — run and calibrate

run's dryRun defaults to true (and anything other than the literal false is treated as true): the safe default wires MockAgentRunner — no network, no cost, fully deterministic. dryRun: false wires a real AgentMcpRunner that spawns npx -y @adhd/agent-mcp and fires real, billed model calls. calibrate always fires one real model call.

DAG agents must pre-exist — --no-dry-run fails AGENT_NOT_FOUND. The production runner (buildProductionAgentMcpRunner) defaults to createAgentsIfMissing: false: a run --no-dry-run whose DAG names an agent that is not registered (e.g. a persona imported and then agent_deleted) fails the run with AGENT_NOT_FOUND instead of silently re-creating the agent with an empty/default systemPrompt — so the run never dispatches under a different agent than the one the DAG named. calibrate is the sole caller that opts back in (createAgentsIfMissing: true, minting its synthetic null-task agent).

CLI implementation: bin/cli.ts (the hand-written fallback) uses Commander's native --no-dry-run negation, so it does reach the real paid path from the command line — proved by cli-smoke.e2e.test.ts's run --no-dry-run test. This is the CLI that ships (compiled to dist/bin/cli.js and executed via npx dispatch-cli).

Neither path is exercised by this package's default-running tests, which call the DI'd lib/core.ts functions directly with an injected MockAgentRunner and a calibration path under tmp/dispatch-cli/.

Environment variables

| Variable | Default | Effect | |---|---|---| | ADHD_AGENT_MCP_COMMAND | npx | Command that launches the agent-mcp child (and the dispatch self member). | | ADHD_AGENT_MCP_ARGS | -y @adhd/agent-mcp@latest | Whitespace-separated argv for that command. | | ADHD_AGENT_MCP_REQUEST_TIMEOUT_MS | the orchestrator poll budget | Per-call MCP request timeout (ms). |

Deprecated legacy names. ADHD_DISPATCH_AGENT_MCP_COMMAND, ADHD_DISPATCH_AGENT_MCP_ARGS and ADHD_DISPATCH_AGENT_MCP_REQUEST_TIMEOUT_MS are honoured for one release as a fallback (the ADHD_AGENT_MCP_* name always wins when both are set). Using any of them prints exactly one DEPRECATED warning to stderr (never stdout, which carries the CLI's JSON) naming the new variable; setting only the new names prints nothing. Proven by src/test/agent-mcp-env-rename.spec.ts (64e7ebe7 AC1/AC2).

Native tooling — declarative storage + task-time resolution (NAT-TOOL-5)

Every agent this host dispatches is STORED with only DECLARATIVE tooling (ADR-0008 D3/D4/D8): the explicit memory-server/backlog mcpServers plus a declarative nativeTooling ({fs?, shell?, dispatch?, hitl?}). The spawned agent-mcp child resolves nativeTooling at task time against its own cwd (threaded by the host, D9), so the SAME stored definition fired from /P then /Q yields fs root /P then /Q while the stored JSON stays byte-identical.

• resolveDispatchMcpServers({ env, explicit }) returns ONLY the explicit half — memory-server + backlog (+ any caller explicit); no fs/shell/dispatch, and no cwd. resolveDispatchNativeTooling({ nativeTooling }) returns the declarative config to store (default {fs:true, shell:true, dispatch:true}).
• buildProductionAgentMcpRunner(env, { cwd, nativeTooling }) threads the dispatching cwd to the spawned agent-mcp child and stores the declarative nativeTooling; it does not root fs/shell itself. The cwd follows --tools-root when given (the same cwd the orchestrator scopes relative fs.* ops to), else process.cwd().
• On reuse (ensureAgent of an already-registered agent), the runner performs NO write: the stored definition is never mutated, so a reused agent picks up the current cwd from the spawned child, not from a stale stored root.

Proven default-running and hermetically (real spawned agent-mcp, fake $HOME, temp registry DB, isolated cwd): src/test/resolve-dispatch-mcp-servers.spec.ts and src/test/dispatch-native-tooling.e2e.test.ts.

Self-enforcement — lane grants and duplicate runs

• validate refuses a milestone whose lane is not satisfied by its tool_grant (typed lane_tool_grant_unsatisfied — see @adhd/dispatch-base-spec).
• run (non-dry-run) takes a per-dag live-dispatch lock under the OS temp dir (adhd-dispatch-locks/<hash>.lock); a second run of the same dag while the first is live fails with DuplicateDispatchError before any unit is fired. A crashed run's lock is reclaimed once its pid is gone.

Building

Run nx build dispatch-cli to build the main library code. This does NOT compile the CLI binary — you must also run nx run dispatch-cli:build-bin to compile bin/cli.ts to JavaScript (dist/bin/cli.js), which is what gets published.

For a complete build (library + CLI binary):

npx nx run dispatch-cli:build-bin

The build-bin target depends on build, so it runs both automatically. This produces dist/bin/cli.js, which is declared as the bin entry in package.json and becomes the npx-invocable command when the package is published.

Running unit tests

Run nx test dispatch-cli to execute the unit tests via Vitest. This automatically builds and tests:

• The generated CLI (via generate-cli target)
• The compiled binary (via build-bin target) — the actual dist/bin/cli.js that ships with the package
• Smoke tests that spawn both CLI paths as child processes

Real end-to-end lifecycle test

src/test/integration/real-e2e.ts is a self-executing tsx script (NOT a Vitest spec — it lives outside src/**/*.{spec,test}.ts on purpose, so nx test dispatch-cli never picks it up) that drives the FULL docs/plan/dispatch-production product lifecycle through real components: a real DagClient + createJsonFileSerializer writing an actual dag.json under tmp/dispatch-cli/e2e/, @adhd/dispatch-core-optimizer's real snapshot()/optimize(), @adhd/dispatch-orchestrator's real orchestrateCycle(), and this package's own bin/cli.ts spawned as a real child process for every CLI-facing assertion. Eight required scenarios run by default (cold start, author, snapshot+optimize, dispatch, a second cycle, a guard failure, its correction, and a simulated process-resume) — deterministic and free, using MockAgentRunner as the sole test double (the agent-mcp task-runner boundary). Run it with:

npx nx build dispatch-cli && npx tsx --tsconfig tsconfig.base.json \
  entrypoint/dispatch-cli/src/test/integration/real-e2e.ts

It prints a per-scenario result table and exits 0 iff every required scenario passes.

Live e2e gate

One additional, fully independent scenario is gated behind DISPATCH_E2E_LIVE=1 and is skipped by default with a loud console notice. When enabled, it fires one real, billed agent-mcp dispatch (a claudecli-provider agent — i.e. whatever model the local claude CLI resolves to) through the real AgentMcpRunner (npx -y @adhd/agent-mcp), asks it to write a real file to disk, and verifies via a real shell guard (test -f <file>) that it did.

This is the repo's single legitimate env-gate exception (CLAUDE.md §6, "Live testing is mandatory" — a real model is a paid third-party service). The gate is disclosed here, in the test file's own header, and in the repo-root CLAUDE.md:

• Gate: DISPATCH_E2E_LIVE=1
• Approved by (named owner): the repo owner/maintainer, git user pseudosky ([email protected])
• Cost/requirement: real money/quota per run; requires local claude auth status to already be configured (no API key needed — claudecli drives the local Claude Code CLI directly, it is not gated on an Anthropic API key)

Run it explicitly with:

DISPATCH_E2E_LIVE=1 npx tsx --tsconfig tsconfig.base.json \
  entrypoint/dispatch-cli/src/test/integration/real-e2e.ts

Live five-AC e2e suite (live-dispatch-five-acs.e2e.test.ts)

A second, independent live suite (src/test/integration/live-dispatch-five-acs.e2e.test.ts) drives the real dispatch stack across the real MCP boundary against a real model to prove five acceptance criteria that no real-model run had exercised: fa9d3079 (dag.session_id end-to-end), 03145a46 (HITL reachable from dispatch), 5339c2e5 (default budget cap), daafe2d3 (default memory-server really called), 4e829a08 (policy enforcement across a delegation chain).

• Gate: DISPATCH_E2E_LIVE=1
• Provider: DISPATCH_E2E_PROVIDER=claudecli (default), anthropic (OAuth via ADHD_AGENT_ANTHROPIC_SECRET; the function-tool provider whose tool advertisement makes AC2/AC5 reachable), or deepseek (ADHD_AGENT_DEEPSEEK_SECRET required). Both function-tool secrets live in ~/.adhd/.env; set -a; source ~/.adhd/.env; set +a before running.
• Negative controls: DISPATCH_E2E_NEGATIVE=1.
• Approved by (named owner): pseudosky ([email protected]) — the real model is a paid/external service, the single gate reason AGENTS.md §7 permits. The same record is in this package's AGENTS.md and in the test's own header.
• Fails loudly when enabled without the required credential/subscription.

# prerequisite: build the child agent-mcp the test spawns
npx nx run agent-mcp:dist-manifest

DISPATCH_E2E_LIVE=1 sh -c 'cd entrypoint/dispatch-cli && \
  npx vitest run --config vite.config.ts \
  src/test/integration/live-dispatch-five-acs.e2e.test.ts'

claudecli cannot be advertised agent-mcp's client-side pseudo-tools, so the HITL and delegation ACs require a function-tool provider (anthropic or deepseek) and are skipped under claudecli with a visible warning.

HITL on AC2 (03145a46) — reachable (implemented 2026-10-05). Under a function-tool provider the model really calls builtin__request_human_input and the child agent-mcp persists the task as awaiting_input with a resume_token. The dispatch pipeline now observes that suspension: AgentMcpRunner.fire() fires a sessioned unit in the background (background:true, taking the task id from the immediate { task_id, status: 'pending' } reply) so poll() sees awaiting_input instead of the MCP call blocking to its 60s deadline; the orchestrator parks the unit rather than failing it; and dispatch-cli status surfaces status: "awaiting_input" plus awaitingInput: { taskId, resumeToken }. Resume the task with agent-mcp's task_resume (that token) to drive the task to completed; the next run cycle then reconciles the completed task back into the DAG — re-runs the milestone guard and marks the milestone complete — so status stops reporting awaiting_input (48b14ec1). AC2 asserts this status surface directly and resumes through the real MCP boundary (live-verified 2026-10-05 under DISPATCH_E2E_PROVIDER=deepseek; anthropic is also a function-tool provider).

Guarded live runner (run-live-guarded.ts)

src/test/integration/run-live-guarded.ts wraps a real dispatch-through-a-real- agent-mcp run with hard, mechanical guards so a live test can never run away. It is a self-executing script (not collected by Vitest), reusing the same real substrate as the five-AC suite, and is the harness a later authorized live test drives. It runs two scenarios — a guarded smoke dispatch and a guarded delegation (a dispatched agent really calls agent-mcp__agent to spawn a child) — under the guards below.

• Gate: DISPATCH_E2E_LIVE=1 (loud notice + exit 0 otherwise; never a silent skip). Real, billed model call — the single AGENTS.md §7 gate reason.
• Approved by (named owner): pseudosky ([email protected]). Recorded here, in this package's AGENTS.md, and in the script's own header.
• Provider: DISPATCH_E2E_PROVIDER=deepseek (default; needs ADHD_AGENT_DEEPSEEK_SECRET), anthropic (ADHD_AGENT_ANTHROPIC_SECRET), or claudecli (the claude CLI's OAuth). Secrets live in ~/.adhd/.env; set -a; source ~/.adhd/.env; set +a before running.
• Fails loudly when enabled without the credential / built agent-mcp::dist-manifest / memory-stub prerequisite.

Guards (all env-overridable; defaults are the guardrails):

| Guard | Env | Default | Behaviour | |---|---|---|---| | Strict turn count | DISPATCH_E2E_MAX_TURNS | 12 | Baked into every agent (maxToolLoops) and the child (ADHD_AGENT_BUDGET_MAX_CALLS, a global model-call cap); asserted post-run (Σ model_calls ≤ cap). | | Cost kill | DISPATCH_E2E_MAX_COST_USD | 0.10 | Polls Σ task_usage.est_cost_usd every DISPATCH_E2E_POLL_MS; hard-kills (closes the spawned agent-mcp, exits non-zero) the moment spend exceeds the cap. Fails loudly if cost is unpriceable (NULL) and no proxy meters it. | | Message-size protection | DISPATCH_E2E_MAX_MSG_BYTES | 262144 | Polls the largest single stored message byte-length; kills if exceeded. | | Proxy | DISPATCH_E2E_PROXY | unset | Routes the provider baseURL + child HTTP(S)_PROXY through a proxy so API calls can be metered/blocked. When unset, the runner says so and relies on the cost + message-size guards. | | Poll interval | DISPATCH_E2E_POLL_MS | 1000 | Monitor cadence (floored at 100 ms). | | Scenario | DISPATCH_E2E_SCENARIO | all | all | dispatch | delegation. |

# prerequisite: build the child agent-mcp the runner spawns
npx nx run agent-mcp:dist-manifest
set -a; source ~/.adhd/.env; set +a

DISPATCH_E2E_LIVE=1 npx tsx --tsconfig tsconfig.base.json \
  entrypoint/dispatch-cli/src/test/integration/run-live-guarded.ts

# prove the KILL fires (a cap of 0 breaches on the first priced turn)
DISPATCH_E2E_LIVE=1 DISPATCH_E2E_MAX_COST_USD=0 DISPATCH_E2E_POLL_MS=100 \
  DISPATCH_E2E_SCENARIO=delegation npx tsx --tsconfig tsconfig.base.json \
  entrypoint/dispatch-cli/src/test/integration/run-live-guarded.ts
# exits non-zero, prints [GUARD-KILL:cost-exceeded] with the observed cost.

The delegation scenario requires a function-tool provider (deepseek/anthropic) and reports a loud SKIP under claudecli.