@jr2/cli 0.4.1 → 0.5.1

package/src/commands/down.ts

@@ -1,7 +1,7 @@
-// `jr2 down [--all] [-n <ns>] [--context <ctx>]` (ADR-0019): remove the instance from the cluster —
-// its namespace and everything `jr2 up` converged into it. ALWAYS confirms (deleting a namespace
-// takes the runs, the store PVC, the Instance Harness's conversations PVC (ADR-0031), and every
-// live Sandbox with it). `--all` also uninstalls the
+// `jr2 down [--all] [--yes] [-n <ns>] [--context <ctx>]` (ADR-0019): remove the instance from the
+// cluster — its namespace and everything `jr2 up` converged into it. Confirms unless `--yes`
+// (deleting a namespace takes the runs, the store PVC, the Instance Harness's conversations PVC
+// (ADR-0031), and every live Sandbox with it). `--all` also uninstalls the
 // per-cluster operator — only sane when this was the cluster's last instance, which is the
 // caller's judgment, not derivable here.
 //
@@ -22,27 +22,17 @@
 // bounded by the node's disk; on kind they live inside the node container and go with the cluster.
 
 import { basename } from "node:path";
-import { parseArgs } from "node:util";
-import { loadConfig } from "@jr2/orchestrator";
+import { loadConfig } from "@jr2/orchestrator/internal";
 import { pnpmDockerBuild } from "../build.ts";
 import { KIT_VERSION, LABEL_INSTANCE, operatorManifest } from "../deploy.ts";
 import { resolveRoot } from "../instance.ts";
 import { kubectlAdmin } from "../kube.ts";
 import { activity, confirmOrBail, type Io } from "../output.ts";
 import { sweepImages } from "../sweep.ts";
+import { parseCommand } from "../command-table.ts";
 
 export async function down(args: string[], io: Io): Promise<number> {
-  const { values } = parseArgs({
-    args,
-    allowPositionals: true,
-    strict: false,
-    options: {
-      all: { type: "boolean" },
-      yes: { type: "boolean" },
-      namespace: { type: "string", short: "n" },
-      context: { type: "string" },
-    },
-  });
+  const { values } = parseCommand("down", args);
 
   const root = resolveRoot(io.cwd);
   const config = (await loadConfig(root)) ?? {};

package/src/commands/gc.ts

@@ -15,24 +15,15 @@
 // resolves no instance folder: "disk is full now" has to work from anywhere, and a kube context is
 // the only address this command needs.
 
-import { parseArgs } from "node:util";
 import { pnpmDockerBuild } from "../build.ts";
 import { kubectlAdmin } from "../kube.ts";
 import { activity, type Io } from "../output.ts";
 import { DEFAULT_REPO_TTL, parseRepoTtl, sweepRepos } from "../repo-sweep.ts";
 import { sweepImages } from "../sweep.ts";
+import { parseCommand } from "../command-table.ts";
 
 export async function gc(args: string[], io: Io): Promise<number> {
-  const { values } = parseArgs({
-    args,
-    allowPositionals: true,
-    strict: false,
-    options: {
-      "dry-run": { type: "boolean" },
-      "repo-ttl": { type: "string" },
-      context: { type: "string" },
-    },
-  });
+  const { values } = parseCommand("gc", args);
   const ttl = (values["repo-ttl"] as string | undefined) ?? DEFAULT_REPO_TTL;
   // Refused before anything is read: a TTL that does not parse must not become "sweep now".
   parseRepoTtl(ttl);

package/src/commands/init.ts

@@ -4,7 +4,8 @@
 // does `jr2 up`, which refuses to converge a folder the compiler rejects — ADR-0050), a
 // `.gitignore` for the runtime `.jr2/`, ONE starter workflow (`ping`) that runs end-to-end with no
 // Workspace/Agent — a small "respond directly" Machine to trim down and build on — and
-// `images/default/Dockerfile`, the Sandbox Image every Workspace falls back to (ADR-0037).
+// `images/default/Dockerfile`, the Sandbox Image every Workspace falls back to (ADR-0037), and
+// the `AGENTS.md` an Assistant reads first, with a `CLAUDE.md` that imports it (ADR-0072).
 //
 // What it does NOT scaffold is as deliberate: there is no `agents/` folder and no `images/` scan,
 // because a Machine carries its own Agents and Sandbox Images (ADR-0049) and only what the CLI
@@ -15,7 +16,8 @@
 // `test/init.test.ts` enforces that; without it the two drift silently, and since the manifest
 // carries the kit version that same test is the version-bump tripwire (bump the kit, re-render the
 // template). Existing files are left untouched (init is additive); created paths are reported on
-// stderr.
+// stderr. A user's own AGENTS.md or CLAUDE.md that keeps an Assistant from the docs index gets one
+// hint line under its skip line (ADR-0072).
 //
 // ONE template serves both checkout and installed mode (ADR-0043) — a branch there would mean the
 // tested output and the shipped output diverge. So the scaffold names no package manager, and pins
@@ -24,20 +26,32 @@
 // not the orchestrator's `KIT_VERSION`: a global `jr2` with no Instance around it must scaffold
 // without a peer resolved, and the two numbers are equal by construction (one release train,
 // lockstep — ADR-0055).
+//
+// The `AGENTS.md` block is the one scaffolded text that comes from the Kit, not from this file: the
+// bundle of the CLI's own peer `@jr2/orchestrator`, when that peer is the version the scaffold pins.
+// A global `jr2` has that peer (npm installs a global's peers with it, and a checkout links it), so
+// a fresh folder indexes its docs before the first install — an Assistant can write the first
+// Machine before the first `jr2 up`. Without the bundle (a checkout before `docs:build`), the
+// markers stay empty and `jr2 up` fills them. The template mirrors the file with the block taken
+// out, since the block is generated and nothing generated is committed (ADR-0072).
 
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
-import { parseArgs } from "node:util";
-import { CLI_VERSION } from "../kit-version.ts";
+import { parseCommand } from "../command-table.ts";
+import {
+  AGENTS_MD,
+  BEGIN_MARKER,
+  CLAUDE_MD,
+  END_MARKER,
+  placeAgentsBlock,
+  readAgentsBlock,
+  scaffoldAgentsMd,
+} from "../agents-md.ts";
+import { CLI_ROOT, CLI_VERSION, resolvePackage, type ResolvedPackage } from "../kit-version.ts";
 import { activity, type Io } from "../output.ts";
 
 export async function init(args: string[], io: Io): Promise<number> {
-  const { values, positionals } = parseArgs({
-    args,
-    allowPositionals: true,
-    strict: false,
-    options: { name: { type: "string" } },
-  });
+  const { values, positionals } = parseCommand("init", args);
 
   const dir = positionals[0] ? resolve(io.cwd, String(positionals[0])) : io.cwd;
   const name = (values.name as string | undefined) ?? basename(dir);
@@ -49,6 +63,8 @@ export async function init(args: string[], io: Io): Promise<number> {
     { path: ".gitignore", content: GITIGNORE },
     { path: join("workflows", "ping.ts"), content: PING_TS },
     { path: join("images", "default", "Dockerfile"), content: IMAGE_DOCKERFILE },
+    { path: AGENTS_MD, content: scaffoldAgentsMd(scaffoldBlock(resolvePackage("@jr2/orchestrator", CLI_ROOT))) },
+    { path: "CLAUDE.md", content: CLAUDE_MD },
   ];
 
   activity(io, `jr2 init — scaffolding ${name} in ${dir}`);
@@ -56,6 +72,8 @@ export async function init(args: string[], io: Io): Promise<number> {
     const full = join(dir, file.path);
     if (await exists(full)) {
       activity(io, `  skip   ${file.path} (exists)`);
+      const hint = await existingHint(file.path, full);
+      if (hint) activity(io, `         ${hint}`);
       continue;
     }
     await mkdir(dirname(full), { recursive: true });
@@ -66,6 +84,29 @@ export async function init(args: string[], io: Io): Promise<number> {
   return 0;
 }
 
+/** The block `init` writes between the markers: the bundle of `peer` when it is the exact version
+ * the scaffold pins, else nothing (`jr2 up` fills it once the Instance resolves its Kit). */
+export function scaffoldBlock(peer: ResolvedPackage | undefined, pinned: string = CLI_VERSION): string | undefined {
+  return peer && peer.version === pinned ? readAgentsBlock(peer.root) : undefined;
+}
+
+/** One line for a user's own `AGENTS.md` or `CLAUDE.md` that init left alone and that keeps an
+ * Assistant from the docs index (ADR-0072): a file with no markers has opted out, and Claude Code
+ * reads `AGENTS.md` only through a `CLAUDE.md` that imports it. Said, never fixed: the file is the
+ * user's. */
+export async function existingHint(path: string, full: string): Promise<string | undefined> {
+  if (path === AGENTS_MD) {
+    const place = placeAgentsBlock(await readFile(full, "utf8"));
+    if (place.kind === "opted-out")
+      return `AGENTS.md has no jr2-docs markers: add the lines ${BEGIN_MARKER} and ${END_MARKER}, and jr2 up fills them`;
+    if (place.kind === "broken") return `AGENTS.md: ${place.reason}, so jr2 up does not update the jr2 block`;
+    return undefined;
+  }
+  if (path === "CLAUDE.md" && !/^@AGENTS\.md\s*$/m.test(await readFile(full, "utf8")))
+    return "CLAUDE.md does not import AGENTS.md: add the line @AGENTS.md, so that Claude Code reads it";
+  return undefined;
+}
+
 async function exists(path: string): Promise<boolean> {
   try {
     await readFile(path);
@@ -85,6 +126,17 @@ async function exists(path: string): Promise<boolean> {
 // rule for `@jr2/*`, applied to the checker): the instance's PROGRAM includes the kit's `.ts`
 // sources — zero-build, `exports` point at source — so the compiler is part of the contract, not
 // the user's choice, and it moves when the kit moves.
+//
+// `zod` is the other import the scaffold's own files do not make but every Machine an author writes
+// does: each defineEvent and each input schema is a zod object, and the Reference's examples start
+// with `import { z } from "zod"`. A strict node_modules (pnpm) does not let the Instance import a
+// package it does not list, so without it a Machine copied from the bundled Reference is refused by
+// `jr2 up`'s typecheck (ADR-0050). npm hoisted it, by accident. The range is the kit's own.
+//
+// `check` runs `jr2 check`: the typecheck AND the load of each Workflow, which `jr2 up` runs first
+// (ADR-0050). `typecheck` alone does not load a module, so it misses each refusal of
+// `createMachine`, `defineEvent` and `workspace()`. The `jr2` it runs is the Instance's own
+// `@jr2/cli`, which strips the types of the kit sources under `node_modules`.
 function packageJson(name: string): string {
   return `${JSON.stringify(
     {
@@ -92,8 +144,8 @@ function packageJson(name: string): string {
       version: "0.0.0",
       private: true,
       type: "module",
-      scripts: { typecheck: "tsc --noEmit" },
-      dependencies: { "@jr2/orchestrator": CLI_VERSION, xstate: "^5.18.0" },
+      scripts: { check: "jr2 check", typecheck: "tsc --noEmit" },
+      dependencies: { "@jr2/orchestrator": CLI_VERSION, xstate: "^5.18.0", zod: "^4.4.3" },
       devDependencies: { "@jr2/cli": CLI_VERSION, "@types/node": "^26.0.1", typescript: "^5.6.0" },
     },
     null,
@@ -159,7 +211,9 @@ const IMAGE_DOCKERFILE = `# A Sandbox Image (ADR-0037): the tools your agents ca
 # (\`user:\` on \`workspace()\`, ADR-0005).
 #
 # Two things jr2 cannot vendor, both proven by \`jr2 up\` before it converges:
-#   - \`git\` — the agent clones, worktrees, and commits with the git you chose;
+#   - \`git\` — the agent clones, worktrees, and commits with the git you chose. With no identity
+#     here, the agent commits as \`jr2 Agent <agent@jr2.invalid>\`, jr2's default at the lowest rung
+#     of git's config: an identity you set at any level wins over it (ADR-0037);
 #   - a glibc base no older than jr2's node. alpine/musl cannot run it at all.
 #
 # This one folder is a path convention; there is no \`images/\` scan (ADR-0049/0050). A SECOND Sandbox
@@ -196,9 +250,11 @@ const PING_TS = `// The simplest jr2 workflow: no Agent, no Workspace, no data p
 // Shape: take the run input, invoke a plain \`fromPromise\` actor, fold its result into context, finish.
 // \`jr2 run ping --input '{"message":"hi"}'\` → the run reaches \`done\` and \`jr2 status\` shows the reply.
 //
-// Module contract (ADR-0011/0015): one named export — \`machine\`. A workflow that accepts
-// external events authors with \`jr2Setup({ events: [...] })\`; ping accepts none, so plain
-// xstate \`setup()\` is all it needs.
+// Module contract (ADR-0011/0015): one named export — \`machine\`. ping takes no workflow event and
+// declares no door, so plain xstate \`setup()\` is enough. A Machine with a door (a zod \`input\` on
+// \`createMachine\`, ADR-0033) uses \`jr2Setup\`, also when it takes no event: then it leaves out
+// \`events\`, as in \`jr2Setup()\`. \`setup()\` does not read that \`input\`, so \`jr2 up\` refuses a
+// zod \`input\` on a Machine that \`setup()\` made.
 //
 // The next step is a Machine the kit already ships (ADR-0054). \`@jr2/machines\` exports \`task\` — one
 // prompt, one Workspace, one human says done — and a Workflow is only the name an Instance
@@ -209,7 +265,7 @@ const PING_TS = `// The simplest jr2 workflow: no Agent, no Workspace, no data p
 //
 //   export const machine = customize(task, {
 //     repos: { target: { url: "https://github.com/you/repo.git" } },
-//     agents: { coder: { model: "anthropic/claude-sonnet-4-6" } },
+//     agents: { coder: { model: "anthropic/claude-haiku-5-5" } },
 //   });
 //
 // A packaged Machine leaves the parts it cannot honestly fill OPEN: it does not know your

package/src/commands/kit.ts

@@ -24,19 +24,14 @@
 // swap — it is the decision.
 
 import { execFile } from "node:child_process";
-import { parseArgs, promisify } from "node:util";
-import { custodianRef, KIT_VERSION } from "@jr2/orchestrator";
+import { promisify } from "node:util";
+import { custodianRef, KIT_VERSION } from "@jr2/orchestrator/internal";
 import { KIT_IMAGES, publishedKitRefs, type KitImageName } from "../build.ts";
 import { activity, result, type Io } from "../output.ts";
+import { commandNamed, parseCommand, renderCommand } from "../command-table.ts";
 
 const exec = promisify(execFile);
 
-const USAGE = `usage: jr2 kit push <registry>
-
-  mirror the v${KIT_VERSION} kit images (harness, operator, orchestrator) from their canonical
-  home, and the Custodian's pinned Envoy from its own, into <registry>, for a cluster whose
-  \`kitRegistry\` names it (ADR-0044, ADR-0059, ADR-0069)`;
-
 /** Run one `docker` invocation, rejecting on a non-zero exit. The seam this command is tested
  * through: the claims are which argv each ref produces and what a failure means, and both are
  * decidable with no registry anywhere near the test. Narrower than `build.ts`'s `RunCommand` on
@@ -51,17 +46,17 @@ const dockerCli: RunDocker = async (args) => {
 type Mirrored = { image: KitImageName | "custodian"; source: string; target: string; copied: boolean };
 
 export async function kit(args: string[], io: Io, docker: RunDocker = dockerCli): Promise<number> {
-  const { positionals } = parseArgs({ args, allowPositionals: true, strict: false, options: {} });
+  const { positionals } = parseCommand("kit push", args);
   const [sub, registry] = positionals;
 
   if (sub !== "push") {
     activity(io, sub === undefined ? "jr2 kit: no subcommand" : `unknown kit subcommand: ${sub}`);
-    activity(io, USAGE);
+    activity(io, renderCommand(commandNamed("kit push")));
     return 2;
   }
   if (!registry) {
     activity(io, "jr2 kit push: no target registry");
-    activity(io, USAGE);
+    activity(io, renderCommand(commandNamed("kit push")));
     return 2;
   }
 

package/src/commands/logs.ts

@@ -3,23 +3,18 @@
 // author emits → stderr). `-f`/`--follow` keeps streaming status deltas until the run settles; without
 // it, we print the replayed status and stop. A run that already settled streams its final status once.
 
-import { parseArgs } from "node:util";
 import { JR2Client } from "../client.ts";
-import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
+import { resolveTarget, targetOptions } from "../instance.ts";
 import { activity, result, type Io } from "../output.ts";
 import { resolveRunId } from "../run-id.ts";
 import { childErrorActivity, placingActivity } from "./run.ts";
+import { parseCommand, usageLine } from "../command-table.ts";
 
 export async function logs(args: string[], io: Io): Promise<number> {
-  const { values, positionals } = parseArgs({
-    args,
-    allowPositionals: true,
-    strict: false,
-    options: { follow: { type: "boolean", short: "f" }, ...TARGET_ARGS },
-  });
+  const { values, positionals } = parseCommand("logs", args);
   const given = positionals[0];
   if (!given) {
-    activity(io, "usage: jr2 logs <runId|abbrev> [-f]");
+    activity(io, usageLine("logs"));
     return 2;
   }
   const target = await resolveTarget(io, targetOptions(values));

package/src/commands/run.ts

@@ -11,28 +11,25 @@
 // A named Chart is a Workflow (ADR-0070): `jr2 run <wrapper>/<name>` starts it as any other run, the
 // name riding the path as one encoded segment. A Chart the door refuses (one-shot, in `--input`)
 // is a 422 whose report lines this prints, one per rule the Chart fails.
+//
+// The exit code (ADR-0073): 0 only for a run that ended `done`. 1 for every other end — `failed`,
+// `error`, `cancelled`, `lost`, `drifted` — and for a run that was parked before it settled. 2 is a
+// usage error, as for every verb. The status line on stderr says which end it was, and a failed
+// run's reason follows it.
 
-import { parseArgs } from "node:util";
-import type { ChildErrorMarker, PlacingMarker } from "@jr2/orchestrator";
+import type { ChildErrorMarker, PlacingMarker } from "@jr2/orchestrator/internal";
 import { JR2Client, JR2HttpError } from "../client.ts";
-import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
+import { failureActivity } from "./status.ts";
+import { resolveTarget, targetOptions } from "../instance.ts";
 import { activity, result, type Io } from "../output.ts";
+import { parseCommand, usageLine } from "../command-table.ts";
 
 export async function run(args: string[], io: Io): Promise<number> {
-  const { values, positionals } = parseArgs({
-    args,
-    allowPositionals: true,
-    strict: false,
-    options: {
-      input: { type: "string" },
-      detach: { type: "boolean" },
-      ...TARGET_ARGS,
-    },
-  });
+  const { values, positionals } = parseCommand("run", args);
 
   const workflow = positionals[0];
   if (!workflow) {
-    activity(io, "usage: jr2 run <workflow | wrapper/chart> [--input <json>] [--detach]");
+    activity(io, usageLine("run"));
     return 2;
   }
   const input = values.input ? (JSON.parse(String(values.input)) as Record<string, unknown>) : {};
@@ -73,8 +70,10 @@ export async function run(args: string[], io: Io): Promise<number> {
       }
       activity(io, `  → ${ev.status.status} ${JSON.stringify(ev.status.value)}`);
       if (ev.status.status !== "active") {
+        const failed = failureActivity(ev.status);
+        if (failed) activity(io, failed);
         result(io, ev.status);
-        return ev.status.status === "error" ? 1 : 0;
+        return ev.status.status === "done" ? 0 : 1;
       }
     }
     // `events()` re-attaches until the run settles (ADR-0022), so reaching here means the run left

package/src/commands/runs.ts

@@ -4,6 +4,8 @@
 // A run with a Workspace in `placing` (ADR-0064) carries `placing`: the child paths of those
 // Workspaces, in `RunWaiting.child`'s form. It is the at-a-glance marker for a run that waits for
 // capacity — why it waits is `jr2 status <runId>`'s `waiting`. A run with none has no `placing` key.
+// A dispatched run (ADR-0071) carries `dispatchedBy` after its id, as the Orchestrator sends it: the
+// run that started it, the caller's slot and the chain's depth, so the chain reads off the listing.
 //
 // The verb also lists the Workflows a run can start (ADR-0070), from `GET /workflows`, as activity on
 // stderr so the result on stdout stays the live runs: one line per Workflow with its origin
@@ -11,32 +13,14 @@
 // with its reason. `--workflows` prints that listing as the result instead. No verb puts or deletes
 // a runtime Chart in this step: `PUT`/`DELETE /workflows/<wrapper>/charts/<name>` is for an MCP or curl.
 
-import { parseArgs } from "node:util";
-import type { RunChild } from "@jr2/orchestrator";
+import type { RunChild } from "@jr2/orchestrator/internal";
 import { JR2Client, type RunStatus, type WorkflowListing, type WorkflowOrigin } from "../client.ts";
-import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
+import { resolveTarget, targetOptions } from "../instance.ts";
 import { activity, result, type Io } from "../output.ts";
-
-export const RUNS_USAGE = `usage: jr2 runs [--workflows]
-
-  the live runs as JSON on stdout; the Workflows a run can start on stderr, each with its origin
-  (machine, chart file, chart) and a Chart wrapper's Charts indented under it (ADR-0070)
-  --workflows   print the Workflow listing as the JSON result instead
-
-  a runtime Chart has no verb here: PUT or DELETE /workflows/<wrapper>/charts/<name> with the
-  Instance token (an MCP or curl), then \`jr2 run <wrapper>/<name>\` starts it`;
+import { parseCommand } from "../command-table.ts";
 
 export async function runs(args: string[], io: Io): Promise<number> {
-  const { values } = parseArgs({
-    args,
-    allowPositionals: true,
-    strict: false,
-    options: { ...TARGET_ARGS, workflows: { type: "boolean" }, help: { type: "boolean", short: "h" } },
-  });
-  if (values.help) {
-    activity(io, RUNS_USAGE);
-    return 0;
-  }
+  const { values } = parseCommand("runs", args);
   const target = await resolveTarget(io, targetOptions(values));
   try {
     const client = new JR2Client(target.url, io.fetch, target.token);
@@ -44,7 +28,7 @@ export async function runs(args: string[], io: Io): Promise<number> {
       result(io, await client.workflows());
       return 0;
     }
-    const live = (await client.list()).map(markPlacing);
+    const live = (await client.list()).map(markListed);
     // A report beside the result: a listing that cannot be read says why, and the runs still print.
     try {
       activity(io, renderWorkflows(await client.workflows()));
@@ -93,12 +77,13 @@ function chartFullName(wrapper: string, name: string): string {
   return name.includes("/") ? name : `${wrapper}/${name}`;
 }
 
-/** The run, with `placing` after its id when any Workspace in it is in `placing`. */
-export function markPlacing(run: RunStatus): RunStatus & { placing?: string[] } {
+/** The run as `jr2 runs` lists it: `dispatchedBy` after its id when a `dispatch` Effect started it
+ * (ADR-0071), and `placing` after that when any Workspace in it is in `placing`. */
+export function markListed(run: RunStatus): RunStatus & { placing?: string[] } {
   const placing = [...(run.value === "placing" ? [""] : []), ...placingIn(run.children ?? [], [])];
-  if (!placing.length) return run;
-  const { runId, ...rest } = run;
-  return { runId, placing, ...rest };
+  if (!placing.length && !run.dispatchedBy) return run;
+  const { runId, dispatchedBy, ...rest } = run;
+  return { runId, ...(dispatchedBy ? { dispatchedBy } : {}), ...(placing.length ? { placing } : {}), ...rest };
 }
 
 /** The paths of every child in `placing`, at any depth — read off the state values alone, which

package/src/commands/send.ts

@@ -20,33 +20,19 @@
 // idle timeout (ADR-0025). It is a fact of this cancel, so it is a flag here and never a config key,
 // and it means nothing on any other event — refused there rather than ignored.
 
-import { parseArgs } from "node:util";
 import { JR2Client } from "../client.ts";
-import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
+import { resolveTarget, targetOptions } from "../instance.ts";
 import { activity, type Io } from "../output.ts";
 import { resolveRunId } from "../run-id.ts";
-
-const USAGE =
-  "usage: jr2 send <runId|abbrev> --event CANCEL [--keep] | jr2 send <runId|abbrev> --gate <gate> --event <name> [--input '<json>']";
+import { commandNamed, parseCommand, renderCommand } from "../command-table.ts";
 
 export async function send(args: string[], io: Io): Promise<number> {
-  const { values, positionals } = parseArgs({
-    args,
-    allowPositionals: true,
-    strict: false,
-    options: {
-      event: { type: "string" },
-      gate: { type: "string" },
-      input: { type: "string" },
-      keep: { type: "boolean" },
-      ...TARGET_ARGS,
-    },
-  });
+  const { values, positionals } = parseCommand("send", args);
   const given = positionals[0];
   const gate = values.gate as string | undefined;
   const event = values.event as string | undefined;
   if (!given || !event) {
-    activity(io, USAGE);
+    activity(io, renderCommand(commandNamed("send")));
     return 2;
   }
   const keep = values.keep === true;

package/src/commands/status.ts

@@ -14,21 +14,24 @@
 //
 // A run that binds a Chart (ADR-0070) carries `bound: true`; the verb says so beside the result as
 // `chart: bound`, with the route that draws the Machine the run binds, its Charts compiled in.
+//
+// A dispatched run (ADR-0071) says beside the result who dispatched it: `dispatched by: <run>
+// (<slot>), depth <n>`. A run that dispatched says the other direction, one line per run it
+// started: `dispatched: <run> (<slot>)`. The result itself carries `dispatchedBy`, `dispatched`
+// and, once the run is no longer live, its `output`, as the Orchestrator sends them.
+//
+// A failed run (ADR-0073) says its reason beside the result: `failed: <reason>`. The result's
+// `output` holds the whole Failure, `{ reason, detail? }`.
 
-import { parseArgs } from "node:util";
-import type { AssemblyView, RepoStatus } from "@jr2/orchestrator";
+import type { AssemblyView, RepoStatus } from "@jr2/orchestrator/internal";
 import { JR2Client, type FetchLike, type RunStatus, workflowPath } from "../client.ts";
-import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
+import { resolveTarget, targetOptions } from "../instance.ts";
 import { activity, result, type Io } from "../output.ts";
 import { resolveRunId } from "../run-id.ts";
+import { parseCommand } from "../command-table.ts";
 
 export async function status(args: string[], io: Io): Promise<number> {
-  const { values, positionals } = parseArgs({
-    args,
-    allowPositionals: true,
-    strict: false,
-    options: { ...TARGET_ARGS, json: { type: "boolean" } },
-  });
+  const { values, positionals } = parseCommand("status", args);
   // NO run named, not an EMPTY one: `jr2 status "$RUNID"` with the variable unset asked about a run
   // and got an empty string, and answering that with the instance's repos would report exit 0 on a
   // question nobody asked. An empty positional falls through to the resolver, which says so.
@@ -48,14 +51,47 @@ export async function status(args: string[], io: Io): Promise<number> {
       return 1;
     }
     result(io, s);
-    const note = boundActivity(s);
-    if (note) activity(io, note);
+    const notes = [failureActivity(s), dispatchedActivity(s), ...dispatchedLines(s), boundActivity(s)];
+    for (const note of notes) if (note) activity(io, note);
     return 0;
   } finally {
     target.close?.();
   }
 }
 
+/** The `failed:` line for a run that ended `failed` (ADR-0073): the Failure's reason, read from its
+ * output. Undefined for every other status, and for an output with no reason text. */
+export function failureActivity(s: Pick<RunStatus, "status" | "output">): string | undefined {
+  if (s.status !== "failed") return undefined;
+  const reason = (s.output as { reason?: unknown } | undefined)?.reason;
+  return typeof reason === "string" ? `failed: ${reason}` : undefined;
+}
+
+/** The most `dispatched:` lines `jr2 status` prints: a watcher dispatches on every pass, and the
+ * result carries the whole list. */
+const DISPATCHED_LINES = 10;
+
+/** The `dispatched:` lines for the runs this run's `dispatch` Effects started (ADR-0071), newest
+ * last, the older ones counted. */
+export function dispatchedLines(s: RunStatus): string[] {
+  const all = s.dispatched ?? [];
+  const shown = all.slice(-DISPATCHED_LINES);
+  const older = all.length - shown.length;
+  return [
+    ...(older > 0 ? [`dispatched: ${older} older run(s); the result lists them all`] : []),
+    ...shown.map((d) => `dispatched: ${d.run} (${d.slot})`),
+  ];
+}
+
+/** The `dispatched by:` line for a run a `dispatch` Effect started (ADR-0071), or undefined for a
+ * run nobody dispatched. A foreign caller is named by its Orchestrator, as that one sent it: opaque
+ * text, which this Orchestrator could not verify. */
+export function dispatchedActivity(s: RunStatus): string | undefined {
+  const by = s.dispatchedBy;
+  if (!by) return undefined;
+  return `dispatched by: ${by.run} (${by.slot}), depth ${by.depth}${by.instance ? `, from Orchestrator ${by.instance}` : ""}`;
+}
+
 /** The `chart: bound` line for a run that binds a Chart (ADR-0070), or undefined for one that binds
  * none. The Workflow name rides the route as one encoded segment. */
 export function boundActivity(s: RunStatus): string | undefined {