@sema-agent/server 1.323.0 → 2.0.0

package/dist/leader/merge.d.ts

@@ -1,8 +1,25 @@
+/**
+ * v2 MVP M3 — merge(b), the hard bone (design/50 §7, V2-MVP-PLAN.md, search [25]/[26], council round-1).
+ *
+ * The deterministic Coordinator integrates N completed workers' branches under FULL isolation:
+ *   1. pull each worker's patch OUT of its container (M2 `pullDiff` — no creds go in).
+ *   2. provision an EPHEMERAL no-net/no-creds integration sandbox (base pre-provisioned by the dep).
+ *   3. `git apply --3way` each patch in sequence (partial-apply → capture `.rej`, quarantine — council#3).
+ *   4. run the full test suite IN the sandbox (the gate; untrusted diff never touches the control plane — [26]§16).
+ *   5. green → the **Coordinator** (trusted control plane, holds creds — NOT the sandbox, council#1) takes the
+ *      integrated patch and pushes with CAS `--force-with-lease=<ref>:<baseSha>` (push race → retry — council#2).
+ *   6. the sandbox is destroyed on ALL exit paths (council#15).
+ *
+ * This module is the ORCHESTRATION/control-flow (deps injected → mock-tested). The real git mechanics
+ * (apply/rebase/test/push in a real E2B container) are validated by the M5 real-E2B joint dogfood.
+ */
 import type { WorkerReport } from "./fanout.js";
 import type { PullDiffResult } from "./diffout.js";
 import { type RepairTerminal } from "@sema-agent/core";
 import { type GraderHandle } from "./grader-env-factory.js";
+/** A buffered command env for the integration sandbox (real E2B adapter adapts to this; mock in tests). */
 export interface IntegrationEnv {
+    /** Run a command; never throws — failures surface as a non-zero exitCode. */
     exec(command: string, opts?: {
         cwd?: string;
     }): Promise<{
@@ -12,8 +29,23 @@ export interface IntegrationEnv {
     }>;
     writeFile(path: string, content: string): Promise<void>;
 }
+/**
+ * Bounded integration-repair (design: search 2026-06-14, Codex-reviewed). When the merged tree applies
+ * cleanly but the integration `testCmd` (the oracle gate) FAILS, the leader used to return terminal — a human
+ * read the build error and re-ran (the "11 runs / 6 fixes" loop was human-driven). This closes that gap: a
+ * bounded repair AGENT runs IN the already-merged sandbox (keeps the workers' good output + sees BOTH sides of
+ * a broken cross-worker contract, e.g. the ChannelShelf edge), edits the working tree (NOT commit/push), then
+ * mergeBranches re-runs `testCmd` to verify. Safe degradation: if repair exhausts rounds / errors, the result
+ * is today's `phase:"test"` failure plus repair metadata — never worse than terminal-fail. ⚠️ repair on a
+ * COMPILE-only `testCmd` can push green-but-incorrect code (oracle-quality, not repair, problem) — pair with a
+ * real hidden-oracle `measureCmd`/L3 when correctness (not just compile) must close.
+ */
 export interface IntegrationRepair {
+    /** Max repair attempts before giving up (each = one agent run + one testCmd re-run). */
     maxRounds: number;
+    /** Run the repair agent against the live merged tree. Edits the working tree to make `testCmd` pass; MUST
+     *  NOT commit or push (mergeBranches squashes worker+repair edits into one commit at the end). Returns its
+     *  spend + a short note; mergeBranches re-runs `testCmd` to decide if the fix actually worked. */
     run(ctx: {
         round: number;
         errorText: string;
@@ -24,8 +56,22 @@ export interface IntegrationRepair {
         note?: string;
     }>;
 }
+/**
+ * Bounded merge-conflict resolution (search 2026-06-16). Symmetric with {@link IntegrationRepair}: when a worker's
+ * patch CONFLICTS on `git apply --3way` (overlapping edits a sibling already touched), run a bounded agent IN the
+ * integration sandbox to integrate THIS worker's patch — instead of the leader discarding ALL fan-out work and
+ * redoing the whole task as one fresh worker (collapseToSingle, leader.ts: "correctness over thrift; half-done
+ * adoption is future"). The agent merges the in-tree conflict markers + applies the `.rej` hunks; mergeBranches
+ * then VERIFIES no marker/.rej remains before continuing, and the downstream test gate still guards correctness.
+ * Wired by the caller (provisionIntegrationSandbox); when unset, an apply conflict stays terminal exactly as before
+ * (zero behaviour change). Reuses the IntegrationRepair sandbox + hands pattern → no new core/env seam (the seam
+ * design/68 §8 feared for "adopting N half-done workspaces" is unnecessary for the conflict case).
+ */
 export interface ConflictResolver {
+    /** Max resolution attempts before giving up (each = one agent run + one marker/.rej re-check). */
     maxRounds: number;
+    /** Run the resolver agent against the live conflicted tree. Edits the working tree to integrate the worker's
+     *  patch + removes the `.rej`/`.orig` files; MUST NOT commit / push / add (the merge squashes at the end). */
     run(ctx: {
         round: number;
         workerId: string;
@@ -38,13 +84,22 @@ export interface ConflictResolver {
     }>;
 }
 export interface MergeDeps {
+    /** Pull one worker's patch from ITS container (M2 pullDiff bound to the worker's env). */
     pullWorkerDiff(report: WorkerReport): Promise<PullDiffResult>;
+    /** Provision a fresh ephemeral no-net/no-creds sandbox with the base repo at `baseSha` already in place.
+     *  `repair` (optional) enables bounded integration-repair on a `testCmd` failure (see {@link IntegrationRepair});
+     *  unset → a failing integration test is terminal (the pre-2026-06-14 behavior, unchanged). */
     provisionIntegrationSandbox(): Promise<{
         env: IntegrationEnv;
         destroy: () => Promise<void>;
         repair?: IntegrationRepair;
         conflictResolver?: ConflictResolver;
     }>;
+    /**
+     * The CREDENTIALED push, done by the Coordinator (control plane), NOT the sandbox (council#1). Takes the
+     * integrated patch (the sandbox's combined diff over base) + the base it forked from; applies to the
+     * Coordinator's own trusted clone and pushes `--force-with-lease=<ref>:<baseSha>`. `raced` = lease reject.
+     */
     push(integratedPatch: string, baseSha: string): Promise<{
         ok: true;
         ref: string;
@@ -53,16 +108,51 @@ export interface MergeDeps {
         raced?: boolean;
         error: string;
     }>;
+    /** Repo dir inside the sandbox (default /repo). */
     repoDir?: string;
+    /** Full test command run in the sandbox (the merge gate). */
     testCmd: string;
+    /** Optional truecorrect MEASURE (design/59): a thorough hidden-oracle command run IN the integration sandbox
+     *  (E2B) right after the gate passes — offloads the measure from the CPU-contended control plane (the
+     *  frontier-multi oracle-timeout fix). NOT a gate (does not affect `ok`); the result lands in MergeResult.measure
+     *  for the caller to read as the objective truly-correct signal. Same place + env as the gate, just a thornier test. */
     measureCmd?: string;
+    /**
+     * LEADER-REPAIRLOOP-INTEGRATION §10.3 — push-hold-on-SIGNAL master flag (the wire sets it from
+     * `LEADER_MEASURE_GATES`, default OFF). When OFF (the default) the push path is BYTE-IDENTICAL to today: the
+     * `measureCmd` stays observe-only and a compile-only-green merge auto-pushes. When ON, a configured strong
+     * oracle that is NOT green HOLDS the push (→ `candidate_only`, no push): the hold keys on the SIGNAL, not a
+     * caller field — `strongOracleSeeded` (an oracleFiles-backed hidden held-out oracle is in the sandbox) OR
+     * (`measureCmd` present AND its measure did not pass). Auto-push only when every configured strong signal is
+     * GREEN; absent BOTH → legacy compile-only auto-push (§10.3). */
     measureGates?: boolean;
+    /**
+     * §10.3 — set by the wire when an oracleFiles-backed hidden held-out oracle was seeded into the integration
+     * sandbox (`wire.ts` `injectOracles`). Under `measureGates`, a seeded-but-only-`testCmd`-green merge is a
+     * strong-oracle-UNCONFIRMED result → the push is HELD (`candidate_only`). The merge module cannot see the
+     * oracleFiles itself (a wire concern), so the wire reports their presence here. Default unset/false → today's
+     * behavior. */
     strongOracleSeeded?: boolean;
+    /**
+     * §10.4 measure-drives-repair — the out-of-process measure grader (R2) + the changed-files allowlist. When set
+     * (and `measureGates` ON) a `measure`-FAIL re-seeds this SINGLE minted grader (`git reset --hard <integBase>` +
+     * `git clean -fdx`, re-apply the integrated patch) and re-runs the trusted `measureCmd` THERE — never in the
+     * repair-edited (possibly poisoned) merge sandbox (§10.4(i)). Before re-measuring, the integrated patch's
+     * changed-file list is mechanically checked against `allowlist` (the workers' planned `files` ∪ trusted spec
+     * dirs): an out-of-allowlist / build-config touch downgrades the candidate to `needs_human_oracle` (§10.4(ii)).
+     * The grader handle is bound by the wire (a re-seedable integration-equivalent sandbox). Unset → no measure
+     * grader; the measure stays observe-only (today's path). */
     measureDrivesRepair?: {
+        /** The out-of-process grader handle (re-seedable; mirrors the integration sandbox, oracle-seeded). */
         grader: GraderHandle;
+        /** The trusted, spec-derived measure steps run in the grader (NEVER worker-authored). */
         measureSteps: import("@sema-agent/core").ExecStep[];
+        /** §10.4(ii): the changed-files allowlist = the workers' planned `files` ∪ trusted spec dirs. */
         allowlist: string[];
+        /** Bounded measure-repair rounds (re-seed + re-measure). Each round optionally drives the existing
+         *  integration `repair` agent first; 0/unset → grade once, no repair. */
         maxRounds?: number;
+        /** Parse the integrated patch into a changed-file list (the wire binds `git apply --numstat` / name-only). */
         changedFiles: (integratedPatch: string) => Promise<string[]>;
     };
     logger?: {
@@ -70,6 +160,9 @@ export interface MergeDeps {
         info?: (m: string, x?: Record<string, unknown>) => void;
     };
 }
+/** Integration-repair outcome (when `MergeDeps.provisionIntegrationSandbox` supplied a `repair`): how many
+ *  rounds ran, whether the post-repair `testCmd` finally passed, and the repair spend. `outsidePlannedFiles`
+ *  is honest accounting — repaired files are NOT attributed to the original disjoint workers. */
 export interface RepairMeta {
     rounds: number;
     fixed: boolean;
@@ -105,5 +198,6 @@ export type MergeResult = {
         reason?: string;
     };
 };
+/** Integrate completed workers' branches. Never throws — failures are typed MergeResult. */
 export declare function mergeBranches(reports: WorkerReport[], baseSha: string, deps: MergeDeps): Promise<MergeResult>;
 //# sourceMappingURL=merge.d.ts.map

package/dist/leader/merge.js

@@ -1,15 +1,23 @@
 import { delimitUntrusted } from "@sema-agent/core";
 import { applyAndGrade, changedFilesOutOfAllowlist } from "./grader-env-factory.js";
-const Q = (s) => `'${s.replace(/'/g, "'\\''")}'`;
+const Q = (s) => `'${s.replace(/'/g, "'\\''")}'`; // single-quote for shell safety
+/** Integrate completed workers' branches. Never throws — failures are typed MergeResult. */
 export async function mergeBranches(reports, baseSha, deps) {
     const repo = deps.repoDir ?? "/repo";
     const mergeable = reports.filter((r) => r.status === "completed");
     if (mergeable.length === 0) {
         return { ok: false, phase: "no-workers", reason: "no completed workers to merge", quarantine: reports.map((r) => r.workerId) };
     }
+    // The whole pipeline is wrapped so this function honours its "never throws" contract AND never leaks the
+    // integration sandbox: provisioning (which connects+seeds a billable VM) and pullWorkerDiff used to run
+    // OUTSIDE the try, so a throw there (e.g. seed failure) escaped as an exception and — worse — left a
+    // connected sandbox with no `destroy` ever called. `destroy` is captured the instant provisioning resolves,
+    // and the finally tears it down on every path (success / typed failure / thrown error).
     let destroy;
+    // Track the current stage so a THROWN error is attributed to the right phase (not always "provision").
     let phase = "diff-out";
     try {
+        // 1. pull each worker's diff OUT of its container (M2). A failed diff quarantines that worker, aborts merge.
         const patches = [];
         for (const r of mergeable) {
             const d = await deps.pullWorkerDiff(r);
@@ -18,24 +26,35 @@ export async function mergeBranches(reports, baseSha, deps) {
             }
             patches.push({ workerId: r.workerId, patch: d.patch });
         }
+        // 2. ephemeral no-creds integration sandbox (destroyed in finally — council#15).
         phase = "provision";
         const integ = await deps.provisionIntegrationSandbox();
         destroy = integ.destroy;
         const { env } = integ;
+        // The sandbox's base commit ≠ the durable remote's `baseSha` (different repos). Capture the sandbox's
+        // pre-apply HEAD so `format-patch <integBase>..HEAD` captures the integration commit even though the
+        // commit advances the sandbox's branch (dogfood-surfaced: `main..HEAD` was empty). `baseSha` is used
+        // ONLY for the durable push CAS below.
         const integBase = (await env.exec("git rev-parse HEAD", { cwd: repo })).stdout.trim();
+        // 3. apply each patch --3way (council#3: keeps conflict context; capture .rej on failure, quarantine).
         phase = "apply";
         const conflictsResolved = [];
-        let conflictResolverCostUsd = 0;
+        let conflictResolverCostUsd = 0; // 🔴 capture the bounded conflict-resolver agent's spend (was dropped → S1 TEAM-cost undercount)
         for (const p of patches) {
             const patchPath = `/tmp/${p.workerId}.patch`;
             await env.writeFile(patchPath, p.patch);
             const ap = await env.exec(`git apply --3way --whitespace=nowarn ${Q(patchPath)}`, { cwd: repo });
             if (ap.exitCode !== 0) {
                 const rej = await env.exec(`find . -name '*.rej' -print -exec cat {} +`, { cwd: repo }).catch(() => ({ stdout: "", stderr: "", exitCode: -1 }));
+                // Bounded conflict-resolution (search 2026-06-16): a --3way conflict left markers/.rej in the tree. Instead
+                // of discarding ALL fan-out work + redoing single (leader collapseToSingle), run a bounded agent IN this
+                // sandbox to integrate THIS worker's patch (siblings already applied clean), gated by a marker/.rej re-check
+                // and the downstream test gate. Symmetric with integration-repair; OFF unless a conflictResolver is wired;
+                // degrades to the original apply-failure (collapse) on any leftover/agent-error — never worse than baseline.
                 const cr = integ.conflictResolver && integ.conflictResolver.maxRounds > 0
                     ? await resolveApplyConflict(env, repo, p, rej.stdout, ap.stderr, integ.conflictResolver, deps)
                     : { resolved: false, costUsd: 0 };
-                conflictResolverCostUsd += cr.costUsd;
+                conflictResolverCostUsd += cr.costUsd; // count the spend even when resolution failed (tokens were spent)
                 if (!cr.resolved) {
                     deps.logger?.warn?.("merge_apply_failed", { workerId: p.workerId, exitCode: ap.exitCode });
                     return { ok: false, phase: "apply", reason: `git apply --3way failed for ${p.workerId} (conflict)`, quarantine: [p.workerId], rej: rej.stdout, details: ap.stderr.slice(0, 800), ...(conflictResolverCostUsd > 0 ? { conflictResolverCostUsd } : {}) };
@@ -43,8 +62,15 @@ export async function mergeBranches(reports, baseSha, deps) {
                 conflictsResolved.push(p.workerId);
             }
         }
+        // 4. full test suite IN the sandbox = the merge gate (untrusted diff stays sandboxed — [26]§16).
+        // testCmd is a caller-provided COMMAND LINE (e.g. "cd x && pytest"), run verbatim by design — NOT a single
+        // arg, so it is intentionally not Q()-quoted (council round-2 noted the asymmetry). Blast radius = the
+        // ephemeral no-creds sandbox; the caller owns the command (trusted control-plane config).
         phase = "test";
         let test = await env.exec(deps.testCmd, { cwd: repo });
+        // Bounded integration-repair (search 2026-06-14): a clean-merge-but-failing-build used to be terminal.
+        // If the sandbox supplied a `repair`, run the repair agent IN this merged tree (it edits the working tree;
+        // the squash commit below captures worker patches + repair together), then re-run testCmd. Up to maxRounds.
         let repairMeta;
         if (test.exitCode !== 0 && integ.repair && integ.repair.maxRounds > 0) {
             let cost = 0;
@@ -58,7 +84,7 @@ export async function mergeBranches(reports, baseSha, deps) {
                 }
                 catch (e) {
                     deps.logger?.warn?.("integration_repair_error", { round: round + 1, err: e instanceof Error ? e.message : String(e) });
-                    break;
+                    break; // a thrown repair agent → stop repairing; fall through to the (still-failing) terminal return
                 }
                 test = await env.exec(deps.testCmd, { cwd: repo });
             }
@@ -68,14 +94,29 @@ export async function mergeBranches(reports, baseSha, deps) {
         if (test.exitCode !== 0) {
             return { ok: false, phase: "test", reason: `integration test failed (exit ${test.exitCode})`, details: (test.stdout + "\n" + test.stderr).slice(-2000), ...(repairMeta ? { repair: repairMeta } : {}), ...(conflictResolverCostUsd > 0 ? { conflictResolverCostUsd } : {}) };
         }
+        // 4b. truecorrect MEASURE (design/59) — run the thorough hidden oracle IN this sandbox (E2B), where the merged
+        // code already lives, NOT on the CPU-contended control plane (fixes the frontier-multi oracle spawn-timeout
+        // that thinned n). Pure observation: never gates `ok`, just reports into MergeResult.measure.
         let measure;
         if (deps.measureCmd) {
             const mr = await env.exec(deps.measureCmd, { cwd: repo });
             measure = mr.exitCode === 0 ? { pass: true } : { pass: false, reason: (mr.stdout + " " + mr.stderr).slice(-200) };
         }
+        // 5. produce the integrated patch over base, hand to the Coordinator's credentialed push (council#1).
+        // Check the commit's exit code: if `git add -A`/commit fails, HEAD doesn't advance and `format-patch`
+        // still exits 0 with EMPTY output — pushing an empty patch would no-op or corrupt the merge silently.
         phase = "push";
+        // If integration-repair ran, a repair agent may have created commits despite the instruction not to. Flatten
+        // any such commits back to the working tree (Codex review #2) so the single `commit` below squashes worker
+        // patches + repair edits into ONE integration commit — otherwise format-patch would emit the repair commit
+        // PLUS an empty leader commit, and the Coordinator's `git am` can choke on the empty patch. No-op when no
+        // repair commits exist (HEAD already == integBase).
         if (repairMeta)
             await env.exec(`git reset --soft ${Q(integBase)}`, { cwd: repo });
+        // Cost legs that MUST ride EVERY push-phase failure return (wq64gmm5e HIGH: TEAM C1 undercount). A
+        // conflictResolver and/or integration-repair may already have spent real tokens BEFORE any push-phase
+        // failure; dropping these on the commit/format-patch/empty/race/push-fail returns made captureTeamC1
+        // undercount the arm. Mirror the success/hold/test-fail returns exactly.
         const costTail = { ...(repairMeta ? { repair: repairMeta } : {}), ...(conflictResolverCostUsd > 0 ? { conflictResolverCostUsd } : {}) };
         const commit = await env.exec(`git add -A && git -c user.email=leader@local -c user.name=leader commit -m ${Q(`merge: integrate ${mergeable.map((r) => r.workerId).join("+")}`)} --allow-empty`, { cwd: repo });
         if (commit.exitCode !== 0) {
@@ -88,9 +129,17 @@ export async function mergeBranches(reports, baseSha, deps) {
         if (!integrated.stdout.trim()) {
             return { ok: false, phase: "push", reason: "integrated patch is empty (nothing applied over base) — refusing to push", quarantine: mergeable.map((r) => r.workerId), ...costTail };
         }
+        // ── §10.6 THE PUSH CHOKEPOINT + §10.3 push-hold-on-signal + §10.4 measure-drives-repair ──
+        // A single gate covering EVERY push path by construction (collapse `leader.ts:451` + N=1 `leader.ts:508`):
+        // the credentialed push fires ONLY when (a) no mergeable report carries a non-auto-accepting
+        // `repairTerminal` (§10.6 — the SAFE-tier `candidate_only` that the status collapse to "completed" would
+        // otherwise hide), AND (b) under `LEADER_MEASURE_GATES`, every configured strong oracle signal is GREEN
+        // (§10.3). When any of these HOLDS, the push is withheld and the held, DELIMITED candidate is surfaced for
+        // human acceptance (a candidate is never a silent push and never a silent drop — §5 invariant). With
+        // `measureGates` OFF and no report carrying a `repairTerminal`, this whole block is inert → byte-identical.
         const evald = await evaluatePushHold(env, repo, mergeable, measure, integrated.stdout, deps);
         if (evald.measure !== undefined)
-            measure = evald.measure;
+            measure = evald.measure; // §10.4: the out-of-process re-measure supersedes the observe-only one
         if (evald.hold) {
             const h = evald.hold;
             deps.logger?.warn?.("merge_push_held", { terminal: h.terminal, reason: h.reason.slice(0, 200) });
@@ -113,51 +162,103 @@ export async function mergeBranches(reports, baseSha, deps) {
         return { ok: true, ref: push.ref, merged: mergeable.map((r) => r.workerId), ...(measure ? { measure } : {}), ...(repairMeta ? { repair: repairMeta } : {}), ...(conflictsResolved.length > 0 ? { conflictsResolved } : {}), ...(conflictResolverCostUsd > 0 ? { conflictResolverCostUsd } : {}) };
     }
     catch (e) {
+        // Honour the "never throws" contract: a thrown pullWorkerDiff/provision/exec becomes a typed failure,
+        // attributed to the stage it threw in (not a blanket "provision").
         return { ok: false, phase, reason: `merge aborted in ${phase}: ${e instanceof Error ? e.message : String(e)}`, quarantine: mergeable.map((r) => r.workerId) };
     }
     finally {
+        // council#15: destroy the sandbox on EVERY exit path. Guarded because we may bail (diff-out) or throw
+        // BEFORE provisioning — `destroy` is only set once provisionIntegrationSandbox has resolved.
         if (destroy)
             await destroy().catch(() => { });
     }
 }
+/**
+ * §10.6 + §10.3 + §10.4 — the push chokepoint decision (pure-ish: reads the reports + the optional measure grader;
+ * never throws — a grader error falls back to a HOLD, never a silent push). Returns `{ hold }` to WITHHOLD the
+ * credentialed push, surfacing the held candidate; `{}` to allow it. Three independent hold triggers:
+ *
+ *   §10.6 — any mergeable report carries a `repairTerminal ∉ {undefined, "fixed"}`. A SAFE-tier `candidate_only`
+ *           maps to core verdict "PASS" → the report status collapses to "completed", so WITHOUT this gate the
+ *           merge would push `testCmd`-green-but-strong-oracle-UNCONFIRMED work. This fires regardless of
+ *           `measureGates` (the single-agent repair loop is itself OFF-by-default behind LEADER_REPAIR_LOOP — once
+ *           a report carries a repairTerminal, the operator opted in; the candidate MUST be held). Covers the
+ *           collapse-to-single and N=1 leader paths by construction.
+ *
+ *   §10.3 — under `measureGates` ONLY: a configured STRONG oracle that is not GREEN holds the push. The hold keys
+ *           on the SIGNAL not a caller field: (`strongOracleSeeded`) OR (`measureCmd` present AND the measure did
+ *           not pass). Absent BOTH strong signals → no §10.3 hold (legacy compile-only auto-push). With
+ *           `measureGates` OFF this trigger is inert (today's observe-only measure).
+ *
+ *   §10.4 — under `measureGates` AND `measureDrivesRepair`: re-seed the SINGLE out-of-process grader, mechanically
+ *           check the integrated patch's changed files against the allowlist (out-of-allowlist / build-config →
+ *           downgrade to `needs_human_oracle`), then re-measure THERE (never the repair-poisoned merge sandbox).
+ *           A still-failing re-measure holds (`candidate_only`); a passing re-measure clears the §10.3 measure
+ *           signal (so the §10.3 trigger no longer holds on it).
+ */
 async function evaluatePushHold(env, repo, mergeable, observeMeasure, integratedPatch, deps) {
+    // §10.7 — the integrated patch is worker-authored code reaching a human-read HTTP body / durable-approval row.
     const heldCandidate = () => delimitUntrusted("CANDIDATE PATCH (untrusted worker code)", integratedPatch);
+    // §10.6 — a non-auto-accepting single-agent repair terminal rode in on a report (status collapsed to
+    // "completed"). The strongest non-fixed terminal wins the label (it's the WHY surfaced to the human).
     const carried = mergeable.map((r) => r.repairTerminal).filter((t) => t !== undefined && t !== "fixed");
     if (carried.length > 0) {
-        const terminal = carried[0];
+        const terminal = carried[0]; // every mergeable solo report shares one repairTerminal (N=1 / collapse-solo)
         return { hold: { reason: `single-agent repair terminal '${terminal}' — strong oracle unconfirmed, push held for human acceptance (§10.6)`, terminal, candidatePatch: heldCandidate() } };
     }
+    // §10.3/§10.4 are OFF unless the master measure-gates flag is on → byte-identical default path.
     if (!deps.measureGates)
         return {};
     let measure = observeMeasure;
+    // §10.4 measure-drives-repair: re-measure the integrated patch in a FRESH-seeded out-of-process grader, with the
+    // mechanical changed-files allowlist guard. Runs only when configured AND there is a measure to re-confirm.
     if (deps.measureDrivesRepair && deps.measureCmd) {
         const mdr = deps.measureDrivesRepair;
         try {
+            // §10.4(ii) — mechanical allowlist FIRST (a fresh sandbox is necessary-not-sufficient: poison can ride
+            // INSIDE the integrated patch). An out-of-allowlist / build-config touch → downgrade to needs_human_oracle.
             const changed = await mdr.changedFiles(integratedPatch);
             const offending = changedFilesOutOfAllowlist(changed, mdr.allowlist);
             if (offending.length > 0) {
                 deps.logger?.warn?.("merge_measure_allowlist_denied", { offending: offending.slice(0, 20) });
                 return { hold: { reason: `integrated patch touches out-of-allowlist / build-config paths (${offending.slice(0, 5).join(", ")}) — needs_human_oracle (§10.4(ii))`, terminal: "needs_human_oracle", candidatePatch: heldCandidate() }, measure };
             }
+            // Re-seed the SINGLE grader + re-measure THERE (never the repair-edited merge sandbox — §10.4(i)). The
+            // existing in-sandbox `repair` agent already ran in `mergeBranches`; the grader re-measure is the
+            // authoritative correctness signal. (Bounded measure-repair rounds beyond the existing integration-repair
+            // are a future enable; v1 re-measures once.)
             const grade = await applyAndGrade(mdr.grader, integratedPatch, mdr.measureSteps);
             measure = grade.passed ? { pass: true } : { pass: false, reason: (grade.trace ?? "measure failed in out-of-process grader").slice(-200) };
             deps.logger?.info?.("merge_measure_grader", { passed: grade.passed, applied: grade.applied });
         }
         catch (e) {
+            // Fail-CLOSED (never a silent push): a grader transport/exec error holds the push as needs_human_oracle.
             deps.logger?.warn?.("merge_measure_grader_error", { err: e instanceof Error ? e.message : String(e) });
+            // §10.7 — surfaced reason is a trusted constant; the untrusted error detail is in the warn log above.
             return { hold: { reason: `measure grader errored — needs_human_oracle (§10.4)`, terminal: "needs_human_oracle", candidatePatch: heldCandidate() }, measure };
         }
     }
+    // §10.3 — push-hold on the SIGNAL. Auto-push only when every configured strong signal is GREEN.
     const measureFailing = deps.measureCmd !== undefined && measure?.pass !== true;
-    const strongOracleUnconfirmed = deps.strongOracleSeeded === true;
+    const strongOracleUnconfirmed = deps.strongOracleSeeded === true; // a hidden held-out oracle was seeded but only testCmd cleared
     if (measureFailing || strongOracleUnconfirmed) {
+        // §10.7 — the surfaced `reason` reaches a human-read HTTP body / durable-approval row, so it is built from
+        // TRUSTED constants ONLY; the untrusted measure output tail (`measure.reason`) stays in the logs, NEVER
+        // interpolated into a human-/LLM-reachable string.
         const why = measureFailing ? "measure did not pass" : "hidden held-out oracle seeded but only the compile gate cleared";
         deps.logger?.warn?.("merge_push_held_signal", { why, measureReason: (measure?.reason ?? "").slice(0, 200) });
         return { hold: { reason: `strong oracle unconfirmed: ${why} — candidate_only, push held (§10.3)`, terminal: "candidate_only", candidatePatch: heldCandidate() }, measure };
     }
     return { measure };
 }
+/** Bounded resolution of a `git apply --3way` conflict (search 2026-06-16). The failed apply left conflict markers
+ *  in-tree and/or `.rej` files. Run the resolver agent up to maxRounds, then VERIFY the tree is conflict-free (no
+ *  `<<<<<<<`/`>>>>>>>` markers, no `*.rej`). Returns true iff clean → the patch is treated as applied and the merge
+ *  continues, KEEPING every other worker's clean work. Any agent error / leftover marker → false → the caller falls
+ *  back to today's apply-failure (collapse-to-single). Never worse than the baseline. */
 async function resolveApplyConflict(env, repo, p, rejText, applyStderr, resolver, deps) {
+    // 🔴 Accumulate + RETURN the resolver's spend (it used to return only a boolean → the cost was dropped, the S1
+    // TEAM-cost-undercount bug). Counts every round, including the round that throws (the tokens were spent).
     let costUsd = 0;
     const conflictText = `git apply --3way could not cleanly apply worker '${p.workerId}'.\n--- apply stderr ---\n${applyStderr.slice(0, 1500)}\n--- reject hunks (*.rej) ---\n${rejText.slice(0, 3000)}`;
     for (let round = 0; round < resolver.maxRounds; round++) {
@@ -168,8 +269,10 @@ async function resolveApplyConflict(env, repo, p, rejText, applyStderr, resolver
         }
         catch (e) {
             deps.logger?.warn?.("merge_conflict_repair_error", { workerId: p.workerId, err: e instanceof Error ? e.message : String(e) });
-            return { resolved: false, costUsd };
+            return { resolved: false, costUsd }; // a thrown resolver → give up, fall back to collapse
         }
+        // Resolved iff NO conflict markers and NO .rej files remain under the repo. `grep -rIlE` LEADS the command so a
+        // mock/impl can distinguish this verify from the `.rej` CAPTURE in mergeBranches; non-empty stdout = still dirty.
         const check = await env
             .exec(`grep -rIlE '^(<<<<<<<|>>>>>>>)' . 2>/dev/null; find . -name '*.rej' 2>/dev/null | head -20`, { cwd: repo })
             .catch(() => ({ exitCode: -1, stdout: "DIRTY", stderr: "" }));
@@ -179,6 +282,6 @@ async function resolveApplyConflict(env, repo, p, rejText, applyStderr, resolver
             return { resolved: true, costUsd };
         }
     }
-    return { resolved: false, costUsd };
+    return { resolved: false, costUsd }; // still conflicted after maxRounds
 }
 //# sourceMappingURL=merge.js.map

package/dist/leader/planner.d.ts

@@ -1,23 +1,75 @@
+/**
+ * v2 MVP — LLM Planner (design/50 §3: leader = LLM-planner that splits a DAG + deterministic Coordinator).
+ * Decomposes an objective into N **disjoint-file** sub-tasks via one model completion, then VALIDATES the plan
+ * deterministically (the trust boundary: an LLM proposes, the Coordinator enforces — service[19] leaderless-
+ * leader). Disjoint file-ownership is the invariant that lets workers run in parallel + merge without conflict.
+ *
+ * The model call is injected (`runPlan: prompt → text`) so this is pure + mock-tested; wire.ts binds it to a
+ * real Runner completion. Invalid/overlapping plans throw a clear error → the leader returns plan-failed
+ * (never a half-valid fan-out).
+ */
 import type { SubtaskSpec } from "./leader.js";
 export interface PlanOptions {
+    /** Max sub-tasks the planner may emit (guards a runaway fan-out). Default 6. */
     maxSubtasks?: number;
+    /** Extra repo/context guidance appended to the prompt (e.g. file layout, conventions). */
     context?: string;
+    /** Deployment knob (design/68 §11 A6, correctness-first): `false` = never fan out — `routePlan` skips the
+     *  router model call entirely and returns the deterministic single route (zero routing cost, zero risk of a
+     *  false fan-out). Default (undefined/true) = the router decides. */
     fanoutEnabled?: boolean;
+    /** Economic guard threshold (design/68 §7, search[83] ruling): an objective SHORTER than this never reaches
+     *  the router — deterministic single (a small task can't be economically decomposable; false-single is the
+     *  cheap error side). Default 64 — deliberately below the route corpus's smallest fan-out case. */
     minFanoutChars?: number;
 }
+/**
+ * Deterministic economic 防灾 guard (design/68 §7 / §11 D2, search [83] ruling (b)): the asymmetry is that a
+ * false fan-out is the -98% disaster while a false single merely runs slower — so every case decidable WITHOUT
+ * the model resolves to single, for free. Pure function (unit-testable); the semantic judgments (sequential/
+ * coupled/uncertain) stay with the router LLM, and "估不准回 single" is the collapse fallback (B3).
+ */
 export declare function economicGuard(objective: string, opts?: PlanOptions): {
     single: true;
     reason: string;
 } | {
     single: false;
 };
+/** The deterministic SINGLE route: one sub-task owning the whole objective (the same shape the router emits
+ *  for its single decision — N=1 runs through the identical leader pipeline). */
 export declare function singleRoute(objective: string): SubtaskSpec[];
+/** The planning prompt: asks for a strict JSON array of disjoint-file sub-tasks. */
 export declare function planPrompt(objective: string, opts?: PlanOptions): string;
+/** Parse + VALIDATE a planner completion into SubtaskSpec[]. Throws on any violation (disjointness etc.). */
 export declare function parsePlan(raw: string, opts?: PlanOptions): SubtaskSpec[];
+/**
+ * Deterministically validate an array of sub-tasks (the trust boundary — see file header). Used both for the
+ * LLM planner output AND for caller-supplied `body.subtasks`, which would otherwise skip every invariant: the
+ * `branch` is interpolated into a worker-container shell command (`git checkout -b <branch>`), so an
+ * unvalidated branch (`x; curl …|sh`, `` `reboot` ``, `--upload-pack=…`) would inject; and the disjoint-file /
+ * unique-id invariants are what the Coordinator's parallel-merge depends on. Throws on any violation.
+ */
 export declare function validateSubtasks(arr: unknown, opts?: PlanOptions): SubtaskSpec[];
+/** Run the planner: one model completion → validated disjoint-file sub-tasks. */
 export declare function llmPlan(objective: string, runPlan: (prompt: string) => Promise<string>, opts?: PlanOptions): Promise<SubtaskSpec[]>;
+/**
+ * The DIFFICULTY-ROUTER prompt (search [43], planner-light). Same disjoint-subtask contract as `planPrompt`,
+ * but the model FIRST routes: default to a SINGLE agent (one sub-task owning the whole task) and only fan out
+ * when the objective is CLEARLY + ECONOMICALLY decomposable (disjoint files, independent/non-sequential, each
+ * part buildable without most of the same context). The campaign proved forcing fan-out on a sequential/coupled
+ * task is a -98% disaster, so the bias is firmly toward single. The output is still a plain disjoint-file
+ * sub-task array — a 1-element array IS the single route (the leader runs N=1 through the same pipeline).
+ */
 export declare function routePrompt(objective: string, opts?: PlanOptions): string;
+/** Run the difficulty router: one model completion → a routed plan (1 sub-task = single route, N = fan-out),
+ *  validated by `parsePlan` (the same disjointness/shape invariants the Coordinator depends on). */
 export declare function routePlan(objective: string, runRoute: (prompt: string) => Promise<string>, opts?: PlanOptions): Promise<SubtaskSpec[]>;
+/**
+ * Decomposer quality gate (design/68 §5/§11 B1-B3): run the router, and on a rejected/unparseable plan retry
+ * the LLM AT MOST ONCE, then COLLAPSE TO SINGLE (never fail the task on a bad plan — single is almost always
+ * the right fallback, and a false fan-out is the -98% disaster; a plan failure must not be louder than that).
+ * `collapsed` carries the reason (observability: a collapse is a router-quality signal, not silent).
+ */
 export declare function routePlanWithFallback(objective: string, runRoute: (prompt: string) => Promise<string>, opts?: PlanOptions): Promise<{
     subs: SubtaskSpec[];
     collapsed?: string;

package/dist/leader/planner.js

@@ -1,3 +1,9 @@
+/**
+ * Deterministic economic 防灾 guard (design/68 §7 / §11 D2, search [83] ruling (b)): the asymmetry is that a
+ * false fan-out is the -98% disaster while a false single merely runs slower — so every case decidable WITHOUT
+ * the model resolves to single, for free. Pure function (unit-testable); the semantic judgments (sequential/
+ * coupled/uncertain) stay with the router LLM, and "估不准回 single" is the collapse fallback (B3).
+ */
 export function economicGuard(objective, opts = {}) {
     if (opts.fanoutEnabled === false)
         return { single: true, reason: "fan-out disabled by deployment (A6)" };
@@ -8,9 +14,12 @@ export function economicGuard(objective, opts = {}) {
     }
     return { single: false };
 }
+/** The deterministic SINGLE route: one sub-task owning the whole objective (the same shape the router emits
+ *  for its single decision — N=1 runs through the identical leader pipeline). */
 export function singleRoute(objective) {
     return [{ workerId: "main", branch: "worker/main", files: ["."], spec: { objective } }];
 }
+/** The planning prompt: asks for a strict JSON array of disjoint-file sub-tasks. */
 export function planPrompt(objective, opts = {}) {
     const max = opts.maxSubtasks ?? 6;
     return [
@@ -24,6 +33,7 @@ export function planPrompt(objective, opts = {}) {
         `Rules: workerId unique + url-safe; files non-empty + disjoint across ALL sub-tasks; objective self-contained.`,
     ].filter(Boolean).join(" ");
 }
+/** Extract a JSON array from a model completion (tolerates ```json fences / surrounding prose). */
 function extractJsonArray(raw) {
     const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
     const candidate = (fenced ? fenced[1] : raw).trim();
@@ -38,11 +48,20 @@ function extractJsonArray(raw) {
         throw new Error("planner output is not valid JSON");
     }
 }
+/** Parse + VALIDATE a planner completion into SubtaskSpec[]. Throws on any violation (disjointness etc.). */
 export function parsePlan(raw, opts = {}) {
     return validateSubtasks(extractJsonArray(raw), opts);
 }
+/**
+ * Deterministically validate an array of sub-tasks (the trust boundary — see file header). Used both for the
+ * LLM planner output AND for caller-supplied `body.subtasks`, which would otherwise skip every invariant: the
+ * `branch` is interpolated into a worker-container shell command (`git checkout -b <branch>`), so an
+ * unvalidated branch (`x; curl …|sh`, `` `reboot` ``, `--upload-pack=…`) would inject; and the disjoint-file /
+ * unique-id invariants are what the Coordinator's parallel-merge depends on. Throws on any violation.
+ */
 export function validateSubtasks(arr, opts = {}) {
     const max = opts.maxSubtasks ?? 6;
+    // "plan" not "planner" — this also validates caller-supplied body.subtasks, not just LLM output.
     if (!Array.isArray(arr) || arr.length === 0)
         throw new Error("plan must be a non-empty array of sub-tasks");
     if (arr.length > max)
@@ -70,6 +89,8 @@ export function validateSubtasks(arr, opts = {}) {
             seenFiles.add(norm);
         }
         const branch = typeof e.branch === "string" && e.branch.trim() ? e.branch.trim() : `worker/${workerId}`;
+        // Reject a leading "-" (would be parsed as an option by `git checkout -b <branch>`), ".." (ref escape), and
+        // an over-long ref (git rejects it anyway; cap keeps the value tidy). The char set is shell-safe.
         if (branch.length > 200 || !/^[A-Za-z0-9._/-]+$/.test(branch) || branch.startsWith("-") || branch.includes("..")) {
             throw new Error(`sub-task ${workerId}: invalid branch`);
         }
@@ -78,10 +99,19 @@ export function validateSubtasks(arr, opts = {}) {
     }
     return subs;
 }
+/** Run the planner: one model completion → validated disjoint-file sub-tasks. */
 export async function llmPlan(objective, runPlan, opts = {}) {
     const raw = await runPlan(planPrompt(objective, opts));
     return parsePlan(raw, opts);
 }
+/**
+ * The DIFFICULTY-ROUTER prompt (search [43], planner-light). Same disjoint-subtask contract as `planPrompt`,
+ * but the model FIRST routes: default to a SINGLE agent (one sub-task owning the whole task) and only fan out
+ * when the objective is CLEARLY + ECONOMICALLY decomposable (disjoint files, independent/non-sequential, each
+ * part buildable without most of the same context). The campaign proved forcing fan-out on a sequential/coupled
+ * task is a -98% disaster, so the bias is firmly toward single. The output is still a plain disjoint-file
+ * sub-task array — a 1-element array IS the single route (the leader runs N=1 through the same pipeline).
+ */
 export function routePrompt(objective, opts = {}) {
     const max = opts.maxSubtasks ?? 6;
     return [
@@ -104,25 +134,39 @@ export function routePrompt(objective, opts = {}) {
         `Rules: always a JSON ARRAY (SINGLE = one element, not a bare object); workerId unique + url-safe; files non-empty + DISJOINT across ALL elements; each objective self-contained.`,
     ].filter(Boolean).join(" ");
 }
+/** Run the difficulty router: one model completion → a routed plan (1 sub-task = single route, N = fan-out),
+ *  validated by `parsePlan` (the same disjointness/shape invariants the Coordinator depends on). */
 export async function routePlan(objective, runRoute, opts = {}) {
     if (opts.fanoutEnabled === false)
-        return singleRoute(objective);
+        return singleRoute(objective); // A6: deploy-disabled fan-out → no router call
     const raw = await runRoute(routePrompt(objective, opts));
     return parsePlan(raw, opts);
 }
+/**
+ * Decomposer quality gate (design/68 §5/§11 B1-B3): run the router, and on a rejected/unparseable plan retry
+ * the LLM AT MOST ONCE, then COLLAPSE TO SINGLE (never fail the task on a bad plan — single is almost always
+ * the right fallback, and a false fan-out is the -98% disaster; a plan failure must not be louder than that).
+ * `collapsed` carries the reason (observability: a collapse is a router-quality signal, not silent).
+ */
 export async function routePlanWithFallback(objective, runRoute, opts = {}) {
-    const guard = economicGuard(objective, opts);
+    const guard = economicGuard(objective, opts); // deterministic 防灾经济 cases never pay for a router call
     if (guard.single)
         return { subs: singleRoute(objective) };
     let firstErr;
-    let firstRaw = "";
+    let firstRaw = ""; // capture the raw completion of the FIRST failed attempt for diagnosis (see below)
     for (let attempt = 0; attempt < 2; attempt++) {
+        // §5: no more than ONE LLM re-plan
         const raw = await runRoute(routePrompt(objective, opts));
         try {
             return { subs: parsePlan(raw, opts) };
         }
         catch (e) {
             firstErr ??= e;
+            // Capturing the raw output on collapse is load-bearing for diagnosis: a collapse logs only "not valid
+            // JSON", and the router runs on an in-memory (non-durable) session, so the raw completion is otherwise
+            // GONE — task#2d's flaky collapse could not be root-caused because nothing recorded the bad output. Keep
+            // a bounded head+tail so the next collapse is diagnosable (truncated/unterminated vs unescaped-quote vs
+            // prose) without dumping a 32k-token runaway in full.
             if (!firstRaw)
                 firstRaw = raw.length > 600 ? `${raw.slice(0, 300)}…[${raw.length}ch]…${raw.slice(-150)}` : raw;
         }