muonroi-cli 1.8.5 → 1.9.0

package/dist/src/orchestrator/stream-runner.js

@@ -26,6 +26,7 @@
 //   - C3 (cross-turn dedup wrap)            — wrapToolSetWithDedup
 //   - F1 (sub-agent cumulative cap)         — wrapToolSetWithCap
 //   - reasoning-strip (provider quirk)       — taskCaps.sanitizeHistory
+import { appendFileSync } from "node:fs";
 import { stepCountIs, streamText } from "ai";
 import { recordArtifact } from "../ee/artifact-cache.js";
 import { getDefaultEEClient } from "../ee/intercept.js";
@@ -36,7 +37,7 @@ import { injectCheapModelWorkbook, shouldInjectCheapModelWorkbook, subagentTaskT
 import { getProviderCapabilities } from "../providers/capabilities.js";
 import { getVisionGuidanceForTextOnly } from "../providers/mcp-vision-bridge.js";
 import { captureToolSchemas } from "../providers/patch-zod-schema.js";
-import { buildTurnProviderOptions, requireRuntimeProvider, resolveModelRuntime, resolveTemperatureParam, shouldDropParam, } from "../providers/runtime.js";
+import { buildTurnProviderOptions, factoryForModel, requireRuntimeProvider, resolveModelRuntime, resolveTemperatureParam, shouldDropParam, } from "../providers/runtime.js";
 import { needsVisionProxy } from "../providers/vision-proxy.js";
 import { wireDebug } from "../providers/wire-debug.js";
 import { statusBarStore } from "../state/status-bar-store.js";
@@ -60,6 +61,35 @@ import { createStallWatchdog, STALL_ERROR_MESSAGE } from "./stall-watchdog.js";
 import { wrapToolSetWithCap } from "./sub-agent-cap.js";
 import { applyAnthropicPromptCaching, compactSubAgentMessages } from "./subagent-compactor.js";
 import { combineAbortSignals, firstLine, formatSubagentActivity } from "./tool-utils.js";
+/**
+ * Emit one sub-agent diagnostic line (MUONROI_DEBUG_SUBAGENT=1).
+ *
+ * Writes to the file named by MUONROI_SUBAGENT_DEBUG_LOG when set, else stderr.
+ * The file sink exists because stderr is a dead end for the case this
+ * diagnostic was written for: under the MCP harness the TUI runs as a child
+ * whose stderr nobody reads (opentui-spawn.ts consumes only the fd3/named-pipe
+ * stream), so every line went into a pipe no one drains. G1 — "Task failed: No
+ * output generated" — was named, given this flag, and never diagnosed, because
+ * the diagnostic could not reach whoever turned it on. Mirrors the working
+ * MUONROI_COUNCIL_DEBUG_LOG sink in council/llm.ts.
+ */
+export function writeSubagentDebug(enabled, line) {
+    if (!enabled)
+        return;
+    const text = `[subagent] ${line}\n`;
+    const path = process.env.MUONROI_SUBAGENT_DEBUG_LOG?.trim();
+    if (!path) {
+        process.stderr.write(text);
+        return;
+    }
+    try {
+        appendFileSync(path, text);
+    }
+    catch (err) {
+        // Never let diagnostics become the failure. Fall back to stderr and say why.
+        process.stderr.write(`[subagent] debug-log append failed (path=${path}): ${err instanceof Error ? err.message : String(err)}\n${text}`);
+    }
+}
 /**
  * StreamRunner — extracted sub-agent stream lifecycle.
  *
@@ -81,7 +111,6 @@ export class StreamRunner {
      * Returns either a prepared call or a short-circuit ToolResult.
      */
     async setup(request, onActivity, signal) {
-        const provider = this.deps.getProvider();
         const agentKey = String(request.agent);
         const isExplore = agentKey === "explore";
         const isGeneral = agentKey === "general";
@@ -189,12 +218,18 @@ export class StreamRunner {
         if (childModelId !== topModelId) {
             statusBarStore.setState({ routed_from: topModelId, model: childModelId });
         }
+        // The vision branch must build its model from the CHILD model's own factory.
+        // It previously called the PARENT session's factory directly, so a sub-agent
+        // routed to another provider had its id POSTed to the parent's endpoint.
         const childRuntime = isVision
-            ? {
-                ...resolveModelRuntime(provider, childModelId),
-                model: provider.responses?.(childModelId) ?? provider(childModelId),
-            }
-            : resolveModelRuntime(provider, childModelId);
+            ? (() => {
+                const childFactory = factoryForModel(childModelId);
+                return {
+                    ...resolveModelRuntime(childModelId),
+                    model: childFactory.responses?.(childModelId) ?? childFactory(childModelId),
+                };
+            })()
+            : resolveModelRuntime(childModelId);
         const taskCaps = getProviderCapabilities(requireRuntimeProvider(childRuntime));
         if (isComputer && !taskCaps.supportsClientTools(childRuntime.modelInfo)) {
             return {
@@ -321,10 +356,7 @@ export class StreamRunner {
         // diagnose "No output generated" / silent task failures (e.g. with
         // gpt-5.4 reasoning models). Disabled by default — zero cost.
         const debugSubagent = process.env.MUONROI_DEBUG_SUBAGENT === "1";
-        const debugLog = (line) => {
-            if (debugSubagent)
-                process.stderr.write(`[subagent] ${line}\n`);
-        };
+        const debugLog = writeSubagentDebug.bind(null, debugSubagent);
         if (debugSubagent) {
             const mi = childRuntime.modelInfo;
             debugLog(`start: model=${childRuntime.modelId} provider=${mi?.provider} reasoning=${mi?.reasoning} thinkingType=${mi?.thinkingType} supportsClientTools=${mi?.supportsClientTools} supportsMaxOutputTokens=${mi?.supportsMaxOutputTokens} agent=${prepared.request.agent}`);
@@ -789,30 +821,31 @@ export class StreamRunner {
             // MUONROI_DEBUG_SUBAGENT=1 so we can see whether `msg` is "No output
             // generated" (AI SDK validation failure on empty assistant response)
             // or a deeper provider error.
-            if (process.env.MUONROI_DEBUG_SUBAGENT === "1") {
+            const debugCatch = process.env.MUONROI_DEBUG_SUBAGENT === "1";
+            if (debugCatch) {
                 const e = err;
-                process.stderr.write(`[subagent] catch: name=${e.name ?? "?"} statusCode=${e.statusCode ?? "?"} message=${(e.message ?? "").slice(0, 400)}\n`);
+                writeSubagentDebug(true, `catch: name=${e.name ?? "?"} statusCode=${e.statusCode ?? "?"} message=${(e.message ?? "").slice(0, 400)}`);
                 if (e.cause !== undefined) {
                     try {
-                        process.stderr.write(`[subagent] catch.cause=${JSON.stringify(e.cause, Object.getOwnPropertyNames(e.cause)).slice(0, 600)}\n`);
+                        writeSubagentDebug(true, `catch.cause=${JSON.stringify(e.cause, Object.getOwnPropertyNames(e.cause)).slice(0, 600)}`);
                     }
-                    catch {
-                        process.stderr.write(`[subagent] catch.cause(string)=${String(e.cause).slice(0, 400)}\n`);
+                    catch (jsonErr) {
+                        writeSubagentDebug(true, `catch.cause(string)=${String(e.cause).slice(0, 400)} [stringify failed: ${jsonErr instanceof Error ? jsonErr.message : String(jsonErr)}]`);
                     }
                 }
                 if (e.responseBody !== undefined) {
-                    process.stderr.write(`[subagent] catch.responseBody=${String(e.responseBody).slice(0, 600)}\n`);
+                    writeSubagentDebug(true, `catch.responseBody=${String(e.responseBody).slice(0, 600)}`);
                 }
                 if (e.data !== undefined) {
                     try {
-                        process.stderr.write(`[subagent] catch.data=${JSON.stringify(e.data).slice(0, 400)}\n`);
+                        writeSubagentDebug(true, `catch.data=${JSON.stringify(e.data).slice(0, 400)}`);
                     }
-                    catch {
-                        /* non-serializable */
+                    catch (jsonErr) {
+                        writeSubagentDebug(true, `catch.data(unserializable): ${jsonErr instanceof Error ? jsonErr.message : String(jsonErr)}`);
                     }
                 }
                 if (e.stack)
-                    process.stderr.write(`[subagent] stack: ${e.stack.split("\n").slice(0, 6).join(" | ")}\n`);
+                    writeSubagentDebug(true, `stack: ${e.stack.split("\n").slice(0, 6).join(" | ")}`);
             }
             const output = `Task failed: ${msg}`;
             return {

package/dist/src/orchestrator/tool-engine.d.ts

@@ -7,6 +7,7 @@ import type { SessionInfo, StreamChunk, SubagentStatus } from "../types/index.js
 import { type PermissionMode } from "../utils/permission-mode.js";
 import type { AbortContext } from "./abort.js";
 import type { LegacyProvider, ProcessMessageObserver } from "./agent-options.js";
+import type { AskUserAskInfo } from "./ask-user.js";
 import type { CouncilManager } from "./council-manager.js";
 import type { CrossTurnDedup } from "./cross-turn-dedup.js";
 import type { PendingCallsLog } from "./pending-calls.js";
@@ -136,6 +137,8 @@ export interface MessageProcessorDeps extends TurnRunnerDepsBase {
     askToolLoopContinue?: ToolLoopCapAsk;
     /** Safety override handler — invoked when a tool call is blocked by the safety filter. */
     askSafetyOverride?: (info: SafetyOverrideAskInfo) => Promise<SafetyOverrideVerdict>;
+    /** ask_user handler — invoked when the model calls the `ask_user` tool; resolves the human's answer. */
+    askUser?: (info: AskUserAskInfo) => Promise<string>;
     runCouncilV2(userMessage: string, opts: {
         skipClarification: boolean;
         observer?: ProcessMessageObserver;
@@ -168,6 +171,22 @@ export declare function rewriteSafetyApprovedToolResults<T extends {
     role: string;
     content?: any;
 }>(messages: T[]): T[];
+/**
+ * Replace the `result` value of a single tool-result part (matched by
+ * toolCallId) in an AI-SDK message history, in place, preserving the
+ * tool-call/tool-result pairing. Used by the convene_council path to splice the
+ * council synthesis into the placeholder tool_result the model saw, so on the
+ * restarted step the model reads the conclusion as that tool's result. Pure +
+ * exported for unit testing. Returns the same array reference untouched when the
+ * toolCallId is absent (with a caller-visible `replaced` flag).
+ */
+export declare function spliceConveneToolResult<T extends {
+    role: string;
+    content?: any;
+}>(messages: T[], toolCallId: string | null, value: string): {
+    messages: T[];
+    replaced: boolean;
+};
 export declare class SimpleMutex {
     private queue;
     run<T>(fn: () => Promise<T> | T): Promise<T>;

package/dist/src/orchestrator/tool-engine.js

@@ -79,6 +79,7 @@ import { createBuiltinTools } from "../tools/registry.js";
 import { snapshotFromTodoWriteArgs } from "../tools/todo-write-snapshot.js";
 import { visionToolsNeeded } from "../tools/vision-gate.js";
 import { appendDecisionLog } from "../usage/decision-log.js";
+import { setLoopBreadcrumb } from "../utils/event-loop-monitor.js";
 import { logger } from "../utils/logger.js";
 import { openUrl } from "../utils/open-url.js";
 import { appendAudit, toolNeedsApproval } from "../utils/permission-mode.js";
@@ -88,9 +89,11 @@ import { resolveShell } from "../utils/shell.js";
 import { foldDynamicTailIntoUserMessage, splitFrontAndDynamicTail } from "./cache-prefix.js";
 import { consumeProactiveCompact } from "./compact-request.js";
 import { relaxCompactionSettings } from "./compaction.js";
+import { consumeCouncilConvene, hasPendingCouncilConvene, peekCouncilConveneToolCallId } from "./council-request.js";
 import { wrapToolSetWithDedup } from "./cross-turn-dedup.js";
 import { humanizeApiError, isAuthenticationError, isContextLimitError, summarizeApiErrorForLog } from "./error-utils.js";
 import { buildGroundingFootnote, findUnverifiedClaims } from "./grounding-check.js";
+import { isInteractivePaused } from "./interactive-pause.js";
 import { buildInterruptedTurnNote } from "./interrupted-turn.js";
 import { stableCallId } from "./pending-calls.js";
 import { buildMcpCapabilityBlock, MAX_LLM_CALLS_PER_TURN, } from "./prompts.js";
@@ -225,6 +228,38 @@ export function rewriteSafetyApprovedToolResults(messages) {
         return changed ? { ...m, content: newContent } : m;
     });
 }
+/**
+ * Replace the `result` value of a single tool-result part (matched by
+ * toolCallId) in an AI-SDK message history, in place, preserving the
+ * tool-call/tool-result pairing. Used by the convene_council path to splice the
+ * council synthesis into the placeholder tool_result the model saw, so on the
+ * restarted step the model reads the conclusion as that tool's result. Pure +
+ * exported for unit testing. Returns the same array reference untouched when the
+ * toolCallId is absent (with a caller-visible `replaced` flag).
+ */
+export function spliceConveneToolResult(messages, toolCallId, value) {
+    if (!toolCallId)
+        return { messages, replaced: false };
+    let replaced = false;
+    const out = messages.map((m) => {
+        if (m.role !== "tool" || !Array.isArray(m.content))
+            return m;
+        let changed = false;
+        const newContent = m.content.map((part) => {
+            if (part?.type === "tool-result" && part?.toolCallId === toolCallId) {
+                changed = true;
+                replaced = true;
+                // AI SDK v6 tool-result parts carry the value under `output` (typed) or
+                // `result` (legacy). Set both so whichever the provider serializer reads
+                // sees the synthesis, and clear any error flag.
+                return { ...part, isError: false, output: value, result: value };
+            }
+            return part;
+        });
+        return changed ? { ...m, content: newContent } : m;
+    });
+    return { messages: replaced ? out : messages, replaced };
+}
 export class SimpleMutex {
     queue = Promise.resolve();
     async run(fn) {
@@ -284,6 +319,17 @@ export async function* executeToolEngine(args) {
     // (default 6, env MUONROI_TOOL_LIMIT_AUTO_RECOVER_CAP).
     let toolLimitAutoRecoverCount = 0;
     const TOOL_LIMIT_AUTO_RECOVER_CAP = getToolLimitAutoRecoverCap();
+    // Convene-council loop guard. The agent may convene the council at most once
+    // per turn — a second convene_council call in the SAME turn does NOT re-run a
+    // full (5-10min) council; instead its tool-result is a non-binding suggestion
+    // to USE the synthesis already above (respond, or ask_user). Turn-scoped (not
+    // per-stream-attempt) so a `continue` restart cannot reset it. Live-caught:
+    // the model looped convene→synthesis→convene, burning a second council.
+    let conveneRunsThisTurn = 0;
+    const COUNCIL_MAX_CONVENES_PER_TURN = (() => {
+        const raw = Number.parseInt(process.env.MUONROI_MAX_CONVENES_PER_TURN ?? "", 10);
+        return Number.isFinite(raw) && raw >= 1 ? raw : 1;
+    })();
     let stallTriggered = false;
     // Time-to-first-byte stall RE-PROMPT: some providers (observed:
     // xai/grok-build-0.1) accept the request then never send the first byte —
@@ -432,18 +478,23 @@ export async function* executeToolEngine(args) {
             skipClarification: !isAutoCouncilClarifyEnabled(),
             observer,
             userModelMessage,
+            // Suppress the CLI-hardcoded post-debate option card. The follow-up is
+            // decided by the agent's own intent via the neutral continuation below,
+            // not a fixed CLI menu. (Pre-debate clarification is orthogonal and still
+            // runs per skipClarification.)
+            convenePath: true,
         });
         const synthesis = deps.councilManager.lastSynthesis;
         const chosenAction = deps.councilManager.lastPostDebateAction;
         deps.councilManager.setLastSynthesis(null);
         deps.councilManager.setLastPostDebateAction(null);
-        // Honor the user's post-debate choice instead of always continuing: an
-        // evaluation/decision debate whose deliverable is the conclusion (default
-        // save_exit) now returns to the composer rather than being force-fed a
-        // meaningless "proceed with the action items" turn. postDebateContinuation
-        // is shared with the /council slash path (orchestrator.runCouncilV2).
-        const { postDebateContinuation } = await import("../council/index.js");
-        const continuationPrompt = synthesis ? postDebateContinuation(chosenAction ?? undefined, synthesis) : null;
+        // convenePath suppressed the hardcoded card, so there is no chosenAction to
+        // branch on. Hand the synthesis to a normal agent turn with a non-binding
+        // nudge and let the agent decide the next step (respond / ask_user /
+        // implement). Re-entry is guarded by setContinuation(true) below so
+        // shouldAutoCouncil (which checks !isContinuation) can't re-fire into a loop.
+        const { buildNeutralPostCouncilContinuation } = await import("../council/index.js");
+        const continuationPrompt = synthesis ? buildNeutralPostCouncilContinuation(synthesis) || null : null;
         if (continuationPrompt) {
             yield { type: "content", content: "\n[Auto-continuing with council recommendations...]\n" };
             deps.councilManager.setContinuation(true);
@@ -456,12 +507,10 @@ export async function* executeToolEngine(args) {
         }
         return;
     }
-    if (shouldSkipForReasoning) {
-        yield {
-            type: "content",
-            content: `\n[Auto-council skipped: ${deps.modelId} is a reasoning model and already performs internal self-debate. Set MUONROI_AUTOCOUNCIL_SKIP_REASONING=0 or autoCouncilSkipReasoning=false to force council.]\n`,
-        };
-    }
+    // Skipping auto-council is the normal, expected path for a reasoning model —
+    // not an event the user needs narrated on every turn. The decision (and the
+    // gate values behind it) is still recorded via autoCouncilSkipReason above,
+    // so forensics keep the full story without the transcript noise.
     if (deps.batchApi) {
         try {
             yield* deps.processMessageBatchTurn({
@@ -612,15 +661,44 @@ export async function* executeToolEngine(args) {
                     sessionId: deps.session?.id,
                     includeVisionTools,
                     consultParentSession: deps.consultParentSession,
+                    // Register convene_council only when the council is actually usable
+                    // for this session (enough configured roles) — else the model could
+                    // call a council that can't convene.
+                    councilConfigured: configuredRoleCount >= autoCouncilMinRoles,
+                    askUser: deps.askUser,
                     runDebate: async (topic) => {
+                        // Reset before draining so a generator that throws BEFORE setting
+                        // synthesis (orchestrator.setLastSynthesis) cannot return a STALE
+                        // synthesis from a prior council run.
+                        deps.councilManager.setLastSynthesis(null);
                         const gen = deps.runCouncilV2(topic, {
                             skipClarification: true,
                             userModelMessage: { role: "user", content: `/council ${topic}` },
+                            // Model-callable debate: the synthesis is returned to the model as
+                            // the tool result and the model decides the follow-up — so suppress
+                            // the CLI-hardcoded post-debate card, same as convene_council.
+                            convenePath: true,
                         });
+                        // Capture a tail of content chunks so an empty-synthesis failure
+                        // (provider unreachable / sub-phase fail-open / abort — all of which
+                        // yield a content hint then `return null`) surfaces a real reason in
+                        // the log instead of a silent "".
+                        let lastContentHint = "";
                         for await (const chunk of gen) {
-                            // Drain the generator
+                            const text = chunk?.content;
+                            if (chunk?.type === "content" && typeof text === "string" && text.trim()) {
+                                lastContentHint = text.trim().slice(-200);
+                            }
+                        }
+                        const synthesis = deps.councilManager.lastSynthesis ?? "";
+                        if (!synthesis.trim()) {
+                            // No-Silent-Catch: the debate produced no synthesis. plan-council
+                            // will retry then fall back to the perspective path — log why here
+                            // so the failure is diagnosable remotely.
+                            console.error(`[tool-engine] plan-review runDebate returned empty synthesis` +
+                                `${lastContentHint ? ` (last council chunk: ${lastContentHint})` : ""}`);
                         }
-                        return deps.councilManager.lastSynthesis ?? "";
+                        return synthesis;
                     },
                 });
                 // Top-level cumulative cap state. We accumulate the raw tool set
@@ -799,6 +877,14 @@ export async function* executeToolEngine(args) {
                     "ee_feedback",
                     "ee_write",
                 ]);
+                /**
+                 * Tools that perform mutations (writes, edits, side-effects).
+                 * MUTATION_TOOLS are read from this set to route them through the mutation
+                 * gate and prevent accidental execution when GSD hard gate is active.
+                 * Registration: add the tool name string to this set and ensure the tool
+                 * itself is wired in the tool assembly step.
+                 */
+                const MUTATION_TOOLS = new Set(["lsp_mutation_preview"]);
                 // Task 8: native GSD mutation gate. Read once per turn (not per call) since
                 // hardGateEnabled/directAnswer don't change mid-turn; the gate itself
                 // re-reads STATE.md per call (cheap fs read) so it stays live if the
@@ -807,12 +893,23 @@ export async function* executeToolEngine(args) {
                 const gsdDirectAnswer = pilCtx.directAnswer;
                 for (const name of Object.keys(tools)) {
                     const tool = tools[name];
-                    if (tool &&
-                        typeof tool.execute === "function" &&
-                        !READ_ONLY_TOOLS.has(name) &&
-                        !name.startsWith("respond_")) {
-                        const originalExecute = tool.execute;
-                        tool.execute = async (input, context) => {
+                    if (!tool || typeof tool.execute !== "function")
+                        continue;
+                    const originalExecute = tool.execute;
+                    // Read-only tools skip the mutation gate and the write mutex, but ALL
+                    // tools get a breadcrumb: a freeze can start under any of them, and a
+                    // block report that cannot name a suspect is much weaker evidence.
+                    const guarded = !READ_ONLY_TOOLS.has(name) && !name.startsWith("respond_");
+                    tool.execute = async (input, context) => {
+                        // Never cleared, only overwritten — a block often starts just AFTER
+                        // a tool returns (the 2026-07-16 freeze began on the tick after a
+                        // bash result), so "after:bash" is exactly the clue we want. Also
+                        // why this is not a stack: with parallel tool calls, last-writer-
+                        // wins is the honest summary; the CPU profile is the real evidence.
+                        setLoopBreadcrumb(`tool:${name}`);
+                        try {
+                            if (!guarded)
+                                return await originalExecute(input, context);
                             const gate = evaluateMutationGate(deps.bash.getCwd(), {
                                 toolName: name,
                                 hardGateEnabled: gsdHardGateEnabled,
@@ -821,9 +918,12 @@ export async function* executeToolEngine(args) {
                             if (gate.blocked) {
                                 return { success: false, output: gate.reason, error: gate.reason };
                             }
-                            return writeMutex.run(() => originalExecute(input, context));
-                        };
-                    }
+                            return await writeMutex.run(() => originalExecute(input, context));
+                        }
+                        finally {
+                            setLoopBreadcrumb(`after-tool:${name}`);
+                        }
+                    };
                 }
                 captureToolSchemas(tools);
                 let responseToolCalled = false;
@@ -1225,6 +1325,14 @@ export async function* executeToolEngine(args) {
                         _hardCapHit = true;
                         return true;
                     }
+                    // convene_council fast-path: if the model queued a council convening
+                    // during this step, STOP now so the outer loop runs the council and
+                    // splices the synthesis BEFORE the model consumes the placeholder
+                    // tool_result. This is a fast-path only — the authoritative
+                    // consumption is the outer-loop check after the stream drains (a
+                    // phase-1 SAMR step ends on stepCountIs(1) and never reaches here).
+                    if (hasPendingCouncilConvene())
+                        return true;
                     // Terminal response tool: a `respond_*` call IS the model's final
                     // structured answer (its `execute` is identity — the payload lives
                     // in the tool-call args). `shouldHaltOnResponseTool` decides if the
@@ -1337,7 +1445,9 @@ export async function* executeToolEngine(args) {
                         console.error(`[tool-engine] stream aborted: no text/tool output for ${getProviderProgressTimeoutMs()}ms ` +
                             `(runaway reasoning / no forward progress) model=${runtime.modelId}`);
                     },
-                });
+                }, 
+                // Hold the stream open while a blocking `ask_user` card awaits a human.
+                isInteractivePaused);
                 // F3c — hard-cap LLM calls per turn before this streamText()
                 if (++llmCallsThisTurn > MAX_LLM_CALLS_PER_TURN) {
                     stall.dispose();
@@ -1808,6 +1918,9 @@ export async function* executeToolEngine(args) {
                 const _wireProviderIdTop = runtime.modelInfo?.provider ?? "unknown";
                 for await (const part of result.fullStream) {
                     stall.pet(); // chunk arrived — reset the stall watchdog
+                    // Breadcrumb the chunk type: if the loop blocks while draining the
+                    // stream, this says which part kind we were handling when it froze.
+                    setLoopBreadcrumb(`stream:${String(part.type ?? "unknown")}`);
                     // Count only real content parts. The watchdog abort itself surfaces
                     // as an "abort" part — counting it would defeat the TTFB-stall gate
                     // (a frozen-before-first-byte stall yields ONLY the abort part).
@@ -2861,6 +2974,109 @@ export async function* executeToolEngine(args) {
                     }
                 }
                 stall.dispose(); // stream drained normally — stop the stall watchdog
+                // ─── convene_council consumption ───────────────────────────────
+                // The convene_council tool queued a request during THIS step's execute().
+                // Consume it here in the OUTER loop after every stream drain — NOT solely
+                // via dynamicStopWhen, because a phase-1 SAMR step ends on stepCountIs(1)
+                // and never evaluates the stop hook (design-debate BUG 2). Runs the
+                // council autonomously (convenePath suppresses ALL post-debate decision
+                // surface — no card, no continuation), splices the synthesis into the
+                // convene tool_result, grafts into deps.messages, and restarts the step
+                // so the model reads the conclusion as the tool result and continues.
+                if (hasPendingCouncilConvene()) {
+                    if (responseToolCalled) {
+                        // The same step also emitted a terminal respond_* answer — the model
+                        // is done; discard the convene request rather than override the
+                        // answer (design-debate BUG 1: never let the flag leak across turns).
+                        consumeCouncilConvene();
+                        logger.warn("orchestrator", "convene: discarded — step also emitted a terminal response tool");
+                    }
+                    else {
+                        const pendingId = peekCouncilConveneToolCallId();
+                        let conveneResponse = null;
+                        try {
+                            conveneResponse = await result.response;
+                        }
+                        catch (err) {
+                            logger.error("orchestrator", "convene: failed to read response.messages", {
+                                error: err?.message,
+                            });
+                        }
+                        // BUG 3 guard: only run council when the pending convene toolCallId is
+                        // a recorded tool-result in THIS drain's messages — else a nested
+                        // frame's convene call would be wrongly consumed by this loop.
+                        const belongsHere = !!conveneResponse &&
+                            !!pendingId &&
+                            conveneResponse.messages.some((m) => m?.role === "tool" &&
+                                Array.isArray(m.content) &&
+                                m.content.some((p) => p?.type === "tool-result" && p?.toolCallId === pendingId));
+                        if (belongsHere && conveneResponse) {
+                            const req = consumeCouncilConvene();
+                            // Loop guard: a second convene in the SAME turn short-circuits —
+                            // do NOT pay for another council. Splice a non-binding suggestion
+                            // pointing the model at the synthesis already in the transcript so
+                            // it responds (or asks the user) instead of re-convening forever.
+                            if (conveneRunsThisTurn >= COUNCIL_MAX_CONVENES_PER_TURN) {
+                                logger.warn("orchestrator", "convene: loop guard hit — suppressing re-convene", {
+                                    conveneRunsThisTurn,
+                                    cap: COUNCIL_MAX_CONVENES_PER_TURN,
+                                });
+                                const suggestion = "[The council already convened this turn — its synthesis is in the transcript above. " +
+                                    "Do NOT convene again for the same question. Use that synthesis now: give the user your " +
+                                    "recommendation, or call ask_user if you need their go-ahead before implementing.]";
+                                const { messages: guardSpliced, replaced: guardReplaced } = spliceConveneToolResult(conveneResponse.messages, req?.toolCallId ?? null, suggestion);
+                                if (!guardReplaced) {
+                                    logger.warn("orchestrator", "convene: loop-guard splice found no matching toolCallId", {
+                                        toolCallId: req?.toolCallId ?? null,
+                                    });
+                                }
+                                const guardNewMsgs = guardSpliced.slice(deps.messages.length);
+                                for (const msg of guardNewMsgs)
+                                    deps.messages.push(msg);
+                                continue; // re-enter with the suggestion as the tool result
+                            }
+                            conveneRunsThisTurn++;
+                            yield { type: "content", content: "\n[Convening the council…]\n" };
+                            // Filter the terminal `done` runCouncilV2 emits on its
+                            // non-continuation path (orchestrator.ts ~2274): letting it through
+                            // would finalize the UI turn BEFORE we restart streamText below, so
+                            // the model's post-council continuation would be orphaned/invisible
+                            // (live-caught: council ran, synthesis produced, but no final answer
+                            // rendered). We continue the SAME turn ourselves via the splice +
+                            // `continue` restart, so the council's `done` must not propagate.
+                            for await (const chunk of deps.runCouncilV2(userMessage, {
+                                convenePath: true,
+                                skipClarification: true,
+                                observer,
+                                userModelMessage,
+                            })) {
+                                if (chunk.type === "done")
+                                    continue;
+                                yield chunk;
+                            }
+                            const synthesis = deps.councilManager.lastSynthesis;
+                            const spliceValue = synthesis && synthesis.trim().length > 0
+                                ? synthesis
+                                : `[Council could not produce a conclusion${req?.reason ? ` for: ${req.reason}` : ""}. Proceed using your own judgment.]`;
+                            if (!synthesis || synthesis.trim().length === 0) {
+                                logger.warn("orchestrator", "convene: council returned no synthesis", { reason: req?.reason ?? null });
+                            }
+                            const { messages: spliced, replaced } = spliceConveneToolResult(conveneResponse.messages, req?.toolCallId ?? null, spliceValue);
+                            if (!replaced) {
+                                logger.warn("orchestrator", "convene: tool_result splice found no matching toolCallId", {
+                                    toolCallId: req?.toolCallId ?? null,
+                                });
+                            }
+                            // Graft the new messages (assistant tool-call + spliced tool-result)
+                            // into deps.messages, then restart the step so the model reads the
+                            // synthesis as the convene tool's result (SAMR restart precedent).
+                            const newMsgs = spliced.slice(deps.messages.length);
+                            for (const msg of newMsgs)
+                                deps.messages.push(msg);
+                            continue; // re-enter the loop with the spliced history
+                        }
+                    }
+                }
                 // ─── SAMR Phase 1 → Phase 2 transition ─────────────────────────
                 // Phase 1 (premium model) produced tool calls but the SDK stopped
                 // before executing them (stopWhen: stepCountIs(1)). Append the

package/dist/src/orchestrator/turn-watchdog.d.ts

@@ -33,5 +33,12 @@ export interface TurnWatchdogOptions {
     totalMs: number;
     /** Human label used in the thrown error (e.g. "council continuation turn"). */
     label: string;
+    /**
+     * Optional gate consulted the instant a timer would fire. When it returns
+     * true the timer RE-ARMS instead of throwing — used to hold the turn open
+     * while a blocking `ask_user` card awaits a human (no chunks flow, but the
+     * turn is not hung). See interactive-pause.ts.
+     */
+    shouldSuppressFire?: () => boolean;
 }
 export declare function withTurnWatchdog(gen: AsyncGenerator<StreamChunk, void, unknown>, opts: TurnWatchdogOptions): AsyncGenerator<StreamChunk, void, unknown>;

package/dist/src/orchestrator/turn-watchdog.js

@@ -7,15 +7,23 @@ export class TurnStallError extends Error {
     }
 }
 export async function* withTurnWatchdog(gen, opts) {
-    const { idleMs, totalMs, label } = opts;
+    const { idleMs, totalMs, label, shouldSuppressFire } = opts;
     const it = gen[Symbol.asyncIterator]();
     let totalTimer;
     const total = totalMs > 0
         ? new Promise((_, reject) => {
-            totalTimer = setTimeout(() => {
-                reject(new TurnStallError("total", `${label} exceeded ${Math.round(totalMs / 1000)}s total watchdog — treated as hung`));
-            }, totalMs);
-            totalTimer.unref?.();
+            const armTotal = () => {
+                totalTimer = setTimeout(() => {
+                    // Hold open while an interactive card blocks the turn.
+                    if (shouldSuppressFire?.()) {
+                        armTotal();
+                        return;
+                    }
+                    reject(new TurnStallError("total", `${label} exceeded ${Math.round(totalMs / 1000)}s total watchdog — treated as hung`));
+                }, totalMs);
+                totalTimer.unref?.();
+            };
+            armTotal();
         })
         : null;
     try {
@@ -23,10 +31,17 @@ export async function* withTurnWatchdog(gen, opts) {
             let idleTimer;
             const idle = idleMs > 0
                 ? new Promise((_, reject) => {
-                    idleTimer = setTimeout(() => {
-                        reject(new TurnStallError("idle", `${label} produced no output for ${Math.round(idleMs / 1000)}s — treated as hung`));
-                    }, idleMs);
-                    idleTimer.unref?.();
+                    const armIdle = () => {
+                        idleTimer = setTimeout(() => {
+                            if (shouldSuppressFire?.()) {
+                                armIdle();
+                                return;
+                            }
+                            reject(new TurnStallError("idle", `${label} produced no output for ${Math.round(idleMs / 1000)}s — treated as hung`));
+                        }, idleMs);
+                        idleTimer.unref?.();
+                    };
+                    armIdle();
                 })
                 : null;
             const racers = [it.next()];
@@ -38,6 +53,20 @@ export async function* withTurnWatchdog(gen, opts) {
             try {
                 res = await Promise.race(racers);
             }
+            catch (err) {
+                // Stall (idle/total) fired while `it.next()` is still pending: the inner
+                // generator is suspended at an `await` and, unless told to unwind, its
+                // finally blocks (write-mutex release, in-flight council/tool cleanup)
+                // NEVER run — the turn "ends" for the UI but leaks a wedged generator
+                // that can block the NEXT turn (observed live: council reasoning-model
+                // hang, session c1d461439618 — user had to Ctrl+C and relaunch).
+                // Signal it to return. Fire-and-forget on purpose: the queued return
+                // only settles once the CALLER aborts its controller (in its catch,
+                // AFTER we rethrow), which settles the hung provider call — awaiting the
+                // return here would deadlock against that ordering.
+                void it.return?.(undefined).catch(() => { });
+                throw err;
+            }
             finally {
                 if (idleTimer)
                     clearTimeout(idleTimer);