@phuetz/code-buddy 1.6.1 → 2.0.0

package/dist/agent/execution/ordered-tool-executor.js

@@ -0,0 +1,54 @@
+/**
+ * Split tool calls into ordered execution batches.
+ *
+ * Consecutive read-only calls share a batch. Every mutating call is isolated,
+ * which creates a barrier before and after it. Consumers must process each
+ * batch before starting the next one to preserve side-effect ordering.
+ */
+export function createOrderedToolBatches(items, isParallelizable) {
+    const batches = [];
+    let parallelBatch = [];
+    const flushParallelBatch = () => {
+        if (parallelBatch.length > 0) {
+            batches.push(parallelBatch);
+            parallelBatch = [];
+        }
+    };
+    for (const item of items) {
+        if (isParallelizable(item)) {
+            parallelBatch.push(item);
+            continue;
+        }
+        flushParallelBatch();
+        batches.push([item]);
+    }
+    flushParallelBatch();
+    return batches;
+}
+/**
+ * Execute a batch with bounded concurrency while returning results in input
+ * order. Rejections are converted by `onError`, keeping the caller's hot loop
+ * never-throws contract intact.
+ */
+export async function executeBoundedInOrder(items, worker, onError, maxConcurrent = 5) {
+    const results = new Array(items.length);
+    const concurrency = Math.max(1, Math.min(maxConcurrent, items.length));
+    let nextIndex = 0;
+    const runWorker = async () => {
+        while (nextIndex < items.length) {
+            const index = nextIndex++;
+            const item = items[index];
+            if (item === undefined)
+                continue;
+            try {
+                results[index] = await worker(item, index);
+            }
+            catch (error) {
+                results[index] = onError(error, item, index);
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: concurrency }, () => runWorker()));
+    return results;
+}
+//# sourceMappingURL=ordered-tool-executor.js.map

package/dist/agent/execution/post-tool-handlers.d.ts

@@ -16,7 +16,7 @@
  * Call-id-keyed; allows later restoration of compacted tool results.
  * No-op when toolCallId is empty.
  */
-export declare function persistToolResult(toolCallId: string | undefined, rawContent: string): void;
+export declare function persistToolResult(toolCallId: string | undefined, rawContent: string, workDir?: string, sessionId?: string): void;
 /**
  * Wrap raw tool output through the observation variator (Manus AI #17),
  * which rotates the presentation wrapper to prevent repetition drift.

package/dist/agent/execution/post-tool-handlers.js

@@ -19,9 +19,9 @@ import { getObservationVariator } from '../../context/observation-variator.js';
  * Call-id-keyed; allows later restoration of compacted tool results.
  * No-op when toolCallId is empty.
  */
-export function persistToolResult(toolCallId, rawContent) {
+export function persistToolResult(toolCallId, rawContent, workDir = process.cwd(), sessionId) {
     if (toolCallId) {
-        getRestorableCompressor().writeToolResult(toolCallId, rawContent);
+        getRestorableCompressor().writeToolResult(toolCallId, rawContent, workDir, sessionId);
     }
 }
 /**

package/dist/agent/execution/query-classifier.d.ts

@@ -14,6 +14,8 @@ export interface ContextInjectionLevel {
     codeGraph: boolean;
     docs: boolean;
     todo: boolean;
+    /** Collective Knowledge Graph (shared cross-agent memory). Optional → opt-in (Phase 0). */
+    collectiveGraph?: boolean;
 }
 export declare function classifyQuery(message: string): {
     complexity: QueryComplexity;

package/dist/agent/execution/query-classifier.js

@@ -12,10 +12,12 @@ const INJECTION_LEVELS = {
     simple: {
         workspace: false, lessons: true, knowledgeGraph: true,
         decisionMemory: false, icmMemory: false, codeGraph: false, docs: false, todo: true,
+        collectiveGraph: true,
     },
     complex: {
         workspace: true, lessons: true, knowledgeGraph: true,
         decisionMemory: true, icmMemory: true, codeGraph: true, docs: true, todo: true,
+        collectiveGraph: true,
     },
 };
 const GREETING_PATTERNS = /^(h(ello|i|ey|owdy)|bonjour|salut|coucou|hola|ciao|guten\s*tag|yo|sup|what'?s?\s*up|good\s*(morning|afternoon|evening|night)|bonsoir)[\s!?.,:;]*$/i;

package/dist/agent/execution/tool-dependency-graph.js

@@ -168,6 +168,13 @@ export const TOOL_METADATA = {
         parallelSafe: true,
         priority: 7,
     },
+    object_detect: {
+        reads: ["file"],
+        writes: ["file"],
+        hasSideEffects: true,
+        parallelSafe: true,
+        priority: 7,
+    },
     // Generation tools (write files)
     screenshot: {
         reads: [],

package/dist/agent/execution/tool-selection-strategy.d.ts

@@ -31,6 +31,12 @@ export interface ToolSelectionConfig {
     minScore: number;
     /** Tool names that should always be included (default: core tools) */
     alwaysInclude: string[];
+    /**
+     * Optional hard model-facing allowlist. Unlike relevance filtering this is an
+     * effect boundary: schemas outside the list are removed even if they are
+     * normally always included. Used by evidence-only introspection turns.
+     */
+    allowedToolNames?: string[];
     /** Enable adaptive threshold based on success metrics (default: true) */
     useAdaptiveThreshold: boolean;
     /** Enable caching of selected tools for multi-round consistency (default: true) */
@@ -61,6 +67,10 @@ export interface SelectionResult {
     /** Confidence score (0-1) based on best match score ratio */
     confidence?: number;
 }
+/**
+ * Default configuration for tool selection
+ */
+export declare const DEFAULT_TOOL_SELECTION_CONFIG: ToolSelectionConfig;
 /**
  * Tool Selection Strategy
  *
@@ -88,6 +98,8 @@ export declare class ToolSelectionStrategy {
     private cachedToolNames;
     private cacheModelName;
     private lastQuery;
+    /** Query the cached tool set was selected FOR — cache hits require equality. */
+    private cachedQuery;
     private lastSelection;
     private cacheTimestamp;
     private activeSkill;
@@ -117,6 +129,14 @@ export declare class ToolSelectionStrategy {
      * @param tools - Tools to cache
      */
     cacheTools(tools: CodeBuddyTool[], modelName?: string): void;
+    /**
+     * Expand the CURRENT turn's cached selection with named tools — called by
+     * the executor after a successful `tool_search` so a discovered tool is
+     * actually invocable on the next round (the cache would otherwise re-serve
+     * the same list for the rest of the turn). No-op for unknown names or when
+     * no cache is active.
+     */
+    expandCachedTools(names: string[]): Promise<number>;
     /**
      * Get cached tools if available and valid
      *

package/dist/agent/execution/tool-selection-strategy.js

@@ -21,10 +21,11 @@ import { filterToolsForModel, getModelToolConfig, } from '../../config/model-too
 import { getPromptCacheManager } from '../../optimization/prompt-cache.js';
 import { logger } from '../../utils/logger.js';
 import { getSkillsHub } from '../../skills/hub.js';
+import { DESIGN_SYSTEM_TOOL } from '../../codebuddy/tool-definitions/design-tools.js';
 /**
  * Default configuration for tool selection
  */
-const DEFAULT_CONFIG = {
+export const DEFAULT_TOOL_SELECTION_CONFIG = {
     useRAG: true,
     maxTools: 15,
     minScore: 0.5,
@@ -42,11 +43,50 @@ const DEFAULT_CONFIG = {
     // `tool_search` is ALWAYS exposed so the model can discover & pull ANY tool
     // on demand when the per-query TF-IDF subset missed it (progressive disclosure,
     // like Codex/Claude). Without it, a tool outside the top-K is unreachable.
-    alwaysInclude: ['view_file', 'bash', 'search', 'str_replace_editor', 'web_search', 'remember', 'memory_propose', 'lessons_add', 'lessons_propose', 'lessons_search', 'tool_search'],
+    // `create_file` pairs with `str_replace_editor`: without it an agent whose
+    // RAG subset missed it can EDIT files but never CREATE one — proven live in
+    // Cowork's App Studio generation ("l'outil create_file n'est pas disponible
+    // dans cette session"). `apply_patch` likewise: WritePolicy strict blocks
+    // direct editors and points at apply_patch, so a selection without it
+    // re-opens the historical edit deadlock. `extension_forge` is the one safe,
+    // confirmation-gated entry point for creating reusable runtime capabilities.
+    alwaysInclude: ['view_file', 'create_file', 'str_replace_editor', 'apply_patch', 'bash', 'search', 'web_search', 'restore_context', 'remember', 'memory_propose', 'lessons_add', 'lessons_propose', 'lessons_search', 'tool_search', 'extension_forge'],
     useAdaptiveThreshold: true,
     enableCaching: true,
     cacheTTLMs: 5 * 60 * 1000, // 5 minutes
 };
+function requiredToolsForQuery(query) {
+    // A bare shared URL has almost no semantic words for TF-IDF/BM25 to match.
+    // Route YouTube links deterministically to both the local-first caption/video
+    // cascade and web verification. The video pipeline explicitly surfaces
+    // unverified claims and ASR-damaged names; even lite model profiles must be
+    // able to check those against primary sources in the same turn.
+    const required = new Set();
+    if (/https?:\/\/(?:www\.|m\.)?(?:youtube\.com\/(?:watch|shorts|embed|v)(?:[/?])|youtu\.be\/)[^\s]+/i.test(query)) {
+        required.add('understand_video');
+        required.add('web_search');
+    }
+    // Short voice turns carry too little lexical context for the RAG selector.
+    // Fresh-information intents must therefore retain their deterministic tool,
+    // including on lite profiles whose alwaysInclude list is intentionally tiny.
+    if (/\b(?:m[eé]t[eé]o|weather|pr[eé]visions?\s+m[eé]t[eé]o|temp[eé]ratures?|temps\s+qu['’ ]?il\s+fait)\b/i.test(query)) {
+        required.add('weather');
+    }
+    if (/\b(?:bourse|cotation|cours\s+(?:de\s+)?(?:l['’]\s*)?action|indice\s+boursier|cac\s*40|nasdaq|s\s*&\s*p\s*500|stock\s+(?:price|quote))\b/i.test(query)) {
+        required.add('stock_quote');
+    }
+    if (/\b(?:actualit[eé]s?|gros\s+titres|derni[eè]res?\s+infos?|news)\b/i.test(query)) {
+        required.add('web_search');
+    }
+    // Le prompt App Studio est le seul à porter ce marqueur. Son système de
+    // design est une dépendance explicite de génération, pas un simple indice
+    // de pertinence : l'inclure évite un aller-retour tool_search au premier tour.
+    if (query.includes('COMMENCE ta réponse par un plan de développement dans un bloc ```plan') &&
+        query.includes('`design_system`')) {
+        required.add('design_system');
+    }
+    return [...required];
+}
 /**
  * Tool Selection Strategy
  *
@@ -74,6 +114,8 @@ export class ToolSelectionStrategy {
     cachedToolNames = [];
     cacheModelName = null;
     lastQuery = '';
+    /** Query the cached tool set was selected FOR — cache hits require equality. */
+    cachedQuery = '';
     lastSelection = null;
     cacheTimestamp = 0;
     activeSkill = null;
@@ -83,7 +125,7 @@ export class ToolSelectionStrategy {
      * @param config - Optional configuration overrides
      */
     constructor(config = {}) {
-        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.config = { ...DEFAULT_TOOL_SELECTION_CONFIG, ...config };
     }
     /**
      * Select relevant tools for a given query
@@ -96,12 +138,30 @@ export class ToolSelectionStrategy {
      * @returns Selection result with tools and metadata
      */
     async selectToolsForQuery(query, options = {}) {
-        const effectiveConfig = { ...this.config, ...options };
+        const mergedConfig = { ...this.config, ...options };
+        const requiredTools = requiredToolsForQuery(query);
+        // Recovery is part of the observation contract, not a relevance hint.
+        // Keep it available even when a lite profile supplies a smaller
+        // `alwaysInclude` override: once an earlier result was compacted, the
+        // model must never be stranded without the exact callId recovery path.
+        const effectiveConfig = {
+            ...mergedConfig,
+            alwaysInclude: Array.from(new Set([
+                ...mergedConfig.alwaysInclude,
+                'restore_context',
+                ...requiredTools,
+            ])),
+        };
         const modelName = ToolSelectionStrategy.normalizeModelName(effectiveConfig.modelName);
         this.lastQuery = query;
-        // Check if we should use cached tools
-        if (effectiveConfig.enableCaching && this.isCacheValid(modelName)) {
-            logger.debug('Using cached tools for query', { query: query.slice(0, 50) });
+        // Check if we should use cached tools. The cache exists for MULTI-ROUND
+        // consistency within one turn (same query, rounds 2..N) — it must never
+        // leak a PREVIOUS turn's selection into a new user query, or a turn that
+        // needs text_to_speech inherits the tool set of the "pwd" turn before it
+        // (observed live in Cowork: alwaysInclude apparently ignored, tools
+        // "missing" at random depending on the prior turn).
+        if (effectiveConfig.enableCaching && this.cachedQuery === query && this.isCacheValid(modelName)) {
+            logger.debug('Using cached tools for query', { query: query.slice(0, 50), count: this.cachedTools.length });
             return {
                 tools: this.cachedTools,
                 selection: this.lastSelection,
@@ -113,22 +173,45 @@ export class ToolSelectionStrategy {
         let tools;
         let selection = null;
         if (effectiveConfig.useRAG) {
-            // Use RAG-based selection
-            const result = await getRelevantTools(query, {
-                maxTools: effectiveConfig.maxTools,
-                useRAG: true,
-                alwaysInclude: effectiveConfig.alwaysInclude,
-            });
-            tools = result.selectedTools;
-            selection = result;
-            this.lastSelection = result;
-            this.cachedToolNames = result.selectedTools.map(t => t.function.name);
-            logger.debug('RAG tool selection completed', {
-                query: query.slice(0, 50),
-                selectedCount: tools.length,
-                categories: result.classification.categories,
-                tokenSavings: result.originalTokens - result.reducedTokens,
-            });
+            try {
+                // Use RAG-based selection
+                const result = await getRelevantTools(query, {
+                    maxTools: effectiveConfig.maxTools,
+                    useRAG: true,
+                    alwaysInclude: effectiveConfig.alwaysInclude,
+                });
+                tools = result.selectedTools;
+                selection = result;
+                this.lastSelection = result;
+                this.cachedToolNames = result.selectedTools.map(t => t.function.name);
+                logger.debug('RAG tool selection completed', {
+                    query: query.slice(0, 50),
+                    selectedCount: tools.length,
+                    categories: result.classification.categories,
+                    tokenSavings: result.originalTokens - result.reducedTokens,
+                });
+            }
+            catch (error) {
+                // La sélection réduit le prompt mais ne doit jamais empêcher le tour.
+                // En cas d'échec, on garde la génération avec tous les tools disponibles.
+                logger.warn('RAG tool selection failed; using fail-open fallback', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                selection = null;
+                this.lastSelection = null;
+                try {
+                    tools = await getAllCodeBuddyTools();
+                }
+                catch (fallbackError) {
+                    // Même l'assemblage complet est optionnel : un tour sans tool reste
+                    // préférable à une génération bloquée ou rejetée avant le premier token.
+                    logger.warn('Full tool fallback failed; continuing without tools', {
+                        error: fallbackError instanceof Error ? fallbackError.message : String(fallbackError),
+                    });
+                    tools = [];
+                }
+                this.cachedToolNames = tools.map(t => t.function.name);
+            }
         }
         else {
             // Fallback: return all tools
@@ -139,6 +222,12 @@ export class ToolSelectionStrategy {
                 toolCount: tools.length,
             });
         }
+        // `design_system` n'appartient pas à la surface générale : App Studio
+        // reçoit ce schéma fixe uniquement lorsque son marqueur est présent.
+        if (requiredTools.includes('design_system') &&
+            !tools.some((tool) => tool.function.name === 'design_system')) {
+            tools = [...tools, DESIGN_SYSTEM_TOOL];
+        }
         // Augment with skill-required tools if a skill is active
         if (this.activeSkill) {
             tools = getSkillAugmentedTools(tools, this.activeSkill);
@@ -149,6 +238,10 @@ export class ToolSelectionStrategy {
             });
         }
         tools = this.applyModelFacingSchemaFilter(tools, modelName);
+        if (effectiveConfig.allowedToolNames) {
+            const allowed = new Set(effectiveConfig.allowedToolNames);
+            tools = tools.filter((tool) => allowed.has(tool.function.name));
+        }
         this.cachedToolNames = tools.map(t => t.function.name);
         if (selection) {
             selection = {
@@ -191,11 +284,40 @@ export class ToolSelectionStrategy {
         this.cachedToolNames = tools.map(t => t.function.name);
         this.cacheModelName = ToolSelectionStrategy.normalizeModelName(modelName);
         this.cacheTimestamp = Date.now();
+        // The executor calls this right after round 0's selection — the cache
+        // belongs to the query that produced it (this turn's user message).
+        this.cachedQuery = this.lastQuery;
         logger.debug('Tools cached for multi-round consistency', {
             toolCount: tools.length,
             modelName: this.cacheModelName,
         });
     }
+    /**
+     * Expand the CURRENT turn's cached selection with named tools — called by
+     * the executor after a successful `tool_search` so a discovered tool is
+     * actually invocable on the next round (the cache would otherwise re-serve
+     * the same list for the rest of the turn). No-op for unknown names or when
+     * no cache is active.
+     */
+    async expandCachedTools(names) {
+        if (!this.config.enableCaching || !this.cachedTools || names.length === 0)
+            return 0;
+        const have = new Set(this.cachedTools.map((t) => t.function.name));
+        const wanted = names.filter((n) => !have.has(n));
+        if (wanted.length === 0)
+            return 0;
+        const { getAllCodeBuddyTools } = await import('../../codebuddy/tools.js');
+        const all = await getAllCodeBuddyTools();
+        const additions = all.filter((t) => wanted.includes(t.function.name));
+        if (additions.length === 0)
+            return 0;
+        this.cachedTools = [...this.cachedTools, ...additions];
+        this.cachedToolNames = this.cachedTools.map((t) => t.function.name);
+        logger.debug('Tool selection cache expanded via tool_search', {
+            added: additions.map((t) => t.function.name),
+        });
+        return additions.length;
+    }
     /**
      * Get cached tools if available and valid
      *

package/dist/agent/facades/message-history-manager.d.ts

@@ -90,7 +90,7 @@ export declare class MessageHistoryManager {
      *
      * Pattern aligned with Gemini CLI's comprehensive vs curated history
      * distinction (see audit doc
-     * `claude-et-patrice/propositions/AUDIT-GEMINI-CLI-AGENTIC-LOOP-2026-05-04.md`,
+     * the handover repo's `propositions/AUDIT-GEMINI-CLI-AGENTIC-LOOP-2026-05-04.md`,
      * recommendation #3).
      */
     getComprehensiveHistory(): CodeBuddyMessage[];

package/dist/agent/facades/message-history-manager.js

@@ -103,7 +103,7 @@ export class MessageHistoryManager {
      *
      * Pattern aligned with Gemini CLI's comprehensive vs curated history
      * distinction (see audit doc
-     * `claude-et-patrice/propositions/AUDIT-GEMINI-CLI-AGENTIC-LOOP-2026-05-04.md`,
+     * the handover repo's `propositions/AUDIT-GEMINI-CLI-AGENTIC-LOOP-2026-05-04.md`,
      * recommendation #3).
      */
     getComprehensiveHistory() {

package/dist/agent/facades/model-routing-facade.d.ts

@@ -10,6 +10,7 @@
 import type { ModelRouter, RoutingDecision } from '../../optimization/model-routing.js';
 import type { CostTracker } from '../../utils/cost-tracker.js';
 import type { ModelPairsConfig } from '../../config/toml-config.js';
+import { type ModelScoreboard } from '../../fleet/model-scoreboard.js';
 /**
  * Task intent classification used for architect/editor model pair routing.
  */
@@ -34,6 +35,17 @@ export interface ModelRoutingFacadeDeps {
     modelRouter: ModelRouter;
     costTracker: CostTracker;
 }
+/**
+ * Optional injection seams for {@link ModelRoutingFacade.autoRouteIfEnabled}.
+ * Used by tests to supply a deterministic scoreboard / env without touching the
+ * real `~/.codebuddy/fleet-model-performance.jsonl` ledger or `process.env`.
+ */
+export interface AutoRouteOptions {
+    /** Inject a ModelScoreboard (tests). Production uses the singleton. */
+    scoreboard?: ModelScoreboard;
+    /** Inject env (tests). Production reads `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
 /**
  * Facade for model routing and cost management in agents.
  *
@@ -79,10 +91,28 @@ export declare class ModelRoutingFacade {
      *
      * @param userMessage - The user's message to classify
      * @param availableModels - Optional list of available model IDs (defaults to GROK_MODELS keys)
+     * @param opts - Optional test injection seams (scoreboard / env)
      * @returns The recommended model name, or null if auto-routing is disabled
      *          or fewer than 2 models are available
      */
-    autoRouteIfEnabled(userMessage: string, availableModels?: string[]): string | null;
+    autoRouteIfEnabled(userMessage: string, availableModels?: string[], opts?: AutoRouteOptions): string | null;
+    /**
+     * Council-learned tie-break for auto-routing — opt-in via
+     * `CODEBUDDY_COUNCIL_ROUTING=true`. This is the only place the council's
+     * `ModelScoreboard` (trained by `buddy council` runs) feeds the MAIN chat
+     * model choice; without it the scoreboard only steered the voice loop and the
+     * diff reviewer.
+     *
+     * CONSERVATIVE by design — it never overrides a hard constraint (cost,
+     * capacity, a pinned or `/switch`-ed model, the vision requirement all live
+     * upstream). It only arbitrates between the complexity-based
+     * `recommendedModel` and the `alternativeModel` that `selectModel` itself
+     * already surfaced as viable, and only departs from the recommendation when
+     * the scoreboard has ACTUAL run history showing the alternative is the better
+     * AI for this task category. An empty / unseen scoreboard leaves the decision
+     * untouched (silent fallback). Never throws.
+     */
+    private applyScoreboardTieBreak;
     /**
      * Get the model router instance (for advanced operations)
      */

package/dist/agent/facades/model-routing-facade.js

@@ -8,6 +8,11 @@
  * - Routing statistics and savings calculation
  */
 import { classifyTaskComplexity, selectModel, GROK_MODELS } from '../../optimization/model-routing.js';
+import { getModelScoreboard } from '../../fleet/model-scoreboard.js';
+import { inferTaskType } from '../../fleet/model-capability-heuristics.js';
+import { SCOREBOARD_TASK_TYPES } from '../../council/task-types.js';
+import { logger } from '../../utils/logger.js';
+const SCOREBOARD_DIRECT_ROUTING_TASKS = new Set(SCOREBOARD_TASK_TYPES.filter((taskType) => ['redaction-fr', 'arbitrage-litteraire', 'jugement-litteraire', 'audit-adversarial', 'relecture-typo'].includes(taskType)));
 /**
  * Facade for model routing and cost management in agents.
  *
@@ -70,10 +75,11 @@ export class ModelRoutingFacade {
      *
      * @param userMessage - The user's message to classify
      * @param availableModels - Optional list of available model IDs (defaults to GROK_MODELS keys)
+     * @param opts - Optional test injection seams (scoreboard / env)
      * @returns The recommended model name, or null if auto-routing is disabled
      *          or fewer than 2 models are available
      */
-    autoRouteIfEnabled(userMessage, availableModels) {
+    autoRouteIfEnabled(userMessage, availableModels, opts) {
         if (!this.autoRoutingEnabled) {
             return null;
         }
@@ -82,10 +88,88 @@ export class ModelRoutingFacade {
             return null;
         }
         const classification = classifyTaskComplexity(userMessage);
-        const decision = selectModel(classification, undefined, models);
+        let decision = selectModel(classification, undefined, models);
+        // Opt-in council-learned tie-break (CODEBUDDY_COUNCIL_ROUTING). Default OFF
+        // is a STRICT no-op: the branch is skipped entirely, so no ModelScoreboard
+        // is constructed, no ledger file is read, and no latency is added.
+        const env = opts?.env ?? process.env;
+        if (env.CODEBUDDY_COUNCIL_ROUTING === 'true') {
+            decision = this.applyScoreboardTieBreak(decision, userMessage, models, opts?.scoreboard);
+        }
         this.lastRoutingDecision = decision;
         return decision.recommendedModel;
     }
+    /**
+     * Council-learned tie-break for auto-routing — opt-in via
+     * `CODEBUDDY_COUNCIL_ROUTING=true`. This is the only place the council's
+     * `ModelScoreboard` (trained by `buddy council` runs) feeds the MAIN chat
+     * model choice; without it the scoreboard only steered the voice loop and the
+     * diff reviewer.
+     *
+     * CONSERVATIVE by design — it never overrides a hard constraint (cost,
+     * capacity, a pinned or `/switch`-ed model, the vision requirement all live
+     * upstream). It only arbitrates between the complexity-based
+     * `recommendedModel` and the `alternativeModel` that `selectModel` itself
+     * already surfaced as viable, and only departs from the recommendation when
+     * the scoreboard has ACTUAL run history showing the alternative is the better
+     * AI for this task category. An empty / unseen scoreboard leaves the decision
+     * untouched (silent fallback). Never throws.
+     */
+    applyScoreboardTieBreak(decision, userMessage, models, scoreboardOverride) {
+        try {
+            const alt = decision.alternativeModel;
+            // Only a genuine {recommended, alternative} ambiguity is a tie to break.
+            if (!alt || alt === decision.recommendedModel || !models.includes(alt)) {
+                return decision;
+            }
+            const sb = scoreboardOverride ?? getModelScoreboard();
+            const taskType = inferTaskType(userMessage);
+            const rec = decision.recommendedModel;
+            // Literary benchmark categories are not represented by the legacy Grok
+            // complexity table. When one is observed in the scoreboard, select the
+            // best available measured model directly; all legacy categories retain
+            // the original recommended/alternative-only tie-break below.
+            if (SCOREBOARD_DIRECT_ROUTING_TASKS.has(taskType)) {
+                const best = sb.best(taskType, models);
+                if (best && sb.runCount(taskType, best.model) > 0 && best.model !== rec) {
+                    logger.debug(`[council-routing] scoreboard selects ${best.model} for ${taskType} `
+                        + `(win ${best.winRate.toFixed(2)}, quality ${best.avgQuality.toFixed(2)})`);
+                    return {
+                        ...decision,
+                        recommendedModel: best.model,
+                        tier: GROK_MODELS[best.model]?.tier ?? 'standard',
+                        reason: `${decision.reason} | council-routing: ${best.model} measured best for ${taskType}`,
+                        alternativeModel: rec,
+                        alternativeReason: decision.reason,
+                    };
+                }
+                return decision;
+            }
+            const recBias = sb.selectionBias(taskType, rec);
+            const altBias = sb.selectionBias(taskType, alt);
+            // Depart from the recommendation only on real evidence: the alternative
+            // must both out-score the recommendation AND have observed runs. Selection
+            // bias is a neutral 0 for unseen models, so an empty scoreboard can never
+            // satisfy `altBias > recBias` with `runCount > 0` → guaranteed fallback.
+            if (altBias > recBias && sb.runCount(taskType, alt) > 0) {
+                logger.debug(`[council-routing] scoreboard prefers ${alt} over ${rec} for ${taskType} ` +
+                    `(bias ${altBias.toFixed(2)} > ${recBias.toFixed(2)})`);
+                return {
+                    ...decision,
+                    recommendedModel: alt,
+                    tier: GROK_MODELS[alt]?.tier ?? decision.tier,
+                    reason: `${decision.reason} | council-routing: ${alt} historically stronger for ${taskType} tasks`,
+                    alternativeModel: rec,
+                    alternativeReason: decision.reason,
+                };
+            }
+            return decision;
+        }
+        catch (err) {
+            logger.debug(`[council-routing] tie-break skipped: ${err instanceof Error ? err.message : String(err)}`);
+            return decision;
+        }
+    }
     /**
      * Get the model router instance (for advanced operations)
      */

package/dist/agent/facades/session-facade.d.ts

@@ -8,7 +8,7 @@
  * - Session export functionality
  */
 import type { CheckpointManager } from '../../checkpoints/checkpoint-manager.js';
-import type { SessionStore } from '../../persistence/session-store.js';
+import type { Session, SessionStore, SessionUsageSnapshot } from '../../persistence/session-store.js';
 import type { ChatEntry } from '../types.js';
 /**
  * Result of a checkpoint rewind operation
@@ -37,6 +37,7 @@ export declare class SessionFacade {
     private readonly sessionStore;
     private encryption;
     private encryptionInitialized;
+    private attachUsageIfSupported;
     constructor(deps: SessionFacadeDeps);
     /**
      * Lazily initialize session encryption if enabled via SESSION_ENCRYPTION env var
@@ -65,7 +66,7 @@ export declare class SessionFacade {
     /**
      * Save the current chat history to the session
      */
-    saveCurrentSession(chatHistory: ChatEntry[]): Promise<void>;
+    saveCurrentSession(chatHistory: ChatEntry[], usage?: SessionUsageSnapshot): Promise<void>;
     /**
      * Get formatted list of sessions
      */
@@ -79,4 +80,11 @@ export declare class SessionFacade {
      * Get the current session ID
      */
     getCurrentSessionId(): string | null;
+    /** Load a persisted session through the canonical session store. */
+    loadSession(sessionId: string): Promise<Session | null>;
+    /**
+     * Fork a session at a timeline boundary while preserving the existing
+     * on-disk session format. The source session is never modified.
+     */
+    forkSessionAtTurn(sourceSessionId: string, newSessionId: string, turn: number): Promise<Session>;
 }