@agent-delivery-harness/cli 0.2.0 → 0.7.3

package/src/commands/runs.ts

@@ -1,3 +1,7 @@
+import { runViewCommand } from "../run-view-command.ts";
+import { readArchiveFile } from "../run-archive-commands.ts";
+import { runArchiveCommand } from "../run-archive-commands.ts";
+import { runArtifactCommand } from "../run-artifact-commands.ts";
 /**
  * `runs` — read the run store back: `runs list`, `runs show <id>`, and
  * `runs serve`, the local page over the same files.
@@ -18,21 +22,51 @@
  */
 import { stat } from "node:fs/promises";
 import path from "node:path";
-import { evaluateRunJournal } from "@agent-delivery-harness/kernel";
+import {
+  RUN_EVENT_KINDS,
+  RUN_EVENT_KINDS_V1,
+  RUN_EVENT_SPEC,
+  RUN_EVENT_SPEC_V2,
+  RUN_JOURNAL_STATUSES,
+  describeRunEventPayload,
+  evaluateRunJournal,
+  type RunEventPayloadGrammar,
+  type RunEventPayloadMemberGrammar,
+  type RunEventValueGrammar,
+  type RunEventVersion,
+} from "@agent-delivery-harness/kernel";
 import {
   READOUT_LABELS,
   detailOf,
+  durationLabel,
+  phaseRows,
   readoutRows,
   roundRows,
+  summarize,
 } from "../run-projection.ts";
+import { buildRunExport } from "../run-export.ts";
 import { startRunServer, type RunServerHandle } from "../run-server.ts";
-import { oneLine, oneLineOf, resolveRunSurface, runSurfaceBlocker, type RunSurface } from "../run-surface.ts";
+import {
+  oneLine,
+  oneLineOf,
+  resolveRunSurface,
+  resolveWorktreeRoot,
+  runSurfaceBlocker,
+  type RunSurface,
+} from "../run-surface.ts";
 import type { CommandResult, ConfigFreeCommandContext, ConfigFreeCommandDescriptor } from "../boundary.ts";
 
 const USAGE = [
-  "Usage: delivery-harness runs list",
-  "       delivery-harness runs show <run-id>",
-  "       delivery-harness runs serve [--repo <path>]... [--port <n>]",
+  "Usage: delivery-harness runs capabilities --json",
+  "       delivery-harness runs list [--json] [--limit <n>] [--status <status>] [--open|--ended]",
+  "       delivery-harness runs show [<run-id>] [--json]",
+  "       delivery-harness runs grammar <kind> [--version 1|2] [--json]",
+  "       delivery-harness runs view <run-id> [--json] [--record <repository-relative-path>]",
+  "       delivery-harness runs export <run-id> --output <file>",
+  "       delivery-harness runs archive <file> [--artifact <id>]",
+  "       delivery-harness runs capture <run-id> --json <request>",
+  "       delivery-harness runs artifact <run-id> <artifact-id> [--json]",
+  "       delivery-harness runs serve [--repo <path>]... [--archive <file>]... [--port <n>] [--freshness-seconds <n>] [--record <repository-relative-path>]",
 ].join("\n");
 
 const unresolvable = (reason: string): CommandResult => ({
@@ -54,32 +88,264 @@ export const runsCommand: ConfigFreeCommandDescriptor = {
   name: "runs",
   sourceId: "delivery-harness.cli.runs",
   summary: "List, show, and serve the delivery runs this repository has recorded.",
+  usage: USAGE,
   configFree: true,
   async run(context: ConfigFreeCommandContext): Promise<CommandResult> {
     const [subcommand, ...rest] = context.args;
+    if (subcommand === "capabilities") {
+      if (rest.length !== 1 || rest[0] !== "--json") return { kind: "usage", message: "Usage: runs capabilities --json" };
+      context.write(`${JSON.stringify({ spec: "run-capabilities/1", writerVersions: ["run-event/1", "run-event/2"], artifactCapture: true })}\n`);
+      return { kind: "ok" };
+    }
+    if (subcommand === "grammar") return showGrammar(context, rest);
+    if (subcommand === "view") return runViewCommand(context, rest);
+    if (subcommand === "export" || subcommand === "archive") return runArchiveCommand(context, subcommand, rest);
+    if (subcommand === "capture" || subcommand === "artifact") return runArtifactCommand(context, subcommand, rest);
     if (subcommand === undefined) return { kind: "usage", message: `runs needs a subcommand.\n${USAGE}` };
     if (subcommand !== "list" && subcommand !== "show" && subcommand !== "serve") {
       return { kind: "usage", message: `Unknown runs subcommand ${oneLine(subcommand, 64)}.\n${USAGE}` };
     }
-    if (subcommand === "show" && rest[0] === undefined) {
-      return { kind: "usage", message: `runs show needs a run id.\n${USAGE}` };
-    }
     // `serve` resolves its OWN repositories — one per `--repo`, none of them
     // necessarily the invoking worktree — so it never asks the invoking
     // worktree's store to resolve first.
     if (subcommand === "serve") return serveRuns(context, rest);
 
+    // `list`'s argument surface is decided BEFORE the store is resolved. A
+    // mistyped bound is a usage error wherever it was typed, and an operator
+    // standing outside a repository should not have to fix the repository to
+    // find out the flag was wrong.
+    const listArgs = subcommand === "list" ? parseListArgs(rest) : undefined;
+    if (listArgs !== undefined && !listArgs.ok) return { kind: "usage", message: listArgs.message };
+    const showArgs = subcommand === "show" ? parseShowArgs(rest) : undefined;
+    if (showArgs !== undefined && !showArgs.ok) return { kind: "usage", message: showArgs.message };
+
     const resolved = await resolveRunSurface(context.rootDir);
     if (!resolved.ok) return unresolvable(resolved.reason);
 
-    return subcommand === "list"
-      ? listRuns(resolved.surface, context)
-      : showRun(resolved.surface, context, rest[0]!);
+    if (listArgs !== undefined && listArgs.ok) return listRuns(resolved.surface, context, listArgs.args);
+    if (showArgs === undefined || !showArgs.ok) throw new Error("runs show arguments were not parsed");
+    let runId = showArgs.args.runId;
+    if (runId === undefined) {
+      const current = await resolved.surface.store.current(resolved.surface.worktreeKey);
+      if (!current.ok || current.runId === undefined) {
+        return {
+          kind: "blocked",
+          blockers: [runSurfaceBlocker({
+            code: "run_unresolvable",
+            summary: "There is no current run that can be resolved in this worktree.",
+            details: current.ok
+              ? "no run id was supplied and the worktree has no readable current run"
+              : `no run id was supplied; current-run lookup was refused: ${oneLine(current.rejections[0]?.message ?? "unreadable", 200)}`,
+            remediation: {
+              id: "start-or-name-a-run",
+              summary: "Start a run with `delivery-harness emit run.started`, or pass a run id from `delivery-harness runs list`.",
+            },
+          })],
+        };
+      }
+      runId = current.runId;
+    }
+    return showRun(resolved.surface, context, runId, showArgs.args.json);
   },
 };
 
+interface ShowArgs { readonly runId?: string; readonly json: boolean }
+type ShowParse = { readonly ok: true; readonly args: ShowArgs } | { readonly ok: false; readonly message: string };
+
+function parseShowArgs(args: readonly string[]): ShowParse {
+  let runId: string | undefined;
+  let json = false;
+  for (const token of args) {
+    if (token === "--json") {
+      if (json) return { ok: false, message: `runs show: --json was given twice.\n${USAGE}` };
+      json = true;
+      continue;
+    }
+    if (token.startsWith("-")) return { ok: false, message: `runs show: unknown flag ${oneLine(token, 64)}.\n${USAGE}` };
+    if (runId !== undefined) return { ok: false, message: `runs show accepts at most one run id.\n${USAGE}` };
+    runId = token;
+  }
+  return { ok: true, args: { json, ...(runId === undefined ? {} : { runId }) } };
+}
+
+interface GrammarArgs { readonly kind: string; readonly version: RunEventVersion; readonly json: boolean }
+type GrammarParse = { readonly ok: true; readonly args: GrammarArgs } | { readonly ok: false; readonly message: string };
+
+function parseGrammarArgs(args: readonly string[]): GrammarParse {
+  let kind: string | undefined;
+  let version: RunEventVersion = RUN_EVENT_SPEC_V2;
+  let versionSeen = false;
+  let json = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index]!;
+    if (token === "--json") {
+      if (json) return { ok: false, message: `runs grammar: --json was given twice.\n${USAGE}` };
+      json = true;
+      continue;
+    }
+    if (token === "--version") {
+      if (versionSeen) return { ok: false, message: `runs grammar: --version was given twice.\n${USAGE}` };
+      const value = args[index + 1];
+      if (value !== "1" && value !== "2") return { ok: false, message: `runs grammar: --version needs 1 or 2.\n${USAGE}` };
+      version = value === "1" ? RUN_EVENT_SPEC : RUN_EVENT_SPEC_V2;
+      versionSeen = true;
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("-")) return { ok: false, message: `runs grammar: unknown flag ${oneLine(token, 64)}.\n${USAGE}` };
+    if (kind !== undefined) return { ok: false, message: `runs grammar accepts exactly one event kind.\n${USAGE}` };
+    kind = token;
+  }
+  if (kind === undefined) return { ok: false, message: `runs grammar needs an event kind.\n${USAGE}` };
+  return { ok: true, args: { kind, version, json } };
+}
+
+/**
+ * One described value, and everything beneath it. Types, nested tables, array
+ * items and variants are printed rather than summarised: the whole point of
+ * this view is that a caller never has to open the validator to find out what
+ * a member holds.
+ */
+function renderValue(value: RunEventValueGrammar, indent: string, lead: string, context: ConfigFreeCommandContext): void {
+  context.write(`${indent}${lead}${value.type}  ${value.constraint}${value.values === undefined ? "" : `  values: ${value.values.join(", ")}`}`);
+  context.write(`${indent}  example: ${JSON.stringify(value.example)}`);
+  for (const member of value.members ?? []) renderMember(member, `${indent}  `, context);
+  if (value.items !== undefined) renderValue(value.items, `${indent}  `, "items  ", context);
+  for (const [index, variant] of (value.variants ?? []).entries()) {
+    renderValue(variant, `${indent}  `, `variant ${index + 1}  `, context);
+  }
+}
+
+function renderMember(member: RunEventPayloadMemberGrammar, indent: string, context: ConfigFreeCommandContext): void {
+  renderValue(member, indent, `${member.name}  ${member.required ? "required" : "optional"}  `, context);
+}
+
+function renderGrammar(grammar: RunEventPayloadGrammar, context: ConfigFreeCommandContext): void {
+  context.write(`${grammar.kind} (${grammar.version})`);
+  for (const member of grammar.members) renderMember(member, "  ", context);
+  context.write("  example:");
+  context.write(JSON.stringify(grammar.example, null, 2));
+}
+
+function showGrammar(context: ConfigFreeCommandContext, args: readonly string[]): CommandResult {
+  const parsed = parseGrammarArgs(args);
+  if (!parsed.ok) return { kind: "usage", message: parsed.message };
+  const grammar = describeRunEventPayload(parsed.args.kind, parsed.args.version);
+  if (grammar === undefined) {
+    const kinds = parsed.args.version === RUN_EVENT_SPEC ? RUN_EVENT_KINDS_V1 : RUN_EVENT_KINDS;
+    return {
+      kind: "usage",
+      message: `runs grammar: ${oneLine(parsed.args.kind, 128)} is not a ${parsed.args.version} event kind; accepted kinds: ${kinds.join(", ")}.\n${USAGE}`,
+    };
+  }
+  if (parsed.args.json) context.write(JSON.stringify(grammar, null, 2));
+  else renderGrammar(grammar, context);
+  return { kind: "ok" };
+}
+
 // ── list ─────────────────────────────────────────────────────────────────────
 
+/**
+ * The one label this listing prints for a journal it could not read at all.
+ * It is not a completeness verdict — nothing was evaluated — so it is not one
+ * of the kernel's statuses, and it is spelled once, here.
+ */
+export const RUN_LIST_UNREADABLE = "unreadable";
+
+/**
+ * `absent` is the completeness vocabulary's answer to "no journal bound this
+ * candidate", which an inventory of the journals that exist can never be. It
+ * is excluded rather than accepted-and-never-matched, because a selector that
+ * cannot select anything whatever the store holds is a false affordance: an
+ * agent filtering on it would read the empty result as "no such runs" rather
+ * than as "this question cannot be asked here".
+ */
+const STATUS_NEVER_LISTED = "absent";
+
+/**
+ * Exactly the statuses a row of this listing can carry, which is what
+ * `--status` accepts. Derived from the kernel's closed vocabulary so a status
+ * renamed there is a compile-and-test problem here rather than a filter that
+ * silently stops matching.
+ */
+export const RUN_LIST_STATUSES: readonly string[] = Object.freeze([
+  ...RUN_JOURNAL_STATUSES.filter((status) => status !== STATUS_NEVER_LISTED),
+  RUN_LIST_UNREADABLE,
+]);
+
+/** The spec every machine-readable inventory carries, beside `runs show --json`'s export spec. */
+export const RUN_INVENTORY_SPEC = "run-inventory/1";
+
+interface ListArgs {
+  readonly json: boolean;
+  readonly limit?: number;
+  readonly status?: string;
+  /** True selects the runs with no `run.ended`; false selects the ended ones. */
+  readonly open?: boolean;
+}
+
+type ListParse = { readonly ok: true; readonly args: ListArgs } | { readonly ok: false; readonly message: string };
+
+/**
+ * The separate-argument form the rest of this command uses, and the same
+ * refusal discipline: an unknown flag, a repeated one, a positional, and a
+ * value that is not a bound are all usage errors rather than conveniences.
+ *
+ * A LIMIT IS A COUNT OF ROWS, so it is a positive integer and nothing else.
+ * `0` is refused rather than read as "no rows" or as "no bound": both readings
+ * are plausible, an operator cannot tell which one they got from the output,
+ * and neither is a thing anyone means to ask for.
+ */
+function parseListArgs(args: readonly string[]): ListParse {
+  const refuse = (reason: string): ListParse => ({ ok: false, message: `runs list: ${reason}.\n${USAGE}` });
+  let json = false;
+  let limit: number | undefined;
+  let status: string | undefined;
+  let open: boolean | undefined;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index]!;
+    if (token === "--json") {
+      if (json) return refuse("--json was given twice");
+      json = true;
+      continue;
+    }
+    if (token === "--open" || token === "--ended") {
+      // Two names for one question, so asking it twice — however spelled —
+      // has no answer to give.
+      if (open !== undefined) return refuse("use at most one of --open and --ended");
+      open = token === "--open";
+      continue;
+    }
+    if (token === "--limit" || token === "--status") {
+      const value = args[index + 1];
+      if (value === undefined) return refuse(`${token} needs a value`);
+      index += 1;
+      if (token === "--limit") {
+        if (limit !== undefined) return refuse("--limit was given twice");
+        if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < 1) {
+          return refuse(`--limit needs a positive whole number, not ${oneLine(value, 64)}`);
+        }
+        limit = Number(value);
+        continue;
+      }
+      if (status !== undefined) return refuse("--status was given twice");
+      if (!RUN_LIST_STATUSES.includes(value)) {
+        return refuse(`--status accepts ${RUN_LIST_STATUSES.join(", ")}, not ${oneLine(value, 64)}`);
+      }
+      status = value;
+      continue;
+    }
+    if (token.startsWith("--")) return refuse(`unknown flag ${oneLine(token, 64)}`);
+    return refuse("it takes no positional arguments");
+  }
+
+  return {
+    ok: true,
+    args: { json, ...(limit === undefined ? {} : { limit }), ...(status === undefined ? {} : { status }), ...(open === undefined ? {} : { open }) },
+  };
+}
+
 /** The journal's size on disk, or zero where it cannot be measured. */
 async function sizeOf(runsDir: string, runId: string): Promise<number> {
   try {
@@ -89,39 +355,137 @@ async function sizeOf(runsDir: string, runId: string): Promise<number> {
   }
 }
 
-async function listRuns(surface: RunSurface, context: ConfigFreeCommandContext): Promise<CommandResult> {
+/** One run as both surfaces see it: the same six facts, rendered or serialized. */
+interface InventoryRow {
+  readonly runId: string;
+  readonly status: string;
+  readonly open: boolean;
+  readonly current: boolean;
+  /**
+   * The journal's own span in whole seconds, and `null` where there is no
+   * journal to take a span from.
+   *
+   * NULL, NEVER ZERO. An unreadable journal has no duration; a run that began
+   * and ended inside one second has a duration of zero. Spelling both `0` would
+   * make the listing's one cycle-time figure unreadable exactly where the
+   * status column already says something is wrong — and an agent summing the
+   * column would count the unreadable ones as instantaneous.
+   */
+  readonly durationSeconds: number | null;
+  readonly bytes: number;
+}
+
+/**
+ * Every run the store holds, in the store's own order.
+ *
+ * THE ORDER IS THE STORE'S, and the store sorts run ids ascending. That is
+ * what makes a bounded listing reproducible: the same store bounded the same
+ * way returns the same rows, and the row a `--limit 1` returns is the one an
+ * unbounded listing printed first. Nothing here re-orders it, so the order
+ * this surface documents is the order the store defines and not a second one
+ * that happens to agree today.
+ */
+async function inventoryOf(
+  surface: RunSurface,
+): Promise<{ readonly rows: readonly InventoryRow[]; readonly currentRunId: string | undefined }> {
   const runIds = await surface.store.list();
   const current = await surface.store.current(surface.worktreeKey);
   const currentRunId = current.ok ? current.runId : undefined;
 
+  const rows: InventoryRow[] = [];
+  for (const runId of runIds) {
+    const bytes = await sizeOf(surface.runsDir, runId);
+    const read = await surface.store.read(runId);
+    rows.push(
+      read.ok
+        ? {
+            runId,
+            status: evaluateRunJournal(read.events).status,
+            open: !read.events.some((event) => event.kind === "run.ended"),
+            current: runId === currentRunId,
+            durationSeconds: summarize(read.events).durationSeconds,
+            bytes,
+          }
+        : // Nothing was read, so no lifecycle or completeness state is claimed.
+          // The worktree pointer and on-disk size are independent readable facts.
+          { runId, status: RUN_LIST_UNREADABLE, open: false, current: runId === currentRunId, durationSeconds: null, bytes },
+    );
+  }
+  return { rows, currentRunId };
+}
+
+/**
+ * `runs list`, human and machine.
+ *
+ * THE FILTER RUNS BEFORE THE BOUND. A bound applied first would spend its rows
+ * on runs the filter then discards, so `--status x --limit 1` could answer
+ * "none" for a store that holds one — the bound is a bound on the ANSWER, not
+ * on how far the store was read.
+ *
+ * WHAT `total` COUNTS is the set the filters selected, before the bound. That
+ * is the number a reader needs to know it was bounded (`returned` below it
+ * means rows were cut), and with no filter it is the whole store — which is
+ * why the unfiltered human listing's total line is unchanged.
+ */
+async function listRuns(surface: RunSurface, context: ConfigFreeCommandContext, args: ListArgs): Promise<CommandResult> {
+  const { rows, currentRunId } = await inventoryOf(surface);
+  const selected = rows.filter(
+    (row) =>
+      (args.status === undefined || row.status === args.status) &&
+      (args.open === undefined || (row.status !== RUN_LIST_UNREADABLE && row.open === args.open)),
+  );
+  const totalBytes = selected.reduce((sum, row) => sum + row.bytes, 0);
+  const shown = args.limit === undefined ? selected : selected.slice(0, args.limit);
+  const truncated = shown.length < selected.length;
+
+  if (args.json) {
+    context.write(
+      JSON.stringify(
+        {
+          spec: RUN_INVENTORY_SPEC,
+          labels: READOUT_LABELS,
+          runsDir: surface.runsDir,
+          current: currentRunId ?? null,
+          runs: shown,
+          total: { count: selected.length, bytes: totalBytes },
+          returned: shown.length,
+          truncated,
+        },
+        null,
+        2,
+      ),
+    );
+    return { kind: "ok" };
+  }
+
   // The status column carries a completeness verdict, so this readout is
   // labeled exactly like `show`'s. `list` is the command an operator reaches
   // for first, before it knows which id to show; an unlabeled `complete` here
   // is the misreading the labels exist to prevent.
   const lines: string[] = [`runs in ${oneLine(surface.runsDir, 400)}`, `  (${READOUT_LABELS})`];
-  let total = 0;
-  for (const runId of runIds) {
-    const size = await sizeOf(surface.runsDir, runId);
-    total += size;
-    const read = await surface.store.read(runId);
-    if (!read.ok) {
-      lines.push(`  ${runId}  unreadable  ${size} bytes`);
-      continue;
-    }
-    const evaluation = evaluateRunJournal(read.events);
-    const open = !read.events.some((event) => event.kind === "run.ended");
+  // The duration goes AHEAD of the size, which is the demotion this column was
+  // added for: an operator scanning this listing is asking which delivery took
+  // a day, and the journal's size on disk answers a question nobody has except
+  // when something is wrong with the file. The size stays, because it is the
+  // only readable fact about an unreadable journal.
+  for (const row of shown) {
     lines.push(
-      `  ${runId}  ${evaluation.status}  ${open ? "open" : "ended"}${runId === currentRunId ? " current" : ""}  ${size} bytes`,
+      row.status === RUN_LIST_UNREADABLE || row.durationSeconds === null
+        ? `  ${row.runId}  ${RUN_LIST_UNREADABLE}  ${row.bytes} bytes`
+        : `  ${row.runId}  ${row.status}  ${row.open ? "open" : "ended"}${row.current ? " current" : ""}  ${durationLabel(row.durationSeconds)}  ${row.bytes} bytes`,
     );
   }
-  lines.push(`total ${total} bytes across ${runIds.length} run(s)`);
+  lines.push(`total ${totalBytes} bytes across ${selected.length} run(s)`);
+  // Said only when something was actually cut, so the unbounded listing keeps
+  // the bytes it always had.
+  if (truncated) lines.push(`showing ${shown.length} of ${selected.length} run(s) (--limit ${args.limit})`);
   for (const line of lines) context.write(line);
   return { kind: "ok" };
 }
 
 // ── show ─────────────────────────────────────────────────────────────────────
 
-async function showRun(surface: RunSurface, context: ConfigFreeCommandContext, runId: string): Promise<CommandResult> {
+async function showRun(surface: RunSurface, context: ConfigFreeCommandContext, runId: string, json: boolean): Promise<CommandResult> {
   const read = await surface.store.read(runId);
   if (!read.ok) {
     return {
@@ -138,6 +502,17 @@ async function showRun(surface: RunSurface, context: ConfigFreeCommandContext, r
   }
 
   const events = read.events;
+  if (json) {
+    const worktreeRoot = await resolveWorktreeRoot(context.rootDir);
+    const rootDir = worktreeRoot.ok ? worktreeRoot.root : context.rootDir;
+    context.write(JSON.stringify(buildRunExport({
+      runId,
+      events,
+      rootDir,
+      refusedAppends: await surface.store.readNotes(runId),
+    }), null, 2));
+    return { kind: "ok" };
+  }
   const open = !events.some((event) => event.kind === "run.ended");
   const current = await surface.store.current(surface.worktreeKey);
   const isCurrent = current.ok && current.runId === runId;
@@ -148,6 +523,10 @@ async function showRun(surface: RunSurface, context: ConfigFreeCommandContext, r
     context.write(`    ${event.seq}  ${event.at}  ${event.kind.padEnd(20)}  ${event.actor.role.padEnd(8)}  ${detailOf(event)}`);
   }
 
+  // The phase breakdown sits directly under the timeline, before the rounds it
+  // divides the run by, because it is the summary those rows are the detail of.
+  for (const row of phaseRows(events)) context.write(row);
+
   const rounds = roundRows(events);
   if (rounds.length > 0) {
     context.write("  rounds:");
@@ -173,19 +552,56 @@ async function showRun(surface: RunSurface, context: ConfigFreeCommandContext, r
 
   // No record tree sha and no mandated pair: the viewer has neither, and
   // pretending otherwise would turn an observation into a claim.
-  for (const row of readoutRows(events, evaluateRunJournal(events), context.rootDir)) context.write(row);
+  //
+  // THE ROOT IS THE WORKTREE'S, NOT THE INVOCATION'S. The config-presence note
+  // is a question about the repository, and `runs serve` answers it at the
+  // toplevel of the path it was given. Answering it here at the cwd would tell
+  // an operator standing in `packages/cli` that this repository carries no
+  // config while the page, over the same journal, says it carries one — two
+  // answers to one question, which is the thing the shared projection exists
+  // to prevent. The cwd stands in only where git can name no root at all, and
+  // then it is the only root there is.
+  const worktreeRoot = await resolveWorktreeRoot(context.rootDir);
+  const rootDir = worktreeRoot.ok ? worktreeRoot.root : context.rootDir;
+  for (const row of readoutRows(events, evaluateRunJournal(events), rootDir)) context.write(row);
   return { kind: "ok" };
 }
 
 // ── serve ────────────────────────────────────────────────────────────────────
 
 interface ServeArgs {
+ readonly archives:readonly string[];
+ readonly recordPath?:string;
+ readonly freshnessWindowMs?:number;
   readonly repos: readonly string[];
   readonly port?: number;
 }
 
 type ServeParse = { readonly ok: true; readonly args: ServeArgs } | { readonly ok: false; readonly message: string };
 
+/**
+ * The ports a browser leaves out of the `Host` header, being the defaults of
+ * the schemes it would dial them under.
+ *
+ * `run-server.ts` decides whether a request is addressed to the socket it
+ * arrived on by comparing `Host` against the bound `host:port` for EXACT
+ * equality — it parses nothing, normalizes nothing, and matches no list of
+ * names that "mean" loopback. That exactness is the property; it is what makes
+ * the page's answer to a DNS rebind checkable rather than a matter of parsing
+ * taste. A page served on one of these ports is one no browser can ever reach:
+ * the request arrives carrying `Host: 127.0.0.1`, with no port at all, and is
+ * answered 403 — the same 403 a rebind gets, with nothing to tell them apart.
+ *
+ * So the choice is between widening the check and refusing the port, and it is
+ * settled by what each costs. Widening costs the property. Refusing costs an
+ * operator nothing they wanted: a loopback viewer of a run store has no reason
+ * to sit on a privileged port, and the ephemeral default is one flag away.
+ * The refusal lives HERE, at the one surface an operator types a port at,
+ * rather than beside the check it protects — a second guard inside the server
+ * would make neither one provable.
+ */
+const BROWSER_ELIDED_PORTS: readonly number[] = [80, 443];
+
 /**
  * The separate-argument form every other command uses. `--flag=value` is
  * REFUSED rather than accepted as a convenience: one spelling means an
@@ -194,14 +610,20 @@ type ServeParse = { readonly ok: true; readonly args: ServeArgs } | { readonly o
  */
 function parseServeArgs(args: readonly string[], rootDir: string): ServeParse {
   const repos: string[] = [];
+  const archives:string[]=[];
+  let recordPath:string|undefined;
+  let freshnessWindowMs:number|undefined;
   let port: number | undefined;
 
   for (let index = 0; index < args.length; index += 1) {
     const token = args[index]!;
-    if (token === "--repo" || token === "--port") {
+    if (token === "--repo" || token === "--port" || token === "--archive" || token === "--freshness-seconds" || token === "--record") {
       const value = args[index + 1];
       if (value === undefined) return { ok: false, message: `${token} needs a value.\n${USAGE}` };
       index += 1;
+      if(token==="--record"){if(recordPath!==undefined)return {ok:false,message:"Use one explicit record path"};recordPath=value;continue;}
+      if(token==="--archive"){archives.push(path.resolve(rootDir,value));continue;}
+      if(token==="--freshness-seconds"){if(!/^\d+$/.test(value)||!Number.isSafeInteger(Number(value))||Number(value)>86400)return {ok:false,message:"freshness seconds must be between 0 and 86400"};freshnessWindowMs=Number(value)*1000;continue;}
       if (token === "--repo") {
         repos.push(path.resolve(rootDir, value));
         continue;
@@ -209,6 +631,14 @@ function parseServeArgs(args: readonly string[], rootDir: string): ServeParse {
       if (!/^\d{1,5}$/.test(value)) return { ok: false, message: `--port needs a port number.\n${USAGE}` };
       const parsed = Number(value);
       if (parsed > 65535) return { ok: false, message: `--port needs a port number.\n${USAGE}` };
+      if (BROWSER_ELIDED_PORTS.includes(parsed)) {
+        return {
+          ok: false,
+          message:
+            `--port ${parsed} cannot be served: a browser omits a scheme's default port from the Host header, ` +
+            `and this page answers only to the exact host:port it bound.\n${USAGE}`,
+        };
+      }
       port = parsed;
       continue;
     }
@@ -218,7 +648,7 @@ function parseServeArgs(args: readonly string[], rootDir: string): ServeParse {
 
   // No `--repo` means the worktree the operator is standing in, which is the
   // only repository they can have meant.
-  return { ok: true, args: { repos: repos.length === 0 ? [rootDir] : repos, ...(port === undefined ? {} : { port }) } };
+  return { ok: true, args: { repos: repos.length === 0 && archives.length===0 ? [rootDir] : repos, archives,...(recordPath===undefined?{}:{recordPath}),...(freshnessWindowMs===undefined?{}:{freshnessWindowMs}), ...(port === undefined ? {} : { port }) } };
 }
 
 /**
@@ -233,7 +663,8 @@ async function serveRuns(context: ConfigFreeCommandContext, args: readonly strin
   const parsed = parseServeArgs(args, context.rootDir);
   if (!parsed.ok) return { kind: "usage", message: parsed.message };
 
-  const started = await startRunServer({ repos: parsed.args.repos, ...(parsed.args.port === undefined ? {} : { port: parsed.args.port }) });
+  let archives:{label:string;text:string}[];try{archives=await Promise.all(parsed.args.archives.map(async file=>({label:path.basename(file),text:await readArchiveFile(file)})));}catch{return unresolvable("An explicitly selected archive could not be read within its size limit.");}
+  const started = await startRunServer({ repos: parsed.args.repos,archives,...(parsed.args.recordPath===undefined?{}:{recordPath:parsed.args.recordPath}),...(parsed.args.freshnessWindowMs===undefined?{}:{freshnessWindowMs:parsed.args.freshnessWindowMs}), ...(parsed.args.port === undefined ? {} : { port: parsed.args.port }) });
   if (!started.ok) return unresolvable(started.reason);
 
   const server: RunServerHandle = started.server;