@agent-delivery-harness/cli 0.1.0 → 0.5.0

package/src/run-surface.ts

@@ -0,0 +1,334 @@
+/**
+ * What `emit`, `runs`, and the boundary wrap share: how the run store is
+ * 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
+ * exists in repositories that have no harness config at all. So the run store
+ * is resolved from git and nothing else, through the kernel's namespace
+ * resolver, with a direct runner and the `GIT_` namespace cleared: an
+ * inherited `GIT_DIR` must never relocate the store into someone else's
+ * repository.
+ *
+ * WHY EVERY PRINTED STRING GOES THROUGH `oneLine`. A journal carries
+ * executor-written free text — rationales, decisions, blocker summaries. It is
+ * rendered to a terminal in a row-per-event table, so an escape sequence could
+ * repaint the screen and an embedded newline could forge a row that looks
+ * exactly like a CLI-written completion. Neutralizing strips the sequences;
+ * collapsing the whitespace is what removes the second attack, and it has to
+ * happen on every single-line field, not just the ones that look risky.
+ */
+import { lstatSync } from "node:fs";
+import path from "node:path";
+import {
+  createBlocker,
+  createRunStore,
+  sha256Hex,
+  evaluateRunJournal,
+  gitNamespaceClearedEnvironment,
+  neutralizeForDisplay,
+  resolveRunStoreLocation,
+  runGitDirect,
+  type Blocker,
+  type RunEventInput,
+  type RunEventKind,
+  type RunJournalRow,
+  type RunStore,
+} from "@agent-delivery-harness/kernel";
+
+/** The config-free commands' own source id family. */
+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;
+}
+
+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({
+    cwd,
+    run: runGitDirect,
+    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,
+      commonDir: location.commonDir,
+      runsDir: store.runsDir,
+      worktreeKey: location.worktreeKey,
+    },
+  };
+}
+
+/**
+ * The worktree ROOT of a path, for the one thing the run surface needs it for:
+ * 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
+ * same reason the store resolution does: a `GIT_DIR` inherited from the
+ * operator's shell must not decide which repository a `--repo` path names.
+ */
+export async function resolveWorktreeRoot(
+  cwd: string,
+): Promise<{ readonly ok: true; readonly root: string } | { readonly ok: false; readonly reason: string }> {
+  const outcome = await runGitDirect({
+    cwd,
+    args: ["rev-parse", "--path-format=absolute", "--show-toplevel"],
+    env: gitNamespaceClearedEnvironment(),
+  });
+  const root = outcome.stdout.trim();
+  if (outcome.code !== 0 || root.length === 0) return { ok: false, reason: `not a git worktree: ${cwd}` };
+  return { ok: true, root };
+}
+
+/**
+ * The writing process's own instant, at the contract's second granularity.
+ * `at` is never settable through an argument surface: whoever writes the event
+ * is whoever is holding the clock.
+ */
+export function runInstant(): string {
+  return `${new Date().toISOString().slice(0, 19)}Z`;
+}
+
+/** The two envelope members a payload may own; both are copied, never invented. */
+const MIRRORED = ["ticket", "candidateTreeSha"] as const;
+
+/**
+ * Builds the envelope around a payload. The mirrored members are copied
+ * verbatim — including a value the validator will reject — because the store
+ * requires the envelope and the payload to agree exactly, and a "helpful"
+ * coercion here would turn a malformed payload into a disagreement instead.
+ */
+export function buildRunEvent(input: {
+  readonly runId: string;
+  readonly commonDir: string;
+  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> = {};
+  if (payload !== undefined) {
+    for (const member of MIRRORED) {
+      if (Object.prototype.hasOwnProperty.call(payload, member) && payload[member] !== undefined) {
+        mirrored[member] = payload[member];
+      }
+    }
+  }
+  return {
+    version: input.version ?? "run-event/1",
+    ...(input.eventId === undefined ? {} : { eventId: input.eventId }),
+    runId: input.runId,
+    at: runInstant(),
+    repo: { commonDir: input.commonDir },
+    kind: input.kind as RunEventKind,
+    actor: { role: input.role },
+    ...mirrored,
+    attestation: "self",
+    payload: (input.payload ?? null) as Readonly<Record<string, unknown>>,
+  } as RunEventInput;
+}
+
+/**
+ * One row's worth of a string: neutralized, then whitespace-collapsed so no
+ * free-text member can end a row and start one of its own, then bounded.
+ */
+export function oneLine(value: string, maximum = 240): string {
+  const collapsed = neutralizeForDisplay(value).replace(/\s+/g, " ").trim();
+  return collapsed.length <= maximum ? collapsed : `${collapsed.slice(0, Math.max(maximum - 1, 0))}…`;
+}
+
+/** The same treatment for anything that is not already a string. */
+export function oneLineOf(value: unknown, maximum = 240): string {
+  if (typeof value === "string") return oneLine(value, maximum);
+  if (value === undefined) return "";
+  return oneLine(JSON.stringify(value) ?? String(value), maximum);
+}
+
+/**
+ * The labels the row carries wherever it is printed. `bound to the record` is
+ * the one that differs from the viewer's: `verify` always has a record's tree
+ * sha, so its round constraints were judged against THIS candidate rather than
+ * against any paired round.
+ */
+export const RUN_JOURNAL_ROW_LABELS = "self-attested; observability, not evidence; bound to the record";
+
+/** Nothing was found, so nothing was evaluated. The one shape `absent` takes. */
+const ABSENT: RunJournalRow = { status: "absent", missing: [], attestation: "self" };
+
+/**
+ * The self-attested completeness row for the candidate a delivery record binds.
+ *
+ * FOUND BY THE RECORD'S TREE SHA, NOT BY THE POINTER. The run whose journal
+ * describes this candidate has usually ended by the time anyone verifies it,
+ * and `run.ended` clears the worktree pointer — so "the current run" is exactly
+ * the wrong question. The store scans instead, which is affordable because it
+ * is unpruned by design and small, and which is what lets a journal outlive the
+ * worktree its run happened in.
+ *
+ * EVERY FAILURE IS `absent`. No store, no match, a journal that refuses the
+ * read discipline, a journal that vanished between the scan and the read: the
+ * row says nothing was found rather than inventing a verdict. A reader that
+ * treats `absent` as a failure does so behind its own opt-in — this function
+ * never decides that.
+ */
+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 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, 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,
+    ...(alsoMatching.length === 0 ? {} : { alsoMatching }),
+    status: evaluation.status,
+    missing: evaluation.missing,
+    ...(evaluation.violations.length === 0 ? {} : { violations: evaluation.violations }),
+    ...(acceptedTrees.length === 1 ? {} : { recordTreeSha: input.treeSha, reviewedCandidateTreeShas: acceptedTrees.slice(1) }),
+    attestation: "self",
+  };
+}
+
+/**
+ * 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
+ * name printed raw is a string from a file anyone who can execute here may
+ * write, and this one is printed under a line an operator reads as a verdict.
+ */
+export function runJournalRows(row: RunJournalRow): readonly string[] {
+  const rows = [`  run journal: ${oneLine(row.status, 64)}  (${RUN_JOURNAL_ROW_LABELS})`];
+  if (row.runId !== undefined) rows.push(`    run: ${oneLine(row.runId, 128)}`);
+  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)`);
+  }
+  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(", ")}`);
+  }
+  return rows;
+}
+
+/** The typed refusal a config-free command returns when it has nothing to work with. */
+export function runSurfaceBlocker(input: {
+  readonly code: string;
+  readonly summary: string;
+  readonly details?: string;
+  readonly remediation: { readonly id: string; readonly summary: string };
+}): Blocker {
+  return createBlocker({
+    code: input.code,
+    source: { kind: "command", id: RUN_SURFACE_SOURCE },
+    summary: input.summary,
+    ...(input.details === undefined ? {} : { details: input.details }),
+    remediations: [{ id: input.remediation.id, kind: "manual_action", summary: input.remediation.summary }],
+  });
+}
+
+/**
+ * Whether a `harness.config.ts` sits at this worktree root. `lstat` only: the
+ * module is never imported, never read, never parsed. The note this answers is
+ * presentational, and the file it looks for is candidate-committed, so its
+ * absence is suppressible by anyone who can write the tree — it bounds
+ * accident, not tampering.
+ */
+export function harnessConfigPresentAt(rootDir: string): boolean {
+  try {
+    return lstatSync(path.join(rootDir, "harness.config.ts")).isFile();
+  } catch {
+    return false;
+  }
+}

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>`;
+}