@jr2/cli 0.2.1 → 0.4.1

package/src/cli.ts

@@ -31,11 +31,15 @@ usage: jr2 <command> [args]
   kit push <registry>               mirror the published kit images into a registry (ADR-0044)
   run <workflow> [--input <json>]   start a run; stream activity, print terminal result
        [--detach]                   ...or just print the runId and return
-  runs                              list live runs
+  runs                              list live runs; "placing" names the Workspaces that wait for
+                                    capacity (ADR-0064), and "status <runId>" says why; the
+                                    Workflows and their named Charts on stderr (ADR-0070)
+       [--workflows]                ...or print that listing as the result (see "runs --help")
   status [runId]                    print a run's current status (read-through),
          [--json]                   or the instance's Repos, per node, when given none (ADR-0048/0051)
   logs <runId> [-f]                 replay a run's status; -f to follow until it settles
-  send <runId> --event CANCEL       abandon a live run
+  send <runId> --event CANCEL       abandon a live run and destroy its Workspaces
+       [--keep]                     ...or keep them for inspection until the idle timeout
   send <runId> --gate <gate> --event <name> [--input <json>]
                                     deliver a workflow event to an open gate
 

package/src/client.ts

@@ -6,7 +6,7 @@
 // `fetchImpl` is injectable so tests drive it with a hono `app.request` (no socket) the same way the
 // orchestrator's own http tests do; in production it defaults to the global `fetch`.
 
-import type { MachineDoc, RepoStatus } from "@jr2/orchestrator";
+import type { ChildErrorMarker, MachineDoc, PlacingMarker, RepoStatus, RunChild, RunWaiting } from "@jr2/orchestrator";
 import { parseSSE } from "./sse.ts";
 
 /** A run's current observable state — mirrors the orchestrator's `RunStatus` (run-host.ts). */
@@ -17,19 +17,56 @@ export type RunStatus = {
   status: string;
   value: unknown;
   context: unknown;
-  /** Why the host set this status, for statuses the Machine did not choose — `drifted` says the
-   * workflow changed shape since the run was saved, and names both fingerprints (ADR-0030). */
+  /** The live child machines beneath the root, context-free — where most of a run is. */
+  children?: RunChild[];
+  /** Every Workspace waiting for capacity, and why (ADR-0064). Optional: an orchestrator older
+   * than ADR-0064 does not send it. */
+  waiting?: RunWaiting[];
+  /** Why the host set this status, for statuses the Machine did not choose — `drifted` names the
+   * Assembly hash and why this Orchestrator cannot read it: not on the volume, published for
+   * another Kit version, or does not load (ADR-0030, ADR-0069). */
   reason?: string;
+  /** The hash of the Assembly the run started under, and holds while it is live (ADR-0069).
+   * Absent for a run no Assembly started. */
+  assembly?: string;
+  /** The run binds at least one Chart (ADR-0070): its Machine is the Chart wrapper's with each bound
+   * Open body's Chart compiled in, which `GET /workflows/:name/runs/:runId/machine` serves.
+   * Absent when the run binds none. */
+  bound?: true;
+  /** The hashes of the Charts the run binds now, distinct and sorted (ADR-0070). */
+  chartHashes?: string[];
+};
+
+/** Where a Workflow came from (ADR-0070): a Machine in the Assembly, a Chart file in the Assembly, or
+ * a runtime Chart put by `PUT /workflows/:wrapper/charts/:name`. */
+export type WorkflowOrigin = "machine" | "file" | "runtime";
+
+/** One entry of `GET /workflows` (ADR-0070) — mirrors the orchestrator's `WorkflowListing`
+ * (run-host.ts). A Chart wrapper's entry carries its Open body slot, whether its door takes a Chart
+ * one-shot, and its named Charts, inside its entry and not beside it. `unrunnable` is why a
+ * Workflow cannot start now (a runtime Chart a publish no longer admits). */
+export type WorkflowListing = {
+  name: string;
+  origin: WorkflowOrigin;
+  wrapper?: {
+    body: string;
+    oneShot: boolean;
+    charts: Array<{ name: string; origin: "file" | "runtime"; unrunnable?: string }>;
+  };
+  unrunnable?: string;
 };
 
 /** One item on a run's observation feed — mirrors the orchestrator's `RunFeedEvent`. */
 export type RunFeedEvent =
   | { kind: "status"; status: RunStatus }
   | { kind: "emit"; event: { type: string } & Record<string, unknown> }
-  | { kind: "retry"; child: string; attempt: number; reason: string };
+  | { kind: "retry"; child: string; attempt: number; reason: string }
+  | PlacingMarker
+  | ChildErrorMarker;
 
-/** A run-control event posted to a live run (ADR-0013): CANCEL is the vocabulary that is left. */
-export type RunEvent = { type: string };
+/** A run-control event posted to a live run (ADR-0013): CANCEL is the vocabulary that is left.
+ * `keep` leaves a cancelled run's Workspaces instead of destroying them (ADR-0025). */
+export type RunEvent = { type: string; keep?: boolean };
 
 /** The subset of `fetch` the client uses. `globalThis.fetch` and hono's `app.request` both satisfy it. */
 export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
@@ -57,16 +94,27 @@ export class JR2HttpError extends Error {
   readonly status: number;
   readonly path: string;
   readonly instance?: InstanceIdentity;
+  /** The door's report lines, when the answer carried them: a refused Chart is
+   * `422 { error: "refused", report }` (ADR-0070), one line per rule it fails. */
+  readonly report?: string[];
 
-  constructor(message: string, status: number, path: string, instance?: InstanceIdentity) {
+  constructor(message: string, status: number, path: string, instance?: InstanceIdentity, report?: string[]) {
     super(message);
     this.name = "JR2HttpError";
     this.status = status;
     this.path = path;
     this.instance = instance;
+    if (report) this.report = report;
   }
 }
 
+/** The path of a Workflow's routes. The name is ONE path segment, encoded: a named Chart's
+ * `<wrapper>/<name>` rides as `<wrapper>%2F<name>` (ADR-0070), which the Orchestrator reads as the
+ * same Workflow as `/workflows/<wrapper>/charts/<name>`. */
+export function workflowPath(workflow: string): string {
+  return `/workflows/${encodeURIComponent(workflow)}`;
+}
+
 export class JR2Client {
   readonly baseUrl: string;
   private readonly fetchImpl: FetchLike;
@@ -85,20 +133,40 @@ export class JR2Client {
     return this.token ? { ...extra, authorization: `Bearer ${this.token}` } : extra;
   }
 
-  /** `GET /workflows` — names of the registered workflows. */
-  async workflows(): Promise<string[]> {
-    return (await this.json(await this.fetchImpl(`${this.baseUrl}/workflows`), "/workflows")) as string[];
+  /** `GET /workflows` — every registered Workflow with its origin, each Chart wrapper's Charts inside
+   * its entry (ADR-0070). An orchestrator older than ADR-0070 answers bare names; each reads as a
+   * Machine, so the listing has one shape for every caller. */
+  async workflows(): Promise<WorkflowListing[]> {
+    const body = await this.json(await this.fetchImpl(`${this.baseUrl}/workflows`), "/workflows");
+    // An answer that is no listing is not "none registered": say what came back (`jr2 runs` prints
+    // `workflows: unknown — ...` for it, never "none registered").
+    if (!Array.isArray(body)) throw new Error("GET /workflows: the answer is not a listing");
+    return body.map((w: unknown) =>
+      typeof w === "string" ? { name: w, origin: "machine" as const } : (w as WorkflowListing),
+    );
   }
 
   /** `GET /workflows/:name/machine` — the workflow's Machine as the Console's DTO. */
   async machine(workflow: string): Promise<MachineDoc> {
-    const res = await this.fetchImpl(`${this.baseUrl}/workflows/${encodeURIComponent(workflow)}/machine`);
+    const res = await this.fetchImpl(`${this.baseUrl}${workflowPath(workflow)}/machine`);
     return (await this.json(res, "/workflows/:name/machine")) as MachineDoc;
   }
 
-  /** `POST /workflows/:name/runs` — start a run; unknown workflow → 404 → throws. */
+  /** `GET /workflows/:name/runs/:runId/machine` — the run's bound Machine (ADR-0070): the Chart
+   * wrapper's Machine with each bound Open body's Chart compiled in. An unknown run → undefined. */
+  async runMachine(workflow: string, runId: string): Promise<MachineDoc | undefined> {
+    const res = await this.fetchImpl(
+      `${this.baseUrl}${workflowPath(workflow)}/runs/${encodeURIComponent(runId)}/machine`,
+    );
+    if (res.status === 404) return undefined;
+    return (await this.json(res, "/workflows/:name/runs/:runId/machine")) as MachineDoc;
+  }
+
+  /** `POST /workflows/:name/runs` — start a run; unknown workflow → 404 → throws. A named Chart's
+   * name `<wrapper>/<name>` rides the path as one encoded segment (ADR-0070); a refused Chart in
+   * the input → 422 → throws with the door's `report`. */
   async start(workflow: string, input: Record<string, unknown> = {}): Promise<{ runId: string; instanceId: string }> {
-    const res = await this.fetchImpl(`${this.baseUrl}/workflows/${encodeURIComponent(workflow)}/runs`, {
+    const res = await this.fetchImpl(`${this.baseUrl}${workflowPath(workflow)}/runs`, {
       method: "POST",
       headers: this.headers(JSON_HEADERS),
       body: JSON.stringify(input),
@@ -142,7 +210,8 @@ export class JR2Client {
 
   /** `POST /runs/:runId/gates/:gate/events` — deliver a workflow-defined event to an open gate
    * (ADR-0011). The body is `{ type, ...input }`, validated against the event's schema host-side;
-   * an unknown gate (404) or rejected payload (400) surfaces as a throw. */
+   * an unknown gate (404), a rejected payload (400) or an answer the run would not take now (409,
+   * ADR-0013) surfaces as a throw. */
   async sendToGate(runId: string, gate: string, event: { type: string } & Record<string, unknown>): Promise<void> {
     const res = await this.fetchImpl(
       `${this.baseUrl}/runs/${encodeURIComponent(runId)}/gates/${encodeURIComponent(gate)}/events`,
@@ -165,26 +234,48 @@ export class JR2Client {
    * `GET /runs/:runId/events` — the SSE feed as an async-iterable of `RunFeedEvent`. The current status
    * is replayed first (attach), then deltas + author `emit`s until the terminal status (or the consumer
    * breaks, which cancels the stream). A settled run streams its final status once and ends.
+   *
+   * A feed that ends BEFORE a terminal status is re-attached, never read as the run's end: the
+   * server closes a reader that fell behind (a paused pager on `jr2 run | less`), and the feed is
+   * level-triggered, so the re-attach opens with where the run stands now (ADR-0022). What falls in
+   * the gap is activity — Emits, retries — never state. The one end that IS the run's own without
+   * a terminal status is `gone`: the run was stopped and is parked (ADR-0025); the generator ends.
    */
   async *events(runId: string): AsyncGenerator<RunFeedEvent> {
-    const res = await this.fetchImpl(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/events`, {
-      headers: this.headers({ accept: "text/event-stream" }),
-    });
-    if (res.status === 404) {
-      throw new JR2HttpError(`no run "${runId}"`, 404, "/runs/:runId/events", await this.identify());
-    }
-    if (!res.body) return;
-    for await (const frame of parseSSE(res.body)) {
-      if (frame.event === "emit") {
-        yield { kind: "emit", event: JSON.parse(frame.data) as { type: string } & Record<string, unknown> };
-      } else if (frame.event === "retry") {
-        yield { kind: "retry", ...(JSON.parse(frame.data) as { child: string; attempt: number; reason: string }) };
-      } else if (frame.event === "status") {
-        yield { kind: "status", status: JSON.parse(frame.data) as RunStatus };
+    for (;;) {
+      const res = await this.fetchImpl(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/events`, {
+        headers: this.headers({ accept: "text/event-stream" }),
+      });
+      if (res.status === 404) {
+        throw new JR2HttpError(`no run "${runId}"`, 404, "/runs/:runId/events", await this.identify());
+      }
+      if (!res.body) return;
+      let settled = false;
+      for await (const frame of parseSSE(res.body)) {
+        if (frame.event === "emit") {
+          yield { kind: "emit", event: JSON.parse(frame.data) as { type: string } & Record<string, unknown> };
+        } else if (frame.event === "retry") {
+          yield { kind: "retry", ...(JSON.parse(frame.data) as { child: string; attempt: number; reason: string }) };
+        } else if (frame.event === "status") {
+          const status = JSON.parse(frame.data) as RunStatus;
+          settled = status.status !== "active";
+          yield { kind: "status", status };
+        } else if (frame.event === "placing" || frame.event === "placed") {
+          // A wait for capacity starting and ending (ADR-0064) — activity, never a status.
+          yield { ...(JSON.parse(frame.data) as object), kind: frame.event } as PlacingMarker;
+        } else if (frame.event === "child-error") {
+          // A child's error below an Agent's state, which the Agent's answer does not carry (ADR-0024).
+          yield { ...(JSON.parse(frame.data) as object), kind: "child-error" } as ChildErrorMarker;
+        } else if (frame.event === "gone") {
+          // The run left the live set without settling — stopped, parked for the next boot's
+          // restore (ADR-0025). This end is the run's own (ADR-0022): nothing to re-attach to.
+          return;
+        }
+        // Any other frame (a Turn marker — ADR-0023 — or a kind this CLI predates) is skipped, not
+        // misread as a status: `jr2 logs -f` decides "settled" off `status.status`, and a marker
+        // parsed as a status would end the follow mid-run.
       }
-      // Any other frame (a Turn marker — ADR-0023 — or a kind this CLI predates) is skipped, not
-      // misread as a status: `jr2 logs -f` decides "settled" off `status.status`, and a marker
-      // parsed as a status would end the follow mid-run.
+      if (settled) return;
     }
   }
 
@@ -209,10 +300,12 @@ export class JR2Client {
     const text = await res.text();
     const body = text ? JSON.parse(text) : undefined;
     if (!res.ok) {
-      const message = (body as { error?: string } | undefined)?.error ?? `HTTP ${res.status}`;
+      const { error, report } = (body ?? {}) as { error?: string; report?: unknown };
+      const message = error ?? `HTTP ${res.status}`;
+      const lines = Array.isArray(report) ? report.map(String) : undefined;
       // Probe HERE, not at the catch site: by the time the error reaches `cli.ts` the command's
       // `finally` has closed the port-forward, and there is nothing left to ask.
-      throw new JR2HttpError(message, res.status, path, await this.identify());
+      throw new JR2HttpError(message, res.status, path, await this.identify(), lines);
     }
     return body;
   }

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
+// 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.
 //

package/src/commands/init.ts

@@ -117,9 +117,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.
@@ -182,7 +189,7 @@ 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".
 //

package/src/commands/kit.ts

@@ -2,16 +2,18 @@
 //
 // Kit images live at a canonical public home (`ghcr.io/snapwich`, baked into `publishedKitRefs()`).
 // A cluster that cannot reach it — air-gapped, mirror-only, or simply policy-bound to one registry —
-// needs the three refs at its own address, which is what `kitRegistry` names in the config. This
-// command is how the bytes get there.
+// needs those refs at its own address, which is what `kitRegistry` names in the config. This
+// command is how the bytes get there. It moves one more image the same way: the Custodian's, the
+// pinned upstream Envoy every Harness pod runs (ADR-0059), which jr2 deploys and never builds — a
+// mirror-only cluster needs it just as much, and `kitRegistry` re-homes it the same way.
 //
 // It is deliberately INSTANCE-LESS: no `jr2.config.ts`, no kube context, no namespace. Kit images are
 // shared by every instance on a cluster (and possibly by every instance in an org), so moving them
 // is its own deliberate act rather than a side effect of converging one instance — which is exactly
 // why ADR-0044 keeps this out of `jr2 up`.
 //
-// It is a MIRROR and nothing else. There is no build arm here: the npm packages carry no Harness or
-// Adapter source, and an installed CLI that could build Kit images would be the patched-Harness
+// It is a MIRROR and nothing else. There is no build arm here: the npm packages carry no Harness
+// source, and an installed CLI that could build Kit images would be the patched-Harness
 // eject hatch ADR-0027/ADR-0038 welded shut. The kit developer's arm is `just kit-push`, in the
 // checkout, where the sources actually are.
 //
@@ -23,7 +25,7 @@
 
 import { execFile } from "node:child_process";
 import { parseArgs, promisify } from "node:util";
-import { KIT_VERSION } from "@jr2/orchestrator";
+import { custodianRef, KIT_VERSION } from "@jr2/orchestrator";
 import { KIT_IMAGES, publishedKitRefs, type KitImageName } from "../build.ts";
 import { activity, result, type Io } from "../output.ts";
 
@@ -31,8 +33,9 @@ const exec = promisify(execFile);
 
 const USAGE = `usage: jr2 kit push <registry>
 
-  mirror the v${KIT_VERSION} kit images (harness, adapter, operator) from their canonical
-  home into <registry>, for a cluster whose \`kitRegistry\` names it (ADR-0044)`;
+  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
@@ -45,7 +48,7 @@ const dockerCli: RunDocker = async (args) => {
 };
 
 /** What one image's mirror did — the per-image line, and the machine-readable result's rows. */
-type Mirrored = { image: KitImageName; source: string; target: string; copied: boolean };
+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: {} });
@@ -77,6 +80,9 @@ export async function kit(args: string[], io: Io, docker: RunDocker = dockerCli)
   for (const image of Object.keys(KIT_IMAGES) as KitImageName[]) {
     rows.push(await mirror(io, docker, image, sources[image], targets[image]));
   }
+  // The Custodian's: pinned by digest, and a registry-to-registry copy keeps the digest — so the
+  // ref a converge with this `kitRegistry` deploys (`custodianRef`) resolves in the mirror.
+  rows.push(await mirror(io, docker, "custodian", custodianRef(), custodianRef(target)));
 
   const copied = rows.filter((r) => r.copied).length;
   activity(io, `mirrored ${copied} image(s), ${rows.length - copied} already present`);
@@ -97,7 +103,7 @@ export async function kit(args: string[], io: Io, docker: RunDocker = dockerCli)
 async function mirror(
   io: Io,
   docker: RunDocker,
-  image: KitImageName,
+  image: KitImageName | "custodian",
   source: string,
   target: string,
 ): Promise<Mirrored> {
@@ -106,7 +112,8 @@ async function mirror(
     return { image, source, target, copied: false };
   }
   await requireSource(docker, image, source, target);
-  await docker(["buildx", "imagetools", "create", "-t", target, source]);
+  // A digest-pinned target is pushed by its tag; the copy lands at that same digest.
+  await docker(["buildx", "imagetools", "create", "-t", target.replace(/@sha256:[0-9a-f]+$/, ""), source]);
   activity(io, `${image}: copied ${source} → ${target}`);
   return { image, source, target, copied: true };
 }
@@ -130,12 +137,17 @@ async function resolves(docker: RunDocker, ref: string): Promise<boolean> {
  * it points at is the other arm of ADR-0044: `just kit-push`, in the checkout, is what puts images
  * at a published name in the first place; this command only moves what is already there.
  */
-async function requireSource(docker: RunDocker, image: KitImageName, source: string, target: string): Promise<void> {
+async function requireSource(
+  docker: RunDocker,
+  image: KitImageName | "custodian",
+  source: string,
+  target: string,
+): Promise<void> {
   if (await resolves(docker, source)) return;
   throw new Error(
     `${image}: ${source} is not there, so nothing can be mirrored to ${target}\n` +
       `  a kit image reaches ${target} only by being copied from its published home;\n` +
       `  if v${KIT_VERSION} was never published (a dev version never is), seed a registry from a kit\n` +
-      `  checkout with \`just kit-push <registry>\`, which builds the three images from source`,
+      `  checkout with \`just kit-push <registry>\`, which builds the Kit images from source`,
   );
 }

package/src/commands/logs.ts

@@ -8,6 +8,7 @@ import { JR2Client } from "../client.ts";
 import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
 import { activity, result, type Io } from "../output.ts";
 import { resolveRunId } from "../run-id.ts";
+import { childErrorActivity, placingActivity } from "./run.ts";
 
 export async function logs(args: string[], io: Io): Promise<number> {
   const { values, positionals } = parseArgs({
@@ -39,6 +40,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,9 +7,14 @@
 // 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.
 
 import { parseArgs } from "node:util";
-import { JR2Client } from "../client.ts";
+import type { ChildErrorMarker, PlacingMarker } from "@jr2/orchestrator";
+import { JR2Client, JR2HttpError } from "../client.ts";
 import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
 import { activity, result, type Io } from "../output.ts";
 
@@ -27,7 +32,7 @@ export async function run(args: string[], io: Io): Promise<number> {
 
   const workflow = positionals[0];
   if (!workflow) {
-    activity(io, "usage: jr2 run <workflow> [--input <json>] [--detach]");
+    activity(io, "usage: jr2 run <workflow | wrapper/chart> [--input <json>] [--detach]");
     return 2;
   }
   const input = values.input ? (JSON.parse(String(values.input)) as Record<string, unknown>) : {};
@@ -35,7 +40,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 +63,56 @@ 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") {
         result(io, ev.status);
         return ev.status.status === "error" ? 1 : 0;
       }
     }
-    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,111 @@
 // `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.
+//
+// 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 type { RunChild } from "@jr2/orchestrator";
+import { JR2Client, type RunStatus, type WorkflowListing, type WorkflowOrigin } from "../client.ts";
 import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
-import { result, type Io } from "../output.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`;
 
 export async function runs(args: string[], io: Io): Promise<number> {
-  const { values } = parseArgs({ args, allowPositionals: true, strict: false, options: { ...TARGET_ARGS } });
+  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 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(markPlacing);
+    // 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, with `placing` after its id when any Workspace in it is in `placing`. */
+export function markPlacing(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 };
+}
+
+/** 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)];
+  });
+}