llm-switcher 1.2.7 → 1.2.8

package/state.mjs

@@ -134,6 +134,10 @@ export const paths = {
   envClaudeSh: path.join(STATE_DIR, 'env-claude.sh'),
   envCodexCmd: path.join(STATE_DIR, 'env-codex.cmd'),
   envCodexSh: path.join(STATE_DIR, 'env-codex.sh'),
+  // One line per tool, written with that tool's env file: what the launcher shows the person at
+  // launch. Empty exactly when the tool is not routed, so the launcher needs no second condition.
+  routeClaude: path.join(STATE_DIR, 'route-claude.txt'),
+  routeCodex: path.join(STATE_DIR, 'route-codex.txt'),
   // The gateway port of the last switch on. The shim scrubs a stale loopback base URL
   // against it, so a shell opened before a port change still reaches the right gateway.
   gatewayPort: path.join(STATE_DIR, 'gateway.port'),
@@ -454,6 +458,11 @@ export function validateProfileInput(p) {
   return null;
 }
 
+/** True while a profile still carries the example config's placeholder baseURL or apiKey. */
+export function hasPlaceholder(p) {
+  return !p?.baseURL || /YOUR-|REPLACE-ME/i.test(`${p.baseURL} ${p.apiKey ?? ''}`);
+}
+
 export function needsMigration(cfg) {
   if (!cfg || typeof cfg !== 'object') return false;
   if (Object.hasOwn(cfg, 'activeProfile')) return true;
@@ -1227,8 +1236,9 @@ export function setTargetProfile(cfg, target, profileKey) {
   if (!profileAcceptsTarget(p, tool)) {
     return `Profile "${profileKey}" only accepts "${p.tool || p.inFormat}" input and cannot serve target "${tool}"`;
   }
+  // No legacy `activeProfile` here: needsMigration flags it, so every switch would re-run the
+  // migration on the next load and leave another config.json.bak-* holding the API keys.
   map[tool] = profileKey;
-  cfg.activeProfile = profileKey;
   return null;
 }
 
@@ -1240,7 +1250,6 @@ export function activateProfile(cfg, profileKey) {
   for (const t of TOOLS) {
     if (profileAcceptsTarget(p, t)) map[t] = profileKey;
   }
-  cfg.activeProfile = profileKey;
   return null;
 }
 
@@ -1300,6 +1309,16 @@ export function primaryModel(profile) {
   return '';
 }
 
+// What a person needs at launch: which profile took the traffic, the host it goes to, the model it
+// maps to, and whether the 1M window is on, because that changes what the session costs. Never the
+// API key: a desktop notification reads this line, and so can any shell.
+function routeLine(tool, key, profile) {
+  let host = '';
+  try { host = new URL(profile.baseURL).host; } catch { /* a profile may carry no address yet */ }
+  return [`${tool} -> ${key}`, host, primaryModel(profile), anyTier1M(profile) ? '1M' : '']
+    .filter(Boolean).join(' | ');
+}
+
 // Derive launcher state from activeProfiles (single source of truth).
 export function computeLaunchState(cfg, port) {
   const map = getActiveMap(cfg);
@@ -1310,7 +1329,15 @@ export function computeLaunchState(cfg, port) {
 
   // One interceptor serves both tools (R3) and its port lives at the top level of config.json
   // (R3b). The per-profile port went with the per-profile host and prefix.
-  const bfPort = parsePort(cfg?.blindfold?.port) || DEFAULT_BLINDFOLD_PORT;
+  // Precedence mirrors resolvePort for the gateway: the environment, then the file, then the
+  // default. Without the variable a second instance could not move the interceptor, and a gateway
+  // sent to 3457 by --port or by LLM_SWITCHER_PORT landed on the interceptor's own port.
+  let bfPort = parsePort(process.env.LLM_SWITCHER_BLINDFOLD_PORT)
+    || parsePort(cfg?.blindfold?.port)
+    || DEFAULT_BLINDFOLD_PORT;
+  if (bfPort === port) {
+    bfPort = port === DEFAULT_BLINDFOLD_PORT ? DEFAULT_BLINDFOLD_PORT + 1 : DEFAULT_BLINDFOLD_PORT;
+  }
   const interceptor = `http://127.0.0.1:${bfPort}`;
   const loopbackOnly = '127.0.0.1,localhost';
   const proxyPairs = () => [
@@ -1339,7 +1366,10 @@ export function computeLaunchState(cfg, port) {
     // no --config (F1, F3, F4). The shim of the tool may therefore never capture the traffic
     // of the other tool, and a restart cannot leave a stale override behind.
     envClaude: [],
-    envCodex: []
+    envCodex: [],
+    // The launcher notice, one line per tool. Empty for a tool that is not routed (A1).
+    routeClaude: claude ? routeLine('claude', map.claude, claude) : '',
+    routeCodex: codex ? routeLine('codex', map.codex, codex) : ''
   };
 
   // NODE_EXTRA_CA_CERTS is deliberately absent from env-claude: the shim decides it at launch,
@@ -1446,6 +1476,7 @@ export function emptyToolEnvFiles(tool) {
     const before = codex ? readOrEmpty(paths.envCodexSh) : '';
     writeAtomic(codex ? paths.envCodexCmd : paths.envClaudeCmd, '');
     writeAtomic(codex ? paths.envCodexSh : paths.envClaudeSh, '');
+    writeAtomic(codex ? paths.routeCodex : paths.routeClaude, '');
     return before !== '';
   });
   return { codexRouteChanged, codexDaemon: codexRouteChanged ? restartCodexDaemon([]) : undefined };
@@ -1513,6 +1544,10 @@ function writeLaunchState(cfg, port) {
   try {
     writeToolFiles(st.envClaude, paths.envClaudeSh, paths.envClaudeCmd);
     writeToolFiles(st.envCodex, paths.envCodexSh, paths.envCodexCmd);
+    writeAtomic(paths.routeClaude, st.routeClaude ? `${st.routeClaude}
+` : '');
+    writeAtomic(paths.routeCodex, st.routeCodex ? `${st.routeCodex}
+` : '');
     st.codexRouteChanged = readOrEmpty(paths.envCodexSh) !== codexBefore;
     // Recorded on switch on so a shell opened while the gateway ran can still recognize its own
     // stale loopback URL later, after the port changed (R8).
@@ -1537,7 +1572,8 @@ export function clearLaunchState(port) {
     // leave env.sh present and containing no export and no unset.
     writeAtomic(paths.envCmd, STUB_CMD);
     writeAtomic(paths.envSh, STUB_SH);
-    for (const f of [paths.envClaudeCmd, paths.envClaudeSh, paths.envCodexCmd, paths.envCodexSh]) {
+    for (const f of [paths.envClaudeCmd, paths.envClaudeSh, paths.envCodexCmd, paths.envCodexSh,
+      paths.routeClaude, paths.routeCodex]) {
       writeAtomic(f, '');
     }
     return codexBefore !== '';

package/switch.cmd

@@ -1,2 +1,2 @@
-@echo off
-node "%~dp0switch.mjs" %*
+@echo off
+node "%~dp0switch.mjs" %*

package/switch.mjs

@@ -4,7 +4,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { spawn, execFileSync } from 'node:child_process';
 import {
-  ROOT_DIR, STATE_DIR, TOOLS, configPath, claudeSettingsPath, paths, certCoversHost, loadConfig, getConfigLoadError, saveConfig,
+  ROOT_DIR, STATE_DIR, TOOLS, configPath, hasPlaceholder, claudeSettingsPath, paths, certCoversHost, loadConfig, getConfigLoadError, saveConfig,
   resolvePort, parsePort, findProfileKey, getActiveMap, setTargetProfile, activateProfile, deactivateAll,
   applyLaunchState, clearLaunchState, computeLaunchState,
   modelSlotsForProfile, modelForSlot, model1MForSlot, readAdminToken, adminTokenPath, openLog,
@@ -14,6 +14,7 @@ import {
   casClearToolPointers, emptyToolEnvFiles, syncInterceptorTools
 } from './state.mjs';
 import { runProbe, runCheck } from './contract.mjs';
+import { installPlugin, uninstallPlugin, pluginStatus, PLUGIN_NAME } from './plugin.mjs';
 import {
   SHIM_DIR, installShims, uninstallShims, shimStatus, pathExportLine, pathOrderHint,
   suggestedRcFiles, auditRunningProcesses
@@ -391,6 +392,10 @@ async function turnOn(profileName, cliTarget) {
 
   // Plan on a copy. Nothing is written until every check below passes.
   let planned = planSwitch(config, key, cliTarget);
+  // The example config routes to YOUR-ROUTER-HOST; activating it silently makes every request fail.
+  if (hasPlaceholder(planned.profiles[key])) {
+    console.warn(`[WARN] Profile "${show(key)}" still has a placeholder baseURL/apiKey. Edit ${configPath} first, or requests will fail.`);
+  }
   console.log(`Activating profile: [${show(planned.profiles[key].name || key)}] (${show(key)})${cliTarget ? ` for ${cliTarget}` : ''} on port ${port}...`);
 
   const gatewayState = await probeGateway(port);
@@ -777,6 +782,47 @@ async function manageService(action) {
   console.log('Usage: switch service [install|uninstall]');
 }
 
+// The launch notice, as a hook inside each tool. Opt-in: the routing does not depend on it, and a
+// person who installs nothing still gets the toast from the shim.
+async function managePlugin(action = 'status') {
+  const act = (action || 'status').toLowerCase();
+
+  if (act === 'install' || act === 'on') {
+    const { CURRENT_VERSION } = await import('./version.mjs');
+    const { installed, failed, paths } = installPlugin({}, CURRENT_VERSION);
+    for (const tool of installed) console.log(`[OK] ${tool}: ${paths[tool]}`);
+    for (const f of failed) console.error(`[Error] ${f.tool}: ${f.reason}`);
+    if (installed.length) {
+      console.log('\nNeither settings.json nor config.toml was opened. Each tool reads a file of its own.');
+      console.log(`Claude Code loads it on the next session as ${PLUGIN_NAME}@skills-dir.`);
+      console.log('Codex asks you once to trust a new hook. Accept it, or the hook stays off.');
+      console.log('\nTo remove it:  switch plugin uninstall');
+    }
+    if (failed.length) process.exit(1);
+    return;
+  }
+
+  if (act === 'uninstall' || act === 'off' || act === 'remove') {
+    const { installed, failed, paths } = uninstallPlugin();
+    for (const tool of installed) console.log(`[OK] ${tool}: removed from ${paths[tool]}`);
+    for (const f of failed) console.error(`[Error] ${f.tool}: ${f.reason}`);
+    if (failed.length) process.exit(1);
+    return;
+  }
+
+  const st = pluginStatus();
+  console.log('=== Launch notice (hook inside each coding tool) ===\n');
+  console.log(`Claude Code: ${st.claude.installed ? `INSTALLED as ${st.claude.id}` : 'not installed'}`);
+  console.log(`             ${st.claude.path}`);
+  console.log(`Codex      : ${st.codex.installed ? 'INSTALLED' : 'not installed'}`);
+  console.log(`             ${st.codex.path}`);
+  if (!st.claude.installed || !st.codex.installed) {
+    console.log(`\nThe notice is optional. Without it the gateway still routes every request,`);
+    console.log(`and the shim still raises its own notice at launch.`);
+    console.log(`To add it:  switch plugin install`);
+  }
+}
+
 async function manageShim(action = 'status') {
   const act = (action || 'status').toLowerCase();
 
@@ -862,7 +908,7 @@ async function runDoctor() {
     if (!key) continue;
     const p = config.profiles[key];
     if (!p) warn(`[WARN] Target ${t} points to missing profile "${show(key)}".`);
-    else if (!p.baseURL || /YOUR-|REPLACE-ME/i.test(`${p.baseURL} ${p.apiKey}`)) warn(`[WARN] Profile "${show(key)}" (${t}) still has placeholder baseURL/apiKey.`);
+    else if (hasPlaceholder(p)) warn(`[WARN] Profile "${show(key)}" (${t}) still has placeholder baseURL/apiKey.`);
     if (p && t === 'codex') {
       const codexWarning = codexPublicModelsWarning(show(key), p);
       if (codexWarning) warn(`[WARN] ${codexWarning}`);
@@ -1109,6 +1155,8 @@ if (cmd === 'off' || cmd === 'stop') {
   await manageService(subArg.toLowerCase() || 'status');
 } else if (cmd === 'shim' || cmd === 'shims') {
   await manageShim(subArg.toLowerCase() || 'status');
+} else if (cmd === 'plugin' || cmd === 'plugins') {
+  await managePlugin(subArg.toLowerCase() || 'status');
 } else if (Object.hasOwn(TARGET_ALIASES, cmd)) {
   await turnOn(subArg, TARGET_ALIASES[cmd]);
 } else if (cmd === 'ui' || cmd === 'web' || cmd === 'gui') {
@@ -1141,6 +1189,9 @@ if (cmd === 'off' || cmd === 'stop') {
   console.log('  switch shim install            # Auto-inject env into resumed sessions (claude --resume)');
   console.log('  switch shim status             # Check shims + detect sessions bypassing the gateway');
   console.log('  switch shim uninstall          # Remove launcher shims');
+  console.log('  switch plugin install          # Optional launch notice inside Claude Code & Codex');
+  console.log('  switch plugin status           # Is that notice installed');
+  console.log('  switch plugin uninstall        # Remove that notice');
   console.log('  switch off [target]            # Restore official endpoints (all, or one target)');
   console.log('  switch models [--refresh]      # Show discovered models catalog for Claude Code & Codex');
   console.log('  switch contract-probe [--model m] # Drive the contract-lab variants through the gateway');

package/tests/blindfold.test.mjs

@@ -137,7 +137,7 @@ test('a compressed response body is decoded for the capture', () => {
   assert.equal(decodeBody(zlib.gzipSync(Buffer.from(sse)), 'GZIP'), sse, 'must be case-insensitive');
   assert.equal(decodeBody(zlib.brotliCompressSync(Buffer.from(sse)), 'br'), sse);
   assert.equal(decodeBody(zlib.deflateSync(Buffer.from(sse)), 'deflate'), sse);
-  assert.equal(decodeBody(zlib.zstdCompressSync(Buffer.from(sse)), 'zstd'), sse);
+  if (typeof zlib.zstdCompressSync === 'function') assert.equal(decodeBody(zlib.zstdCompressSync(Buffer.from(sse)), 'zstd'), sse);
 });
 
 test('an unencoded body is passed through untouched', () => {

package/tests/cdp.mjs

@@ -82,6 +82,7 @@ export class Page {
     this.dialogs = [];       // { type, message } for every alert, confirm and prompt
     this.dialogPolicy = 'accept';
     this.inflight = new Map();   // requestId -> url, so a stuck request can be named
+    this.requests = [];      // { method, url } for every request, so a double submit is countable
     this.ws.addEventListener('message', (ev) => this.#onMessage(JSON.parse(ev.data)));
   }
 
@@ -93,7 +94,10 @@ export class Page {
     });
     this.on('Runtime.exceptionThrown', (e) => this.problems.push(`exception: ${e.exceptionDetails.exception?.description || e.exceptionDetails.text}`));
     this.on('Log.entryAdded', (e) => { if (e.entry.level === 'error') this.problems.push(`log: ${e.entry.text} ${e.entry.url || ''}`.trim()); });
-    this.on('Network.requestWillBeSent', (e) => this.inflight.set(e.requestId, e.request.url));
+    this.on('Network.requestWillBeSent', (e) => {
+      this.inflight.set(e.requestId, e.request.url);
+      this.requests.push({ method: e.request.method, url: e.request.url });
+    });
     // A new document ends every request of the old one, and no event says so for some of them.
     this.on('Page.frameNavigated', (e) => { if (!e.frame.parentId) this.inflight.clear(); });
     this.on('Network.loadingFinished', (e) => this.inflight.delete(e.requestId));
@@ -132,7 +136,22 @@ export class Page {
   close() { try { this.ws.close(); } catch { /* already closed */ } }
 
   // Forget what happened so far, so a test asserts only on the action it just made.
-  clearProblems() { this.problems.length = 0; this.badResponses.length = 0; this.dialogs.length = 0; }
+  clearProblems() {
+    this.problems.length = 0;
+    this.badResponses.length = 0;
+    this.dialogs.length = 0;
+    this.requests.length = 0;
+  }
+
+  // Every request of one method whose URL holds `part`. A double submit is two entries here.
+  sent(method, part) { return this.requests.filter(r => r.method === method && r.url.includes(part)); }
+
+  // A real viewport change, the way a narrow window is, so a media query takes effect.
+  async resize(width, height) {
+    await this.send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false });
+    // A layout pass runs on the next frame, so a measurement taken at once reads the old box.
+    await this.evaluate('new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)))');
+  }
 
   // Wait until no request is in flight for `quiet` ms. A click starts a request, and the page then
   // starts a second one to read the state back, so one quiet moment is not enough.

package/tests/dashboard.e2e.test.mjs

@@ -667,4 +667,120 @@ describe('dashboard, driven in a real browser', { skip: skipReason() }, () => {
       await expectScreenMatchesDisk('after outside edit');
     });
   });
+  // Found by a human-behaviour pass over the running dashboard on 2026-09-29: a real browser, real
+  // clicks and real keys, never a value set through the page's own JavaScript. Each test here is the
+  // reproduction of one finding from that pass.
+  describe('what a person notices when pressing the dashboard hard', () => {
+    const editButtons = () => page.evaluate(
+      `[...document.querySelectorAll('#profiles-grid .pcard button')].map(b => b.textContent.trim()).filter(t => /Edit/.test(t))`
+    );
+
+    it('gives a card back its normal Edit button after a close that saved nothing', async () => {
+      await editProfile('intact-claude');
+      await page.waitFor('document.getElementById("profile-modal-overlay").style.display === "grid"', 'the dialog');
+      await page.key('Escape');
+      await page.waitFor('document.getElementById("profile-modal-overlay").style.display === "none"', 'the dialog to close');
+      assert.deepEqual((await editButtons()).filter(t => /Editing/.test(t)), [],
+        'a dialog closed without saving left the card in the editing state');
+    });
+
+    it('moves the keyboard into the dialog when it opens', async () => {
+      await editProfile('intact-claude');
+      await page.waitFor('document.getElementById("profile-modal-overlay").style.display === "grid"', 'the dialog');
+      const inside = await page.evaluate(
+        `document.getElementById('profile-modal-overlay').contains(document.activeElement)`
+      );
+      assert.equal(inside, true, 'the focus stayed behind the overlay, so the first Tab leaves the dialog');
+    });
+
+    it('never shows the connection result of the profile opened before', async () => {
+      await editProfile('intact-claude');
+      await page.waitFor('document.getElementById("profile-modal-overlay").style.display === "grid"', 'the dialog');
+      await act(() => page.clickText('#profile-modal-overlay button', 'Test Connection'));
+      await page.waitFor(`document.getElementById('test-result').textContent.trim().length > 0`, 'a result');
+      await page.key('Escape');
+      await act(() => page.clickText('button', '+ Add Profile'));
+      assert.equal(await page.text('#test-result'), '',
+        'an untested new profile showed the connection result of the profile opened before it');
+    });
+
+    it('sends one save for one double-click on Save Profile', async () => {
+      await act(() => page.clickText('button', '+ Add Profile'));
+      await page.type('#p-key', 'dbl');
+      await page.type('#p-name', 'Double click');
+      await page.type('#p-url', 'https://dbl.example.io/v1');
+      await page.type('#p-key-val', 'sk-dbl');
+      page.clearProblems();
+      const save = '#profile-modal-overlay button[type="submit"]';
+      await page.click(save);
+      await page.click(save);
+      await page.idle();
+      assert.equal(page.sent('POST', '/api/save-profile').length, 1,
+        'a double-click sent the save twice, because the button is not disabled while it runs');
+    });
+
+    it('says so when a model search matches nothing', async () => {
+      await open('#/models');
+      await page.waitFor(`document.querySelectorAll('#catalog-claude-items .row').length > 0`, 'the catalog rows');
+      await page.type('#catalog-search', 'zzz-nothing-matches-this-zzz');
+      await page.waitFor(
+        `[...document.querySelectorAll('#catalog-claude-items .row, #catalog-codex-items .row')].every(r => r.offsetParent === null)`,
+        'every row hidden'
+      );
+      const shown = await page.evaluate(`(() => {
+        const visible = (e) => e.offsetParent !== null;
+        const message = [...document.querySelectorAll('#view-models *')]
+          .some(e => visible(e) && /no match|nothing matches|no model/i.test(e.textContent));
+        const badge = document.getElementById('badge-claude-count');
+        return { message, badge: badge && visible(badge) ? badge.textContent.trim() : '' };
+      })()`);
+      assert.equal(shown.message, true, 'an empty result looked like a broken page: no message at all');
+      assert.doesNotMatch(shown.badge, /^[1-9]/, `the header kept the unfiltered count: "${shown.badge}"`);
+    });
+
+    it('keeps the navigation reachable on a narrow window', async () => {
+      await page.resize(400, 900);
+      try {
+        const box = await page.evaluate(`(() => {
+          const aside = document.querySelector('aside'), nav = document.querySelector('aside nav');
+          const a = aside.getBoundingClientRect(), n = nav.getBoundingClientRect();
+          return { navHeight: n.height, navBottom: n.bottom, asideBottom: a.bottom, asideHeight: a.height };
+        })()`);
+        assert.ok(box.navHeight > 0, 'the navigation has no height at 400 px');
+        assert.ok(box.navBottom <= box.asideBottom + 1,
+          `the navigation is drawn outside the sidebar (nav bottom ${box.navBottom}, sidebar bottom ${box.asideBottom}, sidebar height ${box.asideHeight})`);
+        assert.equal(await page.visible('aside nav a'), true, 'no navigation link is visible at 400 px');
+      } finally {
+        await page.resize(1280, 900);
+      }
+    });
+
+    it('does not let a long profile name break the dialog header', async () => {
+      const cfg = fx.config();
+      cfg.profiles['intact-claude'].name = 'N'.repeat(300);
+      fx.writeConfig(cfg);
+      await open('#/routes');
+      await editProfile('intact-claude');
+      await page.waitFor('document.getElementById("profile-modal-overlay").style.display === "grid"', 'the dialog');
+      const t = await page.evaluate(`(() => {
+        const e = document.getElementById('form-title');
+        return { scroll: e.scrollWidth, client: e.clientWidth };
+      })()`);
+      assert.ok(t.scroll <= t.client + 1,
+        `the header text is wider than its box (${t.scroll} > ${t.client}), so it clips mid-character`);
+    });
+
+    it('opens the payload preview while auto-refresh is on', async () => {
+      const sent = await fx.messages();
+      assert.equal(sent.status, 200, sent.text);
+      await open('#/logs');
+      await page.waitFor(`document.querySelectorAll('#inspector-logs-container details').length >= 1`, 'at least one log row with a preview');
+      assert.equal(await page.evaluate(`document.getElementById('chk-auto-refresh-logs').checked`), true,
+        'this test needs the default, which is auto-refresh on');
+      // One click, the way a person clicks. A control that the poll detaches fails right here.
+      await page.click('#inspector-logs-container details summary');
+      const opened = await page.evaluate(`Boolean(document.querySelector('#inspector-logs-container details[open]'))`);
+      assert.equal(opened, true, 'the poll replaces the row, so the preview cannot be opened while it runs');
+    });
+  });
 });

package/tests/gateway.e2e.test.mjs

@@ -470,7 +470,7 @@ test('save-profile rejects a model name that could act as a command', async () =
   assert.equal(ok.status, 200);
 });
 
-test('Codex WS transport: upstream 429 becomes response.failed with rate_limit_exceeded', async () => {  const ws = new WebSocket(`ws://127.0.0.1:${proxyPort}/v1/responses`);
+test('Codex WS transport: upstream 429 becomes response.failed with rate_limit_exceeded', { skip: typeof WebSocket === 'undefined' && 'global WebSocket needs Node 22+' }, async () => {  const ws = new WebSocket(`ws://127.0.0.1:${proxyPort}/v1/responses`);
   await new Promise((resolve, reject) => {
     const t = setTimeout(() => reject(new Error('ws open timeout')), 5000);
     ws.addEventListener('open', () => { clearTimeout(t); resolve(); }, { once: true });

package/tests/helpers.mjs

@@ -1,24 +1,24 @@
-import assert from 'node:assert/strict';
-
-// Validate an Anthropic event sequence: indexes increase in start order, deltas only target an open block.
-export function assertValidAnthropicEvents(events) {
-  const open = new Set();
-  const seen = new Set();
-  let expectedNext = 0;
-  for (const { event, data } of events) {
-    if (event === 'content_block_start') {
-      assert.equal(data.index, expectedNext, `block index must be sequential (got ${data.index}, want ${expectedNext})`);
-      assert.ok(!seen.has(data.index), `index ${data.index} reused`);
-      seen.add(data.index);
-      open.add(data.index);
-      expectedNext++;
-    } else if (event === 'content_block_delta') {
-      assert.ok(open.has(data.index), `delta for block ${data.index} which is not open`);
-    } else if (event === 'content_block_stop') {
-      assert.ok(open.has(data.index), `stop for block ${data.index} which is not open`);
-      open.delete(data.index);
-    } else if (event === 'message_stop') {
-      assert.equal(open.size, 0, 'all blocks must be closed before message_stop');
-    }
-  }
-}
+import assert from 'node:assert/strict';
+
+// Validate an Anthropic event sequence: indexes increase in start order, deltas only target an open block.
+export function assertValidAnthropicEvents(events) {
+  const open = new Set();
+  const seen = new Set();
+  let expectedNext = 0;
+  for (const { event, data } of events) {
+    if (event === 'content_block_start') {
+      assert.equal(data.index, expectedNext, `block index must be sequential (got ${data.index}, want ${expectedNext})`);
+      assert.ok(!seen.has(data.index), `index ${data.index} reused`);
+      seen.add(data.index);
+      open.add(data.index);
+      expectedNext++;
+    } else if (event === 'content_block_delta') {
+      assert.ok(open.has(data.index), `delta for block ${data.index} which is not open`);
+    } else if (event === 'content_block_stop') {
+      assert.ok(open.has(data.index), `stop for block ${data.index} which is not open`);
+      open.delete(data.index);
+    } else if (event === 'message_stop') {
+      assert.equal(open.size, 0, 'all blocks must be closed before message_stop');
+    }
+  }
+}

package/tests/hook-status.test.mjs

@@ -0,0 +1,119 @@
+// The launch hook: what a coding tool shows the person about the switcher at the start of a session.
+//
+// The shim toast fires only when the shim runs, and it needs the shim directory first on PATH. A
+// hook runs inside the tool itself, so it reports even when the launcher is the person's own script.
+// Both tools read one JSON object from stdout and show `systemMessage` to the person.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import http from 'node:http';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HOOK = path.join(ROOT, 'hook-status.mjs');
+const { identityProof } = await import(pathToFileURL(path.join(ROOT, 'state.mjs')).href);
+
+function tmpState(t) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'llmsw-hook-'));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  // The proof is an HMAC over the admin token, so the fake gateway needs the same file.
+  fs.writeFileSync(path.join(dir, 'admin.token'), 'tok-for-the-hook-test', { mode: 0o600 });
+  return dir;
+}
+
+function writeConfig(dir, port) {
+  fs.writeFileSync(path.join(dir, 'config.json'), JSON.stringify({
+    port,
+    activeProfiles: { claude: 'cl', codex: null },
+    profiles: {
+      cl: {
+        name: 'Intact Claude', baseURL: 'https://intact.example.io/v1', apiKey: 'sk-secret',
+        defaultModels: { opus: 'gemini-3.8-flash' }, model1M: { opus: true }
+      }
+    }
+  }), { mode: 0o600 });
+}
+
+// A gateway of this build: it answers /health with a proof over the challenge.
+function fakeGateway(t, port) {
+  const srv = http.createServer((req, res) => {
+    const nonce = new URL(req.url, 'http://127.0.0.1').searchParams.get('challenge') || '';
+    const body = { proxy: 'llm-switcher', port, pid: process.pid };
+    body.proof = identityProof(nonce, { role: 'gateway', port, pid: body.pid }, 'tok-for-the-hook-test');
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(body));
+  });
+  return new Promise((resolve) => srv.listen(port, '127.0.0.1', () => {
+    t.after(() => new Promise(r => srv.close(r)));
+    resolve(srv);
+  }));
+}
+
+function freePort() {
+  return new Promise((resolve) => {
+    const s = http.createServer();
+    s.listen(0, '127.0.0.1', () => { const p = s.address().port; s.close(() => resolve(p)); });
+  });
+}
+
+function runHook(dir, tool) {
+  const out = execFileSync(process.execPath, [HOOK, tool], {
+    encoding: 'utf8', timeout: 20000,
+    env: {
+      ...process.env,
+      LLM_SWITCHER_STATE_DIR: dir,
+      LLM_SWITCHER_CONFIG: path.join(dir, 'config.json'),
+      LLM_SWITCHER_PORT: ''
+    }
+  });
+  return { raw: out, json: JSON.parse(out.trim() || '{}') };
+}
+
+test('a tool that is not routed gets no message at all', async (t) => {
+  const dir = tmpState(t);
+  writeConfig(dir, await freePort());
+  // codex has no profile, so its route file is empty. This is the state after `switch off codex`.
+  fs.writeFileSync(path.join(dir, 'active.flag'), 'active');
+  fs.writeFileSync(path.join(dir, 'route-codex.txt'), '');
+  const r = runHook(dir, 'codex');
+  assert.equal(r.json.systemMessage, undefined, 'a tool on its official endpoint says nothing');
+});
+
+test('a routed tool with a live gateway reports where its traffic goes', async (t) => {
+  const dir = tmpState(t);
+  const port = await freePort();
+  writeConfig(dir, port);
+  await fakeGateway(t, port);
+  fs.writeFileSync(path.join(dir, 'active.flag'), 'active');
+  fs.writeFileSync(path.join(dir, 'route-claude.txt'), 'claude -> cl | intact.example.io | gemini-3.8-flash | 1M\n');
+  const r = runHook(dir, 'claude');
+  assert.match(r.json.systemMessage, /LLM Switcher/, 'the message names the switcher');
+  assert.match(r.json.systemMessage, /intact\.example\.io/, 'and the host the traffic goes to');
+  assert.match(r.json.systemMessage, /gemini-3\.8-flash/, 'and the model');
+  assert.doesNotMatch(r.json.systemMessage, /sk-secret/, 'and never the API key');
+});
+
+test('a routed tool with a dead gateway is warned that it cannot reach the provider', async (t) => {
+  const dir = tmpState(t);
+  const port = await freePort();   // nothing listens on it
+  writeConfig(dir, port);
+  fs.writeFileSync(path.join(dir, 'active.flag'), 'active');
+  fs.writeFileSync(path.join(dir, 'route-claude.txt'), 'claude -> cl | intact.example.io | gemini-3.8-flash | 1M\n');
+  const r = runHook(dir, 'claude');
+  assert.match(r.json.systemMessage, /does not answer|not running/i, 'the message says the gateway is down');
+  assert.match(r.json.systemMessage, new RegExp(String(port)), 'and names the port');
+  assert.match(r.json.systemMessage, /switch on/, 'and names the command that fixes it');
+});
+
+test('a broken state never fails the session: exit 0 and parseable output', async (t) => {
+  const dir = tmpState(t);
+  fs.writeFileSync(path.join(dir, 'config.json'), '{ this is not json', { mode: 0o600 });
+  fs.writeFileSync(path.join(dir, 'active.flag'), 'active');
+  const r = runHook(dir, 'claude');
+  assert.equal(typeof r.json, 'object', 'the tool still gets one JSON object');
+  const bad = runHook(dir, 'not-a-tool');
+  assert.equal(bad.json.systemMessage, undefined, 'an unknown tool name says nothing');
+});