muonroi-cli 1.8.5 → 1.9.0

package/dist/src/tools/git-safety.js

@@ -24,6 +24,7 @@
  *
  * Override the push gate with `MUONROI_ALLOW_PUSH_ON_RED=1`.
  */
+import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { isVerificationCommand } from "../orchestrator/tool-args-hash.js";
@@ -216,6 +217,173 @@ export function checkSensitiveStaging(cwd) {
         "To bypass this gate (not recommended), set MUONROI_ALLOW_BROAD_STAGE=1.";
     return { blocked: true, sensitive, message };
 }
+// ── Destructive-op guard (2026-07-12) ──────────────────────────────────────
+//
+// Motivation: an autonomous /ideal plan-adherence fix sub-agent ran
+// `git checkout -- <files>` + committed the result, silently discarding the
+// user's UNCOMMITTED, unrelated working-tree changes (a whole set of harness
+// fixes). No existing guard caught it. This guard classifies commands that
+// irreversibly discard uncommitted work and blocks them PRE-EXECUTION when
+// there is actually work at risk. Routed as the `destructive-revert` safety
+// kind: interactive → askcard (allow-once/block, never auto-allow even in
+// yolo); headless/autonomous → hard-block. Escape hatch:
+// MUONROI_ALLOW_DESTRUCTIVE_REVERT=1 (user-set, logged like the other gates).
+// `git checkout … -- ` (discard paths) OR `git checkout .` (discard all).
+const CHECKOUT_DISCARD_RE = /\bgit\b[^|&;\n]*[ \t]checkout\b(?:[^|&;\n]*[ \t]--(?:[ \t]|$)|[ \t]+\.(?=[ \t]|$))/;
+// `git restore …` discards the working tree by default. `git restore --staged`
+// WITHOUT `--worktree`/`-W` only unstages (non-destructive) — exempt that.
+const RESTORE_RE = /\bgit\b[^|&;\n]*[ \t]restore\b/;
+const RESTORE_STAGED_RE = /[ \t]--staged\b/;
+const RESTORE_WORKTREE_RE = /[ \t](?:--worktree\b|-[a-z]*W)/;
+// `git reset --hard` throws away all uncommitted changes.
+const RESET_HARD_RE = /\bgit\b[^|&;\n]*[ \t]reset\b[^|&;\n]*[ \t]--hard\b/;
+// `git clean -f[d][x]` deletes untracked files.
+const CLEAN_FORCE_RE = /\bgit\b[^|&;\n]*[ \t]clean\b[^|&;\n]*[ \t]-[a-eg-wyz]*f/;
+// `git stash drop` / `git stash clear` destroy stashed work.
+const STASH_DROP_RE = /\bgit\b[^|&;\n]*[ \t]stash[ \t]+(?:drop|clear)\b/;
+// `rm` (not rmdir) — targets checked against git tracking below.
+const RM_RE = /(?:^|[|&;\n]|\s)rm\b(?!dir)/;
+export function analyzeDestructiveGit(command) {
+    const c = stripQuoted(command);
+    if (RESET_HARD_RE.test(c))
+        return { kind: "reset-hard", untrackedRisk: false };
+    if (CHECKOUT_DISCARD_RE.test(c))
+        return { kind: "checkout-discard", untrackedRisk: false };
+    if (RESTORE_RE.test(c)) {
+        const stagedOnly = RESTORE_STAGED_RE.test(c) && !RESTORE_WORKTREE_RE.test(c);
+        if (!stagedOnly)
+            return { kind: "restore", untrackedRisk: false };
+    }
+    if (CLEAN_FORCE_RE.test(c))
+        return { kind: "clean", untrackedRisk: true };
+    if (STASH_DROP_RE.test(c))
+        return { kind: "stash-drop", untrackedRisk: false };
+    return { kind: null, untrackedRisk: false };
+}
+function git(cwd, args) {
+    try {
+        const r = spawnSync("git", args, { cwd, encoding: "utf8", timeout: 8000, maxBuffer: 8 * 1024 * 1024 });
+        return (r.stdout ?? "").trim();
+    }
+    catch {
+        return "";
+    }
+}
+/** Working-tree paths that a destructive command would discard (best-effort). */
+function atRiskPaths(cwd, untrackedRisk) {
+    // NOTE: read raw stdout — do NOT trim the whole output. Porcelain v1 lines
+    // are "XY<space>PATH" where XY is 2 chars; a global trim would eat the leading
+    // space of a " M file" line and shift the path parse by one character.
+    let raw;
+    try {
+        const r = spawnSync("git", ["status", "--porcelain"], {
+            cwd,
+            encoding: "utf8",
+            timeout: 8000,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        raw = r.stdout ?? "";
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (line.length < 4)
+            continue;
+        const xy = line.slice(0, 2);
+        const file = line.slice(3).trim();
+        const isUntracked = xy === "??";
+        if (untrackedRisk ? isUntracked : !isUntracked && xy !== "!!")
+            out.push(file);
+    }
+    return out;
+}
+/** Extract rm target tokens (non-flag args) from a single-clause rm command. */
+function rmTargets(command) {
+    const c = stripQuoted(command);
+    const m = c.match(/(?:^|[|&;\n]|\s)rm\b(?!dir)([^|&;\n]*)/);
+    if (!m)
+        return [];
+    return m[1]
+        .split(/\s+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0 && !t.startsWith("-") && t !== '""' && t !== "''");
+}
+/** rm targets that are git-tracked (file directly, or a dir containing tracked files). */
+function rmTrackedTargets(cwd, command) {
+    const targets = rmTargets(command);
+    const tracked = [];
+    for (const t of targets) {
+        // Tracked file?
+        const asFile = spawnSync("git", ["ls-files", "--error-unmatch", t], {
+            cwd,
+            encoding: "utf8",
+            timeout: 6000,
+        });
+        if (asFile.status === 0) {
+            tracked.push(t);
+            continue;
+        }
+        // Directory containing tracked files?
+        const underDir = git(cwd, ["ls-files", "--", t]);
+        if (underDir)
+            tracked.push(t);
+    }
+    return tracked;
+}
+/**
+ * Pre-execution guard: block a working-tree-destroying command when it would
+ * actually discard uncommitted work. Returns blocked=false (no message) when
+ * the command is non-destructive, when nothing is at risk, or when the user set
+ * the escape hatch. Deterministic + cheap (a couple of git plumbing calls).
+ */
+export function checkDestructiveOp(command, cwd) {
+    if (process.env.MUONROI_ALLOW_DESTRUCTIVE_REVERT === "1") {
+        return { blocked: false, kind: null, message: "" };
+    }
+    const shape = analyzeDestructiveGit(command);
+    if (shape.kind) {
+        let atRisk;
+        if (shape.kind === "stash-drop") {
+            atRisk = git(cwd, ["stash", "list"]).split("\n").filter(Boolean);
+        }
+        else {
+            atRisk = atRiskPaths(cwd, shape.untrackedRisk);
+        }
+        if (atRisk.length === 0)
+            return { blocked: false, kind: shape.kind, message: "" };
+        return { blocked: true, kind: shape.kind, message: destructiveMessage(shape.kind, atRisk) };
+    }
+    if (RM_RE.test(stripQuoted(command))) {
+        const tracked = rmTrackedTargets(cwd, command);
+        if (tracked.length > 0) {
+            return { blocked: true, kind: "rm-tracked", message: destructiveMessage("rm-tracked", tracked) };
+        }
+    }
+    return { blocked: false, kind: null, message: "" };
+}
+function destructiveMessage(kind, items) {
+    const list = items
+        .slice(0, 30)
+        .map((n) => `  • ${n}`)
+        .join("\n");
+    const more = items.length > 30 ? `\n  … and ${items.length - 30} more` : "";
+    const verb = {
+        "checkout-discard": "`git checkout` discarding working-tree changes",
+        restore: "`git restore` discarding working-tree changes",
+        "reset-hard": "`git reset --hard` discarding ALL uncommitted changes",
+        clean: "`git clean` deleting untracked files",
+        "stash-drop": "`git stash drop/clear` destroying stashed work",
+        "rm-tracked": "`rm` deleting git-tracked file(s)",
+    };
+    return (`BLOCKED: refusing ${verb[kind]} — this irreversibly discards uncommitted work:\n` +
+        `${list}${more}\n\n` +
+        "These changes are NOT committed and cannot be recovered once discarded. If you did " +
+        "not intend to destroy them, leave them alone (they may be the user's unrelated work). " +
+        "To keep them, `git add` + `git commit` (or `git stash`) FIRST, then retry. To bypass " +
+        "this guard for a genuine, intentional discard, set MUONROI_ALLOW_DESTRUCTIVE_REVERT=1.");
+}
 /**
  * @deprecated Use checkSensitiveStaging() for hard-blocking.
  * Kept for call sites that emit a trailing warning (non-broad-stage contexts).

package/dist/src/tools/native-tools.d.ts

@@ -20,7 +20,7 @@
  */
 import { type ToolSet } from "ai";
 /** The native tool names this module registers — used by the MCP-twin dedup. */
-export declare const NATIVE_MUONROI_TOOL_NAMES: readonly ["ee_health", "ee_feedback", "ee_write", "usage_forensics", "lsp_query", "setup_guide", "selfverify_start", "selfverify_status", "selfverify_result", "selfverify_list", "selfverify_cancel"];
+export declare const NATIVE_MUONROI_TOOL_NAMES: readonly ["ee_health", "ee_feedback", "ee_write", "usage_forensics", "lsp_query", "wait_for_diagnostics", "impact_of_change", "lsp_mutation_preview", "setup_guide", "selfverify_start", "selfverify_status", "selfverify_result", "selfverify_list", "selfverify_cancel"];
 export interface NativeToolOpts {
     /** Workspace cwd for lsp_query. Defaults to process.cwd(). */
     cwd?: string;

package/dist/src/tools/native-tools.js

@@ -19,9 +19,22 @@
  * identical across the two surfaces.
  */
 import { dynamicTool, jsonSchema } from "ai";
-import { LSP_TOOL_OPERATIONS } from "../lsp/types.js";
+import { LSP_TOOL_OPERATIONS, LspError } from "../lsp/types.js";
 import { getSelfVerifyJobManager } from "../mcp/self-verify-runner.js";
 import { SETUP_GUIDE_TEXT } from "../mcp/setup-guide-text.js";
+/** Map a thrown error to the LspError tagged-union shape. */
+function mapLspError(e) {
+    if (e instanceof LspError)
+        return e;
+    if (e && typeof e === "object" && "kind" in e && "message" in e) {
+        return new LspError(e.kind, e.message);
+    }
+    return new LspError("unknown", e instanceof Error ? e.message : String(e));
+}
+function lspErrLine(e) {
+    const err = mapLspError(e);
+    return JSON.stringify({ error: err.kind, message: err.message });
+}
 /** The native tool names this module registers — used by the MCP-twin dedup. */
 export const NATIVE_MUONROI_TOOL_NAMES = [
     "ee_health",
@@ -29,6 +42,9 @@ export const NATIVE_MUONROI_TOOL_NAMES = [
     "ee_write",
     "usage_forensics",
     "lsp_query",
+    "wait_for_diagnostics",
+    "impact_of_change",
+    "lsp_mutation_preview",
     "setup_guide",
     "selfverify_start",
     "selfverify_status",
@@ -219,6 +235,65 @@ export function registerNativeMuonroiTools(tools, opts = {}) {
             }
         },
     });
+    // ── Sprint 1: readiness contract tools ─────────────────────────────────────
+    tools.wait_for_diagnostics = dynamicTool({
+        description: "Wait for LSP diagnostics on a file, with timeout clamping (default 1500ms, max 5000ms). " +
+            "Returns { diagnostics: LspDiagnostic[], lspStatus: 'ok'|'partial'|'unavailable', clean: boolean, metadata: { tokenBudgetUsed } }. " +
+            "clean=true means zero error-level diagnostics. Grep fallback is allowed when lspStatus !== 'ok'.",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                filePath: { type: "string", description: "Absolute or workspace-relative path" },
+                timeout: { type: "number", description: "Timeout in ms (default 1500, max 5000)", optional: true },
+            },
+            required: ["filePath"],
+        }),
+        execute: async (input) => {
+            const cwd = opts.cwd ?? process.cwd();
+            try {
+                const { getOrCreateManager } = await import("../lsp/runtime.js");
+                return json(await getOrCreateManager(cwd).waitForDiagnostics(input.filePath, input.timeout ?? 1500));
+            }
+            catch (e) {
+                return lspErrLine(e);
+            }
+        },
+    });
+    tools.impact_of_change = dynamicTool({
+        description: "Analyse impact of a change: returns { references, diagnostics, referencesComplete, safeToRename, clean, " +
+            "suggestedGuard, degraded, lspStatus, metadata }. Safe for use as lsp-before-grep gate: grep fallback is " +
+            "allowed when lspStatus !== 'ok'; safeToRename is true only when refs are complete and the union is clean.",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                filePath: { type: "string", description: "Absolute or workspace-relative path" },
+                query: { type: "string", description: "Optional symbol query", optional: true },
+            },
+            required: ["filePath"],
+        }),
+        execute: async (input) => {
+            const cwd = opts.cwd ?? process.cwd();
+            const { getOrCreateManager } = await import("../lsp/runtime.js");
+            return json(await getOrCreateManager(cwd).impactOfChange(input.filePath, input.query));
+        },
+    });
+    tools.lsp_mutation_preview = dynamicTool({
+        description: "Preview a mutation (stub — no real edits). Returns { op: 'allowlist', dryRunResult: { proposedEdits: [], " +
+            "tokenEstimate: 0 }, schemaVersion: '1.0' }. MUTATION_TOOLS gating applies; no apply path in Sprint 1.",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                filePath: { type: "string", description: "File path" },
+                change: { type: "string", description: "Change specification (stub)" },
+            },
+            required: ["filePath", "change"],
+        }),
+        execute: async (input) => {
+            const cwd = opts.cwd ?? process.cwd();
+            const { getOrCreateManager } = await import("../lsp/runtime.js");
+            return json(await getOrCreateManager(cwd).lspMutationPreview(input.filePath, input.change));
+        },
+    });
     // ── Onboarding: setup_guide ───────────────────────────────────────────────
     tools.setup_guide = dynamicTool({
         description: "Returns the up-to-date setup / install / first-run / MCP wiring / verify guide for muonroi-cli. Call this " +

package/dist/src/tools/registry.d.ts

@@ -6,6 +6,7 @@
  * is sent to the API for all providers (including DeepSeek, Gemini, etc.).
  */
 import { type ToolSet } from "ai";
+import type { AskUserAskInfo } from "../orchestrator/ask-user.js";
 import type { AgentMode, TaskRequest, ToolResult } from "../types/index.js";
 import type { BashTool } from "./bash.js";
 interface ToolRegistryOpts {
@@ -34,6 +35,22 @@ interface ToolRegistryOpts {
      */
     sessionId?: string;
     runDebate?: (topic: string) => Promise<string>;
+    /**
+     * When true, the `convene_council` tool is registered so the agent can
+     * convene the multi-model council on demand mid-turn. Set by the tool-engine
+     * only when the council is actually usable for this session
+     * (`configuredRoleCount >= getAutoCouncilMinRoles()`); omitted/false → the
+     * tool is absent so the model never calls a council that cannot convene.
+     */
+    councilConfigured?: boolean;
+    /**
+     * When provided, the `ask_user` tool is registered so the agent can ask the
+     * human a question mid-turn and receive their answer AS the tool result. The
+     * handler blocks until the human responds (or dismisses). Omitted (headless
+     * with no answerer) → the tool is absent, so the model never calls a card
+     * that can never be answered.
+     */
+    askUser?: (info: AskUserAskInfo) => Promise<string>;
 }
 /**
  * Phase 4R: session-scoped bash repeat detector state.

package/dist/src/tools/registry.js

@@ -8,6 +8,7 @@
 import { dynamicTool, jsonSchema } from "ai";
 import { registerGsdWorkflowTools } from "../gsd/workflow-tools.js";
 import { requestProactiveCompact } from "../orchestrator/compact-request.js";
+import { requestCouncilConvene } from "../orchestrator/council-request.js";
 import { canonicalizeBashCommand } from "../orchestrator/tool-args-hash.js";
 import { analyzeImageFromSource, askVisionProxy, listCachedImages } from "../providers/mcp-vision-bridge.js";
 import { needsVisionProxy } from "../providers/vision-proxy.js";
@@ -15,7 +16,7 @@ import { loadMcpServers } from "../utils/settings.js";
 import { getBashRun, sliceBashOutput } from "./bash-output-cache.js";
 import { editFile, readFile, readFiles, writeFile } from "./file.js";
 import { FileTracker } from "./file-tracker.js";
-import { analyzeGitCommand, checkPushGate, checkSensitiveStaging, commitBlockedMessage, pushBlockedMessage, recordCommandOutcome, } from "./git-safety.js";
+import { analyzeGitCommand, checkDestructiveOp, checkPushGate, checkSensitiveStaging, commitBlockedMessage, pushBlockedMessage, recordCommandOutcome, } from "./git-safety.js";
 import { executeGrep } from "./grep.js";
 import { registerNativeMuonroiTools } from "./native-tools.js";
 import { registerNativeResearchTools } from "./research.js";
@@ -168,6 +169,109 @@ export function createBuiltinTools(bash, mode, opts) {
             });
         },
     });
+    // convene_council — agent-initiated multi-model council. The model calls this
+    // when THIS request genuinely warrants a cross-provider debate (conflicting
+    // design tradeoffs, high-stakes decision). The request is queued here; the
+    // tool-engine consumes it from the outer restart loop, runs runCouncilV2 with
+    // convenePath:true (which suppresses ALL hardcoded post-debate decision
+    // surface — no card, no continuation), splices the synthesis into THIS tool's
+    // tool_result, and restarts the step so the model reads the conclusion as the
+    // result and continues. Registered only when the council is usable so the
+    // model never calls a council that cannot convene.
+    if (opts?.councilConfigured) {
+        tools.convene_council = dynamicTool({
+            description: "Convene the multi-model council to debate THIS request. Use ONLY when the task has genuinely conflicting design tradeoffs, needs a cross-provider/second-opinion review, or is a high-stakes architecture/analysis decision where a single model's view is insufficient. It runs a real multi-role debate across several models and returns a synthesized conclusion AS THIS TOOL'S RESULT. Do NOT use it for routine or low-ambiguity work — it is expensive. After calling, read the returned conclusion and continue; nothing is auto-decided for you.",
+            inputSchema: jsonSchema({
+                type: "object",
+                properties: {
+                    reason: {
+                        type: "string",
+                        description: "Why this task needs a multi-model debate (the specific tradeoff or decision at stake).",
+                    },
+                },
+            }),
+            execute: async (input, execOpts) => {
+                const reason = input && typeof input === "object" && typeof input.reason === "string"
+                    ? input.reason
+                    : null;
+                requestCouncilConvene(reason, execOpts?.toolCallId ?? null);
+                return formatResult({
+                    success: true,
+                    output: "Council convening — the multi-model debate runs now and its conclusion replaces this result before your next step. Read the conclusion, then continue.",
+                });
+            },
+        });
+    }
+    // ask_user — agent-initiated question to the human. The model calls this from
+    // its OWN judgment (e.g. after a convene_council conclusion, when it wants a
+    // go/no-go before implementing). The CLI does NOT synthesise options or decide
+    // the branch: question, options, and default all come from the model's input.
+    // execute() BLOCKS until the human answers; the answer becomes the tool result.
+    // Registered only when a UI answerer is wired (opts.askUser present).
+    if (opts?.askUser) {
+        const askUser = opts.askUser;
+        tools.ask_user = dynamicTool({
+            description: "Ask the human user a question and receive their answer AS THIS TOOL'S RESULT. Use when you need a decision, confirmation (e.g. 'proceed with implementation?'), or missing detail that only the user can provide — typically in an interactive discussion, or after a convene_council conclusion when you want a go/no-go before building. Supply the exact `question` and, optionally, `options` the user picks from (omit for a free-text answer). This BLOCKS until the user responds. Nothing is auto-decided: read their answer and continue from your own judgment. Do NOT use it to narrate or for rhetorical questions — only when you genuinely need input to proceed.",
+            inputSchema: jsonSchema({
+                type: "object",
+                properties: {
+                    question: {
+                        type: "string",
+                        description: "The exact question to put to the user.",
+                    },
+                    context: {
+                        type: "string",
+                        description: "Optional short context shown under the question.",
+                    },
+                    options: {
+                        type: "array",
+                        description: "Optional choices the user picks from. Omit for a free-text answer. These are YOUR options — the CLI adds none.",
+                        items: {
+                            type: "object",
+                            properties: {
+                                label: { type: "string", description: "The choice shown to the user." },
+                                description: { type: "string", description: "Optional one-line explanation of the choice." },
+                                value: { type: "string", description: "Optional value returned when picked (defaults to the label)." },
+                            },
+                            required: ["label"],
+                        },
+                    },
+                    defaultIndex: {
+                        type: "number",
+                        description: "Optional index into options for the pre-selected choice (defaults to 0 = first).",
+                    },
+                },
+                required: ["question"],
+            }),
+            execute: async (input) => {
+                const obj = (input && typeof input === "object" ? input : {});
+                const question = typeof obj.question === "string" ? obj.question : "";
+                if (question.trim().length === 0) {
+                    return formatResult({
+                        success: false,
+                        output: "ask_user requires a non-empty `question`.",
+                    });
+                }
+                const rawOptions = Array.isArray(obj.options) ? obj.options : [];
+                const options = rawOptions
+                    .filter((o) => !!o && typeof o === "object")
+                    .map((o) => ({
+                    label: typeof o.label === "string" ? o.label : String(o.label ?? ""),
+                    description: typeof o.description === "string" ? o.description : undefined,
+                    value: typeof o.value === "string" ? o.value : undefined,
+                }))
+                    .filter((o) => o.label.length > 0);
+                const info = {
+                    question,
+                    context: typeof obj.context === "string" ? obj.context : undefined,
+                    options: options.length > 0 ? options : undefined,
+                    defaultIndex: typeof obj.defaultIndex === "number" ? obj.defaultIndex : undefined,
+                };
+                const answer = await askUser(info);
+                return formatResult({ success: true, output: answer });
+            },
+        });
+    }
     // bash — every foreground call goes through here. We track the LAST
     // canonical command + runId in SESSION-SCOPED state so we can inject a
     // reminder when the model issues another bash call that canonicalizes to
@@ -265,6 +369,17 @@ export function createBuiltinTools(bash, mode, opts) {
             // motivation (session 18285908637a). gitSafetyKey is STABLE per process
             // (or the real sessionId) — unlike repeatKey, whose anon fallback changes
             // on every registry rebuild and would silently drop the gate across turns.
+            // Destructive-op guard (pre-execution, any permission mode): block a
+            // command that would irreversibly discard uncommitted work (git
+            // checkout --/restore/reset --hard/clean, git stash drop/clear, or rm of
+            // a tracked file) when there is actually work at risk. Routed as
+            // `destructive-revert` so the tool-engine shows the safety askcard
+            // interactively and hard-blocks headless (autonomous sub-agents) — the
+            // fix for the /ideal plan-adherence agent silently reverting user files.
+            const destructive = checkDestructiveOp(cmd, bash.getCwd());
+            if (destructive.blocked) {
+                return _prefixBlock("destructive-revert", destructive.message);
+            }
             const gitShape = analyzeGitCommand(cmd);
             // Hard-block broad staging when sensitive files are present.
             // This runs PRE-EXECUTION (before bash.execute) regardless of permission mode.

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

@@ -194,6 +194,13 @@ export interface ToolGroup {
     items: ToolGroupItem[];
     startedAt: number;
     finishedAt?: number;
+    /**
+     * True when this group was rebuilt from a persisted transcript rather than
+     * observed live (see ui/utils/group-tool-entries.ts). Its timestamps come
+     * from entry write-time, so the elapsed span is NOT a real measurement and
+     * must not be displayed as one.
+     */
+    restored?: boolean;
     inputTokens?: number;
     outputTokens?: number;
 }
@@ -225,7 +232,7 @@ export interface StructuredResponse {
     taskType: string;
     data: Record<string, unknown>;
 }
-export type CouncilQuestionPhase = "clarify" | "preflight" | "plan-confirm" | "post-debate" | "pil-interview" | "pil-acceptance" | "tool-loop-cap" | "safety-override";
+export type CouncilQuestionPhase = "clarify" | "preflight" | "plan-confirm" | "post-debate" | "pil-interview" | "pil-acceptance" | "tool-loop-cap" | "safety-override" | "ask-user";
 export type CouncilOptionKind = "choice" | "freetext" | "chat";
 export interface CouncilQuestionOption {
     label: string;
@@ -262,6 +269,17 @@ export interface CouncilStatusData {
     startedAt?: number;
     tokensIn?: number;
     tokensOut?: number;
+    /**
+     * Push-based stream liveness (additive, optional). `elapsedMs` alone cannot
+     * prove a council call is alive: the tick generator only advances when the
+     * CONSUMER pulls, so a round awaiting its pairs via Promise.all freezes it.
+     * These two come from the token stream itself — `streamedChars` counts text +
+     * reasoning deltas since the phase began, and `lastDeltaAgeMs` is the age of
+     * the most recent delta. Growing chars / small age = SLOW BUT ALIVE; static
+     * chars + growing age = genuinely STUCK.
+     */
+    streamedChars?: number;
+    lastDeltaAgeMs?: number;
     errorMessage?: string;
 }
 /** High-level lifecycle event for a council phase. Drives the phase timeline UI. */
@@ -433,6 +451,16 @@ export interface CouncilMessage {
     attempts?: number;
     failureReason?: string;
     runId?: string;
+    /**
+     * Wall-clock of THIS speaker's LLM call, including retries.
+     *
+     * Without it the only timed council rows are `debate_complete` (the whole
+     * debate, measured at 87s..1128s) and `council_summary` — aggregates that
+     * cannot say WHICH model burned the time, so every latency diagnosis is
+     * guesswork. Persisted to `interaction_logs.duration_ms` alongside the
+     * `speakerModel` this row already carries, making the bottleneck queryable.
+     */
+    durationMs?: number;
 }
 export interface StreamChunk {
     type: "content" | "tool_calls" | "tool_result" | "tool_approval_request" | "council_question" | "council_preflight" | "council_status" | "council_phase" | "council_message" | "council_info_card" | "council_meta" | "council_round" | "done" | "error" | "reasoning" | "structured_response" | "product_status_card" | "experience_warning" | "experience_injected" | "push_notification" | "halt" | "toast" | "task_list_update";