@sema-agent/server 1.322.0 → 2.0.0

package/dist/bench/s1/run-firm.d.ts

@@ -1,48 +1,95 @@
+/**
+ * S1 value-verdict harness — the RESUMABLE FIRM-RUN DRIVER. SPEC-S1-value-harness.md §11 ("the human's post-step
+ * that wires this scaffold into a runnable batch CLI"). Enumerates the firm cells {C1,C2,C4} × the arms each trap
+ * declares × N seeds, runs each MISSING cell via `runArm` against a REAL `ProfileDeps` (live-deps.ts), records an
+ * append-only JSONL LEDGER keyed by (taskId, arm, seed), and at the end builds the `ValueJudgmentReport` via
+ * `buildS1Report`. The report IS the output — this driver never asserts which arm wins.
+ *
+ * 🔴 RESUMABLE (clay's hard requirement): on start the driver READS the ledger, builds the done-set, and runs ONLY
+ *    missing cells. A completed SCORED cell is NEVER re-run. A cell that throws / times out is recorded
+ *    `runStatus:"infra-failed"` (EXCLUDED from scoring, NOT a fake loss) AND left re-runnable on the next pass — so
+ *    a hang/crash mid-run resumes cleanly. Per-cell wall-clock timeout → kill the cell, mark infra-failed, move on.
+ *
+ * 🔴 --dry-run: a MOCK ProfileDeps (no E2B/DeepSeek) proves the driver loop + ledger + resume + buildReport work
+ *    DETERMINISTICALLY (this is what the test + CI exercise; the REAL run is the owner's gated step).
+ *
+ * 🔴 ENV GATING: the live path requires E2B_API_KEY + DEEPSEEK_API_KEY; absent → the driver refuses the live path
+ *    with a clear message (never a silent fake run). The deterministic --dry-run never needs keys.
+ */
 import { Runner } from "@sema-agent/core";
 import { type Arm } from "./arms.js";
 import { type TrapSpec } from "./tasks.js";
 import { type BenchBudget } from "./runner-ctx.js";
 import { type RawRow, type ValueJudgmentReport } from "./row.js";
 import { type LiveRuntimeConfig, type LiveCell } from "./live-deps.js";
+/** A ledger key uniquely identifies one cell (the resume primary key). */
 export interface CellKey {
     taskId: string;
     arm: Arm;
     seed: number | string;
 }
+/** One ledger record on disk: the emitted RawRow (a completed cell) — re-aggregated on the final pass. */
 export type LedgerRecord = RawRow;
+/** The driver options. */
 export interface RunFirmOptions {
+    /** Seeds per (trap, arm). Default 5 (clay: comprehensive → CLI `--seeds N`). */
     seeds?: number;
+    /** Optional cell filters for a controlled live run (single-cell smoke / re-run one trap-arm). `only` = a trapId
+     *  (e.g. "C1"), `arm` = a lowercase arm tag ("solo"|"sup"|"team"). The ledger keys are unchanged → a filtered run
+     *  still resumes/merges into the same run. */
     only?: string;
     arm?: string;
+    /** Per-cell wall-clock timeout ms. A cell that exceeds it is killed → infra-failed → re-runnable. Default 15min. */
     cellTimeoutMs?: number;
+    /** The append-only JSONL ledger path. */
     ledgerPath: string;
+    /** The output report JSON path. */
     reportPath: string;
+    /** The shared budget every arm runs on (the §3.2 fairness root). */
     budget: BenchBudget;
+    /** Provenance. */
     runId: string;
     gitSha: string;
+    /** DRY-RUN: inject a MOCK deps factory (no E2B/DeepSeek). The live path uses buildLiveDeps when this is absent. */
     mockDepsFactory?: (trap: TrapSpec, seed: number | string, cellId: string) => LiveCell;
+    /** The live runtime config (required for the live path; ignored in dry-run). */
     liveRuntime?: LiveRuntimeConfig;
+    /** Observability sink. */
     log?: (msg: string, meta?: Record<string, unknown>) => void;
 }
+/** The cell + the seam through which it runs (the SUP arm needs a per-cell CheckpointStore). */
 interface PlannedCell extends CellKey {
     trap: TrapSpec;
 }
+/** Enumerate the firm cells = FIRM_TRAPS × trap.arms × seeds. Optional `only` (trapId) / `arm` filters slice the
+ *  set for a controlled live run — a single-cell smoke (`--only C1 --arm solo --seeds 1`) before the full sweep, or
+ *  re-running one trap/arm. The ledger keys are unchanged, so a filtered run still resumes/merges into the same run. */
 export declare function enumerateCells(seeds: number, filter?: {
     only?: string;
     arm?: string;
 }): PlannedCell[];
+/** A stable string key for a cell (the ledger dedupe key). */
 export declare function cellKeyStr(k: CellKey): string;
+/** Read the ledger, returning ALL records + the done-set of SCORED-or-otherwise-completed cell keys. A record with
+ *  `runStatus:"infra-failed"` is NOT in the done-set (it is re-runnable — the resume contract). */
 export declare function readLedger(ledgerPath: string): Promise<{
     records: LedgerRecord[];
     done: Set<string>;
 }>;
+/**
+ * Run the firm batch. Returns the final `ValueJudgmentReport` (also written to `reportPath`). Resumable: re-running
+ * continues where it stopped, never re-running a completed scored cell.
+ */
 export declare function runFirm(opts: RunFirmOptions): Promise<{
     report: ValueJudgmentReport;
     scored: number;
     excluded: number;
     ranThisPass: number;
 }>;
+/** Parse a CLI flag as a positive integer; default when the flag is absent; exit(2) on a present-but-invalid value
+ *  (0, negative, NaN, fractional) rather than silently coercing it. */
 export declare function positiveIntArg(raw: string | undefined, def: number, flag: string): number;
+/** CLI entry. */
 export declare function main(argv?: string[]): Promise<void>;
 export { buildLiveDeps, liveRuntimeConfigFromEnv } from "./live-deps.js";
 export { Runner };

package/dist/bench/s1/run-firm.js

@@ -1,3 +1,21 @@
+/**
+ * S1 value-verdict harness — the RESUMABLE FIRM-RUN DRIVER. SPEC-S1-value-harness.md §11 ("the human's post-step
+ * that wires this scaffold into a runnable batch CLI"). Enumerates the firm cells {C1,C2,C4} × the arms each trap
+ * declares × N seeds, runs each MISSING cell via `runArm` against a REAL `ProfileDeps` (live-deps.ts), records an
+ * append-only JSONL LEDGER keyed by (taskId, arm, seed), and at the end builds the `ValueJudgmentReport` via
+ * `buildS1Report`. The report IS the output — this driver never asserts which arm wins.
+ *
+ * 🔴 RESUMABLE (clay's hard requirement): on start the driver READS the ledger, builds the done-set, and runs ONLY
+ *    missing cells. A completed SCORED cell is NEVER re-run. A cell that throws / times out is recorded
+ *    `runStatus:"infra-failed"` (EXCLUDED from scoring, NOT a fake loss) AND left re-runnable on the next pass — so
+ *    a hang/crash mid-run resumes cleanly. Per-cell wall-clock timeout → kill the cell, mark infra-failed, move on.
+ *
+ * 🔴 --dry-run: a MOCK ProfileDeps (no E2B/DeepSeek) proves the driver loop + ledger + resume + buildReport work
+ *    DETERMINISTICALLY (this is what the test + CI exercise; the REAL run is the owner's gated step).
+ *
+ * 🔴 ENV GATING: the live path requires E2B_API_KEY + DEEPSEEK_API_KEY; absent → the driver refuses the live path
+ *    with a clear message (never a silent fake run). The deterministic --dry-run never needs keys.
+ */
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { Runner, InMemoryCheckpointStore } from "@sema-agent/core";
@@ -7,8 +25,14 @@ import { makeBenchClock } from "./runner-ctx.js";
 import { buildS1Report, S1_SCHEMA_VERSION, S1_CORE_VERSION } from "./row.js";
 import { armTag } from "./row.js";
 import { buildLiveDeps, liveRuntimeConfigFromEnv } from "./live-deps.js";
+/** Enumerate the firm cells = FIRM_TRAPS × trap.arms × seeds. Optional `only` (trapId) / `arm` filters slice the
+ *  set for a controlled live run — a single-cell smoke (`--only C1 --arm solo --seeds 1`) before the full sweep, or
+ *  re-running one trap/arm. The ledger keys are unchanged, so a filtered run still resumes/merges into the same run. */
 export function enumerateCells(seeds, filter = {}) {
     const cells = [];
+    // 🔴 default sweep = FIRM_TRAPS only (directional traps must NEVER enter a firm verdict). An explicit --only MAY
+    // target a directional trap (e.g. C6 hazard) for a controlled make-real probe — its rows carry liveProof:directional
+    // so buildReport still excludes them from the verdict; running it just produces the data to CONFIRM the hazard fires.
     const source = filter.only ? ALL_TRAPS : FIRM_TRAPS;
     for (const trap of source) {
         if (filter.only && trap.id !== filter.only)
@@ -23,9 +47,12 @@ export function enumerateCells(seeds, filter = {}) {
     }
     return cells;
 }
+/** A stable string key for a cell (the ledger dedupe key). */
 export function cellKeyStr(k) {
     return `${k.taskId}::${armTag(k.arm)}::${String(k.seed)}`;
 }
+/** Read the ledger, returning ALL records + the done-set of SCORED-or-otherwise-completed cell keys. A record with
+ *  `runStatus:"infra-failed"` is NOT in the done-set (it is re-runnable — the resume contract). */
 export async function readLedger(ledgerPath) {
     let raw;
     try {
@@ -45,12 +72,14 @@ export async function readLedger(ledgerPath) {
             rec = JSON.parse(t);
         }
         catch {
-            continue;
+            continue; // a torn final line from a crash mid-write — skip it (the cell stays re-runnable)
         }
         records.push(rec);
+        // A cell is "done" (never re-run) ONLY when it is a completed scored/excluded-but-final row. An infra-failed
+        // row is re-runnable, so it does NOT enter the done-set. (The LAST record for a key wins on re-aggregation.)
         const key = cellKeyStr({ taskId: rec.taskId, arm: armUpper(rec.arm), seed: rec.seed ?? 0 });
         if (rec.runStatus === "infra-failed") {
-            done.delete(key);
+            done.delete(key); // a later successful re-run supersedes; an infra-failed alone keeps it runnable
         }
         else {
             done.add(key);
@@ -58,6 +87,7 @@ export async function readLedger(ledgerPath) {
     }
     return { records, done };
 }
+/** Map the lowercase wire tag back to the internal uppercase Arm. */
 function armUpper(tag) {
     switch (tag) {
         case "solo":
@@ -67,13 +97,18 @@ function armUpper(tag) {
         case "team":
             return "TEAM";
         default:
+            // 🔴 fail-loud (review council DESIGN#1): `tag` comes from a parsed JSONL ledger line, so a corrupt/unknown arm
+            // would otherwise produce an `undefined` cellKeyStr → silent dedup poisoning. A bad ledger row must throw, not
+            // collapse two cells onto one undefined key.
             throw new Error(`s1 run-firm: unknown arm tag ${JSON.stringify(tag)} in ledger row (expected solo|sup|team)`);
     }
 }
+/** Append one record to the ledger (atomic-ish: one write of one line + newline). */
 async function appendLedger(ledgerPath, rec) {
     await fs.mkdir(path.dirname(ledgerPath), { recursive: true });
     await fs.appendFile(ledgerPath, JSON.stringify(rec) + "\n", "utf8");
 }
+/** Run a promise with a wall-clock timeout. Rejects with a timeout error on expiry (the caller marks infra-failed). */
 function withTimeout(p, ms, label) {
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => reject(new Error(`cell timeout after ${ms}ms (${label})`)), ms);
@@ -87,6 +122,7 @@ function withTimeout(p, ms, label) {
         });
     });
 }
+/** Build an infra-failed RawRow for a cell that threw/timed out (EXCLUDED, NOT a fake loss; re-runnable). */
 function infraFailedRow(cell, ctx) {
     const now = ctx.clock.now();
     return {
@@ -105,9 +141,13 @@ function infraFailedRow(cell, ctx) {
             humanReview: { count: 0, totalWaitMs: 0, gates: [] },
         },
         wallTimeSec: 0,
-        meta: { startedAt: now, finishedAt: now, coreVersion: S1_CORE_VERSION, gitSha: ctx.gitSha, runId: ctx.runId },
+        meta: { startedAt: now, finishedAt: now, coreVersion: S1_CORE_VERSION, gitSha: ctx.gitSha, runId: ctx.runId }, // L16:动态读装机 core 版本(硬钉曾漂到 1.111.0)
     };
 }
+/**
+ * Run the firm batch. Returns the final `ValueJudgmentReport` (also written to `reportPath`). Resumable: re-running
+ * continues where it stopped, never re-running a completed scored cell.
+ */
 export async function runFirm(opts) {
     const seeds = opts.seeds ?? 5;
     if (!Number.isInteger(seeds) || seeds < 1)
@@ -146,16 +186,23 @@ export async function runFirm(opts) {
         }
         await appendLedger(opts.ledgerPath, row);
         ranThisPass++;
+        // Only a non-infra-failed row enters the done-set (an infra-failed cell stays re-runnable on the next pass).
         if (row.runStatus !== "infra-failed")
             done.add(key);
         log("cell_done", { key, runStatus: row.runStatus });
     }
+    // Final pass: load ALL ledger rows, de-dupe to the LAST record per key (a re-run supersedes an earlier
+    // infra-failed), build the report.
     const { records } = await readLedger(opts.ledgerPath);
     const lastByKey = new Map();
     for (const rec of records) {
         lastByKey.set(cellKeyStr({ taskId: rec.taskId, arm: armUpper(rec.arm), seed: rec.seed ?? 0 }), rec);
     }
     const allRows = [...lastByKey.values()];
+    // 🔴 (review HIGH finding) the firm report is FIRM_TRAPS rows ONLY. A directional probe (C6/C7) can share a ledger
+    //    via --only, and buildReport does NOT filter by liveProof — an unfiltered call would let directional rows
+    //    pollute the firm comparisons/pareto. Filter to firm taskIds here (directional rows stay in the ledger for
+    //    separate analysis); a directional probe should also use its own --run-id to keep ledgers cleanly separate.
     const firmIds = new Set(FIRM_TRAPS.map((t) => t.id));
     const rows = allRows.filter((r) => firmIds.has(r.taskId));
     const report = buildS1Report(rows);
@@ -165,13 +212,21 @@ export async function runFirm(opts) {
     const excluded = rows.length - scored;
     return { report, scored, excluded, ranThisPass };
 }
+/** Build a live cell or throw a clear message if the live runtime is missing (env gating). */
 function buildLiveCellOrThrow(opts, trap, seed, cellId) {
     if (!opts.liveRuntime) {
         throw new Error("S1 run-firm: live path requires E2B_API_KEY + DEEPSEEK_API_KEY (the brain gateway). None resolved — refusing a silent fake run. Use --dry-run for the deterministic loop, or set the keys for the owner's gated live run.");
     }
     return buildLiveDeps(opts.liveRuntime, trap, seed, cellId);
 }
+// ─────────────────────────────── CLI ───────────────────────────────
+/** The default shared budget (the §3.2 fairness root). Overridable via CLI flags. */
 function defaultBudget(modelId) {
+    // 🔴 maxTokens is a GENEROUS safety net, NOT the binding gate (clay: budget unlimited). The 1-cell live smoke caught
+    // that maxTokens:8000 capped EVERY run "failed" → infra-failed → nothing ever scored: the token counter includes
+    // CACHED tokens (97% cache hit), so a single verify round over repo context blew 8000 while real cost was ~$0. The
+    // real, FAIR economic gate is maxCostUsd + maxTurns (uniform across all arms); maxTokens just must not bind before
+    // them. 200k comfortably fits ~12 turns of verify→fix with repo context; cost stays the measured economic axis.
     return { modelId, maxTokens: 200_000, maxCostUsd: 1.0, maxTurns: 12, maxRounds: 2, supAutoBudget: 1 };
 }
 function parseArgs(argv) {
@@ -180,6 +235,9 @@ function parseArgs(argv) {
         return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined;
     };
     const runId = get("run-id") ?? `s1-firm-${Date.now()}`;
+    // --seeds / --cell-timeout-ms: explicit positive-integer validation (NOT a `|| default` truthy coercion, which
+    // silently turns `--seeds 0` into 5 and lets `--seeds -1` enumerate ZERO cells = a silent empty run). Absent flag
+    // → default; present-but-invalid → a clear error + non-zero exit (never a silently-coerced batch).
     const seeds = positiveIntArg(get("seeds"), 5, "--seeds");
     const cellTimeoutMs = positiveIntArg(get("cell-timeout-ms"), 15 * 60_000, "--cell-timeout-ms");
     return {
@@ -193,6 +251,8 @@ function parseArgs(argv) {
         ...(get("arm") ? { arm: get("arm") } : {}),
     };
 }
+/** Parse a CLI flag as a positive integer; default when the flag is absent; exit(2) on a present-but-invalid value
+ *  (0, negative, NaN, fractional) rather than silently coercing it. */
 export function positiveIntArg(raw, def, flag) {
     if (raw === undefined)
         return def;
@@ -203,13 +263,15 @@ export function positiveIntArg(raw, def, flag) {
     }
     return n;
 }
+/** The mock deps factory for --dry-run: a deterministic LiveCell (no E2B/DeepSeek). Per-cell deterministic by seed. */
 function dryRunMockFactory() {
     return (trap, seed) => {
+        // A deterministic stats fixture + a deterministic oracle keyed on the trap (C2 = impossible-spec → not green).
         const stats = {
             costBreakdown: { llmRootMicroUsd: 50_000, nestedSubagentMicroUsd: 0, memoryConsolidationMicroUsd: 0, compactionMicroUsd: 0 },
             humanReview: { count: 0, totalWaitMs: 0, gates: [] },
         };
-        const green = trap.id !== "C2-honest-bound";
+        const green = trap.id !== "C2-honest-bound"; // C2's contradiction can never be objectively correct
         const oracle = { delivered: true, hiddenTestsGreen: green, buildPassed: true, invariantsOk: true };
         const vr = {
             taskId: trap.id,
@@ -232,6 +294,7 @@ function dryRunMockFactory() {
         return { deps, dispose: async () => { } };
     };
 }
+/** CLI entry. */
 export async function main(argv = process.argv.slice(2)) {
     const args = parseArgs(argv);
     const liveRuntime = liveRuntimeConfigFromEnv();
@@ -272,6 +335,8 @@ export async function main(argv = process.argv.slice(2)) {
         directionalOnly: result.report.directionalOnly,
     }, null, 2));
 }
+// Run as a CLI when invoked directly (not when imported by the test). `import.meta.url` guard keeps the module
+// import-safe for the deterministic test.
 const isMain = (() => {
     try {
         return typeof process !== "undefined" && Array.isArray(process.argv) && /run-firm(\.[jt]s)?$/.test(process.argv[1] ?? "");
@@ -286,6 +351,7 @@ if (isMain) {
         process.exit(1);
     });
 }
+// Re-export the live wiring for the owner's gated run + the test.
 export { buildLiveDeps, liveRuntimeConfigFromEnv } from "./live-deps.js";
 export { Runner };
 //# sourceMappingURL=run-firm.js.map

package/dist/bench/s1/runner-ctx.d.ts

@@ -1,4 +1,26 @@
+/**
+ * S1 value-verdict harness — the FAIRNESS ROOT (SPEC-S1-value-harness.md §2). ONE place constructs the shared
+ * Runner ingredients (config / brain / pricing), the SAME budget for every arm, and the injected deterministic
+ * clock that makes C2 (human-review wall-time) reproducible.
+ *
+ * 🔴 THE §3.2 RED LINE (design/89's #1 confound): every leaf TaskSpec across all 3 arms carries the SAME
+ * `{ maxTokens, maxCostUsd, limits.maxTurns }`, and TEAM's per-worker budgets sum to ≤ the solo budget — so no
+ * arm can win on a bigger pie. `assertBudgetMatch` (below) is the build-time guard the shape test runs.
+ *
+ * 🔴 BUDGET-MATCH for TEAM is NEW WIRING the live conflict test does NOT do: `leader-conflict-resolver-live.test.ts`
+ * sets NO budget on `SubtaskSpec.spec` and NO `now` on any Runner. The harness STAMPS both (arms.ts) — copying the
+ * live test verbatim would yield an unbounded TEAM (the confound) and an empty `humanReview` (C2 = undefined).
+ *
+ * The real-infra construction (E2B worker/grader envs + a live brain) is deferred to the live make-real proof
+ * (`test/s1-value-live.test.ts`, gated on E2B+DEEPSEEK). This module only fixes the SHAPE + the budget invariant
+ * + the clock; a deterministic shape test exercises it with a MOCK runner (no real agents, no keys).
+ */
 import type { ExecutionEnv } from "@sema-agent/core";
+/**
+ * The budget block the budget-match guard compares. NOT a s1.v1 RawRow field (the contract carries no budget) —
+ * it is a PRODUCER-side fairness descriptor (one per emitted cell). `teamWorkerBudgetSumUsd` is the bigger-pie
+ * guard input (TEAM only): Σ per-worker maxCostUsd, asserted ≤ maxCostUsd.
+ */
 export interface RowBudget {
     modelId: string;
     maxTokens: number;
@@ -6,28 +28,68 @@ export interface RowBudget {
     maxTurns: number;
     maxRounds: number;
     supAutoBudget?: number;
+    /** TEAM only: Σ per-worker maxCostUsd — asserted ≤ maxCostUsd (anti-bigger-pie confound). */
     teamWorkerBudgetSumUsd?: number;
 }
+/** Project the producer's shared budget (+ an optional TEAM worker-sum) into a `RowBudget` for the fairness guard. */
 export declare function budgetDescriptor(budget: BenchBudget, arm: string, teamWorkerBudgetSumUsd?: number): RowBudget;
+/** The single budget every arm shares (the §3.2 red line). All scalars are the SAME across SOLO/SUP/TEAM. */
 export interface BenchBudget {
+    /** SAME base model all arms (design/89 §3.2 — decorrelation is a separate axis, not the value axis). */
     modelId: string;
+    /** `TaskSpec.maxTokens` — SAME all arms. */
     maxTokens: number;
+    /** `TaskSpec.maxCostUsd` — SAME all arms (also the per-run spend cap). For TEAM, Σworker ≤ this. */
     maxCostUsd: number;
+    /** `TaskSpec.limits.maxTurns` — SAME all arms. */
     maxTurns: number;
+    /** `VerifyConfig.maxRounds` (verify-fix rounds) — SAME for SOLO & SUP. */
     maxRounds: number;
+    /** `createDurableAskPolicy.autoBudget` — the SUP per-leg auto-approve circuit-breaker count, constant across SUP cells. */
     supAutoBudget: number;
 }
+/**
+ * An injectable deterministic clock (SPEC §2). EVERY Runner in EVERY arm is built with `now: ctx.now`, and the
+ * reviewer's modeled think-time advances `advanceClock(ms)` — so `stats.humanReview.totalWaitMs` is reproducible
+ * and NEVER consumes real wall-time (`RunnerDeps.now`, core types.d.ts:1002 / design/91 §4.3 flaky-guard).
+ *
+ * 🔴 CLOCK-ADVANCE OWNERSHIP (review #10 — HARNESS-OWNS-CLOCK, the single fold point per arm): the modeled review
+ * wait is folded into ctx.clock by the HARNESS exactly once per arm — SUP in driveSupSuspendResume (per leg), TEAM
+ * in runArm after captureTeamStats. The live TEAM leader's workers therefore MUST NOT advance ctx.clock themselves
+ * (give them a child/frozen clock); if a worker shared ctx.now and hit a modeled review gate it would advance the
+ * clock, and runArm's `advanceClock(stats.humanReview.totalWaitMs)` would DOUBLE-COUNT the same wait into C3
+ * (wallTimeSec), making TEAM look slower than it is — a value-verdict confound in a fair-comparison harness.
+ */
 export interface BenchClock {
     now: () => number;
     advanceClock: (ms: number) => void;
 }
+/** Construct the deterministic clock used to model C2 review seconds (no real wall-time advance). */
 export declare function makeBenchClock(startEpochMs?: number): BenchClock;
+/**
+ * The shared context every arm runs in. Construction of `config/brain/pricing/newWorkerEnv/newGraderEnv` is the
+ * live make-real proof's job (it needs real keys + a real adapter). The SHAPE is fixed here so the arm runner +
+ * the shape test type-check against it.
+ *
+ * 🔴 `newGraderEnv` MUST return a DISTINCT env object from `newWorkerEnv` (decorrelation + the repair-loop §5.1
+ * anti-reward-hack identity check — `repair-loop.d.ts`: `graderEnv === workerEnv → oracle.unprotected`). The
+ * oracle (oracle.ts) ALWAYS grades in a grader env; the repair leg ALWAYS passes `workerEnv` so the identity
+ * check is LIVE (it is SKIPPED when `workerEnv` is undefined → a silently reward-hackable oracle).
+ */
 export interface RunnerCtx {
     budget: BenchBudget;
     clock: BenchClock;
+    /** A stable id for the whole batch (rows carry it for resume-by-(taskId,repeatIdx,arm) + orphan reap). */
     runId: string;
+    /** The git SHA the harness ran at (provenance for search). */
     gitSha: string;
 }
+/**
+ * Apply the shared budget to a leaf TaskSpec-like object (SOLO impl, SUP impl, each TEAM `SubtaskSpec.spec`).
+ * Returns the budget fields to spread onto the spec — kept as a helper so EVERY leaf is stamped identically
+ * (the live tests forget this for TEAM workers — the confound). `maxCostUsd` is overridable for the TEAM
+ * per-worker split (Σ ≤ solo, enforced by `assertBudgetMatch`).
+ */
 export declare function leafBudgetFields(budget: BenchBudget, overrideMaxCostUsd?: number): {
     maxTokens: number;
     maxCostUsd: number;
@@ -35,10 +97,19 @@ export declare function leafBudgetFields(budget: BenchBudget, overrideMaxCostUsd
         maxTurns: number;
     };
 };
+/**
+ * BUDGET-MATCH build-time guard (the §3.2 red line — run by the shape test). FAILS if, within a task class:
+ *   (a) any arm's `{ modelId, maxTokens, maxCostUsd, maxTurns, maxRounds }` differs, OR
+ *   (b) a TEAM row's `teamWorkerBudgetSumUsd` exceeds `maxCostUsd` (the bigger-pie confound).
+ *
+ * Pure over the rows' `budget` blocks (so it works on emitted RawRows AND on a pre-flight check). Returns the
+ * list of violations (empty = OK) so the caller can assert it.
+ */
 export declare function assertBudgetMatch(rows: Array<{
     arm: string;
     taskId: string;
     budget: RowBudget;
 }>): string[];
+/** Assert two execution envs are DISTINCT objects (the §5.1 anti-reward-hack precondition). Throws if same. */
 export declare function assertDistinctEnvs(workerEnv: ExecutionEnv, graderEnv: ExecutionEnv): void;
 //# sourceMappingURL=runner-ctx.d.ts.map

package/dist/bench/s1/runner-ctx.js

@@ -1,3 +1,21 @@
+/**
+ * S1 value-verdict harness — the FAIRNESS ROOT (SPEC-S1-value-harness.md §2). ONE place constructs the shared
+ * Runner ingredients (config / brain / pricing), the SAME budget for every arm, and the injected deterministic
+ * clock that makes C2 (human-review wall-time) reproducible.
+ *
+ * 🔴 THE §3.2 RED LINE (design/89's #1 confound): every leaf TaskSpec across all 3 arms carries the SAME
+ * `{ maxTokens, maxCostUsd, limits.maxTurns }`, and TEAM's per-worker budgets sum to ≤ the solo budget — so no
+ * arm can win on a bigger pie. `assertBudgetMatch` (below) is the build-time guard the shape test runs.
+ *
+ * 🔴 BUDGET-MATCH for TEAM is NEW WIRING the live conflict test does NOT do: `leader-conflict-resolver-live.test.ts`
+ * sets NO budget on `SubtaskSpec.spec` and NO `now` on any Runner. The harness STAMPS both (arms.ts) — copying the
+ * live test verbatim would yield an unbounded TEAM (the confound) and an empty `humanReview` (C2 = undefined).
+ *
+ * The real-infra construction (E2B worker/grader envs + a live brain) is deferred to the live make-real proof
+ * (`test/s1-value-live.test.ts`, gated on E2B+DEEPSEEK). This module only fixes the SHAPE + the budget invariant
+ * + the clock; a deterministic shape test exercises it with a MOCK runner (no real agents, no keys).
+ */
+/** Project the producer's shared budget (+ an optional TEAM worker-sum) into a `RowBudget` for the fairness guard. */
 export function budgetDescriptor(budget, arm, teamWorkerBudgetSumUsd) {
     return {
         modelId: budget.modelId,
@@ -9,6 +27,7 @@ export function budgetDescriptor(budget, arm, teamWorkerBudgetSumUsd) {
         ...(arm === "TEAM" && teamWorkerBudgetSumUsd !== undefined ? { teamWorkerBudgetSumUsd } : {}),
     };
 }
+/** Construct the deterministic clock used to model C2 review seconds (no real wall-time advance). */
 export function makeBenchClock(startEpochMs = Date.now()) {
     let t = startEpochMs;
     return {
@@ -20,6 +39,12 @@ export function makeBenchClock(startEpochMs = Date.now()) {
         },
     };
 }
+/**
+ * Apply the shared budget to a leaf TaskSpec-like object (SOLO impl, SUP impl, each TEAM `SubtaskSpec.spec`).
+ * Returns the budget fields to spread onto the spec — kept as a helper so EVERY leaf is stamped identically
+ * (the live tests forget this for TEAM workers — the confound). `maxCostUsd` is overridable for the TEAM
+ * per-worker split (Σ ≤ solo, enforced by `assertBudgetMatch`).
+ */
 export function leafBudgetFields(budget, overrideMaxCostUsd) {
     return {
         maxTokens: budget.maxTokens,
@@ -27,8 +52,17 @@ export function leafBudgetFields(budget, overrideMaxCostUsd) {
         limits: { maxTurns: budget.maxTurns },
     };
 }
+/**
+ * BUDGET-MATCH build-time guard (the §3.2 red line — run by the shape test). FAILS if, within a task class:
+ *   (a) any arm's `{ modelId, maxTokens, maxCostUsd, maxTurns, maxRounds }` differs, OR
+ *   (b) a TEAM row's `teamWorkerBudgetSumUsd` exceeds `maxCostUsd` (the bigger-pie confound).
+ *
+ * Pure over the rows' `budget` blocks (so it works on emitted RawRows AND on a pre-flight check). Returns the
+ * list of violations (empty = OK) so the caller can assert it.
+ */
 export function assertBudgetMatch(rows) {
     const violations = [];
+    // Group by task class (here: taskId — each trap is its own class for the budget invariant).
     const byTask = new Map();
     for (const r of rows) {
         const g = byTask.get(r.taskId) ?? [];
@@ -44,6 +78,7 @@ export function assertBudgetMatch(rows) {
                     violations.push(`budget-match: task ${taskId} arm ${r.arm} ${k}=${String(b[k])} != ${r.arm === group[0].arm ? "" : `${group[0].arm} `}${String(ref[k])}`);
                 }
             }
+            // (b) TEAM bigger-pie guard: Σ per-worker budget must not exceed the shared per-arm maxCostUsd.
             if (b.teamWorkerBudgetSumUsd !== undefined && b.teamWorkerBudgetSumUsd > b.maxCostUsd + 1e-9) {
                 violations.push(`budget-match: task ${taskId} arm ${r.arm} teamWorkerBudgetSumUsd=${b.teamWorkerBudgetSumUsd} > maxCostUsd=${b.maxCostUsd} (bigger-pie confound)`);
             }
@@ -51,6 +86,7 @@ export function assertBudgetMatch(rows) {
     }
     return violations;
 }
+/** Assert two execution envs are DISTINCT objects (the §5.1 anti-reward-hack precondition). Throws if same. */
 export function assertDistinctEnvs(workerEnv, graderEnv) {
     if (workerEnv === graderEnv) {
         throw new Error("S1 oracle: graderEnv === workerEnv — the anti-reward-hack identity check would fail closed (oracle.unprotected). The grader MUST be a distinct env (decorrelation + the repair-loop §5.1 boundary).");