muonroi-cli 1.8.4 → 1.9.0

package/dist/src/pil/llm-classify.js

@@ -12,25 +12,140 @@
  * Cost target: <200 input tokens, <10 output tokens per call (~$0.0001 on
  * DeepSeek Flash). Timeout 2500ms — bails fast if the model stalls.
  */
+import { appendFileSync } from "node:fs";
 import { streamText } from "ai";
-import { getModelByTier, getModelInfo } from "../models/registry.js";
+import { getModelInfo, SWITCH_PROVIDER_ORDER } from "../models/registry.js";
 import { getProviderCapabilities } from "../providers/capabilities.js";
-import { resolveModelRuntime } from "../providers/runtime.js";
-const LLM_CLASSIFY_TIMEOUT_MS = 2500;
-// Reasoning models (grok-4.3, deepseek-v4-flash, gpt-5.x) spend their output
-// budget on reasoning tokens BEFORE any visible text. The legacy 16-token cap
-// was consumed entirely by reasoning → zero text-delta → parseResponse("") →
-// null → `llm=fail` on every borderline turn (observed 5/5 live grok sessions).
-// Give reasoning models a real ceiling so the 2-word answer streams back, and a
-// longer timeout because reasoning round-trips take seconds, not ~200ms.
-// The ceiling is a cap, not padding: the model still stops after two words, so a
-// generous headroom costs nothing when reasoning is short.
-const REASONING_CLASSIFY_TIMEOUT_MS = 8000;
-// Seven comma-separated words now (added <scope>,<lang>) — ~18-26 tokens worst
-// case ("documentation,balanced,task,report,standard,ecosystem,vietnamese").
-// 48 keeps headroom without padding (the model still stops after seven words).
-const NONREASONING_MAX_OUTPUT_TOKENS = 48;
+import { getConfiguredProviders, loadKeyForProvider, ProviderKeyMissingError } from "../providers/keychain.js";
+import { createProviderFactoryAsync, resolveModelRuntime } from "../providers/runtime.js";
+import { getRoutedModelByTier } from "../router/peak-hour.js";
+import { isProviderDisabled } from "../utils/settings.js";
+// Single flat classify ceiling for EVERY model. Harness-measured latency
+// (2026-07-15, grok-composer via OAuth, 7 samples) is 1045–1277ms — no tested
+// model (agentic balanced OR fast flash) approaches even the legacy 2.5s cap,
+// so a tier-scaled timeout was solving a non-existent latency problem: the
+// /ideal over-engineering root cause was NOT a timeout abort but grok-composer
+// ignoring the terse contract (it emits task-planning prose, never the 8-word
+// line → null → fail-open). The ceiling is a pure safety net: a healthy model
+// returns in <1.5s, so the headroom only bites a genuinely stuck call. Data-
+// driven off measurement, not an identity/tier proxy string.
+const CLASSIFY_TIMEOUT_MS = 8000;
+// Absolute wall-clock cap for the WHOLE classify (every candidate AND its
+// self-repair). Enforced via a shared deadline passed into attemptClassify, so
+// a run of dead/hanging keys — or one legitimately slow reasoning model —
+// degrades to fail-open in bounded time. Sized to fit a healthy reasoning fast
+// model twice over: deepseek-v4-flash measured 2026-07-15 answers a classify in
+// ~2–5s (with a valid key), so 10s leaves room for one candidate + a self-repair
+// before the deadline. A dead key ahead of it (auth-fails in ~0.2s) barely eats
+// the budget; only a genuinely hanging candidate consumes it.
+const CLASSIFY_TOTAL_BUDGET_MS = 10_000;
+// Floor for any single streamText attempt's own timeout, so a nearly-exhausted
+// deadline still gives a final candidate a real (if short) chance rather than an
+// instant abort.
+const CLASSIFY_MIN_ATTEMPT_MS = 1200;
+// Eight comma-separated words now (added <clarity>) — ~20-30 tokens worst case
+// ("documentation,balanced,task,report,standard,ecosystem,vietnamese,underspecified").
+// 56 keeps headroom without padding (the model still stops after eight words).
+const NONREASONING_MAX_OUTPUT_TOKENS = 56;
 const REASONING_MAX_OUTPUT_TOKENS = 2048;
+/**
+ * Compute the classify call budget from the resolved model's catalog metadata.
+ *
+ * TIMEOUT is a flat safety-net ceiling for all models — see CLASSIFY_TIMEOUT_MS.
+ * Measurement showed classify latency is provider-independent and well under
+ * the ceiling, so keying the timeout off `tier`/`reasoning` added no value and
+ * amounted to an identity-proxy soft-hardcode.
+ *
+ * MAX-OUTPUT scales with REASONING only: a reasoning model burns its output
+ * budget on reasoning tokens before any visible text, so it needs the room in
+ * tokens; a non-reasoning model emits the 8 words directly. This knob is real —
+ * it is the fix for reasoning models routing the verdict into the reasoning
+ * channel — and stays decoupled from the (now flat) timeout.
+ */
+export function classifierBudget(modelInfo) {
+    const isReasoning = modelInfo?.reasoning === true;
+    return {
+        isReasoning,
+        timeoutMs: CLASSIFY_TIMEOUT_MS,
+        maxOutputTokens: isReasoning ? REASONING_MAX_OUTPUT_TOKENS : NONREASONING_MAX_OUTPUT_TOKENS,
+    };
+}
+/**
+ * Session-scoped cache of cross-provider factories built for the throwaway
+ * classify. Keyed by provider so the OAuth-aware build (keychain read + token
+ * refresh) happens at most once per provider per process, not per turn.
+ */
+const crossFactoryCache = new Map();
+/** Test seam — clear the cross-provider factory cache between specs. */
+export function __resetClassifyFactoryCache() {
+    crossFactoryCache.clear();
+}
+/**
+ * Build (or reuse) a real factory for a DIFFERENT provider than the session's,
+ * so the throwaway classify can run on a keyed instruction-following model when
+ * the session provider has none. Mirrors the council's `resolveCouncilFactory`:
+ * `loadKeyForProvider` for API-key providers, falling back to
+ * `createProviderFactoryAsync` for OAuth-only providers (injects the bearer
+ * token). Failures degrade gracefully (logged, returns undefined → caller keeps
+ * the session model). Never throws.
+ */
+async function resolveCrossProviderClassifyFactory(providerId) {
+    const cached = crossFactoryCache.get(providerId);
+    if (cached)
+        return cached;
+    try {
+        let apiKey;
+        try {
+            apiKey = await loadKeyForProvider(providerId);
+        }
+        catch (err) {
+            if (!(err instanceof ProviderKeyMissingError))
+                throw err;
+            // OAuth-only provider — createProviderFactoryAsync injects the bearer token.
+        }
+        const { factory } = await createProviderFactoryAsync(providerId, apiKey ? { apiKey } : {});
+        crossFactoryCache.set(providerId, factory);
+        return factory;
+    }
+    catch (err) {
+        console.error(`[pil.llm-classify] cross-provider classify factory build failed for ${providerId}: ${err?.message}`);
+        return undefined;
+    }
+}
+/**
+ * Ordered list of keyed fast-tier models from providers OTHER than the session's,
+ * for the throwaway classify. Candidate order is the catalog's vendor-defined
+ * `switch_provider_order` (zero-hardcode), gated by `getConfiguredProviders`
+ * (the authoritative credential check — unifies API key / env / OAuth) and the
+ * user's disabled-provider setting. The caller tries them in order and falls
+ * through to the next on an auth/stream failure — so a configured-but-DEAD key
+ * (e.g. an expired deepseek key) doesn't strand the classify at fail-open.
+ * Empty when no other provider is configured with a fast tier → caller keeps the
+ * session model (status quo).
+ */
+async function pickCrossProviderClassifyModels(excludeProvider) {
+    let configured;
+    try {
+        configured = new Set(await getConfiguredProviders());
+    }
+    catch (err) {
+        console.error(`[pil.llm-classify] getConfiguredProviders failed for classify route: ${err?.message}`);
+        return [];
+    }
+    const out = [];
+    for (const p of SWITCH_PROVIDER_ORDER) {
+        if (p === excludeProvider)
+            continue;
+        if (isProviderDisabled(p))
+            continue;
+        if (!configured.has(p))
+            continue;
+        const m = getRoutedModelByTier("fast", p);
+        if (m && m.provider === p)
+            out.push({ modelId: m.id, providerId: p });
+    }
+    return out;
+}
 /**
  * Per-namespace shallow merge of providerOptions. The base already carries
  * factory-level defaults folded into the provider namespace (e.g. OAuth
@@ -85,8 +200,11 @@ const KNOWN_CLASSIFY_WORDS = new Set([
     "heavy",
     "ecosystem",
     "local",
+    "clear",
+    "underspecified",
 ]);
-const SYSTEM_PROMPT = "You classify user prompts for a coding assistant. Reply with ONE line of SEVEN lowercase words separated by commas: <taskType>,<style>,<intent>,<deliverable>,<depth>,<scope>,<lang>\n\n" +
+const SYSTEM_PROMPT = "You classify user prompts for a coding assistant. Reply with ONE line of EIGHT lowercase words separated by commas: <taskType>,<style>,<intent>,<deliverable>,<depth>,<scope>,<lang>,<clarity>\n\n" +
+    "The message may be preceded by a '[RECENT CONVERSATION]' block. Use it ONLY to resolve what a terse follow-up refers to (e.g. 'từ các phần đó', 'làm tiếp', 'debate mode đi', 'this one'); then classify the NEW message. Crucially, if the new message points back at heavy prior work, its depth is the depth of THAT work — a short sentence like 'ok debate these parts and plan improvements' is NOT quick just because it is short. Never classify the conversation block itself.\n\n" +
     "taskType ∈ { refactor | debug | plan | analyze | documentation | generate | general }\n" +
     "style ∈ { concise | balanced | detailed }\n" +
     "intent ∈ { task | chat } — 'chat' ONLY for a pure greeting, thanks, or acknowledgement with NO work request (e.g. 'hi', 'cảm ơn nhé', 'ok great'). EVERYTHING else is 'task', including questions about code or the CLI, 'are you done?', and requests to call a tool. When unsure, choose 'task'.\n" +
@@ -99,8 +217,12 @@ const SYSTEM_PROMPT = "You classify user prompts for a coding assistant. Reply w
     "- quick — a trivial single-shot change or a small direct answer: typo, rename one symbol, one-line edit, a quick lookup, 'what does X do'. No plan needed.\n" +
     "- standard — ordinary feature or bugfix touching a handful of files/functions; needs a short plan + a verify step, but no upfront research or user discussion.\n" +
     "- heavy — architectural, cross-cutting, multi-file/multi-module, a migration, 'redo/rebuild', a vague 'make it better', or a request with real unresolved design choices. Needs discussion + research + a checked plan before any code.\n" +
+    "  BREADTH decides heavy, NOT how clearly the steps are spelled out. A migration, vendoring an external dependency's code in-tree, or a rename/restructure that spans MANY files or modules is ALWAYS heavy — even when the plan is fully specified and it 'just' has to keep tests green. Do not downgrade a wide change to standard because it sounds mechanical.\n" +
     "  For a pure question/answer (deliverable=answer), depth reflects how much investigation the answer needs: 'quick' for a simple fact, 'standard' for a normal explanation, 'heavy' for a deep architectural review.\n" +
     "  When unsure between quick and standard, choose standard. When the task is genuinely wide or ambiguous, choose heavy.\n" +
+    "clarity ∈ { clear | underspecified } — whether the request gives enough to proceed WITHOUT guessing:\n" +
+    "- underspecified — missing information the agent would need: an unstated target/scope ('add auth' — which flow?), a vague 'make it better' with no direction, competing interpretations, or an unresolved design choice. Such a task should be clarified with the user before code.\n" +
+    "- clear — well-specified enough to plan and execute directly, even if large. A fully-spelled-out migration is 'clear'. When unsure, choose 'clear' (do NOT over-ask on ordinary work).\n" +
     "scope ∈ { ecosystem | local }:\n" +
     "- ecosystem — the turn is about the Muonroi PLATFORM as a whole: the building-block / .NET packages, open-core boundary, the rule engine / decision tables, NuGet packages, or platform setup/install. These are documented in an authoritative docs source.\n" +
     "- local — EVERYTHING else, including questions about this CLI's own internals (even when they mention the word 'muonroi'). When unsure, choose local.\n" +
@@ -129,21 +251,29 @@ const SYSTEM_PROMPT = "You classify user prompts for a coding assistant. Reply w
     "- documentation → balanced (examples + explanation)\n" +
     "- general → concise\n" +
     "Only output 'detailed' if the user prompt LITERALLY contains words like 'explain in detail', 'thorough analysis', 'walk me through', 'giải thích chi tiết', 'phân tích kỹ'.\n\n" +
-    "Full examples (taskType,style,intent,deliverable,depth,scope,lang):\n" +
-    "- 'hi' → general,concise,chat,answer,quick,local,english\n" +
-    "- 'cảm ơn bạn nhé' → general,concise,chat,answer,quick,local,vietnamese\n" +
-    "- 'bạn xong chưa' → general,concise,task,answer,quick,local,vietnamese (a question — NOT chat)\n" +
-    "- 'fix the typo in the README title' → generate,concise,task,code,quick,local,english\n" +
-    "- 'fix CI failing on Windows' → debug,concise,task,code,standard,local,english\n" +
-    "- 'rename function shouldInject to needsReminder' → refactor,concise,task,code,quick,local,english\n" +
-    "- 'thêm caching cho provider layer và update tests' → generate,concise,task,code,standard,local,vietnamese\n" +
-    "- 'tại sao bash_output_get trả empty' → analyze,concise,task,answer,standard,local,vietnamese\n" +
-    "- 'liệt kê tất cả env var CLI đọc' → analyze,concise,task,report,standard,local,vietnamese\n" +
-    "- 'refactor the entire auth system to use OAuth' → refactor,concise,task,code,heavy,local,english\n" +
-    "- 'how does the building-block rule engine work' → analyze,concise,task,answer,standard,ecosystem,english\n" +
-    "- 'hệ sinh thái muonroi gồm những gì' → analyze,balanced,task,answer,standard,ecosystem,vietnamese\n" +
-    "- 'plan the migration to hooks' → plan,balanced,task,report,heavy,local,english\n\n" +
-    "Prompts may be Vietnamese, English, or mixed. Reply with exactly seven words separated by commas. No other text.";
+    "Full examples (taskType,style,intent,deliverable,depth,scope,lang,clarity):\n" +
+    "- 'hi' → general,concise,chat,answer,quick,local,english,clear\n" +
+    "- 'cảm ơn bạn nhé' → general,concise,chat,answer,quick,local,vietnamese,clear\n" +
+    "- 'bạn xong chưa' → general,concise,task,answer,quick,local,vietnamese,clear (a question — NOT chat)\n" +
+    "- 'fix the typo in the README title' → generate,concise,task,code,quick,local,english,clear\n" +
+    "- 'fix CI failing on Windows' → debug,concise,task,code,standard,local,english,clear\n" +
+    "- 'rename function shouldInject to needsReminder' → refactor,concise,task,code,quick,local,english,clear\n" +
+    "- 'thêm caching cho provider layer và update tests' → generate,concise,task,code,standard,local,vietnamese,clear\n" +
+    "- 'tại sao bash_output_get trả empty' → analyze,concise,task,answer,standard,local,vietnamese,clear\n" +
+    "- 'liệt kê tất cả env var CLI đọc' → analyze,concise,task,report,standard,local,vietnamese,clear\n" +
+    "- 'refactor the entire auth system to use OAuth' → refactor,concise,task,code,heavy,local,english,clear\n" +
+    "- 'vendor the used subset of the gsd package natively into src and rename gsd to workflow, keep tests green' → refactor,concise,task,code,heavy,local,english,clear (a migration spanning many files — heavy even though fully specified)\n" +
+    "- 'add auth' → generate,concise,task,code,standard,local,english,underspecified (which flow/provider? unstated)\n" +
+    "- 'làm cho CLI tốt hơn' → generate,concise,task,code,heavy,local,vietnamese,underspecified (vague 'make it better', no target)\n" +
+    "- 'how does the building-block rule engine work' → analyze,concise,task,answer,standard,ecosystem,english,clear\n" +
+    "- 'hệ sinh thái muonroi gồm những gì' → analyze,balanced,task,answer,standard,ecosystem,vietnamese,clear\n" +
+    "- 'plan the migration to hooks' → plan,balanced,task,report,heavy,local,english,clear\n\n" +
+    "Prompts may be Vietnamese, English, or mixed. Reply with exactly eight words separated by commas. No other text.";
+// Appended to SYSTEM_PROMPT on the self-repair retry (see createLlmClassifier).
+// The first attempt produced an unparseable reply; this reminder + the full
+// (untrimmed) prompt is the agent-first recovery the design mandates INSTEAD of
+// a keyword-regex fallback.
+const CLASSIFY_REPAIR_INSTRUCTION = "REPAIR MODE: your previous reply could NOT be parsed. Output NOTHING except the single line of eight lowercase words separated by commas — no prose, no explanation, no code fences, no quotes. If you are unsure of a field, pick the safe default (task, standard, clear, local).";
 function parseResponse(raw) {
     const cleaned = raw.trim().toLowerCase().replace(/[`*"]/g, "");
     const firstLine = cleaned.split(/\r?\n/)[0] ?? "";
@@ -177,6 +307,12 @@ function parseResponse(raw) {
     // anything else (incl. absent) → not ecosystem. Position-independent.
     const scopeWord = parts.find((p) => p === "ecosystem" || p === "local");
     const ecosystemScope = scopeWord ? scopeWord === "ecosystem" : null;
+    // Eighth word is the clarity signal. "underspecified" → the request is missing
+    // information the agent needs → earn a clarify/council pass. Anything else
+    // (incl. absent) → not underspecified (don't-over-ask safe direction).
+    // Position-independent so a reordered/garbled reply still recovers it.
+    const clarityWord = parts.find((p) => p === "clear" || p === "underspecified");
+    const needsClarification = clarityWord ? clarityWord === "underspecified" : null;
     // Seventh word is the user's language. It is the one alphabetic token that is
     // NOT a known enum value (open vocabulary). null when English / absent so
     // Layer 4 skips the language re-anchor for English turns.
@@ -191,6 +327,7 @@ function parseResponse(raw) {
         intentKind,
         deliverableKind,
         depthTier,
+        needsClarification,
         ecosystemScope,
         replyLanguage,
     };
@@ -202,26 +339,64 @@ function parseResponse(raw) {
  * Returns null if the call fails / times out / parses to garbage. Callers must
  * fail-open (keep prior taskType, do not block the turn).
  */
-export function createLlmClassifier(factory, modelId) {
-    return async function classify(prompt, signal) {
-        const controller = new AbortController();
-        let timer;
-        try {
-            const runtime = resolveModelRuntime(factory, modelId);
-            const isReasoning = runtime.modelInfo?.reasoning === true;
-            // Budget + timeout scale with reasoning: a reasoning model needs room and
-            // time to emit reasoning THEN the answer; a plain model answers in <16
-            // tokens almost instantly.
-            timer = setTimeout(() => controller.abort(), isReasoning ? REASONING_CLASSIFY_TIMEOUT_MS : LLM_CLASSIFY_TIMEOUT_MS);
-            const combinedSignal = signal
-                ? (AbortSignal.any?.([signal, controller.signal]) ?? controller.signal)
-                : controller.signal;
+/**
+ * Order the classify candidate list.
+ *
+ * - `hasSameFast` (e.g. openai → gpt-5.4-mini): the same-provider fast tier is a
+ *   real fast model, so try it FIRST, then keyed cross-provider models as a
+ *   FALLBACK. This is the fix for the failure-not-just-absence case: an
+ *   openai-OAuth session's fast tier can 401 on the api-key path — previously
+ *   the chain stopped there and fail-opened to "standard" (so /ideal
+ *   over-councilled trivial tasks). Appending the cross-provider models lets a
+ *   working alternative (a keyed deepseek/opencode fast model) rescue it.
+ * - No same-provider fast tier (e.g. xai, whose session model is agentic and
+ *   ignores the terse contract): try keyed cross-provider fast models FIRST and
+ *   keep the session model as the last-resort candidate.
+ */
+export function orderClassifyCandidates(args) {
+    const candidates = [];
+    if (args.hasSameFast) {
+        candidates.push({ modelId: args.primaryModelId, providerId: null });
+        for (const m of args.crossModels)
+            candidates.push({ modelId: m.modelId, providerId: m.providerId });
+    }
+    else {
+        for (const m of args.crossModels)
+            candidates.push({ modelId: m.modelId, providerId: m.providerId });
+        candidates.push({ modelId: args.primaryModelId, providerId: null });
+    }
+    return candidates;
+}
+export function createLlmClassifier(modelId, classifyOpts) {
+    return async function classify(prompt, opts) {
+        const signal = opts?.signal;
+        const recentTurns = opts?.recentTurns;
+        const debug = process.env.MUONROI_DEBUG_PIL_CLASSIFY === "1";
+        // Bounded recent-conversation block so the classifier can resolve back-
+        // references in a terse follow-up ("từ các phần đó", "làm tiếp", "this")
+        // instead of scoring the isolated sentence. Same for every candidate.
+        const trimmedRecent = recentTurns?.trim();
+        const promptWithContext = trimmedRecent
+            ? `[RECENT CONVERSATION — reference only, do NOT classify this]\n${trimmedRecent.slice(0, 800)}\n\n` +
+                `[NEW USER MESSAGE — classify THIS; if it refers back to the conversation above, judge the depth of the work it actually entails]\n${prompt.slice(0, 600)}`
+            : prompt.slice(0, 600);
+        const fullRecent = recentTurns?.trim();
+        const repairPrompt = (fullRecent
+            ? `[RECENT CONVERSATION — reference only, do NOT classify this]\n${fullRecent.slice(0, 1500)}\n\n`
+            : "") + `[NEW USER MESSAGE — classify THIS]\n${prompt.slice(0, 1500)}`;
+        // One classify attempt against a single resolved model, including the
+        // self-repair retry on that same model. Returns the parsed verdict, or null
+        // (unparseable OR provider/stream error) so the caller can fall through to
+        // the next candidate. Each attempt owns its AbortController/timer.
+        const attemptClassify = async (runtime, cmId, deadlineMs) => {
+            // Max-output scales with reasoning; each streamText timeout is bounded by
+            // the shared deadline (min of the flat ceiling and the time left), so the
+            // whole classify — this attempt AND its repair — never overruns the budget.
+            const { isReasoning } = classifierBudget(runtime.modelInfo);
+            const timeoutMs = Math.max(CLASSIFY_MIN_ATTEMPT_MS, Math.min(CLASSIFY_TIMEOUT_MS, deadlineMs - Date.now()));
             const dropMaxTokens = runtime.unsupportedParams?.includes("maxOutputTokens") === true;
             const maxOut = isReasoning ? REASONING_MAX_OUTPUT_TOKENS : NONREASONING_MAX_OUTPUT_TOKENS;
-            // Minimize reasoning cost: force the lowest effort the provider exposes for
-            // this throwaway 2-word classification. Only providers with
-            // `supportsReasoningEffort` (openai, xai) honor it; deepseek has no per-call
-            // knob (disable via MUONROI_DEEPSEEK_DISABLE_THINKING at the factory).
+            // Minimize reasoning cost: force the lowest effort the provider exposes.
             let providerOptions = runtime.providerOptions;
             if (isReasoning && runtime.modelInfo?.supportsReasoningEffort && runtime.modelInfo.provider) {
                 const lowEffort = getProviderCapabilities(runtime.modelInfo.provider).buildProviderOptions({
@@ -230,34 +405,186 @@ export function createLlmClassifier(factory, modelId) {
                 });
                 providerOptions = mergeProviderOptions(runtime.providerOptions, lowEffort);
             }
-            const result = streamText({
-                model: runtime.model,
-                abortSignal: combinedSignal,
-                system: SYSTEM_PROMPT,
-                prompt: prompt.slice(0, 600),
-                ...(dropMaxTokens ? {} : { maxOutputTokens: maxOut }),
-                ...(providerOptions ? { providerOptions } : {}),
-            });
-            let text = "";
-            let reasoningText = "";
-            const partCounts = {};
-            const debug = process.env.MUONROI_DEBUG_PIL_CLASSIFY === "1";
-            for await (const part of result.fullStream) {
-                if (debug)
-                    partCounts[part.type] = (partCounts[part.type] ?? 0) + 1;
-                if (part.type === "text-delta")
-                    text += part.textDelta ?? part.text ?? "";
-                else if (part.type === "reasoning-delta")
-                    reasoningText += part.textDelta ?? part.text ?? "";
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            const combinedSignal = signal
+                ? (AbortSignal.any?.([signal, controller.signal]) ?? controller.signal)
+                : controller.signal;
+            try {
+                const t0 = Date.now();
+                const result = streamText({
+                    model: runtime.model,
+                    abortSignal: combinedSignal,
+                    system: SYSTEM_PROMPT,
+                    prompt: promptWithContext,
+                    ...(dropMaxTokens ? {} : { maxOutputTokens: maxOut }),
+                    ...(providerOptions ? { providerOptions } : {}),
+                });
+                let text = "";
+                let reasoningText = "";
+                let streamError = "";
+                const partCounts = {};
+                for await (const part of result.fullStream) {
+                    if (debug)
+                        partCounts[part.type] = (partCounts[part.type] ?? 0) + 1;
+                    if (part.type === "text-delta")
+                        text += part.textDelta ?? part.text ?? "";
+                    else if (part.type === "reasoning-delta")
+                        reasoningText += part.textDelta ?? part.text ?? "";
+                    else if (part.type === "error") {
+                        const e = part.error;
+                        streamError = e instanceof Error ? e.message : String(e ?? "unknown");
+                    }
+                }
+                const elapsedMs = Date.now() - t0;
+                if (debug) {
+                    console.error(`[pil.llm-classify] raw(${cmId}${cmId !== modelId ? `←${modelId}` : ""}) ` +
+                        `maxOut=${dropMaxTokens ? "dropped" : maxOut} streamError=${JSON.stringify(streamError)} ` +
+                        `parts=${JSON.stringify(partCounts)} text<<<${text}>>> reasoning<<<${reasoningText.slice(0, 200)}>>>`);
+                }
+                // Reasoning models occasionally route the entire answer into reasoning
+                // parts (no committed text). Fall back to the reasoning channel.
+                let parsed = parseResponse(text) ?? (reasoningText ? parseResponse(reasoningText) : null);
+                // Metrics-only probe sink (env-gated): latency + parsed depth + any
+                // stream error. NO prompt/response content — safe to leave wired.
+                const probeLog = process.env.MUONROI_CLASSIFY_LATENCY_LOG;
+                if (probeLog) {
+                    try {
+                        appendFileSync(probeLog, `${JSON.stringify({
+                            model: cmId,
+                            from: modelId === cmId ? undefined : modelId,
+                            tier: runtime.modelInfo?.tier,
+                            reasoning: isReasoning,
+                            timeoutMs,
+                            elapsedMs,
+                            textLen: text.length,
+                            reasoningLen: reasoningText.length,
+                            parsed: parsed != null,
+                            depth: parsed?.depthTier ?? null,
+                            streamError: streamError || undefined,
+                        })}\n`);
+                    }
+                    catch (e) {
+                        console.error(`[pil.llm-classify] probe-log write failed: ${e?.message}`);
+                    }
+                }
+                if (parsed)
+                    return parsed;
+                // Surface a swallowed provider/transport error (No-Silent-Catch): a
+                // stream `error` part means the call FAILED (auth/key/rate-limit), which
+                // is categorically different from unparseable text. Before this fix such
+                // errors vanished into a silent null → fail-open "standard". On error we
+                // skip the same-model self-repair (it would fail identically) and let the
+                // caller fall through to the next provider candidate.
+                if (streamError) {
+                    console.error(`[pil.llm-classify] stream error on ${cmId} (from ${modelId}): ${streamError} — trying next candidate`);
+                    return null;
+                }
+                // Self-repair (agent-first recovery — NOT a regex fallback): the reply
+                // did not parse. Call the SAME model once more with the full prompt + an
+                // explicit format-repair instruction on a doubled budget. Skip it when
+                // too little of the shared deadline remains (the caller then falls
+                // through to the next candidate / fails open).
+                clearTimeout(timer);
+                const repairBudget = deadlineMs - Date.now();
+                if (repairBudget < 1500)
+                    return null;
+                const repairTimeout = Math.max(CLASSIFY_MIN_ATTEMPT_MS, Math.min(CLASSIFY_TIMEOUT_MS, repairBudget));
+                const repairController = new AbortController();
+                const repairTimer = setTimeout(() => repairController.abort(), repairTimeout);
+                const repairSignal = signal
+                    ? (AbortSignal.any?.([signal, repairController.signal]) ?? repairController.signal)
+                    : repairController.signal;
+                try {
+                    const repairRun = streamText({
+                        model: runtime.model,
+                        abortSignal: repairSignal,
+                        system: `${SYSTEM_PROMPT}\n\n${CLASSIFY_REPAIR_INSTRUCTION}`,
+                        prompt: repairPrompt,
+                        ...(dropMaxTokens ? {} : { maxOutputTokens: maxOut * 2 }),
+                        ...(providerOptions ? { providerOptions } : {}),
+                    });
+                    let rt = "";
+                    let rr = "";
+                    for await (const part of repairRun.fullStream) {
+                        if (part.type === "text-delta")
+                            rt += part.textDelta ?? part.text ?? "";
+                        else if (part.type === "reasoning-delta")
+                            rr += part.textDelta ?? part.text ?? "";
+                    }
+                    parsed = parseResponse(rt) ?? (rr ? parseResponse(rr) : null);
+                    if (parsed)
+                        console.error(`[pil.llm-classify] self-repair recovered classification (${cmId})`);
+                    return parsed;
+                }
+                finally {
+                    clearTimeout(repairTimer);
+                }
+            }
+            catch (err) {
+                console.error(`[pil.llm-classify] classify attempt failed on ${cmId}: ${err?.message}`, {
+                    stack: err?.stack?.split("\n").slice(0, 3),
+                });
+                return null;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        };
+        try {
+            // Build the ordered candidate list. Primary = same-provider fast tier (or
+            // the session model); on NO same-provider fast tier (e.g. xai) append keyed
+            // cross-provider fast models. Measured 2026-07-15: an agentic session model
+            // (grok-composer) ignores the terse contract and emits task-planning prose
+            // → null → fail-open "standard" (the /ideal over-engineering root cause);
+            // and a configured-but-dead key (expired deepseek) errors. Trying
+            // candidates in order until one parses fixes both.
+            let candidates = [];
+            const provider = getModelInfo(modelId)?.provider;
+            let primaryModelId = modelId;
+            if (classifyOpts?.routeFastTier) {
+                const sameFast = provider ? getRoutedModelByTier("fast", provider) : undefined;
+                if (sameFast && sameFast.id !== modelId)
+                    primaryModelId = sameFast.id;
+                // Cross-provider models are a FALLBACK appended whenever crossProviderFallback
+                // is set — NOT only when the session provider lacks a fast tier. Measured
+                // 2026-07-16: an openai-OAuth session's fast tier (gpt-5.4-mini) 401s on the
+                // api-key path; with the old absence-only gate the chain had no fallback and
+                // fail-opened to "standard", so /ideal over-councilled trivial tasks. Ordering
+                // (same-fast-first vs cross-first) is decided by orderClassifyCandidates.
+                const crossModels = classifyOpts?.crossProviderFallback && provider ? await pickCrossProviderClassifyModels(provider) : [];
+                candidates = orderClassifyCandidates({ primaryModelId, hasSameFast: !!sameFast, crossModels });
             }
-            if (debug) {
-                console.error(`[pil.llm-classify] raw(${modelId}) maxOut=${dropMaxTokens ? "dropped" : maxOut} ` +
-                    `parts=${JSON.stringify(partCounts)} text<<<${text}>>> reasoning<<<${reasoningText.slice(0, 200)}>>>`);
+            else {
+                candidates.push({ modelId: primaryModelId, providerId: null });
             }
-            // Reasoning models occasionally route the entire answer into reasoning
-            // parts (no committed text). Fall back to the reasoning channel so the
-            // 2-word verdict is still recoverable.
-            return parseResponse(text) ?? (reasoningText ? parseResponse(reasoningText) : null);
+            // Shared absolute deadline bounds the whole chain (each attempt + its
+            // repair). A lone same-provider candidate (the common case) simply gets
+            // the full flat ceiling within it.
+            const chainDeadline = Date.now() + CLASSIFY_TOTAL_BUDGET_MS;
+            for (const cand of candidates) {
+                if (chainDeadline - Date.now() < 750)
+                    break; // too little left → fail-open
+                // A cross-provider candidate's factory must exist in the registry before
+                // resolveModelRuntime can derive it — the session only ever warmed its
+                // own. A provider we cannot build (no key, no OAuth) simply drops out.
+                if (cand.providerId && !(await resolveCrossProviderClassifyFactory(cand.providerId)))
+                    continue;
+                let runtime;
+                try {
+                    runtime = resolveModelRuntime(cand.modelId);
+                }
+                catch (e) {
+                    console.error(`[pil.llm-classify] resolveModelRuntime failed for ${cand.modelId}: ${e?.message}`);
+                    continue;
+                }
+                const res = await attemptClassify(runtime, cand.modelId, chainDeadline);
+                if (res)
+                    return res;
+            }
+            console.error(`[pil.llm-classify] all ${candidates.length} candidate(s) failed — surfacing UNKNOWN, NO regex fallback. ` +
+                `rawPreview=${JSON.stringify(prompt.slice(0, 120))}`);
+            return null;
         }
         catch (err) {
             console.error(`[pil.llm-classify] classify failed: ${err?.message}`, {
@@ -266,112 +593,8 @@ export function createLlmClassifier(factory, modelId) {
             });
             return null;
         }
-        finally {
-            if (timer)
-                clearTimeout(timer);
-        }
     };
 }
-export function classifySubSessionActionHeuristic(prompt) {
-    const trimmed = prompt.trim().toLowerCase();
-    if (!trimmed)
-        return null;
-    // Strip trailing punctuation for list-based matching so "hello!" and "cảm ơn!"
-    // still hit the static lists instead of falling through to the LLM classifier.
-    const stripped = trimmed.replace(/[!?.…,;:]+$/g, "").trim();
-    // 1. Simple math equations (exact matches like "2+2", "1 + 1")
-    if (/^\d+\s*[+\-*/]\s*\d+$/.test(trimmed)) {
-        return {
-            action: "DIRECT_ANSWER",
-            confidence: 0.99,
-            reason: "Obvious input classified via heuristic (simple math)",
-        };
-    }
-    // 2. Greetings (exact matches only, trailing punctuation stripped)
-    const greetings = [
-        "hi",
-        "hello",
-        "hey",
-        "chào",
-        "xin chào",
-        "hi there",
-        "hello there",
-        "chào bạn",
-        "halo",
-        "hola",
-        "bạn ơi",
-    ];
-    if (greetings.includes(stripped)) {
-        return {
-            action: "DIRECT_ANSWER",
-            confidence: 0.99,
-            reason: "Obvious input classified via heuristic (greeting)",
-        };
-    }
-    // 3. Thanks (exact matches only, trailing punctuation stripped)
-    const thanks = [
-        "thanks",
-        "thank you",
-        "cảm ơn",
-        "cám ơn",
-        "thank",
-        "thx",
-        "ty",
-        "cảm ơn bạn",
-        "cám ơn bạn",
-        "cảm ơn nhé",
-        "cám ơn nhé",
-    ];
-    if (thanks.includes(stripped)) {
-        return {
-            action: "DIRECT_ANSWER",
-            confidence: 0.99,
-            reason: "Obvious input classified via heuristic (thanks)",
-        };
-    }
-    // 4. Help (exact matches only, trailing punctuation stripped)
-    const help = ["help", "hướng dẫn", "cứu", "help me"];
-    if (help.includes(stripped)) {
-        return {
-            action: "DIRECT_ANSWER",
-            confidence: 0.99,
-            reason: "Obvious input classified via heuristic (help)",
-        };
-    }
-    // 5. Short conversational words / acknowledgements (exact matches only, trailing punctuation stripped)
-    const conversation = [
-        "ok",
-        "okay",
-        "yes",
-        "no",
-        "vâng",
-        "dạ",
-        "ừ",
-        "chắc thế",
-        "ừm",
-        "umm",
-        "cool",
-        "nice",
-        "perfect",
-        "done",
-        "xong",
-        "yep",
-        "yup",
-        "nah",
-        "fine",
-        "tốt",
-        "được",
-        "okie",
-    ];
-    if (conversation.includes(stripped)) {
-        return {
-            action: "DIRECT_ANSWER",
-            confidence: 0.99,
-            reason: "Obvious input classified via heuristic (acknowledgement)",
-        };
-    }
-    return null;
-}
 const ROUTER_SYSTEM_PROMPT = "You are a routing controller for an AI coding agent. Your goal is to decide the execution strategy for the user's prompt based on the conversation history and metadata.\n\n" +
     "Analyze the user's prompt and select one of the following ACTIONS:\n" +
     '- "DIRECT_ANSWER": The prompt is informational, a quick question, a code review, an explanation, greeting, or thanks. No file creation/modification, test execution, or multi-turn tool runs are needed.\n' +
@@ -385,23 +608,27 @@ const ROUTER_SYSTEM_PROMPT = "You are a routing controller for an AI coding agen
     '- "ROTATE_SESSION,0.95,Session size exceeds threshold and current request starts a new task."\n' +
     '- "SPAWN_SUB_SESSION,0.98,Requires writing a test suite and fixing multiple files to get it green."\n' +
     "No other text, only the comma-separated line.";
-export async function classifySubSessionAction(factory, modelId, prompt, contextInfo, signal) {
-    if (process.env.MUONROI_DISABLE_HEURISTIC_ROUTING !== "1") {
-        const heuristic = classifySubSessionActionHeuristic(prompt);
-        if (heuristic)
-            return heuristic;
-    }
+export async function classifySubSessionAction(modelId, prompt, contextInfo, signal) {
+    // No regex pre-filter: the model decides the route for EVERY prompt, including
+    // greetings/acks (which it routes to DIRECT_ANSWER). The old keyword/list
+    // heuristic was removed (2026-07-07, no-regex rule) — a hardcoded whitelist
+    // mis-handles the long tail of natural-language inputs the whole design moved
+    // off of. On a null/failed model result the caller keeps the conservative
+    // DIRECT_ANSWER default (a semantic default, not a regex guess).
     const controller = new AbortController();
     let timer;
     try {
         // Zero-hardcode: query models catalog for a cheap fast-tier model under the same provider.
         const info = getModelInfo(modelId);
         const provider = info?.provider;
-        const fastModel = provider ? getModelByTier("fast", provider) || getModelByTier("balanced", provider) : undefined;
+        const fastModel = provider
+            ? getRoutedModelByTier("fast", provider) || getRoutedModelByTier("balanced", provider)
+            : undefined;
         const classificationModelId = fastModel?.id ?? modelId;
-        const runtime = resolveModelRuntime(factory, classificationModelId);
+        const runtime = resolveModelRuntime(classificationModelId);
         const isReasoning = runtime.modelInfo?.reasoning === true;
-        timer = setTimeout(() => controller.abort(), isReasoning ? REASONING_CLASSIFY_TIMEOUT_MS : LLM_CLASSIFY_TIMEOUT_MS);
+        // Same flat safety-net ceiling as the main classifier (see CLASSIFY_TIMEOUT_MS).
+        timer = setTimeout(() => controller.abort(), CLASSIFY_TIMEOUT_MS);
         const combinedSignal = signal
             ? (AbortSignal.any?.([signal, controller.signal]) ?? controller.signal)
             : controller.signal;
@@ -417,10 +644,15 @@ export async function classifySubSessionAction(factory, modelId, prompt, context
         }
         let promptWithContext = prompt.slice(0, 1000);
         if (contextInfo) {
+            const recent = contextInfo.recentTurns?.trim();
+            const historyBlock = recent
+                ? `[CONVERSATION HISTORY — for context; the prompt may continue or reference it]\n${recent.slice(0, 800)}\n\n`
+                : "";
             promptWithContext =
                 `[SESSION METADATA]\n` +
                     `Current session size: ${contextInfo.currentChars} characters.\n` +
                     `Rotation threshold: ${contextInfo.threshold} characters.\n\n` +
+                    `${historyBlock}` +
                     `[USER PROMPT]\n${promptWithContext}`;
         }
         const result = streamText({