@agent-delivery-harness/cli 0.1.0 → 0.5.0

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

@@ -0,0 +1,419 @@
+/**
+ * `emit` — append one run event to the current delivery run's journal.
+ *
+ * THE EXECUTOR'S ONE WRITE PATH. Everything an executor knows that the product
+ * cannot observe — which lenses it chose and why, what it decided at a fork,
+ * what a review round cost — arrives here or is lost to a transcript. The
+ * command is deliberately small: a kind, a JSON payload, and the store.
+ *
+ * WHAT `emit` MAY NOT SET. Not `seq`, which is the store's, taken inside its
+ * critical section. Not `at`, which is this process's own instant. Not
+ * `actor`, which is always `executor` here — the boundary wrap is the only
+ * writer of `cli`, and the store refuses `cli` on any other kind. And not
+ * `command.completed` at all: a completion is a claim that the product ran a
+ * command, and only the product may make it. That refusal is noted in the
+ * run's note exactly like any other refused append, so an executor that tries
+ * leaves a trace rather than nothing.
+ *
+ * ORDER OF OPERATIONS, AND WHY IT IS THIS ORDER.
+ *   1. Arguments. A malformed invocation is a usage error and touches nothing.
+ *   2. The repository. Outside one there is no store, so there is nowhere to
+ *      write and nowhere to note.
+ *   3. The run. Resolution precedes kind validation, because a refused append
+ *      is recorded against a run — with no run there is nothing to note
+ *      against, and inventing one would create a journal for a typo.
+ *      `run.started` is the single exception: it allocates the run it needs.
+ *   4. The store. Kind and payload validation, the secret discipline, and the
+ *      note on refusal are all the store's, so there is exactly one
+ *      implementation of each.
+ */
+import {
+  RUN_STORE_ID,
+  reduceToProviderId,
+  type RunStore,
+} from "@agent-delivery-harness/kernel";
+import {
+  buildRunEvent,
+  oneLine,
+  resolveRunSurface,
+  runSurfaceBlocker,
+  type RunSurface,
+} from "../run-surface.ts";
+import type { CommandResult, ConfigFreeCommandContext, ConfigFreeCommandDescriptor } from "../boundary.ts";
+
+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 };
+
+function parseArgs(args: readonly string[]): ArgParse {
+  let kind: string | undefined;
+  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]!;
+    if (token === "--force") {
+      force = true;
+      continue;
+    }
+    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 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;
+    }
+    if (token.startsWith("--")) return { ok: false, message: `Unknown flag ${oneLine(token, 64)}.\n${USAGE}` };
+    if (kind !== undefined) return { ok: false, message: `emit takes one kind.\n${USAGE}` };
+    kind = token;
+  }
+
+  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 }),
+    ...(version === undefined ? {} : { version }), ...(eventId === undefined ? {} : { eventId }) } };
+}
+
+/**
+ * The payload as the caller supplied it. Text that is not JSON is passed
+ * through as-is rather than rejected here: the store owns payload validation,
+ * and routing it there is what puts the refusal in the run's note.
+ */
+function parsePayload(text: string): unknown {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return {};
+  try {
+    return JSON.parse(trimmed) as unknown;
+  } catch {
+    return trimmed;
+  }
+}
+
+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",
+    summary: "There is no current run to emit against.",
+    details,
+    remediation: {
+      id: "start-a-run",
+      summary: "Run `delivery-harness emit run.started` in this worktree, or name an existing run with --run.",
+    },
+  });
+
+/**
+ * Resolves the run this event belongs to: `--run` when given, else the
+ * invoking worktree's pointer. An explicit `--run` resolves only when the id
+ * passes the charset check AND its journal exists, so no arbitrary id ever
+ * causes a journal or a note to be created.
+ */
+async function resolveRun(store: RunStore, surface: RunSurface, named: string | undefined): Promise<string | undefined> {
+  if (named !== undefined) {
+    if (named.length > 128 || !RUN_STORE_ID.test(named)) return undefined;
+    const read = await store.read(named);
+    return read.ok ? named : undefined;
+  }
+  const current = await store.current(surface.worktreeKey);
+  return current.ok ? current.runId : undefined;
+}
+
+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);
+    if (!parsed.ok) return { kind: "usage", message: parsed.message };
+    const { kind, run: named, force } = parsed.args;
+
+    const resolved = await resolveRunSurface(context.rootDir);
+    if (!resolved.ok) {
+      return {
+        kind: "blocked",
+        blockers: [
+          runSurfaceBlocker({
+            code: "run_store_unresolvable",
+            summary: "The run store could not be resolved.",
+            details: oneLine(resolved.reason, 200),
+            remediation: {
+              id: "run-inside-a-repository",
+              summary: "Run this command inside a git repository; the run store lives under its common directory.",
+            },
+          }),
+        ],
+      };
+    }
+    const surface = resolved.surface;
+    const store = surface.store;
+
+    if (kind === "run.started") {
+      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);
+    if (runId === undefined) {
+      return {
+        kind: "blocked",
+        blockers: [
+          noRun(
+            named === undefined
+              ? "no current run is pointed at from this worktree, and no --run was given"
+              : `--run ${oneLine(named, 128)} names no readable journal in this store`,
+          ),
+        ],
+      };
+    }
+
+    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
+    // leaves the same trace as any other refused append.
+    if (kind === "command.completed") {
+      await store.noteRefusal(runId, event, {
+        code: "unsupported_combination",
+        pointer: "/kind",
+        message: "command.completed is written by the CLI; emit may not write it",
+      });
+      return {
+        kind: "blocked",
+        blockers: [
+          runSurfaceBlocker({
+            code: "run_event_refused",
+            summary: "command.completed is written by the CLI, never by emit.",
+            details: `run ${runId}: the product's own commands append their completions; an executor reports a non-product gate with gate.reported`,
+            remediation: {
+              id: "use-gate-reported",
+              summary: "Emit gate.reported when the repository's gate is not a product command.",
+            },
+          }),
+        ],
+      };
+    }
+
+    // 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 {
+        kind: "blocked",
+        blockers: [
+          runSurfaceBlocker({
+            code: "run_event_refused",
+            // The rejected kind is echoed reduced to the bound the note records
+            // it at, so the diagnostic and the durable line say the same thing
+            // and neither can carry an escape sequence to the terminal.
+            summary: `The run event was refused: ${reduceToProviderId(kind)}`,
+            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 ${version} contract and emit again.`,
+            },
+          }),
+        ],
+      };
+    }
+
+    if (kind === "run.ended") await store.clearCurrent(surface.worktreeKey, runId);
+    return { kind: "ok", summary: `emitted ${appended.event.kind} seq ${appended.event.seq} to run ${runId}` };
+  },
+};
+
+/**
+ * `run.started` is the one kind that allocates rather than resolves.
+ *
+ * The pointer is read BEFORE the journal is allocated, so the ordinary refusal
+ * — a run is already current and no `--force` was given — leaves no orphan
+ * 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,
+  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;
+  if (displaced !== undefined && !force) {
+    return {
+      kind: "blocked",
+      blockers: [
+        runSurfaceBlocker({
+          code: "run_already_current",
+          summary: "A run is already current for this worktree.",
+          details: `run ${displaced} is current; --force displaces it and records it as displacedRunId`,
+          remediation: {
+            id: "end-or-force",
+            summary: "End the current run with `emit run.ended`, or start this one with --force.",
+          },
+        }),
+      ],
+    };
+  }
+
+  const allocated = await store.allocate();
+  if (!allocated.ok) {
+    return {
+      kind: "blocked",
+      blockers: [
+        runSurfaceBlocker({
+          code: "run_not_allocated",
+          summary: "A run journal could not be allocated.",
+          details: oneLine(allocated.rejections[0]?.message ?? "the store refused to allocate", 200),
+          remediation: { id: "check-the-store", summary: "Check that the repository's git common directory is writable." },
+        }),
+      ],
+    };
+  }
+  const runId = allocated.runId;
+
+  const payload =
+    typeof supplied === "object" && supplied !== null && displaced !== undefined
+      ? { ...(supplied as Record<string, unknown>), displacedRunId: displaced }
+      : supplied;
+
+  const appended = await store.append(
+    runId,
+    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: [
+        runSurfaceBlocker({
+          code: "run_event_refused",
+          summary: "The run event was refused: run.started",
+          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 ${version} contract and emit again.`,
+          },
+        }),
+      ],
+    };
+  }
+
+  let pointed = await store.setCurrent(surface.worktreeKey, runId, { force });
+  let displacedStale = false;
+  // A STALE POINTER IS NOT A CONFLICT. `current` answers `undefined` both when
+  // no pointer exists and when one exists naming a journal this store can no
+  // longer read — a pruned store, a restored `.git`. In the second case the
+  // exclusive create below refuses, and without this the caller's only recourse
+  // is to retry, allocating one more orphan journal per attempt. Re-reading the
+  // pointer separates the two: a run that is now current is a genuine race and
+  // is still refused; a pointer that still names nothing is stale and is
+  // displaced, which is what the operator meant.
+  if (!pointed.ok && !force) {
+    const recheck = await store.current(surface.worktreeKey);
+    if (recheck.ok && recheck.runId === undefined) {
+      pointed = await store.setCurrent(surface.worktreeKey, runId, { force: true });
+      displacedStale = pointed.ok;
+    }
+  }
+  if (!pointed.ok) {
+    await store.discard(runId);
+    return {
+      kind: "blocked",
+      blockers: [
+        runSurfaceBlocker({
+          code: "run_pointer_refused",
+          summary: "The worktree pointer could not be written.",
+          details: `run ${runId}: ${oneLine(pointed.rejections[0]?.message ?? "the pointer was refused", 200)}`,
+          // `--run` cannot help here: `run.started` allocates rather than
+          // resolves, so it never reads that flag. `--force` is the one thing
+          // that displaces a pointer this command refused to overwrite.
+          remediation: { id: "force-the-start", summary: "Start the run with --force to displace the pointer that is already current." },
+        }),
+      ],
+    };
+  }
+
+  // A stale displacement has no id to record — the pointer named nothing this
+  // store could read, which is why it was displaceable at all — so the summary
+  // is the only place the operator learns it happened. It is also the only
+  // signal that the store itself needs attention: a pointer reaches this state
+  // through a pruned journal, a truncated write, or a permissions fault.
+  return {
+    kind: "ok",
+    summary: `started run ${runId}${
+      displaced === undefined
+        ? displacedStale
+          ? " (displaced a stale pointer naming no readable run; the run store may need attention)"
+          : ""
+        : ` (displaced ${displaced})`
+    }`,
+  };
+}

package/src/commands/gate.ts

@@ -1,3 +1,4 @@
+import { runDeclaredCheck } from "../declared-checks.ts";
 /**
  * `gate` — evaluate the delivery gate and, under a TTY, offer a scoped waiver.
  *
@@ -9,29 +10,128 @@
  * only ever offers a waiver to a `human` context, all-or-nothing over waivable
  * findings; the CLI adds no waiver logic of its own.
  */
-import { runAdmission } from "@agent-delivery-harness/kernel";
-import type { CommandContext, CommandDescriptor, CommandResult } from "../boundary.ts";
+import { computeDeliverableIdentity, runAdmission, type AdmissionResult, type Blocker, type LiveProviderResult } from "@agent-delivery-harness/kernel";
+import { CliInterruption, type CommandContext, type CommandDescriptor, type CommandResult } from "../boundary.ts";
+import { oneLine } from "../run-surface.ts";
+
+/**
+ * Runs the ordinary admission first, invokes only configured providers that can
+ * answer the resulting missing-evidence/live-result blocks, then re-evaluates
+ * through the same admission adapter. Configs without provider commands take
+ * the pre-existing path unchanged.
+ */
+export async function runProviderBackedAdmission(
+  context: CommandContext,
+  options: { readonly allowPrompt: boolean; readonly includeInjectedLiveResults: boolean },
+): Promise<AdmissionResult & { readonly observedLiveResults?: readonly LiveProviderResult[] }> {
+  const wiring = await context.wire();
+  const admissionOptions = {
+    captureCandidate: wiring.captureCandidate,
+    projectActivation: wiring.projectActivation,
+    ...wiring.storageOptions,
+  };
+  const input = {
+    rootDir: context.rootDir,
+    config: context.config,
+    context: context.classifyContext(),
+    ...(options.includeInjectedLiveResults && context.liveResults !== undefined ? { liveResults: context.liveResults } : {}),
+  };
+  const finalAdmissionOptions = {
+    ...admissionOptions,
+    ...(options.allowPrompt && context.promptForWaiver !== undefined ? { promptForWaiver: context.promptForWaiver } : {}),
+  };
+
+  if (!context.config.providers.some((provider) => provider.command !== undefined || provider.check !== undefined)) {
+    return runAdmission(input, finalAdmissionOptions);
+  }
+
+  const liveResults: LiveProviderResult[] = options.includeInjectedLiveResults ? [...(context.liveResults ?? [])] : [];
+  const attempted = new Set<string>();
+  const attemptBlockers: Blocker[] = [];
+  let admission = await runAdmission(input, admissionOptions);
+
+  while (!admission.admitted && admission.decision !== undefined && admission.candidate !== undefined) {
+    const requested = new Map<string, { obligationIds: string[]; requiresEvidence: boolean; needsLiveResult: boolean }>();
+    for (const resolution of admission.decision.resolutions) {
+      if (resolution.kind !== "blocked") continue;
+      const obligation = context.config.obligations.find((entry) => entry.id === resolution.obligationId);
+      if (obligation === undefined) continue;
+      const missingCode = obligation.freshness === "live" ? "live_provider_missing" : "review_evidence_missing";
+      for (const finding of resolution.providerFindings ?? []) {
+        if (finding.code !== missingCode || finding.providerId === undefined || attempted.has(finding.providerId)) continue;
+        const registration = context.config.providers.find((provider) => provider.id === finding.providerId);
+        if (registration === undefined || (registration.command === undefined && registration.check === undefined) || !obligation.providers.includes(registration.id)) continue;
+        if (registration.check !== undefined && (obligation.freshness !== "exact_candidate" || !obligation.acceptedPayloadSpecs.includes("checks.passed/1") || admission.decision.resolutions.some(resolution => resolution.kind !== "satisfied_evidence" && resolution.kind !== "not_applicable" && resolution.kind !== "waived" && context.config.obligations.find(entry => entry.id === resolution.obligationId)?.acceptedPayloadSpecs.includes("review.green/1")))) continue;
+        const entry = requested.get(registration.id) ?? { obligationIds: [], requiresEvidence: false, needsLiveResult: false };
+        entry.obligationIds.push(obligation.id);
+        entry.requiresEvidence ||= obligation.freshness === "exact_candidate";
+        entry.needsLiveResult ||= obligation.freshness === "live";
+        requested.set(registration.id, entry);
+      }
+    }
+
+    const next = requested.entries().next().value as
+      | [string, { obligationIds: string[]; requiresEvidence: boolean; needsLiveResult: boolean }]
+      | undefined;
+    if (next === undefined) break;
+    const [providerId, request] = next;
+    attempted.add(providerId);
+    const registration = context.config.providers.find(provider => provider.id === providerId)!;
+    if (registration.check !== undefined) {
+      attemptBlockers.push(...await runDeclaredCheck(context, registration, request.obligationIds, admission.candidate));
+      admission = await runAdmission({ ...input, ...(liveResults.length === 0 ? {} : { liveResults }) }, admissionOptions);
+      continue;
+    }
+    const result = await context.invokeProvider?.({
+      providerId,
+      requiresEvidence: request.requiresEvidence,
+      payload: {
+        gateId: context.config.gateId,
+        providerId,
+        obligationIds: [...new Set(request.obligationIds)].sort(),
+        candidate: admission.candidate,
+      },
+    });
+    if (result === undefined) continue;
+    if (result.kind === "interrupted") throw new CliInterruption("Provider invocation interrupted before a trustworthy terminal outcome.");
+    if (result.kind === "blocked") {
+      attemptBlockers.push(...result.blockers);
+      if (request.needsLiveResult) {
+        liveResults.push({ providerId, runId: result.runId, status: "failed", findings: [] });
+      }
+    } else if (request.needsLiveResult) {
+      liveResults.push(result.liveResult);
+    }
+
+    admission = await runAdmission(
+      { ...input, ...(liveResults.length === 0 ? {} : { liveResults }) },
+      admissionOptions,
+    );
+  }
+
+  if (admission.admitted) return { ...admission, observedLiveResults: liveResults };
+  const final = await runAdmission(
+    { ...input, ...(liveResults.length === 0 ? {} : { liveResults }) },
+    finalAdmissionOptions,
+  );
+  return attemptBlockers.length === 0 || final.admitted
+    ? { ...final, observedLiveResults: liveResults }
+    : { ...final, observedLiveResults: liveResults, blockers: [...attemptBlockers, ...final.blockers] };
+}
 
 export const gateCommand: CommandDescriptor = {
   name: "gate",
   sourceId: "delivery-harness.cli.gate",
   summary: "Evaluate the delivery gate for the current candidate.",
+  usage: "Usage: delivery-harness gate\nTakes no arguments; a waiver is offered only under a real TTY.",
   async run(context: CommandContext): Promise<CommandResult> {
-    const wiring = await context.wire();
-    const result = await runAdmission(
-      {
-        rootDir: context.rootDir,
-        config: context.config,
-        context: context.classifyContext(),
-        ...(context.liveResults === undefined ? {} : { liveResults: context.liveResults }),
-      },
-      {
-        captureCandidate: wiring.captureCandidate,
-        projectActivation: wiring.projectActivation,
-        ...(context.promptForWaiver === undefined ? {} : { promptForWaiver: context.promptForWaiver }),
-        ...wiring.storageOptions,
-      },
-    );
+    // Arguments before admission: `gate` accepts none, and a call it cannot
+    // honour is answered about the call rather than performed approximately.
+    const unexpected = context.args[0];
+    if (unexpected !== undefined) {
+      return { kind: "usage", message: `gate takes no arguments, and ${oneLine(unexpected, 64)} is one.\n${gateCommand.usage}` };
+    }
+    const result = await runProviderBackedAdmission(context, { allowPrompt: true, includeInjectedLiveResults: true });
 
     if (result.admitted) {
       const waiverNote =
@@ -39,7 +139,16 @@ export const gateCommand: CommandDescriptor = {
           ? ` (waived: ${result.waivedObligationIds.join(", ")})`
           : "";
       const kinds = (result.decision?.resolutions ?? []).map((resolution) => `${resolution.obligationId}=${resolution.kind}`);
-      return { kind: "ok", summary: `admitted${waiverNote}: ${kinds.join(", ")}` };
+      // This observation describes the admitted immutable tree. Failure to
+      // observe it cannot change admission; the run journal is not evidence.
+      let digest: string | undefined;
+      if (result.candidate !== undefined) {
+        try {
+          digest = await computeDeliverableIdentity({ rootDir: context.rootDir, treeSha: result.candidate.treeSha,
+            config: { ...context.config, computingIdentityVersion: "validation-tree/v1", reviewNeutral: context.config.recordNeutral } });
+        } catch { /* Best-effort observability, like the completion append. */ }
+      }
+      return { kind: "ok", summary: `admitted${waiverNote}: ${kinds.join(", ")}`, ...(digest === undefined ? {} : { digest }) };
     }
     return { kind: "blocked", blockers: [...result.blockers] };
   },