@agent-delivery-harness/cli 0.2.0 → 0.7.3

package/src/check-snapshot.ts

@@ -0,0 +1,167 @@
+/** Private execution tree. Never shares writable source, objects, index or dependencies. */
+import { spawn } from "node:child_process";
+import { mkdir, mkdtemp, realpath, rename, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { createExecPort, type ExecOutcome } from "@agent-delivery-harness/kernel";
+
+import { snapshotInventoryWorker } from "./snapshot-inventory-worker.ts";
+
+const SNAPSHOT_TIMEOUT_MS = 5 * 60_000;
+export class CheckSnapshotError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string) { super(message); this.code = code; }
+}
+export interface SnapshotRequest {
+  readonly rootDir: string;
+  readonly candidate: { readonly treeSha: string; readonly headSha: string; readonly base: { readonly ref: string; readonly tipSha: string; readonly mergeBaseSha: string } };
+  readonly outputs: readonly string[];
+  readonly gitContext?: "full" | "none";
+  readonly environment: Readonly<Record<string, string>>;
+  readonly dependencies?: { readonly command: readonly [string, ...string[]]; readonly timeoutMs: number };
+  readonly onDependencyResult?: (result: ExecOutcome, durationMs: number) => void;
+  readonly signal?: AbortSignal;
+}
+export interface CheckSnapshot {
+  readonly commandRoot: string;
+  readonly rootDir: string;
+  readonly environment: Readonly<Record<string, string>>;
+  readonly dependencyDigest: string;
+  verify(options?: { readonly timeoutMs: number }): Promise<void>;
+  cleanup(): Promise<void>;
+}
+function inside(root: string, target: string): boolean {
+  const relative = path.relative(root, target);
+  return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+/** Kill the owned read-only process and await close before callers may clean up.
+ * AbortSignal is handled here: child_process's early AbortError event is not
+ * proof that the process has stopped touching the snapshot. */
+async function snapshotProcess(command: string, args: string[], cwd: string, env: Readonly<Record<string, string>>, deadline: number, signal?: AbortSignal): Promise<{ code: number | null; stdout: string }> {
+  if (signal?.aborted) throw new CheckSnapshotError("check_snapshot_interrupted", "Snapshot verification was interrupted.");
+  const remaining = deadline - performance.now();
+  if (remaining <= 0) throw new CheckSnapshotError("check_snapshot_timeout", "Snapshot verification exceeded its deadline.");
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    let failure: CheckSnapshotError | undefined, stdout = "", size = 0;
+    const stop = (code: string, message: string) => {
+      failure ??= new CheckSnapshotError(code, message);
+      child.kill("SIGKILL");
+    };
+    const abort = () => stop("check_snapshot_interrupted", "Snapshot verification was interrupted.");
+    const timer = setTimeout(() => stop("check_snapshot_timeout", "Snapshot verification exceeded its deadline."), remaining);
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+    child.stdout.on("data", (bytes: Buffer) => {
+      size += bytes.length;
+      if (size > 64 * 1024) stop("check_snapshot_unavailable", "Snapshot verifier output exceeded its limit.");
+      else stdout += bytes.toString();
+    });
+    child.stderr.on("data", () => {}); // Drain; never expose private paths or source bytes.
+    child.on("error", () => { failure ??= new CheckSnapshotError("check_snapshot_unavailable", "Snapshot verifier could not execute."); });
+    child.once("close", code => {
+      clearTimeout(timer); signal?.removeEventListener("abort", abort);
+      if (!failure && performance.now() >= deadline) failure = new CheckSnapshotError("check_snapshot_timeout", "Snapshot verification exceeded its deadline.");
+      if (failure) reject(failure); else resolve({ code, stdout });
+    });
+  });
+}
+/** The inventory's blocking filesystem operations live only in a killable process. */
+export async function snapshotInventory(root: string, outputs: readonly string[], excludeDependencies = false, deadline = performance.now() + SNAPSHOT_TIMEOUT_MS, signal?: AbortSignal, forbidGit = false): Promise<string> {
+  const result = await snapshotProcess(process.execPath, ["--input-type=module", "--eval", snapshotInventoryWorker], root,
+    { PATH: process.env["PATH"] ?? "/usr/bin:/bin", DELIVERY_SNAPSHOT_REQUEST: JSON.stringify({ root, outputs, excludeDependencies, forbidGit }) }, deadline, signal);
+  let parsed: { code?: string; digest?: string };
+  try { parsed = JSON.parse(result.stdout); } catch { throw new CheckSnapshotError("check_snapshot_unavailable", "Snapshot inventory returned no valid result."); }
+  if (result.code !== 0 || !/^[a-f0-9]{64}$/.test(parsed.digest ?? "")) throw new CheckSnapshotError(["check_snapshot_escape", "check_snapshot_drift"].includes(parsed.code ?? "") ? parsed.code! : "check_snapshot_unavailable", "Snapshot inventory could not verify private bytes and links.");
+  return parsed.digest!;
+}
+export function executionPath(root: string, value: string): string {
+  return value.split(path.delimiter).filter(p => p && path.isAbsolute(p) && !inside(root, p) && !p.split(path.sep).includes("node_modules")).join(path.delimiter) || "/usr/bin:/bin";
+}
+export async function createCheckSnapshot(input: SnapshotRequest): Promise<CheckSnapshot> {
+  const rootDir = await realpath(await mkdtemp(path.join(tmpdir(), "delivery-check-")));
+  const cleanEnv = { ...input.environment, PATH: executionPath(input.rootDir, input.environment["PATH"] ?? process.env["PATH"] ?? "/usr/bin:/bin"), GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_TERMINAL_PROMPT: "0", GIT_AUTHOR_DATE: "2000-01-01T00:00:00Z", GIT_COMMITTER_DATE: "2000-01-01T00:00:00Z" };
+  let privateControl: string | undefined;
+  let gitDirectory: string | undefined;
+  const git = async (...args: string[]) => {
+    const controller = new AbortController();
+    let timedOut = false;
+    const deadline = performance.now() + SNAPSHOT_TIMEOUT_MS;
+    const timer = setTimeout(() => { timedOut = true; controller.abort(); }, SNAPSHOT_TIMEOUT_MS);
+    const abort = () => controller.abort();
+    input.signal?.addEventListener("abort", abort, { once: true });
+    if (input.signal?.aborted) abort();
+    try {
+      const result = await createExecPort().run({ command: "git", args: gitDirectory ? [`--git-dir=${gitDirectory}`, `--work-tree=${rootDir}`, ...args] : args,
+        cwd: rootDir, env: cleanEnv, maxBuffer: 128 * 1024 * 1024, signal: controller.signal });
+      timedOut ||= performance.now() >= deadline;
+      if (timedOut || result.code !== 0) throw new CheckSnapshotError(timedOut ? "check_snapshot_timeout" : input.signal?.aborted ? "check_snapshot_interrupted" : "check_snapshot_unavailable", "Private Git materialization did not complete successfully.");
+      return result.stdout.trim();
+    } finally { clearTimeout(timer); input.signal?.removeEventListener("abort", abort); }
+  };
+  const cleanup = async () => {
+    const removed = await Promise.allSettled([rootDir, ...(privateControl ? [privateControl] : [])].map(dir => rm(dir, { recursive: true, force: true })));
+    if (removed.some(result => result.status === "rejected")) throw new CheckSnapshotError("check_snapshot_cleanup_failed", "Cannot remove the owned execution snapshot after retaining evidence.");
+  };
+  try {
+    await git("init", "-q");
+    // Fetch transfers object bytes; unlike worktrees/alternates/local clones it
+    // cannot create writable links back to the author's Git metadata.
+    // Accept the source's shallow boundary in this private repository. Without
+    // it, fetch can reject objects or succeed while dropping required grafts.
+    await git("fetch", "--update-shallow", "--no-tags", "--no-write-fetch-head", input.rootDir, input.candidate.headSha, input.candidate.base.tipSha, input.candidate.treeSha);
+    await git("update-ref", "HEAD", input.candidate.headSha);
+    await git("read-tree", input.candidate.treeSha);
+    await git("checkout-index", "--all", "--force");
+    if ((await git("ls-tree", "-r", "--name-only", input.candidate.treeSha)).split("\n").some(p => p.split("/").includes("node_modules"))) throw new CheckSnapshotError("check_dependency_source_overlap", "Tracked node_modules cannot be replaced by private dependency setup.");
+    const candidateRef = "refs/delivery/candidate", baseRef = "refs/delivery/base";
+    const candidateCommit = await git("-c", "user.name=Delivery", "-c", "user.email=delivery@example.invalid", "-c", "commit.gpgsign=false", "commit-tree", input.candidate.treeSha, "-p", input.candidate.headSha, "-m", "Prepared execution snapshot");
+    await git("update-ref", candidateRef, candidateCommit);
+    await git("update-ref", "refs/delivery/origin-head", input.candidate.headSha);
+    await git("update-ref", "HEAD", candidateCommit);
+    await git("update-ref", baseRef, input.candidate.base.tipSha);
+    await git("update-ref", "refs/delivery/merge-base", input.candidate.base.mergeBaseSha);
+    // Conventional branch refs also resolve to the pinned base for existing checks.
+    if (/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(input.candidate.base.ref)) await git("update-ref", input.candidate.base.ref.startsWith("refs/") ? input.candidate.base.ref : `refs/remotes/${input.candidate.base.ref}`, input.candidate.base.tipSha);
+    if (input.gitContext === "none") {
+      privateControl = await realpath(await mkdtemp(path.join(tmpdir(), "delivery-check-control-")));
+      gitDirectory = path.join(privateControl, "repository");
+      await rename(path.join(rootDir, ".git"), gitDirectory);
+    }
+    const controlRoot = privateControl ?? path.join(rootDir, ".git");
+    const inventory = (outputs: readonly string[], sourceOnly = false, deadline = performance.now() + SNAPSHOT_TIMEOUT_MS) => snapshotInventory(rootDir, outputs, sourceOnly, deadline, input.signal, input.gitContext === "none");
+    const sourceDigest = await inventory(input.outputs, true);
+    const environment: Record<string, string> = { ...input.environment, PATH: `${path.join(rootDir, "node_modules/.bin")}${path.delimiter}${cleanEnv["PATH"]}`, HOME: path.join(controlRoot, "home"), TMPDIR: path.join(controlRoot, "tmp"), GIT_CEILING_DIRECTORIES: path.dirname(rootDir),
+      ...(input.gitContext === "none" ? {} : {
+      DELIVERY_CHECK_BASE_REF: baseRef, DELIVERY_CHECK_CANDIDATE_REF: candidateRef, DELIVERY_CHECK_ORIGIN_HEAD: input.candidate.headSha, DELIVERY_CHECK_ORIGIN_TREE: input.candidate.treeSha, DELIVERY_CHECK_MERGE_BASE: input.candidate.base.mergeBaseSha }) };
+    await mkdir(environment["HOME"]!, { recursive: true }); await mkdir(environment["TMPDIR"]!, { recursive: true });
+    if (input.dependencies) {
+      const started = performance.now();
+      const result = await createExecPort().run({ command: input.dependencies.command[0], args: input.dependencies.command.slice(1), cwd: rootDir, env: environment, timeoutMs: input.dependencies.timeoutMs, maxBuffer: 1024 * 1024, ...(input.signal ? { signal: input.signal } : {}) });
+      input.onDependencyResult?.(result, Math.round(performance.now() - started));
+      if (result.code !== 0 || input.signal?.aborted) throw new CheckSnapshotError("check_dependency_failed", "Private dependency installation did not complete successfully.");
+    }
+    if (sourceDigest !== await inventory(input.outputs, true)) throw new CheckSnapshotError("check_snapshot_drift", "Dependency setup changed prepared source bytes.");
+    const dependencyDigest = await inventory(input.outputs);
+    // The second digest covers both source and installed dependency bytes and
+    // all links. It intentionally excludes only declared mutable output paths.
+    const verify = async (options?: { readonly timeoutMs: number }) => {
+      const timeoutMs = options?.timeoutMs ?? SNAPSHOT_TIMEOUT_MS;
+      if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > SNAPSHOT_TIMEOUT_MS) throw new CheckSnapshotError("check_snapshot_timeout", "Snapshot deadline must be positive and cannot exceed five minutes.");
+      const deadline = performance.now() + timeoutMs;
+      // The worker also checks file-only Git metadata, so lstat cannot stall the parent.
+      const verifyGit = async (...args: string[]) => {
+        const result = await snapshotProcess("git", gitDirectory ? [`--git-dir=${gitDirectory}`, `--work-tree=${rootDir}`, ...args] : args, rootDir, cleanEnv, deadline, input.signal);
+        if (result.code !== 0) throw new CheckSnapshotError("check_snapshot_unavailable", "Snapshot Git identity could not be read.");
+        return result.stdout.trim();
+      };
+      await inventory([], false, deadline);
+      if (await verifyGit("write-tree") !== input.candidate.treeSha || await verifyGit("rev-parse", "HEAD") !== candidateCommit || await verifyGit("rev-parse", `${candidateRef}^{tree}`) !== input.candidate.treeSha || await verifyGit("rev-parse", baseRef) !== input.candidate.base.tipSha || dependencyDigest !== await inventory(input.outputs, false, deadline)) throw new CheckSnapshotError("check_snapshot_drift", "Execution changed the private source, dependencies or pinned Git context.");
+    };
+    return { rootDir, commandRoot: path.join(controlRoot, "commands"), environment, dependencyDigest, verify, cleanup };
+  } catch (error) {
+    await cleanup();
+    if (error instanceof CheckSnapshotError) throw error;
+    throw new CheckSnapshotError("check_snapshot_unavailable", "The exact prepared Git tree could not be materialized privately.");
+  }
+}

package/src/command-activity.ts

@@ -0,0 +1,75 @@
+/** Best-effort CLI observations. No caller uses these results for admission. */
+import { randomUUID } from "node:crypto";
+import type { RunEventKind, RunPreparationObservation, WaiverPrompt } from "@agent-delivery-harness/kernel";
+import { buildRunEvent, resolveRunSurface } from "./run-surface.ts";
+
+export interface CommandObservation {
+  readonly needsCandidate: boolean;
+  start(candidateTreeSha: string): Promise<void>;
+  prompt(prompt: WaiverPrompt): WaiverPrompt;
+  finish(exitCode: number, durationMs: number, digest?: string, preparation?: RunPreparationObservation): Promise<void>;
+}
+const absent: CommandObservation = { needsCandidate: false, start: async () => {}, prompt: prompt => prompt, finish: async () => {} };
+function outcome(code: number) { return code === 0 ? "ok" : code === 2 ? "usage" : code === 130 ? "interrupted" : "policy"; }
+
+/** Pin the current run once, so a pointer change cannot split an invocation. */
+export async function beginCommandObservation(cwd: string, command: string): Promise<CommandObservation> {
+  try {
+    const resolved = await resolveRunSurface(cwd);
+    if (!resolved.ok) return absent;
+    const { store, commonDir, worktreeKey } = resolved.surface;
+    const current = await store.current(worktreeKey);
+    if (!current.ok || current.runId === undefined) return absent;
+    const runId = current.runId;
+    const history = await store.read(runId);
+    if (!history.ok) return absent;
+    // Capability is selected before emission. Never upgrade an existing writer.
+    const version = history.events[0]?.version ?? "run-event/1";
+    const attemptId = `command-${randomUUID()}`;
+    const activityId = attemptId;
+    let candidateTreeSha: string | undefined;
+    async function emit(kind: RunEventKind, payload: Record<string, unknown>) {
+      try {
+        await store.append(runId, buildRunEvent({runId,commonDir,kind,role:"cli",version,
+          ...(version === "run-event/2" ? {eventId:randomUUID()} : {}),payload}));
+      } catch { /* Observations never change the command's result. */ }
+    }
+    const binding = () => ({activityId,attemptId,candidateTreeSha});
+    async function activity(state: string, nextStep: string) {
+      if (version !== "run-event/2" || candidateTreeSha === undefined) return;
+      await emit("activity.observed", {...binding(),state,owner:"delivery-harness.cli",phase:command,nextStep});
+    }
+    return {
+      needsCandidate: version === "run-event/2",
+      async start(tree) {
+        candidateTreeSha = tree;
+        await activity("running", "Await command outcome; intermediate progress is unavailable unless explicitly observed.");
+      },
+      prompt(prompt) {
+        return async (decision, obligations) => {
+          if (version !== "run-event/2" || candidateTreeSha === undefined) return prompt(decision, obligations);
+          const waitId = `wait-${randomUUID()}`;
+          const scope = "This command invocation and the waiver decision's candidate and obligations only; this observation grants no authority.";
+          await activity("waiting", "Respond to the native waiver prompt.");
+          await emit("wait.started", {...binding(),waitId,owner:"operator",waitingOn:"human",reason:"The executing command opened its native waiver prompt.",nextAction:"Answer the native prompt.",scope});
+          try {
+            const answer = await prompt(decision, obligations);
+            await emit("wait.resolved", {...binding(),waitId,resolution:answer === false ? "Native prompt declined." : "Native prompt answered; approval remains subject to the gate.",scope});
+            return answer;
+          } catch (error) {
+            await emit("wait.resolved", {...binding(),waitId,resolution:"Native prompt ended without a decision.",scope});
+            throw error;
+          } finally {
+            await activity("running", "Await command outcome.");
+          }
+        };
+      },
+      async finish(code, durationMs, digest, preparation) {
+        await activity(code === 0 ? "completed" : code === 130 ? "interrupted" : "failed", `Command returned ${outcome(code)} (exit ${code}); continue the declared delivery workflow.`);
+        await emit("command.completed", {command,outcome:outcome(code),durationMs,
+          ...(code === 0 && digest !== undefined ? {digest} : {}),
+          ...(version === "run-event/2" && command === "prepare" && code === 0 && preparation !== undefined ? {preparation} : {})});
+      },
+    };
+  } catch { return absent; }
+}

package/src/commands/admit.ts

@@ -0,0 +1,106 @@
+/**
+ * `admit` — carry a concluded host review through the existing admission path.
+ *
+ * The command does not run reviewers and does not construct an approval. The
+ * supplied review-outcome/1 document must already name the digest of the exact
+ * review-context/1 document the current prepared candidate produces. Rebuilding
+ * that deterministic context after preparation lets the existing emitter retain
+ * it with the supplied outcome while refusing any candidate, base, policy,
+ * wiring, release, or charter drift.
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { commandBlocker, type CommandContext, type CommandDescriptor, type CommandResult } from "../boundary.ts";
+import { emitReviewEvidence, OutcomeError } from "../review-evidence.ts";
+import { gateCommand } from "./gate.ts";
+import { prepareCommand } from "./prepare.ts";
+import { recordCommand } from "./record.ts";
+import { reviewContextCommand } from "./review-context.ts";
+import { submitEvidenceCommand } from "./submit-evidence.ts";
+
+const USAGE = [
+  "Usage: delivery-harness admit --outcome <review-outcome.json>",
+  "Prepares the candidate, binds the concluded outcome to its exact current review context, submits it, gates it, and writes the tracked record.",
+  "The command never runs reviewers or commits the record.",
+].join("\n");
+
+function withArgs(context: CommandContext, args: readonly string[]): CommandContext {
+  return { ...context, args };
+}
+
+function report(context: CommandContext, label: string, result: CommandResult): CommandResult | undefined {
+  if (result.kind !== "ok") return result;
+  if (result.summary !== undefined && result.summary !== "") context.write(`${label}: ${result.summary}`);
+  return undefined;
+}
+
+function invalidOutcome(message: string): CommandResult {
+  return {
+    kind: "blocked",
+    blockers: [commandBlocker({
+      code: "review_outcome_invalid",
+      sourceId: "delivery-harness.cli.admit",
+      summary: message,
+      remediations: [{
+        id: "supply-reviewed-current-context",
+        kind: "manual_action",
+        summary: "Prepare the candidate, retain review-context --json before independent review, and supply the concluded outcome naming that exact digest.",
+      }],
+    })],
+  };
+}
+
+export const admitCommand: CommandDescriptor = {
+  name: "admit",
+  sourceId: "delivery-harness.cli.admit",
+  summary: "Prepare and admit a concluded review outcome through the tracked record write.",
+  usage: USAGE,
+  async run(context: CommandContext): Promise<CommandResult> {
+    if (context.args.length !== 2 || context.args[0] !== "--outcome" || !context.args[1] || context.args[1].startsWith("-")) {
+      return { kind: "usage", message: `admit requires --outcome <review-outcome.json>.\n${USAGE}` };
+    }
+
+    let outcome: unknown;
+    try {
+      outcome = JSON.parse(await readFile(path.resolve(context.rootDir, context.args[1]), "utf8"));
+    } catch {
+      return { kind: "usage", message: `The review outcome must be a readable JSON document.\n${USAGE}` };
+    }
+
+    const prepared = await prepareCommand.run(withArgs(context, []));
+    const stoppedAfterPrepare = report(context, "prepared", prepared);
+    if (stoppedAfterPrepare !== undefined) return stoppedAfterPrepare;
+
+    const reviewed = await reviewContextCommand.run(withArgs(context, ["--json"]));
+    if (reviewed.kind !== "ok") return reviewed;
+    if (reviewed.summary === undefined) return invalidOutcome("the prepared candidate produced no review context");
+
+    let originalContext: unknown;
+    try {
+      originalContext = JSON.parse(reviewed.summary);
+    } catch {
+      return invalidOutcome("the prepared candidate produced an unreadable review context");
+    }
+
+    let manifestPath: string;
+    try {
+      const emitted = await emitReviewEvidence(context, originalContext, outcome);
+      manifestPath = emitted.manifestPath;
+    } catch (error) {
+      if (!(error instanceof OutcomeError)) throw error;
+      return invalidOutcome(error.message);
+    }
+    context.write(`review evidence: ${manifestPath}`);
+
+    const submitted = await submitEvidenceCommand.run(withArgs(context, ["--manifest", manifestPath]));
+    const stoppedAfterSubmission = report(context, "submitted", submitted);
+    if (stoppedAfterSubmission !== undefined) return stoppedAfterSubmission;
+
+    const gated = await gateCommand.run(withArgs(context, []));
+    const stoppedAfterGate = report(context, "gate", gated);
+    if (stoppedAfterGate !== undefined) return stoppedAfterGate;
+
+    return recordCommand.run(withArgs(context, []));
+  },
+};

package/src/commands/check.ts

@@ -10,8 +10,9 @@
  * behind. An unresolvable or unwritable store is a typed block, never a crash.
  */
 import path from "node:path";
-import { resolveRecordStorage, BlockedError } from "@agent-delivery-harness/kernel";
+import { deliveryRecordPathFor, resolveRecordStorage, BlockedError } from "@agent-delivery-harness/kernel";
 import type { CommandContext, CommandDescriptor, CommandResult } from "../boundary.ts";
+import { oneLine } from "../run-surface.ts";
 
 /** Named so an interrupted run leaves something obviously disposable. */
 const PROBE_FILE = ".delivery-harness-write-probe";
@@ -20,19 +21,29 @@ export const checkCommand: CommandDescriptor = {
   name: "check",
   sourceId: "delivery-harness.cli.check",
   summary: "Confirm the config loads and the evidence store is usable.",
+  usage: "Usage: delivery-harness check\nTakes no arguments.",
   async run(context: CommandContext): Promise<CommandResult> {
+    const unexpected = context.args[0];
+    if (unexpected !== undefined) {
+      return { kind: "usage", message: `check takes no arguments, and ${oneLine(unexpected, 64)} is one.\n${checkCommand.usage}` };
+    }
     try {
       const storage = await resolveRecordStorage(context.rootDir, { storageNamespace: context.config.storageNamespace });
       const probe = path.join(storage.storageDir, PROBE_FILE);
       await context.artifacts.writeTextFile(probe, "probe\n", { mode: 0o600 });
       await context.artifacts.removeFile(probe);
+      const recordPath = deliveryRecordPathFor(context.config, "<deliverableDigest>");
+      const baseMovement = context.config.deliveryRecordVerification.baseMovement === "stale"
+        ? "base movement stale: verification refuses base-ref, base-tip, or merge-base drift; admit again against the current base"
+        : "base movement allow: verification may accept base drift and names every relaxed drift class";
       return {
         kind: "ok",
         summary: [
           `ok: gate ${context.config.gateId}`,
           `  ${context.config.obligations.length} obligation(s), ${context.config.providers.length} provider(s)`,
           `  store ${storage.storageDir} (writable)`,
-          `  delivery record path ${context.config.deliveryRecordPath} (base movement: ${context.config.deliveryRecordVerification.baseMovement})`,
+          `  delivery record path ${recordPath}`,
+          `  ${baseMovement}`,
         ].join("\n"),
       };
     } catch (error) {

package/src/commands/emit-review-evidence.ts

@@ -0,0 +1,38 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { commandBlocker, type CommandDescriptor } from "../boundary.ts";
+import { emitReviewEvidence, OutcomeError } from "../review-evidence.ts";
+
+export const emitReviewEvidenceCommand: CommandDescriptor = {
+  name: "emit-review-evidence",
+  sourceId: "delivery-harness.cli.emit-review-evidence",
+  summary: "Bind concluded review outcomes to their original prepared context.",
+  usage: "Usage: delivery-harness emit-review-evidence --context <review-context.json>\nReads a review-outcome/1 document on stdin.",
+  async run(context) {
+    if (context.args.length !== 2 || context.args[0] !== "--context" || !context.args[1] || context.args[1].startsWith("-")) {
+      return { kind: "usage", message: "emit-review-evidence requires --context <review-context.json> and a review-outcome/1 document on stdin." };
+    }
+    let original: unknown;
+    let document: unknown;
+    try {
+      original = JSON.parse(await readFile(path.resolve(context.rootDir, context.args[1]), "utf8"));
+      const raw = await context.readStdin?.() ?? "";
+      if (!raw.trim()) return { kind: "usage", message: "The review-outcome/1 document is required on stdin." };
+      document = JSON.parse(raw);
+    } catch {
+      return { kind: "usage", message: "The original context and review outcome must be readable JSON documents." };
+    }
+    try {
+      const result = await emitReviewEvidence(context, original, document);
+      return { kind: "ok", summary: result.manifestPath };
+    } catch (error) {
+      if (!(error instanceof OutcomeError)) throw error;
+      return { kind: "blocked", blockers: [commandBlocker({
+        code: "review_outcome_invalid",
+        sourceId: "delivery-harness.cli.emit-review-evidence",
+        summary: error.message,
+        remediations: [{ id: "supply-reviewed-context", kind: "manual_action", summary: "Use the original review-context --json output and concluded outcomes naming its digest; acquire a new review if the deliverable or review inputs changed." }],
+      })] };
+    }
+  },
+};

package/src/commands/emit.ts

@@ -41,13 +41,18 @@ import {
 } from "../run-surface.ts";
 import type { CommandResult, ConfigFreeCommandContext, ConfigFreeCommandDescriptor } from "../boundary.ts";
 
-const USAGE = "Usage: delivery-harness emit <kind> [--run <id>] [--json <payload>] [--force]";
+const USAGE = "Usage: delivery-harness emit <kind> [--run <id>] [--json <payload>] [--force] [--version 1|2] [--event-id <id>]";
+
+const PAYLOAD_USAGE =
+  "emit needs a JSON payload: use --json <payload>, or omit --json only when piping JSON to stdin until EOF.";
 
 interface ParsedArgs {
   readonly kind: string;
   readonly run?: string;
   readonly json?: string;
   readonly force: boolean;
+  readonly version?: "run-event/1" | "run-event/2";
+  readonly eventId?: string;
 }
 
 type ArgParse = { readonly ok: true; readonly args: ParsedArgs } | { readonly ok: false; readonly message: string };
@@ -57,6 +62,8 @@ function parseArgs(args: readonly string[]): ArgParse {
   let run: string | undefined;
   let json: string | undefined;
   let force = false;
+  let version: "run-event/1" | "run-event/2" | undefined;
+  let eventId: string | undefined;
 
   for (let index = 0; index < args.length; index += 1) {
     const token = args[index]!;
@@ -64,11 +71,16 @@ function parseArgs(args: readonly string[]): ArgParse {
       force = true;
       continue;
     }
-    if (token === "--run" || token === "--json") {
+    if (token === "--run" || token === "--json" || token === "--version" || token === "--event-id") {
       const value = args[index + 1];
       if (value === undefined) return { ok: false, message: `${token} needs a value.\n${USAGE}` };
       if (token === "--run") run = value;
-      else json = value;
+      else if (token === "--json") json = value;
+      else if (token === "--event-id") eventId = value;
+      else {
+        if (value !== "1" && value !== "2") return { ok: false, message: `--version must be 1 or 2.\n${USAGE}` };
+        version = value === "1" ? "run-event/1" : "run-event/2";
+      }
       index += 1;
       continue;
     }
@@ -78,7 +90,8 @@ function parseArgs(args: readonly string[]): ArgParse {
   }
 
   if (kind === undefined) return { ok: false, message: `emit needs a kind.\n${USAGE}` };
-  return { ok: true, args: { kind, force, ...(run === undefined ? {} : { run }), ...(json === undefined ? {} : { json }) } };
+  return { ok: true, args: { kind, force, ...(run === undefined ? {} : { run }), ...(json === undefined ? {} : { json }),
+    ...(version === undefined ? {} : { version }), ...(eventId === undefined ? {} : { eventId }) } };
 }
 
 /**
@@ -96,6 +109,18 @@ function parsePayload(text: string): unknown {
   }
 }
 
+async function suppliedPayload(context: ConfigFreeCommandContext, json: string | undefined): Promise<
+  { readonly ok: true; readonly payload: unknown } | { readonly ok: false; readonly message: string }
+> {
+  if (json !== undefined) return { ok: true, payload: parsePayload(json) };
+  if (context.stdinIsTTY === true) {
+    return { ok: false, message: `${PAYLOAD_USAGE}\nstdin is interactive, so emit will not wait for terminal EOF.\n${USAGE}` };
+  }
+  const text = await context.readStdin();
+  if (text.trim() === "") return { ok: false, message: `${PAYLOAD_USAGE}\n${USAGE}` };
+  return { ok: true, payload: parsePayload(text) };
+}
+
 const noRun = (details: string) =>
   runSurfaceBlocker({
     code: "run_unresolvable",
@@ -127,6 +152,7 @@ export const emitCommand: ConfigFreeCommandDescriptor = {
   name: "emit",
   sourceId: "delivery-harness.cli.emit",
   summary: "Append one run event to the current delivery run's journal.",
+  usage: USAGE,
   configFree: true,
   async run(context: ConfigFreeCommandContext): Promise<CommandResult> {
     const parsed = parseArgs(context.args);
@@ -154,7 +180,18 @@ export const emitCommand: ConfigFreeCommandDescriptor = {
     const store = surface.store;
 
     if (kind === "run.started") {
-      return startRun(surface, force, parsePayload(parsed.args.json ?? (await context.readStdin())));
+      const version = parsed.args.version ?? "run-event/1";
+      if ((version === "run-event/2") !== (parsed.args.eventId !== undefined)) {
+        return {
+          kind: "usage",
+          message: version === "run-event/2"
+            ? `run.started is creating a version 2 run; every emit needs --event-id.\n${USAGE}`
+            : `run.started is creating a version 1 run and does not accept --event-id; drop it.\n${USAGE}`,
+        };
+      }
+      const supplied = await suppliedPayload(context, parsed.args.json);
+      if (!supplied.ok) return { kind: "usage", message: supplied.message };
+      return startRun(surface, force, supplied.payload, version, parsed.args.eventId);
     }
 
     const runId = await resolveRun(store, surface, named);
@@ -171,8 +208,25 @@ export const emitCommand: ConfigFreeCommandDescriptor = {
       };
     }
 
-    const payload = parsePayload(parsed.args.json ?? (await context.readStdin()));
-    const event = buildRunEvent({ runId, commonDir: surface.commonDir, kind, role: "executor", payload });
+    const history = await store.read(runId);
+    if (!history.ok) return { kind: "blocked", blockers: [noRun("the selected run is unreadable")] };
+    const version = history.events[0]?.version ?? "run-event/1";
+    if (parsed.args.version !== undefined && parsed.args.version !== version) {
+      return { kind: "usage", message: "A run's writer version cannot change. End it and start an explicitly linked successor run." };
+    }
+    if ((version === "run-event/2") !== (parsed.args.eventId !== undefined)) {
+      return {
+        kind: "usage",
+        message: version === "run-event/2"
+          ? `run ${runId} is version 2; every emit needs --event-id.\n${USAGE}`
+          : `run ${runId} is version 1 and does not accept --event-id; drop it, and drop the version-2 payload members roundId, bound, grace and reopensRoundId.\n${USAGE}`,
+      };
+    }
+    const supplied = await suppliedPayload(context, parsed.args.json);
+    if (!supplied.ok) return { kind: "usage", message: supplied.message };
+    const payload = supplied.payload;
+    const event = buildRunEvent({ runId, commonDir: surface.commonDir, kind, role: "executor", payload, version,
+      ...(parsed.args.eventId === undefined ? {} : { eventId: parsed.args.eventId }) });
 
     // `command.completed` is the CLI's to write. The refusal is recorded in the
     // run's note through the store's one bounded note writer, so an attempt
@@ -199,7 +253,9 @@ export const emitCommand: ConfigFreeCommandDescriptor = {
       };
     }
 
-    const appended = await store.append(runId, event);
+    // Resolve generated timestamps inside the append lock so concurrent retries
+    // retain the first observation instant while changed content still refuses.
+    const appended = await store.append(runId, event, { reuseExistingTimestamp: true });
     if (!appended.ok) {
       const first = appended.rejections[0];
       return {
@@ -214,7 +270,7 @@ export const emitCommand: ConfigFreeCommandDescriptor = {
             details: `run ${runId}: ${first === undefined ? "the store refused the append" : `${first.code} at ${oneLine(first.pointer, 64) || "/"}: ${oneLine(first.message, 200)}`}`,
             remediation: {
               id: "correct-the-event",
-              summary: "Correct the kind or the payload against the run-event/1 contract and emit again.",
+              summary: `Correct the kind or the payload against the ${version} contract and emit again.`,
             },
           }),
         ],
@@ -234,8 +290,17 @@ export const emitCommand: ConfigFreeCommandDescriptor = {
  * journal behind. `--force` carries the displaced run's id into the new run's
  * own `run.started` payload, which is what makes a restarted delivery legible
  * afterwards.
+ *
+ * THE TWO REFUSALS THAT COME AFTER ALLOCATION are the append and the exclusive
+ * pointer write, and each takes the journal back through `discard`. Without
+ * that, a payload the store refuses leaves an empty journal per retry, and the
+ * loser of a pointer race leaves a journal carrying a real `run.started` —
+ * both of which `runs list` shows as open runs an operator cannot tell from an
+ * abandoned delivery. The removal is best-effort by construction: this command
+ * has already decided to refuse, and a store failure may not change that.
  */
-async function startRun(surface: RunSurface, force: boolean, supplied: unknown): Promise<CommandResult> {
+async function startRun(surface: RunSurface, force: boolean, supplied: unknown,
+  version: "run-event/1" | "run-event/2", eventId?: string): Promise<CommandResult> {
   const store = surface.store;
   const existing = await store.current(surface.worktreeKey);
   const displaced = existing.ok ? existing.runId : undefined;
@@ -279,10 +344,12 @@ async function startRun(surface: RunSurface, force: boolean, supplied: unknown):
 
   const appended = await store.append(
     runId,
-    buildRunEvent({ runId, commonDir: surface.commonDir, kind: "run.started", role: "executor", payload }),
+    buildRunEvent({ runId, commonDir: surface.commonDir, kind: "run.started", role: "executor", payload, version,
+      ...(eventId === undefined ? {} : { eventId }) }),
   );
   if (!appended.ok) {
     const first = appended.rejections[0];
+    await store.discard(runId);
     return {
       kind: "blocked",
       blockers: [
@@ -292,7 +359,7 @@ async function startRun(surface: RunSurface, force: boolean, supplied: unknown):
           details: `run ${runId}: ${first === undefined ? "the store refused the append" : `${first.code} at ${oneLine(first.pointer, 64) || "/"}: ${oneLine(first.message, 200)}`}`,
           remediation: {
             id: "correct-the-event",
-            summary: "Correct the payload against the run-event/1 contract and emit again.",
+            summary: `Correct the payload against the ${version} contract and emit again.`,
           },
         }),
       ],
@@ -317,6 +384,7 @@ async function startRun(surface: RunSurface, force: boolean, supplied: unknown):
     }
   }
   if (!pointed.ok) {
+    await store.discard(runId);
     return {
       kind: "blocked",
       blockers: [