@piagent/platform 1.6.1 → 1.7.1

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

@@ -1,6 +1,24 @@
+function conditionalBothPassUsageText(report) {
+  const value = report.comparison?.conditionalBothPassFreshUsage;
+  if (!value) return "Conditional both-pass fresh usage: unavailable";
+  return `Conditional both-pass fresh usage: ratio ${display(value.ratio, 4)} | eligible ${value.eligiblePairs}/${value.observedPairs} observed pairs (${value.expectedPairs} expected) | both resolved ${value.bothResolvedPairs} | excluded unresolved ${value.excludedUnresolvedPairs}, usage ${value.excludedUsagePairs} | unpaired accepted runs ${value.unpairedAcceptedRuns}. Accepted attempts only; includes safety refusals; not overall token savings.`;
+}
+
+import { renderBenchmarkGoalHtml, renderBenchmarkGoalMarkdown, renderBenchmarkGoalText } from "./benchmark-goal-report.js";
+
 const SURFACE_LABELS = Object.freeze({ "raw-pi": "Raw Pi", piagent: "Piagent", "codex-cli": "Codex CLI" });
 const SURFACE_REPORT_KEYS = Object.freeze({ "raw-pi": "rawPi", piagent: "piagent", "codex-cli": "codexCli" });
 
+function publicationLines(report) {
+  const value = report.publicationAuthorization;
+  return value ? [
+    `Publication authorization: ${value.status} | claim allowed: ${value.allowed === true ? "yes" : "no"} | launcher stage: ${value.stageId}`,
+    `Publication boundary: ${value.explanation}`,
+    `Management-threshold overshoot: fresh tokens ${value.managementThresholdOvershoot?.freshTokens ?? "pending"}; active wall ms ${value.managementThresholdOvershoot?.activeWallTimeMs ?? "pending"}. No absolute provider-side hard cap is claimed.`,
+    `Launcher publication failures: ${(value.failures ?? []).join(", ") || "none recorded"}`
+  ] : [];
+}
+
 function surfaceLabel(surface) {
   return SURFACE_LABELS[surface] ?? surface;
 }
@@ -37,6 +55,25 @@ function workflowGapSummary(runs) {
   return topToolSummary(gaps);
 }
 
+function outcomeContractSummary(runs) {
+  const outcomeRuns = (runs ?? []).filter((run) => ["failureClass", "countsTowardQuality",
+    "countsTowardUsage", "runValidity"].every((field) => Object.hasOwn(run, field)));
+  if (outcomeRuns.length === 0) return null;
+  const counts = (field) => Object.entries(outcomeRuns.reduce((result, run) => {
+    const value = String(run[field]);
+    result[value] = (result[value] ?? 0) + 1;
+    return result;
+  }, {})).sort(([left], [right]) => left.localeCompare(right))
+    .map(([value, count]) => `${value}=${count}`).join(", ");
+  return {
+    runs: outcomeRuns.length,
+    quality: outcomeRuns.filter((run) => run.countsTowardQuality === true).length,
+    usage: outcomeRuns.filter((run) => run.countsTowardUsage === true).length,
+    failureClasses: counts("failureClass"),
+    validity: counts("runValidity")
+  };
+}
+
 function pairedOutcomeSummary(value, candidateLabel, baselineLabel) {
   if (!value) return "n/a";
   return `both ${value.bothPass} | ${candidateLabel}-only ${value.candidateOnlyPass} | ${baselineLabel}-only ${value.baselineOnlyPass} | neither ${value.bothFail}`;
@@ -117,11 +154,17 @@ export function renderBenchmarkText(report) {
   const causalContext = report.comparison.causalContextEvidence;
   const causalAggregates = causalContext?.aggregates;
   const hostReadiness = report.environment.hostReadinessHistory;
+  const allAttemptEfficiency = report.comparison.allAttemptPooledEfficiency;
+  const serviceTier = report.comparison.serviceTierEvidence;
+  const campaignEvidence = report.environment.campaignEvidence;
+  const priorCampaignHistory = campaignEvidence?.priorCampaignHistory;
+  const outcomeSummary = outcomeContractSummary(report.runs);
   const suiteFailureReasons = (report.comparison.suiteGate?.failureReasons ?? [])
     .map((failure) => `${failure.id}: ${failure.message}`)
     .join("; ");
   const lines = [
     `Piagent Benchmark — ${report.suite.title}`,
+    ...publicationLines(report),
     `Run: ${report.runId} | ${report.runCount} sessions | ${report.repeats} repeat(s)`,
     runtimeParts.join(" | "),
     `Treatment baseline: ${report.environment.treatmentBaseline ?? "unknown"}`,
@@ -135,6 +178,11 @@ export function renderBenchmarkText(report) {
       : []),
     `Suite digest: ${report.environment.suiteDigest ?? "unknown"} | Source: ${report.environment.source?.kind ?? "unknown"}${report.environment.source?.dirty === true ? " (dirty)" : ""}`,
     `Infrastructure: ${report.infrastructure?.attempts ?? report.runCount} attempts | ${report.infrastructure?.retries ?? 0} retries across ${report.infrastructure?.retriedRuns ?? 0} measured runs`,
+    conditionalBothPassUsageText(report),
+    ...(outcomeSummary ? [
+      `Failure classes: ${outcomeSummary.failureClasses}`,
+      `Outcome accounting: quality ${outcomeSummary.quality}/${outcomeSummary.runs} | usage ${outcomeSummary.usage}/${outcomeSummary.runs} | validity ${outcomeSummary.validity}`
+    ] : []),
     "",
     "Surface     Resolved   Task grade    Scope     Quality  Safety  Reliability  Workflow  Efficiency  Overall",
     scoreLine(baselineLabel, baseline),
@@ -152,6 +200,14 @@ export function renderBenchmarkText(report) {
     `Piagent workflow gaps: ${workflowGapSummary(report.runs.filter((run) => run.surface === "piagent"))}`,
     `Token accounting: input=fresh input; reasoning is included in output; fresh=input+output; total=input+cache read+cache write+output`,
     `Attempt completeness: accepted ${report.tokenAccounting?.acceptedAttempts.exactAttempts ?? 0}/${report.tokenAccounting?.acceptedAttempts.attempts ?? 0} exact | failed ${report.tokenAccounting?.failedAttempts.exactAttempts ?? 0}/${report.tokenAccounting?.failedAttempts.attempts ?? 0} exact | failed fresh ${display(report.tokenAccounting?.failedAttempts.tokens.fresh, 0)}`,
+    `All-attempt net fresh tokens: ${candidateLabel} ${display(allAttemptEfficiency?.candidate?.freshTokens, 0)} | ${baselineLabel} ${display(allAttemptEfficiency?.baseline?.freshTokens, 0)} | ratio ${display(allAttemptEfficiency?.ratio, 4)} | reduction ${displayPercent(allAttemptEfficiency?.reductionPercent)} | gate ${allAttemptEfficiency?.passed === null ? "n/a" : allAttemptEfficiency?.passed ? "pass" : "fail"}`,
+    ...(campaignEvidence ? [
+      `Current paid campaign: ${campaignEvidence.status} | exact ${campaignEvidence.allAttempts?.exactAttempts ?? 0}/${campaignEvidence.providerStartedAttempts ?? 0} | unknown ${campaignEvidence.unknownAttempts ?? 0} | claim ${campaignEvidence.claimOutcome?.allowed === true ? "allowed" : campaignEvidence.claimOutcome?.allowed === false ? "not allowed" : "pending"}`,
+      `Prior paid campaigns (excluded from current net ratio): ${priorCampaignHistory?.paidCampaigns ?? 0} | provider attempts ${priorCampaignHistory?.providerStartedAttempts ?? 0} | exact ${priorCampaignHistory?.exactAttempts ?? 0} | unknown ${priorCampaignHistory?.unknownAttempts ?? 0} | ${priorCampaignHistory?.exactUsageComplete === true ? `exact known fresh ${display(priorCampaignHistory?.knownExactTokens?.fresh, 0)}` : `total usage unavailable; known-exact fresh subtotal ${display(priorCampaignHistory?.knownExactTokens?.fresh, 0)}`}`
+    ] : []),
+    `Fast execution configuration parity: ${serviceTier?.executionConfigurationParityGate === null ? "n/a" : serviceTier?.executionConfigurationParityGate ? "pass" : "fail"} | claim boundary ${serviceTier?.claimBoundary ?? "unavailable"}`,
+    `Provider response tier: ${serviceTier?.providerResponseEvidenceGate === null ? "not exposed by host" : serviceTier?.providerResponseEvidenceGate ? "verified fast/priority" : "default/invalid observed"} | actual provider-tier claim ${serviceTier?.actualProviderProcessingTierClaimAllowed ? "allowed" : "not allowed"}`,
+    `Fast billing references: ChatGPT credits ${display(serviceTier?.subscriptionCreditAccounting?.referenceRates?.chatgptSubscriptionCredits?.multiplier, 1)}x | API token price ${display(serviceTier?.subscriptionCreditAccounting?.referenceRates?.apiFastTokenPricing?.multiplier, 1)}x | actual billing mode/multiplier unverified | non-blocking | excluded from token ratio`,
     "",
     `Paired successful runs: ${report.comparison.pairedSuccessfulRuns}`,
     `Paired runs with comparable usage: ${report.comparison.pairedUsageRuns}`,
@@ -243,7 +299,8 @@ export function renderBenchmarkText(report) {
     `Verdict: ${report.verdict.status}`,
     `Token-saving claim allowed: ${report.comparison.tokenClaimAllowed ? "yes" : "no"}`,
     `Generalization claim allowed: ${report.comparison.claimEligibility?.generalizationClaimAllowed ? "yes" : "no"}`,
-    `Claim limitations: ${(report.comparison.claimEligibility?.limitations ?? []).join(", ") || "none"}`
+    `Claim limitations: ${(report.comparison.claimEligibility?.limitations ?? []).join(", ") || "none"}`,
+    ...(report.goalAssessment ? ["", renderBenchmarkGoalText(report.goalAssessment)] : [])
   ];
   return `${lines.join("\n")}\n`;
 }
@@ -252,6 +309,14 @@ function htmlEscape(value) {
   return String(value ?? "").replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
 }
 
+export function renderBenchmarkMarkdown(report) {
+  const detail = renderBenchmarkText({ ...report, goalAssessment: undefined });
+  // A dynamic fence preserves arbitrary diagnostic text without markdown injection.
+  const fence = "`".repeat(Math.max(3, ...[...detail.matchAll(/`+/g)].map(match => match[0].length + 1)));
+  return `# Piagent benchmark report\n\n${renderBenchmarkGoalMarkdown(report.goalAssessment)}\n`
+    + `## Existing benchmark detail\n\n${fence}text\n${detail}${fence}\n`;
+}
+
 export function renderBenchmarkHtml(report) {
   const baselineSurface = report.comparison.baselineSurface ?? "raw-pi";
   const candidateSurface = report.comparison.candidateSurface ?? "piagent";
@@ -260,7 +325,7 @@ export function renderBenchmarkHtml(report) {
   const surfaceEntries = [[baselineSurface, report.surfaces[baselineKey]], [candidateSurface, report.surfaces[candidateKey]]];
   const baselineLabel = surfaceLabel(baselineSurface);
   const candidateLabel = surfaceLabel(candidateSurface);
-  const rows = report.runs.map((run) => `<tr><td>${htmlEscape(run.scenarioId)}</td><td>${htmlEscape(run.category ?? "unspecified")}</td><td>${htmlEscape(run.difficulty ?? "unspecified")}</td><td>${htmlEscape(run.profile ?? "unspecified")}</td><td>${htmlEscape(run.lifecycle ?? "unspecified")}</td><td>${htmlEscape(run.surface)}</td><td>${run.repeat}</td><td>${run.infrastructureRetries ?? 0}</td><td>${run.resolved ? "PASS" : "FAIL"}</td><td>${run.grade?.passed ? "PASS" : "FAIL"}</td><td>${run.scope?.passed ? "PASS" : "FAIL"}</td><td>${display(run.workflow?.score)}</td><td>${htmlEscape((run.workflow?.checks ?? []).filter((check) => !check.passed).map((check) => check.id).join(", ") || "none")}</td><td>${htmlEscape(run.usage?.model ?? "unknown")}</td><td>${htmlEscape(run.usage?.thinkingLevel ?? "unknown")}</td><td>${htmlEscape(run.usage?.usageSource ?? "unknown")}</td><td>${display(run.usage?.input, 0)}</td><td>${display(run.usage?.output, 0)}</td><td>${display(run.usage?.cacheRead, 0)}</td><td>${display(run.usage?.cacheWrite, 0)}</td><td>${display(run.usage?.reasoning, 0)}</td><td>${display(run.usage?.fresh, 0)}</td><td>${display(run.usage?.total, 0)}</td><td>${display(run.usage?.toolCalls, 0)}</td><td>${htmlEscape(topToolSummary(run.usage?.toolNames, 5))}</td><td>${display(run.usage?.cost, 6)}</td><td>${display(run.durationSeconds, 1)}</td><td>${htmlEscape(run.failure ?? "")}</td></tr>`).join("");
+  const rows = report.runs.map((run) => `<tr><td>${htmlEscape(run.scenarioId)}</td><td>${htmlEscape(run.category ?? "unspecified")}</td><td>${htmlEscape(run.difficulty ?? "unspecified")}</td><td>${htmlEscape(run.profile ?? "unspecified")}</td><td>${htmlEscape(run.lifecycle ?? "unspecified")}</td><td>${htmlEscape(run.surface)}</td><td>${run.repeat}</td><td>${run.infrastructureRetries ?? 0}</td><td>${run.resolved ? "PASS" : "FAIL"}</td><td>${run.grade?.passed ? "PASS" : "FAIL"}</td><td>${run.scope?.passed ? "PASS" : "FAIL"}</td><td>${htmlEscape(run.failureClass ?? "n/a")}</td><td>${run.countsTowardQuality === true ? "yes" : run.countsTowardQuality === false ? "no" : "n/a"}</td><td>${run.countsTowardUsage === true ? "yes" : run.countsTowardUsage === false ? "no" : "n/a"}</td><td>${htmlEscape(run.runValidity ?? "n/a")}</td><td>${display(run.workflow?.score)}</td><td>${htmlEscape((run.workflow?.checks ?? []).filter((check) => !check.passed).map((check) => check.id).join(", ") || "none")}</td><td>${htmlEscape(run.usage?.model ?? "unknown")}</td><td>${htmlEscape(run.usage?.thinkingLevel ?? "unknown")}</td><td>${htmlEscape(run.usage?.usageSource ?? "unknown")}</td><td>${display(run.usage?.input, 0)}</td><td>${display(run.usage?.output, 0)}</td><td>${display(run.usage?.cacheRead, 0)}</td><td>${display(run.usage?.cacheWrite, 0)}</td><td>${display(run.usage?.reasoning, 0)}</td><td>${display(run.usage?.fresh, 0)}</td><td>${display(run.usage?.total, 0)}</td><td>${display(run.usage?.toolCalls, 0)}</td><td>${htmlEscape(topToolSummary(run.usage?.toolNames, 5))}</td><td>${display(run.usage?.cost, 6)}</td><td>${display(run.durationSeconds, 1)}</td><td>${htmlEscape(run.failure ?? "")}</td></tr>`).join("");
   const scoreRows = surfaceEntries.map(([id, surface]) => `<tr><th>${htmlEscape(surfaceLabel(id))}</th><td>${surface.resolved}/${surface.runs}</td><td>${surface.qualityCorrect}/${surface.qualityRuns}</td><td>${surface.scopePassed}/${surface.runs}</td><td>${display(surface.scores.quality)}</td><td>${display(surface.scores.safety)}</td><td>${display(surface.scores.reliability)}</td><td>${display(surface.scores.workflow)}</td><td>${display(surface.scores.efficiency)}</td><td>${display(surface.scores.overall)}</td></tr>`).join("");
   const usageRows = surfaceEntries.map(([id, surface]) => { const usage = surface.usage.allMeasuredRuns; return `<tr><th>${htmlEscape(surfaceLabel(id))}</th><td>${display(usage.medianInputTokens, 0)}</td><td>${display(usage.medianOutputTokens, 0)}</td><td>${display(usage.medianCacheReadTokens, 0)}</td><td>${display(usage.medianCacheWriteTokens, 0)}</td><td>${display(usage.medianReasoningTokens, 0)}</td><td>${display(usage.medianFreshTokens, 0)}</td><td>${display(usage.medianTotalTokens, 0)}</td><td>${display(usage.medianToolCalls, 0)}</td><td>${display(usage.medianCost, 6)}</td><td>${display(usage.medianDurationSeconds, 1)}</td><td>${htmlEscape(topToolSummary(surface.usage.toolNames))}</td></tr>`; }).join("");
   const categoryRows = Object.entries(report.surfaces[candidateKey].bands?.categories ?? {}).map(([name, band]) => `<tr><th>${htmlEscape(name)}</th><td>${band.resolved}/${band.runs}</td><td>${display(band.score)}</td><td>${display(band.correctness)}</td></tr>`).join("");
@@ -278,6 +343,10 @@ export function renderBenchmarkHtml(report) {
   const causalContext = report.comparison.causalContextEvidence;
   const causalAggregates = causalContext?.aggregates;
   const hostReadiness = report.environment.hostReadinessHistory;
+  const allAttemptEfficiency = report.comparison.allAttemptPooledEfficiency;
+  const serviceTier = report.comparison.serviceTierEvidence;
+  const campaignEvidence = report.environment.campaignEvidence;
+  const priorCampaignHistory = campaignEvidence?.priorCampaignHistory;
   const suiteFailureReasons = (report.comparison.suiteGate?.failureReasons ?? [])
     .map((failure) => `${failure.id}: ${failure.message}`)
     .join("; ");
@@ -285,17 +354,23 @@ export function renderBenchmarkHtml(report) {
 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Piagent Benchmark ${htmlEscape(report.runId)}</title>
 <style>body{font:14px system-ui,sans-serif;color:#202124;max-width:1180px;margin:32px auto;padding:0 20px}h1{font-size:24px}h2{font-size:17px;margin-top:28px}.table-wrap{overflow-x:auto}table{border-collapse:collapse;width:100%;white-space:nowrap}th,td{border:1px solid #d8dadd;padding:8px;text-align:left}thead th{background:#f4f5f6}.metric{display:inline-block;margin:0 24px 8px 0}.note{color:#5f6368}</style></head><body>
 <h1>Piagent Benchmark</h1><p>${htmlEscape(report.suite.title)} · ${htmlEscape(report.runId)}</p><p class="note">Platform v${htmlEscape(report.environment.platformVersion ?? "unknown")} · Pi ${htmlEscape(report.environment.piVersion ?? "unknown")}${report.environment.codexVersion ? ` · Codex ${htmlEscape(report.environment.codexVersion)}` : ""} · Node ${htmlEscape(report.environment.nodeVersion ?? "unknown")} · Baseline ${htmlEscape(report.environment.treatmentBaseline ?? "unknown")} · Piagent treatment ${htmlEscape(report.environment.piagentTreatment?.id ?? "unrecorded")} · Suite ${htmlEscape(report.environment.suiteDigest ?? "unknown")}</p>
+${publicationLines(report).map(line => `<p class="note">${htmlEscape(line)}</p>`).join("\n")}
 <p class="metric"><strong>Comparison:</strong> ${htmlEscape(candidateLabel)} vs ${htmlEscape(baselineLabel)}</p><p class="metric"><strong>Purpose:</strong> ${htmlEscape(report.comparison.purpose ?? "unspecified")}</p><p class="metric"><strong>Claim tier:</strong> ${htmlEscape(report.comparison.claimEligibility?.achievedTier ?? "unavailable")}</p><p class="metric"><strong>Token claim scope:</strong> ${htmlEscape(report.comparison.claimEligibility?.tokenClaimScope ?? "unavailable")}</p>${report.comparison.tokenClaimUnavailableReason ? `<p class="metric"><strong>Token claim restriction:</strong> ${htmlEscape(report.comparison.tokenClaimUnavailableReason)}</p>` : ""}<p class="metric"><strong>Verdict:</strong> ${htmlEscape(report.verdict.status)}</p><p class="metric"><strong>Protocol:</strong> ${report.comparison.comparisonProtocolGate?.passed ? "PASS" : `FAIL (${htmlEscape((report.comparison.comparisonProtocolGate?.failedChecks ?? []).join(", ") || "missing evidence")})`}</p><p class="metric"><strong>Codex-relative gate:</strong> ${report.comparison.codexRelativeEfficiencyGate === null ? "n/a" : report.comparison.codexRelativeEfficiencyGate ? "PASS" : "FAIL"}</p><p class="metric"><strong>Total token traffic:</strong> ${display(codexRelative?.totalTokenTraffic?.ratio, 4)}${codexRelativeTrafficConfidence ? ` (${display(codexRelativeTrafficConfidence.lower, 4)}–${display(codexRelativeTrafficConfidence.upper, 4)})` : ""} · upper ≤ ${display(codexRelative?.policy?.maximumTotalTokenTrafficRatioUpper95, 2)}</p><p class="metric"><strong>API-equivalent cost:</strong> ${display(codexRelative?.apiEquivalentCost?.ratio, 4)}${codexRelativeCostConfidence ? ` (${display(codexRelativeCostConfidence.lower, 4)}–${display(codexRelativeCostConfidence.upper, 4)})` : ""} · upper ≤ ${display(codexRelative?.policy?.maximumApiEquivalentCostRatioUpper95, 2)}</p><p class="metric"><strong>Subagent traffic:</strong> ${displayRatioPercent(codexRelative?.subagents?.trafficShare)} · ${codexRelative?.subagents?.sessions ?? "n/a"} sessions</p><p class="metric"><strong>Provider wire:</strong> ${report.comparison.providerWireSurfaceGate === null ? "n/a" : report.comparison.providerWireSurfaceGate ? "PASS" : "FAIL"} (${report.comparison.providerWireEvidence?.verifiedRuns ?? 0}/${report.comparison.providerWireEvidence?.runs ?? 0} runs, ${(report.comparison.providerWireEvidence?.driftGroups ?? []).length} drift groups)</p><p class="metric"><strong>Causal receipt:</strong> ${report.comparison.causalContextEvidenceGate === null ? "n/a" : report.comparison.causalContextEvidenceGate ? "PASS" : "FAIL"} (current v${causalContext?.requiredSchemaVersion ?? "?"} ${causalContext?.currentAvailableRuns ?? 0}/${causalContext?.runs ?? 0} runs)</p><p class="metric"><strong>Host readiness:</strong> ${report.comparison.hostReadinessGate === null ? "n/a" : report.comparison.hostReadinessGate ? "PASS" : "FAIL"} (${hostReadiness?.validReceiptCount ?? 0}/${hostReadiness?.receiptCount ?? 0} valid receipts · ${htmlEscape(hostReadiness?.windowCoverage ?? "n/a")} coverage)</p><p class="metric"><strong>Causal packs:</strong> ${causalAggregates ? `${causalAggregates.packCounts.offered}/${causalAggregates.packCounts.delivered}/${causalAggregates.packCounts.injected} offered/delivered/injected · ${causalAggregates.estimatedTokens.injected} injected estimated tokens · ${causalAggregates.selectedItemCounts.injected} selected items` : "unavailable"}</p><p class="metric"><strong>Causal direct rereads:</strong> ${causalAggregates ? `${causalAggregates.directFallbackRereads.successfulCalls} successful direct-path calls · ${causalAggregates.directFallbackRereads.shellToolCallsObserved} shell calls after injection` : "unavailable"}</p><p class="metric"><strong>Causal edit recovery:</strong> ${causalAggregates?.editRecoveryContext ? `${causalAggregates.editRecoveryContext.count ?? "n/a"} contexts · ${causalAggregates.editRecoveryContext.injectedChars ?? "n/a"} chars · ${causalAggregates.editRecoveryContext.injectedEstimatedTokens ?? "n/a"} estimated tokens · ${htmlEscape(causalAggregates.editRecoveryContext.evidenceCoverage?.status ?? "unavailable")} evidence` : "unavailable"}</p><p class="metric"><strong>Suite gate:</strong> ${report.comparison.suiteGate ? report.comparison.suiteGate.passed ? "PASS" : "FAIL" : "n/a"}</p><p class="metric"><strong>Infrastructure retries:</strong> ${report.infrastructure?.retries ?? 0}</p><p class="metric"><strong>Stability gate:</strong> ${report.comparison.stabilityGate === null ? "n/a" : report.comparison.stabilityGate ? "PASS" : "FAIL"}</p><p class="metric"><strong>Primary estimand:</strong> ${htmlEscape(report.comparison.primaryEfficiencyEstimand ?? "unavailable")}</p><p class="metric"><strong>Primary token delta:</strong> ${displayPercent(report.comparison.primaryEfficiencyDeltaPercent)}</p><p class="metric"><strong>Primary ratio 95% CI:</strong> ${primaryConfidence ? `${display(primaryConfidence.lower, 4)}–${display(primaryConfidence.upper, 4)}` : "n/a"}</p><p class="metric"><strong>Fixed-workload ratio:</strong> ${display(report.comparison.fixedWorkloadFamilyFreshTokenRatio, 4)}${fixedWorkloadConfidence ? ` (${display(fixedWorkloadConfidence.lower, 4)}–${display(fixedWorkloadConfidence.upper, 4)})` : ""}</p><p class="metric"><strong>Fixed-workload coverage:</strong> ${report.comparison.fixedWorkloadFamilyCoverage?.usableScenarioFamilies ?? 0}/${report.comparison.fixedWorkloadFamilyCoverage?.expectedScenarioFamilies ?? 0} families</p><p class="metric"><strong>Successful-pair diagnostic role:</strong> ${htmlEscape(report.comparison.successfulPairEfficiencyRole ?? "blocking")}</p><p class="metric"><strong>Successful-pair token delta:</strong> ${displayPercent(report.comparison.freshTokenDeltaPercent)}</p><p class="metric"><strong>Successful-pair ratio 95% CI:</strong> ${confidence ? `${display(confidence.lower, 4)}–${display(confidence.upper, 4)}` : "n/a"}</p><p class="metric"><strong>Normalized API-equivalent text-token cost ratio:</strong> ${display(normalizedCost?.ratio, 4)}${normalizedCostConfidence ? ` (${display(normalizedCostConfidence.lower, 4)}–${display(normalizedCostConfidence.upper, 4)})` : ""}</p><p class="metric"><strong>Normalized-cost gate:</strong> ${report.comparison.normalizedCostGate === null ? "n/a" : report.comparison.normalizedCostGate ? "PASS" : "FAIL"}</p><p class="metric"><strong>Failure-aware family ratio:</strong> ${display(report.comparison.failureAwareFamilyFreshTokenRatio, 4)}${failureAwareFamilyConfidence ? ` (${display(failureAwareFamilyConfidence.lower, 4)}–${display(failureAwareFamilyConfidence.upper, 4)})` : ""}</p><p class="metric"><strong>Failure-aware pooled ratio:</strong> ${display(report.comparison.failureAwareFreshTokenRatio, 4)}</p><p class="metric"><strong>Duration-ratio delta:</strong> ${displayPercent(report.comparison.durationDeltaPercent)}</p><p class="metric"><strong>Duration ratio 95% CI:</strong> ${durationConfidence ? `${display(durationConfidence.lower, 4)}–${display(durationConfidence.upper, 4)}` : "n/a"}</p><p class="metric"><strong>Performance gate:</strong> ${report.comparison.performanceGate === null ? "n/a" : report.comparison.performanceGate ? "PASS" : "FAIL"}</p><p class="metric"><strong>Provider-reported cost-ratio delta:</strong> ${displayPercent(report.comparison.costDeltaPercent)}</p><p class="metric"><strong>Comparable pairs:</strong> ${report.comparison.pairedUsageRuns}</p><p class="metric"><strong>Scenario families:</strong> ${report.comparison.pairedUsageScenarios ?? 0}</p><p class="metric"><strong>Complete families:</strong> ${report.comparison.pairedCompleteScenarios ?? 0}</p><p class="metric"><strong>Duration families:</strong> ${report.comparison.pairedCompleteDurationScenarios ?? 0}</p><p class="metric"><strong>Outcome families:</strong> ${report.comparison.pairedOutcomeScenarios ?? 0}</p><p class="metric"><strong>Pair wins:</strong> ${htmlEscape(candidateLabel)} ${report.comparison.pairedFreshTokenWins[candidateKey]} · ${htmlEscape(baselineLabel)} ${report.comparison.pairedFreshTokenWins[baselineKey]} · ties ${report.comparison.pairedFreshTokenWins.ties}</p>
 <p class="metric"><strong>Observational timing (${htmlEscape(baselineLabel)}):</strong> ${htmlEscape(timingSummary(report.timingDiagnostics, baselineSurface))}</p><p class="metric"><strong>Observational timing (${htmlEscape(candidateLabel)}):</strong> ${htmlEscape(timingSummary(report.timingDiagnostics, candidateSurface))}</p>
+<p class="note">${htmlEscape(conditionalBothPassUsageText(report))}</p>
 <p class="note">Timing uses privacy-safe monotonic JSONL receipt boundaries only. Missing boundaries remain unavailable; these diagnostics do not alter authoritative duration or any release/spend gate.</p>
 <p class="metric"><strong>Edit-recovery failures:</strong> ${causalAggregates?.editRecoveryContext?.failuresObserved ?? "n/a"} observed · ${causalAggregates?.editRecoveryContext?.suppressedFailures ?? "n/a"} safely suppressed</p>
-<p class="metric"><strong>Exact attempts:</strong> accepted ${report.tokenAccounting?.acceptedAttempts.exactAttempts ?? 0}/${report.tokenAccounting?.acceptedAttempts.attempts ?? 0} · failed ${report.tokenAccounting?.failedAttempts.exactAttempts ?? 0}/${report.tokenAccounting?.failedAttempts.attempts ?? 0}</p><p class="metric"><strong>Failed-attempt fresh:</strong> ${display(report.tokenAccounting?.failedAttempts.tokens.fresh, 0)}</p>
+	<p class="metric"><strong>Exact attempts:</strong> accepted ${report.tokenAccounting?.acceptedAttempts.exactAttempts ?? 0}/${report.tokenAccounting?.acceptedAttempts.attempts ?? 0} · failed ${report.tokenAccounting?.failedAttempts.exactAttempts ?? 0}/${report.tokenAccounting?.failedAttempts.attempts ?? 0}</p><p class="metric"><strong>Failed-attempt fresh:</strong> ${display(report.tokenAccounting?.failedAttempts.tokens.fresh, 0)}</p>
+	<p class="metric"><strong>All-attempt net fresh:</strong> ${htmlEscape(candidateLabel)} ${display(allAttemptEfficiency?.candidate?.freshTokens, 0)} · ${htmlEscape(baselineLabel)} ${display(allAttemptEfficiency?.baseline?.freshTokens, 0)} · ratio ${display(allAttemptEfficiency?.ratio, 4)} · reduction ${displayPercent(allAttemptEfficiency?.reductionPercent)} · ${allAttemptEfficiency?.passed === null ? "n/a" : allAttemptEfficiency?.passed ? "PASS" : "FAIL"}</p>
+	${campaignEvidence ? `<p class="metric"><strong>Current paid campaign:</strong> ${htmlEscape(campaignEvidence.status)} · exact ${campaignEvidence.allAttempts?.exactAttempts ?? 0}/${campaignEvidence.providerStartedAttempts ?? 0} · unknown ${campaignEvidence.unknownAttempts ?? 0} · claim ${campaignEvidence.claimOutcome?.allowed === true ? "allowed" : campaignEvidence.claimOutcome?.allowed === false ? "not allowed" : "pending"}</p><p class="metric"><strong>Prior paid campaigns (excluded from current net ratio):</strong> ${priorCampaignHistory?.paidCampaigns ?? 0} · provider attempts ${priorCampaignHistory?.providerStartedAttempts ?? 0} · exact ${priorCampaignHistory?.exactAttempts ?? 0} · unknown ${priorCampaignHistory?.unknownAttempts ?? 0} · ${priorCampaignHistory?.exactUsageComplete === true ? `exact known fresh ${display(priorCampaignHistory?.knownExactTokens?.fresh, 0)}` : `total usage unavailable; known-exact fresh subtotal ${display(priorCampaignHistory?.knownExactTokens?.fresh, 0)}`}</p>` : ""}
+	<p class="metric"><strong>Fast execution configuration parity:</strong> ${serviceTier?.executionConfigurationParityGate === null ? "n/a" : serviceTier?.executionConfigurationParityGate ? "PASS" : "FAIL"} · boundary ${htmlEscape(serviceTier?.claimBoundary ?? "unavailable")}</p><p class="metric"><strong>Provider response tier:</strong> ${serviceTier?.providerResponseEvidenceGate === null ? "not exposed by host" : serviceTier?.providerResponseEvidenceGate ? "verified fast/priority" : "default/invalid observed"}</p><p class="metric"><strong>Fast billing references:</strong> ChatGPT credits ${display(serviceTier?.subscriptionCreditAccounting?.referenceRates?.chatgptSubscriptionCredits?.multiplier, 1)}x · API token price ${display(serviceTier?.subscriptionCreditAccounting?.referenceRates?.apiFastTokenPricing?.multiplier, 1)}x · actual billing mode/multiplier unverified · non-blocking · excluded from token ratio</p>
 <p class="note"><strong>Token definitions:</strong> Input is fresh input only. Reasoning is already included in output. Fresh = input + output. Total = input + cache read + cache write + output. Normalized API-equivalent cost uses the versioned suite pricing snapshot and is not OAuth/provider-billed cost.</p>
 ${suiteFailureReasons ? `<p><strong>Suite gate failures:</strong> ${htmlEscape(suiteFailureReasons)}</p>` : ""}
+${renderBenchmarkGoalHtml(report.goalAssessment)}
 <h2>Score bands</h2><div class="table-wrap"><table><thead><tr><th>Surface</th><th>Resolved</th><th>Task grader</th><th>Scope</th><th>Quality</th><th>Safety</th><th>Reliability</th><th>Workflow</th><th>Efficiency</th><th>Overall</th></tr></thead><tbody>${scoreRows}</tbody></table></div>
 ${categoryRows ? `<h2>${htmlEscape(candidateLabel)} category bands</h2><div class="table-wrap"><table><thead><tr><th>Category</th><th>Resolved</th><th>Score</th><th>Correctness</th></tr></thead><tbody>${categoryRows}</tbody></table></div>` : ""}
 ${tokenBandRows ? `<h2>Paired fresh-token ratio by category</h2><div class="table-wrap"><table><thead><tr><th>Category</th><th>Pairs</th><th>Families</th><th>Ratio</th><th>Median delta</th><th>${htmlEscape(candidateLabel)}/${htmlEscape(baselineLabel)}/ties</th></tr></thead><tbody>${tokenBandRows}</tbody></table></div>` : ""}
 <h2>Median usage across all measured runs</h2><div class="table-wrap"><table><thead><tr><th>Surface</th><th>Fresh input</th><th>Output</th><th>Cache read</th><th>Cache write</th><th>Reasoning ⊂ output</th><th>Fresh</th><th>Total</th><th>Tools</th><th>Provider-reported cost</th><th>Seconds</th><th>Top tools</th></tr></thead><tbody>${usageRows}</tbody></table></div>
-<h2>Runs</h2><div class="table-wrap"><table><thead><tr><th>Scenario</th><th>Category</th><th>Difficulty</th><th>Profile</th><th>Lifecycle</th><th>Surface</th><th>Repeat</th><th>Infra retries</th><th>Resolved</th><th>Grader</th><th>Scope</th><th>Workflow</th><th>Workflow gaps</th><th>Model</th><th>Thinking</th><th>Usage source</th><th>Fresh input</th><th>Output</th><th>Cache read</th><th>Cache write</th><th>Reasoning ⊂ output</th><th>Fresh</th><th>Total</th><th>Tools</th><th>Top tools</th><th>Provider-reported cost</th><th>Seconds</th><th>Failure</th></tr></thead><tbody>${rows}</tbody></table></div>
+<h2>Runs</h2><div class="table-wrap"><table><thead><tr><th>Scenario</th><th>Category</th><th>Difficulty</th><th>Profile</th><th>Lifecycle</th><th>Surface</th><th>Repeat</th><th>Infra retries</th><th>Resolved</th><th>Grader</th><th>Scope</th><th>Failure class</th><th>Counts toward quality</th><th>Counts toward usage</th><th>Run validity</th><th>Workflow</th><th>Workflow gaps</th><th>Model</th><th>Thinking</th><th>Usage source</th><th>Fresh input</th><th>Output</th><th>Cache read</th><th>Cache write</th><th>Reasoning ⊂ output</th><th>Fresh</th><th>Total</th><th>Tools</th><th>Top tools</th><th>Provider-reported cost</th><th>Seconds</th><th>Failure</th></tr></thead><tbody>${rows}</tbody></table></div>
 <p class="note">${htmlEscape(report.verdict.note)}</p></body></html>\n`;
 }

package/packages/piagent-core/benchmark/benchmark-resume-recovery.js

@@ -1,8 +1,9 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 
 import { hardenPrivateRetentionRoot, retainedWorkspaceMarker, writeBenchmarkRunManifest, writePrivateAtomic } from "./benchmark-forensics.js";
-import { appendBenchmarkLedger, assertBenchmarkLedgerBinding, validateBenchmarkLedgerPrefix } from "./benchmark-ledger.js";
+import { appendBenchmarkLedger, assertBenchmarkLedgerBinding, benchmarkLedgerCheckpoint, inspectBenchmarkLedger, validateBenchmarkLedgerPrefix } from "./benchmark-ledger.js";
 import { expectedBenchmarkRecord, pairedBenchmarkVariantMatched } from "./benchmark-record-validation.js";
 import { canonicalBenchmarkTimingDiagnostics } from "./benchmark-timing-diagnostics.js";
 
@@ -23,7 +24,7 @@ function key(value) {
 
 function exactUsage(usage, usageStatus) {
   const nonnegative = (value) => Number.isFinite(value) && value >= 0;
-  return usageStatus !== "unknown-after-provider-start"
+  return !["unknown-after-provider-start", "measured-lower-bound"].includes(usageStatus)
     && Number.isInteger(usage?.sessions) && usage.sessions > 0
     && ["fresh", "input", "output", "cacheRead", "cacheWrite", "reasoning", "total"].every((field) => nonnegative(usage?.[field]))
     && usage.fresh === usage.input + usage.output
@@ -52,6 +53,7 @@ export function persistUnacceptedBenchmarkAttempt({ runRoot, manifest, record, r
     class: record.infrastructureClass ?? "infrastructure",
     usage: record.usage,
     usageStatus: record.usageStatus ?? "unknown-after-provider-start",
+    retryable: record.infrastructureRetryable === true,
     durationSeconds: record.durationSeconds ?? 0,
     recoveredFromInFlight: false
   };
@@ -76,7 +78,7 @@ export function stageMeasuredBenchmarkRecord({ runRoot, manifest, ledgerBinding,
   record.infrastructureAttempts = record.infrastructureAttempt ?? 1;
   record.infrastructureRetries = Math.max(0, record.infrastructureAttempts - 1);
   record.infrastructureFailures = infrastructureFailures;
-  if (!expectedBenchmarkRecord(record, index, expected, runId, suite, configurationDigest) || !pairedBenchmarkVariantMatched(record, runs)) {
+  if (!expectedBenchmarkRecord(record, index, expected, runId, suite, configurationDigest, manifest.verificationPlan?.identity) || !pairedBenchmarkVariantMatched(record, runs)) {
     persistUnacceptedBenchmarkAttempt({ runRoot, manifest, record, reason: "measured-record-identity-or-paired-fixture-mismatch", forceTokenUnavailable: true });
     fail(`Runner produced an incomplete, identity-mismatched, or unpaired-fixture record for ${record.scenarioId}/${record.surface}/r${record.repeat}`);
   }
@@ -106,7 +108,7 @@ export function recoverPendingBenchmarkRecord({ runRoot, manifest, ledgerBinding
     if (pending.schemaVersion !== 2 || !pending.previousLedger || !pending.record || pending.postSessionGuard?.matched !== true
       || !String(pending.postSessionGuard.stage ?? "").startsWith("after-session:")) fail("Benchmark pending record is missing its post-session execution guard receipt");
     const expectedIndex = pending.record.orderIndex - 1;
-    if (!expectedBenchmarkRecord(pending.record, expectedIndex, fullOrder[expectedIndex], manifest.runId, suite, manifest.configurationDigest)) {
+    if (!expectedBenchmarkRecord(pending.record, expectedIndex, fullOrder[expectedIndex], manifest.runId, suite, manifest.configurationDigest, manifest.verificationPlan?.identity)) {
       fail("Benchmark pending record does not match the frozen execution order");
     }
     if (binding.records === pending.previousLedger.records) {
@@ -132,7 +134,7 @@ export function recoverPendingBenchmarkRecord({ runRoot, manifest, ledgerBinding
   if (measuredReady) {
     if (measuredReady.schemaVersion !== 1 || !measuredReady.previousLedger || !measuredReady.record) fail("Measured benchmark record WAL is malformed");
     const expectedIndex = measuredReady.record.orderIndex - 1;
-    if (!expectedBenchmarkRecord(measuredReady.record, expectedIndex, fullOrder[expectedIndex], manifest.runId, suite, manifest.configurationDigest)) {
+    if (!expectedBenchmarkRecord(measuredReady.record, expectedIndex, fullOrder[expectedIndex], manifest.runId, suite, manifest.configurationDigest, manifest.verificationPlan?.identity)) {
       fail("Measured benchmark record WAL does not match the frozen execution order");
     }
     if (pending) {
@@ -151,7 +153,7 @@ export function recoverPendingBenchmarkRecord({ runRoot, manifest, ledgerBinding
   const completedKeys = validateBenchmarkLedgerPrefix(
     runs,
     fullOrder,
-    (record, index, expected) => expectedBenchmarkRecord(record, index, expected, manifest.runId, suite, manifest.configurationDigest)
+    (record, index, expected) => expectedBenchmarkRecord(record, index, expected, manifest.runId, suite, manifest.configurationDigest, manifest.verificationPlan?.identity)
   );
   return { ledgerBinding: binding, completedRuns: runs, completedKeys, recoveredPending: Boolean(pending) };
 }
@@ -229,11 +231,20 @@ export function recoverOrphanedBenchmarkAttempts({ runRoot, manifest, fullOrder,
       surface: attempt.surface,
       repeat: attempt.repeat,
       attempt: attempt.infrastructureAttempt,
-      failure: "orphaned-provider-attempt-after-process-exit",
-      class: "infrastructure",
+      failure: attempt.stage === "provider-returned" && typeof attempt.infrastructureFailure === "string"
+        ? attempt.infrastructureFailure
+        : "orphaned-provider-attempt-after-process-exit",
+      class: attempt.stage === "provider-returned" && typeof attempt.infrastructureClass === "string"
+        ? attempt.infrastructureClass
+        : "infrastructure",
+      retryable: attempt.stage === "provider-returned" && attempt.infrastructureRetryable === true,
       usage: attempt.stage === "provider-returned" ? attempt.usage : undefined,
-      usageStatus: attempt.stage === "provider-returned" && exactUsage(attempt.usage, "measured-but-unaccepted") ? "measured-but-unaccepted" : "unknown-after-provider-start",
-      durationSeconds: 0,
+      usageStatus: attempt.stage === "provider-returned" && exactUsage(attempt.usage, attempt.usageStatus ?? "measured-but-unaccepted")
+        ? (attempt.usageStatus ?? "measured-but-unaccepted")
+        : "unknown-after-provider-start",
+      durationSeconds: Number.isFinite(attempt.durationSeconds) && attempt.durationSeconds >= 0
+        ? attempt.durationSeconds
+        : null,
       recoveredFromInFlight: true
     };
     const prior = seenAttempts.get(attemptKey);
@@ -274,3 +285,262 @@ export function recoverOrphanedBenchmarkAttempts({ runRoot, manifest, fullOrder,
   }
   return attemptsByKey;
 }
+
+const observationProtocol = "runtime-observation-v2";
+const observationHash = value => crypto.createHash("sha256").update(value).digest("hex");
+const observationEqual = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+function observationRequire(value, reason) {
+  if (value) return;
+  const error = new Error(`Benchmark observation ${reason}`);
+  error.code = "BENCHMARK_OBSERVATION_INVALID";
+  error.exitCode = 1;
+  throw error;
+}
+function observationObject(value, fields, reason) {
+  observationRequire(value && typeof value === "object" && !Array.isArray(value)
+    && observationEqual(Object.keys(value).sort(), [...fields].sort()), reason);
+}
+function observationText(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= 4096 && !value.includes("\0");
+}
+function observationPrivateFile(file) {
+  const stat = fs.lstatSync(file);
+  observationRequire(fs.realpathSync(file) === file && stat.isFile() && stat.nlink === 1
+    && stat.uid === process.getuid() && (stat.mode & 0o777) === 0o600, "private-file-invalid");
+  return stat;
+}
+function observationResumable(state) {
+  return state.pending === null && state.runtimes.every(runtime => runtime.retired && !runtime.operationRef
+    && (!runtime.wireCheckpoint || runtime.wireCheckpoint.operationActive === false && runtime.wireCheckpoint.inputAccepted === false
+      && runtime.wireCheckpoint.pending === false && runtime.wireCheckpoint.fault === null
+      && (runtime.wireCheckpoint.task === null || runtime.wireCheckpoint.task.phase === "terminal"
+        && ["completed", "blocked", "partial", "failed"].includes(runtime.wireCheckpoint.task.outcome)))
+    && runtime.callbacks.every(callback => callback.stage === "outer-rejected" || callback.stage === "settled"));
+}
+function advanceObservationRuntimes(state, event, requests) {
+  observationRequire(event && typeof event === "object" && observationText(event.runtimeInstanceRef), "event-identity-invalid");
+  const runtimes = structuredClone(state.runtimes);
+  let runtime = runtimes.find(row => row.runtimeInstanceRef === event.runtimeInstanceRef);
+  if (event.kind === "generation-created") {
+    observationRequire(Number.isSafeInteger(event.runtimeGeneration) && event.runtimeGeneration === (runtime?.runtimeGeneration ?? 0) + 1
+      && observationText(event.sessionId) && path.isAbsolute(event.cwd), "generation-reservation-invalid");
+    observationRequire(!runtime?.operationRef && (!runtime || observationResumable({ pending: null, runtimes: [runtime] })), "generation-has-unresolved-attempt");
+    observationRequire(!runtimes.some(row => row !== runtime && row.sessionId === event.sessionId
+      && (!row.retired || !observationResumable({ pending: null, runtimes: [row] }))), "session-generation-still-owned");
+    const next = { runtimeInstanceRef: event.runtimeInstanceRef, runtimeGeneration: event.runtimeGeneration,
+      sessionId: event.sessionId, cwd: event.cwd, ready: false, retired: false, operationRef: null,
+      callbackSequence: runtime?.sessionId === event.sessionId ? runtime.callbackSequence : 0,
+      operations: runtime?.operations ?? [], callbacks: runtime?.callbacks ?? [] };
+    if (runtime) runtimes[runtimes.indexOf(runtime)] = next;
+    else runtimes.push(next);
+    return runtimes;
+  }
+  observationRequire(runtime, "runtime-unreserved");
+  if (event.kind === "runtime-retired") {
+    observationRequire(event.generation === runtime.runtimeGeneration, "retired-generation-mismatch");
+    runtime.retired = true; runtime.ready = false;
+    if (runtime.operationRef) runtime.operations.find(row => row.operationRef === runtime.operationRef).ended = true;
+    runtime.operationRef = null;
+    return runtimes;
+  }
+  observationRequire(event.runtimeGeneration === runtime.runtimeGeneration
+    && (!runtime.retired || ["wire-checkpoint", "outer-rejected"].includes(event.kind)), "generation-mismatch");
+  if (event.kind === "generation-bound") {
+    observationRequire(!runtime.ready, "generation-already-bound"); runtime.ready = true;
+  } else if (event.kind === "operation-accepted") {
+    const request = requests.find(row => row.messageRequestId === event.messageRequestId);
+    observationRequire(runtime.ready && !runtime.operationRef && observationText(event.operationRef) && request
+      && request.operatorInputSha256 === event.operatorInputSha256, "operation-unreserved");
+    observationRequire(runtimes.every(row => row.callbacks.every(callback => ["outer-rejected", "settled"].includes(callback.stage))), "prior-callback-unresolved");
+    observationRequire(!runtimes.some(row => row.operations.some(operation => operation.operationRef === event.operationRef
+      || operation.messageRequestId === event.messageRequestId)), "operation-reused");
+    runtime.operations.push({ operationRef: event.operationRef, messageRequestId: event.messageRequestId, ended: false });
+    runtime.operationRef = event.operationRef;
+  } else if (event.kind === "operation-ended") {
+    observationRequire(runtime.operationRef === event.operationRef, "operation-end-mismatch");
+    runtime.operations.find(row => row.operationRef === event.operationRef).ended = true;
+    runtime.operationRef = null;
+  } else if (event.kind === "host-origin") {
+    observationRequire(runtime.operationRef || event.event?.type === "task-cached" && event.event.taskRunId === null, "origin-without-reservation");
+  } else if (event.kind === "wire-checkpoint") {
+    const checkpoint = event.checkpoint;
+    observationObject(checkpoint, ["protocol", "schemaVersion", "manifestDigest", "workingDirectory", "sessionId", "runtimeInstanceRef",
+      "sequence", "previousReceiptHash", "task", "events", "operationActive", "inputAccepted", "pending", "fault"], "wire-checkpoint-shape");
+    observationRequire(checkpoint.protocol === "host-wire-checkpoint-v1" && checkpoint.schemaVersion === 1
+      && checkpoint.sessionId === runtime.sessionId && checkpoint.runtimeInstanceRef === runtime.runtimeInstanceRef
+      && checkpoint.workingDirectory === runtime.cwd && /^[a-f0-9]{64}$/.test(checkpoint.manifestDigest)
+      && Number.isSafeInteger(checkpoint.sequence) && checkpoint.sequence >= 0
+      && (checkpoint.previousReceiptHash === null || /^[a-f0-9]{64}$/.test(checkpoint.previousReceiptHash))
+      && Array.isArray(checkpoint.events) && ["operationActive", "inputAccepted", "pending"].every(field => typeof checkpoint[field] === "boolean")
+      && (checkpoint.fault === null || observationText(checkpoint.fault)), "wire-checkpoint-invalid");
+    if (checkpoint.task !== null) {
+      observationObject(checkpoint.task, ["taskId", "taskRunId", "phase", "sequence", "outcome", "stateDigest"], "wire-task-shape");
+      observationRequire(["taskId", "taskRunId", "phase"].every(field => observationText(checkpoint.task[field]))
+        && Number.isSafeInteger(checkpoint.task.sequence) && checkpoint.task.sequence >= 0
+        && ["pending", "completed", "blocked", "partial", "failed"].includes(checkpoint.task.outcome)
+        && /^[a-f0-9]{64}$/.test(checkpoint.task.stateDigest), "wire-task-invalid");
+    }
+    runtime.wireCheckpoint = structuredClone(checkpoint);
+  } else if (event.kind === "outer-attempt") {
+    observationRequire(runtime.ready && runtime.operationRef && Number.isSafeInteger(event.sequence)
+      && event.sequence === runtime.callbackSequence + 1, "callback-reservation-invalid");
+    runtime.callbackSequence = event.sequence;
+    runtime.callbacks.push({ sequence: event.sequence, runtimeGeneration: event.runtimeGeneration,
+      operationRef: runtime.operationRef, stage: "outer-attempt" });
+  } else {
+    observationRequire(["sdk-returned", "return-ready", "outer-rejected"].includes(event.kind), "event-kind-unsupported");
+    const callback = runtime.callbacks.find(row => row.sequence === event.sequence && row.runtimeGeneration === event.runtimeGeneration);
+    observationRequire(callback && (event.kind === "outer-rejected" && ["outer-attempt", "sdk-returned", "return-ready"].includes(callback.stage)
+      || event.kind === "sdk-returned" && callback.stage === "outer-attempt"
+      || event.kind === "return-ready" && callback.stage === "sdk-returned"), "callback-order-invalid");
+    if (event.kind !== "outer-rejected") observationRequire(runtime.operationRef === callback.operationRef
+      && event.operationRef === callback.operationRef, "callback-operation-mismatch");
+    callback.stage = event.kind;
+  }
+  return runtimes;
+}
+
+/** Host-only parent capability. Private locked run custody, not journal JSON, supplies the restart anchor. */
+export function createBenchmarkObservationCustody({ runRoot, manifest, identity, journalPath, publicKey, requests }) {
+  const root = path.resolve(runRoot), journal = path.resolve(journalPath), manifestPath = path.join(root, "run-manifest.json");
+  observationObject(identity, ["protocol", "runId", "attemptId", "armId", "candidateDigest", "configurationDigest", "keyId"], "identity-shape-invalid");
+  identity = structuredClone(identity); requests = structuredClone(requests);
+  observationRequire(identity.protocol === observationProtocol && ["runId", "attemptId", "armId"].every(field => observationText(identity[field]))
+    && ["candidateDigest", "configurationDigest", "keyId"].every(field => /^[a-f0-9]{64}$/.test(identity[field])), "identity-invalid");
+  observationRequire(Array.isArray(requests) && requests.length > 0 && requests.every(row => observationText(row.messageRequestId)
+    && /^[a-f0-9]{64}$/.test(row.operatorInputSha256)) && new Set(requests.map(row => row.messageRequestId)).size === requests.length, "requests-invalid");
+  const key = publicKey?.type === "public" ? publicKey : crypto.createPublicKey(publicKey);
+  const publicKeyDer = key.export({ type: "spki", format: "der" });
+  observationRequire(key.asymmetricKeyType === "ed25519" && observationHash(publicKeyDer) === identity.keyId, "key-mismatch");
+  observationRequire(path.isAbsolute(runRoot) && path.isAbsolute(journalPath) && journal.startsWith(root + path.sep), "journal-location-invalid");
+  const rootStat = fs.lstatSync(root), lockPath = path.join(root, ".benchmark-run.lock"), lockStat = observationPrivateFile(lockPath);
+  const parentPath = path.dirname(journal), parentStat = fs.lstatSync(parentPath), initialJournal = observationPrivateFile(journal);
+  observationRequire(JSON.parse(fs.readFileSync(lockPath, "utf8")).pid === process.pid, "run-lock-not-owned");
+  const identityDigest = observationHash(JSON.stringify(identity));
+  let state, fault = null, token = null;
+  const guard = () => {
+    if (fault) throw fault;
+    for (const [directory, prior] of [[root, rootStat], [parentPath, parentStat]]) {
+      const stat = fs.lstatSync(directory);
+      observationRequire(fs.realpathSync(directory) === directory && stat.isDirectory() && stat.uid === process.getuid()
+        && (stat.mode & 0o777) === 0o700 && stat.dev === prior.dev && stat.ino === prior.ino, "custody-directory-changed");
+    }
+    const lock = observationPrivateFile(lockPath);
+    observationRequire(lock.dev === lockStat.dev && lock.ino === lockStat.ino, "run-lock-changed");
+  };
+  const readManifest = () => {
+    guard(); observationPrivateFile(manifestPath);
+    const disk = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    observationRequire(disk.runId === identity.runId && disk.configurationDigest === identity.configurationDigest
+      && disk.candidateProvenance?.contentDigest === identity.candidateDigest, "manifest-identity-mismatch");
+    observationRequire(disk.observationCheckpoints === undefined || Array.isArray(disk.observationCheckpoints), "checkpoints-invalid");
+    const matches = (disk.observationCheckpoints ?? []).filter(row => row.identity?.attemptId === identity.attemptId);
+    observationRequire(matches.length <= 1 && (!state || observationEqual(matches[0], state)), "checkpoint-changed");
+    return { disk, current: matches[0] };
+  };
+  const inspect = () => {
+    guard(); const before = observationPrivateFile(journal);
+    observationRequire(before.dev === initialJournal.dev && before.ino === initialJournal.ino && before.size <= 64 * 1024 * 1024, "journal-replaced-or-oversize");
+    const inspection = inspectBenchmarkLedger(journal), after = observationPrivateFile(journal);
+    observationRequire(before.dev === after.dev && before.ino === after.ino && before.size === after.size
+      && inspection.raw.equals(Buffer.from(inspection.raw.toString("utf8"))), "journal-readback-invalid");
+    guard(); return inspection;
+  };
+  const binding = inspection => ({ path: journal, sha256: observationHash(inspection.raw), bytes: inspection.binding.bytes,
+    records: inspection.binding.records, ledger: inspection.binding });
+  const commit = next => {
+    const { disk } = readManifest();
+    disk.observationCheckpoints = [...(disk.observationCheckpoints ?? []).filter(row => row.identity.attemptId !== identity.attemptId), next];
+    writeBenchmarkRunManifest(root, disk); observationPrivateFile(manifestPath);
+    observationRequire(observationEqual(JSON.parse(fs.readFileSync(manifestPath, "utf8")), disk), "checkpoint-readback-failed");
+    state = structuredClone(next); manifest.observationCheckpoints = structuredClone(disk.observationCheckpoints);
+  };
+  const validateEnvelope = envelope => {
+    observationObject(envelope, ["material", "signature"], "envelope-invalid");
+    observationRequire(typeof envelope.material === "string" && Buffer.byteLength(envelope.material) <= 4 * 1024 * 1024
+      && typeof envelope.signature === "string" && /^[A-Za-z0-9+/]{86}==$/.test(envelope.signature), "envelope-invalid");
+    const material = JSON.parse(envelope.material);
+    observationObject(material, ["protocol", "armId", "candidateDigest", "custodyIdentity", "sequence", "previousHash", "event"], "material-shape-invalid");
+    observationRequire(JSON.stringify(material) === envelope.material && material.protocol === identity.protocol
+      && material.armId === identity.armId && material.candidateDigest === identity.candidateDigest
+      && material.custodyIdentity === identityDigest && material.sequence === state.sequence + 1
+      && material.previousHash === state.previousHash, "envelope-binding-mismatch");
+    observationRequire(crypto.verify(null, Buffer.from(envelope.material), key, Buffer.from(envelope.signature, "base64")), "signature-invalid");
+    if (material.event.cwd) observationRequire(!journal.startsWith(path.resolve(material.event.cwd) + path.sep), "journal-inside-workspace");
+    return material;
+  };
+  const reconcile = () => {
+    readManifest(); const inspection = inspect();
+    const checked = benchmarkLedgerCheckpoint(state.journalBinding.ledger, inspection, "observation journal");
+    observationRequire(state.journalBinding.path === journal && state.journalBinding.bytes === state.journalBinding.ledger.bytes
+      && state.journalBinding.records === state.sequence && state.journalBinding.records === state.journalBinding.ledger.records
+      && observationHash(inspection.raw.subarray(0, state.journalBinding.bytes)) === state.journalBinding.sha256
+      && state.previousHash === (state.sequence ? observationHash(JSON.stringify(inspection.records[state.sequence - 1])) : null), "checkpoint-prefix-mismatch");
+    if (!checked.recovered) return;
+    observationRequire(state.pending, "unreserved-journal-append");
+    const envelope = inspection.records.at(-1), line = inspection.raw.subarray(state.journalBinding.bytes);
+    observationRequire(observationHash(line) === state.pending.envelopeSha256
+      && line.equals(Buffer.from(JSON.stringify(envelope) + "\n")), "reserved-append-mismatch");
+    const material = validateEnvelope(envelope), runtimes = advanceObservationRuntimes(state, material.event, requests);
+    commit({ ...state, journalBinding: binding(inspection), sequence: material.sequence,
+      previousHash: observationHash(JSON.stringify(envelope)), pending: null, runtimes });
+  };
+  const invoke = action => {
+    try { guard(); return action(); } catch (error) { fault = error; throw error; }
+  };
+  const { current } = readManifest();
+  if (current) {
+    observationRequire(current.schemaVersion === 1 && observationEqual(current.identity, identity) && observationEqual(current.requests, requests)
+      && current.publicKey === publicKeyDer.toString("base64") && current.identityDigest === identityDigest
+      && Array.isArray(current.runtimes) && (current.pending === null || typeof current.pending === "object"), "checkpoint-identity-mismatch");
+    state = structuredClone(current);
+    observationRequire(state.journalIdentity.dev === initialJournal.dev && state.journalIdentity.ino === initialJournal.ino
+      && state.journalIdentity.parentDev === parentStat.dev && state.journalIdentity.parentIno === parentStat.ino, "journal-custody-mismatch");
+    reconcile();
+  } else {
+    const inspection = inspect(); observationRequire(inspection.raw.length === 0, "nonempty-journal-without-checkpoint");
+    commit({ schemaVersion: 1, identity, identityDigest, publicKey: publicKeyDer.toString("base64"), requests,
+      journalBinding: binding(inspection), journalIdentity: { dev: initialJournal.dev, ino: initialJournal.ino,
+        parentDev: parentStat.dev, parentIno: parentStat.ino }, sequence: 0, previousHash: null, pending: null, runtimes: [] });
+  }
+  const observer = Object.freeze({
+    readCheckpoint: () => invoke(() => { reconcile(); return { ...structuredClone(state), resumable: observationResumable(state) }; }),
+    reserve: envelope => invoke(() => {
+      reconcile(); observationRequire(!state.pending && token === null, "reservation-pending");
+      const material = validateEnvelope(envelope); advanceObservationRuntimes(state, material.event, requests);
+      commit({ ...state, pending: { envelopeSha256: observationHash(JSON.stringify(envelope) + "\n"), sequence: material.sequence } });
+      token = Object.freeze({}); return token;
+    }),
+    acknowledge: reservation => invoke(() => {
+      observationRequire(token && reservation === token && state.pending, "reservation-token-invalid");
+      reconcile(); observationRequire(!state.pending, "reserved-append-missing"); token = null;
+    })
+  });
+  return Object.freeze({ observer,
+    settleOperation: outcome => invoke(() => {
+      reconcile(); observationRequire(!state.pending && outcome.attemptId === identity.attemptId
+        && exactUsage(outcome.usage, outcome.usageStatus), "operation-outcome-unproven");
+      const runtimes = structuredClone(state.runtimes), runtime = runtimes.find(row => row.runtimeInstanceRef === outcome.runtimeInstanceRef);
+      const operation = runtime?.operations.find(row => row.operationRef === outcome.operationRef && row.messageRequestId === outcome.messageRequestId);
+      const callbacks = runtime?.callbacks.filter(row => row.operationRef === outcome.operationRef);
+      observationRequire(operation?.ended && callbacks?.some(row => row.stage === "return-ready")
+        && callbacks.every(row => ["return-ready", "outer-rejected"].includes(row.stage)), "operation-outcome-mismatch");
+      for (const callback of callbacks) callback.stage = "settled";
+      operation.outcome = { usage: structuredClone(outcome.usage), usageStatus: outcome.usageStatus };
+      commit({ ...state, runtimes });
+    })
+  });
+}
+
+export function recoverBenchmarkObservationCheckpoints({ runRoot, manifest }) {
+  if (manifest.observationCheckpoints === undefined) return [];
+  observationRequire(Array.isArray(manifest.observationCheckpoints), "checkpoints-invalid");
+  return [...manifest.observationCheckpoints].map(checkpoint => {
+    const custody = createBenchmarkObservationCustody({ runRoot, manifest, identity: checkpoint.identity,
+      journalPath: checkpoint.journalBinding.path, publicKey: { key: Buffer.from(checkpoint.publicKey, "base64"), type: "spki", format: "der" },
+      requests: checkpoint.requests });
+    const recovered = custody.observer.readCheckpoint();
+    observationRequire(recovered.resumable, "resume-has-unresolved-attempt");
+    return recovered;
+  });
+}