llm-switcher 1.2.5 → 1.2.7

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog — LLM Switcher
 
+## Release 1.2.7
+
+- **Save from the dashboard:** The dashboard sent `tool: "auto"` for a profile that serves both tools. The gateway refuses that value. As a result, a new profile with the default tool, four of the five templates, and a save of any both-tools profile all failed. Now the dashboard saves `tool: null` for such a profile. The Vertex AI template uses `claude`.
+- **New profile with a used key:** A new profile with the key of an existing profile replaced that profile and its API key without a warning. Now the dashboard refuses the save and names the key.
+- **Turn all routes on:** After you turned every route off, "Activate compatible routes" gave only one profile a route. Codex stayed on the official endpoint. Now each tool gets its own profile, the same way as the `target` form of `/api/toggle`.
+- **Failed switch:** After a failed switch, the dashboard kept the state that the person had pressed. Now it reads the state from the gateway again, so the switch, the badges, and the file agree.
+- **Element ids:** The sidebar and the page header both used the id `btn-toggle`. The header button is now `btn-toggle-routes`.
+- **Unsaved changes:** The dashboard never asked before it threw away typed text. Now the close button, Cancel, a press on the dark area, and Escape ask "Discard unsaved changes?" when you typed something. A refresh of the state no longer wipes the text you are typing.
+- **Save with no change:** Every save added `thinkingMode: "auto"` and an empty `model1M` to the profile. Now a save with no edit leaves the profile as it was.
+- **Emptied slots:** A model slot that you emptied, and a 1M box that you cleared, came back after the save. Now the save keeps what the form shows.
+- **Tests:** New browser tests press the real dashboard: routes, profile forms, model slots, connection test, delete, catalog, and request inspector. After each step they check that the page, the gateway, and `config.json` say the same. They need Chromium and a global `WebSocket` (Node 22 or newer). Without them, the tests skip. Set `LLM_SWITCHER_CHROMIUM` to use another browser binary.
+
+## Release 1.2.6
+
+- **Deactivate in the dashboard:** The Deactivate button did not change the configuration, but the dashboard showed "deactivated". The dashboard sends `deactivate: true` and the profile key in `profile`. The gateway read `deactivate` as the profile key, so no target matched. Now `POST /api/switch` accepts both forms: `{"profile": "x", "deactivate": true}` and `{"deactivate": "x"}`.
+- **No silent success:** If the profile is not active, `POST /api/switch` now answers `404` with the error `Profile "x" is not active`. If `deactivate` is `true` and no profile is named, it answers `400`. Before, both requests answered `200` with `success: true`.
+
 ## Release 1.2.5
 
 - **Dashboard controls:** The dashboard controls use MIT elements from Uiverse.io galaxy as a base. The CSS gives the name of each author.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-switcher",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "description": "Zero-dependency multi-protocol edge gateway & provider switcher for Claude Code, Codex, OpenAI and Gemini clients",
   "keywords": [
     "llm",

package/proxy.mjs

@@ -1367,7 +1367,12 @@ async function routeConfigApi(res, method, pathname, body) {
   if (pathname === '/api/switch') {
     let err = null;
     if (body.deactivate) {
-      deactivateProfile(cfg, body.deactivate);
+      // The dashboard sends `deactivate: true` with the key in `profile`; the CLI sends the key itself.
+      const key = body.deactivate === true ? body.profile : body.deactivate;
+      if (typeof key !== 'string' || !key) return sendJson(res, 400, { error: 'deactivate needs a profile key' });
+      // A no-op must not answer success: the dashboard trusts `success` alone.
+      if (!isProfileActive(cfg, key)) return sendJson(res, 404, { error: `Profile "${key}" is not active` });
+      deactivateProfile(cfg, key);
     } else if (body.target) {
       err = setTargetProfile(cfg, body.target, body.profile || null);
     } else if (body.profile) {
@@ -1394,9 +1399,14 @@ async function routeConfigApi(res, method, pathname, body) {
       }
       err = setTargetProfile(cfg, body.target, key);
     } else if (body.enabled) {
-      const key = hasProfile(cfg, cfg.activeProfile) ? cfg.activeProfile : Object.keys(cfg.profiles)[0];
-      if (!key) return sendJson(res, 400, { error: 'No profiles configured' });
-      err = activateProfile(cfg, key);
+      if (!Object.keys(cfg.profiles).length) return sendJson(res, 400, { error: 'No profiles configured' });
+      // Each tool gets the profile that the `target` form would give it. Turning everything off and on
+      // again must not leave a tool on the official endpoint when a profile can serve it.
+      const preferred = cfg.activeProfile;
+      for (const tool of TOOLS) {
+        const key = [map[tool], preferred, ...Object.keys(cfg.profiles)].find(k => hasProfile(cfg, k) && profileAcceptsTarget(cfg.profiles[k], tool));
+        if (key) err = err || setTargetProfile(cfg, tool, key);
+      }
     } else {
       deactivateAll(cfg);
     }

package/switch.cmd

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

package/tests/cdp.mjs

@@ -0,0 +1,278 @@
+// A headless Chromium and one page, driven over the Chrome DevTools Protocol with no dependency.
+// The tests use it to press the real dashboard the way a person does: a click is a mouse event at
+// the pixel where the element is drawn, so a control that is hidden or covered fails the test.
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const CANDIDATES = [
+  process.env.LLM_SWITCHER_CHROMIUM,
+  '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable',
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'
+].filter(Boolean);
+
+export function findChromium() {
+  return CANDIDATES.find(p => fs.existsSync(p)) || null;
+}
+
+// undefined when this machine can run the browser tests, otherwise the reason to skip them.
+export function skipReason() {
+  if (typeof WebSocket === 'undefined') return 'needs a global WebSocket (Node 22 or newer)';
+  if (!findChromium()) return 'needs a Chromium or Chrome binary (set LLM_SWITCHER_CHROMIUM)';
+  return undefined;
+}
+
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+const KEYS = {
+  Enter: { code: 'Enter', vk: 13, text: '\r' },
+  Escape: { code: 'Escape', vk: 27 },
+  Tab: { code: 'Tab', vk: 9 },
+  ArrowDown: { code: 'ArrowDown', vk: 40 },
+  ArrowUp: { code: 'ArrowUp', vk: 38 },
+  Backspace: { code: 'Backspace', vk: 8 }
+};
+
+export async function launchBrowser() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lsw-chromium-'));
+  const args = [
+    '--headless=new', '--remote-debugging-port=0', `--user-data-dir=${dir}`,
+    '--no-first-run', '--no-default-browser-check', '--disable-extensions', '--disable-gpu',
+    '--disable-background-networking', '--window-size=1280,900',
+    ...(process.getuid?.() === 0 ? ['--no-sandbox'] : []),
+    'about:blank'
+  ];
+  const child = spawn(findChromium(), args, { stdio: 'ignore', env: { ...process.env, HOME: dir } });
+  let port = 0;
+  for (let i = 0; i < 150 && !port; i++) {
+    try { port = Number(fs.readFileSync(path.join(dir, 'DevToolsActivePort'), 'utf8').split('\n')[0]) || 0; } catch { /* not written yet */ }
+    if (!port) await sleep(100);
+  }
+  if (!port) { child.kill(); throw new Error('Chromium did not open a debugging port'); }
+
+  const pages = [];
+  return {
+    async newPage() {
+      const list = await (await fetch(`http://127.0.0.1:${port}/json/new?about:blank`, { method: 'PUT' })).json();
+      const page = new Page(list.webSocketDebuggerUrl);
+      await page.ready();
+      pages.push(page);
+      return page;
+    },
+    async close() {
+      for (const p of pages) p.close();
+      child.kill();
+      await new Promise(r => { child.once('exit', r); setTimeout(r, 2000); });
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  };
+}
+
+export class Page {
+  constructor(wsUrl) {
+    this.ws = new WebSocket(wsUrl);
+    this.nextId = 1;
+    this.pending = new Map();
+    this.listeners = new Map();
+    // What a person would notice or what the code would report: kept so a test can assert on it.
+    this.problems = [];      // console errors, uncaught exceptions, failed loads
+    this.badResponses = [];  // { url, status } for every HTTP 4xx and 5xx
+    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.ws.addEventListener('message', (ev) => this.#onMessage(JSON.parse(ev.data)));
+  }
+
+  async ready() {
+    if (this.ws.readyState !== 1) await new Promise((res, rej) => { this.ws.addEventListener('open', res, { once: true }); this.ws.addEventListener('error', rej, { once: true }); });
+    await Promise.all(['Page', 'Runtime', 'Network', 'Log'].map(d => this.send(`${d}.enable`)));
+    this.on('Runtime.consoleAPICalled', (e) => {
+      if (e.type === 'error' || e.type === 'assert') this.problems.push(`console.${e.type}: ${e.args.map(a => a.value ?? a.description ?? '').join(' ')}`);
+    });
+    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));
+    // 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));
+    this.on('Network.responseReceived', (e) => { if (e.response.status >= 400) this.badResponses.push({ url: e.response.url, status: e.response.status }); });
+    this.on('Network.loadingFailed', (e) => {
+      this.inflight.delete(e.requestId);
+      if (!e.canceled) this.problems.push(`load failed: ${e.errorText} ${e.requestId}`);
+    });
+    this.on('Page.javascriptDialogOpening', (e) => {
+      this.dialogs.push({ type: e.type, message: e.message });
+      this.send('Page.handleJavaScriptDialog', { accept: this.dialogPolicy === 'accept' }).catch(() => {});
+    });
+  }
+
+  #onMessage(msg) {
+    if (msg.id && this.pending.has(msg.id)) {
+      const { resolve, reject } = this.pending.get(msg.id);
+      this.pending.delete(msg.id);
+      if (msg.error) reject(new Error(`${msg.error.message} (${msg.error.code})`)); else resolve(msg.result);
+    } else if (msg.method) {
+      for (const cb of this.listeners.get(msg.method) || []) cb(msg.params);
+    }
+  }
+
+  on(method, cb) {
+    if (!this.listeners.has(method)) this.listeners.set(method, []);
+    this.listeners.get(method).push(cb);
+  }
+
+  send(method, params = {}) {
+    const id = this.nextId++;
+    this.ws.send(JSON.stringify({ id, method, params }));
+    return new Promise((resolve, reject) => this.pending.set(id, { resolve, reject }));
+  }
+
+  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; }
+
+  // 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.
+  async idle(quiet = 250, timeout = 8000) {
+    const end = Date.now() + timeout;
+    let quietSince = Date.now();
+    while (Date.now() < end) {
+      if (this.inflight.size > 0) quietSince = Date.now();
+      else if (Date.now() - quietSince >= quiet) return;
+      await sleep(25);
+    }
+    throw new Error(`the page still has ${this.inflight.size} request(s) in flight after ${timeout} ms: ${[...this.inflight.values()].join(', ')}`);
+  }
+
+  #loaded(timeout = 10000) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error(`the page did not finish loading in ${timeout} ms`)), timeout);
+      const done = () => {
+        clearTimeout(timer);
+        const handlers = this.listeners.get('Page.loadEventFired');
+        handlers.splice(handlers.indexOf(done), 1);
+        resolve();
+      };
+      this.on('Page.loadEventFired', done);
+    });
+  }
+
+  async goto(url) {
+    const loaded = this.#loaded();
+    const { errorText, loaderId } = await this.send('Page.navigate', { url });
+    if (errorText) throw new Error(`could not open ${url}: ${errorText}`);
+    // A change of the #hash alone stays in the same document: no load event will follow.
+    if (loaderId) await loaded; else loaded.catch(() => {});
+  }
+
+  async reload() {
+    const loaded = this.#loaded();
+    await this.send('Page.reload');
+    await loaded;
+  }
+
+  async evaluate(expression) {
+    const r = await this.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true });
+    if (r.exceptionDetails) throw new Error(`evaluate failed: ${r.exceptionDetails.exception?.description || r.exceptionDetails.text}\n${expression}`);
+    return r.result.value;
+  }
+
+  // Poll until the page expression is truthy. The message says what the test was waiting for.
+  async waitFor(expression, message, timeout = 5000) {
+    const end = Date.now() + timeout;
+    let last;
+    while (Date.now() < end) {
+      try { last = await this.evaluate(expression); if (last) return last; } catch (e) { last = e.message; }
+      await sleep(50);
+    }
+    throw new Error(`timed out after ${timeout} ms waiting for: ${message}\nlast value: ${JSON.stringify(last)}\nexpression: ${expression}`);
+  }
+
+  q(selector) { return `document.querySelector(${JSON.stringify(selector)})`; }
+  text(selector) { return this.evaluate(`${this.q(selector)}?.textContent.trim() ?? null`); }
+  value(selector) { return this.evaluate(`${this.q(selector)}?.value ?? null`); }
+  count(selector) { return this.evaluate(`document.querySelectorAll(${JSON.stringify(selector)}).length`); }
+  exists(selector) { return this.evaluate(`Boolean(${this.q(selector)})`); }
+  // Visible means drawn with a size and not hidden by display, visibility or an ancestor.
+  visible(selector) {
+    return this.evaluate(`(() => { const e = ${this.q(selector)}; if (!e) return false; const r = e.getBoundingClientRect(); const s = getComputedStyle(e); return r.width > 0 && r.height > 0 && s.visibility !== 'hidden' && s.display !== 'none' && e.getClientRects().length > 0; })()`);
+  }
+
+  // The centre of the element after it scrolled into view, and what the browser draws there.
+  async #target(selector) {
+    return this.evaluate(`(() => {
+      const e = ${this.q(selector)};
+      if (!e) return { missing: true };
+      e.scrollIntoView({ block: 'center', inline: 'center' });
+      const r = e.getBoundingClientRect();
+      if (r.width === 0 || r.height === 0) return { hidden: true };
+      const x = r.left + r.width / 2, y = r.top + r.height / 2;
+      const hit = document.elementFromPoint(x, y);
+      const label = e.closest('label');
+      const reachable = hit && (e.contains(hit) || hit.contains(e) || (label && label.contains(hit)));
+      return { x, y, reachable, hit: hit ? hit.tagName + (hit.id ? '#' + hit.id : '') + (hit.className && typeof hit.className === 'string' ? '.' + hit.className.split(' ').join('.') : '') : null };
+    })()`);
+  }
+
+  async click(selector) {
+    const t = await this.#target(selector);
+    if (t.missing) throw new Error(`click: no element matches ${selector}`);
+    if (t.hidden) throw new Error(`click: ${selector} has no size, a person cannot press it`);
+    if (!t.reachable) throw new Error(`click: ${selector} is covered by ${t.hit}, a person cannot press it`);
+    await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x: t.x, y: t.y });
+    await this.send('Input.dispatchMouseEvent', { type: 'mousePressed', x: t.x, y: t.y, button: 'left', clickCount: 1 });
+    await this.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: t.x, y: t.y, button: 'left', clickCount: 1 });
+  }
+
+  // A press at a pixel, for a target that has no element of its own: the dark area outside a dialog.
+  async clickAt(x, y) {
+    await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x, y });
+    await this.send('Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button: 'left', clickCount: 1 });
+    await this.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button: 'left', clickCount: 1 });
+  }
+
+  // Press the visible button or link whose label is `text`, the way a person finds it by reading.
+  async clickText(scope, text) {
+    const marked = await this.evaluate(`(() => {
+      document.querySelectorAll('[data-test-target]').forEach(e => e.removeAttribute('data-test-target'));
+      const hit = [...document.querySelectorAll(${JSON.stringify(scope)})].filter(e => e.textContent.trim() === ${JSON.stringify(text)} && e.getClientRects().length > 0);
+      if (hit.length !== 1) return hit.length;
+      hit[0].setAttribute('data-test-target', '1');
+      return 1;
+    })()`);
+    if (marked !== 1) throw new Error(`clickText: ${marked} visible match(es) for "${text}" in ${scope}, expected exactly 1`);
+    await this.click('[data-test-target="1"]');
+    await this.evaluate(`document.querySelector('[data-test-target]')?.removeAttribute('data-test-target')`);
+  }
+
+  // Focus the field with a click, drop the old text, then type like a person: one input event.
+  async type(selector, text) {
+    await this.click(selector);
+    await this.evaluate(`${this.q(selector)}.select()`);
+    if (text === '') await this.key('Backspace'); else await this.send('Input.insertText', { text });
+  }
+
+  async key(name) {
+    const k = KEYS[name];
+    if (!k) throw new Error(`key: unknown key ${name}`);
+    const base = { key: name, code: k.code, windowsVirtualKeyCode: k.vk, nativeVirtualKeyCode: k.vk };
+    await this.send('Input.dispatchKeyEvent', { type: k.text ? 'keyDown' : 'rawKeyDown', ...base, ...(k.text ? { text: k.text } : {}) });
+    await this.send('Input.dispatchKeyEvent', { type: 'keyUp', ...base });
+  }
+
+  // A native <select> opens an operating system popup that no protocol call can press, so this sets
+  // the value the way the popup would and fires the same events.
+  async select(selector, value) {
+    await this.click(selector);
+    await this.evaluate(`(() => { const s = ${this.q(selector)}; s.value = ${JSON.stringify(value)}; if (s.value !== ${JSON.stringify(value)}) throw new Error('select: no option ' + ${JSON.stringify(value)}); s.dispatchEvent(new Event('input', { bubbles: true })); s.dispatchEvent(new Event('change', { bubbles: true })); })()`);
+  }
+
+  async screenshot(file) {
+    const { data } = await this.send('Page.captureScreenshot', { format: 'png' });
+    fs.writeFileSync(file, Buffer.from(data, 'base64'));
+    return file;
+  }
+}

package/tests/dashboard-fixture.mjs

@@ -0,0 +1,167 @@
+// A real gateway on its own data directory, a stand-in upstream, and a stand-in interceptor.
+// The dashboard tests open this gateway in a browser, so nothing here may touch the real home
+// directory, the real Codex daemon, the real npm registry or a real interceptor.
+import http from 'node:http';
+import net from 'node:net';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const s = net.createServer();
+    s.listen(0, '127.0.0.1', () => { const { port } = s.address(); s.close(() => resolve(port)); });
+    s.on('error', reject);
+  });
+}
+
+const MODELS = { opus: 'up-opus', sonnet: 'up-sonnet', haiku: 'up-haiku' };
+
+// The starting point of every test. Two profiles that each serve one tool and one that serves
+// both, with Claude and Codex each on their own profile: the state in the Deactivate bug report.
+export function baselineConfig(port, blindfoldPort, upstreamBase) {
+  return {
+    port,
+    blindfold: { port: blindfoldPort },
+    activeProfiles: { claude: 'intact-claude', codex: 'intact-codex' },
+    profiles: {
+      'intact-claude': { name: 'Intact Claude', mode: 'convert', tool: 'claude', outFormat: 'openai-chat', baseURL: `${upstreamBase}/chat/v1`, apiKey: 'sk-secret-claude', defaultModels: { ...MODELS } },
+      'intact-codex': { name: 'Intact Codex', mode: 'convert', tool: 'codex', inFormat: 'responses', outFormat: 'openai-chat', baseURL: `${upstreamBase}/chat/v1`, apiKey: 'sk-secret-codex', defaultModels: { main: 'up-main', review: 'up-review' } },
+      shared: { name: 'Shared Router', mode: 'convert', tool: null, outFormat: 'openai-chat', baseURL: `${upstreamBase}/chat/v1`, apiKey: 'sk-secret-shared', defaultModels: { ...MODELS } }
+    }
+  };
+}
+
+export async function startDashboardFixture() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lsw-dashboard-'));
+  const cfgPath = path.join(dir, 'config.json');
+  const received = [];
+  // 'ok' answers like a healthy provider; 'deny' answers 401; 'down' answers 503.
+  const upstream = { mode: 'ok', received, models: ['up-alpha', 'up-beta', 'up-gamma'], latest: '99.0.0' };
+
+  const upstreamServer = http.createServer((req, res) => {
+    let body = '';
+    req.on('data', c => { body += c; });
+    req.on('end', () => {
+      received.push({ method: req.method, url: req.url, headers: req.headers, body });
+      const json = (status, obj) => { res.writeHead(status, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(obj)); };
+      if (req.url.startsWith('/registry')) return json(200, { version: upstream.latest });
+      if (upstream.mode === 'deny') return json(401, { error: { message: 'bad key' } });
+      if (upstream.mode === 'down') return json(503, { error: { message: 'upstream is down' } });
+      if (req.url.endsWith('/models')) {
+        return json(200, { data: upstream.models.map(id => ({ id, context_length: id === 'up-alpha' ? 200000 : 1000000 })) });
+      }
+      if (req.url.includes('/chat/completions')) {
+        return json(200, { id: 'c1', object: 'chat.completion', model: 'up', choices: [{ index: 0, message: { role: 'assistant', content: 'Final answer' }, finish_reason: 'stop' }], usage: { prompt_tokens: 3, completion_tokens: 2, total_tokens: 5 } });
+      }
+      return json(404, { error: 'not found' });
+    });
+  });
+  await new Promise(r => upstreamServer.listen(0, '127.0.0.1', r));
+  const upstreamBase = `http://127.0.0.1:${upstreamServer.address().port}`;
+
+  const port = await freePort();
+  const blindfoldPort = await freePort();
+  fs.writeFileSync(cfgPath, JSON.stringify(baselineConfig(port, blindfoldPort, upstreamBase), null, 2));
+
+  // The model lists that Claude Code and Codex keep for the signed-in account. With both present the
+  // catalog reads them from disk and never asks the official endpoints.
+  const home = path.join(dir, 'home');
+  fs.mkdirSync(path.join(home, '.claude', 'cache', 'model-catalog'), { recursive: true });
+  fs.mkdirSync(path.join(home, '.codex'), { recursive: true });
+  fs.writeFileSync(path.join(home, '.claude', 'cache', 'model-catalog', 'account.json'), JSON.stringify({
+    fetchedAt: 1,
+    catalog: { config: { models: [{ id: 'claude-opus-4-6', name: 'Opus' }, { id: 'claude-sonnet-4-6', name: 'Sonnet' }, { id: 'claude-haiku-4-5', name: 'Haiku' }] } }
+  }));
+  fs.writeFileSync(path.join(home, '.codex', 'models_cache.json'), JSON.stringify({
+    client_version: '1.0.0',
+    models: [{ slug: 'gpt-5.6-sol', context_window: 400000 }, { slug: 'gpt-5.6-terra', context_window: 400000 }]
+  }));
+  const env = {
+    ...process.env,
+    HOME: home,
+    CODEX_HOME: path.join(home, '.codex'),
+    CLAUDE_CONFIG_DIR: path.join(home, '.claude'),
+    LLM_SWITCHER_CONFIG: cfgPath,
+    LLM_SWITCHER_STATE_DIR: dir,
+    LLM_SWITCHER_PORT: '',
+    // Without this the gateway reads and writes the certificates of the checkout.
+    LLM_SWITCHER_BLINDFOLD_CERTS: path.join(dir, 'certs'),
+    LLM_SWITCHER_REGISTRY_URL: `${upstreamBase}/registry/latest`
+  };
+  // The gateway starts an interceptor of its own when it finds none on the port. This one is up
+  // first and answers the identity proof with this gateway's port and tool set, so nothing real
+  // is spawned.
+  const interceptor = spawn(process.execPath, ['--input-type=module', '-e', `
+    const s = await import(${JSON.stringify(pathToFileURL(path.join(ROOT, 'state.mjs')).href)});
+    const http = await import('node:http');
+    s.ensureAdminToken();
+    http.createServer((req, res) => {
+      const nonce = new URL(req.url, 'http://x').searchParams.get('challenge');
+      const activeTools = s.deriveActiveTools(s.loadConfig() || {}).join(',');
+      const f = { role: 'blindfold', port: ${blindfoldPort}, pid: process.pid, gatewayPort: ${port}, activeTools };
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify({ proxy: 'llm-switcher-blindfold', port: ${blindfoldPort}, pid: process.pid, gatewayPort: ${port}, activeTools, proof: s.identityProof(nonce, f) }));
+    }).listen(${blindfoldPort}, '127.0.0.1');
+  `], { env, stdio: 'ignore' });
+  const deadline = Date.now() + 8000;
+  for (;;) {
+    const probe = await fetch(`http://127.0.0.1:${blindfoldPort}/?challenge=probe`).catch(() => null);
+    if (probe?.ok) break;
+    if (Date.now() > deadline) { interceptor.kill(); throw new Error('the stand-in interceptor never came up'); }
+    await new Promise(r => setTimeout(r, 100));
+  }
+
+  const proxy = spawn(process.execPath, [path.join(ROOT, 'proxy.mjs'), '--port', String(port)], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+  let log = '';
+  proxy.stdout.on('data', d => { log += d; });
+  proxy.stderr.on('data', d => { log += d; });
+  let started = false;
+  for (let i = 0; i < 80 && !started; i++) {
+    try { started = (await fetch(`http://127.0.0.1:${port}/health`)).ok; } catch { /* not listening yet */ }
+    if (!started) await new Promise(r => setTimeout(r, 100));
+  }
+  if (!started) { proxy.kill(); interceptor.kill(); throw new Error(`gateway did not start:\n${log}`); }
+
+  const adminToken = () => fs.readFileSync(path.join(dir, 'admin.token'), 'utf8').trim();
+  return {
+    port,
+    dir,
+    upstream,
+    upstreamBase,
+    dashboardUrl: `http://127.0.0.1:${port}/ui`,
+    // What is on disk, which the dashboard has to agree with after every action.
+    config: () => JSON.parse(fs.readFileSync(cfgPath, 'utf8')),
+    // A change made outside the dashboard, as `switch` in a terminal or an editor would make it.
+    writeConfig: (cfg) => fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2)),
+    baseline: () => baselineConfig(port, blindfoldPort, upstreamBase),
+    // The same call the dashboard makes, for a test that needs the server's own answer.
+    api: (p, body) => fetch(`http://127.0.0.1:${port}${p}`, {
+      method: body ? 'POST' : 'GET',
+      headers: { 'x-llm-switcher-token': adminToken(), 'Content-Type': 'application/json' },
+      body: body ? JSON.stringify(body) : undefined
+    }).then(async r => ({ status: r.status, json: await r.json().catch(() => null) })),
+    // One request from Claude Code through the route that is on, so the request inspector has a row.
+    messages: () => fetch(`http://127.0.0.1:${port}/v1/messages`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'anthropic-version': '2023-06-01' },
+      body: JSON.stringify({ model: 'claude-opus-4-6', max_tokens: 64, messages: [{ role: 'user', content: 'hello from the test' }] })
+    }).then(async r => ({ status: r.status, text: await r.text() })),
+    async stop() {
+      interceptor.kill();
+      proxy.kill();
+      upstreamServer.close();
+      upstreamServer.closeAllConnections?.();
+      // A tool set change can start a detached interceptor of its own; stop the one the gateway recorded.
+      try {
+        const { pid } = JSON.parse(fs.readFileSync(path.join(dir, 'blindfold.json'), 'utf8'));
+        if (Number.isInteger(pid) && pid !== interceptor.pid) process.kill(pid);
+      } catch { /* none was started */ }
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  };
+}