@phuetz/code-buddy 1.6.1 → 2.1.0

package/dist/fleet/model-scoreboard.d.ts

@@ -2,31 +2,54 @@
  * Model Scoreboard — the learning layer for the multi-LLM council.
  *
  * Records, per (taskType × model), the outcome of each council run (won?,
- * judge quality 0-1, latency, cost) to an append-only JSON ledger under
- * ~/.codebuddy/fleet-model-performance.json (same spirit as cost-tracker.ts).
+ * optional role, judge quality 0-1, latency, cost) to an append-only JSONL
+ * ledger under ~/.codebuddy/fleet-model-performance.jsonl (one record per
+ * line — O(1) appends, and concurrent writers — CLI + voice loop + server —
+ * interleave lines instead of overwriting each other). A legacy pretty-JSON
+ * array ledger (the pre-v2 format) is migrated in place on first load.
  *
- * The council reads `winRate(taskType, model)` to bias model selection toward
- * the historically-best AI for that kind of task, and `ranking(taskType)` to
- * show what it has learned. This is the piece the Fleet was missing: dispatch +
- * ensemble + consensus existed; *learning which model is best over time* did not.
+ * The council reads `selectionBias(taskType, model)` to bias model selection
+ * toward the historically-best AI for that kind of task: it is Laplace-
+ * smoothed and confidence-weighted so a model with 1 win in 1 run does NOT
+ * outrank one with 9 wins in 10, and unseen models sit at a neutral 0 instead
+ * of being locked out by early winners. `ranking(taskType)` shows what it has
+ * learned (raw wins/runs, human-readable).
  */
+import type { TaskType } from '../council/task-types.js';
 export interface OutcomeRecord {
     /** ISO timestamp of the run. */
     at: string;
     /** Inferred or supplied task category (e.g. 'code', 'reasoning', 'french'). */
-    taskType: string;
+    taskType: TaskType;
     /** Model id (e.g. 'gpt-5.5', 'grok-3'). */
     model: string;
     /** Provider id (e.g. 'chatgpt', 'grok'). */
     provider: string;
+    /** Optional council role played by this answer (e.g. 'reviewer', 'verifier'). */
+    role?: string;
     /** Did this model win the judge's vote this run? */
     won: boolean;
-    /** Judge quality score for this answer, 0-1. */
+    /** Judge TASK-fit score for this answer, 0-1. */
     quality: number;
+    /**
+     * Judge ROLE-fit score, 0-1 — did the answer hold its council role? Feeds
+     * `roleScore` so specialised roles (critic, verifier) are no longer punished
+     * for doing their job instead of answering the task directly. Absent on
+     * legacy records — `roleScore` falls back to `quality`.
+     */
+    roleQuality?: number;
     /** Wall-clock latency of this model's answer (ms). */
     latencyMs: number;
     /** Marginal cost of this answer in USD (0 for local / flat-fee). */
     costUsd: number;
+    /**
+     * True when the model FAILED to answer (timeout, 404, empty reply) rather
+     * than losing on quality. Failed records count as losses in
+     * `smoothedWinRate`/`runCount` (so `selectionBias` stops re-seating dead
+     * models and ε-exploration stops treating them as unseen), but are EXCLUDED
+     * from `winRate`/`ranking`/`print` — a 404 is not a quality defeat.
+     */
+    failed?: boolean;
 }
 export interface ModelStat {
     model: string;
@@ -39,16 +62,98 @@ export interface ModelStat {
     avgLatencyMs: number;
     avgCostUsd: number;
 }
+export interface RoleModelStat {
+    role: string;
+    model: string;
+    provider: string;
+    runs: number;
+    wins: number;
+    winRate: number;
+    avgQuality: number;
+}
+export interface MeasuredTurnLatency {
+    latencyMs: number;
+    samples: number;
+    metric: 'ttfm-p50';
+}
+export interface ModelScoreboardOptions {
+    turnMetricsJournalPath?: string;
+}
+export interface ScoreboardImportResult {
+    imported: number;
+    skippedDuplicates: number;
+    rejected: number;
+}
+/** Stable append/import identity required by the SCORE1 bench importer. */
+export declare function outcomeKey(record: Pick<OutcomeRecord, 'at' | 'model' | 'taskType'>): string;
+export declare function isOutcomeRecord(value: unknown): value is OutcomeRecord;
 export declare class ModelScoreboard {
-    private readonly file;
     private records;
-    constructor(file?: string);
+    private cachedMtimeMs;
+    private readonly file;
+    private readonly turnMetricsJournalPath;
+    private turnMetricsMtimeMs;
+    private turnMetricsAggregates;
+    constructor(file?: string, options?: ModelScoreboardOptions);
+    /** The pre-v2 array ledger sits next to the JSONL one, `.jsonl` → `.json`. */
+    private legacyFile;
+    private statMtimeMs;
+    private measuredTurnAggregates;
+    /**
+     * Precise streamed-turn latency for routing. TTFM p50 is used only after
+     * enough complete messages exist; failed/no-message turns cannot create a
+     * deceptively fast routing signal.
+     */
+    measuredTurnLatency(provider: string, model: string, minimumSamples?: number): MeasuredTurnLatency | null;
+    /** Pick up records appended by OTHER processes since our last read. */
+    private maybeReload;
     private load;
-    private save;
-    /** Append one model's outcome for a run and persist. */
+    private rewriteAsJsonl;
+    /** Append one model's outcome for a run and persist (O(1), concurrent-safe append). */
     recordOutcome(rec: OutcomeRecord): void;
-    /** Historical win rate (0-1) of a model for a task type. 0 when never seen. */
+    /**
+     * Append validated records while ignoring an already-known
+     * `(at, model, taskType)` identity. Existing council writes remain untouched;
+     * this stricter path is used by external benchmark imports.
+     */
+    importRecords(records: readonly OutcomeRecord[]): ScoreboardImportResult;
+    /** Read a JSONL benchmark file and append only valid, unseen records. */
+    importJsonl(sourceFile: string): ScoreboardImportResult;
+    /** Best measured model for a task, optionally restricted to active models. */
+    best(taskType: string, candidates?: readonly string[]): ModelStat | null;
+    private runsFor;
+    /** Raw historical win rate (0-1) of a model for a task type. 0 when never seen. Display only. */
     winRate(taskType: string, model: string): number;
+    /** How many council runs this (taskType × model) has been observed in. */
+    runCount(taskType: string, model: string): number;
+    /** Laplace-smoothed win rate: (wins + 1) / (runs + 2). 0.5 when never seen. */
+    smoothedWinRate(taskType: string, model: string): number;
+    /** How much to trust this model's history: runs / (runs + K). 0 when never seen. */
+    historyWeight(taskType: string, model: string): number;
+    /**
+     * Selection bias for routing, in [-1, 1]: smoothed win rate re-centred on 0
+     * and weighted by history confidence. Unseen models sit at 0 (neutral); a
+     * 1/1 model gets a small nudge (~+0.06), a 9/10 one a strong one (~+0.44),
+     * and consistent losers go negative. Replaces the raw `(1 + winRate)`
+     * multiplier that locked in the first-ever winner.
+     */
+    selectionBias(taskType: string, model: string): number;
+    /**
+     * Historical role-specific score for assigning future council roles. 0 when
+     * never seen. Weighted toward the judge's ROLE-fit quality (not the task
+     * win): a critic that consistently holds its role must rank high for the
+     * critic seat even though critics rarely win the task vote — the old
+     * win-rate-dominant formula was training role erosion.
+     */
+    roleScore(taskType: string, role: string, model: string): number;
+    /**
+     * Trailing consecutive failures for a model ACROSS task types (most recent
+     * records first). Used to exclude dead models from the judge seat — a
+     * retired catalog model kept being re-picked as judge, aborting every
+     * deliberation, because failure penalties only applied to panel seats.
+     */
+    consecutiveRecentFailures(model: string): number;
+    roleRanking(taskType?: string, role?: string): RoleModelStat[];
     /**
      * Per-model aggregate stats, optionally scoped to one task type, sorted by
      * win rate desc then avg quality desc.

package/dist/fleet/model-scoreboard.js

@@ -2,38 +2,159 @@
  * Model Scoreboard — the learning layer for the multi-LLM council.
  *
  * Records, per (taskType × model), the outcome of each council run (won?,
- * judge quality 0-1, latency, cost) to an append-only JSON ledger under
- * ~/.codebuddy/fleet-model-performance.json (same spirit as cost-tracker.ts).
+ * optional role, judge quality 0-1, latency, cost) to an append-only JSONL
+ * ledger under ~/.codebuddy/fleet-model-performance.jsonl (one record per
+ * line — O(1) appends, and concurrent writers — CLI + voice loop + server —
+ * interleave lines instead of overwriting each other). A legacy pretty-JSON
+ * array ledger (the pre-v2 format) is migrated in place on first load.
  *
- * The council reads `winRate(taskType, model)` to bias model selection toward
- * the historically-best AI for that kind of task, and `ranking(taskType)` to
- * show what it has learned. This is the piece the Fleet was missing: dispatch +
- * ensemble + consensus existed; *learning which model is best over time* did not.
+ * The council reads `selectionBias(taskType, model)` to bias model selection
+ * toward the historically-best AI for that kind of task: it is Laplace-
+ * smoothed and confidence-weighted so a model with 1 win in 1 run does NOT
+ * outrank one with 9 wins in 10, and unseen models sit at a neutral 0 instead
+ * of being locked out by early winners. `ranking(taskType)` shows what it has
+ * learned (raw wins/runs, human-readable).
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { logger } from '../utils/logger.js';
+import { readJsonLinesAtomicSync, readTextAtomicSync, writeFileAtomicSync } from '../utils/atomic-write.js';
+import { defaultTurnMetricsJournalPath, readTurnMetricsAggregates, } from '../observability/turn-metrics.js';
 function defaultLedgerPath() {
-    return path.join(os.homedir(), '.codebuddy', 'fleet-model-performance.json');
+    return path.join(os.homedir(), '.codebuddy', 'fleet-model-performance.jsonl');
 }
+/**
+ * Conductor panels repeat roles on extra seats; historically those seats got
+ * suffixed ids ('reviewer-4') that fragmented role history by panel position.
+ * Normalising here also heals any such legacy records at query time.
+ */
+function normalizeRole(role) {
+    return role.replace(/-\d+$/, '');
+}
+/** Stable append/import identity required by the SCORE1 bench importer. */
+export function outcomeKey(record) {
+    return `${record.at}\u0000${record.model}\u0000${record.taskType}`;
+}
+export function isOutcomeRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const record = value;
+    return Boolean(typeof record.at === 'string' && record.at.length > 0
+        && typeof record.taskType === 'string' && record.taskType.length > 0
+        && typeof record.model === 'string' && record.model.length > 0
+        && typeof record.provider === 'string' && record.provider.length > 0
+        && typeof record.won === 'boolean'
+        && typeof record.quality === 'number' && Number.isFinite(record.quality)
+        && record.quality >= 0 && record.quality <= 1
+        && typeof record.latencyMs === 'number' && Number.isFinite(record.latencyMs)
+        && record.latencyMs >= 0
+        && typeof record.costUsd === 'number' && Number.isFinite(record.costUsd)
+        && record.costUsd >= 0
+        && (record.role === undefined || typeof record.role === 'string')
+        && (record.roleQuality === undefined
+            || (typeof record.roleQuality === 'number'
+                && Number.isFinite(record.roleQuality)
+                && record.roleQuality >= 0
+                && record.roleQuality <= 1))
+        && (record.failed === undefined || typeof record.failed === 'boolean'));
+}
+/** History weight saturation: with K=5, 5 runs ≈ half-trust, 20 runs ≈ 0.8. */
+const HISTORY_WEIGHT_K = 5;
 export class ModelScoreboard {
-    file;
     records = [];
-    constructor(file = defaultLedgerPath()) {
+    cachedMtimeMs = -1;
+    file;
+    turnMetricsJournalPath;
+    turnMetricsMtimeMs = -1;
+    turnMetricsAggregates = [];
+    constructor(file = defaultLedgerPath(), options = {}) {
         this.file = file;
+        this.turnMetricsJournalPath = options.turnMetricsJournalPath ?? defaultTurnMetricsJournalPath();
         this.load();
     }
+    /** The pre-v2 array ledger sits next to the JSONL one, `.jsonl` → `.json`. */
+    legacyFile() {
+        return this.file.endsWith('.jsonl') ? this.file.slice(0, -1) : null;
+    }
+    statMtimeMs() {
+        try {
+            return fs.statSync(this.file).mtimeMs;
+        }
+        catch {
+            return -1;
+        }
+    }
+    measuredTurnAggregates() {
+        let mtimeMs = -1;
+        try {
+            mtimeMs = fs.statSync(this.turnMetricsJournalPath).mtimeMs;
+        }
+        catch {
+            // A missing journal is the normal cold-start state.
+        }
+        if (mtimeMs !== this.turnMetricsMtimeMs) {
+            this.turnMetricsAggregates = readTurnMetricsAggregates(this.turnMetricsJournalPath);
+            this.turnMetricsMtimeMs = mtimeMs;
+        }
+        return this.turnMetricsAggregates;
+    }
+    /**
+     * Precise streamed-turn latency for routing. TTFM p50 is used only after
+     * enough complete messages exist; failed/no-message turns cannot create a
+     * deceptively fast routing signal.
+     */
+    measuredTurnLatency(provider, model, minimumSamples = 3) {
+        const wantedProvider = provider.toLowerCase();
+        const wantedModel = model.toLowerCase();
+        const aggregate = this.measuredTurnAggregates().find((item) => item.provider.toLowerCase() === wantedProvider
+            && item.model.toLowerCase() === wantedModel);
+        if (!aggregate
+            || aggregate.ttfmSamples < minimumSamples
+            || aggregate.ttfmP50Ms === undefined) {
+            return null;
+        }
+        return {
+            latencyMs: aggregate.ttfmP50Ms,
+            samples: aggregate.ttfmSamples,
+            metric: 'ttfm-p50',
+        };
+    }
+    /** Pick up records appended by OTHER processes since our last read. */
+    maybeReload() {
+        const mtime = this.statMtimeMs();
+        if (mtime !== this.cachedMtimeMs)
+            this.load();
+    }
     load() {
         try {
-            if (!fs.existsSync(this.file))
-                return;
-            const raw = fs.readFileSync(this.file, 'utf-8').trim();
-            if (!raw)
+            let raw = '';
+            let sourcePath = this.file;
+            if (fs.existsSync(this.file)) {
+                raw = readTextAtomicSync(this.file, '').trim();
+            }
+            else {
+                const legacy = this.legacyFile();
+                if (legacy && fs.existsSync(legacy)) {
+                    sourcePath = legacy;
+                    raw = readTextAtomicSync(legacy, '').trim();
+                }
+            }
+            if (!raw) {
+                this.records = [];
+                this.cachedMtimeMs = this.statMtimeMs();
                 return;
-            const parsed = JSON.parse(raw);
-            if (Array.isArray(parsed))
-                this.records = parsed;
+            }
+            if (raw.startsWith('[')) {
+                // Legacy pretty-JSON array (or a legacy .json ledger) — migrate to JSONL.
+                const parsed = JSON.parse(raw);
+                this.records = Array.isArray(parsed) ? parsed : [];
+                this.rewriteAsJsonl();
+            }
+            else {
+                this.records = readJsonLinesAtomicSync(sourcePath, [], isOutcomeRecord);
+            }
+            this.cachedMtimeMs = this.statMtimeMs();
         }
         catch (err) {
             logger.warn?.('[model-scoreboard] could not read ledger, starting empty', {
@@ -42,10 +163,26 @@ export class ModelScoreboard {
             this.records = [];
         }
     }
-    save() {
+    rewriteAsJsonl() {
+        try {
+            writeFileAtomicSync(this.file, this.records.map((r) => JSON.stringify(r)).join('\n') + (this.records.length ? '\n' : ''), { mode: 0o600 });
+            this.cachedMtimeMs = this.statMtimeMs();
+        }
+        catch (err) {
+            logger.warn?.('[model-scoreboard] could not migrate ledger to JSONL', {
+                err: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /** Append one model's outcome for a run and persist (O(1), concurrent-safe append). */
+    recordOutcome(rec) {
+        const normalized = rec.role ? { ...rec, role: normalizeRole(rec.role) } : rec;
+        this.maybeReload();
+        this.records.push(normalized);
         try {
             fs.mkdirSync(path.dirname(this.file), { recursive: true });
-            fs.writeFileSync(this.file, JSON.stringify(this.records, null, 2), 'utf-8');
+            fs.appendFileSync(this.file, JSON.stringify(normalized) + '\n', { encoding: 'utf8', mode: 0o600 });
+            this.cachedMtimeMs = this.statMtimeMs();
         }
         catch (err) {
             logger.warn?.('[model-scoreboard] could not write ledger', {
@@ -53,27 +190,190 @@ export class ModelScoreboard {
             });
         }
     }
-    /** Append one model's outcome for a run and persist. */
-    recordOutcome(rec) {
-        this.records.push(rec);
-        this.save();
+    /**
+     * Append validated records while ignoring an already-known
+     * `(at, model, taskType)` identity. Existing council writes remain untouched;
+     * this stricter path is used by external benchmark imports.
+     */
+    importRecords(records) {
+        this.maybeReload();
+        const known = new Set(this.records.map(outcomeKey));
+        const pending = [];
+        let skippedDuplicates = 0;
+        for (const record of records) {
+            const normalized = record.role ? { ...record, role: normalizeRole(record.role) } : record;
+            const key = outcomeKey(normalized);
+            if (known.has(key)) {
+                skippedDuplicates++;
+                continue;
+            }
+            known.add(key);
+            pending.push(normalized);
+        }
+        if (pending.length === 0) {
+            return { imported: 0, skippedDuplicates, rejected: 0 };
+        }
+        try {
+            fs.mkdirSync(path.dirname(this.file), { recursive: true });
+            fs.appendFileSync(this.file, pending.map((record) => JSON.stringify(record)).join('\n') + '\n', { encoding: 'utf8', mode: 0o600 });
+            this.records.push(...pending);
+            this.cachedMtimeMs = this.statMtimeMs();
+            return { imported: pending.length, skippedDuplicates, rejected: 0 };
+        }
+        catch (err) {
+            logger.warn?.('[model-scoreboard] could not import ledger records', {
+                err: err instanceof Error ? err.message : String(err),
+            });
+            return { imported: 0, skippedDuplicates, rejected: 0 };
+        }
+    }
+    /** Read a JSONL benchmark file and append only valid, unseen records. */
+    importJsonl(sourceFile) {
+        if (!fs.existsSync(sourceFile)) {
+            throw new Error(`Benchmark file not found: ${sourceFile}`);
+        }
+        const raw = fs.readFileSync(sourceFile, 'utf8');
+        const records = [];
+        let rejected = 0;
+        for (const line of raw.split(/\r?\n/)) {
+            if (!line.trim())
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (!isOutcomeRecord(parsed)) {
+                    rejected++;
+                    continue;
+                }
+                records.push(parsed);
+            }
+            catch {
+                rejected++;
+            }
+        }
+        const result = this.importRecords(records);
+        return { ...result, rejected };
     }
-    /** Historical win rate (0-1) of a model for a task type. 0 when never seen. */
+    /** Best measured model for a task, optionally restricted to active models. */
+    best(taskType, candidates) {
+        const allowed = candidates ? new Set(candidates) : null;
+        return this.ranking(taskType).find((stat) => !allowed || allowed.has(stat.model)) ?? null;
+    }
+    runsFor(taskType, model) {
+        this.maybeReload();
+        return this.records.filter((r) => r.taskType === taskType && r.model === model);
+    }
+    /** Raw historical win rate (0-1) of a model for a task type. 0 when never seen. Display only. */
     winRate(taskType, model) {
-        const runs = this.records.filter((r) => r.taskType === taskType && r.model === model);
+        const runs = this.runsFor(taskType, model).filter((r) => !r.failed);
         if (runs.length === 0)
             return 0;
         const wins = runs.filter((r) => r.won).length;
         return wins / runs.length;
     }
+    /** How many council runs this (taskType × model) has been observed in. */
+    runCount(taskType, model) {
+        return this.runsFor(taskType, model).length;
+    }
+    /** Laplace-smoothed win rate: (wins + 1) / (runs + 2). 0.5 when never seen. */
+    smoothedWinRate(taskType, model) {
+        const runs = this.runsFor(taskType, model);
+        const wins = runs.filter((r) => r.won).length;
+        return (wins + 1) / (runs.length + 2);
+    }
+    /** How much to trust this model's history: runs / (runs + K). 0 when never seen. */
+    historyWeight(taskType, model) {
+        const runs = this.runCount(taskType, model);
+        return runs / (runs + HISTORY_WEIGHT_K);
+    }
+    /**
+     * Selection bias for routing, in [-1, 1]: smoothed win rate re-centred on 0
+     * and weighted by history confidence. Unseen models sit at 0 (neutral); a
+     * 1/1 model gets a small nudge (~+0.06), a 9/10 one a strong one (~+0.44),
+     * and consistent losers go negative. Replaces the raw `(1 + winRate)`
+     * multiplier that locked in the first-ever winner.
+     */
+    selectionBias(taskType, model) {
+        const centred = (this.smoothedWinRate(taskType, model) - 0.5) * 2;
+        const bias = centred * this.historyWeight(taskType, model);
+        return Math.max(-1, Math.min(1, bias));
+    }
+    /**
+     * Historical role-specific score for assigning future council roles. 0 when
+     * never seen. Weighted toward the judge's ROLE-fit quality (not the task
+     * win): a critic that consistently holds its role must rank high for the
+     * critic seat even though critics rarely win the task vote — the old
+     * win-rate-dominant formula was training role erosion.
+     */
+    roleScore(taskType, role, model) {
+        const wanted = normalizeRole(role);
+        this.maybeReload();
+        const runs = this.records.filter((r) => !r.failed && r.taskType === taskType && r.role !== undefined && normalizeRole(r.role) === wanted && r.model === model);
+        if (runs.length === 0)
+            return 0;
+        const wins = runs.filter((r) => r.won).length;
+        const winRate = wins / runs.length;
+        const avgRoleQuality = runs.reduce((acc, r) => acc + (r.roleQuality ?? r.quality), 0) / runs.length;
+        return 0.7 * avgRoleQuality + 0.3 * winRate;
+    }
+    /**
+     * Trailing consecutive failures for a model ACROSS task types (most recent
+     * records first). Used to exclude dead models from the judge seat — a
+     * retired catalog model kept being re-picked as judge, aborting every
+     * deliberation, because failure penalties only applied to panel seats.
+     */
+    consecutiveRecentFailures(model) {
+        this.maybeReload();
+        let count = 0;
+        for (let i = this.records.length - 1; i >= 0; i--) {
+            const r = this.records[i];
+            if (r.model !== model)
+                continue;
+            if (!r.failed)
+                break;
+            count++;
+        }
+        return count;
+    }
+    roleRanking(taskType, role) {
+        this.maybeReload();
+        const wanted = role ? normalizeRole(role) : undefined;
+        const scoped = this.records.filter((r) => !r.failed &&
+            Boolean(r.role) &&
+            (!taskType || r.taskType === taskType) &&
+            (!wanted || normalizeRole(r.role) === wanted));
+        const byRoleModel = new Map();
+        for (const r of scoped) {
+            const key = `${normalizeRole(r.role)}${r.model}`;
+            const arr = byRoleModel.get(key) ?? [];
+            arr.push(r);
+            byRoleModel.set(key, arr);
+        }
+        const stats = [];
+        for (const runs of byRoleModel.values()) {
+            const first = runs[0];
+            const wins = runs.filter((r) => r.won).length;
+            const n = runs.length;
+            stats.push({
+                role: normalizeRole(first.role),
+                model: first.model,
+                provider: first.provider,
+                runs: n,
+                wins,
+                winRate: wins / n,
+                avgQuality: runs.reduce((acc, r) => acc + r.quality, 0) / n,
+            });
+        }
+        return stats.sort((a, b) => a.role.localeCompare(b.role) || b.winRate - a.winRate || b.avgQuality - a.avgQuality);
+    }
     /**
      * Per-model aggregate stats, optionally scoped to one task type, sorted by
      * win rate desc then avg quality desc.
      */
     ranking(taskType) {
-        const scoped = taskType
+        this.maybeReload();
+        const scoped = (taskType
             ? this.records.filter((r) => r.taskType === taskType)
-            : this.records;
+            : this.records).filter((r) => !r.failed);
         const byModel = new Map();
         for (const r of scoped) {
             const arr = byModel.get(r.model) ?? [];
@@ -115,7 +415,19 @@ export class ModelScoreboard {
             const cost = s.avgCostUsd === 0 ? '$0' : `$${s.avgCostUsd.toFixed(4)}`;
             return `  ${i + 1}. ${s.model.padEnd(22)} win ${wr.padStart(4)} (${s.wins}/${s.runs})  q${q}  ${lat}  ${cost}`;
         });
-        return [header, ...lines].join('\n');
+        const roleRows = this.roleRanking(taskType);
+        if (roleRows.length === 0)
+            return [header, ...lines].join('\n');
+        const bestByRole = new Map();
+        for (const row of roleRows) {
+            if (!bestByRole.has(row.role))
+                bestByRole.set(row.role, row);
+        }
+        const roleLines = Array.from(bestByRole.values()).map((s) => {
+            const wr = `${Math.round(s.winRate * 100)}%`;
+            return `  ${s.role.padEnd(14)} ${s.model.padEnd(22)} win ${wr.padStart(4)} (${s.wins}/${s.runs})  q${s.avgQuality.toFixed(2)}`;
+        });
+        return [header, ...lines, '', 'Role specialists:', ...roleLines].join('\n');
     }
 }
 let singleton = null;

package/dist/fleet/model-selector.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Latency-aware LLM selector — picks the LLM best suited to a task, with a
+ * latency objective for real-time use (the voice loop, where a 16s reply kills
+ * the illusion of a companion). It REUSES the council's "which LLM is best"
+ * system rather than reinventing it:
+ *
+ *   - candidate LLMs  ← buildActiveLlmRegistry (cloud / subscription, one model each)
+ *                       + getLocalCapabilities (EVERY probed local model — the registry
+ *                         collapses each local provider to a single model, which would
+ *                         hide qwen2.5:7b vs gemma vs the 27Bs from the ranking)
+ *   - capability floor ← council inferStrengths / inferTaskType (drop embed/vision-only)
+ *   - learned latency  ← ModelScoreboard.avgLatencyMs (measured on real council runs)
+ *   - cold-start       ← size / "fast"-name heuristic until the scoreboard has data
+ *
+ * Latency-first, but GATED by a capability floor: the globally-fastest model
+ * (a 1B vision model) is useless for a French chat, so we pick min-latency
+ * AMONG models that clear the floor. Cost is only a tie-break (the user asked
+ * for *latency*) — a flat-fee subscription model like grok-3-fast can be both
+ * the fastest AND $0-marginal, so we must not exclude it on the registry's
+ * nominal $/Mtok. `localOnly` is the privacy escape hatch.
+ *
+ * Never-throws: any failure → null, and the caller falls back to its own
+ * default. Stateless (no singleton) so it stays deterministically testable —
+ * inject `candidates` + `scoreboard` to rank without touching the network.
+ *
+ * @module fleet/model-selector
+ */
+import type { ModelStrength } from './types.js';
+import { type ModelScoreboard } from './model-scoreboard.js';
+/** One LLM the selector can choose, normalised across cloud + local sources. */
+export interface LlmCandidate {
+    provider: string;
+    model: string;
+    apiKey?: string;
+    baseURL?: string;
+    /** On-box runtime (Ollama / LM Studio) — eligible under `localOnly`. */
+    isLocal: boolean;
+    /** Nominal input $/Mtok (0 for local + OAuth subscriptions). Tie-break only. */
+    costInputUsdPerMtok: number;
+    strengths: ModelStrength[];
+}
+/** The chosen model, ready to drop into `new CodeBuddyClient(apiKey, model, baseURL)`. */
+export interface ModelSelection {
+    provider: string;
+    model: string;
+    apiKey?: string;
+    baseURL?: string;
+    isLocal: boolean;
+    /** Latency (ms) used to rank — measured when available, else heuristic. */
+    estLatencyMs: number;
+    /** True when `estLatencyMs` came from the scoreboard (measured), false = guessed. */
+    measured: boolean;
+    /** Human-readable rationale, for logs. */
+    reason: string;
+}
+export interface SelectFastestOptions {
+    /** Task type override; else inferred from the task text. */
+    taskType?: string;
+    /** Only consider on-box ($0, never-leaves-the-machine) models — privacy. */
+    localOnly?: boolean;
+    /** Only consider $0-nominal models. Default false (a flat-fee cloud model can be fastest). */
+    freeOnly?: boolean;
+    /** Require reliable structured tool calls (the future spoken-command agent turn). */
+    requireToolCalling?: boolean;
+    /**
+     * Prefer a specific model (case-insensitive substring of its id) when it is
+     * among the qualifying candidates — used to pin the council triage model via
+     * `CODEBUDDY_COUNCIL_TRIAGE_MODEL`. Falls through to latency ranking when the
+     * pin matches nothing active (we can't select a model that isn't there).
+     */
+    preferModel?: string;
+    /** Inject candidates for tests (skips the registry + local probe). */
+    candidates?: LlmCandidate[];
+    /** Inject a scoreboard for tests. */
+    scoreboard?: ModelScoreboard;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Pick the lowest-latency LLM that can do the task. Returns null when nothing
+ * qualifies (no active LLMs, all filtered out, or any failure) — the caller
+ * should fall back to its own default.
+ */
+export declare function selectFastestModel(task: string, opts?: SelectFastestOptions): Promise<ModelSelection | null>;