@agent-delivery-harness/cli 0.2.0 → 0.7.3

package/src/run-view.ts

@@ -0,0 +1,343 @@
+/** One operational readout for terminal, JSON and HTML; no admission decisions. */
+import type { RunEvent } from "@agent-delivery-harness/kernel";
+import {
+  projectRunProgress,
+  projectCosts,
+  costLabel,
+} from "./run-projection.ts";
+export interface RunViewItem {
+  readonly id: string;
+  readonly label: string;
+  readonly fields: readonly { label: string; value: string }[];
+  readonly artifactId?: string;
+}
+export interface RunViewSection {
+  readonly id: string;
+  readonly title: string;
+  readonly empty: string;
+  readonly items: readonly RunViewItem[];
+}
+export interface RunView {
+  readonly spec: "run-view/1";
+  readonly historical: boolean;
+  readonly asOf: string;
+  readonly authority: string;
+  readonly sections: readonly RunViewSection[];
+}
+const value = (v: unknown): string =>
+  v === undefined
+    ? "Unreported"
+    : typeof v === "string"
+      ? v
+      : JSON.stringify(v);
+const item = (
+  id: string,
+  label: string,
+  fields: Record<string, unknown>,
+  artifactId?: string,
+): RunViewItem => ({
+  id,
+  label,
+  fields: Object.entries(fields).map(([label, v]) => ({
+    label,
+    value: value(v),
+  })),
+  ...(artifactId === undefined ? {} : { artifactId }),
+});
+export function projectRunView(
+  events: readonly RunEvent[],
+  options: {
+    readonly now: string;
+    readonly historical?: boolean;
+    readonly freshnessWindowMs?: number;
+  },
+): RunView {
+  const p = projectRunProgress(events, options.now, options.freshnessWindowMs);
+  const historical = options.historical === true;
+  const costs = projectCosts(events);
+  const runCost = costs.run as Record<string, unknown>;
+  const attempts = p.activities.flatMap((a) => a.attempts);
+  const current = attempts.filter((a) => !a.superseded);
+  const sections: RunViewSection[] = [
+    {
+      id: "waiting",
+      title: "Waiting and required action",
+      empty: "No current waiting observation. Unreported waits remain unknown.",
+      items: p.waits
+        .filter((w) => w.current && !w.resolvedAt)
+        .map((w) =>
+          item(w.waitId, w.reason, {
+            Owner: w.owner,
+            "Human action required":
+              w.waitingOn === "human"
+                ? "Yes — human"
+                : w.waitingOn === "unknown"
+                  ? "Unknown"
+                  : `No — ${w.waitingOn}`,
+            "Next action": w.nextAction,
+            Scope: w.scope,
+            Attempt: w.attemptId,
+            Observed: w.startedAt,
+            Freshness: historical
+              ? "Historical observation"
+              : !Number.isFinite(Date.parse(w.startedAt))
+                ? "unknown"
+                : Date.parse(options.now) - Date.parse(w.startedAt) >
+                    (options.freshnessWindowMs ?? 300000)
+                  ? "stale"
+                  : "recent",
+            Candidate: w.candidateTreeSha,
+          }),
+        ),
+    },
+    {
+      id: "work",
+      title: "Current work",
+      empty: attempts.length === 0
+        ? "No activity observations; execution status unknown."
+        : "No active work in the latest observations. Retained attempts appear in history.",
+      items: current
+        .filter(
+          (a) => !["completed", "failed", "interrupted"].includes(a.state),
+        )
+        .map((a) =>
+          item(a.attemptId, a.activityId, {
+            Owner: a.owner,
+            Phase: a.phase,
+            State: `${a.state} (reported)`,
+            Freshness: historical ? "Historical observation" : a.freshness,
+            "Last observed": a.lastObservedAt,
+            "Elapsed since start": a.startedAt
+              ? `${Math.max(0, Math.floor((Date.parse(options.now) - Date.parse(a.startedAt)) / 1000))}s`
+              : "Unknown — start not observed",
+            "Next step": a.nextStep,
+            Candidate: a.candidateTreeSha,
+            "Lifecycle history": a.lifecycleIncomplete
+              ? "Incomplete"
+              : "Observed",
+          }),
+        ),
+    },
+    {
+      id: "reviews",
+      title: "Reviewer attempts and history",
+      empty: "No reviewer attempt observations.",
+      items: attempts
+        .filter((a) => a.lensId !== undefined || a.phase === "review")
+        .map((a) =>
+          item(a.attemptId, a.lensId ?? a.activityId, {
+            Attempt: a.attemptId,
+            Round: a.round,
+            "Round ID": a.roundId,
+            Owner: a.owner,
+            State: a.state,
+            History: a.superseded
+              ? "Superseded attempt"
+              : "Latest observed attempt",
+            Verdict: a.verdict,
+            Cost: costLabel(a.cost),
+            Candidate: a.candidateTreeSha,
+          }),
+        ),
+    },
+    {
+      id: "findings",
+      title: "Current unresolved findings",
+      empty:
+        p.findingsCoverage === "unreported"
+          ? "Unknown — detailed finding observations were not recorded."
+          : "No unresolved findings in latest reported observations; this is not approval.",
+      items: p.currentFindings
+        .filter((f) => f.payload["state"] === "unresolved")
+        .map((f) =>
+          item(String(f.payload["findingId"]), String(f.payload["findingId"]), {
+            Severity: f.payload["severity"],
+            State: "Unresolved (reported)",
+            Report: f.payload["reportId"],
+            Attempt: f.payload["attemptId"],
+            Candidate: f.payload["candidateTreeSha"],
+          }),
+        ),
+    },
+    {
+      id: "evidence",
+      title: "Evidence and candidate",
+      empty: "No evidence observations. Applicability unknown.",
+      items: events
+        .filter((e) =>
+          [
+            "gate.reported",
+            "command.completed",
+            "review.round.closed",
+          ].includes(e.kind),
+        )
+        .map((e) =>
+          item(String(e.seq), e.kind, {
+            "Reported at": e.at,
+            Candidate: e.candidateTreeSha ?? e.payload["candidateTreeSha"],
+            Observation: e.payload,
+            Authority:
+              "Reported only — Applicability unknown; no verification is run by this view",
+          }),
+        ),
+    },
+    {
+      id: "reports",
+      title: "Retained reports",
+      empty: "No report references recorded.",
+      items: p.reports.map((r) =>
+        item(
+          String(r.payload["reportId"]),
+          String(r.payload["role"]),
+          {
+            Report: r.payload["reportId"],
+            Availability: r.payload["availability"],
+            Reason: r.payload["reason"],
+            "Originating report": r.payload["originatingReportId"],
+            Lens: r.payload["lensId"],
+            Attempt: r.payload["attemptId"],
+            Candidate: r.payload["candidateTreeSha"],
+            History: r.current
+              ? "Latest observed attempt"
+              : "Historical or incomplete binding",
+          },
+          typeof r.payload["artifactId"] === "string"
+            ? r.payload["artifactId"]
+            : undefined,
+        ),
+      ),
+    },
+    {
+      id: "finish",
+      title: "Declared finish line",
+      empty: "Finish steps unreported; delivery completion unknown.",
+      items: [],
+    },
+    {
+      id: "cost",
+      title: "Reported cost",
+      empty: "Cost unreported.",
+      items: [
+        {
+          id: "review-cost",
+          label: "Review totals",
+          fields: [
+            ...item("review-cost", "Review totals", {
+              Coverage: costs.review.coverage,
+              "Unreported round entries": costs.review.unreportedEntries,
+              ...(costs.review.totals.length === 0
+                ? { Measurement: "Unreported" }
+                : {}),
+            }).fields,
+            ...costs.review.totals.map((total) => ({
+              label: `${total.reportedBy} · ${total.unit}`,
+              value:
+                total.total === null
+                  ? "Unavailable — reported sum exceeds numeric range"
+                  : `${total.total} ${total.unit}`,
+            })),
+          ],
+        },
+        item("run-cost", "Run total", {
+          Coverage: runCost["coverage"],
+          Measurement: costLabel(runCost),
+          "Reported by": runCost["reportedBy"],
+          Accounting:
+            "Run totals can include review and attempt costs. These totals are shown separately and are not added together.",
+        }),
+        ...attempts.filter((a) => a.cost !== undefined).map((a) => {
+          const cost = a.cost as Record<string, unknown>;
+          return item(`attempt-cost-${a.attemptId}`, `Attempt cost · ${a.activityId}`, {
+            Attempt: a.attemptId,
+            Owner: a.owner,
+            Phase: a.phase,
+            State: `${a.state} (reported)`,
+            History: a.superseded ? "Superseded attempt" : "Latest observed attempt",
+            Candidate: a.candidateTreeSha,
+            Coverage: cost["coverage"],
+            Measurement: costLabel(a.cost),
+            "Reported by": cost["reportedBy"],
+            Accounting: "Reported attempt measurement; not added to run or review totals, which may overlap.",
+          });
+        }),
+      ],
+    },
+    {
+      id: "activity-history",
+      title: "Activity history",
+      empty: "No completed, failed, interrupted or superseded activity observations.",
+      items: attempts
+        .filter((a) => a.superseded || ["completed", "failed", "interrupted"].includes(a.state))
+        .map((a) => item(a.attemptId, a.activityId, {
+          Attempt: a.attemptId,
+          Owner: a.owner,
+          Phase: a.phase,
+          State: `${a.state} (reported)`,
+          History: a.superseded ? "Superseded attempt" : "Latest observed attempt",
+          Freshness: historical ? "Historical observation" : a.freshness,
+          "Last observed": a.lastObservedAt,
+          Candidate: a.candidateTreeSha,
+          "Lifecycle history": a.lifecycleIncomplete ? "Incomplete" : "Observed",
+          Cost: costLabel(a.cost),
+        })),
+    },
+    {
+      id: "finding-history",
+      title: "Finding history",
+      empty: "No detailed finding history.",
+      items: p.findings.map((f) =>
+        item(String(f.seq), String(f.payload["findingId"]), {
+          State: f.payload["state"],
+          Severity: f.payload["severity"],
+          Attempt: f.payload["attemptId"],
+          Candidate: f.payload["candidateTreeSha"],
+          "Deferred issue": f.payload["deferredIssueId"],
+          Observed: f.at,
+        }),
+      ),
+    },
+  ];
+  const reviewSection = sections.find((s) => s.id === "reviews")!;
+  sections[2] = {
+    ...reviewSection,
+    items: [
+      ...events
+        .filter((e) => e.kind === "review.round.opened")
+        .map((e) =>
+          item(`round-${e.seq}`, "Declared review round", {
+            Round: e.payload["round"],
+            "Round ID": e.payload["roundId"],
+            Bound: e.payload["bound"],
+            Grace: e.payload["grace"],
+            Reopens: e.payload["reopensRoundId"],
+            Candidate: e.payload["candidateTreeSha"],
+          }),
+        ),
+      ...reviewSection.items,
+    ],
+  };
+  const finish = new Map<string, (typeof p.finishSteps)[number]>();
+  for (const step of p.finishSteps)
+    finish.set(String(step.payload["stepId"]), step);
+  sections[6] = {
+    id: "finish",
+    title: "Declared finish line",
+    empty: "Finish steps unreported; delivery completion unknown.",
+    items: [...finish.values()].map((s) =>
+      item(String(s.payload["stepId"]), String(s.payload["name"]), {
+        State: s.payload["state"],
+        Owner: s.payload["owner"],
+        Reason: s.payload["reason"],
+        Candidate: s.payload["candidateTreeSha"],
+      }),
+    ),
+  };
+  return {
+    spec: "run-view/1",
+    historical,
+    asOf: options.now,
+    authority:
+      "Self-attested observations. Applicability unknown; no permission or candidate approval is granted.",
+    sections,
+  };
+}

package/src/scoped-attempts.ts

@@ -0,0 +1,86 @@
+/** Durable per-check history; allocation order, never completion time, owns precedence. */
+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 { CheckSnapshotError } from "./check-snapshot.ts";
+import type { RecordedScopedAttemptDiagnostic } from "./scoped-diagnostics.ts";
+export interface AttemptPayload {
+  readonly outputs: readonly { readonly path: string; readonly base64: string; readonly sha256: string }[];
+  readonly durationMs?: number;
+  readonly dependencyDigest?: string;
+  readonly log?: string;
+  readonly diagnostic?: RecordedScopedAttemptDiagnostic;
+}
+export interface StoredAttempt { readonly attempt: ScopedCheckAttempt; readonly payload?: AttemptPayload }
+const corrupt = () => new CheckSnapshotError("check_attempt_corrupt", "Scoped check attempt history is missing, corrupt or inconsistent.");
+export class AttemptStore {
+  readonly root: string;
+  constructor(root: string) { this.root = root; }
+  private async generations(): Promise<number[]> {
+    let names: string[];
+    try { names = await readdir(this.root); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw error; }
+    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> {
+    await mkdir(this.root, { recursive: true, mode: 0o700 });
+    let generation = Math.max(0, ...await this.generations()) + 1;
+    for (;;) {
+      const dir = path.join(this.root, String(generation));
+      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 });
+      return attempt;
+    }
+  }
+  private async publish(target: string, entry: StoredAttempt): Promise<void> {
+    const temp = `${target}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(temp, JSON.stringify({ digest: digestCanonical(entry), entry }), { flag: "wx", mode: 0o600 });
+      // Linking a complete private file publishes atomically without replacing an
+      // already-published terminal result from this or a competing invocation.
+      await link(temp, target);
+    } finally { await unlink(temp).catch(() => undefined); }
+  }
+  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 });
+  }
+  private async load(file: string): Promise<StoredAttempt> {
+    const raw = JSON.parse(await readFile(file, "utf8")) as { digest?: string; entry?: StoredAttempt };
+    const row = raw.entry;
+    const attempt = row?.attempt;
+    const nonempty = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+    const candidate = attempt?.origin?.candidate;
+    if (!row || !attempt || raw.digest !== digestCanonical(row) || attempt.version !== "scoped-attempt/1" ||
+        !nonempty(attempt.attemptId) || !nonempty(attempt.providerId) || !nonempty(attempt.origin?.runId) ||
+        !Number.isSafeInteger(attempt.generation) || attempt.generation < 1 ||
+        !["running", "passed", "failed", "interrupted"].includes(attempt.status) ||
+        ![attempt.inputDigest, attempt.profileDigest].every(value => typeof value === "string" && /^[a-f0-9]{64}$/.test(value)) ||
+        !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();
+    return row;
+  }
+  async read(): Promise<StoredAttempt[]> {
+    try {
+      const rows: StoredAttempt[] = [];
+      for (const generation of await this.generations()) {
+        const dir = path.join(this.root, String(generation));
+        const start = await this.load(path.join(dir, "running.json"));
+        if (start.attempt.status !== "running" || start.attempt.generation !== generation) throw corrupt();
+        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();
+        rows.push(terminal ?? start);
+      }
+      return rows;
+    } catch { throw corrupt(); }
+  }
+}

package/src/scoped-candidate.ts

@@ -0,0 +1,28 @@
+/** Opt-in worktree capture through a private index; the author's staging is untouched. */
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import { promisify } from "node:util";
+import { captureGitCandidate, type CandidateCaptureOptions, type CandidateCommandRunner } from "@agent-delivery-harness/kernel";
+const exec = promisify(execFile);
+export async function captureScopedCandidate(options: CandidateCaptureOptions) {
+  const dir = await mkdtemp(path.join(tmpdir(), "delivery-index-"));
+  const env = { ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_"))), GIT_INDEX_FILE: path.join(dir, "index"), GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" };
+  const run: CandidateCommandRunner = async (command, invocation) => {
+    try {
+      const result = await exec(command[0]!, command.slice(1), { cwd: invocation.cwd, env, encoding: "buffer", maxBuffer: 64 * 1024 * 1024 });
+      return { exitCode: 0, stdout: result.stdout.toString("utf8"), ...(invocation.captureBytes ? { stdoutBase64: result.stdout.toString("base64") } : {}), stderr: result.stderr.toString("utf8") };
+    } catch (error) {
+      const failure = error as { code?: number; stdout?: Buffer; stderr?: Buffer };
+      return { exitCode: typeof failure.code === "number" ? failure.code : -1, stdout: failure.stdout?.toString("utf8") ?? "", stderr: failure.stderr?.toString("utf8") ?? "Git capture failed" };
+    }
+  };
+  try {
+    for (const args of [["read-tree", "HEAD"], ["add", "--all"]]) {
+      const result = await run(["git", ...args], { cwd: options.rootDir });
+      if (result.exitCode !== 0) throw new Error("Cannot capture source into a private index");
+    }
+    return await captureGitCandidate({ ...options, run });
+  } finally { await rm(dir, { recursive: true, force: true }); }
+}

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(); }
+}