synabun 1.3.0 → 2.0.0

package/neural-interface/lib/assistant-pricing.js

@@ -0,0 +1,159 @@
+// ═══════════════════════════════════════════
+// SynaBun — Assistant list prices (one table)
+// ═══════════════════════════════════════════
+//
+// The only place a model's list price is written. The model catalog (routing
+// sheet, agent_catalog, the pickers), the usage ledger (Codex tokens, Claude
+// estimates), the budget caps and the side panel's cost scanner all read it.
+//
+// Sources, read 2026-10-01:
+//   Anthropic  https://platform.claude.com/docs/en/about-claude/pricing
+//   OpenAI     https://developers.openai.com/api/docs/pricing
+//              (gpt-6-sol: https://developers.openai.com/api/docs/models/gpt-6-sol)
+//
+// $ per million tokens, one rate per token class:
+//   input         uncached input
+//   cacheRead     a cache hit ("cached input")
+//   cacheWrite    a cache write (Anthropic: the 5-minute cache, 1.25x input)
+//   cacheWrite1h  Anthropic's 1-hour cache write (2x input). The Claude CLI writes most of
+//                 its cache at this rate, so an estimate of its usage prices writes with it.
+//   output        output, reasoning / thinking included
+//   long          OpenAI only: a request whose prompt is over `size` input tokens is priced at
+//                 these rates for the whole request (2x input and cache, 1.5x output).
+//                 Anthropic prices the full 1M window at the standard rate (Claude 4.6 and later).
+//
+// What is billed is the provider's business: Claude Code and Codex usually run on a plan, where
+// these dollars are the list-price equivalent of the tokens, not a charge.
+//
+// Pure: no I/O, no dependencies.
+
+export const PRICING_VERIFIED = '2026-10-01';
+export const PRICING_SOURCES = Object.freeze({
+  anthropic: 'https://platform.claude.com/docs/en/about-claude/pricing',
+  openai: 'https://developers.openai.com/api/docs/pricing',
+});
+/** OpenAI's long-context boundary: a prompt over this many input tokens is priced at the long rates. */
+export const LONG_PROMPT_TOKENS = 272_000;
+
+const round = (value) => Number(Number(value).toFixed(6));
+
+/** Anthropic: cache writes are 1.25x (5 minutes) and 2x (1 hour) the input rate; cache reads are per model. */
+function claude(input, output, cacheRead) {
+  return Object.freeze({ input, output, cacheRead, cacheWrite: round(input * 1.25), cacheWrite1h: round(input * 2), long: null });
+}
+/** OpenAI: cache writes are 1.25x input; over 272K prompt tokens input and cache rates double and output is 1.5x. */
+function openai(input, output, cacheRead) {
+  const cacheWrite = round(input * 1.25);
+  return Object.freeze({
+    input, output, cacheRead, cacheWrite, cacheWrite1h: null,
+    long: Object.freeze({ size: LONG_PROMPT_TOKENS, input: round(input * 2), output: round(output * 1.5), cacheRead: round(cacheRead * 2), cacheWrite: round(cacheWrite * 2) }),
+  });
+}
+
+const ANTHROPIC = Object.freeze({
+  'claude-fable-5-1': claude(10, 50, 0.25), // cache reads 0.025x
+  'claude-fable-5': claude(10, 50, 1),
+  'claude-opus-5-5': claude(4, 20, 0.2), // cache reads 0.05x
+  'claude-opus-5': claude(5, 25, 0.5),
+  'claude-opus-4-8': claude(5, 25, 0.5),
+  'claude-opus-4-7': claude(5, 25, 0.5),
+  'claude-opus-4-6': claude(5, 25, 0.5),
+  'claude-opus-4-5': claude(5, 25, 0.5),
+  'claude-sonnet-5-5': claude(2, 10, 0.2),
+  // $2 / $10 was introductory until 2026-08-31 and is the standard price now (the $3 / $15 increase was cancelled).
+  'claude-sonnet-5': claude(2, 10, 0.2),
+  'claude-sonnet-4-6': claude(3, 15, 0.3),
+  'claude-sonnet-4-5': claude(3, 15, 0.3),
+  'claude-haiku-4-5': claude(1, 5, 0.1),
+  // Retired models, at their last published price (old sessions are still priced).
+  'claude-3-5-sonnet': claude(3, 15, 0.3),
+  'claude-3-5-haiku': claude(0.8, 4, 0.08),
+});
+
+const OPENAI = Object.freeze({
+  'gpt-6-astra': openai(10, 50, 1),
+  'gpt-6.1-sol': openai(2, 10, 0.1),
+  'gpt-6-sol': openai(2, 10, 0.2),
+  'gpt-6-luna': openai(0.1, 0.5, 0.01),
+});
+
+const TABLES = Object.freeze({ anthropic: ANTHROPIC, openai: OPENAI });
+const VENDOR = Object.freeze({ 'claude-code': 'anthropic', claude: 'anthropic', anthropic: 'anthropic', codex: 'openai', openai: 'openai' });
+
+/** The id a price is filed under: lower case, no "[1m]" / "[extended]", no "provider/" prefix, no -YYYYMMDD snapshot date. */
+export function priceModelId(model) {
+  return String(model || '').trim().toLowerCase().replace(/\[[^\]]*\]$/, '').replace(/^.*\//, '').replace(/-\d{8}$/, '');
+}
+
+/**
+ * The list price of a model, or null when the table has none.
+ * @param {string} provider 'claude-code' | 'codex' (or the vendor: 'anthropic' | 'openai')
+ * @param {string} model any spelling the providers use ("claude-opus-5-5[1m]", "gpt-6-sol[extended]", "claude-haiku-4-5-20251001")
+ * @returns {{ input:number, output:number, cacheRead:number, cacheWrite:number, cacheWrite1h:number|null,
+ *   long:{ size:number, input:number, output:number, cacheRead:number, cacheWrite:number }|null,
+ *   unit:'usd_per_mtok', vendor:string, model:string, source:string, verified:string }|null}
+ */
+export function listPrice(provider, model) {
+  const vendor = VENDOR[String(provider || '').toLowerCase()];
+  const id = priceModelId(model);
+  const row = vendor && id ? TABLES[vendor][id] : null;
+  return row ? { ...row, unit: 'usd_per_mtok', vendor, model: id, source: PRICING_SOURCES[vendor], verified: PRICING_VERIFIED } : null;
+}
+
+const count = (value) => { const n = Number(value); return Number.isFinite(n) && n > 0 ? n : 0; };
+
+/**
+ * Five token classes ({ input, cacheWrite, cacheRead, output, reasoning }) at a price, in USD.
+ * `cacheWrite` '1h' prices cache writes at the 1-hour rate (falls back to the 5-minute one);
+ * `long` uses the long-context rates when the price has them. null without a price.
+ */
+export function tokensCostUsd(price, tokens, { cacheWrite = '5m', long = false } = {}) {
+  if (!price || !tokens || typeof tokens !== 'object') return null;
+  const r = long && price.long ? price.long : price;
+  const write = cacheWrite === '1h' && r.cacheWrite1h != null ? r.cacheWrite1h : (r.cacheWrite ?? r.input);
+  const usd = (count(tokens.input) * r.input + count(tokens.cacheWrite) * write + count(tokens.cacheRead) * (r.cacheRead ?? r.input)
+    + (count(tokens.output) + count(tokens.reasoning)) * r.output) / 1e6;
+  return Number(usd.toFixed(8));
+}
+
+/** Five token classes on a Claude model at list price; cache writes at the 1-hour rate unless told otherwise. null when the model has no price. */
+export function claudeTokensCostUsd(model, tokens, { cacheWrite = '1h' } = {}) {
+  return tokensCostUsd(listPrice('claude-code', model), tokens, { cacheWrite });
+}
+
+/**
+ * A raw Anthropic usage object at list price. With usage.cache_creation
+ * ({ ephemeral_5m_input_tokens, ephemeral_1h_input_tokens }) each write is priced at its own
+ * rate; without it every write is taken as a 5-minute one. null when the model has no price.
+ */
+export function claudeUsageCostUsd(model, usage) {
+  const price = listPrice('claude-code', model);
+  if (!price || !usage || typeof usage !== 'object') return null;
+  const split = usage.cache_creation && typeof usage.cache_creation === 'object' ? usage.cache_creation : null;
+  const written = count(usage.cache_creation_input_tokens);
+  const oneHour = split ? Math.min(written || Infinity, count(split.ephemeral_1h_input_tokens)) : 0;
+  const fiveMin = split ? Math.max(count(split.ephemeral_5m_input_tokens), written - oneHour) : written;
+  const usd = (count(usage.input_tokens) * price.input + fiveMin * price.cacheWrite + oneHour * price.cacheWrite1h
+    + count(usage.cache_read_input_tokens) * price.cacheRead + count(usage.output_tokens) * price.output) / 1e6;
+  return Number(usd.toFixed(8));
+}
+
+/** Claude prices in the older array form { [id]: [input, output, cacheWrite5m, cacheRead] }, dated aliases included. */
+export function claudeLegacyPricing() {
+  const out = {};
+  for (const [id, row] of Object.entries(ANTHROPIC)) out[id] = [row.input, row.output, row.cacheWrite, row.cacheRead];
+  // Snapshot ids the CLI and old transcripts name.
+  out['claude-haiku-4-5-20251001'] = out['claude-haiku-4-5'];
+  out['claude-3-5-sonnet-20241022'] = out['claude-3-5-sonnet'];
+  out['claude-3-5-haiku-20241022'] = out['claude-3-5-haiku'];
+  return out;
+}
+
+/** Every priced model, for the docs, the Budget tab and the tests: [{ vendor, model, input, output, cacheRead, cacheWrite, cacheWrite1h, long, source, verified }]. */
+export function pricingRows() {
+  const rows = [];
+  for (const [vendor, table] of Object.entries(TABLES)) {
+    for (const [model, row] of Object.entries(table)) rows.push({ vendor, model, ...row, source: PRICING_SOURCES[vendor], verified: PRICING_VERIFIED });
+  }
+  return rows;
+}

package/neural-interface/lib/assistant-route-gate-codex.js

@@ -0,0 +1,163 @@
+// ═══════════════════════════════════════════
+// SynaBun — Assistant route gate for the Codex brain (PreToolUse hook)
+// ═══════════════════════════════════════════
+//
+// Codex (0.156+) runs command hooks before every tool call; a PreToolUse hook
+// that answers permissionDecision "deny" blocks the call and hands the reason
+// to the model. The assistant brain's app-server gets one such hook as a
+// session flag (-c), never written to the user's config, so the Codex
+// sidepanel and CLI sessions are untouched. Codex only runs a hook the user
+// trusted: the session-flag hook is trusted with a session-flag
+// hooks.state.<key>.trusted_hash, and the key and hash come from one probe
+// app-server (temporary CODEX_HOME, `hooks/list`), cached per binary.
+// No trusted hook → the runtime falls back to reactive enforcement.
+// The Assistant's Codex workers (`codex exec` through the SDK) get the browser
+// policy's hook the same way (codexBrowserPolicyHook), trusted by the same probe.
+
+import { spawn } from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const CODEX_GATE_HOOK_PATH = resolve(dirname(fileURLToPath(import.meta.url)), 'assistant-brains', 'codex-route-gate-hook.mjs');
+export const CODEX_BROWSER_POLICY_HOOK_PATH = resolve(dirname(fileURLToPath(import.meta.url)), 'assistant-brains', 'codex-browser-policy-hook.mjs');
+/** The run note of a Codex worker whose browser-policy hook Codex would not run. */
+export const CODEX_BROWSER_POLICY_UNTRUSTED_NOTE = 'browser policy: instructions only (Codex hook not trusted)';
+
+export function codexGateHookCommand({ nodePath = process.execPath, hookPath = CODEX_GATE_HOOK_PATH } = {}) {
+  return `${JSON.stringify(nodePath)} ${JSON.stringify(hookPath)}`;
+}
+
+/** The -c flags that install (and, with `trust`, trust) the hook. TOML basic strings = JSON strings here. */
+export function codexGateHookFlags(command, trust = null) {
+  const flags = ['-c', 'features.hooks=true', '-c', `hooks.PreToolUse=[{matcher="*", hooks=[{type="command", command=${JSON.stringify(command)}, timeout=15}]}]`];
+  if (trust?.key && trust?.hash) flags.push('-c', `hooks.state={${JSON.stringify(trust.key)}={trusted_hash=${JSON.stringify(trust.hash)}}}`);
+  return flags;
+}
+
+/**
+ * The same trusted hook as the Codex SDK's `config` (the SDK has no raw
+ * arguments): the flags of codexGateHookFlags, for `codex exec`. The SDK
+ * turns `config` into dotted -c paths and Codex splits a path at every ".",
+ * so the trust entry, whose key holds one
+ * ("/<session-flags>/config.toml:pre_tool_use:0:0"), cannot be a path: it
+ * travels as a key that is the whole override, `hooks.state={…} #`. The SDK
+ * appends "=true" to it, which the trailing TOML comment swallows. Hook entries
+ * render as inline tables with the same hash (tests pin the argv through the
+ * real SDK). null without a trust entry: Codex would not run the hook.
+ */
+export function codexHookConfig(command, trust) {
+  if (!command || !trust?.key || !trust?.hash) return null;
+  return {
+    features: { hooks: true },
+    hooks: { PreToolUse: [{ matcher: '*', hooks: [{ type: 'command', command, timeout: 15 }] }] },
+    [`hooks.state={${JSON.stringify(trust.key)}={trusted_hash=${JSON.stringify(trust.hash)}}} #`]: true,
+  };
+}
+
+/**
+ * True when the codex skin would spawn this binary through a shell (a bare
+ * name, or a Windows .cmd/.bat; server.js `useShell`). The shell would split
+ * and glob the hook's -c values, so the gate falls back to reactive instead.
+ */
+export function codexNeedsShell(bin, platform = process.platform) {
+  const value = String(bin || '');
+  if (/\.js$/i.test(value)) return false; // run through node, never a shell
+  return !value.includes(sep) || (platform === 'win32' && /\.(cmd|bat)$/i.test(value));
+}
+
+/** The hook `hooks/list` reports for our session-flag entry, or null. */
+export function findGateHook(listResult, command) {
+  const hooks = (listResult?.data || []).flatMap((entry) => entry?.hooks || []);
+  const hook = hooks.find((h) => h?.source === 'sessionFlags' && h.command === command && /^pre_?tool_?use$/i.test(String(h.eventName || '')));
+  return hook?.key && hook?.currentHash ? { key: hook.key, hash: hook.currentHash, trustStatus: hook.trustStatus || null } : null;
+}
+
+function probe({ codexBin, command, timeoutMs, spawnImpl }) {
+  return new Promise((done) => {
+    let bin = codexBin || 'codex';
+    if (codexNeedsShell(bin)) { done(null); return; }
+    const home = resolve(tmpdir(), 'synabun-codex-gate-probe');
+    try { mkdirSync(home, { recursive: true }); } catch {}
+    const args = [...codexGateHookFlags(command), 'app-server'];
+    if (/\.js$/i.test(bin)) { args.unshift(bin); bin = process.execPath; }
+    let proc;
+    try {
+      proc = spawnImpl(bin, args, { env: { ...process.env, CODEX_HOME: home, NO_COLOR: '1' }, stdio: ['pipe', 'pipe', 'ignore'], shell: false });
+    } catch { done(null); return; }
+    let buf = '';
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { proc.kill(); } catch {}
+      done(value);
+    };
+    const timer = setTimeout(() => finish(null), timeoutMs);
+    timer.unref?.();
+    const send = (message) => { try { proc.stdin.write(`${JSON.stringify(message)}\n`); } catch {} };
+    proc.on('error', () => finish(null));
+    proc.on('exit', () => finish(null));
+    proc.stdout.setEncoding?.('utf8');
+    proc.stdout.on('data', (chunk) => {
+      buf += chunk;
+      let index;
+      while ((index = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, index);
+        buf = buf.slice(index + 1);
+        let message;
+        try { message = JSON.parse(line); } catch { continue; }
+        if (message.id === 1) { send({ method: 'initialized' }); send({ id: 2, method: 'hooks/list', params: {} }); }
+        else if (message.id === 2) { const hook = findGateHook(message.result, command); finish(hook ? { key: hook.key, hash: hook.hash } : null); }
+      }
+    });
+    send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'synabun-route-gate-probe', version: '1.0.0' } } });
+  });
+}
+
+const trustCache = new Map();
+
+/** { key, hash } for the gate hook on this Codex binary, or null (probe failed). Cached per binary + command. */
+export function codexGateTrust({ codexBin = 'codex', command = codexGateHookCommand(), timeoutMs = 12_000, spawnImpl = spawn } = {}) {
+  const cacheKey = `${codexBin}\n${command}`;
+  if (!trustCache.has(cacheKey)) {
+    trustCache.set(cacheKey, probe({ codexBin, command, timeoutMs, spawnImpl }).then((trust) => { if (!trust) trustCache.delete(cacheKey); return trust; }));
+  }
+  return trustCache.get(cacheKey);
+}
+
+/**
+ * An Assistant task run's Codex worker: the browser policy's hook
+ * (codex-browser-policy-hook.mjs, evaluated locally) as SDK `config`, trusted
+ * like the brain's gate hook: { command, config }, or null when this Codex
+ * cannot run it trusted (no absolute binary, the probe failed). The run then
+ * has the policy as instructions only (CODEX_BROWSER_POLICY_UNTRUSTED_NOTE).
+ */
+export async function codexBrowserPolicyHook({ codexBin = null, trust = codexGateTrust, nodePath = process.execPath } = {}) {
+  if (!codexBin || codexNeedsShell(codexBin)) return null;
+  const command = codexGateHookCommand({ nodePath, hookPath: CODEX_BROWSER_POLICY_HOOK_PATH });
+  let trusted = null;
+  try { trusted = await trust({ codexBin, command }); } catch { trusted = null; }
+  const config = codexHookConfig(command, trusted);
+  return config ? { command, config } : null;
+}
+
+/**
+ * Bootstrap payload for the codex skin handler (role "assistant"): the flags
+ * and the env the hook reads, or null when Codex cannot run a trusted hook.
+ * `remote`: a WhatsApp session — the hook denies a call it could not check.
+ */
+export async function codexRouteGateBootstrap({ url, session, token, codexBin = 'codex', trust = codexGateTrust, remote = false } = {}) {
+  if (!url || !session || !token) return null;
+  if (codexNeedsShell(codexBin)) return null;
+  const command = codexGateHookCommand();
+  let trusted = null;
+  try { trusted = await trust({ codexBin, command }); } catch { trusted = null; }
+  if (!trusted) return null;
+  return {
+    flags: codexGateHookFlags(command, trusted),
+    env: { SYNABUN_ROUTE_GATE_URL: String(url), SYNABUN_ROUTE_GATE_SESSION: String(session), SYNABUN_ROUTE_GATE_TOKEN: String(token), ...(remote === true ? { SYNABUN_ROUTE_GATE_REMOTE: '1' } : {}) },
+  };
+}

package/neural-interface/lib/assistant-route-gate.js

@@ -0,0 +1,212 @@
+// ═══════════════════════════════════════════
+// SynaBun — Assistant route gate (route before working, per turn)
+// ═══════════════════════════════════════════
+//
+// Every brain turn starts unrouted. Until agent_route answers in that turn,
+// every tool call outside the exempt set is refused before it runs, and the
+// refusal tells the model what to do instead; the turn goes on so it can route.
+// One module for every host: the Claude PreToolUse hook, the OpenCode plugin
+// (opencode-route-gate.js), the Codex PreToolUse hook (codex-route-gate-hook.mjs)
+// and the reactive fallback all ask the same gate.
+//
+//   unrouted  turn start: exempt tools only
+//   open      agent_route approved kind "direct" with no continuation: every tool, for the rest of the turn
+//   held      approved dispatch / pending / continuation / declined / expired, or a "chat" route,
+//             or questions to the user still open (agent_clarify pending, agent_route "clarifying"):
+//             exempt tools only, and the refusal names the next step
+//   failed    agent_route itself errored (router or catalog failure): open for the rest of the turn
+//
+// Another agent_route call in the same turn re-evaluates the state. After
+// ROUTE_GATE_MAX_REFUSALS refusals in one turn the caller aborts the turn.
+// A brain that cannot reach agent_route at all (its SynaBun MCP server failed,
+// or it lacks the assistant role) is marked unavailable and not gated.
+
+export const ROUTE_GATE_MAX_REFUSALS = 8;
+
+/** Always allowed, matched by base name (lower case) whatever the host prefix. */
+export const ROUTE_GATE_EXEMPT = Object.freeze([
+  // Memory
+  'recall', 'remember', 'reflect', 'memories', 'forget', 'restore', 'category', 'sync',
+  // Orchestration (agent_dispatch is gated by the router and the clarifier itself)
+  'agent_route', 'agent_clarify', 'agent_catalog', 'agent_list', 'agent_status', 'agent_read', 'agent_send', 'agent_wait', 'agent_stop', 'agent_focus', 'agent_usage', 'agent_dispatch',
+  // Asking the user (OpenCode's own tool is `question`)
+  'AskUserQuestion', 'choice', 'question',
+  // Profile, the images the user attached, the desktop lease
+  'profile', 'image_staged', 'computer_status',
+  // Host plumbing routing needs: MCP tools are deferred behind ToolSearch
+  'ToolSearch', 'TodoWrite',
+]);
+const EXEMPT = new Set(ROUTE_GATE_EXEMPT.map((name) => name.toLowerCase()));
+
+/** "mcp__SynaBun__recall" / "SynaBun_recall" / "SynaBun.recall" → "recall"; other names unchanged. */
+export function toolBaseName(name) {
+  const text = String(name ?? '').trim();
+  const match = /^mcp__synabun__(.+)$/i.exec(text) || /^synabun[_.:/-]+(.+)$/i.exec(text);
+  return match ? match[1] : text;
+}
+
+export function isExemptTool(name) {
+  return EXEMPT.has(toolBaseName(name).toLowerCase());
+}
+
+/** A held gate while the user has not answered the brain's clarify questions. */
+export const CLARIFY_HOLD_TEXT = 'Waiting for the user\'s answers to your questions: end your turn now with one short line. The answers arrive as a [SynaBun Mailbox] clarify_answered event, or as the user\'s next message. Work that does not depend on them: route and dispatch it with independent:true.';
+
+function targetLabel(target) {
+  if (!target) return 'the chosen model';
+  const model = target.model || target.label || 'default';
+  return target.kind === 'direct' ? (target.label || target.model || 'the chosen model') : `${target.provider}/${model}`;
+}
+
+/**
+ * The gate state a route result leads to: { state, text } where text is the
+ * next step a held gate names in its refusals. `taskClass` is the class the
+ * brain routed: a "chat" route unlocks nothing (conversation needs no tools),
+ * so it cannot be used to skip the user's saved routes.
+ */
+export function gateStateFor(result, { taskClass = null } = {}) {
+  if (!result || typeof result !== 'object' || result.ok === false || !result.status) return { state: 'failed', text: null };
+  const target = result.target || null;
+  switch (result.status) {
+    case 'approved':
+      if (String(taskClass || '').toLowerCase() === 'chat') return { state: 'held', text: 'A chat route unlocks no tools: answer in text, or route this task again with its real task_class (quick, research, code, browser, …).' };
+      if (result.continuation || target?.continuation) return { state: 'held', text: `Continuing on ${targetLabel(target)}: end your turn now with one short line; SynaBun runs the task on that model next.` };
+      if (target?.kind === 'dispatch') return { state: 'held', text: `Routed to ${targetLabel(target)}: call agent_dispatch with route_id ${result.routeId}; do not do this task here.` };
+      return { state: 'open', text: null };
+    case 'pending':
+      return { state: 'held', text: 'Waiting for the user\'s route choice: end your turn now with one short line. The choice arrives as a [SynaBun Mailbox] route_decided event.' };
+    case 'declined':
+      // Image / video creation with no model that makes the medium (design: none that can see): nothing can run it.
+      if (result.reason === 'no_capable_model' && result.needs === 'vision') return { state: 'held', text: 'No model in the catalog can see images, which this task needs: do not start or dispatch it; tell the user which Model routes row needs a model.' };
+      if (result.reason === 'no_capable_model') return { state: 'held', text: 'No model in the catalog can make what this task creates: do not start or dispatch it; tell the user which Model routes row needs a model.' };
+      return { state: 'held', text: 'The user declined this route: do not start the task; ask what they would like instead.' };
+    case 'expired':
+    case 'cancelled':
+      return { state: 'held', text: 'This route is no longer valid: do not start the task; ask the user how to proceed.' };
+    case 'clarifying':
+      return { state: 'held', text: CLARIFY_HOLD_TEXT };
+    default:
+      return { state: 'failed', text: null };
+  }
+}
+
+const ROUTE_TOOL_RE = /^(?:mcp__synabun__|synabun[_.:/-]+)agent_route$/i;
+const DOWN_STATUSES = new Set(['failed', 'disabled', 'needs_auth', 'needs-auth', 'needs_client_registration', 'cancelled']);
+
+/**
+ * Whether a Claude brain can route, from its `system/init` event:
+ * { available, reason } or null when it cannot tell yet (still connecting).
+ */
+export function claudeRouteAvailability(event) {
+  const servers = Array.isArray(event?.mcp_servers) ? event.mcp_servers : null;
+  if (!servers) return null;
+  const synabun = servers.find((s) => String(s?.name || '').toLowerCase() === 'synabun');
+  if (!synabun) return { available: false, reason: 'this brain has no SynaBun MCP server' };
+  const status = String(synabun.status || '').toLowerCase();
+  if (status === 'connected') {
+    if (!Array.isArray(event.tools)) return null;
+    return event.tools.some((t) => ROUTE_TOOL_RE.test(String(t)))
+      ? { available: true }
+      : { available: false, reason: 'agent_route is missing from its SynaBun tools' };
+  }
+  if (DOWN_STATUSES.has(status)) return { available: false, reason: `its SynaBun MCP server is ${status.replace(/[_-]/g, ' ')}` };
+  return null;
+}
+
+/**
+ * The same from an `mcp_status` event: OpenCode's `{ name: { status } }` map
+ * or Codex's `[{ name, status }]` startup list. null when SynaBun is not in it
+ * or its status says nothing yet.
+ */
+export function mcpStatusRouteAvailability(servers) {
+  let status;
+  if (Array.isArray(servers)) {
+    const row = servers.find((s) => String(s?.name || '').toLowerCase() === 'synabun');
+    if (!row) return null;
+    status = row.status;
+  } else if (servers && typeof servers === 'object') {
+    const key = Object.keys(servers).find((k) => k.toLowerCase() === 'synabun');
+    if (!key) return null;
+    status = servers[key]?.status ?? servers[key];
+  } else return null;
+  const s = String(status || '').toLowerCase();
+  if (s === 'connected' || s === 'ready') return { available: true };
+  if (DOWN_STATUSES.has(s)) return { available: false, reason: `its SynaBun MCP server is ${s.replace(/[_-]/g, ' ')}` };
+  return null;
+}
+
+/**
+ * One gate per assistant session.
+ * @param {object} [opts]
+ * @param {string} [opts.sessionId]        named in the refusal (assistant_session_id)
+ * @param {() => string} [opts.routeTool]  the agent_route name this host's model sees
+ * @param {number} [opts.maxRefusals]
+ */
+export function createRouteGate({ sessionId = null, routeTool = () => 'agent_route', maxRefusals = ROUTE_GATE_MAX_REFUSALS } = {}) {
+  let state = 'unrouted';
+  let heldText = null;
+  let refusals = 0;
+  let turn = 0;
+  let aborted = false;
+  let routeId = null;
+  let unavailable = null;
+
+  /** `carry` keeps the refusal count (the reactive fallback's follow-up turn still counts toward the loop guard). */
+  function startTurn({ open = false, carry = false } = {}) {
+    turn += 1;
+    state = open ? 'open' : 'unrouted';
+    heldText = null;
+    if (!carry) { refusals = 0; aborted = false; }
+    routeId = null;
+  }
+  /** `meta.taskClass`: the class the brain routed (a chat route holds). */
+  function onRouteResult(result, meta = {}) {
+    const next = gateStateFor(result, meta);
+    state = next.state;
+    heldText = next.text;
+    routeId = result?.routeId || null;
+    return snapshot();
+  }
+  function onRouteError() {
+    state = 'failed';
+    heldText = null;
+    return snapshot();
+  }
+  /**
+   * agent_clarify answered: still waiting for the user holds the rest of the
+   * turn (nothing that depends on the answers may start); answered or skipped
+   * in the call leaves the gate as it was (the task is routed next).
+   */
+  function onClarify(result) {
+    if (result?.status !== 'pending') return snapshot();
+    state = 'held';
+    heldText = CLARIFY_HOLD_TEXT;
+    return snapshot();
+  }
+  function refusalText(tool) {
+    const name = toolBaseName(tool) || 'this tool';
+    if (state === 'held' && heldText) return `SynaBun route gate: ${name} was refused. ${heldText}`;
+    return `SynaBun route gate: ${name} was refused because this turn is not routed. Call ${routeTool()} first (task_class, one-line summary, confidence, 1-3 proposals${sessionId ? `, assistant_session_id "${sessionId}"` : ''}) and follow its status: approved + direct opens every tool for this turn. Memory tools, agent_* tools and asking the user work without routing. For plain conversation, just answer in text.`;
+  }
+  /**
+   * The brain cannot reach agent_route (reason), or can again (null). While
+   * unavailable nothing is refused: a brain that cannot route must not be
+   * locked out of every tool. Survives turn starts; the host re-evaluates it.
+   */
+  function setUnavailable(reason) { unavailable = reason ? String(reason) : null; }
+  /** { allow, exempt?, reason?, refusals, abort } — abort is true once, on the refusal that reaches the limit. */
+  function check(tool) {
+    if (isExemptTool(tool)) return { allow: true, exempt: true, state, refusals };
+    if (unavailable) return { allow: true, state, refusals, unavailable: true };
+    if (state === 'open' || state === 'failed') return { allow: true, state, refusals };
+    refusals += 1;
+    const abort = !aborted && refusals >= maxRefusals;
+    if (abort) aborted = true;
+    return { allow: false, state, refusals, abort, reason: refusalText(tool) };
+  }
+  function snapshot() { return { state, turn, refusals, routeId, held: heldText, aborted, unavailable }; }
+
+  return { startTurn, onRouteResult, onRouteError, onClarify, setUnavailable, check, snapshot, isOpen: () => !!unavailable || state === 'open' || state === 'failed' };
+}
+
+export const ROUTE_GATE_LOOP_MESSAGE = 'Stopped: the assistant kept working without routing.';