llm-switcher 1.2.11 → 1.2.12

package/tests/live-optimizer-interop.mjs

@@ -1,205 +1,205 @@
-// LIVE test: requires a running gateway (switch on) and a real upstream (costs tokens).
-// Offline test, no network needed: npm test
-const GATEWAY_PORT = Number(process.env.LLM_SWITCHER_PORT) || 3456;
-const BASE_URL = `http://127.0.0.1:${GATEWAY_PORT}`;
-
-console.log('================================================================');
-console.log('  LLM SWITCHER — TOKEN OPTIMIZER INTEROPERABILITY TEST SUITE   ');
-console.log('  Simulating failure modes from Headroom, RTK, and Ponytail    ');
-console.log('================================================================\n');
-
-let passed = 0;
-let failed = 0;
-
-async function runTest(name, fn) {
-  process.stdout.write(`[TEST] ${name}... `);
-  const t0 = Date.now();
-  try {
-    const detail = await fn();
-    console.log(`PASS (${Date.now() - t0}ms)`);
-    if (detail) console.log(`       ↳ ${detail}`);
-    passed++;
-  } catch (err) {
-    console.log(`FAIL (${Date.now() - t0}ms)`);
-    console.log(`       ↳ ERROR: ${err.message}`);
-    failed++;
-  }
-}
-
-// -----------------------------------------------------------------------------
-// TEST 1: Headroom Failure Mode — Orphaned tool_result
-// When Headroom prunes history to save tokens, it drops the assistant tool_use turn.
-// Anthropic strictly throws: 400 invalid_request_error: 'tool_use_id does not correspond to any tool_use'
-// LLM Switcher Healer Engine: Repairs orphaned result into context text -> 200 OK
-// -----------------------------------------------------------------------------
-await runTest('Headroom Simulation: Orphaned tool_result turn', async () => {
-  const payload = {
-    model: 'claude-opus-4-6',
-    max_tokens: 40,
-    messages: [
-      { role: 'user', content: 'Context turn before pruning' },
-      {
-        role: 'user',
-        content: [
-          { type: 'tool_result', tool_use_id: 'headroom_pruned_call_99', content: 'Database query result: 42 rows found' },
-          { type: 'text', text: 'Reply: healed successfully' }
-        ]
-      }
-    ],
-    stream: false
-  };
-
-  const res = await fetch(`${BASE_URL}/v1/messages`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json', 'anthropic-version': '2023-06-01' },
-    body: JSON.stringify(payload)
-  });
-
-  if (res.status !== 200) {
-    const err = await res.text();
-    throw new Error(`Expected HTTP 200, got ${res.status}: ${err}`);
-  }
-  const json = await res.json();
-  const text = json.content?.map(c => c.text).join('') || '';
-  return `Healed orphaned tool_result. Response HTTP 200: "${text.slice(0, 50).replace(/\n/g, ' ')}..."`;
-});
-
-// -----------------------------------------------------------------------------
-// TEST 2: Headroom Failure Mode — Consecutive User turns (Roles must alternate)
-// When Headroom collapses history, multiple user turns occur back-to-back.
-// Anthropic strictly throws: 400 invalid_request_error: 'roles must alternate'
-// LLM Switcher Healer Engine: Merges consecutive same-role turns -> 200 OK
-// -----------------------------------------------------------------------------
-await runTest('Headroom Simulation: Consecutive User turns (Role alternation violation)', async () => {
-  const payload = {
-    model: 'claude-opus-4-6',
-    max_tokens: 30,
-    messages: [
-      { role: 'user', content: 'User message turn 1' },
-      { role: 'user', content: 'User message turn 2 (no assistant in between)' },
-      { role: 'user', content: 'User message turn 3: reply pong' }
-    ],
-    stream: false
-  };
-
-  const res = await fetch(`${BASE_URL}/v1/messages`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json', 'anthropic-version': '2023-06-01' },
-    body: JSON.stringify(payload)
-  });
-
-  if (res.status !== 200) {
-    const err = await res.text();
-    throw new Error(`Expected HTTP 200, got ${res.status}: ${err}`);
-  }
-  const json = await res.json();
-  return `Merged consecutive turns seamlessly. Stop reason: ${json.stop_reason}`;
-});
-
-// -----------------------------------------------------------------------------
-// TEST 3: Headroom / RTK Failure Mode — Stripped Thinking Parameter
-// Optimizer stripped the 'thinking' object to reduce tokens.
-// LLM Switcher Thinking Guard: Detects reasoning model (ag/claude-opus-4-6-thinking)
-// and restores thinking.budget_tokens automatically -> thinking_delta emitted!
-// -----------------------------------------------------------------------------
-await runTest('Thinking Guard: Restoring stripped thinking parameter on reasoning models', async () => {
-  const payload = {
-    model: 'claude-opus-4-6',
-    max_tokens: 200,
-    // Note: NO thinking parameter included (simulating optimizer stripping it)
-    messages: [
-      { role: 'user', content: 'Solve step by step: what is 17 * 23? Show reasoning.' }
-    ],
-    stream: true
-  };
-
-  const res = await fetch(`${BASE_URL}/v1/messages`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json', 'anthropic-version': '2023-06-01' },
-    body: JSON.stringify(payload)
-  });
-
-  if (res.status !== 200) {
-    throw new Error(`Expected HTTP 200, got ${res.status}`);
-  }
-
-  const text = await res.text();
-  const hasThinkingDelta = text.includes('thinking_delta');
-  const hasSignatureDelta = text.includes('signature_delta');
-  const hasTextDelta = text.includes('text_delta');
-
-  if (!hasThinkingDelta) {
-    throw new Error('Thinking Guard failed: thinking_delta was NOT emitted in stream!');
-  }
-
-  return `Automatically restored thinking: thinking_delta=${hasThinkingDelta}, signature_delta=${hasSignatureDelta}, text_delta=${hasTextDelta}`;
-});
-
-// -----------------------------------------------------------------------------
-// TEST 4: RTK & Intermediary Headers Passthrough
-// RTK / tracing tools inject headers: x-rtk-version, traceparent, x-request-id.
-// LLM Switcher: Transparently preserves all tracking headers without rejection.
-// -----------------------------------------------------------------------------
-await runTest('RTK Intermediary: Custom headers and traceparent passthrough', async () => {
-  const payload = {
-    model: 'claude-opus-4-6',
-    max_tokens: 20,
-    messages: [{ role: 'user', content: 'ping' }],
-    stream: false
-  };
-
-  const res = await fetch(`${BASE_URL}/v1/messages`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'anthropic-version': '2023-06-01',
-      'x-rtk-version': '0.37.2',
-      'x-optimizer-id': 'rtk-cli-hook',
-      'traceparent': '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01'
-    },
-    body: JSON.stringify(payload)
-  });
-
-  if (res.status !== 200) {
-    throw new Error(`Expected HTTP 200, got ${res.status}`);
-  }
-  return `Headers accepted cleanly with HTTP 200 OK`;
-});
-
-// -----------------------------------------------------------------------------
-// TEST 5: OpenAI Chat Healer Mode — Orphaned Tool Result in Chat Completions
-// Same test but over /v1/chat/completions: tool role message without prior tool_calls assistant message.
-// OpenAI API strictly throws: 400 'messages with role tool must be a response to a preceding message with tool_calls'
-// LLM Switcher: Converts orphaned tool to user text message -> 200 OK
-// -----------------------------------------------------------------------------
-await runTest('OpenAI Chat Healer: Orphaned role tool without preceding assistant tool_calls', async () => {
-  const payload = {
-    model: 'ag/gpt-oss-120b-medium',
-    max_tokens: 30,
-    messages: [
-      { role: 'user', content: 'Turn 1 context' },
-      { role: 'tool', tool_call_id: 'orphaned_chat_call_77', content: 'Tool execution logs: OK' },
-      { role: 'user', content: 'reply pong' }
-    ],
-    stream: false
-  };
-
-  const res = await fetch(`${BASE_URL}/v1/chat/completions`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(payload)
-  });
-
-  if (res.status !== 200) {
-    const err = await res.text();
-    throw new Error(`Expected HTTP 200, got ${res.status}: ${err}`);
-  }
-  const json = await res.json();
-  return `Chat Healer rescued orphaned tool role. Stop reason: ${json.choices?.[0]?.finish_reason}`;
-});
-
-console.log('\n================================================================');
-console.log(`  TEST RESULTS: ${passed} PASSED / ${failed} FAILED               `);
-console.log('================================================================\n');
-
-process.exit(failed ? 1 : 0);
+// LIVE test: requires a running gateway (switch on) and a real upstream (costs tokens).
+// Offline test, no network needed: npm test
+const GATEWAY_PORT = Number(process.env.LLM_SWITCHER_PORT) || 3456;
+const BASE_URL = `http://127.0.0.1:${GATEWAY_PORT}`;
+
+console.log('================================================================');
+console.log('  LLM SWITCHER — TOKEN OPTIMIZER INTEROPERABILITY TEST SUITE   ');
+console.log('  Simulating failure modes from Headroom, RTK, and Ponytail    ');
+console.log('================================================================\n');
+
+let passed = 0;
+let failed = 0;
+
+async function runTest(name, fn) {
+  process.stdout.write(`[TEST] ${name}... `);
+  const t0 = Date.now();
+  try {
+    const detail = await fn();
+    console.log(`PASS (${Date.now() - t0}ms)`);
+    if (detail) console.log(`       ↳ ${detail}`);
+    passed++;
+  } catch (err) {
+    console.log(`FAIL (${Date.now() - t0}ms)`);
+    console.log(`       ↳ ERROR: ${err.message}`);
+    failed++;
+  }
+}
+
+// -----------------------------------------------------------------------------
+// TEST 1: Headroom Failure Mode — Orphaned tool_result
+// When Headroom prunes history to save tokens, it drops the assistant tool_use turn.
+// Anthropic strictly throws: 400 invalid_request_error: 'tool_use_id does not correspond to any tool_use'
+// LLM Switcher Healer Engine: Repairs orphaned result into context text -> 200 OK
+// -----------------------------------------------------------------------------
+await runTest('Headroom Simulation: Orphaned tool_result turn', async () => {
+  const payload = {
+    model: 'claude-opus-4-6',
+    max_tokens: 40,
+    messages: [
+      { role: 'user', content: 'Context turn before pruning' },
+      {
+        role: 'user',
+        content: [
+          { type: 'tool_result', tool_use_id: 'headroom_pruned_call_99', content: 'Database query result: 42 rows found' },
+          { type: 'text', text: 'Reply: healed successfully' }
+        ]
+      }
+    ],
+    stream: false
+  };
+
+  const res = await fetch(`${BASE_URL}/v1/messages`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'anthropic-version': '2023-06-01' },
+    body: JSON.stringify(payload)
+  });
+
+  if (res.status !== 200) {
+    const err = await res.text();
+    throw new Error(`Expected HTTP 200, got ${res.status}: ${err}`);
+  }
+  const json = await res.json();
+  const text = json.content?.map(c => c.text).join('') || '';
+  return `Healed orphaned tool_result. Response HTTP 200: "${text.slice(0, 50).replace(/\n/g, ' ')}..."`;
+});
+
+// -----------------------------------------------------------------------------
+// TEST 2: Headroom Failure Mode — Consecutive User turns (Roles must alternate)
+// When Headroom collapses history, multiple user turns occur back-to-back.
+// Anthropic strictly throws: 400 invalid_request_error: 'roles must alternate'
+// LLM Switcher Healer Engine: Merges consecutive same-role turns -> 200 OK
+// -----------------------------------------------------------------------------
+await runTest('Headroom Simulation: Consecutive User turns (Role alternation violation)', async () => {
+  const payload = {
+    model: 'claude-opus-4-6',
+    max_tokens: 30,
+    messages: [
+      { role: 'user', content: 'User message turn 1' },
+      { role: 'user', content: 'User message turn 2 (no assistant in between)' },
+      { role: 'user', content: 'User message turn 3: reply pong' }
+    ],
+    stream: false
+  };
+
+  const res = await fetch(`${BASE_URL}/v1/messages`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'anthropic-version': '2023-06-01' },
+    body: JSON.stringify(payload)
+  });
+
+  if (res.status !== 200) {
+    const err = await res.text();
+    throw new Error(`Expected HTTP 200, got ${res.status}: ${err}`);
+  }
+  const json = await res.json();
+  return `Merged consecutive turns seamlessly. Stop reason: ${json.stop_reason}`;
+});
+
+// -----------------------------------------------------------------------------
+// TEST 3: Headroom / RTK Failure Mode — Stripped Thinking Parameter
+// Optimizer stripped the 'thinking' object to reduce tokens.
+// LLM Switcher Thinking Guard: Detects reasoning model (ag/claude-opus-4-6-thinking)
+// and restores thinking.budget_tokens automatically -> thinking_delta emitted!
+// -----------------------------------------------------------------------------
+await runTest('Thinking Guard: Restoring stripped thinking parameter on reasoning models', async () => {
+  const payload = {
+    model: 'claude-opus-4-6',
+    max_tokens: 200,
+    // Note: NO thinking parameter included (simulating optimizer stripping it)
+    messages: [
+      { role: 'user', content: 'Solve step by step: what is 17 * 23? Show reasoning.' }
+    ],
+    stream: true
+  };
+
+  const res = await fetch(`${BASE_URL}/v1/messages`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'anthropic-version': '2023-06-01' },
+    body: JSON.stringify(payload)
+  });
+
+  if (res.status !== 200) {
+    throw new Error(`Expected HTTP 200, got ${res.status}`);
+  }
+
+  const text = await res.text();
+  const hasThinkingDelta = text.includes('thinking_delta');
+  const hasSignatureDelta = text.includes('signature_delta');
+  const hasTextDelta = text.includes('text_delta');
+
+  if (!hasThinkingDelta) {
+    throw new Error('Thinking Guard failed: thinking_delta was NOT emitted in stream!');
+  }
+
+  return `Automatically restored thinking: thinking_delta=${hasThinkingDelta}, signature_delta=${hasSignatureDelta}, text_delta=${hasTextDelta}`;
+});
+
+// -----------------------------------------------------------------------------
+// TEST 4: RTK & Intermediary Headers Passthrough
+// RTK / tracing tools inject headers: x-rtk-version, traceparent, x-request-id.
+// LLM Switcher: Transparently preserves all tracking headers without rejection.
+// -----------------------------------------------------------------------------
+await runTest('RTK Intermediary: Custom headers and traceparent passthrough', async () => {
+  const payload = {
+    model: 'claude-opus-4-6',
+    max_tokens: 20,
+    messages: [{ role: 'user', content: 'ping' }],
+    stream: false
+  };
+
+  const res = await fetch(`${BASE_URL}/v1/messages`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'anthropic-version': '2023-06-01',
+      'x-rtk-version': '0.37.2',
+      'x-optimizer-id': 'rtk-cli-hook',
+      'traceparent': '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01'
+    },
+    body: JSON.stringify(payload)
+  });
+
+  if (res.status !== 200) {
+    throw new Error(`Expected HTTP 200, got ${res.status}`);
+  }
+  return `Headers accepted cleanly with HTTP 200 OK`;
+});
+
+// -----------------------------------------------------------------------------
+// TEST 5: OpenAI Chat Healer Mode — Orphaned Tool Result in Chat Completions
+// Same test but over /v1/chat/completions: tool role message without prior tool_calls assistant message.
+// OpenAI API strictly throws: 400 'messages with role tool must be a response to a preceding message with tool_calls'
+// LLM Switcher: Converts orphaned tool to user text message -> 200 OK
+// -----------------------------------------------------------------------------
+await runTest('OpenAI Chat Healer: Orphaned role tool without preceding assistant tool_calls', async () => {
+  const payload = {
+    model: 'ag/gpt-oss-120b-medium',
+    max_tokens: 30,
+    messages: [
+      { role: 'user', content: 'Turn 1 context' },
+      { role: 'tool', tool_call_id: 'orphaned_chat_call_77', content: 'Tool execution logs: OK' },
+      { role: 'user', content: 'reply pong' }
+    ],
+    stream: false
+  };
+
+  const res = await fetch(`${BASE_URL}/v1/chat/completions`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload)
+  });
+
+  if (res.status !== 200) {
+    const err = await res.text();
+    throw new Error(`Expected HTTP 200, got ${res.status}: ${err}`);
+  }
+  const json = await res.json();
+  return `Chat Healer rescued orphaned tool role. Stop reason: ${json.choices?.[0]?.finish_reason}`;
+});
+
+console.log('\n================================================================');
+console.log(`  TEST RESULTS: ${passed} PASSED / ${failed} FAILED               `);
+console.log('================================================================\n');
+
+process.exit(failed ? 1 : 0);

package/tests/service.test.mjs

@@ -8,7 +8,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import {
-  systemdUnit, launchdPlist, scheduledTaskXml, portFromServiceText, decodeConsoleText, serviceEnv, writeServiceFile
+  systemdUnit, launchdPlist, scheduledTaskXml, portFromServiceText, autoupdateFromServiceText, decodeConsoleText, serviceEnv, writeServiceFile
 } from '../service.mjs';
 
 const HAS_XMLLINT = (() => { try { execFileSync('xmllint', ['--version'], { stdio: 'ignore' }); return true; } catch { return false; } })();
@@ -58,6 +58,32 @@ test('the port is read back from UTF-16 console output, as schtasks /Query /XML
   assert.equal(portFromServiceText('no port here'), null);
 });
 
+test('autoupdate flag is placed into task XML, systemd unit, and launchd plist', () => {
+  const xml = scheduledTaskXml({ nodeBin: 'node.exe', script: 'proxy.mjs', port: 3456, userId: 'u', autoupdate: true });
+  assert.match(xml, /<Arguments>&quot;proxy\.mjs&quot; --port 3456 --autoupdate<\/Arguments>/);
+  assert.equal(portFromServiceText(xml), 3456);
+
+  const unit = systemdUnit({ nodeBin: '/usr/bin/node', script: '/opt/proxy.mjs', port: 3456, autoupdate: true });
+  assert.match(unit, /ExecStart="\/usr\/bin\/node" "\/opt\/proxy\.mjs" --port 3456 --autoupdate/);
+  assert.equal(portFromServiceText(unit), 3456);
+
+  const plistText = launchdPlist({ nodeBin: '/node', script: '/proxy.mjs', port: 3456, logPath: '/log', autoupdate: true });
+  assert.match(plistText, /<string>--autoupdate<\/string>/);
+  assert.equal(portFromServiceText(plistText), 3456);
+});
+
+// `switch port` rewrites the service. It must keep the choice that `service install --no-autoupdate` made.
+test('the autoupdate flag is read back from each service definition', () => {
+  for (const autoupdate of [true, false]) {
+    const texts = [
+      scheduledTaskXml({ nodeBin: 'node.exe', script: 'proxy.mjs', port: 3456, userId: 'u', autoupdate }),
+      systemdUnit({ nodeBin: '/usr/bin/node', script: '/opt/proxy.mjs', port: 3456, autoupdate }),
+      launchdPlist({ nodeBin: '/node', script: '/proxy.mjs', port: 3456, logPath: '/log', autoupdate })
+    ];
+    for (const text of texts) assert.equal(autoupdateFromServiceText(text), autoupdate);
+  }
+});
+
 test('writeServiceFile keeps a hand-edited definition as .bak before it replaces it', (t) => {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'llmsw-svc-'));
   t.after(() => fs.rmSync(dir, { recursive: true, force: true }));

package/tests/update.e2e.test.mjs

@@ -0,0 +1,197 @@
+// A real gateway, run from a copy of this checkout that tracks a local bare repository. A release
+// pushed there must reach the running gateway through POST /api/update, and through --autoupdate at
+// start. Nothing here reaches the network or the real home directory.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import http from 'node:http';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { launchBrowser, skipReason } from './cdp.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+const ID = ['-c', 'user.name=t', '-c', 'user.email=t@t', '-c', 'commit.gpgsign=false', '-c', 'core.autocrlf=false'];
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+const freePort = () => new Promise(r => {
+  const s = net.createServer().listen(0, '127.0.0.1', () => { const { port } = s.address(); s.close(() => r(port)); });
+});
+
+function copySource(dest) {
+  const files = git(ROOT, 'ls-files', '--cached', '--others', '--exclude-standard').split(/\r?\n/).filter(Boolean);
+  for (const f of files) {
+    const from = path.join(ROOT, f);
+    if (!fs.existsSync(from)) continue;
+    fs.mkdirSync(path.dirname(path.join(dest, f)), { recursive: true });
+    fs.copyFileSync(from, path.join(dest, f));
+  }
+}
+
+function bumpVersion(dir, version) {
+  const p = path.join(dir, 'package.json');
+  fs.writeFileSync(p, JSON.stringify({ ...JSON.parse(fs.readFileSync(p, 'utf8')), version }, null, 2) + '\n');
+}
+
+// The npm registry answer only drives the dashboard notice; a git checkout updates from git.
+async function registry(t, version) {
+  const srv = http.createServer((req, res) => { res.setHeader('content-type', 'application/json'); res.end(JSON.stringify({ version })); });
+  await new Promise(r => srv.listen(0, '127.0.0.1', r));
+  t.after(() => srv.close());
+  return `http://127.0.0.1:${srv.address().port}/`;
+}
+
+async function fixture(t, { registryUrl = 'http://127.0.0.1:9/' } = {}) {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'llmsw-update-e2e-'));
+  const upstream = path.join(base, 'upstream.git');
+  const install = path.join(base, 'install');
+  const publisher = path.join(base, 'publisher');
+  git(base, 'init', '-q', '--bare', '-b', 'main', upstream);
+  fs.mkdirSync(install);
+  copySource(install);
+  git(install, 'init', '-q', '-b', 'main');
+  git(install, 'add', '-A');
+  git(install, ...ID, 'commit', '-q', '-m', 'installed');
+  git(install, 'remote', 'add', 'origin', upstream);
+  git(install, 'push', '-q', '-u', 'origin', 'main');
+  fs.mkdirSync(publisher);
+  git(publisher, 'init', '-q', '-b', 'main');
+  git(publisher, 'remote', 'add', 'origin', upstream);
+  git(publisher, 'fetch', '-q', 'origin');
+  git(publisher, 'checkout', '-q', '-b', 'main', '--track', 'origin/main');
+
+  const data = path.join(base, 'data');
+  const home = path.join(data, 'home');
+  fs.mkdirSync(home, { recursive: true });
+  const port = await freePort();
+  const cfgPath = path.join(data, 'config.json');
+  fs.writeFileSync(cfgPath, JSON.stringify({
+    port, blindfold: { port: await freePort() }, activeProfiles: { anthropic: null, responses: null, 'openai-chat': null, vertex: null },
+    profiles: { plain: { name: 'Plain', mode: 'convert', inFormat: 'auto', baseURL: 'http://127.0.0.1:9/v1', apiKey: 'k', defaultModels: { opus: 'o' } } }
+  }, null, 2));
+  const env = {
+    ...process.env, HOME: home, USERPROFILE: home, CODEX_HOME: path.join(home, '.codex'), CLAUDE_CONFIG_DIR: path.join(home, '.claude'),
+    LLM_SWITCHER_CONFIG: cfgPath, LLM_SWITCHER_STATE_DIR: data, LLM_SWITCHER_BLINDFOLD_CERTS: path.join(data, 'certs'),
+    LLM_SWITCHER_PORT: '', PORT: '', LLM_SWITCHER_REGISTRY_URL: registryUrl
+  };
+
+  let proc = null;
+  let log = '';
+  const pid = async () => {
+    try { return (await (await fetch(`http://127.0.0.1:${port}/health?challenge=t`)).json()).pid ?? null; } catch { return null; }
+  };
+  const fx = {
+    port,
+    log: () => log,
+    pid,
+    release(version) {
+      bumpVersion(publisher, version);
+      git(publisher, 'add', '-A');
+      git(publisher, ...ID, 'commit', '-q', '-m', `v${version}`);
+      git(publisher, 'push', '-q', 'origin', 'main');
+    },
+    async start(...extra) {
+      proc = spawn(process.execPath, [path.join(install, 'proxy.mjs'), '--port', String(port), ...extra], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+      proc.stdout.on('data', d => { log += d; });
+      proc.stderr.on('data', d => { log += d; });
+      return proc;
+    },
+    async waitFor(check, what) {
+      for (let i = 0; i < 120; i++) {
+        const v = await check();
+        if (v) return v;
+        await sleep(250);
+      }
+      throw new Error(`timed out waiting for ${what}\n${log}`);
+    },
+    cli: (...args) => new Promise((resolve) => {
+      const c = spawn(process.execPath, [path.join(install, 'switch.mjs'), ...args, '--port', String(port)], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+      let out = '';
+      c.stdout.on('data', d => { out += d; });
+      c.stderr.on('data', d => { out += d; });
+      c.on('close', code => resolve({ code, out }));
+    }),
+    dashboardUrl: `http://127.0.0.1:${port}/ui`,
+    api: (p, opts = {}) => fetch(`http://127.0.0.1:${port}${p}`, {
+      ...opts,
+      headers: { 'x-llm-switcher-token': fs.readFileSync(path.join(data, 'admin.token'), 'utf8').trim(), 'Content-Type': 'application/json' }
+    })
+  };
+  t.after(async () => {
+    const live = await pid();
+    if (live) try { process.kill(live); } catch {}
+    proc?.kill();
+    await sleep(300);
+    fs.rmSync(base, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+  });
+  return fx;
+}
+
+async function readSse(res) {
+  const events = [];
+  for (const block of (await res.text()).split('\n\n')) {
+    const event = /^event: (.*)$/m.exec(block)?.[1];
+    if (event) events.push({ event, data: JSON.parse(/^data: (.*)$/m.exec(block)[1]) });
+  }
+  return events;
+}
+
+test('POST /api/update pulls the release and a new gateway takes over the port', { timeout: 90000 }, async (t) => {
+  const fx = await fixture(t);
+  const proc = await fx.start();
+  const oldPid = await fx.waitFor(fx.pid, 'the gateway');
+  assert.equal((await (await fx.api('/api/version')).json()).current, JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version);
+
+  fx.release('9.9.9');
+  const events = await readSse(await fx.api('/api/update', { method: 'POST', body: '{}' }));
+  const result = events.find(e => e.event === 'result')?.data;
+  assert.equal(result?.updated, true, JSON.stringify(events));
+  assert.equal(result.to, '9.9.9');
+
+  await fx.waitFor(async () => { const p = await fx.pid(); return p && p !== oldPid; }, 'the new gateway');
+  assert.equal((await (await fx.api('/api/version')).json()).current, '9.9.9');
+  // The first process stays as the parent: a service manager still sees the pid it started.
+  assert.equal(proc.exitCode, null);
+
+  const again = (await readSse(await fx.api('/api/update', { method: 'POST', body: '{}' }))).find(e => e.event === 'result')?.data;
+  assert.equal(again?.updated, false);
+  assert.match(again.reason, /latest/i);
+});
+
+test('--autoupdate starts the newest release', { timeout: 90000 }, async (t) => {
+  const fx = await fixture(t);
+  fx.release('9.9.10');
+  await fx.start('--autoupdate');
+  await fx.waitFor(fx.pid, 'the gateway');
+  assert.equal((await (await fx.api('/api/version')).json()).current, '9.9.10');
+  assert.match(fx.log(), /Pulled 1 commit/);
+});
+
+test('switch update asks the running gateway and waits for the new one', { timeout: 90000 }, async (t) => {
+  const fx = await fixture(t);
+  await fx.start();
+  await fx.waitFor(fx.pid, 'the gateway');
+  fx.release('9.9.11');
+  const r = await fx.cli('update');
+  assert.equal(r.code, 0, r.out);
+  assert.match(r.out, /runs v9\.9\.11/);
+  assert.equal((await (await fx.api('/api/version')).json()).current, '9.9.11');
+});
+
+test('the dashboard Update now button installs the release and reloads on the new gateway', { timeout: 90000, skip: skipReason() }, async (t) => {
+  const fx = await fixture(t, { registryUrl: await registry(t, '9.9.12') });
+  await fx.start();
+  await fx.waitFor(fx.pid, 'the gateway');
+  fx.release('9.9.12');
+  const browser = await launchBrowser();
+  t.after(() => browser.close());
+  const page = await browser.newPage();
+  await page.goto(fx.dashboardUrl);
+  await page.waitFor(`!document.getElementById('update-notice').hidden`, 'the update notice');
+  await page.click('#update-now');
+  await page.waitFor(`document.getElementById('app-version')?.textContent === 'v9.9.12'`, 'the reloaded dashboard on the new version', 30000);
+  assert.equal(await page.evaluate(`document.getElementById('update-notice').hidden`), true);
+});