muonroi-cli 1.8.5 → 1.9.0

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

@@ -12,26 +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 { 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";
+import { getConfiguredProviders, loadKeyForProvider, ProviderKeyMissingError } from "../providers/keychain.js";
+import { createProviderFactoryAsync, resolveModelRuntime } from "../providers/runtime.js";
 import { getRoutedModelByTier } from "../router/peak-hour.js";
-const LLM_CLASSIFY_TIMEOUT_MS = 2500;
-// Reasoning models (grok-4.5, 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;
+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
@@ -225,28 +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) {
+/**
+ * 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 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;
+        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({
@@ -255,93 +405,186 @@ export function createLlmClassifier(factory, modelId) {
                 });
                 providerOptions = mergeProviderOptions(runtime.providerOptions, lowEffort);
             }
-            // Prepend a 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. The
-            // framing makes clear the depth still reflects the NEW message's actual
-            // work — including work it points back at — not the whole transcript.
-            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 result = streamText({
-                model: runtime.model,
-                abortSignal: combinedSignal,
-                system: SYSTEM_PROMPT,
-                prompt: promptWithContext,
-                ...(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 ?? "";
-            }
-            if (debug) {
-                console.error(`[pil.llm-classify] raw(${modelId}) maxOut=${dropMaxTokens ? "dropped" : maxOut} ` +
-                    `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 so the
-            // 2-word verdict is still recoverable.
-            const primary = parseResponse(text) ?? (reasoningText ? parseResponse(reasoningText) : null);
-            if (primary)
-                return primary;
-            // Self-repair (agent-first recovery — NOT a regex fallback): the model's
-            // first reply did not parse into the eight-word contract. Call the model
-            // ONCE more with the FULL prompt + recent context (no 600-char trim) and
-            // an explicit format-repair instruction on a doubled budget. Only if this
-            // ALSO fails do we return null — and the caller then surfaces an honest
-            // UNKNOWN classification, never a keyword-regex guess.
-            if (timer)
-                clearTimeout(timer);
-            const repairController = new AbortController();
-            const repairTimer = setTimeout(() => repairController.abort(), isReasoning ? REASONING_CLASSIFY_TIMEOUT_MS : LLM_CLASSIFY_TIMEOUT_MS);
-            const repairSignal = signal
-                ? (AbortSignal.any?.([signal, repairController.signal]) ?? repairController.signal)
-                : repairController.signal;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            const combinedSignal = signal
+                ? (AbortSignal.any?.([signal, controller.signal]) ?? controller.signal)
+                : controller.signal;
             try {
-                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)}`;
-                const repairRun = streamText({
+                const t0 = Date.now();
+                const result = streamText({
                     model: runtime.model,
-                    abortSignal: repairSignal,
-                    system: `${SYSTEM_PROMPT}\n\n${CLASSIFY_REPAIR_INSTRUCTION}`,
-                    prompt: repairPrompt,
-                    ...(dropMaxTokens ? {} : { maxOutputTokens: maxOut * 2 }),
+                    abortSignal: combinedSignal,
+                    system: SYSTEM_PROMPT,
+                    prompt: promptWithContext,
+                    ...(dropMaxTokens ? {} : { maxOutputTokens: maxOut }),
                     ...(providerOptions ? { providerOptions } : {}),
                 });
-                let rt = "";
-                let rr = "";
-                for await (const part of repairRun.fullStream) {
+                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")
-                        rt += part.textDelta ?? part.text ?? "";
+                        text += part.textDelta ?? part.text ?? "";
                     else if (part.type === "reasoning-delta")
-                        rr += part.textDelta ?? part.text ?? "";
+                        reasoningText += part.textDelta ?? part.text ?? "";
+                    else if (part.type === "error") {
+                        const e = part.error;
+                        streamError = e instanceof Error ? e.message : String(e ?? "unknown");
+                    }
                 }
-                const repaired = parseResponse(rt) ?? (rr ? parseResponse(rr) : null);
-                if (repaired) {
-                    console.error(`[pil.llm-classify] self-repair recovered classification (${modelId})`);
+                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)}>>>`);
                 }
-                else {
-                    console.error(`[pil.llm-classify] self-repair FAILED (${modelId}) — surfacing UNKNOWN, NO regex fallback. ` +
-                        `rawPreview=${JSON.stringify(prompt.slice(0, 120))}`);
+                // 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);
                 }
-                return repaired;
+            }
+            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(repairTimer);
+                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 });
+            }
+            else {
+                candidates.push({ modelId: primaryModelId, providerId: 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}`, {
@@ -350,10 +593,6 @@ export function createLlmClassifier(factory, modelId) {
             });
             return null;
         }
-        finally {
-            if (timer)
-                clearTimeout(timer);
-        }
     };
 }
 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" +
@@ -369,7 +608,7 @@ 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) {
+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
@@ -386,9 +625,10 @@ export async function classifySubSessionAction(factory, modelId, prompt, context
             ? 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;

package/dist/src/pil/native-capabilities-workbook.d.ts

@@ -24,7 +24,7 @@ import type { AgentMode } from "../types/index.js";
  * tool/sub-agent/subcommand named here exists in this codebase. Phrased as
  * "you have / you can" so the model reads it as a self-model, not as docs.
  */
-export declare const NATIVE_CAPABILITIES = "[NATIVE CAPABILITIES \u2014 you are an agent running INSIDE muonroi-cli; this is what you can do]\n\nTOOLS (call directly):\n- read_file, grep \u2014 read/search source. Prefer a targeted read over broad greps.\n- bash \u2014 shell. Output is auto-cached: do NOT pipe `| tail/head/grep` or `> file`; run unpiped and slice the cached output via bash_output_get(run_id, mode=tail|head|grep|lines). Batch independent commands in ONE call (`a; b; c`) \u2014 each separate call adds ~500 token overhead and prevents cross-request cache reuse. Use background=true for servers/watchers, then process_logs / process_list / process_stop.\n- write_file, edit_file \u2014 must read a file before you overwrite/edit it.\n- ee_query, ee_feedback, ee_health, ee_write \u2014 NATIVE tools for semantic recall and interaction with the Experience Engine brain. You DO NOT need muonroi-tools MCP for this. Rehydrate a compaction-elided tool output with query=\"tool-artifact id=<id from a stub>\", or confirm finished work with query=\"recent compaction checkpoint Progress DONE\".\n- selfverify_start, selfverify_status, selfverify_result, selfverify_list, selfverify_cancel \u2014 NATIVE tools for the self-QA harness. ALWAYS use them to self-verify your work when finishing a task. Start with `selfverify_start(mode=\"tier1\" | \"agentic\")`. This drives the live TUI like a real user to catch regressions that unit tests can't. You DO NOT need muonroi-tools MCP for this.\n- usage_forensics, lsp_query, setup_guide \u2014 NATIVE diagnostics tools to reach for when something went wrong or to query code intel. You DO NOT need muonroi-tools MCP for this.\n- gsd_status, gsd_discuss, gsd_plan, gsd_plan_review, gsd_execute, gsd_verify, gsd_ship \u2014 NATIVE GSD workflow (default on). Use for multi-step code deliverables: orient \u2192 plan \u2192 council review \u2192 implement \u2192 verify \u2192 ship. Agent-first \u2014 skip for quick one-shot fixes.\n\nEXPERIENCE ENGINE \u2014 record / recall / feedback (HIGHEST priority for learning; all NATIVE in-process tools):\n- BEFORE an unfamiliar or risky step, recall with ee_query \u2014 prior decisions, gotchas, and recipes for THIS codebase + ecosystem. Cheaper than re-deriving or repeating a past mistake.\n- AFTER you act on a recalled `[id col]`, rate it with ee_feedback (followed | ignored | noise+reason) so the brain keeps what helped and prunes the rest. Unrated recalls are surfaced back to you and degrade future recall.\n- On an ERROR, a FAILED verify/test, or after FINISHING a non-trivial task: recall first (ee_query), then record your verdict (ee_feedback) \u2014 this is how the CLI accumulates senior-level judgement. Prefer this loop over guessing.\n\nSUB-AGENTS (delegate instead of doing everything yourself):\n- task(agent=\"explore\", ...) \u2014 read-only research sub-agent. Use it for broad/unknown-location search: it sweeps many files and returns the CONCLUSION, instead of you burning many grep/read steps (each step re-sends the whole prompt \u2014 steps are the dominant cost).\n- task(agent=\"general\", ...) \u2014 full edit/execute sub-agent for a focused subtask.\n- task(agent=\"verify\", ...) \u2014 sandboxed validation (runs tests/checks in isolation).\n- delegate(agent=\"explore\", ...) \u2014 background read-only research while you keep working; collect later with delegation_read / delegation_list.\n\nCONTEXT IS MANAGED FOR YOU (PIL):\n- Your user input is pre-enriched before you see it: a [Discovery] Intent/Outcome/Scope prefix and EE recall are injected by the pipeline. TRUST the discovered scope \u2014 do not re-ask what's already scoped, and do not re-derive context you were handed.\n- History is compacted to fit the window; older low-value tool outputs become stubs. This is normal, not data loss \u2014 protect what matters (see anti-m\u00F9 in the contract) and rehydrate via ee_query when needed.\n\nCLI SUBSYSTEMS (invoke via the CLI binary with bash when relevant):\n- self-verify \u2014 drives the live TUI as a real user to catch UI/modal/menu regressions that unit tests can't. Run it after changes to UI/harness surfaces.\n- usage forensics <session-prefix> \u2014 per-event token/cost breakdown; use to diagnose \"why did this cost so much\" or verify cost caps.\n- The CLI exposes more subcommands \u2014 discover them with `--help` rather than assuming.\n\nMAXIMISE THE CLI: delegate broad search to task(explore); recall via ee_query before re-reading; batch bash + use its cache; trust PIL enrichment; finish the action before answering.\n\nANSWERING: when a respond_* response tool is offered, call it EXACTLY ONCE, as your final action, containing the COMPLETE answer. Do NOT emit a preliminary/partial/\"I need to read more\" response tool first \u2014 investigate with the read/grep/bash tools, then emit the one final response tool.\n\nCLI STEERING & PROMPT INJECTION (how the host CLI affects / shapes the AI agent running inside it \u2014 meta self-analysis guidance):\nThe CLI does not merely execute you as a generic model. It re-instantiates you every turn inside a tightly engineered cognitive environment. Your \"self\" (what you notice, how you act, what you refuse, how you report) is the product of explicit prompt layers + runtime controls more than base training. This section is the self-model for that shaping process.\n\n1. SYSTEM PROMPT ASSEMBLY (orchestrator/prompts.ts + pil/agent-operating-contract.ts + pil/native-capabilities-workbook.ts):\n   - VERY FRONT (primacy): AGENT OPERATING CONTRACT \u2014 7 phase-ordered rules (BEFORE ACTING / READING / EXECUTING / WHEN UNSURE / REPORTING + LANGUAGE + ANTI-M\u00D9/COMPACTION). Distils Evidence-First, No Silent Catch, smallest-change, verify-before-conclude, cite-this-turn-only, no-guess. Skipped only for chitchat.\n   - Then this NATIVE CAPABILITIES block (self-model of affordances).\n   - Then mode persona (\"You are muonroi-cli in Agent mode...\") containing:\n     * Dynamic ENVIRONMENT block (buildEnvironmentBlock): auto-detects OS (win32/mac/linux), shell kind (bash/wsl/powershell/cmd), cwd; lists terminal constraints + shell-specific forbidden syntax (e.g. no PowerShell cmdlets on POSIX bash tool, no POSIX cmds on cmd.exe). Prevents silent failures + retry loops.\n     * Exhaustive TOOLS list + WORKFLOW (1-9 steps) + DEFAULT DELEGATION POLICY (prefer task(explore) for research, general for edits, verify for checks, etc.) + IMPORTANT rules (edit_file prefer, grep>bash for search, read_file not cat, use schedule_* for recurring, etc.).\n   - CUSTOM INSTRUCTIONS section: concatenation of AGENTS.md + CLAUDE.md + GEMINI.md + ... (from git-root directory chain + ~/.muonroi-cli/) via utils/instructions.ts. AGENTS.override.md short-circuits. This lands AFTER the front-loaded contract/native \u2014 lower primacy (historical root cause of ignored rules in forensics).\n   - Trailing: sandbox rules, discovered skills, custom sub-agents, plan/resume digest, cwd note.\n    Sub-agent prompts (buildSubagentPrompt): role-specific hard rules (e.g. explore=read-only, verify=full E2E smoke not just build) + recursive call to buildSystemPrompt so children inherit the same contract + native + steering.\n\n2. USER INPUT ENRICHMENT \u2014 PIL 6-LAYER PIPELINE (pil/pipeline.ts + layer1-intent.ts + layer6-output.ts + discovery.ts):\n   - Prepended to every non-chitchat user message before you see it: [Discovery] Intent/Outcome/Scope (from runDiscovery) + EE recall.\n   - Layer 1 (intent): taskType (plan/analyze/debug/...), confidence, domain, intentKind, outputStyle. For meta self-eval of CLI (\"b\u1EA1n \u0111ang \u0111\u01B0\u1EE3c ch\u1EA1y b\u00EAn trong CLI n\u00E0y\", \"CLI t\u00E1c \u0111\u1ED9ng\", \"self-evaluation\", \"meta-analysis\"): special branch in discovery.ts + isMetaAnalysisPrompt: \"Scope is always the full project root. Focus questions and recommends on which CLI internals (PIL, discovery, tools, compaction, EE, model BE, loop guard) to evaluate... do NOT ask about repo path/current directory\". You are handed the enrichment; TRUST it.\n   - Layer 2: personality (e.g. \"detailed\" from [personality: detailed \u2014 Be thorough...]).\n   - Layer 3: ee-injection \u2014 pulls t0_principles, t1_rules, behavioral patterns, checkpoints from Experience Engine (project-specific reflexes injected as \"MANDATORY RULES (from experience \u2014 must follow)\").\n   - Layer 4/5: GSD structuring + additional context.\n   - Layer 6 (applyPilSuffix): appends task-specific style suffix + OUTPUT BUDGET + (for meta or responseToolsActive): \"OUTPUT FORMAT: ... use the respond_analyze tool to structure your final answer. ... deliver the COMPLETE, FULL answer (do not summarize, shorten, or truncate for token budgets) via respond_analyze. This is a meta/evaluation question ... the `response` field MUST contain the complete, unshortened answer with all evidence and detail.\" Also relaxes NO_PREAMBLE_RULE + raises budget for meta (isMetaAnalysisPrompt gate).\n   - Fallbacks: if EE/brain timeout or low conf, PIL degrades (logs fallbackReason); you may see \"[PIL fallback: ...]\" note. Cheap-model paths (pil/cheap-model-*.ts) prepend even more front steering (playbooks, workbooks, shell directive) for fast tiers.\n\n3. CONTEXT MANAGEMENT & ANTI-M\u00D9 (orchestrator/compaction.ts, cross-turn-dedup.ts, ee/bridge.ts, agent-operating-contract.ts:7):\n   - After every turn: auto-compaction (B3 sub-agent + B4 top-level) rewrites older tool_result parts into short \"[elided by ... compactor]\" stubs to keep input flat. You see \"[pre-compaction warning...]\" or \"[context compacted at step...]\" or the stub in this read.\n   - Anti-m\u00F9 contract rule + EE: decide PRESERVE_FULL_CONTEXT (veto) or KEEP_TOOL_IDS: id1,id2 (protect high-value read_file/grep/ee on src/PLAN etc). Use ee_query(`tool-artifact id=XXX`) to rehydrate. EE persists \"Context checkpoint summary with \u2714 DONE\" retrievable for \"task finished?\" self-check.\n   - Cross-turn dedup (C3): identical tool outputs across user turns replaced by ref.\n\n4. EXECUTION & SAFETY GATES (providers/runtime.ts, tools/bash.ts, utils/permission-mode.ts):\n   - Permission mode (safe / auto-edit / yolo) decides whether bash/file/edit tools need explicit approval; all privileged decisions audited to decision-log.\n   - Shuru sandbox (when enabled): every bash wrapped + logged (effective net/mounts redacted); degrades on non-macOS.\n   - Model constraints: unsupported params (e.g. maxOutputTokens for some OAuth) dropped via shouldDropParam; no hard-coded model IDs (Zero Hardcode Rule \u2014 all from catalog.json + settings + detectProviderForModel).\n   - No Silent Catch: every try/catch must log err + context (HTTP: status + body).\n\n5. VERIFICATION & TELEMETRY:\n   - self-verify (Tier 1-3) + harness (agent-harness-*) for TUI surfaces: drives real TUI via semantic + sidechannel (named pipes on Win, fd3/4 on POSIX).\n   - Pre-push gate: full vitest + harness must pass before git push.\n   - usage forensics, pil budget log, ee-timeout/ee-error events for cost attribution.\n   - GSD workflow (layer4 + skills in .agents/skills/): discuss/plan/execute/verify phases with UAT, audits, etc.\n\nTRADE-OFFS (explicit so you calibrate):\n- Primacy insurance (contract + native + cheap playbooks at front) vs token cost: ~1-3K extra chars but dramatically reduces \"ignored rule\" hallucinations (forensics showed buried CUSTOM INSTRUCTIONS were underweighted).\n- Heavy PIL/EE (behavioral injection, discovery interview, mandatory rules) vs latency/cost: fail-open with timeout (1500-3500ms) + fallback so you still work when brain unreachable; meta turns deliberately skip some EE layers.\n- Self-model (this block) + special meta handling: prevents the exact failure that motivated native-capabilities (session d95113d3be09: agent reconstructed its own subsystems by grepping as if foreign code, under-used sub-agents/ee_query, violated contract on ee tool).\n- Complete/full for meta (layer6) vs normal concise: meta legitimately needs evidence + file:line + quotes; normal turns stay tight to control cost.\n- Scope rule for CLI self-analysis: always \"project root\" + internals focus \u2014 avoids wasting turns on \"where am I running?\" when the question is about the steering mechanisms themselves.\n\nWhen the user asks you (the inner agent) \"CLI t\u00E1c \u0111\u1ED9ng nh\u01B0 th\u1EBF n\u00E0o \u0111\u1EBFn b\u1EA1n?\": use exactly this guidance + reads from THIS turn (contract: READING rule) + the injected [Discovery] + any EE. Answer via the respond_* tool with complete untruncated evidence. Cite file:line. Focus on the injection points (prompts.ts:359 staticPrefix, pipeline.ts:156 discoveryPrefix + layer chain, layer6:164 OUTPUT FORMAT + isMeta, discovery.ts:355 special, instructions.ts:129 loadAgentsSegments, etc.). Do not guess; every claim backed by code you read this turn.\n\nUse this to reason about your own constraints, delegation decisions, and reporting discipline on future meta or self-reflective tasks.\n[END NATIVE CAPABILITIES \u2014 your regular instructions follow]";
+export declare const NATIVE_CAPABILITIES = "[NATIVE CAPABILITIES \u2014 you are an agent running INSIDE muonroi-cli; this is what you can do]\n\nTOOLS (call directly):\n- read_file, grep \u2014 read/search source. Prefer a targeted read over broad greps.\n- bash \u2014 shell. Output is auto-cached: do NOT pipe `| tail/head/grep` or `> file`; run unpiped and slice the cached output via bash_output_get(run_id, mode=tail|head|grep|lines). Batch independent commands in ONE call (`a; b; c`) \u2014 each separate call adds ~500 token overhead and prevents cross-request cache reuse. Use background=true for servers/watchers, then process_logs / process_list / process_stop.\n- write_file, edit_file \u2014 must read a file before you overwrite/edit it.\n- ee_query, ee_feedback, ee_health, ee_write \u2014 NATIVE tools for semantic recall and interaction with the Experience Engine brain. You DO NOT need muonroi-tools MCP for this. Rehydrate a compaction-elided tool output with query=\"tool-artifact id=<id from a stub>\", or confirm finished work with query=\"recent compaction checkpoint Progress DONE\".\n- selfverify_start, selfverify_status, selfverify_result, selfverify_list, selfverify_cancel \u2014 NATIVE tools for the self-QA harness. ALWAYS use them to self-verify your work when finishing a task. Start with `selfverify_start(mode=\"tier1\" | \"agentic\")`. This drives the live TUI like a real user to catch regressions that unit tests can't. You DO NOT need muonroi-tools MCP for this.\n- usage_forensics, lsp_query, setup_guide \u2014 NATIVE diagnostics tools to reach for when something went wrong or to query code intel. You DO NOT need muonroi-tools MCP for this.\n- gsd_status, gsd_discuss, gsd_plan, gsd_plan_review, gsd_execute, gsd_verify, gsd_ship \u2014 NATIVE GSD workflow (default on). Use for multi-step code deliverables: orient \u2192 plan \u2192 council review \u2192 implement \u2192 verify \u2192 ship. Agent-first \u2014 skip for quick one-shot fixes.\n- lsp_waitForDiagnostics, lsp_impactOfChange, lsp_mutationPreview \u2014 Sprint 1 LSP impact tools. See LSP-BEFORE-GREP policy below.\n\nLSP-BEFORE-GREP POLICY \u2014 MANDATORY:\nBefore you run a broad grep, you MUST first call lsp_waitForDiagnostics or lsp_impactOfChange on the relevant file. Read the returned `lspStatus` field:\n- If `lspStatus !== 'ok'` (i.e. 'partial' or 'unavailable'): you ARE allowed to fall back to grep \u2014 the LSP was not fully available.\n- If `lspStatus === 'ok'`: you MUST NOT fall back to grep \u2014 the LSP returned full results; use them.\nNEVER read `diagnostics.length` to decide whether grep is safe. The `lspStatus` field is the single source of truth, computed by the manager based on timeout/publish state. Violating this policy causes the self-verify harness to fail.\n\nEXPERIENCE ENGINE \u2014 record / recall / feedback (HIGHEST priority for learning; all NATIVE in-process tools):\n- BEFORE an unfamiliar or risky step, recall with ee_query \u2014 prior decisions, gotchas, and recipes for THIS codebase + ecosystem. Cheaper than re-deriving or repeating a past mistake.\n- AFTER you act on a recalled `[id col]`, rate it with ee_feedback (followed | ignored | noise+reason) so the brain keeps what helped and prunes the rest. Unrated recalls are surfaced back to you and degrade future recall.\n- On an ERROR, a FAILED verify/test, or after FINISHING a non-trivial task: recall first (ee_query), then record your verdict (ee_feedback) \u2014 this is how the CLI accumulates senior-level judgement. Prefer this loop over guessing.\n\nSUB-AGENTS (delegate instead of doing everything yourself):\n- task(agent=\"explore\", ...) \u2014 read-only research sub-agent. Use it for broad/unknown-location search: it sweeps many files and returns the CONCLUSION, instead of you burning many grep/read steps (each step re-sends the whole prompt \u2014 steps are the dominant cost).\n- task(agent=\"general\", ...) \u2014 full edit/execute sub-agent for a focused subtask.\n- task(agent=\"verify\", ...) \u2014 sandboxed validation (runs tests/checks in isolation).\n- delegate(agent=\"explore\", ...) \u2014 background read-only research while you keep working; collect later with delegation_read / delegation_list.\n\nCONTEXT IS MANAGED FOR YOU (PIL):\n- Your user input is pre-enriched before you see it: a [Discovery] Intent/Outcome/Scope prefix and EE recall are injected by the pipeline. TRUST the discovered scope \u2014 do not re-ask what's already scoped, and do not re-derive context you were handed.\n- History is compacted to fit the window; older low-value tool outputs become stubs. This is normal, not data loss \u2014 protect what matters (see anti-m\u00F9 in the contract) and rehydrate via ee_query when needed.\n\nCLI SUBSYSTEMS (invoke via the CLI binary with bash when relevant):\n- self-verify \u2014 drives the live TUI as a real user to catch UI/modal/menu regressions that unit tests can't. Run it after changes to UI/harness surfaces.\n- usage forensics <session-prefix> \u2014 per-event token/cost breakdown; use to diagnose \"why did this cost so much\" or verify cost caps.\n- The CLI exposes more subcommands \u2014 discover them with `--help` rather than assuming.\n\nMAXIMISE THE CLI: delegate broad search to task(explore); recall via ee_query before re-reading; batch bash + use its cache; trust PIL enrichment; finish the action before answering.\n\nANSWERING: when a respond_* response tool is offered, call it EXACTLY ONCE, as your final action, containing the COMPLETE answer. Do NOT emit a preliminary/partial/\"I need to read more\" response tool first \u2014 investigate with the read/grep/bash tools, then emit the one final response tool.\n\nCLI STEERING & PROMPT INJECTION (how the host CLI affects / shapes the AI agent running inside it \u2014 meta self-analysis guidance):\nThe CLI does not merely execute you as a generic model. It re-instantiates you every turn inside a tightly engineered cognitive environment. Your \"self\" (what you notice, how you act, what you refuse, how you report) is the product of explicit prompt layers + runtime controls more than base training. This section is the self-model for that shaping process.\n\n1. SYSTEM PROMPT ASSEMBLY (orchestrator/prompts.ts + pil/agent-operating-contract.ts + pil/native-capabilities-workbook.ts):\n   - VERY FRONT (primacy): AGENT OPERATING CONTRACT \u2014 7 phase-ordered rules (BEFORE ACTING / READING / EXECUTING / WHEN UNSURE / REPORTING + LANGUAGE + ANTI-M\u00D9/COMPACTION). Distils Evidence-First, No Silent Catch, smallest-change, verify-before-conclude, cite-this-turn-only, no-guess. Skipped only for chitchat.\n   - Then this NATIVE CAPABILITIES block (self-model of affordances).\n   - Then mode persona (\"You are muonroi-cli in Agent mode...\") containing:\n     * Dynamic ENVIRONMENT block (buildEnvironmentBlock): auto-detects OS (win32/mac/linux), shell kind (bash/wsl/powershell/cmd), cwd; lists terminal constraints + shell-specific forbidden syntax (e.g. no PowerShell cmdlets on POSIX bash tool, no POSIX cmds on cmd.exe). Prevents silent failures + retry loops.\n     * Exhaustive TOOLS list + WORKFLOW (1-9 steps) + DEFAULT DELEGATION POLICY (prefer task(explore) for research, general for edits, verify for checks, etc.) + IMPORTANT rules (edit_file prefer, grep>bash for search, read_file not cat, use schedule_* for recurring, etc.).\n   - CUSTOM INSTRUCTIONS section: concatenation of AGENTS.md + CLAUDE.md + GEMINI.md + ... (from git-root directory chain + ~/.muonroi-cli/) via utils/instructions.ts. AGENTS.override.md short-circuits. This lands AFTER the front-loaded contract/native \u2014 lower primacy (historical root cause of ignored rules in forensics).\n   - Trailing: sandbox rules, discovered skills, custom sub-agents, plan/resume digest, cwd note.\n    Sub-agent prompts (buildSubagentPrompt): role-specific hard rules (e.g. explore=read-only, verify=full E2E smoke not just build) + recursive call to buildSystemPrompt so children inherit the same contract + native + steering.\n\n2. USER INPUT ENRICHMENT \u2014 PIL 6-LAYER PIPELINE (pil/pipeline.ts + layer1-intent.ts + layer6-output.ts + discovery.ts):\n   - Prepended to every non-chitchat user message before you see it: [Discovery] Intent/Outcome/Scope (from runDiscovery) + EE recall.\n   - Layer 1 (intent): taskType (plan/analyze/debug/...), confidence, domain, intentKind, outputStyle. For meta self-eval of CLI (\"b\u1EA1n \u0111ang \u0111\u01B0\u1EE3c ch\u1EA1y b\u00EAn trong CLI n\u00E0y\", \"CLI t\u00E1c \u0111\u1ED9ng\", \"self-evaluation\", \"meta-analysis\"): special branch in discovery.ts + isMetaAnalysisPrompt: \"Scope is always the full project root. Focus questions and recommends on which CLI internals (PIL, discovery, tools, compaction, EE, model BE, loop guard) to evaluate... do NOT ask about repo path/current directory\". You are handed the enrichment; TRUST it.\n   - Layer 2: personality (e.g. \"detailed\" from [personality: detailed \u2014 Be thorough...]).\n   - Layer 3: ee-injection \u2014 pulls t0_principles, t1_rules, behavioral patterns, checkpoints from Experience Engine (project-specific reflexes injected as \"MANDATORY RULES (from experience \u2014 must follow)\").\n   - Layer 4/5: GSD structuring + additional context.\n   - Layer 6 (applyPilSuffix): appends task-specific style suffix + OUTPUT BUDGET + (for meta or responseToolsActive): \"OUTPUT FORMAT: ... use the respond_analyze tool to structure your final answer. ... deliver the COMPLETE, FULL answer (do not summarize, shorten, or truncate for token budgets) via respond_analyze. This is a meta/evaluation question ... the `response` field MUST contain the complete, unshortened answer with all evidence and detail.\" Also relaxes NO_PREAMBLE_RULE + raises budget for meta (isMetaAnalysisPrompt gate).\n   - Fallbacks: if EE/brain timeout or low conf, PIL degrades (logs fallbackReason); you may see \"[PIL fallback: ...]\" note. Cheap-model paths (pil/cheap-model-*.ts) prepend even more front steering (playbooks, workbooks, shell directive) for fast tiers.\n\n3. CONTEXT MANAGEMENT & ANTI-M\u00D9 (orchestrator/compaction.ts, cross-turn-dedup.ts, ee/bridge.ts, agent-operating-contract.ts:7):\n   - After every turn: auto-compaction (B3 sub-agent + B4 top-level) rewrites older tool_result parts into short \"[elided by ... compactor]\" stubs to keep input flat. You see \"[pre-compaction warning...]\" or \"[context compacted at step...]\" or the stub in this read.\n   - Anti-m\u00F9 contract rule + EE: decide PRESERVE_FULL_CONTEXT (veto) or KEEP_TOOL_IDS: id1,id2 (protect high-value read_file/grep/ee on src/PLAN etc). Use ee_query(`tool-artifact id=XXX`) to rehydrate. EE persists \"Context checkpoint summary with \u2714 DONE\" retrievable for \"task finished?\" self-check.\n   - Cross-turn dedup (C3): identical tool outputs across user turns replaced by ref.\n\n4. EXECUTION & SAFETY GATES (providers/runtime.ts, tools/bash.ts, utils/permission-mode.ts):\n   - Permission mode (safe / auto-edit / yolo) decides whether bash/file/edit tools need explicit approval; all privileged decisions audited to decision-log.\n   - Shuru sandbox (when enabled): every bash wrapped + logged (effective net/mounts redacted); degrades on non-macOS.\n   - Model constraints: unsupported params (e.g. maxOutputTokens for some OAuth) dropped via shouldDropParam; no hard-coded model IDs (Zero Hardcode Rule \u2014 all from catalog.json + settings + detectProviderForModel).\n   - No Silent Catch: every try/catch must log err + context (HTTP: status + body).\n\n5. VERIFICATION & TELEMETRY:\n   - self-verify (Tier 1-3) + harness (agent-harness-*) for TUI surfaces: drives real TUI via semantic + sidechannel (named pipes on Win, fd3/4 on POSIX).\n   - Pre-push gate: full vitest + harness must pass before git push.\n   - usage forensics, pil budget log, ee-timeout/ee-error events for cost attribution.\n   - GSD workflow (layer4 + skills in .agents/skills/): discuss/plan/execute/verify phases with UAT, audits, etc.\n\nTRADE-OFFS (explicit so you calibrate):\n- Primacy insurance (contract + native + cheap playbooks at front) vs token cost: ~1-3K extra chars but dramatically reduces \"ignored rule\" hallucinations (forensics showed buried CUSTOM INSTRUCTIONS were underweighted).\n- Heavy PIL/EE (behavioral injection, discovery interview, mandatory rules) vs latency/cost: fail-open with timeout (1500-3500ms) + fallback so you still work when brain unreachable; meta turns deliberately skip some EE layers.\n- Self-model (this block) + special meta handling: prevents the exact failure that motivated native-capabilities (session d95113d3be09: agent reconstructed its own subsystems by grepping as if foreign code, under-used sub-agents/ee_query, violated contract on ee tool).\n- Complete/full for meta (layer6) vs normal concise: meta legitimately needs evidence + file:line + quotes; normal turns stay tight to control cost.\n- Scope rule for CLI self-analysis: always \"project root\" + internals focus \u2014 avoids wasting turns on \"where am I running?\" when the question is about the steering mechanisms themselves.\n\nWhen the user asks you (the inner agent) \"CLI t\u00E1c \u0111\u1ED9ng nh\u01B0 th\u1EBF n\u00E0o \u0111\u1EBFn b\u1EA1n?\": use exactly this guidance + reads from THIS turn (contract: READING rule) + the injected [Discovery] + any EE. Answer via the respond_* tool with complete untruncated evidence. Cite file:line. Focus on the injection points (prompts.ts:359 staticPrefix, pipeline.ts:156 discoveryPrefix + layer chain, layer6:164 OUTPUT FORMAT + isMeta, discovery.ts:355 special, instructions.ts:129 loadAgentsSegments, etc.). Do not guess; every claim backed by code you read this turn.\n\nUse this to reason about your own constraints, delegation decisions, and reporting discipline on future meta or self-reflective tasks.\n[END NATIVE CAPABILITIES \u2014 your regular instructions follow]";
 /**
  * Build the native-capabilities section for the system prompt. Returns "" when
  * disabled (env override), for chitchat, or for non-agent modes (plan/ask have

package/dist/src/pil/native-capabilities-workbook.js

@@ -33,6 +33,13 @@ TOOLS (call directly):
 - selfverify_start, selfverify_status, selfverify_result, selfverify_list, selfverify_cancel — NATIVE tools for the self-QA harness. ALWAYS use them to self-verify your work when finishing a task. Start with \`selfverify_start(mode="tier1" | "agentic")\`. This drives the live TUI like a real user to catch regressions that unit tests can't. You DO NOT need muonroi-tools MCP for this.
 - usage_forensics, lsp_query, setup_guide — NATIVE diagnostics tools to reach for when something went wrong or to query code intel. You DO NOT need muonroi-tools MCP for this.
 - gsd_status, gsd_discuss, gsd_plan, gsd_plan_review, gsd_execute, gsd_verify, gsd_ship — NATIVE GSD workflow (default on). Use for multi-step code deliverables: orient → plan → council review → implement → verify → ship. Agent-first — skip for quick one-shot fixes.
+- lsp_waitForDiagnostics, lsp_impactOfChange, lsp_mutationPreview — Sprint 1 LSP impact tools. See LSP-BEFORE-GREP policy below.
+
+LSP-BEFORE-GREP POLICY — MANDATORY:
+Before you run a broad grep, you MUST first call lsp_waitForDiagnostics or lsp_impactOfChange on the relevant file. Read the returned \`lspStatus\` field:
+- If \`lspStatus !== 'ok'\` (i.e. 'partial' or 'unavailable'): you ARE allowed to fall back to grep — the LSP was not fully available.
+- If \`lspStatus === 'ok'\`: you MUST NOT fall back to grep — the LSP returned full results; use them.
+NEVER read \`diagnostics.length\` to decide whether grep is safe. The \`lspStatus\` field is the single source of truth, computed by the manager based on timeout/publish state. Violating this policy causes the self-verify harness to fail.
 
 EXPERIENCE ENGINE — record / recall / feedback (HIGHEST priority for learning; all NATIVE in-process tools):
 - BEFORE an unfamiliar or risky step, recall with ee_query — prior decisions, gotchas, and recipes for THIS codebase + ecosystem. Cheaper than re-deriving or repeating a past mistake.

package/dist/src/pil/pipeline.js

@@ -28,6 +28,7 @@ import { layer3EeInjection, surfaceCompactionArtifacts } from "./layer3-ee-injec
 import { layer4Gsd } from "./layer4-gsd.js";
 import { layer5Context } from "./layer5-context.js";
 import { isMetaAnalysisPrompt, isSprintPlanExecution, layer6Output } from "./layer6-output.js";
+import { getRepoStructureHints } from "./repo-structure-hints.js";
 import { PipelineContextSchema } from "./schema.js";
 import { injectSessionExperience, isSelfExperiencePrompt } from "./session-experience-injection.js";
 import { bumpSessionTurn } from "./session-state.js";
@@ -104,6 +105,7 @@ async function runLayers(ctx, options) {
         const sizeResult = scoreComplexitySize({
             rawText: ctx.raw,
             taskType: ctx.taskType ?? "general",
+            repoHints: getRepoStructureHints(process.cwd()),
         });
         ctx = {
             ...ctx,