@piagent/platform 1.6.0 → 1.7.1

package/scripts/benchmark-budget-processes.mjs

@@ -0,0 +1,133 @@
+import { performance } from "node:perf_hooks";
+
+const KIND = "benchmark-budget-process-v1";
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+const validPid = pid => Number.isInteger(pid) && pid > 1 && pid <= 2_147_483_647 && pid !== process.pid && pid !== process.ppid;
+
+function defaultSignalGroup(pid, signal) {
+  process.kill(process.platform === "win32" ? pid : -pid, signal);
+}
+
+function defaultGroupAlive(pid) {
+  try { process.kill(process.platform === "win32" ? pid : -pid, 0); return true; }
+  catch (error) { if (error.code === "ESRCH") return false; throw error; }
+}
+
+/**
+ * The trusted core reports each detached provider process group through its
+ * direct IPC channel. The parent never scans or guesses other process IDs.
+ * Registration must be acknowledged before dispatch can progress. Core exit is
+ * not proof of descendant exit: drain independently TERM/KILL/verifies every
+ * still-owned group, including when the core event loop stops responding.
+ */
+export function createBenchmarkBudgetProcessRegistry({ stageId, signalGroup = defaultSignalGroup,
+  groupAlive = defaultGroupAlive, now = () => performance.now(), sleep = delay } = {}) {
+  if (!/^[a-f0-9]{32}$/.test(stageId ?? "")
+    || ![signalGroup, groupAlive, now, sleep].every(value => typeof value === "function")) {
+    throw new Error("Benchmark process registry requires a stage identity and valid operations");
+  }
+  const groups = new Map();
+  const errors = [];
+  const signals = [];
+  const livenessProbeFailures = new Map();
+  let draining = false;
+  let drainPromise;
+  const note = code => { if (!errors.includes(code)) errors.push(code); };
+  const fail = message => {
+    note(message);
+    throw Object.assign(new Error(`Benchmark process registry: ${message}`), { code: "BENCHMARK_BUDGET_PROCESS_INVALID", exitCode: 1 });
+  };
+  const inspect = pid => {
+    try {
+      const result = groupAlive(pid);
+      if (typeof result !== "boolean") throw Object.assign(new Error("invalid liveness result"), { code: "INVALID_LIVENESS_RESULT" });
+      const priorFailure = livenessProbeFailures.get(pid);
+      if (priorFailure) priorFailure.latestObservation = result ? "alive" : "absent";
+      return result;
+    } catch (error) {
+      // A dying POSIX group can transiently reject kill(group, 0), e.g. EPERM.
+      // This is NEVER proof of exit: retain ownership and retry within the same
+      // bounded drain. Only a later conclusive absent probe can resolve it.
+      const prior = livenessProbeFailures.get(pid);
+      const code = /^[A-Z0-9_]{1,80}$/.test(error?.code ?? "") ? error.code : "UNKNOWN";
+      livenessProbeFailures.set(pid, { pid, count: (prior?.count ?? 0) + 1, lastErrorCode: code, latestObservation: "unknown" });
+      return true;
+    }
+  };
+  const collectExited = () => {
+    for (const [pid, status] of groups) if (status === "active" && !inspect(pid)) groups.set(pid, "closed");
+  };
+  const snapshot = () => {
+    const unconfirmedPids = [...groups].filter(([, status]) => status === "active").map(([pid]) => pid);
+    return { schemaVersion: 1, stageId, registeredGroups: groups.size, cleanupConfirmed: errors.length === 0 && unconfirmedPids.length === 0,
+      unconfirmedPids, errors: [...errors], signals: signals.map(value => ({ ...value })),
+      livenessProbeFailures: [...livenessProbeFailures.values()].map(value => ({ ...value })), draining };
+  };
+  const terminateAll = signal => {
+    if (!["SIGINT", "SIGTERM", "SIGHUP", "SIGKILL"].includes(signal)) fail("unsupported termination signal");
+    for (const [pid, status] of groups) {
+      if (status !== "active") continue;
+      signals.push({ pid, signal });
+      try { signalGroup(pid, signal); }
+      catch (error) { if (error.code !== "ESRCH") note("process-group-signal-unconfirmed"); }
+    }
+    return snapshot();
+  };
+  const waitForGroups = async (graceMs, pollMs) => {
+    const started = now();
+    if (!Number.isFinite(started)) { note("invalid-registry-clock"); return; }
+    // The iteration bound also prevents an injected or regressing clock hanging
+    // shutdown forever. Production uses a monotonic clock, not wall-clock time.
+    for (let index = 0; index <= Math.ceil(graceMs / pollMs); index += 1) {
+      collectExited();
+      if (![...groups.values()].includes("active")) return;
+      const elapsed = now() - started;
+      if (!Number.isFinite(elapsed) || elapsed < 0) { note("invalid-registry-clock"); return; }
+      if (elapsed >= graceMs || index === Math.ceil(graceMs / pollMs)) return;
+      await sleep(Math.min(pollMs, graceMs - elapsed));
+    }
+  };
+  return {
+    handleMessage(message) {
+      if (!message || typeof message !== "object" || Array.isArray(message)
+        || Object.keys(message).sort().join(",") !== "event,kind,pid,stageId"
+        || message.kind !== KIND || message.stageId !== stageId
+        || !["started", "closed"].includes(message.event) || !validPid(message.pid)) fail("malformed-or-foreign-process-message");
+      if (message.event === "started") {
+        if (draining) fail("registry is draining or closed");
+        if (groups.has(message.pid)) fail("duplicate process registration");
+        if (groups.size >= 10_000) fail("process registry capacity exceeded");
+        groups.set(message.pid, "active");
+      } else {
+        if (!groups.has(message.pid)) fail("unknown process close");
+        if (groups.get(message.pid) !== "active") fail("duplicate process close");
+        if (inspect(message.pid)) fail("process group still alive after close receipt");
+        groups.set(message.pid, "closed");
+      }
+      return { accepted: true, pid: message.pid, event: message.event };
+    },
+    terminateAll,
+    snapshot,
+    drain({ termGraceMs = 2000, killGraceMs = 1000, pollMs = 20 } = {}) {
+      if (![termGraceMs, killGraceMs, pollMs].every(Number.isInteger)
+        || termGraceMs < 0 || killGraceMs < 0 || termGraceMs + killGraceMs > 10_000 || pollMs < 1 || pollMs > 1000) {
+        return Promise.reject(new Error("Benchmark process registry drain timing bounds are invalid"));
+      }
+      if (!drainPromise) {
+        draining = true;
+        drainPromise = (async () => {
+          collectExited();
+          terminateAll("SIGTERM");
+          await waitForGroups(termGraceMs, pollMs);
+          terminateAll("SIGKILL");
+          await waitForGroups(killGraceMs, pollMs);
+          collectExited();
+          if ([...groups.values()].includes("active")) note("process-group-cleanup-unconfirmed");
+          if ([...livenessProbeFailures.values()].some(value => value.latestObservation === "unknown")) note("process-group-liveness-unconfirmed");
+          return snapshot();
+        })();
+      }
+      return drainPromise;
+    }
+  };
+}

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