muonroi-cli 1.8.4 → 1.9.0

package/dist/src/council/clarifier.js

@@ -1,5 +1,8 @@
+import { getMcpKey } from "../mcp/mcp-keychain.js";
+import { getWebResearchModel } from "../models/registry.js";
+import { getCouncilLanguage } from "../utils/settings.js";
 import { pickCouncilTaskModel } from "./leader.js";
-import { tracedGenerate } from "./llm.js";
+import { tracedAsync, tracedGenerate, tracedGenerateWithFallback } from "./llm.js";
 import { phaseDone, phaseError, phaseStart } from "./phase-events.js";
 import { buildClarificationPrompt, buildReadinessJudgePrompt, buildSpecSynthesisPrompt } from "./prompts.js";
 /** P5: Hard cap on clarification rounds regardless of judge verdict. */
@@ -97,6 +100,51 @@ function grayAreaToRoundQuestion(g) {
         isRequired: true,
     };
 }
+/**
+ * Resolve the concrete interview language from the council language setting +
+ * the topic. Pinned locale → that locale; "english" → English; "auto" (default)
+ * → detect from the topic (Vietnamese diacritics, mirroring
+ * `detectReplyLanguageHint`). Returned as a concrete name so the clarify prompt
+ * FORCES it (immune to an English "## Scope Research" block) and the escape-hatch
+ * labels can be localized.
+ */
+const VI_DIACRITIC_RE = /[à-ỹÀ-Ỹ]/;
+export function resolveInterviewLanguage(topic) {
+    const setting = getCouncilLanguage();
+    if (setting && setting !== "auto" && setting !== "english")
+        return setting;
+    if (setting === "english")
+        return "english";
+    return VI_DIACRITIC_RE.test(topic ?? "") ? "vietnamese" : "english";
+}
+/**
+ * The two escape-hatch options appended to every clarification card, localized to
+ * the interview language so a Vietnamese interview doesn't show English buttons.
+ * `lang` is a concrete language name; anything not recognized as Vietnamese falls
+ * back to English labels (the LLM-authored question itself is still localized).
+ * When `lang` is undefined the historical English-label pair is kept byte-
+ * identical so existing callers/tests are unaffected.
+ */
+function escapeHatchOptions(lang) {
+    const isVi = typeof lang === "string" && /vietnamese|tiếng việt/i.test(lang.trim());
+    if (isVi) {
+        return [
+            { label: "Nhập câu trả lời", description: "Nhập câu trả lời tự do", value: "", kind: "freetext" },
+            { label: "Thảo luận thêm", description: "Thảo luận thêm trước khi trả lời", value: "", kind: "chat" },
+        ];
+    }
+    if (lang === undefined) {
+        // Historical default preserved byte-identical (EN label + VN description).
+        return [
+            { label: "Type something", description: "Nhập câu trả lời tự do", value: "", kind: "freetext" },
+            { label: "Chat about this", description: "Thảo luận thêm trước khi trả lời", value: "", kind: "chat" },
+        ];
+    }
+    return [
+        { label: "Type something", description: "Type a free-form answer", value: "", kind: "freetext" },
+        { label: "Chat about this", description: "Discuss before answering", value: "", kind: "chat" },
+    ];
+}
 /**
  * Convert legacy `suggestions: string[]` into the new options schema with
  * standard "Type something" / "Chat about this" escape-hatches appended.
@@ -110,25 +158,11 @@ function grayAreaToRoundQuestion(g) {
  * returned `defaultIndex` points to it. Otherwise `defaultIndex` is omitted
  * so the UI knows to suppress the "(Recommended)" tag.
  */
-export function buildClarifyOptions(suggestions, recommended) {
+export function buildClarifyOptions(suggestions, recommended, lang) {
     const choices = (suggestions ?? [])
         .filter((s) => typeof s === "string" && s.trim().length > 0)
         .map((s) => ({ label: s.trim(), value: s.trim(), kind: "choice" }));
-    const options = [
-        ...choices,
-        {
-            label: "Type something",
-            description: "Nhập câu trả lời tự do",
-            value: "",
-            kind: "freetext",
-        },
-        {
-            label: "Chat about this",
-            description: "Thảo luận thêm trước khi trả lời",
-            value: "",
-            kind: "chat",
-        },
-    ];
+    const options = [...choices, ...escapeHatchOptions(lang)];
     let defaultIndex;
     if (typeof recommended === "string" && recommended.trim().length > 0) {
         const target = recommended.trim().toLowerCase();
@@ -138,6 +172,123 @@ export function buildClarifyOptions(suggestions, recommended) {
     }
     return { options, defaultIndex };
 }
+/**
+ * Build council options from the model's richer `{label, description,
+ * recommended}` objects, preserving each choice's explanation as `description`
+ * and pointing `defaultIndex` at the option the model flagged `recommended`
+ * (falling back to the first when none is flagged). The same "Type something" /
+ * "Chat about this" escape-hatches are appended as in `buildClarifyOptions`.
+ * Pure + exported for unit testing.
+ */
+export function buildClarifyOptionsRich(specs, lang) {
+    const cleaned = (specs ?? []).filter((s) => !!s && typeof s.label === "string" && s.label.trim().length > 0);
+    const choices = cleaned.map((s) => ({
+        label: s.label.trim(),
+        value: s.label.trim(),
+        kind: "choice",
+        ...(typeof s.description === "string" && s.description.trim().length > 0
+            ? { description: s.description.trim() }
+            : {}),
+    }));
+    const options = [...choices, ...escapeHatchOptions(lang)];
+    let defaultIndex;
+    const recIdx = cleaned.findIndex((s) => s.recommended === true);
+    if (recIdx !== -1)
+        defaultIndex = recIdx;
+    return { options, defaultIndex };
+}
+/**
+ * Pre-clarify scope research (research-first grounding).
+ *
+ * Before asking ANY clarification question, research the topic — codebase for an
+ * existing repo (the research method reads the tree) plus web — so the
+ * question-generator surfaces the REAL gray areas the evidence exposes instead
+ * of guessing blind ("hỏi tào lao"). The returned brief is appended to the
+ * `conversationContext` that `buildClarificationPrompt` already reads, so both
+ * `/council` and `/ideal` (which reuses this clarifier as its gather engine)
+ * inherit evidence-grounded questions from one shared code path.
+ *
+ * Web-capability policy (owner's Part E rule): PREFER a model with native web
+ * research integrated (catalog `nativeWebResearch`), switching the research call
+ * to it when one is reachable. Only when no native-web model is reachable fall
+ * back to Tavily (via the research method's builtin web tools). When NEITHER a
+ * native-web model NOR a Tavily key exists, warn the user before continuing —
+ * research proceeds on the codebase + model knowledge only, never silently blind.
+ * (Codebase evidence is always gathered by the research tool regardless of the
+ * web tier, so an existing repo is still grounded.)
+ *
+ * Never throws and never blocks the interview: if the flag is off, the llm has
+ * no `research` method (most unit-test mocks), the run is aborted, or the call
+ * fails, it yields nothing and returns "". Default ON; opt out with
+ * MUONROI_CLARIFY_RESEARCH_FIRST=0.
+ */
+async function hasTavilyKey() {
+    try {
+        const k = ((await getMcpKey("tavily")) || process.env.TAVILY_API_KEY || "").trim();
+        return k.length >= 10;
+    }
+    catch {
+        return (process.env.TAVILY_API_KEY ?? "").trim().length >= 10;
+    }
+}
+export async function* researchScopeForClarification(topic, conversationContext, leaderModelId, llm, signal, reachableModels) {
+    if (process.env.MUONROI_CLARIFY_RESEARCH_FIRST === "0")
+        return "";
+    if (signal?.aborted)
+        return "";
+    // Skip cleanly when the injected llm can't research (generate-only test mocks)
+    // — keeps every existing clarifier test on its current, research-free path.
+    if (typeof llm.research !== "function")
+        return "";
+    // Choose the research model + web tier. Prefer a reachable native-web model.
+    const reachable = new Set([leaderModelId, ...reachableModels].filter(Boolean));
+    const nativeModel = getWebResearchModel(reachable);
+    let researchModel = leaderModelId;
+    let webTier;
+    if (nativeModel) {
+        researchModel = nativeModel.id;
+        webTier = "native";
+    }
+    else {
+        webTier = (await hasTavilyKey()) ? "tavily" : "none";
+    }
+    const phaseId = "phase:clarification-scope-research";
+    const startedAt = Date.now();
+    yield phaseStart({ phaseId, kind: "clarification", label: "Scope research" });
+    // Owner's Part E principle: never research the web fully blind without telling
+    // the user. Codebase + model-knowledge research still runs, but web findings
+    // will be absent — surface that so they can wire a native-web model or Tavily.
+    if (webTier === "none") {
+        yield {
+            type: "content",
+            content: `\n> ⚠ Scope research: no web-research-native model is reachable and no Tavily key is configured. ` +
+                `Researching from the codebase + model knowledge only — no live web findings. ` +
+                `Configure a native-web model or a Tavily API key for grounded web research.\n`,
+        };
+    }
+    try {
+        const goal = `${topic}\n\n(Research goal: narrow the scope of this request. Report verified findings, and — ` +
+            `critically — END with an explicit "## Open Questions / Assumptions" section listing what you could ` +
+            `NOT verify and had to ASSUME (the real goal/pain, the concrete task, the system of record, the ` +
+            `target user, hard constraints). Those unresolved items are exactly what the user must clarify next, ` +
+            `so name them plainly rather than papering over them with a plausible guess.)`;
+        const brief = yield* tracedAsync(() => llm.research(researchModel, goal, conversationContext, signal, undefined, {
+            internetFirst: webTier !== "none",
+        }), { phase: "clarify", label: "Scope research" });
+        yield phaseDone({ phaseId, kind: "clarification", label: "Scope research", startedAt });
+        return typeof brief === "string" ? brief.trim() : "";
+    }
+    catch (err) {
+        yield phaseError({
+            phaseId,
+            kind: "clarification",
+            label: "Scope research",
+            startedAt,
+            errorMessage: err instanceof Error ? err.message : String(err),
+        });
+        return "";
+    }
+}
 export async function* runClarification(topic, leaderModelId, conversationContext, respondToQuestion, llm, signal, seedQuestions, maxRounds, 
 /**
  * Optional pre-filled answers keyed by seed-question id. When the loop's
@@ -152,16 +303,32 @@ prefillAnswers,
  * a cheaper tier model on the same provider as the leader. Falls back to
  * the leader model if no cheaper model is cataloged. Default false.
  */
-costAware = false) {
+costAware = false, 
+/**
+ * Healthy panel models to fall back to when the leader's cost-tier spec-synth
+ * model is on a failing proxy — keeps the spec's ≥3 observable criteria (and
+ * thus a meaningful leader eval) instead of degrading to one generic criterion.
+ */
+fallbackModels = []) {
     // P5: use MAX_CLARIFY_ROUNDS (12) as the hard cap; respect explicit override
     // from callers that pass maxRounds (e.g. tests that want old 3-round behavior).
     const max = typeof maxRounds === "number" && maxRounds > 0 ? maxRounds : MAX_CLARIFY_ROUNDS;
+    // Interview language (the user's conversation language, not English-by-default).
+    // Resolved once and forced into the clarify prompt + escape-hatch labels.
+    const uiLang = resolveInterviewLanguage(topic);
     const allQA = [];
     // P5: full Q&A history with timestamps for clarifyHistory field
     const clarifyHistory = [];
     const phaseStartedAt = Date.now();
     yield phaseStart({ phaseId: "phase:clarification", kind: "clarification", label: "Clarification" });
     const seeded = (seedQuestions ?? []).map(grayAreaToRoundQuestion);
+    // Research-first: ground the interview in evidence BEFORE asking anything, so
+    // the question-generator targets the real gray areas the research surfaced
+    // rather than guessing. Appended to the context every round's prompt reads.
+    const scopeBrief = yield* researchScopeForClarification(topic, conversationContext, leaderModelId, llm, signal, fallbackModels);
+    if (scopeBrief) {
+        conversationContext = `${conversationContext}${conversationContext ? "\n\n" : ""}## Scope Research\n${scopeBrief}`;
+    }
     // P5: track ready-gate state across rounds
     let gateReady = false;
     let gateConfidence = 0;
@@ -195,7 +362,7 @@ costAware = false) {
             const gapHint = pendingGaps.length > 0
                 ? `\n\n## Known Gaps (target these with follow-up questions)\n${pendingGaps.map((g) => `- ${g}`).join("\n")}`
                 : "";
-            const { system, prompt } = buildClarificationPrompt(topic, conversationContext, allQA.length > 0 ? allQA : undefined);
+            const { system, prompt } = buildClarificationPrompt(topic, conversationContext, allQA.length > 0 ? allQA : undefined, uiLang);
             let questionsRaw;
             try {
                 const clarifyModel = pickCouncilTaskModel("clarify_questions", leaderModelId, costAware);
@@ -284,7 +451,16 @@ costAware = false) {
                 continue;
             }
             const questionId = crypto.randomUUID();
-            const { options, defaultIndex } = buildClarifyOptions(q.suggestions, q.recommended);
+            // Prefer the model's richer {label, description, recommended} options so
+            // every choice shows its own explanation + the recommended default is
+            // pre-selected. Fall back to the legacy string `suggestions` shape (PIL
+            // gray-area seeds and any model still emitting the old format).
+            const { options, defaultIndex } = q.options && q.options.length > 0
+                ? buildClarifyOptionsRich(q.options, uiLang)
+                : buildClarifyOptions(q.suggestions, q.recommended, uiLang);
+            // Keep the deprecated `suggestions` mirror populated for consumers that
+            // still read it (audit/replay), deriving labels from rich options.
+            const suggestionLabels = q.suggestions ?? (q.options ? q.options.map((o) => o.label).filter((l) => typeof l === "string") : undefined);
             yield {
                 type: "council_question",
                 content: `**${q.question}**\n${q.why ? `> ${q.why}` : ""}`,
@@ -293,7 +469,7 @@ costAware = false) {
                     phase: "clarify",
                     question: q.question,
                     context: q.why,
-                    suggestions: q.suggestions,
+                    suggestions: suggestionLabels,
                     options,
                     isRequired: q.isRequired,
                     defaultIndex,
@@ -329,7 +505,7 @@ costAware = false) {
         startedAt: phaseStartedAt,
         detail: allQA.length > 0 ? `${allQA.length} Q&A` : "no clarification needed",
     });
-    const spec = yield* synthesizeSpec(topic, conversationContext, allQA, leaderModelId, llm, costAware);
+    const spec = yield* synthesizeSpec(topic, conversationContext, allQA, leaderModelId, llm, costAware, fallbackModels);
     // P5: attach ready-gate metadata to the returned spec
     spec.confidenceScore = gateConfidence;
     spec.remainingGaps = gateGaps;
@@ -355,13 +531,18 @@ costAware = false) {
     };
     return spec;
 }
-export function buildSpecFromTopic(topic, _conversationContext) {
+export function buildSpecFromTopic(topic, conversationContext) {
     return {
         problemStatement: topic,
         constraints: [],
         successCriteria: [`Address the topic: ${topic.slice(0, 100)}`],
         scope: "Determined by conversation context",
         rawQA: [],
+        // Carry the session/task context onto the spec so every debate stage (not
+        // just the opening) can stay anchored to the parent task. Previously this
+        // argument was dropped (prefixed `_`), which is why auto-council debates saw
+        // only the isolated sub-task and drifted off-topic.
+        parentContext: conversationContext?.trim() || undefined,
     };
 }
 /**
@@ -374,7 +555,7 @@ export function buildSpecFromTopic(topic, _conversationContext) {
  * We LLM-extract criteria/constraints/scope from the topic when QA is empty.
  * Falls back to the original buildSpecFromTopic if the LLM call fails.
  */
-async function* inferSpecFromTopicOnly(topic, conversationContext, leaderModelId, llm, costAware) {
+async function* inferSpecFromTopicOnly(topic, conversationContext, leaderModelId, llm, costAware, fallbackModels = []) {
     const system = `You are extracting an implicit specification from a short topic statement. ` +
         `The user did not answer clarification questions, but the topic itself often ` +
         `implies scope, criteria, and constraints. Tease them out.\n\n` +
@@ -396,16 +577,21 @@ async function* inferSpecFromTopicOnly(topic, conversationContext, leaderModelId
         `- Write all fields in the user's language (detected from the topic).`;
     const prompt = `## Topic\n${topic}\n\n${conversationContext ? `## Context\n${conversationContext}\n` : ""}`;
     try {
+        // Model-fallback: the cost-tier synth model can sit on a flaky proxy
+        // (Console Go glm/kimi → "Upstream request failed"). Falling back to
+        // buildSpecFromTopic yields a single generic criterion, which makes the
+        // leader eval read a vague "1/1 criteria met". Retry on healthy panel models
+        // first so the spec keeps its ≥3 observable criteria.
         const synthModel = pickCouncilTaskModel("spec_synthesis", leaderModelId, costAware);
-        const raw = yield* tracedGenerate(llm, {
+        const raw = yield* tracedGenerateWithFallback(llm, {
             phase: "synthesis",
             label: "Inferring spec from topic (no clarification answers)",
-            modelId: synthModel,
+            models: [synthModel, ...fallbackModels],
             system,
             prompt,
             maxTokens: 1024,
         });
-        const match = raw.match(/\{[\s\S]*\}/);
+        const match = raw?.match(/\{[\s\S]*\}/);
         if (match) {
             const parsed = JSON.parse(match[0]);
             const criteria = Array.isArray(parsed.successCriteria) && parsed.successCriteria.length >= 1
@@ -429,12 +615,12 @@ async function* inferSpecFromTopicOnly(topic, conversationContext, leaderModelId
     }
     return buildSpecFromTopic(topic, conversationContext);
 }
-async function* synthesizeSpec(topic, conversationContext, qa, leaderModelId, llm, costAware = false) {
+async function* synthesizeSpec(topic, conversationContext, qa, leaderModelId, llm, costAware = false, fallbackModels = []) {
     if (qa.length === 0) {
         // Clarifier asked 0 questions OR user skipped all of them. Use the LLM to
         // pull implicit criteria/constraints/scope from the topic alone instead of
         // returning the single-criterion fallback that makes leader-eval trivial.
-        return yield* inferSpecFromTopicOnly(topic, conversationContext, leaderModelId, llm, costAware);
+        return yield* inferSpecFromTopicOnly(topic, conversationContext, leaderModelId, llm, costAware, fallbackModels);
     }
     const { system, prompt } = buildSpecSynthesisPrompt(topic, conversationContext, qa);
     const resolved = {};
@@ -444,16 +630,18 @@ async function* synthesizeSpec(topic, conversationContext, qa, leaderModelId, ll
         }
     }
     try {
+        // Model-fallback (see inferSpecFromTopicOnly): keep the ≥3-criteria spec even
+        // when the leader's cost-tier synth model is on a failing proxy.
         const synthModel = pickCouncilTaskModel("spec_synthesis", leaderModelId, costAware);
-        const raw = yield* tracedGenerate(llm, {
+        const raw = yield* tracedGenerateWithFallback(llm, {
             phase: "synthesis",
             label: "Synthesizing clarified spec",
-            modelId: synthModel,
+            models: [synthModel, ...fallbackModels],
             system,
             prompt,
             maxTokens: 2048,
         });
-        const match = raw.match(/\{[\s\S]*\}/);
+        const match = raw?.match(/\{[\s\S]*\}/);
         if (match) {
             const parsed = JSON.parse(match[0]);
             return {

package/dist/src/council/context.js

@@ -98,7 +98,7 @@ function getCompactionText(msg) {
         return null;
     return msg.content;
 }
-function extractUserText(content) {
+function extractText(content) {
     if (typeof content === "string")
         return content;
     if (Array.isArray(content)) {
@@ -109,40 +109,74 @@ function extractUserText(content) {
     }
     return "";
 }
+/** Filter assistant messages to exclude tool-call-only turns (tool_use + tool_result
+ *  pairs that carry no analytical text). An assistant turn with ≥80 chars of text
+ *  content is considered "analytical" (contains decisions, analysis, code, or plans). */
+function isAnalyticalAssistant(content) {
+    const text = extractText(content);
+    return text.trim().length >= 80;
+}
+/** Maximum total characters for the built context string. Raised from 12K to 32K
+ *  (~8K tokens) so council participants get meaningful session history rather than
+ *  only 5 user-message snippets. */
+const MAX_CONTEXT_CHARS = 32_000;
 export function buildCouncilContext(messages) {
     const parts = [];
+    // 1. Compaction summary (first message if it's a system compaction)
     if (messages.length > 0 && isCompactionSummary(messages[0])) {
         const summary = getCompactionText(messages[0]);
         if (summary) {
             parts.push(`## Session Context (from compaction summary)\n${summary}`);
         }
     }
-    const userMessages = [];
-    for (let i = messages.length - 1; i >= 0 && userMessages.length < 5; i--) {
+    // 2. Recent conversation turns — scan BOTH user + analytical assistant messages
+    //    from the tail, capturing at most 8 meaningful entries.
+    //    Previously only captured 5 user messages — lost ALL assistant analysis,
+    //    code changes, and decisions made during the session.
+    const conversationTurns = [];
+    for (let i = messages.length - 1; i >= 0 && conversationTurns.length < 8; i--) {
         const msg = messages[i];
         if (msg.role === "user") {
-            const text = extractUserText(msg.content);
+            const text = extractText(msg.content);
+            if (text.trim()) {
+                conversationTurns.unshift(`[User] ${text.slice(0, 3000).trim()}`);
+            }
+        }
+        else if (msg.role === "assistant" && isAnalyticalAssistant(msg.content)) {
+            const text = extractText(msg.content);
             if (text.trim()) {
-                userMessages.unshift(`- ${text.slice(0, 2000).trim()}`);
+                // Cap assistant text to 1500 chars — enough to convey analysis/decisions
+                // without blowing the context budget on long code outputs.
+                conversationTurns.unshift(`[Assistant] ${text.slice(0, 1500).trim()}`);
             }
         }
     }
-    if (userMessages.length > 0) {
-        parts.push(`## Recent User Messages\n${userMessages.join("\n")}`);
+    if (conversationTurns.length > 0) {
+        parts.push(`## Recent Conversation\n${conversationTurns.join("\n\n")}`);
     }
-    const councilMemories = [];
+    // 3. Key decisions from system messages (task outcomes, decisions, plans)
+    const decisionMsgs = [];
     for (const msg of messages) {
-        if (msg.role === "system" && typeof msg.content === "string" && msg.content.includes("[Council Memory]")) {
-            councilMemories.push(msg.content);
+        if (msg.role !== "system" || typeof msg.content !== "string")
+            continue;
+        const c = msg.content;
+        if (c.includes("[Council Memory]") ||
+            c.includes("[Council Decision]") ||
+            c.includes("[Council Action Items]") ||
+            c.includes("[Council Plan Update]") ||
+            c.includes("[Decision]") ||
+            c.includes("[Task Completed]") ||
+            c.includes("[NEEDS HUMAN REVIEW]")) {
+            decisionMsgs.push(c);
         }
     }
-    if (councilMemories.length > 0) {
-        const digests = councilMemories.slice(-2).map(formatCouncilMemoryDigest);
-        parts.push(`## Previous Council Outcomes (cite by role/round)\n${digests.join("\n\n")}`);
+    if (decisionMsgs.length > 0) {
+        const digests = decisionMsgs.slice(-4).map(formatCouncilMemoryDigest);
+        parts.push(`## Key Decisions\n${digests.join("\n\n")}`);
     }
     const combined = parts.join("\n\n---\n\n");
-    if (combined.length > 12000) {
-        return `${combined.slice(0, 12000)}\n\n[... context truncated to fit token budget]`;
+    if (combined.length > MAX_CONTEXT_CHARS) {
+        return `${combined.slice(0, MAX_CONTEXT_CHARS)}\n\n[... context truncated to fit token budget]`;
     }
     return combined;
 }

package/dist/src/council/debate-checkpoint.d.ts

@@ -0,0 +1,129 @@
+/**
+ * src/council/debate-checkpoint.ts
+ *
+ * C (mid-debate checkpoint) — persist the CB-1 council debate's per-round state
+ * so a break mid-debate (provider 5xx on round 5, host crash, cap breach) can
+ * resume from the last completed round instead of re-running the whole debate.
+ *
+ * The debate accumulates all state in RAM (`exchangeLogs`, `active`,
+ * `runningSummary`, `archive`, convergence trackers). Without a checkpoint a
+ * break loses every round — a 5-round multi-provider debate must restart from
+ * round 1. This module owns the on-disk snapshot: `runDebate` writes it after
+ * each completed round and deletes it on normal completion; the resume path
+ * reads it and seeds `runDebate` so it skips research + openings + completed
+ * rounds.
+ *
+ * File: `<checkpointDir>/debate-checkpoint.json` (checkpointDir = the run dir,
+ * `.muonroi-flow/runs/<runId>`). Written atomically (tmp + rename) so a crash
+ * mid-write can never leave a half-JSON file.
+ */
+import type { ClarifiedSpec, CouncilParticipant, DebateArchiveEntry } from "./types.js";
+/** Bump when the checkpoint shape changes incompatibly so stale files are ignored. */
+export declare const DEBATE_CHECKPOINT_VERSION: 1;
+export declare const DEBATE_CHECKPOINT_FILE = "debate-checkpoint.json";
+/**
+ * Serializable snapshot of an in-flight debate, written after each completed
+ * discussion round. `exchangeLogs` (a `Map`) is stored as entry tuples since
+ * JSON has no Map; everything else in the payload is already JSON-native.
+ */
+export interface DebateCheckpoint {
+    version: typeof DEBATE_CHECKPOINT_VERSION;
+    /**
+     * Identity guard — the checkpoint is only restored when it matches the debate
+     * about to run. `problemStatement` pins the spec; `participantModels` pins the
+     * panel. A mismatch (spec changed, panel re-resolved differently) => ignore
+     * the stale checkpoint and run the debate fresh rather than splice wrong state.
+     */
+    problemStatement: string;
+    participantModels: string[];
+    /** Rounds fully completed (transcript + summary persisted). Resume starts at roundCount+1. */
+    roundCount: number;
+    /** Current round budget after any leader/user extensions. */
+    maxRounds: number;
+    /** Accumulated per-pair transcript (Map<pairKey, turns[]> serialized as entries). */
+    exchangeLogs: Array<[string, string[]]>;
+    /** Latest inter-round summary. */
+    runningSummary: string;
+    /** Research findings (so the research phase is not re-run on resume). */
+    researchFindings?: string;
+    /** Surviving participants with their latest position + stance (so openings are not re-run). */
+    active: CouncilParticipant[];
+    /** Citation archive accumulated so far. */
+    archive: DebateArchiveEntry[];
+    /** Convergence continuity: last round's per-criterion met flags. */
+    lastCriteriaMet: boolean[];
+    /** B4 auto-remedy high-water mark of pinned criteria met. */
+    bestCriteriaMetCount: number;
+    /** B4 consecutive evaluated rounds with no new met criterion. */
+    roundsSinceProgress: number;
+    /** Topic carried into the next round from the prior leader nextRoundFocus. */
+    nextTopic?: string;
+    /** Wall-clock the checkpoint was written (ISO). Diagnostics only. */
+    savedAt: string;
+}
+/** Input to {@link buildDebateCheckpoint} — the live round-loop locals. */
+export interface DebateCheckpointInput {
+    problemStatement: string;
+    roundCount: number;
+    maxRounds: number;
+    exchangeLogs: Map<string, string[]>;
+    runningSummary: string;
+    researchFindings?: string;
+    active: CouncilParticipant[];
+    archive: DebateArchiveEntry[];
+    lastCriteriaMet: boolean[];
+    bestCriteriaMetCount: number;
+    roundsSinceProgress: number;
+    nextTopic?: string;
+    /** ISO timestamp; the caller supplies it (Date.now is unavailable in some sandboxes). */
+    savedAt: string;
+}
+/** Build the serializable checkpoint payload from live debate state. */
+export declare function buildDebateCheckpoint(input: DebateCheckpointInput): DebateCheckpoint;
+/** Rehydrate `exchangeLogs` from the serialized entry tuples. */
+export declare function restoreExchangeLogs(cp: DebateCheckpoint): Map<string, string[]>;
+/**
+ * Whether `cp` describes the debate that is about to run. Guards against
+ * splicing a stale checkpoint (different question, re-resolved panel) into a
+ * fresh debate. Participant order is not significant; the model SET must match.
+ */
+export declare function checkpointMatches(cp: DebateCheckpoint, problemStatement: string, participantModels: string[]): boolean;
+/**
+ * Atomically write the checkpoint to `<dir>/debate-checkpoint.json`.
+ * Non-fatal: a checkpoint write failure must never break the live debate — it
+ * only forfeits resumability for that round. Logs with context (No-Silent-Catch).
+ */
+export declare function writeDebateCheckpoint(dir: string, cp: DebateCheckpoint): Promise<void>;
+/**
+ * Read + parse the checkpoint. Returns null when absent or unparseable (a
+ * corrupt checkpoint must not crash resume — the debate just runs fresh).
+ */
+export declare function readDebateCheckpoint(dir: string): Promise<DebateCheckpoint | null>;
+/**
+ * Delete the checkpoint (debate completed normally, or the run was aborted).
+ * Non-fatal — a leftover checkpoint is only re-validated (and discarded on
+ * mismatch) on the next resume, never silently mis-applied.
+ */
+export declare function deleteDebateCheckpoint(dir: string): Promise<void>;
+export declare const DEBATE_INPUTS_FILE = "debate-inputs.json";
+/**
+ * C-v2 — the minimal gather-stage outputs needed to re-enter the council debate
+ * on a fresh session (cross-process resume) WITHOUT re-running the interactive
+ * discovery + interview. Persisted once at debate start; the loop-driver resume
+ * entry restores `clarifiedSpec` + `conversationContext` and jumps straight to
+ * the research/debate stage (participants + leader are re-resolved from the
+ * session model deterministically, then matched against the checkpoint panel).
+ */
+export interface DebateInputs {
+    version: typeof DEBATE_CHECKPOINT_VERSION;
+    problemStatement: string;
+    clarifiedSpec: ClarifiedSpec;
+    conversationContext: string;
+    savedAt: string;
+}
+/** Atomically persist the debate inputs. Non-fatal on failure (forfeits cross-session resume only). */
+export declare function writeDebateInputs(dir: string, inputs: DebateInputs): Promise<void>;
+/** Read the debate inputs. Returns null when absent/unparseable/version-mismatched. */
+export declare function readDebateInputs(dir: string): Promise<DebateInputs | null>;
+/** Delete the debate inputs (debate + scoping finished, or run aborted). Non-fatal. */
+export declare function deleteDebateInputs(dir: string): Promise<void>;