muonroi-cli 1.8.5 → 1.9.0

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

@@ -1,3 +1,5 @@
+import type { LanguageModel, ToolSet } from "ai";
+import { stepCountIs } from "ai";
 import type { BashTool } from "../tools/bash.js";
 import type { AgentMode, CouncilStatusPhase, StreamChunk } from "../types/index.js";
 import type { CouncilLLM, CouncilStats } from "./types.js";
@@ -25,6 +27,56 @@ export declare function recordCouncilUsage(sessionId: string | undefined, modelI
 declare global {
     var __muonroiMockLlm: any;
 }
+/** Record `chars` of streamed output (text OR reasoning) against the live window. */
+export declare function noteCouncilStreamDelta(chars: number): void;
+/**
+ * Open a liveness window and return a reader for it.
+ *
+ * `streamedChars` counts only what streamed SINCE the window opened, and
+ * `lastDeltaAgeMs` is measured from the window's own start until the first
+ * delta lands — so a cold stall reads as an age growing from 0, never as a
+ * bogus epoch-sized number. Reasoning-delta counts toward both: a reasoning
+ * model emits reasoning tokens for minutes before any text, and that is
+ * exactly the window an operator must not mistake for a hang.
+ */
+export declare function councilStreamLivenessReader(): () => {
+    streamedChars: number;
+    lastDeltaAgeMs: number;
+};
+declare function collectStreamText(args: {
+    model: LanguageModel;
+    system: string;
+    prompt: string;
+    maxOutputTokens?: number;
+    temperature?: number;
+    providerOptions?: Record<string, unknown>;
+    abortSignal?: AbortSignal;
+    tools?: ToolSet;
+    stopWhen?: ReturnType<typeof stepCountIs>;
+    prepareStep?: (opts: {
+        stepNumber: number;
+        messages: readonly unknown[];
+    }) => unknown;
+    /** Called with the char length of every text/reasoning delta as it arrives. */
+    onDelta?: (chars: number) => void;
+}): Promise<{
+    text: string;
+    usage?: unknown;
+    finishReason?: string;
+    reasoningText?: string;
+    toolCalls: Array<{
+        toolName: string;
+        input?: unknown;
+        result?: unknown;
+    }>;
+}>;
+/**
+ * Test-only handle on the private stream collector, so `onDelta` (the liveness
+ * signal that tells a slow reasoning call from a hung one) is directly
+ * assertable without standing up a full council run. Not for production use.
+ * @internal
+ */
+export declare const __testCollectStreamText: typeof collectStreamText;
 export declare function createCouncilLLM(bash: BashTool, mode: AgentMode, sessionId: string | undefined, stats: CouncilStats): CouncilLLM;
 interface TracedGenerateArgs {
     phase: CouncilStatusPhase;
@@ -62,6 +114,16 @@ interface TracedAsyncArgs {
     detail?: string;
     role?: string;
     tickIntervalMs?: number;
+    /**
+     * Optional push-based stream liveness reader (see {@link councilStreamLivenessReader}).
+     * When supplied, every tick/done carries the chars streamed inside this window
+     * and the age of the last delta — so a frozen `elapsedMs` (generator not being
+     * pumped) can still be told apart from a genuinely stuck call.
+     */
+    liveness?: () => {
+        streamedChars: number;
+        lastDeltaAgeMs: number;
+    };
 }
 /**
  * Generic version of {@link tracedGenerate} for arbitrary async work

package/dist/src/council/llm.js

@@ -7,7 +7,8 @@ import { buildMcpToolSet } from "../mcp/runtime.js";
 import { getModelInfo } from "../models/registry.js";
 import { getProviderCapabilities, resolveTemperature } from "../providers/capabilities.js";
 import { loadKeyForProvider, ProviderKeyMissingError } from "../providers/keychain.js";
-import { createProviderFactoryAsync, detectProviderForModel, resolveModelRuntime } from "../providers/runtime.js";
+import { createProviderFactoryAsync, detectProviderForModel, resolveModelRuntime, shouldDropParam, } from "../providers/runtime.js";
+import { wireDebug } from "../providers/wire-debug.js";
 import { statusBarStore } from "../state/status-bar-store.js";
 import { recordUsageEvent } from "../storage/index.js";
 import { createBuiltinTools as createTools } from "../tools/registry.js";
@@ -20,7 +21,11 @@ import { withVisibleRetry } from "../utils/visible-retry.js";
 import { buildResearchSystemPrompt } from "./prompts.js";
 import { stripThinkBlocks } from "./strip-think.js";
 /**
- * Resolve a provider factory for a council sub-call, OAuth-aware.
+ * Register a provider factory for a council sub-call, OAuth-aware.
+ *
+ * A council roster routes stances to providers the session itself never built,
+ * so their factory must exist in the registry before `resolveModelRuntime` can
+ * derive it from the model id.
  *
  * The council reachability gate (`isProviderReachable` in leader.ts) counts
  * OAuth-authenticated providers as usable (via `getConfiguredProviders`), so a
@@ -33,7 +38,7 @@ import { stripThinkBlocks } from "./strip-think.js";
  * refreshes the stored OAuth bearer token. Only the expected missing-key case
  * is swallowed; unexpected errors propagate.
  */
-async function resolveCouncilFactory(providerId) {
+async function ensureCouncilFactory(providerId) {
     let apiKey;
     try {
         apiKey = await loadKeyForProvider(providerId);
@@ -43,8 +48,7 @@ async function resolveCouncilFactory(providerId) {
             throw err;
         // OAuth-only provider — createProviderFactoryAsync injects the bearer token.
     }
-    const { factory } = await createProviderFactoryAsync(providerId, apiKey ? { apiKey } : {});
-    return factory;
+    await createProviderFactoryAsync(providerId, apiKey ? { apiKey } : {});
 }
 function getDebugLogPath() {
     const p = process.env.MUONROI_COUNCIL_DEBUG_LOG;
@@ -297,13 +301,64 @@ const COUNCIL_LLM_TIMEOUT_MS = (() => {
  * `generateText` result exposed. A debater on the codex/oauth endpoint hit the
  * exact same non-stream 400 as the eval path — streaming fixes it uniformly.
  */
+/**
+ * Spread for the `maxOutputTokens` param, omitted when the resolved runtime
+ * rejects it. The ChatGPT Codex OAuth endpoint (chatgpt.com/backend-api/codex/
+ * responses) 400s with `{"detail":"Unsupported parameter: max_output_tokens"}`
+ * on EVERY council sub-call (clarify / debate / research) — every council
+ * generate on a Codex-OAuth session was failing wholesale. Mirrors the
+ * orchestrator + classify paths, which already gate this param via
+ * `shouldDropParam`.
+ */
+function maxOutSpread(runtime, n) {
+    return shouldDropParam(runtime, "maxOutputTokens") ? {} : { maxOutputTokens: n };
+}
+/**
+ * Push-based stream liveness — module-level because the only readers
+ * (`tracedAsync` wrappers in debate.ts) sit OUTSIDE the `CouncilLLM` interface
+ * and cannot reach the in-flight `collectStreamText` any other way.
+ *
+ * Why it exists. `tracedAsync`'s 1s tick only materializes when the CONSUMER
+ * pulls `.next()`; a round that awaits its pairs via `Promise.all` stops
+ * pumping the tick generator, so `elapsedMs` FREEZES and a slow-but-alive run
+ * is indistinguishable from a hung one (observed: tick frozen at 33142ms for
+ * 8+ minutes while status was still "tick"). Token deltas are PUSHED here as
+ * they arrive, so liveness survives any back-pressure on the generator.
+ */
+let councilStreamedCharsTotal = 0;
+let councilLastDeltaAt = 0;
+/** Record `chars` of streamed output (text OR reasoning) against the live window. */
+export function noteCouncilStreamDelta(chars) {
+    if (chars <= 0)
+        return;
+    councilStreamedCharsTotal += chars;
+    councilLastDeltaAt = Date.now();
+}
+/**
+ * Open a liveness window and return a reader for it.
+ *
+ * `streamedChars` counts only what streamed SINCE the window opened, and
+ * `lastDeltaAgeMs` is measured from the window's own start until the first
+ * delta lands — so a cold stall reads as an age growing from 0, never as a
+ * bogus epoch-sized number. Reasoning-delta counts toward both: a reasoning
+ * model emits reasoning tokens for minutes before any text, and that is
+ * exactly the window an operator must not mistake for a hang.
+ */
+export function councilStreamLivenessReader() {
+    const baseChars = councilStreamedCharsTotal;
+    const windowStart = Date.now();
+    return () => ({
+        streamedChars: councilStreamedCharsTotal - baseChars,
+        lastDeltaAgeMs: Date.now() - (councilLastDeltaAt > windowStart ? councilLastDeltaAt : windowStart),
+    });
+}
 async function collectStreamText(args) {
     const hasTools = !!args.tools && Object.keys(args.tools).length > 0;
     const result = streamText({
         model: args.model,
         system: args.system,
         prompt: args.prompt,
-        maxOutputTokens: args.maxOutputTokens,
+        ...(args.maxOutputTokens === undefined ? {} : { maxOutputTokens: args.maxOutputTokens }),
         maxRetries: 0,
         ...(args.temperature === undefined ? {} : { temperature: args.temperature }),
         ...(args.providerOptions ? { providerOptions: args.providerOptions } : {}),
@@ -318,12 +373,21 @@ async function collectStreamText(args) {
     const byId = new Map();
     for await (const part of result.fullStream) {
         switch (part.type) {
-            case "text-delta":
-                text += part.text ?? "";
+            case "text-delta": {
+                const d = part.text ?? "";
+                text += d;
+                args.onDelta?.(d.length);
                 break;
-            case "reasoning-delta":
-                reasoningText += part.text ?? "";
+            }
+            case "reasoning-delta": {
+                // Reasoning deltas count as liveness: a reasoning model streams these
+                // for minutes before its first text-delta, and that silent-on-text
+                // window is precisely what gets misread as a hang.
+                const d = part.text ?? "";
+                reasoningText += d;
+                args.onDelta?.(d.length);
                 break;
+            }
             case "tool-call": {
                 const p = part;
                 const tc = { toolName: p.toolName, input: p.input };
@@ -352,6 +416,13 @@ async function collectStreamText(args) {
     }
     return { text, usage, finishReason, reasoningText: reasoningText || undefined, toolCalls };
 }
+/**
+ * Test-only handle on the private stream collector, so `onDelta` (the liveness
+ * signal that tells a slow reasoning call from a hung one) is directly
+ * assertable without standing up a full council run. Not for production use.
+ * @internal
+ */
+export const __testCollectStreamText = collectStreamText;
 export function createCouncilLLM(bash, mode, sessionId, stats) {
     return {
         async generate(modelId, system, prompt, maxTokens = 4096, onUsage, signal) {
@@ -362,8 +433,8 @@ export function createCouncilLLM(bash, mode, sessionId, stats) {
                 return stripThinkBlocks(result.text);
             }
             const providerId = detectProviderForModel(modelId);
-            const factory = await resolveCouncilFactory(providerId);
-            const runtime = resolveModelRuntime(factory, modelId);
+            await ensureCouncilFactory(providerId);
+            const runtime = resolveModelRuntime(modelId);
             const t0 = Date.now();
             // Combine the user-abort signal (when threaded from runCouncil) with the
             // per-call wall-clock deadline. Without the parent signal, an Esc/Ctrl-C
@@ -381,7 +452,7 @@ export function createCouncilLLM(bash, mode, sessionId, stats) {
                     model: runtime.model,
                     system,
                     prompt,
-                    maxOutputTokens: maxTokens,
+                    ...maxOutSpread(runtime, maxTokens),
                     // Never hardcode temperature: some upstreams (Moonshot/Kimi via
                     // opencode-go) reject any value but their pinned one, which
                     // failed every clarify/spec call on a Kimi session. resolveTemperature
@@ -389,6 +460,7 @@ export function createCouncilLLM(bash, mode, sessionId, stats) {
                     temperature: resolveTemperature(providerId, runtime.modelInfo, 0.7),
                     providerOptions: runtime.providerOptions,
                     abortSignal: timedSignal,
+                    onDelta: noteCouncilStreamDelta,
                 }), { label: "council.generate" }), COUNCIL_LLM_TIMEOUT_MS + 5_000, "council.generate", signal);
                 cleanupTimeout();
                 stats.calls++;
@@ -426,6 +498,12 @@ export function createCouncilLLM(bash, mode, sessionId, stats) {
             }
             catch (err) {
                 cleanupTimeout();
+                // Capture the provider-side detail (status code + response body +
+                // request param shape) that `err.message` alone drops — a generic
+                // "Bad Request" on the council path was previously undiagnosable
+                // because collectStreamText re-throws only the message. PII-safe,
+                // no-op unless MUONROI_DEBUG_LLM_WIRE=1. (No-Silent-Catch.)
+                wireDebug.logError(providerId, err);
                 writeDebugRecord({
                     ts: new Date().toISOString(),
                     kind: "generate",
@@ -452,8 +530,8 @@ export function createCouncilLLM(bash, mode, sessionId, stats) {
                 return { text: stripThinkBlocks(result.text), toolCalls: [] };
             }
             const providerId = detectProviderForModel(modelId);
-            const factory = await resolveCouncilFactory(providerId);
-            const runtime = resolveModelRuntime(factory, modelId);
+            await ensureCouncilFactory(providerId);
+            const runtime = resolveModelRuntime(modelId);
             // Verification tools — re-introduced after the no-tools fix (session
             // a7a5690d2049). The original failure was stepCountIs(4) + full toolset
             // letting reasoning models exhaust steps on exploratory tool chains and
@@ -484,13 +562,16 @@ export function createCouncilLLM(bash, mode, sessionId, stats) {
                             }
                         }
                     }
-                    catch {
-                        /* MCP optional — debate continues with builtins only */
+                    catch (err) {
+                        // MCP is optional here — debate continues with builtins only — but a
+                        // silent swallow hid which server failed and why. (No-Silent-Catch.)
+                        console.error(`[council/llm] debate MCP tool discovery failed, continuing with builtins only: ${err instanceof Error ? err.message : String(err)}`, { modelId, provider: providerId });
                     }
                     verificationTools = wrapToolsWithEeCheck(filtered, sessionId ?? "council-debate");
                 }
-                catch {
-                    /* fail-open: no tools */
+                catch (err) {
+                    // fail-open: the debate turn still runs, just without verification tools.
+                    console.error(`[council/llm] debate verification toolset build failed, running without tools: ${err instanceof Error ? err.message : String(err)}`, { modelId, provider: providerId });
                 }
             }
             // sanitizeHistory is identity for every provider (kept as a hook for
@@ -515,11 +596,15 @@ export function createCouncilLLM(bash, mode, sessionId, stats) {
                     // text. E2E showed 2048 caused finishReason=length on 3KB debate
                     // prompts. 6144 leaves ~4000 tokens for text after typical reasoning
                     // overhead and avoids cuts mid-thought.
-                    maxOutputTokens: 6144,
+                    ...maxOutSpread(runtime, 6144),
                     // See generate(): capability-aware temperature (omit / clamp).
                     temperature: resolveTemperature(providerId, runtime.modelInfo, 0.7),
                     providerOptions: runtime.providerOptions,
                     abortSignal: timedSignal,
+                    // Push liveness for the round wrapper: a debate turn on a
+                    // reasoning model runs near the 5-min ceiling, and the tick
+                    // generator is not being pumped while Promise.all awaits.
+                    onDelta: noteCouncilStreamDelta,
                     ...(verificationTools && Object.keys(verificationTools).length > 0
                         ? {
                             tools: verificationTools,
@@ -611,8 +696,8 @@ export function createCouncilLLM(bash, mode, sessionId, stats) {
                 return stripThinkBlocks(result.text);
             }
             const providerId = detectProviderForModel(modelId);
-            const factory = await resolveCouncilFactory(providerId);
-            const runtime = resolveModelRuntime(factory, modelId);
+            await ensureCouncilFactory(providerId);
+            const runtime = resolveModelRuntime(modelId);
             const builtinTools = createTools(bash, mode);
             // CQ-03: Lazy MCP bundle per research call — fail-open so builtins remain available
             let mcpBundle = null;
@@ -668,7 +753,7 @@ export function createCouncilLLM(bash, mode, sessionId, stats) {
                         const stripped = researchCaps.sanitizeHistory(messages);
                         return stripped === messages ? {} : { messages: stripped };
                     },
-                    maxOutputTokens: 4096,
+                    ...maxOutSpread(runtime, 4096),
                     // See generate(): capability-aware temperature (omit / clamp).
                     ...(() => {
                         const t = resolveTemperature(providerId, runtime.modelInfo, 0.3);
@@ -894,6 +979,19 @@ export async function* tracedAsync(fn, args) {
         : `status-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
     const start = Date.now();
     const tickInterval = args.tickIntervalMs ?? 1000;
+    /** Never let a liveness read break the heartbeat it is meant to enrich. */
+    const livenessFields = () => {
+        if (!args.liveness)
+            return {};
+        try {
+            const l = args.liveness();
+            return { streamedChars: l.streamedChars, lastDeltaAgeMs: l.lastDeltaAgeMs };
+        }
+        catch (err) {
+            console.error(`[council/llm] tracedAsync liveness read failed: ${err instanceof Error ? err.message : String(err)}`, { phase: args.phase, label: args.label });
+            return {};
+        }
+    };
     yield {
         type: "council_status",
         councilStatus: {
@@ -939,6 +1037,7 @@ export async function* tracedAsync(fn, args) {
                 detail: args.detail,
                 role: args.role,
                 elapsedMs: Date.now() - start,
+                ...livenessFields(),
             },
         };
     }
@@ -970,6 +1069,7 @@ export async function* tracedAsync(fn, args) {
             detail: args.detail,
             role: args.role,
             elapsedMs: Date.now() - start,
+            ...livenessFields(),
         },
     };
     return result;

package/dist/src/council/panel-select.js

@@ -42,17 +42,27 @@ export async function* selectTaskAwarePanel(opts) {
             maxTokens: 512,
         });
     }
-    catch {
+    catch (err) {
+        // Fail-open: caller keeps its default roster. Log so a provider outage on
+        // the leader model is diagnosable instead of silently degrading panel
+        // selection to the prompt-blind roster. (No-Silent-Catch.)
+        console.error(`[council/panel-select] leader panel selection call failed, keeping default roster: ${err instanceof Error ? err.message : String(err)}`, { leaderModelId, poolSize: pool.length });
         return null;
     }
     const match = raw.match(/\{[\s\S]*\}/);
-    if (!match)
+    if (!match) {
+        console.error("[council/panel-select] leader returned no JSON object, keeping default roster", {
+            leaderModelId,
+            rawHead: raw.slice(0, 200),
+        });
         return null;
+    }
     let parsed;
     try {
         parsed = JSON.parse(match[0]);
     }
-    catch {
+    catch (err) {
+        console.error(`[council/panel-select] leader selection JSON parse failed, keeping default roster: ${err instanceof Error ? err.message : String(err)}`, { leaderModelId, rawHead: match[0].slice(0, 200) });
         return null;
     }
     const valid = new Set(pool.map((c) => c.model));

package/dist/src/council/planner.js

@@ -1,6 +1,7 @@
 import { getCouncilLanguage } from "../utils/settings.js";
 import { tracedGenerate } from "./llm.js";
 import { phaseDone, phaseError, phaseStart } from "./phase-events.js";
+import { emitPreflightHarnessEvent } from "./preflight.js";
 import { buildSynthesisPrompt } from "./prompts.js";
 export async function* runPlanning(debateState, spec, participants, leaderModelId, respondToPreflight, llm, debatePlan, 
 // CQ-18: PIL outputStyle from runCouncil
@@ -145,6 +146,15 @@ planEmphasis) {
             yield { type: "content", content: `- [${step.priority}] ${step.description}\n` };
         }
         const preflightId = crypto.randomUUID();
+        emitPreflightHarnessEvent({
+            t: "event",
+            kind: "askcard-open",
+            questionId: preflightId,
+            question: `Approve action plan for: ${spec.problemStatement}`,
+            phase: "plan-confirm",
+            optionCount: 2,
+            defaultIndex: 0,
+        });
         yield {
             type: "council_preflight",
             content: "Review the action plan above. Approve to proceed with execution, or reject.",
@@ -159,6 +169,13 @@ planEmphasis) {
             },
         };
         const approved = await respondToPreflight(preflightId);
+        emitPreflightHarnessEvent({
+            t: "event",
+            kind: "askcard-answered",
+            questionId: preflightId,
+            answerKind: "choice",
+            answerText: approved ? "approve" : "reject",
+        });
         yield phaseDone({
             phaseId: "phase:action-plan",
             kind: "action_plan",

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

@@ -1,5 +1,15 @@
 import type { StreamChunk } from "../types/index.js";
 import type { ClarifiedSpec, PreflightResponder } from "./types.js";
+/**
+ * Emit a harness LiveEvent for a preflight/plan-confirm approval gate.
+ *
+ * These gates are surfaced as `council_preflight` StreamChunks (a UI render path),
+ * NOT as LiveEvents — so a monitor on MUONROI_HARNESS_EVENT_LOG is structurally
+ * blind to them, unlike the clarify gate which flows through askcard-open. Emitting
+ * askcard-open/answered here lets a wake-at-milestone monitor react to the
+ * human-approval pause. Observe-only: never throws, no-op when no agent runtime.
+ */
+export declare function emitPreflightHarnessEvent(event: Record<string, unknown>): void;
 export interface RunPreflightOptions {
     repoEmpty?: boolean;
     researchOverridable?: boolean;

package/dist/src/council/preflight.js

@@ -1,4 +1,24 @@
 import { phaseDone, phaseStart } from "./phase-events.js";
+/**
+ * Emit a harness LiveEvent for a preflight/plan-confirm approval gate.
+ *
+ * These gates are surfaced as `council_preflight` StreamChunks (a UI render path),
+ * NOT as LiveEvents — so a monitor on MUONROI_HARNESS_EVENT_LOG is structurally
+ * blind to them, unlike the clarify gate which flows through askcard-open. Emitting
+ * askcard-open/answered here lets a wake-at-milestone monitor react to the
+ * human-approval pause. Observe-only: never throws, no-op when no agent runtime.
+ */
+export function emitPreflightHarnessEvent(event) {
+    try {
+        const ar = globalThis.__muonroiAgentRuntime;
+        if (!ar || typeof ar.emitEvent !== "function")
+            return;
+        ar.emitEvent(event);
+    }
+    catch {
+        /* observe-only */
+    }
+}
 export async function* runPreflight(spec, participants, researchNeeded, respondToPreflight, options) {
     const preflightId = crypto.randomUUID();
     const startedAt = Date.now();
@@ -50,6 +70,15 @@ export async function* runPreflight(spec, participants, researchNeeded, respondT
         });
         return true;
     }
+    emitPreflightHarnessEvent({
+        t: "event",
+        kind: "askcard-open",
+        questionId: preflightId,
+        question: `Approve discussion plan for: ${spec.problemStatement}`,
+        phase: "preflight",
+        optionCount: 2,
+        defaultIndex: 0,
+    });
     yield {
         type: "council_preflight",
         content: "Review the discussion brief above. Approve to start debate, or reject to revise.",
@@ -66,6 +95,13 @@ export async function* runPreflight(spec, participants, researchNeeded, respondT
         },
     };
     const approved = await respondToPreflight(preflightId);
+    emitPreflightHarnessEvent({
+        t: "event",
+        kind: "askcard-answered",
+        questionId: preflightId,
+        answerKind: "choice",
+        answerText: approved ? "approve" : "reject",
+    });
     yield phaseDone({
         phaseId: "phase:preflight",
         kind: "preflight",

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

@@ -2,7 +2,15 @@ import type { ClarifiedSpec, DebatePlan, DebateStance, OutputShape } from "./typ
 export declare function buildClarificationPrompt(topic: string, conversationContext: string, previousQA?: Array<{
     question: string;
     answer: string;
-}>): {
+}>, 
+/**
+ * Interview language, already resolved by the caller (runClarification): a
+ * concrete language name ("vietnamese", "english", a pinned locale) or "auto".
+ * Feeds the shared `buildLanguageRule` so the cards follow the SAME language
+ * policy as the debate — the user's conversation language, not English-by-
+ * default. Defaults to "auto" so existing no-arg callers keep auto-detection.
+ */
+lang?: string): {
     system: string;
     prompt: string;
 };

package/dist/src/council/prompts.js

@@ -1,6 +1,14 @@
 import { buildStackLockSection } from "./decisions-lock.js";
 // ── Clarification prompts ────────────────────────────────────────────────────
-export function buildClarificationPrompt(topic, conversationContext, previousQA) {
+export function buildClarificationPrompt(topic, conversationContext, previousQA, 
+/**
+ * Interview language, already resolved by the caller (runClarification): a
+ * concrete language name ("vietnamese", "english", a pinned locale) or "auto".
+ * Feeds the shared `buildLanguageRule` so the cards follow the SAME language
+ * policy as the debate — the user's conversation language, not English-by-
+ * default. Defaults to "auto" so existing no-arg callers keep auto-detection.
+ */
+lang = "auto") {
     const qaSection = previousQA?.length
         ? `\n\n## Already Clarified\n${previousQA.map((qa) => `Q: ${qa.question}\nA: ${qa.answer}`).join("\n\n")}`
         : "";
@@ -12,6 +20,16 @@ export function buildClarificationPrompt(topic, conversationContext, previousQA)
             `- SCOPE: what is in/out of scope for THIS change?\n` +
             `- CONSTRAINTS: hard technical/time/business constraints not already implied by the context.\n` +
             `- SUCCESS CRITERIA: how "done" is judged, when it isn't already obvious.\n\n` +
+            `## Ground your questions in the research (IMPORTANT)\n` +
+            `If a "## Scope Research" section is present, it is evidence gathered about THIS topic before you ` +
+            `were asked to clarify. Read it first, then use it to ask SHARPER, better-grounded questions — ` +
+            `research makes your questions more pointed, it does NOT reduce the need to ask. Treat the research's ` +
+            `own guesses/speculation as UNVERIFIED, never as the user's answer: if the research had to assume ` +
+            `what the user actually wants (their real goal, the concrete task, the system of record, the target ` +
+            `user), that assumption IS the gray area you must confirm with them — do not adopt it silently. ` +
+            `In particular, when the request is vague and the research could only speculate about the core goal, ` +
+            `asking the user to name that goal/pain concretely is the single highest-value question — ask it. ` +
+            `Only skip a question when the research (or the topic/context) settles it with real evidence, not a guess.\n\n` +
             `## How many questions\n` +
             `Ask the minimum that unblocks a focused discussion — typically 0-2. A well-scoped topic, or one ` +
             `whose context already answers the gaps, needs ZERO questions: return []. Do NOT pad to a quota, ` +
@@ -36,11 +54,10 @@ export function buildClarificationPrompt(topic, conversationContext, previousQA)
             `the project IS the one described in the "## Current Project" section of the context. DO NOT ask which project.\n` +
             `- Only ask about project identity when the topic mentions multiple distinct projects or external products.\n` +
             `- Use the project's package.json name and description as implicit context for follow-up questions.\n\n` +
-            `## Language Rule (mandatory)\n` +
-            `Write the "question", "why", and every option "label"/"description" in the SAME ` +
-            `language the user used in the Topic below — detect it; if the user wrote Vietnamese, write ` +
-            `Vietnamese; if English, English. The user reads and answers these on a card, so they must ` +
-            `NOT default to English. Keep code identifiers, file paths, tech/product names, and JSON keys in English.\n\n` +
+            buildLanguageRule(lang) +
+            `The user reads and answers these on a card, so the "question", "why", and every option ` +
+            `"label"/"description" MUST be in that language — never default to English for card text, and ` +
+            `do NOT mirror the language of any "## Scope Research"/context block; follow the user's language.\n\n` +
             `Output ONLY a JSON array (no markdown, no preamble):\n` +
             `[{"question": "...", "why": "why this matters for a focused discussion", "options": [` +
             `{"label": "option A", "description": "what picking this means and its trade-off — one line", "recommended": true}, ` +

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

@@ -313,6 +313,16 @@ export interface CouncilConfig {
      * responder the clarifier + post-debate askcards use.
      */
     respondToQuestion?: QuestionResponder;
+    /**
+     * convene_council path — when true, the mid-debate escalation askcard
+     * (runEscalationPrompt) is auto-accepted WITHOUT emitting a blocking
+     * council_question card. The convene tool runs the council autonomously
+     * mid-agent-turn: there is no interactive user answering the escalation, so a
+     * card would hang the tool call. Auto-accept = conclude with the best
+     * synthesis so far. No decision is hardcoded post-synthesis — the calling
+     * agent decides what to do with the returned conclusion.
+     */
+    convenePath?: boolean;
     /**
      * C (mid-debate checkpoint) — directory to persist the per-round debate
      * checkpoint (`debate-checkpoint.json`), normally the run dir

package/dist/src/ee/auth.d.ts

@@ -25,6 +25,25 @@ export declare function refreshAuthToken(opts?: {
 export declare function writeExperienceConfig(patch: Partial<ExperienceConfig>, opts?: {
     home?: string;
 }): Promise<void>;
+/** Where the EE config lives, for display in setup/status output. */
+export declare function getExperienceConfigPath(opts?: {
+    home?: string;
+}): string;
+/**
+ * Best-effort reachability probe against an EE server's /health.
+ *
+ * Returns a reason on failure rather than a bare boolean: "saved but not
+ * reachable" and "saved, server says 401" are different problems for the user
+ * to act on, and collapsing them to `false` hides which one they have.
+ * Never throws — a probe is diagnostics, and must not fail a config write that
+ * already succeeded.
+ */
+export declare function probeEEHealth(baseUrl: string, token?: string, opts?: {
+    timeoutMs?: number;
+}): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
 export declare function getCachedAuthToken(): string | null;
 export declare function getEmbeddingModelVersion(): string;
 export declare function getCachedServerBaseUrl(): string | null;