@piagent/platform 1.6.1 → 1.7.1

package/scripts/benchmark-budget-publication.mjs

@@ -0,0 +1,228 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { benchmarkBudgetDigest } from "../packages/piagent-core/benchmark/benchmark-budget-governor.js";
+import { openProductionBenchmarkCampaign, productionCampaignExpectedAttempts,
+  publicProductionBenchmarkCampaignEvidence } from "../packages/piagent-core/benchmark/benchmark-campaign.js";
+import { inspectBenchmarkLedger } from "../packages/piagent-core/benchmark/benchmark-ledger.js";
+import { writeBenchmarkRunManifest, writePrivateAtomic } from "../packages/piagent-core/benchmark/benchmark-forensics.js";
+import { benchmarkTrustChecklist } from "../packages/piagent-core/benchmark/benchmark-matrix.js";
+import { renderBenchmarkText, renderBenchmarkHtml, renderBenchmarkMarkdown } from "../packages/piagent-core/benchmark/benchmark-report.js";
+import { acquireBenchmarkRunLock } from "../packages/piagent-core/benchmark/benchmark-run-lock.js";
+import { BENCHMARK_BUDGET_CONTEXT, assertBenchmarkBudgetPolicyUnchanged } from "./benchmark-budget-runtime.mjs";
+
+const hash = value => crypto.createHash("sha256").update(value).digest("hex");
+const json = value => `${JSON.stringify(value, null, 2)}\n`;
+const same = (a, b) => benchmarkBudgetDigest(a) === benchmarkBudgetDigest(b);
+const thresholds = new Set(["session-cap", "fresh-token-threshold", "active-wall-threshold"]);
+const fields = ["input", "output", "cacheRead", "cacheWrite", "reasoning", "fresh", "total"];
+function fail(message) {
+  throw Object.assign(new Error(`Benchmark budget publication: ${message}`), { code: "BENCHMARK_BUDGET_PUBLICATION_DENIED", exitCode: 1 });
+}
+function read(file) {
+  const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+  try {
+    if (!fs.fstatSync(descriptor).isFile()) fail("receipt or evidence must be a regular file");
+    const raw = fs.readFileSync(descriptor); return { value: JSON.parse(raw), sha256: hash(raw) };
+  } finally { fs.closeSync(descriptor); }
+}
+function receiptPath(identity, stageId, suffix = "json") {
+  if (!/^[a-f0-9]{32}$/.test(stageId ?? "")) fail("invalid launcher stage identity");
+  const root = `${identity.statePath}.launcher-receipts`;
+  if (fs.existsSync(root) && (!fs.lstatSync(root).isDirectory() || fs.lstatSync(root).isSymbolicLink())) fail("receipt directory is not canonical");
+  return path.join(root, `${stageId}.${suffix}`);
+}
+function writeNew(file, value) {
+  if (fs.existsSync(file)) fail("receipt already exists; refusing favorable regeneration");
+  writePrivateAtomic(file, json(value));
+}
+function readState(control) {
+  const envelope = read(control.identity.statePath).value;
+  if (envelope.schemaVersion !== 1 || envelope.stateDigest !== benchmarkBudgetDigest(envelope.state)
+    || !same(envelope.state.policy, control.policy) || !same(envelope.state.binding, control.binding)
+    || envelope.state.policyDigest !== benchmarkBudgetDigest(control.policy)
+    || envelope.state.bindingDigest !== benchmarkBudgetDigest(control.binding)) fail("state identity or integrity mismatch");
+  return envelope;
+}
+function stageProof(state, stageId) {
+  const index = state.stages.findIndex(stage => stage.stageId === stageId);
+  if (index < 0) fail("stage missing from budget state");
+  const ids = new Set(state.stages.slice(0, index + 1).map(stage => stage.stageId));
+  const prefix = state.attempts.filter(attempt => ids.has(attempt.stageId));
+  return { stageDigest: benchmarkBudgetDigest(state.stages[index]), attemptPrefixDigest: benchmarkBudgetDigest(prefix), attemptCount: prefix.length };
+}
+
+// A closed governor stage alone is not evidence that its parent completed cleanup.
+// A crash after endStage but before the receipt stays fail-closed on later resume.
+export function assertBenchmarkBudgetParentReceipts(control) {
+  if (!control || !fs.existsSync(control.identity.statePath)) return;
+  const { state } = readState(control);
+  for (const stage of state.stages) {
+    if (stage.status !== "closed") fail("prior launcher stage lacks a closed parent receipt");
+    let receipt;
+    try { receipt = read(receiptPath(control.identity, stage.stageId)).value; }
+    catch { fail("prior launcher-final receipt is missing or corrupt"); }
+    if (receipt.kind !== "benchmark-launcher-final-v1" || receipt.closureAllowed !== true
+      || !same(receipt.budgetIdentity, control.identity) || receipt.policyDigest !== state.policyDigest
+      || receipt.bindingDigest !== state.bindingDigest || !same(receipt.stageProof, stageProof(state, stage.stageId))) {
+      fail("prior launcher-final receipt is failed or belongs to a different stage identity");
+    }
+  }
+}
+
+function withhold(report, reason) {
+  report.comparison.tokenClaimAllowed = false;
+  report.comparison.tokenClaimUnavailableReason = reason;
+  if (report.goalAssessment) {
+    report.goalAssessment.claimAllowed = false;
+    if (report.goalAssessment.status === "GOAL_PASS") report.goalAssessment.status = "GOAL_CLAIM_WITHHELD";
+    report.goalAssessment.claimFailures = [...new Set([...(report.goalAssessment.claimFailures ?? []), reason])];
+  }
+}
+
+// Called only after measurement adjudication. It never alters the verdict or observed metrics.
+export function deferBenchmarkBudgetPublication({ report, manifest, runRoot,
+  expectedChildExitCode = process.exitCode ?? 0,
+  stageId = JSON.parse(process.env[BENCHMARK_BUDGET_CONTEXT] ?? "null")?.stageId }) {
+  if (!manifest.budgetControl) return;
+  if (path.resolve(runRoot) !== runRoot) fail("noncanonical report root");
+  const identity = manifest.budgetControl;
+  const checkpointPath = receiptPath(identity, stageId, "pending-report.json");
+  const eligibility = { tokenClaimAllowed: report.comparison.tokenClaimAllowed === true,
+    tokenClaimUnavailableReason: report.comparison.tokenClaimUnavailableReason ?? null,
+    goal: report.goalAssessment ? { claimAllowed: report.goalAssessment.claimAllowed === true,
+      status: report.goalAssessment.status, claimFailures: report.goalAssessment.claimFailures ?? [] } : null };
+  report.publicationAuthorization = { schemaVersion: 1, status: "pending-launcher-finalization", allowed: false,
+    stageId, policySha256: identity.sha256,
+    explanation: "Measurement verdict and observed metrics are provisional; no claim until an identity-bound parent receipt confirms cleanup, exact usage, and policy continuity." };
+  withhold(report, "pending-launcher-finalization");
+  report.trustChecklist = benchmarkTrustChecklist(report);
+  writeNew(checkpointPath, { schemaVersion: 1, kind: "benchmark-pending-publication-v1", stageId,
+    budgetIdentity: identity, runRoot, runId: manifest.runId, configurationDigest: manifest.configurationDigest,
+    reportSha256: hash(json(report)), manifestSha256: read(path.join(runRoot, "run-manifest.json")).sha256,
+    expectedChildExitCode, eligibility });
+}
+
+function validateAccounting(control, stageId, accounting, state) {
+  if (!accounting || accounting.launcherSucceeded !== true || accounting.launcherErrors?.length !== 0
+    || accounting.processCleanup?.cleanupConfirmed !== true || accounting.usageComplete !== true
+    || accounting.unknownAttempts !== 0 || accounting.inFlightAttempts !== 0 || accounting.activeWallTimeExact !== true
+    || state.activeWallTimeExact !== true || state.stages.some(stage => stage.status !== "closed")
+    || state.stages.at(-1)?.stageId !== stageId || state.attempts.some(attempt => attempt.status !== "exact")
+    || state.stopReasons.some(reason => !thresholds.has(reason))) fail("launcher cleanup, policy, usage, or finalization is not valid");
+  const tokens = Object.fromEntries(fields.map(field => [field, state.attempts.reduce((sum, attempt) => sum + attempt.usage[field], 0)]));
+  const wall = state.stages.reduce((sum, stage) => sum + stage.elapsedMs, 0);
+  if (!same(accounting.stages, state.stages) || !same(accounting.stopReasons, state.stopReasons)
+    || accounting.policyDigest !== state.policyDigest || accounting.bindingDigest !== state.bindingDigest
+    || accounting.providerStartedAttempts !== state.attempts.length || accounting.exactAttempts !== state.attempts.length
+    || accounting.freshTokens !== tokens.fresh || !same(accounting.knownExactTokens, tokens)
+    || accounting.activeWallTimeMs !== wall || !same(accounting.overshoot, {
+      freshTokens: Math.max(0, tokens.fresh - control.policy.freshTokenThreshold),
+      activeWallTimeMs: Math.max(0, wall - control.policy.activeWallTimeMsThreshold) })) fail("final accounting differs from durable budget state");
+}
+
+function pendingReport(control, stageId, state) {
+  const checkpointFile = receiptPath(control.identity, stageId, "pending-report.json");
+  const reportFile = path.join(control.binding.runRoot, "report.json");
+  if (!fs.existsSync(checkpointFile) && !fs.existsSync(reportFile)) return null;
+  const pending = read(checkpointFile).value, reportData = read(reportFile);
+  const manifestData = read(path.join(control.binding.runRoot, "run-manifest.json"));
+  const report = reportData.value, manifest = manifestData.value;
+  const ledger = inspectBenchmarkLedger(path.join(control.binding.runRoot, "runs.jsonl"));
+  const order = manifest.order.map((item, index) => ({ orderIndex: index + 1, ...item }));
+  if (pending.kind !== "benchmark-pending-publication-v1" || pending.stageId !== stageId
+    || !same(pending.budgetIdentity, control.identity) || !same(manifest.budgetControl, control.identity)
+    || pending.runRoot !== control.binding.runRoot || pending.runId !== manifest.runId || report.runId !== manifest.runId
+    || pending.reportSha256 !== reportData.sha256 || pending.manifestSha256 !== manifestData.sha256
+    || pending.configurationDigest !== manifest.configurationDigest || report.environment.configurationDigest !== manifest.configurationDigest
+    || manifest.candidateProvenance?.contentDigest !== control.binding.candidateDigest
+    || report.environment.candidateProvenance?.contentDigest !== control.binding.candidateDigest
+    || manifest.suiteDigest !== control.binding.suiteDigest || report.environment.suiteDigest !== control.binding.suiteDigest
+    || !same(order, control.binding.plannedAttempts) || !same(manifest.ledger, ledger.binding)
+    || !same(report.ledger, ledger.binding) || !same(report.runs, ledger.records)
+    || state.attempts.length !== order.length || !same(productionCampaignExpectedAttempts(report.runs), state.attempts.map(attempt => {
+      const { attemptId, orderIndex, scenarioId, surface, repeat, infrastructureAttempt } = attempt;
+      return { attemptId, orderIndex, scenarioId, surface, repeat, infrastructureAttempt };
+    })) || report.runs.some((run, index) => fields.some(field => run.usage?.[field] !== state.attempts[index].usage?.[field]))
+    || report.publicationAuthorization?.stageId !== stageId || report.publicationAuthorization?.allowed !== false
+    || report.comparison.tokenClaimAllowed !== false || report.goalAssessment?.claimAllowed === true) fail("pending report is not the exact verified core publication");
+  return { pending, report, manifest };
+}
+
+function publish(control, receipt, publication) {
+  const { report, manifest, pending } = publication, root = control.binding.runRoot;
+  const allowed = receipt.publicationAllowed;
+  let campaign;
+  try {
+    if (manifest.campaign) {
+      const binding = manifest.campaign;
+      campaign = openProductionBenchmarkCampaign({ registryBase: path.dirname(path.dirname(binding.campaignRoot)),
+        ...binding, existingBinding: binding });
+      campaign.sealForClaim(report.runs);
+      manifest.campaignEvidence = campaign.finalizeClaim({ allowed,
+        reason: `launcher-final-receipt:${benchmarkBudgetDigest(receipt)}:${allowed ? "release-token-claim-allowed" : "no-claim"}` });
+      writeBenchmarkRunManifest(root, manifest);
+      report.environment.campaignEvidence = publicProductionBenchmarkCampaignEvidence(manifest.campaignEvidence);
+      report.comparison.campaignEvidence = report.environment.campaignEvidence;
+    }
+    report.publicationAuthorization = { schemaVersion: 1, status: receipt.closureAllowed ? "launcher-finalized" : "launcher-finalization-failed",
+      allowed, stageId: receipt.stageId, policySha256: control.identity.sha256,
+      launcherReceiptDigest: benchmarkBudgetDigest(receipt), failures: receipt.failures,
+      managementThresholdOvershoot: receipt.accounting?.overshoot ?? null,
+      explanation: "Measurement verdict and observed metrics are unchanged. Claim authorization requires the durable exact-report launcher receipt; management-threshold overshoot is disclosed, not a hard-cap guarantee." };
+    if (allowed) {
+      report.comparison.tokenClaimAllowed = true;
+      if (pending.eligibility.tokenClaimUnavailableReason === null) delete report.comparison.tokenClaimUnavailableReason;
+      else report.comparison.tokenClaimUnavailableReason = pending.eligibility.tokenClaimUnavailableReason;
+    } else withhold(report, receipt.closureAllowed ? "original-measurement-claim-not-eligible" : "launcher-finalization-failed");
+    if (report.goalAssessment && receipt.closureAllowed) {
+      Object.assign(report.goalAssessment, pending.eligibility.goal, { claimAllowed: allowed && pending.eligibility.goal?.claimAllowed === true });
+      if (!report.goalAssessment.claimAllowed && report.goalAssessment.status === "GOAL_PASS") report.goalAssessment.status = "GOAL_CLAIM_WITHHELD";
+    }
+    report.trustChecklist = benchmarkTrustChecklist(report);
+    writePrivateAtomic(path.join(root, "report.html"), renderBenchmarkHtml(report));
+    writePrivateAtomic(path.join(root, "report.md"), renderBenchmarkMarkdown(report));
+    writePrivateAtomic(path.join(root, "summary.txt"), renderBenchmarkText(report));
+    writePrivateAtomic(path.join(root, "report.json"), json(report));
+  } catch (error) {
+    if (campaign) {
+      manifest.campaignEvidence = campaign.invalidateClaimPublication({ reason: "launcher-publication-failed" });
+      writeBenchmarkRunManifest(root, manifest);
+    }
+    // Remove only publication files from this exact run; retained ledgers/checkpoints remain intact.
+    for (const name of ["report.html", "report.md", "summary.txt", "report.json"]) {
+      try { fs.rmSync(path.join(root, name), { force: true }); } catch { /* Receipt/campaign still prevents unsupported promotion. */ }
+    }
+    throw error;
+  } finally { campaign?.close(); }
+}
+
+export function finalizeBenchmarkBudgetPublication({ control, stageId, launcherReceipt,
+  childExitCode, outerSucceeded, outerErrorCodes = [] }) {
+  const file = receiptPath(control.identity, stageId);
+  if (fs.existsSync(file)) fail("launcher-final receipt already exists");
+  const release = acquireBenchmarkRunLock(`${control.identity.statePath}.guard`, benchmarkBudgetDigest(control.binding));
+  try {
+    const failures = [...outerErrorCodes];
+    if (outerSucceeded !== true || ![0, 1].includes(childExitCode)) failures.push("outer-launcher-incomplete");
+    let envelope, publication = null;
+    try {
+      envelope = readState(control);
+      assertBenchmarkBudgetPolicyUnchanged(control);
+      validateAccounting(control, stageId, launcherReceipt, envelope.state);
+      publication = pendingReport(control, stageId, envelope.state);
+      if (publication && childExitCode !== publication.pending.expectedChildExitCode) fail("child exit differs from adjudicated result; late core cleanup may have failed");
+      if (!publication && childExitCode !== 0) fail("a stage without an adjudicated report must have a successful core exit");
+    } catch (error) { failures.push(error.message); }
+    const closureAllowed = failures.length === 0;
+    const receipt = { schemaVersion: 1, kind: "benchmark-launcher-final-v1", stageId,
+      budgetIdentity: control.identity, policyDigest: benchmarkBudgetDigest(control.policy), bindingDigest: benchmarkBudgetDigest(control.binding),
+      stateDigest: envelope?.stateDigest ?? null, stageProof: envelope ? stageProof(envelope.state, stageId) : null,
+      closureAllowed, publicationAllowed: closureAllowed && publication?.pending.eligibility.tokenClaimAllowed === true,
+      pendingReportSha256: publication?.pending.reportSha256 ?? null, childExitCode, failures,
+      accounting: launcherReceipt ?? null };
+    writeNew(file, receipt); // Durable and identity-bound BEFORE any favorable campaign/report transition.
+    if (publication) publish(control, receipt, publication);
+    return receipt;
+  } finally { release(); }
+}

package/scripts/benchmark-budget-runtime.mjs

@@ -0,0 +1,136 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { openBenchmarkBudgetGovernor } from "../packages/piagent-core/benchmark/benchmark-budget-governor.js";
+
+export const BENCHMARK_BUDGET_CONTEXT = "PIAGENT_BENCHMARK_BUDGET_CONTEXT";
+const hash = bytes => crypto.createHash("sha256").update(bytes).digest("hex");
+const digestPattern = /^[a-f0-9]{64}$/;
+const executionKeys = ["model", "thinking", "serviceTier", "surfaces", "repeats", "timeoutSeconds",
+  "infrastructureRetries", "codexMode", "codexBaseline", "piagentTreatment"];
+function fail(message) {
+  throw Object.assign(new Error(`Benchmark budget: ${message}`), { exitCode: 1, code: "BENCHMARK_BUDGET_DENIED" });
+}
+function read(file) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink()) fail("policy must be a regular file");
+  const bytes = fs.readFileSync(file);
+  return { value: JSON.parse(bytes), sha256: hash(bytes) };
+}
+function canonicalPath(file) {
+  let ancestor = file;
+  const suffix = [];
+  while (!fs.existsSync(ancestor)) {
+    const parent = path.dirname(ancestor);
+    if (parent === ancestor) fail("path has no existing ancestor");
+    suffix.unshift(path.basename(ancestor));
+    ancestor = parent;
+  }
+  return path.join(fs.realpathSync(ancestor), ...suffix);
+}
+
+export function readBenchmarkBudgetControl({ options, resumeManifest, sourceRoot } = {}) {
+  const saved = resumeManifest?.budgetControl;
+  if (resumeManifest && !saved && options.budgetPolicy) fail("cannot add a budget policy to an existing unbudgeted lineage");
+  if (!saved && !options.budgetPolicy) return null;
+  const policyPath = options.budgetPolicy ?? saved?.policyPath;
+  const statePath = options.budgetState ?? saved?.statePath;
+  if (![policyPath, statePath].every(p => typeof p === "string" && path.isAbsolute(p) && path.normalize(p) === p)
+    || policyPath === statePath) fail("canonical distinct policy/state paths are required");
+  if ([policyPath, statePath, `${statePath}.guard`].some(file => canonicalPath(file) !== file)) {
+    fail("canonical paths are required; symlink aliases are not allowed");
+  }
+  const { value, sha256 } = read(policyPath);
+  if (value?.schemaVersion !== 1 || value.kind !== "benchmark-management-budget-v1"
+    || value.policy?.semantics !== "management-thresholds"
+    || ![value.policy.maxProviderAttempts, value.policy.freshTokenThreshold, value.policy.activeWallTimeMsThreshold]
+      .every(n => Number.isSafeInteger(n) && n > 0)
+    || typeof value.authorityDecision !== "string" || !value.authorityDecision
+    || !value.binding || !digestPattern.test(value.binding.candidateDigest)
+    || !digestPattern.test(value.binding.suiteDigest)
+    || !path.isAbsolute(value.binding.runRoot ?? "")
+    || path.normalize(value.binding.runRoot) !== value.binding.runRoot
+    || !Array.isArray(value.binding.plannedAttempts)
+    || value.binding.plannedAttempts.length !== value.policy.maxProviderAttempts
+    || !value.binding.execution) fail("unsupported policy or incomplete frozen binding");
+  const identity = { schemaVersion: 1, policyPath, statePath, sha256 };
+  if (saved && JSON.stringify(saved) !== JSON.stringify(identity)) fail("resume policy identity changed");
+  const output = options.resume ?? options.output;
+  if (!output) fail("an explicit pinned output or resume path is required");
+  if (path.resolve(output) !== value.binding.runRoot || canonicalPath(output) !== value.binding.runRoot) {
+    fail("policy belongs to a different or aliased run root");
+  }
+  const forbiddenRoots = [value.binding.runRoot, ...(sourceRoot ? [canonicalPath(sourceRoot)] : [])];
+  for (const root of forbiddenRoots) {
+    const rel = path.relative(root, statePath);
+    if (!rel || (!rel.startsWith(".." + path.sep) && rel !== ".." && !path.isAbsolute(rel))) {
+      fail("budget state must be outside source, model workspaces and run output");
+    }
+  }
+  options.budgetPolicy = policyPath;
+  options.budgetState = statePath;
+  options.budgetControl = identity;
+  return Object.freeze({ ...value, identity });
+}
+
+export function assertBenchmarkBudgetBinding(control, { options, candidateDigest, suiteDigest, fullOrder }) {
+  if (!control) return;
+  if (control.binding.candidateDigest !== candidateDigest || control.binding.suiteDigest !== suiteDigest) {
+    fail("source or suite differs from the approved policy");
+  }
+  const execution = Object.fromEntries(executionKeys.map(key => [key, options[key]]));
+  if (executionKeys.some(key => JSON.stringify(execution[key]) !== JSON.stringify(control.binding.execution[key]))) {
+    fail("execution configuration differs from the approved policy");
+  }
+  const order = fullOrder.map((item, index) => ({
+    orderIndex: index + 1, scenarioId: item.scenario?.id ?? item.scenarioId,
+    surface: item.surface, repeat: item.repeat
+  }));
+  if (JSON.stringify(order) !== JSON.stringify(control.binding.plannedAttempts)) fail("planned attempt order differs");
+}
+
+export function assertBenchmarkBudgetPolicyUnchanged(control) {
+  if (control && read(control.identity.policyPath).sha256 !== control.identity.sha256) fail("policy changed during execution");
+}
+
+export function openBenchmarkBudgetCore(control, { env = process.env, parentPid = process.ppid, now = Date.now } = {}) {
+  if (!control) {
+    if (env[BENCHMARK_BUDGET_CONTEXT]) fail("launcher budget context has no bound policy");
+    return null;
+  }
+  let context;
+  try { context = JSON.parse(env[BENCHMARK_BUDGET_CONTEXT] ?? "null"); } catch { fail("malformed launcher context"); }
+  if (!context || context.parentPid !== parentPid || context.policySha256 !== control.identity.sha256
+    || context.statePath !== control.identity.statePath || !/^[a-f0-9]{32}$/.test(context.stageId ?? "")) {
+    fail("trusted launcher stage handoff is missing or mismatched");
+  }
+  assertBenchmarkBudgetPolicyUnchanged(control);
+  const governor = openBenchmarkBudgetGovernor({ statePath: control.identity.statePath,
+    policy: control.policy, binding: control.binding, resume: true, attachStageId: context.stageId, now });
+  return { governor, stageId: context.stageId,
+    check() {
+      assertBenchmarkBudgetPolicyUnchanged(control);
+      const snapshot = governor.checkpointStage(context.stageId);
+      const reasons = snapshot.stopReasons.filter(reason => !(reason === "session-cap" && snapshot.inFlightAttempts === 1));
+      if (reasons.length) fail(`stopped: ${reasons.join(",")}`);
+    },
+    providerStarted(attempt) { governor.startAttempt(attempt); },
+    providerReturned(attempt) {
+      governor.settleAttempt(attempt, { usage: attempt.usage, usageStatus: attempt.usageStatus });
+      try { assertBenchmarkBudgetPolicyUnchanged(control); }
+      catch (error) { governor.stop("budget-policy-changed"); throw error; }
+    },
+    close() { governor.close(); }
+  };
+}
+
+export function createBudgetProviderCallbacks(budget, campaign) {
+  return {
+    onProviderAttemptStart(attempt) { budget?.providerStarted(attempt); campaign?.providerStarted(attempt); },
+    onProviderAttemptReturned(attempt) {
+      // Keep observed spend even if the independent campaign journal fails.
+      try { campaign?.providerReturned(attempt); }
+      finally { budget?.providerReturned(attempt); }
+    }
+  };
+}

package/scripts/benchmark-candidate-ablation.mjs

@@ -0,0 +1,265 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { collectBenchmarkCandidate } from "../packages/piagent-core/benchmark/benchmark-candidate.js";
+import { benchmarkTreeIdentity } from "../packages/piagent-core/benchmark/benchmark-tree-identity.js";
+import { appendBenchmarkLedger, benchmarkLedgerCheckpoint, emptyBenchmarkLedgerBinding, inspectBenchmarkLedger } from "../packages/piagent-core/benchmark/benchmark-ledger.js";
+import { acquireBenchmarkRunLock } from "../packages/piagent-core/benchmark/benchmark-run-lock.js";
+import { writePrivateAtomic } from "../packages/piagent-core/benchmark/benchmark-forensics.js";
+import { exactBenchmarkMeasuredUsage } from "../packages/piagent-core/benchmark/benchmark-usage.js";
+import { resolveBenchmarkSuiteEntry } from "../packages/piagent-core/benchmark/benchmark-suite-runtime.js";
+import { runOfflineBenchmarkSession } from "./benchmark-session.mjs";
+
+// Offline diagnostic plumbing only. No default process/provider implementation,
+// credential access, approval mechanism, retries, or release claims live here.
+const KIND = "piagent-candidate-ablation-offline-v1";
+const BASELINE = "05903656958fc78638779bf0a9e9b403f18992a2";
+const adapterFile = fileURLToPath(import.meta.url);
+const clone = value => JSON.parse(JSON.stringify(value));
+const digest = value => crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const read = file => JSON.parse(fs.readFileSync(file, "utf8"));
+const write = (file, value) => writePrivateAtomic(file, `${JSON.stringify(value, null, 2)}\n`);
+const now = () => new Date().toISOString();
+const safeId = value => typeof value === "string" && /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,100}$/.test(value);
+const inside = (root, target) => { const relative = path.relative(root, target); return !relative || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative)); };
+function fail(message) { throw new Error(`Offline ablation: ${message}`); }
+function source(root) {
+  return { head: execFileSync("git", ["-C", root, "rev-parse", "HEAD"], { encoding: "utf8" }).trim(),
+    ...collectBenchmarkCandidate(root).provenance };
+}
+function config(file) { return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); }
+function validatePlan(plan) {
+  if (plan?.kind !== KIND || plan.schemaVersion !== 1 || plan.providerMode !== "fake"
+    || plan.providerDispatchAllowed !== false || !safeId(plan.runId)) fail("only an explicit offline fake-provider plan is supported");
+  if (plan.arms?.length !== 2 || new Set(plan.arms.map(arm => arm.armId)).size !== 2
+    || plan.arms.some(arm => !safeId(arm.armId) || arm.surface !== "piagent")) fail("two distinct actual piagent arms are required");
+  if (plan.suite?.scenarios?.length !== 27 || new Set(plan.suite.scenarios.map(s => s.id)).size !== 27
+    || plan.suite.scenarios.some(s => !safeId(s.id))) fail("the locked workload must have exactly 27 distinct coordinates");
+  if (plan.execution?.concurrency !== 1 || plan.execution.repeat !== 1 || plan.execution.infrastructureRetries !== 0
+    || plan.execution.model !== "openai-codex/gpt-5.6-luna" || plan.execution.thinking !== "medium"
+    || plan.execution.serviceTier !== "fast" || !Number.isSafeInteger(plan.execution.timeoutSeconds)
+    || plan.execution.timeoutSeconds < 1) fail("unsupported execution configuration");
+  if (![plan.budget?.maxFreshTokens, plan.budget?.reserveFreshPerSession].every(n => Number.isSafeInteger(n) && n > 0)) fail("positive management budget and per-session reservation are required");
+  if (JSON.stringify(plan.order) !== JSON.stringify(orderFor(plan))) fail("execution order differs from the locked interleaving");
+}
+function orderFor(plan) {
+  return plan.suite.scenarios.flatMap((scenario, index) => (index % 2 ? [...plan.arms].reverse() : plan.arms).map(arm => ({
+    orderIndex: index * 2 + (index % 2 ? [...plan.arms].reverse() : plan.arms).indexOf(arm) + 1,
+    scenarioId: scenario.id, armId: arm.armId, surface: "piagent", repeat: 1,
+    armRunId: `${plan.runId}-${arm.armId}`, candidateDigest: arm.source.contentDigest,
+    configurationDigest: arm.configurationDigest, suiteDigest: plan.suiteIdentity.contentDigest
+  })));
+}
+
+/** Freeze inputs for a fake-provider proof; this never qualifies or authorizes an experiment. */
+export function createOfflineAblationPlan({ runId, arms, suite, suiteRoot, execution = {}, budget, rootSeed }) {
+  const plan = { schemaVersion: 1, kind: KIND, providerMode: "fake", providerDispatchAllowed: false, runId, adapterDigest: config(adapterFile),
+    arms: arms.map(arm => {
+      const packageRoot = fs.realpathSync(arm.packageRoot);
+      const configurationFile = fs.realpathSync(arm.configurationFile);
+      const identity = source(packageRoot);
+      if (arm.armId === "A" && (identity.head !== BASELINE || execFileSync("git", ["-C", packageRoot, "status", "--porcelain"], { encoding: "utf8" }).trim())) fail("arm A must be the clean exact baseline");
+      return { armId: arm.armId, surface: "piagent", packageRoot, source: identity, configurationFile,
+        configurationDigest: config(configurationFile), patchDigest: digest({ head: identity.head, contentDigest: identity.contentDigest }) };
+    }), suite: clone(suite), suiteRoot: fs.realpathSync(suiteRoot), suiteIdentity: benchmarkTreeIdentity(suiteRoot, { rejectSymlinks: true }),
+    execution: { model: "openai-codex/gpt-5.6-luna", thinking: "medium", serviceTier: "fast", timeoutSeconds: 900,
+      ...execution, concurrency: 1, repeat: 1, infrastructureRetries: 0 }, budget: clone(budget), rootSeed };
+  if (typeof rootSeed !== "string" || !rootSeed) fail("a fixed root seed is required");
+  plan.order = orderFor(plan);
+  validatePlan(plan);
+  return plan;
+}
+
+function assertInputs(plan) {
+  if (plan.adapterDigest !== config(adapterFile)) fail("adapter source drift");
+  for (const arm of plan.arms) {
+    if (digest(source(arm.packageRoot)) !== digest(arm.source)) fail(`source/HEAD drift for ${arm.armId}`);
+    if (config(arm.configurationFile) !== arm.configurationDigest) fail(`configuration drift for ${arm.armId}`);
+  }
+  if (digest(benchmarkTreeIdentity(plan.suiteRoot, { rejectSymlinks: true })) !== digest(plan.suiteIdentity)) fail("fixture/evaluator/suite drift");
+}
+
+function auditRows(plan, rows) {
+  const sessions = new Set();
+  const attempts = new Set();
+  const fixtures = new Map();
+  if (rows.length > 54) fail("ledger exceeds locked coordinate count");
+  rows.forEach((row, index) => {
+    if (digest(row.coordinate) !== digest(plan.order[index]) || row.state !== "sealed" || row.planDigest !== digest(plan)
+      || !exactBenchmarkMeasuredUsage(row.usage) || !row.attemptId || attempts.has(row.attemptId)) fail(`foreign, duplicate or incomplete sealed row ${index + 1}`);
+    const arm = plan.arms.find(a => a.armId === row.coordinate.armId);
+    if (digest(row.source) !== digest(arm.source) || row.patchDigest !== arm.patchDigest
+      || row.configurationDigest !== arm.configurationDigest || digest(row.fixtureEvaluatorIdentity) !== digest(plan.suiteIdentity)
+      || JSON.stringify(row.transitions?.map(event => event.state)) !== JSON.stringify(["planned", "dispatched", "returned", "verified", "sealed"])) fail("sealed source/config/lifecycle identity mismatch");
+    if (row.record) {
+      validateRecord(plan, row, row.record);
+      if (sessions.has(row.record.sessionId)) fail("provider session reused across arms or coordinates");
+      sessions.add(row.record.sessionId);
+      const previous = fixtures.get(row.coordinate.scenarioId);
+      if (previous && previous !== row.record.variant.fixtureDigest) fail("paired fixture mismatch");
+      fixtures.set(row.coordinate.scenarioId, row.record.variant.fixtureDigest);
+    }
+    attempts.add(row.attemptId);
+  });
+}
+
+export function offlineAblationAccounting(plan, rows, active = null) {
+  const knownFresh = rows.reduce((sum, row) => sum + row.usage.fresh, 0)
+    + (active?.usage && exactBenchmarkMeasuredUsage(active.usage) ? active.usage.fresh : 0);
+  const unknown = active && ["dispatched", "returned"].includes(active.state) && !exactBenchmarkMeasuredUsage(active.usage) ? 1 : 0;
+  const reservedFresh = active && !exactBenchmarkMeasuredUsage(active.usage) ? plan.budget.reserveFreshPerSession : 0;
+  const partialFresh = active && !exactBenchmarkMeasuredUsage(active.usage) && Number.isSafeInteger(active.usage?.fresh) && active.usage.fresh >= 0 ? active.usage.fresh : 0;
+  const reservationExceeded = rows.some(row => row.usage.fresh > plan.budget.reserveFreshPerSession)
+    || (active?.usage?.fresh ?? 0) > plan.budget.reserveFreshPerSession;
+  return { knownFresh, knownFreshLowerBound: knownFresh + partialFresh, unknownAttempts: unknown, reservedFresh, reservationExceeded,
+    admitted: !unknown && !reservationExceeded && knownFresh + reservedFresh + (active ? 0 : plan.budget.reserveFreshPerSession) <= plan.budget.maxFreshTokens,
+    overshootFresh: Math.max(0, knownFresh - plan.budget.maxFreshTokens), hardCapProven: false };
+}
+
+function validateRecord(plan, active, record) {
+  const c = active.coordinate;
+  if (record.runId !== c.armRunId || record.attemptId !== active.attemptId || record.scenarioId !== c.scenarioId
+    || record.surface !== "piagent" || record.repeat !== 1 || record.orderIndex !== c.orderIndex
+    || record.configurationDigest !== c.configurationDigest || !record.sessionId || !record.variant?.fixtureDigest
+    || ["unknown-after-provider-start", "measured-lower-bound"].includes(record.usageStatus)
+    || !exactBenchmarkMeasuredUsage(record.usage) || digest(record.usage) !== digest(active.usage)) fail("returned record identity/usage mismatch");
+}
+
+/** Uses the existing single-session runner with required fake process AND WebUI seams.
+ * The caller supplies trusted local test doubles; no CLI can select a live provider.
+ * External preflight, S0, credential custody and approval remain unimplemented here.
+ */
+export async function runOfflineCandidateAblation({ plan: inputPlan, runRoot: inputRoot, fakeProvider,
+  stopRequested = () => false, checkpoint = () => {}, reconciliation = null }) {
+  const plan = clone(inputPlan);
+  validatePlan(plan);
+  if (fakeProvider?.kind !== "offline-test-double" || typeof fakeProvider.runCommand !== "function"
+    || typeof fakeProvider.piagentWebUiJourney !== "function") fail("both explicit fake-provider seams are mandatory");
+  fs.mkdirSync(inputRoot, { recursive: true, mode: 0o700 });
+  const runRoot = fs.realpathSync(inputRoot);
+  for (const root of [plan.suiteRoot, ...plan.arms.map(a => a.packageRoot)]) if (inside(root, runRoot) || inside(runRoot, root)) fail("evidence and frozen inputs must be disjoint");
+  for (const arm of plan.arms) if (inside(runRoot, arm.configurationFile)) fail("configuration must be outside mutable evidence");
+  const release = acquireBenchmarkRunLock(runRoot, plan.runId);
+  const lockPath = path.join(runRoot, ".benchmark-run.lock");
+  const lockStat = fs.lstatSync(lockPath);
+  const assertOwner = () => { const current = fs.lstatSync(lockPath); if (current.ino !== lockStat.ino || current.dev !== lockStat.dev) fail("campaign lock owner changed"); };
+  const manifestPath = path.join(runRoot, "run-manifest.json");
+  const ledgerPath = path.join(runRoot, "runs.jsonl");
+  let manifest;
+  let rows = [];
+  let status = "blocked";
+  const persist = () => { assertOwner(); write(manifestPath, manifest); };
+  const advance = (state, fields = {}) => {
+    Object.assign(manifest.active, fields, { state });
+    manifest.active.transitions.push({ state, at: now() });
+    persist(); checkpoint(state, clone(manifest.active));
+  };
+  const seal = () => {
+    assertOwner(); assertInputs(plan);
+    const row = { ...manifest.active, state: "sealed", transitions: [...manifest.active.transitions, { state: "sealed", at: now() }] };
+    auditRows(plan, [...rows, row]);
+    manifest.ledger = appendBenchmarkLedger(ledgerPath, row, manifest.ledger);
+    checkpoint("ledger-appended", clone(row));
+    rows.push(row); manifest.active = null; persist(); checkpoint("sealed", clone(row));
+  };
+  try {
+    assertInputs(plan);
+    manifest = fs.existsSync(manifestPath) ? read(manifestPath) : { schemaVersion: 1, kind: KIND, plan, planDigest: digest(plan), ledger: emptyBenchmarkLedgerBinding(), active: null };
+    if (manifest.planDigest !== digest(plan) || digest(manifest.plan) !== digest(plan)) fail("resume source/config/protocol identity differs");
+    const inspected = benchmarkLedgerCheckpoint(manifest.ledger, inspectBenchmarkLedger(ledgerPath));
+    rows = inspected.records;
+    auditRows(plan, rows);
+    if (inspected.recovered) {
+      if (manifest.active?.state !== "verified" || rows.at(-1).attemptId !== manifest.active.attemptId
+        || digest({ ...rows.at(-1), state: "verified", transitions: rows.at(-1).transitions.slice(0, -1) }) !== digest(manifest.active)) fail("unmatched recovered append");
+      manifest.ledger = inspected.binding; manifest.active = null;
+    }
+    persist();
+    if (manifest.active && manifest.active.state !== "planned") {
+      if (manifest.active.state !== "verified") {
+        // Even a returned usage marker is insufficient to infer verification.
+        // Explicit fake evidence settles interruption as FAIL, never as PASS.
+        const active = manifest.active;
+        if (!reconciliation) fail("unsealed provider attempt requires reconciliation before further dispatch");
+        const receipt = read(reconciliation);
+        if (receipt.kind !== "offline-interruption-reconciliation-v1" || receipt.planDigest !== manifest.planDigest
+          || receipt.attemptId !== active.attemptId || digest(receipt.coordinate) !== digest(active.coordinate)
+          || !exactBenchmarkMeasuredUsage(receipt.usage) || !receipt.terminalReason
+          || (exactBenchmarkMeasuredUsage(active.usage) && digest(active.usage) !== digest(receipt.usage))) fail("invalid or cross-attempt reconciliation");
+        if (active.state === "dispatched") advance("returned", { usage: receipt.usage, usageProvenance: { kind: receipt.kind, fileDigest: config(reconciliation) } });
+        advance("verified", { disposition: "interrupted-reconciled-failure", resolved: false,
+          terminalReason: receipt.terminalReason, usage: receipt.usage, reconciliationDigest: config(reconciliation) });
+      }
+      seal();
+    }
+    for (const coordinate of plan.order.slice(rows.length)) {
+      if (stopRequested()) { status = "stopped"; break; }
+      assertOwner(); assertInputs(plan);
+      if (!offlineAblationAccounting(plan, rows).admitted) fail("management budget admission denied; reservation is not a hard cap");
+      const arm = plan.arms.find(a => a.armId === coordinate.armId);
+      const scenario = plan.suite.scenarios.find(s => s.id === coordinate.scenarioId);
+      if (manifest.active && (manifest.active.state !== "planned" || digest(manifest.active.coordinate) !== digest(coordinate))) fail("foreign active coordinate");
+      const preparationId = crypto.randomUUID();
+      const sessionRoot = path.join(runRoot, "arms", arm.armId, "preparations", preparationId);
+      const runtimeHome = path.join(sessionRoot, "runtime-home");
+      fs.mkdirSync(runtimeHome, { recursive: true, mode: 0o700 });
+      manifest.active = { planDigest: manifest.planDigest, coordinate, source: arm.source, patchDigest: arm.patchDigest,
+        configurationDigest: arm.configurationDigest, fixtureEvaluatorIdentity: plan.suiteIdentity, transitions: [],
+        preparationId, sessionRoot, runtimeHome, reservedFresh: plan.budget.reserveFreshPerSession };
+      advance("planned");
+      const session = await runOfflineBenchmarkSession({
+        packageRoot: arm.packageRoot, runCommand: fakeProvider.runCommand, piagentWebUiJourney: fakeProvider.piagentWebUiJourney,
+        resolveSuiteEntry: resolveBenchmarkSuiteEntry, interrupted: stopRequested,
+        suite: plan.suite, suiteRoot: plan.suiteRoot, scenario, surface: "piagent", repeat: 1,
+        orderIndex: coordinate.orderIndex, infrastructureAttempt: 1, runId: coordinate.armRunId, runRoot: sessionRoot,
+        options: { ...plan.execution, piagentTreatment: "release-defaults" }, piCommand: "offline-fake-pi",
+        piRuntimeHome: { path: runtimeHome }, systemCommands: { node: "offline-fake-node", git: "offline-fake-git", bash: "offline-fake-bash" },
+        suiteDigest: coordinate.suiteDigest, configurationDigest: coordinate.configurationDigest, rootSeed: plan.rootSeed,
+        assertProviderDispatchReady: () => { assertOwner(); assertInputs(plan); },
+        onProviderAttemptStart: attempt => {
+          assertOwner(); assertInputs(plan);
+          if (stopRequested()) fail("stopped before provider dispatch");
+          if (manifest.active.state !== "planned" || attempt.surface !== "piagent" || attempt.scenarioId !== coordinate.scenarioId) fail("duplicate or foreign provider dispatch");
+          advance("dispatched", { attemptId: attempt.attemptId, usage: null, usageProvenance: { kind: "unknown-after-provider-start" } });
+        },
+        onProviderAttemptReturned: attempt => {
+          if (manifest.active.state !== "dispatched" || attempt.attemptId !== manifest.active.attemptId) fail("duplicate or foreign provider return");
+          // Preserve cost before any post-session identity/verification failure.
+          advance("returned", { usage: attempt.usage, usageProvenance: { kind: "single-session-runner", usageStatus: attempt.usageStatus } });
+        },
+        persistCompletedRecord: record => {
+          validateRecord(plan, manifest.active, record); assertInputs(plan);
+          advance("verified", { record, usage: record.usage, resolved: record.resolved, terminalReason: record.failure ?? "completed", disposition: "fake-session-result" });
+        }
+      });
+      if (manifest.active.state !== "verified") {
+        validateRecord(plan, manifest.active, session.record);
+        advance("verified", { record: session.record, usage: session.record.usage, resolved: false,
+          terminalReason: stopRequested() ? "interrupted" : session.record.failure, disposition: "fake-session-failure" });
+      }
+      seal();
+    }
+    if (rows.length === 54) status = "offline-proof-complete";
+    return { status, rows: rows.length, accounting: offlineAblationAccounting(plan, rows, manifest.active),
+      providerDispatchAllowed: false, measurementComplete: false, tokenClaimAllowed: false };
+  } finally {
+    try {
+      assertOwner();
+      write(path.join(runRoot, "stop-acknowledgment.json"), { schemaVersion: 1, status, at: now(), pid: process.pid,
+        activeState: manifest?.active?.state ?? null, accounting: manifest ? offlineAblationAccounting(plan, rows, manifest.active) : null,
+        providerDispatchAllowed: false, dispatchLoopStopped: true });
+    } finally { release(); }
+  }
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  if (process.argv.length === 4 && process.argv[2] === "--inspect") {
+    const plan = read(process.argv[3]); validatePlan(plan); assertInputs(plan);
+    process.stdout.write(`${JSON.stringify({ kind: KIND, planDigest: digest(plan), coordinates: plan.order.length, providerDispatchAllowed: false }, null, 2)}\n`);
+  } else {
+    process.stdout.write("Offline only: --inspect <locked-plan.json>. Execute via runOfflineCandidateAblation with explicit local fake-provider seams. No paid dispatch is implemented.\n");
+    process.exitCode = process.argv.length > 2 ? 2 : 0;
+  }
+}