@agent-delivery-harness/cli 0.2.0 → 0.7.3

package/src/commands/gate.ts

@@ -1,3 +1,7 @@
+import { ScopedChecks } from "../scoped-checks.ts";
+import { CheckSnapshotError } from "../check-snapshot.ts";
+import { commandBlocker } from "../boundary.ts";
+import { runDeclaredCheck } from "../declared-checks.ts";
 /**
  * `gate` — evaluate the delivery gate and, under a TTY, offer a scoped waiver.
  *
@@ -9,8 +13,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
@@ -18,10 +23,15 @@ import { CliInterruption, type CommandContext, type CommandDescriptor, type Comm
  * through the same admission adapter. Configs without provider commands take
  * the pre-existing path unchanged.
  */
-export async function runProviderBackedAdmission(
+async function providerAdmission(
   context: CommandContext,
   options: { readonly allowPrompt: boolean; readonly includeInjectedLiveResults: boolean },
-): Promise<AdmissionResult> {
+  session?: ScopedChecks,
+): Promise<AdmissionResult & { readonly observedLiveResults?: readonly LiveProviderResult[] }> {
+  const admit = async (input: Parameters<typeof runAdmission>[0], options: Parameters<typeof runAdmission>[1]) => runAdmission(input, { ...options, ...(session ? { scopedPlan: await session.plan(), readOutput: session.readOutput } : {}) });
+  if (session) {
+    await session.fenceNonReusable(context.config.providers.filter(p => p.check?.scope).map(p => p.id));
+  }
   const wiring = await context.wire();
   const admissionOptions = {
     captureCandidate: wiring.captureCandidate,
@@ -39,14 +49,15 @@ export async function runProviderBackedAdmission(
     ...(options.allowPrompt && context.promptForWaiver !== undefined ? { promptForWaiver: context.promptForWaiver } : {}),
   };
 
-  if (!context.config.providers.some((provider) => provider.command !== undefined)) {
-    return runAdmission(input, finalAdmissionOptions);
+  if (!context.config.providers.some((provider) => provider.command !== undefined || provider.check !== undefined)) {
+    return admit(input, finalAdmissionOptions);
   }
 
   const liveResults: LiveProviderResult[] = options.includeInjectedLiveResults ? [...(context.liveResults ?? [])] : [];
   const attempted = new Set<string>();
   const attemptBlockers: Blocker[] = [];
-  let admission = await runAdmission(input, admissionOptions);
+  let admission = await admit(input, admissionOptions);
+  await session?.explainReuse((admission.decision?.resolutions ?? []).flatMap(r => r.kind === "satisfied_evidence" ? [r.providerId] : []));
 
   while (!admission.admitted && admission.decision !== undefined && admission.candidate !== undefined) {
     const requested = new Map<string, { obligationIds: string[]; requiresEvidence: boolean; needsLiveResult: boolean }>();
@@ -58,7 +69,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 +85,18 @@ 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) {
+      if (registration.check.scope && session) {
+        try { await session.execute(registration, request.obligationIds); }
+        catch (error) {
+          if (!(error instanceof CheckSnapshotError)) throw error;
+          attemptBlockers.push(commandBlocker({ code: error.code, sourceId: "delivery-harness.cli.gate", summary: error.message, remediations: [{ id: "repair-scoped-check", kind: "manual_action", summary: "Repair the declared scoped check or its execution profile and run the gate again." }] }));
+        }
+      } else attemptBlockers.push(...await runDeclaredCheck(context, registration, request.obligationIds, admission.candidate));
+      admission = await admit({ ...input, ...(liveResults.length === 0 ? {} : { liveResults }) }, admissionOptions);
+      continue;
+    }
     const result = await context.invokeProvider?.({
       providerId,
       requiresEvidence: request.requiresEvidence,
@@ -94,27 +118,45 @@ export async function runProviderBackedAdmission(
       liveResults.push(result.liveResult);
     }
 
-    admission = await runAdmission(
+    admission = await admit(
       { ...input, ...(liveResults.length === 0 ? {} : { liveResults }) },
       admissionOptions,
     );
   }
 
-  if (admission.admitted) return admission;
-  const final = await runAdmission(
+  if (admission.admitted) return { ...admission, observedLiveResults: liveResults };
+  const final = await admit(
     { ...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 async function runProviderBackedAdmission(context: CommandContext, options: { readonly allowPrompt: boolean; readonly includeInjectedLiveResults: boolean }): Promise<AdmissionResult & { readonly observedLiveResults?: readonly LiveProviderResult[] }> {
+  let session: ScopedChecks | undefined;
+  try {
+    if (context.config.providers.some(p => p.check?.scope)) {
+      const capture = await (await context.wire()).captureCandidate();
+      if (capture.ok) session = await ScopedChecks.create(context, capture.candidate);
+    }
+    return await providerAdmission(context, options, session);
+  } finally { await session?.cleanup(); }
 }
 
 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 +165,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

@@ -35,6 +35,7 @@ const SOURCE_ID = "delivery-harness.cli.managed";
 /** Every operation this command answers, in the order its usage lists them. */
 const MANAGED_OPERATIONS: readonly string[] = Object.freeze([
   "status",
+  "deliveries",
   "next",
   "operations",
   "blockers",
@@ -98,21 +99,28 @@ interface ResolvedManaged {
   readonly fence: number | undefined;
 }
 
+interface ResolvedInstallation {
+  readonly facade: ManagedDeliveryFacade;
+  readonly namespace: string;
+  /** Every delivery this installation registered, sorted. */
+  readonly deliveries: readonly string[];
+  /** Those whose journal has not committed a transition into a terminal state. */
+  readonly active: readonly string[];
+}
+
 /**
- * Resolves the delivery this invocation addresses.
+ * Resolves the INSTALLATION this invocation runs against, without resolving a
+ * delivery.
  *
- * `requested` exists for the retention operations alone. The skeleton's rule —
- * one delivery in flight per repository — is right for every checkpoint
- * operation, but it makes the retention lane unusable the moment a repository
- * has finished more than one delivery: `active[0] ?? deliveries.at(-1)` then
- * addresses only the newest, and every earlier terminal delivery's durable
- * detail becomes unreachable from the CLI even though the facade can export and
- * delete it. Naming one explicitly is the whole remedy, and it is deliberately
- * NOT offered to the checkpoint operations: those bind an invocation fence
- * derived from the worktree, and a delivery named by flag would not be the one
- * that worktree is bound to.
+ * WHY THE SPLIT EXISTS. Delivery resolution refuses when a repository has zero
+ * registered deliveries or more than one in flight — correct for every
+ * checkpoint operation, which drives exactly one. But those are precisely the
+ * situations the installation-scoped listing exists to report, so a listing
+ * built on top of delivery resolution would refuse in the two cases it is for.
+ * Everything above delivery selection is shared and lives here; selection and
+ * the fence stay below.
  */
-async function resolveManaged(context: CommandContext, requested?: string): Promise<ResolvedManaged | CommandResult> {
+async function resolveInstallation(context: CommandContext): Promise<ResolvedInstallation | CommandResult> {
   const common = await gitCommonDir(context.rootDir);
   if (common === undefined) {
     return blocked("not_a_repository", "The working directory is not a git repository.", "Run from the delivery worktree.");
@@ -130,7 +138,15 @@ async function resolveManaged(context: CommandContext, requested?: string): Prom
   }
   let deliveries: string[];
   try {
-    deliveries = (await readdir(path.join(namespace, "deliveries"))).sort();
+    // Directories only, the same rule the facade's listing applies. A stray
+    // FILE in the namespace is not a delivery, and counting one as in flight is
+    // the two-surfaces-contradict state the listing exists to prevent: `status`
+    // would refuse with "several deliveries are in flight" while `deliveries`
+    // named it in neither list, leaving no id to reconcile the two counts by.
+    deliveries = (await readdir(path.join(namespace, "deliveries"), { withFileTypes: true }))
+      .filter((candidate) => candidate.isDirectory())
+      .map((candidate) => candidate.name)
+      .sort();
   } catch {
     deliveries = [];
   }
@@ -161,26 +177,6 @@ async function resolveManaged(context: CommandContext, requested?: string): Prom
       active.push(candidate);
     }
   }
-  let deliveryId: string | undefined;
-  if (requested !== undefined) {
-    if (!deliveries.includes(requested)) {
-      return blocked(
-        "delivery_unresolved",
-        `No delivery ${requested} is registered for this repository.`,
-        "Name a delivery this repository registered; `managed status` reports the current one.",
-      );
-    }
-    deliveryId = requested;
-  } else {
-    deliveryId = active[0] ?? deliveries[deliveries.length - 1];
-    if (deliveryId === undefined || active.length > 1) {
-      return blocked(
-        "delivery_unresolved",
-        active.length > 1 ? "Several deliveries are in flight; the skeleton drives one." : "No registered delivery exists.",
-        "Register exactly one delivery for this repository, or name one with --delivery for export and delete.",
-      );
-    }
-  }
   let policyBinding: CompiledAdopterPolicyBinding | undefined = context.policyBinding;
   if (policyBinding === undefined) {
     try {
@@ -206,6 +202,48 @@ async function resolveManaged(context: CommandContext, requested?: string): Prom
     installation: { installationPath: pointer.installationPath, receiptDir: pointer.receiptDir },
     hostVersion: pointer.hostVersion,
   });
+  return { facade, namespace, deliveries, active };
+}
+
+/**
+ * Resolves the delivery this invocation addresses.
+ *
+ * `requested` exists for the retention operations alone. The skeleton's rule —
+ * one delivery in flight per repository — is right for every checkpoint
+ * operation, but it makes the retention lane unusable the moment a repository
+ * has finished more than one delivery: `active[0] ?? deliveries.at(-1)` then
+ * addresses only the newest, and every earlier terminal delivery's durable
+ * detail becomes unreachable from the CLI even though the facade can export and
+ * delete it. Naming one explicitly is the whole remedy, and it is deliberately
+ * NOT offered to the checkpoint operations: those bind an invocation fence
+ * derived from the worktree, and a delivery named by flag would not be the one
+ * that worktree is bound to.
+ */
+async function resolveManaged(context: CommandContext, requested?: string): Promise<ResolvedManaged | CommandResult> {
+  const installation = await resolveInstallation(context);
+  if (isCommandResult(installation)) return installation;
+  const { facade, namespace, deliveries, active } = installation;
+
+  let deliveryId: string | undefined;
+  if (requested !== undefined) {
+    if (!deliveries.includes(requested)) {
+      return blocked(
+        "delivery_unresolved",
+        `No delivery ${requested} is registered for this repository.`,
+        "Name a delivery this repository registered; `managed status` reports the current one.",
+      );
+    }
+    deliveryId = requested;
+  } else {
+    deliveryId = active[0] ?? deliveries[deliveries.length - 1];
+    if (deliveryId === undefined || active.length > 1) {
+      return blocked(
+        "delivery_unresolved",
+        active.length > 1 ? "Several deliveries are in flight; the skeleton drives one." : "No registered delivery exists.",
+        "Register exactly one delivery for this repository, or name one with --delivery for export and delete, or list them all with `managed deliveries`.",
+      );
+    }
+  }
 
   let fence: number | undefined;
   try {
@@ -222,12 +260,13 @@ async function resolveManaged(context: CommandContext, requested?: string): Prom
   return { facade, deliveryId, fence };
 }
 
-const isCommandResult = (value: ResolvedManaged | CommandResult): value is CommandResult => "kind" in value;
+const isCommandResult = (value: ResolvedManaged | ResolvedInstallation | CommandResult): value is CommandResult => "kind" in value;
 
 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) {
@@ -254,6 +293,38 @@ export const managedCommand: CommandDescriptor = {
       return { kind: "ok", summary: `${FACADE_OPERATIONS.length} facade operations` };
     }
 
+    // The installation-scoped listing mode of the status surface. It answers
+    // HERE, above delivery resolution, for the same reason `operations` does:
+    // the two situations it exists to report — no delivery registered, and
+    // several in flight — are exactly the two that delivery resolution
+    // refuses, so a listing resolved through it would be unavailable whenever
+    // it had something to say. It names no delivery and binds no fence.
+    //
+    // It still requires an INSTALLATION. A repository with no product
+    // namespace pointer has registered nothing at all, and there is then no
+    // installation to scope a listing to — which is a different answer from an
+    // installation whose registered deliveries happen to number zero, and the
+    // facade reports that one as an empty listing.
+    if (operation === "deliveries") {
+      const installation = await resolveInstallation(context);
+      if (isCommandResult(installation)) return installation;
+      const listing = await installation.facade.listDeliveries({ observedAt: nowInstant() });
+      if (!listing.ok) return { kind: "blocked", blockers: [...listing.blockers] };
+      context.write(`${JSON.stringify(listing.deliveries, null, 2)}\n`);
+      // An unreadable delivery is NAMED, not dropped. Delivery resolution below
+      // counts the same directory as registered, so a listing that quietly
+      // omitted it would leave `managed status` saying several deliveries are in
+      // flight while the surface it points at shows fewer — with no id to
+      // reconcile the two by. The id here is enough to ask `managed status
+      // --delivery <id>` and get the refusal that says what is wrong.
+      const unreadable =
+        listing.unreadable.length === 0 ? "" : `; ${listing.unreadable.length} unreadable (${listing.unreadable.join(", ")})`;
+      return {
+        kind: "ok",
+        summary: `${listing.deliveries.length} delivery(ies) registered for this installation${unreadable}`,
+      };
+    }
+
     // Only the retention operations may name a delivery; everything else binds
     // the fence of the worktree it runs in.
     const RETENTION_OPERATIONS = ["export", "delete"];

package/src/commands/prepare.ts

@@ -1,3 +1,5 @@
+import { ScopedChecks } from "../scoped-checks.ts";
+import { CheckSnapshotError } from "../check-snapshot.ts";
 /**
  * `prepare` — capture the candidate and publish its preparation receipt.
  *
@@ -5,34 +7,158 @@
  * admission. Capturing an unprepared tree (dirty or with untracked files) is a
  * typed block, not a silent skip.
  */
-import { publishPreparationReceipt } from "@agent-delivery-harness/kernel";
-import type { CommandContext, CommandDescriptor, CommandResult } from "../boundary.ts";
+import {
+  classifyCandidateDrift,
+  computePreparationFingerprint,
+  computeDeliverableIdentity,
+  evaluatePreparationReceipt,
+  createBlocker,
+  createExecPort,
+  invalidatePreparationReceipt,
+  revokePreparationAttempt,
+  publishPreparationReceipt,
+  type RunPreparationObservation,
+} from "@agent-delivery-harness/kernel";
+import { CliInterruption, type CommandContext, type CommandDescriptor, type CommandResult } from "../boundary.ts";
+
+const USAGE = "Usage: delivery-harness prepare [--refresh-record-neutral]";
 
 export const prepareCommand: CommandDescriptor = {
   name: "prepare",
   sourceId: "delivery-harness.cli.prepare",
-  summary: "Capture the candidate and publish its preparation receipt.",
+  summary: "Run preparation checks; --refresh-record-neutral permits proven artifact-only receipt refresh.",
+  // The text prepare has always answered `--help` with, unchanged; the
+  // boundary is what prints it now, for every command rather than this one.
+  usage: `${USAGE}\nOrdinary prepare always runs mechanical checks. The refresh flag reuses prior success only when strict validation, policy, wiring and base are unchanged; otherwise it runs the checks.`,
   async run(context: CommandContext): Promise<CommandResult> {
+    if (context.args.length > 1 || (context.args.length === 1 && context.args[0] !== "--refresh-record-neutral")) {
+      return { kind: "usage", message: USAGE };
+    }
+    if (context.config.providers.some(p => p.check?.scope) && !context.config.scopedExecution) throw new CheckSnapshotError("scoped_executor_required", "Scoped execution profiles are required before preparation commands may run.");
+    let scoped: ScopedChecks | undefined;
+    const refreshRecordNeutral = context.args[0] === "--refresh-record-neutral";
     const wiring = await context.wire();
-    const capture = await wiring.captureCandidate();
-    if (!capture.ok) {
-      return { kind: "blocked", blockers: [...capture.blockers] };
+    let retainedAttemptId: string | undefined;
+    let ownedAttemptId: string | undefined;
+    let refreshed = false;
+    try {
+      let capture: Awaited<ReturnType<typeof wiring.captureCandidate>>;
+      // A refresh continues the successful attempt it evaluated. It cannot
+      // transfer that success to new ownership after another attempt revokes it.
+      let reusableFingerprint: string | undefined;
+      let attemptId: string;
+      try {
+        if (context.config.scopedExecution?.repairCommands?.length) {
+          ownedAttemptId = await invalidatePreparationReceipt(context.rootDir, context.config, wiring.storageOptions);
+          const beforeRepair = await computePreparationFingerprint(context.rootDir, context.config, wiring.storageOptions);
+          for (const repair of context.config.scopedExecution.repairCommands) {
+            context.write(`repairing ${repair.id}`);
+            const result = await createExecPort().run({ command: repair.command[0], args: repair.command.slice(1), cwd: context.rootDir,
+              env: Object.fromEntries(Object.entries(context.env).filter((e): e is [string, string] => e[1] !== undefined)), timeoutMs: repair.timeoutMs, maxBuffer: 1024 * 1024, ...(context.signal ? { signal: context.signal } : {}) });
+            if (context.signal?.aborted) throw new CliInterruption();
+            if (result.code !== 0) throw new CheckSnapshotError("preparation_repair_failed", `Source repair ${repair.id} failed; fix it and prepare again.`);
+          }
+          if (beforeRepair !== await computePreparationFingerprint(context.rootDir, context.config, wiring.storageOptions)) throw new CheckSnapshotError("preparation_candidate_changed", "Repair changed preparation wiring; reload the configuration and prepare again.");
+        }
+        capture = await wiring.captureCandidate();
+        if (capture.ok && refreshRecordNeutral) {
+          const previous = await evaluatePreparationReceipt(context.rootDir,
+            { config: context.config, candidate: capture.candidate }, { ...wiring.storageOptions, allowValidationEquivalent: true });
+          if (previous.prepared && previous.receipt.attemptId !== undefined) {
+            reusableFingerprint = previous.receipt.preparationFingerprint;
+            retainedAttemptId = previous.receipt.attemptId;
+          }
+        }
+      } finally {
+        attemptId = retainedAttemptId ?? ownedAttemptId ?? await invalidatePreparationReceipt(context.rootDir, context.config, wiring.storageOptions);
+        ownedAttemptId = attemptId;
+      }
+      if (!capture.ok) {
+        return { kind: "blocked", blockers: [...capture.blockers] };
+      }
+      const fingerprint = await computePreparationFingerprint(context.rootDir, context.config, wiring.storageOptions);
+      const reusable = reusableFingerprint === fingerprint;
+      const preparation: RunPreparationObservation = reusable
+        ? { checks: "reused", reason: "validation-equivalent" }
+        : { checks: "executed", reason: !refreshRecordNeutral ? "ordinary"
+          : retainedAttemptId === undefined ? "receipt-not-reusable" : "preparation-fingerprint-changed" };
+      if (!reusable && retainedAttemptId !== undefined) {
+        attemptId = await invalidatePreparationReceipt(context.rootDir, context.config, wiring.storageOptions);
+        ownedAttemptId = attemptId;
+        retainedAttemptId = undefined;
+      }
+      let validationDigest = await computeDeliverableIdentity({ rootDir: context.rootDir, treeSha: capture.candidate.treeSha,
+        config: { ...context.config, computingIdentityVersion: "validation-tree/v1", reviewNeutral: context.config.recordNeutral } });
+      if (reusable) context.write("reusing preparation checks: strict validation projection, base, policy and wiring unchanged");
+      const exec = createExecPort();
+      const env = Object.fromEntries(Object.entries(context.env).filter((entry): entry is [string, string] => entry[1] !== undefined));
+      for (const check of reusable ? [] : context.config.preparationCommands ?? []) {
+        context.write(`preparing ${check.id}`);
+        const result = await exec.run({
+          command: check.command[0], args: check.command.slice(1), cwd: context.rootDir,
+          env, timeoutMs: check.timeoutMs, maxBuffer: 1024 * 1024,
+          ...(context.signal === undefined ? {} : { signal: context.signal }),
+        });
+        if (result.code !== 0 || context.signal?.aborted) {
+          return {
+            kind: "blocked",
+            blockers: [createBlocker({
+              code: "preparation_command_failed", source: { kind: "command", id: "delivery-harness.cli.prepare" },
+              summary: `Preparation check ${check.id} failed; no receipt was published.`,
+              details: `exit ${result.code}${result.errorCode === undefined ? "" : ` (${result.errorCode})`}\n${`${result.stdout}\n${result.stderr}`.slice(-4000)}`,
+              remediations: [{ id: "repair-preparation-check", kind: "manual_action", summary: `Fix ${check.id}, then run prepare again.` }],
+            })],
+          };
+        }
+      }
+      if (context.signal?.aborted) throw new CliInterruption();
+      const finalCapture = await wiring.captureCandidate();
+      if (!finalCapture.ok) return { kind: "blocked", blockers: [...finalCapture.blockers] };
+      const after = finalCapture.candidate;
+      if (classifyCandidateDrift(capture.candidate, after).length > 0 ||
+          capture.candidate.headSha !== after.headSha || capture.candidate.mode !== after.mode ||
+          fingerprint !== await computePreparationFingerprint(context.rootDir, context.config, wiring.storageOptions)) {
+        return {
+          kind: "blocked",
+          blockers: [createBlocker({
+            code: "preparation_candidate_changed", source: { kind: "command", id: "delivery-harness.cli.prepare" },
+            summary: "The candidate, base, or preparation wiring changed while checks ran; no receipt was published.",
+            remediations: [{ id: "prepare-stable-candidate", kind: "manual_action", summary: "Commit any intended changes and prepare the stable candidate again." }],
+          })],
+        };
+      }
+      if (context.config.scopedExecution) {
+        capture = finalCapture;
+        validationDigest = await computeDeliverableIdentity({ rootDir: context.rootDir, treeSha: capture.candidate.treeSha, config: { ...context.config, computingIdentityVersion: "validation-tree/v1", reviewNeutral: context.config.recordNeutral } });
+        scoped = await ScopedChecks.create(context, capture.candidate);
+        await scoped?.satisfyMechanical();
+      }
+      const published = await publishPreparationReceipt(
+        context.rootDir,
+        { config: context.config, candidate: capture.candidate, attemptId, validationDigest },
+        wiring.storageOptions,
+      );
+      if (context.signal?.aborted) throw new CliInterruption();
+      await scoped?.submitMechanical();
+      await scoped?.cleanup();
+      refreshed = true;
+      // The labelled line exists so a reader — an operator or a review round
+      // about to bind itself to this candidate — has one unambiguous token to
+      // copy. It is the same value the record carries as `treeSha` and the same
+      // value `review-context` reports as `candidate tree`.
+      return {
+        kind: "ok",
+        preparation,
+        summary: [
+          `prepared ${context.config.gateId}: tree ${capture.candidate.treeSha} (${capture.candidate.mode}); receipt ${published.path}`,
+          `  treeSha ${capture.candidate.treeSha}`,
+        ].join("\n"),
+      };
+    } finally {
+      try { await scoped?.cleanup(); }
+      finally {
+        if (ownedAttemptId !== undefined && !refreshed) await revokePreparationAttempt(context.rootDir, context.config, ownedAttemptId, wiring.storageOptions);
+      }
     }
-    const published = await publishPreparationReceipt(
-      context.rootDir,
-      { config: context.config, candidate: capture.candidate },
-      wiring.storageOptions,
-    );
-    // The labelled line exists so a reader — an operator or a review round
-    // about to bind itself to this candidate — has one unambiguous token to
-    // copy. It is the same value the record carries as `treeSha` and the same
-    // value `review-context` reports as `candidate tree`.
-    return {
-      kind: "ok",
-      summary: [
-        `prepared ${context.config.gateId}: tree ${capture.candidate.treeSha} (${capture.candidate.mode}); receipt ${published.path}`,
-        `  treeSha ${capture.candidate.treeSha}`,
-      ].join("\n"),
-    };
   },
 };