muonroi-cli 1.8.4 → 1.9.0

package/dist/src/pil/layer15-context-scan.js

@@ -1,3 +1,4 @@
+import { execSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 export function detectLanguage(cwd, exists = (p) => existsSync(p)) {
@@ -141,14 +142,27 @@ export async function scanProjectContext(raw, cwd) {
     catch {
         /* EE unavailable */
     }
+    let recentModifiedFiles = [];
+    try {
+        const gitOut = execSync("git status --porcelain", { cwd, encoding: "utf-8", stdio: "pipe" });
+        recentModifiedFiles = gitOut
+            .split("\n")
+            .map((line) => line.slice(3).trim())
+            .filter((line) => line.length > 0)
+            .slice(0, 10);
+    }
+    catch {
+        // Not a git repo or git not installed
+    }
     return {
         language,
         framework,
         packageManager,
-        domain: language,
+        domain: null,
         boundedContexts,
         eePatterns,
         relevantModules,
+        recentModifiedFiles,
         scannedAt: Date.now(),
         cwd,
     };

package/dist/src/pil/layer1_5-complexity-size.d.ts

@@ -11,13 +11,20 @@
  * "Layer 1.5 complexity-size (4C)"). Do NOT alter weights without re-running the
  * baseline harness regression.
  */
+import type { RepoStructureHint } from "./repo-structure-hints.js";
 export interface ComplexitySizeInput {
     rawText: string;
     taskType: string;
+    repoHints?: RepoStructureHint[];
 }
 export interface ComplexitySizeResult {
     size: "small" | "medium" | "large";
     score: number;
     features: Record<string, number | boolean>;
 }
+export declare function extractPathTokens(rawText: string): string[];
+export declare function scoreRepoGrounding(paths: string[], hints: RepoStructureHint[]): {
+    score: number;
+    hits: number;
+};
 export declare function scoreComplexitySize(input: ComplexitySizeInput): ComplexitySizeResult;

package/dist/src/pil/layer1_5-complexity-size.js

@@ -62,14 +62,32 @@ function effectiveLen(rawText, taskType) {
 // ---------------------------------------------------------------------------
 // Path token counter — counts DISTINCT path-like tokens.
 // ---------------------------------------------------------------------------
-function countDistinctPaths(rawText) {
+export function extractPathTokens(rawText) {
     const matches = rawText.match(PATH_TOKEN_RE);
     if (!matches)
-        return 0;
+        return [];
     const set = new Set();
     for (const m of matches)
         set.add(m.toLowerCase());
-    return set.size;
+    return [...set];
+}
+export function scoreRepoGrounding(paths, hints) {
+    if (paths.length === 0 || hints.length === 0)
+        return { score: 0, hits: 0 };
+    const hinted = new Map(hints.map((hint) => [hint.path.toLowerCase(), hint]));
+    let score = 0;
+    let hits = 0;
+    for (const path of paths) {
+        const hint = hinted.get(path);
+        if (!hint)
+            continue;
+        hits += 1;
+        if (hint.lineCount >= 5000)
+            score = Math.max(score, 4);
+        else if (hint.lineCount >= 2000)
+            score = Math.max(score, 2);
+    }
+    return { score, hits };
 }
 // ---------------------------------------------------------------------------
 // Main: scoreComplexitySize
@@ -77,6 +95,7 @@ function countDistinctPaths(rawText) {
 export function scoreComplexitySize(input) {
     const rawText = input.rawText ?? "";
     const taskType = input.taskType ?? "general";
+    const repoHints = input.repoHints ?? [];
     // 1. Length score (debug + stack-trace gets mitigation).
     // CONTEXT-locked thresholds are <60 / >240. We use <80 for the "small" knee
     // because the baseline-2 prompt "đổi default --max-tool-rounds từ 100 →
@@ -102,13 +121,18 @@ export function scoreComplexitySize(input) {
     //     baseline-2 "đổi default ... trong src/orchestrator/cli-args.ts")
     //   - zero paths is neutral (vagueness is handled by `vaguenessAmplifier`)
     //   - ≥3 paths is multi-file work, push toward large
-    const pathCount = countDistinctPaths(rawText);
+    const distinctPaths = extractPathTokens(rawText);
+    const pathCount = distinctPaths.length;
     let pathScore = 0;
     if (pathCount === 1)
         pathScore = -1;
     else if (pathCount >= 3)
         pathScore = 2;
     // 0 or 2 → 0 (neutral)
+    // 4.5 Repo-structure grounding probe. Cheap deterministic lookup against the
+    // checked-in REPO_DEEP_MAP index: monolith roots like src/ui/app.tsx should
+    // not size the same as a narrow leaf module when both appear as one-path asks.
+    const repoGrounding = scoreRepoGrounding(distinctPaths, repoHints);
     // 5. Question form score.
     const trimmed = rawText.trim();
     const isQuestion = QUESTION_START_RE.test(trimmed) || trimmed.endsWith("?");
@@ -123,7 +147,7 @@ export function scoreComplexitySize(input) {
     // "improve X" / "clean up Y" without targets is the canonical wandering shape.
     const vaguenessAmplifier = sweepCount > 0 && pathCount === 0 ? 4 : 0;
     // Total score → bucket.
-    const score = lenScore + sweepScore + heavyScore + pathScore + questionScore + vaguenessAmplifier;
+    const score = lenScore + sweepScore + heavyScore + pathScore + repoGrounding.score + questionScore + vaguenessAmplifier;
     let size;
     if (score <= -1)
         size = "small";
@@ -142,6 +166,8 @@ export function scoreComplexitySize(input) {
             heavyScore,
             pathCount,
             pathScore,
+            repoGroundingHits: repoGrounding.hits,
+            repoGroundingScore: repoGrounding.score,
             isQuestion,
             questionScore,
             isImperative,

package/dist/src/pil/layer3-ee-injection.js

@@ -19,6 +19,8 @@ import { searchByText } from "../ee/bridge.js";
 import { updateLastSurfacedState } from "../ee/intercept.js";
 import { formatPendingReminder, isRecallLedgerEnabled, sessionRecallLedger } from "../ee/recall-ledger.js";
 import { getRenderSink } from "../ee/render.js";
+import { PLANNING_CHECKPOINT_QUERY } from "../gsd/ee-closure.js";
+import { isGsdNativeEnabled } from "../gsd/flags.js";
 import { logInteraction } from "../storage/interaction-log.js";
 import { classifyEeError, logEeFailure, readTimeoutEnv } from "../utils/ee-logger.js";
 import { truncateToBudget } from "./budget.js";
@@ -138,10 +140,13 @@ async function queryEeBridge(raw, taskType) {
         // Phase 3 (ee-anti-mu): third arm for compaction checkpoints so PIL can surface
         // prior "Progress ✔ DONE / elided" without the agent having to ask "task finished?".
         const signal = AbortSignal.timeout(PIL_SEARCH_TIMEOUT_MS);
+        const planningQuery = isGsdNativeEnabled()
+            ? `${PLANNING_CHECKPOINT_QUERY} OR compaction checkpoint`
+            : 'Context checkpoint summary OR "compaction checkpoint" recent Progress DONE elided OR tool-artifact OR "tool result id="';
         const [principleRaw, behavioralRaw, checkpointRaw] = await Promise.all([
             searchByText(queryWithTask, ["experience-principles"], 3, signal),
             searchByText(queryWithTask, ["experience-behavioral"], 4, signal),
-            searchByText('Context checkpoint summary OR "compaction checkpoint" recent Progress DONE elided OR tool-artifact OR "tool result id="', ["experience-behavioral"], 3, signal).catch(() => []),
+            searchByText(planningQuery, ["experience-behavioral"], 3, signal).catch(() => []),
         ]);
         const principlePoints = principleRaw.filter((p) => (p.score ?? 0) >= PIL_PRINCIPLES_FLOOR);
         const behavioralPoints = behavioralRaw.filter((p) => (p.score ?? 0) >= PIL_SCORE_FLOOR);
@@ -217,10 +222,15 @@ export async function layer3EeInjection(ctx) {
             ...p,
             collection: p.collection ?? "experience-behavioral",
         }));
-        // Suppress already-fedback entries so they don't re-inject as noise.
+        // Suppress (a) already-fed-back entries AND (b) entries already surfaced
+        // earlier this session (still pending) — re-injecting the full body of a
+        // hint the agent already saw is pure repetition (the "hint lặp"); the hit
+        // stays in the feedback nudge (shown once via _surfacedPendingIds) so the
+        // rating path is preserved without duplicating content every turn.
         if (isRecallLedgerEnabled()) {
-            principleItems = principleItems.filter((p) => !sessionRecallLedger.wasCleared(String(p.id)));
-            behavioralItems = behavioralItems.filter((p) => !sessionRecallLedger.wasCleared(String(p.id)));
+            const alreadyShown = (id) => sessionRecallLedger.wasCleared(id) || sessionRecallLedger.isPending(id);
+            principleItems = principleItems.filter((p) => !alreadyShown(String(p.id)));
+            behavioralItems = behavioralItems.filter((p) => !alreadyShown(String(p.id)));
         }
         // Render the [id:..] handle inline (mirrors formatPrincipleRules/Hints) so the
         // [id collection] reminder below refers to handles the agent can actually see.
@@ -397,11 +407,16 @@ export async function layer3EeInjection(ctx) {
             return text.length === 0 || !checkpointMarkerShas.has(payloadSha16(text));
         })
         : result.checkpointPoints || [];
-    // Feedback-cleared suppression: skip points that were already rated via ee_feedback in an earlier turn.
-    // This prevents already-judged entries from being re-injected as noise.
+    // Suppression: skip rateable hints that were already (a) rated via ee_feedback
+    // OR (b) surfaced earlier this session (still pending). Re-injecting the full
+    // body of a hint the agent already saw is the "hint lặp" repetition; the entry
+    // stays in the feedback nudge (shown once) so rating is still prompted.
+    // Checkpoints are GSD status context (not rateable) — only cleared-suppressed,
+    // they may legitimately re-surface each turn.
     const ledgerEnabled = isRecallLedgerEnabled();
-    const clearedFilteredPrinciples = deduplicatedPrinciples.filter((p) => !(ledgerEnabled && sessionRecallLedger.wasCleared(String(p.id))));
-    const clearedFilteredBehavioral = deduplicatedBehavioral.filter((p) => !(ledgerEnabled && sessionRecallLedger.wasCleared(String(p.id))));
+    const alreadyShown = (id) => ledgerEnabled && (sessionRecallLedger.wasCleared(id) || sessionRecallLedger.isPending(id));
+    const clearedFilteredPrinciples = deduplicatedPrinciples.filter((p) => !alreadyShown(String(p.id)));
+    const clearedFilteredBehavioral = deduplicatedBehavioral.filter((p) => !alreadyShown(String(p.id)));
     const clearedFilteredCheckpoints = deduplicatedCheckpoints.filter((p) => !(ledgerEnabled && sessionRecallLedger.wasCleared(String(p.id))));
     const allPoints = [...clearedFilteredPrinciples, ...clearedFilteredBehavioral, ...clearedFilteredCheckpoints];
     // STALE-01: Register injected point IDs for prompt-stale reconciliation.

package/dist/src/pil/layer4-gsd.js

@@ -17,10 +17,12 @@
  * the agent, into the user's language.
  */
 import { getWhoAmIProfile, routeTask } from "../ee/bridge.js";
+import { isGsdNativeEnabled } from "../gsd/flags.js";
+import { readState } from "../gsd/workflow-engine.js";
 import { buildDirective } from "../playbook/directives.js";
 import { classifyEeError, logEeFailure } from "../utils/ee-logger.js";
 import { truncateToBudget } from "./budget.js";
-import { isImplementationIntent, isMetaAnalysisPrompt, isQuestionLike } from "./layer6-output.js";
+import { isImplementationIntent, isMetaAnalysisPrompt, isQuestionLike, isSprintPlanExecution, } from "./layer6-output.js";
 function mapRouteToPhase(route) {
     switch (route) {
         case "qc-flow":
@@ -66,10 +68,10 @@ export async function layer4Gsd(ctx) {
     }
     let phase = ctx.gsdPhase ?? null;
     let routeSource = "preset";
-    // Skip brain routeTask when L1's unified call already supplied brain data:
-    // any phase L1 derived is already on ctx.gsdPhase, and a separate routeTask
-    // round-trip would duplicate the brain hit the unified endpoint replaces.
-    if (!phase && !ctx._brainData) {
+    // Skip brain routeTask when L1 unified pilContext already supplied gsd_phase
+    // (on ctx.gsdPhase) or brain retrieval data (_brainData) — a separate routeTask
+    // round-trip would duplicate the unified endpoint.
+    if (!phase && !ctx._brainData && !ctx.gsdPhase) {
         const eeRoute = await routeTask(ctx.raw).catch((err) => {
             logEeFailure("pil.layer4.routeTask", classifyEeError(err), err);
             return null;
@@ -124,13 +126,23 @@ export async function layer4Gsd(ctx) {
     // read/summarize/architecture tasks (deliverableKind "report") down the heavy
     // council + AskUserQuestion path, over-asking on a task that just wanted a
     // written summary (session 666630479c1a: "Đọc và tóm tắt kiến trúc…" raised 2
-    // askcards + a council loop). Only when the model emitted no deliverable
-    // (deliverableKind null → legacy cascade) do we fall back to regex predicates:
+    // askcards + a council loop).
+    //
+    // BUT a "report" deliverable can still be a genuine implementation request the
+    // model mis-tagged (e.g. "make a plan to implement OAuth device flow" — the
+    // deliverable IS a plan/report, yet the raw prompt asks to implement). Without
+    // a guard this never entered GSD. isImplementationIntent re-checks the raw
+    // text so a real implementation ask overrides the deliverable-kind shortcut;
+    // a genuine summary/read prompt (no implementation keywords) still passes
+    // through as informational.
+    //
+    // Only when the model emitted no deliverable (deliverableKind null → legacy
+    // cascade) do we fall back to regex predicates:
     //   1. isMetaAnalysisPrompt — self/CLI evaluation, prior-turn reflection.
     //   2. taskType "general" classified as a real task by L1.
     //   3. question-shaped prompt that is NOT an implementation request.
     const informational = ctx.deliverableKind
-        ? ctx.deliverableKind !== "code"
+        ? ctx.deliverableKind !== "code" && !isImplementationIntent(ctx.raw)
         : isMetaAnalysisPrompt(ctx.raw) ||
             (ctx.taskType === "general" && ctx.intentKind === "task") ||
             (isQuestionLike(ctx.raw) && !isImplementationIntent(ctx.raw));
@@ -141,17 +153,57 @@ export async function layer4Gsd(ctx) {
     // language the model detected (the old regex only caught Vietnamese).
     const ecosystem = ctx.ecosystemScope === true;
     const replyLanguage = ctx.replyLanguage ?? undefined;
-    const directive = buildDirective({ tier, phase, informational, ecosystem, replyLanguage });
-    // truncateToBudget takes a TOKEN budget (×CHARS_PER_TOKEN internally). Floor it
-    // at DIRECTIVE_MIN_TOKENS so the full directive always survives, even at the
-    // default tokenBudget=500 where the bare fraction would gut it.
-    const directiveTokenBudget = Math.max(Math.floor(ctx.tokenBudget * DIRECTIVE_BUDGET_FRACTION), DIRECTIVE_MIN_TOKENS);
-    const trimmed = truncateToBudget(directive.text, directiveTokenBudget);
+    const native = isGsdNativeEnabled();
+    const sprintExecution = isSprintPlanExecution(ctx.raw);
+    let trimmed;
+    let blocking = false;
+    let appliedTier = tier;
+    if (sprintExecution) {
+        // Sprint plan execution: the plan has already been debated and reviewed by
+        // the council. The impl turn must APPLY it, not re-enter gsd_plan_review.
+        // Override any depth-tier hint that would tell the model to plan first.
+        const execDirective = [
+            "[sprint-execution] The attached text is an APPROVED sprint plan.",
+            "EXECUTE it directly with edit_file/write_file/bash tools.",
+            "Do NOT call gsd_discuss, gsd_plan, or gsd_plan_review — the plan is already reviewed.",
+            "After edits, run gsd_verify if verification steps are listed, otherwise finish.",
+        ].join(" ");
+        trimmed = truncateToBudget(execDirective, 200);
+        blocking = false;
+        appliedTier = "standard";
+    }
+    else if (native && !informational) {
+        const cwd = process.cwd();
+        const wf = readState(cwd);
+        // Heavy is now a hard MANDATORY sequence (Task 8 wires the runtime mutation
+        // gate that actually BLOCKs edit_file/write_file/bash on this depth); standard
+        // stays advisory-only — never say BLOCKED for standard, the gate doesn't fire there.
+        const heavyLine = tier === "heavy"
+            ? " MANDATORY (heavy): gsd_status → gsd_discuss → gsd_plan → gsd_plan_review BEFORE any edit_file/write_file/bash. Mutation tools are BLOCKED until plan-review passes. Start with gsd_status now."
+            : "";
+        const nativeHint = [
+            "[gsd-native] Tools: gsd_status, gsd_discuss, gsd_plan, gsd_plan_review, gsd_execute, gsd_verify, gsd_ship.",
+            `Depth=${tier}. standard/heavy: recommend gsd_plan_review before gsd_execute; then gsd_verify → gsd_ship.${heavyLine}`,
+            wf.phase ? `phase=${wf.phase}` : "gsd_status bootstraps .planning/",
+            wf.planVerified ? "plan-verified=yes" : "plan-verified=pending",
+        ].join(" ");
+        trimmed = truncateToBudget(nativeHint, 200);
+        blocking = tier === "heavy";
+        appliedTier = tier;
+    }
+    else {
+        const directive = buildDirective({ tier, phase, informational, ecosystem, replyLanguage, nativeGsd: native });
+        const directiveTokenBudget = Math.max(Math.floor(ctx.tokenBudget * DIRECTIVE_BUDGET_FRACTION), DIRECTIVE_MIN_TOKENS);
+        trimmed = truncateToBudget(directive.text, directiveTokenBudget);
+        blocking = directive.blocking;
+        appliedTier = directive.tier;
+    }
     const depthSource = ctx.modelDepthTier ? "model" : "default";
     return {
         ...ctx,
         gsdPhase: phase,
         complexityTier: tier,
+        gsdGateBlocking: blocking,
         grayAreas,
         enriched: `${ctx.enriched}\n${trimmed}`,
         layers: [
@@ -160,11 +212,12 @@ export async function layer4Gsd(ctx) {
                 name: "gsd-workflow-structuring",
                 applied: true,
                 delta: [
-                    `tier=${directive.tier}`,
+                    `tier=${appliedTier}`,
+                    `native=${native}`,
                     `depth=${depthSource}`,
                     `phase=${phase ?? "none"}`,
                     `route=${routeSource}`,
-                    `blocking=${directive.blocking}`,
+                    `blocking=${blocking}`,
                     `chars=${trimmed.length}`,
                 ].join(" "),
             },

package/dist/src/pil/layer5-context.js

@@ -50,11 +50,15 @@ async function fetchPrinciples(raw, budget) {
 }
 async function fetchFlowState(cwd, budget) {
     try {
-        const activeRunPath = path.join(cwd, ".muonroi-flow", "active-run");
-        const runId = (await fs.readFile(activeRunPath, "utf8")).trim();
+        // Canonical focus pointer: `state.md` `Active Run` (run-manager). The old
+        // `.muonroi-flow/active-run` file had no writer in src and always read stale
+        // (F8 follow-up: dropped that dead path in favor of the single source).
+        const { getActiveRunId } = await import("../flow/run-manager.js");
+        const flowDir = path.join(cwd, ".muonroi-flow");
+        const runId = await getActiveRunId(flowDir);
         if (!runId)
             return "";
-        const statePath = path.join(cwd, ".muonroi-flow", "runs", runId, "state.md");
+        const statePath = path.join(flowDir, "runs", runId, "state.md");
         const state = await fs.readFile(statePath, "utf8");
         const phaseLine = state.match(/phase:\s*(.+)/i)?.[1]?.trim() ?? "unknown";
         const statusLine = state.match(/status:\s*(.+)/i)?.[1]?.trim() ?? "unknown";

package/dist/src/pil/layer6-output.d.ts

@@ -17,6 +17,29 @@ import type { ProviderId } from "../providers/types.js";
 import type { PipelineContext } from "./types.js";
 export declare function isMetaAnalysisPrompt(raw: string): boolean;
 export declare function applyPilSuffix(systemPrompt: string, ctx: PipelineContext, responseToolsActive?: boolean): string;
+/**
+ * Detect an explicit IMPLEMENTATION / edit-the-files intent. When the user asks
+ * to implement/edit/refactor (the deliverable is file changes, not a structured
+ * report), a terminal `respond_<task>` tool is inappropriate: the model can call
+ * it mid-task to "state a plan/answer" and the turn then winds down before the
+ * edits are finished. Live (grok session 19fa8895c41c): an "Improve … implement
+ * these fixes" prompt was classified `debug`, so `respond_debug` was offered; the
+ * model called it after reading the files, made a few edits, then stopped — the
+ * HTML was never wired. Dropping the tool just falls through to the markdown
+ * OUTPUT RULES (graceful — exactly what code-heavy tasks already do), so a false
+ * positive on an analysis turn only forgoes structured JSON, never breaks output.
+ *
+ * High-signal verbs only (implement/edit/wire/rewrite/rename/scaffold/refactor/
+ * improve, "make the change", "apply the fix/patch", VI equivalents incl. "cải
+ * thiện"). Bare "fix"/"replace" are excluded — too common in analysis ("explain
+ * the fix") — so pure analyze/plan/debug-investigation turns keep their
+ * structured output. "improve(ment)" / "cải thiện" added after session
+ * 2b7a10219499: "lên plan rồi improvement … cải thiện Compaction" was an
+ * implement turn the model mis-classified as a `report`, so a terminal
+ * respond_plan ended it on a plan (edits done but uncommitted/unreported).
+ */
+export declare const SPRINT_EXECUTION_MARKER = "[SPRINT-PLAN-EXECUTION: locked]";
+export declare function isSprintPlanExecution(raw: string): boolean;
 export declare function isImplementationIntent(raw: string): boolean;
 export declare function isQuestionLike(raw: string): boolean;
 export declare function prefersStructuredReport(raw: string): boolean;

package/dist/src/pil/layer6-output.js

@@ -285,7 +285,11 @@ export function applyPilSuffix(systemPrompt, ctx, responseToolsActive = false) {
  * implement turn the model mis-classified as a `report`, so a terminal
  * respond_plan ended it on a plan (edits done but uncommitted/unreported).
  */
-const IMPLEMENTATION_INTENT_RE = /\b(implement|edit|wire(?:\s+up)?|rewrite|rename|scaffold|refactor)\b|\bimprove(?:ment)?\b|\bmake\s+(the\s+)?(change|edit|modification)s?\b|\bapply\s+(the\s+)?(fix|change|patch|edit|diff)\b|(?:^|\s)(triển\s*khai|trien\s*khai|chỉnh\s*sửa|chinh\s*sua|viết\s*lại|viet\s*lai|đổi\s*tên|doi\s*ten|cải\s*thiện|cai\s*thien)\b/i;
+export const SPRINT_EXECUTION_MARKER = "[SPRINT-PLAN-EXECUTION: locked]";
+export function isSprintPlanExecution(raw) {
+    return raw.includes(SPRINT_EXECUTION_MARKER) || raw.includes("--- SPRINT PLAN TO IMPLEMENT ---");
+}
+const IMPLEMENTATION_INTENT_RE = /\b(implement|edit|wire(?:\s+up)?|rewrite|rename|scaffold|refactor)\b|\bimprove(?:ment)?\b|\bmake\s+(the\s+)?(change|edit|modification)s?\b|\bapply\s+(the\s+)?(fix|change|patch|edit|diff)\b|(?:^|\s)(triển\s*khai|trien\s*khai|chỉnh\s*sửa|chinh\s*sua|viết\s*lại|viet\s*lai|đổi\s*tên|doi\s*ten|cải\s*thiện|cai\s*thien)\b|\[SPRINT-PLAN-EXECUTION:\s*locked\]/i;
 export function isImplementationIntent(raw) {
     return !!raw && IMPLEMENTATION_INTENT_RE.test(raw);
 }

package/dist/src/pil/llm-classify.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderFactory } from "../providers/runtime.js";
+import type { ProviderId } from "../providers/types.js";
 import type { OutputStyle, TaskType } from "./types.js";
 /**
  * What the user wants the turn to PRODUCE — decided by the model (Phase 2b) so
@@ -49,6 +49,18 @@ export interface LlmClassifyResult {
      * what the task actually entails, not by which keywords it happens to contain.
      */
     depthTier: DepthTier | null;
+    /**
+     * Model-decided clarity: true when the request is UNDERSPECIFIED — missing
+     * information the agent would need to proceed without guessing (an unstated
+     * target/scope, a vague "make it better", competing interpretations, or an
+     * unresolved design choice). Drives the interview gate: a `standard`-depth
+     * task that is underspecified earns a clarify/council pass instead of hot-
+     * pathing straight to implementation. `false` = well-specified enough to plan
+     * directly. null when the model omitted the word → treated as not-
+     * underspecified (the don't-over-ask safe direction). Agent-first replacement
+     * for the regex `scoreSufficiency` scorer.
+     */
+    needsClarification: boolean | null;
     /**
      * Model-decided scope: true when the turn is about the Muonroi PLATFORM /
      * ecosystem (BB/.NET packages, building-block, open-core, rule engine,
@@ -67,7 +79,69 @@ export interface LlmClassifyResult {
      */
     replyLanguage: string | null;
 }
-export type LlmClassifyFn = (prompt: string, signal?: AbortSignal) => Promise<LlmClassifyResult | null>;
+/**
+ * Options for a classify call. `recentTurns` is a compact digest of the last
+ * few conversation turns; when present the classifier uses it ONLY to resolve
+ * back-references in the new message (e.g. "từ các phần đó", "làm tiếp", "this")
+ * so a terse follow-up that points at heavy prior work is not mis-scored as a
+ * trivial one-liner. Without it the classifier sees the bare prompt and is blind
+ * to context — the documented "chấm điểm chỉ dựa only prompt" failure.
+ */
+export interface LlmClassifyOptions {
+    recentTurns?: string | null;
+    signal?: AbortSignal;
+}
+export type LlmClassifyFn = (prompt: string, opts?: LlmClassifyOptions) => Promise<LlmClassifyResult | null>;
+/**
+ * Factory-level options for `createLlmClassifier` (distinct from the per-call
+ * `LlmClassifyOptions`). Chosen once when the closure is built.
+ */
+export interface CreateClassifierOptions {
+    /**
+     * Route the throwaway classify to the provider's fast tier when one exists
+     * (mirrors `classifySubSessionAction`). Same-provider only, so the already-
+     * bound factory/key still works. A no-op when the provider exposes no
+     * routable fast model (e.g. xai). Zero-hardcode: the fast id comes from
+     * `getRoutedModelByTier`, not a literal. Cheap — safe on every turn.
+     */
+    routeFastTier?: boolean;
+    /**
+     * When the session provider has NO same-provider fast tier (e.g. xai, whose
+     * session model may be an agentic model that ignores the terse classify
+     * contract — measured 2026-07-15 for grok-composer), also try keyed fast
+     * models from OTHER configured providers, in catalog switch order, until one
+     * parses. Bounded by CLASSIFY_TOTAL_BUDGET_MS so a chain of dead/slow keys
+     * can't stall the turn. This adds latency ONLY on that fallback path, so it is
+     * opt-in per call-site: enable it for the high-value /ideal routing classify,
+     * NOT for the per-turn PIL classify (there a fast fail-open "standard" is fine
+     * and cheaper than chaining providers on every message).
+     */
+    crossProviderFallback?: boolean;
+}
+/**
+ * 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 declare function classifierBudget(modelInfo: {
+    reasoning?: boolean;
+    tier?: string;
+} | undefined): {
+    isReasoning: boolean;
+    timeoutMs: number;
+    maxOutputTokens: number;
+};
+/** Test seam — clear the cross-provider factory cache between specs. */
+export declare function __resetClassifyFactoryCache(): void;
 /**
  * Build a closure the PIL pipeline can call. Reuses the orchestrator's already-
  * constructed providerFactory + modelId so we don't pay key-loading cost twice.
@@ -75,15 +149,47 @@ export type LlmClassifyFn = (prompt: string, signal?: AbortSignal) => Promise<Ll
  * Returns null if the call fails / times out / parses to garbage. Callers must
  * fail-open (keep prior taskType, do not block the turn).
  */
-export declare function createLlmClassifier(factory: ProviderFactory, modelId: string): LlmClassifyFn;
+/**
+ * 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 declare function orderClassifyCandidates(args: {
+    primaryModelId: string;
+    hasSameFast: boolean;
+    crossModels: ReadonlyArray<{
+        modelId: string;
+        providerId: ProviderId;
+    }>;
+}): Array<{
+    modelId: string;
+    providerId: ProviderId | null;
+}>;
+export declare function createLlmClassifier(modelId: string, classifyOpts?: CreateClassifierOptions): LlmClassifyFn;
 export type SubSessionAction = "DIRECT_ANSWER" | "ROTATE_SESSION" | "SPAWN_SUB_SESSION";
 export interface SubSessionRouteResult {
     action: SubSessionAction;
     confidence: number;
     reason: string;
 }
-export declare function classifySubSessionActionHeuristic(prompt: string): SubSessionRouteResult | null;
-export declare function classifySubSessionAction(factory: ProviderFactory, modelId: string, prompt: string, contextInfo?: {
+export declare function classifySubSessionAction(modelId: string, prompt: string, contextInfo?: {
     currentChars: number;
     threshold: number;
+    /**
+     * Compact digest of recent conversation turns. The router's system prompt
+     * says it decides "based on the conversation history" — without this the
+     * history was never actually supplied and the router judged the prompt in
+     * isolation, so a follow-up like "ok làm phần đó đi" could not be told apart
+     * from a fresh unrelated task. Supplying it makes the claim true.
+     */
+    recentTurns?: string | null;
 }, signal?: AbortSignal): Promise<SubSessionRouteResult | null>;