@agent-delivery-harness/cli 0.8.2 → 0.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-delivery-harness/cli",
-  "version": "0.8.2",
+  "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.2"
+    "@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

@@ -7,13 +7,28 @@ import { deliveryRecordPathFor, recordOutputProvider, computeDeliverableIdentity
   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.");
 }
@@ -167,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);