@agent-delivery-harness/cli 0.2.0 → 0.7.3

package/src/run-surface.ts

@@ -3,6 +3,28 @@
  * found, how an event envelope is built, and how a store-derived string is
  * made safe to print.
  *
+ * THE ONE STORE OVERRIDE. `DELIVERY_HARNESS_RUN_STORE` names an absolute
+ * directory to resolve the store under instead of the repository's git common
+ * directory, read HERE — at resolution time, on every CLI path that reaches a
+ * run store — so no path can be honouring it while another is not. It exists
+ * because a process that is not a delivery can invoke this CLI from a worktree
+ * that has a delivery run current: the repository's own test suite does,
+ * hundreds of times per `npm run check`, and every wrapped invocation appended
+ * a `command.completed` to whatever run the executor had open there. Such a
+ * process pins the override at a directory of its own and is thereby unable to
+ * reach any live store. An invocation with the override unset writes where it
+ * always did; an invocation under test with it unset is a defect in the test,
+ * not a behaviour of the product, so nothing here tries to detect a test
+ * runner.
+ *
+ * WHAT THE OVERRIDE DOES NOT COLLAPSE. Each repository keeps its own store
+ * under the named directory, at a subdirectory digested from its common
+ * directory, so the two rules the surface documents survive being overridden:
+ * two paths in different repositories are two stores, and two worktrees of one
+ * repository are one store. `repo.commonDir` on every event still names the
+ * repository, never the override — the event says where the run happened, not
+ * where its journal was filed.
+ *
  * WHY THE STORE IS RESOLVED HERE AND NOT WIRED. The record store is wired from
  * the config, because a delivery record belongs to a configured gate. A run
  * belongs to the *repository* — it outlives the worktree it ran in and it
@@ -25,7 +47,9 @@ import path from "node:path";
 import {
   createBlocker,
   createRunStore,
+  sha256Hex,
   evaluateRunJournal,
+  explainRunJournal,
   gitNamespaceClearedEnvironment,
   neutralizeForDisplay,
   resolveRunStoreLocation,
@@ -33,6 +57,7 @@ import {
   type Blocker,
   type RunEventInput,
   type RunEventKind,
+  type RunJournalRoundBinding,
   type RunJournalRow,
   type RunStore,
 } from "@agent-delivery-harness/kernel";
@@ -42,7 +67,9 @@ export const RUN_SURFACE_SOURCE = "delivery-harness.cli.run-surface";
 
 export interface RunSurface {
   readonly store: RunStore;
+  /** The repository's OWN git common directory, which is what an event names. */
   readonly commonDir: string;
+  /** The store's `runs` directory, under the override when one is named. */
   readonly runsDir: string;
   /** The invoking worktree's pointer key — the identity of "the current run" here. */
   readonly worktreeKey: string;
@@ -52,10 +79,39 @@ export type RunSurfaceResolution =
   | { readonly ok: true; readonly surface: RunSurface }
   | { readonly ok: false; readonly reason: string };
 
+/** The environment variable that relocates the run store. See this file's header. */
+export const RUN_STORE_OVERRIDE = "DELIVERY_HARNESS_RUN_STORE";
+
+/**
+ * The directory the store is rooted at for a repository whose common directory
+ * is `commonDir`.
+ *
+ * Blank is unset, following this repository's other environment levers. A
+ * value that is set but not absolute FAILS CLOSED — the resolution is refused
+ * rather than falling back to the repository's own store, because a caller
+ * that mis-spells its override is exactly the caller that must not reach a
+ * live store by accident.
+ */
+function storeRootFor(
+  commonDir: string,
+  override: string | undefined,
+): { readonly ok: true; readonly root: string } | { readonly ok: false; readonly reason: string } {
+  const named = override?.trim() ?? "";
+  if (named.length === 0) return { ok: true, root: commonDir };
+  if (!path.isAbsolute(named)) {
+    return { ok: false, reason: `${RUN_STORE_OVERRIDE} must name an absolute directory` };
+  }
+  return { ok: true, root: path.join(named, sha256Hex(commonDir)) };
+}
+
 /**
  * Resolves the run store for the invoking worktree. Never throws: a config-free
  * command turns a failure into a typed blocker, and the boundary wrap turns it
  * into silence.
+ *
+ * The override is read here, on this one path, because this is the one path
+ * every CLI reach for a run store goes through: `emit`, `runs`, `runs serve`,
+ * the boundary wrap's automatic completion, and `verify`'s journal row.
  */
 export async function resolveRunSurface(cwd: string): Promise<RunSurfaceResolution> {
   const location = await resolveRunStoreLocation({
@@ -64,12 +120,15 @@ export async function resolveRunSurface(cwd: string): Promise<RunSurfaceResoluti
     env: gitNamespaceClearedEnvironment(),
   });
   if (!location.ok) return { ok: false, reason: location.reason };
+  const rooted = storeRootFor(location.commonDir, process.env[RUN_STORE_OVERRIDE]);
+  if (!rooted.ok) return { ok: false, reason: rooted.reason };
+  const store = createRunStore(rooted.root);
   return {
     ok: true,
     surface: {
-      store: createRunStore(location.commonDir),
+      store,
       commonDir: location.commonDir,
-      runsDir: location.runsDir,
+      runsDir: store.runsDir,
       worktreeKey: location.worktreeKey,
     },
   };
@@ -77,8 +136,11 @@ export async function resolveRunSurface(cwd: string): Promise<RunSurfaceResoluti
 
 /**
  * The worktree ROOT of a path, for the one thing the run surface needs it for:
- * the config-presence note names a root, and `runs serve` renders a root the
- * operator named rather than the one it was invoked in.
+ * the config-presence note names a root, and BOTH surfaces resolve it here.
+ * `runs serve` renders a root the operator named rather than the one it was
+ * invoked in; `runs show` renders the root of the worktree it was invoked in
+ * rather than the directory, which may be any depth below it. One question
+ * about one repository has to have one answer whichever surface asks it.
  *
  * `--show-toplevel` is a plumbing query that reads no index and runs no hook,
  * alias, or pager, and it runs here with the `GIT_` namespace cleared for the
@@ -122,6 +184,8 @@ export function buildRunEvent(input: {
   readonly kind: string;
   readonly role: "cli" | "executor";
   readonly payload: unknown;
+  readonly version?: "run-event/1" | "run-event/2";
+  readonly eventId?: string;
 }): RunEventInput {
   const payload = typeof input.payload === "object" && input.payload !== null ? (input.payload as Record<string, unknown>) : undefined;
   const mirrored: Record<string, unknown> = {};
@@ -133,7 +197,8 @@ export function buildRunEvent(input: {
     }
   }
   return {
-    version: "run-event/1",
+    version: input.version ?? "run-event/1",
+    ...(input.eventId === undefined ? {} : { eventId: input.eventId }),
     runId: input.runId,
     at: runInstant(),
     repo: { commonDir: input.commonDir },
@@ -191,25 +256,133 @@ const ABSENT: RunJournalRow = { status: "absent", missing: [], attestation: "sel
 export async function resolveRunJournalRow(input: {
   readonly cwd: string;
   readonly treeSha: string;
+  readonly reviewedCandidateTreeShas?: readonly string[];
   readonly mandatedLensIds?: readonly string[];
 }): Promise<RunJournalRow> {
   const resolved = await resolveRunSurface(input.cwd);
   if (!resolved.ok) return ABSENT;
-  const match = await resolved.surface.store.findByCandidateTreeSha(input.treeSha);
+  const acceptedTrees = [...new Set([input.treeSha, ...(input.reviewedCandidateTreeShas ?? [])])];
+  const matches = await Promise.all(acceptedTrees.map((treeSha) => resolved.surface.store.findByCandidateTreeSha(treeSha)));
+  const match = matches.find((entry) => entry !== undefined);
   if (match === undefined) return ABSENT;
   const read = await resolved.surface.store.read(match.runId);
   if (!read.ok) return ABSENT;
-  const evaluation = evaluateRunJournal(read.events, input.treeSha, input.mandatedLensIds);
+  const evaluation = evaluateRunJournal(read.events, input.treeSha, input.mandatedLensIds, acceptedTrees.slice(1));
+  // The same arguments, so the explanations describe exactly these violations.
+  const diagnostics = explainRunJournal(read.events, input.treeSha, input.mandatedLensIds, acceptedTrees.slice(1));
+  const alsoMatching = [...new Set(matches.flatMap((entry) => entry === undefined ? [] : [entry.runId, ...entry.alsoMatching]))]
+    .filter((runId) => runId !== match.runId);
   return {
     runId: match.runId,
-    ...(match.alsoMatching.length === 0 ? {} : { alsoMatching: match.alsoMatching }),
+    ...(alsoMatching.length === 0 ? {} : { alsoMatching }),
     status: evaluation.status,
     missing: evaluation.missing,
-    ...(evaluation.violations.length === 0 ? {} : { violations: evaluation.violations }),
+    ...(evaluation.violations.length === 0 ? {} : { violations: evaluation.violations, explanations: diagnostics.explanations }),
+    ...(acceptedTrees.length === 1 ? {} : { recordTreeSha: input.treeSha, reviewedCandidateTreeShas: acceptedTrees.slice(1) }),
+    ...(diagnostics.roundBinding === undefined ? {} : { roundBinding: diagnostics.roundBinding }),
     attestation: "self",
   };
 }
 
+/**
+ * The instants a delivery record stamps: the journal's own first and last.
+ *
+ * `endedAt` is the last instant the journal had REACHED when it was read, not
+ * the run's ending — `record` runs long before `run.ended`, and a record that
+ * waited for the run to end would never be written. So the pair is the span the
+ * delivery had spent by the time it recorded, which is the figure the record is
+ * for; `runs show` is where the run's own ending is read.
+ */
+export interface RunSpanRow {
+  readonly runId: string;
+  readonly startedAt: string;
+  readonly endedAt: string;
+}
+
+/**
+ * The span of the journal that describes this candidate, or nothing.
+ *
+ * FOUND BY TREE SHA FIRST, for the reason `resolveRunJournalRow` is: a journal
+ * bound to this candidate is one that provably describes it, and by verify time
+ * the run has usually ended and cleared the worktree pointer. The pointer is a
+ * FALLBACK and only where the caller says so, because the two callers need
+ * different things from a miss. `record` is stamping: it runs mid-run, before
+ * anything need have journaled this exact tree, and the worktree's current run
+ * is the run it is recording from — a best-effort stamp is better than none.
+ * `verify` is refusing: a refusal must rest on a journal that binds the
+ * candidate the record binds, never on whichever run happens to be current in
+ * the checkout someone verified from, so it asks without the fallback and
+ * reports the miss as unchecked.
+ *
+ * MORE THAN ONE RUN CAN BIND ONE CANDIDATE, and the store says so: a delivery
+ * that recorded in run A and is verified from a later run B in the same
+ * worktree has two journals naming that tree, and `findByCandidateTreeSha`
+ * returns the most recently started one with the rest in `alsoMatching`.
+ * Refusing on whichever sorted first would block an honest record whose span
+ * run A reports exactly. So a caller that already knows the span it is checking
+ * passes `preferStartedAt`, and the matching run whose journal starts there is
+ * the one returned; only where NO matching run starts there does the
+ * top-ranked run stand, which is the case a refusal may rest on.
+ *
+ * Every failure is nothing found: no store, no match, an unreadable journal, an
+ * empty one. Nothing here decides what a miss means.
+ */
+export async function resolveRunSpan(input: {
+  readonly cwd: string;
+  readonly treeSha: string;
+  readonly allowCurrentRun?: boolean;
+  readonly preferStartedAt?: string;
+}): Promise<RunSpanRow | undefined> {
+  const resolved = await resolveRunSurface(input.cwd);
+  if (!resolved.ok) return undefined;
+  const matched = await resolved.surface.store.findByCandidateTreeSha(input.treeSha);
+  const runIds: string[] = matched === undefined ? [] : [matched.runId, ...matched.alsoMatching];
+  if (runIds.length === 0 && input.allowCurrentRun === true) {
+    const current = await resolved.surface.store.current(resolved.surface.worktreeKey);
+    if (current.ok && current.runId !== undefined) runIds.push(current.runId);
+  }
+  let fallback: RunSpanRow | undefined;
+  for (const runId of runIds) {
+    const read = await resolved.surface.store.read(runId);
+    if (!read.ok) continue;
+    const startedAt = read.events[0]?.at;
+    const endedAt = read.events[read.events.length - 1]?.at;
+    if (startedAt === undefined || endedAt === undefined) continue;
+    const row: RunSpanRow = { runId, startedAt, endedAt };
+    if (input.preferStartedAt === undefined || startedAt === input.preferStartedAt) return row;
+    fallback ??= row;
+  }
+  return fallback;
+}
+
+/**
+ * What the round binding means to someone deciding whether to act on the row.
+ *
+ * The `reviewed-tree` sentence is the one this ticket's readout exists for: it
+ * names WHERE the acceptance came from — the record's own verified evidence —
+ * and says in the same breath that the two trees differ, because the row prints
+ * both and an operator who reads "accepted" as "equal" would then wonder why.
+ */
+const ROUND_BINDING_ROWS: Readonly<Record<RunJournalRoundBinding, string>> = {
+  "record-tree": "the governing closed round binds the record's own candidate tree",
+  "reviewed-tree":
+    "the governing closed round binds a reviewed candidate above, accepted from this record's verified review-neutral projection; the two trees differ and neither is claimed to equal the other",
+  unbound: "no closed round binds the record's candidate tree or any reviewed candidate it accepts",
+};
+
+/**
+ * The one true sentence about authority, printed wherever a violation is.
+ *
+ * An operator reading a list of violated constraints under a line that says
+ * `verified` is being asked a question the row cannot answer by itself: does
+ * this stop anything? It does not. The journal is appended to by anything the
+ * owner can execute, so no admission, gate, or record decision reads it — and
+ * the only thing that can be blocked by it is this command, behind the local
+ * opt-in the operator typed themselves.
+ */
+export const RUN_JOURNAL_ADMISSION_ROW =
+  "none of the above blocks admission: the record's own evidence decides that, and no gate, admission, or record decision reads a journal. Only --require-run-journal blocks, and only this verify invocation.";
+
 /**
  * The row, rendered for a terminal. Every store-derived string goes through
  * `oneLine` for the same reason the viewer's rows do: a run id or a constraint
@@ -222,9 +395,23 @@ export function runJournalRows(row: RunJournalRow): readonly string[] {
   if (row.alsoMatching !== undefined && row.alsoMatching.length > 0) {
     rows.push(`    also matching: ${row.alsoMatching.map((id) => oneLine(id, 128)).join(", ")}`);
   }
+  if (row.recordTreeSha !== undefined && row.reviewedCandidateTreeShas !== undefined) {
+    rows.push(`    record candidate: ${oneLine(row.recordTreeSha, 64)}`);
+    rows.push(`    reviewed candidate: ${row.reviewedCandidateTreeShas.map((tree) => oneLine(tree, 64)).join(", ")} (verified review-neutral projection)`);
+  }
+  if (row.roundBinding !== undefined) rows.push(`    round binding: ${ROUND_BINDING_ROWS[row.roundBinding]}`);
   rows.push(`    missing: ${row.missing.length === 0 ? "(none)" : row.missing.map((entry) => oneLine(entry, 64)).join(", ")}`);
   if (row.violations !== undefined && row.violations.length > 0) {
     rows.push(`    violations: ${row.violations.map((entry) => oneLine(entry, 64)).join(", ")}`);
+    // One indented line per violation, in the order they were raised, each
+    // saying why it exists and — where it is only another warning restated —
+    // which warning that is. Product-authored text, bounded like every other
+    // store-derived row for the same reason.
+    for (const explanation of row.explanations ?? []) {
+      const consequence = explanation.consequenceOf === undefined ? "" : `; a consequence of ${oneLine(explanation.consequenceOf, 64)}, not a separate mistake`;
+      rows.push(`      ${oneLine(explanation.violation, 64)}: ${oneLine(explanation.because, 400)}${consequence}`);
+    }
+    rows.push(`    admission: ${RUN_JOURNAL_ADMISSION_ROW}`);
   }
   return rows;
 }

package/src/run-view-command.ts

@@ -0,0 +1,77 @@
+import { withRetainedRecord } from "./run-view-record.ts";
+import { projectRunView } from "./run-view.ts";
+import {
+  resolveRunSurface,
+  oneLine,
+  runSurfaceBlocker,
+} from "./run-surface.ts";
+import type { ConfigFreeCommandContext, CommandResult } from "./boundary.ts";
+export async function runViewCommand(
+  context: ConfigFreeCommandContext,
+  args: readonly string[],
+): Promise<CommandResult> {
+  const runId = args[0];
+  let json = false;
+  let recordPath: string | undefined;
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === "--json" && !json) json = true;
+    else if (args[i] === "--record" && recordPath === undefined && args[i + 1])
+      recordPath = args[++i];
+    else
+      return {
+        kind: "usage",
+        message:
+          "Usage: runs view <run-id> [--json] [--record <repository-relative-path>]",
+      };
+  }
+  if (!runId)
+    return {
+      kind: "usage",
+      message:
+        "Usage: runs view <run-id> [--json] [--record <repository-relative-path>]",
+    };
+  const resolved = await resolveRunSurface(context.rootDir);
+  const read = resolved.ok
+    ? await resolved.surface.store.read(args[0]!)
+    : undefined;
+  if (!read?.ok)
+    return {
+      kind: "blocked",
+      blockers: [
+        runSurfaceBlocker({
+          code: "run_view_unavailable",
+          summary: "Run observations are unavailable.",
+          details: resolved.ok
+            ? "The selected run could not be read."
+            : oneLine(resolved.reason),
+          remediation: {
+            id: "inspect-run",
+            summary: "Check the selected repository and run identifier.",
+          },
+        }),
+      ],
+    };
+  const view = await withRetainedRecord(
+    projectRunView(read.events, { now: new Date().toISOString() }),
+    context.rootDir,
+    recordPath,
+  );
+  if (json) context.write(JSON.stringify(view));
+  else {
+    context.write(view.authority);
+    for (const section of view.sections) {
+      context.write(section.title);
+      if (!section.items.length) context.write(`  ${section.empty}`);
+      for (const item of section.items) {
+        context.write(`  ${oneLine(item.label)}`);
+        for (const field of item.fields)
+          context.write(`    ${oneLine(field.label)}: ${oneLine(field.value, 8192)}`);
+        if (item.artifactId)
+          context.write(
+            `    Report: runs artifact ${oneLine(args[0]!)} ${oneLine(item.artifactId)} --json`,
+          );
+      }
+    }
+  }
+  return { kind: "ok" };
+}

package/src/run-view-html.ts

@@ -0,0 +1,138 @@
+import { oneLine } from "./run-surface.ts";
+import type { RunView, RunViewItem, RunViewSection } from "./run-view.ts";
+import type {
+  RunArtifactResult,
+  RunArtifactMetadata,
+} from "@agent-delivery-harness/kernel";
+export const escapeViewHtml = (value: string) =>
+  value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+const text = (value: string) => escapeViewHtml(oneLine(value, 8192));
+export const OPERATIONAL_STYLE = `
+:root{color-scheme:light dark;--paper:#f5f5f7;--surface:#fff;--ink:#1d1d1f;--muted:#626267;--line:#d8d8de;--link:#0067c0;--wash:#eaf2fa}
+*{box-sizing:border-box}body{font:400 1rem/1.55 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;font-optical-sizing:auto;letter-spacing:-.01em;color:var(--ink);background:var(--paper);max-width:76rem;margin:0 auto;padding:2.5rem 2rem 5rem;overflow-wrap:anywhere}
+h1{font-size:2.25rem;line-height:1.12;letter-spacing:-.04em;margin:0 0 1.25rem;font-weight:700}h2{font-size:1.35rem;line-height:1.3;letter-spacing:-.025em;margin:2rem 0 .5rem}h3{font-size:1.3rem;line-height:1.3;letter-spacing:-.025em;color:var(--ink);margin:0 0 1rem}h4{font-size:1.05rem;line-height:1.35;margin:0 0 1rem;letter-spacing:-.015em}
+p{margin:.6rem 0 1rem}.meta,.ended{color:var(--muted);font-size:.875rem}.labels{font-size:.875rem;color:var(--muted);background:var(--surface);border:1px solid var(--line);border-radius:.75rem;padding:1rem 1.25rem;margin:1rem 0}.live{color:var(--ink)}.open{color:var(--muted)}
+a{color:var(--link);text-underline-offset:.2em;border-radius:.3rem}a:hover{text-decoration-thickness:2px}a:active,summary:active{background:var(--wash);color:var(--ink)}a:focus-visible,summary:focus-visible{outline:3px solid var(--link);outline-offset:3px}nav{display:flex;flex-wrap:wrap;gap:.4rem;margin:1.5rem 0 2.5rem}nav a{display:inline-flex;align-items:center;min-height:2.75rem;padding:.5rem .85rem;border:1px solid var(--line);border-radius:2rem;background:var(--surface);font-size:.875rem;text-decoration:none}nav a:hover{border-color:var(--link)}
+section{scroll-margin-top:1.5rem;margin:2.5rem 0}section>p{color:var(--muted);font-size:.9375rem}.cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,23rem),1fr));gap:1rem}.card{background:var(--surface);border:1px solid var(--line);border-radius:1rem;padding:1.5rem;min-width:0}.card>a{display:inline-flex;align-items:center;min-height:2.75rem;margin-top:.5rem}dl{margin:.5rem 0}dt{font-size:.8125rem;color:var(--muted);font-weight:500;margin-top:.75rem}dd{margin:.15rem 0 .75rem;overflow-wrap:anywhere}details{margin:1rem 0;border-top:1px solid var(--line);padding-top:.5rem}summary{cursor:pointer;min-height:2.75rem;padding:.5rem 0;font-size:.875rem;color:var(--muted);border-radius:.3rem}
+pre{white-space:pre-wrap;overflow-wrap:anywhere;background:var(--surface);border:1px solid var(--line);border-radius:1rem;padding:1.5rem;font: .875rem/1.65 ui-monospace,SFMono-Regular,Menlo,monospace}.table-scroll{max-width:100%;overflow-x:auto;margin:1rem 0 2rem;border:1px solid var(--line);border-radius:.75rem}table{border-collapse:collapse;display:table;min-width:48rem;width:100%;font-size:.8125rem;margin:0}th,td{border:0;border-bottom:1px solid var(--line);padding:.75rem;text-align:left;vertical-align:top}th{background:var(--surface);font-weight:600}tr:last-child td{border-bottom:0}
+.back{margin:.5rem 0}.run-identifiers,.view-provenance{margin:.25rem 0;border:0;padding:0}.section-navigation{margin:.25rem 0 1rem;border:0;padding:0}.section-navigation nav{margin:.5rem 0}body>details:first-of-type{margin:.5rem 0;border:0;padding:0}body>h1{margin-bottom:.5rem}section:first-of-type{margin-top:1.25rem}
+@media(max-width:600px){body{padding:1.5rem 1rem 3rem;margin:0}h1{font-size:1.875rem}.cards{grid-template-columns:1fr}.card{padding:1.125rem}nav{gap:.375rem}section{margin:2rem 0}}
+@media(prefers-color-scheme:dark){:root{--paper:#161618;--surface:#212124;--ink:#f5f5f7;--muted:#b1b1b8;--line:#45454b;--link:#8ac7ff;--wash:#263b50}}
+@media(prefers-reduced-motion:reduce){*,*::before,*::after{scroll-behavior:auto!important;transition:none!important;animation:none!important}}
+@media(prefers-reduced-transparency:reduce){.card,nav a,.labels{background:var(--surface);backdrop-filter:none}}
+@media(prefers-contrast:more){:root{--muted:var(--ink);--line:var(--ink)}a{text-decoration:underline}nav a{border-width:2px}}
+body{max-width:68rem;padding-top:2rem}main{min-width:0}.page-header{margin:2rem 0}.page-header h1{margin:.4rem 0 .75rem}.eyebrow{font-size:.75rem;letter-spacing:.1em;text-transform:uppercase;font-weight:600;color:var(--muted);margin:0 0 .5rem}.toolbar{display:flex;align-items:center;flex-wrap:wrap;gap:1rem;font-size:.8125rem;margin:1rem 0 2rem}.toolbar a{min-height:2.75rem;display:inline-flex;align-items:center}.toolbar .meta{margin-right:auto}.status{display:inline-flex;padding:.3rem .65rem;background:var(--wash);border-radius:2rem;font-size:.8125rem;font-weight:600}.run-list{display:grid;gap:.75rem}.run-row{display:grid;grid-template-columns:minmax(0,1fr) auto;gap:.75rem 2rem;background:var(--surface);border:1px solid var(--line);border-radius:1rem;padding:1.25rem 1.5rem}.run-row h3{font-size:1.125rem;margin:0}.run-row h3 a{display:inline-flex;align-items:center;min-height:2.75rem}.run-row p{margin:.25rem 0}.run-row .run-caption{grid-column:1/-1;font-size:.8125rem;color:var(--muted)}.now-grid{display:grid;grid-template-columns:1fr 1fr;gap:1.5rem}.now-grid section{margin:0}.now-grid section h2{margin-top:.5rem}.now-grid .cards{grid-template-columns:1fr}.empty-note{margin:0;padding:1rem 0;font-size:.875rem}.supporting{margin-top:3rem}.supporting>summary{font-size:1rem;font-weight:600;color:var(--ink)}summary span{display:block;font-size:.8125rem;font-weight:400;color:var(--muted);margin:.25rem 0}.section-detail>section{margin-top:.5rem}.card{padding:1.25rem}.card h3{font-size:1rem;margin-bottom:.75rem}.card dl{display:grid;grid-template-columns:7rem minmax(0,1fr);gap:.35rem 1rem;margin:0}.card dt,.card dd{margin:0;font-size:.875rem}.card details{margin-bottom:0}.card details dl{display:block}.card details dt{margin-top:.75rem}.card details dd{margin-top:.2rem}.report-card{border-top:3px solid var(--line)}.report-link{font-weight:500;gap:.5rem}.notice{border-left:3px solid var(--line);padding:.75rem 1rem;background:var(--surface);border-radius:.25rem}.report-page{max-width:54rem}.report-document{background:var(--surface);border:1px solid var(--line);border-radius:1.25rem;padding:2.5rem}.report-document header h2{font-size:1.8rem;margin:.5rem 0 1rem}.report-document p{line-height:1.7;white-space:pre-wrap}.report-document pre{padding:0;border:0}.report-document section{margin:2rem 0}.report-document h3{font-size:1.2rem;line-height:1.4}.finding{border-top:1px solid var(--line);padding:1.75rem 0 .5rem}.finding h4{margin:1.5rem 0 .5rem}.count{font-size:.875rem;font-weight:400;color:var(--muted);margin-left:.5rem}.document-fields>dt{color:var(--ink);font-weight:600;font-size:.875rem;margin-top:1.5rem}.document-fields dd p{margin-top:.25rem}.document-list{padding-left:1.25rem}.document-list li{margin:.75rem 0}.report-tools{margin:1.5rem 0}.report-tools a{display:inline-flex;align-items:center;min-height:2.75rem}
+@media(max-width:600px){.now-grid{grid-template-columns:1fr;gap:.5rem}.run-row{padding:1rem;gap:.5rem}.run-row .status{align-self:start}.card dl{grid-template-columns:5.5rem minmax(0,1fr)}.card dt{margin-top:0}.report-document{padding:1.25rem}.page-header{margin:1.5rem 0}.toolbar{gap:.5rem 1rem}}
+`;
+// Presentation consumes the shared projection; it never decides admission.
+const field = (item: RunViewItem, label: string) => item.fields.find(f => f.label === label)?.value;
+const friendlyLabels = new Map([
+  ["lens.outcome-correctness", "Outcome review"],
+  ["lens.adversarial-testing", "Testing review"],
+  ["review", "Review report"],
+  ["reduction", "Review summary"],
+  ["clarification", "Review clarification"],
+  ["partial-output", "Partial report"],
+]);
+const friendly = (value: string) => friendlyLabels.get(value) ?? value;
+const primaryLabels: Record<string, readonly string[]> = {
+  waiting: ["Owner", "Human action required", "Next action", "Freshness"],
+  work: ["Owner", "State", "Freshness", "Next step"],
+  reviews: ["Round", "Owner", "State", "Verdict", "Freshness", "Next step"],
+  reports: ["Availability", "Reason"],
+  finish: ["State", "Owner"],
+  findings: ["State", "Severity", "Deferred issue"],
+};
+function fieldsHtml(fields: RunViewItem["fields"]): string {
+  return fields.map(f => `<dt>${text(f.label)}</dt><dd>${text(f.value)}</dd>`).join("");
+}
+function card(item: RunViewItem, section: string, baseHref: string): string {
+  const labels = primaryLabels[section];
+  const primary = item.fields.filter(f => labels ? labels.includes(f.label) && f.value !== "Unreported" && !(section === "reports" && f.label === "Availability" && f.value === "referenced") : true);
+  const supporting = item.fields.filter(f => !primary.includes(f));
+  const title = section === "reports"
+    ? friendly(field(item, "Lens") === "Unreported" ? item.label : field(item, "Lens") ?? item.label)
+    : section === "work" ? label(field(item, "Phase") ?? "Delivery activity") : friendly(item.label);
+  return `<article data-key="${text(item.id)}" class="card ${section === "reports" ? "report-card" : ""}"><h3>${text(title)}</h3><dl>${fieldsHtml(primary)}</dl>${item.artifactId === undefined ? "" : `<a class="report-link" href="${text(baseHref)}/artifacts/${encodeURIComponent(item.artifactId)}">Read report <span aria-hidden="true">↗</span></a>`}${supporting.length ? `<details data-key="support-${text(item.id)}"><summary>Supporting details</summary><dl>${section === "work" ? `<dt>Activity</dt><dd>${text(item.label)}</dd>` : ""}${fieldsHtml(supporting)}</dl></details>` : ""}</article>`;
+}
+const sectionTitles: Record<string, string> = { waiting: "Needs attention", work: "In progress", reviews: "Reviews", reports: "Review reports", finish: "Delivery milestones" };
+const emptyCopy: Record<string, string> = { waiting: "No waits reported.", reviews: "No current reviews reported.", reports: "Review reports will appear here when they are recorded.", finish: "Delivery milestones have not been reported." };
+function sectionHtml(section: RunViewSection, baseHref: string): string {
+  return `<section id="${text(section.id)}"><h2>${text(sectionTitles[section.id] ?? section.title)}</h2>${section.items.length ? `<div class="cards">${section.items.map(i => card(i, section.id === "earlier-report-list" ? "reports" : section.id, baseHref)).join("")}</div>` : `<p class="empty-note">${text(emptyCopy[section.id] ?? section.empty)}</p>`}</section>`;
+}
+export function renderOperationalView(view: RunView, baseHref: string): string {
+  const sections = new Map(view.sections.map(s => [s.id, s]));
+  const render = (id: string) => sections.has(id) ? sectionHtml(sections.get(id)!, baseHref) : "";
+  const reviews = sections.get("reviews");
+  const work = sections.get("work");
+  const currentReviews = reviews?.items.filter(i => i.label !== "Declared review round" && field(i, "History") !== "Superseded attempt") ?? [];
+  const reviewIds = new Set(currentReviews.map(i => i.id));
+  const reviewCards = currentReviews.map(i => ({ ...i, fields: [...i.fields, ...(work?.items.find(w => w.id === i.id)?.fields.filter(f => ["Freshness", "Next step"].includes(f.label)) ?? [])] }));
+  if (work) sections.set("work", { ...work, items: work.items.filter(i => !reviewIds.has(i.id)), empty: work.items.some(i => reviewIds.has(i.id)) ? "Reviews are shown below." : work.empty });
+  const reports = sections.get("reports");
+  const currentReports = reports?.items.filter(i => field(i, "History") === "Latest observed attempt") ?? [];
+  const earlierReports = reports?.items.filter(i => !currentReports.includes(i)) ?? [];
+  const pastReviews = reviews?.items.filter(i => !currentReviews.includes(i)) ?? [];
+  return `${view.historical ? '<p class="notice">Historical archive · Observations retained at export.</p>' : ""}
+    <div class="now-grid">${render("waiting")}${render("work")}</div>
+    ${sections.get("findings")?.items.length ? render("findings") : ""}
+    ${reviews ? sectionHtml({ ...reviews, items: reviewCards }, baseHref) : ""}
+    ${reports ? sectionHtml({ ...reports, items: currentReports }, baseHref) : ""}
+    ${earlierReports.length && reports ? `<details id="earlier-reports"><summary>Earlier reports <span>${earlierReports.length} reports from earlier attempts or incomplete references</span></summary>${sectionHtml({ ...reports, id: "earlier-report-list", title: "Earlier reports", items: earlierReports }, baseHref)}</details>` : ""}${render("finish")}
+    <details id="supporting-evidence" class="supporting"><summary>Evidence, cost and history<span>Supporting facts and earlier observations</span></summary>
+    ${pastReviews.length && reviews ? sectionHtml({ ...reviews, id: "review-history", title: "Earlier reviews and round details", items: pastReviews }, baseHref) : ""}
+    ${["evidence", "cost", "activity-history", "finding-history"].map(id => `<details id="details-${id}" class="section-detail"><summary>${text(sections.get(id)?.title ?? id)} <span>${sections.get(id)?.items.length ?? 0} entries</span></summary>${render(id)}</details>`).join("")}
+    ${!sections.get("findings")?.items.length ? render("findings") : ""}</details>`;
+}
+const record = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+const label = (key: string) => key.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[_-]/g, " ").replace(/^./, c => c.toUpperCase());
+// A bounded reading view for arbitrary report schemas. All content remains inert;
+// the retained source and download are the authority for exact report bytes.
+function documentValue(value: unknown, depth = 0): string {
+  if (depth > 4) return '<p class="meta">Further detail is available in the original report.</p>';
+  if (Array.isArray(value)) return value.length ? `<ul class="document-list">${value.slice(0, 40).map(v => `<li>${documentValue(v, depth + 1)}</li>`).join("")}</ul>${value.length > 40 ? '<p class="meta">Additional entries are available in the original report.</p>' : ""}` : '<p class="meta">None reported.</p>';
+  if (record(value)) return `<dl class="document-fields">${Object.entries(value).slice(0, 40).map(([k,v]) => `<dt>${text(label(k))}</dt><dd>${documentValue(v, depth + 1)}</dd>`).join("")}</dl>${Object.keys(value).length > 40 ? '<p class="meta">Additional fields are available in the original report.</p>' : ""}`;
+  return `<p>${text(value === null ? "Not reported" : String(value))}</p>`;
+}
+function structuredReport(source: string): string | undefined {
+  let parsed: unknown;
+  try { parsed = JSON.parse(source); } catch { return undefined; }
+  if (!record(parsed)) return undefined;
+  const result = parsed["outcome"] ?? parsed["verdict"] ?? parsed["decision"];
+  const findings = parsed["findings"];
+  const headline = result === "aligned" ? "Aligned" : (result === "dissent" || result === "changes-requested" || result === "CHANGES_REQUESTED") ? "Changes requested" : typeof result === "string" ? result : "Report contents";
+  const summary = parsed["summary"] ?? parsed["assessment"];
+  const rest = Object.fromEntries(Object.entries(parsed).filter(([k]) => !["outcome", "verdict", "decision", "findings", "summary", "assessment"].includes(k)));
+  return `<article class="report-document"><header><p class="eyebrow">Reported result</p><h2>${text(headline)}</h2>${summary === undefined ? "" : documentValue(summary)}</header>
+    ${Array.isArray(findings) ? `<section><h2>Findings <span class="count">${findings.length}</span></h2>${findings.length === 0 ? '<p>No findings reported in this document.</p>' : findings.slice(0, 40).map((finding, index) => {
+      if (!record(finding)) return documentValue(finding);
+      const title = typeof finding["title"] === "string" ? finding["title"] : `Finding ${index + 1}`;
+      const why = finding["why_it_matters"] ?? finding["description"];
+      const fix = finding["suggested_fix"];
+      const extra = Object.fromEntries(Object.entries(finding).filter(([k]) => !["title", "severity", "why_it_matters", "description", "suggested_fix"].includes(k)));
+      return `<article class="finding"><p class="eyebrow">${text(typeof finding["severity"] === "string" ? finding["severity"] : "Severity unreported")}</p><h3>${text(title)}</h3>${why === undefined ? "" : documentValue(why)}${fix === undefined ? "" : `<h4>Recommended change</h4>${documentValue(fix)}`}<details><summary>Evidence and context</summary>${documentValue(extra)}</details></article>`;
+    }).join("")}${findings.length > 40 ? '<p>Additional findings are available in the original report.</p>' : ""}</section>` : findings === undefined ? "" : `<section><h2>Findings</h2>${documentValue(findings)}</section>`}
+    <details><summary>Review context and supporting evidence</summary>${documentValue(rest)}</details></article>`;
+}
+export function renderArtifactDetail(input: {
+  runId: string;
+  artifactId: string;
+  backHref: string;
+  result: RunArtifactResult;
+  historical: boolean;
+  metadata?: RunArtifactMetadata;
+}): string {
+  const { result } = input;
+  const m = result.ok ? result.metadata : input.metadata;
+  const source = result.ok ? Buffer.from(result.base64, "base64").toString("utf8") : "";
+  const document = result.ok ? structuredReport(source) : undefined;
+  const title = friendly(m?.lensId ?? "Review report");
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${text(title)} · Delivery runs</title><style>${OPERATIONAL_STYLE}</style></head><body class="report-page"><main><a class="back" href="${text(input.backHref)}#reports">Return to run</a><header class="page-header"><p class="eyebrow">${input.historical ? "Historical archive" : "Retained report"}${m?.round === undefined ? "" : ` · Round ${m.round}`}</p><h1>${text(title)}</h1><p class="meta">Reported review output; not approval evidence.</p></header>
+    ${result.ok ? `${document ?? `<article class="report-document"><h2>Report contents</h2><pre>${escapeViewHtml(source)}</pre></article>`}<div class="report-tools"><a href="${text(input.backHref)}/artifacts/${encodeURIComponent(input.artifactId)}/download">Download original report</a></div>${document ? `<details><summary>Original report source</summary><pre>${escapeViewHtml(source)}</pre></details>` : ""}` : `<section class="notice" role="status"><h2>Report unavailable</h2><p>${text(result.reason)}</p><p class="meta">${text(result.code)}</p></section>`}
+    <details><summary>Report details and provenance</summary><dl><dt>Run</dt><dd>${text(input.runId)}</dd><dt>Artifact</dt><dd>${text(input.artifactId)}</dd>${m ? `<dt>Lens</dt><dd>${text(m.lensId ?? "Unreported")}</dd><dt>Attempt</dt><dd>${text(m.attemptId)}</dd><dt>Candidate</dt><dd>${text(m.candidateTreeSha)}</dd><dt>Digest</dt><dd>${text(m.digest)}</dd><dt>Size</dt><dd>${m.sizeBytes} bytes</dd>` : ""}</dl></details></main></body></html>`;
+}

package/src/run-view-record.ts

@@ -0,0 +1,119 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { readArchiveFile } from "./run-archive-commands.ts";
+/** Explicit retained-record reads only: no executable configuration or verification. */
+import {
+  isSafeRelativePath,
+  isInsideResolved,
+  parseDeliveryRecord,
+  digestCanonical,
+} from "@agent-delivery-harness/kernel";
+import type { RunView, RunViewItem } from "./run-view.ts";
+export async function withRetainedRecord(
+  view: RunView,
+  root: string,
+  relativePath?: string,
+): Promise<RunView> {
+  if (relativePath === undefined || view.historical) return view;
+  const fields: { label: string; value: string }[] = [];
+  const add = (label: string, value: string) => fields.push({ label, value });
+  add("Source", relativePath);
+  add(
+    "Applicability",
+    "Unknown — no current identity comparison or fresh verification is performed",
+  );
+  add(
+    "Original verification time",
+    "Unavailable — delivery records do not store a verification timestamp",
+  );
+  try {
+    let status = "path_refused";
+    let contents: string | null = null;
+    if (isSafeRelativePath(relativePath)) {
+      const resolvedRoot = await realpath(root);
+      const resolvedFile = await realpath(
+        path.join(resolvedRoot, relativePath),
+      );
+      if (!isInsideResolved(resolvedRoot, resolvedFile))
+        status = "outside_run_root";
+      else {
+        contents = await readArchiveFile(resolvedFile);
+        status = "readable";
+      }
+    }
+    const read = { status, contents };
+    if (read.status !== "readable" || read.contents === null) {
+      add("Status", `Unavailable — ${read.status}`);
+    } else {
+      const parsed = parseDeliveryRecord(read.contents);
+      if (!parsed.ok)
+        add("Status", "Corrupt — retained record grammar is invalid");
+      else {
+        const { integrityDigest, ...unsigned } = parsed.record;
+        if (parsed.record.version !== "delivery-record/2")
+          add(
+            "Status",
+            "Legacy record — integrity unavailable; no accepted evidence inferred",
+          );
+        else if (integrityDigest !== digestCanonical(unsigned))
+          add("Status", "Corrupt — retained record digest does not match");
+        else {
+          add(
+            "Status",
+            "Recorded for the candidate below — retained self-attested record, not current approval",
+          );
+          add("Candidate", parsed.record.candidateBinding.treeSha);
+          add(
+            "Deliverable digest",
+            parsed.record.candidateBinding.deliverableDigest,
+          );
+          for (const claim of parsed.record.claims) {
+            add(`Recorded claim · ${claim.obligationId}`, claim.outcome);
+            for (const evidence of [
+              claim.evidence,
+              ...(claim.supportingEvidence ?? []),
+            ]) {
+              if (evidence?.resolution.kind !== "evidence") continue;
+              const manifest = evidence.resolution.portable?.manifest;
+              if (typeof manifest !== "object" || manifest === null) continue;
+              if (
+                digestCanonical(manifest) !== evidence.resolution.manifestDigest
+              ) {
+                add(
+                  "Retained manifest",
+                  "Corrupt — digest does not match; timestamp unavailable",
+                );
+                continue;
+              }
+              const at = (manifest as Record<string, unknown>)["recordedAt"];
+              add(
+                `Provider-reported recording time · ${evidence.resolution.providerId}`,
+                typeof at === "string" ? at : "Unavailable",
+              );
+            }
+          }
+        }
+      }
+    }
+  } catch (error) {
+    add(
+      "Status",
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+        ? "Unavailable — missing"
+        : "Unavailable — bounded retained record read refused",
+    );
+  }
+  const retained: RunViewItem = {
+    id: "retained-record",
+    label: "Retained delivery record",
+    fields,
+  };
+  return {
+    ...view,
+    sections: view.sections.map((section) =>
+      section.id === "evidence"
+        ? { ...section, items: [retained, ...section.items] }
+        : section,
+    ),
+  };
+}