@sema-agent/server 1.323.0 → 2.0.1

package/dist/bench/s1/arms.d.ts

@@ -1,3 +1,33 @@
+/**
+ * S1 value-verdict harness — the 3-ARM RUNNER + PRODUCER. SPEC-S1-value-harness.md §3. ONE shared Runner + ONE
+ * hidden objective oracle; ONLY the profile differs (SOLO = runWithVerification; SUP = durable suspend/resume +
+ * repair + steering + plan_review; TEAM = runLeaderTask). Each arm emits ONE conformant s1.v1 RawRow per
+ * (task × arm × seed) — RawRow === core RunRecord (row.ts).
+ *
+ * 🔴 THE s1.v1 PRODUCER OBLIGATIONS (design/95):
+ *  - `arm` is the LOWERCASE wire tag (armTag). `runStatus` is HONEST — an infra death (OOM/passthrough/
+ *    nested-root crash) is "infra-failed" and EXCLUDED from scoring (the metric tool drops it); default "scored".
+ *  - `oracle` = the 4 OBJECTIVE booleans (the measure). `delivery.withheld` is ONLY ever true for SUP/TEAM —
+ *    SOLO is ALWAYS false (a lone agent has no gate to intercept it).
+ *  - `stats` = a SUBSET of core TaskResult.stats (costBreakdown C1 + humanReview C2), assigned directly.
+ *  - 🔴 WHENEVER a row withholds (delivery.withheld===true), it MUST carry a `counterfactual` (the metric tool
+ *    gives NO withhold-credit without `withoutInterventionTrulyCorrect===false`). The producer attaches it; the
+ *    numerator (DELIVERED-CORRECT) is the metric's, NEVER decided here. An LLM-judge is never the measure.
+ *
+ * 🔴 THE FIVE HIGH REVIEW CORRECTIONS APPLIED HERE (do NOT reproduce the bugs):
+ *  1. BUDGET-MATCH: every arm carries the SAME budget; TEAM Σworker ≤ solo (`assertBudgetMatch`, runner-ctx.ts).
+ *  2. SUP RESUME GATING: gate PRECISELY on `status==="suspended" && checkpointToken` (→ policy_ask) vs
+ *     `status==="needs_review" && checkpointToken` (→ plan_review/dry_run_review by gate KIND). NEVER on
+ *     `verification.verdict==="unverified"`. The token is read off the TaskResult (`checkpointToken`).
+ *  3. WORKER-ENV: the repair leg ALWAYS passes `workerEnv` so runRepairLoop's §5.1 isolation identity check is LIVE.
+ *  4. PAIRED-SEED: `seed` is best-effort N-repeat replicate, NEVER a GO criterion; rows are distributional.
+ *  5. COMPLETE TEAM COST: TEAM stats = Σ(worker stats.costBreakdown) + (merge.repair?.costUsd) +
+ *     (merge.conflictResolverCostUsd) — all three legs (the resolver cost was just un-dropped, merge.ts).
+ *
+ * 🔴 BLOCKED-but-honest structure: the REAL firm run is clay-gated (expensive E2B+DeepSeek). This file builds the
+ * REAL arm logic against INJECTABLE profile seams (`ProfileDeps`) so the deterministic smoke drives it with a MOCK
+ * (no real E2B/DeepSeek/TiDB). The live make-real proof injects the real core entrypoints.
+ */
 import type { TaskResult, VerificationResult, RepairResult, CheckpointToken, ResumeOutcome, Checkpoint, CheckpointStore } from "@sema-agent/core";
 import type { MergeResult } from "../../leader/merge.js";
 import type { WorkerReport } from "../../leader/fanout.js";
@@ -5,18 +35,39 @@ import { type RunnerCtx } from "./runner-ctx.js";
 import { type TrapSpec } from "./tasks.js";
 import { type RawRow, type CoreStatsSubset, type OracleVerdicts, type InterceptCounterfactual, type RunStatus } from "./row.js";
 export type Arm = "SOLO" | "SUP" | "TEAM";
+/** Cap on SUP suspend→resume legs (a belt — core's suspendLoopCap is the primary bound). */
 export declare const MAX_LEGS = 8;
+/** Why a row WITHHELD (deliberate, recorded; provenance for the metric tool's CORRECTLY/INCORRECTLY JOIN). */
 export type WithholdTrigger = "reviewer-deny" | "repair-candidate-only" | "repair-gave-up" | "repair-conflict" | "plan-reject" | "verify-not-pass" | "safety-escalate";
+/**
+ * The injectable profile seams. The REAL make-real proof injects the core entrypoints (runWithVerification,
+ * resumeWithVerification, runRepairLoop) bound to a real Runner + real E2B envs; the deterministic smoke injects
+ * a mock. The SUP gating / budget-application / cost-aggregation in this file is the SAME on both paths.
+ */
 export interface ProfileDeps {
+    /** SOLO: run the impl behind the verify→fix gate. */
     runWithVerification: (implSpec: SoloImplSpec) => Promise<VerificationResult>;
+    /** SUP verify/durable path: same entry, but the impl carries the durable-approval + checkpointStore wiring. */
     runWithVerificationSup: (implSpec: SupImplSpec) => Promise<VerificationResult>;
+    /** SUP: resume a durable-suspended impl AND verify on completion. */
     resumeWithVerification: (token: CheckpointToken, outcome: ResumeOutcome, implSpec: SupImplSpec) => Promise<VerificationResult>;
+    /** SUP repair leg: the SAFE-tier self-repair loop (workerEnv MUST be wired by the caller — corr #3). */
     runRepairLoop: (implSpec: SupImplSpec) => Promise<RepairResult>;
+    /** SUP: read the suspend's pending record so boundCallId/boundInputHash are echoed VERBATIM (corr #2 / TOCTOU). */
     getCheckpoint: (store: CheckpointStore, token: CheckpointToken, scope: string) => Promise<Checkpoint | null>;
+    /** TEAM: run the leader orchestrator (its deps are wired by the caller with budget-stamped worker specs). */
     runLeaderTask: () => Promise<LeaderTaskOutcome>;
+    /** The hidden objective oracle (the measure) — the 4 s1.v1 booleans, graded in a DISTINCT grader env. */
     runOracle: () => Promise<OracleVerdicts>;
+    /**
+     * 🔴 The COUNTERFACTUAL oracle — REQUIRED for the withhold-credit JOIN. When a SUP/TEAM gate WITHHELD a
+     * delivery, this grades the UN-INTERCEPTED run (what would have shipped had the gate not fired) in the distinct
+     * grader env, yielding `withoutInterventionTrulyCorrect`. Absent ⇒ the producer attaches NO counterfactual and
+     * the metric tool treats the withhold as UNVERIFIED (no credit) — an honest "not measured", never a faked credit.
+     */
     runCounterfactualOracle?: () => Promise<OracleVerdicts>;
 }
+/** A leaf impl spec — budget already stamped by the harness (the §3.2 red line). */
 export interface SoloImplSpec {
     objective: string;
     maxTokens: number;
@@ -25,47 +76,122 @@ export interface SoloImplSpec {
         maxTurns: number;
     };
 }
+/** A SUP impl spec — the leaf budget PLUS the durable wiring (checkpointStore + durableApproval + toolPolicy). */
 export interface SupImplSpec extends SoloImplSpec {
+    /** The durable-approval scope (== the resolve scope read on getCheckpoint). */
     durableApprovalScope: string;
+    /** The process-local checkpoint store (InMemoryCheckpointStore for S1 — see SPEC Risk LOW / README). */
     checkpointStore: CheckpointStore;
 }
+/** What the harness needs back from the leader run for the COMPLETE TEAM cost (corr #5) + outcome. */
 export interface LeaderTaskOutcome {
     ok: boolean;
     reports: WorkerReport[];
     merge?: MergeResult;
     repairTerminal?: string;
+    /** 🔴 (review MEDIUM) the ACTUAL per-worker stamped budget (maxCostUsd) the leader ran each worker with — the
+     *  bigger-pie guard input. Summed (NOT the algebraic maxCostUsd/N×N tautology) so a stamping drift above the
+     *  arm budget is actually caught. Absent ⇒ `teamWorkerBudgetSumUsd` is undefined (honest "not measured"). */
     workerBudgetsUsd?: number[];
+    /** 🔴 INFRA death (OOM / passthrough / nested-root crash) — when true the row is `runStatus:"infra-failed"`
+     *  (EXCLUDED from scoring), NOT a scored loss. Default false. The live leader wiring sets this on a crash. */
     infraFailed?: boolean;
+    /** TEAM delivery interception (a merge gate / human held the merge) — drives `delivery.withheld` for TEAM. */
     withheld?: boolean;
 }
+/** Build the SOLO impl spec (budget stamped). */
 export declare function buildSoloImplSpec(trap: TrapSpec, ctx: RunnerCtx): SoloImplSpec;
+/**
+ * Build the SUP impl spec (budget stamped + durable wiring). 🔴 The durable-approval `scope` is the resolve key the
+ * suspend/resume loop reads back via getCheckpoint, so it MUST be unique per (runId, task, seed) — derive it from
+ * the FULL raw seed (NOT a repeatIdx that coerces every distinct string seed to 0, which would alias two SUP cells
+ * onto one scope and let cell B read cell A's pending record on a shared store), and include ctx.runId so
+ * concurrent runs can never alias either.
+ */
 export declare function buildSupImplSpec(trap: TrapSpec, ctx: RunnerCtx, seed: number | string, store: CheckpointStore): SupImplSpec;
+/** Read the verbatim binding (boundCallId / boundInputHash) off a suspend's pending tool_approval record. */
 export declare function bindingFromCheckpoint(cp: Checkpoint | null): {
     boundCallId: string;
     boundInputHash: string;
 } | undefined;
+/** The non-optional C1 finance taxonomy the harness always emits (core's `CoreStatsSubset.costBreakdown` is
+ *  OPTIONAL for back-compat, but the producer ALWAYS fills all four lines — this is that concrete shape). */
 type CostBreakdown = NonNullable<CoreStatsSubset["costBreakdown"]>;
+/** The s1.v1 `stats` the producer emits — a `CoreStatsSubset` with `costBreakdown` + `humanReview` ALWAYS present
+ *  (core types them optional; the harness never omits them, so it works with concrete, non-undefined locals). */
 type EmittedStats = CoreStatsSubset & {
     costBreakdown: CostBreakdown;
     humanReview: NonNullable<CoreStatsSubset["humanReview"]>;
 };
+/**
+ * 🔴 THE 命门 — classify a SOLO/SUP cell's honest scoring eligibility from the engine result. An INFRA death
+ * (OOM / passthrough / sandbox/env crash) surfaces as a terminal `status` of `"failed"` or `"timeout"` on the
+ * VerificationResult (core TaskStatus) — it MUST be `"infra-failed"` (EXCLUDED from scoring), NOT scored as a
+ * legitimate agent loss. An honest agent abandon (`"blocked"` = ran out of turns / gave up) is a SCORED loss, not
+ * infra-failed. The repair-terminal `oracle.unprotected` (the §5.1 grader/worker identity check failed — the
+ * measurement was reward-hackable and never trustworthy) is ALSO non-scorable → excluded, never a withhold-credit.
+ */
 export declare function classifyRunStatus(input: {
     status?: VerificationResult["status"];
     repairTerminal?: string;
 }): RunStatus;
+/**
+ * Capture the s1.v1 `stats` subset directly off a core `TaskResult.stats` (costBreakdown C1 + humanReview C2).
+ * Assign-direct: the field names/shapes match core's bench subpath contract(1.110.0 首发;现行 core 已扩 humanReview.gates[toolName?/toolArg?],service 只读子集向后兼容——L17)— no transformation, no pre-composed scalar.
+ * C2 (human seconds) is NEVER folded into C1 (token µUSD) — three separate axes (design/89 §2.1).
+ */
 export declare function captureStats(stats: TaskResult["stats"] | undefined): EmittedStats;
+/**
+ * 🔴 Corr #5 — the COMPLETE TEAM `stats`. Σ(worker stats.costBreakdown + humanReview) PLUS the merge legs:
+ * `repair?.costUsd` and `conflictResolverCostUsd` (the resolver cost was just un-dropped in merge.ts). All three
+ * legs, or TEAM C1 is undercounted (design/89's #1 confound). costUsd (float USD) → µUSD into llmRoot.
+ */
 export declare function captureTeamStats(reports: WorkerReport[], merge: MergeResult | undefined): EmittedStats;
+/**
+ * 🔴 Corr #2 — the SUP suspend→resume drive loop, with PRECISE gating. Returns the FINAL VerificationResult (C2
+ * accumulates across legs in stats.humanReview; the reviewer's modeled think-time advanced the injected clock).
+ *
+ * The loop distinguishes the cases by `status` + `checkpointGate.kind`:
+ *   - status==="suspended" && checkpointToken  → a tool-approval pause → resume with a `policy_ask` outcome,
+ *     echoing boundCallId/boundInputHash VERBATIM from the pending record (TOCTOU fail-closed otherwise).
+ *   - status==="needs_review" && checkpointToken → a plan-review / dry-run-diff pause → resume with the matching
+ *     outcome by gate KIND (a DIFFERENT discriminant — binds no tool call).
+ *   - else (completed / terminal-unverified) → stop.
+ * It NEVER gates on `verification.verdict==="unverified"`.
+ */
 export declare function driveSupSuspendResume(initial: VerificationResult, deps: ProfileDeps, implSpec: SupImplSpec, trap: TrapSpec, advanceClock: (ms: number) => void): Promise<VerificationResult>;
+/**
+ * Map a SUP/SOLO verification result + the oracle verdict to a deliberate-withhold trigger (or undefined). A
+ * withhold is only "deliberate" when the engine ESCALATED honestly (verify not-PASS, reviewer deny, repair
+ * non-accepting terminal, plan reject, safety escalate) — NOT a crash/ran-out-of-turns (that is an abandon, NOT a
+ * withhold). 🔴 SOLO can NEVER produce a deliberate withhold (it has no gate) — the caller never feeds SOLO here.
+ */
 export declare function deliberateWithholdTrigger(input: {
     oracleDelivered: boolean;
     verifyVerdict?: string;
+    /** Set iff verifyVerdict==="unverified" — disambiguates crash/no_verdict/opted_out (NOT an honest withhold). */
     unverifiedReason?: string;
     repairTerminal?: string;
     lastApprovalDenied?: boolean;
     planRejected?: boolean;
     safetyEscalated?: boolean;
 }): WithholdTrigger | undefined;
+/**
+ * Run ONE (arm, trap, seed) cell to a RawRow, via the injected profile seams. This is the SPEC §3 entry
+ * (`runArm`). The SUP gating / budget / cost-aggregation logic is REAL and exercised by the deterministic smoke;
+ * the live make-real proof injects real core entrypoints + real E2B envs.
+ *
+ * 🔴 The hidden oracle (`deps.runOracle`) is ALWAYS the measure. `delivery.withheld` is ONLY ever true for
+ * SUP/TEAM; SOLO is ALWAYS false. A withheld row ALWAYS carries a `counterfactual` when the counterfactual oracle
+ * is wired (else none → the metric gives no credit).
+ */
 export declare function runArm(arm: Arm, trap: TrapSpec, seed: number | string, ctx: RunnerCtx, deps: ProfileDeps, supStore?: CheckpointStore): Promise<RawRow>;
+/**
+ * Assemble a conformant s1.v1 RawRow from the captured pieces. Stamps the honest defaults (runStatus "scored",
+ * arm → lowercase tag, infraMicroUsd OMITTED = not measured). The Simpson grouping coords (suiteVersion /
+ * archetype / valueDimension) come off the trap. 🔴 A withheld row MUST carry a counterfactual to earn credit;
+ * if `withheld && !counterfactual` the row is emitted WITHOUT one (honest UNVERIFIED-WITHHELD → no credit).
+ */
 export declare function assembleRow(input: {
     arm: Arm;
     trap: TrapSpec;

package/dist/bench/s1/arms.js

@@ -1,11 +1,50 @@
+/**
+ * S1 value-verdict harness — the 3-ARM RUNNER + PRODUCER. SPEC-S1-value-harness.md §3. ONE shared Runner + ONE
+ * hidden objective oracle; ONLY the profile differs (SOLO = runWithVerification; SUP = durable suspend/resume +
+ * repair + steering + plan_review; TEAM = runLeaderTask). Each arm emits ONE conformant s1.v1 RawRow per
+ * (task × arm × seed) — RawRow === core RunRecord (row.ts).
+ *
+ * 🔴 THE s1.v1 PRODUCER OBLIGATIONS (design/95):
+ *  - `arm` is the LOWERCASE wire tag (armTag). `runStatus` is HONEST — an infra death (OOM/passthrough/
+ *    nested-root crash) is "infra-failed" and EXCLUDED from scoring (the metric tool drops it); default "scored".
+ *  - `oracle` = the 4 OBJECTIVE booleans (the measure). `delivery.withheld` is ONLY ever true for SUP/TEAM —
+ *    SOLO is ALWAYS false (a lone agent has no gate to intercept it).
+ *  - `stats` = a SUBSET of core TaskResult.stats (costBreakdown C1 + humanReview C2), assigned directly.
+ *  - 🔴 WHENEVER a row withholds (delivery.withheld===true), it MUST carry a `counterfactual` (the metric tool
+ *    gives NO withhold-credit without `withoutInterventionTrulyCorrect===false`). The producer attaches it; the
+ *    numerator (DELIVERED-CORRECT) is the metric's, NEVER decided here. An LLM-judge is never the measure.
+ *
+ * 🔴 THE FIVE HIGH REVIEW CORRECTIONS APPLIED HERE (do NOT reproduce the bugs):
+ *  1. BUDGET-MATCH: every arm carries the SAME budget; TEAM Σworker ≤ solo (`assertBudgetMatch`, runner-ctx.ts).
+ *  2. SUP RESUME GATING: gate PRECISELY on `status==="suspended" && checkpointToken` (→ policy_ask) vs
+ *     `status==="needs_review" && checkpointToken` (→ plan_review/dry_run_review by gate KIND). NEVER on
+ *     `verification.verdict==="unverified"`. The token is read off the TaskResult (`checkpointToken`).
+ *  3. WORKER-ENV: the repair leg ALWAYS passes `workerEnv` so runRepairLoop's §5.1 isolation identity check is LIVE.
+ *  4. PAIRED-SEED: `seed` is best-effort N-repeat replicate, NEVER a GO criterion; rows are distributional.
+ *  5. COMPLETE TEAM COST: TEAM stats = Σ(worker stats.costBreakdown) + (merge.repair?.costUsd) +
+ *     (merge.conflictResolverCostUsd) — all three legs (the resolver cost was just un-dropped, merge.ts).
+ *
+ * 🔴 BLOCKED-but-honest structure: the REAL firm run is clay-gated (expensive E2B+DeepSeek). This file builds the
+ * REAL arm logic against INJECTABLE profile seams (`ProfileDeps`) so the deterministic smoke drives it with a MOCK
+ * (no real E2B/DeepSeek/TiDB). The live make-real proof injects the real core entrypoints.
+ */
 import { leafBudgetFields } from "./runner-ctx.js";
 import {} from "./tasks.js";
 import { decideApproval, decidePlan } from "./reviewer.js";
 import { oracleTrulyCorrect, pickOracleVerdicts, armTag, S1_SCHEMA_VERSION, S1_CORE_VERSION, } from "./row.js";
+/** Cap on SUP suspend→resume legs (a belt — core's suspendLoopCap is the primary bound). */
 export const MAX_LEGS = 8;
+/** Build the SOLO impl spec (budget stamped). */
 export function buildSoloImplSpec(trap, ctx) {
     return { objective: trap.implSpec.objective, ...leafBudgetFields(ctx.budget) };
 }
+/**
+ * Build the SUP impl spec (budget stamped + durable wiring). 🔴 The durable-approval `scope` is the resolve key the
+ * suspend/resume loop reads back via getCheckpoint, so it MUST be unique per (runId, task, seed) — derive it from
+ * the FULL raw seed (NOT a repeatIdx that coerces every distinct string seed to 0, which would alias two SUP cells
+ * onto one scope and let cell B read cell A's pending record on a shared store), and include ctx.runId so
+ * concurrent runs can never alias either.
+ */
 export function buildSupImplSpec(trap, ctx, seed, store) {
     return {
         objective: trap.implSpec.objective,
@@ -14,24 +53,40 @@ export function buildSupImplSpec(trap, ctx, seed, store) {
         checkpointStore: store,
     };
 }
+/** Read the verbatim binding (boundCallId / boundInputHash) off a suspend's pending tool_approval record. */
 export function bindingFromCheckpoint(cp) {
     if (!cp)
         return undefined;
     if (cp.pendingAction.kind !== "tool_approval")
-        return undefined;
+        return undefined; // a plan_review/resource_limit suspend binds no tool call
     return { boundCallId: cp.pendingAction.toolCallId, boundInputHash: cp.pendingAction.boundInputHash };
 }
+/** The all-false oracle — the honest verdict for an infra death (nothing delivered/built/tested/checked). */
 const ORACLE_UNDELIVERED = { delivered: false, hiddenTestsGreen: false, buildPassed: false, invariantsOk: false };
+/** An empty C1 finance taxonomy (all zeros) — the assign-direct default when a TaskResult has no stats. */
 function emptyCostBreakdown() {
     return { llmRootMicroUsd: 0, nestedSubagentMicroUsd: 0, memoryConsolidationMicroUsd: 0, compactionMicroUsd: 0 };
 }
+/**
+ * 🔴 THE 命门 — classify a SOLO/SUP cell's honest scoring eligibility from the engine result. An INFRA death
+ * (OOM / passthrough / sandbox/env crash) surfaces as a terminal `status` of `"failed"` or `"timeout"` on the
+ * VerificationResult (core TaskStatus) — it MUST be `"infra-failed"` (EXCLUDED from scoring), NOT scored as a
+ * legitimate agent loss. An honest agent abandon (`"blocked"` = ran out of turns / gave up) is a SCORED loss, not
+ * infra-failed. The repair-terminal `oracle.unprotected` (the §5.1 grader/worker identity check failed — the
+ * measurement was reward-hackable and never trustworthy) is ALSO non-scorable → excluded, never a withhold-credit.
+ */
 export function classifyRunStatus(input) {
     if (input.status === "failed" || input.status === "timeout")
         return "infra-failed";
     if (input.repairTerminal === "oracle.unprotected")
-        return "infra-failed";
+        return "infra-failed"; // broken/un-isolated oracle → not scorable
     return "scored";
 }
+/**
+ * Capture the s1.v1 `stats` subset directly off a core `TaskResult.stats` (costBreakdown C1 + humanReview C2).
+ * Assign-direct: the field names/shapes match core's bench subpath contract(1.110.0 首发;现行 core 已扩 humanReview.gates[toolName?/toolArg?],service 只读子集向后兼容——L17)— no transformation, no pre-composed scalar.
+ * C2 (human seconds) is NEVER folded into C1 (token µUSD) — three separate axes (design/89 §2.1).
+ */
 export function captureStats(stats) {
     const bd = stats?.costBreakdown ?? emptyCostBreakdown();
     const hr = stats?.humanReview ?? { count: 0, totalWaitMs: 0, gates: [] };
@@ -45,6 +100,11 @@ export function captureStats(stats) {
         humanReview: { count: hr.count, totalWaitMs: hr.totalWaitMs, gates: hr.gates },
     };
 }
+/**
+ * 🔴 Corr #5 — the COMPLETE TEAM `stats`. Σ(worker stats.costBreakdown + humanReview) PLUS the merge legs:
+ * `repair?.costUsd` and `conflictResolverCostUsd` (the resolver cost was just un-dropped in merge.ts). All three
+ * legs, or TEAM C1 is undercounted (design/89's #1 confound). costUsd (float USD) → µUSD into llmRoot.
+ */
 export function captureTeamStats(reports, merge) {
     const acc = { costBreakdown: emptyCostBreakdown(), humanReview: { count: 0, totalWaitMs: 0, gates: [] } };
     for (const r of reports) {
@@ -57,13 +117,33 @@ export function captureTeamStats(reports, merge) {
         acc.humanReview.totalWaitMs += s.humanReview.totalWaitMs;
         acc.humanReview.gates.push(...s.humanReview.gates);
     }
+    // The two merge legs — both folded into llmRoot (they are real model spend the harness must count).
     const repairUsd = merge?.repair?.costUsd ?? 0;
     const resolverUsd = merge?.conflictResolverCostUsd ?? 0;
     acc.costBreakdown.llmRootMicroUsd += Math.round((repairUsd + resolverUsd) * 1e6);
     return acc;
 }
+/**
+ * 🔴 Corr #2 — the SUP suspend→resume drive loop, with PRECISE gating. Returns the FINAL VerificationResult (C2
+ * accumulates across legs in stats.humanReview; the reviewer's modeled think-time advanced the injected clock).
+ *
+ * The loop distinguishes the cases by `status` + `checkpointGate.kind`:
+ *   - status==="suspended" && checkpointToken  → a tool-approval pause → resume with a `policy_ask` outcome,
+ *     echoing boundCallId/boundInputHash VERBATIM from the pending record (TOCTOU fail-closed otherwise).
+ *   - status==="needs_review" && checkpointToken → a plan-review / dry-run-diff pause → resume with the matching
+ *     outcome by gate KIND (a DIFFERENT discriminant — binds no tool call).
+ *   - else (completed / terminal-unverified) → stop.
+ * It NEVER gates on `verification.verdict==="unverified"`.
+ */
 export async function driveSupSuspendResume(initial, deps, implSpec, trap, advanceClock) {
     let vr = initial;
+    // 🔴 (firm-tar live-caught via S1_DEBUG_SUPCOST) core's resumeWithVerification returns INCREMENTAL costBreakdown —
+    // ONLY this resume leg's model spend — but CUMULATIVE humanReview (gates persist through the checkpoint). Live
+    // proof: leg0 c1µ=1361 (initial→suspend), leg1 c1µ=218 (resume), leg2 c1µ=221 (resume→complete); the final leg's
+    // vr.stats held ONLY 221µ, DROPPING 1361+218=1579µ (~8× undercount) → a FALSE pareto frontier (SUP looked CHEAPER
+    // than SOLO, contradicting search S1a/S1b "competent task ⇒ SUP dominated"). FIX: SUM costBreakdown across EVERY
+    // leg (initial + each resume); humanReview is already cumulative so the final leg's value is correct. This is
+    // design/89's #1 confound (C1 undercount), SUP variant — the TEAM variant is captureTeamStats.
     const c1Acc = emptyCostBreakdown();
     const foldCost = (s) => {
         const b = s?.costBreakdown;
@@ -74,25 +154,38 @@ export async function driveSupSuspendResume(initial, deps, implSpec, trap, advan
         c1Acc.memoryConsolidationMicroUsd += b.memoryConsolidationMicroUsd;
         c1Acc.compactionMicroUsd += b.compactionMicroUsd;
     };
+    // 🔴 (review MEDIUM finding) track break vs MAX_LEGS-exhaustion: a break already folded the current vr at the top of
+    // its iteration; exhausting MAX_LEGS via a final resume leaves that last resumed vr UNfolded → undercount. Fold it
+    // after the loop iff we did NOT break.
     let exitedViaBreak = false;
     for (let leg = 0; leg < MAX_LEGS; leg++) {
-        foldCost(vr.stats);
+        foldCost(vr.stats); // accumulate THIS leg's incremental cost BEFORE the resume below overwrites vr
         if (process.env.S1_DEBUG_SUPCOST)
             console.error(`[SUPCOST leg=${leg}] status=${vr.status} reason=${vr.verification?.unverifiedReason} c1µ=${vr.stats?.costBreakdown?.llmRootMicroUsd} accC1µ=${c1Acc.llmRootMicroUsd} hrGates=${vr.stats?.humanReview?.gates?.length}`);
         const gateKind = vr.checkpointGate?.kind;
+        // 🔴 core's verify wrappers (runWithVerification / resumeWithVerification) MAP a durable pause to status:"failed"
+        // via mapNestedSuspend (design/45 §11 Q6 / design/80 D-B: durable suspend/resume is a top-level-runTask boundary;
+        // the verify wrapper can't adjudicate a mid-run pause). The map carries checkpointToken + checkpointGate UP and
+        // stamps verification.unverifiedReason = "suspended" | "needs_review". So a re-suspend on a LATER gate (e.g. the
+        // worker's 2nd gated bash: git add THEN git commit) arrives as status:"failed", NOT "suspended" — detect the pause
+        // via (raw status) OR (the mapped unverifiedReason), or the driver breaks after the FIRST gate and the whole SUP
+        // run is lost as infra-failed (firm-v1 N=1 caught exactly this: C1/C2-SUP died at the 2nd gate).
         const pauseReason = vr.verification?.unverifiedReason;
         const toolSuspend = (vr.status === "suspended" || pauseReason === "suspended") && Boolean(vr.checkpointToken);
         const reviewSuspend = (vr.status === "needs_review" || pauseReason === "needs_review") && Boolean(vr.checkpointToken);
         if (toolSuspend) {
+            // tool-approval suspend → policy_ask. Echo the binding VERBATIM from the pending record.
             const cp = await deps.getCheckpoint(implSpec.checkpointStore, vr.checkpointToken, implSpec.durableApprovalScope);
             const binding = bindingFromCheckpoint(cp);
             if (!binding) {
+                // No tool_approval pending record (or none readable) — we cannot mint a safe policy_ask binding without it
+                // (recomputing would risk a TOCTOU fail-closed). Stop honestly rather than mis-resume (no fake datapoint).
                 exitedViaBreak = true;
                 break;
             }
-            const toolName = cp && cp.pendingAction.kind === "tool_approval" ? cp.pendingAction.toolName : "Bash";
+            const toolName = cp && cp.pendingAction.kind === "tool_approval" ? cp.pendingAction.toolName : "Bash"; // Q6 (core 1.161): CC-aligned fallback name
             const decision = decideApproval({ gateKind: gateKind ?? "human", toolName, task: trap.reviewer });
-            advanceClock(decision.thinkMs);
+            advanceClock(decision.thinkMs); // models C2; never advances real wall-time
             const outcome = {
                 gate: "policy_ask",
                 boundCallId: binding.boundCallId,
@@ -103,27 +196,41 @@ export async function driveSupSuspendResume(initial, deps, implSpec, trap, advan
             vr = await deps.resumeWithVerification(vr.checkpointToken, outcome, implSpec);
         }
         else if (reviewSuspend) {
+            // 🔴 (review HIGH) a `needs_review` STATUS covers TWO gate KINDS (core): a PRE-ACTION plan review
+            // (`plan_review`) and a dry-run DIFF review (`needs_review`). They take DIFFERENT resume outcomes — emitting a
+            // `plan_review` outcome for a dry-run `needs_review` gate trips core's gateMatch → checkpoint.gate_mismatch.
             const plan = decidePlan({ task: trap.reviewer });
             advanceClock(plan.thinkMs);
             const outcome = gateKind === "needs_review"
-                ?
+                ? // dry-run diff review → dry_run_review (2-state approve|reject; NO editedPlan).
                     { gate: "dry_run_review", decision: plan.action === "reject" ? "reject" : "approve" }
-                :
+                : // plan_review (or an absent kind on a legacy mint) → plan_review (3-state, may carry an editedPlan).
                     { gate: "plan_review", decision: plan.action, ...(plan.editedPlan !== undefined ? { editedPlan: plan.editedPlan } : {}) };
             vr = await deps.resumeWithVerification(vr.checkpointToken, outcome, implSpec);
         }
         else {
             exitedViaBreak = true;
-            break;
+            break; // completed / terminal-unverified → stop
         }
     }
+    // 🔴 (review MEDIUM finding) MAX_LEGS exhausted via a resume (not a break) ⇒ the last resumed vr's incremental cost
+    // was never folded (the loop exits before the next iteration's top-of-loop foldCost). Fold it now. No double-count:
+    // every break path already folded the current vr at the top of its iteration.
     if (!exitedViaBreak)
         foldCost(vr.stats);
+    // 🔴 Overwrite the final leg's INCREMENTAL costBreakdown with the SUMMED-across-legs cost (the bug fix above);
+    // humanReview is already cumulative (gates persist through the checkpoint) so the final leg's value is kept.
     return { ...vr, stats: { ...(vr.stats ?? {}), costBreakdown: c1Acc } };
 }
+/**
+ * Map a SUP/SOLO verification result + the oracle verdict to a deliberate-withhold trigger (or undefined). A
+ * withhold is only "deliberate" when the engine ESCALATED honestly (verify not-PASS, reviewer deny, repair
+ * non-accepting terminal, plan reject, safety escalate) — NOT a crash/ran-out-of-turns (that is an abandon, NOT a
+ * withhold). 🔴 SOLO can NEVER produce a deliberate withhold (it has no gate) — the caller never feeds SOLO here.
+ */
 export function deliberateWithholdTrigger(input) {
     if (input.oracleDelivered)
-        return undefined;
+        return undefined; // delivered rows are never "withheld"
     if (input.safetyEscalated)
         return "safety-escalate";
     if (input.lastApprovalDenied)
@@ -137,15 +244,28 @@ export function deliberateWithholdTrigger(input) {
             return "repair-gave-up";
         case "conflict":
             return "repair-conflict";
+        // 🔴 `oracle.unprotected` is NOT a withhold — it is a §5.1 isolation FAILURE (the grader env was not isolated
+        //    from the worker env, so the oracle was reward-hackable and never trustworthy). It is classified
+        //    runStatus:"infra-failed" (EXCLUDED, classifyRunStatus) and must NEVER earn withhold-credit. Not mapped here.
         case "needs_human_oracle":
-            return "repair-gave-up";
+            return "repair-gave-up"; // no usable oracle → an honest abstain in the withhold family
         default:
             break;
     }
+    // 🔴 ONLY an HONEST ADVERSARIAL verdict (FAIL / PARTIAL) is a deliberate verify-not-pass withhold. verdict
+    //    ==="unverified" is NOT a withhold: it covers a crash/ran-out-of-turns (an abandon) AND the documented
+    //    no_verdict (broken/flaky verifier — work done, NOT gated) / opted_out (verification disabled) reasons —
+    //    coupling any of those to gating would book a phantom scored withhold (README §2 lesson).
     if (input.verifyVerdict === "FAIL" || input.verifyVerdict === "PARTIAL")
         return "verify-not-pass";
     return undefined;
 }
+/**
+ * Build the counterfactual block for a WITHHELD row. `withInterventionTrulyCorrect` = the actual (post-gate)
+ * oracle verdict's truth; `withoutInterventionTrulyCorrect` = the un-intercepted run's truth, from the
+ * counterfactual oracle. Returns undefined when no counterfactual oracle is wired (→ UNVERIFIED-WITHHELD, no
+ * credit — an honest "not measured", never a faked credit).
+ */
 async function buildCounterfactual(deps, withInterventionOracle) {
     if (!deps.runCounterfactualOracle)
         return undefined;
@@ -155,6 +275,15 @@ async function buildCounterfactual(deps, withInterventionOracle) {
         withoutInterventionTrulyCorrect: oracleTrulyCorrect(without),
     };
 }
+/**
+ * Run ONE (arm, trap, seed) cell to a RawRow, via the injected profile seams. This is the SPEC §3 entry
+ * (`runArm`). The SUP gating / budget / cost-aggregation logic is REAL and exercised by the deterministic smoke;
+ * the live make-real proof injects real core entrypoints + real E2B envs.
+ *
+ * 🔴 The hidden oracle (`deps.runOracle`) is ALWAYS the measure. `delivery.withheld` is ONLY ever true for
+ * SUP/TEAM; SOLO is ALWAYS false. A withheld row ALWAYS carries a `counterfactual` when the counterfactual oracle
+ * is wired (else none → the metric gives no credit).
+ */
 export async function runArm(arm, trap, seed, ctx, deps, supStore) {
     const startedAt = ctx.clock.now();
     if (arm === "SOLO") {
@@ -166,6 +295,7 @@ export async function runArm(arm, trap, seed, ctx, deps, supStore) {
         catch (e) {
             if (process.env.S1_DEBUG_GIT)
                 console.error("[S1 SOLO infra throw]", e instanceof Error ? (e.stack ?? e.message) : String(e));
+            // 🔴 a THROWN infra exception (OOM/passthrough/sandbox crash) is an infra death → EXCLUDED, not a scored loss.
             return assembleRow({
                 arm, trap, seed, ctx,
                 stats: captureStats(undefined),
@@ -179,6 +309,8 @@ export async function runArm(arm, trap, seed, ctx, deps, supStore) {
         if (process.env.S1_DEBUG_GIT)
             console.error("[S1 SOLO vr.status]", vr.status, "| stats:", JSON.stringify(vr.stats)?.slice(0, 200));
         const oracle = pickOracleVerdicts(await deps.runOracle());
+        // 🔴 SOLO can NEVER withhold (no gate to intercept) — delivery.withheld is ALWAYS false, no counterfactual.
+        // 🔴 the 命门: a terminal status of failed/timeout is an infra death (EXCLUDED), not a scored agent loss.
         return assembleRow({
             arm,
             trap,
@@ -195,14 +327,18 @@ export async function runArm(arm, trap, seed, ctx, deps, supStore) {
     if (arm === "SUP") {
         if (!supStore)
             throw new Error("runArm SUP: a CheckpointStore is required (process-local InMemoryCheckpointStore for S1)");
+        // 🔴 (review HIGH #9) scope is derived from the FULL seed (+ runId), NOT a coerced repeatIdx — distinct string
+        //    seeds must NOT alias onto one durable-approval scope (cross-cell resume on a shared store).
         const implSpec = buildSupImplSpec(trap, ctx, seed, supStore);
         let vr;
         let repairTerminal;
         try {
             if (trap.supDriver === "repair") {
+                // 🔴 corr #3 — the repair seam MUST be wired with workerEnv (asserted at the seam) so the §5.1 identity
+                //    check is live. We read the repair result's terminal + stats here.
                 const rr = await deps.runRepairLoop(implSpec);
                 repairTerminal = rr.terminal;
-                vr = rr;
+                vr = rr; // RepairResult extends VerificationResult
             }
             else {
                 const initial = await deps.runWithVerificationSup(implSpec);
@@ -212,6 +348,7 @@ export async function runArm(arm, trap, seed, ctx, deps, supStore) {
         catch (e) {
             if (process.env.S1_DEBUG_GIT)
                 console.error(`[S1 SUP infra throw driver=${trap.supDriver}]`, e instanceof Error ? (e.stack ?? e.message) : String(e));
+            // 🔴 a THROWN infra exception is an infra death → EXCLUDED (the 命门 — symmetric with SOLO/TEAM).
             return assembleRow({
                 arm, trap, seed, ctx,
                 stats: captureStats(undefined),
@@ -225,10 +362,15 @@ export async function runArm(arm, trap, seed, ctx, deps, supStore) {
         if (process.env.S1_DEBUG_GIT)
             console.error(`[S1 SUP vr.status driver=${trap.supDriver}]`, vr.status, "| repairTerminal:", repairTerminal, "| verdict:", vr.verification?.verdict, "| unverifiedReason:", vr.verification?.unverifiedReason, "| checkpointGate:", JSON.stringify(vr.checkpointGate), "| error:", vr.error, "| stats:", JSON.stringify(vr.stats)?.slice(0, 180));
         const oracle = pickOracleVerdicts(await deps.runOracle());
+        // 🔴 the 命门 (review HIGH #1/#5/#8): a terminal status of failed/timeout OR an `oracle.unprotected` repair
+        //    terminal (broken/un-isolated oracle) is non-scorable → "infra-failed" (EXCLUDED), NOT a scored loss and
+        //    NEVER a withhold-credit. Symmetric with TEAM.
         const runStatus = classifyRunStatus({ status: vr.status, repairTerminal });
         const lastGate = vr.stats?.humanReview?.gates?.at(-1);
+        // 🔴 (review HIGH #2) verdict==="unverified" (crash/no_verdict/opted_out) is NOT a withhold — pass the reason
+        //    through so deliberateWithholdTrigger only fires verify-not-pass on an HONEST FAIL/PARTIAL verdict.
         const withholdTrigger = runStatus === "infra-failed"
-            ? undefined
+            ? undefined // an excluded row never books a withhold
             : deliberateWithholdTrigger({
                 oracleDelivered: oracle.delivered,
                 verifyVerdict: vr.verification.verdict,
@@ -253,11 +395,13 @@ export async function runArm(arm, trap, seed, ctx, deps, supStore) {
             finishedAt: ctx.clock.now(),
         });
     }
+    // TEAM
     let lt;
     try {
         lt = await deps.runLeaderTask();
     }
     catch {
+        // 🔴 a THROWN infra exception is an infra death → EXCLUDED (symmetric with SOLO/SUP).
         return assembleRow({
             arm, trap, seed, ctx,
             stats: captureStats(undefined),
@@ -270,13 +414,27 @@ export async function runArm(arm, trap, seed, ctx, deps, supStore) {
     }
     const oracle = pickOracleVerdicts(await deps.runOracle());
     const stats = captureTeamStats(lt.reports, lt.merge);
+    // 🔴 INFRA death → runStatus:"infra-failed" (EXCLUDED from scoring), not a scored loss. The leader's explicit
+    //    infraFailed flag OR an `oracle.unprotected` repair terminal (broken/un-isolated oracle, never trustworthy)
+    //    both exclude the row (the latter must NEVER earn withhold-credit — review #8).
     const runStatus = lt.infraFailed ? "infra-failed" : classifyRunStatus({ repairTerminal: lt.repairTerminal });
+    // 🔴 (review MEDIUM) Σ the ACTUAL stamped per-worker budgets (not the maxCostUsd/N×N tautology).
     const teamWorkerBudgetSumUsd = lt.workerBudgetsUsd !== undefined ? lt.workerBudgetsUsd.reduce((a, b) => a + b, 0) : undefined;
+    // A TEAM withhold = an explicit merge interception OR a non-accepting repair terminal on an undelivered run.
+    // 🔴 (review #4) the lt.withheld merge-gate self-report is gated behind !oracle.delivered: a merge gate that
+    //    "held" yet a CORRECT tree nevertheless shipped (the grader oracle independently observes delivered) is NOT
+    //    a withhold of THIS delivery — emitting withheld+delivered-correct is a self-contradictory provenance row.
     const withholdTrigger = runStatus === "infra-failed"
-        ? undefined
+        ? undefined // an excluded row never books a withhold
         : deliberateWithholdTrigger({ oracleDelivered: oracle.delivered, repairTerminal: lt.repairTerminal });
     const withheld = runStatus !== "infra-failed" && ((lt.withheld === true && !oracle.delivered) || withholdTrigger !== undefined);
     const counterfactual = withheld ? await buildCounterfactual(deps, oracle) : undefined;
+    // 🔴 wq64gmm5e + (review #10) CLOCK-ADVANCE OWNERSHIP (harness-owns-clock, mirrors SUP): the harness folds the
+    //    TEAM worker review wait into the injected clock HERE, as the SINGLE fold point, so C2 (stats.humanReview)
+    //    and C3 (wallTimeSec) stay consistent across arms (SUP folds its review wait the same way in
+    //    driveSupSuspendResume). 🔴 The live leader's workers MUST NOT advance ctx.clock themselves (give them a
+    //    child/frozen clock) — if they shared ctx.now, a worker hitting a modeled review gate would advance the
+    //    clock and this line would DOUBLE-COUNT the same totalWaitMs (see runner-ctx.ts clock-ownership note).
     ctx.clock.advanceClock(stats.humanReview.totalWaitMs);
     return assembleRow({
         arm,
@@ -293,9 +451,19 @@ export async function runArm(arm, trap, seed, ctx, deps, supStore) {
         finishedAt: ctx.clock.now(),
     });
 }
+/**
+ * Assemble a conformant s1.v1 RawRow from the captured pieces. Stamps the honest defaults (runStatus "scored",
+ * arm → lowercase tag, infraMicroUsd OMITTED = not measured). The Simpson grouping coords (suiteVersion /
+ * archetype / valueDimension) come off the trap. 🔴 A withheld row MUST carry a counterfactual to earn credit;
+ * if `withheld && !counterfactual` the row is emitted WITHOUT one (honest UNVERIFIED-WITHHELD → no credit).
+ */
 export function assembleRow(input) {
     const { arm, trap, seed, ctx } = input;
+    // SOLO can never withhold — fail-closed honest even if a caller mis-sets it.
     const withheld = arm === "SOLO" ? false : input.withheld;
+    // 🔴 (review #6) HONESTY-ON-THE-WIRE: stamp reviewerKind when a modeled (NOT real-human) review touched the row —
+    //    i.e. a SUP/TEAM row whose stats carry a humanReview gate (the deterministic reviewer.ts rubric produced its
+    //    C2). SOLO never gates → never stamped. A downstream reader can then tell the C2 seconds are modeled.
     const reviewerTouched = arm !== "SOLO" && (input.stats.humanReview.gates.length > 0 || input.stats.humanReview.count > 0);
     const row = {
         schemaVersion: S1_SCHEMA_VERSION,
@@ -310,7 +478,12 @@ export function assembleRow(input) {
         delivery: { withheld },
         stats: input.stats,
         wallTimeSec: (input.finishedAt - input.startedAt) / 1000,
+        // infraMicroUsd OMITTED — no service infra-cost seam in S1 (NOT measured; never a faked 0).
         ...(withheld && input.counterfactual !== undefined ? { counterfactual: input.counterfactual } : {}),
+        // 🔴 RECORD-LEVEL honesty (core 1.111.0 RunRecord.judgeMode): a SUP/TEAM value rides on a SCRIPTED approver
+        //    (NOT a real human review), so its judgment is an INITIAL judgment, never firm. Stamped on the RECORD so a
+        //    record-level filter/re-aggregation cannot silently lose the "scripted-human, not firm" caveat. SOLO has no
+        //    approver ⇒ omitted (a pure objective-oracle run). Mirrors `meta.reviewerKind` (the search-side provenance copy).
         ...(reviewerTouched ? { judgeMode: "scripted-human-initjudge" } : {}),
         meta: {
             startedAt: input.startedAt,
@@ -321,6 +494,8 @@ export function assembleRow(input) {
             ...(reviewerTouched ? { reviewerKind: "scripted-human-rubric" } : {}),
         },
     };
+    // teamWorkerBudgetSumUsd is the bigger-pie guard input — kept on meta so assertBudgetMatch can read it (it is
+    // NOT a RunRecord scoring field). Stamped only for TEAM when the leader reported the real stamped split.
     if (arm === "TEAM" && input.teamWorkerBudgetSumUsd !== undefined && row.meta) {
         row.meta.teamWorkerBudgetSumUsd = input.teamWorkerBudgetSumUsd;
     }