@agent-delivery-harness/cli 0.1.0 → 0.5.0

package/src/boundary.ts

@@ -1,9 +1,9 @@
 /**
  * The one boundary every CLI command runs behind.
  *
- * WHY ONE BOUNDARY. Seven commands, one place that loads config, wires the repo,
- * classifies exit codes, and renders failures. A command never touches
- * `process`, never prints a stack, never chooses an exit code of its own: it
+ * WHY ONE BOUNDARY. Nine config-loading commands, one place that loads config,
+ * wires the repo, classifies exit codes, and renders failures. A command never
+ * touches `process`, never prints a stack, never chooses an exit code of its own: it
  * returns a typed result and the boundary maps it. That is what keeps the three
  * exit semantics — policy block, usage error, interruption — identical across
  * commands, and what keeps every operator-facing byte flowing through the one
@@ -26,6 +26,7 @@
  * disagreement unconstructible in the first place.
  */
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { pathToFileURL } from "node:url";
 import {
   BlockedError,
@@ -37,20 +38,30 @@ import {
   evaluateCandidateActivation,
   renderBlockers,
   resolveRecordStorage,
+  submitManifest,
   validateHarnessConfig,
   withDeliverableIdentity,
   type ArtifactsPort,
   type Blocker,
   type CaptureCandidate,
   type CapturedCandidate,
+  type CompiledAdopterPolicyBinding,
   type EnvSnapshot,
   type ExecutionContext,
   type HarnessConfig,
   type LiveProviderResult,
   type NonEmptyTuple,
   type ReviewActivationProjection,
+  type RunPreparationObservation,
   type WaiverPrompt,
 } from "@agent-delivery-harness/kernel";
+import {
+  invokeProviderRail,
+  openProviderRailProcess,
+  type ProviderRailInvocationResult,
+  type ProviderRailSession,
+} from "./provider-rails.ts";
+import { beginCommandObservation, type CommandObservation } from "./command-activity.ts";
 
 // ── Exit codes ───────────────────────────────────────────────────────────────
 
@@ -78,7 +89,7 @@ export class CliInterruption extends Error {
  * the typed blockers to render; `usage` is an argument or invocation error.
  */
 export type CommandResult =
-  | { readonly kind: "ok"; readonly summary?: string }
+  | { readonly kind: "ok"; readonly summary?: string; readonly digest?: string; readonly preparation?: RunPreparationObservation }
   | { readonly kind: "blocked"; readonly blockers: readonly Blocker[] }
   | { readonly kind: "usage"; readonly message: string };
 
@@ -96,11 +107,15 @@ export interface RepoWiring {
 export interface CommandContext {
   readonly rootDir: string;
   readonly config: HarnessConfig;
+  /** Optional adopter binding; managed commands also load the persisted binding after registration. */
+  readonly policyBinding?: CompiledAdopterPolicyBinding;
   readonly env: EnvSnapshot;
   readonly stdinIsTTY: boolean;
   readonly stdoutIsTTY: boolean;
   /** Positional and flag arguments after the command name. */
   readonly args: readonly string[];
+  readonly readStdin?: () => Promise<string>;
+  readonly signal?: AbortSignal;
   /**
    * Wires capture and the store from this repo, memoized. Lazy so `--help`
    * wires nothing and so a command owns how it renders a store that will not
@@ -111,6 +126,12 @@ export interface CommandContext {
   /** Present only when the run can ask a human; the boundary gates it on a TTY. */
   readonly promptForWaiver?: WaiverPrompt;
   readonly liveResults?: readonly LiveProviderResult[];
+  /** Runs one configured provider through the neutral stdio rail, if it has a command. */
+  readonly invokeProvider?: (input: {
+    readonly providerId: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly requiresEvidence: boolean;
+  }) => Promise<ProviderRailInvocationResult | undefined>;
   /** Emits one line of operator-facing output to stdout. */
   readonly write: (text: string) => void;
   /** Classifies the execution context from this invocation's env + TTY. */
@@ -122,9 +143,71 @@ export interface CommandDescriptor {
   /** The blocker `source.id` this command stamps on failures it raises itself. */
   readonly sourceId: string;
   readonly summary: string;
+  /**
+   * What a lone `--help`/`-h` on this command is answered with, printed by the
+   * boundary before anything is loaded. It is the command's own text — its
+   * invocation form and, where the command has one, the sentence explaining
+   * what its flags decide. Most commands build their own usage errors from it
+   * too, but nothing enforces that: `emit-review-evidence`, `maintain`,
+   * `managed` and `submit-evidence`'s missing-manifest arm phrase theirs from
+   * separate literals, so this member is the help answer and not a
+   * single-authority claim over every usage message.
+   */
+  readonly usage: string;
   run(context: CommandContext): Promise<CommandResult>;
 }
 
+// ── The config-free command class ────────────────────────────────────────────
+
+/**
+ * What a config-free command may reach. Deliberately much less than
+ * {@link CommandContext}: no config, no wiring, no provider rail, no artifacts
+ * port. A run event belongs to the repository, not to a configured gate, and
+ * `emit` has to work in a repository that has no `harness.config.ts` at all.
+ *
+ * The ONE thing a config-free command may do with `harness.config.ts` is ask
+ * whether the path exists (`lstat`, no follow) at a worktree root. It never
+ * imports it, loads it, or parses it — which is why the config loader is not
+ * reachable from here even as a seam.
+ */
+export interface ConfigFreeCommandContext {
+  readonly rootDir: string;
+  readonly env: EnvSnapshot;
+  /** Whether omitted payload input would read from an interactive terminal. */
+  readonly stdinIsTTY?: boolean;
+  /** Positional and flag arguments after the command name. */
+  readonly args: readonly string[];
+  /** The payload channel: everything on stdin, when a command reads one. */
+  readStdin(): Promise<string>;
+  /** Emits one line of operator-facing output to stdout. */
+  readonly write: (text: string) => void;
+  /**
+   * The invocation's cancellation, for the one config-free command that does
+   * not return on its own. `runs serve` holds a socket open until the operator
+   * ends it; without a signal it serves forever, which is exactly right for a
+   * terminal and useless for a caller that has to get its process back.
+   */
+  readonly signal?: AbortSignal;
+}
+
+export interface ConfigFreeCommandDescriptor {
+  readonly name: string;
+  readonly sourceId: string;
+  readonly summary: string;
+  /** As {@link CommandDescriptor.usage}: one help contract across both classes. */
+  readonly usage: string;
+  /** The discriminator the boundary dispatches on, before any config load. */
+  readonly configFree: true;
+  run(context: ConfigFreeCommandContext): Promise<CommandResult>;
+}
+
+/** Either command class; the registry holds both. */
+export type AnyCommandDescriptor = CommandDescriptor | ConfigFreeCommandDescriptor;
+
+export function isConfigFreeCommand(descriptor: AnyCommandDescriptor): descriptor is ConfigFreeCommandDescriptor {
+  return (descriptor as ConfigFreeCommandDescriptor).configFree === true;
+}
+
 // ── Runtime the boundary is driven with ──────────────────────────────────────
 
 export interface CliRuntime {
@@ -136,11 +219,23 @@ export interface CliRuntime {
   readonly stderr: (text: string) => void;
   /** Loads the consumer config. Defaults to importing `harness.config.ts`. */
   readonly loadConfig?: (rootDir: string) => Promise<HarnessConfig>;
+  /** An embedding adopter may pass its already-compiled policy directly. */
+  readonly policyBinding?: CompiledAdopterPolicyBinding;
   /** The interactive waiver prompt. Only ever offered under a TTY. */
   readonly promptForWaiver?: WaiverPrompt;
   /** The filesystem port. Defaults to one rooted in the system temp directory. */
   readonly artifacts?: ArtifactsPort;
   readonly liveResults?: readonly LiveProviderResult[];
+  readonly signal?: AbortSignal;
+  /** Reads the whole of stdin, for the one command whose payload arrives there. */
+  readonly readStdin?: () => Promise<string>;
+  /** Test/embedding seam. The ordinary runtime opens the provider's configured command. */
+  readonly openProviderRail?: (input: {
+    readonly providerId: string;
+    readonly command: readonly [string, ...string[]];
+    readonly cwd: string;
+    readonly env: EnvSnapshot;
+  }) => Promise<ProviderRailSession>;
 }
 
 // ── Blocker helpers ──────────────────────────────────────────────────────────
@@ -225,13 +320,58 @@ export async function wireRepo(rootDir: string, config: HarnessConfig): Promise<
 
 // ── The boundary ─────────────────────────────────────────────────────────────
 
-const USAGE = (commands: readonly CommandDescriptor[]): string =>
-  [
+/**
+ * The listing column is computed from the longest registered name, never a
+ * constant: a fixed pad width silently fused `emit-review-evidence` (twenty
+ * characters) into its own summary, and every later command name long enough
+ * to reach the width would have done the same. Two spaces is the separator, so
+ * the longest name is still visibly separated from its summary.
+ */
+const NAME_GAP = 2;
+
+const USAGE = (commands: readonly AnyCommandDescriptor[]): string => {
+  const column = Math.max(0, ...commands.map((command) => command.name.length)) + NAME_GAP;
+  return [
     "Usage: delivery-harness <command> [options]",
     "",
     "Commands:",
-    ...commands.map((command) => `  ${command.name.padEnd(16)}${command.summary}`),
+    ...commands.map((command) => `  ${command.name.padEnd(column)}${command.summary}`),
   ].join("\n");
+};
+
+/**
+ * A lone `--help`/`-h`, and nothing else. Deliberately exact: `--help` among
+ * other arguments is an invocation the command itself has to judge, and
+ * answering it as help would let a real invocation be silently swallowed.
+ */
+const isHelpRequest = (args: readonly string[]): boolean =>
+  args.length === 1 && (args[0] === "--help" || args[0] === "-h");
+
+/**
+ * THE WRAPPED COMMANDS, NAMED ONE BY ONE.
+ *
+ * Exactly the candidate-facing loop plus its preflight. `managed` and
+ * `maintain` are deliberately absent: they are host-facing and
+ * installation-scoped, and a completion event for them would describe
+ * something that is not a step of the delivery run the journal is about.
+ * `emit` and `runs` are absent because a viewer that recorded its own
+ * invocations would fill the journal it renders.
+ *
+ * An allowlist rather than a denylist: a command added to the registry is
+ * unwrapped until someone decides it belongs here, which is the direction that
+ * fails safe for a store nothing authoritative may read.
+ */
+export const COMPLETION_WRAPPED_COMMANDS: readonly string[] = [
+  "admit",
+  "check",
+  "prepare",
+  "review-context",
+  "emit-review-evidence",
+  "submit-evidence",
+  "gate",
+  "record",
+  "verify",
+];
 
 /**
  * Runs one CLI invocation to an exit code. Total: it maps every command result
@@ -240,7 +380,7 @@ const USAGE = (commands: readonly CommandDescriptor[]): string =>
  */
 export async function runCliBoundary(
   argv: readonly string[],
-  commands: readonly CommandDescriptor[],
+  commands: readonly AnyCommandDescriptor[],
   runtime: CliRuntime,
 ): Promise<number> {
   const [commandName, ...args] = argv;
@@ -256,6 +396,89 @@ export async function runCliBoundary(
     return EXIT_USAGE;
   }
 
+  // HELP IS ANSWERED HERE, AND ONLY HERE. After the descriptor is resolved —
+  // so the answer is that command's own usage — and before config loading,
+  // wiring, the command observation, or the action. Answering it inside each
+  // command would put the answer after the config load the command class
+  // performs for it, which is how `gate --help`, `record --help` and
+  // `check --help` came to run the gate, the record and the preflight: those
+  // commands parse no arguments at all, so a help request reached their action
+  // unexamined. A read-only question is answered read-only, for every command
+  // in both classes, from one predicate.
+  if (isHelpRequest(args)) {
+    runtime.stdout(`${descriptor.usage}\n`);
+    return EXIT_OK;
+  }
+
+  // CONFIG-FREE COMMANDS ARE DISPATCHED FIRST, before any config load. That
+  // ordering is the whole point of the class: `emit` runs in a repository with
+  // no `harness.config.ts`, and no other command's `config_unloadable` timing
+  // moves because of it.
+  if (isConfigFreeCommand(descriptor)) {
+    return runConfigFreeCommand(descriptor, args, runtime);
+  }
+
+  const startedAt = Date.now();
+  const observation = COMPLETION_WRAPPED_COMMANDS.includes(descriptor.name)
+    ? await beginCommandObservation(runtime.cwd, descriptor.name) : undefined;
+  let completed: Extract<CommandResult, { kind: "ok" }> | undefined;
+  const code = await runConfiguredCommand(descriptor, args, runtime, value => { completed = value; }, observation);
+  await observation?.finish(code, Date.now() - startedAt, completed?.digest, completed?.preparation);
+  return code;
+}
+
+/** The config-free path: a typed result mapped to an exit code, and nothing else. */
+async function runConfigFreeCommand(
+  descriptor: ConfigFreeCommandDescriptor,
+  args: readonly string[],
+  runtime: CliRuntime,
+): Promise<number> {
+  try {
+    const result = await descriptor.run({
+      rootDir: runtime.cwd,
+      env: runtime.env,
+      stdinIsTTY: runtime.stdinIsTTY,
+      args,
+      readStdin: runtime.readStdin ?? (async () => ""),
+      write: (text) => runtime.stdout(`${text}\n`),
+      ...(runtime.signal === undefined ? {} : { signal: runtime.signal }),
+    });
+    if (result.kind === "ok") {
+      if (result.summary !== undefined && result.summary !== "") runtime.stdout(`${result.summary}\n`);
+      return EXIT_OK;
+    }
+    if (result.kind === "usage") {
+      runtime.stderr(`${result.message}\n`);
+      return EXIT_USAGE;
+    }
+    runtime.stderr(`${renderBlockers(result.blockers)}\n`);
+    return EXIT_POLICY;
+  } catch (error) {
+    if (error instanceof CliInterruption) {
+      runtime.stderr(`${error.message}\n`);
+      return EXIT_INTERRUPTED;
+    }
+    if (error instanceof BlockedError) {
+      runtime.stderr(`${renderBlockers(error.blockers)}\n`);
+      return EXIT_POLICY;
+    }
+    const blocker = createInternalErrorBlocker({
+      source: { kind: "command", id: descriptor.sourceId },
+      error,
+      reproduce: ["delivery-harness", descriptor.name],
+    });
+    runtime.stderr(`${renderBlockers([blocker])}\n`);
+    return EXIT_POLICY;
+  }
+}
+
+async function runConfiguredCommand(
+  descriptor: CommandDescriptor,
+  args: readonly string[],
+  runtime: CliRuntime,
+  observeSuccess: (result: Extract<CommandResult, { kind: "ok" }>) => void,
+  observation?: CommandObservation,
+): Promise<number> {
   const loadConfig = runtime.loadConfig ?? importHarnessConfig;
   const artifacts = runtime.artifacts ?? createArtifactsPort();
 
@@ -268,21 +491,89 @@ export async function runCliBoundary(
       return wiringPromise;
     };
 
+    if (observation?.needsCandidate) {
+      try {
+        const capture = await (await wire()).captureCandidate();
+        if (capture.ok) await observation.start(capture.candidate.treeSha);
+      } catch { /* Missing candidate observations never block execution. */ }
+    }
     const context: CommandContext = {
       rootDir: runtime.cwd,
       config,
+      ...(runtime.policyBinding === undefined ? {} : { policyBinding: runtime.policyBinding }),
       env: runtime.env,
       stdinIsTTY: runtime.stdinIsTTY,
       stdoutIsTTY: runtime.stdoutIsTTY,
       args,
       wire,
+      readStdin: runtime.readStdin ?? (async () => ""),
       artifacts,
+      ...(runtime.signal === undefined ? {} : { signal: runtime.signal }),
       // The waiver prompt is offered only under a real TTY. A non-interactive
       // invocation never prompts — it blocks — no matter what the run wired.
       ...(runtime.stdinIsTTY && runtime.stdoutIsTTY && runtime.promptForWaiver !== undefined
-        ? { promptForWaiver: runtime.promptForWaiver }
+        ? { promptForWaiver: observation?.prompt(runtime.promptForWaiver) ?? runtime.promptForWaiver }
         : {}),
       ...(runtime.liveResults === undefined ? {} : { liveResults: runtime.liveResults }),
+      invokeProvider: async ({ providerId, payload, requiresEvidence }) => {
+        const provider = config.providers.find((registration) => registration.id === providerId);
+        if (provider?.command === undefined) return undefined;
+        const command = provider.command;
+        const requestId = randomUUID();
+        const allocation = await artifacts.allocateRunRoot({ providerId, runId: requestId });
+        if (!allocation.ok) {
+          throw new BlockedError([
+            commandBlocker({
+              code: "provider_rail_run_root_refused",
+              sourceId: "delivery-harness.cli.provider-rails",
+              summary: "The provider run root could not be allocated.",
+              details: `${providerId}/${requestId}: ${allocation.reason}`,
+              remediations: [
+                {
+                  id: "check-provider-identity",
+                  kind: "code_change",
+                  summary: "Correct the provider id or restore the harness run-root location, then retry.",
+                },
+              ],
+            }),
+          ]);
+        }
+        const wiring = await wire();
+        const interruptController = runtime.signal === undefined ? new AbortController() : undefined;
+        const onInterrupt = (): void => interruptController?.abort();
+        if (interruptController !== undefined) process.once("SIGINT", onInterrupt);
+        try {
+          return await invokeProviderRail(
+            {
+              providerId,
+              requestId,
+              idempotencyKey: randomUUID(),
+              payload: { ...payload, runId: requestId, runRoot: allocation.runRoot.path },
+              requiresEvidence,
+            },
+            {
+              open: () =>
+                runtime.openProviderRail === undefined
+                  ? openProviderRailProcess({ command, cwd: runtime.cwd, env: { ...runtime.env } })
+                  : runtime.openProviderRail({ providerId, command, cwd: runtime.cwd, env: runtime.env }),
+              publishManifest: (manifestPath) =>
+                submitManifest(
+                  { rootDir: runtime.cwd, config, manifestPath },
+                  {
+                    captureCandidate: wiring.captureCandidate,
+                    artifacts,
+                    expectedProviderAttempt: { providerId, runId: requestId, runRootPath: allocation.runRoot.path },
+                    ...wiring.storageOptions,
+                  },
+                ),
+              signal: runtime.signal ?? interruptController?.signal,
+              cancellationId: randomUUID(),
+            },
+          );
+        } finally {
+          if (interruptController !== undefined) process.off("SIGINT", onInterrupt);
+        }
+      },
       write: (text) => runtime.stdout(`${text}\n`),
       classifyContext: () =>
         classifyExecutionContext({
@@ -294,7 +585,9 @@ export async function runCliBoundary(
     };
 
     const result = await descriptor.run(context);
+    if (runtime.signal?.aborted) throw new CliInterruption();
     if (result.kind === "ok") {
+      observeSuccess(result);
       if (result.summary !== undefined && result.summary !== "") runtime.stdout(`${result.summary}\n`);
       return EXIT_OK;
     }

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) {