@jr2/cli 0.6.0 → 0.7.0

package/src/commands/completion.ts

@@ -0,0 +1,236 @@
+// `jr2 completion bash|zsh|fish` (ADR-0009): the shell completion script, a value on stdout.
+//
+// The script is small and the same for each shell: on each TAB it asks this jr2 for the words that
+// complete the command line, with `jr2 completion __complete <words…>`, the last word being the one
+// the cursor is in. The answer comes from the command table (`complete`), so a verb, a sub-verb or a
+// flag that the CLI does not take never completes. Some values come from the deployment: Workspace
+// handles (from the Sandbox CRs' labels, over kube), live run ids, Workflow names, and a run's Agent
+// slots (from the Orchestrator). Each lookup has 2 s: a slower one offers nothing, so a slow cluster
+// never holds the shell. `__complete` is not in the table: no person types it.
+
+import { JR2Client } from "../client.ts";
+import { commandsFor, COMMANDS, parseCommand, usageLine, type Command } from "../command-table.ts";
+import { resolveRoot, resolveTarget } from "../instance.ts";
+import { activity, type Io } from "../output.ts";
+import { kubectlWorkspaces, rowOf } from "../workspaces.ts";
+import { basename } from "node:path";
+import { loadConfig } from "@jr2/orchestrator/internal";
+
+/** The longest a dynamic lookup may take before it offers nothing. */
+export const LOOKUP_BUDGET_MS = 2_000;
+
+/** A value from the deployment, by what the argument or the flag names. */
+export type DynamicKind = "run" | "workflow" | "agent" | "workspace";
+
+/** Where `complete` finds dynamic values: `run` is the run id that the line names, for `agent`. */
+export type Lookup = (
+  kind: DynamicKind,
+  ctx: { run?: string; namespace?: string; context?: string },
+) => Promise<string[]>;
+
+/** The completion scripts: each asks `jr2 completion __complete` with the words up to the cursor. */
+export const SCRIPTS: Readonly<Record<"bash" | "zsh" | "fish", string>> = {
+  bash: [
+    "# jr2 completion for bash: source <(jr2 completion bash)",
+    "_jr2_complete() {",
+    "  local IFS=$'\\n'",
+    '  COMPREPLY=($(jr2 completion __complete "${COMP_WORDS[@]:1:COMP_CWORD}" 2>/dev/null))',
+    "}",
+    "complete -o default -F _jr2_complete jr2",
+    "",
+  ].join("\n"),
+  zsh: [
+    "#compdef jr2",
+    "# jr2 completion for zsh: source <(jr2 completion zsh)",
+    "_jr2() {",
+    "  local -a candidates",
+    // Unquoted, so an empty answer gives no element, and compadd adds no empty match.
+    '  candidates=(${(f)"$(jr2 completion __complete "${(@)words[2,CURRENT]}" 2>/dev/null)"})',
+    '  (( ${#candidates} )) && compadd -Q -- "${candidates[@]}"',
+    "}",
+    "compdef _jr2 jr2",
+    "",
+  ].join("\n"),
+  fish: [
+    "# jr2 completion for fish: jr2 completion fish | source",
+    "function __jr2_complete",
+    "    set -l words (commandline -opc) (commandline -ct)",
+    "    jr2 completion __complete $words[2..-1] 2>/dev/null",
+    "end",
+    "complete -c jr2 -f -a '(__jr2_complete)'",
+    "",
+  ].join("\n"),
+};
+
+/** The dynamic kind of a positional argument, by its name in the table. */
+function argKind(name: string): DynamicKind | "shell" | undefined {
+  if (name === "runId" || name === "run") return "run";
+  if (name === "workflow") return "workflow";
+  if (name === "agent") return "agent";
+  if (name === "ws") return "workspace";
+  if (name === "shell") return "shell";
+  return undefined;
+}
+
+/** Static values of a flag, or the dynamic kind it takes. */
+function flagValues(name: string): string[] | DynamicKind | undefined {
+  if (name === "workflow") return "workflow";
+  if (name === "status")
+    return ["live", "ended", "all", "active", "done", "failed", "error", "cancelled", "lost", "drifted"];
+  return undefined;
+}
+
+/**
+ * The words that complete `words` (the line after `jr2`; the last one is the word the cursor is in,
+ * empty at a new word). Verbs, sub-verbs, flags and their values from the command table; dynamic
+ * values from `lookup`. Every candidate starts with the current word.
+ */
+export async function complete(words: readonly string[], lookup: Lookup): Promise<string[]> {
+  const cur = words.at(-1) ?? "";
+  const done = words.slice(0, -1);
+  const starts = (list: Iterable<string>) => [...new Set(list)].filter((w) => w.startsWith(cur));
+  if (done.length === 0) return starts(COMMANDS.map((c) => c.verb));
+  const entries = commandsFor(done[0]!);
+  if (entries.length === 0) return [];
+  let entry: Command | undefined;
+  let rest: string[];
+  if (entries.some((c) => c.sub !== undefined)) {
+    if (done.length === 1) return starts(entries.flatMap((c) => (c.sub ? [c.sub] : [])));
+    entry = entries.find((c) => c.sub === done[1]);
+    rest = done.slice(2);
+  } else {
+    entry = entries[0];
+    rest = done.slice(1);
+  }
+  if (!entry) return [];
+
+  // The addressing on the line, for the lookups.
+  const flagOf = (word: string) =>
+    entry.flags.find((f) => word === `--${f.name}` || (f.short !== undefined && word === `-${f.short}`));
+  const given = (name: string) => {
+    const i = rest.findIndex((w) => flagOf(w)?.name === name);
+    return i >= 0 ? rest[i + 1] : undefined;
+  };
+  const ctx = {
+    ...(given("namespace") ? { namespace: given("namespace")! } : {}),
+    ...(given("context") ? { context: given("context")! } : {}),
+  };
+
+  // A flag's value.
+  const prev = flagOf(rest.at(-1) ?? "");
+  if (prev?.value !== undefined && !rest.includes("--")) {
+    const values = flagValues(prev.name);
+    if (values === undefined) return [];
+    return starts(Array.isArray(values) ? values : await lookup(values, ctx));
+  }
+  if (rest.includes("--")) return [];
+  if (cur.startsWith("-")) return starts(entry.flags.map((f) => `--${f.name}`));
+
+  // A positional: the arguments before the cursor, less the flags and their values.
+  const positionals: string[] = [];
+  for (let i = 0; i < rest.length; i++) {
+    const f = flagOf(rest[i]!);
+    if (f) {
+      if (f.value !== undefined) i++;
+      continue;
+    }
+    if (!rest[i]!.startsWith("-")) positionals.push(rest[i]!);
+  }
+  const arg = entry.args[positionals.length];
+  const kind = arg ? argKind(arg.name) : undefined;
+  if (kind === undefined) return [];
+  if (kind === "shell") return starts(Object.keys(SCRIPTS));
+  return starts(await lookup(kind, { ...ctx, ...(positionals[0] ? { run: positionals[0] } : {}) }));
+}
+
+/** `p`, or nothing after `ms`. A lookup that fails offers nothing too. */
+export async function bounded(p: Promise<string[]>, ms = LOOKUP_BUDGET_MS): Promise<string[]> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<string[]>((resolve) => {
+    timer = setTimeout(() => resolve([]), ms);
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([p.catch(() => []), late]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** The real lookups: the Sandbox CRs over kube, and the Orchestrator for the rest. Quiet: no
+ * activity. With them, the close of each forward to the Orchestrator that a lookup holds now: a
+ * lookup past its budget is still in flight when `__complete` exits. */
+function deploymentLookup(io: Io): { lookup: Lookup; closeOpen: () => void } {
+  const quiet: Io = { ...io, stderr: () => {} };
+  const open = new Set<() => void>();
+  const lookup: Lookup = async (kind, ctx) => {
+    if (kind === "workspace") {
+      const kube = io.workspaces ?? kubectlWorkspaces;
+      let namespace = ctx.namespace;
+      if (namespace === undefined) {
+        const root = resolveRoot(io.cwd);
+        namespace = (await loadConfig(root))?.name ?? basename(root);
+      }
+      const listed = await kube.list({ namespace, ...(ctx.context ? { context: ctx.context } : {}) });
+      return listed.items.flatMap((cr) => {
+        const row = rowOf(cr, listed.serverNow);
+        return row.path ? [row.handle, row.name] : [row.name];
+      });
+    }
+    const target = await resolveTarget(quiet, { namespace: ctx.namespace, context: ctx.context });
+    const close = () => target.close?.();
+    open.add(close);
+    try {
+      const client = new JR2Client(target.url, io.fetch, target.token, target.onBehalfOf);
+      if (kind === "run") return (await client.runs({ status: "live" })).runs.map((r) => r.runId);
+      if (kind === "workflow")
+        return (await client.workflows()).flatMap((w) => [
+          w.name,
+          ...(w.wrapper?.charts ?? []).map((c) => `${w.name}/${c.name}`),
+        ]);
+      if (ctx.run === undefined) return [];
+      const [live, kept] = await Promise.all([
+        client.agents(ctx.run).catch(() => []),
+        client.conversations(ctx.run).catch(() => []),
+      ]);
+      return [...live.map((a) => a.agent), ...kept.flatMap((c) => (c.slot ? [c.slot] : []))];
+    } finally {
+      open.delete(close);
+      close();
+    }
+  };
+  return {
+    lookup,
+    closeOpen: () => {
+      for (const close of open) close();
+      open.clear();
+    },
+  };
+}
+
+export async function completion(
+  args: string[],
+  io: Io,
+  opts: { lookup?: Lookup; exit?: (code: number) => void; budgetMs?: number } = {},
+): Promise<number> {
+  if (args[0] === "__complete") {
+    const deployment = opts.lookup ? undefined : deploymentLookup(io);
+    const lookup = opts.lookup ?? deployment!.lookup;
+    const words = await complete(args.slice(1), (kind, ctx) => bounded(lookup(kind, ctx), opts.budgetMs));
+    for (const w of words) io.stdout(`${w}\n`);
+    // A lookup past its budget is still in flight, and the shell waits for this process: close the
+    // forward that it holds (its kubectl child also ends on this process's exit, `endsWithProcess`),
+    // then exit, not waiting for the lookup.
+    deployment?.closeOpen();
+    (opts.exit ?? ((code: number) => process.exit(code)))(0);
+    return 0;
+  }
+  const { positionals } = parseCommand("completion", args);
+  const shell = positionals[0] as keyof typeof SCRIPTS | undefined;
+  if (shell === undefined || !(shell in SCRIPTS) || positionals.length > 1) {
+    activity(io, usageLine("completion"));
+    return 2;
+  }
+  io.stdout(SCRIPTS[shell]);
+  return 0;
+}

package/src/commands/gates.ts

@@ -0,0 +1,23 @@
+// `jr2 gates` (ADR-0011): the Gate inbox as JSON on stdout. Each open Gate of every live run that
+// this Caller may answer, oldest first, from `GET /gates`: its run, the run's Workflow, the Gate's
+// id and path, the events it accepts and those it takes now, its `meta`, when it opened, and the
+// Hook kinds that it hears. Never a run's context (ADR-0014). `--workflow` keeps one Workflow's
+// runs. A Caller whose `answer` scope names single Gates sees only those Gates (ADR-0078).
+// `jr2 send <runId> --gate <gate> --event <name>` answers one.
+
+import { JR2Client } from "../client.ts";
+import { parseCommand } from "../command-table.ts";
+import { resolveTarget, targetOptions } from "../instance.ts";
+import { result, type Io } from "../output.ts";
+
+export async function gates(args: string[], io: Io): Promise<number> {
+  const { values } = parseCommand("gates", args);
+  const target = await resolveTarget(io, targetOptions(values));
+  try {
+    const client = new JR2Client(target.url, io.fetch, target.token, target.onBehalfOf);
+    result(io, await client.gates(typeof values.workflow === "string" ? values.workflow : undefined));
+    return 0;
+  } finally {
+    target.close?.();
+  }
+}

package/src/commands/hooks.ts

@@ -0,0 +1,31 @@
+// `jr2 hooks <name>` (ADR-0011): a Hook's log, as `GET /hooks/:name` gives it — each delivery of
+// the time that jr2 keeps it (`runs.retain`), newest first, and what the door did with it: a handshake, the outcome of a
+// delivery, a repeat, a payload that the parse refused, a request that the kind could not read, or
+// a follow-up post that failed.
+// The route takes the Instance token alone, so on a kube context the CLI reads it, as for every
+// run-verb; with `--url` it needs `JR2_TOKEN` to be the Instance token.
+
+import { JR2Client } from "../client.ts";
+import { commandNamed, parseCommand, renderCommand } from "../command-table.ts";
+import { resolveTarget, targetOptions } from "../instance.ts";
+import { activity, result, type Io } from "../output.ts";
+
+export async function hooks(args: string[], io: Io): Promise<number> {
+  const { values, positionals } = parseCommand("hooks", args);
+  const [name] = positionals;
+  const limit = values.limit === undefined ? undefined : Number(values.limit);
+  if (!name || positionals.length > 1 || (limit !== undefined && !(Number.isInteger(limit) && limit >= 1))) {
+    activity(io, renderCommand(commandNamed("hooks")));
+    return 2;
+  }
+  const target = await resolveTarget(io, targetOptions(values));
+  try {
+    const client = new JR2Client(target.url, io.fetch, target.token, target.onBehalfOf);
+    const log = await client.hookLog(name, limit);
+    if (!log.declared) activity(io, `note: the current Assembly's config declares no Hook "${name}"`);
+    result(io, log);
+    return 0;
+  } finally {
+    target.close?.();
+  }
+}

package/src/commands/init.ts

@@ -195,9 +195,8 @@ export default defineConfig({
 // injects its runtime at POD time and never builds a stage on top of this file. It also satisfies
 // the floor by construction — a glibc base with git — so the `preflight` init step that proves it
 // at the pod's first provision passes without the author ever meeting it.
-const IMAGE_DOCKERFILE = `# A Sandbox Image (ADR-0037): the tools your agents can reach, and the shell you get when you
-# \`kubectl exec\` into a running Workspace. This file is yours — jr2 never rewrites it and reads
-# nothing out of it.
+const IMAGE_DOCKERFILE = `# A Sandbox Image (ADR-0037): the tools your agents can reach, and the shell you get with
+# \`jr2 workspace shell\`. This file is yours — jr2 never rewrites it and reads nothing out of it.
 #
 # The build context is THIS directory (\`images/default/\`), so \`COPY\` paths are relative to it and
 # nothing outside it can invalidate the image's content hash.

package/src/commands/logs.ts

@@ -1,53 +1,129 @@
-// `jr2 logs <runId|abbrev> [-f]` (ADR-0009): re-attach to a run's feed. The orchestrator replays the current
-// status on attach, so even without -f you see where the run IS right now (status → stdout as JSON;
-// 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.
+// `jr2 logs <runId|abbrev> [agent] [-f]` (ADR-0009, ADR-0023): a run's kept conversations, printed
+// as the Harness prints them to its pod log. Each line is `[<agent>] [<instance id>] <body line>`,
+// and a body starts with its label (`[text]`, `[bash]`, `[<pick> answer]`, `[cut]`). The
+// conversations of every Agent of the run are interleaved by the time of each entry, or `[agent]`
+// keeps one: an Agent slot as `jr2 steer <runId>` lists it (`<machine path>/<agent>`), or an Agent
+// name. Menu-only Agents too. It reads the Orchestrator's record, so it works after the Sandbox is
+// gone, for as long as the run is kept (`runs.retain`, ADR-0065).
+//
+// `-f` follows: it prints what is kept, then each new entry as the Orchestrator keeps it, and
+// starts to follow each new conversation of the run, until the run is not live and no conversation
+// is open. The line format is the Harness's `printLines` (packages/harness/src/printer.ts); the CLI
+// does not import the Harness, so it is stated again here, and the test holds the two the same.
 
-import { JR2Client } from "../client.ts";
+import { JR2Client, type ConversationEntryView, type KeptConversationView } from "../client.ts";
 import { resolveTarget, targetOptions } from "../instance.ts";
-import { activity, result, type Io } from "../output.ts";
+import { activity, 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> {
+/** How often `-f` asks for the run's conversations, to find a new one. */
+export const LOGS_POLL_MS = 2_000;
+
+/** One kept entry as the lines of the print (ADR-0023): `[<agent>] [<instance id>] ` before each line
+ * of its body. An entry that kept no label prints its text alone, as the Harness printed it. */
+export function printedLines(instanceId: string, entry: ConversationEntryView): string {
+  const body = entry.kind === "line" ? entry.text : `[${entry.kind}] ${entry.text}`;
+  return body
+    .split("\n")
+    .map((line) => `[${entry.agent}] [${instanceId}] ${line}\n`)
+    .join("");
+}
+
+/** The conversations that `agent` names: those of that slot, else those of that Agent name. */
+export function conversationsOf(
+  all: readonly KeptConversationView[],
+  agent: string | undefined,
+): KeptConversationView[] {
+  if (agent === undefined) return [...all];
+  const bySlot = all.filter((c) => c.slot === agent);
+  return bySlot.length ? bySlot : all.filter((c) => c.agent === agent);
+}
+
+/** Every kept entry of one conversation after `after`, page by page. */
+async function entriesAfter(client: JR2Client, runId: string, instanceId: string, after: number) {
+  const out: ConversationEntryView[] = [];
+  for (let last = after; ; ) {
+    const page = await client.conversationEntries(runId, instanceId, last);
+    out.push(...page);
+    if (page.length < 1000) return out;
+    last = page.at(-1)!.seq;
+  }
+}
+
+export async function logs(args: string[], io: Io, opts: { pollMs?: number } = {}): Promise<number> {
   const { values, positionals } = parseCommand("logs", args);
-  const given = positionals[0];
-  if (!given) {
+  const [given, agent] = positionals;
+  if (!given || positionals.length > 2) {
     activity(io, usageLine("logs"));
     return 2;
   }
   const target = await resolveTarget(io, targetOptions(values));
   try {
-    const client = new JR2Client(target.url, io.fetch, target.token);
+    const client = new JR2Client(target.url, io.fetch, target.token, target.onBehalfOf);
     const ref = await resolveRunId(client, given);
     if (!ref.ok) {
       activity(io, ref.message);
       return ref.code;
     }
+    const runId = ref.runId;
+    const all = await client.conversations(runId);
+    const chosen = conversationsOf(all, agent);
+    if (agent !== undefined && chosen.length === 0) {
+      const names = [...new Set(all.map((c) => c.slot ?? c.agent))];
+      activity(
+        io,
+        `run ${runId} keeps no conversation of "${agent}"` +
+          (names.length ? ` — its Agents: ${names.join(", ")}` : " — it keeps no conversation yet"),
+      );
+      if (!values.follow) return 1;
+    }
+    for (const c of chosen) {
+      if (c.swept) activity(io, `${c.slot ?? c.agent} [${c.instanceId}]: ${c.swept}`);
+    }
 
-    for await (const ev of client.events(ref.runId)) {
-      if (ev.kind === "emit") {
-        activity(io, `emit ${JSON.stringify(ev.event)}`);
-        continue;
-      }
-      if (ev.kind === "retry") {
-        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;
+    // What is kept now, every chosen conversation interleaved by time.
+    const last = new Map<string, number>();
+    const kept = await Promise.all(
+      chosen.map(async (c) => ({ c, entries: await entriesAfter(client, runId, c.instanceId, -1) })),
+    );
+    const merged = kept.flatMap(({ c, entries }) => entries.map((entry) => ({ iid: c.instanceId, entry })));
+    merged.sort((a, b) => a.entry.at.localeCompare(b.entry.at) || a.entry.seq - b.entry.seq);
+    for (const { iid, entry } of merged) io.stdout(printedLines(iid, entry));
+    for (const { c, entries } of kept) last.set(c.instanceId, entries.at(-1)?.seq ?? -1);
+    if (!values.follow) return 0;
+
+    // Follow: each conversation from its last printed entry, and each new one from its first.
+    const following = new Map<string, Promise<void>>();
+    const finished = new Set<string>(); // conversations followed to the end of their feed
+    const follow = (c: KeptConversationView) => {
+      if (following.has(c.instanceId)) return;
+      const after = last.get(c.instanceId) ?? -1;
+      following.set(
+        c.instanceId,
+        (async () => {
+          for await (const entry of client.followConversation(runId, c.instanceId, after)) {
+            last.set(c.instanceId, entry.seq);
+            io.stdout(printedLines(c.instanceId, entry));
+          }
+        })()
+          .catch((err: unknown) => activity(io, `${c.slot ?? c.agent} [${c.instanceId}]: ${(err as Error).message}`))
+          .finally(() => {
+            following.delete(c.instanceId);
+            finished.add(c.instanceId);
+          }),
+      );
+    };
+    const pollMs = opts.pollMs ?? LOGS_POLL_MS;
+    for (;;) {
+      // An open conversation is followed; one that is not open is followed once, to read its end.
+      for (const c of conversationsOf(await client.conversations(runId), agent)) {
+        if (c.open || (!finished.has(c.instanceId) && !c.cut && !c.swept)) follow(c);
       }
-      result(io, ev.status);
-      if (!values.follow) break;
-      if (ev.status.status !== "active") break;
+      const status = (await client.read(runId))?.status;
+      if (status !== "active" && following.size === 0) return 0;
+      await new Promise((r) => setTimeout(r, pollMs));
     }
-    return 0;
   } finally {
     target.close?.();
   }

package/src/commands/run.ts

@@ -1,4 +1,4 @@
-// `jr2 run <workflow> [--input <json>] [--detach]` (ADR-0009). BLOCKING + attach-by-default, mirroring
+// `jr2 run <workflow> [--input <json>] [--detach] [--drop-held]` (ADR-0009). BLOCKING + attach-by-default, mirroring
 // `flue run`: start the run, then attach to its SSE feed — status deltas + author emits go to stderr
 // as they happen; the terminal RunStatus is printed as JSON on stdout and we exit. So `jr2 run ping`
 // shows progress to a human while `jr2 run ping | jq` yields just the result.
@@ -12,13 +12,23 @@
 // 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.
 //
+// A standing Workflow (ADR-0017): jr2 starts its run, so `jr2 run` of it only resumes a paused
+// one, with its held items (none with `--drop-held`). It prints the new run and returns, because a
+// standing run never ends by itself. The door refuses it with 409 while the Workflow is not paused.
+//
 // 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 type { ChildErrorMarker, PlacingMarker } from "@jr2/orchestrator/internal";
-import { JR2Client, JR2HttpError } from "../client.ts";
+import type {
+  ChildErrorMarker,
+  GateMarker,
+  HookRefusedMarker,
+  PlacingMarker,
+  PoolMarker,
+} from "@jr2/orchestrator/internal";
+import { JR2Client, JR2HttpError, type RunFeedEvent } from "../client.ts";
 import { failureActivity } from "./status.ts";
 import { resolveTarget, targetOptions } from "../instance.ts";
 import { activity, result, type Io } from "../output.ts";
@@ -35,16 +45,25 @@ export async function run(args: string[], io: Io): Promise<number> {
   const input = values.input ? (JSON.parse(String(values.input)) as Record<string, unknown>) : {};
   const target = await resolveTarget(io, targetOptions(values));
   try {
-    const client = new JR2Client(target.url, io.fetch, target.token);
+    const client = new JR2Client(target.url, io.fetch, target.token, target.onBehalfOf);
 
     let runId: string;
+    let resumed = false;
     try {
-      ({ runId } = await client.start(workflow, input));
+      ({ runId, resumed = false } = (await client.start(workflow, input, {
+        dropHeld: values["drop-held"] === true,
+      })) as { runId: string; resumed?: boolean });
     } catch (err) {
       if (!(err instanceof JR2HttpError) || !err.report) throw err;
       activity(io, refusalActivity(workflow, err.report));
       return 1;
     }
+    // A standing run never ends by itself (ADR-0017): the resume prints it and returns.
+    if (resumed) {
+      activity(io, `resumed the standing workflow ${workflow}: run ${runId}`);
+      result(io, { runId, resumed: true });
+      return 0;
+    }
     if (values.detach) {
       result(io, { runId });
       return 0;
@@ -52,24 +71,8 @@ export async function run(args: string[], io: Io): Promise<number> {
 
     activity(io, `run ${runId} (${workflow}) — attached`);
     for await (const ev of client.events(runId)) {
-      if (ev.kind === "emit") {
-        activity(io, `  emit ${JSON.stringify(ev.event)}`);
-        continue;
-      }
-      if (ev.kind === "retry") {
-        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") {
+      activity(io, `  ${attachedLine(ev)}`);
+      if (ev.kind === "status" && ev.status.status !== "active") {
         const failed = failureActivity(ev.status);
         if (failed) activity(io, failed);
         result(io, ev.status);
@@ -79,16 +82,40 @@ export async function run(args: string[], io: Io): Promise<number> {
     // `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`,
-    );
+    activity(io, `run ${runId} is parked: stopped before it settled — \`jr2 watch ${runId}\` follows it once restored`);
     return 1;
   } finally {
     target.close?.();
   }
 }
 
+/**
+ * One event of a run's feed as the line `jr2 run` prints while it is attached, and `jr2 watch`
+ * prints (ADR-0009): an Emit, a retry, a wait for capacity, a child's error, a Gate's look, a
+ * Hook's refused delivery, a Pool's mark, or where the run stands.
+ */
+export function attachedLine(ev: RunFeedEvent): string {
+  switch (ev.kind) {
+    case "emit":
+      return `emit ${JSON.stringify(ev.event)}`;
+    case "retry":
+      return `retry ${ev.child} attempt ${ev.attempt} (${ev.reason})`;
+    case "placing":
+    case "placed":
+      return placingActivity(ev);
+    case "child-error":
+      return childErrorActivity(ev);
+    case "looked":
+      return lookedActivity(ev);
+    case "hook-refused":
+      return hookRefusedActivity(ev);
+    case "pool":
+      return poolActivity(ev);
+    case "status":
+      return `→ ${ev.status.status} ${JSON.stringify(ev.status.value)}`;
+  }
+}
+
 /**
  * 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.
@@ -108,6 +135,29 @@ export function placingActivity(ev: PlacingMarker): string {
   return `placing${who}: waits for ${ev.on === "quota" ? "quota" : "a node"} — ${ev.message}`;
 }
 
+/** A Gate's look as one activity line (ADR-0011): the look read its fact, and the run took its event. */
+export function lookedActivity(ev: GateMarker): string {
+  return `looked: gate ${ev.gate} read its fact, and the run took "${ev.event}"`;
+}
+
+/** A Hook's delivery that a Gate did not take, as one activity line (ADR-0011): the run goes on. */
+export function hookRefusedActivity(ev: HookRefusedMarker): string {
+  return (
+    `hook-refused: hook ${ev.hook} delivery ${ev.delivery} at gate ${ev.gate}` +
+    `${ev.event !== undefined ? ` ("${ev.event}")` : ""} — ${ev.reason}`
+  );
+}
+
+/** What a Pool of runs did with one item, as one activity line (ADR-0017). */
+export function poolActivity(ev: PoolMarker): string {
+  const run = ev.run !== undefined ? ` run ${ev.run}` : "";
+  if (ev.mark === "started")
+    return `pool ${ev.pool}: started ${ev.key}${run}${ev.existing ? " (the key found it)" : ""}`;
+  if (ev.mark === "skipped") return `pool ${ev.pool}: skipped an item — ${ev.reason ?? ""}`;
+  if (ev.mark === "carry-refused") return `pool ${ev.pool}: carry-refused ${ev.key} — ${ev.reason ?? ""}`;
+  return `pool ${ev.pool}: settled ${ev.key}${run} ${ev.status ?? ""}${ev.reason !== undefined ? ` — ${ev.reason}` : ""}`;
+}
+
 /**
  * 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.