muonroi-cli 1.8.4 → 1.9.0

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

@@ -0,0 +1,176 @@
+/**
+ * src/council/debate-checkpoint.ts
+ *
+ * C (mid-debate checkpoint) — persist the CB-1 council debate's per-round state
+ * so a break mid-debate (provider 5xx on round 5, host crash, cap breach) can
+ * resume from the last completed round instead of re-running the whole debate.
+ *
+ * The debate accumulates all state in RAM (`exchangeLogs`, `active`,
+ * `runningSummary`, `archive`, convergence trackers). Without a checkpoint a
+ * break loses every round — a 5-round multi-provider debate must restart from
+ * round 1. This module owns the on-disk snapshot: `runDebate` writes it after
+ * each completed round and deletes it on normal completion; the resume path
+ * reads it and seeds `runDebate` so it skips research + openings + completed
+ * rounds.
+ *
+ * File: `<checkpointDir>/debate-checkpoint.json` (checkpointDir = the run dir,
+ * `.muonroi-flow/runs/<runId>`). Written atomically (tmp + rename) so a crash
+ * mid-write can never leave a half-JSON file.
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+/** Bump when the checkpoint shape changes incompatibly so stale files are ignored. */
+export const DEBATE_CHECKPOINT_VERSION = 1;
+export const DEBATE_CHECKPOINT_FILE = "debate-checkpoint.json";
+/** Build the serializable checkpoint payload from live debate state. */
+export function buildDebateCheckpoint(input) {
+    return {
+        version: DEBATE_CHECKPOINT_VERSION,
+        problemStatement: input.problemStatement,
+        participantModels: input.active.map((p) => p.model),
+        roundCount: input.roundCount,
+        maxRounds: input.maxRounds,
+        exchangeLogs: [...input.exchangeLogs.entries()].map(([k, v]) => [k, [...v]]),
+        runningSummary: input.runningSummary,
+        researchFindings: input.researchFindings,
+        active: input.active,
+        archive: input.archive,
+        lastCriteriaMet: [...input.lastCriteriaMet],
+        bestCriteriaMetCount: input.bestCriteriaMetCount,
+        roundsSinceProgress: input.roundsSinceProgress,
+        nextTopic: input.nextTopic,
+        savedAt: input.savedAt,
+    };
+}
+/** Rehydrate `exchangeLogs` from the serialized entry tuples. */
+export function restoreExchangeLogs(cp) {
+    return new Map(cp.exchangeLogs.map(([k, v]) => [k, [...v]]));
+}
+/**
+ * Whether `cp` describes the debate that is about to run. Guards against
+ * splicing a stale checkpoint (different question, re-resolved panel) into a
+ * fresh debate. Participant order is not significant; the model SET must match.
+ */
+export function checkpointMatches(cp, problemStatement, participantModels) {
+    if (cp.version !== DEBATE_CHECKPOINT_VERSION)
+        return false;
+    if (cp.roundCount < 1)
+        return false; // nothing useful to resume from
+    if (cp.problemStatement !== problemStatement)
+        return false;
+    const a = [...cp.participantModels].sort();
+    const b = [...participantModels].sort();
+    if (a.length !== b.length)
+        return false;
+    return a.every((m, i) => m === b[i]);
+}
+/**
+ * Atomically write the checkpoint to `<dir>/debate-checkpoint.json`.
+ * Non-fatal: a checkpoint write failure must never break the live debate — it
+ * only forfeits resumability for that round. Logs with context (No-Silent-Catch).
+ */
+export async function writeDebateCheckpoint(dir, cp) {
+    const finalPath = path.join(dir, DEBATE_CHECKPOINT_FILE);
+    const tmpPath = `${finalPath}.${process.pid}.tmp`;
+    try {
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(tmpPath, JSON.stringify(cp), "utf8");
+        await fs.rename(tmpPath, finalPath);
+    }
+    catch (err) {
+        console.error(`[debate-checkpoint] write failed (dir=${dir}, round=${cp.roundCount}): ${err?.message}`);
+        // Best-effort cleanup of the temp file; ignore if it never got created.
+        await fs.rm(tmpPath, { force: true }).catch(() => { });
+    }
+}
+/**
+ * Read + parse the checkpoint. Returns null when absent or unparseable (a
+ * corrupt checkpoint must not crash resume — the debate just runs fresh).
+ */
+export async function readDebateCheckpoint(dir) {
+    const finalPath = path.join(dir, DEBATE_CHECKPOINT_FILE);
+    let raw;
+    try {
+        raw = await fs.readFile(finalPath, "utf8");
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT") {
+            console.error(`[debate-checkpoint] read failed (dir=${dir}): ${err?.message}`);
+        }
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed?.version !== DEBATE_CHECKPOINT_VERSION)
+            return null;
+        return parsed;
+    }
+    catch (err) {
+        console.error(`[debate-checkpoint] parse failed (dir=${dir}): ${err?.message}`);
+        return null;
+    }
+}
+/**
+ * Delete the checkpoint (debate completed normally, or the run was aborted).
+ * Non-fatal — a leftover checkpoint is only re-validated (and discarded on
+ * mismatch) on the next resume, never silently mis-applied.
+ */
+export async function deleteDebateCheckpoint(dir) {
+    const finalPath = path.join(dir, DEBATE_CHECKPOINT_FILE);
+    try {
+        await fs.rm(finalPath, { force: true });
+    }
+    catch (err) {
+        console.error(`[debate-checkpoint] delete failed (dir=${dir}): ${err?.message}`);
+    }
+}
+// ── Debate inputs (C-v2 cross-session resume) ────────────────────────────────
+export const DEBATE_INPUTS_FILE = "debate-inputs.json";
+/** Atomically persist the debate inputs. Non-fatal on failure (forfeits cross-session resume only). */
+export async function writeDebateInputs(dir, inputs) {
+    const finalPath = path.join(dir, DEBATE_INPUTS_FILE);
+    const tmpPath = `${finalPath}.${process.pid}.tmp`;
+    try {
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(tmpPath, JSON.stringify(inputs), "utf8");
+        await fs.rename(tmpPath, finalPath);
+    }
+    catch (err) {
+        console.error(`[debate-checkpoint] inputs write failed (dir=${dir}): ${err?.message}`);
+        await fs.rm(tmpPath, { force: true }).catch(() => { });
+    }
+}
+/** Read the debate inputs. Returns null when absent/unparseable/version-mismatched. */
+export async function readDebateInputs(dir) {
+    const finalPath = path.join(dir, DEBATE_INPUTS_FILE);
+    let raw;
+    try {
+        raw = await fs.readFile(finalPath, "utf8");
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT") {
+            console.error(`[debate-checkpoint] inputs read failed (dir=${dir}): ${err?.message}`);
+        }
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed?.version !== DEBATE_CHECKPOINT_VERSION)
+            return null;
+        return parsed;
+    }
+    catch (err) {
+        console.error(`[debate-checkpoint] inputs parse failed (dir=${dir}): ${err?.message}`);
+        return null;
+    }
+}
+/** Delete the debate inputs (debate + scoping finished, or run aborted). Non-fatal. */
+export async function deleteDebateInputs(dir) {
+    try {
+        await fs.rm(path.join(dir, DEBATE_INPUTS_FILE), { force: true });
+    }
+    catch (err) {
+        console.error(`[debate-checkpoint] inputs delete failed (dir=${dir}): ${err?.message}`);
+    }
+}
+//# sourceMappingURL=debate-checkpoint.js.map

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

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { loadKeyForProvider } from "../providers/keychain.js";
 import { createProviderFactory, detectProviderForModel, resolveModelRuntime } from "../providers/runtime.js";
 import { withDeadlineRace, withTimeoutSignal } from "../utils/llm-deadline.js";
+import { logger } from "../utils/logger.js";
 import { getProviderStallTimeoutMs } from "../utils/settings.js";
 import { tracedGenerate } from "./llm.js";
 import { buildDebatePlanPrompt } from "./prompts.js";
@@ -94,6 +95,37 @@ function injectAuditorStance(plan, eeWarnings, experienceMode) {
     }
     return { ...plan, stances };
 }
+/**
+ * PIL task types whose deliverable is understanding/evaluation of something that
+ * already exists — never a build. The user asked to assess, not to implement.
+ */
+const ANALYSIS_TASK_TYPES = new Set(["analyze"]);
+function isAnalysisTaskType(taskType) {
+    return !!taskType && ANALYSIS_TASK_TYPES.has(taskType);
+}
+/**
+ * Deterministic backstop for post-debate drift (session c4f78752a316).
+ *
+ * PIL is the authoritative intent classifier. When it says the request is
+ * analysis/evaluation, the leader LLM must not be allowed to silently reshape the
+ * debate into an `implementation_plan` — that shape makes the post-debate AskCard
+ * default to "generate_plan" (build a plan) via pickPostDebateRecommendation,
+ * which is the wrong next step for a request that only wanted an assessment.
+ *
+ * The prompt already asks the leader to honor the intent (soft), but LLMs drift;
+ * this coerces a drifted shape back to "evaluation" so the synthesis stays the
+ * deliverable and the default action becomes save_exit. Non-implementation shapes
+ * are left untouched.
+ */
+function enforceAnalysisIntentShape(plan, taskType) {
+    if (!isAnalysisTaskType(taskType))
+        return plan;
+    if (plan.outputShape.kind !== "implementation_plan")
+        return plan;
+    logger.info("orchestrator", `[debate-planner] PIL taskType=${taskType} (analysis) but leader chose implementation_plan; ` +
+        "coercing outputShape.kind→evaluation to honor analysis intent");
+    return { ...plan, outputShape: { ...plan.outputShape, kind: "evaluation" } };
+}
 export async function* planDebate(spec, leaderModelId, llm, eeWarnings, // CQ-13: experience snippets to seed prompt
 experienceMode, // CQ-14: controls Experience Auditor injection
 taskType, // CQ-11: task type from PIL (e.g. "architecture", "bugfix")
@@ -101,6 +133,10 @@ complexityTier, // CQ-11: complexity tier from PIL (e.g. "heavy", "medium", "lig
 signal) {
     const eeSnippets = eeWarnings?.map((w) => w.text).filter(Boolean) ?? [];
     const { system: baseSystem, prompt } = buildDebatePlanPrompt(spec);
+    // Every return path funnels through here: auditor + product-stance injection,
+    // plus the deterministic analysis-intent backstop (applied first so a coerced
+    // shape doesn't get a spurious product stance injected for it).
+    const finalizePlan = (plan) => ensureProductStance(injectAuditorStance(enforceAnalysisIntentShape(plan, taskType), eeWarnings, experienceMode));
     // Build calibration context from PIL metadata
     const pilCalibration = [];
     if (taskType)
@@ -111,6 +147,18 @@ signal) {
     if (pilCalibration.length > 0) {
         system += `\n\n## Task Context (from PIL)\n${pilCalibration.join("\n")}`;
     }
+    // Hard intent lock (steers stances AND shape). PIL already classified this as
+    // analysis; the deterministic backstop in finalizePlan enforces it regardless,
+    // but steering the leader here keeps the whole roster/synthesis on-intent.
+    if (isAnalysisTaskType(taskType)) {
+        system +=
+            `\n\n## INTENT LOCK (authoritative)\n` +
+                `PIL classified this request as ANALYSIS/EVALUATION (taskType=${taskType}). The user wants to ` +
+                `understand and assess what ALREADY exists — not to build anything. ` +
+                `outputShape.kind MUST be "evaluation" or "investigation" — NEVER "implementation_plan". ` +
+                `Do NOT propose building, implementing, scaffolding, or "I'll spec that in vN". ` +
+                `Stances must be analyst/critic/investigator voices, not implementers.`;
+    }
     if (eeSnippets.length > 0) {
         system += `\n\n## Experience Warnings (from brain)\nNote these past mistakes when designing debate stances:\n${eeSnippets.map((s) => `- ${s}`).join("\n")}`;
     }
@@ -129,8 +177,9 @@ signal) {
     try {
         const providerId = detectProviderForModel(leaderModelId);
         const key = await loadKeyForProvider(providerId);
-        const { factory } = createProviderFactory(providerId, { apiKey: key });
-        const runtime = resolveModelRuntime(factory, leaderModelId);
+        // Registers the leader provider's factory so resolveModelRuntime can derive it.
+        createProviderFactory(providerId, { apiKey: key });
+        const runtime = resolveModelRuntime(leaderModelId);
         // Bound attempt-1: a wedged provider response here would freeze the whole
         // council/loop silently (no streamText stall watchdog covers generateObject).
         // On timeout this rejects → caught below → retry (guarded) → fallback plan.
@@ -158,7 +207,7 @@ signal) {
                 outputShape,
                 plannedRounds,
             };
-            return ensureProductStance(injectAuditorStance(plan, eeWarnings, experienceMode));
+            return finalizePlan(plan);
         }
         // Invalid even with schema — fall through to retry with a sanitize-failure message
         throw new Error("Sanitize check failed: stances.length < 2 or outputShape is null");
@@ -180,7 +229,7 @@ signal) {
             });
             const retryParsed = parsePlan(retryRaw);
             if (retryParsed)
-                return ensureProductStance(injectAuditorStance(retryParsed, eeWarnings, experienceMode));
+                return finalizePlan(retryParsed);
         }
         catch (retryErr) {
             yield {
@@ -190,7 +239,7 @@ signal) {
         }
     }
     // All attempts exhausted — return fallback
-    return ensureProductStance(injectAuditorStance(FALLBACK_PLAN, eeWarnings, experienceMode));
+    return finalizePlan(FALLBACK_PLAN);
 }
 function parsePlan(raw) {
     try {

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

@@ -0,0 +1,25 @@
+/**
+ * src/council/debate-summary.ts
+ *
+ * Fallback debate-summary synthesis.
+ *
+ * The /ideal research phase persists the debate into `research.md` +
+ * `delegations.md` from `DebateState.runningSummary`. But a debate that returns
+ * after opening statements (e.g. the leader routes straight to the preflight
+ * gate without evaluation rounds) leaves `runningSummary` empty — and the whole
+ * debate (opening positions, design/impl reasoning) was silently dropped from
+ * the canonical artifacts, surviving only in TUI scrollback.
+ *
+ * This builds a faithful fallback from the participants' latest positions
+ * (`active[]`), falling back to per-round archive excerpts, so the research
+ * artifact ALWAYS captures the debate. Pure + synchronous → unit-testable.
+ */
+import type { DebateState } from "./types.js";
+/**
+ * Return a markdown summary of the debate suitable for `research.md` /
+ * `delegations.md`. Prefers `state.runningSummary` when present; otherwise
+ * synthesizes one from `active[]` positions, then `archive[]` excerpts. Returns
+ * "" only when there is genuinely nothing to show (no summary, no positions, no
+ * archive) — callers keep their existing "(no summary produced)" placeholder.
+ */
+export declare function resolveDebateSummary(state: Pick<DebateState, "runningSummary" | "active" | "archive">): string;

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

@@ -0,0 +1,85 @@
+/**
+ * src/council/debate-summary.ts
+ *
+ * Fallback debate-summary synthesis.
+ *
+ * The /ideal research phase persists the debate into `research.md` +
+ * `delegations.md` from `DebateState.runningSummary`. But a debate that returns
+ * after opening statements (e.g. the leader routes straight to the preflight
+ * gate without evaluation rounds) leaves `runningSummary` empty — and the whole
+ * debate (opening positions, design/impl reasoning) was silently dropped from
+ * the canonical artifacts, surviving only in TUI scrollback.
+ *
+ * This builds a faithful fallback from the participants' latest positions
+ * (`active[]`), falling back to per-round archive excerpts, so the research
+ * artifact ALWAYS captures the debate. Pure + synchronous → unit-testable.
+ */
+/** Cap so the fallback can't balloon the artifact; per-position + overall. */
+const PER_POSITION_CHARS = 4000;
+const TOTAL_CHARS = 16000;
+/**
+ * Return a markdown summary of the debate suitable for `research.md` /
+ * `delegations.md`. Prefers `state.runningSummary` when present; otherwise
+ * synthesizes one from `active[]` positions, then `archive[]` excerpts. Returns
+ * "" only when there is genuinely nothing to show (no summary, no positions, no
+ * archive) — callers keep their existing "(no summary produced)" placeholder.
+ */
+export function resolveDebateSummary(state) {
+    const running = state.runningSummary?.trim();
+    if (running)
+        return running;
+    const fromPositions = summarizeFromActive(state.active);
+    if (fromPositions)
+        return fromPositions;
+    return summarizeFromArchive(state.archive);
+}
+function speakerLabel(role, stanceName) {
+    return stanceName?.trim() ? `${stanceName} (${role})` : role;
+}
+function summarizeFromActive(active) {
+    if (!Array.isArray(active) || active.length === 0)
+        return "";
+    const parts = [
+        "_(Synthesized from participants' final positions — the debate produced no running summary.)_",
+        "",
+    ];
+    let total = 0;
+    for (const p of active) {
+        const position = (p.position ?? "").trim();
+        if (!position)
+            continue;
+        const clipped = position.length > PER_POSITION_CHARS ? `${position.slice(0, PER_POSITION_CHARS)}…` : position;
+        const block = `### ${speakerLabel(p.role, p.stance?.name)}\n\n${clipped}`;
+        if (total + block.length > TOTAL_CHARS) {
+            parts.push("_(remaining positions truncated)_");
+            break;
+        }
+        parts.push(block, "");
+        total += block.length;
+    }
+    // Only the header + no real positions → nothing worth persisting.
+    return parts.length > 2 ? parts.join("\n").trimEnd() : "";
+}
+function summarizeFromArchive(archive) {
+    if (!Array.isArray(archive) || archive.length === 0)
+        return "";
+    const parts = [
+        "_(Synthesized from per-round debate excerpts — the debate produced no running summary.)_",
+        "",
+    ];
+    let total = 0;
+    for (const e of archive) {
+        const excerpt = (e.excerpt ?? "").trim();
+        if (!excerpt)
+            continue;
+        const block = `### Round ${e.round} — ${speakerLabel(e.role, e.stanceName)}\n\n${excerpt}`;
+        if (total + block.length > TOTAL_CHARS) {
+            parts.push("_(remaining excerpts truncated)_");
+            break;
+        }
+        parts.push(block, "");
+        total += block.length;
+    }
+    return parts.length > 2 ? parts.join("\n").trimEnd() : "";
+}
+//# sourceMappingURL=debate-summary.js.map

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

@@ -1,5 +1,5 @@
-import type { StreamChunk } from "../types/index.js";
-import type { ClarifiedSpec, CouncilConfig, CouncilLLM, DebateState } from "./types.js";
+import type { CouncilQuestionOption, StreamChunk } from "../types/index.js";
+import type { ClarifiedSpec, CouncilConfig, CouncilLLM, DebateStance, DebateState, IsolatedTaskRunner, QuestionResponder } from "./types.js";
 /**
  * Resolve the initial round budget + hard ceiling from the plan's output-shape kind
  * and the planner-proposed round count. Pure + exported for unit testing the cap.
@@ -9,5 +9,172 @@ export declare function resolveDebateRoundBudget(planKind: string | undefined, p
     effectiveCeiling: number;
     kindCapped: boolean;
 };
+export declare function researchWithFallback(llm: CouncilLLM, primaryModel: string, topic: string, conversationContext: string, signal: AbortSignal | undefined, traceCb: (t: string) => void, options: {
+    internetFirst?: boolean;
+}, fallbackPool: string[], runIsolatedTask?: IsolatedTaskRunner): Promise<string>;
 export declare function runDebate(spec: ClarifiedSpec, config: CouncilConfig, llm: CouncilLLM): AsyncGenerator<StreamChunk, DebateState, unknown>;
 export declare function evaluateResearchNeed(spec: ClarifiedSpec, leaderModelId: string, conversationContext: string, llm: CouncilLLM, costAware?: boolean): AsyncGenerator<StreamChunk, boolean, unknown>;
+/**
+ * F3b — robustly extract the leader-evaluation JSON object from a model's raw
+ * output. Replaces a greedy `/\{[\s\S]*\}/` match that could swallow prose,
+ * multiple objects, or a trailing partial object into an unparseable span.
+ *
+ * Strategy: strip code fences, then brace-scan and return the LAST fully
+ * balanced top-level `{…}` object (the eval schema is emitted last, after any
+ * chain-of-thought prose). Returns null only when no balanced object exists.
+ * Deterministic, no LLM call. Braces inside string values are rare in the
+ * machine-emitted eval payload; a real tokenizer would be overkill here.
+ */
+export declare function extractEvalJson(raw: string): string | null;
+/**
+ * Format a speaker list as newline-joined "Name — lens" rows for the composing
+ * placeholder (A: live debate preview). Prefers the concrete `focus`, falls back
+ * to the one-sentence `lens`, then to bare name. Dedups identical rows so a
+ * speaker in multiple pairs renders once. Returns undefined when nothing useful
+ * is available so the UI falls back to label-only.
+ */
+/**
+ * Project a leader evaluation's `criteriaStatus` onto the PINNED spec criteria,
+ * returning a boolean[] index-aligned to `pinned` (B2/B3). The eval prompt asks
+ * for one entry per criterion in order, so index alignment is the primary path;
+ * when the model drifts (wrong count/order) we fall back to a case-insensitive
+ * substring match either direction, defaulting unmatched criteria to not-met so
+ * a hallucinated "all met" never silently marks an untouched criterion done.
+ */
+export declare function alignCriteriaMet(pinned: string[], status: Array<{
+    criterion?: string;
+    met?: boolean;
+}>): boolean[];
+/**
+ * B5 leader-conductor visibility. Default ON; opt out with
+ * MUONROI_LEADER_CONDUCTOR=0 (fallback = pre-B5 behavior, no directive/verdict
+ * messages — keeps headless/legacy transcripts unchanged).
+ */
+export declare function leaderConductorEnabled(): boolean;
+/**
+ * B4 leader auto-remedy. When pinned criteria remain unmet at the round budget's
+ * end, the leader auto-extends toward them (up to the hard ceiling) instead of
+ * stopping at the initial plan — "done = all criteria met", ceiling is a managed
+ * budget. Default ON under the conductor; opt out with
+ * MUONROI_COUNCIL_AUTO_REMEDY=0 (fallback = only leader-requested extensions).
+ */
+export declare function leaderAutoRemedyEnabled(): boolean;
+/**
+ * #3 — grounding-verify pass. When a debate ends with weak evidence density
+ * (< GROUNDING_VERIFY_THRESHOLD, i.e. debaters barely tagged any [CONFIRMED]/
+ * [REFUTED] claims — the common case since each debater is capped at
+ * stepCountIs(2)), an isolated explore sub-agent verifies the load-bearing
+ * claims against the codebase and emits authoritative tags that raise the
+ * density metric council uses for confidence. Default ON when an isolated-task
+ * bridge is wired; opt out with MUONROI_COUNCIL_GROUNDING_VERIFY=0.
+ */
+export declare function groundingVerifyEnabled(): boolean;
+/**
+ * #3 — run an isolated explore sub-agent that fact-checks the debate's
+ * load-bearing claims and emits `[CONFIRMED via file:line]` / `[REFUTED via …]`
+ * tags (the exact shape `countCitations` recognises). Returns the tagged output
+ * on success, or "" on any failure (caller only folds it in when it actually
+ * raised the citation count).
+ */
+export declare function runGroundingVerify(runIsolatedTask: IsolatedTaskRunner, model: string, problemStatement: string, exchangeText: string, traceCb: (t: string) => void): Promise<string>;
+/**
+ * B4: does auto-remedy want to extend the budget this round? True while pinned
+ * criteria remain unmet AND progress is still being made (a new criterion was
+ * met within the last 2 rounds). A stuck debate (roundsSinceProgress ≥ 2) returns
+ * false so the ceiling isn't burned chasing a criterion that isn't moving.
+ */
+export declare function autoRemedyWantsExtend(pinnedUnmet: number, roundsSinceProgress: number): boolean;
+/**
+ * B4: the diagnostic closing-remedy line for a debate that ended with unmet
+ * pinned criteria — distinguishes a stuck criterion (needs evidence/rescope)
+ * from a genuine ceiling hit (needs a higher budget) from an ordinary early
+ * stop, so the leader's final word is an actionable next move, not a shrug.
+ */
+export declare function diagnoseUnmetRemedy(opts: {
+    stuck: boolean;
+    atCeiling: boolean;
+    effectiveCeiling: number;
+    roundsSinceProgress: number;
+}): string;
+/**
+ * B4 interactive escalation. When the debate is about to stop with pinned
+ * criteria unmet AND auto-remedy can't help (stuck / at ceiling), hand the
+ * decision to the user instead of silently synthesizing a partial outcome.
+ * Default ON under the conductor; opt out with MUONROI_COUNCIL_ESCALATE=0
+ * (fallback = diagnostic closing verdict only, no askcard).
+ */
+export declare function leaderEscalationEnabled(): boolean;
+/**
+ * B4: should we interrupt to ask the user at this stop boundary? True only when
+ * pinned criteria remain unmet AND the leader can no longer self-remedy — it is
+ * stuck (no progress for ≥2 rounds) or has hit the round ceiling. While progress
+ * is still being made under the ceiling, auto-remedy handles it silently and we
+ * don't nag the user.
+ */
+export declare function escalationWanted(opts: {
+    pinnedUnmet: number;
+    stuck: boolean;
+    atCeiling: boolean;
+}): boolean;
+/**
+ * B4: the three escalation choices. When the debate is already at the absolute
+ * safety ceiling, the "extend" option degrades to a disabled-looking accept
+ * (label says so) — we never let the user push past ABSOLUTE_MAX_ROUNDS.
+ */
+export declare function buildEscalationOptions(unmetCount: number, atAbsoluteMax: boolean): CouncilQuestionOption[];
+/**
+ * B4: emit the escalation askcard and resolve the user's choice. Yields the
+ * council_question chunk (rendered by the same consumer as clarifier/post-debate
+ * askcards), awaits the responder, echoes the choice, and returns the decision.
+ * `grantedRounds` is pre-computed here (bounded by ABSOLUTE_MAX_ROUNDS) so the
+ * caller only mutates loop state. Any unmatched / empty answer is treated as
+ * "accept" — never a silent hang.
+ */
+export declare function runEscalationPrompt(opts: {
+    respondToQuestion: QuestionResponder;
+    openCriteria: string[];
+    pinnedUnmet: number;
+    stuck: boolean;
+    atAbsoluteMax: boolean;
+    currentMax: number;
+}): AsyncGenerator<StreamChunk, {
+    action: "extend" | "accept" | "rescope";
+    grantedRounds: number;
+}, unknown>;
+/** One-line criterion label for directive/verdict bodies. */
+export declare function shortCriterion(c: string, max?: number): string;
+/**
+ * B5: build the leader's pre-round DIRECTIVE body — the round goal plus the
+ * criteria still unmet going into this round. `metSoFar` is the prior round's
+ * aligned criteriaMet (empty before round 1 → everything is unmet).
+ */
+export declare function buildLeaderDirective(round: number, criteria: string[], metSoFar: boolean[], focus?: string): string;
+/**
+ * B5: build the leader's post-round VERDICT body — per-criterion ✓/○ against the
+ * pinned outcome, the leader's reason, and the focus it hands to the next round.
+ */
+export declare function buildLeaderVerdict(criteria: string[], met: boolean[], reason: string, nextFocus?: string): string;
+export declare function formatSpeakerRoster(list: Array<{
+    stance?: DebateStance;
+    model: string;
+}>): string | undefined;
+export declare function countCitations(text: string): number;
+/**
+ * Evidence density = verified / (verified + unverified).
+ *
+ * Previous definition was `citations / total-sentences`, which fundamentally
+ * couldn't exceed ~0.05 because most debate sentences are not citable claims
+ * (opinions, transitions, questions). Session ea13da132dec hit "Low
+ * confidence 0.00" despite having 2 real [CONFIRMED via web_fetch] tags
+ * because they were drowned in ~700 sentences of debate prose.
+ *
+ * New definition only counts claims that participants explicitly FLAGGED as
+ * needing evidence — either by verifying them ([CONFIRMED]/[REFUTED]) or by
+ * marking them unverified ([UNVERIFIED:…]). This measures how much of the
+ * debate's own factual claim-tagging was actually backed up.
+ *
+ * If participants tagged zero claims, density is 0 — no evidence awareness
+ * shown, low confidence is correct. This biases participants (via the
+ * EVIDENCE_RULE prompt) to either verify or explicitly mark unverified.
+ */
+export declare function computeEvidenceDensity(text: string): number;