@agent-delivery-harness/cli 0.2.0 → 0.5.0

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: [

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,8 +10,9 @@
  * 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, type AdmissionResult, type Blocker, type LiveProviderResult } from "@agent-delivery-harness/kernel";
+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
@@ -21,7 +23,7 @@ import { CliInterruption, type CommandContext, type CommandDescriptor, type Comm
 export async function runProviderBackedAdmission(
   context: CommandContext,
   options: { readonly allowPrompt: boolean; readonly includeInjectedLiveResults: boolean },
-): Promise<AdmissionResult> {
+): Promise<AdmissionResult & { readonly observedLiveResults?: readonly LiveProviderResult[] }> {
   const wiring = await context.wire();
   const admissionOptions = {
     captureCandidate: wiring.captureCandidate,
@@ -39,7 +41,7 @@ export async function runProviderBackedAdmission(
     ...(options.allowPrompt && context.promptForWaiver !== undefined ? { promptForWaiver: context.promptForWaiver } : {}),
   };
 
-  if (!context.config.providers.some((provider) => provider.command !== undefined)) {
+  if (!context.config.providers.some((provider) => provider.command !== undefined || provider.check !== undefined)) {
     return runAdmission(input, finalAdmissionOptions);
   }
 
@@ -58,7 +60,8 @@ export async function runProviderBackedAdmission(
       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?.command === undefined || !obligation.providers.includes(registration.id)) continue;
+        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";
@@ -73,6 +76,12 @@ export async function runProviderBackedAdmission(
     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,
@@ -100,21 +109,28 @@ export async function runProviderBackedAdmission(
     );
   }
 
-  if (admission.admitted) return admission;
+  if (admission.admitted) return { ...admission, observedLiveResults: liveResults };
   const final = await runAdmission(
     { ...input, ...(liveResults.length === 0 ? {} : { liveResults }) },
     finalAdmissionOptions,
   );
   return attemptBlockers.length === 0 || final.admitted
-    ? final
-    : { ...final, blockers: [...attemptBlockers, ...final.blockers] };
+    ? { ...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> {
+    // 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) {
@@ -123,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] };
   },

package/src/commands/maintain.ts

@@ -129,6 +129,7 @@ export const maintainCommand: CommandDescriptor = {
   name: "maintain",
   sourceId: SOURCE_ID,
   summary: "Maintain the product installation (update, rollback, trust-state pin/revoke/unrevoke/high-water-mark).",
+  usage: `Usage: delivery-harness maintain <operation> [options]\nOperations: ${MAINTAIN_OPERATIONS.join(" | ")}`,
   async run(context: CommandContext): Promise<CommandResult> {
     const [operation, ...rest] = context.args;
     if (operation === undefined) {

package/src/commands/managed.ts

@@ -228,6 +228,7 @@ export const managedCommand: CommandDescriptor = {
   name: "managed",
   sourceId: SOURCE_ID,
   summary: "Drive the managed delivery's next checkpoint (status, stages, sensor, review, admission, record, finish).",
+  usage: `Usage: delivery-harness managed <operation> [options]\nOperations: ${MANAGED_OPERATIONS.join(" | ")}`,
   async run(context: CommandContext): Promise<CommandResult> {
     const [operation, ...rest] = context.args;
     if (operation === undefined) {