@piagent/platform 1.5.4 → 1.6.0

package/scripts/benchmark-runner-finalization.mjs

@@ -0,0 +1,309 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  renderBenchmarkHtml,
+  renderBenchmarkText,
+  summarizeBenchmark
+} from "../packages/piagent-core/benchmark/benchmark-core.js";
+import { codexModelName } from "../packages/piagent-core/benchmark/benchmark-codex.js";
+import { benchmarkTrustChecklist } from "../packages/piagent-core/benchmark/benchmark-matrix.js";
+import { applyBenchmarkClaimRestrictions } from "../packages/piagent-core/benchmark/benchmark-claim-restrictions.js";
+import { piagentTreatment } from "../packages/piagent-core/benchmark/benchmark-runtime.js";
+import { cleanupBenchmarkPiRuntimeHome } from "../packages/piagent-core/benchmark/benchmark-pi-home.js";
+import { benchmarkSuiteCoverage } from "../packages/piagent-core/benchmark/benchmark-runner-policy.js";
+import {
+  benchmarkHostReadinessPolicyDigest,
+  summarizeBenchmarkHostReadinessHistory
+} from "../packages/piagent-core/benchmark/benchmark-host-readiness.js";
+import {
+  cleanupUnretainedWorkspaces,
+  writeBenchmarkAbort,
+  writeBenchmarkRunManifest,
+  writePrivate,
+  writePrivateAtomic
+} from "../packages/piagent-core/benchmark/benchmark-forensics.js";
+import {
+  buildBenchmarkStageDiagnostic,
+  pendProductionStageControl
+} from "../packages/piagent-core/benchmark/benchmark-stage-diagnostic.js";
+import {
+  assertBenchmarkLedgerBinding,
+  inspectBenchmarkLedger,
+  validateBenchmarkLedgerPrefix
+} from "../packages/piagent-core/benchmark/benchmark-ledger.js";
+import {
+  completedBenchmarkRecord,
+  expectedBenchmarkRecord
+} from "../packages/piagent-core/benchmark/benchmark-record-validation.js";
+import { recoverOrphanedBenchmarkAttempts } from "../packages/piagent-core/benchmark/benchmark-resume-recovery.js";
+import { benchmarkResumeCommand, benchmarkRunKey } from "./benchmark-runner-support.mjs";
+
+export function finalizeBenchmarkRun(context) {
+  const {
+    assuranceEvidence,
+    bootstrapMetadata,
+    candidateGuard,
+    canonicalProductionSuite,
+    codexCredentialBridge,
+    comparison,
+    configurationDigest,
+    declaredScenarioCount,
+    detachPiRuntimeHome,
+    environmentPolicy,
+    executionGuard,
+    fatalExecutionReceipt,
+    fatalRunError,
+    finalizationReceipt,
+    fullOrder,
+    interruptedSignal,
+    ledgerBinding,
+    ledgerPath,
+    lifecycles,
+    manifest,
+    options,
+    packageVersion,
+    pauseReason,
+    piRuntimeHome,
+    preservePiRuntime,
+    productionAllStageBoundaries,
+    productionHostReadinessPolicy,
+    productionSpendControlled,
+    rootSeed,
+    rootSeedDigest,
+    runId,
+    runRoot,
+    runs,
+    runtime,
+    runtimeCommands,
+    source,
+    startedAt,
+    suite,
+    suiteDigest,
+    suiteIdentity,
+    terminalStop
+  } = context;
+
+  if (interruptedSignal) {
+    const provenanceStamp = executionGuard.stamp("interrupted", [piRuntimeHome]);
+    detachPiRuntimeHome();
+    recoverOrphanedBenchmarkAttempts({ runRoot, manifest, fullOrder, completedKeys: new Set(runs.map(benchmarkRunKey)) });
+    cleanupUnretainedWorkspaces(runRoot, options.keepWorkspaces);
+    const interruptedCompletedRuns = runs.filter(completedBenchmarkRecord).length;
+    const resumeCommand = benchmarkResumeCommand({
+      runRoot,
+      productionSpendControlled,
+      completedRuns: interruptedCompletedRuns,
+      stageControl: manifest.stageControl,
+      stageBoundaries: productionAllStageBoundaries
+    });
+    writePrivateAtomic(path.join(runRoot, "interrupted.json"), `${JSON.stringify({ schemaVersion: 1, runId, signal: interruptedSignal, completedRuns: interruptedCompletedRuns, expectedRuns: fullOrder.length, interruptedAt: new Date().toISOString(), resumeCommand, ledger: ledgerBinding, provenanceStamp }, null, 2)}\n`);
+    process.stderr.write(`Benchmark interrupted by ${interruptedSignal}. Partial ledger: ${ledgerPath}\n`);
+    process.exitCode = interruptedSignal === "SIGINT" ? 130 : interruptedSignal === "SIGHUP" ? 129 : 143;
+    return;
+  }
+  if (fatalRunError) {
+    const provenanceStamp = finalizationReceipt?.stamp ?? fatalExecutionReceipt?.stamp ?? executionGuard.stamp("fatal", piRuntimeHome ? [piRuntimeHome] : []);
+    if (!preservePiRuntime) cleanupBenchmarkPiRuntimeHome(bootstrapMetadata.piAgentHome, piRuntimeHome);
+    detachPiRuntimeHome();
+    recoverOrphanedBenchmarkAttempts({ runRoot, manifest, fullOrder, completedKeys: new Set(runs.map(benchmarkRunKey)) });
+    cleanupUnretainedWorkspaces(runRoot, options.keepWorkspaces);
+    const provenanceFailure = writeBenchmarkAbort(runRoot, { runId, completedRuns: runs.filter(completedBenchmarkRecord).length, expectedRuns: fullOrder.length }, fatalRunError, {
+      ledger: ledgerBinding,
+      provenanceStamp
+    });
+    process.stderr.write(provenanceFailure
+      ? `Benchmark aborted because candidate provenance changed. Partial ledger: ${ledgerPath}\n`
+      : `Benchmark aborted after an infrastructure error. Partial ledger: ${ledgerPath}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (terminalStop) {
+    cleanupBenchmarkPiRuntimeHome(bootstrapMetadata.piAgentHome, piRuntimeHome);
+    detachPiRuntimeHome();
+    cleanupUnretainedWorkspaces(runRoot, options.keepWorkspaces);
+    for (const marker of ["paused.json", "stage-diagnostic.json", "interrupted.json", "aborted.json"]) fs.rmSync(path.join(runRoot, marker), { force: true });
+    writePrivateAtomic(path.join(runRoot, "stopped.json"), `${JSON.stringify({ ...terminalStop, runId, completedRuns: runs.filter(completedBenchmarkRecord).length, expectedRuns: fullOrder.length, stoppedAt: new Date().toISOString(), resumeAllowed: false, ledger: ledgerBinding, provenanceStamp: finalizationReceipt.stamp }, null, 2)}\n`);
+    process.stderr.write(`Benchmark terminal-stopped after paired outcome-floor failure. Partial ledger: ${ledgerPath}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const completedRuns = runs.filter(completedBenchmarkRecord);
+  const summarizedHostReadinessHistory = productionHostReadinessPolicy
+    ? summarizeBenchmarkHostReadinessHistory({
+        policy: productionHostReadinessPolicy,
+        receipts: manifest.hostReadinessReceipts,
+        completedRuns: completedRuns.length,
+        authorizedThroughRuns: manifest.stageControl?.authorizedThroughRuns,
+        runId: manifest.runId,
+        configurationDigest: manifest.configurationDigest,
+        stageBoundaries: productionAllStageBoundaries
+      })
+    : null;
+  const hostReadinessPolicyBindingValid = !productionHostReadinessPolicy
+    || manifest.hostReadinessPolicyDigest === benchmarkHostReadinessPolicyDigest(productionHostReadinessPolicy);
+  const hostReadinessHistory = summarizedHostReadinessHistory && !hostReadinessPolicyBindingValid
+    ? {
+        ...summarizedHostReadinessHistory,
+        valid: false,
+        ready: false,
+        errors: [...summarizedHostReadinessHistory.errors, "host-readiness-manifest-policy-digest-mismatch"]
+      }
+    : summarizedHostReadinessHistory;
+  if (completedRuns.length < fullOrder.length) {
+    detachPiRuntimeHome();
+    cleanupUnretainedWorkspaces(runRoot, options.keepWorkspaces);
+    const resumeCommand = benchmarkResumeCommand({
+      runRoot,
+      productionSpendControlled,
+      completedRuns: completedRuns.length,
+      stageControl: manifest.stageControl,
+      stageBoundaries: productionAllStageBoundaries
+    });
+    const paused = {
+      schemaVersion: 1,
+      runId,
+      reason: pauseReason ?? "partial-run",
+      completedRuns: completedRuns.length,
+      expectedRuns: fullOrder.length,
+      remainingRuns: fullOrder.length - completedRuns.length,
+      pausedAt: new Date().toISOString(),
+      resumeCommand,
+      ledger: ledgerBinding,
+      provenanceStamp: executionGuard.stamp("paused")
+    };
+    const stageDiagnostic = buildBenchmarkStageDiagnostic({
+      runId,
+      reason: paused.reason,
+      runs: completedRuns,
+      fullOrder,
+      candidateSurface: comparison.candidateSurface,
+      baselineSurface: comparison.baselineSurface,
+      requestedModel: options.model,
+      requestedThinking: options.thinking,
+      suite,
+      manifest,
+      hostReadinessPolicy: productionHostReadinessPolicy,
+      hostReadinessStageBoundaries: productionAllStageBoundaries
+    });
+    if (productionSpendControlled) {
+      manifest.stageControl = pendProductionStageControl(manifest.stageControl, {
+        reason: paused.reason,
+        completedRuns: completedRuns.length,
+        ledger: ledgerBinding
+      });
+      manifest.ledger = ledgerBinding;
+      writeBenchmarkRunManifest(runRoot, manifest);
+      for (const marker of ["interrupted.json", "aborted.json"]) fs.rmSync(path.join(runRoot, marker), { force: true });
+    }
+    paused.stageDiagnostic = {
+      path: "stage-diagnostic.json",
+      diagnosticOnly: true,
+      claimEligible: false,
+      stageAdvanceAllowed: stageDiagnostic.stageAdvanceAllowed
+    };
+    writePrivateAtomic(path.join(runRoot, "stage-diagnostic.json"), `${JSON.stringify(stageDiagnostic, null, 2)}\n`);
+    writePrivateAtomic(path.join(runRoot, "paused.json"), `${JSON.stringify(paused, null, 2)}\n`);
+    process.stdout.write(`Benchmark paused after ${completedRuns.length}/${fullOrder.length} completed sessions (${paused.reason}).\nStage advance: ${stageDiagnostic.stageAdvanceAllowed ? "allowed by diagnostic" : `blocked (${stageDiagnostic.blockingReasons.join(", ")})`}\nResume: ${paused.resumeCommand}\nStage diagnostic: ${path.join(runRoot, "stage-diagnostic.json")}\nPartial ledger: ${ledgerPath}\n`);
+    return;
+  }
+
+  cleanupBenchmarkPiRuntimeHome(bootstrapMetadata.piAgentHome, piRuntimeHome);
+  detachPiRuntimeHome();
+  const report = summarizeBenchmark({
+    suite,
+    canonicalProductionSuite,
+    runId,
+    startedAt,
+    completedAt: new Date().toISOString(),
+    repeats: options.repeats,
+    environment: {
+      platformVersion: packageVersion,
+      suiteDigest,
+      variantRootSeed: suite.scenarios.some((scenario) => scenario.variantGenerator) ? rootSeed : null,
+      variantRootSeedDigest: suite.scenarios.some((scenario) => scenario.variantGenerator) ? rootSeedDigest : null,
+      executionOrder: suite.schemaVersion === 2 ? "seeded-paired-block-randomized" : "paired-alternating",
+      replaySource: options.replaySource ?? null,
+      profile: suite.profile,
+      requestedModel: options.model ?? null,
+      requestedThinking: options.thinking ?? null,
+      piagentTreatment: piagentTreatment(options.piagentTreatment),
+      treatmentBaseline: lifecycles.length === 1 && lifecycles[0] === "steady-state"
+        ? options.surfaces.includes("codex-cli")
+          ? "piagent-initialized-and-onboarded; codex-clean-fixture"
+          : "initialized-and-onboarded"
+        : "scenario-defined-mixed-lifecycle",
+      timeoutSeconds: options.timeoutSeconds,
+      nodeVersion: process.version,
+      piVersion: runtime.piVersion,
+      codexVersion: runtime.codexVersion ?? null,
+      codexMode: options.surfaces.includes("codex-cli") ? options.codexMode : null,
+      codexAuth: runtime.codexAuth ?? null,
+      codexIsolation: options.surfaces.includes("codex-cli")
+        ? options.codexMode === "controlled" ? "per-session-temporary-home" : "operator-home"
+        : null,
+      codexCredentialBridge: options.surfaces.includes("codex-cli") ? codexCredentialBridge : null,
+      codexGlobalInstructions: options.surfaces.includes("codex-cli")
+        ? options.codexMode === "controlled" ? "excluded" : "operator-home"
+        : null,
+      piGlobalInstructions: "excluded",
+      piAgentHome: manifest.piAgentHome,
+      usageIntegrity: manifest.tokenClaimsUnavailableReason ?? "measured",
+      codexDisabledFeatures: runtime.codexDisabledFeatures,
+      surfaces: options.surfaces,
+      scenarioSelection: options.scenarioIds ?? null,
+      suiteCoverage: benchmarkSuiteCoverage(declaredScenarioCount, suite.scenarios.length),
+      surfaceModels: options.surfaces.includes("codex-cli") ? {
+        piagent: options.model,
+        "codex-cli": codexModelName(options.model)
+      } : { "raw-pi": options.model ?? null, piagent: options.model ?? null },
+      modelParityEvidence: options.surfaces.includes("codex-cli") ? "command-line-pinned" : "session-reported",
+      gitVersion: runtime.gitVersion,
+      source,
+      candidateProvenance: candidateGuard.report(),
+      suiteIdentity,
+      runtimeCommands,
+      configurationDigest,
+      hostReadinessHistory,
+      environmentPolicy,
+      runtimeDependencies: bootstrapMetadata?.runtimeDependencies ?? null,
+      assuranceEvidence
+    },
+    runs: completedRuns,
+    ...comparison
+  });
+  report.ledger = ledgerBinding;
+  applyBenchmarkClaimRestrictions(report, { tokenReason: manifest.tokenClaimsUnavailableReason, replaySource: options.replaySource, codexMode: options.codexMode, surfaces: options.surfaces });
+  report.trustChecklist = benchmarkTrustChecklist(report);
+  const text = renderBenchmarkText(report);
+  const reportLedger = inspectBenchmarkLedger(ledgerPath);
+  assertBenchmarkLedgerBinding(ledgerBinding, reportLedger.binding, "benchmark report ledger");
+  validateBenchmarkLedgerPrefix(reportLedger.records, fullOrder, (record, index, expected) => expectedBenchmarkRecord(record, index, expected, runId, suite, configurationDigest));
+  writePrivate(path.join(runRoot, "report.html"), renderBenchmarkHtml(report));
+  writePrivate(path.join(runRoot, "summary.txt"), text);
+  cleanupUnretainedWorkspaces(runRoot, options.keepWorkspaces);
+  const prepublishReceipt = executionGuard.receipt("prepublish");
+  const prepublishError = prepublishReceipt.error;
+  if (prepublishError) {
+    writeBenchmarkAbort(runRoot, { runId, completedRuns: completedRuns.length, expectedRuns: fullOrder.length }, prepublishError, { ledger: ledgerBinding, provenanceStamp: prepublishReceipt.stamp });
+    throw prepublishError;
+  }
+  for (const marker of ["paused.json", "stage-diagnostic.json", "interrupted.json", "aborted.json", "stopped.json"]) fs.rmSync(path.join(runRoot, marker), { force: true });
+  writePrivateAtomic(path.join(runRoot, "report.json"), `${JSON.stringify(report, null, 2)}\n`);
+  process.stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : text);
+  process.stdout.write(`Reports: ${runRoot}\n`);
+  const productionTokenClaimFailed = canonicalProductionSuite
+    && suite.releaseGate?.requireEfficiencyClaim === true
+    && report.comparison.tokenClaimAllowed !== true;
+  if (
+    report.comparison.qualityGate === false
+    || report.comparison.safetyGate === false
+    || report.comparison.reliabilityGate === false
+    || report.comparison.qualityNonInferior === false
+    || report.comparison.workflowGate === false
+    || report.comparison.categoryGate === false
+    || report.comparison.suiteGate?.passed === false
+    || productionTokenClaimFailed
+  ) process.exitCode = 1;
+}

package/scripts/benchmark-runner-host-readiness.mjs

@@ -0,0 +1,94 @@
+import {
+  benchmarkHostReadinessPolicyDigest,
+  benchmarkHostReadinessStartValidationErrors,
+  collectBenchmarkHostReadinessReceipt,
+  summarizeBenchmarkHostReadinessHistory
+} from "../packages/piagent-core/benchmark/benchmark-host-readiness.js";
+
+export { benchmarkHostReadinessPolicyDigest };
+
+function readinessReasons(summary) {
+  return [...summary.errors, ...summary.blockingReasons].join(", ")
+    || "invalid-host-readiness-history";
+}
+
+function benchmarkHostError(message, code) {
+  const error = new Error(message);
+  error.code = code;
+  error.exitCode = 1;
+  return error;
+}
+
+export function assertExistingBenchmarkHostReadiness(input) {
+  const summary = summarizeBenchmarkHostReadinessHistory(input);
+  if (!summary.valid || !summary.ready) {
+    throw benchmarkHostError(
+      `Cannot resume production benchmark: host-readiness history is missing or invalid (${readinessReasons(summary)}). Start a new staged run.`,
+      "BENCHMARK_HOST_READINESS_HISTORY_INVALID"
+    );
+  }
+  return summary;
+}
+
+export async function collectReadyBenchmarkHostReadiness({
+  policy,
+  completedRuns,
+  authorizedThroughRuns,
+  runId,
+  configurationDigest,
+  stageBoundaries,
+  existingReceipts = [],
+  collectionDependencies
+}) {
+  const receipt = await collectBenchmarkHostReadinessReceipt({
+    policy,
+    completedRuns,
+    authorizedThroughRuns,
+    runId,
+    configurationDigest
+  }, collectionDependencies);
+  if (receipt.status !== "ready") {
+    const sample = receipt.samples.at(-1);
+    throw benchmarkHostError(
+      `Production benchmark host is not ready (${receipt.failureReasons.join(", ") || "incomplete-host-readiness-evidence"}; normalized load ${sample?.normalizedLoad1 ?? "n/a"}, CPU idle ${sample?.cpuIdlePercent ?? "n/a"}%). No auth, tool, or provider preflight was started.`,
+      "BENCHMARK_HOST_NOT_READY"
+    );
+  }
+  const prospective = summarizeBenchmarkHostReadinessHistory({
+    policy,
+    receipts: [...existingReceipts, receipt],
+    completedRuns,
+    authorizedThroughRuns,
+    runId,
+    configurationDigest,
+    stageBoundaries
+  });
+  if (!prospective.valid || !prospective.ready) {
+    throw benchmarkHostError(
+      `Production benchmark host-readiness history rejected the new receipt (${readinessReasons(prospective)}). No auth, tool, or provider preflight was started.`,
+      "BENCHMARK_HOST_READINESS_HISTORY_INVALID"
+    );
+  }
+  return receipt;
+}
+
+export function assertBenchmarkHostReadinessStartReady(receipt, {
+  policy,
+  runId,
+  configurationDigest,
+  nowMilliseconds = Date.now()
+}) {
+  if (!receipt) return;
+  const errors = benchmarkHostReadinessStartValidationErrors(receipt, {
+    policy,
+    runId,
+    configurationDigest,
+    nowMilliseconds
+  });
+  if (errors.length > 0) {
+    throw benchmarkHostError(
+      `Production benchmark host-readiness receipt became stale or invalid before execution (${errors.join(", ")}). No provider session was started.`,
+      "BENCHMARK_HOST_READINESS_STALE"
+    );
+  }
+}

package/scripts/benchmark-runner-support.mjs

@@ -0,0 +1,200 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { productionStageResumeWindow } from "../packages/piagent-core/benchmark/benchmark-stage-diagnostic.js";
+import { benchmarkLedgerCheckpoint, inspectBenchmarkLedger } from "../packages/piagent-core/benchmark/benchmark-ledger.js";
+import { acquireBenchmarkRunLock } from "../packages/piagent-core/benchmark/benchmark-run-lock.js";
+
+export function fail(message, code = 2) {
+  const error = new Error(message);
+  error.exitCode = code;
+  throw error;
+}
+
+export function frozenRuntimeCommandsForFinalization(manifest, surfaces) {
+  const commands = manifest?.runtimeCommands;
+  const validIdentity = (identity) => identity?.schemaVersion === 1
+    && identity.kind === "regular"
+    && typeof identity.resolvedPath === "string"
+    && /^[a-f0-9]{64}$/.test(String(identity.contentDigest ?? ""));
+  const required = ["pi", "node", "git", "bash", ...(surfaces.includes("codex-cli") ? ["codex"] : [])];
+  if (!commands || typeof commands !== "object" || required.some((label) => !validIdentity(commands[label]))) {
+    fail("Cannot finalize production benchmark provider-free: frozen runtime command identities are missing or invalid", 1);
+  }
+  if (!surfaces.includes("codex-cli") && commands.codex !== null) {
+    fail("Cannot finalize production benchmark provider-free: frozen Codex command identity does not match the surface list", 1);
+  }
+  return commands;
+}
+
+export function isLegacyInvocation(argv) {
+  return argv.includes("--record") || argv.includes("--init");
+}
+
+export function privateDirectory(target) {
+  fs.mkdirSync(target, { recursive: true, mode: 0o700 });
+  try { fs.chmodSync(target, 0o700); } catch { /* Non-POSIX filesystem. */ }
+  return target;
+}
+
+export function defaultOutputRoot(bootstrapMetadata) {
+  if (bootstrapMetadata?.defaultOutputRoot) return bootstrapMetadata.defaultOutputRoot;
+  const agentRoot = process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+  return path.join(agentRoot, "benchmarks", "piagent");
+}
+
+export function createRunId(suiteId) {
+  const timestamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+  return `${suiteId}-${timestamp}-${crypto.randomBytes(3).toString("hex")}`;
+}
+
+export function ensureEmptyOutput(target) {
+  if (fs.existsSync(target) && fs.readdirSync(target).length > 0) fail(`Output directory is not empty: ${target}`, 1);
+  return privateDirectory(target);
+}
+
+export function benchmarkRunKey(value) {
+  return `${value.scenarioId ?? value.scenario?.id}\0${value.surface}\0${value.repeat}`;
+}
+
+export function samePairedBlock(left, right) {
+  return left?.scenario?.id === right?.scenario?.id && left?.repeat === right?.repeat;
+}
+
+export function pairedChunk(order, maximum) {
+  if (maximum === undefined || order.length <= maximum) return order;
+  let length = maximum;
+  while (length > 0 && samePairedBlock(order[length - 1], order[length])) length -= 1;
+  if (length === 0) fail(`--max-sessions ${maximum} would split the first paired benchmark block; increase the chunk size`, 1);
+  return order.slice(0, length);
+}
+
+function shellCommandArgument(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(text)) return text;
+  return `'${text.replaceAll("'", `'"'"'`)}'`;
+}
+
+export function benchmarkResumeCommand({ runRoot, productionSpendControlled, completedRuns, stageControl, stageBoundaries }) {
+  const base = `piagent-benchmark --resume ${shellCommandArgument(runRoot)}`;
+  if (!productionSpendControlled) return `${base} --yes`;
+  const window = productionStageResumeWindow(stageControl, { completedRuns, stageBoundaries });
+  return window?.remainingSessions > 0
+    ? `${base} --max-sessions ${window.remainingSessions} --yes`
+    : `${base} --yes`;
+}
+
+export function readJsonFile(file, label) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    fail(`Cannot read ${label} ${file}: ${error.message}`, 1);
+  }
+}
+
+function resolveResumeRunRoot(input) {
+  const target = path.resolve(input);
+  try {
+    const stat = fs.statSync(target);
+    if (stat.isDirectory()) return target;
+    if (stat.isFile()) return path.dirname(target);
+  } catch {
+    fail(`Cannot resume benchmark; path does not exist: ${target}`, 1);
+  }
+  fail(`Cannot resume benchmark; path is not a file or directory: ${target}`, 1);
+}
+
+export function loadResumeState(input) {
+  const runRoot = resolveResumeRunRoot(input);
+  const releaseRunLock = acquireBenchmarkRunLock(runRoot, "resume-pending");
+  try {
+    const manifestPath = path.join(runRoot, "run-manifest.json");
+    if (!fs.existsSync(manifestPath)) {
+      fail(`Cannot resume ${runRoot}: missing run-manifest.json. This run was created before resume metadata was written, so its root seed cannot be recovered safely. Start a new run with --max-sessions or --max-runtime-minutes to make it resumable.`, 1);
+    }
+    const manifest = readJsonFile(manifestPath, "benchmark resume manifest");
+    if (fs.existsSync(path.join(runRoot, "stopped.json"))) fail(`Cannot resume ${runRoot}: the paired release stop is terminal`, 1);
+    if (manifest?.schemaVersion !== 1 || typeof manifest.runId !== "string") {
+      fail(`Cannot resume ${runRoot}: run-manifest.json has an unsupported shape`, 1);
+    }
+    const ledger = benchmarkLedgerCheckpoint(
+      manifest.ledger,
+      inspectBenchmarkLedger(path.join(runRoot, "runs.jsonl")),
+      "benchmark resume ledger"
+    );
+    const pendingPath = path.join(runRoot, "pending-record.json");
+    const pendingRecord = fs.existsSync(pendingPath) ? readJsonFile(pendingPath, "benchmark pending record") : null;
+    const measuredPath = path.join(runRoot, "measured-record-ready.json");
+    const measuredReady = fs.existsSync(measuredPath) ? readJsonFile(measuredPath, "measured benchmark record") : null;
+    return {
+      runRoot,
+      manifest,
+      completedRuns: ledger.records,
+      ledgerBinding: ledger.binding,
+      recoveredLedgerSuffix: ledger.recovered,
+      pendingRecord,
+      measuredReady,
+      releaseRunLock
+    };
+  } catch (error) {
+    releaseRunLock();
+    throw error;
+  }
+}
+
+export function sameStringList(left, right) {
+  return Array.isArray(left)
+    && Array.isArray(right)
+    && left.length === right.length
+    && left.every((value, index) => value === right[index]);
+}
+
+export function formatDuration(ms) {
+  const totalSeconds = Math.max(0, Math.round(ms / 1_000));
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  if (hours > 0) return `${hours}h${String(minutes).padStart(2, "0")}m`;
+  if (minutes > 0) return `${minutes}m${String(seconds).padStart(2, "0")}s`;
+  return `${seconds}s`;
+}
+
+export function executionOrder(suite, repeats, surfaces, rootSeed) {
+  const order = [];
+  for (let repeat = 1; repeat <= repeats; repeat += 1) {
+    const scenarios = suite.schemaVersion === 2
+      ? [...suite.scenarios].sort((left, right) => {
+        const rank = (scenario) => crypto.createHmac("sha256", rootSeed).update(`order\0${repeat}\0${scenario.id}`).digest("hex");
+        return rank(left).localeCompare(rank(right));
+      })
+      : suite.scenarios;
+    for (const [index, scenario] of scenarios.entries()) {
+      const reverse = suite.schemaVersion === 2
+        ? (crypto.createHmac("sha256", rootSeed).update(`surface\0${repeat}\0${scenario.id}`).digest()[0] & 1) === 1
+        : (repeat + index) % 2 !== 0;
+      const ordered = reverse ? [...surfaces].reverse() : surfaces;
+      for (const surface of ordered) order.push({ scenario, surface, repeat });
+    }
+  }
+  return order;
+}
+
+export async function confirmPlan(message) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) fail("Refusing to start billed model runs without --yes in a non-interactive terminal", 1);
+  const terminal = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await terminal.question(`${message}\nContinue? [y/N] `);
+    return /^(?:y|yes)$/i.test(answer.trim());
+  } finally {
+    terminal.close();
+  }
+}
+
+export function invokedAsEntrypoint(metaUrl, argvEntry) {
+  try { return fs.realpathSync(fileURLToPath(metaUrl)) === fs.realpathSync(argvEntry || ""); }
+  catch { return metaUrl === pathToFileURL(argvEntry || "").href; }
+}