@sema-agent/server 1.322.0 → 2.0.0

package/dist/leader/endpoint.js

@@ -1,4 +1,19 @@
+/**
+ * v2 MVP M4 — leader HTTP endpoint (V2-MVP-PLAN.md). Exposes `runLeaderTask` over HTTP:
+ *   POST /v1/leader        → 202 { leaderRunId, status:"running" }, runs in the background
+ *   GET  /v1/leader/:id     → { id, status, result?, error? }
+ * A leader run is long (minutes: provision N E2B workers → real model coding → merge → push), so it is async
+ * (background + poll), mirroring /v1/runs. `runLeader` is injected (the real wiring lives in wire.ts /
+ * main.ts) so this handler is pure + mock-tested. MVP tracking is in-memory (single-replica); a TiDB-backed
+ * leader-run store is the cross-replica follow-up (same shape as run-store).
+ */
 import { uuidv7 } from "@sema-agent/core";
+/**
+ * LEADER-REPAIRLOOP-INTEGRATION §5/§10.6 — map a finished `LeaderResult` to the run status. The repair terminal
+ * (set only when LEADER_REPAIR_LOOP/LEADER_MEASURE_GATES drove a single-agent path or the merge push chokepoint
+ * held) refines the legacy `ok ? completed : failed` into a THIRD `needs_human` for an ABSTAIN (a held candidate
+ * awaiting a human), keeping `oracle.unprotected`/`gave_up` as `failed` (carry the terminal as the WHY —
+ * no-silent-failures). Undefined `repairTerminal` ⇒ the exact legacy mapping (byte-identical default path). */
 function statusForLeaderResult(result) {
     switch (result.repairTerminal) {
         case "candidate_only":
@@ -9,13 +24,17 @@ function statusForLeaderResult(result) {
         case "gave_up":
             return "failed";
         default:
+            // `fixed` (not reachable SAFE-tier) or undefined → the legacy ok-based mapping.
             return result.ok ? "completed" : "failed";
     }
 }
 const LEADER_ID_RE = /^\/v1\/leader\/([^/]+)$/;
+/** How long a FINISHED leader run stays pollable before it's evicted from the in-memory registry. */
 const RUN_RETENTION_MS = 60 * 60_000;
 export function createLeaderEndpoint(runLeader, opts = {}) {
     const runs = new Map();
+    // Bound the in-memory registry: a finished leader run stays pollable for RUN_RETENTION_MS, then is evicted.
+    // Swept on each POST (amortized, no timer) so the map can't grow without limit over a long-lived process.
     function reap() {
         const cutoff = Date.now() - RUN_RETENTION_MS;
         for (const [id, run] of runs) {
@@ -37,12 +56,13 @@ export function createLeaderEndpoint(runLeader, opts = {}) {
             }
             reap();
             const id = uuidv7();
-            runs.set(id, { id, status: "running", startedAt: Date.now(), owner: requester ?? null });
+            runs.set(id, { id, status: "running", startedAt: Date.now(), owner: requester ?? null }); // BL-4: record owner
+            // fire-and-forget; status polled via GET. Never throws out of the handler.
             void (async () => {
                 try {
                     const result = await runLeader(b);
                     const run = runs.get(id);
-                    run.status = statusForLeaderResult(result);
+                    run.status = statusForLeaderResult(result); // §10.6: ok→completed/failed PLUS needs_human for a held candidate
                     run.result = result;
                     run.finishedAt = Date.now();
                     opts.logger?.info?.("leader_run_done", { id, ok: result.ok, status: run.status, ...(result.repairTerminal ? { repairTerminal: result.repairTerminal } : {}), merged: result.merge && result.merge.ok ? result.merge.merged : undefined });
@@ -62,6 +82,9 @@ export function createLeaderEndpoint(runLeader, opts = {}) {
             const run = runs.get(m[1]);
             if (!run)
                 return { status: 404, body: { error: "leader run not found", errorCode: "not_found.leader_run" } };
+            // BL-4 owner check: an owned run is visible ONLY to its owner — 404 (not 403) to anyone else, so a
+            // non-owner can't even confirm the id exists. owner null/undefined = anonymous/single-tenant run,
+            // visible to any authenticated caller (back-compat; mirrors GET /v1/runs/:id's runOwnerOk).
             if (run.owner != null && run.owner !== (requester ?? null)) {
                 return { status: 404, body: { error: "leader run not found", errorCode: "not_found.leader_run" } };
             }

package/dist/leader/fanout.d.ts

@@ -1,16 +1,54 @@
+/**
+ * v2 MVP — leader fan-out composition layer (design/50 §3, V2-MVP-PLAN.md M1, core seam).
+ *
+ * Runs N sub-task workers in parallel over `runner.runTaskStream` sharing ONE AbortController, bounded by a
+ * Semaphore, with an overall deadline (no infinite wait — council#5), a concurrency claim (run-store
+ * createRun unique-key CAS — the rule-5 dual-session tax solved at worker scale), and a
+ * `cancelAll` that ABORTS first (stopping not-yet-started workers + aborting running ones) then interrupts the
+ * snapshot — closing the late-registration race (council round-2). Returns a typed WorkerReport per worker (council#6 — the
+ * Coordinator needs a defined shape to route diffs in merge(b)).
+ *
+ * cancelAll uses `TaskStream.destroy()` (core 1.71): abort + await run-settle + CAS-expire the checkpoint
+ * (fencing any concurrent resume) + reap a SUSPENDED worker's paused container — closing the interim-`interrupt()`
+ * gap (a cancel hitting a suspended worker no longer leaks a paused container or an orphan checkpoint). Per core's
+ * contract, `destroy()` reaps the CHECKPOINT; the leader (leader.ts) still owns + destroys each worker's static env
+ * in its own finally (the two are disjoint). Verified on real E2B+TiDB by the suspended-cancel dogfood.
+ *
+ * MVP scope: the COMPOSITION mechanics, unit-tested with a mock runner. Real E2B workers + branch/baseSha from
+ * a worker's actual git state are wired at M4/M5 (joint dogfood).
+ */
 import type { TaskSpec, TaskResult, TaskStream, RepairTerminal } from "@sema-agent/core";
+/** What the Coordinator gets back per worker (council#6 — merge(b) routes on this). */
 export interface WorkerReport {
     workerId: string;
     sessionId: string;
+    /** completed = mergeable; failed/suspended/timeout/rejected = not merged (quarantined). */
     status: "completed" | "failed" | "suspended" | "timeout" | "rejected";
+    /** Worker's branch + the base it forked from — drives the merge(b) `git format-patch <baseSha>` diff-out. */
     branch?: string;
     baseSha?: string;
     error?: string;
+    /** The worker's TaskResult.stats (tokens/cost/turns) — for the value-campaign cost accounting. */
     stats?: TaskResult["stats"];
+    /** design/52 L3a module sub-gate: did this worker's module pass the per-module judge (after any repair)? */
     moduleJudge?: "pass" | "fail";
+    /** Number of bounded repairs the module sub-gate spent on this worker (0 = passed first try). */
     repairs?: number;
+    /** design/74 Slice 6: the terminal checkpoint gate when a worker is still SUSPENDED (the leader auto-resumed
+     *  it up to its bound but it didn't fully complete — e.g. the overall deadline hit or the slice cap). Present
+     *  ⇒ resumable: the operator/leader can escalate (more budget) or accept the belt-diff partial progress. */
     checkpointGate?: TaskResult["checkpointGate"];
+    /** design/74 Slice 6: the worker's terminal `TaskResult.errorCode` (e.g. `budget.exceeded` on an exhausted
+     *  resume, `limit.max_turns`) — surfaced for /v1/leader observability. */
     errorCode?: TaskResult["errorCode"];
+    /** LEADER-REPAIRLOOP-INTEGRATION §10.6 (THE push chokepoint): the `runRepairLoop` terminal a single-agent
+     *  worker resolved to, when the repair loop ran on this worker (LEADER_REPAIR_LOOP on). It MUST ride on the
+     *  report because a SAFE-tier `candidate_only` maps to core verdict "PASS" → this report's `status` collapses
+     *  to "completed" (there is no `candidate_only` status member) → the candidate state would otherwise be LOST,
+     *  and `merge.ts:226` would push `testCmd`-green-but-unconfirmed work. The merge push chokepoint gates on this
+     *  field (fires only when no mergeable report carries `repairTerminal ∉ {undefined, "fixed"}`), covering the
+     *  collapse-to-single and N=1 paths by construction. `status` stays "completed" for back-compat; this is the
+     *  WHY. Undefined ⇒ the repair loop did not run (the default, byte-identical path). */
     repairTerminal?: RepairTerminal;
 }
 export interface FanOutSubtask {
@@ -18,29 +56,51 @@ export interface FanOutSubtask {
     sessionId: string;
     baseSha?: string;
     branch?: string;
+    /** The sub-task spec MINUS the fields fan-out owns (sessionId + signal are injected per worker). */
     spec: Omit<TaskSpec, "sessionId" | "signal">;
 }
+/** Only the two TaskStream methods fan-out consumes (the real core TaskStream satisfies this). */
 export type FanOutStream = Pick<TaskStream, "result" | "destroy">;
 export interface RunnerLike {
     runTaskStream(spec: TaskSpec): FanOutStream;
 }
+/** Concurrency claim (run-store `createRun` unique-key CAS). Returns false = a duplicate spawn lost the claim. */
 export type ClaimFn = (workerId: string, sessionId: string) => Promise<boolean>;
 export interface FanOutOptions {
     runner: RunnerLike;
+    /** Overall fan-out deadline (ms). On expiry → cancelAll, the still-running workers are cancelled. */
     timeoutMs: number;
+    /** Grace (ms) after cancelAll before fanOut returns regardless — HARD-bounds a worker that ignores the abort.
+     *  Default {@link CANCEL_GRACE_MS}. The un-settled workers are reported `timeout`. */
     cancelGraceMs?: number;
+    /** Semaphore cap on concurrent workers (MVP = 2; structure scales to N). */
     maxConcurrency: number;
+    /** Optional concurrency claim; omitted = always-claim (single-session MVP). */
     claim?: ClaimFn;
     logger?: {
         warn?: (msg: string, meta?: Record<string, unknown>) => void;
         info?: (msg: string, meta?: Record<string, unknown>) => void;
     };
+    /** Optional per-worker run override (e.g. runWithVerification). When set, runOne routes through THIS instead of
+     *  the default runTaskStream-and-map — still bounded by the semaphore, the overall timeout→cancelAll, and the
+     *  claim. Lets the verify path reuse fan-out's concurrency/timeout/cancellation rather than an unbounded
+     *  Promise.all (council). The override receives the shared abort signal; pass it into the run so a hung or
+     *  cancelled worker actually aborts (else the overall-timeout's `await work` can never unblock). Like the default
+     *  path it need not catch — runOne maps a throw to failed/timeout. */
     runWorker?: (st: FanOutSubtask, signal: AbortSignal) => Promise<WorkerReport>;
+    /** Replan-lite C4 (design/68 §6): when a worker settles SUSPENDED, immediately cancelAll the rest — the
+     *  suspended worker itself has already settled (its stream is deregistered), so the cancel sweep cannot
+     *  touch its checkpoint/paused env (the destroy-exemption falls out of the registration lifecycle). */
     cancelOnSuspend?: boolean;
 }
 export interface FanOutResult {
     reports: WorkerReport[];
+    /** True if the overall deadline fired and cancelAll ran. */
     cancelled: boolean;
 }
+/**
+ * Fan out `subtasks` in parallel. Never throws — every worker resolves to a WorkerReport (failures captured).
+ * The caller (Coordinator) merges only `status==="completed"` reports.
+ */
 export declare function fanOut(subtasks: FanOutSubtask[], opts: FanOutOptions): Promise<FanOutResult>;
 //# sourceMappingURL=fanout.d.ts.map

package/dist/leader/fanout.js

@@ -1,3 +1,4 @@
+/** A tiny counting semaphore (FIFO-ish) bounding concurrent worker execution. */
 class Semaphore {
     max;
     active = 0;
@@ -21,17 +22,30 @@ class Semaphore {
 function mapStatus(s) {
     return s === "completed" ? "completed" : s === "suspended" ? "suspended" : "failed";
 }
+/**
+ * Fan out `subtasks` in parallel. Never throws — every worker resolves to a WorkerReport (failures captured).
+ * The caller (Coordinator) merges only `status==="completed"` reports.
+ */
 export async function fanOut(subtasks, opts) {
     const sharedAC = new AbortController();
     const streams = new Map();
     let cancelled = false;
     const cancelAll = async () => {
         cancelled = true;
+        // Abort FIRST (council round-2): one signal both aborts RUNNING workers (their shared spec.signal) AND
+        // stops NOT-YET-STARTED ones — runOne's `sharedAC.signal.aborted` guard returns before provisioning a VM.
+        // Closes the race where a worker registering AFTER the snapshot would miss it. Then destroy() each registered
+        // stream (core 1.71): abort + await settle + CAS-expire the checkpoint (fences any concurrent resume) + reap
+        // a SUSPENDED worker's paused container — so a cancel that hits a suspended worker leaks neither a paused
+        // container nor an orphan checkpoint. The leader (leader.ts) still destroys each worker's static env in its
+        // own finally; destroy() here reaps the (durable) checkpoint — the two are disjoint (core [R47]).
         sharedAC.abort();
         await Promise.allSettled([...streams.values()].map((s) => s.destroy()));
     };
     const sem = new Semaphore(opts.maxConcurrency);
     let pendingCancel;
+    // C4: a SUSPENDED settle preempts the remaining fan-out (the settled worker is already out of `streams`,
+    // so cancelAll's destroy sweep is exempt of it by construction — its checkpoint/paused env survive).
     const maybeCancelOnSuspend = (r) => {
         if (opts.cancelOnSuspend && r.status === "suspended" && !cancelled) {
             opts.logger?.info?.("fanout_suspend_cancel", { suspendedWorker: r.workerId });
@@ -41,12 +55,15 @@ export async function fanOut(subtasks, opts) {
     };
     const runOne = async (st) => {
         const base = { workerId: st.workerId, sessionId: st.sessionId, branch: st.branch, baseSha: st.baseSha };
+        // Concurrency claim (CAS) BEFORE provisioning — a lost claim means a duplicate spawn; skip, don't run.
         if (opts.claim && !(await opts.claim(st.workerId, st.sessionId))) {
             return { ...base, status: "rejected", error: "claim lost (duplicate spawn)" };
         }
         return sem.run(async () => {
             if (sharedAC.signal.aborted)
                 return { ...base, status: "timeout", error: "cancelled before start" };
+            // Per-worker run override (verify path): reuse the semaphore + shared abort signal; map throws like the
+            // default path so runOne still never rejects (Promise.all stays safe).
             if (opts.runWorker) {
                 try {
                     return maybeCancelOnSuspend(await opts.runWorker(st, sharedAC.signal));
@@ -69,24 +86,32 @@ export async function fanOut(subtasks, opts) {
                 report = { ...base, status: mapStatus(result.status), stats: result.stats, ...(result.errorMessage ? { error: result.errorMessage } : {}) };
             }
             catch (e) {
+                // interrupted/aborted workers may reject here — report, don't propagate.
                 report = { ...base, status: cancelled ? "timeout" : "failed", error: e instanceof Error ? e.message : String(e) };
             }
             finally {
                 streams.delete(st.workerId);
             }
+            // AFTER deregistration — so a suspend-triggered cancelAll can never destroy THIS worker's own stream
+            // (destroying a suspended stream = CAS-expiring its checkpoint, the exact thing C4 forbids).
             return maybeCancelOnSuspend(report);
         });
     };
+    // Record each worker's report as it settles so the overall deadline can HARD-bound the wait: if a worker's
+    // stream.result() ignores the abort, `Promise.all(work)` would never resolve and `await work` below would hang
+    // PAST the deadline (the overall timeout would be only "soft"). On the grace expiry we return whatever settled
+    // + a synthesized `timeout` for the rest, so fanOut always returns within timeoutMs + the cancel grace.
     const results = new Map();
     const work = Promise.all(subtasks.map((st) => runOne(st).then((r) => { results.set(st.workerId, r); return r; })));
     const timer = new Promise((resolve) => {
         const id = setTimeout(() => resolve("timeout"), opts.timeoutMs);
-        void work.then(() => clearTimeout(id));
+        void work.then(() => clearTimeout(id)); // don't leak the timer when work finishes first
     });
     const raced = await Promise.race([work.then(() => "done"), timer]);
     if (raced === "timeout") {
         opts.logger?.warn?.("fanout_timeout", { timeoutMs: opts.timeoutMs, workers: subtasks.length });
         await cancelAll();
+        // Hard bound: give cancelAll a grace window to settle the running workers, then stop waiting regardless.
         const graceMs = opts.cancelGraceMs ?? CANCEL_GRACE_MS;
         const grace = new Promise((resolve) => {
             const id = setTimeout(() => resolve("grace"), graceMs);
@@ -100,10 +125,11 @@ export async function fanOut(subtasks, opts) {
             };
         }
     }
-    const reports = await work;
+    const reports = await work; // all settled (normal path, or cancelled workers settled within grace)
     if (pendingCancel)
-        await pendingCancel.catch(() => { });
+        await pendingCancel.catch(() => { }); // suspend-triggered sweep fully settled before return
     return { reports, cancelled };
 }
+/** Grace window after `cancelAll` before fanOut returns regardless — bounds a worker that ignores the abort. */
 const CANCEL_GRACE_MS = 30_000;
 //# sourceMappingURL=fanout.js.map

package/dist/leader/grader-env-factory.d.ts

@@ -1,36 +1,110 @@
+/**
+ * The OUT-OF-PROCESS grader plumbing for the leader × `runRepairLoop` integration
+ * (`docs/LEADER-REPAIRLOOP-INTEGRATION.md` §3.2 + the authoritative §10 layer). Two distinct consumers:
+ *
+ *  - **R1 (single-agent oracle, §10.1)** — the `RepairOracle` closure (`repair-oracle.ts`) reuses the EXISTING
+ *    integration sandbox as its grader at ZERO extra sandbox cost. It needs only a `GraderHandle` (a writeFile +
+ *    exec bound to that sandbox via the wire's `asIntegrationEnv`/`sh` pattern) and the worker-diff source — it
+ *    grades through `runExecGate(graderEnv, steps)` itself, so it does NOT use `applyAndGrade` (the closure owns
+ *    its hermetic reset+apply inline; `repair-oracle.ts:89`). This file gives the merge path the SAME apply-and-
+ *    grade primitive so the two stay byte-consistent.
+ *
+ *  - **R2 (measure-drives-repair, §10.4)** — the merge path (`merge.ts`, Stage-2) RE-SEEDS a single minted
+ *    grader per measure round (NOT a new microVM): `git reset --hard <integBase> && git clean -fdx`, re-apply the
+ *    INTEGRATED patch, then run the trusted `measureCmd` there. The repair agent edits the merged sandbox, so the
+ *    measure must NOT run in that (possibly poisoned) sandbox — `applyAndGrade` runs it in a fresh-seeded grader.
+ *    Before re-measure, the caller mechanically checks the patch's changed-file list against an allowlist
+ *    (`changedFilesWithinAllowlist`, §10.4(ii)) — an out-of-allowlist / build-config touch denies the candidate.
+ *
+ * The standalone, mint-a-distinct-sandbox grader factory (`createGraderEnvFactory`) is the AUTO-ACCEPT slice path
+ * (flag `LEADER_GRADER_FACTORY`, default OFF until the §7 OFF-Gate-1 end-to-end verification). It is documented +
+ * stubbed here, NOT wired — v1 reuses the integration sandbox (R1) + re-seeds it (R2) instead.
+ *
+ * Everything here is additive + OFF by default: nothing in this file runs unless the Stage-2 seams call it behind
+ * `LEADER_REPAIR_LOOP` / `LEADER_MEASURE_GATES` / `LEADER_GRADER_FACTORY`.
+ */
 import { type ExecutionEnv, type ExecStep } from "@sema-agent/core";
+/**
+ * A grader env bound to a concrete sandbox. The wire constructs this from the integration sandbox's
+ * `RemoteExecutionEnv` (the `asIntegrationEnv`/`sh` pattern in `wire.ts`), so `grader-env-factory.ts` never
+ * depends on the adapter/wire module (no cycle). `env` is the core `ExecutionEnv` `runExecGate` grades in;
+ * `writeFile` plants the candidate patch into the grader tree; `repoDir`/`integBase` are the hermetic reset
+ * target (§10.1) — `git rev-parse HEAD` taken right after seed + oracle-inject (`merge.ts:137` pattern).
+ */
 export interface GraderHandle {
+    /** The isolated grader env (the reused integration sandbox for R1, a fresh-minted one for the auto-accept slice). */
     env: ExecutionEnv;
+    /** Write a file into the grader tree (the wire binds this to the sandbox's `writeFile`). */
     writeFile: (path: string, content: string) => Promise<void>;
+    /** Repo dir inside the grader (e.g. `/repo`). */
     repoDir: string;
+    /** The grader's CLEAN base rev — the hermetic reset target (§10.1). Re-applies run base→latest, never cumulative. */
     integBase: string;
 }
+/** The outcome of one `applyAndGrade` round: whether the trusted steps passed + a failure trace tail (untrusted). */
 export interface GradeOutcome {
+    /** True iff the prep applied cleanly AND every trusted step ran and exited 0. */
     passed: boolean;
+    /** False when the patch failed to apply onto the clean base (an apply conflict) — distinct from a step failure. */
     applied: boolean;
+    /** Failure-output tail (untrusted worker-adjacent data; the caller delimits/sanitizes before surfacing). */
     trace?: string;
 }
+/**
+ * §10.1/§10.4 — HERMETIC apply-and-grade. Reset the grader to its clean `integBase` (`git reset --hard` +
+ * `git clean -fdx`), apply the FULL `base→latest` `patch` (never cumulative onto an already-applied tree), then
+ * run the TRUSTED, spec-derived `steps` (`testCmd` / `measureCmd`) there. `steps` MUST NOT be worker-authored
+ * (the `runExecGate` security contract — exec-gate.ts header). Used by the R2 measure grader; the R1 oracle
+ * closure performs the equivalent inline (`repair-oracle.ts`) so the single-agent and merge paths grade
+ * identically. Never throws — an apply conflict or a step failure is a non-passing `GradeOutcome`.
+ */
 export declare function applyAndGrade(handle: GraderHandle, patch: string, steps: ExecStep[]): Promise<GradeOutcome>;
+/** The §10.4(ii) decision: the subset of `changedFiles` that is OUT of the allowlist or hits a build-config deny. */
 export declare function changedFilesOutOfAllowlist(changedFiles: string[], allowlist: string[]): string[];
+/** §10.4(ii): true iff EVERY changed file is within the allowlist and none is a denied build-config path. */
 export declare function changedFilesWithinAllowlist(changedFiles: string[], allowlist: string[]): boolean;
+/**
+ * §3.2 — the FUTURE standalone grader factory (the auto-accept-slice sibling of `main.ts`'s `executionEnvFactory`,
+ * `main.ts:204-249`). Mints a DISTINCT sandbox via the same `e2b/k8sExecutionEnvFactory`, seeds `seedCmd` + the
+ * oracle files ONLY there, and returns a `GraderHandle` with `provenance:"control_plane"`. v1 does NOT mint a
+ * standalone grader (R1 reuses the integration sandbox; R2 re-seeds it) — this is the path the auto-accept slice
+ * (flag `LEADER_GRADER_FACTORY`, default OFF) opens once the §7 OFF-Gate-1 deployment-contract proof lands. It is
+ * a documented STUB (NOT wired): minting + seeding a per-run sandbox is real provisioning work that belongs to the
+ * auto-accept stage, and shipping a half-mint here would be a stopgap (clay rule). The signature is fixed so the
+ * Stage-N auto-accept wiring drops in without a contract change.
+ */
 export interface GraderEnvFactoryCfg {
+    /** Mint a distinct, isolated sandbox env (the same factory the workers/integration sandbox use). */
     mint: (sessionId: string) => {
         env: ExecutionEnv;
         writeFile: (p: string, c: string) => Promise<void>;
         sh: (cmd: string) => Promise<string>;
         destroy: () => Promise<void>;
     };
+    /** Shell to seed the base repo (idempotent) — runs ONLY in the minted grader. */
     seedCmd: string;
+    /** Repo dir inside the grader. */
     repoDir: string;
+    /** Hidden-oracle files seeded ONLY in the grader (never the worker env). */
     oracleFiles?: Array<{
         path: string;
         content: string;
     }>;
 }
+/** §3.2 — a minted standalone grader plus its lifecycle + isolation brand (for the auto-accept slice). */
 export interface MintedGrader extends GraderHandle {
+    /** The control-plane provenance brand (distinguishes a minted grader from the reused integration sandbox). */
     provenance: "control_plane";
+    /** The grader's hidden-oracle paths (passed to `runRepairLoop.immutableOraclePaths` ONLY when the auto-accept
+     *  slice runs the full `assertOracleIsolation` — v1 OMITS these; §10.2). */
     immutableOraclePaths: string[];
+    /** Reap the minted sandbox. */
     destroy: () => Promise<void>;
 }
+/**
+ * §3.2 STUB — build the standalone grader factory. NOT wired in v1 (the auto-accept slice owns it, flag
+ * `LEADER_GRADER_FACTORY`). Throws a clearly-marked not-implemented error if invoked before that slice lands so a
+ * stray call fails loudly rather than silently mis-grading — this is an explicit placeholder, not a quiet stopgap.
+ */
 export declare function createGraderEnvFactory(_cfg: GraderEnvFactoryCfg): () => Promise<MintedGrader>;
 //# sourceMappingURL=grader-env-factory.d.ts.map

package/dist/leader/grader-env-factory.js

@@ -1,9 +1,46 @@
+/**
+ * The OUT-OF-PROCESS grader plumbing for the leader × `runRepairLoop` integration
+ * (`docs/LEADER-REPAIRLOOP-INTEGRATION.md` §3.2 + the authoritative §10 layer). Two distinct consumers:
+ *
+ *  - **R1 (single-agent oracle, §10.1)** — the `RepairOracle` closure (`repair-oracle.ts`) reuses the EXISTING
+ *    integration sandbox as its grader at ZERO extra sandbox cost. It needs only a `GraderHandle` (a writeFile +
+ *    exec bound to that sandbox via the wire's `asIntegrationEnv`/`sh` pattern) and the worker-diff source — it
+ *    grades through `runExecGate(graderEnv, steps)` itself, so it does NOT use `applyAndGrade` (the closure owns
+ *    its hermetic reset+apply inline; `repair-oracle.ts:89`). This file gives the merge path the SAME apply-and-
+ *    grade primitive so the two stay byte-consistent.
+ *
+ *  - **R2 (measure-drives-repair, §10.4)** — the merge path (`merge.ts`, Stage-2) RE-SEEDS a single minted
+ *    grader per measure round (NOT a new microVM): `git reset --hard <integBase> && git clean -fdx`, re-apply the
+ *    INTEGRATED patch, then run the trusted `measureCmd` there. The repair agent edits the merged sandbox, so the
+ *    measure must NOT run in that (possibly poisoned) sandbox — `applyAndGrade` runs it in a fresh-seeded grader.
+ *    Before re-measure, the caller mechanically checks the patch's changed-file list against an allowlist
+ *    (`changedFilesWithinAllowlist`, §10.4(ii)) — an out-of-allowlist / build-config touch denies the candidate.
+ *
+ * The standalone, mint-a-distinct-sandbox grader factory (`createGraderEnvFactory`) is the AUTO-ACCEPT slice path
+ * (flag `LEADER_GRADER_FACTORY`, default OFF until the §7 OFF-Gate-1 end-to-end verification). It is documented +
+ * stubbed here, NOT wired — v1 reuses the integration sandbox (R1) + re-seeds it (R2) instead.
+ *
+ * Everything here is additive + OFF by default: nothing in this file runs unless the Stage-2 seams call it behind
+ * `LEADER_REPAIR_LOOP` / `LEADER_MEASURE_GATES` / `LEADER_GRADER_FACTORY`.
+ */
 import { runExecGate } from "@sema-agent/core";
+/** Single-quote a string for safe interpolation into a shell command (mirrors `repair-oracle.ts` / `merge.ts`). */
 const sq = (s) => `'${s.replace(/'/g, "'\\''")}'`;
+/**
+ * §10.1/§10.4 — HERMETIC apply-and-grade. Reset the grader to its clean `integBase` (`git reset --hard` +
+ * `git clean -fdx`), apply the FULL `base→latest` `patch` (never cumulative onto an already-applied tree), then
+ * run the TRUSTED, spec-derived `steps` (`testCmd` / `measureCmd`) there. `steps` MUST NOT be worker-authored
+ * (the `runExecGate` security contract — exec-gate.ts header). Used by the R2 measure grader; the R1 oracle
+ * closure performs the equivalent inline (`repair-oracle.ts`) so the single-agent and merge paths grade
+ * identically. Never throws — an apply conflict or a step failure is a non-passing `GradeOutcome`.
+ */
 export async function applyAndGrade(handle, patch, steps) {
     const repo = handle.repoDir;
     const patchPath = `/tmp/grade-${Date.now()}.patch`;
     await handle.writeFile(patchPath, patch);
+    // Hermetic prep: clean base, then apply the full base→latest diff. `--whitespace=nowarn` matches `merge.ts:144`
+    // and `repair-oracle.ts:93`. An apply failure is a non-flaky, non-applied failure (a candidate that no longer
+    // applies onto the clean base — e.g. it raced the integration head).
     const prep = await runExecGate(handle.env, [
         { command: `git -C ${sq(repo)} reset --hard ${sq(handle.integBase)} && git -C ${sq(repo)} clean -fdx`, label: "grader-reset" },
         { command: `git -C ${sq(repo)} apply --whitespace=nowarn ${sq(patchPath)}`, label: "grader-apply" },
@@ -18,6 +55,21 @@ export async function applyAndGrade(handle, patch, steps) {
     const trace = gate.steps.map((s) => `${s.label}\n${s.stdout}\n${s.stderr}`).join("\n").slice(-4000);
     return { passed: false, applied: true, trace };
 }
+/**
+ * §10.4(ii) — the mechanical CHANGED-FILES ALLOWLIST guard. A "fresh sandbox" is necessary-NOT-sufficient: poison
+ * can ride INSIDE the integrated patch (a malicious `build.gradle` / git hook / test shim). Before re-measuring,
+ * diff the patch's changed-file list against the allowlist = the workers' planned `files` ∪ trusted spec dirs.
+ * Any out-of-allowlist path, or a build-config touch (gradle / settings / dependency manifests / git hooks), is a
+ * DENY — the caller downgrades the candidate to `needs_human_oracle` (the prompt-only "do NOT modify build config"
+ * `wire.ts:269` is unreliable; this makes it mechanical). Returns the offending paths (empty ⇒ within allowlist).
+ *
+ * `changedFiles` is parsed by the caller from the patch (`git apply --numstat` / `git diff --name-only`); this is
+ * the PURE policy over that list so it is unit-testable without a sandbox. Matching is path-prefix on normalized
+ * POSIX paths: an allowlist entry `"."` or `""` allows everything UNDER it (a worker that legitimately owns the
+ * whole tree); a file allow-entry matches exactly; a dir allow-entry (trailing `/` or a real dir) matches its
+ * subtree. Build-config patterns are denied even when nominally within the allowlist (a worker must not be able
+ * to launder a `build.gradle` edit through an over-broad `files:["."]`).
+ */
 const BUILD_CONFIG_DENY = [
     /(^|\/)build\.gradle(\.kts)?$/,
     /(^|\/)settings\.gradle(\.kts)?$/,
@@ -42,11 +94,12 @@ const norm = (p) => p.replace(/^\.\/+/, "").replace(/\/+$/, "");
 function withinAllowEntry(file, entry) {
     const e = norm(entry);
     if (e === "" || e === ".")
-        return true;
+        return true; // owns the whole tree
     if (file === e)
-        return true;
-    return file.startsWith(`${e}/`);
+        return true; // exact file match
+    return file.startsWith(`${e}/`); // subtree match
 }
+/** The §10.4(ii) decision: the subset of `changedFiles` that is OUT of the allowlist or hits a build-config deny. */
 export function changedFilesOutOfAllowlist(changedFiles, allowlist) {
     const files = changedFiles.map(norm).filter((f) => f !== "");
     const offending = [];
@@ -60,9 +113,15 @@ export function changedFilesOutOfAllowlist(changedFiles, allowlist) {
     }
     return offending;
 }
+/** §10.4(ii): true iff EVERY changed file is within the allowlist and none is a denied build-config path. */
 export function changedFilesWithinAllowlist(changedFiles, allowlist) {
     return changedFilesOutOfAllowlist(changedFiles, allowlist).length === 0;
 }
+/**
+ * §3.2 STUB — build the standalone grader factory. NOT wired in v1 (the auto-accept slice owns it, flag
+ * `LEADER_GRADER_FACTORY`). Throws a clearly-marked not-implemented error if invoked before that slice lands so a
+ * stray call fails loudly rather than silently mis-grading — this is an explicit placeholder, not a quiet stopgap.
+ */
 export function createGraderEnvFactory(_cfg) {
     return async () => {
         throw new Error("createGraderEnvFactory: the standalone control-plane grader is the auto-accept slice (LEADER_GRADER_FACTORY) — " +