@polderlabs/bizar 10.17.0 → 10.17.3

package/cli/commands/hook.mjs

@@ -248,7 +248,7 @@ export function selectEventChain(eventKey, input = '') {
   if (eventKey === 'subagent-start') {
     return chain.filter((leaf) => {
       if (leaf === 'advisor-context') {
-        return /^(linda|karen|carl|qa-reviewer|principal-engineer|debug-specialist)$/.test(agentType);
+        return /^(linda|carl)$/.test(agentType);
       }
       if (leaf === 'worktree-bootstrap') {
         return /^(brad|carl|pam|brenda|karen|todd|ria)$/.test(agentType);

package/cli/commands/models.mjs

@@ -21,10 +21,11 @@ import chalk from 'chalk';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
+import readline from 'node:readline';
 
 import {
   rankUserSelectedForRole as rankUserSelectedForRoleMirror,
-} from '../../packages/sdk/src/router/failover-mirror.mjs';
+} from '../../packages/sdk/dist/router/failover-mirror.mjs';
 
 // ── Endpoint resolution ──────────────────────────────────────────────────────
 
@@ -696,7 +697,7 @@ function explainRankedEntry(entry) {
  * Pure function over `routerPath` — no stdout I/O. The `run` entry point
  * owns the output and exit codes.
  *
- * The mirror lives at `packages/sdk/src/router/failover-mirror.mjs` and is
+ * The mirror lives at `packages/sdk/dist/router/failover-mirror.mjs` and is
  * byte-identical to the SDK's algorithm; if it diverges, the divergence
  * test in `cli/__tests__/models-picker.test.mjs` fails.
  *
@@ -721,7 +722,7 @@ export function explainSelection({ routerPath, role, requirements = {} } = {}) {
     registry = { userSelected: undefined };
   }
   if (typeof rankUserSelectedForRoleMirror !== 'function') {
-    const err = new Error('bizar models explain requires packages/sdk/src/router/failover-mirror.mjs to be loadable');
+    const err = new Error('bizar models explain requires packages/sdk/dist/router/failover-mirror.mjs to be loadable');
     err.code = 'SDK_UNAVAILABLE';
     throw err;
   }
@@ -732,12 +733,13 @@ export function explainSelection({ routerPath, role, requirements = {} } = {}) {
 /**
  * Interactive multi-select picker. Pure function over streams — testable.
  *
- * The picker prints candidates with current picks marked, accepts a space-
- * separated list of indices (or `all` / `none` / `toggle <i>`), and returns
- * the chosen IDs in the user's most-recent selection order.
- *
- * Non-TTY input (pipes, tests, CI) is supported via a simple async line
- * iterator; TTY input uses `rl.question` so the prompt stays interactive.
+ * Branching: when stdin is a TTY with raw-mode support, the picker drives a
+ * keypress-driven checklist (arrow keys / j-k / space / a / n / enter / q /
+ * esc / ?).  When stdin is not a TTY (pipes, CI, tests) the picker falls
+ * through to a line-mode loop that accepts a space-separated index list,
+ * `all`, `none`, `toggle <i>`, an empty line (confirm), or `q` (quit). Both
+ * branches return the chosen IDs in the user's most-recent selection order,
+ * so external callers and existing tests see a single `Promise<string[]>`.
  *
  * @param {{ candidates: Array<{ id: string }>, current?: string[], stdin?: NodeJS.ReadableStream, stdout?: NodeJS.WriteStream, prompt?: string }} opts
  * @returns {Promise<string[]>}
@@ -754,10 +756,36 @@ export async function pickModels({ candidates, current = [], stdin, stdout, prom
   const selected = new Set(current);
   let lastOrder = [...current];
 
-  const lines = makeLineReader(in$);
+  const useTty = in$.isTTY === true && typeof in$.setRawMode === 'function';
+  if (!useTty) {
+    return pickModelsLineMode({ ordered, candidates, selected, lastOrder, stdin: in$, stdout: out$, prompt });
+  }
+
+  // Try to enable raw mode. If that fails (rare — redirected TTY, broken
+  // pseudo-terminal), fall back to the line-mode picker so the user never
+  // sees a silent no-op.
+  let rawOk = true;
+  try {
+    in$.setRawMode(true);
+  } catch {
+    rawOk = false;
+  }
+  if (!rawOk) {
+    return pickModelsLineMode({ ordered, candidates, selected, lastOrder, stdin: in$, stdout: out$, prompt });
+  }
+
+  try {
+    return await pickModelsInteractive({ ordered, candidates, selected, lastOrder, stdin: in$, stdout: out$, prompt });
+  } finally {
+    try { in$.setRawMode(false); } catch { /* swallow — terminal may already be gone */ }
+  }
+}
+
+async function pickModelsLineMode({ ordered, candidates, selected, lastOrder, stdin, stdout, prompt }) {
+  const lines = makeLineReader(stdin);
   for (;;) {
-    renderPicker(out$, ordered, selected, prompt, candidates);
-    const line = await readPrompt(lines, out$, in$.isTTY === true, '> ');
+    renderPicker(stdout, ordered, selected, prompt, candidates);
+    const line = await readPrompt(lines, stdout, stdin.isTTY === true, '> ');
     if (line === null) break; // EOF on non-TTY
     const cmd = String(line || '').trim();
     if (cmd === '') break;
@@ -775,7 +803,7 @@ export async function pickModels({ candidates, current = [], stdin, stdout, prom
     if (cmd.startsWith('toggle ')) {
       const idx = Number(cmd.slice('toggle '.length).trim());
       if (!Number.isInteger(idx) || idx < 1 || idx > ordered.length) {
-        out$.write(chalk.red(`  x index out of range\n`));
+        stdout.write(chalk.red(`  x index out of range\n`));
         continue;
       }
       const id = ordered[idx - 1];
@@ -802,7 +830,7 @@ export async function pickModels({ candidates, current = [], stdin, stdout, prom
       }
       changed = true;
     }
-    if (!changed) out$.write(chalk.yellow(`  ! unrecognised input - try 'all', 'none', 'toggle <i>', or '1 3 5'\n`));
+    if (!changed) stdout.write(chalk.yellow(`  ! unrecognised input - try 'all', 'none', 'toggle <i>', or '1 3 5'\n`));
   }
   const seen = new Set();
   return lastOrder.filter((id) => {
@@ -813,6 +841,145 @@ export async function pickModels({ candidates, current = [], stdin, stdout, prom
   });
 }
 
+const VIEWPORT_SIZE = 20;
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+const ERASE_SCREEN = '\x1b[2J\x1b[H';
+
+function cursorUp(n) {
+  return `\x1b[${n}A`;
+}
+
+function fitRow({ i, id, profile, width, isCursor, isSelected, columns }) {
+  const mark = isSelected ? chalk.green('[x]') : '[ ]';
+  const idx = String(i + 1).padStart(width, ' ');
+  const label = capabilityLabel(profile);
+  const budget = Math.max(40, (columns ?? 80) - 32);
+  const idText = id.length > budget ? `${id.slice(0, Math.max(1, budget - 1))}…` : id;
+  const cursorMark = isCursor ? chalk.inverse(' ▌ ') : '   ';
+  return `  ${cursorMark}${mark} ${chalk.dim(`${idx}.`)} ${idText}${chalk.dim(`  [${label}]`)}`;
+}
+
+async function pickModelsInteractive({ ordered, candidates, selected, lastOrder, stdin, stdout, prompt }) {
+  let cursor = 0;
+  let scrollTop = 0;
+  let lastRenderHeight = 0;
+  let showHelp = false;
+
+  readline.emitKeypressEvents(stdin);
+  if (typeof stdin.resume === 'function') stdin.resume();
+  stdout.write(`${ERASE_SCREEN}${HIDE_CURSOR}`);
+
+  const exitState = await new Promise((resolve) => {
+    const onKey = (str, key) => {
+      if (!key) return;
+      // Resolve confirmation
+      if (key.name === 'return' || str === 'q' || key.name === 'escape') {
+        return finish();
+      }
+      if (key.ctrl && key.name === 'c') {
+        // SIGINT: discard selection and break out, but do not bubble.
+        selected.clear();
+        lastOrder.length = 0;
+        return finish();
+      }
+      if (key.name === 'up' || str === 'k') {
+        cursor = (cursor - 1 + ordered.length) % ordered.length;
+      } else if (key.name === 'down' || str === 'j') {
+        cursor = (cursor + 1) % ordered.length;
+      } else if (key.name === 'space' || str === 'x') {
+        const id = ordered[cursor];
+        if (selected.has(id)) {
+          selected.delete(id);
+          lastOrder = lastOrder.filter((x) => x !== id);
+        } else {
+          selected.add(id);
+          lastOrder.push(id);
+        }
+      } else if (str === 'a') {
+        for (const id of ordered) selected.add(id);
+        lastOrder = [...ordered];
+      } else if (str === 'n') {
+        selected.clear();
+        lastOrder = [];
+      } else if (str === '?') {
+        showHelp = !showHelp;
+      } else {
+        return;
+      }
+      adjustScroll();
+      render();
+    };
+
+    const finish = () => {
+      stdin.removeListener('keypress', onKey);
+      if (typeof stdin.pause === 'function') stdin.pause();
+      resolve();
+    };
+
+    stdin.on('keypress', onKey);
+    render();
+  });
+
+  stdout.write(SHOW_CURSOR);
+
+  const seen = new Set();
+  return lastOrder.filter((id) => {
+    if (!selected.has(id)) return false;
+    if (seen.has(id)) return false;
+    seen.add(id);
+    return true;
+  });
+
+  function adjustScroll() {
+    if (ordered.length <= VIEWPORT_SIZE) {
+      scrollTop = 0;
+      return;
+    }
+    if (cursor < scrollTop) scrollTop = cursor;
+    else if (cursor >= scrollTop + VIEWPORT_SIZE) scrollTop = cursor - VIEWPORT_SIZE + 1;
+    if (scrollTop < 0) scrollTop = 0;
+    if (scrollTop > Math.max(0, ordered.length - VIEWPORT_SIZE)) {
+      scrollTop = Math.max(0, ordered.length - VIEWPORT_SIZE);
+    }
+  }
+
+  function render() {
+    const width = String(ordered.length).length;
+    const columns = typeof stdout.columns === 'number' ? stdout.columns : 80;
+    const lines = [];
+    lines.push(`\x1b[K${chalk.bold(`-- ${prompt} --`)}`);
+    const start = scrollTop;
+    const end = Math.min(ordered.length, start + VIEWPORT_SIZE);
+    const above = start;
+    const below = ordered.length - end;
+    if (above > 0) lines.push(`\x1b[K${chalk.dim(`  ⋮ ${above} more above`)}`);
+    for (let i = start; i < end; i++) {
+      const profile = candidates.find((candidate) => candidate.id === ordered[i])?.profile;
+      const row = fitRow({
+        i,
+        id: ordered[i],
+        profile,
+        width,
+        isCursor: i === cursor,
+        isSelected: selected.has(ordered[i]),
+        columns,
+      });
+      lines.push(`\x1b[K${row}`);
+    }
+    if (below > 0) lines.push(`\x1b[K${chalk.dim(`  ⋮ ${below} more below`)}`);
+    lines.push(`\x1b[K${chalk.dim(`  ${selected.size}/${ordered.length} selected. ↑/↓ move · space toggle · a all · n none · enter confirm.`)}`);
+    if (showHelp) lines.push(`\x1b[K${chalk.dim(`  Extra: j/k · x toggle · q/esc confirm · ? help.`)}`);
+    lines.push(`\x1b[K`);
+
+    if (lastRenderHeight > 0) {
+      stdout.write(cursorUp(lastRenderHeight));
+    }
+    stdout.write(lines.join('\n'));
+    lastRenderHeight = lines.length;
+  }
+}
+
 /**
  * Build a small async iterator over `stdin` lines.
  * Returns null from `next()` when the stream ends.
@@ -909,7 +1076,7 @@ function showHelp() {
   bizar models - User-controlled model picker
 
   Usage:
-    bizar models                    Interactive picker (lists + asks for selection)
+    bizar models                    Interactive picker (TTY: arrow keys / space / enter; pipe: line-mode)
     bizar models --list             Print candidate IDs, one per line
     bizar models --set a,b,c        Persist the comma-separated IDs to userSelected
     bizar models --clear            Remove userSelected; orchestrator falls back to session-only

package/config/claude/hooks/advisor-context.mjs

@@ -1,43 +1,125 @@
 #!/usr/bin/env node
 /**
- * Inject the recent parent transcript into review-oriented subagents.
- * Reads newest-first with hard record and character caps.
+ * advisor-context.mjs — Claude Code SubagentStart leaf hook.
+ *
+ * Inject a SHORT, FILTERED slice of the parent transcript into reviewer /
+ * debug-specialist subagents (`@linda`, `@carl`). The previous version
+ * dumped up to 30kB of raw parent transcript on every dispatch of
+ * `linda|karen|carl|qa-reviewer|principal-engineer|debug-specialist`. Two
+ * failure modes followed:
+ *
+ *   1. The dump was too noisy — reviewers only need the recent intent
+ *      and the changed files, not arbitrary chitchat from earlier in
+ *      the session.
+ *   2. The JSONL transcript persists across sessions on the same
+ *      project (Claude Code appends to `~/.claude/projects/.../<id>.jsonl`
+ *      rather than rotating per session). Reading the "tail" of that
+ *      file can surface content from a previous, unrelated session —
+ *      including prior user prompts, spinner/status text, and stuff the
+ *      current session has no business knowing.
+ *
+ * The fix below:
+ *   - Take only the last 8 user/assistant records (was 60).
+ *   - Skip non-substantive records entirely: `isSidechain`, `isMeta`,
+ *     `type: 'attachment'`, `type: 'system'`, `type: 'last-prompt'`,
+ *     `type: 'ai-title'`, `type: 'agent-name'`,
+ *     `type: 'stop_hook_summary'`.
+ *   - Per-record cap: 800 chars (was 3000).
+ *   - Hard total cap: 6kB (was 30kB).
+ *   - Strip `<system-reminder>` and `<total_tokens>` blocks inside text
+ *     content.
+ *   - Fall back to "could not be reconstructed" when the dump is too
+ *     short to be useful (< 100 chars).
+ *
+ * Output envelope (unchanged from the previous version):
+ *   { hookSpecificOutput: { hookEventName: 'SubagentStart', additionalContext } }
  */
 
 import { readFileSync } from 'node:fs';
 
-const clip = (value, limit) => value.length > limit ? `${value.slice(0, limit)} …[truncated]` : value;
+const MAX_RECORDS = 8;
+const PER_RECORD_CAP = 800;
+const TOTAL_CAP = 6_000;
+const MIN_USEFUL_LENGTH = 100;
+
+// Records that should never be replayed as "parent context" — they are
+// bookkeeping, meta, or status output rather than substantive session
+// content.
+const SKIP_TYPES = new Set([
+  'attachment',
+  'system',
+  'last-prompt',
+  'ai-title',
+  'agent-name',
+  'stop_hook_summary',
+  'queue-operation',
+]);
+
+const SYSTEM_REMINDER_RE = /<system-reminder>[\s\S]*?<\/system-reminder>/g;
+const TOTAL_TOKENS_RE = /<total_tokens>[\s\S]*?<\/total_tokens>/g;
+const CCR_RE = /\[\s*CCR\s+retrieve[^\]]*\]/g;
+
+function clip(value, limit) {
+  return value.length > limit ? `${value.slice(0, limit)} …[truncated]` : value;
+}
+
+function cleanText(text) {
+  if (typeof text !== 'string' || text.length === 0) return '';
+  return text
+    .replace(SYSTEM_REMINDER_RE, '')
+    .replace(TOTAL_TOKENS_RE, '')
+    .replace(CCR_RE, '[compacted context omitted]')
+    .replace(/[ \t]+\n/g, '\n')
+    .trim();
+}
+
+function isSubstantiveRecord(record) {
+  if (!record || typeof record !== 'object') return false;
+  if (record.isSidechain === true || record.isMeta === true) return false;
+  if (SKIP_TYPES.has(record.type)) return false;
+  return record.type === 'user' || record.type === 'assistant';
+}
+
+function extractText(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter((block) => block && block.type === 'text')
+    .map((block) => block.text || '')
+    .join('\n');
+}
+
+function readTranscriptLines(transcriptPath) {
+  if (!transcriptPath) return [];
+  let text;
+  try {
+    text = readFileSync(transcriptPath, 'utf8');
+  } catch {
+    return [];
+  }
+  return text.split('\n').filter(Boolean);
+}
 
 let input = {};
 try { input = JSON.parse(readFileSync(0, 'utf8') || '{}'); } catch { input = {}; }
 
-let rendered = [];
-try {
-  const lines = readFileSync(input.transcript_path, 'utf8').split('\n');
-  for (let index = lines.length - 1; index >= 0 && rendered.length < 60; index--) {
-    let record;
-    try { record = JSON.parse(lines[index]); } catch { continue; }
-    if (record.isSidechain || record.isMeta || !['user', 'assistant'].includes(record.type)) continue;
-    const content = record.message?.content;
-    if (typeof content === 'string') rendered.push(`${record.type}: ${clip(content, 3_000)}`);
-    else if (Array.isArray(content)) {
-      const text = content
-        .filter((block) => block?.type === 'text')
-        .map((block) => block.text || '')
-        .join('\n');
-      if (text) rendered.push(`${record.type}: ${clip(text, 3_000)}`);
-    }
-  }
-} catch { rendered = []; }
-
-rendered.reverse();
-let recent = rendered.join('\n\n---\n\n');
-if (recent.length > 30_000) recent = `…[older turns truncated]\n${recent.slice(-30_000)}`;
-// Strip CCR (context-compaction-retrieval) compression markers so subagents
-// do not interpret them as user content. Replace with a brief note.
-recent = recent.replace(/\[\s*CCR\s+retrieve[^\]]*\]/g, '[compacted context omitted]');
-const additionalContext = recent
-  ? `Review the caller's request against this recent parent-session evidence, not only its summary:\n\n<recent-conversation>\n${recent}\n</recent-conversation>`
+const lines = readTranscriptLines(input.transcript_path);
+const records = [];
+for (let index = lines.length - 1; index >= 0 && records.length < MAX_RECORDS; index--) {
+  let record;
+  try { record = JSON.parse(lines[index]); } catch { continue; }
+  if (!isSubstantiveRecord(record)) continue;
+  const text = cleanText(extractText(record.message?.content));
+  if (!text) continue;
+  records.push(`${record.type}: ${clip(text, PER_RECORD_CAP)}`);
+}
+
+records.reverse();
+let recent = records.join('\n\n---\n\n');
+if (recent.length > TOTAL_CAP) recent = `…[older turns truncated]\n${recent.slice(-TOTAL_CAP)}`;
+
+const additionalContext = recent.length >= MIN_USEFUL_LENGTH
+  ? `Recent parent transcript (last ${records.length} records, capped at ${TOTAL_CAP} chars):\n\n<recent-conversation>\n${recent}\n</recent-conversation>`
   : 'The parent transcript could not be reconstructed. State any context needed before making a strong claim.';
 
 process.stdout.write(JSON.stringify({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar",
-  "version": "10.17.0",
+  "version": "10.17.3",
   "description": "Autonomous, human-in-the-loop multi-agent harness for Claude Code with guarded workflows, typed SDK primitives, and MCP tools.",
   "type": "module",
   "bin": {
@@ -35,7 +35,7 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "build:sdk": "node scripts/clean-sdk-dist.mjs && tsc -p packages/sdk/tsconfig.json",
+    "build:sdk": "node scripts/build-sdk.mjs",
     "test:sdk": "node_modules/.bin/vitest run --root packages/sdk",
     "test:sdk:watch": "node_modules/.bin/vitest --root packages/sdk",
     "test:node": "node scripts/run-node-tests.mjs",

package/packages/sdk/dist/router/failover-mirror.mjs

@@ -0,0 +1,311 @@
+/**
+ * router/failover-mirror.mjs
+ *
+ * Pure-JavaScript mirror of `packages/sdk/src/router/failover.ts` for
+ * direct Node loading (`node --test`, `bizar models explain`). This is
+ * NOT a runtime import path for the SDK — the SDK ships the TypeScript
+ * source — but the CLI is `mjs` and cannot import TS directly without a
+ * build step. The mirror keeps the algorithm byte-identical:
+ *
+ *   - `defaultTierHintForId` regex set matches `cli/commands/models.mjs:defaultTierHint`
+ *     and the SDK's `defaultTierHintForId` verbatim.
+ *   - The eligible ranking rules mirror `rankUserSelectedForRole`'s sort
+ *     key (`eligible desc, capabilityScore desc, hasProfile desc,
+ *     originalIndex asc`).
+ *   - `pickFailover` walks the eligible list, skips `attemptedIds`,
+ *     applies the same transport/availability whitelist, and caps at
+ *     one failover attempt.
+ *
+ * If `failover.ts` and `failover-mirror.mjs` ever diverge, the unit
+ * tests in `cli/__tests__/models-picker.test.mjs` will fail with a
+ * divergence diff.
+ */
+
+/**
+ * Default tier classification for a model ID. Mirrors
+ * `cli/commands/models.mjs:defaultTierHint` and
+ * `packages/sdk/src/router/agent-model-registry.ts:defaultTierHintForId`
+ * byte-for-byte. Most-specific patterns run first.
+ */
+export function defaultTierHintForId(modelId) {
+  const id = String(modelId || "").toLowerCase();
+  if (!id) return "default";
+  if (/(qwen3\.8|gpt-5|opus|o3-pro|o4-mini|sonnet-4)/.test(id)) return "premium";
+  if (/(haiku-4|sonnet-3-7|mini-high|m3-high|grok-3)/.test(id)) return "high";
+  if (/(sonnet|gpt-4|m3(-|$)|(^|[^a-z])default($|[^a-z]))/.test(id)) return "default";
+  if (/(nano|mini[-/]|flash|lite|tiny|haiku($|[-_]\d))/.test(id)) return "budget";
+  return "mid";
+}
+
+/**
+ * Weighted capability score, byte-identical to `scoreCapabilityProfile`.
+ *   reasoning=0.3, toolCall=0.25, structuredOutput=0.15, attachment=0.1,
+ *   temperature=0.05, +0.15 when `inputModalities` includes "image".
+ * Missing/partial profiles score 0.
+ */
+export function scoreCapabilityProfile(profile) {
+  if (!profile || !profile.capabilities) return 0;
+  const caps = profile.capabilities;
+  let score = 0;
+  if (caps.reasoning) score += 0.3;
+  if (caps.toolCall) score += 0.25;
+  if (caps.structuredOutput) score += 0.15;
+  if (caps.attachment) score += 0.1;
+  if (caps.temperature) score += 0.05;
+  if (Array.isArray(caps.inputModalities) && caps.inputModalities.includes("image")) score += 0.15;
+  return Math.round(score * 1e6) / 1e6;
+}
+
+/**
+ * Mirror of `evaluateRoleRequirements`. Returns
+ * `{ eligible, ineligibleReasons }`. Profiles missing the relevant data
+ * (e.g., `null` context tokens) pass unknown-values — the resolver
+ * only downgrades when a known value violates a floor.
+ */
+export function evaluateRoleRequirements(profile, requirements, tier) {
+  const reasons = [];
+  if (typeof requirements?.minContextTokens === "number" && profile?.limits && Number.isFinite(profile.limits.contextTokens) && profile.limits.contextTokens < requirements.minContextTokens) {
+    reasons.push(`contextTokens ${profile.limits.contextTokens} < required ${requirements.minContextTokens}`);
+  }
+  if (requirements?.requireReasoning && profile?.capabilities && profile.capabilities.reasoning !== true) {
+    reasons.push("missing required reasoning capability");
+  }
+  if (requirements?.requireToolCall && profile?.capabilities && profile.capabilities.toolCall !== true) {
+    reasons.push("missing required tool-call capability");
+  }
+  if (requirements?.requireStructuredOutput && profile?.capabilities && profile.capabilities.structuredOutput !== true) {
+    reasons.push("missing required structured-output capability");
+  }
+  if (requirements?.requireImageInput && profile?.capabilities && !(Array.isArray(profile.capabilities.inputModalities) && profile.capabilities.inputModalities.includes("image"))) {
+    reasons.push("missing required image input modality");
+  }
+  if (Array.isArray(requirements?.preferredTiers) && requirements.preferredTiers.length > 0 && !requirements.preferredTiers.includes(tier)) {
+    reasons.push(`tier ${tier} not in preferred list`);
+  }
+  return { eligible: reasons.length === 0, ineligibleReasons: reasons };
+}
+
+/**
+ * F-190 / IMP-017 protocol-floor mirror. Byte-identical to
+ * `protocolMeets` in `packages/sdk/src/router/model-profile.ts`. Returns
+ * an array of strings describing each violated floor; empty when all
+ * floors pass. The discriminator is the discriminated
+ * `ModelProfile` shape; the legacy F-184 `ModelCapabilityProfile`
+ * falls through to an empty array (legacy `evaluateRoleRequirements`
+ * owns those floors).
+ *
+ * IMP-017 reject strings (mirrored):
+ *   - `context-too-small: <actual> < <required>`
+ *   - `no-tool-use`
+ *   - `no-reasoning`
+ *   - `no-structured-output`
+ *   - `no-image-input`
+ */
+export function protocolMeetsMirror(discriminatedProfile, requirements) {
+  if (!discriminatedProfile || typeof discriminatedProfile !== "object") return [];
+  const protocol = discriminatedProfile.protocol;
+  if (!protocol || typeof protocol !== "object") return [];
+  const reasons = [];
+  if (typeof requirements?.minContextTokens === "number" && Number.isFinite(protocol.contextTokens) && protocol.contextTokens < requirements.minContextTokens) {
+    reasons.push(`context-too-small: ${protocol.contextTokens} < ${requirements.minContextTokens}`);
+  }
+  if (requirements?.requireToolCall === true && protocol.toolUse !== true) {
+    reasons.push("no-tool-use");
+  }
+  if (requirements?.requireReasoning === true && protocol.reasoning !== true) {
+    reasons.push("no-reasoning");
+  }
+  if (requirements?.requireStructuredOutput === true && protocol.structuredOutput !== true) {
+    reasons.push("no-structured-output");
+  }
+  if (requirements?.requireImageInput === true && !(Array.isArray(protocol.modalities) && protocol.modalities.includes("image"))) {
+    reasons.push("no-image-input");
+  }
+  return reasons;
+}
+
+/**
+ * Rank user-selected models for a role. Byte-identical algorithm to
+ * `packages/sdk/src/router/agent-model-registry.ts:rankUserSelectedForRole`.
+ *
+ * Sort key (descending primary, ascending tie-breaker):
+ *   1. `eligible` desc
+ *   2. `capabilityScore` desc
+ *   3. `hasProfile` desc
+ *   4. `originalIndex` asc
+ *
+ * @param {object} registry
+ * @param {string} role
+ * @param {object} [requirements]
+ * @returns {{ ranked: object[], eligible: object[] }}
+ */
+export function rankUserSelectedForRole(registry, role, requirements = {}) {
+  const userSelected = registry.userSelected;
+  if (!userSelected || !Array.isArray(userSelected.models) || userSelected.models.length === 0) {
+    return { ranked: [], eligible: [] };
+  }
+  const tierHints = userSelected.tierHints;
+  const profiles = userSelected.profiles;
+  const discriminatedProfiles = userSelected.discriminatedProfiles && typeof userSelected.discriminatedProfiles === "object"
+    ? userSelected.discriminatedProfiles
+    : {};
+  const ranked = userSelected.models
+    .map((id, originalIndex) => {
+      const profile = profiles?.[id];
+      const discriminatedProfile = discriminatedProfiles?.[id];
+      const hasProfile = Boolean(profile) || Boolean(discriminatedProfile);
+      const tier = (tierHints && typeof tierHints[id] === "string" ? tierHints[id] : defaultTierHintForId(id));
+      const legacy = evaluateRoleRequirements(profile, requirements, tier);
+      const protocolReasons = protocolMeetsMirror(discriminatedProfile, requirements);
+      const ineligibleReasons = [...protocolReasons, ...legacy.ineligibleReasons];
+      const eligible = ineligibleReasons.length === 0;
+      const capabilityScore = scoreCapabilityProfile(profile);
+      return {
+        id,
+        tier,
+        eligible,
+        ineligibleReasons,
+        capabilityScore,
+        hasProfile,
+        originalIndex,
+        ...(discriminatedProfile ? { discriminatedProfile, reasons: protocolReasons } : {}),
+        ...(discriminatedProfile?.measured ? { measured: discriminatedProfile.measured } : {}),
+        ...(discriminatedProfile?.provenance ? { provenance: discriminatedProfile.provenance } : {}),
+      };
+    });
+  ranked.sort((a, b) => {
+    if (a.eligible !== b.eligible) return a.eligible ? -1 : 1;
+    if (a.capabilityScore !== b.capabilityScore) return b.capabilityScore - a.capabilityScore;
+    if (a.hasProfile !== b.hasProfile) return a.hasProfile ? -1 : 1;
+    return a.originalIndex - b.originalIndex;
+  });
+  const eligible = ranked.filter((entry) => entry.eligible);
+  // role is consumed only for future per-role filtering / logging hooks.
+  void role;
+  return { ranked, eligible };
+}
+
+export const TRANSPORT_OR_AVAILABILITY = new Set([
+  "invalid-model",
+  "auth-failure",
+  "rate-limit",
+  "timeout",
+  "provider-outage",
+]);
+
+/**
+ * Walk the ranked eligible list and pick the next ID that has not been
+ * attempted. Returns the same `FailoverVerdict` shape as the TS module.
+ *
+ *   - Non-transport reason → exhausts immediately (no failover).
+ *   - First eligible ID already attempted → it stays as `primary`; the
+ *     next un-attempted eligible ID becomes the failover.
+ *   - One-failover cap. A second transport failure on the failover
+ *     target marks subsequent entries as `exhausted` and refuses to walk.
+ */
+export function pickFailover({ registry, role, requirements, attemptedIds, failure, primaryDecisionId }) {
+  const attempted = new Set((attemptedIds || []).filter((id) => typeof id === "string"));
+  const routingDecisionId = typeof primaryDecisionId === "string" && primaryDecisionId.length > 0 ? primaryDecisionId : null;
+  // IMP-020 / F-192: ordered list of attempted-and-failed IDs. The
+  // learner updates only the FINAL model's posterior; the IMP-018
+  // evidence store records per-attempt outcomes against this list. We
+  // always populate it with the primary's id when the primary was
+  // already attempted, and with subsequent attempted failover IDs.
+  const failoverFrom = [];
+
+  if (!TRANSPORT_OR_AVAILABILITY.has(failure)) {
+    return {
+      primary: null,
+      failover: null,
+      attempts: 0,
+      exhaustReason: failure,
+      chain: [{ id: "", eligible: false, capabilityScore: 0, attempted: false, outcome: "skipped-non-transport-reason" }],
+      routingDecisionId,
+      failoverFrom,
+    };
+  }
+
+  const { eligible, ranked } = rankUserSelectedForRole(registry, role, requirements);
+  if (ranked.length === 0) {
+    return { primary: null, failover: null, attempts: 0, exhaustReason: failure, chain: [], routingDecisionId, failoverFrom };
+  }
+
+  const head = ranked[0];
+  const chain = [{
+    id: head.id,
+    eligible: head.eligible,
+    capabilityScore: head.capabilityScore,
+    attempted: attempted.has(head.id),
+    outcome: "primary",
+  }];
+  // IMP-020: if the primary was already attempted, it counts as a
+  // failed-and-skipped ID in the `failoverFrom` list.
+  if (attempted.has(head.id)) {
+    failoverFrom.push(head.id);
+  }
+  const primary = { id: head.id, reason: failure };
+
+  let failover = null;
+  let exhaustedAtTopLevel = false;
+
+  for (const entry of eligible) {
+    if (entry.id === head.id) continue;
+    if (attempted.has(entry.id)) {
+      failoverFrom.push(entry.id);
+      chain.push({
+        id: entry.id,
+        eligible: entry.eligible,
+        capabilityScore: entry.capabilityScore,
+        attempted: true,
+        outcome: "skipped-already-attempted",
+      });
+      continue;
+    }
+    if (failover === null) {
+      failover = { id: entry.id, reason: failure };
+      chain.push({
+        id: entry.id,
+        eligible: entry.eligible,
+        capabilityScore: entry.capabilityScore,
+        attempted: false,
+        outcome: "failover",
+      });
+    } else {
+      chain.push({
+        id: entry.id,
+        eligible: entry.eligible,
+        capabilityScore: entry.capabilityScore,
+        attempted: false,
+        outcome: "exhausted",
+      });
+    }
+  }
+
+  if (failover === null) exhaustedAtTopLevel = true;
+
+  return {
+    primary,
+    failover,
+    attempts: attempted.size + (failover !== null ? 1 : 0),
+    exhaustReason: exhaustedAtTopLevel ? failure : null,
+    chain,
+    routingDecisionId,
+    failoverFrom,
+  };
+}
+
+/**
+ * Convenience classifier for the dispatch wrapper.
+ */
+export function classifyError(message) {
+  const m = String(message || "").toLowerCase();
+  if (!m) return "invalid-model";
+  if (/(context.*length|context.*overflow|context.*window|too long|maximum context)/.test(m)) return "context-overflow";
+  if (/(429|rate.?limit|too many requests|quota)/.test(m)) return "rate-limit";
+  if (/(401|403|unauthorized|forbidden|auth.?token|invalid.*api.*key)/.test(m)) return "auth-failure";
+  if (/(timeout|timed out|etimedout|aborted|deadline)/.test(m)) return "timeout";
+  if (/(502|503|504|bad gateway|service unavailable|gateway timeout|provider outage|upstream)/.test(m)) return "provider-outage";
+  if (/(invalid.*model|unknown.*model|model not found|no such model|not a valid model)/.test(m)) return "invalid-model";
+  if (/(quality|incomplete|truncated|garbage|low quality|incoherent)/.test(m)) return "model-quality";
+  return "invalid-model";
+}

package/packages/sdk/dist/version.d.ts

@@ -1,5 +1,5 @@
 /**
  * SDK version constant. Keep synchronized with the workspace package versions.
  */
-export declare const SDK_VERSION: "10.17.0";
+export declare const SDK_VERSION: "10.17.3";
 //# sourceMappingURL=version.d.ts.map

package/packages/sdk/dist/version.js

@@ -1,5 +1,5 @@
 /**
  * SDK version constant. Keep synchronized with the workspace package versions.
  */
-export const SDK_VERSION = "10.17.0";
+export const SDK_VERSION = "10.17.3";
 //# sourceMappingURL=version.js.map

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar-sdk",
-  "version": "10.17.0",
+  "version": "10.17.3",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",