@agent-delivery-harness/cli 0.7.4 → 0.8.1

package/src/declared-checks.ts

@@ -1,10 +1,10 @@
 import { randomUUID } from "node:crypto";
 import path from "node:path";
-import { captureCheckBindings, captureCheckOutputSnapshots, digestCanonical, classifyCandidateDrift, computeCheckWiringFingerprint, createBlocker, createExecPort, sha256Hex, submitManifest, type Blocker, type CandidateBinding, type ProviderRegistration } from "@agent-delivery-harness/kernel";
+import { captureCheckBindings, captureCheckOutputSnapshots, digestCanonical, classifyCandidateDrift, computeCheckWiringFingerprint, createBlocker, createExecPort, sha256Hex, submitManifest, type Blocker, type CandidateBinding, type CheckBindingOptions, type ProviderRegistration, type SubmissionOptions } from "@agent-delivery-harness/kernel";
 import type { CommandContext } from "./boundary.ts";
 
 /** Runs one declared argv check and submits its product-constructed terminal evidence. */
-export async function runDeclaredCheck(context: CommandContext, provider: ProviderRegistration, obligationIds: readonly string[], before: CandidateBinding): Promise<readonly Blocker[]> {
+export async function runDeclaredCheck(context: CommandContext, provider: ProviderRegistration, obligationIds: readonly string[], before: CandidateBinding, scoped: Pick<CheckBindingOptions, "scopedPlan" | "readOutput"> & Pick<SubmissionOptions, "resourceBindings"> = {}): Promise<readonly Blocker[]> {
   const check = provider.check!;
   const wiring = await context.wire();
   const fail = (code: string, summary: string, details?: string): readonly Blocker[] => [createBlocker({ code, source: { kind: "command", id: "delivery-harness.cli.gate" }, summary,
@@ -21,7 +21,7 @@ export async function runDeclaredCheck(context: CommandContext, provider: Provid
   const captured = await wiring.captureCandidate();
   if (!captured.ok) return captured.blockers;
   if (classifyCandidateDrift(before, captured.candidate).length || start.candidate.headSha !== captured.candidate.headSha || fingerprint !== await computeCheckWiringFingerprint(context.rootDir, context.config, wiring.storageOptions)) return fail("check_candidate_changed", "The candidate, base or wiring changed while the check ran.");
-  const binding = (await captureCheckBindings(context.rootDir, context.config, captured.candidate, wiring.storageOptions))[provider.id];
+  const binding = (await captureCheckBindings(context.rootDir, context.config, captured.candidate, { ...wiring.storageOptions, ...scoped }))[provider.id];
   if (binding === undefined) return fail("check_output_missing", `Declared check ${provider.id} has a missing, unreadable, oversized or escaped output.`);
   const runId = randomUUID(), finalPassId = "pass-1";
   const allocation = await context.artifacts.allocateRunRoot({ providerId: provider.id, runId });
@@ -45,6 +45,6 @@ export async function runDeclaredCheck(context: CommandContext, provider: Provid
     attestation: { level: "self", signatures: [] }, recordedAt: new Date().toISOString(), claims: obligationIds.map(obligation => ({ obligation, payloadSpec: "checks.passed/1", payload })) };
   const manifestPath = path.join(allocation.runRoot.path, "manifest.json");
   await context.artifacts.writeTextFile(manifestPath, JSON.stringify(manifest));
-  const outcome = await submitManifest({ rootDir: context.rootDir, config: context.config, manifestPath }, { captureCandidate: wiring.captureCandidate, artifacts: context.artifacts, ...wiring.storageOptions });
+  const outcome = await submitManifest({ rootDir: context.rootDir, config: context.config, manifestPath }, { captureCandidate: wiring.captureCandidate, artifacts: context.artifacts, ...wiring.storageOptions, ...scoped });
   return outcome.status === "accepted" ? [] : outcome.blockers;
 }

package/src/delivery-posture.ts

@@ -0,0 +1,39 @@
+/**
+ * What `verify`, `gate`, `record` and `resume` do with the declared posture.
+ *
+ * Each calls this once its arguments have parsed and before anything else. Under
+ * `focused` the command returns the one outcome this builds, having read no
+ * 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.
+ */
+import { resolveDeliveryPosture } from "@agent-delivery-harness/kernel";
+import { CliInterruption, type CommandContext, type CommandResult } from "./boundary.ts";
+import { oneLine } from "./run-surface.ts";
+
+export async function focusedOutcome(context: CommandContext): Promise<Extract<CommandResult, { kind: "ok" }> | undefined> {
+  const resolved = await resolveDeliveryPosture({
+    rootDir: context.rootDir,
+    baseRef: context.config.baseRef,
+    ...(context.signal === undefined ? {} : { signal: context.signal }),
+  });
+  if (context.signal?.aborted) throw new CliInterruption();
+  if (resolved.posture === "focused") {
+    return {
+      kind: "ok",
+      unobserved: true,
+      summary: [
+        "outcome: focused",
+        `posture: ${resolved.posture}`,
+        `reason: ${oneLine(resolved.reason, 512)}`,
+        `source: ${oneLine(resolved.source, 256)}`,
+        `base tip: ${resolved.baseTipSha ?? "(none)"}`,
+      ].join("\n"),
+    };
+  }
+  if (resolved.code === "posture_malformed") context.writeError(`${resolved.code}: ${oneLine(resolved.reason, 512)}`);
+  return undefined;
+}

package/src/installed-data-resources.ts

@@ -0,0 +1,57 @@
+import { createExecPort, captureInstalledDataResources, normalizeInstalledDataResourceRequests, InstalledDataResourceError, INSTALLED_DATA_LIMITS,
+  type InstalledDataResourceContext, type InstalledDataResourceRequest, type InstalledDataResourcePorts } from "@agent-delivery-harness/kernel";
+import type { CheckSnapshot } from "./check-snapshot.ts";
+import { installedDataWorker } from "./installed-data-worker.ts";
+
+/** Only ScopedChecks may turn these observations into native applicability.
+ * This adapter's return alone is not an attestation or passing check result.
+ */
+export async function captureOwnedInstalledDataResources(
+  snapshot: Pick<CheckSnapshot, "rootDir" | "verify">,
+  requests: readonly InstalledDataResourceRequest[],
+  context: InstalledDataResourceContext,
+  options: { readonly signal?: AbortSignal; readonly timeoutMs?: number } = {},
+) {
+  const normalized = normalizeInstalledDataResourceRequests(requests);
+  const timeoutMs = options.timeoutMs ?? 60_000;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000)
+    throw new InstalledDataResourceError("installed_data_descriptor_invalid", "Resource observer requires a bounded positive deadline.");
+  if (options.signal?.aborted)
+    throw new InstalledDataResourceError("installed_data_resource_unsafe", "Resource observation was cancelled before it started.");
+  const request = JSON.stringify({ requests: normalized, limits: INSTALLED_DATA_LIMITS });
+  if (Buffer.byteLength(request) > 64 * 1024) throw new InstalledDataResourceError("installed_data_limit_exceeded", "Resource request exceeds the bounded observer input.");
+  await snapshot.verify({ outputs: [] });
+  try {
+    const result = await createExecPort().run({ command: process.execPath, args: ["--input-type=module", "--eval", installedDataWorker], cwd: snapshot.rootDir,
+      env: { DELIVERY_INSTALLED_DATA_REQUEST: request }, timeoutMs, maxBuffer: INSTALLED_DATA_LIMITS.serializedBytes,
+      ...(options.signal ? { signal: options.signal } : {}) });
+    if (result.code !== 0) {
+      const code = result.stderr.trim();
+      if (code === "installed_data_resolution_unsafe" || code === "installed_data_resource_unsafe" || code === "installed_data_limit_exceeded")
+        throw new InstalledDataResourceError(code, "Owned installed resource observation refused.");
+      throw new InstalledDataResourceError("installed_data_resource_unsafe", "Owned installed resource observation did not complete.");
+    }
+    let observed: { entries: Record<string, { kind: string; physicalPath: string; linkTarget: string | null; bytesBase64?: string; members?: string[] }>; resolutions: Record<string, unknown> };
+    try { observed = JSON.parse(result.stdout); }
+    catch { throw new InstalledDataResourceError("installed_data_capture_invalid", "Owned resource observation returned malformed facts."); }
+    const ports: InstalledDataResourcePorts = {
+      resolve: async request => observed.resolutions[request.id] as Awaited<ReturnType<InstalledDataResourcePorts["resolve"]>>,
+      stat: async file => {
+        const entry = observed.entries[file];
+        if (!entry) throw new InstalledDataResourceError("installed_data_capture_invalid", "Owned resource metadata is incomplete.");
+        return { kind: entry.kind, physicalPath: entry.physicalPath, linkTarget: entry.linkTarget } as Awaited<ReturnType<InstalledDataResourcePorts["stat"]>>;
+      },
+      readFile: async file => {
+        const entry = observed.entries[file];
+        if (typeof entry?.bytesBase64 !== "string") throw new InstalledDataResourceError("installed_data_capture_invalid", "Owned resource bytes are incomplete.");
+        return Buffer.from(entry.bytesBase64, "base64");
+      },
+      listDirectory: async file => {
+        const entry = observed.entries[file];
+        if (!Array.isArray(entry?.members)) throw new InstalledDataResourceError("installed_data_capture_invalid", "Owned directory membership is incomplete.");
+        return entry.members;
+      },
+    };
+    return await captureInstalledDataResources(normalized, context, ports);
+  } finally { await snapshot.verify({ outputs: [] }); }
+}

package/src/installed-data-worker.ts

@@ -0,0 +1,83 @@
+/** Runs only in a bounded, killable child over one invocation-owned snapshot.
+ * The parent validates descriptors first and validates/hashes these facts again.
+ * No dependency package code or host preload is executed by observation.
+ */
+export const installedDataWorker = String.raw`
+import { lstat, realpath, readdir, open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+const fail=(code)=>{const e=new Error(code);e.code=code;throw e;};
+const input=JSON.parse(process.env.DELIVERY_INSTALLED_DATA_REQUEST);
+const root=await realpath(process.cwd());
+const entries=Object.create(null), resolutions=Object.create(null);
+let rawBytes=0;
+const safe=(value)=>typeof value==='string'&&value.length>0&&!value.includes('\\')&&!value.startsWith('/')&&value.split('/').every(p=>p&&p!=='.'&&p!=='..');
+const absolute=(value)=>{if(!safe(value))fail('installed_data_resource_unsafe');return path.join(root,value);};
+async function statOne(relative){
+ if(entries[relative])return entries[relative];
+ if(Object.keys(entries).length>=input.limits.entries)fail('installed_data_limit_exceeded');
+ let s;try{s=await lstat(absolute(relative));}catch(e){if(e.code!=='ENOENT')throw e;return entries[relative]={kind:'absent',physicalPath:relative,linkTarget:null};}
+ if(s.isSymbolicLink())fail('installed_data_resource_unsafe');
+ const physical=path.relative(root,await realpath(absolute(relative))).split(path.sep).join('/');
+ if(physical!==relative)fail('installed_data_resource_unsafe');
+ const kind=s.isFile()?'file':s.isDirectory()?'directory':'unsupported';
+ if(kind==='unsupported')fail('installed_data_resource_unsafe');
+ return entries[relative]={kind,physicalPath:physical,linkTarget:null};
+}
+async function observe(relative){
+ const parts=relative.split('/');
+ for(let i=1;i<parts.length;i++){
+  const ancestor=await statOne(parts.slice(0,i).join('/'));
+  if(ancestor.kind!=='directory'&&ancestor.kind!=='absent')fail('installed_data_resource_unsafe');
+ }
+ return statOne(relative);
+}
+async function read(relative){
+ const entry=await observe(relative);if(entry.kind!=='file')fail('installed_data_resource_unsafe');
+ if(entry.bytesBase64!==undefined)return;
+ const handle=await open(absolute(relative),constants.O_RDONLY|constants.O_NOFOLLOW);
+ try{
+  const s=await handle.stat();if(!s.isFile())fail('installed_data_resource_unsafe');
+  if(s.size>input.limits.rawBytes-rawBytes)fail('installed_data_limit_exceeded');
+  const bytes=Buffer.alloc(s.size+1);const {bytesRead}=await handle.read(bytes,0,bytes.length,0);
+  if(bytesRead!==s.size)fail('installed_data_resource_unsafe');
+  rawBytes+=bytesRead;entry.bytesBase64=bytes.subarray(0,bytesRead).toString('base64');
+ }finally{await handle.close();}
+}
+try{
+ for(const r of input.requests){
+  const issuer=await observe(r.issuer);if(issuer.kind!=='file')fail('installed_data_resource_unsafe');
+  const require=createRequire(absolute(r.issuer));
+  const paths=require.resolve.paths(r.package+'/package.json');
+  const boundary=paths?.indexOf(path.join(root,'node_modules'))??-1;
+  if(boundary<0)fail('installed_data_resolution_unsafe');
+  const search=[];
+  for(const dir of paths.slice(0,boundary+1)){
+   const candidate=path.relative(root,path.join(dir,r.package)).split(path.sep).join('/');
+   if(!safe(candidate))fail('installed_data_resolution_unsafe');
+   const entry=await observe(candidate);search.push({path:candidate,kind:entry.kind});
+   if(search.length<=boundary&&entry.kind!=='absent')fail('installed_data_resolution_unsafe');
+  }
+  const packageRoot='node_modules/'+r.package, manifestPath=packageRoot+'/package.json';
+  await read(manifestPath);
+  let resolved;try{resolved=require.resolve(r.package+'/package.json');}catch{fail('installed_data_resolution_unsafe');}
+  if(resolved!==absolute(manifestPath))fail('installed_data_resolution_unsafe');
+  resolutions[r.id]={mode:'require',packageRoot,manifestPath,search};
+  for(const f of r.files)await read(packageRoot+'/'+f);
+  for(const d of r.directories){
+   const directory=packageRoot+'/'+d.path,entry=await observe(directory);
+   if(entry.kind!=='directory')fail('installed_data_resource_unsafe');
+   const names=await readdir(absolute(directory));if(names.length>input.limits.directoryMembers)fail('installed_data_limit_exceeded');
+   entry.members=names.sort();
+   for(const name of names)if(name.endsWith(d.suffix))await read(directory+'/'+name);
+  }
+ }
+ const result=JSON.stringify({entries,resolutions});
+ if(Buffer.byteLength(result)>input.limits.serializedBytes)fail('installed_data_limit_exceeded');
+ process.stdout.write(result);
+}catch(e){
+ const allowed=['installed_data_descriptor_invalid','installed_data_resolution_unsafe','installed_data_resource_unsafe','installed_data_limit_exceeded'];
+ process.stderr.write(allowed.includes(e.code)?e.code:'installed_data_resource_unsafe');process.exitCode=1;
+}
+`;

package/src/review-evidence.ts

@@ -88,7 +88,7 @@ export async function buildReviewContext(
   candidate: CapturedCandidate,
   receipt: PreparationReceipt,
 ) {
-  const inputs = await capturePortableEvidenceContext(config, repositoryEvidenceReader(rootDir, createArtifactsPort()), receipt.preparationFingerprint);
+  const inputs = await capturePortableEvidenceContext(config, repositoryEvidenceReader(rootDir, createArtifactsPort()), receipt.preparationFingerprint, candidate.deliverable.digest);
   const charters = inputs.reviewerCharters;
   if (charters.length === 0 || inputs.release === null) throw new OutcomeError("the compiled policy activates no review lens or installed release");
   const binding = {

package/src/scoped-attempts.ts

@@ -2,7 +2,7 @@
 import { randomUUID } from "node:crypto";
 import { link, mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { digestCanonical, type ScopedCheckAttempt } from "@agent-delivery-harness/kernel";
+import { digestCanonical, validateResourceApplicabilityProjection, type ResourceApplicabilityProjection, type ScopedCheckAttempt, type ScopedCheckDefinition } from "@agent-delivery-harness/kernel";
 import { CheckSnapshotError } from "./check-snapshot.ts";
 import type { RecordedScopedAttemptDiagnostic } from "./scoped-diagnostics.ts";
 export interface AttemptPayload {
@@ -11,9 +11,29 @@ export interface AttemptPayload {
   readonly dependencyDigest?: string;
   readonly log?: string;
   readonly diagnostic?: RecordedScopedAttemptDiagnostic;
+  /** Native successful origin binding is checked before retention and on every load. */
+  readonly resourceApplicability?: ResourceApplicabilityProjection;
+  /** Original broad selection, authenticated by the native attempt digests. */
+  readonly resourceScope?: ScopedCheckDefinition;
 }
-export interface StoredAttempt { readonly attempt: ScopedCheckAttempt; readonly payload?: AttemptPayload }
+export interface StoredAttempt { readonly attempt: ScopedCheckAttempt; readonly payload?: AttemptPayload; readonly executionHeadSha?: string }
 const corrupt = () => new CheckSnapshotError("check_attempt_corrupt", "Scoped check attempt history is missing, corrupt or inconsistent.");
+const gitSha = (value: unknown): value is string => typeof value === "string" && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value);
+/** Shape validation alone is not authority: bind to the native running allocation. */
+function validateResourceOrigin(row: StoredAttempt): void {
+  if (row.executionHeadSha !== undefined && !gitSha(row.executionHeadSha)) throw corrupt();
+  const resource = row.payload?.resourceApplicability;
+  if (resource === undefined) return;
+  if (row.attempt.status !== "passed" || !row.executionHeadSha) throw corrupt();
+  try {
+    const projection = validateResourceApplicabilityProjection(resource);
+    const attempt = row.attempt;
+    const origin = { providerId: attempt.providerId, runId: attempt.origin.runId, attemptId: attempt.attemptId,
+      generation: attempt.generation, inputDigest: attempt.inputDigest, profileDigest: attempt.profileDigest,
+      source: { headSha: row.executionHeadSha, treeSha: attempt.origin.candidate.treeSha }, status: "passed", superseded: false };
+    if (digestCanonical(projection.origin) !== digestCanonical(origin)) throw corrupt();
+  } catch { throw corrupt(); }
+}
 export class AttemptStore {
   readonly root: string;
   constructor(root: string) { this.root = root; }
@@ -24,7 +44,8 @@ export class AttemptStore {
     if (names.some(n => !/^[1-9][0-9]*$/.test(n) || !Number.isSafeInteger(Number(n)))) throw corrupt();
     return names.map(Number).sort((a, b) => a - b);
   }
-  async allocate(input: Omit<ScopedCheckAttempt, "attemptId" | "generation" | "status">): Promise<ScopedCheckAttempt> {
+  async allocate(input: Omit<ScopedCheckAttempt, "attemptId" | "generation" | "status">, options: { readonly executionHeadSha?: string } = {}): Promise<ScopedCheckAttempt> {
+    if (options.executionHeadSha !== undefined && !gitSha(options.executionHeadSha)) throw corrupt();
     await mkdir(this.root, { recursive: true, mode: 0o700 });
     let generation = Math.max(0, ...await this.generations()) + 1;
     for (;;) {
@@ -32,7 +53,7 @@ export class AttemptStore {
       try { await mkdir(dir, { mode: 0o700 }); }
       catch (error) { if ((error as NodeJS.ErrnoException).code === "EEXIST") { generation++; continue; } throw error; }
       const attempt: ScopedCheckAttempt = { ...input, generation, attemptId: randomUUID(), status: "running" };
-      await this.publish(path.join(dir, "running.json"), { attempt });
+      await this.publish(path.join(dir, "running.json"), { attempt, ...(options.executionHeadSha !== undefined ? { executionHeadSha: options.executionHeadSha } : {}) });
       return attempt;
     }
   }
@@ -47,10 +68,14 @@ export class AttemptStore {
   }
   async finish(attempt: ScopedCheckAttempt, status: "passed" | "failed" | "interrupted", payload: AttemptPayload): Promise<void> {
     const rows = await this.read();
-    const running = rows.find(row => row.attempt.generation === attempt.generation)?.attempt;
-    if (running?.status !== "running" || digestCanonical(running) !== digestCanonical(attempt)) throw corrupt();
-    await this.publish(path.join(this.root, String(attempt.generation), "terminal.json"), { attempt: { ...attempt, status }, payload });
+    const running = rows.find(row => row.attempt.generation === attempt.generation);
+    if (running?.attempt.status !== "running" || digestCanonical(running.attempt) !== digestCanonical(attempt)) throw corrupt();
+    const terminal: StoredAttempt = { attempt: { ...attempt, status }, payload,
+      ...(running.executionHeadSha !== undefined ? { executionHeadSha: running.executionHeadSha } : {}) };
+    validateResourceOrigin(terminal);
+    await this.publish(this.terminalPath(attempt), terminal);
   }
+  terminalPath(attempt: ScopedCheckAttempt): string { return path.join(this.root, String(attempt.generation), "terminal.json"); }
   private async load(file: string): Promise<StoredAttempt> {
     const raw = JSON.parse(await readFile(file, "utf8")) as { digest?: string; entry?: StoredAttempt };
     const row = raw.entry;
@@ -65,6 +90,7 @@ export class AttemptStore {
         !candidate || ![candidate.treeSha, candidate.deliverableDigest, candidate.identityToken, candidate.baseRef,
           candidate.baseTipSha, candidate.mergeBaseSha, candidate.workspaceId].every(nonempty)) throw corrupt();
     if (row.payload?.durationMs !== undefined && (typeof row.payload.durationMs !== "number" || !Number.isFinite(row.payload.durationMs) || row.payload.durationMs < 0)) throw corrupt();
+    validateResourceOrigin(row);
     return row;
   }
   async read(): Promise<StoredAttempt[]> {
@@ -77,7 +103,7 @@ export class AttemptStore {
         let terminal: StoredAttempt | undefined;
         try { terminal = await this.load(path.join(dir, "terminal.json")); }
         catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
-        if (terminal && (terminal.attempt.status === "running" || digestCanonical({ ...terminal.attempt, status: "running" }) !== digestCanonical(start.attempt))) throw corrupt();
+        if (terminal && (terminal.executionHeadSha !== start.executionHeadSha || terminal.attempt.status === "running" || digestCanonical({ ...terminal.attempt, status: "running" }) !== digestCanonical(start.attempt))) throw corrupt();
         rows.push(terminal ?? start);
       }
       return rows;

package/src/scoped-budget.ts

@@ -0,0 +1,20 @@
+/** The declared pre-merge budget, enforced where a selection enters the runner, before any check starts. */
+import { scopedBudgetOffenders, type HarnessConfig } from "@agent-delivery-harness/kernel";
+import { CheckSnapshotError } from "./check-snapshot.ts";
+
+/**
+ * Refuses a selection whose scoped checks declare more than `scopedExecution.budgetMs` in total, or any one
+ * of which declares more than `scopedExecution.checkBudgetMs`. The refusal names only the offending checks:
+ * those over the cap, and those that push the running total past the budget in declaration order.
+ */
+export function refuseOverBudget(config: Pick<HarnessConfig, "providers" | "scopedExecution">): void {
+  const { overCap, overBudget, totalMs } = scopedBudgetOffenders(config);
+  if (overCap.length === 0 && overBudget.length === 0) return;
+  const { budgetMs, checkBudgetMs } = config.scopedExecution!;
+  const timeout = (id: string) => config.providers.find(p => p.id === id)!.check!.timeoutMs;
+  const reasons = [
+    ...overCap.map(id => `${id} declares timeoutMs ${timeout(id)} over checkBudgetMs ${checkBudgetMs}`),
+    ...(overBudget.length ? [`${overBudget.join(", ")} ${overBudget.length === 1 ? "pushes" : "push"} the declared total to ${totalMs}ms over budgetMs ${budgetMs}`] : []),
+  ];
+  throw new CheckSnapshotError("scoped_budget_exceeded", `The scoped check selection exceeds its declared budget, so no check ran: ${reasons.join("; ")}.`);
+}