muonroi-cli 1.8.4 → 1.9.0

package/dist/src/product-loop/loop-driver.js

@@ -1,11 +1,18 @@
 import * as path from "node:path";
 import { runDebate } from "../council/debate.js";
+import { deleteDebateInputs, readDebateCheckpoint, readDebateInputs, writeDebateInputs, } from "../council/debate-checkpoint.js";
+import { resolveDebateSummary } from "../council/debate-summary.js";
 import { resolveLeaderModelDetailed, resolveParticipants } from "../council/leader.js";
 import { phaseStart } from "../council/phase-events.js";
 import { runPreflight } from "../council/preflight.js";
+import { makeStanceRecall } from "../council/stance-recall.js";
 import { fetchBBContext, inferBBFromPrompt, renderBBContextBlock } from "../ee/bb-retrieval.js";
+import { getDefaultEEClient } from "../ee/intercept.js";
+import { fireAndForgetWorkflowEvent } from "../ee/workflow-event.js";
 import { readArtifact, writeArtifact } from "../flow/artifact-io.js";
-import { logInteraction, recordUsageEvent } from "../storage/index.js";
+import { ensureRunScoped } from "../flow/hierarchy.js";
+import { renderResumeDigest, writeContextDoc, writeResearchDoc } from "../flow/run-artifacts.js";
+import { logInteraction } from "../storage/index.js";
 import { isCouncilMultiProviderPreferred } from "../utils/settings.js";
 import { extractAssumptionsFromDebate, mergeAssumptions, renderLedgerSummary } from "./assumption-ledger.js";
 import { buildPriorContext } from "./cross-run-memory.js";
@@ -17,60 +24,58 @@ import { recordPhaseEnd, recordPhaseStart } from "./phase-budget.js";
 import { additionalPrefills, auditAsContextBlock, auditRepo } from "./repo-audit.js";
 import { SEED_DIMENSIONS } from "./seed-questions.js";
 import { deriveTasksFromSpec, writeTasks } from "./typed-artifacts.js";
+// Council usage_events recording (source="council") now happens at the single
+// source of truth inside createCouncilLLM (src/council/llm.ts → recordCouncilUsage),
+// so it covers EVERY council entry point — the /council slash path, auto-council,
+// and all /ideal phases (clarifier, research, generate, sprint) — not just this
+// driver's runDebate call site. The former loop-driver-local wrapper only wrapped
+// the debate llm and double-counted nothing else; recording at the source removes
+// both the leak and the risk of a double count here.
 /**
- * Wraps a CouncilLLM so every debate/research/generate call records a
- * usage_events row with source="council". debate.ts callers don't pass an
- * onUsage callback today, so the only place we can intercept is here, by
- * injecting our recorder into each method invocation before forwarding.
- * The original onUsage (if any) is still called.
+ * Best-effort interaction_logs writer for the loop-driver. Logs and continues on
+ * failure so a broken DB never blocks the FSM. `ctx.sessionId` falls back to
+ * runId for legacy callers that don't pass a chat session id. `cols` carries
+ * fields that belong in real columns rather than metadata_json.
  */
-function wrapLLMForUsageTracking(llm, ctx) {
-    const sid = ctx.sessionId ?? ctx.runId;
-    const recorder = (modelId) => (usage) => {
-        try {
-            recordUsageEvent(sid, "council", modelId, {
-                inputTokens: usage.inputTokens,
-                outputTokens: usage.outputTokens,
-                cacheReadTokens: usage.cachedInputTokens,
-            });
-        }
-        catch {
-            /* best-effort — never block the debate */
-        }
-    };
-    return {
-        generate: (modelId, system, prompt, maxTokens, onUsage, signal) => llm.generate(modelId, system, prompt, maxTokens, (u) => {
-            recorder(modelId)(u);
-            onUsage?.(u);
-        }, signal),
-        debate: (modelId, system, prompt, signal, persistTrace, options, onUsage) => llm.debate(modelId, system, prompt, signal, persistTrace, options, (u) => {
-            recorder(modelId)(u);
-            onUsage?.(u);
-        }),
-        research: (modelId, topic, conversationContext, signal, persistTrace, options, onUsage) => llm.research(modelId, topic, conversationContext, signal, persistTrace, options, (u) => {
-            recorder(modelId)(u);
-            onUsage?.(u);
-        }),
-    };
-}
-/**
- * Best-effort interaction_logs writer for the loop-driver. Swallows failures
- * so a broken DB never blocks the FSM. `ctx.sessionId` falls back to runId
- * for legacy callers that don't pass a chat session id.
- */
-function logLoopEvent(ctx, subtype, data) {
+function logLoopEvent(ctx, subtype, data, cols) {
     try {
         const sid = ctx.sessionId ?? ctx.runId;
         // Stamp runId on every row so multi-run sessions can be demuxed during
         // forensics — previously only route_decision carried this field. Caller
         // overrides win if the payload already contained a runId.
         const enriched = "runId" in data ? data : { ...data, runId: ctx.runId };
-        logInteraction(sid, "council", { eventSubtype: subtype, data: enriched });
+        // `cols` promotes fields out of metadata_json into real columns so they are
+        // aggregatable in SQL. Without it every council_message row landed with
+        // duration_ms NULL, leaving `debate_complete` (the whole debate) as the only
+        // timed row — an aggregate that cannot name which speaker was slow.
+        logInteraction(sid, "council", {
+            eventSubtype: subtype,
+            data: enriched,
+            ...(cols?.model ? { model: cols.model } : {}),
+            ...(typeof cols?.durationMs === "number" ? { durationMs: cols.durationMs } : {}),
+        });
     }
-    catch {
-        /* non-critical — audit trail only */
+    catch (err) {
+        // Audit trail only — never block the FSM. Logged so a broken DB surfaces
+        // instead of silently emptying the forensics table. (No-Silent-Catch.)
+        console.error(`[loop-driver] logLoopEvent failed for subtype "${subtype}": ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+/**
+ * Clamp a title for the milestone/phase index (F12): truncate at a word
+ * boundary when possible and strip trailing punctuation/whitespace so a raw
+ * slice can't leave a dangling "(" or a half word. Falls back to a hard slice
+ * for a single long token.
+ */
+export function clampTitle(raw, max) {
+    const s = (raw ?? "").trim();
+    if (s.length <= max)
+        return s.replace(/[\s([{<"'.,;:–—-]+$/u, "").trim() || s;
+    const hard = s.slice(0, max);
+    const lastSpace = hard.lastIndexOf(" ");
+    const base = lastSpace >= Math.floor(max * 0.6) ? hard.slice(0, lastSpace) : hard;
+    return base.replace(/[\s([{<"'.,;:–—-]+$/u, "").trim() || hard.trim();
+}
 function buildWorkspaceDiscoveryCard(d, a, priorRunCount) {
     const sections = [];
     if (!d.hasProject) {
@@ -157,6 +162,12 @@ export async function* runLoopDriver(ctx) {
     let state = "idle";
     let clarifiedSpec;
     let debateState;
+    // Resolved once the research debate completes (F9): runningSummary, or a
+    // faithful fallback synthesized from participant positions when the debate
+    // returned after openings without a running summary. Reused across the
+    // research artifacts AND the scoping synthesis prompt so neither loses the
+    // debate. Empty until the research phase runs.
+    let resolvedDebateSummary = "";
     let discovery;
     let audit;
     let productSpec;
@@ -168,6 +179,28 @@ export async function* runLoopDriver(ctx) {
     const leaderResolution = await resolveLeaderModelDetailed(ctx.sessionModelId);
     const leaderModelId = leaderResolution.modelId;
     const councilParticipants = await resolveParticipants(ctx.sessionModelId, isCouncilMultiProviderPreferred());
+    // C-v2 cross-session resume — a persisted debate checkpoint means the council
+    // debate was interrupted in a PRIOR session (the process died mid-round; the
+    // in-process C-v1 retry only covers same-session throws). Skip the already-
+    // completed + persisted discovery + interview and jump straight to the
+    // research/debate stage with the restored gather outputs; the `research` case
+    // reads the checkpoint and resumes the debate from its last completed round.
+    const priorCheckpoint = await readDebateCheckpoint(runDir);
+    if (priorCheckpoint) {
+        const inputs = await readDebateInputs(runDir);
+        if (inputs) {
+            clarifiedSpec = inputs.clarifiedSpec;
+            conversationContext = inputs.conversationContext;
+            state = "research";
+            yield {
+                type: "content",
+                content: `\n> Resuming an interrupted council debate (round ${priorCheckpoint.roundCount + 1}) — skipping discovery + interview.\n`,
+            };
+        }
+        else {
+            console.error(`[loop-driver] debate checkpoint present but debate-inputs.json missing (run ${ctx.runId}); running the council FSM fresh.`);
+        }
+    }
     while (true) {
         switch (state) {
             case "idle": {
@@ -218,6 +251,21 @@ export async function* runLoopDriver(ctx) {
                 if (discoveryCard) {
                     yield { type: "council_info_card", councilInfoCard: discoveryCard };
                 }
+                // Part A — persist prior-run context as a first-class context.md. The
+                // digest is intentionally NOT re-injected into the live system prompt
+                // (PIL Layer 3 already does semantic injection), but writing it to disk
+                // makes it a reviewable, resumable surface — the run's inherited memory.
+                try {
+                    const ctxParts = [`Prior runs on this workspace: ${prior.runs.length}`];
+                    if (prior.digest?.trim())
+                        ctxParts.push("", prior.digest.trim());
+                    if (audit.hasProject)
+                        ctxParts.push("", "## Repo audit", conversationContext);
+                    await writeContextDoc(ctx.flowDir, ctx.runId, ctxParts.join("\n"));
+                }
+                catch {
+                    /* non-critical — context.md is a review surface, never blocks the FSM */
+                }
                 // Persist discovery evidence + repo audit so resume can replay.
                 const stateMap = (await readArtifact(runDir, "state.md")) ?? { preamble: "", sections: new Map() };
                 if (discovery.evidence.length > 0) {
@@ -266,7 +314,12 @@ export async function* runLoopDriver(ctx) {
                 });
                 // Write Resume Digest to state.md
                 const stateMap = (await readArtifact(runDir, "state.md")) ?? { preamble: "", sections: new Map() };
-                stateMap.sections.set("Resume Digest", "Stage: Gather - Defining product dimensions");
+                stateMap.sections.set("Resume Digest", renderResumeDigest({
+                    stage: "gather",
+                    lastCompleted: "discover",
+                    nextAction: "Answer clarification questions to define product dimensions",
+                    updatedAt: new Date().toISOString(),
+                }));
                 await writeArtifact(runDir, "state.md", stateMap);
                 // runGatherPhase is async (not a generator), but the discovery
                 // interview emits askcard chunks via the io.emit callback. We collect
@@ -390,6 +443,9 @@ export async function* runLoopDriver(ctx) {
                 if (!clarifiedSpec) {
                     return { runId: ctx.runId, stage: "error", success: false, reason: "missing_spec_for_research" };
                 }
+                // Part E — web-research confidence for this run, filled when the
+                // Researcher stance is (re)assigned to a web-capable model below.
+                let researchWebConfidence;
                 const researchPhaseStartMs = Date.now();
                 yield phaseStart({
                     phaseId: "loop:research",
@@ -402,7 +458,12 @@ export async function* runLoopDriver(ctx) {
                     phase: "research",
                 });
                 const stateMap = (await readArtifact(runDir, "state.md")) ?? { preamble: "", sections: new Map() };
-                stateMap.sections.set("Resume Digest", "Stage: Research - Multi-expert debate");
+                stateMap.sections.set("Resume Digest", renderResumeDigest({
+                    stage: "research",
+                    lastCompleted: "gather",
+                    nextAction: "Run / resume the multi-expert council debate",
+                    updatedAt: new Date().toISOString(),
+                }));
                 await writeArtifact(runDir, "state.md", stateMap);
                 // inside research phase, before building councilTopic:
                 const projectCtx = await readProjectContext(ctx.flowDir, ctx.runId);
@@ -456,6 +517,42 @@ export async function* runLoopDriver(ctx) {
                         stance: s,
                     };
                 });
+                // Part E — the Researcher stance MUST prefer a model with NATIVE online
+                // web research (its own web_search/browsing), so the research phase gets
+                // real online facts rather than codebase-only reasoning. If a web-capable
+                // model is reachable this session, route the Researcher to it; otherwise
+                // record degraded confidence into research.md (the fallback add-in path
+                // — Tavily/MCP — is untrusted per the owner's Part E principle).
+                const { modelHasNativeWebResearch, getWebResearchModel } = await import("../models/registry.js");
+                const reachableIds = new Set([...councilParticipants.map((p) => p.model), leaderModelId].filter(Boolean));
+                const researcherIdx = participants.findIndex((p) => p.stance?.name === "Researcher");
+                if (researcherIdx >= 0) {
+                    const current = participants[researcherIdx].model;
+                    if (!modelHasNativeWebResearch(current)) {
+                        // ONLY reroute to a web-native model that is actually REACHABLE this
+                        // session. A model whose provider has no factory wired (e.g. grok/xai
+                        // when only opencode-go is authed) would fail council participant
+                        // creation ("no factory for model's provider") and wedge the debate —
+                        // so if no reachable web-native model exists, degrade gracefully and
+                        // KEEP the current reachable model rather than swap in a dead id.
+                        const webModel = getWebResearchModel(reachableIds);
+                        if (webModel) {
+                            participants[researcherIdx].model = webModel.id;
+                            researchWebConfidence = { confidence: "native", model: webModel.id };
+                        }
+                        else {
+                            researchWebConfidence = { confidence: "degraded" };
+                            logLoopEvent(ctx, "research_web_degraded", {
+                                phase: "research",
+                                reason: "no reachable native_web_research model",
+                                researcherModel: current,
+                            });
+                        }
+                    }
+                    else {
+                        researchWebConfidence = { confidence: "native", model: current };
+                    }
+                }
                 // CB-1 — BB-aware context injection. Runs before council debate fires so
                 // the research stances have access to relevant BB recipes and rules.
                 //
@@ -503,67 +600,125 @@ export async function* runLoopDriver(ctx) {
                         /* graceful degrade — never block the research phase */
                     }
                 }
-                const debateGen = runDebate(clarifiedSpec, {
-                    topic: ctx.idea,
+                // C-v2 — persist the minimal gather outputs so a fresh session can
+                // re-enter the debate (loop-driver resume entry above) without re-running
+                // the interactive discovery + interview. Written once here at debate start,
+                // captures the final conversationContext (after project + BB context).
+                // Deleted after scoping writes the spec. Non-fatal on failure.
+                await writeDebateInputs(runDir, {
+                    version: 1,
+                    problemStatement: clarifiedSpec.problemStatement,
+                    clarifiedSpec,
                     conversationContext,
-                    leaderModelId,
-                    participants,
-                }, wrapLLMForUsageTracking(ctx.llm, ctx));
-                // Suppress raw debate content so the user is not confused by inter-role
-                // monologue ("Researcher → Architect ... Question back to you?") which
-                // is NOT addressed to them. We still pass through phase/status events
-                // so the UI keeps a live progress indicator. After the debate completes
-                // we emit a single condensed summary.
-                try {
-                    while (true) {
-                        const { value, done } = await debateGen.next();
-                        if (done) {
-                            debateState = value;
-                            break;
+                    savedAt: new Date().toISOString(),
+                });
+                // C (mid-debate checkpoint) — runDebate snapshots its per-round state to
+                // `<runDir>/debate-checkpoint.json` after each completed round and deletes
+                // it on normal completion. If a prior attempt (this process, or a crashed
+                // earlier run of the SAME runId) left a checkpoint, seed it so the debate
+                // resumes from the last completed round instead of re-running rounds 1..N.
+                let resumeCheckpoint = (await readDebateCheckpoint(runDir)) ?? undefined;
+                // In-process resilience: a mid-debate throw (provider 5xx after the
+                // fallback budget, transient network) re-runs runDebate ONCE (default)
+                // from the freshly-written checkpoint, so a round-5 break loses one round,
+                // not five. Only retried when a checkpoint exists (≥1 round completed) —
+                // a pre-round-1 failure has nothing to resume and rethrows immediately.
+                const maxDebateRetries = (() => {
+                    const raw = process.env.MUONROI_DEBATE_RESUME_RETRIES;
+                    const n = raw ? Number.parseInt(raw, 10) : Number.NaN;
+                    return Number.isFinite(n) && n >= 0 ? n : 1;
+                })();
+                for (let attempt = 0;; attempt++) {
+                    const debateGen = runDebate(clarifiedSpec, {
+                        topic: ctx.idea,
+                        conversationContext,
+                        leaderModelId,
+                        participants,
+                        runId: ctx.sessionId ?? ctx.runId,
+                        checkpointDir: runDir,
+                        resumeCheckpoint,
+                        // Item 3 — per-stance recall: each participant opens grounded in the
+                        // stance-weighted slice of the brain its lens cares about. Bounded +
+                        // failure-tolerant; unavailable EE leaves openings unchanged.
+                        stanceRecall: makeStanceRecall(getDefaultEEClient(), {
+                            cwd: ctx.flowDir,
+                            sourceSession: ctx.sessionId ?? ctx.runId,
+                        }),
+                    }, ctx.llm);
+                    // Suppress raw debate content so the user is not confused by inter-role
+                    // monologue ("Researcher → Architect ... Question back to you?") which
+                    // is NOT addressed to them. We still pass through phase/status events
+                    // so the UI keeps a live progress indicator. After the debate completes
+                    // we emit a single condensed summary.
+                    try {
+                        while (true) {
+                            const { value, done } = await debateGen.next();
+                            if (done) {
+                                debateState = value;
+                                break;
+                            }
+                            const chunk = value;
+                            if (chunk.type === "content")
+                                continue;
+                            // Persist debate speaker turns to interaction_logs so forensics
+                            // can replay the debate text without relying on TUI scrollback
+                            // (which currently holds the only copy — messages/usage_events
+                            // tables stay empty for the debate path).
+                            if (chunk.type === "council_message" && chunk.councilMessage) {
+                                const cm = chunk.councilMessage;
+                                logLoopEvent(ctx, "council_message", {
+                                    phase: "research",
+                                    kind: cm.kind,
+                                    speakerRole: cm.speaker.role,
+                                    speakerModel: cm.speaker.model,
+                                    partnerRole: cm.partner?.role ?? null,
+                                    round: cm.round ?? null,
+                                    attempts: cm.attempts ?? 1,
+                                    failureReason: cm.failureReason ?? null,
+                                    toolCalls: cm.toolCalls?.map((tc) => tc.name) ?? [],
+                                    // Cap at 4000 chars so a single row stays well under SQLite
+                                    // text limits even for the most verbose speaker turn.
+                                    textExcerpt: cm.text.slice(0, 4000),
+                                    textLength: cm.text.length,
+                                    durationMs: cm.durationMs ?? null,
+                                }, { model: cm.speaker.model, durationMs: cm.durationMs });
+                            }
+                            yield chunk;
                         }
-                        const chunk = value;
-                        if (chunk.type === "content")
+                        break; // debate completed — exit the retry loop.
+                    }
+                    catch (err) {
+                        // The debate iterator hit an exception (e.g. provider 5xx after the
+                        // retry budget). Persist an audit row so we have a forensics trail —
+                        // without it the FSM unwinds silently and the session looks like
+                        // "research = 0 word" in the DB.
+                        const freshCp = (await readDebateCheckpoint(runDir)) ?? undefined;
+                        logLoopEvent(ctx, "council_error", {
+                            phase: "research",
+                            stage: "debate",
+                            error: err instanceof Error ? err.message : String(err),
+                            roundCount: debateState?.roundCount ?? freshCp?.roundCount ?? 0,
+                            participantCount: participants.length,
+                            elapsedMs: Date.now() - researchPhaseStartMs,
+                        });
+                        // C — resume-from-checkpoint retry: only when a completed round was
+                        // checkpointed and retries remain. Otherwise rethrow unchanged.
+                        if (attempt < maxDebateRetries && freshCp && freshCp.roundCount >= 1) {
+                            resumeCheckpoint = freshCp;
+                            yield {
+                                type: "content",
+                                content: `\n> Debate interrupted (${err instanceof Error ? err.message : String(err)}); resuming from round ${freshCp.roundCount + 1}…\n`,
+                            };
                             continue;
-                        // Persist debate speaker turns to interaction_logs so forensics
-                        // can replay the debate text without relying on TUI scrollback
-                        // (which currently holds the only copy — messages/usage_events
-                        // tables stay empty for the debate path).
-                        if (chunk.type === "council_message" && chunk.councilMessage) {
-                            const cm = chunk.councilMessage;
-                            logLoopEvent(ctx, "council_message", {
-                                phase: "research",
-                                kind: cm.kind,
-                                speakerRole: cm.speaker.role,
-                                speakerModel: cm.speaker.model,
-                                partnerRole: cm.partner?.role ?? null,
-                                round: cm.round ?? null,
-                                attempts: cm.attempts ?? 1,
-                                failureReason: cm.failureReason ?? null,
-                                toolCalls: cm.toolCalls?.map((tc) => tc.name) ?? [],
-                                // Cap at 4000 chars so a single row stays well under SQLite
-                                // text limits even for the most verbose speaker turn.
-                                textExcerpt: cm.text.slice(0, 4000),
-                                textLength: cm.text.length,
-                            });
                         }
-                        yield chunk;
+                        throw err;
                     }
                 }
-                catch (err) {
-                    // The debate iterator hit an exception (e.g. provider 5xx after the
-                    // retry budget). Persist an audit row before re-throwing so we have
-                    // a forensics trail — without it the FSM unwinds silently and the
-                    // session looks like "research = 0 word" in the DB.
-                    logLoopEvent(ctx, "council_error", {
-                        phase: "research",
-                        stage: "debate",
-                        error: err instanceof Error ? err.message : String(err),
-                        roundCount: debateState?.roundCount ?? 0,
-                        participantCount: participants.length,
-                        elapsedMs: Date.now() - researchPhaseStartMs,
-                    });
-                    throw err;
-                }
+                // F9 — resolve the debate summary once (runningSummary or a fallback
+                // synthesized from participant positions) for reuse across the research
+                // artifacts + scoping synthesis.
+                if (debateState)
+                    resolvedDebateSummary = resolveDebateSummary(debateState);
                 // Forensics row mirrors the council/index.ts council_summary record
                 // (which only fires for sprint planning via runCouncil). The /ideal
                 // initial debate goes through runDebate here and was previously
@@ -592,18 +747,47 @@ export async function* runLoopDriver(ctx) {
                         durationMs: Date.now() - researchPhaseStartMs,
                     });
                 }
-                const summaryText = debateState?.runningSummary?.trim() || "(debate produced no summary — using empty research findings)";
+                const summaryText = resolvedDebateSummary || "(debate produced no summary — using empty research findings)";
                 yield {
                     type: "council_info_card",
                     councilInfoCard: buildResearchSummaryCard(summaryText, debateState?.researchFindings),
                 };
-                // Append research summary to delegations.md
+                // Append research summary to delegations.md (kept for back-compat: the
+                // EE transcript extractor + legacy readers still read these sections).
+                // A debate that returns after openings (leader routes straight to the
+                // preflight gate) leaves runningSummary empty — synthesize a faithful
+                // fallback from the participants' positions so the canonical research
+                // artifacts never silently drop the whole debate.
                 const delegationsMap = (await readArtifact(runDir, "delegations.md")) ?? { preamble: "", sections: new Map() };
-                delegationsMap.sections.set("Research Summary", debateState.runningSummary);
+                delegationsMap.sections.set("Research Summary", resolvedDebateSummary);
                 if (debateState.researchFindings) {
                     delegationsMap.sections.set("Research Findings", debateState.researchFindings);
                 }
                 await writeArtifact(runDir, "delegations.md", delegationsMap);
+                // Part A — promote the debate output to a first-class research.md. This
+                // is the canonical, reviewable surface (`/ideal review`) and the home
+                // for the EE recall seed once per-turn grounding lands (deferred).
+                try {
+                    await writeResearchDoc(ctx.flowDir, ctx.runId, {
+                        summary: resolvedDebateSummary,
+                        findings: debateState.researchFindings ?? undefined,
+                        webResearch: researchWebConfidence,
+                    });
+                    // Part C — persist the debate as a workflow_debate experience so a
+                    // future run on a similar topic can seed its stances with what this
+                    // council concluded (gate-on-outcome: fired after the debate produced
+                    // a summary, not per-turn — Kill #4/#5).
+                    fireAndForgetWorkflowEvent({
+                        kind: "council-debate",
+                        phaseRef: `runs/${ctx.runId}#research`,
+                        sessionId: ctx.sessionId ?? ctx.runId,
+                        text: (debateState.runningSummary ?? "").slice(0, 2000) || `debate on: ${ctx.idea.slice(0, 200)}`,
+                        payload: { topic: ctx.idea.slice(0, 200), roundCount: debateState.roundCount ?? 0 },
+                    });
+                }
+                catch {
+                    /* non-critical — research.md is a review surface, never blocks the FSM */
+                }
                 // P6 - extract assumptions from the research debate so foundational
                 // claims (perf budgets, SDK contracts, etc.) become trackable across
                 // sprints rather than buried in stance prose. Silent skip on
@@ -667,7 +851,12 @@ export async function* runLoopDriver(ctx) {
                     phase: "scoping",
                 });
                 const stateMap = (await readArtifact(runDir, "state.md")) ?? { preamble: "", sections: new Map() };
-                stateMap.sections.set("Resume Digest", "Stage: Scoping - Synthesizing product roadmap");
+                stateMap.sections.set("Resume Digest", renderResumeDigest({
+                    stage: "scoping",
+                    lastCompleted: "research",
+                    nextAction: "Synthesize the ProductSpec and confirm the roadmap at the preflight gate",
+                    updatedAt: new Date().toISOString(),
+                }));
                 await writeArtifact(runDir, "state.md", stateMap);
                 // Visible progress indicator — without this the TUI sits silent for
                 // 30-60s while ctx.llm.generate runs the synthesis call. Users read
@@ -687,7 +876,7 @@ export async function* runLoopDriver(ctx) {
                 const synthesisPrompt = `Synthesize a ProductSpec JSON based on the following:
 Idea: ${ctx.idea}
 Clarified Spec: ${JSON.stringify(clarifiedSpec)}
-Debate Summary: ${debateState.runningSummary}
+Debate Summary: ${resolvedDebateSummary || debateState.runningSummary}
 Research Findings: ${debateState.researchFindings ?? "N/A"}
 
 Output ONLY a JSON object matching this interface:
@@ -758,6 +947,41 @@ interface ProductSpec {
                 const roadmapMap = (await readArtifact(runDir, "roadmap.md")) ?? { preamble: "", sections: new Map() };
                 roadmapMap.sections.set("Product Specification", JSON.stringify(productSpec, null, 2));
                 await writeArtifact(runDir, "roadmap.md", roadmapMap);
+                // Part C — the synthesized spec IS the council's decision. Persist it as
+                // a workflow_decision experience so future runs don't re-litigate a
+                // settled architectural/scoping choice.
+                fireAndForgetWorkflowEvent({
+                    kind: "decision",
+                    phaseRef: `runs/${ctx.runId}#scoping`,
+                    sessionId: ctx.sessionId ?? ctx.runId,
+                    text: `Scoped "${ctx.idea.slice(0, 120)}": ${(productSpec?.architecture ?? "").slice(0, 400)}`,
+                    payload: {
+                        persona: productSpec?.persona ?? null,
+                        mvp: productSpec?.mvp ?? [],
+                        sprintEstimate: productSpec?.sprintEstimate ?? null,
+                    },
+                });
+                // C-v2 — debate + scoping are done and the spec is persisted, so the
+                // cross-session resume inputs are obsolete (the checkpoint was already
+                // deleted by runDebate on completion). Clean them up so a later
+                // `/ideal resume` of this run does not re-enter the debate FSM.
+                await deleteDebateInputs(runDir);
+                // Hierarchy index — place this run under a milestone (the product idea)
+                // and a phase (this scoped iteration). Idempotent across resume; purely
+                // an index over runs/, never rewrites run artifacts or ROADMAP phases.
+                try {
+                    const mvpHead = Array.isArray(productSpec?.mvp) && productSpec.mvp.length > 0 ? productSpec.mvp[0] : "";
+                    await ensureRunScoped(ctx.flowDir, {
+                        runId: ctx.runId,
+                        milestoneTitle: clampTitle(ctx.idea, 60),
+                        milestoneGoal: (productSpec?.architecture ?? "").slice(0, 200),
+                        phaseTitle: clampTitle(mvpHead || ctx.idea, 50),
+                        phaseGoal: (productSpec?.persona ?? "").slice(0, 200),
+                    }, new Date().toISOString());
+                }
+                catch {
+                    /* non-critical — hierarchy is an index; failure must not block scoping */
+                }
                 // P8 - derive tasks.json from the spec (canonical machine-readable
                 // surface for downstream /execute consumption). MVP items get
                 // sprint=1, phase2 gets sprint=2. Re-deriving the same spec is

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

@@ -3,6 +3,27 @@ import type { Migrator } from "./discovery-migrations.js";
 import type { LeaderLike } from "./discovery-prompt-parser.js";
 import type { PhasePlanArtifact, ProductRunManifest } from "./types.js";
 export declare const PHASE_PLANNER_SYSTEM: string;
+/**
+ * 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 declare function clampMaxSprints(raw: unknown): number;
+export declare function normalizePhasePlan(plan: PhasePlanArtifact): PhasePlanArtifact;
 export declare function parsePhasePlanJson(raw: string): PhasePlanArtifact;
 export declare function validatePhasePlan(plan: PhasePlanArtifact, spec: ClarifiedSpec): void;
 export declare function fallbackSinglePhase(spec: ClarifiedSpec, manifest: ProductRunManifest): PhasePlanArtifact;