@jr2/cli 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/cli",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "The jr2 CLI: init, up, run — the interface to a jr2 Instance.",
   "license": "MIT",
   "private": false,
@@ -39,14 +39,14 @@
     "ts-blank-space": "^0.9.0"
   },
   "peerDependencies": {
-    "@jr2/orchestrator": "0.5.1"
+    "@jr2/orchestrator": "0.7.0"
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "0.91.1",
     "@types/node": "^26.0.1",
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/orchestrator": "0.5.1"
+    "@jr2/orchestrator": "0.7.0"
   },
   "files": [
     "bin",

package/src/build.ts

@@ -375,10 +375,10 @@ export const KIT_IMAGES: Record<KitImageName, KitImage> = {
     dockerfile: "deploy/orchestrator/Dockerfile",
     context: ".",
     // `@jr2/orchestrator` and every kit package it depends on, which the Dockerfile packs into the
-    // image (ADR-0069). `packages/agent-protocol` is a runtime dependency, so an edit there changes
-    // the image and must move its tag. The third-party closure (xstate, zod, hono, …) comes from
-    // the registry, each package forced to the version `deploy/orchestrator/closure.json` pins, so
-    // the tag addresses it through that file. closure.json equals pnpm-lock.yaml's closure, and
+    // image (ADR-0069). `packages/agent-protocol` is a runtime dependency, so
+    // an edit there changes the image and must move its tag. The third-party closure (xstate, zod,
+    // hono, …) comes from the registry, each package forced to the version
+    // `deploy/orchestrator/closure.json` pins, so the tag addresses it through that file. closure.json equals pnpm-lock.yaml's closure, and
     // this list equals the Orchestrator's `workspace:` dependencies, both asserted in
     // test/orchestrator-image.test.ts.
     sources: ["packages/orchestrator", "packages/agent-protocol", "deploy/orchestrator"],

package/src/caller-tokens.ts

@@ -0,0 +1,108 @@
+// The named Caller tokens on the cluster (ADR-0078): what `jr2 up` and `jr2 caller rotate` share.
+//
+// Each name that `callers.tokens` declares has a Secret of its own, `jr2-caller-<name>`, which holds
+// its value (`jr2c_` and 32 random bytes in base64url) and which no pod mounts. The Orchestrator
+// gets only the digests, in `jr2-caller-digests`, which it mounts and reads again when it changes.
+// So the value stays where kube RBAC guards it, as the Instance token does, and a new token or a
+// rotation rolls no pod.
+//
+// `jr2 up` makes a value once, for a name that has none, and keeps it after that. It deletes the
+// Secret of a name that the config no longer declares, so that value stops working. `jr2 caller
+// rotate` makes a new value for one name and writes the digests again from every token Secret.
+
+import { CALLER_TOKEN_PREFIX, mintCallerToken } from "@jr2/orchestrator/internal";
+import { CALLER_TOKEN_KEY, callerTokenObjects, LABEL_CALLER_TOKEN, LABEL_INSTANCE } from "./deploy.ts";
+import type { KubeAdmin, KubeObject } from "./kube.ts";
+import { mountedDigests, type AppliedObject } from "./mount-wait.ts";
+
+type Ctx = { context?: string };
+type SecretObject = KubeObject & { data?: Record<string, string> };
+
+/** The values of the token Secrets in the namespace, by the name on their label. A Secret with no
+ * value, or a value that is not a Caller token's, is left out. */
+export async function storedCallerTokens(kube: KubeAdmin, namespace: string, ctx: Ctx): Promise<Map<string, string>> {
+  const found = new Map<string, string>();
+  for (const secret of await kube.listJson<SecretObject>({
+    kind: "secret",
+    selector: LABEL_CALLER_TOKEN,
+    namespace,
+    ...ctx,
+  })) {
+    const name = secret.metadata.labels?.[LABEL_CALLER_TOKEN];
+    const b64 = secret.data?.[CALLER_TOKEN_KEY];
+    if (!name || !b64) continue;
+    const value = Buffer.from(b64, "base64").toString("utf8");
+    if (value.startsWith(CALLER_TOKEN_PREFIX)) found.set(name, value);
+  }
+  return found;
+}
+
+/** What `jr2 up` does with the named Caller tokens: the value of each declared name, the names it
+ * made a value for now, and the names whose Secret it deletes. */
+export type CallerTokenPlan = {
+  values: Record<string, string>;
+  made: string[];
+  undeclared: string[];
+};
+
+/**
+ * Plan the named Caller tokens for one converge (ADR-0078): keep the stored value of each declared
+ * name, make one for a declared name that has none, and name each stored name that the config no
+ * longer declares.
+ */
+export async function planCallerTokens(
+  kube: KubeAdmin,
+  declared: readonly string[],
+  namespace: string,
+  ctx: Ctx,
+): Promise<CallerTokenPlan> {
+  const stored = await storedCallerTokens(kube, namespace, ctx);
+  const values: Record<string, string> = {};
+  const made: string[] = [];
+  for (const name of [...declared].sort()) {
+    const kept = stored.get(name);
+    if (kept !== undefined) values[name] = kept;
+    else {
+      values[name] = mintCallerToken();
+      made.push(name);
+    }
+  }
+  const undeclared = [...stored.keys()].filter((n) => !declared.includes(n)).sort();
+  return { values, made, undeclared };
+}
+
+/**
+ * Make a new value for one named Caller token, and write the digests again (ADR-0078). The value
+ * goes first: when the digests write fails, `jr2 caller rotate` runs again and the token still has
+ * a value that `jr2 caller token` prints. Refuses a name that has no token Secret: `jr2 up` makes
+ * it, from the config. Returns the digest of the digests Secret it applied, by name
+ * (`mountedDigests`): `jr2 caller rotate` waits until the Orchestrator has loaded it.
+ */
+export async function rotateCallerToken(
+  kube: KubeAdmin,
+  opts: { instance: string; namespace: string; name: string; ctx: Ctx },
+): Promise<Record<string, string>> {
+  const stored = await storedCallerTokens(kube, opts.namespace, opts.ctx);
+  if (!stored.has(opts.name)) {
+    const known = [...stored.keys()].sort();
+    throw new Error(
+      `no Caller token "${opts.name}" in namespace "${opts.namespace}" — declare it in callers.tokens of ` +
+        `jr2.config.ts and run \`jr2 up\`${known.length ? ` (tokens here: ${known.join(", ")})` : ""}`,
+    );
+  }
+  stored.set(opts.name, mintCallerToken());
+  const labels = { [LABEL_INSTANCE]: opts.instance, "app.kubernetes.io/managed-by": "jr2" };
+  const meta = (name: string, extra: Record<string, string> = {}) => ({
+    name,
+    namespace: opts.namespace,
+    labels: { ...labels, ...extra },
+  });
+  const [valueSecret, digests] = callerTokenObjects(Object.fromEntries(stored), meta).filter(
+    (o) =>
+      (o.metadata as { labels: Record<string, string> }).labels[LABEL_CALLER_TOKEN] === opts.name ||
+      (o.metadata as { labels: Record<string, string> }).labels[LABEL_CALLER_TOKEN] === undefined,
+  );
+  await kube.apply({ manifest: JSON.stringify(valueSecret), ...opts.ctx });
+  await kube.apply({ manifest: JSON.stringify(digests), ...opts.ctx });
+  return mountedDigests([digests as AppliedObject]);
+}

package/src/cli.ts

@@ -11,15 +11,24 @@ import { loadDotenv } from "./env.ts";
 import { init } from "./commands/init.ts";
 import { run } from "./commands/run.ts";
 import { runs } from "./commands/runs.ts";
+import { workflows } from "./commands/workflows.ts";
+import { gates } from "./commands/gates.ts";
 import { status } from "./commands/status.ts";
 import { logs } from "./commands/logs.ts";
+import { watch } from "./commands/watch.ts";
+import { workspace } from "./commands/workspace.ts";
+import { completion } from "./commands/completion.ts";
 import { send } from "./commands/send.ts";
+import { steer } from "./commands/steer.ts";
 import { up } from "./commands/up.ts";
 import { check } from "./commands/check.ts";
 import { down } from "./commands/down.ts";
 import { gc } from "./commands/gc.ts";
 import { kit } from "./commands/kit.ts";
 import { version } from "./commands/version.ts";
+import { whoami } from "./commands/whoami.ts";
+import { hooks } from "./commands/hooks.ts";
+import { caller } from "./commands/caller.ts";
 import { asksForHelp, commandsFor, GLOBAL, renderCommand, renderHelp } from "./command-table.ts";
 
 /**
@@ -48,8 +57,12 @@ export async function main(argv: string[], io: Io = defaultIo): Promise<number>
     // `jr2.config.ts` (whose deployment-varying values are read from there — ADR-0019).
     loadDotenv(io);
     const entries = cmd === undefined ? [] : commandsFor(cmd);
-    if (entries.length && asksForHelp(entries, rest)) {
-      activity(io, entries.map(renderCommand).join("\n\n"));
+    // `completion __complete` carries the line being completed, which can hold `-h` itself.
+    const completing = cmd === "completion" && rest[0] === "__complete";
+    if (entries.length && !completing && asksForHelp(entries, rest)) {
+      // `jr2 caller rotate --help` prints that sub-verb's entry; `jr2 caller --help` prints each.
+      const named = entries.filter((c) => c.sub !== undefined && c.sub === rest[0]);
+      activity(io, (named.length ? named : entries).map(renderCommand).join("\n\n"));
       return 0;
     }
     if (cmd !== undefined && (GLOBAL.help as readonly string[]).includes(cmd)) {
@@ -63,12 +76,20 @@ export async function main(argv: string[], io: Io = defaultIo): Promise<number>
         return await run(rest, io);
       case "runs":
         return await runs(rest, io);
+      case "workflows":
+        return await workflows(rest, io);
+      case "gates":
+        return await gates(rest, io);
       case "status":
         return await status(rest, io);
+      case "watch":
+        return await watch(rest, io);
       case "logs":
         return await logs(rest, io);
       case "send":
         return await send(rest, io);
+      case "steer":
+        return await steer(rest, io);
       case "check":
         return await check(rest, io);
       case "up":
@@ -79,6 +100,16 @@ export async function main(argv: string[], io: Io = defaultIo): Promise<number>
         return await gc(rest, io);
       case "kit":
         return await kit(rest, io);
+      case "whoami":
+        return await whoami(rest, io);
+      case "hooks":
+        return await hooks(rest, io);
+      case "caller":
+        return await caller(rest, io);
+      case "workspace":
+        return await workspace(rest, io);
+      case "completion":
+        return await completion(rest, io);
       case "version":
       case "--version":
         return await version(rest, io);

package/src/client.ts

@@ -6,23 +6,42 @@
 // `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 {
-  ChildErrorMarker,
-  DispatchedBy,
-  MachineDoc,
-  PlacingMarker,
-  RepoStatus,
-  RunChild,
-  RunWaiting,
+import {
+  ON_BEHALF_OF_HEADER,
+  type CallerRecord,
+  type ChildErrorMarker,
+  type GateMarker,
+  type HookLogLine,
+  type HookRefusedMarker,
+  type PoolMarker,
+  type DispatchedBy,
+  type GateInboxEntry,
+  type MachineDoc,
+  type PlacingMarker,
+  type RepoStatus,
+  type RunChild,
+  type RunPage,
+  type RunSummary,
+  type RunStarter,
+  type RunWaiting,
+  type Scopes,
+  type ShownStatus,
 } from "@jr2/orchestrator/internal";
 import { parseSSE } from "./sse.ts";
 
+/** The query of `GET /runs` (ADR-0009): `status` is `live` (the default), `ended`, `all`, or a comma
+ * list; `since` a duration back from now or an ISO-8601 time; `cursor` a page's `next`. */
+export type RunsQuery = { status?: string; workflow?: string; since?: string; cursor?: string; limit?: number };
+
+export type { RunPage, RunSummary };
+
 /** A run's current observable state — mirrors the orchestrator's `RunStatus` (run-host.ts). */
 export type RunStatus = {
   runId: string;
   workflow: string;
   instanceId: string;
-  status: string;
+  /** `active` while the run is live, else how it ended (ADR-0025): never xstate's `stopped`. */
+  status: ShownStatus;
   value: unknown;
   context: unknown;
   /** The live child machines beneath the root, context-free — where most of a run is. */
@@ -53,8 +72,24 @@ export type RunStatus = {
   /** The runs this run's `dispatch` Effects started, oldest first: the slot, the run, and when its
    * ledger row was written (ADR-0071). Absent when it started none. */
   dispatched?: Array<{ slot: string; run: string; at: string }>;
+  /** The Worktrees this run's cuts made, oldest first: the Repo Slot, the path, and the branch,
+   * `null` when detached (ADR-0075). Absent when it cut none. */
+  worktrees?: Array<{ slot: string; path: string; branch: string | null }>;
+  /** Who started the run (ADR-0078): a Caller, a run through a local `dispatch`, or jr2. Behind the
+   * token; absent for a run that a host started with no starter. */
+  startedBy?: RunStarter;
+  /** The Caller that cancelled the run (ADR-0078). */
+  cancelledBy?: CallerRecord;
+  /** The Caller whose `jr2 run` resumed this standing run (ADR-0017, ADR-0078). */
+  resumedBy?: CallerRecord;
+  /** The run that took over from this standing run at a hand-over (ADR-0017). */
+  handedOverTo?: string;
 };
 
+/** A request's Caller, as `GET /whoami` gives it (ADR-0078): how jr2 knows it, its name, the name
+ * jr2 shows, what it may do, and the party it says it acts for. */
+export type WhoAmI = CallerRecord & { may: Scopes };
+
 /** 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";
@@ -80,12 +115,37 @@ export type RunFeedEvent =
   | { kind: "emit"; event: { type: string } & Record<string, unknown> }
   | { kind: "retry"; child: string; attempt: number; reason: string }
   | PlacingMarker
-  | ChildErrorMarker;
+  | ChildErrorMarker
+  | GateMarker
+  | HookRefusedMarker
+  | PoolMarker;
+
+/** A Hook's log, as `GET /hooks/:name` gives it (ADR-0011): whether the current config declares the
+ * Hook, and its lines, newest first. */
+export type HookLog = { hook: string; declared: boolean; lines: HookLogLine[] };
 
 /** 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 };
 
+/** One kept conversation, as `GET /runs/:runId/conversations` lists it (ADR-0023). `slot` is the
+ * Agent slot from the run's admission ledger. */
+export type KeptConversationView = {
+  agent: string;
+  slot?: string;
+  instanceId: string;
+  open: boolean;
+  bytes: number;
+  cut: boolean;
+  swept?: string;
+};
+
+/** One entry of a kept conversation (ADR-0023): one body of the print, its label as `kind`. */
+export type ConversationEntryView = { id: string; seq: number; at: string; agent: string; kind: string; text: string };
+
+/** One Agent slot of a live run, as `GET /runs/:runId/agents` lists it (ADR-0002). */
+export type RunAgentView = { agent: string; open: boolean; steerable: 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>;
 
@@ -136,19 +196,44 @@ export function workflowPath(workflow: string): string {
 export class JR2Client {
   readonly baseUrl: string;
   private readonly fetchImpl: FetchLike;
-  /** The Instance token (ADR-0013). The run and gate surfaces are authenticated; without it every
-   * call below is a 401. Absent only for an unauthenticated surface (a test's in-process app). */
+  /** The Caller's credential (ADR-0078): the Instance token, or any Caller's. The run and gate
+   * surfaces are authenticated; without it every call below is a 401. Absent only for an
+   * unauthenticated surface (a test's in-process app). */
   private readonly token?: string;
+  /** The party the Caller says it acts for, sent as `jr2-on-behalf-of` with the bearer (ADR-0078). */
+  private readonly onBehalfOf?: string;
 
-  constructor(baseUrl: string, fetchImpl: FetchLike = globalThis.fetch, token?: string) {
+  constructor(baseUrl: string, fetchImpl: FetchLike = globalThis.fetch, token?: string, onBehalfOf?: string) {
     this.baseUrl = baseUrl.replace(/\/+$/, "");
     this.fetchImpl = fetchImpl;
     this.token = token;
+    this.onBehalfOf = onBehalfOf;
   }
 
-  /** Request headers: the bearer, plus whatever the call adds. */
+  /** Request headers: the bearer and the party it acts for, plus whatever the call adds. */
   private headers(extra: Record<string, string> = {}): Record<string, string> {
-    return this.token ? { ...extra, authorization: `Bearer ${this.token}` } : extra;
+    if (!this.token) return extra;
+    return {
+      ...extra,
+      authorization: `Bearer ${this.token}`,
+      ...(this.onBehalfOf ? { [ON_BEHALF_OF_HEADER]: this.onBehalfOf } : {}),
+    };
+  }
+
+  /** `GET /whoami` — the Caller this credential is (ADR-0078). It needs no scope, so a credential
+   * that may do nothing still learns why. */
+  async whoami(): Promise<WhoAmI> {
+    const res = await this.fetchImpl(`${this.baseUrl}/whoami`, { headers: this.headers() });
+    return (await this.json(res, "/whoami")) as WhoAmI;
+  }
+
+  /** `GET /hooks/:name` — a Hook's log, newest first (ADR-0011). The Instance token alone. */
+  async hookLog(name: string, limit?: number): Promise<HookLog> {
+    const query = limit === undefined ? "" : `?limit=${limit}`;
+    const res = await this.fetchImpl(`${this.baseUrl}/hooks/${encodeURIComponent(name)}${query}`, {
+      headers: this.headers(),
+    });
+    return (await this.json(res, "/hooks/:name")) as HookLog;
   }
 
   /** `GET /workflows` — every registered Workflow with its origin, each Chart wrapper's Charts inside
@@ -183,19 +268,57 @@ export class JR2Client {
   /** `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}${workflowPath(workflow)}/runs`, {
+  async start(
+    workflow: string,
+    input: Record<string, unknown> = {},
+    opts: { dropHeld?: boolean } = {},
+  ): Promise<{ runId: string; instanceId: string; resumed?: true }> {
+    // `drop-held` resumes a paused standing Workflow with no held item (ADR-0017).
+    const query = opts.dropHeld ? "?drop-held=true" : "";
+    const res = await this.fetchImpl(`${this.baseUrl}${workflowPath(workflow)}/runs${query}`, {
       method: "POST",
       headers: this.headers(JSON_HEADERS),
       body: JSON.stringify(input),
     });
-    return (await this.json(res, "/workflows/:name/runs")) as { runId: string; instanceId: string };
+    return (await this.json(res, "/workflows/:name/runs")) as { runId: string; instanceId: string; resumed?: true };
+  }
+
+  /** `GET /runs` — one page of the run listing (ADR-0009): live runs when `query` names no
+   * `status`, newest start first, and the cursor of the next page when there is one. */
+  async runs(query: RunsQuery = {}): Promise<RunPage> {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) if (value !== undefined) params.set(key, String(value));
+    const qs = params.size ? `?${params}` : "";
+    const res = await this.fetchImpl(`${this.baseUrl}/runs${qs}`, { headers: this.headers() });
+    const page = (await this.json(res, "/runs")) as RunPage;
+    if (typeof page !== "object" || page === null || !Array.isArray(page.runs)) {
+      throw new Error("GET /runs: the answer is not a page of runs");
+    }
+    return page;
   }
 
-  /** `GET /runs` — every live run's status. */
-  async list(): Promise<RunStatus[]> {
-    const res = await this.fetchImpl(`${this.baseUrl}/runs`, { headers: this.headers() });
-    return (await this.json(res, "/runs")) as RunStatus[];
+  /** `GET /gates` — the Gate inbox (ADR-0011): the open Gates of every live run that this Caller
+   * may answer, oldest first, of one Workflow when `workflow` names it. */
+  async gates(workflow?: string): Promise<GateInboxEntry[]> {
+    const qs = workflow !== undefined ? `?${new URLSearchParams({ workflow })}` : "";
+    const res = await this.fetchImpl(`${this.baseUrl}/gates${qs}`, { headers: this.headers() });
+    const body = (await this.json(res, "/gates")) as { gates?: unknown };
+    if (typeof body !== "object" || body === null || !Array.isArray(body.gates)) {
+      throw new Error("GET /gates: the answer is not a list of Gates");
+    }
+    return body.gates as GateInboxEntry[];
+  }
+
+  /** Every run that `query` selects: each page of `GET /runs`, in turn, until a page has no `next`. */
+  async allRuns(query: Omit<RunsQuery, "cursor"> = {}): Promise<RunSummary[]> {
+    const runs: RunSummary[] = [];
+    let cursor: string | undefined;
+    do {
+      const page = await this.runs({ ...query, ...(cursor !== undefined ? { cursor } : {}) });
+      runs.push(...page.runs);
+      cursor = page.next;
+    } while (cursor !== undefined);
+    return runs;
   }
 
   /** `GET /repos` — whether the instance has a data plane, and every Repo resource as the cluster
@@ -238,6 +361,25 @@ export class JR2Client {
     await this.json(res, "/runs/:runId/gates/:gate/events"); // surface { error }; ignore { ok:true }
   }
 
+  /** `GET /runs/:runId/agents` — the Agent slots a Steering message can go to (ADR-0002). */
+  async agents(runId: string): Promise<RunAgentView[]> {
+    const res = await this.fetchImpl(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/agents`, {
+      headers: this.headers(),
+    });
+    return (await this.json(res, "/runs/:runId/agents")) as RunAgentView[];
+  }
+
+  /** `POST /runs/:runId/steering` — a Steering message to one Agent slot of a live run (ADR-0002).
+   * Answers its id, and whether a Turn of the slot is open now. */
+  async steer(runId: string, agent: string, text: string): Promise<{ id: string; agent: string; open: boolean }> {
+    const res = await this.fetchImpl(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/steering`, {
+      method: "POST",
+      headers: this.headers(JSON_HEADERS),
+      body: JSON.stringify({ agent, text }),
+    });
+    return (await this.json(res, "/runs/:runId/steering")) as { id: string; agent: string; open: boolean };
+  }
+
   /** `POST /runs/:runId/events` — feed one run-control event into a live run. */
   async send(runId: string, event: RunEvent): Promise<void> {
     const res = await this.fetchImpl(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/events`, {
@@ -284,19 +426,81 @@ export class JR2Client {
         } 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 === "looked") {
+          // A Gate's look gave its event, and the run took it (ADR-0011).
+          yield { ...(JSON.parse(frame.data) as object), kind: "looked" } as GateMarker;
+        } else if (frame.event === "hook-refused") {
+          // A Hook's delivery reached an open Gate, and the Gate did not take it (ADR-0011).
+          yield { ...(JSON.parse(frame.data) as object), kind: "hook-refused" } as HookRefusedMarker;
+        } else if (frame.event === "pool") {
+          // What a Pool of runs did with an item (ADR-0017).
+          yield { ...(JSON.parse(frame.data) as object), kind: "pool" } as PoolMarker;
         } 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
+        // misread as a status: `jr2 watch` decides "settled" off `status.status`, and a marker
         // parsed as a status would end the follow mid-run.
       }
       if (settled) return;
     }
   }
 
+  /** `GET /runs/:runId/conversations` — the run's kept conversations (ADR-0023), the first first. */
+  async conversations(runId: string): Promise<KeptConversationView[]> {
+    const res = await this.fetchImpl(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/conversations`, {
+      headers: this.headers(),
+    });
+    return (await this.json(res, "/runs/:runId/conversations")) as KeptConversationView[];
+  }
+
+  /** `GET /runs/:runId/conversations/:instanceId` — one page of a kept conversation's entries after
+   * `after` (-1: from the first). */
+  async conversationEntries(
+    runId: string,
+    instanceId: string,
+    after: number,
+    limit = 1000,
+  ): Promise<ConversationEntryView[]> {
+    const res = await this.fetchImpl(
+      `${this.baseUrl}/runs/${encodeURIComponent(runId)}/conversations/${encodeURIComponent(instanceId)}` +
+        `?after=${after}&limit=${limit}`,
+      { headers: this.headers() },
+    );
+    return (await this.json(res, "/runs/:runId/conversations/:instanceId")) as ConversationEntryView[];
+  }
+
+  /** `GET /runs/:runId/conversations/:instanceId/events` — follow one kept conversation: its entries
+   * after `after`, then each new one, until the server ends the feed (the conversation is not open,
+   * or it is cut or swept). A feed that ends with no `end` frame is opened again after the last
+   * entry read. */
+  async *followConversation(runId: string, instanceId: string, after: number): AsyncGenerator<ConversationEntryView> {
+    let last = after;
+    for (;;) {
+      const res = await this.fetchImpl(
+        `${this.baseUrl}/runs/${encodeURIComponent(runId)}/conversations/${encodeURIComponent(instanceId)}/events` +
+          `?after=${last}`,
+        { headers: this.headers({ accept: "text/event-stream" }) },
+      );
+      if (!res.ok) {
+        await this.json(res, "/runs/:runId/conversations/:instanceId/events");
+        return;
+      }
+      if (!res.body) return;
+      for await (const frame of parseSSE(res.body)) {
+        if (frame.event === "entry") {
+          const entry = JSON.parse(frame.data) as ConversationEntryView;
+          if (entry.seq > last) last = entry.seq;
+          yield entry;
+        } else if (frame.event === "end") {
+          return;
+        }
+      }
+    }
+  }
+
   /**
    * `GET /healthz` — what this orchestrator says it is. Unauthenticated (it is the readiness probe),
    * best-effort by contract: an unreachable or older instance answers `undefined`/`{}` rather than