@agent-delivery-harness/cli 0.8.1 → 0.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-delivery-harness/cli",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "type": "module",
   "description": "Delivery harness CLI: admit, prepare, review-context, submit-evidence, gate, record, verify, check",
   "license": "FSL-1.1-ALv2",
@@ -13,7 +13,7 @@
     "node": ">=22.6.0"
   },
   "dependencies": {
-    "@agent-delivery-harness/kernel": "0.8.1"
+    "@agent-delivery-harness/kernel": "0.8.3"
   },
   "exports": {
     ".": "./src/index.ts"

package/src/boundary.ts

@@ -244,6 +244,7 @@ export interface CliRuntime {
     readonly command: readonly [string, ...string[]];
     readonly cwd: string;
     readonly env: EnvSnapshot;
+    readonly inheritDescriptors?: readonly (3 | 4)[];
   }) => Promise<ProviderRailSession>;
 }
 
@@ -533,6 +534,8 @@ async function runConfiguredCommand(
         const provider = config.providers.find((registration) => registration.id === providerId);
         if (provider?.command === undefined) return undefined;
         const command = provider.command;
+        // Only this provider's own declaration reaches its process.
+        const inherited = provider.inheritDescriptors;
         const requestId = randomUUID();
         const allocation = await artifacts.allocateRunRoot({ providerId, runId: requestId });
         if (!allocation.ok) {
@@ -566,10 +569,10 @@ async function runConfiguredCommand(
               requiresEvidence,
             },
             {
-              open: () =>
-                runtime.openProviderRail === undefined
-                  ? openProviderRailProcess({ command, cwd: runtime.cwd, env: { ...runtime.env } })
-                  : runtime.openProviderRail({ providerId, command, cwd: runtime.cwd, env: runtime.env }),
+              // One call, so the test seam is given exactly what the real launch is.
+              open: () => (runtime.openProviderRail ?? openProviderRailProcess)({
+                providerId, command, cwd: runtime.cwd, env: { ...runtime.env }, ...(inherited ? { inheritDescriptors: inherited } : {}),
+              }),
               publishManifest: (manifestPath) =>
                 submitManifest(
                   { rootDir: runtime.cwd, config, manifestPath },

package/src/check-snapshot.ts

@@ -1,6 +1,7 @@
 /** Private execution tree. Never shares writable source, objects, index or dependencies. */
 import { spawn } from "node:child_process";
-import { chmod, lstat, mkdir, mkdtemp, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, mkdtemp, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { candidateTreeSourceReader, capturePhysicalSource, createExecPort, isPhysicalSourceDefinition, physicalSourceOutputOverlap, type CandidateCommandRunner, type PhysicalSourceDefinition, type ExecOutcome } from "@agent-delivery-harness/kernel";
@@ -60,8 +61,80 @@ function phaseMeter(onPhase?: (phase: SnapshotPhase, durationMs: number) => void
     try { return await operation(); } finally { try { onPhase?.(phase, performance.now() - started); } catch { /* Timing cannot change admission. */ } }
   };
 }
+/** Where removed trees wait to be deleted: beside them in the temporary directory, so moving one is a rename on
+ * the same volume. Nothing here is evidence, and nothing reads it. */
+const trash = () => path.join(tmpdir(), `delivery-harness-trash-${process.getuid?.() ?? "user"}`);
+/**
+ * The trash, only when it is this user's own private directory. A temporary directory may be shared, and the
+ * sweep deletes what it lists, so a link or another user's directory at that name is never followed: the
+ * caller removes in place instead.
+ */
+async function ownTrash(create: boolean): Promise<string | undefined> {
+  const dir = trash();
+  try {
+    if (create) await mkdir(dir, { mode: 0o700 }).catch(error => { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; });
+    const found = await lstat(dir);
+    // A link's own mode usually fails the mode test as well; isDirectory() still refuses one made private.
+    return found.isDirectory() && found.uid === process.getuid?.() && (found.mode & 0o077) === 0 ? dir : undefined;
+  } catch { return undefined; }
+}
+/** Deletes `paths` in a process this one does not wait for or outlive the need of. Best effort: whatever a stopped
+ * deletion leaves in the trash, the next session's sweep removes. Batched so no argument list outgrows the host's. */
+function deleteDetached(paths: readonly string[]): void {
+  for (let at = 0; at < paths.length; at += 256) {
+    try {
+      const child = spawn("/bin/rm", ["-rf", "--", ...paths.slice(at, at + 256)], { detached: true, stdio: "ignore" });
+      child.on("error", () => { /* Left for the next sweep. */ });
+      child.unref();
+    } catch { /* Left for the next sweep. */ }
+  }
+}
+/** Whether the process that moved a tree aside may still be deleting it. A reused pid only delays a sweep. */
+function ownerAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return (error as NodeJS.ErrnoException).code === "EPERM"; }
+}
+/** Removes, in the background, what sessions that have ended left in the trash. An entry is named for the process
+ * that moved it there; one whose owner is still alive, this process included, is left to that owner's deletion. */
+export async function sweepRemovedTrees(): Promise<void> {
+  if (process.platform === "win32") return;
+  const dir = await ownTrash(false);
+  if (!dir) return;
+  const entries = await readdir(dir).catch(() => [] as string[]);
+  deleteDetached(entries.filter(entry => {
+    const pid = Number(/^(\d+)-/.exec(entry)?.[1]);
+    return !Number.isSafeInteger(pid) || pid <= 0 || !ownerAlive(pid);
+  }).map(entry => path.join(dir, entry)));
+}
+/**
+ * Takes each owned tree out of its path at once, by renaming it into the trash, and deletes it in a detached
+ * process: a tree with installed dependencies can take ten seconds or more to remove, and the evidence it
+ * produced is already retained. A tree that cannot be moved is removed in place, as before, and only a tree
+ * neither moved nor removed fails the cleanup.
+ */
 async function removeTrees(directories: readonly string[]): Promise<void> {
-  const removed = await Promise.allSettled(directories.map(dir => rm(dir, { recursive: true, force: true })));
+  const moved: string[] = [];
+  const into = process.platform === "win32" ? undefined : await ownTrash(true);
+  const removed = await Promise.allSettled(directories.map(async dir => {
+    if (into) {
+      try {
+        // A rename never copies; on another volume the tree is removed in place instead. The device check only
+        // spares a doomed rename: one across volumes fails with EXDEV and falls through to the same removal.
+        const [from, to] = await Promise.all([stat(path.dirname(dir)), stat(into)]);
+        if (from.dev === to.dev) {
+          const target = path.join(into, `${process.pid}-${randomUUID()}`);
+          await rename(dir, target);
+          moved.push(target);
+          return;
+        }
+      } catch (error) {
+        // Done only when the tree itself is gone, not when the trash went missing under the move.
+        if ((error as NodeJS.ErrnoException).code === "ENOENT" && await lstat(dir).then(() => false, gone => (gone as NodeJS.ErrnoException).code === "ENOENT")) return;
+      }
+    }
+    await rm(dir, { recursive: true, force: true });
+  }));
+  deleteDetached(moved);
   if (removed.some(result => result.status === "rejected")) throw new CheckSnapshotError("check_snapshot_cleanup_failed", "Cannot remove the owned execution snapshot after retaining evidence.");
 }
 /** One copy-on-write clone of a directory tree into a path that must not exist yet. On macOS

package/src/delivery-posture.ts

@@ -6,11 +6,13 @@
  * delivery record and run no obligation, and that outcome is the whole record.
  * It journals no completion: `gate ok` in a run would read as a gate that passed.
  * Under `gate` the command carries on, with output as it would be had nothing
- * been declared. The one exception is a malformed declaration: a repository said
- * something and it didn't take, so its code and reason go to stderr, leaving
- * what a command writes to stdout as it is.
+ * been declared. There are two exceptions, each of which writes its code and
+ * reason to stderr, leaving what a command writes to stdout as it is: a malformed
+ * declaration, where a repository said something and it didn't take, and a
+ * command run from a directory that is not its repository's root, which is the
+ * caller's to fix rather than the base's.
  */
-import { resolveDeliveryPosture } from "@agent-delivery-harness/kernel";
+import { deliveryPostureRefusedOutsideRoot, resolveDeliveryPosture } from "@agent-delivery-harness/kernel";
 import { CliInterruption, type CommandContext, type CommandResult } from "./boundary.ts";
 import { oneLine } from "./run-surface.ts";
 
@@ -34,6 +36,6 @@ export async function focusedOutcome(context: CommandContext): Promise<Extract<C
       ].join("\n"),
     };
   }
-  if (resolved.code === "posture_malformed") context.writeError(`${resolved.code}: ${oneLine(resolved.reason, 512)}`);
+  if (resolved.code === "posture_malformed" || deliveryPostureRefusedOutsideRoot(resolved)) context.writeError(`${resolved.code}: ${oneLine(resolved.reason, 512)}`);
   return undefined;
 }

package/src/fixtures/live-descriptors-parent.ts

@@ -0,0 +1,50 @@
+// V26-3314: run by live-providers.test.ts with a marker pipe on fd 3. Collects
+// live results once with a provider that declares fd 3 and once with one that
+// does not, and prints what each provider held on fd 3 and what its
+// environment said it inherited.
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import adopter from "../../../../harness.config.ts";
+import { captureGitCandidate, channelIdentity, collectLiveProviderResults, computePreparationFingerprint, defineHarnessConfig, evaluateCandidateActivation, INHERITED_DESCRIPTORS_ENV, withDeliverableIdentity } from "@agent-delivery-harness/kernel";
+
+const exec = promisify(execFile);
+const provider = `const fs=require('fs');let held=null;try{held=fs.readFileSync(3,'utf8')}catch{}
+fs.writeFileSync('.git/inherited',JSON.stringify({held,stated:process.env.${INHERITED_DESCRIPTORS_ENV}??null}));
+require('readline').createInterface({input:process.stdin}).on('line',line=>{const m=JSON.parse(line);
+ if(m.kind==='negotiate')console.log(JSON.stringify({kind:'negotiation',outcome:'supported',selectedVersion:'delivery-provider-rails/1',supportedVersions:['delivery-provider-rails/1']}));
+ if(m.kind==='request')console.log(JSON.stringify({kind:'terminal',version:m.version,requestId:m.requestId,sequence:1,summary:'observed',outcome:'success'}));});`;
+
+async function collect(env: NodeJS.ProcessEnv): Promise<unknown[]> {
+  const reports: unknown[] = [];
+  for (const declared of [false, true]) {
+    const dir = await mkdtemp(path.join(tmpdir(), "live-descriptors-"));
+    try {
+      const git = (...args: string[]) => exec("git", args, { cwd: dir });
+      await git("init", "-q"); await git("config", "user.name", "Test"); await git("config", "user.email", "test@example.invalid");
+      await writeFile(path.join(dir, "source.ts"), "export const a=1;"); await writeFile(path.join(dir, "harness.config.ts"), "export default {};");
+      await git("add", "."); await git("-c", "commit.gpgsign=false", "commit", "-qm", "base"); await git("branch", "origin/main");
+      const config = defineHarnessConfig({ ...adopter, preparationCommands: [], preparationWiringPaths: ["harness.config.ts"],
+        providers: [{ id: "live.sensor", findingCodes: [], command: [process.execPath, "-e", provider], ...(declared ? { inheritDescriptors: [3] as const } : {}) }],
+        obligations: [{ ...adopter.obligations[0]!, id: "live.current", freshness: "live", providers: ["live.sensor"], activation: { kind: "always" }, humanWaiverAllowed: false, allowedResolutionKinds: ["satisfied_live_fact", "not_applicable"] }] });
+      const capture = await captureGitCandidate({ rootDir: dir, config, workspaceId: "test-workspace", computeIdentity: withDeliverableIdentity() });
+      if (!capture.ok) throw new Error(JSON.stringify(capture));
+      const result = await collectLiveProviderResults({ rootDir: dir, config, candidate: capture.candidate,
+        projection: await evaluateCandidateActivation({ rootDir: dir, config, candidate: capture.candidate }),
+        evidenceContext: { preparationFingerprint: await computePreparationFingerprint(dir, config), release: null },
+        env: { ...env, [INHERITED_DESCRIPTORS_ENV]: `3:${channelIdentity(3)}` } });
+      reports.push({ status: result.liveResults[0]?.status ?? null, ...JSON.parse(await readFile(path.join(dir, ".git/inherited"), "utf8")) });
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }
+  return reports;
+}
+
+async function main(): Promise<void> {
+  console.log(JSON.stringify(await collect(process.env)));
+}
+
+await main();

package/src/scoped-checks.ts

@@ -1,19 +1,34 @@
 /** Invocation-scoped execution coordinator; durable truth remains per-check evidence. */
 import { randomUUID } from "node:crypto";
-import { access, mkdir, readFile, realpath, rm, stat } from "node:fs/promises";
+import { access, mkdir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { deliveryRecordPathFor, recordOutputProvider, computeDeliverableIdentity, capturePhysicalSource, captureCheckBindings, captureCheckOutputSnapshots, candidateTreeEvidenceReader, candidateTreeSourceReader, createExecPort, digestCanonical, resolveRecordStorage, runGitCommand, scopedCheckIdentity, selectScopedCheckAttempt, sha256Hex, submitManifest,
   createResourceApplicabilityProjection, matchResourceApplicabilityProjection, createResourceApplicabilityBinding, reconstructResourceApplicability, discoverRecords, portableArtifactContents, isRecordFreshForCandidate, isRecordNeutralPath, type ResourceApplicabilityBinding, type InstalledDataAttemptOrigin, type InstalledDataResourceRequest, normalizeInstalledDataResourceRequests, type InstalledDataResourceContext, type InstalledDataResourceCapture,
   type CandidateBinding, type CapturedCandidate, type ProviderRegistration, type ScopedCheckPlan, type ScopedExecutionProfile, type ScopedRuntimeObservation, type RecordCandidateBinding } from "@agent-delivery-harness/kernel";
 import type { CommandContext } from "./boundary.ts";
 import { AttemptStore, type AttemptPayload, type StoredAttempt } from "./scoped-attempts.ts";
-import { CheckSnapshotError, createCheckSnapshot, executionPath, snapshotCloneMethod, type CheckSnapshot, type CloneMethod, type SnapshotRequest } from "./check-snapshot.ts";
+import { CheckSnapshotError, createCheckSnapshot, executionPath, snapshotCloneMethod, sweepRemovedTrees, type CheckSnapshot, type CloneMethod, type SnapshotRequest } from "./check-snapshot.ts";
 import { captureInstalledDataBinding, type InstalledDataSourceTree } from "./scoped-installed-data.ts";
 import { captureOwnedInstalledDataResources } from "./installed-data-resources.ts";
 import { redactScopedStreams, scopedCommandDiagnostic, scopedDependencyDiagnostic, scopedDiagnosticFailure, type RecordedScopedAttemptDiagnostic, type ScopedSetupDiagnostic } from "./scoped-diagnostics.ts";
 export function scopedCandidate(candidate: CandidateBinding): RecordCandidateBinding {
   return { treeSha: candidate.treeSha, deliverableDigest: candidate.deliverable.digest, identityToken: candidate.deliverable.identity, baseRef: candidate.base.ref, baseTipSha: candidate.base.tipSha, mergeBaseSha: candidate.base.mergeBaseSha, workspaceId: candidate.workspaceId };
 }
+/** A host tool's sha256 within this process, by the file's identity and last change: every scoped check binds
+ * the same node, package manager and setup tool, and each is often 50–120 MB. A changed file has a new key. */
+const hostToolDigests = new Map<string, Promise<string>>();
+export async function hostToolDigest(file: string, readBytes: (file: string) => Promise<Uint8Array> = readFile): Promise<{ sha256: string; mode: number }> {
+  const before = await stat(file);
+  const key = JSON.stringify([before.dev, before.ino, before.size, before.mtimeMs, before.ctimeMs]);
+  let digest = hostToolDigests.get(key);
+  if (!digest) {
+    // ctime moves on every write, so a file changed during this read can never present this key again.
+    digest = readBytes(file).then(bytes => sha256Hex(bytes));
+    hostToolDigests.set(key, digest);
+    digest.catch(() => { if (hostToolDigests.get(key) === digest) hostToolDigests.delete(key); });
+  }
+  return { sha256: await digest, mode: before.mode & 0o111 };
+}
 async function executableIdentity(command: string, root: string, searchPath: string, cwd: string, read: Awaited<ReturnType<typeof candidateTreeEvidenceReader>>) {
   if (command.includes(path.sep) && !path.isAbsolute(command)) {
     const file = path.posix.normalize(path.posix.join(cwd, command));
@@ -27,7 +42,8 @@ async function executableIdentity(command: string, root: string, searchPath: str
     try { await access(file); } catch { continue; }
     const relative = path.relative(await realpath(root), await realpath(file));
     if (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)) throw new CheckSnapshotError("check_runtime_author_path", "Repository execution tools must use a relative command so they run from the private prepared tree.");
-    return { command, sha256: sha256Hex(await readFile(file)), mode: (await stat(file)).mode & 0o111 };
+    const { sha256, mode } = await hostToolDigest(file);
+    return { command, sha256, mode };
   }
   throw new CheckSnapshotError("check_runtime_unavailable", "A declared execution tool cannot be resolved and bound.");
 }
@@ -60,11 +76,25 @@ function oneAtATime() {
   let tail: Promise<unknown> = Promise.resolve();
   return <T>(task: () => Promise<T>): Promise<T> => { const result = tail.then(task); tail = result.catch(() => undefined); return result; };
 }
+/** Runs the tasks it is given one at a time; of those waiting, the highest `priority` goes next, ties in call order. */
+function highestFirst() {
+  const waiting: { priority: number; start: () => void }[] = [];
+  let busy = false;
+  const next = () => {
+    if (busy || waiting.length === 0) return;
+    const index = waiting.reduce((best, entry, i) => entry.priority > waiting[best]!.priority ? i : best, 0);
+    busy = true; waiting.splice(index, 1)[0]!.start();
+  };
+  return <T>(priority: number, task: () => Promise<T>): Promise<T> => new Promise<T>((resolve, reject) => {
+    waiting.push({ priority, start: () => { task().then(resolve, reject).finally(() => { busy = false; next(); }); } });
+    next();
+  });
+}
 type AcquiredSetup = Omit<ScopedSetupDiagnostic, "verification" | "phases">;
 /** A fail-fast gate's hold on one check: the signal that cancels it, and the check whose failure did. */
 interface Cancellation { readonly signal: AbortSignal; readonly after: () => string }
 /** One worker's view while it runs a check: the snapshots only it uses, by setup key, and where its lines go. */
-interface Lane { readonly snapshots: Map<string, CheckSnapshot>; readonly write: (text: string) => void }
+interface Lane { readonly snapshots: Map<string, CheckSnapshot>; readonly write: (text: string) => void; readonly priority?: number }
 export class ScopedChecks {
   /** `scopedExecution.concurrency` workers, each owning its snapshots; the first is the serial lane. */
   private readonly workers: Map<string, CheckSnapshot>[];
@@ -82,6 +112,16 @@ export class ScopedChecks {
   /** With more than one worker: one read-only warm base per setup key, which no command runs in. Each
    * worker takes a copy-on-write clone of it; without cloning each worker builds its own, as before. */
   private readonly bases = new Map<string, Promise<CheckSnapshot>>();
+  /** Each base's settlement, after which its entry is current: a failed setup has left `bases`. */
+  private readonly settling = new WeakMap<Promise<CheckSnapshot>, Promise<void>>();
+  private readonly settled = new WeakSet<Promise<CheckSnapshot>>();
+  /** Stops the bases `prewarm` started, which no attempt owns, once no check can need one still setting up. */
+  private readonly prewarming = new AbortController();
+  /** Prewarmed bases not yet taken as a worker's own tree, which a path-bound one becomes. */
+  private readonly prewarmedBases = new WeakSet<Promise<CheckSnapshot>>();
+  /** Concurrent copy-on-write clones of one large tree each take several times as long as one alone, so
+   * they run one at a time, the check expected to run longest first. */
+  private readonly cloningOne = highestFirst();
   private cloning?: Promise<CloneMethod | undefined>;
   /** Profiles whose checks a tree has run and verified since it was made: their outputs may be in it. */
   private readonly ranOutputs = new WeakMap<CheckSnapshot, Set<string>>();
@@ -143,6 +183,8 @@ export class ScopedChecks {
   static async create(context: CommandContext, candidate: CapturedCandidate): Promise<ScopedChecks | undefined> {
     const providers = scopedProviders(context);
     if (!providers.length) return undefined;
+    // Trees an earlier session moved aside but did not finish deleting: one listing, in the background.
+    void sweepRemovedTrees().catch(() => undefined);
     const session = new ScopedChecks(context, candidate);
     const storage = await resolveRecordStorage(context.rootDir, { storageNamespace: context.config.storageNamespace, leaf: "scoped-attempts" });
     const { inventory, read } = await preparedSource(context, candidate);
@@ -234,14 +276,22 @@ export class ScopedChecks {
    * duration less that attempt's own dependency setup; never-timed checks follow timed ones and ties keep
    * declaration order. Checks then run one dependency setup at a time, in the order each setup first
    * appears, so each setup installs once. */
+  /** A check's most recent passed or failed attempt's duration less that attempt's own dependency setup, any
+   * wait for another's warm base, and its clone with that clone's queue; undefined for a never-timed check. */
+  private async lastCost(id: string): Promise<number | undefined> {
+    const last = (await this.stores.get(id)!.read()).filter(r => r.attempt.status === "passed" || r.attempt.status === "failed").at(-1)?.payload;
+    const waited = last?.diagnostic?.setup?.phases.filter(p => p.phase === "warm-base-wait" || p.phase === "clone").reduce((sum, p) => sum + p.durationMs, 0) ?? 0;
+    return last?.durationMs === undefined ? undefined : last.durationMs - (last.diagnostic?.dependency?.durationMs ?? 0) - waited;
+  }
+  /** How long each check is expected to run: its last cost, or, never timed, its declared `timeoutMs`. */
+  private async expectedCosts(ids: readonly string[]): Promise<Map<string, number>> {
+    const costs = new Map<string, number>();
+    for (const id of ids) costs.set(id, await this.lastCost(id) ?? this.context.config.providers.find(p => p.id === id)?.check?.timeoutMs ?? 0);
+    return costs;
+  }
   private async cheapestFirst(ids: readonly string[]): Promise<string[]> {
     const cost = new Map<string, number>();
-    for (const id of ids) {
-      const last = (await this.stores.get(id)!.read()).filter(r => r.attempt.status === "passed" || r.attempt.status === "failed").at(-1)?.payload;
-      // A check that waited on another's warm base did not pay that setup either.
-      const waited = last?.diagnostic?.setup?.phases.filter(p => p.phase === "warm-base-wait").reduce((sum, p) => sum + p.durationMs, 0) ?? 0;
-      cost.set(id, last?.durationMs === undefined ? Infinity : last.durationMs - (last.diagnostic?.dependency?.durationMs ?? 0) - waited);
-    }
+    for (const id of ids) cost.set(id, await this.lastCost(id) ?? Infinity);
     const [first, ...rest] = ids;
     if (first === undefined) return [];
     const byCost = [first, ...rest.sort((a, b) => cost.get(a)! === cost.get(b)! ? 0 : cost.get(a)! < cost.get(b)! ? -1 : 1)];
@@ -253,21 +303,68 @@ export class ScopedChecks {
    * snapshots, so two checks never share one at once. A worker prints a check's lines together when it
    * finishes; a single worker prints them as they come. After a check throws no new id starts, the running
    * ones finish, and the first failure in `ids` order is thrown.
+   *
+   * A worker takes the first remaining id whose warm base is not still setting up, so no check's setup waits
+   * on a base being built; while every remaining id's base is, the worker waits for one to settle before
+   * taking a check. Once `halted`, the remaining ids are taken in order without waiting. With `expected`, a
+   * worker takes the startable id expected to run longest instead, and its clone queues by that cost, so
+   * the critical path gets its base, clone and worker first.
    */
-  private async pool(ids: readonly string[], run: (id: string, lane: Lane) => Promise<void>): Promise<void> {
-    const failures = new Map<string, unknown>();
-    let next = 0;
-    await Promise.all(this.workers.map(async snapshots => {
-      while (next < ids.length && failures.size === 0) {
-        const id = ids[next++]!, lines: string[] = [];
-        try { await run(id, this.concurrency === 1 ? this.serial : { snapshots, write: text => { lines.push(text); } }); }
-        catch (error) { failures.set(id, error); }
-        finally { for (const line of lines) this.context.write(line); }
+  private async pool(ids: readonly string[], run: (id: string, lane: Lane) => Promise<void>, halted: () => boolean = () => false, expected?: ReadonlyMap<string, number>): Promise<void> {
+    const failures = new Map<string, unknown>(), remaining = [...ids];
+    const sleepers = new Set<() => void>();
+    const woken = () => new Promise<void>(resolve => { sleepers.add(resolve); });
+    const waker = () => { for (const sleeper of [...sleepers]) sleeper(); sleepers.clear(); };
+    this.poolWakers.add(waker);
+    const take = async (): Promise<string | undefined> => {
+      for (;;) {
+        if (failures.size > 0 || remaining.length === 0) return undefined;
+        const index = halted() ? 0 : remaining.reduce((best, id, i) => !this.startable(id) ? best
+          : best < 0 || (expected?.get(id) ?? 0) > (expected?.get(remaining[best]!) ?? 0) ? i : best, -1);
+        if (index >= 0) { const id = remaining.splice(index, 1)[0]!; this.claim(id); return id; }
+        await Promise.race([woken(), ...remaining.flatMap(id => { const key = this.keyOf(id), base = this.bases.get(key); return base ? [this.settling.get(base)!] : this.claims.has(key) ? [this.claims.get(key)!.released] : []; })]);
       }
-    }));
+    };
+    try {
+      await Promise.all(this.workers.map(async snapshots => {
+        for (let id = await take(); id !== undefined; id = await take()) {
+          const lines: string[] = [];
+          try { await run(id, this.concurrency === 1 ? this.serial : { snapshots, write: text => { lines.push(text); }, priority: expected?.get(id) ?? 0 }); }
+          catch (error) { failures.set(id, error); this.wakePools(); }
+          finally { this.release(this.keyOf(id), id); for (const line of lines) this.context.write(line); }
+        }
+      }));
+    } finally { this.poolWakers.delete(waker); }
     const failed = ids.find(id => failures.has(id));
     if (failed !== undefined) throw failures.get(failed);
   }
+  private readonly poolWakers = new Set<() => void>();
+  private wakePools(): void { for (const wake of [...this.poolWakers]) wake(); }
+  private keyOf(id: string): string {
+    return setupKey(this.profileOf(id), this.context.config.providers.find(p => p.id === id)?.check?.physicalSource);
+  }
+  /** A base for this id's setup key whose setup has settled, or no base and no check about to set one up. */
+  private startable(id: string): boolean {
+    const key = this.keyOf(id), base = this.bases.get(key);
+    return base === undefined ? !this.claims.has(key) : this.settled.has(base);
+  }
+  /** While bases are shared, a check taken for a key with no base holds the key until its setup has started
+   * one (or it finished), so a second check of that key waits outside its attempt rather than on that build. */
+  private readonly claims = new Map<string, { readonly owner: string; readonly released: Promise<void>; readonly release: () => void }>();
+  private sharing = false;
+  private claim(id: string): void {
+    const key = this.keyOf(id);
+    if (!this.sharing || this.bases.has(key) || this.claims.has(key)) return;
+    let release = () => {};
+    const released = new Promise<void>(resolve => { release = resolve; });
+    this.claims.set(key, { owner: id, released, release });
+  }
+  /** Ends the key's claim: once a base exists, whoever holds it; when a check finishes, only its own. */
+  private release(key: string, owner?: string): void {
+    const claim = this.claims.get(key);
+    if (!claim || (owner !== undefined && claim.owner !== owner)) return;
+    this.claims.delete(key); claim.release();
+  }
   /** Stops at the first failure: a failed mechanical check publishes no receipt. */
   async satisfyMechanical(): Promise<void> {
     const ids = await this.cheapestFirst(this.context.config.scopedExecution!.mechanicalProviders);
@@ -277,8 +374,11 @@ export class ScopedChecks {
       const provider = this.context.config.providers.find(p => p.id === id)!;
       await this.execute(provider, this.context.config.obligations.filter(o => o.providers.includes(id)).map(o => o.id), true, lane);
     };
-    // The first declared check guards the rest, so it finishes before any other starts.
+    // The first declared check guards the rest, so it finishes before any other starts, or sets up.
+    const executing = async (some: readonly string[]) => { const out: string[] = []; for (const id of some) if ((await this.selected(id))?.attempt.status !== "passed") out.push(id); return out; };
+    await this.prewarm(await executing(ids.slice(0, 1)));
     await this.pool(ids.slice(0, 1), satisfy);
+    await this.prewarm(await executing(ids.slice(1)));
     await this.pool(ids.slice(1), satisfy);
   }
   /**
@@ -305,18 +405,24 @@ export class ScopedChecks {
         if (failFast && firstFailure === undefined) {
           firstFailure = id;
           for (const [other, controller] of running) if (other !== id) controller.abort();
+          // A worker waiting for a base takes the rest now, which never start.
+          this.wakePools();
         }
       } finally { running.delete(id); }
     };
+    const halted = () => firstFailure !== undefined;
+    const expected = await this.expectedCosts(requests.map(r => r.provider.id));
     const resource = requests.find(r => this.acceptsApplicability(r.provider, r.obligationIds));
+    // V1 has one conditional consumer. Keep the first configured check ahead of
+    // it, and execute both on the capture worker before releasing the rest to
+    // the pool. Other workers never inherit that worker's installed tree.
+    const serialIds = resource ? [...new Set([requests[0]!.provider.id, resource.provider.id])] : [];
+    // Those two hold every other worker, so their bases set up first, in that order.
+    await this.prewarm(requests.map(r => r.provider.id), expected, serialIds);
     if (resource) {
-      // V1 has one conditional consumer. Keep the first configured check ahead of
-      // it, and execute both on the capture worker before releasing the rest to
-      // the pool. Other workers never inherit that worker's installed tree.
-      const serialIds = [...new Set([requests[0]!.provider.id, resource.provider.id])];
       for (const id of serialIds) await run(id, this.serial);
-      await this.pool(requests.map(r => r.provider.id).filter(id => !serialIds.includes(id)), run);
-    } else await this.pool(requests.map(r => r.provider.id), run);
+      await this.pool(requests.map(r => r.provider.id).filter(id => !serialIds.includes(id)), run, halted, expected);
+    } else await this.pool(requests.map(r => r.provider.id), run, halted, expected);
     if (firstFailure !== undefined) await this.cancelUnstarted(unstarted, firstFailure);
     return requests.flatMap(r => failures.has(r.provider.id) ? [failures.get(r.provider.id)!] : []);
   }
@@ -333,12 +439,98 @@ export class ScopedChecks {
   /** One acquisition path preserves setup sharing, output ownership and worker isolation. A worker's tree
    * for a setup key is built here, cloned from the warm base, or retained from its previous check.
    * `onSetup` hears how the tree is being got before any setup runs, so a failed setup is attributed. */
+  /** Every scoped check's profile sharing this setup may write its own outputs in the shared tree;
+   * only those profiles passed the overlap refusal in create(). */
+  private sharedOutputsFor(key: string): string[] {
+    return [...new Set(this.context.config.scopedExecution!.profiles
+      .filter(p => this.context.config.providers.some(q => q.check?.scope?.profile === p.id && setupKey(p, q.check.physicalSource) === key)).flatMap(p => p.mutableOutputs))];
+  }
+  private buildSnapshot(profile: ScopedExecutionProfile, physicalSource: SnapshotRequest["physicalSource"] | undefined, onPhase: NonNullable<SnapshotRequest["onPhase"]>, dependencyResult?: SnapshotRequest["onDependencyResult"], signal = this.context.signal): Promise<CheckSnapshot> {
+    return createCheckSnapshot({ rootDir: this.context.rootDir, candidate: this.candidate, outputs: this.sharedOutputsFor(setupKey(profile, physicalSource)), gitContext: profile.gitContext ?? "full", environment: { PATH: this.context.env["PATH"] ?? process.env["PATH"] ?? "/usr/bin:/bin" }, ...(physicalSource ? { physicalSource } : {}), ...(profile.dependencies ? { dependencies: profile.dependencies } : {}), ...(signal ? { signal } : {}),
+      onPhase, ...(dependencyResult ? { onDependencyResult: dependencyResult } : {}) });
+  }
+  /** Shares `base` for its setup key. A failed setup is not shared: it leaves `bases` as it settles, and the
+   * next check of this key sets up again, as it would on its own worker. */
+  private shareBase(key: string, base: Promise<CheckSnapshot>): void {
+    this.bases.set(key, base);
+    this.settling.set(base, base.then(() => { this.settled.add(base); }, () => { this.settled.add(base); if (this.bases.get(key) === base) this.bases.delete(key); }));
+  }
+  /**
+   * Sets up the warm base of each setup key among `ids` that has none yet, so the checks that clone it neither
+   * build it nor wait for another check to. Bases set up one at a time: concurrent dependency installs on one
+   * machine each take about twice as long, so a key's base is ready soonest on its own. With `expected`, the
+   * keys of `leading` go first, in that order, and then the key whose own critical path is longest: its last
+   * recorded build plus the longest expected check that needs it. Without it, the order of `ids`. Every key
+   * is registered at once, so no worker takes its checks before its base settles. No attempt owns this setup:
+   * a check cloning the base records it as reused and carries no dependency result, and a failed one leaves
+   * no base, so the check that next needs its key sets up itself and owns that result. Only with cloning:
+   * without it each worker builds its own tree, as before.
+   */
+  private async prewarm(ids: readonly string[], expected?: ReadonlyMap<string, number>, leading: readonly string[] = []): Promise<void> {
+    if (this.concurrency === 1 || !await (this.cloning ??= snapshotCloneMethod())) return;
+    this.sharing = true;
+    const signal = this.context.signal ? AbortSignal.any([this.context.signal, this.prewarming.signal]) : this.prewarming.signal;
+    const keyed = new Map<string, { id: string; check: number; order: number }>();
+    for (const [order, id] of ids.entries()) {
+      const key = this.keyOf(id), check = expected?.get(id) ?? 0, seen = keyed.get(key);
+      if (this.bases.has(key)) continue;
+      if (!seen) keyed.set(key, { id, check, order });
+      else if (check > seen.check) keyed.set(key, { id, check, order: seen.order });
+    }
+    const rank = (key: string) => { const index = leading.findIndex(id => this.keyOf(id) === key); return index < 0 ? leading.length : index; };
+    const critical = new Map<string, number>();
+    for (const [key, { check }] of keyed) critical.set(key, expected ? await this.lastBuild(key) + check : 0);
+    const keys = [...keyed].sort(([a, x], [b, y]) => rank(a) - rank(b) || critical.get(b)! - critical.get(a)! || x.order - y.order);
+    for (const [key, { id }] of keys) {
+      const profile = this.profileOf(id), physicalSource = this.context.config.providers.find(p => p.id === id)?.check?.physicalSource;
+      const previous = this.prewarmTail;
+      // A build queued when the prewarm stops sees the aborted signal and settles as interrupted.
+      const base = (async () => {
+        await previous;
+        const started = performance.now();
+        const snapshot = await this.buildSnapshot(profile, physicalSource, (phase, durationMs) => this.context.write(`prewarm ${profile.id}: ${phase} ${Math.round(durationMs)}ms`), undefined, signal);
+        // Recorded in the background: a base never waits on its timing.
+        this.timingWrites.push(this.recordBuild(key, performance.now() - started));
+        return snapshot;
+      })();
+      this.prewarmTail = base.then(() => undefined, () => undefined);
+      this.prewarmedBases.add(base);
+      this.shareBase(key, base);
+      base.catch(error => { if (!this.prewarming.signal.aborted) this.context.write(`prewarm ${profile.id}: setup failed (${error instanceof CheckSnapshotError ? error.code : "unclassified"}); its first check sets up itself`); });
+    }
+  }
+  /** Where the last successful prewarm of each setup key's base is timed, resolved once a session. Ordering
+   * only: no admission, gate or record reads it, and a missing or unreadable timing counts as no build time.
+   * A check-owned build is not timed: it follows a failed prewarm and may share the machine with the chain. */
+  private timings?: Promise<string>;
+  private readonly timingWrites: Promise<void>[] = [];
+  private async timingPath(key: string): Promise<string> {
+    const dir = await (this.timings ??= resolveRecordStorage(this.context.rootDir, { storageNamespace: this.context.config.storageNamespace, leaf: "scoped-setup-timings" }).then(storage => storage.storageDir));
+    return path.join(dir, `${digestCanonical({ gate: this.context.config.gateId, setup: key })}.json`);
+  }
+  private async lastBuild(key: string): Promise<number> {
+    try {
+      const timing = JSON.parse(await readFile(await this.timingPath(key), "utf8")) as { version?: unknown; buildMs?: unknown };
+      return timing.version === "scoped-setup-timing/1" && typeof timing.buildMs === "number" && Number.isFinite(timing.buildMs) && timing.buildMs >= 0 ? timing.buildMs : 0;
+    } catch { return 0; }
+  }
+  private async recordBuild(key: string, buildMs: number): Promise<void> {
+    let temporary: string | undefined;
+    try {
+      const file = await this.timingPath(key);
+      temporary = `${file}.${randomUUID()}`;
+      await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+      await writeFile(temporary, `${JSON.stringify({ version: "scoped-setup-timing/1", buildMs: Math.round(buildMs) })}\n`);
+      await rename(temporary, file);
+    } catch {
+      // Timing orders prewarms; it cannot fail a setup, and leaves no partial file behind.
+      if (temporary) await rm(temporary, { force: true }).catch(() => undefined);
+    }
+  }
+  private prewarmTail: Promise<void> = Promise.resolve();
   private async acquireSnapshot(profile: ScopedExecutionProfile, lane: Lane, onDependencyResult?: SnapshotRequest["onDependencyResult"], physicalSource?: SnapshotRequest["physicalSource"], onSetup: (setup: AcquiredSetup) => void = () => {}): Promise<{ snapshot: CheckSnapshot; sharedOutputs: string[]; setup: AcquiredSetup }> {
     const key = setupKey(profile, physicalSource);
-    // Every scoped check's profile sharing this setup may write its own outputs in the shared tree;
-    // only those profiles passed the overlap refusal in create().
-    const sharedOutputs = [...new Set(this.context.config.scopedExecution!.profiles
-      .filter(p => this.context.config.providers.some(q => q.check?.scope?.profile === p.id && setupKey(p, q.check.physicalSource) === key)).flatMap(p => p.mutableOutputs))];
+    const sharedOutputs = this.sharedOutputsFor(key);
     const method = this.concurrency === 1 ? undefined : await (this.cloning ??= snapshotCloneMethod());
     const acquired = (snapshot: CheckSnapshot, setup: AcquiredSetup) => { lane.snapshots.set(key, snapshot); onSetup(setup); return { snapshot, sharedOutputs, setup }; };
     const retained = lane.snapshots.get(key);
@@ -354,19 +546,16 @@ export class ScopedChecks {
       if (write) write(phase, durationMs);
       else lane.write(`snapshot ${profile.id}: bootstrap ${phase} ${Math.round(durationMs)}ms`);
     };
-    const build = (dependencyResult?: SnapshotRequest["onDependencyResult"]) => createCheckSnapshot({ rootDir: this.context.rootDir, candidate: this.candidate, outputs: sharedOutputs, gitContext: profile.gitContext ?? "full", environment: { PATH: this.context.env["PATH"] ?? process.env["PATH"] ?? "/usr/bin:/bin" }, ...(physicalSource ? { physicalSource } : {}), ...(profile.dependencies ? { dependencies: profile.dependencies } : {}), ...(this.context.signal ? { signal: this.context.signal } : {}),
-      onPhase, ...(dependencyResult ? { onDependencyResult: dependencyResult } : {}) });
+    const build = (dependencyResult?: SnapshotRequest["onDependencyResult"]) => this.buildSnapshot(profile, physicalSource, onPhase, dependencyResult);
     let executed = false, clone: AcquiredSetup["clone"] = this.concurrency === 1 ? "not-used" : "unavailable";
     if (method) {
       let base = this.bases.get(key);
       if (!base) {
         executed = true;
         base = build(onDependencyResult);
-        this.bases.set(key, base);
-        // A failed setup is not shared: the next check of this key sets up again, as it would on its own worker.
-        const failed = base;
-        failed.catch(() => { if (this.bases.get(key) === failed) this.bases.delete(key); });
+        this.shareBase(key, base);
       }
+      this.release(key);
       onSetup({ action: executed ? "executed" : "reused", snapshot: "cloned", clone: method });
       const waiting = performance.now();
       let warm: CheckSnapshot | undefined;
@@ -382,8 +571,13 @@ export class ScopedChecks {
         clone = "path-bound";
         lane.write(`snapshot ${profile.id}: setup wrote its own path into the tree; each worker builds its own`);
         if (executed) return acquired(warm, { action: "executed", snapshot: "built", clone });
+        // A prewarmed base no check owns becomes exactly one worker's own tree; every other worker builds its own.
+        if (this.prewarmedBases.delete(base)) return acquired(warm, { action: "reused", snapshot: "built", clone });
       } else if (warm) {
-        try { return acquired(await warm.clone(method, onPhase), { action: executed ? "executed" : "reused", snapshot: "cloned", clone: method }); }
+        // Clones run one at a time; the time this one queued counts as its clone.
+        const queued = performance.now(), source = warm;
+        const cloned = () => this.cloningOne(lane.priority ?? 0, () => { const wait = performance.now() - queued; return source.clone(method, (phase, durationMs) => onPhase(phase, phase === "clone" ? durationMs + wait : durationMs)); });
+        try { return acquired(await cloned(), { action: executed ? "executed" : "reused", snapshot: "cloned", clone: method }); }
         catch (error) {
           if (!(error instanceof CheckSnapshotError) || this.context.signal?.aborted) throw error;
           // The base stays for other workers; this one sets up its own tree, as without cloning.
@@ -691,6 +885,9 @@ export class ScopedChecks {
     this.cleanupStarted = true;
     await this.closeCapturePhase();
     await Promise.all(this.executionTails.values());
+    // No check needs a base still setting up now; stop rather than wait for it.
+    this.prewarming.abort();
+    await Promise.all(this.timingWrites);
     for (const snapshots of this.workers) { for (const snapshot of snapshots.values()) await snapshot.cleanup(); snapshots.clear(); }
     const bases = [...this.bases.values()]; this.bases.clear();
     for (const base of bases) await (await base.catch(() => undefined))?.cleanup();

package/src/scoped-diagnostics.ts

@@ -21,8 +21,9 @@ export interface ScopedDependencyDiagnostic {
 const setupPhases = ["materialization", "baseline-inventory", "dependencies", "post-dependency-inventory", "warm-base-wait", "clone", "pre-command-verification"] as const;
 /** How this attempt got the tree its command ran in, and what that cost up to the command.
  * `executed`: this attempt ran the setup (a tree it built, or the warm base it then cloned);
- * `reused`: the setup had already run (a clone of a warm base another check built, or the
- * worker's tree retained from its previous check). `clone` names the copy-on-write method, or says
+ * `reused`: the setup had already run (a clone of a warm base another check or the session's prewarm
+ * built, a prewarmed path-bound base taken as this worker's own tree, or the worker's tree retained
+ * from its previous check). `clone` names the copy-on-write method, or says
  * why each worker built its own tree: cloning is unavailable here, or the setup wrote its own path
  * into the tree (`path-bound`), or there is one worker (`not-used`). */
 export interface ScopedSetupDiagnostic {