@yagni-app/code-staging 0.0.0 → 0.1.0-staging.1002.1

package/dist/extension/pipeline/orchestrator.js

@@ -0,0 +1,636 @@
+/**
+ * The pipeline driver.
+ *
+ * Sequences `runStage` for the build stages (map → plan → implement), threading
+ * each stage's `finalOutput` into the next as `{previous}` (mirrors the subagent
+ * example's chain). Then it runs the bounded review→fix LOOP: each round fans the
+ * review stage out across the 3 lenses (parallel, bounded by MAX_CONCURRENCY),
+ * parses each lens with `parseFindings` (with ONE cheap format-recovery re-ask
+ * for a healthy lens that broke the findings contract — spec §3e), unions them,
+ * and asks the PURE `shouldStop`. If not stopped it runs the fix stage against
+ * ONLY the blocking findings, increments the round, and re-reviews.
+ *
+ * ALL branching is delegated to the pure `shouldStop` / `parseFindings`; the
+ * orchestrator is just sequencing + an injectable `runStage`, so it is
+ * unit-tested with a fake `runStage`. The explicit stop reason is always logged
+ * (spec §7.3 — no silent truncation). An early build-stage failure short-circuits
+ * the pipeline by throwing (the /go handler catches and reports it). In the
+ * review→fix loop, a user abort or a crashed review/fix child is surfaced as an
+ * honest `aborted` / `failed` stopReason rather than being mis-read as `clean`
+ * (an aborted/crashed child has empty output, which otherwise parses to zero
+ * findings — i.e. a false "reviewed and clean").
+ */
+import { addRunUsage, aggregateRunUsage, DEFAULT_RUN_BUDGET, EMPTY_RUN_USAGE, exceedsBudget } from "./budget.js";
+import { extractFindingsBlock, hasBlockingFindings, parseFindings, shouldStop, unionFindings } from "./findings.js";
+import { withResilience } from "./resilience.js";
+import { runStage as defaultRunStage } from "./runner.js";
+import { makeRunVerify, parseChangedPaths } from "./verify.js";
+import { REQUIRED_LENSES, REVIEW_LENSES, reaskStage, reviewStage, selectStages } from "./stages.js";
+import { snapshotWorkspace as defaultSnapshotWorkspace, workspaceChanged } from "./workspace.js";
+import { DEFAULT_RESILIENCE_POLICY, MAX_CONCURRENCY, MIN_TOOL_CALLS_FOR_HEALTH, TOOL_ERROR_FAIL_RATE, } from "./types.js";
+/** Error thrown when a build stage fails; carries the partial run for the caller. */
+export class PipelineStageError extends Error {
+    stageId;
+    partial;
+    constructor(stageId, message, partial) {
+        super(message);
+        this.name = "PipelineStageError";
+        this.stageId = stageId;
+        this.partial = partial;
+    }
+}
+const BUILD_STAGE_IDS = ["map", "plan", "implement"];
+/**
+ * Stages whose whole value is in landed edits, so a high tool-error rate there is
+ * a real failure (R3-a). Read-only recon/review stages are intentionally exempt:
+ * a grep/read that misses is normal navigation, not a broken stage.
+ */
+const WRITE_STAGE_IDS = ["implement", "fix"];
+/**
+ * R3-a: true when a WRITE stage exited cleanly yet most of its tool calls errored
+ * — the silent partial-implement landmine, where the model narrates a tidy
+ * summary while its edits never landed. Conservative on purpose: only write
+ * stages are gated, and BOTH a meaningful sample (MIN_TOOL_CALLS_FOR_HEALTH) and
+ * a clear-majority error rate (above TOOL_ERROR_FAIL_RATE) must hold, so a couple
+ * of expected errors never fail a stage.
+ */
+function toolFailureExceeded(r) {
+    if (!WRITE_STAGE_IDS.includes(r.stageId))
+        return false;
+    if (r.toolCalls < MIN_TOOL_CALLS_FOR_HEALTH)
+        return false;
+    return r.toolErrors / r.toolCalls > TOOL_ERROR_FAIL_RATE;
+}
+/** The honest reason string for a tool-failure-flagged stage, else undefined. */
+function toolFailureReason(r) {
+    if (!toolFailureExceeded(r))
+        return undefined;
+    return `tool failures: ${r.toolErrors} of ${r.toolCalls} tool calls errored, so its edits likely did not land despite a clean-looking summary. Re-run /go.`;
+}
+/**
+ * A stage outcome counts as a failure on a non-zero exit, an error/abort stop, or
+ * (for a write stage) a tool-error rate over the threshold (R3-a) — so a stage
+ * that exits 0 while most of its edits failed is not trusted on its prose alone.
+ */
+function isFailed(r) {
+    return r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted" || toolFailureExceeded(r);
+}
+/**
+ * A non-final build stage threads its `finalOutput` forward as the NEXT stage's
+ * only input, so an empty or truncated handoff silently starves it — the bug: a
+ * cut-off plan fed to implement, which then writes nothing and bottoms out at a
+ * confusing `no_changes`. This converts that silent fragment into an honest,
+ * actionable stop the user sees BEFORE implement runs on nothing. Returns the
+ * stop reason when the handoff is unusable, else undefined.
+ *
+ * `length` is pi's max_tokens truncation (the literal "plan appears to be cut
+ * off" case) — a deterministic smoking gun. An empty body is the other half.
+ * We deliberately do NOT content-match a "plan shape" (unreliable, and would
+ * false-positive on legitimately short stages); persona hardening handles the
+ * interstitial-fragment flavor. The FINAL build stage (implement) is exempt: its
+ * real handoff is the working-tree diff, governed by the `no_changes` guard
+ * below, so an empty prose summary there is not a broken handoff.
+ */
+function incompleteHandoff(r) {
+    if (r.stopReason === "length") {
+        return "its output was cut off before it finished (the model reached its length limit), so the handoff to the next stage is incomplete. Re-run /go.";
+    }
+    if (r.finalOutput.trim().length === 0) {
+        return "it finished without producing any output to hand to the next stage. Re-run /go.";
+    }
+    return undefined;
+}
+/**
+ * Credit-exhaustion shapes the model proxy emits when the workspace runs out of
+ * credits: the workspace-budget 402 body ("This workspace is out of credits."),
+ * the OpenAI-style `insufficient_quota` code, and the bare HTTP status. Matched
+ * against stderr/errorMessage only — never a stage's real output.
+ */
+const CREDIT_EXHAUSTION_RE = /out of credits|insufficient_quota|payment required|\b402\b/;
+/**
+ * The silent-402 landmine: when the workspace runs out of credits mid-run, the
+ * proxy 402s every model request, the child pi exits 0 with an EMPTY transcript,
+ * and the run otherwise dies as a confusing `no_changes` / empty-handoff / false
+ * "clean" stop with the real cause buried in stderr. Detect it and stop with an
+ * actionable message instead. Gated on the stage having produced no real output
+ * (or having failed outright) so a healthy stage whose stderr happens to contain
+ * a matching token can never trip it.
+ */
+function creditExhaustionReason(r) {
+    if (r.finalOutput.trim().length > 0 && !isFailed(r))
+        return undefined;
+    const hay = `${r.errorMessage ?? ""}\n${r.stderr}`;
+    if (!CREDIT_EXHAUSTION_RE.test(hay))
+        return undefined;
+    return "the workspace is out of YAGNI credits (the model proxy returned 402). Top up credits, then re-run /go.";
+}
+/** Render only the blocking findings as the fix stage's `{previous}` handoff. */
+function serializeBlocking(findings) {
+    return findings
+        .filter((f) => f.severity === "critical" || f.severity === "high")
+        .map((f) => {
+        const loc = f.file ? `${f.file}${f.line != null ? `:${f.line}` : ""}` : "";
+        return `${f.severity} | ${loc} | ${f.message}`;
+    })
+        .join("\n");
+}
+/** Bounded-concurrency map preserving input order (copied from the subagent example). */
+async function mapWithConcurrencyLimit(items, concurrency, fn) {
+    if (items.length === 0)
+        return [];
+    const limit = Math.max(1, Math.min(concurrency, items.length));
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workers = new Array(limit).fill(null).map(async () => {
+        while (true) {
+            const current = nextIndex++;
+            if (current >= items.length)
+                return;
+            results[current] = await fn(items[current], current);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+export async function runPipeline(ticket, deps) {
+    const log = (event, data) => deps.logger?.(event, data);
+    // R1: wrap the real child runner with in-loop resilience (idle/wall timeout +
+    // transient-only retry) by DEFAULT, so every /go survives a transient blip
+    // across its up-to-8 spawns. A caller that injects its own `runStage` (the unit
+    // tests, a custom lane) bypasses the wrapper untouched. Per-attempt telemetry
+    // rides the existing logger seam, so resume + the checkpoint journal are unaffected.
+    const runStageFn = deps.runStage ??
+        withResilience(defaultRunStage, DEFAULT_RESILIENCE_POLICY, {
+            telemetry: (rec) => log("resilience_attempt", rec),
+        });
+    const snapshotFn = deps.snapshotWorkspace ?? defaultSnapshotWorkspace;
+    const runVerifyFn = deps.runVerify ?? makeRunVerify();
+    const progress = (p) => deps.onProgress?.(p);
+    // Count of record_decision tool calls that completed without error across the
+    // whole run, tapped off the NDJSON stream (spec §3c: the FINISH trailer's
+    // YAGNI-Decisions line). COUNT only — decision ids are not observable without
+    // widening JsonEvent.
+    let decisionsRecorded = 0;
+    // Per-stage runner deps that tag each tapped event with the emitting stage
+    // (and, for the parallel review fan-out, that lens + round). Built fresh per
+    // call so every review lens captures its OWN tag — interleaved parallel events
+    // stay attributed to review/<lens>. The tap is ALWAYS installed (the
+    // decisionsRecorded count must not depend on a caller wiring onEvent);
+    // forwarding to the caller's onEvent stays optional.
+    const stageDepsFor = (tag) => {
+        const onEvent = deps.onEvent;
+        return {
+            cwd: deps.cwd,
+            signal: deps.signal,
+            ...(deps.childEnv ? { env: deps.childEnv } : {}),
+            onEvent: (ev) => {
+                if (ev.type === "tool_execution_end" && ev.toolName === "record_decision" && !ev.isError) {
+                    decisionsRecorded += 1;
+                }
+                onEvent?.(ev, tag);
+            },
+        };
+    };
+    const blockingCount = (findings) => findings.filter((f) => f.severity === "critical" || f.severity === "high").length;
+    // Work-page run-tracking hook: fires at each stage boundary, independent of the
+    // terminal live feed's structured `progress`. Optional + fail-soft via onStage.
+    const stageEvent = (stage, phase, extra) => deps.onStage?.({ stage, phase, ...extra });
+    // The text the stages plan against: the resolved ticket brief (verbatim title +
+    // body) when /go could fetch it, else the raw ticket reference (honest blind).
+    const promptTicket = deps.ticketBrief ?? ticket;
+    // M6: default grounded + the full stage list; the blind eval lane overrides both.
+    const grounded = deps.grounded !== false;
+    const all = deps.stages ?? selectStages("full");
+    // R3-b: aggregate usage ceiling, checked at each stage boundary.
+    const budget = deps.budget ?? DEFAULT_RUN_BUDGET;
+    const buildStages = all.filter((s) => BUILD_STAGE_IDS.includes(s.id));
+    // The last build stage's handoff is the working-tree diff (checked by the
+    // no_changes guard), not its prose; only the earlier stages thread text forward.
+    const finalBuildId = buildStages[buildStages.length - 1]?.id;
+    // Derive review + fix from `all` (not PIPELINE_V1) so the blind eval lane's
+    // grounding-stripped tool lists are honored on these stages too.
+    const review = all.find((s) => s.id === "review") ?? reviewStage();
+    const fix = all.find((s) => s.id === "fix");
+    if (!fix)
+        throw new Error("PIPELINE_V1 is missing the fix stage");
+    // Fail-soft checkpoint helpers (no-op when no store is injected). A checkpoint
+    // write must NEVER break the pipeline, so even a misbehaving store is caught.
+    const meta = deps.checkpointMeta;
+    const writeCheckpoint = (rec) => {
+        try {
+            deps.checkpoint?.record(rec);
+        }
+        catch {
+            /* fail-soft */
+        }
+    };
+    const mkRecord = (kind, extra) => ({
+        v: 1,
+        kind,
+        sessionKey: meta?.sessionKey ?? "",
+        ts: Date.now(),
+        ticket,
+        ...(meta?.runId ? { runId: meta.runId } : {}),
+        ...(meta?.workItemId ? { workItemId: meta.workItemId } : {}),
+        ...(meta?.repo ? { repo: meta.repo } : {}),
+        ...(meta?.branch ? { branch: meta.branch } : {}),
+        ...extra,
+    });
+    const resume = deps.resumeFrom?.mode === "resume_loop" ? deps.resumeFrom : undefined;
+    const stages = [];
+    // Seed the loop state. On resume we re-enter the review→fix loop directly,
+    // carrying the journal's prior rounds for an honest final count; on a fresh run
+    // the build half below fills `reviewInput` from the implement output.
+    const rounds = resume ? [...resume.priorRounds] : [];
+    let round = resume ? resume.round : 1;
+    let reviewInput = resume ? resume.reviewInput : "";
+    let stopReason = "clean";
+    // P4: honest note carried out when the verify gate could not give a verdict on
+    // the final round (no command / unrunnable), so /go never claims a build it did
+    // not actually check. Cleared whenever a later round produces a real verdict.
+    let verifyNote;
+    // The FINAL round's verify command label(s) when it RAN — feeds the FINISH
+    // trailer's `YAGNI-Verify: passed (<cmds>)` honestly (spec §3c). Cleared when
+    // a later round's verify is skipped (the final gate did not actually run).
+    let verifyCommand;
+    // The tree's pre-run dirt (paths already changed before the build half), so the
+    // verify gate scopes to THIS run's own diff. Set on the fresh path once the
+    // baseline snapshot is taken; absent on resume (the build already ran), where the
+    // gate falls back to the whole-tree scope.
+    let baselinePaths;
+    const priorUsage = resume?.priorUsage ?? EMPTY_RUN_USAGE;
+    const currentUsage = () => addRunUsage(priorUsage, aggregateRunUsage(stages, rounds));
+    const overBudget = () => exceedsBudget(currentUsage(), budget);
+    if (resume) {
+        // Resume path: the build half already ran and its diff is in the working
+        // tree (the caller's planResume verified the tree still matches the
+        // checkpoint), so we skip map→plan→implement and the no-op guard entirely.
+        log("pipeline_resume", { round, priorRounds: resume.priorRounds.length });
+        const over = overBudget();
+        if (over) {
+            log("pipeline_stop", { reason: "budget_exceeded", where: "resume", detail: over });
+            progress({ kind: "done", stopReason: "budget_exceeded" });
+            return { stages, rounds, stopReason: "budget_exceeded", findings: rounds[rounds.length - 1]?.findings ?? [], decisionsRecorded };
+        }
+    }
+    else {
+        let previous;
+        // Baseline the working tree BEFORE the (read-only) recon stages so the no-op
+        // guard below can attribute any change to the build half. A git-less / non-repo
+        // cwd yields an untracked snapshot and the guard fails open (see workspace.ts).
+        const beforeBuild = await snapshotFn(deps.cwd, deps.signal);
+        writeCheckpoint(mkRecord("run_start", { snapshot: beforeBuild }));
+        // Record the pre-run dirt so the verify gate scopes to this run's OWN diff.
+        baselinePaths = parseChangedPaths(beforeBuild.status);
+        // Sequential build half — stop at the first failure (mirrors the chain).
+        for (const stage of buildStages) {
+            progress({ kind: "stage_start", stageId: stage.id });
+            stageEvent(stage.id, "start");
+            let r = await runStageFn(stage, { ticket: promptTicket, previous, grounded }, stageDepsFor({ stageId: stage.id }));
+            stages.push(r);
+            log("stage_done", { stageId: stage.id, exitCode: r.exitCode });
+            // Retry a non-final build stage ONCE when it exits cleanly but hands off an
+            // incomplete fragment (length-truncated or empty). A reasoning model that
+            // over-explored and ran out of budget — e.g. a plan ending mid-"let me verify
+            // one more thing" — often converges on a fresh attempt; a task that
+            // systematically won't converge still stops honestly after the retry below.
+            // The final build stage (implement) is exempt: its handoff is the diff, not
+            // prose, so `incompleteHandoff` never flags it.
+            if (!isFailed(r) && stage.id !== finalBuildId && incompleteHandoff(r)) {
+                log("stage_retry", { stageId: stage.id, attempt: 2, reason: "incomplete_handoff", stopReason: r.stopReason });
+                progress({ kind: "stage_start", stageId: stage.id });
+                stageEvent(stage.id, "start");
+                r = await runStageFn(stage, { ticket: promptTicket, previous, grounded }, stageDepsFor({ stageId: stage.id }));
+                stages.push(r);
+                log("stage_done", { stageId: stage.id, exitCode: r.exitCode, attempt: 2 });
+            }
+            const credit = creditExhaustionReason(r);
+            if (isFailed(r)) {
+                const why = credit ?? toolFailureReason(r) ?? (r.errorMessage || r.stderr || r.finalOutput || "(no output)");
+                // A WRITE stage (implement/fix) KILLED mid-work — a timeout or transient blip
+                // that aborted/errored the child once it had begun editing — leaves a real
+                // partial diff in the working tree. R1 deliberately does NOT retry such a stage
+                // (double-apply guard), so don't discard the work as a bare failure: stop with
+                // an honest `partial` outcome that points the user at their tree. Excluded on
+                // purpose: a clean exit-0 stage failed only by the R3-a tool-health gate is the
+                // silent partial-implement landmine (edits never landed), NOT real preservable
+                // work — it keeps the hard-fail. Read-only stages, write stages that changed
+                // nothing, and a user abort also keep the honest hard-fail below. Conservative:
+                // we never feed a possibly-truncated diff into the review loop.
+                const killedMidWork = r.exitCode !== 0 || r.stopReason === "aborted" || r.stopReason === "error";
+                if (killedMidWork &&
+                    !deps.signal?.aborted &&
+                    WRITE_STAGE_IDS.includes(stage.id)) {
+                    const afterFail = await snapshotFn(deps.cwd, deps.signal);
+                    if (workspaceChanged(beforeBuild, afterFail)) {
+                        log("pipeline_partial", { stageId: stage.id, reason: why });
+                        progress({ kind: "done", stopReason: "partial" });
+                        return { stages, rounds, stopReason: "partial", findings: [], decisionsRecorded };
+                    }
+                }
+                log("pipeline_failed", { stageId: stage.id, reason: why });
+                // No structured progress on a build failure: the union has no failed
+                // variant, and the /go handler reports the thrown error + clears the feed.
+                throw new PipelineStageError(stage.id, `Pipeline stopped at ${stage.id}: ${why}`, stages);
+            }
+            // A 402-starved stage exits 0 with an empty transcript (not `isFailed`), so
+            // it would otherwise fall through to the generic empty-handoff / no_changes
+            // stops with the real cause buried. Stop with the actionable message.
+            if (credit) {
+                log("pipeline_failed", { stageId: stage.id, reason: credit });
+                throw new PipelineStageError(stage.id, `Pipeline stopped at ${stage.id}: ${credit}`, stages);
+            }
+            // Honest handoff-completeness guard: a build stage can exit 0 yet hand the
+            // next stage an empty / truncated fragment. Stop honestly here rather than
+            // letting implement run on garbage and bottom out at `no_changes`.
+            if (stage.id !== finalBuildId) {
+                const problem = incompleteHandoff(r);
+                if (problem && stage.id === "plan") {
+                    // The plan's consumer — the worker — is explicitly built to implement from a
+                    // partial or cut-off plan (WORKER_BODY: "if the plan is missing, partial, or
+                    // appears cut off … implement the ticket directly"). GLM-5.2 reliably
+                    // over-reasons this stage into a length-truncation; stopping here throws away
+                    // real partial-plan work and never gives the worker its fallback. So hand the
+                    // partial plan forward and let the worker fill the gaps from the ticket.
+                    log("plan_incomplete_proceeding", { stageId: stage.id, reason: problem });
+                }
+                else if (problem) {
+                    // Other build stages (map) have no such robust downstream consumer, so an
+                    // incomplete handoff still stops honestly here.
+                    log("pipeline_incomplete_handoff", { stageId: stage.id, reason: problem });
+                    throw new PipelineStageError(stage.id, `Pipeline stopped at ${stage.id}: ${problem}`, stages);
+                }
+            }
+            progress({ kind: "stage_done", stageId: stage.id });
+            // The plan finish carries its finalOutput so /go can record the plan onto the
+            // work item; no other boundary streams the full stage text.
+            stageEvent(stage.id, "finish", stage.id === "plan" ? { output: r.finalOutput } : undefined);
+            previous = r.finalOutput;
+            // R3-b: stop honestly if the build half alone blew the run budget.
+            const over = overBudget();
+            if (over) {
+                log("pipeline_stop", { reason: "budget_exceeded", where: stage.id, detail: over });
+                progress({ kind: "done", stopReason: "budget_exceeded" });
+                return { stages, rounds, stopReason: "budget_exceeded", findings: [], decisionsRecorded };
+            }
+        }
+        // No-op guard (spec §7.3 — no silent truncation): the review half is
+        // diff-driven, so an implement stage that exits 0 having changed nothing would
+        // sail through as `clean` (reviewers `git diff`, see nothing, find nothing).
+        // Stop HONESTLY with `no_changes` instead of reporting a false "reviewed and
+        // clean". Skipped (fails open) when the tree state is unknowable — see
+        // workspaceChanged. A user abort mid-build is the more truthful reason.
+        if (deps.signal?.aborted) {
+            log("pipeline_aborted", { phase: "build" });
+            progress({ kind: "done", stopReason: "aborted" });
+            return { stages, rounds, stopReason: "aborted", findings: [], decisionsRecorded };
+        }
+        const afterBuild = await snapshotFn(deps.cwd, deps.signal);
+        if (!workspaceChanged(beforeBuild, afterBuild)) {
+            log("pipeline_stop", { reason: "no_changes" });
+            progress({ kind: "done", stopReason: "no_changes" });
+            return { stages, rounds, stopReason: "no_changes", findings: [], decisionsRecorded };
+        }
+        reviewInput = previous ?? "";
+        // Build half complete + the tree changed: checkpoint the implement output as
+        // the round-1 review handoff so a crash in the (expensive) review loop can
+        // resume here instead of re-running map→plan→implement.
+        writeCheckpoint(mkRecord("build_done", { snapshot: afterBuild, reviewInput, usage: currentUsage() }));
+    }
+    while (true) {
+        progress({ kind: "stage_start", stageId: "review", round });
+        stageEvent("review", "start", { round });
+        // P4 verify runs CONCURRENTLY with the lens fan-out: it is deterministic,
+        // independent of lens output, and the lenses are read-only — the tree it
+        // checks is exactly the tree they review. Run serially it added real wall
+        // time per round (a cold toolchain run costs minutes) that the slower lens
+        // fan-out absorbs entirely. The immediate `.catch` parks a rejection until
+        // the await below (which rethrows it at the same point the serial call
+        // threw), so a seam that rejects mid-fan-out can't crash the process as an
+        // unhandled rejection.
+        let verifyError;
+        const verifyPromise = deps.signal?.aborted
+            ? null
+            : runVerifyFn(deps.cwd, deps.signal, baselinePaths).catch((err) => {
+                verifyError = err ?? new Error("verify failed");
+                return null;
+            });
+        const lensResults = await mapWithConcurrencyLimit(REVIEW_LENSES, MAX_CONCURRENCY, async (lens) => {
+            // Per-lens lifecycle: each lens child is its own agent on the desktop, so it
+            // starts and finishes on its OWN timing rather than the whole fan-out's.
+            // The terminal panel ignores lens-tagged signals and paints one review row.
+            progress({ kind: "stage_start", stageId: "review", lens, round });
+            const lensResult = await runStageFn({ ...review, lens }, { ticket: promptTicket, previous: reviewInput, lens, grounded }, stageDepsFor({ stageId: "review", lens, round }));
+            progress({ kind: "stage_done", stageId: "review", lens, round });
+            return lensResult;
+        });
+        // Credit exhaustion mid-review: a 402-starved lens exits 0 with EMPTY output,
+        // which parses to zero findings — the loop would stop a false "clean" while
+        // every request was failing. Checked on ALL lens results (not just failed
+        // ones) for exactly that reason.
+        const lensCredit = lensResults.map((r) => creditExhaustionReason(r)).find((v) => Boolean(v));
+        if (lensCredit) {
+            stopReason = "failed";
+            log("pipeline_failed", { phase: "review", round, reason: lensCredit });
+            break;
+        }
+        // R2 partial-failure tolerance: split the lens outcomes into healthy vs
+        // failed. A single transient lens failure must NOT discard the lenses that
+        // succeeded, so we parse findings only from the healthy lenses, proceed on
+        // those survivors, and record the skipped lenses as `degradedLenses`. The
+        // round fails only when EVERY lens failed or a REQUIRED lens is the one that
+        // failed (see the health check below). A failed lens has empty/garbage
+        // output, so it is never parsed for findings.
+        const failedLenses = [];
+        const unparseableLenses = [];
+        const perLens = [];
+        for (let i = 0; i < lensResults.length; i++) {
+            const r = lensResults[i];
+            const lens = REVIEW_LENSES[i];
+            if (isFailed(r)) {
+                failedLenses.push(lens);
+                progress({ kind: "stage_done", stageId: "review", lens, round, findings: 0, blocking: 0, degraded: "failed" });
+                continue;
+            }
+            let parsed = parseFindings(r.finalOutput, lens);
+            // Visible signal (not silent): a non-empty reviewer output that parses to
+            // zero findings is a likely format miss, not a guaranteed clean review.
+            if (parsed.length === 0 && r.finalOutput.trim())
+                log("review_parse_warning", { lens });
+            // §3e findings-contract re-ask: a HEALTHY lens whose non-empty prose has
+            // NO ```findings fence broke the output contract (an explicit empty fence
+            // is a real clean review and is left alone). Re-ask that lens ONCE on the
+            // cheap efficient tier — a pure format-recovery pass whose `{previous}` is
+            // the lens's own output — and take whatever it re-emits. Still nothing →
+            // proceed (today's behavior) but record the lens as `<lens> (unparseable)`
+            // in degradedLenses so a zero-findings round built on an unreadable review
+            // is never silent.
+            if (parsed.length === 0 &&
+                r.finalOutput.trim() &&
+                extractFindingsBlock(r.finalOutput) == null &&
+                !deps.signal?.aborted) {
+                const reask = await runStageFn(reaskStage(review), { ticket: promptTicket, previous: r.finalOutput, lens, grounded }, stageDepsFor({ stageId: "review", lens, round }));
+                if (!isFailed(reask))
+                    parsed = parseFindings(reask.finalOutput, lens);
+                log("review_reask", { lens, findings: parsed.length });
+                if (parsed.length === 0)
+                    unparseableLenses.push(lens);
+            }
+            // The count exists only now: findings are parsed after the children return,
+            // so a lens row gains its count a beat after it goes ✔. Honest, not eager.
+            progress({
+                kind: "stage_done",
+                stageId: "review",
+                lens,
+                round,
+                findings: parsed.length,
+                blocking: blockingCount(parsed),
+                ...(unparseableLenses.includes(lens) ? { degraded: "unparseable" } : {}),
+            });
+            perLens.push(parsed);
+        }
+        // P4: the deterministic verify gate runs every round (so a fix that breaks the
+        // build is caught next round) and folds any failure in as critical findings
+        // BEFORE shouldStop, so the loop cannot stop `clean` while the build is broken
+        // and the fix stage receives the real errors via serializeBlocking. Started
+        // above, concurrent with the lens fan-out; awaited (and a seam rejection
+        // rethrown) here. Skipped if the run was already aborting; fail-open (no
+        // findings, honest note) otherwise.
+        let verifyFindings = [];
+        if (verifyPromise) {
+            const verify = await verifyPromise;
+            if (verify === null)
+                throw verifyError;
+            verifyFindings = verify.findings;
+            if (verify.ran) {
+                // A real verdict supersedes any earlier skip note, but a PARTIAL note
+                // from the ran gate (spec §3d: "tests could not run", one package's
+                // check unrunnable) survives honestly — absent reason clears it.
+                verifyNote = verify.reason;
+                verifyCommand = verify.command;
+                log("verify_done", { round, ok: verify.ok, command: verify.command, findings: verify.findings.length });
+            }
+            else if (verify.reason) {
+                verifyNote = verify.reason;
+                verifyCommand = undefined; // the FINAL round's gate did not run
+                log("verify_skipped", { round, reason: verify.reason });
+            }
+        }
+        const findings = unionFindings([...perLens, verifyFindings]);
+        // Two degradation flavors, one honest list (§3e): a failed lens was skipped
+        // outright; an unparseable lens proceeded as zero findings after the re-ask.
+        const degraded = [...failedLenses, ...unparseableLenses.map((l) => `${l} (unparseable)`)];
+        const degradedLenses = degraded.length > 0 ? degraded : undefined;
+        rounds.push({ round, lensResults, findings, ...(degradedLenses ? { degradedLenses } : {}) });
+        log("review_round", {
+            round,
+            findings: findings.length,
+            blocking: hasBlockingFindings(findings),
+            ...(degradedLenses ? { degradedLenses } : {}),
+        });
+        progress({ kind: "findings", round, total: findings.length, blocking: blockingCount(findings) });
+        stageEvent("review", "finish", { round, findings: findings.length });
+        // Honest health check BEFORE trusting the verdict: an aborted or crashed
+        // review must NOT be read as a clean review (empty output → [] findings →
+        // would otherwise stop 'clean'). Mirrors the build half's isFailed guard.
+        // The unhealthy paths intentionally skip the review `stage_done` so the feed
+        // can mark the in-flight stage failed off the closing `done` signal.
+        if (deps.signal?.aborted) {
+            stopReason = "aborted";
+            log("pipeline_aborted", { phase: "review", round });
+            break;
+        }
+        // Fail the round ONLY when every lens failed, or a REQUIRED lens (the one
+        // the loop cannot proceed without, default: correctness) is the one that
+        // failed. Otherwise the surviving lenses carry the round and `degradedLenses`
+        // already records the skip honestly.
+        const requiredFailed = failedLenses.filter((l) => REQUIRED_LENSES.includes(l));
+        if (failedLenses.length === REVIEW_LENSES.length || requiredFailed.length > 0) {
+            stopReason = "failed";
+            log("pipeline_failed", { phase: "review", round, failedLenses, requiredFailed });
+            break;
+        }
+        if (degradedLenses)
+            log("review_degraded", { round, degradedLenses });
+        progress({ kind: "stage_done", stageId: "review", round });
+        // R3-b: stop honestly if the review fan-out pushed the run over budget, before
+        // spending another fix + round. The round's findings are already recorded.
+        const overAfterReview = overBudget();
+        if (overAfterReview) {
+            stopReason = "budget_exceeded";
+            log("pipeline_stop", { reason: "budget_exceeded", phase: "review", round, detail: overAfterReview });
+            break;
+        }
+        const decision = shouldStop(findings, round);
+        if (decision.stop && decision.reason) {
+            stopReason = decision.reason;
+            break;
+        }
+        progress({ kind: "stage_start", stageId: "fix", round });
+        stageEvent("fix", "start", { round });
+        const fixResult = await runStageFn(fix, { ticket: promptTicket, previous: serializeBlocking(findings), grounded }, stageDepsFor({ stageId: "fix", round }));
+        stages.push(fixResult);
+        log("stage_done", { stageId: "fix", exitCode: fixResult.exitCode });
+        if (deps.signal?.aborted) {
+            stopReason = "aborted";
+            log("pipeline_aborted", { phase: "fix", round });
+            break;
+        }
+        // Same silent-402 guard as the lenses: a credit-starved fix exits 0 empty and
+        // would hand the next round an empty reviewInput instead of stopping honestly.
+        const fixCredit = creditExhaustionReason(fixResult);
+        if (fixCredit) {
+            stopReason = "failed";
+            log("pipeline_failed", { phase: "fix", round, reason: fixCredit });
+            break;
+        }
+        if (isFailed(fixResult)) {
+            const why = toolFailureReason(fixResult) ?? (fixResult.errorMessage || fixResult.stderr || "(no output)");
+            // Symmetric with the build-half guard: a fix stage KILLED mid-work (timeout /
+            // transient abort/error) leaves the run's reviewed diff (implement + any prior
+            // accepted rounds) plus a partial fix in the tree. By here the build half has
+            // already changed the tree (we passed the no_changes guard), so there is always
+            // preservable work — report `partial`, not a bare `failed`. A clean exit-0 fix
+            // failed only by the R3-a tool-health gate is the silent landmine (edits never
+            // landed) and keeps the hard `failed`.
+            const fixKilledMidWork = fixResult.exitCode !== 0 || fixResult.stopReason === "aborted" || fixResult.stopReason === "error";
+            if (fixKilledMidWork) {
+                stopReason = "partial";
+                log("pipeline_partial", { phase: "fix", round, reason: why });
+            }
+            else {
+                stopReason = "failed";
+                log("pipeline_failed", { phase: "fix", round, reason: why });
+            }
+            break;
+        }
+        progress({ kind: "stage_done", stageId: "fix", round });
+        stageEvent("fix", "finish", { round });
+        // R3-b: stop honestly if this round crossed the budget, before the next round.
+        const overAfterFix = overBudget();
+        if (overAfterFix) {
+            stopReason = "budget_exceeded";
+            log("pipeline_stop", { reason: "budget_exceeded", phase: "fix", round, detail: overAfterFix });
+            break;
+        }
+        // This whole round (review + fix) completed and the loop will continue, so a
+        // crash now can resume at the NEXT round against this fix's output. Snapshot
+        // the post-fix tree as the resume consistency key.
+        const afterFix = await snapshotFn(deps.cwd, deps.signal);
+        writeCheckpoint(mkRecord("round_done", { round, reviewInput: fixResult.finalOutput, findings, snapshot: afterFix, usage: currentUsage() }));
+        reviewInput = fixResult.finalOutput;
+        round += 1;
+    }
+    log("pipeline_stop", { reason: stopReason, round });
+    progress({ kind: "done", stopReason });
+    return {
+        stages,
+        rounds,
+        stopReason,
+        findings: rounds[rounds.length - 1]?.findings ?? [],
+        decisionsRecorded,
+        ...(verifyNote ? { verifyNote } : {}),
+        ...(verifyCommand ? { verifyCommand } : {}),
+    };
+}
+//# sourceMappingURL=orchestrator.js.map