@agent-delivery-harness/cli 0.5.0 → 0.7.4

package/src/scoped-checks.ts

@@ -0,0 +1,196 @@
+/** 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 path from "node:path";
+import { captureCheckBindings, captureCheckOutputSnapshots, candidateTreeEvidenceReader, candidateTreeSourceReader, createExecPort, digestCanonical, resolveRecordStorage, runGitCommand, scopedCheckIdentity, selectScopedCheckAttempt, sha256Hex, submitManifest,
+  type CandidateBinding, type CapturedCandidate, type ProviderRegistration, type ScopedCheckPlan, 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, type CheckSnapshot } from "./check-snapshot.ts";
+import { redactScopedOutput, scopedCommandDiagnostic, scopedDependencyDiagnostic, scopedDiagnosticFailure, type RecordedScopedAttemptDiagnostic } 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 };
+}
+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));
+    if (file === ".." || file.startsWith("../")) throw new CheckSnapshotError("check_runtime_unavailable", "A relative execution tool must stay inside the prepared tree.");
+    const bytes = await read(file);
+    if (bytes === null) throw new CheckSnapshotError("check_runtime_unavailable", "A relative execution tool is missing from the prepared tree.");
+    return { command, sha256: sha256Hex(bytes), metadata: await read.metadata(file) };
+  }
+  const candidates = command.includes(path.sep) ? [path.resolve(root, command)] : searchPath.split(path.delimiter).map(p => path.join(p, command));
+  for (const file of candidates) {
+    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 };
+  }
+  throw new CheckSnapshotError("check_runtime_unavailable", "A declared execution tool cannot be resolved and bound.");
+}
+export class ScopedChecks {
+  private readonly snapshots = new Map<string, CheckSnapshot>();
+  private readonly owned = new Map<string, Awaited<ReturnType<AttemptStore["allocate"]>>>();
+  private readonly stores = new Map<string, AttemptStore>();
+  private readonly identities = new Map<string, Awaited<ReturnType<typeof scopedCheckIdentity>>>();
+  private readonly observations = new Map<string, ScopedRuntimeObservation>();
+  private readonly runId = randomUUID();
+  private readonly submissions: (() => Promise<void>)[] = [];
+  readonly context: CommandContext;
+  readonly candidate: CapturedCandidate;
+  private constructor(context: CommandContext, candidate: CapturedCandidate) { this.context = context; this.candidate = candidate; }
+  static async create(context: CommandContext, candidate: CapturedCandidate): Promise<ScopedChecks | undefined> {
+    const providers = context.config.providers.filter(p => p.check?.scope);
+    if (!providers.length) return undefined;
+    if (context.config.scopedExecution?.version !== "scoped-execution/1") throw new CheckSnapshotError("scoped_executor_required", "Scoped checks require supported private execution profiles before preparation.");
+    const session = new ScopedChecks(context, candidate);
+    const storage = await resolveRecordStorage(context.rootDir, { storageNamespace: context.config.storageNamespace, leaf: "scoped-attempts" });
+    const read = await candidateTreeSourceReader(context.rootDir, candidate.treeSha);
+    const readEvidence = await candidateTreeEvidenceReader(context.rootDir, candidate.treeSha);
+    const listing = await runGitCommand(["git", "ls-tree", "-r", "--name-only", "-z", candidate.treeSha], { cwd: context.rootDir });
+    if (listing.exitCode !== 0) throw new CheckSnapshotError("check_snapshot_unavailable", "Cannot enumerate the prepared source tree.");
+    const inventory = listing.stdout.split("\0").filter(Boolean);
+    for (const provider of providers) {
+      const scope = provider.check!.scope!, profile = context.config.scopedExecution.profiles.find(p => p.id === scope.profile)!;
+      if (!profile) throw new CheckSnapshotError("scoped_executor_required", "A selected execution profile is unsupported.");
+      if (profile.mutableOutputs.some(o => inventory.some(f => f === o.replace(/\/$/, "") || f.startsWith(`${o.replace(/\/$/, "")}/`)))) throw new CheckSnapshotError("check_output_overlaps_source", "Mutable outputs overlap prepared source.");
+      if ((provider.check!.outputs ?? []).some(o => !profile.mutableOutputs.some(m => m.endsWith("/") ? o.startsWith(m) : o === m))) throw new CheckSnapshotError("check_output_undeclared", "Every retained output must be declared mutable in its profile.");
+      const searchPath = executionPath(context.rootDir, context.env["PATH"] ?? process.env["PATH"] ?? "/usr/bin:/bin");
+      const tools = await Promise.all([[process.execPath, "."], [provider.check!.command[0], scope.cwd], ...(profile.dependencies ? [[profile.dependencies.command[0], "."]] : [])].map(([c, cwd]) => executableIdentity(c!, context.rootDir, searchPath, cwd!, read)));
+      const observation: ScopedRuntimeObservation = { version: "scoped-runtime/1", runtimeDigest: digestCanonical({ platform: process.platform, arch: process.arch, tools, searchPath }),
+        flags: Object.fromEntries(scope.environment.filter(e => e.kind === "flag" && context.env[e.name] !== undefined).map(e => [e.name, context.env[e.name]!])),
+        credentials: Object.fromEntries(scope.environment.filter(e => e.kind === "credential").map(e => {
+          const present = context.env[e.name] !== undefined, identity = present ? profile.credentialIdentities[e.name] ?? null : null;
+          if (identity !== null && (identity === context.env[e.name] || identity === sha256Hex(context.env[e.name] ?? ""))) throw new CheckSnapshotError("check_credential_identity_invalid", "Credential identity must be an external nonsecret revision.");
+          return [e.name, { present, identity }];
+        })) };
+      session.observations.set(provider.id, observation);
+      session.identities.set(provider.id, await scopedCheckIdentity(context.config, provider, inventory, read, observation, candidate, readEvidence));
+      session.stores.set(provider.id, new AttemptStore(path.join(storage.storageDir, digestCanonical({ gate: context.config.gateId, provider: provider.id }))));
+    }
+    return session;
+  }
+  async plan(): Promise<ScopedCheckPlan> {
+    const checks: Record<string, ScopedCheckPlan["checks"][string]> = {};
+    for (const [id, identity] of this.identities) checks[id] = { inputDigest: identity.inputDigest, profileDigest: identity.profileDigest, reusable: identity.reusable, attempts: (await this.stores.get(id)!.read()).map(r => r.attempt) };
+    return { version: "scoped-plan/1", candidate: scopedCandidate(this.candidate), selectionDigest: digestCanonical(this.context.config.providers.filter(p => p.check?.scope).map(p => ({ id: p.id, check: p.check })).sort((a, b) => a.id.localeCompare(b.id))), checks };
+  }
+  private async selected(id: string): Promise<StoredAttempt | undefined> {
+    const identity = this.identities.get(id)!;
+    const rows = await this.stores.get(id)!.read();
+    const selected = selectScopedCheckAttempt(id, identity.inputDigest, identity.profileDigest, rows.map(r => r.attempt));
+    return rows.find(r => r.attempt.attemptId === selected?.attemptId);
+  }
+  readonly readOutput = async (repoPath: string, providerId: string): Promise<Uint8Array> => {
+    if (!this.identities.has(providerId)) return readFile(path.join(this.context.rootDir, repoPath));
+    const selected = await this.selected(providerId);
+    const output = selected?.attempt.status === "passed" ? selected.payload?.outputs.find(o => o.path === repoPath) : undefined;
+    if (!output || sha256Hex(Buffer.from(output.base64, "base64")) !== output.sha256) throw new CheckSnapshotError("check_output_missing", "Retained scoped output is absent or corrupt.");
+    return Buffer.from(output.base64, "base64");
+  };
+  /** No safe secret identity means a fresh attempt in every executing invocation. */
+  async fenceNonReusable(ids: readonly string[]): Promise<void> {
+    for (const id of ids) if (!this.identities.get(id)!.reusable && !this.owned.has(id)) await this.allocate(id);
+  }
+  private async allocate(id: string) {
+    const identity = this.identities.get(id)!;
+    const attempt = await this.stores.get(id)!.allocate({ version: "scoped-attempt/1", providerId: id, inputDigest: identity.inputDigest, profileDigest: identity.profileDigest, origin: { candidate: scopedCandidate(this.candidate), runId: this.runId } });
+    this.owned.set(id, attempt); return attempt;
+  }
+  async explainReuse(admitted: readonly string[]): Promise<void> {
+    for (const id of this.identities.keys()) {
+      const selected = await this.selected(id);
+      if (admitted.includes(id) && selected?.attempt.status === "passed") this.context.write(`reusing ${id}: matching inputs/profile; attempt ${selected.attempt.attemptId}`);
+      for (const row of await this.stores.get(id)!.read()) if (row.attempt.status !== "passed" && row.attempt.inputDigest !== this.identities.get(id)!.inputDigest) this.context.write(`superseded ${id}: ${row.attempt.status} attempt ${row.attempt.attemptId} has different inputs`);
+    }
+  }
+  async satisfyMechanical(): Promise<void> {
+    const ids = this.context.config.scopedExecution!.mechanicalProviders;
+    await this.fenceNonReusable(ids);
+    for (const id of ids) {
+      if ((await this.selected(id))?.attempt.status === "passed") { this.context.write(`reusing mechanical ${id}`); continue; }
+      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);
+    }
+  }
+  async submitMechanical(): Promise<void> { for (const submit of this.submissions) await submit(); this.submissions.length = 0; }
+  async execute(provider: ProviderRegistration, obligationIds: readonly string[], deferSubmission = false): Promise<void> {
+    const started = Date.now(), check = provider.check!, profile = this.context.config.scopedExecution!.profiles.find(p => p.id === check.scope!.profile)!;
+    const attempt = this.owned.get(provider.id) ?? await this.allocate(provider.id);
+    let payload: AttemptPayload = { outputs: [] }, terminal = false;
+    let diagnostic: RecordedScopedAttemptDiagnostic = { availability: "available", phase: "snapshot-setup", failure: { unavailable: "not-failed" }, command: { unavailable: "not-started" } };
+    let executionErrorCode: string | undefined;
+    const store = this.stores.get(provider.id)!;
+    const secrets = check.scope!.environment.filter(e => e.kind === "credential").map(e => this.context.env[e.name]).filter((v): v is string => !!v);
+    try {
+      const key = profile.id;
+      let snapshot = this.snapshots.get(key);
+      if (!snapshot) {
+        // Both invocation paths await each execution. Retain only consecutive
+        // same-profile reuse; durable outputs no longer need the private tree.
+        for (const [previousKey, previous] of this.snapshots) {
+          await previous.cleanup();
+          this.snapshots.delete(previousKey);
+        }
+        snapshot = await createCheckSnapshot({ rootDir: this.context.rootDir, candidate: this.candidate, outputs: profile.mutableOutputs, gitContext: profile.gitContext ?? "full", environment: { PATH: this.context.env["PATH"] ?? process.env["PATH"] ?? "/usr/bin:/bin" }, ...(profile.dependencies ? { dependencies: profile.dependencies } : {}), ...(this.context.signal ? { signal: this.context.signal } : {}),
+          onDependencyResult: (result, durationMs) => { diagnostic = { ...diagnostic, dependency: scopedDependencyDiagnostic(result, durationMs, secrets) }; },
+        });
+        this.snapshots.set(key, snapshot);
+      }
+      diagnostic = { ...diagnostic, phase: "pre-command-verification" };
+      await snapshot.verify();
+      // A sibling or dependency setup cannot supply this command's result.
+      for (const output of check.outputs ?? []) await rm(path.join(snapshot.rootDir, output), { recursive: true, force: true });
+      const injected = Object.fromEntries(check.scope!.environment.filter(e => this.context.env[e.name] !== undefined).map(e => [e.name, this.context.env[e.name]!]));
+      this.context.write(`checking ${provider.id}: attempt ${attempt.attemptId}`);
+      diagnostic = { ...diagnostic, phase: "command" };
+      const commandHome = path.join(snapshot.commandRoot, attempt.attemptId, "home"), commandTemp = path.join(snapshot.commandRoot, attempt.attemptId, "tmp");
+      await mkdir(commandHome, { recursive: true }); await mkdir(commandTemp, { recursive: true });
+      diagnostic = { ...diagnostic, command: { unavailable: "not-completed" } };
+      const result = await createExecPort().run({ command: check.command[0], args: check.command.slice(1), cwd: path.join(snapshot.rootDir, check.scope!.cwd), env: { ...snapshot.environment, ...injected, HOME: commandHome, TMPDIR: commandTemp }, timeoutMs: check.timeoutMs, maxBuffer: 1024 * 1024, ...(this.context.signal ? { signal: this.context.signal } : {}) });
+      const redact = (s: string) => redactScopedOutput(s, secrets);
+      executionErrorCode = result.errorCode;
+      diagnostic = { ...diagnostic, command: scopedCommandDiagnostic(result, secrets) };
+      payload = { outputs: [], durationMs: Date.now() - started, log: redact(`${result.stdout}\n${result.stderr}`).slice(-4000), dependencyDigest: snapshot.dependencyDigest };
+      if (result.code !== 0 || this.context.signal?.aborted) throw new CheckSnapshotError("check_command_failed", `Declared scoped check ${provider.id} did not complete successfully (exit ${result.code}).`);
+      diagnostic = { ...diagnostic, phase: "post-command-verification" };
+      await snapshot.verify();
+      diagnostic = { ...diagnostic, phase: "output-capture" };
+      const outputs = await captureCheckOutputSnapshots(snapshot.rootDir, check.outputs ?? []);
+      if (!outputs || outputs.some(o => secrets.some(secret => Buffer.from(o.base64, "base64").includes(Buffer.from(secret))))) throw new CheckSnapshotError("check_output_missing", "A retained output is absent, corrupt, escaped or contains credential bytes.");
+      payload = { ...payload, outputs, diagnostic: { ...diagnostic, phase: "complete" } };
+      await store.finish(attempt, "passed", payload); terminal = true;
+      const scopedPlan = await this.plan();
+      const wiring = await this.context.wire();
+      const binding = (await captureCheckBindings(this.context.rootDir, this.context.config, this.candidate, { ...wiring.storageOptions, scopedPlan, readOutput: this.readOutput }))[provider.id];
+      if (!binding || binding.scopedAttemptDigest !== digestCanonical({ ...attempt, status: "passed" })) throw new CheckSnapshotError("check_attempt_superseded", "A newer attempt superseded this completion before evidence publication.");
+      const runId = attempt.attemptId, finalPassId = "pass-1";
+      const allocation = await this.context.artifacts.allocateRunRoot({ providerId: provider.id, runId });
+      if (!allocation.ok) throw new CheckSnapshotError("check_artifact_unavailable", "Cannot allocate scoped check evidence.");
+      const artifacts: { path: string; sha256: string; role: string }[] = [];
+      const write = async (name: string, value: unknown, role: string) => { const text = JSON.stringify(value); await this.context.artifacts.writeTextFile(path.join(allocation.runRoot.path, name), text); artifacts.push({ path: name, sha256: sha256Hex(text), role }); };
+      for (const [index, output] of outputs.entries()) await write(`check-output-${index}.json`, { path: output.path, base64: output.base64 }, "check-output");
+      const claim = { verdict: "green", exitCode: 0, binding };
+      await write("check-result.json", { providerId: provider.id, runId, finalPassId, ...claim }, "check-result");
+      await write("scoped-inputs.json", { observation: this.observations.get(provider.id), attempt: { ...attempt, status: "passed" }, durationMs: payload.durationMs, dependencyDigest: payload.dependencyDigest }, "scoped-inputs");
+      const c = this.candidate;
+      const manifest = { spec: "delivery-evidence/1", provider: { id: provider.id, runId, finalPassId }, candidate: { vcs: "git", treeSha: c.treeSha, headSha: c.headSha, deliverable: c.deliverable, base: c.base, workspaceId: c.workspaceId }, runHistory: [{ preparedTreeSha: c.treeSha, evaluatedInPassId: finalPassId }], artifacts, attestation: { level: "self", signatures: [] }, recordedAt: new Date().toISOString(), claims: obligationIds.map(obligation => ({ obligation, payloadSpec: "checks.passed/1", payload: claim })) };
+      const manifestPath = path.join(allocation.runRoot.path, "manifest.json"); await this.context.artifacts.writeTextFile(manifestPath, JSON.stringify(manifest));
+      const submit = async () => {
+      const outcome = await submitManifest({ rootDir: this.context.rootDir, config: this.context.config, manifestPath }, { captureCandidate: wiring.captureCandidate, artifacts: this.context.artifacts, ...wiring.storageOptions, scopedPlan: await this.plan(), readOutput: this.readOutput });
+      if (outcome.status !== "accepted") throw new CheckSnapshotError("check_evidence_rejected", outcome.blockers.map(b => b.code).join(", "));
+      };
+      if (deferSubmission) this.submissions.push(submit); else await submit();
+      this.context.write(`passed ${provider.id}: ${Date.now() - started}ms including snapshot setup; retained ${runId}`);
+    } catch (error) {
+      if (!terminal) await store.finish(attempt, this.context.signal?.aborted ? "interrupted" : "failed", { ...payload, durationMs: Date.now() - started,
+        diagnostic: { ...diagnostic, failure: scopedDiagnosticFailure(error, executionErrorCode) },
+        ...(error instanceof CheckSnapshotError ? { log: `${payload.log ?? ""}\n${error.code}`.slice(-4000) } : {}) });
+      const damaged = this.snapshots.get(profile.id);
+      this.snapshots.delete(profile.id);
+      await damaged?.cleanup();
+      throw error;
+    }
+  }
+  async cleanup(): Promise<void> { for (const snapshot of this.snapshots.values()) await snapshot.cleanup(); this.snapshots.clear(); }
+}

package/src/scoped-diagnostics.ts

@@ -0,0 +1,124 @@
+import path from "node:path";
+import { digestCanonical, resolveRecordStorage, type ExecOutcome, type HarnessConfig, type ScopedCheckAttempt } from "@agent-delivery-harness/kernel";
+import { AttemptStore } from "./scoped-attempts.ts";
+import { CheckSnapshotError } from "./check-snapshot.ts";
+import { projectScopedAttempt } from "./scoped-observations.ts";
+
+const phases = ["snapshot-setup", "pre-command-verification", "command", "post-command-verification", "output-capture", "complete"] as const;
+const failureCodes = ["check_snapshot_interrupted", "check_snapshot_timeout", "check_snapshot_unavailable", "check_snapshot_escape", "check_snapshot_drift", "check_snapshot_cleanup_failed", "check_dependency_source_overlap", "check_dependency_failed", "check_command_failed", "check_output_missing", "check_attempt_superseded", "check_artifact_unavailable", "check_evidence_rejected"] as const;
+const executionCodes = ["ENOENT", "EACCES", "EPERM", "ABORT_ERR", "ERR_CHILD_PROCESS_STDIO_MAXBUFFER", "SIGKILL", "SIGTERM", "execution_failed"] as const;
+export type ScopedDiagnosticPhase = typeof phases[number];
+export type ScopedDiagnosticFailureCode = typeof failureCodes[number];
+export type ScopedDiagnosticExecutionCode = typeof executionCodes[number];
+export type ScopedDiagnosticCommand =
+  | { readonly exitCode: number | null; readonly outputTail: string; readonly truncated: boolean }
+  | { readonly unavailable: "not-started" | "not-completed" };
+export interface ScopedDependencyDiagnostic {
+  readonly durationMs: number;
+  readonly executionErrorCode?: ScopedDiagnosticExecutionCode;
+  readonly command: ScopedDiagnosticCommand;
+}
+export interface RecordedScopedAttemptDiagnostic {
+  readonly availability: "available";
+  readonly phase: ScopedDiagnosticPhase;
+  readonly failure: { readonly code: ScopedDiagnosticFailureCode; readonly executionErrorCode?: ScopedDiagnosticExecutionCode }
+    | { readonly unavailable: "not-failed" | "unclassified" };
+  readonly command: ScopedDiagnosticCommand;
+  /** Present only when this attempt actually ran dependency setup; never borrowed from a reused snapshot. */
+  readonly dependency?: ScopedDependencyDiagnostic;
+}
+export type ScopedAttemptDiagnostic = RecordedScopedAttemptDiagnostic
+  | { readonly availability: "unavailable"; readonly reason: "legacy" | "running" };
+export interface ScopedCheckDiagnostics {
+  readonly version: "scoped-check-diagnostics/1";
+  readonly providers: readonly {
+    readonly providerId: string;
+    readonly attempts: readonly (ScopedCheckAttempt & { readonly durationMs?: number; readonly diagnostic: ScopedAttemptDiagnostic })[];
+  }[];
+  readonly unavailableAttemptIds: readonly string[];
+}
+
+export function scopedDiagnosticFailure(error: unknown, executionErrorCode?: string): RecordedScopedAttemptDiagnostic["failure"] {
+  if (!(error instanceof CheckSnapshotError) || !(failureCodes as readonly string[]).includes(error.code)) return { unavailable: "unclassified" };
+  return { code: error.code as ScopedDiagnosticFailureCode,
+    ...((executionCodes as readonly string[]).includes(executionErrorCode ?? "") ? { executionErrorCode: executionErrorCode as ScopedDiagnosticExecutionCode } : {}) };
+}
+export function redactScopedOutput(text: string, secrets: readonly string[]): string {
+  return [...secrets].filter(Boolean).sort((a, b) => b.length - a.length).reduce((value, secret) => value.split(secret).join("[REDACTED]"), text);
+}
+export function scopedCommandDiagnostic(result: ExecOutcome, secrets: readonly string[]): ScopedDiagnosticCommand {
+  // execFile can clip a fully emitted credential before full-value redaction.
+  // The typed execution failure remains available; this partial capture is not safe to export.
+  if (result.errorCode === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") return { unavailable: "not-completed" };
+  const numericExit = result.errorCode === undefined || result.errorCode === String(result.code);
+  if (!numericExit && result.stdout.length + result.stderr.length === 0) return { unavailable: ["ENOENT", "EACCES", "EPERM"].includes(result.errorCode!) ? "not-started" : "not-completed" };
+  const redacted = redactScopedOutput(`${result.stdout}\n${result.stderr}`, secrets);
+  return { exitCode: numericExit ? result.code : null, outputTail: redacted.slice(-4000), truncated: redacted.length > 4000 };
+}
+
+export function scopedDependencyDiagnostic(result: ExecOutcome, durationMs: number, secrets: readonly string[]): ScopedDependencyDiagnostic {
+  return { durationMs, command: scopedCommandDiagnostic(result, secrets),
+    ...((executionCodes as readonly string[]).includes(result.errorCode ?? "") ? { executionErrorCode: result.errorCode as ScopedDiagnosticExecutionCode } : {}) };
+}
+
+function projectDiagnostic(value: unknown): RecordedScopedAttemptDiagnostic {
+  const corrupt = (): never => { throw new CheckSnapshotError("check_attempt_corrupt", "Selected scoped diagnostics are malformed."); };
+  const object = (v: unknown): Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v) ? v as Record<string, unknown> : corrupt();
+  const row = object(value), failure = object(row["failure"]);
+  if (row["availability"] !== "available" || !(phases as readonly unknown[]).includes(row["phase"])) return corrupt();
+  let safeFailure: RecordedScopedAttemptDiagnostic["failure"];
+  if ("unavailable" in failure) {
+    if (typeof failure["unavailable"] !== "string" || !["not-failed", "unclassified"].includes(failure["unavailable"]) || "code" in failure || "executionErrorCode" in failure) return corrupt();
+    safeFailure = { unavailable: failure["unavailable"] as "not-failed" | "unclassified" };
+  } else {
+    if (!(failureCodes as readonly unknown[]).includes(failure["code"]) || ("executionErrorCode" in failure && !(executionCodes as readonly unknown[]).includes(failure["executionErrorCode"]))) return corrupt();
+    safeFailure = { code: failure["code"] as ScopedDiagnosticFailureCode, ...("executionErrorCode" in failure ? { executionErrorCode: failure["executionErrorCode"] as ScopedDiagnosticExecutionCode } : {}) };
+  }
+  const commandDiagnostic = (value: unknown): ScopedDiagnosticCommand => {
+    const command = object(value);
+    if ("unavailable" in command) {
+      if (typeof command["unavailable"] !== "string" || !["not-started", "not-completed"].includes(command["unavailable"]) || "exitCode" in command || "outputTail" in command || "truncated" in command) return corrupt();
+      return { unavailable: command["unavailable"] as "not-started" | "not-completed" };
+    }
+    if (!(command["exitCode"] === null || typeof command["exitCode"] === "number" && Number.isSafeInteger(command["exitCode"]) && command["exitCode"] >= 0) || typeof command["outputTail"] !== "string" || command["outputTail"].length > 4000 || typeof command["truncated"] !== "boolean") return corrupt();
+    return { exitCode: command["exitCode"] as number | null, outputTail: command["outputTail"], truncated: command["truncated"] };
+  };
+  let dependency: ScopedDependencyDiagnostic | undefined;
+  if ("dependency" in row) {
+    const value = object(row["dependency"]);
+    if (typeof value["durationMs"] !== "number" || !Number.isFinite(value["durationMs"]) || value["durationMs"] < 0 ||
+        ("executionErrorCode" in value && !(executionCodes as readonly unknown[]).includes(value["executionErrorCode"]))) return corrupt();
+    dependency = { durationMs: value["durationMs"], command: commandDiagnostic(value["command"]),
+      ...("executionErrorCode" in value ? { executionErrorCode: value["executionErrorCode"] as ScopedDiagnosticExecutionCode } : {}) };
+  }
+  return { availability: "available", phase: row["phase"] as ScopedDiagnosticPhase, failure: safeFailure, command: commandDiagnostic(row["command"]),
+    ...(dependency === undefined ? {} : { dependency }) };
+}
+
+/** Read at most 100 explicit attempts. No logs from legacy payloads, no writes,
+ * and no claim of applicability/admission. Unselected provider history is ignored. */
+export async function readScopedCheckDiagnostics(input: {
+  readonly rootDir: string;
+  readonly config: Pick<HarnessConfig, "gateId" | "storageNamespace" | "providers">;
+  readonly attemptIds: readonly string[];
+}): Promise<ScopedCheckDiagnostics> {
+  const { rootDir, config, attemptIds } = input;
+  if (!Array.isArray(attemptIds) || attemptIds.length > 100 || attemptIds.some(id => typeof id !== "string" || !id.length || id.length > 128) || new Set(attemptIds).size !== attemptIds.length) throw new CheckSnapshotError("check_diagnostics_request_invalid", "Diagnostics require at most 100 unique nonempty attempt identifiers.");
+  const requested = new Set(attemptIds), seen = new Set<string>();
+  const providers: ScopedCheckDiagnostics["providers"][number][] = [];
+  const storage = await resolveRecordStorage(rootDir, { storageNamespace: config.storageNamespace, leaf: "scoped-attempts" });
+  for (const provider of config.providers.filter(p => p.check?.scope !== undefined)) {
+    const rows = requested.size ? await new AttemptStore(path.join(storage.storageDir, digestCanonical({ gate: config.gateId, provider: provider.id }))).read() : [];
+    if (rows.some(row => row.attempt.providerId !== provider.id)) throw new CheckSnapshotError("check_attempt_corrupt", "Scoped history belongs to a different provider.");
+    const attempts: ScopedCheckDiagnostics["providers"][number]["attempts"][number][] = [];
+    for (const { attempt, payload } of rows.filter(row => requested.has(row.attempt.attemptId))) {
+      if (seen.has(attempt.attemptId)) throw new CheckSnapshotError("check_attempt_corrupt", "A requested attempt identifier is ambiguous.");
+      seen.add(attempt.attemptId);
+      const diagnostic: ScopedAttemptDiagnostic = attempt.status === "running" ? { availability: "unavailable", reason: "running" }
+        : payload?.diagnostic === undefined ? { availability: "unavailable", reason: "legacy" } : projectDiagnostic(payload.diagnostic);
+      attempts.push({ ...projectScopedAttempt(attempt, payload?.durationMs), diagnostic });
+    }
+    providers.push({ providerId: provider.id, attempts });
+  }
+  return { version: "scoped-check-diagnostics/1", providers, unavailableAttemptIds: attemptIds.filter(id => !seen.has(id)) };
+}

package/src/scoped-observations.ts

@@ -0,0 +1,51 @@
+import path from "node:path";
+import { digestCanonical, resolveRecordStorage, type HarnessConfig, type ScopedCheckAttempt } from "@agent-delivery-harness/kernel";
+import { AttemptStore } from "./scoped-attempts.ts";
+import { CheckSnapshotError } from "./check-snapshot.ts";
+
+export interface ScopedCheckObservations {
+  readonly version: "scoped-check-observations/1";
+  readonly providers: readonly {
+    readonly providerId: string;
+    readonly attempts: readonly (ScopedCheckAttempt & { readonly durationMs?: number })[];
+  }[];
+}
+
+export function projectScopedAttempt(attempt: ScopedCheckAttempt, durationMs?: number): ScopedCheckAttempt & { readonly durationMs?: number } {
+  return {
+    version: attempt.version, providerId: attempt.providerId, attemptId: attempt.attemptId,
+    generation: attempt.generation, inputDigest: attempt.inputDigest, profileDigest: attempt.profileDigest,
+    status: attempt.status, origin: { runId: attempt.origin.runId, candidate: {
+      treeSha: attempt.origin.candidate.treeSha, deliverableDigest: attempt.origin.candidate.deliverableDigest,
+      identityToken: attempt.origin.candidate.identityToken, baseRef: attempt.origin.candidate.baseRef,
+      baseTipSha: attempt.origin.candidate.baseTipSha, mergeBaseSha: attempt.origin.candidate.mergeBaseSha,
+      workspaceId: attempt.origin.candidate.workspaceId,
+    } }, ...(durationMs === undefined ? {} : { durationMs }),
+  };
+}
+
+/**
+ * Read retained attempts for the supplied scoped providers, in configuration
+ * order and ascending generation order. This creates no directories or evidence.
+ * Providers removed from this supplied configuration are not inventoried.
+ * Absent history is empty; corrupt selected history throws. Durations are reported only
+ * when recorded by the executor. These observations make no statement about
+ * reuse, current applicability or admission; use the gate/verify for those.
+ */
+export async function readScopedCheckObservations(input: {
+  readonly rootDir: string;
+  readonly config: Pick<HarnessConfig, "gateId" | "storageNamespace" | "providers">;
+}): Promise<ScopedCheckObservations> {
+  const { rootDir, config } = input;
+  const storage = await resolveRecordStorage(rootDir, { storageNamespace: config.storageNamespace, leaf: "scoped-attempts" });
+  const providers: ScopedCheckObservations["providers"][number][] = [];
+  for (const provider of config.providers.filter(provider => provider.check?.scope !== undefined)) {
+    const store = new AttemptStore(path.join(storage.storageDir, digestCanonical({ gate: config.gateId, provider: provider.id })));
+    const retained = await store.read();
+    if (retained.some(row => row.attempt.providerId !== provider.id)) {
+      throw new CheckSnapshotError("check_attempt_corrupt", "Scoped check attempt history belongs to a different provider.");
+    }
+    providers.push({ providerId: provider.id, attempts: retained.map(({ attempt, payload }) => projectScopedAttempt(attempt, payload?.durationMs)) });
+  }
+  return { version: "scoped-check-observations/1", providers };
+}

package/src/snapshot-inventory-worker.ts

@@ -0,0 +1,40 @@
+/** Inline so the distributed single-file runtime owns the worker bytes too.
+ * Only Node builtins are available; no author code or credentials are loaded. */
+export const snapshotInventoryWorker = String.raw`
+import { lstat, readFile, readdir, readlink, realpath } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+const { root, outputs, excludeDependencies, forbidGit } = JSON.parse(process.env.DELIVERY_SNAPSHOT_REQUEST);
+const entries = [];
+const inside = target => {
+  const relative = path.relative(root, target);
+  return relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative);
+};
+const escape = () => { throw { code: 'check_snapshot_escape' }; };
+const walk = async relative => {
+  if (relative === '.git' || (excludeDependencies && relative.split('/').includes('node_modules')) ||
+      outputs.some(o => o.endsWith('/') ? relative === o.slice(0, -1) || relative.startsWith(o) : relative === o)) return;
+  const absolute = path.join(root, relative), stat = await lstat(absolute);
+  if (stat.isSymbolicLink()) {
+    const target = await readlink(absolute);
+    if (path.isAbsolute(target) || !inside(path.resolve(path.dirname(absolute), target))) escape();
+    try { if (!inside(await realpath(absolute))) escape(); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    entries.push([relative, 'link', target]);
+  } else if (stat.isDirectory()) {
+    for (const name of (await readdir(absolute)).sort()) await walk(relative ? relative + '/' + name : name);
+  } else if (stat.isFile()) {
+    entries.push([relative, stat.mode & 0o111, createHash('sha256').update(await readFile(absolute)).digest('hex')]);
+  } else escape();
+};
+try {
+  if (forbidGit && await lstat(path.join(root, '.git')).then(() => true, error => { if (error.code === 'ENOENT') return false; throw error; })) throw { code: 'check_snapshot_drift' };
+  await walk('');
+  // Tuples contain only arrays, strings and permission integers: JSON.stringify
+  // has exactly the same bytes as canonical JSON for this restricted shape.
+  process.stdout.write(JSON.stringify({ digest: createHash('sha256').update(JSON.stringify(entries)).digest('hex') }));
+} catch (error) {
+  process.stdout.write(JSON.stringify({ code: ['check_snapshot_escape', 'check_snapshot_drift'].includes(error.code) ? error.code : 'check_snapshot_unavailable' }));
+  process.exitCode = 1;
+}
+`;