@sema-agent/server 1.322.0 → 2.0.0

package/dist/leader/repair-oracle.d.ts

@@ -1,4 +1,33 @@
+/**
+ * The PROFILE-injected `RepairOracle` closure for the leader's single-agent self-repair loop
+ * (`runRepairLoop`, core design/78 / D1). See `docs/LEADER-REPAIRLOOP-INTEGRATION.md` (§3.1 + the authoritative
+ * §10 corrected layer). The closure GRADES a worker's candidate in an ISOLATED grader env (the reused
+ * integration sandbox, distinct from the worker env) and maps the result to a core `OracleResult`. core only
+ * fixes the `OracleResult` shape + the read-only/identity contract; the composition lives HERE so the core type
+ * never grows a discriminated union.
+ *
+ * Hardened by the adversarial round (§10):
+ *  - §10.1 HERMETIC grade: the grader tree is reset to a clean base (`git reset --hard <integBase> && git clean
+ *    -fdx`) BEFORE applying the worker's LATEST full `base..HEAD` diff each call — so a 2nd/3rd attempt never
+ *    applies cumulatively onto an already-applied tree (the BROKEN finding). The diff is recomputed fresh every
+ *    call (never a stale cached diff — verify.ts:328 BUG5).
+ *  - flaky: the gate is re-isolated K times on a green-looking verdict; a disagreement is reported `flaky:true`
+ *    and core's `terminalForTier` provably refuses to project it to a passing terminal.
+ *  - §10.9 DE-CORRELATION: the L3 judge can only contribute a CLEARING tier when the verifier model is PROVABLY
+ *    distinct from the generator — and the closure CANNOT resolve roles→models itself (that happens inside
+ *    `Runner.runTask` after the closure returns), so the WIRE resolves both ids and passes them in; the closure
+ *    downgrades to `l3_judge_advisory` when they are equal. v1 ships L3 OFF (`cfg.l3` unset) → L2 `trusted_hidden`
+ *    is the sole clearer and `terminalForTier` caps every PASS at `candidate_only`. Wiring the actual
+ *    `verifyCompleted` invocation is a future enable: it needs the worker's `TaskResult` threaded to the oracle
+ *    (core passes only the report `evidence` today), so it is deliberately NOT invoked here.
+ *
+ * The grader topology (graderEnv = the reused integration sandbox, oracle seeded ONLY there, worker env distinct)
+ * means the worker can never read the oracle; for SAFE-tier `candidate_only` the bare `graderEnv !== workerEnv`
+ * identity check is sufficient, so the caller OMITS `immutableOraclePaths` (the structural bash write-probe is
+ * vacuous across distinct sandboxes and matters only for the mandate-OFF auto-accept path — §10.2).
+ */
 import { type ExecStep, type OracleTier, type RepairOracle } from "@sema-agent/core";
+/** A worker's latest diff, pulled fresh from ITS env (the same `PullDiffResult` shape as `diffout.ts`). */
 export type WorkerDiff = {
     ok: true;
     patch: string;
@@ -7,22 +36,49 @@ export type WorkerDiff = {
     error: string;
 };
 export interface RepairOracleCfg {
+    /** Pull the worker's LATEST full `base..HEAD` diff from its own env (recomputed every grade — §10.1). */
     pullWorkerDiff: () => Promise<WorkerDiff>;
+    /** Write a file into the GRADER env (the wire binds this to the integration sandbox's `writeFile`). */
     graderWriteFile: (path: string, content: string) => Promise<void>;
+    /** Repo dir inside the grader (e.g. `/repo`). */
     graderRepoDir: string;
+    /** The grader's CLEAN base rev — `git rev-parse HEAD` taken right after seed + oracle-inject (`merge.ts:137`
+     *  pattern). The §10.1 hermetic reset target; the grade always runs base→latest, never cumulative. */
     integBase: string;
+    /** TRUSTED, spec-derived oracle steps (the hidden-oracle `testCmd` [+ `measureCmd`]) run in the grader. MUST
+     *  NOT be worker-authored (the security contract of `runExecGate` — exec-gate.ts header). */
     oracleSteps: ExecStep[];
+    /** The tier to assign on a PASS (control-plane data, never agent-visible): `trusted_hidden` iff the steps run
+     *  an oracleFiles-backed hidden held-out oracle; `property_harness_weak` for a compile-only gate; `none` if
+     *  there is no usable oracle. */
     passTier: OracleTier;
+    /** K re-isolations to settle a flaky verdict (`LEADER_ORACLE_FLAKY_K`, default 2). */
     flakyK?: number;
+    /** Optional L3 de-correlation gate (§10.9). When the leader runs a distinct verifier model, the wire resolves
+     *  both ids and passes them; a self-certifying pair (`verifierModelId === generatorModelId`) downgrades a PASS
+     *  to `l3_judge_advisory` (advisory never clears). Unset in v1 (L3 off → the L2 tier stands). */
     l3?: {
         generatorModelId: string;
         verifierModelId: string;
     };
+    /** fork1.2 — paths the candidate patch must NOT touch (the seeded hidden-oracle / test paths).
+     *  The §10.2 factory lane OMITs the engine's path-level probe, so a patch that EDITS the grader's oracle could
+     *  tamper with the grade and get rubber-stamped as `candidate_only`. A patch touching one of these is REFUSED
+     *  as `needs_human_oracle` (surfaced for a human, never a silent candidate). Matched by exact path or subtree. */
     oraclePaths?: string[];
+    /** 🔴 council 2026-06-17 — the seeded hidden-oracle files (path + content). The hermetic `git clean -fdx`
+     *  DELETES them (they are untracked/ignored, not committed at `integBase`), so they MUST be RE-INJECTED after
+     *  the worker patch is applied — both to restore the oracle the `clean` wiped AND to overwrite any file the
+     *  patch placed at an oracle path (defence-in-depth with `oraclePaths`). Without this the gate runs against NO
+     *  oracle (or a worker-substituted one) and `trusted_hidden` is a false label. Empty when grading is a pure
+     *  inline `testCmd` with no seeded files (then there is nothing for `clean` to wipe). */
     oracleFiles?: Array<{
         path: string;
         content: string;
     }>;
+    /** fork2.2 — report the EXACT bytes that were graded (the diff + its hash) so the caller binds
+     *  the SURFACED candidate to the graded artifact (a human reviews the bytes that produced the verdict, not a
+     *  re-pulled diff that may differ). Isomorphic to core's boundInputHash: "grade/review the thing you ship". */
     onGraded?: (info: {
         diff: string;
         hash: string;
@@ -30,5 +86,10 @@ export interface RepairOracleCfg {
     }) => void;
     log?: (event: string, x?: Record<string, unknown>) => void;
 }
+/**
+ * Build the `RepairOracle` closure. The returned `(graderEnv, evidence) => OracleResult` is what the leader
+ * passes as `RepairLoopConfig.oracle`. `evidence` (the worker's report text) is intentionally unused — the
+ * closure recomputes the candidate diff from the worker env each call (§10.1).
+ */
 export declare function mkRepairOracle(cfg: RepairOracleCfg): RepairOracle;
 //# sourceMappingURL=repair-oracle.d.ts.map

package/dist/leader/repair-oracle.js

@@ -1,7 +1,38 @@
+/**
+ * The PROFILE-injected `RepairOracle` closure for the leader's single-agent self-repair loop
+ * (`runRepairLoop`, core design/78 / D1). See `docs/LEADER-REPAIRLOOP-INTEGRATION.md` (§3.1 + the authoritative
+ * §10 corrected layer). The closure GRADES a worker's candidate in an ISOLATED grader env (the reused
+ * integration sandbox, distinct from the worker env) and maps the result to a core `OracleResult`. core only
+ * fixes the `OracleResult` shape + the read-only/identity contract; the composition lives HERE so the core type
+ * never grows a discriminated union.
+ *
+ * Hardened by the adversarial round (§10):
+ *  - §10.1 HERMETIC grade: the grader tree is reset to a clean base (`git reset --hard <integBase> && git clean
+ *    -fdx`) BEFORE applying the worker's LATEST full `base..HEAD` diff each call — so a 2nd/3rd attempt never
+ *    applies cumulatively onto an already-applied tree (the BROKEN finding). The diff is recomputed fresh every
+ *    call (never a stale cached diff — verify.ts:328 BUG5).
+ *  - flaky: the gate is re-isolated K times on a green-looking verdict; a disagreement is reported `flaky:true`
+ *    and core's `terminalForTier` provably refuses to project it to a passing terminal.
+ *  - §10.9 DE-CORRELATION: the L3 judge can only contribute a CLEARING tier when the verifier model is PROVABLY
+ *    distinct from the generator — and the closure CANNOT resolve roles→models itself (that happens inside
+ *    `Runner.runTask` after the closure returns), so the WIRE resolves both ids and passes them in; the closure
+ *    downgrades to `l3_judge_advisory` when they are equal. v1 ships L3 OFF (`cfg.l3` unset) → L2 `trusted_hidden`
+ *    is the sole clearer and `terminalForTier` caps every PASS at `candidate_only`. Wiring the actual
+ *    `verifyCompleted` invocation is a future enable: it needs the worker's `TaskResult` threaded to the oracle
+ *    (core passes only the report `evidence` today), so it is deliberately NOT invoked here.
+ *
+ * The grader topology (graderEnv = the reused integration sandbox, oracle seeded ONLY there, worker env distinct)
+ * means the worker can never read the oracle; for SAFE-tier `candidate_only` the bare `graderEnv !== workerEnv`
+ * identity check is sufficient, so the caller OMITS `immutableOraclePaths` (the structural bash write-probe is
+ * vacuous across distinct sandboxes and matters only for the mandate-OFF auto-accept path — §10.2).
+ */
 import { runExecGate, } from "@sema-agent/core";
 import { createHash } from "node:crypto";
+/** Single-quote a string for safe interpolation into a shell command. */
 const sq = (s) => `'${s.replace(/'/g, "'\\''")}'`;
+/** A short, stable content hash for the stale-diff guard (fork2.1) + the graded-bytes binding (fork2.2). */
 const sha = (s) => createHash("sha256").update(s).digest("hex").slice(0, 16);
+/** Parse the changed file paths from a unified diff — the `diff --git a/X b/X` headers (both old + new path). */
 function changedFilesOf(patch) {
     const out = new Set();
     for (const m of patch.matchAll(/^diff --git a\/(.+?) b\/(.+)$/gm)) {
@@ -11,6 +42,8 @@ function changedFilesOf(patch) {
     return [...out];
 }
 const normP = (p) => p.replace(/^\.?\/+/, "").replace(/\/+$/, "");
+/** fork1.2 — the first changed file that touches a protected oracle path (exact, or a subtree either way), else
+ *  undefined. A patch that edits the grader's hidden-oracle/test path is refused (test-tampering guard). */
 function touchesOraclePath(changed, oraclePaths) {
     const ops = oraclePaths.map(normP).filter((p) => p !== "");
     for (const f of changed.map(normP)) {
@@ -21,23 +54,35 @@ function touchesOraclePath(changed, oraclePaths) {
     }
     return undefined;
 }
+/**
+ * Build the `RepairOracle` closure. The returned `(graderEnv, evidence) => OracleResult` is what the leader
+ * passes as `RepairLoopConfig.oracle`. `evidence` (the worker's report text) is intentionally unused — the
+ * closure recomputes the candidate diff from the worker env each call (§10.1).
+ */
 export function mkRepairOracle(cfg) {
     const repo = cfg.graderRepoDir;
     const K = Math.max(1, Math.floor(cfg.flakyK ?? 2));
-    let lastGradedHash;
+    let lastGradedHash; // fork2.1 stale-diff guard — per-loop state across the engine's attempts.
     return async (graderEnv, _evidence) => {
+        // §10.1 — materialize the worker's LATEST code in a CLEAN grader tree. Pull fresh (never a stale diff).
         const diff = await cfg.pullWorkerDiff();
         if (!diff.ok) {
             cfg.log?.("repair_oracle_pull_failed", { error: diff.error });
             return { tier: cfg.passTier, passed: false, flaky: false, retries: 0, trace: `pull worker diff failed: ${diff.error}` };
         }
         const diffHash = sha(diff.patch);
+        // fork1.2 — refuse a candidate that edits a seeded oracle/test path: applied into the grader it
+        // could tamper the very oracle that grades it. Surface as `needs_human_oracle` (tier "none" → terminalForTier),
+        // never a silent candidate_only. (The §10.2 factory lane OMITs the engine path-probe, so this is the fence.)
         const tampered = cfg.oraclePaths && cfg.oraclePaths.length > 0 ? touchesOraclePath(changedFilesOf(diff.patch), cfg.oraclePaths) : undefined;
         if (tampered) {
             cfg.log?.("repair_oracle_tampering_guard", { path: tampered });
             cfg.onGraded?.({ diff: diff.patch, hash: diffHash, passed: false });
             return { tier: "none", passed: false, flaky: false, retries: 0, trace: `candidate patch touches oracle/test path '${tampered}' — refusing to grade (fork1.2 test-tampering guard)` };
         }
+        // fork2.1 — a repair attempt that produced NO new diff (byte-identical to the prior graded one)
+        // made no progress → never grade stale bytes as a fresh PASS: report no-progress (the loop gives up rather
+        // than re-passing a stale artifact). With fork2.2 this guarantees the SURFACED candidate == the graded bytes.
         if (lastGradedHash !== undefined && diffHash === lastGradedHash) {
             cfg.log?.("repair_oracle_stale_diff", { hash: diffHash });
             cfg.onGraded?.({ diff: diff.patch, hash: diffHash, passed: false });
@@ -46,6 +91,8 @@ export function mkRepairOracle(cfg) {
         lastGradedHash = diffHash;
         const patchPath = `/tmp/candidate-${Date.now()}.patch`;
         await cfg.graderWriteFile(patchPath, diff.patch);
+        // Hermetic prep: reset the grader to its clean base, then apply the FULL base→latest diff. `--whitespace=nowarn`
+        // matches the merge path (merge.ts:144). A prep failure (e.g. an apply conflict) is a non-flaky failed grade.
         const prep = await runExecGate(graderEnv, [
             { command: `git -C ${sq(repo)} reset --hard ${sq(cfg.integBase)} && git -C ${sq(repo)} clean -fdx`, label: "grader-reset" },
             { command: `git -C ${sq(repo)} apply --whitespace=nowarn ${sq(patchPath)}`, label: "grader-apply" },
@@ -56,8 +103,15 @@ export function mkRepairOracle(cfg) {
             cfg.onGraded?.({ diff: diff.patch, hash: diffHash, passed: false });
             return { tier: cfg.passTier, passed: false, flaky: false, retries: 0, trace: `grader prep failed:\n${trace}` };
         }
+        // 🔴 council 2026-06-17 — the hermetic `clean -fdx` above DELETED the seeded hidden oracle (untracked/ignored,
+        // never committed at integBase). RE-INJECT it AFTER applying the worker patch, so (a) the gate runs against the
+        // REAL oracle the clean wiped (else `trusted_hidden` is a false label), and (b) any file the patch placed at an
+        // oracle path is OVERWRITTEN by the trusted content (defence-in-depth with the fork1.2 path guard above).
         for (const f of cfg.oracleFiles ?? [])
             await cfg.graderWriteFile(f.path, f.content);
+        // L2 mechanical gate (the trusted hidden oracle), re-isolated K times to settle flakiness. A clear FIRST
+        // failure short-circuits (no point re-running a definite fail); a green verdict is re-run to detect a flaky
+        // (nondeterministic) test — a disagreement is reported flaky and core refuses to project it to a pass.
         const verdicts = [];
         let lastTrace = "";
         for (let k = 0; k < K; k++) {
@@ -70,11 +124,15 @@ export function mkRepairOracle(cfg) {
         }
         const passed = verdicts.length > 0 && verdicts.every(Boolean);
         const flaky = new Set(verdicts).size > 1;
+        // §10.9 — a self-certifying verifier (no distinct model) cannot CLEAR: a PASS downgrades to advisory. v1 has
+        // `cfg.l3` unset (L3 off) → the L2 `passTier` stands and `terminalForTier` caps the PASS at candidate_only.
         let tier = cfg.passTier;
         if (cfg.l3 && passed && !flaky && cfg.l3.verifierModelId === cfg.l3.generatorModelId) {
             cfg.log?.("repair_oracle_l3_decorrelation_failed", { model: cfg.l3.generatorModelId });
             tier = "l3_judge_advisory";
         }
+        // fork2.2 — bind the EXACT graded bytes (the diff that produced this verdict) so the caller surfaces the
+        // candidate the human reviews == the bytes that were graded (not a later re-pull that may differ).
         cfg.onGraded?.({ diff: diff.patch, hash: diffHash, passed });
         cfg.log?.("repair_oracle_verdict", { tier, passed, flaky, retries: K });
         return { tier, passed, flaky, retries: K, ...(passed && !flaky ? {} : { trace: lastTrace || "oracle rejected the candidate" }) };

package/dist/leader/repair-wire.d.ts

@@ -1,30 +1,88 @@
+/**
+ * The WIRE that wraps core `runRepairLoop` onto the leader's single-agent path
+ * (`docs/LEADER-REPAIRLOOP-INTEGRATION.md` §3.3 + the authoritative §10 layer). It owns the three things the
+ * `RepairOracle` closure (`repair-oracle.ts`) and the core engine CANNOT resolve themselves:
+ *
+ *  1. **The grader handle (R1, §10.1)** — the reused integration sandbox's writeFile/exec + `integBase`, bound by
+ *     the caller (`attachRepairLoopDeps` is handed the integration env). The closure grades there; the worker env
+ *     stays distinct so the §5.1 identity check (`graderEnv !== workerEnv`) is LIVE.
+ *  2. **The worker diff source** — `pullWorkerDiff`, the same `pullDiff`/self-upload path the merge uses, so the
+ *     closure materializes the worker's LATEST committed `base..HEAD` diff every grade (§10.1; never a stale diff).
+ *  3. **De-correlation model ids (§10.9 mechanics)** — the closure receives NO model ids (roles→models resolve
+ *     INSIDE `Runner.runTask`, AFTER the closure returns), so the WIRE resolves `generatorModelId` +
+ *     `verifierModelId` from `cfg.roles`/`cfg.models` and passes them to `mkRepairOracle.l3`. v1 ships L3 OFF
+ *     (`cfg.l3` unset) → L2 `trusted_hidden` is the sole clearer; `terminalForTier` caps every PASS at
+ *     `candidate_only`.
+ *
+ * §10.2 — for v1 SAFE-tier `candidate_only` we OMIT `immutableOraclePaths` (the bare `graderEnv !== workerEnv`
+ * identity check suffices; the structural bash write-probe is vacuous across distinct sandboxes and matters only
+ * for the mandate-OFF auto-accept path). `workerEnv` IS passed so the identity check runs.
+ *
+ * §10.7 — the surfaced `candidatePatch.patch` is worker-authored code reaching a human-read HTTP body / durable-
+ * approval row, so it is DELIMITED (`delimitUntrusted(...)`); `reason` comes ONLY from the core-sanitized
+ * `RepairResult.verification.findings[0]`, never the raw oracle trace.
+ *
+ * §10.8 — `attachRepairLoopDeps(deps, integEnv, cfg)` is the SINGLE wire-call helper so `wire.ts` gains one line
+ * per integration-sandbox path instead of in-place edits to its dense provision spreads. Stage-2 calls it.
+ *
+ * Everything here is gated by the caller behind `LEADER_REPAIR_LOOP` (default OFF): when the dep is not attached
+ * the leader's single-agent paths are byte-identical to today.
+ */
 import { type Runner, type TaskSpec, type ExecutionEnv, type ExecStep, type OracleTier, type RepairResult, type RepairBundle, type RepairTerminal } from "@sema-agent/core";
 import { type WorkerDiff } from "./repair-oracle.js";
 import type { GraderHandle } from "./grader-env-factory.js";
 import type { LeaderDeps, ProvisionedWorker, SubtaskSpec } from "./leader.js";
 import type { WorkerReport } from "./fanout.js";
+/** The per-run inputs the leader's single-agent repair loop needs, resolved by the wire (§3.3). */
 export interface RepairWireCfg {
+    /** The CONCRETE core Runner that runs the solo worker's GENERATE/REPAIR turns. `runRepairLoop` requires the
+     *  real `Runner` (not the `RunnerLike` on `ProvisionedWorker`); the wire holds it (it builds the worker Runner). */
     runner: Runner;
+    /** The grader handle (R1: the reused integration sandbox) — writeFile/exec/repoDir/integBase bound by the wire. */
     grader: GraderHandle;
+    /** OPTIONAL solo worker execution env REF — passed as `runRepairLoop.workerEnv` so the §5.1 identity check is
+     *  LIVE. On the FACTORY lane (REMOTE_EXEC=e2b/k8s — the canary) the worker's RAW env is NOT surfaced (only
+     *  `fetchDiff`), so it is OMITTED: `runRepairLoop` then SKIPS the identity check (fires `onWarn` — fine).
+     *  Structural isolation is GUARANTEED regardless because the grader is a SEPARATE provisioned sandbox (a
+     *  distinct object / `sandboxId` from the worker by construction) — §10.2: the identity check is necessary-not-
+     *  sufficient; the real boundary is the separate sandbox. Present on the STATIC E2B lane (the leader owns the
+     *  worker env). When present it is forwarded; when absent runRepairLoop is called without `workerEnv`. */
     workerEnv?: ExecutionEnv;
+    /** Reap the dedicated grader sandbox the wire provisioned for THIS repair loop (called in a `finally` on every
+     *  path — the grader is a separate sandbox the leader owns, distinct from the worker + the integration sandbox). */
     graderDestroy?: () => Promise<void>;
+    /** Pull the worker's LATEST committed `base..HEAD` diff from ITS env (the merge `pullDiff`/self-upload path). */
     pullWorkerDiff: () => Promise<WorkerDiff>;
+    /** TRUSTED, spec-derived oracle steps run in the grader (`testCmd` [+ `measureCmd`]); NEVER worker-authored. */
     oracleSteps: ExecStep[];
+    /** The tier assigned on a PASS — `trusted_hidden` when the steps run an oracleFiles-backed hidden oracle,
+     *  `property_harness_weak` for a compile-only gate, `none` if there is no usable oracle. */
     passTier: OracleTier;
+    /** council 2026-06-17 — the seeded hidden-oracle files (content), RE-INJECTED after each hermetic reset+apply so
+     *  the `clean -fdx` doesn't grade against a wiped/worker-substituted oracle. Empty for an inline-testCmd gate. */
     oracleFiles?: Array<{
         path: string;
         content: string;
     }>;
+    /** fork1.2 — paths the candidate patch must not touch (the oracle/test paths); a touch → `needs_human_oracle`. */
     oraclePaths?: string[];
+    /** In-loop attempt ceiling (LEADER_REPAIR_LOOP_ATTEMPTS, validated 2-3 by the wire). */
     maxAttempts: number;
+    /** K re-isolations to settle a flaky verdict (LEADER_ORACLE_FLAKY_K, default 2). */
     flakyK?: number;
+    /** Cost/time backstops forwarded to `runRepairLoop`. */
     costCeilingMicroUsd?: number;
     totalTimeoutMs?: number;
+    /** §10.5 resume threading: the restored `RepairBundle` from a resumed checkpoint (`repairBundleFromCheckpoint`),
+     *  re-seeded MONOTONICALLY. v1 makes the repair path mutually exclusive with resource-suspend (the wire drops
+     *  `resourceSpec` when `repairLoopActive`), so this is usually undefined; threaded for the future resume path. */
     resumeBundle?: RepairBundle;
+    /** §10.9 — the resolved generator+verifier model ids for the L3 de-correlation gate. v1 leaves L3 OFF (unset). */
     l3?: {
         generatorModelId: string;
         verifierModelId: string;
     };
+    /** Per-attempt observability callback. */
     onAttempt?: (info: {
         attempt: number;
         terminal?: RepairTerminal;
@@ -34,6 +92,7 @@ export interface RepairWireCfg {
     }) => void;
     log?: (event: string, x?: Record<string, unknown>) => void;
 }
+/** A leader-mapped repair outcome: the report (carrying `repairTerminal` — §10.6) + the raw result + held candidate. */
 export interface RepairWireOutcome {
     report: WorkerReport;
     result: RepairResult;
@@ -44,6 +103,25 @@ export interface RepairWireOutcome {
         gradedHash?: string;
     };
 }
+/**
+ * §3.3 — run the bounded single-agent self-repair loop over the solo worker and map the result to a `WorkerReport`
+ * (with `repairTerminal` set — §10.6). Builds the `RepairOracle` closure (capturing the worker-diff source, the
+ * grader handle, `integBase`, the trusted steps, the resolved model ids), then calls `runRepairLoop` with
+ * `graderEnv` = the integration sandbox, `workerEnv` = the solo worker's env (so the identity check is LIVE),
+ * OMITTING `immutableOraclePaths` (§10.2). Never throws — a thrown engine error maps to a `failed` report so the
+ * leader's "never throws" contract holds. The held candidate (`candidate_only` etc.) is surfaced DELIMITED (§10.7).
+ */
 export declare function runRepairLoopForLeader(solo: ProvisionedWorker, implSpec: TaskSpec, cfg: RepairWireCfg): Promise<RepairWireOutcome>;
+/**
+ * §10.8 — the SINGLE wire-call helper. Attaches the `LeaderDeps.repairLoop` dep (the opt-in single-agent repair
+ * loop) using the integration sandbox as the grader (R1). `wire.ts` calls this ONCE per integration-sandbox path
+ * instead of editing its dense provision spreads. When `cfg` is absent (LEADER_REPAIR_LOOP off) it is a NO-OP →
+ * `deps.repairLoop` stays unset → the leader's single-agent paths are byte-identical to today.
+ *
+ * The wire supplies a `resolve(solo, sub)` that, per solo worker, produces the concrete `RepairWireCfg` (the real
+ * Runner + the worker env ref + the worker diff source bound to THAT worker). Kept as a callback so the grader
+ * handle / steps / model ids the wire already holds are closed over once, and only the per-worker bindings are
+ * resolved at call time.
+ */
 export declare function attachRepairLoopDeps(deps: LeaderDeps, resolve: ((solo: ProvisionedWorker, sub: SubtaskSpec) => Promise<RepairWireCfg>) | undefined): void;
 //# sourceMappingURL=repair-wire.d.ts.map

package/dist/leader/repair-wire.js

@@ -1,19 +1,70 @@
+/**
+ * The WIRE that wraps core `runRepairLoop` onto the leader's single-agent path
+ * (`docs/LEADER-REPAIRLOOP-INTEGRATION.md` §3.3 + the authoritative §10 layer). It owns the three things the
+ * `RepairOracle` closure (`repair-oracle.ts`) and the core engine CANNOT resolve themselves:
+ *
+ *  1. **The grader handle (R1, §10.1)** — the reused integration sandbox's writeFile/exec + `integBase`, bound by
+ *     the caller (`attachRepairLoopDeps` is handed the integration env). The closure grades there; the worker env
+ *     stays distinct so the §5.1 identity check (`graderEnv !== workerEnv`) is LIVE.
+ *  2. **The worker diff source** — `pullWorkerDiff`, the same `pullDiff`/self-upload path the merge uses, so the
+ *     closure materializes the worker's LATEST committed `base..HEAD` diff every grade (§10.1; never a stale diff).
+ *  3. **De-correlation model ids (§10.9 mechanics)** — the closure receives NO model ids (roles→models resolve
+ *     INSIDE `Runner.runTask`, AFTER the closure returns), so the WIRE resolves `generatorModelId` +
+ *     `verifierModelId` from `cfg.roles`/`cfg.models` and passes them to `mkRepairOracle.l3`. v1 ships L3 OFF
+ *     (`cfg.l3` unset) → L2 `trusted_hidden` is the sole clearer; `terminalForTier` caps every PASS at
+ *     `candidate_only`.
+ *
+ * §10.2 — for v1 SAFE-tier `candidate_only` we OMIT `immutableOraclePaths` (the bare `graderEnv !== workerEnv`
+ * identity check suffices; the structural bash write-probe is vacuous across distinct sandboxes and matters only
+ * for the mandate-OFF auto-accept path). `workerEnv` IS passed so the identity check runs.
+ *
+ * §10.7 — the surfaced `candidatePatch.patch` is worker-authored code reaching a human-read HTTP body / durable-
+ * approval row, so it is DELIMITED (`delimitUntrusted(...)`); `reason` comes ONLY from the core-sanitized
+ * `RepairResult.verification.findings[0]`, never the raw oracle trace.
+ *
+ * §10.8 — `attachRepairLoopDeps(deps, integEnv, cfg)` is the SINGLE wire-call helper so `wire.ts` gains one line
+ * per integration-sandbox path instead of in-place edits to its dense provision spreads. Stage-2 calls it.
+ *
+ * Everything here is gated by the caller behind `LEADER_REPAIR_LOOP` (default OFF): when the dep is not attached
+ * the leader's single-agent paths are byte-identical to today.
+ */
 import { runRepairLoop, delimitUntrusted, } from "@sema-agent/core";
 import { mkRepairOracle } from "./repair-oracle.js";
+/**
+ * §10.6 status mapping. A SAFE-tier `candidate_only`/`fixed` maps to status `completed` (back-compat — there is no
+ * `candidate_only` status member; the candidate state rides on `repairTerminal`, and the merge push chokepoint
+ * holds the push). Every other terminal is a NON-mergeable abstain/failure → `failed` (quarantined), carrying the
+ * terminal as the WHY (no-silent-failures). `gave_up`/`oracle.unprotected` → `failed`; `needs_human_oracle`/
+ * `conflict` → `failed` too (the HTTP layer re-reads `repairTerminal` to surface `needs_human`, `endpoint.ts:75`).
+ */
 function statusForTerminal(t) {
     return t === "fixed" || t === "candidate_only" ? "completed" : "failed";
 }
+/**
+ * §3.3 — run the bounded single-agent self-repair loop over the solo worker and map the result to a `WorkerReport`
+ * (with `repairTerminal` set — §10.6). Builds the `RepairOracle` closure (capturing the worker-diff source, the
+ * grader handle, `integBase`, the trusted steps, the resolved model ids), then calls `runRepairLoop` with
+ * `graderEnv` = the integration sandbox, `workerEnv` = the solo worker's env (so the identity check is LIVE),
+ * OMITTING `immutableOraclePaths` (§10.2). Never throws — a thrown engine error maps to a `failed` report so the
+ * leader's "never throws" contract holds. The held candidate (`candidate_only` etc.) is surfaced DELIMITED (§10.7).
+ */
 export async function runRepairLoopForLeader(solo, implSpec, cfg) {
     try {
         return await runRepairLoopForLeaderInner(solo, implSpec, cfg);
     }
     finally {
+        // Reap the dedicated grader sandbox on EVERY path (success, abstain, or a thrown engine error). The grader is
+        // a separate provisioned sandbox the wire minted for this loop; the inner fn never throws (its own try/catch
+        // maps an engine error to a failed report), so this `finally` runs once per loop.
         if (cfg.graderDestroy)
             await cfg.graderDestroy().catch(() => { });
     }
 }
 async function runRepairLoopForLeaderInner(solo, implSpec, cfg) {
     const base = { workerId: solo.workerId, sessionId: solo.sessionId, branch: solo.branch, baseSha: solo.baseSha };
+    // fork2.2 — capture the EXACT bytes the oracle graded (the last verdict) so the surfaced
+    // candidate == the graded artifact: a human reviews the bytes that produced the terminal, never a later re-pull
+    // that may have drifted. Updated on every oracle call; the last one is the artifact the terminal is about.
     let graded;
     const oracle = mkRepairOracle({
         pullWorkerDiff: cfg.pullWorkerDiff,
@@ -22,7 +73,7 @@ async function runRepairLoopForLeaderInner(solo, implSpec, cfg) {
         integBase: cfg.grader.integBase,
         oracleSteps: cfg.oracleSteps,
         passTier: cfg.passTier,
-        ...(cfg.oraclePaths ? { oraclePaths: cfg.oraclePaths } : {}),
+        ...(cfg.oraclePaths ? { oraclePaths: cfg.oraclePaths } : {}), // fork1.2 — refuse a patch that touches the oracle
         onGraded: (info) => { graded = { diff: info.diff, hash: info.hash }; },
         ...(cfg.flakyK !== undefined ? { flakyK: cfg.flakyK } : {}),
         ...(cfg.l3 ? { l3: cfg.l3 } : {}),
@@ -33,6 +84,11 @@ async function runRepairLoopForLeaderInner(solo, implSpec, cfg) {
         result = await runRepairLoop(cfg.runner, implSpec, {
             oracle,
             graderEnv: cfg.grader.env,
+            // §10.2 — pass workerEnv ONLY when present (the static E2B lane, where the leader owns the worker env) so
+            // the LIVE identity check runs; OMIT it on the factory lane where the worker's raw env is not surfaced
+            // (runRepairLoop then SKIPS the check + fires onWarn — fine, the grader is a separate sandbox by
+            // construction). Either way OMIT immutableOraclePaths (the structural probe is vacuous across distinct
+            // sandboxes; the bare graderEnv !== workerEnv check is sufficient SAFE-tier).
             ...(cfg.workerEnv ? { workerEnv: cfg.workerEnv } : {}),
             maxAttempts: cfg.maxAttempts,
             ...(cfg.resumeBundle ? { resumeBundle: cfg.resumeBundle } : {}),
@@ -56,8 +112,15 @@ async function runRepairLoopForLeaderInner(solo, implSpec, cfg) {
         ...(result.stats ? { stats: result.stats } : {}),
         ...(result.errorMessage ? { error: result.errorMessage } : {}),
     };
+    // §10.7 — surface a held candidate DELIMITED. `reason` is sourced ONLY from the core-sanitized verification
+    // findings (never the raw oracle trace tail, which is untrusted worker-adjacent text). Surface on any non-
+    // auto-accepting terminal that still carries usable worker output (candidate_only / needs_human_oracle /
+    // gave_up / conflict). `oracle.unprotected` is an infra-isolation failure → no candidate to surface.
     let candidatePatch;
     if (terminal !== "oracle.unprotected" && terminal !== "fixed") {
+        // fork2.2 — surface the EXACT bytes the oracle graded (the last verdict's diff + its hash), so the human
+        // reviews the artifact that produced this terminal — never a later re-pull that may have drifted. Fall back
+        // to a fresh pull only if the loop somehow reached here without a graded diff (defensive; hash unknown).
         const g = graded ??
             (await (async () => {
                 const d = await cfg.pullWorkerDiff().catch((e) => ({ ok: false, error: e instanceof Error ? e.message : String(e) }));
@@ -76,11 +139,25 @@ async function runRepairLoopForLeaderInner(solo, implSpec, cfg) {
     cfg.log?.("repair_loop_outcome", { terminal, status: report.status, hasCandidate: candidatePatch !== undefined });
     return { report, result, ...(candidatePatch ? { candidatePatch } : {}) };
 }
+/**
+ * §10.8 — the SINGLE wire-call helper. Attaches the `LeaderDeps.repairLoop` dep (the opt-in single-agent repair
+ * loop) using the integration sandbox as the grader (R1). `wire.ts` calls this ONCE per integration-sandbox path
+ * instead of editing its dense provision spreads. When `cfg` is absent (LEADER_REPAIR_LOOP off) it is a NO-OP →
+ * `deps.repairLoop` stays unset → the leader's single-agent paths are byte-identical to today.
+ *
+ * The wire supplies a `resolve(solo, sub)` that, per solo worker, produces the concrete `RepairWireCfg` (the real
+ * Runner + the worker env ref + the worker diff source bound to THAT worker). Kept as a callback so the grader
+ * handle / steps / model ids the wire already holds are closed over once, and only the per-worker bindings are
+ * resolved at call time.
+ */
 export function attachRepairLoopDeps(deps, resolve) {
     if (!resolve)
-        return;
+        return; // LEADER_REPAIR_LOOP off → no-op → byte-identical default path
     deps.repairLoop = {
         run: async (solo, sub) => {
+            // `resolve` is ASYNC: it provisions a DEDICATED grader sandbox (seed + inject-oracle) for THIS loop, which
+            // is async. The grader lifecycle (destroy) rides on the returned `RepairWireCfg.graderDestroy`, reaped in
+            // `runRepairLoopForLeader`'s `finally`.
             const cfg = await resolve(solo, sub);
             const implSpec = { ...sub.spec, sessionId: solo.sessionId };
             return runRepairLoopForLeader(solo, implSpec, cfg);

package/dist/leader/wire.d.ts

@@ -3,8 +3,16 @@ import type { CheckpointStoreFull } from "../plugins/store-backend.js";
 import { type LeaderResult } from "./leader.js";
 import type { LeaderRequestBody } from "./endpoint.js";
 export interface LeaderWireConfig {
+    /** Static-env compat mode (E2B only): the leader provisions/owns each env. Required when `envFactory` unset. */
     e2bApiKey?: string;
+    /** design/68 F2(a) + k8s lane: the per-task execution-env factory the service main already built for
+     *  REMOTE_EXEC (e2b or k8s/Kata) — workers and the integration sandbox run on envs from THIS factory.
+     *  Requires `s3` (diff-out is the worker's self-upload; there is no leader-held env to pull from). */
     envFactory?: ExecutionEnvFactory;
+    /** Durable suspend/resume for SUB-WORKERS (design/68 C4): when set, each worker task carries the durable
+     *  question/ask policy + checkpoint store, so a gated ask/AskUserQuestion SUSPENDS the worker (checkpoint +
+     *  paused env) instead of failing — the trigger replan-lite C4 arbitrates on. Mirrors main.ts's per-task
+     *  durable wiring; ctx is seeded at provision so the surfaced token is resumable on the single-agent path. */
     durable?: {
         checkpointStore: CheckpointStoreFull;
         requireApproval: string[];
@@ -13,21 +21,48 @@ export interface LeaderWireConfig {
         autoBudget?: number;
         neverAuto?: string[];
     };
+    /** Durable tool-result offload store (TiDB). REQUIRED for `durable` to actually suspend: core's suspend
+     *  pre-commit refuses with the default InMemoryToolResultStore (offloaded results would deref to null after
+     *  a cross-replica resume) and silently falls back to the synchronous onAsk gate — which the leader does not
+     *  wire, so the gated call is denied and the worker FAILS instead of suspending (found live: drill c3). */
     toolResultStore?: ToolResultStore;
+    /** Durable session store (TiDB). Same durable-resume requirement as `toolResultStore`: a suspended sub-worker's
+     *  session history must be readable by the MAIN runner on /decide resume — with the per-wire in-memory default
+     *  the resume dies with SessionError "Entry <leafId> not found" (found live: drill c3 deny path). */
     sessionStore?: SessionStore;
+    /** Worker model brain + catalog (the same the service runs tasks on). */
     brain: Brain;
     models: Record<string, Model>;
     roles: ModelRoles;
     pricing: Record<string, ModelPricing>;
+    /** Workspace root inside each E2B VM. Default /home/user. */
     workspace?: string;
+    /** Git identity for the Coordinator's local clone/commit. */
     git?: {
         name: string;
         email: string;
     };
+    /** design/68 A6 knob: false = router never fans out (deterministic single route, zero router cost). */
     fanoutEnabled?: boolean;
+    /** The model (a catalog name) the ROUTER/planner call runs on. The route is a trivial single-vs-fanout
+     *  classification; running it on a heavy reasoning model (deepseek-v4-pro + reasoning) returns an EMPTY
+     *  completion ~2/3 of the time — the budget is spent on reasoning with no answer text → "not valid JSON" →
+     *  collapse-to-single, silently defeating fan-out (search 2026-06-14, reproduced 3×). A cheap non-reasoning
+     *  model (deepseek-v4-flash) routes correctly 51/51 in probes. Unset → the route runs on the default model. */
     routerModel?: string;
+    /** Max bounded integration-repair rounds on a clean-merge-but-failing-build (see merge.ts IntegrationRepair).
+     *  0 / unset = OFF (a failing integration test is terminal, the pre-2026-06-14 behavior). Env override:
+     *  LEADER_REPAIR_ROUNDS. Repair runs the strong (default) model with hands in the live merged sandbox. */
     repairRounds?: number;
+    /** Max bounded merge-conflict-resolution rounds on a `git apply --3way` conflict (see merge.ts ConflictResolver).
+     *  0 / unset = OFF (an apply conflict collapses the whole run to a single worker, the pre-2026-06-16 behavior).
+     *  Env override: LEADER_CONFLICT_ROUNDS. Resolves the conflict in-place + keeps the other workers' work, instead
+     *  of discarding all fan-out output and redoing single. Runs the strong (default) model with hands in the sandbox. */
     conflictRounds?: number;
+    /** design/68 §8 F2(a): when set, workers run on FACTORY envs (runner-owned lifecycle — the durable-suspend-
+     *  complete path; a suspended worker's paused env is exempt from the leader reap by construction) and diff-out
+     *  is the worker's mandatory self-upload to this MinIO/S3 store (presigned per worker; creds adapter-held).
+     *  Unset = the original leader-owned static-env mode (pullDiff compat). */
     s3?: {
         endpoint: string;
         bucket: string;
@@ -41,7 +76,38 @@ export interface LeaderWireConfig {
         info?: (m: string, x?: Record<string, unknown>) => void;
     };
 }
+/** The env surface wire needs (both the E2B and k8s adapters implement core's RemoteExecutionEnv). */
 type WireEnv = Pick<RemoteExecutionEnv, "exec" | "writeFile">;
+/**
+ * Resume-safe worker staging (the design/68 F2(a) factory-env path). Runs adapter-side before the agent's
+ * first workspace-touching call: seed the base repo at the worker branch + plant the upload script (so the
+ * presigned URL never passes through the model).
+ *
+ * 🔴 BL-1 fix (design/74 Slice 6): on a RESOURCE-SUSPEND RESUME core re-invokes the `executionEnvFactory`,
+ * producing a FRESH `withStaging` wrapper (`staged=undefined`) whose `stage()` runs AGAIN — AFTER core's
+ * `resumeVM()` has already untar'd the snapshot onto the fresh pod (`resumeVM` is not a STAGED_METHOD, so it
+ * is NOT intercepted by the staging proxy; the agent's first `exec` is what triggers `stage()`, lazily, and
+ * by then the snapshot is restored). The old `stage()` ran the seed UNCONDITIONALLY:
+ *     `${seedCmd}; cd ${repo}; git checkout -q -b ${branch}`
+ * and `seedCmd` begins with `rm -rf /workspace/repo` — so it WIPED the just-restored snapshot and re-seeded at
+ * `baseSha`, then created the worker branch at base. The forensic proof (leaderRunId 019ecda7): the suspend
+ * snapshot object DID contain the worker's commit (`git log` in the S3 tarball = the real progress), yet every
+ * resumed slice's `git log` showed only the base commit — the worker rebuilt destroyed work for ~47 min. THIS
+ * (a staging re-seed clobbering a correctly-restored snapshot) is the dominant cause of failed make-real runs.
+ *
+ * The fix = a RESTORED-SNAPSHOT SENTINEL that no-ops staging on resume. The robust signal is the upload-script
+ * MARKER FILE (`uploadScriptPath`): staging itself plants it, so it is present in EVERY restored snapshot
+ * (verified: it survives in both a base-state in-progress snapshot AND a post-commit one) and ABSENT on a
+ * genuinely fresh pod — and it is INDEPENDENT of git/commit state. That last point matters: a worker can
+ * suspend with work in progress but no commit yet (HEAD still == baseSha), so a "HEAD advanced past baseSha"
+ * probe alone would WRONGLY re-seed+clobber that valid snapshot. The marker captures "staging already ran here"
+ * regardless of whether a commit landed. We additionally accept the worker branch already existing as a
+ * secondary restored-snapshot signal (belt-and-suspenders for the same git-state-independent reason).
+ *
+ * A FRESH pod has neither marker nor branch → full staging runs. A probe transport failure falls through to
+ * full staging too (fails honestly via `sh()`, never silently skips). `branch`/paths are `validateSubtasks`-
+ * clean / deployment config and are JSON-quoted under `bash -lc` regardless. Exported for the regression test.
+ */
 export declare function stageWorkerEnv(env: WireEnv, opts: {
     seedCmd: string;
     repo: string;
@@ -49,12 +115,25 @@ export declare function stageWorkerEnv(env: WireEnv, opts: {
     uploadScriptPath: string;
     uploadScript: string;
 }): Promise<void>;
+/** Build the `runLeader(body)` the HTTP endpoint invokes. Constructs real per-task deps + runs the leader. */
+/**
+ * Per-leader-run resource bounds derived from env (2026-06-14). Exported for unit tests. The worker sandbox
+ * lifetime (BUG2), the worker's diff-upload presigned-URL TTL (BUG1), and the worker spec's triple bound
+ * (maxTurns/timeoutSec/maxCostUsd, #15) ALL track one `leaderTimeoutMs` — a hardcoded 10min (sandbox) or 1h
+ * (URL) silently killed long autonomous builds or expired the diff upload mid-run. core's turn cap is now a
+ * high net (10000), so the leader gives each worker an explicit triple bound; a sub-task's own limits override.
+ */
 export declare function leaderResourceConfig(env?: NodeJS.ProcessEnv): {
     leaderTimeoutMs: number;
     workerMaxTurns: number;
     workerBudgetUsd: number;
     workerLimits: Partial<TaskSpec>;
     presignTtlSec: number;
+    /** design/74 Slice 6: opt-in (LEADER_RESOURCE_SUSPEND=true) resource-slice suspend for workers. When set, a
+     *  worker SUSPENDS at the per-slice window (`sliceMaxCostUsd`) instead of failing at the budget, and the
+     *  leader auto-resumes (resumeWithVerification) until the TOTAL (`totalBudgetUsd` = workerBudgetUsd) is spent
+     *  — a budget overrun becomes a resumable pause, not a worker failure. `maxSuspends` is sized to the slice
+     *  count (+margin) so the suspend-loop cap doesn't fire before the budget is legitimately spent. */
     resourceSuspend?: {
         totalBudgetUsd: number;
         sliceMaxCostUsd: number;