muonroi-cli 1.8.5 → 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, tracedGenerateWithFallback } 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();
@@ -146,7 +180,7 @@ export function buildClarifyOptions(suggestions, recommended) {
  * "Chat about this" escape-hatches are appended as in `buildClarifyOptions`.
  * Pure + exported for unit testing.
  */
-export function buildClarifyOptionsRich(specs) {
+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(),
@@ -156,27 +190,105 @@ export function buildClarifyOptionsRich(specs) {
             ? { description: s.description.trim() }
             : {}),
     }));
-    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;
     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
@@ -201,12 +313,22 @@ 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;
@@ -240,7 +362,7 @@ fallbackModels = []) {
             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);
@@ -334,8 +456,8 @@ fallbackModels = []) {
             // 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)
-                : buildClarifyOptions(q.suggestions, q.recommended);
+                ? 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);

package/dist/src/council/debate-planner.js

@@ -177,8 +177,9 @@ signal) {
     try {
         const providerId = detectProviderForModel(leaderModelId);
         const key = await loadKeyForProvider(providerId);
-        const { factory } = createProviderFactory(providerId, { apiKey: key });
-        const runtime = resolveModelRuntime(factory, leaderModelId);
+        // Registers the leader provider's factory so resolveModelRuntime can derive it.
+        createProviderFactory(providerId, { apiKey: key });
+        const runtime = resolveModelRuntime(leaderModelId);
         // Bound attempt-1: a wedged provider response here would freeze the whole
         // council/loop silently (no streamText stall watchdog covers generateObject).
         // On timeout this rejects → caught below → retry (guarded) → fallback plan.

package/dist/src/council/debate.js

@@ -1,11 +1,12 @@
 import { randomUUID } from "node:crypto";
 import { getModelInfo } from "../models/registry.js";
 import { detectProviderForModel } from "../providers/runtime.js";
+import { getIsolatedTaskDeadlineMs, withDeadlineRace } from "../utils/llm-deadline.js";
 import { getCouncilLanguage } from "../utils/settings.js";
 import { buildDebateCheckpoint, checkpointMatches, deleteDebateCheckpoint, restoreExchangeLogs, writeDebateCheckpoint, } from "./debate-checkpoint.js";
 import { resolveDebateSummary } from "./debate-summary.js";
 import { pickCouncilTaskModel } from "./leader.js";
-import { tracedAsync, tracedGenerate } from "./llm.js";
+import { councilStreamLivenessReader, tracedAsync, tracedGenerate } from "./llm.js";
 import { phaseDone, phaseStart } from "./phase-events.js";
 import { buildFollowupPrompt, buildLeaderEvaluationPrompt, buildOpeningPrompt, buildResponsePrompt, buildRoundSummaryPrompt, } from "./prompts.js";
 /**
@@ -301,13 +302,13 @@ async function runResearchIsolated(runIsolatedTask, model, topic, conversationCo
         `Return a compact "## Research Findings" section: only the concrete facts that bear on the question, each with its source (file:line or URL). ` +
         `Be terse and factual — no opinions, no recommendations. If you cannot find solid evidence, say so in one line.`;
     try {
-        const result = await runIsolatedTask({
+        const result = await withDeadlineRace(() => runIsolatedTask({
             agent: "explore",
             description: `Council research: ${topic.slice(0, 60)}`,
             prompt,
             // Pin the research-role model; bypasses the parent-tier cap in StreamRunner.
             modelId: model,
-        });
+        }), getIsolatedTaskDeadlineMs(), "council-research");
         if (result.success && result.output?.trim())
             return result.output.trim();
         traceCb(`[research] isolated sub-agent produced nothing: ${result.error ?? "no output"}`);
@@ -352,7 +353,22 @@ export async function researchWithFallback(llm, primaryModel, topic, conversatio
         return primary;
     }
 }
+/**
+ * Times every `debateWithRetryInner` exit path — success, retry, fallback and
+ * total failure all cost wall-clock, and a slow FAILING speaker is exactly the
+ * case worth seeing. Wrapping is why `durationMs` cannot drift out of sync with
+ * the four separate returns inside.
+ *
+ * The number is per-SPEAKER. The only timed council rows today are
+ * `debate_complete` (whole debate: 87s..1128s measured) and `council_summary`
+ * — aggregates that cannot name the model responsible.
+ */
 async function debateWithRetry(llm, model, system, prompt, signal, traceCb, toolBudget, fallbackPool = []) {
+    const startedAt = Date.now();
+    const r = await debateWithRetryInner(llm, model, system, prompt, signal, traceCb, toolBudget, fallbackPool);
+    return { ...r, durationMs: Date.now() - startedAt };
+}
+async function debateWithRetryInner(llm, model, system, prompt, signal, traceCb, toolBudget, fallbackPool = []) {
     // Respect the circuit breaker — once a model has tripped, it stays
     // tool-disabled for the rest of this council run.
     const allowTools = debateAllowsTools(model) && !toolBudget.disabled.has(model);
@@ -514,11 +530,16 @@ export async function* runDebate(spec, config, llm) {
             detail: `via ${researchCandidate.model}`,
         });
         const researchTraces = [];
+        const researchStartedAt = Date.now();
         researchFindings = yield* tracedAsync(() => researchWithFallback(llm, researchCandidate.model, spec.problemStatement, conversationContext, signal, (t) => researchTraces.push(t), { internetFirst }, fallbackPool, config.runIsolatedTask), {
             phase: "research",
             label: internetFirst ? "Researching (internet-first)" : "Researching codebase",
             detail: spec.problemStatement.slice(0, 80),
             role: "research",
+            // Research is a single long generateText (up to ~10 min / 15 tool steps)
+            // with a quiet main stream — the phase most easily misread as hung, and
+            // the one whose cost the per-round numbers could not account for.
+            liveness: councilStreamLivenessReader(),
         });
         // CQ-22: emit research tool traces as council_status
         for (const trace of researchTraces) {
@@ -545,6 +566,10 @@ export async function* runDebate(spec, config, llm) {
                 text: researchFailed
                     ? "⚠ Research unavailable — both providers failed. The council proceeds on the panel's own knowledge (no external findings injected)."
                     : (researchFindings ?? ""),
+                // Spans researchWithFallback including any fallback provider attempt.
+                // Measured per-speaker debate turns summed to only ~3.7 min against a
+                // ~507s historical `debate_complete`, so the balance is here.
+                durationMs: Date.now() - researchStartedAt,
             },
         };
     }
@@ -595,6 +620,7 @@ export async function* runDebate(spec, config, llm) {
                 conversationContext: selfContext,
                 language: debateLanguage,
             });
+            const startedAt = Date.now();
             return openingWithRetry(llm, self.model, system, prompt).then((r) => ({
                 role: self.role,
                 model: self.model,
@@ -602,6 +628,7 @@ export async function* runDebate(spec, config, llm) {
                 position: r.text,
                 error: r.text ? null : (r.error ?? "empty completion after retries"),
                 attempts: r.attempts,
+                durationMs: Date.now() - startedAt,
             }));
         });
         const openings = yield* tracedAsync(() => Promise.all(openingPromises), {
@@ -611,6 +638,9 @@ export async function* runDebate(spec, config, llm) {
             // each speaker is tasked to argue (A: live debate preview) instead of a bare
             // spinner during the atomic generateText window.
             detail: formatSpeakerRoster(participants),
+            // Promise.all does not pump this generator, so `elapsedMs` freezes while
+            // the openings run. Push-based stream counters keep the heartbeat honest.
+            liveness: councilStreamLivenessReader(),
         });
         yield { type: "content", content: "\n── Opening Analysis ──\n" };
         for (const o of openings) {
@@ -625,6 +655,7 @@ export async function* runDebate(spec, config, llm) {
                         text: `[Error: ${o.error}]`,
                         attempts: o.attempts,
                         failureReason: o.error,
+                        durationMs: o.durationMs,
                     },
                 };
             }
@@ -645,6 +676,7 @@ export async function* runDebate(spec, config, llm) {
                         round: 0,
                         text: o.position,
                         attempts: o.attempts,
+                        durationMs: o.durationMs,
                     },
                 };
                 emitCouncilTurnLength({
@@ -757,6 +789,14 @@ export async function* runDebate(spec, config, llm) {
     // not yet escalated, criteria unmet).
     async function* escalateStop(stuck, pinnedUnmet, openList) {
         escalated = true;
+        // convene_council path: no interactive user is answering mid-tool-call, so a
+        // blocking escalation card would hang the council. Auto-accept (= conclude
+        // with the best synthesis so far) without emitting the card. Mirrors the
+        // "empty/failed answer → accept" fallback runEscalationPrompt already uses.
+        if (config.convenePath) {
+            escalation = { action: "accept" };
+            return "stop";
+        }
         const dec = yield* runEscalationPrompt({
             respondToQuestion: config.respondToQuestion,
             openCriteria: openList,
@@ -902,6 +942,7 @@ export async function* runDebate(spec, config, llm) {
                         traces: aTraces,
                         failureReason: aResult.failureReason,
                         attempts: aResult.attempts,
+                        durationMs: aResult.durationMs,
                     });
                     const bPrompt = buildResponsePrompt({
                         speakerRole: b.role,
@@ -925,6 +966,7 @@ export async function* runDebate(spec, config, llm) {
                         traces: bTraces,
                         failureReason: bResult.failureReason,
                         attempts: bResult.attempts,
+                        durationMs: bResult.durationMs,
                     });
                 }
                 else {
@@ -956,6 +998,7 @@ export async function* runDebate(spec, config, llm) {
                         traces: aTraces,
                         failureReason: aResult.failureReason,
                         attempts: aResult.attempts,
+                        durationMs: aResult.durationMs,
                     });
                     const bPrompt = buildFollowupPrompt({
                         speakerRole: b.role,
@@ -981,6 +1024,7 @@ export async function* runDebate(spec, config, llm) {
                         traces: bTraces,
                         failureReason: bResult.failureReason,
                         attempts: bResult.attempts,
+                        durationMs: bResult.durationMs,
                     });
                 }
                 // Only update positions when response is non-empty (avoid clearing on LLM error)
@@ -999,6 +1043,11 @@ export async function* runDebate(spec, config, llm) {
             // Distinct speakers with their lens (A: live debate preview) — dedup by
             // formatted line so a speaker appearing in two pairs shows once.
             detail: formatSpeakerRoster(pairs.flatMap((p) => [p.a, p.b])),
+            // THE case this exists for: each pair turn can run to the 5-min council
+            // ceiling on a reasoning model, and Promise.all never pumps this
+            // generator — `elapsedMs` freezes and a healthy 15-min round looks hung.
+            // These counters come off the token stream, so they keep advancing.
+            liveness: councilStreamLivenessReader(),
         });
         yield { type: "content", content: `\n── Round ${round} ──\n` };
         // Track failures so the circuit breaker can fire after this round.
@@ -1063,6 +1112,7 @@ export async function* runDebate(spec, config, llm) {
                             text: chunk.text.trim(),
                             toolCalls: chunk.toolCalls?.map((t) => ({ name: t.toolName })),
                             attempts: chunk.attempts,
+                            durationMs: chunk.durationMs,
                         },
                     };
                     emitCouncilTurnLength({
@@ -1236,6 +1286,10 @@ export async function* runDebate(spec, config, llm) {
                     speaker: { role: "Leader", model: leaderModelId },
                     round,
                     text: verdictText,
+                    // Spans every evaluateDebate attempt including fallback models, so a
+                    // leader that ate the round is attributable rather than hidden inside
+                    // the `debate_complete` aggregate.
+                    durationMs: Date.now() - evalStart,
                 },
             };
             // P5 — guaranteed done record for this round. Decision reflects the
@@ -1912,12 +1966,12 @@ export async function runGroundingVerify(runIsolatedTask, model, problemStatemen
         `words followed by its tag. Do NOT restate the whole debate or add opinions. Prefer [CONFIRMED]/[REFUTED] ` +
         `with a real citation over [UNVERIFIED].`;
     try {
-        const result = await runIsolatedTask({
+        const result = await withDeadlineRace(() => runIsolatedTask({
             agent: "explore",
             description: `Council grounding-verify: ${problemStatement.slice(0, 50)}`,
             prompt,
             modelId: model,
-        });
+        }), getIsolatedTaskDeadlineMs(), "council-grounding-verify");
         if (result.success && result.output?.trim())
             return result.output.trim();
         traceCb(`[grounding-verify] produced nothing: ${result.error ?? "no output"}`);

package/dist/src/council/index.d.ts

@@ -88,6 +88,19 @@ export interface RunCouncilOptions {
      *     decisions.lock artifact actually get written for sprint-runner injection.
      */
     sprintPlanningMode?: boolean;
+    /**
+     * Convene-tool path (the `convene_council` builtin). When true, render
+     * clarify(optional)+debate+synthesis exactly as normal, then RETURN the
+     * synthesis string WITHOUT any post-debate decision surface: NO
+     * `pickPostDebateRecommendation`, NO option set, NO `council_question`
+     * post-debate card, NO `onPostDebateAction`, NO `postDebateContinuation`
+     * routing. The calling AGENT decides what happens next (continue silently,
+     * ask the user via `ask_user`, or hand off to `/ideal`) — the CLI hardcodes
+     * none of it (user directive: no CLI-hardcoded post-council branch). The
+     * persistence block (decisions.lock, judge, council record) still runs — it
+     * is an audit trail, not a decision.
+     */
+    convenePath?: boolean;
     /**
      * #2 — isolated sub-agent bridge (orchestrator.runTaskRequest). When wired,
      * the debate's research phase runs in a budget-capped explore sub-agent
@@ -144,6 +157,16 @@ export declare function pickPostDebateRecommendation(input: {
     reason: string;
 };
 export declare function postDebateContinuation(action: string | undefined, synthesis: string, outputKind?: string): string | null;
+/**
+ * Neutral post-council continuation. Used by the auto-council path (tool-engine)
+ * and the `/council` slash path (runCouncilV2) once they run with
+ * `convenePath: true` — the hardcoded post-debate option card is suppressed, so
+ * there is no `chosenAction` to branch on. Instead of the CLI deciding the next
+ * step, we hand the synthesis back to a normal agent turn with a NON-BINDING
+ * nudge and let the agent's own intent drive the follow-up (respond / ask_user /
+ * implement). Returns "" for an empty synthesis so the caller skips re-entry.
+ */
+export declare function buildNeutralPostCouncilContinuation(synthesis: string): string;
 export declare function runCouncil(topic: string, sessionModelId: string, messages: Array<{
     role: string;
     content: string | unknown;

package/dist/src/council/index.js

@@ -179,6 +179,28 @@ export function postDebateContinuation(action, synthesis, outputKind) {
     }
     return null;
 }
+/**
+ * Neutral post-council continuation. Used by the auto-council path (tool-engine)
+ * and the `/council` slash path (runCouncilV2) once they run with
+ * `convenePath: true` — the hardcoded post-debate option card is suppressed, so
+ * there is no `chosenAction` to branch on. Instead of the CLI deciding the next
+ * step, we hand the synthesis back to a normal agent turn with a NON-BINDING
+ * nudge and let the agent's own intent drive the follow-up (respond / ask_user /
+ * implement). Returns "" for an empty synthesis so the caller skips re-entry.
+ */
+export function buildNeutralPostCouncilContinuation(synthesis) {
+    if (!synthesis || !synthesis.trim())
+        return "";
+    return (`Council debate completed. Conclusion:\n\n${synthesis}\n\n` +
+        `You now decide the next step based on the user's original request — do not ` +
+        `stop without doing one of these:\n` +
+        `  • If the conclusion IS the deliverable (analysis/evaluation/decision), ` +
+        `respond to the user with it.\n` +
+        `  • If a choice genuinely needs the human before proceeding, call ask_user.\n` +
+        `  • If the task calls for building and the conclusion is a sufficient spec, ` +
+        `implement it now through your normal workflow — do NOT re-litigate the ` +
+        `decision or expand scope beyond it.`);
+}
 export async function* runCouncil(topic, sessionModelId, messages, sessionId, rawLlm, respondToQuestion, respondToPreflight, processMessageFn, options) {
     const stats = options?.councilStats ?? { calls: 0, startMs: Date.now(), phases: [] };
     const costAware = isCouncilCostAware();
@@ -349,7 +371,11 @@ export async function* runCouncil(topic, sessionModelId, messages, sessionId, ra
         const preflightGen = runPreflight(spec, participants, researchNeeded, respondToPreflight, {
             repoEmpty: internetFirst,
             researchOverridable: true,
-            autoApprove: spec.ready === true || options?.autoApprovePreflight === true,
+            // convenePath auto-approves the pre-debate plan card too: the agent
+            // already decided to convene, so re-gating the discussion plan is a
+            // redundant interruption of the autonomous tool call (same rationale as
+            // sprintPlanningMode). The brief is still shown; it just isn't blocking.
+            autoApprove: spec.ready === true || options?.autoApprovePreflight === true || options?.convenePath === true,
         });
         let preflightResult;
         do {
@@ -503,6 +529,9 @@ export async function* runCouncil(topic, sessionModelId, messages, sessionId, ra
         // unmet, runDebate asks the user (extend / accept / rescope) instead of
         // silently synthesizing a partial outcome.
         respondToQuestion,
+        // convene_council path — auto-accept escalation (no blocking card) since
+        // the council runs autonomously mid-agent-turn with no interactive user.
+        convenePath: options?.convenePath,
     }, llm);
     let debateResult;
     do {
@@ -568,7 +597,13 @@ export async function* runCouncil(topic, sessionModelId, messages, sessionId, ra
         data: { topic, roundCount: debateState.roundCount, participantCount: debateState.active.length },
     });
     // ── Post-Debate AskCard: What next? ─────────────────────────────────────────
-    if (sessionId) {
+    // convenePath skips this ENTIRE interactive block (recommendation, option set,
+    // card, respondToQuestion, postDebateAction, onPostDebateAction, and the whole
+    // routing tree). On that path the agent that called `convene_council` decides
+    // what happens next — the CLI must not hardcode a post-council pick. The
+    // persistence block below still runs (audit trail, not a decision), and the
+    // function returns synthesisText as usual.
+    if (sessionId && !options?.convenePath) {
         try {
             const { randomUUID } = await import("crypto");
             const refinementTopics = [];