@jr2/cli 0.3.0 → 0.5.1

package/src/commands/down.ts

@@ -1,6 +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, 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.
 //
@@ -21,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,
@@ -117,9 +169,16 @@ export default defineConfig({
     // attach refuses it, so nothing can spend this cluster's credential against an arbitrary host. \`*\` is
     // today's two implicit defaults made visible (JR2_GIT_TOKEN from .env for https, the jr2-git-ssh Secret
     // for ssh). Narrow it to your hosts (\`match: "github.com/yourorg/"\`) before anything untrusted can start
-    // a run. The longest match wins; the url's scheme picks token vs sshKey.
+    // a run. The longest match wins; the url's scheme picks token vs sshKey. It also PUSHES: a \`push()\` whose
+    // Repo Slot url it matches — a per-run url included — spends the same token or key (ADR-0051, ADR-0067).
     credentials: [{ match: "*", token: "JR2_GIT_TOKEN", sshKey: "jr2-git-ssh" }],
   },
+  // Every secret of the Instance, one list (ADR-0068). Where each goes is read, never declared — a pod gets
+  // what something in it names. A model key goes to the pods whose Agents' provider reads it, and a
+  // \`workspace()\` that lists a name under \`secrets\` gets that one: its Custodian holds it and the Agent sees
+  // only a Stand-in (ADR-0059). One an Effect names with \`secret("name")\` is a file in that Effect's Effector
+  // alone. \`hosts\` says where a held value may go. Read values from .env, never commit them.
+  // secrets: [{ name: "ANTHROPIC_API_KEY", value: process.env.ANTHROPIC_API_KEY }],
   // Where Sandboxes land (ADR-0052): by default wherever an ordinary pod lands — not cordoned, no taint — and
   // the Repo cache agent follows the same set. No node label is needed. To admit a tainted pool or narrow to
   // a labeled one, name it in raw pod-spec shapes; \`jr2 up\` reports the Sandbox nodes it sees.
@@ -152,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
@@ -182,16 +243,18 @@ node_modules/
 `;
 
 const PING_TS = `// The simplest jr2 workflow: no Agent, no Workspace, no data plane at all. A Machine is free to "just
-// respond to the request" with a plain actor (CONTEXT.md: a workflow need not spawn a Workspace) —
+// respond to the request" with a plain actor (ADR-0001: a worktree is one piece a coding Machine bolts on) —
 // this is that case, and the one workflow that runs end-to-end on a fresh instance before any Sandbox /
 // Harness infrastructure exists. Filename \`ping.ts\` → workflow "ping".
 //
 // 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
@@ -202,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) 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)`;
-
 /** 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,22 +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));
@@ -39,6 +35,14 @@ export async function logs(args: string[], io: Io): Promise<number> {
         activity(io, `retry ${ev.child} attempt ${ev.attempt} (${ev.reason})`);
         continue;
       }
+      if (ev.kind === "placing" || ev.kind === "placed") {
+        activity(io, placingActivity(ev));
+        continue;
+      }
+      if (ev.kind === "child-error") {
+        activity(io, childErrorActivity(ev));
+        continue;
+      }
       result(io, ev.status);
       if (!values.follow) break;
       if (ev.status.status !== "active") break;

package/src/commands/run.ts

@@ -7,27 +7,29 @@
 // kube context — ADR-0019) rather than a per-invocation runtime, because jr2 runs are durable and may
 // park indefinitely on an approval gate. `--detach` prints the runId and returns, leaving the run
 // going server-side.
+//
+// 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 { JR2Client } from "../client.ts";
-import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
+import type { ChildErrorMarker, PlacingMarker } from "@jr2/orchestrator/internal";
+import { JR2Client, JR2HttpError } from "../client.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> [--input <json>] [--detach]");
+    activity(io, usageLine("run"));
     return 2;
   }
   const input = values.input ? (JSON.parse(String(values.input)) as Record<string, unknown>) : {};
@@ -35,7 +37,14 @@ export async function run(args: string[], io: Io): Promise<number> {
   try {
     const client = new JR2Client(target.url, io.fetch, target.token);
 
-    const { runId } = await client.start(workflow, input);
+    let runId: string;
+    try {
+      ({ runId } = await client.start(workflow, input));
+    } catch (err) {
+      if (!(err instanceof JR2HttpError) || !err.report) throw err;
+      activity(io, refusalActivity(workflow, err.report));
+      return 1;
+    }
     if (values.detach) {
       result(io, { runId });
       return 0;
@@ -51,14 +60,58 @@ export async function run(args: string[], io: Io): Promise<number> {
         activity(io, `  retry ${ev.child} attempt ${ev.attempt} (${ev.reason})`);
         continue;
       }
+      if (ev.kind === "placing" || ev.kind === "placed") {
+        activity(io, `  ${placingActivity(ev)}`);
+        continue;
+      }
+      if (ev.kind === "child-error") {
+        activity(io, `  ${childErrorActivity(ev)}`);
+        continue;
+      }
       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;
       }
     }
-    return 0;
+    // `events()` re-attaches until the run settles (ADR-0022), so reaching here means the run left
+    // the live set without settling: stopped, parked for the next boot's restore (ADR-0025). Never
+    // a success, and nothing on stdout to be mistaken for a result.
+    activity(
+      io,
+      `run ${runId} is parked: stopped before it settled — \`jr2 logs -f ${runId}\` follows it once restored`,
+    );
+    return 1;
   } finally {
     target.close?.();
   }
 }
+
+/**
+ * The door's refusal of a Chart (ADR-0070) as activity: the Workflow, then each report line, which
+ * names the path in the Chart and the rule it fails.
+ */
+export function refusalActivity(workflow: string, report: readonly string[]): string {
+  return [`error: the door refused the Chart for "${workflow}"`, ...report.map((line) => `  ${line}`)].join("\n");
+}
+
+/**
+ * A wait for capacity as one activity line (ADR-0064): the Workspace, what it waits for, and the
+ * scheduler's or the quota's own words — then, once it has a node, how long it waited. The run's
+ * root Workspace has no child path, so its line names none.
+ */
+export function placingActivity(ev: PlacingMarker): string {
+  const who = ev.child ? ` ${ev.child}` : "";
+  if (ev.kind === "placed") return `placed${who} after ${Math.round(ev.after / 1000)}s`;
+  return `placing${who}: waits for ${ev.on === "quota" ? "quota" : "a node"} — ${ev.message}`;
+}
+
+/**
+ * A child's error below an Agent's state as one activity line (ADR-0024): the pick's answer carries
+ * no reply for it, so the Agent is not told, and this line is where the operator reads it.
+ */
+export function childErrorActivity(ev: ChildErrorMarker): string {
+  return `child-error: \`${ev.child}\` failed below ${ev.agent}'s pick \`${ev.pick}\` — ${ev.error}`;
+}

package/src/commands/runs.ts

@@ -1,19 +1,96 @@
 // `jr2 runs` (ADR-0009): list the live runs as JSON on stdout. (Settled runs leave the live registry;
 // read a specific one through to the store with `jr2 status <runId>`.)
+//
+// 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
+// (`machine`, `chart file`, `chart`), a Chart wrapper's Charts indented under it, and `unrunnable`
+// 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 { JR2Client } from "../client.ts";
-import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
-import { result, type Io } from "../output.ts";
+import type { RunChild } from "@jr2/orchestrator/internal";
+import { JR2Client, type RunStatus, type WorkflowListing, type WorkflowOrigin } from "../client.ts";
+import { resolveTarget, targetOptions } from "../instance.ts";
+import { activity, result, type Io } from "../output.ts";
+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 } });
+  const { values } = parseCommand("runs", args);
   const target = await resolveTarget(io, targetOptions(values));
   try {
     const client = new JR2Client(target.url, io.fetch, target.token);
-    result(io, await client.list());
+    if (values.workflows) {
+      result(io, await client.workflows());
+      return 0;
+    }
+    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()));
+    } catch (e) {
+      activity(io, `workflows: unknown — ${e instanceof Error ? e.message : String(e)}`);
+    }
+    result(io, live);
     return 0;
   } finally {
     target.close?.();
   }
 }
+
+/** How a listing names an origin (ADR-0070): a runtime Chart is plainly a `chart`. */
+const ORIGIN_LABEL: Record<WorkflowOrigin, string> = { machine: "machine", file: "chart file", runtime: "chart" };
+
+/**
+ * The Workflow listing as lines: each Workflow with its origin, a Chart wrapper's Open body and
+ * whether its door takes a Chart one-shot, its Charts indented under it, and `unrunnable` with the
+ * reason. A Chart the listing also gives at the top level (or whose wrapper it does not list) prints
+ * once: under its wrapper when the wrapper is listed, else at the top level.
+ */
+export function renderWorkflows(listing: readonly WorkflowListing[]): string {
+  const underWrapper = new Set<string>();
+  for (const w of listing) for (const c of w.wrapper?.charts ?? []) underWrapper.add(chartFullName(w.name, c.name));
+  const line = (indent: string, name: string, label: string, unrunnable?: string): string =>
+    `${indent}${name} (${label})${unrunnable ? ` unrunnable: ${unrunnable}` : ""}`;
+  const out = ["workflows:"];
+  for (const w of listing) {
+    if (w.origin !== "machine" && underWrapper.has(w.name)) continue;
+    const wrapper = w.wrapper;
+    const label = wrapper
+      ? `${ORIGIN_LABEL[w.origin]}, Chart wrapper: body "${wrapper.body}"${wrapper.oneShot ? ", one-shot" : ""}`
+      : ORIGIN_LABEL[w.origin];
+    out.push(line("  ", w.name, label, w.unrunnable));
+    for (const c of wrapper?.charts ?? []) {
+      out.push(line("    ", chartFullName(w.name, c.name), ORIGIN_LABEL[c.origin], c.unrunnable));
+    }
+  }
+  if (out.length === 1) out.push("  none registered — `jr2 up` publishes the Assembly");
+  return out.join("\n");
+}
+
+/** A Chart's Workflow name, `<wrapper>/<name>` (ADR-0070), whether the listing gives it short or whole. */
+function chartFullName(wrapper: string, name: string): string {
+  return name.includes("/") ? name : `${wrapper}/${name}`;
+}
+
+/** 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 && !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
+ * are public (a Workspace's value is the flat state key). */
+function placingIn(children: RunChild[], path: string[]): string[] {
+  return children.flatMap((child) => {
+    const here = [...path, child.id];
+    return [...(child.value === "placing" ? [here.join("/")] : []), ...placingIn(child.children, here)];
+  });
+}