muonroi-cli 1.8.4 → 1.9.0

package/dist/src/product-loop/phase-plan.js

@@ -3,15 +3,80 @@ import { promises as fs } from "node:fs";
 import * as path from "node:path";
 import { readArtifact, writeArtifact } from "../flow/artifact-io.js";
 import { withRateLimitBackoff } from "./discovery-recommender.js";
-export const PHASE_PLANNER_SYSTEM = "You decompose a product idea into 3–5 sequential phases. Output strict JSON only. " +
-    "Each phase covers a subset of successCriteria verbatim from the input spec. " +
-    "Union of all phases.successCriteria MUST equal the input successCriteria array (no drift, no omission).";
+export const PHASE_PLANNER_SYSTEM = "You are the PO/tech-lead planning an agile delivery. Decompose a product idea into 3–5 " +
+    "sequential phases. Output strict JSON only. Each phase covers a subset of successCriteria " +
+    "verbatim from the input spec. Union of all phases.successCriteria MUST equal the input " +
+    "successCriteria array (no drift, no omission).\n\n" +
+    "Size each phase to its REAL difficulty. For every phase, YOU decide its `maxSprints` — the " +
+    "maximum sprint iterations that phase may need — from that phase's own scope, risk, and " +
+    "uncertainty, exactly as a tech lead would in agile planning: a simple/mechanical phase needs " +
+    "1; a phase with hard, uncertain, or risky work needs more (2–5). Do NOT split a fixed budget " +
+    "evenly, do NOT pad to a quota, and never emit a fraction. `maxSprints` is a CEILING — the " +
+    "done-gate ends a phase early once its criteria are met — so give genuinely hard phases enough " +
+    "room to iterate rather than rationing them.";
+/**
+ * Coerce a phase id / dependsOn element to the canonical `phase-N` string form.
+ *
+ * The phase-planner prompt does not pin `id` to a string, so the LLM frequently
+ * emits bare numbers — e.g. `"id": 1, "dependsOn": [1]` instead of
+ * `"id": "phase-1", "dependsOn": ["phase-1"]`. Downstream consumers assume the
+ * declared `Phase.id: string` / `dependsOn: string[]` contract; the roadmap
+ * renderer (`buildRoadmapFromPhasePlan`) calls `dep.match(...)` and crashed with
+ * `dep.match is not a function` on a numeric id, aborting the whole /ideal run
+ * right after the sprint plan committed — before any implementation ran.
+ * Normalising here (the single parse choke-point) restores the contract for
+ * every consumer.
+ */
+function normalizePhaseRef(ref) {
+    if (typeof ref === "number" && Number.isFinite(ref))
+        return `phase-${ref}`;
+    const s = String(ref).trim();
+    const bareNumber = s.match(/^(\d+)$/);
+    if (bareNumber)
+        return `phase-${bareNumber[1]}`;
+    return s;
+}
+/**
+ * Normalise `id` + `dependsOn` on every phase to the canonical string form.
+ * Mutates and returns the same plan object. Safe on already-normalised plans.
+ */
+/**
+ * Coerce a plan's per-phase `maxSprints` to a usable sprint COUNT: an integer
+ * in [1, 20]. This is a pure VALIDITY FLOOR — it does NOT allocate or divide any
+ * budget. The PO/leader decides each phase's `maxSprints` from that phase's
+ * difficulty (see PHASE_PLANNER_SYSTEM); this only defends the executor against a
+ * malformed value the model might still emit.
+ *
+ * The sprint loop is `for (sprintN = 1; sprintN <= phase.maxSprints; sprintN++)`,
+ * so any value < 1 makes `1 <= 0.n` false → the loop body NEVER runs → `runSprint`
+ * is never called → implementation is silently skipped (the historical
+ * "plan is great but implement never starts / hangs" bug — a small `--max-sprints`
+ * once made the old "divide the budget across phases" prompt emit fractions like
+ * `0.3 / 0.2 / 0.5`). Flooring to an integer ≥ 1 guarantees every planned phase
+ * executes at least one sprint regardless of what the model returns.
+ */
+export function clampMaxSprints(raw) {
+    const n = typeof raw === "number" ? raw : Number(raw);
+    if (!Number.isFinite(n) || n < 1)
+        return 1;
+    return Math.min(20, Math.round(n));
+}
+export function normalizePhasePlan(plan) {
+    if (Array.isArray(plan?.phases)) {
+        for (const phase of plan.phases) {
+            phase.id = normalizePhaseRef(phase.id);
+            phase.dependsOn = Array.isArray(phase.dependsOn) ? phase.dependsOn.map(normalizePhaseRef) : [];
+            phase.maxSprints = clampMaxSprints(phase.maxSprints);
+        }
+    }
+    return plan;
+}
 export function parsePhasePlanJson(raw) {
     const stripped = raw
         .replace(/^```(?:json)?\s*/, "")
         .replace(/\s*```$/, "")
         .trim();
-    return JSON.parse(stripped);
+    return normalizePhasePlan(JSON.parse(stripped));
 }
 export function validatePhasePlan(plan, spec) {
     if (plan.phases.length < 1 || plan.phases.length > 6) {
@@ -98,7 +163,15 @@ function buildPhasePlannerPrompt(args) {
         `Scope: ${args.clarifiedSpec.scope}`,
         `SuccessCriteria (return these verbatim, distributed across 3-5 phases):`,
         ...args.clarifiedSpec.successCriteria.map((c, i) => `  ${i + 1}. ${c}`),
-        `MaxSprints budget: ${args.manifest.maxSprints} (divide across phases).`,
+        // maxSprints is PO-decided PER PHASE from that phase's difficulty (see the
+        // system prompt) — NOT a global budget to divide. The user's --max-sprints is
+        // only a SOFT guide for overall ambition, never an arithmetic cap the planner
+        // must partition. Each phase's "maxSprints" MUST be a whole integer >= 1.
+        `Sprint sizing: decide each phase's "maxSprints" from its own difficulty/scope/risk — a whole ` +
+            `integer >= 1, more for harder phases. The user suggested roughly ${args.manifest.maxSprints} ` +
+            `sprint(s) total as a soft guide to overall ambition; you may use fewer if the work is simple ` +
+            `or allocate more per phase if the work genuinely needs it. Do not divide it evenly and do not ` +
+            `treat it as a hard budget.`,
         `Output JSON shape: { version:1, generatedAt:<ISO>, phases:[{id,name,goal,successCriteria,scope,exitCondition:{type:"criteria-threshold",min:${args.manifest.doneThreshold}},dependsOn,maxSprints}] }`,
     ].join("\n");
 }
@@ -109,7 +182,9 @@ export async function readPhasePlan(flowDir, runId) {
     if (!raw)
         return null;
     try {
-        return JSON.parse(raw);
+        // Normalise on read too: runs persisted before the parse-time normalisation
+        // landed (or hand-edited phases.md) can still carry numeric ids.
+        return normalizePhasePlan(JSON.parse(raw));
     }
     catch {
         return null;

package/dist/src/product-loop/phase-rituals.d.ts

@@ -6,6 +6,9 @@ export interface SprintState {
     scoreAfter: number;
     criteriaMet: number;
     totalCriteria: number;
+    /** Verify verdict for this sprint (PASS/FAIL/ERROR) — grounds the review so it
+     * describes what actually happened instead of confabulating an agile narrative. */
+    verifyVerdict?: string;
 }
 export declare function generateSprintReview(args: {
     sprintState: SprintState;

package/dist/src/product-loop/phase-rituals.js

@@ -15,9 +15,14 @@ export async function generateSprintReview(args) {
     if (args.remainingUsd < reviewFloor(args.capUsd)) {
         return { summary: deterministicReview(args.sprintState), usedFallback: true };
     }
-    const prompt = `Sprint ${args.sprintState.sprintN} of phase ${args.phase.id}: score ${args.sprintState.scoreBefore.toFixed(2)} → ${args.sprintState.scoreAfter.toFixed(2)}, ` +
-        `met ${args.sprintState.criteriaMet}/${args.sprintState.totalCriteria} criteria. ` +
-        `Write a ≤500-char demo summary for the customer.`;
+    const s = args.sprintState;
+    const verifyLine = s.verifyVerdict ? ` Verify: ${s.verifyVerdict}.` : "";
+    const goal = args.phase.goal ? ` Phase goal: ${args.phase.goal}.` : "";
+    const prompt = `Sprint ${s.sprintN} of phase ${args.phase.id}: score ${s.scoreBefore.toFixed(2)} → ${s.scoreAfter.toFixed(2)}, ` +
+        `met ${s.criteriaMet}/${s.totalCriteria} acceptance criteria.${verifyLine}${goal} ` +
+        `Write a ≤500-char demo summary describing ONLY what these numbers show — the concrete progress on criteria and verify status. ` +
+        `Do NOT invent activities (e.g. "team alignment", "environment setup") that the metrics do not evidence. ` +
+        `If 0/${s.totalCriteria} criteria are met, say plainly that no criteria passed yet and why (verify status), not that setup was done.`;
     try {
         const res = await withRateLimitBackoff(() => args.leader.generate({ system: "You write concise sprint demo summaries.", prompt, maxTokens: 250 }), { delays: args.backoffDelays });
         return { summary: res.content.trim().slice(0, 500), usedFallback: false };

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

@@ -1,5 +1,7 @@
 import * as path from "node:path";
 import { readArtifact, writeArtifact } from "../flow/artifact-io.js";
+import { isGsdNativeEnabled } from "../gsd/flags.js";
+import { orderPhasesForExecution, syncPhasePlanToRoadmap } from "../gsd/phase-dag.js";
 import { buildSprintContext, digestSprintIntoPhase, handoffPhaseToNext } from "./context-policy.js";
 import { formatProjectContextForPrompt } from "./discovery-context-format.js";
 import { backupCorruptPhases, generatePhasePlan, readPhasePlan, validatePhasePlan, writePhasePlan, } from "./phase-plan.js";
@@ -249,8 +251,14 @@ export async function* runPhases(args) {
             backoffDelays: args.backoffDelays,
         });
         await writePhasePlan(args.flowDir, args.runId, plan);
+        if (isGsdNativeEnabled() && args.projectCwd) {
+            syncPhasePlanToRoadmap(args.projectCwd, args.idea ?? args.clarifiedSpec.problemStatement, plan);
+        }
     }
-    for (const phase of orderByDeps(plan.phases)) {
+    const orderedPhases = args.projectCwd
+        ? orderPhasesForExecution(args.projectCwd, plan.phases)
+        : orderByDeps(plan.phases);
+    for (const phase of orderedPhases) {
         const status = await readPhaseStatus(args.flowDir, args.runId, phase.id);
         if (status === "done" || status === "blocked")
             continue;
@@ -305,7 +313,11 @@ export async function* runPhases(args) {
             lastSprintState = sprintResult;
             totalSprints += 1;
             const review = await generateSprintReview({
-                sprintState: { sprintN, ...sprintResult },
+                sprintState: {
+                    sprintN,
+                    ...sprintResult,
+                    verifyVerdict: sprintResult.lastVerifyResult,
+                },
                 phase,
                 leader: args.leader,
                 capUsd: args.capUsd,
@@ -315,15 +327,29 @@ export async function* runPhases(args) {
             if (!args.suppressPush) {
                 yield { type: "push_notification", content: review.summary };
             }
-            await markAwaitingCustomerReview(args.flowDir, args.runId, phase.id, sprintN);
-            const verdict = await args.awaitCustomerVerdict({
-                flowDir: args.flowDir,
-                runId: args.runId,
-                phaseId: phase.id,
-                sprintN,
-                reviewSummary: review.summary,
-            });
-            await clearAwaitingCustomerReview(args.flowDir, args.runId, phase.id, sprintN);
+            // Autonomy fix: by default /ideal advances between sprints WITHOUT a blocking
+            // human verdict (previously the loop parked in discordAwaitVerdict's poll and
+            // never reached sprint 2 unless a human replied). Set
+            // MUONROI_IDEAL_REQUIRE_VERDICT=1 to restore the human customer-review gate.
+            const requireVerdict = process.env.MUONROI_IDEAL_REQUIRE_VERDICT === "1";
+            let verdict;
+            if (requireVerdict) {
+                await markAwaitingCustomerReview(args.flowDir, args.runId, phase.id, sprintN);
+                verdict = await args.awaitCustomerVerdict({
+                    flowDir: args.flowDir,
+                    runId: args.runId,
+                    phaseId: phase.id,
+                    sprintN,
+                    reviewSummary: review.summary,
+                });
+                await clearAwaitingCustomerReview(args.flowDir, args.runId, phase.id, sprintN);
+            }
+            else {
+                verdict = {
+                    verdict: "accept",
+                    feedback: "[auto-advance: autonomous mode (MUONROI_IDEAL_REQUIRE_VERDICT unset)]",
+                };
+            }
             await appendCustomerDecision(args.flowDir, args.runId, {
                 phaseId: phase.id,
                 sprintN,
@@ -352,7 +378,8 @@ export async function* runPhases(args) {
                 // retro skipped
             }
             await clearRetroPending(args.flowDir, args.runId, phase.id, sprintN);
-            const phaseRatio = sprintResult.criteriaMet / Math.max(1, sprintResult.totalCriteria);
+            const phaseTotal = sprintResult.totalCriteria ?? phase.successCriteria.length;
+            const phaseRatio = sprintResult.criteriaMet / Math.max(1, phaseTotal);
             if (phaseRatio >= phase.exitCondition.min)
                 break;
         }

package/dist/src/product-loop/plan-adherence-review.d.ts

@@ -0,0 +1,26 @@
+import type { StreamChunk, TaskRequest, ToolResult } from "../types/index.js";
+/**
+ * Plan-adherence review gate (requested 2026-07-12): after implementation, spawn a
+ * HIGH-TIER reviewer agent to check the actual diff against the approved plan
+ * (file_edits + acceptance_criteria). When it finds deviations, hand a concrete fix
+ * task to a LOWER-TIER agent and re-review. Bounded rounds; never halts the sprint
+ * (verify + the criteria done-gate remain the hard gates). This catches the Sprint-1
+ * failure mode where a cheap implementer received a rich plan but diverged (wrong
+ * LSP op, stub tools) with nothing to notice.
+ */
+export interface AdherenceVerdict {
+    rounds: number;
+    adherent: boolean;
+    deviations: string[];
+}
+export declare function runPlanAdherenceReview(args: {
+    sprintN: number;
+    planSynthesis: string;
+    cwd: string;
+    reviewModelId: string;
+    fixModelId: string;
+    runIsolatedTask: (req: TaskRequest) => Promise<ToolResult>;
+    maxRounds?: number;
+    /** Injectable for tests; defaults to `git diff HEAD` in cwd. */
+    diffProvider?: (cwd: string) => string;
+}): AsyncGenerator<StreamChunk, AdherenceVerdict, unknown>;

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

@@ -26,6 +26,139 @@ import type { ContinueFeedback } from "./feedback-routing.js";
 import type { DriverContext, IterationState, ProductSpec, RoleSlot } from "./types.js";
 /** @internal Test-only: reset CB-2 retry state for a given runId. */
 export declare function _resetCb2RetryUsed(runId: string): void;
+/**
+ * Idle-chunk ceiling for the implementation stage (ms). Override with
+ * MUONROI_SPRINT_IMPL_IDLE_MS. This is a TIME-SINCE-LAST-CHUNK budget, not a
+ * total-turn cap — a legitimately long implementation streams progress the
+ * whole way, so it may run for many minutes, but it must never go completely
+ * silent (no chunk at all) for this long.
+ */
+export declare function getImplIdleTimeoutMs(): number;
+/**
+ * Hard total-elapsed ceiling for the implementation stage (ms). Override with
+ * MUONROI_SPRINT_IMPL_TOTAL_MS. Unlike the idle budget this is armed once and is
+ * NOT reset by chunks, so it catches a hang that keeps the idle guard alive with
+ * heartbeat/status chunks. Generous by default so a legitimately large sprint is
+ * not cut short; a genuine hang still terminates within this ceiling.
+ */
+export declare function getImplTotalTimeoutMs(): number;
+/**
+ * Whether the implement stage runs in an ISOLATED bounded sub-agent context
+ * (ctx.runIsolatedTask) instead of the shared top-level turn (processMessageFn).
+ * Default ON. Disable with MUONROI_SPRINT_ISOLATED_IMPL=0.
+ *
+ * The isolated path is the fix for the live ctx-overflow wedge: the flat
+ * processMessageFn turn inherited the full council-debate history (~5.9M tokens
+ * observed), started implementation already at ~94% context, then wedged after a
+ * mid-turn compaction. A fresh child context (getSubAgentBudgetChars cap +
+ * independent in-loop compaction) never inherits the debate, so it starts near
+ * empty and its clutter is absorbed as one compact ToolResult.
+ */
+export declare function getSprintIsolatedImplEnabled(): boolean;
+/**
+ * Pure decision: use the isolated sub-agent path for the implement stage?
+ * True only when the flag is on AND the driver actually provides the bridge
+ * (legacy/test drivers omit runIsolatedTask → fall back to processMessageFn).
+ * Extracted for unit testing without spinning up a full runSprint.
+ */
+export declare function shouldUseIsolatedImpl(hasBridge: boolean, enabled?: boolean): boolean;
+/**
+ * Imperative execution directive prepended to the sprint plan before it is
+ * handed to the orchestrator. The raw plan synthesis is a declarative design
+ * document; without this prefix the impl turn narrates it back instead of
+ * applying edits. Exported for test assertion. @internal
+ */
+export declare const IMPL_EXECUTION_DIRECTIVE: string;
+/**
+ * Wrap the implementation `processMessageFn` stream with an idle-chunk watchdog.
+ *
+ * Root cause it addresses (observed live 2026-07-08, /ideal resume of the
+ * gsd-core migration): the implementation stage delegates to the host
+ * orchestrator turn via `ctx.processMessageFn(implPrompt)` and consumes it with
+ * `for await (const chunk of implGen)`. The orchestrator turn finished its final
+ * LLM response cleanly (finishReason "stop", text-only) but the generator then
+ * suspended post-finish and never completed — the `for await` blocked for 17+
+ * minutes with NO chunk, NO phaseDone, NO advance to Verify, NO error. Because
+ * the LLM STREAM had already finished, the orchestrator's mid-stream
+ * time-to-next-chunk stall-watchdog does not fire — the hang is on the JS side
+ * after the stream terminator.
+ *
+ * TWO complementary guards (a single idle guard was observed live to be
+ * defeated: the impl created 2 files then emitted only non-progress heartbeat
+ * chunks for 9+ min, resetting a per-chunk idle timer without ever completing):
+ *   - `idleMs` — resets on every yielded chunk; catches a TOTALLY silent stall
+ *     (the post-finish hang above, zero chunks) quickly.
+ *   - `totalMs` — armed ONCE at entry, NOT reset by chunks; a hard ceiling that
+ *     fires even when heartbeat/status chunks keep the idle guard alive while no
+ *     real progress is made.
+ * Either firing throws so the caller's existing try/catch converts the wedge
+ * into a visible phaseError (the sprint then surfaces + can recover), exactly
+ * like `runVerifyWithWatchdog` does for the verify stage. The suspended
+ * 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;
@@ -60,4 +193,44 @@ export interface RunSprintArgs {
  * Throws on circuit-breaker halt — caller (loop driver) catches and writes
  * the appropriate halt state to manifest/state.
  */
+/** Path to the persisted per-sprint plan synthesis (Wave 2). @internal */
+export declare function sprintPlanPath(runDir: string, sprintN: number): string;
+/**
+ * Wave 2: read a persisted sprint plan if present. Returns "" when absent or on
+ * read error (caller then runs the planning council). Never throws.
+ *
+ * The planning council is non-deterministic — re-running it on a resumed/retried
+ * sprint produces a different design AND a different target folder, which is why
+ * the impl turn was observed re-scaffolding in a new location each run. Reusing
+ * the persisted plan makes per-sprint planning idempotent so the same target
+ * files are continued across resume.
+ */
+export declare function readPersistedSprintPlan(planPath: string): Promise<string>;
+/** Wave 2: persist a sprint plan synthesis for idempotent resume. Never throws. */
+export declare function persistSprintPlan(planPath: string, synthesis: string): Promise<void>;
+/**
+ * Extract repo-relative target file paths a sprint plan names (src/…, packages/…,
+ * tests/…). Deduped, capped. Used by Wave 3 (existing targets → continue) and 4A
+ * (missing targets → completeness re-check). Never throws.
+ */
+export declare function extractPlanTargetPaths(planSynthesis: string, cap?: number): string[];
+/**
+ * Wave 3: plan-named target file paths that ALREADY EXIST on disk, so the impl
+ * turn continues them rather than re-scaffolding in a new location. Empty on a
+ * greenfield sprint (files don't exist yet) → no injection.
+ */
+export declare function detectExistingPlanTargets(planSynthesis: string, cwd: string, cap?: number): Promise<string[]>;
+/**
+ * 4A: plan-named target file paths that STILL DO NOT EXIST after the impl turn —
+ * i.e. action items the implementer left unaddressed. Drives the post-impl
+ * completeness re-check (spend an extra turn ONLY when there is proven-incomplete
+ * work, unlike an unconditional reviewer pass). Empty ⇒ every named target landed.
+ */
+export declare function computeMissingPlanTargets(planSynthesis: string, cwd: string, cap?: number): Promise<string[]>;
+/**
+ * 4A completeness re-check toggle. Default ON; disable with
+ * MUONROI_SPRINT_IMPL_RECHECK=0. When on, and the impl turn left plan-named
+ * target files missing, ONE focused follow-up turn is spent to finish them.
+ */
+export declare function getImplRecheckEnabled(): boolean;
 export declare function runSprint(args: RunSprintArgs): AsyncGenerator<StreamChunk, IterationState, unknown>;