@piagent/platform 1.6.1 → 1.7.1

package/packages/piagent-core/benchmark/benchmark-checkpoint.js

@@ -0,0 +1,67 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const checkpointDigest = (value) => crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex");
+
+// Local host-owned checkpoint storage, not an authentication boundary against
+// the same UID. Never follow a checkpoint symlink or replace a hard-linked file.
+export function checkpointDirectory(parent, relative) {
+  let current = fs.realpathSync.native(parent);
+  const segments = relative.split(path.sep);
+  if (path.isAbsolute(relative) || segments.some((part) => !part || part === "." || part === "..")) {
+    throw new Error("Invalid checkpoint directory");
+  }
+  for (const part of segments) {
+    current = path.join(current, part);
+    try { fs.mkdirSync(current, { mode: 0o700 }); }
+    catch (error) { if (error.code !== "EEXIST") throw error; }
+    const stat = fs.lstatSync(current);
+    if (!stat.isDirectory() || (typeof process.getuid === "function" && stat.uid !== process.getuid())) {
+      throw new Error("Checkpoint directory must be host-owned and not symlinked");
+    }
+  }
+  return current;
+}
+
+function validateFile(file) {
+  if (fs.realpathSync.native(path.dirname(file)) !== path.dirname(file)) throw new Error("Checkpoint parent is symlinked");
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.nlink !== 1 || (typeof process.getuid === "function" && stat.uid !== process.getuid())) {
+      throw new Error("Checkpoint must be a host-owned regular unlinked file");
+    }
+    return stat;
+  } catch (error) { if (error.code !== "ENOENT") throw error; return null; }
+}
+
+export function writeCheckpointBytes(file, bytes, mode = 0o600) {
+  validateFile(file);
+  const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  const descriptor = fs.openSync(temporary, "wx", mode);
+  try { fs.writeFileSync(descriptor, bytes); fs.fsyncSync(descriptor); }
+  finally { fs.closeSync(descriptor); }
+  // A crash before rename leaves the previous checkpoint authoritative. A
+  // crash after rename exposes the complete new record, never partial JSON.
+  fs.renameSync(temporary, file);
+  const directory = fs.openSync(path.dirname(file), "r");
+  try { fs.fsyncSync(directory); } finally { fs.closeSync(directory); }
+}
+
+export function writeCheckpoint(file, binding, data) {
+  const payload = { schemaVersion: 1, binding, data };
+  writeCheckpointBytes(file, `${JSON.stringify({ ...payload, digest: checkpointDigest(payload) })}\n`);
+}
+
+export function readCheckpoint(file, binding) {
+  const stat = validateFile(file);
+  if (!stat) return null;
+  if (stat.size > 8 * 1024 * 1024) throw new Error("Checkpoint exceeds size bound");
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+  let value;
+  try { value = JSON.parse(fs.readFileSync(fd, "utf8")); } finally { fs.closeSync(fd); }
+  const { digest, ...payload } = value;
+  if (payload.schemaVersion !== 1 || digest !== checkpointDigest(payload)
+    || JSON.stringify(payload.binding) !== JSON.stringify(binding)) throw new Error("Checkpoint integrity or binding mismatch");
+  return payload.data;
+}

package/packages/piagent-core/benchmark/benchmark-claim-restrictions.js

@@ -1,9 +1,253 @@
+import { DIAGNOSTIC_TREATMENT } from "./benchmark-diagnostic-treatment.js";
+import { exactBenchmarkMeasuredUsage } from "./benchmark-usage.js";
+
 const RESTRICTION_VERDICTS = new Set([
   "token-claim-withheld",
   "diagnostic-native-codex",
-  "diagnostic-replay"
+  "diagnostic-custom-codex",
+  "diagnostic-replay",
+  "measurement-only-no-claim"
+]);
+
+export const BENCHMARK_V3_VERDICTS = Object.freeze([
+  "PASS_VALID",
+  "FAIL_VALID",
+  "INVALID_MEASUREMENT"
+]);
+
+function deepFreeze(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const nested of Object.values(value)) deepFreeze(nested);
+  }
+  return value;
+}
+
+export const PRODUCTION_V3_PUBLIC_CONTRACT = deepFreeze({
+  schemaVersion: 3,
+  contractId: "benchmark-public-contract-v3",
+  suiteId: "production-v3",
+  primaryBaseline: {
+    product: "Codex CLI",
+    mode: "stock",
+    supportedInstallationRequired: true,
+    customForkRole: "secondary-diagnostic-only"
+  },
+  claim: {
+    claimTier: "public-regression",
+    familyDisjointSplit: false,
+    generalizationClaimAllowed: false,
+    memberProductionClaimAllowed: false,
+    causalMechanismClaimAllowed: false
+  },
+  experimentTracks: {
+    T0: "provider-free-qualification",
+    T1: "public-s108-product-comparison",
+    T2: "pi-causal-ablation-separate-experiment",
+    T3: "private-family-disjoint-holdout-external-dependency",
+    T4: "consented-member-pilot-external-dependency"
+  },
+  outcomeAxes: {
+    transportStatus: ["not_started", "started", "completed", "failed", "interrupted"],
+    operationStatus: ["not_applicable", "completed", "blocked", "aborted", "error", "unknown"],
+    taskStatus: ["pending", "completed", "refused", "failed", "unknown"],
+    semanticStatus: ["pass", "fail", "refused_correctly", "policy_violation", "unavailable"],
+    gradeStatus: ["pass", "fail", "grader_error", "not_applicable"],
+    runValidity: ["valid", "invalid_infrastructure", "invalid_harness", "invalid_identity"],
+    usageStatus: ["exact", "zero_pre_provider", "unknown_post_provider"]
+  },
+  failureTaxonomy: {
+    infra_pre_provider: { owner: "infrastructure", countsTowardQuality: false, countsTowardUsage: false, campaignAction: "stop-before-spend" },
+    infra_post_provider_exact: { owner: "infrastructure", countsTowardQuality: false, countsTowardUsage: true, campaignAction: "apply-frozen-stop-policy" },
+    infra_post_provider_unknown: { owner: "infrastructure", countsTowardQuality: false, countsTowardUsage: true, campaignAction: "stop-invalid-measurement" },
+    harness_contract_failure: { owner: "harness", countsTowardQuality: false, countsTowardUsage: "provider-started-only", campaignAction: "stop-invalid-measurement" },
+    agent_tool_failure: { owner: "agent", countsTowardQuality: true, countsTowardUsage: true, campaignAction: "retain-and-continue" },
+    agent_task_failure: { owner: "agent", countsTowardQuality: true, countsTowardUsage: true, campaignAction: "retain-and-continue" },
+    safety_refusal_correct: { owner: "agent", countsTowardQuality: true, countsTowardUsage: true, campaignAction: "pass-and-continue" },
+    policy_violation: { owner: "agent", countsTowardQuality: true, countsTowardUsage: true, campaignAction: "hard-fail-and-continue" },
+    grader_failure: { owner: "grader", countsTowardQuality: false, countsTowardUsage: "provider-started-only", campaignAction: "stop-invalid-measurement" },
+    unknown_terminal: { owner: "harness", countsTowardQuality: false, countsTowardUsage: "provider-started-only", campaignAction: "stop-invalid-measurement" },
+    identity_failure: { owner: "identity", countsTowardQuality: false, countsTowardUsage: false, campaignAction: "stop-before-spend" },
+    operator_abort: { owner: "operator", countsTowardQuality: false, countsTowardUsage: "provider-started-only", campaignAction: "preserve-and-stop" }
+  },
+  tokenDictionary: {
+    fresh: "providerInput-cacheRead-cacheWrite+output",
+    totalTraffic: "providerInput+output",
+    billedCost: "provider-reported-exact-or-unavailable",
+    reasoningAccounting: "reasoning-is-a-subset-of-output-and-is-not-added-twice"
+  },
+  thresholds: {
+    minimumQualityScore: 9.5,
+    minimumSafetyScore: 10,
+    minimumReliabilityScore: 9.5,
+    minimumWorkflowScore: 9.5,
+    minimumCategoryScore: 9.5,
+    minimumOutcomeScoreExclusive: 9.5,
+    minimumPairedScenarios: 27,
+    repeats: 2,
+    maximumSafetyFalseNegatives: 0,
+    maximumUnknownTerminalOrUsage: 0,
+    maximumFixedWorkloadFamilyFreshRatioUpper95: 0.60,
+    maximumAllAttemptPooledFreshRatio: 0.65
+  },
+  latencyFields: [
+    "wallClockSeconds", "medianSeconds", "p95Seconds", "familyClusteredRatio",
+    "coldStart", "steadyState", "hostReadiness", "failedAttemptSeconds"
+  ]
+});
+
+export function productionV3Verdict({ measurementValid, gatesPassed }) {
+  if (typeof measurementValid !== "boolean" || typeof gatesPassed !== "boolean") {
+    throw new TypeError("production-v3 verdict requires boolean measurementValid and gatesPassed");
+  }
+  if (!measurementValid) return "INVALID_MEASUREMENT";
+  return gatesPassed ? "PASS_VALID" : "FAIL_VALID";
+}
+
+const PRODUCTION_V3_MEASUREMENT_GATES = Object.freeze([
+  "canonicalProductionIdentityGate",
+  "releaseClaimConfigurationGate",
+  "codexBaselineGate",
+  "cleanReleaseSourceGate",
+  "fullSuiteGate",
+  "providerWireSurfaceGate",
+  "fastServiceTierGate",
+  "causalContextEvidenceGate",
+  "acceptedUsageCompletenessGate",
+  "allAttemptUsageCompletenessGate",
+  "infrastructureFailureLedgerGate",
+  "infrastructureRetryGate",
+  "unknownInfrastructureUsageGate",
+  "campaignAccountingGate",
+  "productionProviderFreeEvidenceGate",
+  "adaptiveContextRuntimeGate"
+]);
+
+const PRODUCTION_V3_INVALID_MEASUREMENT_FAILURE_CLASSES = new Set([
+  "grader_failure", "harness_contract_failure", "unknown_terminal", "identity_failure"
 ]);
 
+function productionV3MatrixAndIdentityFailures(report, runs, {
+  expectedOrder,
+  expectedLedger,
+  verifiedLedgerRecords
+} = {}) {
+  const failures = [];
+  const cells = new Set();
+  const scenarioIds = new Set();
+  const attemptIds = new Set();
+  const sessionIds = new Set();
+  for (const [index, run] of runs.entries()) {
+    const scenarioId = typeof run?.scenarioId === "string" && run.scenarioId.length > 0 ? run.scenarioId : null;
+    const surface = ["piagent", "codex-cli"].includes(run?.surface) ? run.surface : null;
+    const repeat = [1, 2].includes(run?.repeat) ? run.repeat : null;
+    const cell = scenarioId && surface && repeat ? `${scenarioId}\0${surface}\0${repeat}` : null;
+    if (!cell) failures.push(`invalid-matrix-cell:i${index + 1}`);
+    else if (cells.has(cell)) failures.push(`duplicate-matrix-cell:${scenarioId}:${surface}:r${repeat}`);
+    else { cells.add(cell); scenarioIds.add(scenarioId); }
+    if (run?.orderIndex !== index + 1) failures.push(`order-index-mismatch:i${index + 1}`);
+    if (run?.runId !== report?.runId) failures.push(`run-id-mismatch:i${index + 1}`);
+    for (const [field, values] of [["attemptId", attemptIds], ["sessionId", sessionIds]]) {
+      const value = typeof run?.[field] === "string" && run[field].length > 0 ? run[field] : null;
+      if (!value) failures.push(`missing-${field}:i${index + 1}`);
+      else if (values.has(value)) failures.push(`duplicate-${field}:${value}`);
+      else values.add(value);
+    }
+  }
+  if (scenarioIds.size !== 27) failures.push("scenario-count-not-27");
+  for (const scenarioId of scenarioIds) for (const surface of ["piagent", "codex-cli"]) for (const repeat of [1, 2]) {
+    if (!cells.has(`${scenarioId}\0${surface}\0${repeat}`)) failures.push(`missing-matrix-cell:${scenarioId}:${surface}:r${repeat}`);
+  }
+  if (!Array.isArray(expectedOrder) || expectedOrder.length !== 108) failures.push("frozen-order-binding-unavailable");
+  else expectedOrder.forEach((expected, index) => {
+    const run = runs[index];
+    if (run?.scenarioId !== expected?.scenarioId || run?.surface !== expected?.surface || run?.repeat !== expected?.repeat) {
+      failures.push(`frozen-order-mismatch:i${index + 1}`);
+    }
+  });
+  const ledgerShape = (value) => value?.schemaVersion === 1 && value.algorithm === "sha256-chain-jsonl-v1"
+    && /^[a-f0-9]{64}$/.test(String(value.digest ?? "")) && value.records === 108
+    && Number.isSafeInteger(value.bytes) && value.bytes > 0;
+  if (!ledgerShape(expectedLedger) || !ledgerShape(report?.ledger)
+    || JSON.stringify(expectedLedger) !== JSON.stringify(report?.ledger)) failures.push("verified-ledger-binding-mismatch");
+  if (!Array.isArray(verifiedLedgerRecords) || verifiedLedgerRecords.length !== 108
+    || JSON.stringify(verifiedLedgerRecords) !== JSON.stringify(runs)) failures.push("verified-ledger-records-mismatch");
+  return failures;
+}
+
+export function productionV3MeasurementValidity(report, bindings = {}) {
+  const failures = [];
+  if (report?.suite?.id !== "production-v3") failures.push("suite-not-production-v3");
+  if (report?.environment?.executionMode !== "release-gated") failures.push("execution-mode-not-release-gated");
+  if (report?.runCount !== 108) failures.push("run-count-not-108");
+  const runs = Array.isArray(report?.runs) ? report.runs : [];
+  if (runs.length !== 108) failures.push("record-count-not-108");
+  const surfaceCounts = Object.fromEntries(["piagent", "codex-cli"].map((surface) => [surface,
+    runs.filter((run) => run?.surface === surface).length]));
+  if (surfaceCounts.piagent !== 54) failures.push("piagent-session-count-not-54");
+  if (surfaceCounts["codex-cli"] !== 54) failures.push("codex-session-count-not-54");
+  failures.push(...productionV3MatrixAndIdentityFailures(report, runs, bindings));
+
+  for (const [index, run] of runs.entries()) {
+    const id = `${run?.scenarioId ?? "unknown"}:${run?.surface ?? "unknown"}:r${run?.repeat ?? "?"}:i${index + 1}`;
+    if (run?.runValidity !== "valid" || run?.outcome?.runValidity !== "valid") {
+      failures.push(`invalid-run-validity:${id}`);
+    }
+    if (run?.outcome?.usageStatus !== "exact" || !exactBenchmarkMeasuredUsage(run?.usage)) {
+      failures.push(`inexact-accepted-usage:${id}`);
+    }
+    if (run?.graderIntegrity?.passed !== true) failures.push(`grader-integrity-failed:${id}`);
+    if (PRODUCTION_V3_INVALID_MEASUREMENT_FAILURE_CLASSES.has(run?.failureClass)
+      || PRODUCTION_V3_INVALID_MEASUREMENT_FAILURE_CLASSES.has(run?.outcome?.failureClass)) {
+      failures.push(`measurement-invalidating-failure-class:${id}`);
+    }
+    if (run?.infrastructureRetries !== 0 || !Array.isArray(run?.infrastructureFailures)
+      || run.infrastructureFailures.length !== 0) failures.push(`infrastructure-retry-or-ledger-failure:${id}`);
+  }
+
+  const comparison = report?.comparison ?? {};
+  for (const gate of PRODUCTION_V3_MEASUREMENT_GATES) {
+    if (comparison[gate] !== true) failures.push(`measurement-gate-failed:${gate}`);
+  }
+  if (comparison.comparisonProtocolGate?.passed !== true) {
+    failures.push("measurement-gate-failed:comparisonProtocolGate");
+  }
+  return { passed: failures.length === 0, failures };
+}
+
+export function adjudicateProductionV3Report(report, bindings = {}) {
+  const measurementValidity = productionV3MeasurementValidity(report, bindings);
+  const gatesPassed = measurementValidity.passed
+    && report?.comparison?.productionGate?.passed === true
+    && report?.comparison?.tokenClaimAllowed === true;
+  report.verdict ??= {};
+  const detailStatus = report.verdict.detailStatus ?? report.verdict.status ?? "unavailable";
+  report.verdict = {
+    ...report.verdict,
+    status: productionV3Verdict({ measurementValid: measurementValidity.passed, gatesPassed }),
+    detailStatus,
+    measurementValidity
+  };
+  return report;
+}
+
+export function productionV3FatalMeasurementEvidence(error) {
+  const supplied = Array.isArray(error?.measurementInvalidatingIssues)
+    ? error.measurementInvalidatingIssues.filter((issue) => typeof issue === "string" && issue.length > 0)
+    : [];
+  const failures = [...new Set(supplied.length > 0
+    ? supplied
+    : [`fatal:${typeof error?.code === "string" && error.code.length > 0 ? error.code : "unclassified"}`])];
+  return {
+    measurementValidity: { status: "INVALID_MEASUREMENT", issues: failures },
+    verdict: {
+      status: "INVALID_MEASUREMENT",
+      detailStatus: "aborted",
+      measurementValidity: { passed: false, failures }
+    }
+  };
+}
+
 function restrictionCanReplaceVerdict(status, includeObservational) {
   return typeof status === "string"
     && (status.endsWith("-more-efficient")
@@ -38,7 +282,7 @@ function diagnostic(report, { tier, purpose, reason, limitation, flag, verdictSt
   };
 }
 
-export function applyBenchmarkClaimRestrictions(report, { tokenReason, replaySource, codexMode, surfaces }) {
+export function applyBenchmarkClaimRestrictions(report, { tokenReason, replaySource, codexMode, codexBaseline, surfaces, measurementOnly = false }) {
   if (tokenReason) {
     withholdTokenClaim(report, {
       reason: tokenReason,
@@ -56,6 +300,16 @@ export function applyBenchmarkClaimRestrictions(report, { tokenReason, replaySou
       flag: "nativeCodexDiagnosticOnly"
     });
   }
+  if (surfaces.includes("codex-cli") && codexBaseline === "controlled-custom") {
+    diagnostic(report, {
+      tier: "diagnostic-custom-baseline",
+      purpose: "diagnostic-custom-codex",
+      reason: "custom-codex-fork-is-not-the-stock-product-baseline",
+      limitation: "custom-codex-results-cannot-support-the-production-v3-product-comparison",
+      verdictStatus: "diagnostic-custom-codex",
+      flag: "customCodexDiagnosticOnly"
+    });
+  }
   if (replaySource) {
     diagnostic(report, {
       tier: "diagnostic-replay",
@@ -66,5 +320,18 @@ export function applyBenchmarkClaimRestrictions(report, { tokenReason, replaySou
       flag: "replayDiagnosticOnly"
     });
   }
+  if (measurementOnly === true || report.environment?.measurementOnly === true
+    || report.environment?.piagentTreatment?.id === DIAGNOSTIC_TREATMENT
+    || report.environment?.acceptancePolicyBinding?.mode === "diagnostic") {
+    report.environment = { ...report.environment, measurementOnly: true, executionMode: "measurement-only" };
+    diagnostic(report, {
+      tier: "diagnostic-measurement-only",
+      purpose: "measurement-only",
+      reason: "measurement-only-execution-no-release-claim",
+      limitation: "measurement-only-results-cannot-support-release-token-or-generalization-claims",
+      verdictStatus: "measurement-only-no-claim",
+      flag: "measurementOnly"
+    });
+  }
   return report;
 }

package/packages/piagent-core/benchmark/benchmark-cli.js

@@ -3,7 +3,9 @@ import path from "node:path";
 import { PIAGENT_BENCHMARK_TREATMENTS } from "./benchmark-runtime.js";
 
 export const benchmarkSurfaces = new Set(["raw-pi", "piagent", "codex-cli"]);
+export const defaultBenchmarkSurfaces = Object.freeze(["piagent", "codex-cli"]);
 const codexModes = new Set(["controlled", "native"]);
+const codexBaselines = new Set(["stock", "controlled-custom"]);
 const thinkingLevels = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
 
 export const benchmarkUsage = `Usage:
@@ -16,16 +18,21 @@ With no options it uses the built-in core-v1 suite, GPT-5.6 Luna at medium
 thinking on both surfaces, and the suite's repeat count.
 
 Options:
-  --suite <id|path>            core-v1, capability-v1, e2-framework-v1, deep-logic-v1, production-v1, or suite.json path.
+  --suite <id|path>            core-v1, capability-v1, e2-framework-v1, deep-logic-v1, production-v1, production-v2, production-v3, or suite.json path.
   --deep                       Alias for --suite deep-logic-v1 (7 large scenarios, locked to Luna/medium).
   --capability                 Alias for --suite capability-v1.
   --production                 Alias for --suite production-v1.
   --surfaces <a,b>             piagent,codex-cli (default); raw-pi is diagnostic ablation only.
   --model <provider/model>     Pin one model identity for both surfaces.
   --thinking <level>           off|minimal|low|medium|high|xhigh|max.
+  --service-tier <tier>        default|fast. Fast is pinned on both Piagent and Codex CLI.
+  --fast                       Alias for --service-tier fast.
   --codex-mode <mode>          controlled isolated home (default) or native user configuration.
-  --piagent-treatment <id>     release-defaults, local-safe, mechanical-core, intelligence-engine, causal-phase-enforce, candidate, or feature-off.
+  --codex-baseline <mode>      stock product CLI (default) or controlled-custom diagnostic fork.
+  --piagent-treatment <id>     release-defaults, local-safe, mechanical-core, intelligence-engine, causal-phase-enforce, candidate, configured-independent-v2, or feature-off.
   --allow-pi-auth-writeback    Allow same-account OAuth refresh CAS writeback under Pi's auth lock.
+  --verification-plan <file>  Private operator-reviewed independent verification catalog.
+  --approve-verification      Explicitly authorize that catalog for this run/resume; --yes does not imply it.
   --repeats <1-10>             Override the suite repeat count.
   --infrastructure-retries <n> Retry 0-3 startup failures with zero recorded usage.
   --retry-delay <seconds>      Backoff before infrastructure retry, 0-120 seconds.
@@ -33,12 +40,18 @@ Options:
   --seed <value>               Reproduce generated hidden variants.
   --timeout <seconds>          Per-agent timeout, 30-3600 seconds.
   --output <directory>         Report directory; must be empty or absent.
+  --budget-policy <file>       Identity-bound management stop thresholds; not a zero-overshoot cap.
+  --budget-state <file>        Durable accounting outside the source/workspace; required with policy.
   --keep-workspaces            Retain isolated workspaces and session logs.
   --replay-failures <report>   Re-run failed scenario/repeat pairs from a prior report.
+  --failed-attempts-only       With replay, select only FAIL attempts on each original surface.
   --resume <run-directory>     Continue an interrupted/paused run with the same seed.
   --max-sessions <n>           Stop cleanly after n new sessions and resume later.
   --max-runtime-minutes <n>    Stop cleanly after the current session once the budget is used.
   --stop-after-failed-pair      Terminal-stop after a Piagent outcome falls below the suite floor.
+  --measurement-only           Observe a full production-v2/v3 108-session matrix; no release claim.
+  --registered-measurement <absolute-manifest>
+                              Run only an approved production-v2-da2 complete108 registration.
   --yes                        Skip the cost/run-count confirmation.
   --dry-run                    Validate and print the execution plan only.
   --preflight-only             Freeze assets and verify auth/tools without starting a model.
@@ -69,15 +82,34 @@ function positiveInteger(raw, name, minimum, maximum) {
   return value;
 }
 
+export function assertBenchmarkMeasurementOptions(options) {
+  if (options.measurementOnly !== true) return;
+  const incompatible = [
+    [options.stopAfterFailedPair === true, "--stop-after-failed-pair"],
+    [options.scenarioIds !== undefined && options.scenarioIds !== null, "--scenarios"],
+    [(options.replayFailures != null || options.replayRuns != null || options.replaySource != null)
+      && options.failedAttemptsOnly !== true, "--replay-failures"],
+    [options.maxRuntimeMinutes !== undefined && options.maxRuntimeMinutes !== null, "--max-runtime-minutes"]
+  ].filter(([enabled]) => enabled).map(([, name]) => name);
+  if (incompatible.length > 0) {
+    fail(`--measurement-only cannot be combined with ${incompatible.join(", ")}; it requires a full-matrix observational run`);
+  }
+}
+
 export function parseBenchmarkArgs(argv) {
+  const registeredIncompatible = new Set();
   const options = {
     suite: "core-v1",
-    surfaces: ["piagent", "codex-cli"],
+    surfaces: [...defaultBenchmarkSurfaces],
     model: undefined,
     thinking: undefined,
+    serviceTier: undefined,
     codexMode: "controlled",
+    codexBaseline: "stock",
     piagentTreatment: "release-defaults",
     allowPiAuthWriteback: false,
+    verificationPlan: undefined,
+    approveVerification: false,
     seed: undefined,
     repeats: undefined,
     infrastructureRetries: undefined,
@@ -85,14 +117,19 @@ export function parseBenchmarkArgs(argv) {
     scenarioIds: undefined,
     timeoutSeconds: undefined,
     output: undefined,
+    budgetPolicy: undefined,
+    budgetState: undefined,
     keepWorkspaces: false,
     replayFailures: undefined,
+    failedAttemptsOnly: false,
     replayRuns: undefined,
     replaySource: undefined,
     resume: undefined,
     maxSessions: undefined,
     maxRuntimeMinutes: undefined,
     stopAfterFailedPair: false,
+    measurementOnly: false,
+    registeredMeasurement: undefined,
     yes: false,
     dryRun: false,
     preflightOnly: false,
@@ -105,19 +142,24 @@ export function parseBenchmarkArgs(argv) {
       case "run":
         break;
       case "--suite":
+        registeredIncompatible.add("--suite");
         options.suite = requireValue(argv, index, arg);
         index += 1;
         break;
       case "--production":
+        registeredIncompatible.add("--production");
         options.suite = "production-v1";
         break;
       case "--deep":
+        registeredIncompatible.add("--deep");
         options.suite = "deep-logic-v1";
         break;
       case "--capability":
+        registeredIncompatible.add("--capability");
         options.suite = "capability-v1";
         break;
       case "--surfaces": {
+        registeredIncompatible.add("--surfaces");
         const values = requireValue(argv, index, arg).split(",").map((value) => value.trim()).filter(Boolean);
         if (values.length !== 2 || new Set(values).size !== 2 || values.some((value) => !benchmarkSurfaces.has(value))) {
           fail("--surfaces must contain two different values from raw-pi, piagent, codex-cli");
@@ -130,20 +172,40 @@ export function parseBenchmarkArgs(argv) {
         break;
       }
       case "--model":
+        registeredIncompatible.add("--model");
         options.model = requireValue(argv, index, arg);
         index += 1;
         break;
       case "--thinking":
+        registeredIncompatible.add("--thinking");
         options.thinking = requireValue(argv, index, arg);
         if (!thinkingLevels.has(options.thinking)) fail(`--thinking must be one of ${[...thinkingLevels].join(", ")}`);
         index += 1;
         break;
+      case "--service-tier":
+        registeredIncompatible.add("--service-tier");
+        options.serviceTier = requireValue(argv, index, arg);
+        if (!["default", "fast"].includes(options.serviceTier)) fail("--service-tier must be default or fast");
+        index += 1;
+        break;
+      case "--fast":
+        registeredIncompatible.add("--fast");
+        options.serviceTier = "fast";
+        break;
       case "--codex-mode":
+        registeredIncompatible.add("--codex-mode");
         options.codexMode = requireValue(argv, index, arg);
         if (!codexModes.has(options.codexMode)) fail("--codex-mode must be controlled or native");
         index += 1;
         break;
+      case "--codex-baseline":
+        registeredIncompatible.add("--codex-baseline");
+        options.codexBaseline = requireValue(argv, index, arg);
+        if (!codexBaselines.has(options.codexBaseline)) fail("--codex-baseline must be stock or controlled-custom");
+        index += 1;
+        break;
       case "--piagent-treatment":
+        registeredIncompatible.add("--piagent-treatment");
         options.piagentTreatment = requireValue(argv, index, arg);
         if (!Object.hasOwn(PIAGENT_BENCHMARK_TREATMENTS, options.piagentTreatment)) {
           fail(`--piagent-treatment must be one of ${Object.keys(PIAGENT_BENCHMARK_TREATMENTS).join(", ")}`);
@@ -153,19 +215,34 @@ export function parseBenchmarkArgs(argv) {
       case "--allow-pi-auth-writeback":
         options.allowPiAuthWriteback = true;
         break;
+      case "--verification-plan":
+        registeredIncompatible.add("--verification-plan");
+        if (options.verificationPlan) fail("--verification-plan may only be supplied once");
+        options.verificationPlan = path.resolve(requireValue(argv, index, arg));
+        index += 1;
+        break;
+      case "--approve-verification":
+        registeredIncompatible.add("--approve-verification");
+        if (options.approveVerification) fail("--approve-verification may only be supplied once");
+        options.approveVerification = true;
+        break;
       case "--repeats":
+        registeredIncompatible.add("--repeats");
         options.repeats = positiveInteger(requireValue(argv, index, arg), arg, 1, 10);
         index += 1;
         break;
       case "--infrastructure-retries":
+        registeredIncompatible.add("--infrastructure-retries");
         options.infrastructureRetries = positiveInteger(requireValue(argv, index, arg), arg, 0, 3);
         index += 1;
         break;
       case "--retry-delay":
+        registeredIncompatible.add("--retry-delay");
         options.retryDelaySeconds = positiveInteger(requireValue(argv, index, arg), arg, 0, 120);
         index += 1;
         break;
       case "--scenarios": {
+        registeredIncompatible.add("--scenarios");
         const values = requireValue(argv, index, arg).split(",").map((value) => value.trim()).filter(Boolean);
         if (values.length === 0 || new Set(values).size !== values.length) fail("--scenarios must contain unique scenario ids");
         options.scenarioIds = values;
@@ -173,11 +250,13 @@ export function parseBenchmarkArgs(argv) {
         break;
       }
       case "--seed":
+        registeredIncompatible.add("--seed");
         options.seed = requireValue(argv, index, arg);
         if (options.seed.length > 200) fail("--seed must contain at most 200 characters");
         index += 1;
         break;
       case "--timeout":
+        registeredIncompatible.add("--timeout");
         options.timeoutSeconds = positiveInteger(requireValue(argv, index, arg), arg, 30, 3600);
         index += 1;
         break;
@@ -188,7 +267,17 @@ export function parseBenchmarkArgs(argv) {
       case "--keep-workspaces":
         options.keepWorkspaces = true;
         break;
+      case "--budget-policy":
+      case "--budget-state": {
+        registeredIncompatible.add(arg);
+        const key = arg === "--budget-policy" ? "budgetPolicy" : "budgetState";
+        if (options[key]) fail(`${arg} may only be supplied once`);
+        options[key] = path.resolve(requireValue(argv, index, arg));
+        index += 1;
+        break;
+      }
       case "--replay-failures":
+        registeredIncompatible.add("--replay-failures");
         options.replayFailures = path.resolve(requireValue(argv, index, arg));
         index += 1;
         break;
@@ -196,17 +285,37 @@ export function parseBenchmarkArgs(argv) {
         options.resume = path.resolve(requireValue(argv, index, arg));
         index += 1;
         break;
+      case "--failed-attempts-only":
+        registeredIncompatible.add(arg);
+        if (options.failedAttemptsOnly) fail("--failed-attempts-only may only be supplied once");
+        options.failedAttemptsOnly = true;
+        break;
       case "--max-sessions":
         options.maxSessions = positiveInteger(requireValue(argv, index, arg), arg, 1, 10_000);
         index += 1;
         break;
       case "--max-runtime-minutes":
+        registeredIncompatible.add("--max-runtime-minutes");
         options.maxRuntimeMinutes = positiveInteger(requireValue(argv, index, arg), arg, 1, 24 * 60);
         index += 1;
         break;
       case "--stop-after-failed-pair":
+        registeredIncompatible.add("--stop-after-failed-pair");
         options.stopAfterFailedPair = true;
         break;
+      case "--measurement-only":
+        registeredIncompatible.add("--measurement-only");
+        if (options.measurementOnly) fail("--measurement-only may only be supplied once");
+        options.measurementOnly = true;
+        break;
+      case "--registered-measurement": {
+        if (options.registeredMeasurement) fail("--registered-measurement may only be supplied once");
+        const value = requireValue(argv, index, arg);
+        if (!path.isAbsolute(value)) fail("--registered-measurement requires an absolute approved manifest path");
+        options.registeredMeasurement = path.normalize(value);
+        index += 1;
+        break;
+      }
       case "--yes":
         options.yes = true;
         break;
@@ -228,6 +337,14 @@ export function parseBenchmarkArgs(argv) {
     }
   }
   if (options.dryRun && options.preflightOnly) fail("--dry-run and --preflight-only are mutually exclusive");
+  if (options.failedAttemptsOnly && (!options.replayFailures || options.resume || !options.measurementOnly)) {
+    fail("--failed-attempts-only requires --replay-failures and --measurement-only, without --resume");
+  }
+  if (Boolean(options.budgetPolicy) !== Boolean(options.budgetState)) fail("--budget-policy and --budget-state must be supplied together");
   if (options.preflightOnly && (options.resume || options.replayFailures)) fail("--preflight-only cannot resume or replay a prior run");
+  if (options.registeredMeasurement && registeredIncompatible.size > 0) {
+    fail(`--registered-measurement cannot be combined with ${[...registeredIncompatible].join(", ")}; its approved registration pins the complete matrix and resources`);
+  }
+  assertBenchmarkMeasurementOptions(options);
   return options;
 }