@sema-agent/server 1.322.0 → 2.0.0

package/dist/leader/leader.d.ts

@@ -1,7 +1,27 @@
+/**
+ * v2 MVP M4 — the leader orchestrator (design/50 §3, V2-MVP-PLAN.md). Composes the proven pieces into one
+ * callable API: Planner → fanOut (M1) → diff-out (M2) → merge(b) (M3) → Coordinator push.
+ *
+ * Worker-env model (design/68 §8 F2(a)): preferred = FACTORY env (runner-owned lifecycle; durable suspend only
+ * yields a complete ownedEnv on this path) + diff-out via the worker's mandatory SELF-UPLOAD last step
+ * (`fetchDiff`, diffup.ts). Compat = the original static env the leader owns: provision up-front, pull each
+ * branch's diff OUT of the still-alive env (pullDiff), destroy every env in a `finally`.
+ * fanOut's runner just routes a sessionId to that worker's env-bound runner. This is the leaderless-leader
+ * pattern (service[19]): authority = owning the integration+verification point + disjoint file-ownership.
+ *
+ * Deps injected → mock-tested; the real-infra wiring (E2B envs + deepseek runners + git push) lives in the
+ * joint dogfood, which this generalizes.
+ */
 import { type RunnerLike, type WorkerReport } from "./fanout.js";
 import { type ExecStreamLike } from "./diffout.js";
 import { type MergeDeps, type MergeResult } from "./merge.js";
 import { type TaskSpec, type VerifyConfig, type CheckpointToken, type ToolSpec, type RepairTerminal, type OracleTier, type RepairResult } from "@sema-agent/core";
+/** design/74 Slice 6: drive a worker's resource-suspend auto-resume to a terminal (or bound) state. Exported
+ *  for unit tests. Loops `resume(token, slice)` WHILE the result carries a `resource_limit` checkpoint gate —
+ *  NOT by status (the verify wrapper may surface a suspend as failed-with-token). Exits on: a terminal result
+ *  (completed/failed → no gate), an exhausted budget (core fails the resume fast → no token/gate), a
+ *  human-approval gate (kind ≠ "resource_limit" — never auto-resumed), `signal.aborted`, or `maxSlices` (a
+ *  belt; core's ledger fail-fast + per-task suspend-loop cap are the primary bounds). Returns the final result. */
 export declare function autoResumeOnResource<T extends {
     checkpointToken?: CheckpointToken;
     checkpointGate?: {
@@ -10,35 +30,61 @@ export declare function autoResumeOnResource<T extends {
 }>(initial: T, signal: {
     readonly aborted: boolean;
 }, resume: (token: CheckpointToken, slice: number) => Promise<T>, maxSlices?: number): Promise<T>;
+/** A planned sub-task: a worker id, its branch, disjoint file-ownership, and the agent objective. */
 export interface SubtaskSpec {
     workerId: string;
     branch: string;
     files: string[];
     spec: Omit<TaskSpec, "sessionId" | "signal">;
 }
+/** A leader-OWNED worker: its env-bound runner + the env handle to pull its diff out + lifecycle. */
 export interface ProvisionedWorker {
     workerId: string;
     sessionId: string;
     branch: string;
+    /** base commit of THIS worker's env (drives `git format-patch <baseSha>..<branch>` diff-out). */
     baseSha: string;
+    /** runs the worker agent on this worker's env (static `executionEnv` or a factory — design/68 F2(a)). */
     runner: RunnerLike;
+    /** Static-env mode (M2 compat): pull the worker's branch diff OUT of its (post-task, still-alive) env. */
     diffEnv?: ExecStreamLike;
+    /** Factory-env mode (design/68 F2(a), preferred when set): fetch the diff the worker SELF-UPLOADED as its
+     *  mandatory last task step (presigned MinIO object) — the env is runner-owned and already gone. */
     fetchDiff?: () => Promise<import("./diffout.js").PullDiffResult>;
+    /** Static-env mode only: the leader owns + destroys the env. Factory envs omit this — the runner's factory
+     *  lifecycle destroys them, and a SUSPENDED worker's paused env is thereby exempt from the leader's reap
+     *  (design/68 row4/C4: destroying a suspended worker's env = expiring its resume token). */
     destroy?: () => Promise<void>;
     spec: Omit<TaskSpec, "sessionId" | "signal">;
+    /** Optional read-effect PROBE tools for the L3 verifier (verifyWorker path). The default verifierTools = the
+     *  impl's tools filtered to effect:"read", which DROPS the env's write-effect `bash` → the verifier can't run
+     *  python3/tests → PARTIAL. Provision a read-effect exec/probe tool here so the verifier can actually verify. */
     verifierTools?: ToolSpec[];
 }
 export interface LeaderDeps {
+    /** Plan a task into N disjoint-file sub-tasks (MVP: simple/hand-authored; adaptive replan = scale). */
     plan: (task: string) => Promise<SubtaskSpec[]>;
+    /** Provision a leader-owned worker (its env seeded with base at `branch` + an env-bound runner). */
     provisionWorker: (sub: SubtaskSpec) => Promise<ProvisionedWorker>;
+    /** Ephemeral no-creds integration sandbox + the credentialed Coordinator push (merge(b) deps). */
     provisionIntegrationSandbox: MergeDeps["provisionIntegrationSandbox"];
     push: MergeDeps["push"];
+    /** Integration test command (the merge gate) + repo dir inside the sandbox. */
     testCmd: string;
+    /** Optional truecorrect MEASURE (design/59): a thorough hidden-oracle command run IN the integration sandbox
+     *  after the gate passes (NOT a gate) — offloads the measure from the control plane. Result in result.merge.measure. */
     measureCmd?: string;
     repoDir?: string;
+    /** Diff-out repo dir inside each WORKER env (default = repoDir). */
     workerRepoDir?: string;
+    /** fan-out deadline + concurrency cap. */
     timeoutMs: number;
     maxConcurrency: number;
+    /** design/52 L3a — optional per-module sub-gate + bounded repair, run AFTER fan-out, BEFORE merge. For each
+     *  completed worker: judge its module (diff) vs its sub-objective; on fail, re-run that ONE worker with the
+     *  judge's feedback (bounded by maxRepairs, default 1) on its own still-alive env, then re-judge. A module that
+     *  still fails is marked `failed` (merge quarantines it). Catches per-module escapes the end-integration test
+     *  misses + restores cheap-team correctness by local repair (search [38] / N=6 all-or-nothing). Omit = off. */
     moduleGate?: {
         judge: (sub: SubtaskSpec, diff: string) => Promise<{
             ok: boolean;
@@ -47,11 +93,34 @@ export interface LeaderDeps {
         repairObjective: (sub: SubtaskSpec, reason: string) => string;
         maxRepairs?: number;
     };
+    /** core 1.72 native L3a (design/54 §4): when set, each worker runs via `runWithVerification` (run the module +
+     *  an ADVERSARIAL DECORRELATED verifier tries to break it reading the diff/workspace + a bounded fix-loop)
+     *  instead of plain fan-out. The worker runner's `models` catalog MUST carry the heterogeneous `verifierModel`
+     *  (decorrelation = deployment contract). Mutually exclusive with `moduleGate` (this IS the native version). */
     verifyWorker?: VerifyConfig;
+    /** Replan-lite (design/68 §6): bounded, DETERMINISTIC reactions — no runtime DAG surgery. When set:
+     *  worker failed → redispatch ×1 on a FRESH env (clean base; a crashed worker's half-written workspace is
+     *  never reused) → still failed = collapse-remainder-to-single; verify FAIL (repair already bounded inside
+     *  the verify loop) → collapse; structural merge conflict → collapse + record; budgetUsd exceeded → stop
+     *  fan-out, single continues. Multi-trigger arbitration priority (C6): suspended > budget > merge-conflict >
+     *  verify-fail > worker-failed — only the highest-priority reaction runs. (The suspended reaction itself —
+     *  cancel the others, exempt the suspended worker, surface its token — is unconditional, not gated here.) */
     replan?: {
+        /** Fan-out budget (USD, sum of worker costs). Exceeded → stop fan-out, collapse to single (C5). */
         budgetUsd?: number;
     };
+    /** LEADER-REPAIRLOOP-INTEGRATION §3/§10 — the OPT-IN single-agent self-repair loop (`runRepairLoop`). When
+     *  set (LEADER_REPAIR_LOOP on; the wire attaches it via `attachRepairLoopDeps`), the single-agent paths
+     *  (`collapseToSingle` `:409` and the N=1 `route==="single"` path) route their solo worker through this
+     *  instead of the plain fan-out map: GENERATE == one `runner.runTask`, GRADED by an ISOLATED grader (the
+     *  reused integration sandbox), capped at `candidate_only` (SAFE-tier never auto-accepts). Stage-2 wires the
+     *  call-sites; this is the additive dep slot. `run` returns the worker's `WorkerReport` (carrying
+     *  `repairTerminal` — §10.6) so the merge push chokepoint can hold an unconfirmed candidate. Unset ⇒ the
+     *  default path is byte-identical to today. */
     repairLoop?: {
+        /** Run the bounded repair loop over a single provisioned worker; the returned report carries `repairTerminal`
+         *  (and the candidate patch is surfaced on LeaderResult). The grader env / oracle steps / model ids are
+         *  captured by the wire (`runRepairLoopForLeader`). */
         run: (solo: ProvisionedWorker, sub: SubtaskSpec) => Promise<{
             report: WorkerReport;
             result: RepairResult;
@@ -63,6 +132,10 @@ export interface LeaderDeps {
             };
         }>;
     };
+    /** LEADER-REPAIRLOOP-INTEGRATION §10.3/§10.4 — the merge-path push-gate extras (the wire sets them from
+     *  `LEADER_MEASURE_GATES`, default OFF). Threaded straight into `MergeDeps` (`measureGates` / `strongOracleSeeded`
+     *  / `measureDrivesRepair`). Unset ⇒ the merge push path is byte-identical to today (the §10.6 repairTerminal
+     *  chokepoint still fires independently — it does NOT need these). */
     mergeGates?: Pick<MergeDeps, "measureGates" | "strongOracleSeeded" | "measureDrivesRepair">;
     logger?: {
         warn?: (m: string, x?: Record<string, unknown>) => void;
@@ -74,23 +147,43 @@ export interface LeaderResult {
     reports: WorkerReport[];
     merge?: MergeResult;
     cancelled: boolean;
+    /** Which route the difficulty router picked (search [43]): "single" = a 1-subtask plan, "fanout" = N. */
     route?: "single" | "fanout";
+    /** Set when planning/provisioning failed before fan-out. */
     error?: string;
+    /** Replan-lite (design/68 §6): which trigger won arbitration + what was done. */
     replan?: {
         trigger: "suspended" | "budget" | "merge-conflict" | "verify-fail" | "worker-failed";
         redispatched?: string[];
         collapsed?: string;
     };
+    /** C4: suspended workers' resume tokens, surfaced to the caller (their checkpoints + paused envs are intact —
+     *  the single-agent resume path owns them from here; orphan protection = the existing deadline reap). */
     suspended?: Array<{
         workerId: string;
         sessionId: string;
     }>;
+    /** design/74 Slice 6 / task#16: the diff (uncommitted work auto-committed by the belt, then diff-out) of
+     *  workers that did NOT merge (failed / still-suspended). Their progress is otherwise lost — the merge only
+     *  integrates COMPLETED workers — so surface it here for review/cherry-pick instead of silently dropping it
+     *  (the migration-run loss: a network-failed worker's 4 commits vanished). Best-effort + non-empty only. */
     salvaged?: Array<{
         workerId: string;
         sessionId: string;
         patch: string;
     }>;
+    /** LEADER-REPAIRLOOP-INTEGRATION §5 — the single-agent repair loop's terminal (when `LeaderDeps.repairLoop`
+     *  ran on a single-agent path). Surfaced so the HTTP status map (`endpoint.ts:75`) can distinguish "abstained,
+     *  awaiting a human" (`candidate_only`/`needs_human_oracle`/`conflict` → `needs_human`) from "broke"
+     *  (`oracle.unprotected`/`gave_up` → `failed`). Undefined ⇒ the repair loop did not run. */
     repairTerminal?: RepairTerminal;
+    /** LEADER-REPAIRLOOP-INTEGRATION §5/§10.7 — the held candidate when the repair loop resolved to a
+     *  non-auto-accepting terminal (`candidate_only` etc.). `patch` is the worker-authored diff, DELIMITED as
+     *  untrusted at the wire surface (`delimitUntrusted("CANDIDATE PATCH (untrusted worker code)", …)` — §10.7) so
+     *  it can safely reach the HTTP body + a durable-approval row a human reads; `reason` is sourced ONLY from the
+     *  core-sanitized `RepairResult.verification.findings[0]`, never the raw oracle trace. The push is HELD — a
+     *  human `/decide` accept fires it, reject discards (an unattended `candidate_only` is never a silent push and
+     *  never a silent drop — §5 invariant). */
     candidatePatch?: {
         patch: string;
         tier: OracleTier;
@@ -98,5 +191,9 @@ export interface LeaderResult {
         gradedHash?: string;
     };
 }
+/**
+ * Run a task to an integrated, pushed result. Never throws — failures (plan, provision, fan-out, merge) are
+ * captured in LeaderResult. ALWAYS destroys every provisioned worker env (leader owns the lifecycle).
+ */
 export declare function runLeaderTask(task: string, durableBaseSha: string, deps: LeaderDeps): Promise<LeaderResult>;
 //# sourceMappingURL=leader.d.ts.map

package/dist/leader/leader.js

@@ -1,8 +1,34 @@
+/**
+ * v2 MVP M4 — the leader orchestrator (design/50 §3, V2-MVP-PLAN.md). Composes the proven pieces into one
+ * callable API: Planner → fanOut (M1) → diff-out (M2) → merge(b) (M3) → Coordinator push.
+ *
+ * Worker-env model (design/68 §8 F2(a)): preferred = FACTORY env (runner-owned lifecycle; durable suspend only
+ * yields a complete ownedEnv on this path) + diff-out via the worker's mandatory SELF-UPLOAD last step
+ * (`fetchDiff`, diffup.ts). Compat = the original static env the leader owns: provision up-front, pull each
+ * branch's diff OUT of the still-alive env (pullDiff), destroy every env in a `finally`.
+ * fanOut's runner just routes a sessionId to that worker's env-bound runner. This is the leaderless-leader
+ * pattern (service[19]): authority = owning the integration+verification point + disjoint file-ownership.
+ *
+ * Deps injected → mock-tested; the real-infra wiring (E2B envs + deepseek runners + git push) lives in the
+ * joint dogfood, which this generalizes.
+ */
 import { fanOut } from "./fanout.js";
 import { pullDiff } from "./diffout.js";
 import { mergeBranches } from "./merge.js";
 import { Runner, runWithVerification, resumeWithVerification, delimitUntrusted } from "@sema-agent/core";
+/** design/74 Slice 6: a belt-and-suspenders bound on the leader's resource auto-resume loop. The PRIMARY bound
+ *  is the resource ledger (core fails an exhausted resume fast) + core's per-task suspend-loop cap; this only
+ *  guards against an unforeseen non-progressing loop. Generous so a legitimate many-slice budget never hits it. */
 const MAX_RESUME_SLICES = 200;
+/** design/74 Slice 6: drive a worker's resource-suspend auto-resume to a terminal (or bound) state. Exported
+ *  for unit tests. Loops `resume(token, slice)` WHILE the result carries a `resource_limit` checkpoint gate —
+ *  NOT by status (the verify wrapper may surface a suspend as failed-with-token). Exits on: a terminal result
+ *  (completed/failed → no gate), an exhausted budget (core fails the resume fast → no token/gate), a
+ *  human-approval gate (kind ≠ "resource_limit" — never auto-resumed), `signal.aborted`, or `maxSlices` (a
+ *  belt; core's ledger fail-fast + per-task suspend-loop cap are the primary bounds). Returns the final result. */
+// Generic over the result type so BOTH leader worker paths reuse it: the verify path (VerificationResult via
+// runWithVerification/resumeWithVerification) AND the non-verify path (plain TaskResult via runTaskStream/
+// runner.resume). The loop only reads `checkpointToken` / `checkpointGate`, both on TaskResult.
 export async function autoResumeOnResource(initial, signal, resume, maxSlices = MAX_RESUME_SLICES) {
     let vr = initial;
     for (let slice = 0; vr.checkpointToken !== undefined && vr.checkpointGate?.kind === "resource_limit" && !signal.aborted && slice < maxSlices; slice++) {
@@ -10,6 +36,10 @@ export async function autoResumeOnResource(initial, signal, resume, maxSlices =
     }
     return vr;
 }
+/**
+ * Run a task to an integrated, pushed result. Never throws — failures (plan, provision, fan-out, merge) are
+ * captured in LeaderResult. ALWAYS destroys every provisioned worker env (leader owns the lifecycle).
+ */
 export async function runLeaderTask(task, durableBaseSha, deps) {
     let subs;
     try {
@@ -20,10 +50,12 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
     }
     if (subs.length === 0)
         return { ok: false, reports: [], cancelled: false, error: "planner produced no sub-tasks" };
+    // difficulty router (search [43]): a 1-subtask plan IS the single route — run through the same N=1 pipeline.
     const route = subs.length === 1 ? "single" : "fanout";
     const workers = [];
-    let finalReports = [];
+    let finalReports = []; // visible to `finally` — drives the suspended-worker destroy exemption
     try {
+        // Provision every worker env up-front (leader-owned; each outlives its task for diff-out).
         for (const sub of subs) {
             try {
                 workers.push(await deps.provisionWorker(sub));
@@ -34,15 +66,22 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
         }
         const byId = new Map(workers.map((w) => [w.workerId, w]));
         const bySession = new Map(workers.map((w) => [w.sessionId, w]));
+        // fan-out: route each sessionId to its own env-bound runner (M1).
         const runner = {
             runTaskStream: (spec) => bySession.get(spec.sessionId).runner.runTaskStream(spec),
         };
         const toSubtask = (w) => ({
             workerId: w.workerId, sessionId: w.sessionId, branch: w.branch, baseSha: w.baseSha, spec: w.spec,
         });
+        // cancelOnSuspend = the unconditional C4 reaction: a suspended settle preempts the remaining fan-out.
         const foBase = { runner, timeoutMs: deps.timeoutMs, maxConcurrency: deps.maxConcurrency, cancelOnSuspend: true, ...(deps.logger ? { logger: deps.logger } : {}) };
         const runWave = async (sts) => {
             if (!deps.verifyWorker) {
+                // design/74 Slice 6 (live-test bug): the NON-verify path ALSO needs the resource-suspend auto-resume.
+                // The auto-resume previously lived only in the verify path's runWorker, so a leader with NO verifier
+                // (e.g. the drill) ran via fanOut's plain runTaskStream — a resource-suspended worker was never resumed,
+                // just surfaced "suspended". Give this path its own runWorker: run, then auto-resume across slices
+                // (plain runner.resume, no verify), then map + WARN-log any non-completed worker (no silent failures).
                 return fanOut(sts, {
                     ...foBase,
                     runWorker: async (st, signal) => {
@@ -58,12 +97,17 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
                             deps.logger?.warn?.("worker_failed", {
                                 workerId: w.workerId, status: r.status, turns: r.stats?.turns ?? 0,
                                 ...(r.errorCode ? { errorCode: r.errorCode } : {}),
+                                // A `blocked` worker carries its reason in `blockedReason`, NOT `errorMessage` — surface it too,
+                                // else a report_blocked is a silent "worker blocked" with no WHY (clay no-silent-failures).
                                 ...(r.errorMessage ? { error: r.errorMessage.slice(0, 200) } : {}),
                                 ...(r.blockedReason ? { blockedReason: r.blockedReason.slice(0, 200) } : {}),
                             });
                         }
                         return {
                             ...base,
+                            // Map the TaskResult status directly (like fanOut's own mapStatus) — a `suspended` result that the
+                            // auto-resume left unresumed (a non-resource gate, e.g. human-approval) stays `suspended` so the
+                            // leader's C4 surface/cancel reaction still fires; only completed/timeout pass through, else failed.
                             status: r.status === "completed" ? "completed" : r.status === "suspended" ? "suspended" : r.status === "timeout" ? "timeout" : "failed",
                             stats: r.stats,
                             ...(r.status === "completed" ? {} : { error: r.errorMessage ?? r.blockedReason ?? `worker ${r.status}` }),
@@ -73,6 +117,13 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
                     },
                 });
             }
+            // design/54 §4 L3a (core 1.72 NATIVE): each worker = runWithVerification — run the module, then an
+            // ADVERSARIAL DECORRELATED verifier (a different model) tries to BREAK it (reads diff/workspace, runs
+            // probes), with a bounded fix-loop = native per-module sub-gate + repair. Replaces the hand-rolled
+            // moduleGate. verdict FAIL after maxRounds → status:"failed" (merge quarantines). Run cost incl verify+fix.
+            // Routed THROUGH fanOut (not an unbounded Promise.all — council): reuses the semaphore (maxConcurrency), the
+            // overall timeout→cancelAll, and the shared abort signal — passed into the spec so a hung/cancelled verify
+            // actually aborts (so the overall-timeout's `await work` can unblock).
             const verify = deps.verifyWorker;
             return fanOut(sts, {
                 ...foBase,
@@ -81,14 +132,27 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
                     const base = { workerId: w.workerId, sessionId: w.sessionId, branch: w.branch, baseSha: w.baseSha };
                     const cfg = w.verifierTools ? { ...verify, verifierTools: w.verifierTools } : verify;
                     let vr = await runWithVerification(w.runner, { ...w.spec, sessionId: w.sessionId, signal }, cfg);
+                    // design/74 Slice 6: auto-resume a RESOURCE-suspended worker (a per-slice budget/turn/walltime overrun)
+                    // until terminal — the leader spends the worker's TOTAL budget across slices instead of failing at the
+                    // first slice. Loop + exit conditions live in `autoResumeOnResource` (unit-tested).
                     vr = await autoResumeOnResource(vr, signal, async (token, slice) => {
                         deps.logger?.info?.("worker_resource_resume", { workerId: w.workerId, slice });
                         return resumeWithVerification(w.runner, token, { gate: "resource_limit", decision: "continue" }, { ...w.spec, sessionId: w.sessionId, signal }, w.spec.objective ?? "", cfg);
                     });
                     deps.logger?.info?.("verify_outcome", { workerId: w.workerId, status: vr.status, verdict: vr.verification.verdict, rounds: vr.verification.rounds, finding: (vr.verification.findings[0] ?? "").slice(0, 220) });
                     const pass = vr.status === "completed" && vr.verification.verdict === "PASS";
+                    // round-3 review BLOCKER: a DURABLE suspend — resource OR human-approval — comes back from
+                    // runWithVerification as failed-WITH-token (core mapNestedSuspend), so gating `stillSuspended` on
+                    // `resource_limit` ONLY mis-routed a human-approval suspend to `failed` → the C4 surface/cancel
+                    // reaction never fired and its paused env could be reaped. Any worker still carrying a checkpoint
+                    // token is suspended (resumable); a genuine failure has no token. The resource auto-resume already
+                    // ran above, so a still-tokened resource worker is one the leader couldn't fully resume (deadline).
                     const stillSuspended = vr.checkpointToken !== undefined;
                     const reportStatus = pass ? "completed" : stillSuspended ? "suspended" : "failed";
+                    // No-silent-failures (clay 2026-06-15): WARN on any non-completed REPORT status — incl. a verify-FAIL
+                    // on an impl that COMPLETED (vr.status "completed" but reportStatus "failed"), which the old
+                    // `vr.status !== completed` guard missed. Carry the impl's reason: errorCode, errorMessage, AND
+                    // blockedReason (a report_blocked worker's reason lives there, not in errorMessage), plus the verdict.
                     if (reportStatus !== "completed") {
                         deps.logger?.warn?.("worker_failed", {
                             workerId: w.workerId, status: reportStatus, turns: vr.stats?.turns ?? 0, verdict: vr.verification.verdict,
@@ -100,6 +164,8 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
                     return {
                         ...base, status: reportStatus, stats: vr.stats,
                         moduleJudge: vr.verification.verdict === "PASS" ? "pass" : "fail", repairs: Math.max(0, vr.verification.rounds - 1),
+                        // A verify FAIL/PARTIAL (the impl completed but the verifier rejected it) reports the verdict;
+                        // an `unverified` (the impl didn't complete — suspend/block/error) reports the impl's own reason.
                         ...(pass
                             ? {}
                             : {
@@ -113,8 +179,18 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
                 },
             });
         };
+        // LEADER-REPAIRLOOP-INTEGRATION §10.6 — the single-agent repair loop's terminal + held candidate, lifted onto
+        // every terminal LeaderResult. Set ONLY when `deps.repairLoop` ran on a single-agent path (LEADER_REPAIR_LOOP
+        // on); undefined otherwise → the result is byte-identical to today. The `repairTerminal` ALSO rides on the
+        // solo worker's report (so the merge push chokepoint, merge.ts, holds an unconfirmed candidate by construction).
         let repairTerminal;
         let candidatePatch;
+        // Route a SINGLE provisioned worker through the opt-in `runRepairLoop` (when `deps.repairLoop` is set) instead
+        // of the plain fan-out map: GENERATE == one runner.runTask, GRADED by the isolated grader, capped at
+        // `candidate_only`. Attaches `repairTerminal` to the report (the chokepoint reads it) + lifts the held
+        // candidate. Falls back to `runWave([toSubtask(solo)])` (today's path) when the repair loop is not attached
+        // OR the per-worker resolve throws (never break the leader). Returns the same shape as `runWave` so the
+        // call-sites are a drop-in. §10.6: this covers BOTH single-agent paths (collapse + N=1) through one helper.
         const runSolo = async (solo, sub) => {
             if (!deps.repairLoop)
                 return runWave([toSubtask(solo)]);
@@ -127,10 +203,14 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
                 return { reports: [rr.report], cancelled: false };
             }
             catch (e) {
+                // The repair wire already maps a thrown engine error to a failed report; a throw HERE is a wire/resolve
+                // failure — degrade to the plain wave so the solo still runs (no silent break; warn the WHY).
                 deps.logger?.warn?.("repair_loop_dispatch_failed", { workerId: solo.workerId, err: e instanceof Error ? e.message : String(e) });
                 return runWave([toSubtask(solo)]);
             }
         };
+        // N=1 (route==="single"): the lone worker IS the single-agent path → route it through `runSolo`. With
+        // `deps.repairLoop` unset, `runSolo` delegates straight to `runWave` → byte-identical to today's `runWave(...)`.
         const fo1 = route === "single" && workers.length === 1
             ? await runSolo(workers[0], subs[0])
             : await runWave(workers.map(toSubtask));
@@ -138,11 +218,17 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
         let cancelled = fo1.cancelled;
         finalReports = reports;
         const workerRepoDir = deps.workerRepoDir ?? deps.repoDir;
+        // One diff source per worker: self-uploaded (factory env, F2(a)) preferred; else pull from the static env.
         const workerDiff = (w) => w.fetchDiff
             ? w.fetchDiff()
             : w.diffEnv
                 ? pullDiff(w.diffEnv, w.baseSha, { ref: w.branch, ...(workerRepoDir ? { cwd: workerRepoDir } : {}) })
                 : Promise.resolve({ ok: false, error: `worker ${w.workerId} has neither fetchDiff nor diffEnv` });
+        // design/74 Slice 6 (task#16, round-3 review BLOCKER): salvage the diff (belt auto-commit + diff-out) of
+        // workers that did NOT merge (failed / still-suspended) so their progress isn't silently dropped. Must run
+        // on EVERY terminal LeaderResult path — the main merge AND the early returns (surfaceSuspended, collapse) —
+        // not just the merge, else a suspended-preempted or collapsed run loses the non-completed workers' work.
+        // Best-effort: a fetch failure or an empty/paused-env diff is skipped; it NEVER blocks the result.
         const salvageNonCompleted = async (rs) => {
             const out = [];
             await Promise.all(rs
@@ -157,10 +243,19 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
                         out.push({ workerId: r.workerId, sessionId: r.sessionId, patch: d.patch });
                 }
                 catch {
+                    /* best-effort — a salvage fetch must not break the leader result */
                 }
             }));
             return out;
         };
+        // design/52 L3a — per-module sub-gate + bounded repair (between fan-out and merge). Judge each completed
+        // worker's module diff vs its sub-objective; on fail, re-run that ONE worker with feedback (bounded), then
+        // re-judge. Still-failing modules → status:"failed" so merge quarantines them. Reaps per-module escapes the
+        // end-integration test can't see + restores cheap-team correctness via localized repair (search [38]).
+        // design/158 A13: lifted from an inline `if (deps.moduleGate) { await Promise.all(...) }` block into a named
+        // stage function (same closure scope/capture/call-site as before — behavior identical), alongside the other
+        // already-named internal stages of this function (runWave/runSolo/salvageNonCompleted/surfaceSuspended/
+        // collapseToSingle below).
         const runModuleGate = async () => {
             if (!deps.moduleGate)
                 return;
@@ -172,7 +267,7 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
                 for (let attempt = 0; attempt <= maxR; attempt++) {
                     const d = await workerDiff(w);
                     if (!d.ok)
-                        return;
+                        return; // diff-out problem → leave it for merge to quarantine
                     const verdict = await deps.moduleGate.judge(sub, d.patch);
                     r.moduleJudge = verdict.ok ? "pass" : "fail";
                     r.repairs = attempt;
@@ -187,7 +282,7 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
                     try {
                         const rr = await w.runner.runTaskStream({ ...sub.spec, objective: deps.moduleGate.repairObjective(sub, verdict.reason ?? ""), sessionId: `${w.sessionId}-r${attempt + 1}` }).result();
                         if (r.stats && rr?.stats)
-                            r.stats = { ...r.stats, tokens: (r.stats.tokens ?? 0) + (rr.stats.tokens ?? 0), costMicroUsd: (r.stats.costMicroUsd ?? 0) + (rr.stats.costMicroUsd ?? 0) };
+                            r.stats = { ...r.stats, tokens: (r.stats.tokens ?? 0) + (rr.stats.tokens ?? 0), costMicroUsd: (r.stats.costMicroUsd ?? 0) + (rr.stats.costMicroUsd ?? 0) }; // fold repair cost into the worker's report
                     }
                     catch (e) {
                         r.status = "failed";
@@ -198,6 +293,7 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
             }));
         };
         await runModuleGate();
+        // merge(b) deps: diff-out per worker (self-upload or static pull), integrate, Coordinator push.
         const mergeDeps = {
             pullWorkerDiff: async (r) => workerDiff(byId.get(r.workerId)),
             provisionIntegrationSandbox: deps.provisionIntegrationSandbox,
@@ -205,12 +301,23 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
             testCmd: deps.testCmd,
             ...(deps.measureCmd ? { measureCmd: deps.measureCmd } : {}),
             ...(deps.repoDir ? { repoDir: deps.repoDir } : {}),
+            // §10.3/§10.4 — the push-gate extras (OFF by default; set by the wire from LEADER_MEASURE_GATES).
             ...(deps.mergeGates?.measureGates ? { measureGates: true } : {}),
             ...(deps.mergeGates?.strongOracleSeeded ? { strongOracleSeeded: true } : {}),
             ...(deps.mergeGates?.measureDrivesRepair ? { measureDrivesRepair: deps.mergeGates.measureDrivesRepair } : {}),
             ...(deps.logger ? { logger: deps.logger } : {}),
         };
+        // ── replan-lite (design/68 §6): deterministic reaction table, arbitrated in C6 priority order ──
+        // Spec priority: suspended > budget > merge-conflict > verify-fail > worker-failed; only the highest-
+        // priority reaction runs, and the check order below IS the arbitration (each returns; later checks never
+        // see its trigger). DETECTION order differs for merge-conflict: it is only observable AFTER mergeBranches
+        // runs, i.e. after the verify/failed reactions — which is spec-equivalent, because all three reactions are
+        // the same collapse-to-single (the ordering only affects the recorded `trigger` label, and a verify/failed
+        // collapse removes the conflicting diff before a merge could ever surface its conflict).
         let redispatched;
+        // C4 (unconditional): a suspended worker preempted the wave (fan-out cancelOnSuspend already cancelled the
+        // rest). NO merge, NO redispatch — surface failed + the resume token; its checkpoint + paused env are intact
+        // (the finally below exempts it from the static-env destroy; factory envs are exempt by construction).
         const surfaceSuspended = async (rs, wave) => {
             const sus = wave.filter((r) => r.status === "suspended");
             if (sus.length === 0)
@@ -225,9 +332,16 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
                 ...(salvaged.length > 0 ? { salvaged } : {}),
             };
         };
+        // Collapse-to-single (at most once): one fresh worker redoes the whole task on a clean branch. The discarded
+        // workers' envs die via the normal lifecycle (factory finish / the static finally) — E1. The full env-layer
+        // "adopt N half-done workspaces" seam (design/68 §8) stays future; INSTEAD (search 2026-06-16) we REUSE the
+        // fan-out work the lightweight, zero-new-seam way — hand the collapse-solo the diffs the parallel workers
+        // already produced as reference so it adapts their correct output (copy the non-overlapping modules, resolve
+        // only the overlap) rather than re-deriving the whole task blind.
         const collapseToSingle = async (trigger, reason, priorMerge) => {
             deps.logger?.warn?.("replan_collapse_to_single", { trigger, reason: reason.slice(0, 300) });
             const replan = { trigger, collapsed: reason.slice(0, 300), ...(redispatched ? { redispatched } : {}) };
+            // Best-effort gather of the fan-out workers' diffs (same source as salvage); an empty/failed diff is omitted.
             const priorDiffs = [];
             await Promise.all(reports.map(async (r) => {
                 const w = byId.get(r.workerId);
@@ -239,6 +353,7 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
                         priorDiffs.push({ workerId: r.workerId, status: r.status, patch: d.patch });
                 }
                 catch {
+                    /* best-effort — a salvage fetch must not break the collapse path */
                 }
             }));
             if (priorDiffs.length > 0)
@@ -250,8 +365,11 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
                     ``,
                     `--- PRIOR PARALLEL WORK — REUSE IT, do not re-derive from scratch ---`,
                     `${priorDiffs.length} worker(s) attempted this task in parallel; their changes could NOT be integrated cleanly (${reason.slice(0, 150)}). Each worker's diff over the base is below. COPY the correct, non-overlapping parts verbatim and produce ONE coherent change for the WHOLE task, resolving only the overlaps. Treat these as a strong starting point — fix anything wrong, but do not throw the work away.`,
+                    // BL-30/BL-32 — each prior worker's diff is untrusted worker-authored code; delimit it so an injected
+                    // instruction in a diff comment can't steer the collapse-solo agent (design/53 trifecta).
                     ...priorDiffs.map((d) => delimitUntrusted(`PRIOR WORKER '${d.workerId}' (${d.status}) DIFF (untrusted)`, d.patch.slice(0, 8000))),
                 ].join("\n");
+            // The synthetic collapse-solo sub-task (kept as a value so the §10.6 repair-loop dispatch can pass it).
             const soloSub = { workerId: "collapse-solo", branch: "worker/collapse-solo", files: ["."], spec: { objective: soloObjective } };
             let solo;
             try {
@@ -264,12 +382,18 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
             workers.push(solo);
             byId.set(solo.workerId, solo);
             bySession.set(solo.sessionId, solo);
+            // §10.6: collapse-to-single IS a single-agent path → route through `runSolo` (the opt-in repair loop when
+            // `deps.repairLoop` is set; the plain wave otherwise). `runSolo` sets the outer `repairTerminal`/
+            // `candidatePatch`, which are lifted onto this return so the chokepoint-held candidate reaches the caller.
             const fo = await runSolo(solo, soloSub);
             finalReports = [...reports, ...fo.reports];
             const sus = await surfaceSuspended(finalReports, fo.reports);
             if (sus)
                 return { ...sus, replan: { ...replan, trigger: "suspended" }, ...(repairTerminal ? { repairTerminal } : {}), ...(candidatePatch ? { candidatePatch } : {}) };
             const mRaw = await mergeBranches(fo.reports, durableBaseSha, mergeDeps);
+            // wq64gmm5e: carry the FAILED prior merge's resolver spend across the collapse so captureTeamC1 sees the
+            // tokens it already burned (a --3way conflict that triggered collapse may have run a conflictResolver). Fold
+            // it into the collapse-merge's conflictResolverCostUsd; default path (no prior cost) is byte-identical.
             const priorCost = priorMerge?.conflictResolverCostUsd ?? 0;
             const m = priorCost > 0 ? { ...mRaw, conflictResolverCostUsd: (mRaw.conflictResolverCostUsd ?? 0) + priorCost } : mRaw;
             const salvaged = await salvageNonCompleted(finalReports);
@@ -287,16 +411,22 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
         const sus1 = await surfaceSuspended(reports, reports);
         if (sus1)
             return sus1;
+        // C5 budget: fan-out overspent → stop fanning, single continues (no expire of anything — C7 falls out of
+        // the suspended check above winning first).
         if (deps.replan?.budgetUsd !== undefined) {
             const spent = reports.reduce((s, r) => s + (r.stats?.costMicroUsd ?? 0) / 1e6, 0);
             if (spent > deps.replan.budgetUsd) {
                 return collapseToSingle("budget", `fan-out spent $${spent.toFixed(4)} > budget $${deps.replan.budgetUsd}`);
             }
         }
+        // C2 verify FAIL: the bounded repair was already spent INSIDE the verify loop (runWithVerification rounds /
+        // moduleGate repairs) — a worker still failing its module gate collapses, it is not redispatched.
         if (deps.replan && reports.some((r) => r.moduleJudge === "fail")) {
             const failed = reports.filter((r) => r.moduleJudge === "fail").map((r) => r.workerId);
             return collapseToSingle("verify-fail", `module verification failed after bounded repair: ${failed.join(", ")}`);
         }
+        // C1 worker failed: redispatch ×1, same spec, FRESH env + clean base (provisionWorker provisions anew; the
+        // crashed worker's half-written workspace is never reused) → still failed = collapse-remainder-to-single.
         if (deps.replan) {
             const failedIds = reports.filter((r) => r.status === "failed").map((r) => r.workerId);
             if (failedIds.length > 0) {
@@ -307,7 +437,7 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
                     for (const id of failedIds) {
                         const w = await deps.provisionWorker(subById.get(id));
                         fresh.push(w);
-                        workers.push(w);
+                        workers.push(w); // register IMMEDIATELY — a later provision throw must not orphan this env (council)
                     }
                 }
                 catch (e) {
@@ -331,16 +461,28 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
                 }
             }
         }
+        // merge(b): integrate + Coordinator push.
         const merge = await mergeBranches(reports, durableBaseSha, mergeDeps);
+        // C3 merge conflict: merge(b)'s sequential --3way apply IS the serial replay; a --3way failure means an
+        // architecture-level conflict → collapse to single + RECORD (the design/52 data feed).
         if (!merge.ok && merge.phase === "apply" && deps.replan) {
             deps.logger?.warn?.("replan_merge_conflict", { reason: merge.reason, quarantine: merge.quarantine ?? [] });
             return collapseToSingle("merge-conflict", merge.reason, merge);
         }
+        // design/74 Slice 6 (task#16): salvage the progress of workers that did NOT merge (failed / still-
+        // suspended). The belt auto-commit + diff-out ran on env teardown, so a non-empty patch exists (in S3 for a
+        // factory worker, or pullable from a still-alive static env, before the `finally` destroys it) — surface it
+        // so the work isn't silently lost (the migration-run loss: a network-failed worker's commits vanished).
+        // Best-effort: a fetch failure or an empty/paused-env diff is skipped, and it NEVER blocks the merge result.
         const salvaged = await salvageNonCompleted(reports);
         return {
             ok: merge.ok, reports, merge, cancelled, route,
             ...(redispatched ? { replan: { trigger: "worker-failed", redispatched } } : {}),
             ...(salvaged.length > 0 ? { salvaged } : {}),
+            // §10.6 — lift the single-agent repair loop's terminal (set by `runSolo` on the N=1 path) + the merge
+            // chokepoint's terminal onto the result so the HTTP status map (`endpoint.ts:75`) surfaces `needs_human`.
+            // `repairTerminal` (the loop's own) takes precedence over `merge.terminal` (the chokepoint's). Both undefined
+            // on the default path → byte-identical. The held `candidatePatch` (delimited at the wire) rides alongside.
             ...(repairTerminal ?? merge.terminal ? { repairTerminal: repairTerminal ?? merge.terminal } : {}),
             ...(candidatePatch
                 ? { candidatePatch }
@@ -350,6 +492,11 @@ export async function runLeaderTask(task, durableBaseSha, deps) {
         };
     }
     finally {
+        // Static envs: the leader owns the lifecycle — destroy on EVERY path, EXCEPT a suspended worker's env
+        // (C4: destroying it kills the resume; its checkpoint + paused env belong to the single-agent resume path,
+        // orphan protection = the existing deadline reap). Factory envs carry no `destroy` (runner-owned).
+        // Keyed by sessionId, not workerId: a redispatched worker shares its predecessor's workerId — exempting by
+        // workerId would also spare the ORIGINAL failed worker's env (leak, council finding).
         const suspendedSessions = new Set(finalReports.filter((r) => r.status === "suspended").map((r) => r.sessionId));
         await Promise.allSettled(workers.filter((w) => w.destroy && !suspendedSessions.has(w.sessionId)).map((w) => w.destroy()));
     }