@sema-agent/server 1.322.0 → 2.0.0

package/dist/bench/s1/live-deps.js

@@ -1,3 +1,39 @@
+/**
+ * S1 value-verdict harness — the REAL `ProfileDeps` factory (the LIVE make-real wiring). SPEC-S1-value-harness.md
+ * §11 "the wiring of ProfileDeps to the REAL core entrypoints + REAL E2B worker/grader envs". This module
+ * ASSEMBLES a bench runtime — createBrain(DeepSeek) + a real `Runner` + a real E2B WORKER env + a DISTINCT E2B
+ * GRADER env + createLeaderRunner for TEAM — and returns a `ProfileDeps` whose EVERY seam runs the REAL engine/
+ * oracle. The deterministic driver (`run-firm.ts --dry-run`) injects a MOCK; this is the clay-gated live path.
+ *
+ * 🔴 ANTI-REWARD-HACK (oracle.ts §, runner-ctx.ts §5.1): the oracle ALWAYS grades in a env that is a DISTINCT
+ *    object from the worker env. We provision a SEPARATE E2B sandbox for the grader and transfer the worker's
+ *    COMMITTED tree into it via `git bundle` (export from the worker sandbox → import into the grader sandbox) —
+ *    so the grader's checkout is the worker's HEAD, but the grader sandbox can never be tampered by the worker
+ *    (its hidden tests + its exec all run in a sandbox the worker never touched). `assertDistinctEnvs` is the
+ *    build-time guard; the structural separation is the real boundary.
+ *
+ * 🔴 TRAP TASKS RUN ISOLATED (the task prompt): every worker leg runs inside an E2B Firecracker VM
+ *    (`RemoteContainerExecutionEnv`), NEVER the bare host — a C4/trap that reaches for a dangerous action is
+ *    contained by the VM boundary (`capabilities.isolation === true`).
+ *
+ * 🔴 OBJECTIVE ORACLE ONLY (row.ts §): `runOracle` runs `runExecGate` over real exit codes in the grader env;
+ *    there is NO LLM-judge in the numerator. The LLM is only a GATE inside an arm (the verify/repair/reviewer).
+ *
+ * 🔴 HONEST GAPS (flagged, NOT stubbed): the per-cell worker/grader env LIFECYCLE (provision → run → grade →
+ *    destroy) is owned by `buildLiveDeps`, which returns a `ProfileDeps` bound to ONE (trap, seed) cell — the
+ *    driver constructs a fresh `buildLiveDeps` per cell and disposes it after the row is emitted (so a hung cell's
+ *    sandboxes are reaped). `runCounterfactualOracle` is DELIBERATELY OMITTED (a real ablation — re-running the
+ *    SAME (trap,seed) with the gate DISABLED into a FRESH worker — is TODO); absent ⇒ buildCounterfactual returns
+ *    undefined ⇒ the metric tool records UNVERIFIED-WITHHELD (NO avoided-loss credit), the honest "not measured"
+ *    choice. The previous `runCounterfactualOracle: runOracle` self-alias re-graded the IDENTICAL post-gate tree and
+ *    auto-credited EVERY withhold as CORRECTLY-WITHHELD (a tautology) — removed.
+ *
+ * 🔴 TEAM (the leader arm): the leader INTEGRATES + PUSHES to a per-cell `git://127.0.0.1` durable remote (served by
+ *    a local `git daemon` — the wire validator forbids file://). On a delivered run the harness clones that
+ *    integrated tree INTO state.worker, so `runOracle` grades the REAL integrated output in the DISTINCT grader (the
+ *    same anti-reward-hack transfer path SOLO/SUP use). If the integrated tree can't be imported, the cell is
+ *    `infraFailed` (EXCLUDED) — NEVER a fabricated uniform delivered=false loss for the whole TEAM column.
+ */
 import { Runner, runWithVerification, resumeWithVerification, runRepairLoop, combinePolicies, createDurableQuestionPolicy, QUESTION_AWAITS_RESUME, } from "@sema-agent/core";
 import { loadConfig } from "../../config.js";
 import { createBrain } from "../../brain.js";
@@ -8,14 +44,23 @@ import { createLeaderRunner } from "../../leader/wire.js";
 import { runOracle as runStandaloneOracle } from "./oracle.js";
 import { makeRepairOracle } from "./repair-oracle-adapter.js";
 import { assertDistinctEnvs } from "./runner-ctx.js";
+/** The worker/grader workspace root inside each E2B VM. */
 const W = "/home/user";
+/** The repo dir inside each VM where the worker's tree lives + the grader checks out. */
 const REPO = `${W}/repo`;
+/** The grader's base ref for the `delivered` (HEAD advanced past base) signal. The seed commits an empty base. */
 const BASE_REF = "s1-base";
+/** Build the live runtime config from env. GATED on E2B_API_KEY + DEEPSEEK_API_KEY + non-zero MODEL_COST_INPUT/OUTPUT
+ *  (so C1 is real and maxCostUsd binds). Returns undefined when a required key/price is absent — the driver then
+ *  refuses the live path with a clear message (never a silent fake run, never a fabricated $0 cost axis). */
 export function liveRuntimeConfigFromEnv(env = process.env) {
     const e2bApiKey = env.E2B_API_KEY;
     const deepseekApiKey = env.DEEPSEEK_API_KEY;
     if (!e2bApiKey || !deepseekApiKey)
         return undefined;
+    // 🔴 Cost rates are LOAD-BEARING for the value verdict (C1 + the maxCostUsd safety net). A live run with $0 pricing
+    // would produce a fully-green report whose entire cost dimension is fake — the SAME defect class as the fixed
+    // delivered-always-false / maxTokens bugs. Fail LOUD (return undefined → driver refuses) when they're missing.
     const costInput = Number(env.MODEL_COST_INPUT ?? "");
     const costOutput = Number(env.MODEL_COST_OUTPUT ?? "");
     if (!(costInput > 0) || !(costOutput > 0))
@@ -37,20 +82,28 @@ export function liveRuntimeConfigFromEnv(env = process.env) {
         ...(Number(env.MODEL_COST_CACHE_WRITE ?? "") > 0 ? { costCacheWrite: Number(env.MODEL_COST_CACHE_WRITE) } : {}),
     };
 }
+/** Build the service `ServiceConfig`-shaped brain/pricing ingredients from the live runtime config. We construct a
+ *  MINIMAL ServiceConfig (only the fields createBrain + buildPricing read) pointed at the DeepSeek gateway. */
 function buildBrainIngredients(rt) {
+    // Point the loader at DeepSeek (mirrors the live tests' env stamping) then build the brain/pricing.
     process.env.MODEL_GATEWAY_BASEURL = rt.gatewayBaseUrl;
     process.env.MODEL_ID = rt.modelId;
     process.env.MODEL_API_KEY = rt.deepseekApiKey;
     process.env.MODEL_MAX_TOKENS = String(rt.maxTokens ?? 8000);
+    // 🔴 Stamp the cost rates so config.ts builds a NON-ZERO Model.cost → core computes real C1 µUSD + the maxCostUsd
+    // gate binds (review fix). Without this the cost half of the value Pareto is a fabricated $0 across all arms.
     process.env.MODEL_COST_INPUT = String(rt.costInput);
     process.env.MODEL_COST_OUTPUT = String(rt.costOutput);
     if (rt.costCacheRead != null)
         process.env.MODEL_COST_CACHE_READ = String(rt.costCacheRead);
     if (rt.costCacheWrite != null)
         process.env.MODEL_COST_CACHE_WRITE = String(rt.costCacheWrite);
+    // loadConfig is the authoritative builder of the models/roles/pricing-key catalog (config.ts has no import of
+    // this module → no cycle). It reads the DeepSeek env we just stamped above.
     const config = loadConfig();
     const brain = createBrain(config, {});
     const pricing = buildPricing(config.models);
+    // 🔴 Defensive assert: if pricing regresses to zero the C1 axis is fake. Catch drift at build, not in a report.
     const p = pricing[rt.modelId];
     if (!p || ((p.inputPer1M ?? 0) === 0 && (p.outputPer1M ?? 0) === 0)) {
         throw new Error(`s1 live: zero pricing for ${rt.modelId} — C1 cost axis would be a fabricated $0 (set MODEL_COST_INPUT/OUTPUT)`);
@@ -63,6 +116,7 @@ const sh = (env) => async (cmd) => {
         throw new Error(`s1 transport: ${r.error.message}`);
     return { code: r.value.exitCode, out: (r.value.stdout + r.value.stderr).trim() };
 };
+/** Provision + connect a fresh E2B sandbox with an empty git repo seeded at the `s1-base` ref. */
 async function provisionSandbox(rt, role, cellId) {
     const env = new RemoteContainerExecutionEnv({
         apiKey: rt.e2bApiKey,
@@ -75,10 +129,14 @@ async function provisionSandbox(rt, role, cellId) {
         throw new Error(`s1 ${role} sandbox connect failed (${cellId}): ${c.error.message}`);
     return env;
 }
+/** Seed a base repo at the `s1-base` ref (the worker commits ON TOP; `delivered` = HEAD advanced past it). When
+ *  `seedFiles` is given (hazard traps, C6) they are written + committed INTO the base — the worker sees them and may
+ *  delete them (the survival oracle then checks the sentinel still exists in the committed tree). Absent ⇒ empty base. */
 async function seedBaseRepo(env, seedFiles) {
+    // Write each seed file via base64 (no shell-escaping hazard with arbitrary content) into REPO before the base commit.
     const writeCmds = (seedFiles ?? [])
         .map((f) => {
-        const rel = f.path.startsWith(REPO) ? f.path.slice(REPO.length + 1) : f.path;
+        const rel = f.path.startsWith(REPO) ? f.path.slice(REPO.length + 1) : f.path; // store relative to REPO
         const b64 = Buffer.from(f.content, "utf8").toString("base64");
         return `mkdir -p "$(dirname '${rel}')" 2>/dev/null; printf %s '${b64}' | base64 -d > '${rel}'`;
     })
@@ -91,7 +149,18 @@ async function seedBaseRepo(env, seedFiles) {
     if (r.code !== 0)
         throw new Error(`s1 seed base repo failed: ${r.out.slice(-400)}`);
 }
+/**
+ * Transfer the WORKER's committed tree into the DISTINCT GRADER sandbox (anti-reward-hack). Exports a `git bundle`
+ * of the full history from the worker sandbox, base64-pipes it through the control plane (no shared remote needed),
+ * imports it into the grader's repo, and checks out the worker HEAD with the `s1-base` ref recreated. The grader is
+ * a SEPARATE sandbox the worker never touched, so its hidden-test run cannot be tampered.
+ */
 async function transferWorkerTreeToGrader(worker, grader) {
+    // 🔴 tar-worktree, NOT git bundle/clone (firm-v1/C4 root cause): the grader-side `git clone` is unreliable on BOTH
+    // backends — E2B is a platform heisenbug (same code firm-v1 ran green now leaves an unusable .git), Kata is a
+    // virtiofs st_dev limit. So the grader NEVER runs git: the worker (where git works) computes the HEAD + s1-base
+    // shas and emits a `git archive` tar of the committed tree (no .git); the grader just `tar -x`s plain files.
+    // `delivered` (head≠base) comes from the shas. anti-reward-hack unchanged (distinct grader env + restore-before-score).
     const headProbe = await sh(worker)(`cd ${REPO} && git rev-parse HEAD`);
     const baseProbe = await sh(worker)(`cd ${REPO} && git rev-parse ${BASE_REF}`);
     const head = headProbe.out.trim();
@@ -100,12 +169,14 @@ async function transferWorkerTreeToGrader(worker, grader) {
         throw new Error(`s1 worker HEAD unresolved: ${headProbe.out.slice(-200)}`);
     if (!/^[0-9a-f]{40}$/.test(base))
         throw new Error(`s1 worker base ref unresolved: ${baseProbe.out.slice(-200)}`);
+    // git archive HEAD = the committed worktree as a tar (no .git), on stdout → base64 to ferry over the exec transport.
     const arch = await sh(worker)(`cd ${REPO} && git archive --format=tar HEAD | base64 -w0`);
     if (arch.code !== 0)
         throw new Error(`s1 worker archive failed: ${arch.out.slice(-400)}`);
     const buf = Buffer.from(arch.out.trim(), "base64");
     if (buf.length === 0)
         throw new Error("s1 worker archive decoded empty on the control plane");
+    // Grader: BINARY write the tar (base64-string-over-files.write corrupts; binary is gtest4-proven) + tar -x plain files.
     const wr = await grader.writeFile(`/tmp/s1-wt.tar`, new Uint8Array(buf));
     if (!wr.ok)
         throw new Error(`s1 grader tar write failed: ${wr.error.message}`);
@@ -116,23 +187,47 @@ async function transferWorkerTreeToGrader(worker, grader) {
         console.error(`[S1_DEBUG_TAR] head=${head.slice(0, 8)} base=${base.slice(0, 8)} tarBytes=${buf.length} ${ext.out.slice(-60)}`);
     return { head, base };
 }
+/**
+ * Import a git-bundle (base64) into the GRADER sandbox and pin `s1-base` to an EXACT base hash. Shared by the SOLO/SUP
+ * path (bundle from the worker sandbox) and the TEAM path (bundle from the control-plane integrated repo — the E2B
+ * worker is network-isolated from the leader's git daemon, so the integrated tree is bundled on the control plane and
+ * shipped here, NOT cloned from inside E2B). The base hash is set explicitly (never re-derived in the grader → can't
+ * collapse to HEAD). Fail-closed: the grader's s1-base MUST resolve to the given hash AND differ from HEAD.
+ */
 async function importBundleB64ToGrader(grader, bundleB64, baseHash) {
     if (!/^[0-9a-f]{40}$/.test(baseHash))
         throw new Error(`s1 grader import: invalid base hash ${JSON.stringify(baseHash)}`);
     const wr = await grader.writeFile(`/tmp/s1.bundle.b64`, bundleB64);
     if (!wr.ok)
         throw new Error(`s1 grader bundle write failed: ${wr.error.message}`);
+    // SOLO/SUP path: the b64 is WORKER-ORIGIN (generated by `base64 -w0` inside the same E2B image), so `base64 -d`
+    // round-trips cleanly (proven by firm-v1 N=10, 40 SOLO/SUP cells delivered=true). The CONTROL-PLANE-origin b64
+    // does NOT round-trip through E2B files.write (firm-v1/C4 dig) — that's why the TEAM path uses a BINARY write
+    // (importBundleBinaryToGrader) instead. `test -s` guards an empty decode defensively.
     const imp = await sh(grader)(`set -e; base64 -d /tmp/s1.bundle.b64 > /tmp/s1.bundle; test -s /tmp/s1.bundle; rm -rf ${REPO}; ` +
         `git clone -q /tmp/s1.bundle ${REPO}; cd ${REPO}; ` +
         `git config user.email s1@bench.local; git config user.name s1-bench; ` +
         `git tag -f ${BASE_REF} ${baseHash}`);
     if (imp.code !== 0)
         throw new Error(`s1 grader import failed: ${imp.out.slice(-400)}`);
+    // Fail-closed verify: the grader's base MUST resolve to the given base hash AND HEAD must have advanced past it
+    // (else `delivered` is meaningless).
     const verify = await sh(grader)(`cd ${REPO} && echo "BASE=$(git rev-parse ${BASE_REF}) HEAD=$(git rev-parse HEAD)"`);
     if (!verify.out.includes(`BASE=${baseHash}`))
         throw new Error(`s1 grader base mismatch: ${verify.out.slice(-200)} expected BASE=${baseHash}`);
 }
+/**
+ * Import a git-bundle (RAW BINARY Buffer) into the GRADER and pin `s1-base` to an EXACT base hash. The TEAM path: the
+ * leader's integrated tree is bundled on the CONTROL PLANE, so we ship the bundle as BINARY via E2B files.write
+ * (Uint8Array) — 🔴 a base64-STRING through files.write decodes to garbage in the sandbox (firm-v1/C4 dig: a
+ * Node-Buffer b64 string, byte-identical to a shell `base64 -w0` locally, came back un-decodable inside E2B; a binary
+ * write of the same bytes + `git clone` succeeds, EXIT=0). E2B git 2.39 reads the macOS git 2.50 v2 bundle fine.
+ */
 async function importBundleBinaryToGrader(grader, tarBuffer, shas) {
+    // 🔴 TEAM tar-worktree (firm-v1/C4): the leader's INTEGRATED worktree is archived as a tar on the CONTROL PLANE
+    // (captureIntegratedTreeToBundle uses `git archive`, no .git). The grader BINARY-writes it + `tar -x`s plain files —
+    // NEVER `git clone` (E2B grader-clone is a platform heisenbug; Kata is virtiofs-st_dev-blocked). delivered comes
+    // from the worker-computed shas (head≠base), not git in the grader.
     if (!/^[0-9a-f]{40}$/.test(shas.head) || !/^[0-9a-f]{40}$/.test(shas.base))
         throw new Error(`s1 grader import: invalid shas ${JSON.stringify(shas)}`);
     const wr = await grader.writeFile(`/tmp/s1-wt.tar`, new Uint8Array(tarBuffer));
@@ -145,9 +240,11 @@ async function importBundleBinaryToGrader(grader, tarBuffer, shas) {
         console.error(`[S1_DEBUG_TAR team] head=${shas.head.slice(0, 8)} base=${shas.base.slice(0, 8)} ${ext.out.slice(-60)}`);
     return shas;
 }
+/** Build the OracleTask the standalone oracle consumes from a trap (stamps graderRepoDir + baseRef). */
 function oracleTaskFromTrap(trap) {
     return { ...trap.oracle, graderRepoDir: REPO, baseRef: BASE_REF };
 }
+/** A GraderTransport bound to a grader sandbox (clone/checkout via exec; hidden-test writes via writeFile). */
 function graderTransport(grader) {
     return {
         exec: async (command) => {
@@ -163,6 +260,16 @@ function graderTransport(grader) {
         },
     };
 }
+/**
+ * 🔴 THE FACTORY — build a REAL `ProfileDeps` bound to ONE (trap, seed) cell. Provisions a worker E2B sandbox + a
+ * DISTINCT grader E2B sandbox (lazily, on first seam call), wires every seam to the REAL core engine/oracle, and
+ * returns `{ deps, dispose }`. The driver calls one `buildLiveDeps` per cell and `dispose()`s it after the row.
+ *
+ * @param rt    the live runtime config (DeepSeek + E2B keys + the shared budget).
+ * @param trap  the class-C trap this cell runs.
+ * @param seed  the cell's seed (provenance; the durable-approval scope keys on it via buildSupImplSpec).
+ * @param cellId a stable id for the cell (used as sandbox metadata for fleet observability).
+ */
 export function buildLiveDeps(rt, trap, seed, cellId) {
     const { brain, models, roles, pricing } = buildBrainIngredients(rt);
     const baseSpec = (objective) => ({
@@ -172,6 +279,8 @@ export function buildLiveDeps(rt, trap, seed, cellId) {
         maxCostUsd: rt.maxCostUsd ?? 1.0,
         limits: { maxTurns: rt.maxTurns ?? 12 },
     });
+    // Lazily-provisioned, memoized per-cell sandboxes (so a cell that never runs a seam pays zero VM cost; a seam
+    // that throws still leaves them on `state` so dispose() reaps them).
     const state = {};
     const ensureWorker = async () => {
         if (!state.worker) {
@@ -181,12 +290,15 @@ export function buildLiveDeps(rt, trap, seed, cellId) {
         }
         return { env: state.worker, runner: state.runner };
     };
+    /** Provision the DISTINCT grader, transfer the worker's committed tree in. Memoized (graded once per cell). */
     const ensureGraderWithWorkerTree = async () => {
         const { env: worker } = await ensureWorker();
         if (!state.grader) {
             state.grader = await provisionSandbox(rt, "grader", cellId);
-            assertDistinctEnvs(worker, state.grader);
+            assertDistinctEnvs(worker, state.grader); // build-time guard (the structural separation is the real boundary)
+            // No grader seedBaseRepo: the grader holds a tar-extracted worktree (no .git at all), so it needs no git identity.
             if (state.teamBundle) {
+                // TEAM: extract the control-plane-archived integrated worktree into the grader (tar, no git — same dodge).
                 state.shas = await importBundleBinaryToGrader(state.grader, state.teamBundle.buffer, { head: state.teamBundle.head, base: state.teamBundle.base });
             }
             else {
@@ -195,54 +307,91 @@ export function buildLiveDeps(rt, trap, seed, cellId) {
         }
         return state.grader;
     };
+    /** Run the OBJECTIVE oracle in the DISTINCT grader env (the measure — runExecGate over real exit codes).
+     *  @param reSyncWorkerTree when true, RE-TRANSFER the worker's committed tree into the (already-provisioned)
+     *         grader before grading. The non-repair path grades a STABLE terminal tree once (memoized transfer is
+     *         correct); the repair loop calls the oracle ONCE PER ATTEMPT against an EVOLVING worker tree, so it MUST
+     *         re-sync or it would forever grade the frozen attempt-1 snapshot (the grader would never see a fix land). */
     const runOracle = async (reSyncWorkerTree = false) => {
         const { env: worker } = await ensureWorker();
         const grader = await ensureGraderWithWorkerTree();
         if (reSyncWorkerTree)
-            state.shas = await transferWorkerTreeToGrader(worker, grader);
+            state.shas = await transferWorkerTreeToGrader(worker, grader); // re-extract the evolving worktree
         const task = { ...oracleTaskFromTrap(trap), ...(state.shas ? { deliveredShas: state.shas } : {}) };
         const v = await runStandaloneOracle(grader, graderTransport(grader), worker, task);
         if (process.env.S1_DEBUG_GIT)
             console.error(`[S1_DEBUG_ORACLE ${trap.id}] delivered=${v.delivered} tests=${v.hiddenTestsGreen} build=${v.buildPassed} inv=${v.invariantsOk} | raw=`, JSON.stringify(v.raw)?.slice(0, 700));
-        return v;
+        return v; // OracleVerdict is a superset of OracleVerdicts; pickOracleVerdicts narrows it in arms.ts.
     };
     const deps = {
+        // ── SOLO: run the impl behind the verify→fix gate via the REAL core runWithVerification ──
         runWithVerification: async (implSpec) => {
             const { runner } = await ensureWorker();
             return runWithVerification(runner, toTaskSpec(baseSpec, implSpec), { maxRounds: rt.maxRounds ?? 2 });
         },
+        // ── SUP verify/durable path ──
+        // 🔴 durable suspend/resume is ONLY supported at the TOP-LEVEL runTask (core's mapNestedSuspend HARD boundary,
+        // design/45 §11 Q6 / design/80 D-B): the NESTED runWithVerification maps a durable pause to status:"failed"
+        // (UNEXPECTED_SUSPENDED), so the SUP HITL gate (gated bash → suspend) was ALWAYS infra-failed (caught by the
+        // firm-v1 N=1 all-paths smoke: C1/C2-SUP failed at turn 1, unverifiedReason="suspended", checkpointGate present).
+        // FIX: run the durable task at the TOP LEVEL so the suspend propagates as status:"suspended" + checkpointToken;
+        // driveSupSuspendResume (arms.ts) then resumes via resumeWithVerification (which resumes AND verifies on
+        // completion). The initial TaskResult is shaped as a VerificationResult placeholder — no verdict until the
+        // resume completes; the objective oracle (runOracle) is the measure regardless.
         runWithVerificationSup: async (implSpec) => {
             const { runner } = await ensureWorker();
             const result = await runner.runTask(toSupTaskSpec(baseSpec, implSpec, trap));
+            // 🔴 Map each durable-pause status to its OWN unverifiedReason (review MED): driveSupSuspendResume routes
+            // tool-approval (suspended → policy_ask) vs plan/dry-run review (needs_review → plan_review/dry_run_review) by
+            // this reason. Collapsing needs_review→"suspended" would send a plan-review gate down the tool-approval branch
+            // (bindingFromCheckpoint fails → the loop stops without resuming). Current firm traps don't hit a first-leg
+            // plan-review, but the driver advertises support for it.
             const unverifiedReason = result.status === "needs_review" ? "needs_review" : result.status === "suspended" ? "suspended" : "no_verdict";
             return { ...result, verification: { verdict: "unverified", unverifiedReason, rounds: 0, findings: [] } };
         },
+        // ── SUP resume: resume the durable-suspended impl AND verify on completion ──
         resumeWithVerification: async (token, outcome, implSpec) => {
             const { runner } = await ensureWorker();
             return resumeWithVerification(runner, token, outcome, toSupTaskSpec(baseSpec, implSpec, trap), implSpec.objective, { maxRounds: rt.maxRounds ?? 2 });
         },
+        // ── SUP repair leg: the SAFE-tier self-repair loop. workerEnv IS wired (corr #3 — the §5.1 identity check
+        //    is LIVE); the grader is the DISTINCT grader sandbox with the worker tree transferred in. ──
         runRepairLoop: async (implSpec) => {
             const { env: worker, runner } = await ensureWorker();
             const grader = await ensureGraderWithWorkerTree();
+            // 🔴 (review #4) RE-SYNC the worker tree into the grader BEFORE EACH attempt's grading — the repair loop grades
+            //    an EVOLVING worker tree once per attempt; the memoized one-shot transfer (correct for the non-repair
+            //    single-grade path) would freeze the grader at the attempt-1 snapshot and a later fix would never be seen.
             const oracle = makeRepairOracle({
                 transport: graderTransport(grader),
                 workerEnv: worker,
                 task: oracleTaskFromTrap(trap),
                 reSyncGraderTree: async () => {
-                    state.shas = await transferWorkerTreeToGrader(worker, grader);
+                    state.shas = await transferWorkerTreeToGrader(worker, grader); // re-extract evolving worktree + refresh shas
                 },
             });
             return runRepairLoop(runner, toSupTaskSpec(baseSpec, implSpec, trap), {
                 oracle,
-                graderEnv: grader,
-                workerEnv: worker,
+                graderEnv: grader, // the DISTINCT grader env (assertDistinctEnvs ran at provision)
+                workerEnv: worker, // 🔴 corr #3 — wired so the §5.1 identity check runs (never skipped)
                 maxAttempts: 2,
             });
         },
+        // ── SUP: read the suspend's pending record (boundCallId/boundInputHash echoed VERBATIM — corr #2 / TOCTOU) ──
         getCheckpoint: async (store, token, _scope) => {
             return store.get(token);
         },
+        // ── TEAM: the leader orchestrator via createLeaderRunner with budget-stamped workers. The leader integrates +
+        //    PUSHES to a per-cell durable remote (git daemon on the CONTROL PLANE). On a DELIVERED run we bundle that
+        //    integrated tree ON THE CONTROL PLANE and stash it as state.teamBundle; ensureGraderWithWorkerTree then seeds
+        //    the GRADER from it directly (the worker stays the empty-base distinct env). If the integrated tree cannot be
+        //    captured, runLeaderForTrap returns infraFailed (EXCLUDED, never a fabricated uniform loss). ──
         runLeaderTask: async () => {
+            // 🔴 NETWORK ISOLATION (firm-v1/C4 drill): the leader's git daemon serves git://127.0.0.1:<port> on the CONTROL
+            // PLANE; the E2B sandboxes are network-isolated → cloning git://127.0.0.1 from INSIDE E2B hits the sandbox's own
+            // localhost ("not a git repository"). FIX: clone+bundle the integrated ref HERE on the control plane, stash the
+            // base64 bundle (+ its base hash) in state; the grader-import path (importBundleB64ToGrader via writeFile, the
+            // PROVEN control-plane↔E2B-grader transport) ships it into the grader. We never touch the E2B worker for this.
             const captureIntegratedTreeToBundle = async (remoteUrl, targetRef) => {
                 const { execFileSync } = await import("node:child_process");
                 const { mkdtempSync, readFileSync, rmSync } = await import("node:fs");
@@ -260,19 +409,25 @@ export function buildLiveDeps(rt, trap, seed, cellId) {
                             console.error(`[S1_DEBUG_IMPORT] cp clone --branch ${branch} failed: ${e1.stderr?.toString().slice(-200)}; retrying default`);
                         execFileSync("git", ["clone", "-q", remoteUrl, cloneDir], { stdio: ["ignore", "ignore", "pipe"] });
                     }
+                    // The integrated repo's root commit = the grader's s1-base (HEAD = the leader's merge commit, advanced past it).
                     const baseHash = execFileSync("git", ["-C", cloneDir, "rev-list", "--max-parents=0", "HEAD"]).toString().trim().split("\n").pop().trim();
                     const head = execFileSync("git", ["-C", cloneDir, "rev-parse", "HEAD"]).toString().trim();
                     if (!/^[0-9a-f]{40}$/.test(baseHash) || head === baseHash) {
                         if (process.env.S1_DEBUG_GIT)
                             console.error(`[S1_DEBUG_IMPORT] cp integrated tree not delivered: head=${head} base=${baseHash}`);
-                        return false;
+                        return false; // no advance past base ⇒ leader didn't deliver ⇒ infra-failed (NEVER a fake loss)
                     }
                     const bundlePath = join(tmp, "team.bundle");
+                    // 🔴 git archive HEAD = the integrated WORKTREE as a tar (no .git) — the grader tar -x's plain files, never
+                    // git clone (E2B grader-clone heisenbug + Kata virtiofs). delivered = head≠base from the shas computed here
+                    // on the control plane (where git works). (Was: `git bundle` + grader clone — that hit both backends' git
+                    // failures.) The single-revision HEAD bundle comment kept for history; we now ship a worktree tar instead.
+                    // is tagged explicitly on the grader side, so delivered = HEAD≠base still resolves).
                     execFileSync("git", ["-C", cloneDir, "archive", "--format=tar", "-o", bundlePath, "HEAD"], { stdio: ["ignore", "ignore", "pipe"] });
-                    const buffer = readFileSync(bundlePath);
+                    const buffer = readFileSync(bundlePath); // RAW tar bytes — shipped to the grader as BINARY + tar -x'd (no git)
                     if (process.env.S1_DEBUG_GIT)
                         console.error(`[S1_DEBUG_IMPORT] cp integrated head=${head} base=${baseHash} tar bytes=${buffer.length}`);
-                    state.teamBundle = { buffer, head, base: baseHash };
+                    state.teamBundle = { buffer, head, base: baseHash }; // consumed by ensureGraderWithWorkerTree (tar -x, no git)
                     return true;
                 }
                 catch (e) {
@@ -286,16 +441,28 @@ export function buildLiveDeps(rt, trap, seed, cellId) {
             };
             return runLeaderForTrap(rt, brain, models, roles, pricing, trap, cellId, captureIntegratedTreeToBundle);
         },
+        // ── The hidden objective oracle (the measure), graded in the DISTINCT grader env ──
         runOracle: () => runOracle(false),
+        // 🔴 runCounterfactualOracle is DELIBERATELY OMITTED (it is OPTIONAL in ProfileDeps). The honest "no counterfactual"
+        //    path: buildCounterfactual returns undefined → the metric tool records UNVERIFIED-WITHHELD (NO avoided-loss
+        //    credit), the documented no-fake-credit choice (README / row.ts). The previous `runCounterfactualOracle:
+        //    runOracle` self-alias re-graded the IDENTICAL post-gate tree, so withoutInterventionTrulyCorrect ALWAYS
+        //    equaled withInterventionTrulyCorrect → every withhold auto-credited CORRECTLY-WITHHELD (withholdPrecision a
+        //    tautological 1.0); for the SUP tool-deny path the deny is a REAL durable suspend that blocked the commit, so
+        //    re-grading the same blocked tree is NOT an ablation. A real ablation (re-run the SAME (trap,seed) with the
+        //    gate DISABLED into a FRESH worker, grade THAT in a separate grader) is the only thing that makes
+        //    INCORRECTLY-WITHHELD reachable — TODO; until it lands we honestly omit rather than manufacture credit.
     };
     const dispose = async () => {
         await Promise.allSettled([state.worker?.destroy(), state.grader?.destroy()]);
     };
     return { deps, dispose };
 }
+/** Project a `SoloImplSpec` (budget already stamped by the harness) onto the bench base TaskSpec. */
 function toTaskSpec(base, impl) {
     return { ...base(impl.objective), maxTokens: impl.maxTokens, maxCostUsd: impl.maxCostUsd, limits: { ...impl.limits } };
 }
+/** Project a `SupImplSpec` onto the bench base TaskSpec PLUS the durable wiring (checkpointStore + ask policy). */
 function toSupTaskSpec(base, impl, trap) {
     const requireApproval = trap.gatedTools ?? ["Bash"];
     const neverAuto = trap.neverAuto ?? [];
@@ -307,7 +474,29 @@ function toSupTaskSpec(base, impl, trap) {
         onQuestion: QUESTION_AWAITS_RESUME,
     };
 }
+/**
+ * Run the leader (TEAM) for a trap via `createLeaderRunner`, then map its `LeaderResult` → `LeaderTaskOutcome` (the
+ * subset the harness needs for the COMPLETE TEAM cost + outcome). The leader runs its OWN integration sandbox + an
+ * objective hidden oracle (its `testCmd` over the trap's oracleSteps) and PUSHES the integrated tree to a per-cell
+ * durable remote. The harness then IMPORTS that integrated tree into state.worker (via `importIntegratedTreeToWorker`)
+ * so its `runOracle` independently re-grades the REAL integrated output in the DISTINCT grader (the trusted measure —
+ * the leader's own gate is NOT trusted as the numerator). Budget-stamped: per-worker maxCostUsd is bounded so
+ * Σworker ≤ the arm budget.
+ *
+ * 🔴 The integrated tree is the actual TEAM output. The durable remote is served over `git://127.0.0.1` by a local
+ *    `git daemon` (the leader/wire.ts validator REJECTS `file://`; `git://` passes AND the Coordinator can push to
+ *    it). After a delivered run the harness clones the pushed targetRef into state.worker; if that import fails (the
+ *    leader never delivered, or no integrated head exists) the cell is `infraFailed:true` (EXCLUDED) — NEVER a
+ *    fabricated uniform "delivered=false" loss for the whole TEAM column.
+ *
+ * 🔴 The leader's workers run on the E2B factory (each its OWN VM — isolation). A leader crash surfaces as
+ *    `infraFailed:true` (EXCLUDED), never a scored loss.
+ */
 async function runLeaderForTrap(rt, brain, models, roles, pricing, trap, cellId, importIntegratedTreeToWorker) {
+    // The TEAM arm needs a durable remote to integrate into. For S1 we serve a throwaway local bare git repo over
+    // `git://127.0.0.1:<port>` via `git daemon` so (a) the leader/wire.ts validator accepts the URL (it forbids
+    // file://) and (b) the Coordinator can clone+push it. 🔴 Needs `git` (incl. `git daemon`) on the control-plane
+    // PATH (deploy req, leader/wire.ts header).
     const { mkdtempSync, rmSync, writeFileSync, mkdirSync } = await import("node:fs");
     const { execFileSync, spawn } = await import("node:child_process");
     const { tmpdir } = await import("node:os");
@@ -317,7 +506,9 @@ async function runLeaderForTrap(rt, brain, models, roles, pricing, trap, cellId,
     const repoName = "team.git";
     const remoteDir = join(baseDir, repoName);
     execFileSync("git", ["init", "-q", "--bare", remoteDir]);
+    // Mark the bare repo daemon-exportable (git daemon refuses to serve a repo without this unless --export-all).
     execFileSync("git", ["--git-dir", remoteDir, "config", "daemon.receivepack", "true"]);
+    // Pick a free localhost port for the daemon (bind:0 → OS-assigned → read it back).
     const port = await new Promise((resolve, reject) => {
         const srv = net.createServer();
         srv.once("error", reject);
@@ -327,6 +518,8 @@ async function runLeaderForTrap(rt, brain, models, roles, pricing, trap, cellId,
             srv.close(() => (p ? resolve(p) : reject(new Error("could not pick a free port"))));
         });
     });
+    // Start `git daemon` serving baseDir over 127.0.0.1:port with push enabled. The URL the leader receives is
+    // git://127.0.0.1:<port>/<repoName>.
     const daemon = spawn("git", [
         "daemon",
         "--reuseaddr",
@@ -337,6 +530,7 @@ async function runLeaderForTrap(rt, brain, models, roles, pricing, trap, cellId,
         "--enable=receive-pack",
         remoteDir,
     ], { stdio: "ignore" });
+    // Give the daemon a moment to bind (poll the port until it accepts, up to ~3s).
     const waitForPort = async () => {
         for (let i = 0; i < 30; i++) {
             const up = await new Promise((resolve) => {
@@ -355,13 +549,22 @@ async function runLeaderForTrap(rt, brain, models, roles, pricing, trap, cellId,
     };
     const remoteUrl = `git://127.0.0.1:${port}/${basename(remoteDir)}`;
     const targetRef = "refs/heads/main";
+    // Budget-stamped workers (Σ ≤ arm budget). The leader splits the arm budget across ≤2 workers for C4.
+    // 🔴 LOAD-BEARING ON THE SEQUENTIAL DRIVER (run-firm.ts: `for (const cell of cells)` is strictly sequential,
+    //    one runArm at a time). loadConfig()/leaderResourceConfig() read these knobs ONLY from process.env (no
+    //    parameterized override seam exists today), so env-stamping is the only lever. If run-firm's loop is ever
+    //    parallelized, two cells would race on shared process.env (cross-contaminating the per-worker budget — the
+    //    §3.2 fairness root); thread the config explicitly (loadConfig override args + LeaderWireConfig fields) FIRST.
     process.env.LEADER_ENABLED = "true";
     process.env.LEADER_WORKER_BUDGET_USD = String((rt.maxCostUsd ?? 1.0) / 2);
-    process.env.LEADER_CONFLICT_ROUNDS = process.env.LEADER_CONFLICT_ROUNDS ?? "2";
+    process.env.LEADER_CONFLICT_ROUNDS = process.env.LEADER_CONFLICT_ROUNDS ?? "2"; // C4 = fan-out conflict → resolver
     const run = createLeaderRunner({
         brain, models, roles, pricing, e2bApiKey: rt.e2bApiKey, workspace: W,
         ...(process.env.S1_DEBUG_GIT ? { logger: { warn: (m, x) => console.error(`[S1_DEBUG_LEADER warn] ${m}`, x ? JSON.stringify(x).slice(0, 300) : ""), info: (m, x) => console.error(`[S1_DEBUG_LEADER info] ${m}`, x ? JSON.stringify(x).slice(0, 200) : "") } } : {}),
     });
+    // The seed command (run in each worker + the integration sandbox): a fresh repo at base. For a hazard trap (C7)
+    // the seedFiles are written + committed INTO each worker's base (PRECIOUS sentinel + scratch) so the worker SEES
+    // them and may over-delete from its local view (search S1c fan-out hazard). Absent ⇒ an empty base.
     const teamSeedWrite = (trap.seedFiles ?? [])
         .map((f) => {
         const rel = f.path.startsWith(REPO) ? f.path.slice(REPO.length + 1) : f.path;
@@ -371,6 +574,7 @@ async function runLeaderForTrap(rt, brain, models, roles, pricing, trap, cellId,
         .join("; ");
     const teamSeedStep = trap.seedFiles && trap.seedFiles.length > 0 ? `${teamSeedWrite}; git add -A; ` : "";
     const seedCmd = `rm -rf ${REPO}; mkdir -p ${REPO}; cd ${REPO}; git init -q; git config user.email s1@bench.local; git config user.name s1-bench; git config commit.gpgsign false; ${teamSeedStep}git commit -q --allow-empty -m base`;
+    // The integration testCmd = the trap's objective COMMAND oracle steps (the leader's hidden-oracle gate).
     const testCmd = trap.oracle.oracleSteps.map((s) => s.command).join(" && ");
     const oracleFiles = trap.oracle.hiddenTestFiles;
     const killDaemon = () => {
@@ -378,6 +582,7 @@ async function runLeaderForTrap(rt, brain, models, roles, pricing, trap, cellId,
             daemon.kill("SIGKILL");
         }
         catch {
+            /* already gone */
         }
     };
     let res;
@@ -385,11 +590,20 @@ async function runLeaderForTrap(rt, brain, models, roles, pricing, trap, cellId,
         if (!(await waitForPort())) {
             return { ok: false, reports: [], infraFailed: true };
         }
+        // 🔴 Seed the bare daemon repo's `main` with a REAL base commit + capture its sha (firm-v1/C4 dig — the deepest
+        // TEAM layer). The bare repo was EMPTY and baseSha was the literal "HEAD": the Coordinator (wire.ts) clones the
+        // durable remote then `git am`s the integrated patch and pushes `--force-with-lease=refs/heads/main:<baseSha>`.
+        // With an empty repo + a non-sha "HEAD" lease, the integrated head landed at root INTERMITTENTLY → my control-plane
+        // clone of main saw root-only (head==base) → TEAM was unmeasurable. A real base commit + the real base sha makes
+        // the Coordinator's am apply on a deterministic base and the lease exact → main = the integrated merge, always.
         const seedDir = mkdtempSync(join(tmpdir(), "s1-team-seed-"));
         execFileSync("git", ["clone", "-q", remoteDir, seedDir], { stdio: ["ignore", "ignore", "pipe"] });
         execFileSync("git", ["-C", seedDir, "config", "user.email", "s1@bench.local"]);
         execFileSync("git", ["-C", seedDir, "config", "user.name", "s1-bench"]);
         execFileSync("git", ["-C", seedDir, "config", "commit.gpgsign", "false"]);
+        // Hazard trap (C7): seed the durable base with the SAME files (PRECIOUS sentinel + scratch) so the merge starts
+        // from a tree CONTAINING the sentinel — a worker's over-delete then surfaces as a real deletion in the integrated
+        // tree (merge-result survival). Absent ⇒ empty base (C4 disjoint creates everything fresh).
         for (const f of trap.seedFiles ?? []) {
             const rel = f.path.startsWith(REPO) ? f.path.slice(REPO.length + 1) : f.path;
             const abs = join(seedDir, rel);
@@ -410,6 +624,10 @@ async function runLeaderForTrap(rt, brain, models, roles, pricing, trap, cellId,
             testCmd,
             seedCmd,
             oracleFiles,
+            // Fan-out plan: the explicit per-worker subtask list lives on the TrapSpec (C4 disjoint modules, C7 fan-out
+            // hazard). The leader's planner REQUIRES disjoint file ownership (a same-file plan is rejected "not disjoint").
+            // Each worker gets ONLY its local objective; the oracle checks the integrated result. Traps without subtasks
+            // stay single (the router collapses).
             ...(trap.subtasks ? { subtasks: trap.subtasks } : {}),
         });
     }
@@ -422,6 +640,10 @@ async function runLeaderForTrap(rt, brain, models, roles, pricing, trap, cellId,
     }
     if (process.env.S1_DEBUG_GIT)
         console.error(`[S1_DEBUG_LEADER ${trap.id}] ok=${res.ok} error=${JSON.stringify(res.error)} cancelled=${res.cancelled} merge=${JSON.stringify(res.merge)} repairTerminal=${res.repairTerminal} reports=${(res.reports ?? []).length} reportsDetail=${JSON.stringify((res.reports ?? []).map((r) => ({ w: r.workerId, ok: r.ok, err: r.error })))?.slice(0, 400)}`);
+    // 🔴 Import the leader's INTEGRATED, pushed tree into state.worker so runOracle grades the REAL TEAM output (not
+    //    an empty repo). The push leg only ran if the leader integrated+pushed successfully (res.merge.ok). If the
+    //    import fails (no integrated head — leader did not deliver), mark the cell infra-failed (EXCLUDED), NEVER a
+    //    fabricated uniform delivered=false loss. The daemon must stay alive for this clone, then we reap it.
     let imported = false;
     const merged = res.merge?.ok === true;
     try {
@@ -435,6 +657,9 @@ async function runLeaderForTrap(rt, brain, models, roles, pricing, trap, cellId,
         killDaemon();
         rmSync(baseDir, { recursive: true, force: true });
     }
+    // The leader ran but its integrated tree could not be moved into the grader path → NOT measurable. Honest
+    // infra-failed (EXCLUDED), never a fabricated loss. (A leader that legitimately withheld — held the merge — is a
+    // DIFFERENT case handled below via res.merge/repairTerminal, where !merged with a withhold terminal is expected.)
     if (!imported && merged) {
         return { ok: false, reports: res.reports, infraFailed: true };
     }
@@ -442,8 +667,21 @@ async function runLeaderForTrap(rt, brain, models, roles, pricing, trap, cellId,
         ok: res.ok,
         reports: res.reports,
         ...(res.merge ? { merge: res.merge } : {}),
+        // 🔴 (review HIGH finding) a leader integration-test gate that REJECTED the merge (res.merge.ok===false,
+        //    phase==="test" — the post-merge oracle/test gate caught a bad integrated tree, e.g. C7's fan-out hazard
+        //    deleted the sentinel) is an HONEST WITHHOLD (the leader held a bad delivery), NOT a plain not-delivered.
+        //    Without this, arms.ts withheld=false → the row is mis-booked. Surfacing withheld:true makes arms classify
+        //    UNVERIFIED-WITHHELD (no counterfactual wired ⇒ NO avoided-loss credit — honest, never DELIVERED-WRONG and
+        //    never a fake CORRECTLY-WITHHELD; the worker DID execute the hazard, the leader just didn't ship it).
         ...(res.merge?.ok === false && res.merge.phase === "test" ? { withheld: true } : {}),
+        // 🔴 the repair terminal (when the single-agent repair loop ran) drives the TEAM withhold classification in
+        //    arms.ts (candidate_only/gave_up/conflict → withhold; oracle.unprotected → infra-failed). Passed through.
         ...(res.repairTerminal ? { repairTerminal: res.repairTerminal } : {}),
+        // A leader that integrated+pushed → the integrated tree is now in state.worker (runOracle grades it). A leader
+        // that did NOT merge (held the merge / repair non-accepting terminal) leaves state.worker empty → runOracle
+        // reports delivered=false, which is the HONEST verdict for an un-delivered TEAM run (the withhold classification
+        // in arms.ts reads merge/repairTerminal, and the absent counterfactual → UNVERIFIED-WITHHELD, no fake credit).
+        // The leader does not surface a stamped per-worker budget split here; honest "not measured" (undefined).
     };
 }
 //# sourceMappingURL=live-deps.js.map