@agent-delivery-harness/cli 0.5.0 → 0.7.4

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@agent-delivery-harness/cli",
-  "version": "0.5.0",
+  "version": "0.7.4",
   "type": "module",
   "description": "Delivery harness CLI: admit, prepare, review-context, submit-evidence, gate, record, verify, check",
   "license": "FSL-1.1-ALv2",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/kwam1na/agent-delivery-harness.git",
+    "url": "git+https://github.com/v26-technologies/agent-delivery-harness.git",
     "directory": "packages/cli"
   },
   "engines": {
     "node": ">=22.6.0"
   },
   "dependencies": {
-    "@agent-delivery-harness/kernel": "0.5.0"
+    "@agent-delivery-harness/kernel": "0.7.4"
   },
   "exports": {
     ".": "./src/index.ts"

package/src/boundary.ts

@@ -1,3 +1,5 @@
+import { CheckSnapshotError } from "./check-snapshot.ts";
+import { captureScopedCandidate } from "./scoped-candidate.ts";
 /**
  * The one boundary every CLI command runs behind.
  *
@@ -307,12 +309,13 @@ export async function importHarnessConfig(rootDir: string): Promise<HarnessConfi
 export async function wireRepo(rootDir: string, config: HarnessConfig): Promise<RepoWiring> {
   const storageOptions = { storageNamespace: config.storageNamespace };
   const storage = await resolveRecordStorage(rootDir, storageOptions);
-  const captureCandidate = createCandidateCapture({
+  const captureOptions = {
     rootDir,
     config,
     workspaceId: storage.workspaceId,
     computeIdentity: withDeliverableIdentity(),
-  });
+  };
+  const captureCandidate = config.scopedExecution ? () => captureScopedCandidate(captureOptions) : createCandidateCapture(captureOptions);
   const projectActivation = (candidate: CapturedCandidate): Promise<ReviewActivationProjection> =>
     evaluateCandidateActivation({ rootDir, candidate, config });
   return { rootDir, workspaceId: storage.workspaceId, captureCandidate, projectActivation, storageOptions };
@@ -458,6 +461,7 @@ async function runConfigFreeCommand(
       runtime.stderr(`${error.message}\n`);
       return EXIT_INTERRUPTED;
     }
+    if (error instanceof CheckSnapshotError) error = new BlockedError([commandBlocker({ code: error.code, sourceId: "delivery-harness.cli.scoped-check", summary: error.message, remediations: [{ id: "repair-scoped-execution", kind: "manual_action", summary: "Repair the scoped execution inputs or profile, prepare and retry." }] })]);
     if (error instanceof BlockedError) {
       runtime.stderr(`${renderBlockers(error.blockers)}\n`);
       return EXIT_POLICY;
@@ -602,6 +606,7 @@ async function runConfiguredCommand(
       runtime.stderr(`${error.message}\n`);
       return EXIT_INTERRUPTED;
     }
+    if (error instanceof CheckSnapshotError) error = new BlockedError([commandBlocker({ code: error.code, sourceId: "delivery-harness.cli.scoped-check", summary: error.message, remediations: [{ id: "repair-scoped-execution", kind: "manual_action", summary: "Repair the scoped execution inputs or profile, prepare and retry." }] })]);
     if (error instanceof BlockedError) {
       runtime.stderr(`${renderBlockers(error.blockers)}\n`);
       return EXIT_POLICY;

package/src/check-snapshot.ts

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

package/src/commands/gate.ts

@@ -1,3 +1,6 @@
+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.
@@ -20,10 +23,15 @@ import { oneLine } from "../run-surface.ts";
  * 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 },
+  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,
@@ -42,13 +50,14 @@ export async function runProviderBackedAdmission(
   };
 
   if (!context.config.providers.some((provider) => provider.command !== undefined || provider.check !== undefined)) {
-    return runAdmission(input, finalAdmissionOptions);
+    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 }>();
@@ -78,8 +87,14 @@ export async function runProviderBackedAdmission(
     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);
+      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?.({
@@ -103,14 +118,14 @@ 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, observedLiveResults: liveResults };
-  const final = await runAdmission(
+  const final = await admit(
     { ...input, ...(liveResults.length === 0 ? {} : { liveResults }) },
     finalAdmissionOptions,
   );
@@ -119,6 +134,17 @@ export async function runProviderBackedAdmission(
     : { ...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",

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,7 +260,7 @@ 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",
@@ -255,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.
  *
@@ -32,6 +34,8 @@ export const prepareCommand: CommandDescriptor = {
     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();
     let retainedAttemptId: string | undefined;
@@ -44,6 +48,18 @@ export const prepareCommand: CommandDescriptor = {
       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,
@@ -54,7 +70,7 @@ export const prepareCommand: CommandDescriptor = {
           }
         }
       } finally {
-        attemptId = retainedAttemptId ?? await invalidatePreparationReceipt(context.rootDir, context.config, wiring.storageOptions);
+        attemptId = retainedAttemptId ?? ownedAttemptId ?? await invalidatePreparationReceipt(context.rootDir, context.config, wiring.storageOptions);
         ownedAttemptId = attemptId;
       }
       if (!capture.ok) {
@@ -71,7 +87,7 @@ export const prepareCommand: CommandDescriptor = {
         ownedAttemptId = attemptId;
         retainedAttemptId = undefined;
       }
-      const validationDigest = await computeDeliverableIdentity({ rootDir: context.rootDir, treeSha: capture.candidate.treeSha,
+      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();
@@ -111,12 +127,20 @@ export const prepareCommand: CommandDescriptor = {
           })],
         };
       }
+      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
@@ -131,8 +155,9 @@ export const prepareCommand: CommandDescriptor = {
         ].join("\n"),
       };
     } finally {
-      if (ownedAttemptId !== undefined && !refreshed) {
-        await revokePreparationAttempt(context.rootDir, context.config, ownedAttemptId, wiring.storageOptions);
+      try { await scoped?.cleanup(); }
+      finally {
+        if (ownedAttemptId !== undefined && !refreshed) await revokePreparationAttempt(context.rootDir, context.config, ownedAttemptId, wiring.storageOptions);
       }
     }
   },

package/src/commands/record.ts

@@ -24,7 +24,7 @@ import {
 import path from "node:path";
 import { commandBlocker } from "../boundary.ts";
 import type { CommandContext, CommandDescriptor, CommandResult } from "../boundary.ts";
-import { oneLine } from "../run-surface.ts";
+import { oneLine, resolveRunSpan } from "../run-surface.ts";
 import { applyDeliveryRecordRetention } from "../record-retention.ts";
 import { runProviderBackedAdmission } from "./gate.ts";
 
@@ -127,7 +127,16 @@ export const recordCommand: CommandDescriptor = {
       await computePreparationFingerprint(context.rootDir, context.config));
     const compiledPolicy = context.policyBinding?.compiledPolicy ??
       await readCompiledRepositoryPolicy(await candidateTreeEvidenceReader(context.rootDir, recheck.candidate.treeSha));
+    // The delivery's own span, read off the run journal rather than off a
+    // clock: `startedAt` is the journal's first instant and `endedAt` the last
+    // it had reached by this write, which is the time this delivery had spent
+    // when it recorded. A delivery with no journal records exactly as it always
+    // did — the member is simply absent — because the record is evidence about
+    // a candidate and this is a cycle-time reading beside it, never a condition
+    // on writing one.
+    const runSpan = await resolveRunSpan({ cwd: context.rootDir, treeSha: recheck.candidate.treeSha, allowCurrentRun: true });
     const built = buildDeliveryRecord({ config: context.config, decision, evidenceRecords, context: evidenceContext,
+      ...(runSpan === undefined ? {} : { runSpan: { startedAt: runSpan.startedAt, endedAt: runSpan.endedAt } }),
       ...(compiledPolicy === null ? {} : { compiledPolicy, observedAt }) });
     if (!built.ok) {
       return { kind: "blocked", blockers: [...built.blockers] };