@agent-delivery-harness/cli 0.2.0 → 0.5.0

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,46 @@
  */
 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 RunEventVersion,
+} from "@agent-delivery-harness/kernel";
 import {
   READOUT_LABELS,
   detailOf,
   readoutRows,
   roundRows,
 } 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 +83,244 @@ 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 } };
+}
+
+function renderGrammar(grammar: RunEventPayloadGrammar, context: ConfigFreeCommandContext): void {
+  context.write(`${grammar.kind} (${grammar.version})`);
+  for (const member of grammar.members) {
+    context.write(`  ${member.name}  ${member.required ? "required" : "optional"}${member.values === undefined ? "" : `  values: ${member.values.join(", ")}`}`);
+  }
+}
+
+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 +330,120 @@ 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 five facts, rendered or serialized. */
+interface InventoryRow {
+  readonly runId: string;
+  readonly status: string;
+  readonly open: boolean;
+  readonly current: boolean;
+  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,
+            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, 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");
+  for (const row of shown) {
     lines.push(
-      `  ${runId}  ${evaluation.status}  ${open ? "open" : "ended"}${runId === currentRunId ? " current" : ""}  ${size} bytes`,
+      row.status === RUN_LIST_UNREADABLE
+        ? `  ${row.runId}  ${RUN_LIST_UNREADABLE}  ${row.bytes} bytes`
+        : `  ${row.runId}  ${row.status}  ${row.open ? "open" : "ended"}${row.current ? " current" : ""}  ${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 +460,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;
@@ -173,19 +506,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 +564,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 +585,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 +602,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 +617,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;

package/src/commands/save-context.ts

@@ -0,0 +1,51 @@
+import { buildRunEvent } from "../run-surface.ts";
+import { installedRelease, ordinaryEventWriter, policyDigest, recoveryBlocker, recoveryRun, rejectionDetails } from "../ordinary-context.ts";
+import type { CommandDescriptor } from "../boundary.ts";
+
+const USAGE = "Usage: delivery-harness save-context --json '{\"contract\":{\"objective\":\"...\",\"acceptanceCriteria\":[\"...\"],\"finishLine\":\"merge-ready\"},\"stage\":\"work\"}'";
+
+export const saveContextCommand: CommandDescriptor = {
+  name: "save-context", sourceId: "delivery-harness.cli.save-context",
+  summary: "Save a bounded delivery contract and stage observation in the current run.",
+  usage: USAGE,
+  async run(context) {
+    if (context.args.length !== 2 || context.args[0] !== "--json") return { kind: "usage", message: USAGE };
+    let input: { contract?: unknown; stage?: unknown };
+    try {
+      const value: unknown = JSON.parse(context.args[1]!);
+      if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some(key => key !== "contract" && key !== "stage")) throw new Error();
+      input = value;
+    } catch { return { kind: "usage", message: "Context must be a JSON object with only contract and stage." }; }
+    const run = await recoveryRun(context.rootDir);
+    if (!run.ok) return { kind: "blocked", blockers: [run.blocker] };
+    const wiring = await context.wire();
+    const capture = await wiring.captureCandidate();
+    if (!capture.ok) return { kind: "blocked", blockers: capture.blockers };
+    let release;
+    try { release = await installedRelease(context.rootDir); }
+    catch { return { kind: "blocked", blockers: [recoveryBlocker("resume_release_unreadable", "The installed workflow release identity cannot be read; restore a valid installation before saving context.")] }; }
+    const candidate = capture.candidate;
+    // An omitted member is absent, never present-and-undefined: the contract
+    // reports it as a missing member, and the v2 retry key stays derivable.
+    const payload = { spec: "ordinary-run-context/1",
+      ...(input.contract === undefined ? {} : { contract: input.contract }),
+      ...(input.stage === undefined ? {} : { stage: input.stage }),
+      candidateTreeSha: candidate.treeSha,
+      candidateBinding: { deliverableDigest: candidate.deliverable.digest, identity: candidate.deliverable.identity,
+        baseRef: candidate.base.ref, baseTipSha: candidate.base.tipSha, mergeBaseSha: candidate.base.mergeBaseSha, workspaceId: candidate.workspaceId },
+      policyDigest: policyDigest(context), release };
+    // The run's own writer version, never this command's: a v2 journal admits
+    // no v1 event, and a v2 event needs the retry key the writer derives.
+    const writer = ordinaryEventWriter(run.version, "context.saved", payload);
+    const appended = await run.surface.store.append(
+      run.runId,
+      buildRunEvent({ runId: run.runId, commonDir: run.surface.commonDir, kind: "context.saved", role: "executor", payload, ...writer }),
+      // An exact retry of one save is one observation, at its first instant.
+      { reuseExistingTimestamp: true },
+    );
+    if (!appended.ok) return { kind: "blocked", blockers: [recoveryBlocker("resume_context_invalid",
+      "Context was refused by the bounded run-event contract; inspect contract, stage, and secret-free inputs.",
+      `run ${run.runId}: ${rejectionDetails(appended.rejections)}`)] };
+    return { kind: "ok", summary: `saved ordinary context for ${run.runId}; stage is an observation, not evidence` };
+  },
+};