muonroi-cli 1.8.5 → 1.9.0

package/dist/src/product-loop/plan-adherence-review.js

@@ -0,0 +1,144 @@
+import { spawnSync } from "node:child_process";
+import { getIsolatedTaskDeadlineMs, withDeadlineRace } from "../utils/llm-deadline.js";
+/**
+ * Run an isolated sub-agent with a wall-clock backstop. The review/fix agents
+ * were bare `await`s — a provider that hangs post-stream would wedge the whole
+ * sprint (same class as the impl stall, run mrhc43f0fb9b). On timeout the race
+ * rejects; we convert it into a failure ToolResult so the existing `.success`
+ * paths handle it (review → leave gate; fix → stop the loop) instead of hanging.
+ */
+async function runIsolatedGuarded(run, req, label) {
+    try {
+        return await withDeadlineRace(() => run(req), getIsolatedTaskDeadlineMs(), label);
+    }
+    catch (err) {
+        return { success: false, output: "", error: err instanceof Error ? err.message : String(err) };
+    }
+}
+function currentDiff(cwd) {
+    try {
+        const r = spawnSync("git", ["diff", "HEAD"], {
+            cwd,
+            encoding: "utf8",
+            timeout: 20000,
+            maxBuffer: 20 * 1024 * 1024,
+        });
+        return (r.stdout ?? "").trim();
+    }
+    catch {
+        return "";
+    }
+}
+function parseReview(output) {
+    const m = output.match(/\{[\s\S]*\}/);
+    if (!m)
+        return null;
+    try {
+        return JSON.parse(m[0]);
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeDeviations(dev) {
+    if (!Array.isArray(dev))
+        return [];
+    return dev
+        .map((d) => {
+        if (typeof d === "string")
+            return d.trim();
+        const where = d.where ? `[${d.where}] ` : "";
+        const issue = d.issue ?? "";
+        const fix = d.fix ? ` → FIX: ${d.fix}` : "";
+        return `${where}${issue}${fix}`.trim();
+    })
+        .filter((s) => s.length > 0);
+}
+export async function* runPlanAdherenceReview(args) {
+    const maxRounds = Math.max(1, Math.min(4, args.maxRounds ?? 2));
+    const plan = args.planSynthesis.trim();
+    if (!plan)
+        return { rounds: 0, adherent: true, deviations: [] };
+    const getDiff = args.diffProvider ?? currentDiff;
+    let diff = getDiff(args.cwd);
+    if (!diff) {
+        yield { type: "content", content: `\n> [adherence] No diff to review for sprint ${args.sprintN}; skipping.\n` };
+        return { rounds: 0, adherent: true, deviations: [] };
+    }
+    let lastDeviations = [];
+    for (let round = 1; round <= maxRounds; round++) {
+        const reviewPrompt = `You are a SENIOR code reviewer. Judge whether the implementation faithfully ` +
+            `follows the APPROVED PLAN below — both its file_edits (right files, right ` +
+            `approach: e.g. pass-through vs re-implementation, correct operation/API) and ` +
+            `its acceptance_criteria. Be strict and specific.\n\n` +
+            `=== APPROVED PLAN ===\n${plan.slice(0, 9000)}\n\n` +
+            `=== ACTUAL GIT DIFF ===\n${diff.slice(0, 12000)}\n\n` +
+            `Return ONLY JSON: {"adherent": boolean, "deviations": [{"where":"<file/symbol>",` +
+            `"issue":"<what diverges from the plan>","fix":"<concrete instruction to conform>"}]}. ` +
+            `adherent=true ONLY if there are no material deviations.`;
+        const review = await runIsolatedGuarded(args.runIsolatedTask, {
+            agent: "general",
+            description: `Sprint ${args.sprintN} plan-adherence review (round ${round})`,
+            prompt: reviewPrompt,
+            modelId: args.reviewModelId,
+            maxToolRounds: 12,
+        }, `adherence-review-s${args.sprintN}-r${round}`);
+        const parsed = review.success ? parseReview(review.output ?? "") : null;
+        if (!parsed) {
+            yield {
+                type: "content",
+                content: `\n> [adherence] Reviewer produced no parseable verdict (round ${round}); leaving verify+criteria as the gate.\n`,
+            };
+            return { rounds: round, adherent: true, deviations: [] };
+        }
+        lastDeviations = normalizeDeviations(parsed.deviations);
+        const adherent = parsed.adherent === true || lastDeviations.length === 0;
+        if (adherent) {
+            yield {
+                type: "content",
+                content: `\n> [adherence] Round ${round}: reviewer (${args.reviewModelId}) confirms the implementation follows the plan.\n`,
+            };
+            return { rounds: round, adherent: true, deviations: [] };
+        }
+        yield {
+            type: "content",
+            content: `\n> [adherence] Round ${round}: ${lastDeviations.length} deviation(s) from plan:\n` +
+                lastDeviations.map((d) => `  - ${d}`).join("\n") +
+                "\n",
+        };
+        if (round === maxRounds) {
+            yield {
+                type: "content",
+                content: `\n> [adherence] Max rounds reached; deviations remain for the verify+criteria gate to catch.\n`,
+            };
+            return { rounds: round, adherent: false, deviations: lastDeviations };
+        }
+        // Hand the fix to the lower-tier agent.
+        const fixPrompt = `The implementation deviates from the APPROVED PLAN. A senior reviewer found ` +
+            `these deviations — fix EACH one by editing the code so it conforms to the plan. ` +
+            `Apply edits directly; do not narrate or re-plan.\n\n` +
+            `Deviations:\n${lastDeviations.map((d, i) => `${i + 1}. ${d}`).join("\n")}\n\n` +
+            `=== APPROVED PLAN (for reference) ===\n${plan.slice(0, 6000)}\n`;
+        yield {
+            type: "content",
+            content: `\n> [adherence] Dispatching fix task to ${args.fixModelId} (round ${round})…\n`,
+        };
+        const fix = await runIsolatedGuarded(args.runIsolatedTask, {
+            agent: "general",
+            description: `Sprint ${args.sprintN} plan-adherence fix (round ${round})`,
+            prompt: fixPrompt,
+            modelId: args.fixModelId,
+        }, `adherence-fix-s${args.sprintN}-r${round}`);
+        if (!fix.success) {
+            yield {
+                type: "content",
+                content: `\n> [adherence] Fix task failed (round ${round}): ${fix.error ?? "unknown"}; stopping the loop.\n`,
+            };
+            return { rounds: round, adherent: false, deviations: lastDeviations };
+        }
+        // Re-read the diff for the next review round.
+        diff = getDiff(args.cwd);
+    }
+    return { rounds: maxRounds, adherent: false, deviations: lastDeviations };
+}
+//# sourceMappingURL=plan-adherence-review.js.map

package/dist/src/product-loop/sprint-runner.d.ts

@@ -97,6 +97,68 @@ export declare const IMPL_EXECUTION_DIRECTIVE: string;
  * orchestrator promise may leak in the background, but the run recovers.
  */
 export declare function withImplIdleWatchdog(gen: AsyncGenerator<StreamChunk, void, unknown>, idleMs: number, sprintN: number, totalMs?: number): AsyncGenerator<StreamChunk, void, unknown>;
+/**
+ * Wall-clock deadline for the ISOLATED implementation path.
+ *
+ * The isolated path (`ctx.runIsolatedTask`) returns a single Promise, not a
+ * stream, so `withImplIdleWatchdog` (which guards the streamed non-isolated
+ * path) cannot wrap it. Its only protection was the sub-agent's INTERNAL
+ * per-chunk stall-watchdog — which does NOT fire once the sub-agent's LLM stream
+ * has finished but its orchestrator turn hangs on the JS side afterwards (the
+ * exact "wrote N files then went silent" wedge documented on
+ * `withImplIdleWatchdog`). Observed live 2026-07-12 (run mrhc43f0fb9b): the
+ * isolated impl wrote 2 files, emitted its final `llm-done`, then wedged for 30+
+ * min with zero events and an idle process — because this `await` had no outer
+ * ceiling.
+ *
+ * This races the isolated task against a hard total-elapsed deadline. On
+ * timeout it rejects so the caller's existing try/catch converts the wedge into
+ * a visible phaseError (the sprint surfaces + can recover), mirroring what
+ * `withImplIdleWatchdog` / `runVerifyWithWatchdog` do for the other stages. The
+ * suspended sub-agent promise may leak in the background, but the run recovers.
+ * `totalMs <= 0` disables the guard (returns the task unchanged).
+ */
+/**
+ * Extract why an isolated implementation task failed, from its ToolResult.
+ *
+ * `output` is checked because StreamRunner reports EVERY sub-agent failure
+ * there — "Task failed: …" (stream-runner.ts:1061), "[Cancelled]" (:982), a
+ * provider stall (:988), an unknown-agent message (:265) — and never assigns
+ * `error`; grep stream-runner.ts for `error:` and there are no hits. Reading
+ * `error` alone made `result.error?.trim()` permanently undefined, so every
+ * distinct failure collapsed into the contentless fallback and two /ideal runs
+ * halted 1s into implementation with the cause already erased.
+ *
+ * `error` still wins when a caller does populate it — ToolResult declares the
+ * field, so a future non-StreamRunner producer may be more specific.
+ */
+export declare function resolveImplFailureReason(result: {
+    output?: string;
+    error?: string;
+}): string;
+/**
+ * Persist an implementation-stage failure to `interaction_logs`.
+ *
+ * The implementation stage is where /ideal either ships code or does not, so its
+ * exception is the single most valuable line in a post-mortem — yet run
+ * mrn9yfle9801 halted with only `halt_card_open {trigger:"loop_throw"}` on
+ * record and the message itself unrecoverable: stderr belongs to the TUI child
+ * (the harness never captures it) and the council path writes no `messages`
+ * rows. `elapsedMs` is what separates the two indistinguishable causes — an
+ * immediate `!result.success` from a `withIsolatedImplDeadline` watchdog trip.
+ *
+ * Never throws: a broken audit trail must not take down the sprint it is
+ * describing.
+ */
+export declare function logSprintImplError(ctx: DriverContext, info: {
+    sprintN: number;
+    message: string;
+    stack?: string;
+    implModelId?: string;
+    elapsedMs: number;
+    isolated: boolean;
+}): void;
+export declare function withIsolatedImplDeadline<T>(task: Promise<T>, totalMs: number, sprintN: number): Promise<T>;
 export { computeFailureSignature, loadVerifyFailureSignatures, pushFailureToEE, recordVerifyFailureAndMaybePush, saveVerifyFailureSignatures, type VerifyFailureRecord, type VerifyFailureSignatures, } from "./verify-failure-tracking.js";
 export interface RunSprintArgs {
     sprintN: number;

package/dist/src/product-loop/sprint-runner.js

@@ -26,6 +26,7 @@ import { readFile, writeFile } from "node:fs/promises";
 import * as path from "node:path";
 import { prependDecisionsLock, readDecisionsLock } from "../council/decisions-lock.js";
 import { runCouncil } from "../council/index.js";
+import { resolveLeaderModel } from "../council/leader.js";
 import { phaseDone, phaseError, phaseStart } from "../council/phase-events.js";
 import { fireAndForgetWorkflowEvent } from "../ee/workflow-event.js";
 import { readArtifact, writeArtifact } from "../flow/artifact-io.js";
@@ -33,21 +34,24 @@ import { renderResumeDigest, writeSprintOutcome, writeSprintVerify } from "../fl
 import { isContextRailEnabled } from "../gsd/flags.js";
 import { SPRINT_EXECUTION_MARKER } from "../pil/layer6-output.js";
 import { detectProviderForModel } from "../providers/runtime.js";
-import { logUIInteraction } from "../storage/index.js";
+import { logInteraction, logUIInteraction } from "../storage/index.js";
 import { commitToProduct, release } from "../usage/ledger.js";
 import { CapBreachError } from "../usage/types.js";
+import { getIsolatedTaskDeadlineMs, withDeadlineRace } from "../utils/llm-deadline.js";
 import { runVerifyOrchestration } from "../verify/orchestrator.js";
 import { appendIteration, readCriteria } from "./artifact-io.js";
 import { formatUnverifiedForSprintContext, readLedger } from "./assumption-ledger.js";
 import { readBacklog } from "./backlog-store.js";
 import { CB1_costProjection, CB2_oscillation, CB3_verifyBlank } from "./circuit-breakers.js";
 import { reserveForProduct } from "./cost-scoper.js";
+import { extractAcceptanceCriteria, judgeCriteriaAgainstVerify, planQualityIssues, seedCriteriaFromPlan, } from "./criteria-seed.js";
 import { formatProjectContextForPrompt } from "./discovery-context-format.js";
 import { readProjectContext } from "./discovery-persistence.js";
 import { evaluateDoneGate } from "./done-gate.js";
 import { buildContinueFeedback } from "./feedback-routing.js";
 import { idealTrace } from "./ideal-trace.js";
 import { postSprintBoundary } from "./phase-tracker-bridge.js";
+import { runPlanAdherenceReview } from "./plan-adherence-review.js";
 import { computeProgressSnapshot, renderSnapshotMarkdown } from "./progress-snapshot.js";
 import { appendRoleMemory } from "./role-memory.js";
 import { loadVerifyFailureSignatures, recordVerifyFailureAndMaybePush } from "./verify-failure-tracking.js";
@@ -254,6 +258,97 @@ export async function* withImplIdleWatchdog(gen, idleMs, sprintN, totalMs = getI
             clearTimeout(totalTimer);
     }
 }
+/**
+ * Wall-clock deadline for the ISOLATED implementation path.
+ *
+ * The isolated path (`ctx.runIsolatedTask`) returns a single Promise, not a
+ * stream, so `withImplIdleWatchdog` (which guards the streamed non-isolated
+ * path) cannot wrap it. Its only protection was the sub-agent's INTERNAL
+ * per-chunk stall-watchdog — which does NOT fire once the sub-agent's LLM stream
+ * has finished but its orchestrator turn hangs on the JS side afterwards (the
+ * exact "wrote N files then went silent" wedge documented on
+ * `withImplIdleWatchdog`). Observed live 2026-07-12 (run mrhc43f0fb9b): the
+ * isolated impl wrote 2 files, emitted its final `llm-done`, then wedged for 30+
+ * min with zero events and an idle process — because this `await` had no outer
+ * ceiling.
+ *
+ * This races the isolated task against a hard total-elapsed deadline. On
+ * timeout it rejects so the caller's existing try/catch converts the wedge into
+ * a visible phaseError (the sprint surfaces + can recover), mirroring what
+ * `withImplIdleWatchdog` / `runVerifyWithWatchdog` do for the other stages. The
+ * suspended sub-agent promise may leak in the background, but the run recovers.
+ * `totalMs <= 0` disables the guard (returns the task unchanged).
+ */
+/**
+ * Extract why an isolated implementation task failed, from its ToolResult.
+ *
+ * `output` is checked because StreamRunner reports EVERY sub-agent failure
+ * there — "Task failed: …" (stream-runner.ts:1061), "[Cancelled]" (:982), a
+ * provider stall (:988), an unknown-agent message (:265) — and never assigns
+ * `error`; grep stream-runner.ts for `error:` and there are no hits. Reading
+ * `error` alone made `result.error?.trim()` permanently undefined, so every
+ * distinct failure collapsed into the contentless fallback and two /ideal runs
+ * halted 1s into implementation with the cause already erased.
+ *
+ * `error` still wins when a caller does populate it — ToolResult declares the
+ * field, so a future non-StreamRunner producer may be more specific.
+ */
+export function resolveImplFailureReason(result) {
+    return result.error?.trim() || result.output?.trim() || "isolated implementation task failed";
+}
+/**
+ * Persist an implementation-stage failure to `interaction_logs`.
+ *
+ * The implementation stage is where /ideal either ships code or does not, so its
+ * exception is the single most valuable line in a post-mortem — yet run
+ * mrn9yfle9801 halted with only `halt_card_open {trigger:"loop_throw"}` on
+ * record and the message itself unrecoverable: stderr belongs to the TUI child
+ * (the harness never captures it) and the council path writes no `messages`
+ * rows. `elapsedMs` is what separates the two indistinguishable causes — an
+ * immediate `!result.success` from a `withIsolatedImplDeadline` watchdog trip.
+ *
+ * Never throws: a broken audit trail must not take down the sprint it is
+ * describing.
+ */
+export function logSprintImplError(ctx, info) {
+    try {
+        logInteraction(ctx.sessionId ?? ctx.runId, "council", {
+            eventSubtype: "sprint_impl_error",
+            ...(info.implModelId ? { model: info.implModelId } : {}),
+            durationMs: info.elapsedMs,
+            data: {
+                runId: ctx.runId,
+                sprintN: info.sprintN,
+                isolated: info.isolated,
+                message: info.message.slice(0, 2000),
+                stack: info.stack,
+            },
+        });
+    }
+    catch (err) {
+        console.error(`[sprint-runner] failed to persist implementation error (sprint ${info.sprintN}): ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export async function withIsolatedImplDeadline(task, totalMs, sprintN) {
+    if (!(Number.isFinite(totalMs) && totalMs > 0))
+        return task;
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(`isolated implementation stage exceeded ${Math.round(totalMs / 1000)}s total watchdog and was ` +
+                `treated as stalled (sprint ${sprintN}) — the isolated sub-agent turn never completed ` +
+                `(hung on the JS side after its final response; the isolated path has no per-chunk stall guard)`));
+        }, totalMs);
+        timer.unref?.();
+    });
+    try {
+        return await Promise.race([task, deadline]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 export { computeFailureSignature, loadVerifyFailureSignatures, pushFailureToEE, recordVerifyFailureAndMaybePush, saveVerifyFailureSignatures, } from "./verify-failure-tracking.js";
 /**
  * Run a single sprint. Yields StreamChunk events for the UI and returns the
@@ -375,9 +470,54 @@ export async function* runSprint(args) {
     // ── Step 2: Detect verify recipe BEFORE the planner spends any token ──────
     // CB-3 fires deterministically on sprint 1 if recipe is null or coverage === 0.
     const verifyAgent = buildVerifyAgent(ctx, cwd);
-    const verifyRecipe = await verifyAgent.detectVerifyRecipe(verifyAgent.getSandboxSettings());
+    // Wall-clock backstop: `detectVerifyRecipe` runs a `verify-detect` LLM
+    // sub-agent turn (orchestrator.detectVerifyRecipe → runTaskRequest). Like the
+    // impl/verify stages, that turn can finish its stream then wedge on the JS side
+    // afterward — and this call site had NO deadline, so a single hung verify-detect
+    // turn bricked the entire /ideal run silently, right after "Committed: N sprints
+    // planned" and BEFORE the "Sprint N — Planning" yield (observed live 2026-07-13:
+    // 8+ min frozen frame, no forward progress). Race it against the shared isolated-
+    // task deadline; a timeout falls through to `null` → CB-3 emits the actionable
+    // recovery card instead of hanging. (The bridge signature does not thread an
+    // abortSignal, so this caller-side race is the guarantee.)
+    let verifyRecipe;
+    try {
+        verifyRecipe = await withDeadlineRace(() => verifyAgent.detectVerifyRecipe(verifyAgent.getSandboxSettings()), getIsolatedTaskDeadlineMs(), `sprint-${sprintN}-detect-verify`);
+    }
+    catch (err) {
+        console.error(`[sprint-runner] detectVerifyRecipe timed out/failed (sprint ${sprintN}, run ${ctx.runId}): ${err instanceof Error ? err.message : String(err)}`);
+        verifyRecipe = null;
+    }
     const cb3 = CB3_verifyBlank(sprintN, verifyRecipe);
-    if (cb3.halt) {
+    // Greenfield build-first (Task #8): on a fresh greenfield /ideal run the first
+    // sprint has nothing to verify yet — detectVerifyRecipe legitimately returns
+    // null / zero-coverage because the code and tests do not exist until THIS sprint
+    // builds them. Halting here (CB-3) would trap every greenfield idea before a
+    // single line is written. So for sprint 1 of a greenfield run, bypass the halt
+    // and let the implement stage scaffold the first increment; the verify stage
+    // re-detects the recipe from the code it creates (Step 5 reads
+    // verifyResult.verifyRecipe, not this one). The halt is preserved for EXISTING
+    // projects, where a missing recipe is a real "I can't tell how to test this"
+    // signal that warrants the recovery card. Opt out with
+    // MUONROI_IDEAL_GREENFIELD_BUILD_FIRST=0.
+    let greenfieldBuildFirst = false;
+    if (cb3.halt && sprintN === 1 && process.env.MUONROI_IDEAL_GREENFIELD_BUILD_FIRST !== "0") {
+        try {
+            const pc = await readProjectContext(ctx.flowDir, ctx.runId);
+            greenfieldBuildFirst = pc?.detection?.classification === "greenfield";
+        }
+        catch {
+            greenfieldBuildFirst = false;
+        }
+    }
+    if (greenfieldBuildFirst) {
+        yield {
+            type: "content",
+            content: `\n> Greenfield: no verify recipe exists yet (nothing is built). Proceeding to build the ` +
+                `first increment — it will be verified against the code and tests this sprint creates.\n`,
+        };
+    }
+    if (cb3.halt && !greenfieldBuildFirst) {
         // Yield a structured halt chunk so the TUI can render an actionable recovery
         // card (Task 5.2). Do NOT throw — callers must discriminate on chunk.type.
         const haltChunk = {
@@ -562,6 +702,36 @@ export async function* runSprint(args) {
         // Persist so a resumed/retried sprint reuses this exact plan (and target folder).
         await persistSprintPlan(planPath, planSynthesis);
     }
+    // Plan-fidelity fix: seed the plan's acceptance_criteria into the criteria store
+    // so the done-gate scores against REAL criteria (previously readCriteria returned
+    // [] → score always 0.00 → no gate on plan divergence). Idempotent + non-clobbering.
+    // Also run a NON-BLOCKING plan-quality check (per-sprint plans are auto-approved
+    // with no gate) and fold any issues into a corrective note for the impl prompt.
+    let planQualityNote = "";
+    try {
+        const planCriteria = extractAcceptanceCriteria(planSynthesis ?? "");
+        const seeded = await seedCriteriaFromPlan(ctx.flowDir, ctx.runId, planCriteria, sprintN);
+        if (seeded > 0) {
+            yield {
+                type: "content",
+                content: `\n> [criteria] Seeded ${seeded} acceptance criteria from the sprint plan (done-gate now scores against them).\n`,
+            };
+        }
+        const issues = planQualityIssues(planSynthesis ?? "", seeded);
+        if (issues.length > 0) {
+            planQualityNote =
+                `\n\n--- PLAN QUALITY WARNINGS (address these while implementing) ---\n` +
+                    issues.map((i) => `- ${i}`).join("\n") +
+                    `\nImplement to satisfy the phase goal and every acceptance criterion; do not stop at scaffolding.\n`;
+            yield {
+                type: "content",
+                content: `\n> [plan-check] ${issues.length} plan-quality warning(s): ${issues.join("; ")}\n`,
+            };
+        }
+    }
+    catch {
+        /* non-critical — a missing criteria seed degrades to the prior empty-criteria behavior */
+    }
     // P4-C: close the planning phase row before opening implementation.
     yield phaseDone({
         phaseId: planPhaseId,
@@ -609,7 +779,7 @@ export async function* runSprint(args) {
     // implement/edit path, not the respond path.
     // C2: Pre-impl gate — read decisions.lock.md and prepend to implementation prompt.
     // When lock file is missing (greenfield / no council with runDir), pass-through unchanged.
-    let implPrompt = planSynthesis.trim() ? IMPL_EXECUTION_DIRECTIVE + planSynthesis : planSynthesis;
+    let implPrompt = planSynthesis.trim() ? IMPL_EXECUTION_DIRECTIVE + planSynthesis + planQualityNote : planSynthesis;
     try {
         const lockContent = await readDecisionsLock(runDir);
         if (lockContent) {
@@ -647,6 +817,7 @@ export async function* runSprint(args) {
         }
     }
     let implError = null;
+    let implErrorStack;
     if (ctx.processMessageFn && implPrompt.trim()) {
         const useIsolated = shouldUseIsolatedImpl(!!ctx.runIsolatedTask);
         try {
@@ -663,14 +834,29 @@ export async function* runSprint(args) {
                     content: "\n> [isolated impl] Executing the sprint in a fresh sub-agent context " +
                         "(anti-overflow: does not inherit the debate history).\n",
                 };
-                const result = await ctx.runIsolatedTask({
+                // Plan-fidelity fix: allow the implementation turn to run on a stronger
+                // model than the cheap session tier (which failed to faithfully follow a
+                // rich plan). Opt-in via MUONROI_IDEAL_IMPL_MODEL; defaults to the session
+                // model so the cheap-model philosophy stays the default.
+                const implModelId = process.env.MUONROI_IDEAL_IMPL_MODEL?.trim() || ctx.sessionModelId;
+                if (implModelId !== ctx.sessionModelId) {
+                    yield {
+                        type: "content",
+                        content: `\n> [impl-model] Running implementation on ${implModelId} (override of session model ${ctx.sessionModelId}).\n`,
+                    };
+                }
+                // Wall-clock deadline: the isolated path has no per-chunk stall guard,
+                // so a post-finish JS-side hang would wedge this await forever (observed
+                // live, run mrhc43f0fb9b). Racing the total-elapsed ceiling turns a wedge
+                // into a phaseError via the try/catch below. See withIsolatedImplDeadline.
+                const result = await withIsolatedImplDeadline(ctx.runIsolatedTask({
                     agent: "general",
                     description: `Sprint ${sprintN} implementation`,
                     prompt: implPrompt,
-                    modelId: ctx.sessionModelId,
-                });
+                    modelId: implModelId,
+                }), getImplTotalTimeoutMs(), sprintN);
                 if (!result.success) {
-                    implError = result.error?.trim() || "isolated implementation task failed";
+                    implError = resolveImplFailureReason(result);
                 }
                 else if (result.output?.trim()) {
                     yield { type: "content", content: `\n${result.output.trim()}\n` };
@@ -687,8 +873,11 @@ export async function* runSprint(args) {
         }
         catch (e) {
             implError = e instanceof Error ? e.message : String(e);
+            implErrorStack = e instanceof Error ? e.stack?.split("\n").slice(0, 4).join(" | ") : undefined;
             // No-Silent-Catch: the finally below surfaces a phaseError chunk, but log
             // here too so the hang/failure is diagnosable from stderr / MUONROI logs.
+            // Persisting happens at the single convergence point below — a thrown
+            // error and a `!result.success` return must not log differently.
             console.error(`[sprint-runner] implementation stage failed (sprint ${sprintN}, run ${ctx.runId}): ${implError}`);
         }
         finally {
@@ -728,6 +917,21 @@ export async function* runSprint(args) {
         });
     }
     if (implError) {
+        // The ONE place both failure shapes converge. The catch above handles a
+        // thrown error; a `!result.success` return never reaches it and instead
+        // falls through to here — which is why persisting from inside the catch
+        // recorded nothing for the two runs that actually failed. This throw
+        // escapes to the UI's loop-level catch (use-app-logic.tsx), which renders
+        // the message but persists only {reason, trigger, sprintN} — no text. So
+        // this is the last point at which the reason still exists.
+        logSprintImplError(ctx, {
+            sprintN,
+            message: implError,
+            stack: implErrorStack,
+            implModelId: process.env.MUONROI_IDEAL_IMPL_MODEL?.trim() || ctx.sessionModelId,
+            elapsedMs: Date.now() - implStartedAt,
+            isolated: shouldUseIsolatedImpl(!!ctx.runIsolatedTask),
+        });
         throw new Error(implError);
     }
     // ── Step 4b: 4A completeness re-check ─────────────────────────────────────
@@ -800,6 +1004,58 @@ export async function* runSprint(args) {
             }
         }
     }
+    // ── Step 4c: Plan-adherence review gate (strong reviewer → cheap fixer) ────
+    // A high-tier reviewer checks the diff against the approved plan; deviations are
+    // handed to a lower-tier fixer and re-reviewed (bounded). Opt out with
+    // MUONROI_IDEAL_ADHERENCE_REVIEW=0. Never halts — verify + the criteria done-gate
+    // remain the hard gates; this tightens plan fidelity before verification so a
+    // cheap implementer's divergence is caught and corrected, not shipped.
+    // Plan deviations that survive the bounded fixer rounds — carried into the next
+    // sprint's focus (Step 9) so "chưa tuân thủ" work continues rather than being
+    // silently dropped after the review.
+    let residualPlanDeviations = [];
+    if (ctx.runIsolatedTask && planSynthesis.trim() && process.env.MUONROI_IDEAL_ADHERENCE_REVIEW !== "0") {
+        const adhPhaseId = `sprint-${sprintN}-adherence`;
+        const adhStartedAt = Date.now();
+        yield phaseStart({
+            phaseId: adhPhaseId,
+            kind: "sprint_stage",
+            label: `Sprint ${sprintN} — Plan-adherence review`,
+            startedAt: adhStartedAt,
+        });
+        try {
+            const reviewModelId = process.env.MUONROI_IDEAL_REVIEW_MODEL?.trim() || resolveLeaderModel(ctx.sessionModelId);
+            const verdict = yield* runPlanAdherenceReview({
+                sprintN,
+                planSynthesis,
+                cwd,
+                reviewModelId,
+                fixModelId: ctx.sessionModelId,
+                runIsolatedTask: ctx.runIsolatedTask,
+                maxRounds: Number.parseInt(process.env.MUONROI_IDEAL_ADHERENCE_ROUNDS ?? "2", 10) || 2,
+            });
+            idealTrace("sprint.adherence.after", {
+                runId: ctx.runId,
+                sprintN,
+                rounds: verdict.rounds,
+                adherent: verdict.adherent,
+                deviations: verdict.deviations.length,
+            });
+            if (!verdict.adherent)
+                residualPlanDeviations = verdict.deviations;
+        }
+        catch (err) {
+            console.error(`[sprint-runner] plan-adherence review failed (sprint ${sprintN}): ${err.message}`);
+        }
+        finally {
+            yield phaseDone({
+                phaseId: adhPhaseId,
+                kind: "sprint_stage",
+                label: `Sprint ${sprintN} — Plan-adherence review`,
+                startedAt: adhStartedAt,
+            });
+        }
+    }
     // ── Step 5: Verify stage ──────────────────────────────────────────────────
     yield { type: "content", content: `\n## Sprint ${sprintN} — Verification\n` };
     const verifyPhaseId = `sprint-${sprintN}-verification`;
@@ -928,6 +1184,42 @@ export async function* runSprint(args) {
         subtype: "sprint_stage",
         data: { sprintIndex: sprintN, stage: "judgment", runId: ctx.runId },
     });
+    // Plan-fidelity fix: judge the seeded acceptance criteria against what was
+    // actually built (verify output + diff) BEFORE the done-gate reads them.
+    // Without this the criteria stay "unmet" forever → score 0.00 and the gate can
+    // never distinguish an on-plan sprint from a divergent one. Only upgrades on a
+    // PASSing verify with concrete evidence (see judgeCriteriaAgainstVerify).
+    try {
+        const judgeModelId = roleAssignments.get("Reviewer")?.modelId ?? roleAssignments.get("PO")?.modelId ?? ctx.sessionModelId;
+        let diffSummary = "";
+        try {
+            const { spawnSync } = await import("node:child_process");
+            const stat = spawnSync("git", ["diff", "--stat", "HEAD"], { cwd, encoding: "utf8", timeout: 15000 });
+            diffSummary = (stat.stdout ?? "").slice(0, 4000) || "(no diff detected)";
+        }
+        catch {
+            diffSummary = "(diff unavailable)";
+        }
+        const verifyOutputForJudge = (verifyResult.error?.trim() ? verifyResult.error : (verifyResult.output ?? "")).trim();
+        const { judged, total } = await judgeCriteriaAgainstVerify({
+            flowDir: ctx.flowDir,
+            runId: ctx.runId,
+            llm: productLlm,
+            modelId: judgeModelId,
+            verifyVerdict,
+            verifyOutput: verifyOutputForJudge,
+            diffSummary,
+        });
+        if (total > 0) {
+            yield {
+                type: "content",
+                content: `\n> [criteria] Judged ${judged}/${total} acceptance criteria as met/partial against verify+diff.\n`,
+            };
+        }
+    }
+    catch {
+        /* non-critical — judging failure leaves criteria unmet (conservative) */
+    }
     const currentCriteria = await readCriteria(ctx.flowDir, ctx.runId);
     // When a phaseScope is provided (subsystem E), evaluate the done-gate only
     // against criteria belonging to this phase. Full criteria are kept for
@@ -1011,6 +1303,7 @@ export async function* runSprint(args) {
         criteriaMet: currentCriteria.filter((c) => c.status === "met").length,
         criteriaPartial: currentCriteria.filter((c) => c.status === "partial").length,
         criteriaUnmet: currentCriteria.filter((c) => c.status === "unmet").length,
+        totalCriteria: currentCriteria.length,
         costUsd: 0, // Per-sprint cost is observed via the per-product ledger; field kept for compat.
         actualCost: 0,
         score: verdict.score,
@@ -1103,6 +1396,14 @@ export async function* runSprint(args) {
     // ── Step 9: If not done, surface continue-feedback to the user ───────────
     if (!verdict.pass) {
         const fb = buildContinueFeedback(verdict, verifyResult, currentCriteria);
+        // Fold any residual plan deviations (surviving the adherence fixer) into the
+        // carry-over focus so the next sprint continues the non-adherent/risky parts.
+        const deviationNote = residualPlanDeviations.length > 0
+            ? `\n\nPlan deviations still open (address these next):\n${residualPlanDeviations
+                .map((d) => `- ${d}`)
+                .join("\n")}`
+            : "";
+        iter.nextFocus = `${fb.focus}${deviationNote}`;
         yield {
             type: "content",
             content: `\n> Sprint ${sprintN} did not satisfy Definition-of-Done (${verdict.failedCondition ?? "unknown"}). Next focus: ${fb.focus}\n`,