@agent-delivery-harness/cli 0.5.0 → 0.7.3

package/src/run-projection.ts

@@ -20,11 +20,13 @@
  */
 import {
   RUN_JOURNAL_REQUIRED_ENTRIES,
+  explainRunJournal,
   runJournalCarries,
   runPrimaryTicket,
   projectRunActivities,
   type RunEvent,
   type RunJournalEvaluation,
+  type RunJournalExplanation,
   type RunJournalRequiredEntry,
 } from "@agent-delivery-harness/kernel";
 import { harnessConfigPresentAt, oneLine, oneLineOf } from "./run-surface.ts";
@@ -152,6 +154,8 @@ export function detailOf(event: RunEvent): string {
       return `${oneLineOf(payload["outcome"])}${payload["reference"] === undefined ? "" : ` — ${oneLineOf(payload["reference"])}`}`;
     case "context.saved":
       return `stage ${oneLineOf(payload["stage"])} (observation only)`;
+    case "action.reconciled":
+      return `${oneLineOf(payload["actionId"])} reconciled ${oneLineOf(payload["outcome"])} (host-attested) evidence ${oneLineOf(payload["evidenceReference"])}`;
     case "action.intent":
     case "action.observed":
       return `${oneLineOf(payload["actionId"])} ${oneLineOf(payload["outcome"] ?? "unknown")} reference ${oneLineOf(payload["reference"])}`;
@@ -225,6 +229,174 @@ export function roundRows(events: readonly RunEvent[]): readonly string[] {
   });
 }
 
+// ── Cycle time ───────────────────────────────────────────────────────────────
+
+/**
+ * A span of seconds as one short label, for a column an operator scans.
+ *
+ * WHY A LABEL AND NOT THE NUMBER. `runs list` prints one row per run and the
+ * question it answers is "which of these took a working day"; 47_112 answers
+ * that only after arithmetic. The machine-readable surfaces carry the seconds
+ * themselves, so nothing is lost: `durationSeconds` is beside this everywhere
+ * the label is serialized.
+ *
+ * The smaller unit is zero-padded so the column aligns under a proportional-
+ * enough terminal font, and the largest unit is never dropped: a run of 104
+ * hours reads `104h 03m` rather than being folded into days, because a journal
+ * spans hours and a day boundary is not a thing this file knows about.
+ */
+export function durationLabel(seconds: number): string {
+  const whole = Number.isFinite(seconds) && seconds > 0 ? Math.round(seconds) : 0;
+  const hours = Math.floor(whole / 3600);
+  const minutes = Math.floor((whole % 3600) / 60);
+  const rest = whole % 60;
+  if (hours > 0) return `${hours}h ${String(minutes).padStart(2, "0")}m`;
+  if (minutes > 0) return `${minutes}m ${String(rest).padStart(2, "0")}s`;
+  return `${rest}s`;
+}
+
+/**
+ * The gate time a journal can actually account for.
+ *
+ * `counted` is how many gate completions were journaled and `totalMs` their
+ * sum; `unseen` says the journal carries none at all. That last one is the
+ * honest answer to the thing this ticket was written for: a delivery whose gate
+ * ran outside the CLI wrapper and emitted no `gate.reported` has a tail that
+ * looks free, and a zero printed with no label is indistinguishable from a gate
+ * that took no time. `unreadable` counts a gate completion whose `durationMs`
+ * could not be read as a number, so a partial sum is never passed off as whole.
+ *
+ * EVERY journaled gate is summed, including one superseded by a re-run. The
+ * headline outcome takes the last completion (a re-run supersedes its verdict),
+ * but the time is time: a delivery that gated twice spent both.
+ */
+export interface RunGateTime {
+  readonly totalMs: number;
+  readonly counted: number;
+  readonly unreadable: number;
+  readonly unseen: boolean;
+}
+
+/**
+ * The run's three phases, in seconds, plus what they were spent on.
+ *
+ * The boundaries are the journal's own events, so the three spans tile the
+ * run's whole span and sum back to `durationSeconds` within per-phase rounding:
+ *
+ * - implementation: the first event to the first round event;
+ * - review: that first round event to the last `review.round.closed`, which
+ *   deliberately INCLUDES the fix time between rounds — an operator asking what
+ *   review cost is asking what the loop cost, not what the reviewers were busy;
+ * - tail: the last closed round to the last event, which is `run.ended` on an
+ *   ended run and whatever the run has reached on an open one.
+ *
+ * A run with no round event has no review and no tail: implementation is the
+ * whole span, which is what a delivery that never opened a round actually did.
+ */
+export interface RunPhases {
+  readonly implementationSeconds: number;
+  readonly reviewSeconds: number;
+  readonly tailSeconds: number;
+  /** Logical rounds the journal mentions, opened or closed. */
+  readonly rounds: number;
+  readonly gate: RunGateTime;
+}
+
+/** The two kinds that bound the review phase. */
+const ROUND_KINDS: ReadonlySet<string> = new Set(["review.round.opened", "review.round.closed"]);
+
+/**
+ * An instant held inside `[low, high]`, so the phases tile the span.
+ *
+ * The journal is append-only and its instants are written by whoever holds the
+ * clock, which is not one clock: an executor on a laptop and a CLI inside a
+ * container can disagree by seconds. Without this, one skewed `at` gives a
+ * negative span — reported as zero by `spanSeconds` — and the three phases
+ * silently stop summing to the total. Clamping keeps the arithmetic true and
+ * loses only the skew, which was never measurable anyway. An unparseable
+ * instant is treated as `high`, the same way a missing one is.
+ */
+function heldWithin(value: string | undefined, low: string, high: string): string {
+  const at = value === undefined ? Number.NaN : Date.parse(value);
+  if (!Number.isFinite(at)) return high;
+  const lowAt = Date.parse(low);
+  const highAt = Date.parse(high);
+  if (!Number.isFinite(lowAt) || !Number.isFinite(highAt)) return high;
+  if (at < lowAt) return low;
+  if (at > highAt) return high;
+  return value as string;
+}
+
+/** A gate completion's duration, or nothing when it cannot be read as one. */
+const gateDurationOf = (event: RunEvent): number | undefined => {
+  const value = payloadOf(event)["durationMs"];
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+};
+
+/**
+ * The gate completions a journal carries: the CLI's own for the `gate` command,
+ * and the executor's `gate.reported` for a repository gate that is not a
+ * product command. Both are counted because they are different gates, not two
+ * writers' accounts of one — an adopter whose `npm run check` is not a product
+ * command journals only the second.
+ */
+export function projectGateTime(events: readonly RunEvent[]): RunGateTime {
+  const gates = events.filter(
+    (event) =>
+      event.kind === "gate.reported" ||
+      (event.kind === "command.completed" && event.actor.role === "cli" && payloadOf(event)["command"] === "gate"),
+  );
+  let totalMs = 0;
+  let unreadable = 0;
+  for (const gate of gates) {
+    const duration = gateDurationOf(gate);
+    if (duration === undefined) unreadable += 1;
+    else totalMs += duration;
+  }
+  return { totalMs, counted: gates.length, unreadable, unseen: gates.length === 0 };
+}
+
+/** The run's phase breakdown, derived from the journal and nothing else. */
+export function projectRunPhases(events: readonly RunEvent[]): RunPhases {
+  const startedAt = events[0]?.at ?? "";
+  const lastAt = events[events.length - 1]?.at ?? "";
+  const reviewStart = heldWithin(events.find((event) => ROUND_KINDS.has(event.kind))?.at, startedAt, lastAt);
+  const reviewEnd = heldWithin(events.findLast((event) => event.kind === "review.round.closed")?.at, reviewStart, lastAt);
+  return {
+    implementationSeconds: spanSeconds(startedAt, reviewStart),
+    reviewSeconds: spanSeconds(reviewStart, reviewEnd),
+    tailSeconds: spanSeconds(reviewEnd, lastAt),
+    rounds: roundEntries(events).length,
+    gate: projectGateTime(events),
+  };
+}
+
+/**
+ * The phase breakdown as text rows, shared by every surface that prints it.
+ *
+ * The total row repeats `durationSeconds` rather than re-deriving it, so a
+ * reader can check the three phases against the one figure `runs list` printed
+ * for the same run; `(open)` is on the total because an open run's last event
+ * is not an ending and the tail is still accruing.
+ */
+export function phaseRows(events: readonly RunEvent[]): readonly string[] {
+  const summary = summarize(events);
+  const phases = summary.phases;
+  const gate = phases.gate;
+  const gateRow = gate.unseen
+    ? "unseen — no gate completion is journaled, so any gate this delivery ran is missing from the tail above"
+    : `${durationLabel(gate.totalMs / 1000)} summed over ${gate.counted} journaled gate completion(s)` +
+      (gate.unreadable === 0 ? "" : `; ${gate.unreadable} journaled no readable duration, so the sum under-reports`);
+  return [
+    "  phases:",
+    `    implementation  ${durationLabel(phases.implementationSeconds)}  (first event to the first round)`,
+    `    review          ${durationLabel(phases.reviewSeconds)}  over ${phases.rounds} round(s), fix time between rounds included`,
+    `    tail            ${durationLabel(phases.tailSeconds)}  (last closed round to the last event)`,
+    `    gate time       ${gateRow}`,
+    `    total           ${durationLabel(summary.durationSeconds)}${summary.open ? "  (open; the tail is still accruing)" : ""}`,
+  ];
+}
+
 // ── The readout ──────────────────────────────────────────────────────────────
 
 export interface Readout {
@@ -232,6 +404,12 @@ export interface Readout {
   readonly present: readonly RunJournalRequiredEntry[];
   readonly missing: readonly RunJournalRequiredEntry[];
   readonly violations: readonly string[];
+  /**
+   * One per violation above, in the same order. The readout evaluates unbound
+   * to any record, so these explain the journal's own ordering only; the
+   * record-bound explanations are `verify`'s.
+   */
+  readonly explanations?: readonly RunJournalExplanation[];
   /** The config-presence note, present on exactly the status that it explains. */
   readonly note?: string;
 }
@@ -255,11 +433,16 @@ export function readoutOf(events: readonly RunEvent[], evaluation: RunJournalEva
     evaluation.status === "complete-executor-only" && rootDir !== undefined && harnessConfigPresentAt(rootDir)
       ? `no CLI gate completion in this journal; harness.config.ts present at ${oneLine(rootDir, 400)}`
       : undefined;
+  // Explained with the arguments this readout is taken with — none — so the
+  // sentences describe exactly the violations printed beside them. `verify`
+  // supplies a record and gets the record-bound explanations instead.
+  const explanations = evaluation.violations.length === 0 ? undefined : explainRunJournal(events).explanations;
   return {
     status: evaluation.status,
     present,
     missing: evaluation.missing,
     violations: evaluation.violations,
+    ...(explanations === undefined ? {} : { explanations }),
     ...(note === undefined ? {} : { note }),
   };
 }
@@ -276,7 +459,13 @@ export function readoutRows(events: readonly RunEvent[], evaluation: RunJournalE
     `    present: ${readout.present.length === 0 ? "(none)" : readout.present.join(", ")}`,
     `    missing: ${readout.missing.length === 0 ? "(none)" : [...readout.missing].join(", ")}`,
   ];
-  if (readout.violations.length > 0) rows.push(`    violations: ${[...readout.violations].join(", ")}`);
+  if (readout.violations.length > 0) {
+    rows.push(`    violations: ${[...readout.violations].join(", ")}`);
+    for (const explanation of readout.explanations ?? []) {
+      rows.push(`      ${explanation.violation}: ${oneLine(explanation.because, 400)}`);
+    }
+    rows.push("    admission: none of the above blocks admission; no gate, admission, or record decision reads a journal.");
+  }
   if (readout.note !== undefined) rows.push(`    note: ${readout.note}`);
   return rows;
 }
@@ -311,6 +500,13 @@ export interface RunSummary {
    * is too.
    */
   readonly durationSeconds: number;
+  /**
+   * The same span, divided into the three phases a delivery is actually made
+   * of. Derived from the events beside it, never carried by a journal: an
+   * archive written before this member existed is projected with it, and one
+   * carrying invented phases is re-derived over its own events.
+   */
+  readonly phases: RunPhases;
   readonly roundsOpened: number;
   readonly roundsClosed: number;
   readonly findings: { readonly P0: number; readonly P1: number; readonly P2: number; readonly P3: number };
@@ -379,6 +575,7 @@ export function summarize(events: readonly RunEvent[]): RunSummary {
     startedAt,
     lastAt,
     durationSeconds: spanSeconds(startedAt, lastAt),
+    phases: projectRunPhases(events),
     roundsOpened: events.filter((event) => event.kind === "review.round.opened").length,
     roundsClosed: closed.length,
     findings: {

package/src/run-server.ts

@@ -320,6 +320,15 @@ const EMPTY_SUMMARY: RunSummary = {
   startedAt: "",
   lastAt: "",
   durationSeconds: 0,
+  // Nothing was read, so every phase is empty and the gate is unseen rather
+  // than summed to zero: an unreadable journal reports no gate, not a free one.
+  phases: {
+    implementationSeconds: 0,
+    reviewSeconds: 0,
+    tailSeconds: 0,
+    rounds: 0,
+    gate: { totalMs: 0, counted: 0, unreadable: 0, unseen: true },
+  },
   roundsOpened: 0,
   roundsClosed: 0,
   findings: { P0: 0, P1: 0, P2: 0, P3: 0 },

package/src/run-surface.ts

@@ -49,6 +49,7 @@ import {
   createRunStore,
   sha256Hex,
   evaluateRunJournal,
+  explainRunJournal,
   gitNamespaceClearedEnvironment,
   neutralizeForDisplay,
   resolveRunStoreLocation,
@@ -56,6 +57,7 @@ import {
   type Blocker,
   type RunEventInput,
   type RunEventKind,
+  type RunJournalRoundBinding,
   type RunJournalRow,
   type RunStore,
 } from "@agent-delivery-harness/kernel";
@@ -266,6 +268,8 @@ export async function resolveRunJournalRow(input: {
   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));
+  // 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 {
@@ -273,12 +277,112 @@ export async function resolveRunJournalRow(input: {
     ...(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
@@ -295,9 +399,19 @@ export function runJournalRows(row: RunJournalRow): readonly string[] {
     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/scoped-attempts.ts

@@ -0,0 +1,86 @@
+/** Durable per-check history; allocation order, never completion time, owns precedence. */
+import { randomUUID } from "node:crypto";
+import { link, mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { digestCanonical, type ScopedCheckAttempt } from "@agent-delivery-harness/kernel";
+import { CheckSnapshotError } from "./check-snapshot.ts";
+import type { RecordedScopedAttemptDiagnostic } from "./scoped-diagnostics.ts";
+export interface AttemptPayload {
+  readonly outputs: readonly { readonly path: string; readonly base64: string; readonly sha256: string }[];
+  readonly durationMs?: number;
+  readonly dependencyDigest?: string;
+  readonly log?: string;
+  readonly diagnostic?: RecordedScopedAttemptDiagnostic;
+}
+export interface StoredAttempt { readonly attempt: ScopedCheckAttempt; readonly payload?: AttemptPayload }
+const corrupt = () => new CheckSnapshotError("check_attempt_corrupt", "Scoped check attempt history is missing, corrupt or inconsistent.");
+export class AttemptStore {
+  readonly root: string;
+  constructor(root: string) { this.root = root; }
+  private async generations(): Promise<number[]> {
+    let names: string[];
+    try { names = await readdir(this.root); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw error; }
+    if (names.some(n => !/^[1-9][0-9]*$/.test(n) || !Number.isSafeInteger(Number(n)))) throw corrupt();
+    return names.map(Number).sort((a, b) => a - b);
+  }
+  async allocate(input: Omit<ScopedCheckAttempt, "attemptId" | "generation" | "status">): Promise<ScopedCheckAttempt> {
+    await mkdir(this.root, { recursive: true, mode: 0o700 });
+    let generation = Math.max(0, ...await this.generations()) + 1;
+    for (;;) {
+      const dir = path.join(this.root, String(generation));
+      try { await mkdir(dir, { mode: 0o700 }); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code === "EEXIST") { generation++; continue; } throw error; }
+      const attempt: ScopedCheckAttempt = { ...input, generation, attemptId: randomUUID(), status: "running" };
+      await this.publish(path.join(dir, "running.json"), { attempt });
+      return attempt;
+    }
+  }
+  private async publish(target: string, entry: StoredAttempt): Promise<void> {
+    const temp = `${target}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(temp, JSON.stringify({ digest: digestCanonical(entry), entry }), { flag: "wx", mode: 0o600 });
+      // Linking a complete private file publishes atomically without replacing an
+      // already-published terminal result from this or a competing invocation.
+      await link(temp, target);
+    } finally { await unlink(temp).catch(() => undefined); }
+  }
+  async finish(attempt: ScopedCheckAttempt, status: "passed" | "failed" | "interrupted", payload: AttemptPayload): Promise<void> {
+    const rows = await this.read();
+    const running = rows.find(row => row.attempt.generation === attempt.generation)?.attempt;
+    if (running?.status !== "running" || digestCanonical(running) !== digestCanonical(attempt)) throw corrupt();
+    await this.publish(path.join(this.root, String(attempt.generation), "terminal.json"), { attempt: { ...attempt, status }, payload });
+  }
+  private async load(file: string): Promise<StoredAttempt> {
+    const raw = JSON.parse(await readFile(file, "utf8")) as { digest?: string; entry?: StoredAttempt };
+    const row = raw.entry;
+    const attempt = row?.attempt;
+    const nonempty = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+    const candidate = attempt?.origin?.candidate;
+    if (!row || !attempt || raw.digest !== digestCanonical(row) || attempt.version !== "scoped-attempt/1" ||
+        !nonempty(attempt.attemptId) || !nonempty(attempt.providerId) || !nonempty(attempt.origin?.runId) ||
+        !Number.isSafeInteger(attempt.generation) || attempt.generation < 1 ||
+        !["running", "passed", "failed", "interrupted"].includes(attempt.status) ||
+        ![attempt.inputDigest, attempt.profileDigest].every(value => typeof value === "string" && /^[a-f0-9]{64}$/.test(value)) ||
+        !candidate || ![candidate.treeSha, candidate.deliverableDigest, candidate.identityToken, candidate.baseRef,
+          candidate.baseTipSha, candidate.mergeBaseSha, candidate.workspaceId].every(nonempty)) throw corrupt();
+    if (row.payload?.durationMs !== undefined && (typeof row.payload.durationMs !== "number" || !Number.isFinite(row.payload.durationMs) || row.payload.durationMs < 0)) throw corrupt();
+    return row;
+  }
+  async read(): Promise<StoredAttempt[]> {
+    try {
+      const rows: StoredAttempt[] = [];
+      for (const generation of await this.generations()) {
+        const dir = path.join(this.root, String(generation));
+        const start = await this.load(path.join(dir, "running.json"));
+        if (start.attempt.status !== "running" || start.attempt.generation !== generation) throw corrupt();
+        let terminal: StoredAttempt | undefined;
+        try { terminal = await this.load(path.join(dir, "terminal.json")); }
+        catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+        if (terminal && (terminal.attempt.status === "running" || digestCanonical({ ...terminal.attempt, status: "running" }) !== digestCanonical(start.attempt))) throw corrupt();
+        rows.push(terminal ?? start);
+      }
+      return rows;
+    } catch { throw corrupt(); }
+  }
+}

package/src/scoped-candidate.ts

@@ -0,0 +1,28 @@
+/** Opt-in worktree capture through a private index; the author's staging is untouched. */
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import { promisify } from "node:util";
+import { captureGitCandidate, type CandidateCaptureOptions, type CandidateCommandRunner } from "@agent-delivery-harness/kernel";
+const exec = promisify(execFile);
+export async function captureScopedCandidate(options: CandidateCaptureOptions) {
+  const dir = await mkdtemp(path.join(tmpdir(), "delivery-index-"));
+  const env = { ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_"))), GIT_INDEX_FILE: path.join(dir, "index"), GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" };
+  const run: CandidateCommandRunner = async (command, invocation) => {
+    try {
+      const result = await exec(command[0]!, command.slice(1), { cwd: invocation.cwd, env, encoding: "buffer", maxBuffer: 64 * 1024 * 1024 });
+      return { exitCode: 0, stdout: result.stdout.toString("utf8"), ...(invocation.captureBytes ? { stdoutBase64: result.stdout.toString("base64") } : {}), stderr: result.stderr.toString("utf8") };
+    } catch (error) {
+      const failure = error as { code?: number; stdout?: Buffer; stderr?: Buffer };
+      return { exitCode: typeof failure.code === "number" ? failure.code : -1, stdout: failure.stdout?.toString("utf8") ?? "", stderr: failure.stderr?.toString("utf8") ?? "Git capture failed" };
+    }
+  };
+  try {
+    for (const args of [["read-tree", "HEAD"], ["add", "--all"]]) {
+      const result = await run(["git", ...args], { cwd: options.rootDir });
+      if (result.exitCode !== 0) throw new Error("Cannot capture source into a private index");
+    }
+    return await captureGitCandidate({ ...options, run });
+  } finally { await rm(dir, { recursive: true, force: true }); }
+}