llm-switcher 1.3.2 → 1.3.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog — LLM Switcher
 
+## Release 1.3.3
+
+- **agy runs behind a relay:** A routed agy no longer gets the gateway port. The shim starts it behind `agy-relay.mjs`, which holds its own loopback port for as long as agy runs. For each connection, the relay asks the gateway for its identity proof on the same socket and sends agy's request only after the proof holds. Before, the shim checked the gateway only at launch, so a gateway that stopped during an agy session left its port free for another program to take, with agy's Google token sent to it. If the proof fails now, agy gets a 502 and the token stays in the relay.
+- **A relay key that no page serves:** The relay accepts only `relayProof`, an HMAC keyed by `gateway.secret`, a random file next to `admin.token`. The gateway makes it at startup and keeps no copy. The dashboard page carries `admin.token`, so a proof keyed by it could be made by any program that loads the page. A gateway older than the relay gets a 502 that says to restart it.
+- **A `.cmd` agy gets its arguments unchanged:** The relay starts a `.cmd` or `.bat` agy through `%SystemRoot%\System32\cmd.exe /e:ON /v:OFF /d /c` with the quoting of the Rust standard library since CVE-2024-24576. `%` cannot expand a variable, and `&` or `|` cannot start a second command. A line break, or a command line over 8191 characters, stops the relay before agy starts, with a hint to pipe the prompt on stdin.
+- **`switch off` and `switch port` leave another instance alone:** They stopped or rewrote the installed service even when it ran the gateway of another port. A second instance (`LLM_SWITCHER_PORT`) then stopped the first one. The service now counts only for the port its definition names. The test suite triggered the same fault and stopped the real gateway of the machine.
+
 ## Release 1.3.2
 
 - **Codex over WebSocket crosses Bifrost:** Codex uses its WebSocket transport by default. The gateway now sends each WebSocket turn to intact `/v1/responses` as one HTTP request with the whole conversation, and sends each event back as one frame. Before, these turns took the convert route. A stream that stops before `response.completed` ends the turn with `response.failed`.

package/README.md

@@ -337,9 +337,18 @@ gateway for its identity proof before it gives agy the variable. If the port doe
 the proof of this install within 3 seconds, the shim removes the variable, prints one line, and agy
 uses its official endpoint.
 
-The shim does this check only when agy starts. If the gateway stops while agy runs (`switch off`, a
-crash, an update), the port is free. Another account on this computer can then take the port and
-receive the token. To close this gap, close agy before you stop the gateway.
+The gateway can also stop while agy runs (`switch off`, a crash, an update). Its port is then free,
+and another program can take it. So a routed agy never talks to the gateway port directly. The shim
+starts agy behind a relay (`agy-relay.mjs`) that holds its own loopback port for as long as agy
+runs. For each connection from agy, the relay asks the gateway for its identity proof on the same
+socket, and sends the request on that socket only after the proof holds. If the proof fails, agy
+gets a 502, and its token stays in the relay.
+
+The relay accepts only a proof keyed by `gateway.secret`, a random key next to `admin.token`. No
+page and no route of the gateway serves this key. The dashboard page carries `admin.token`, so a
+proof keyed by `admin.token` could be made by any program that loads the page. If the running
+gateway is older than the relay, agy gets a 502 that says to restart it (`switch off`, then
+`switch on`).
 
 ### Blindfold mode (optional)
 

package/README.vi.md

@@ -337,9 +337,17 @@ agy gửi token này dạng rõ tới `CLOUD_CODE_URL`. Vì vậy shim `agy` h
 trước khi giao biến này cho agy. Nếu cổng không trả lời đúng bằng chứng của bản cài này trong 3 giây,
 shim gỡ biến, in một dòng thông báo, và agy dùng endpoint chính thức.
 
-Shim chỉ kiểm tra việc này lúc agy khởi động. Nếu gateway dừng trong lúc agy đang chạy (`switch off`,
-crash, cập nhật), cổng bị bỏ trống. Khi đó một tài khoản khác trên máy có thể chiếm cổng và nhận token.
-Để không có khoảng hở này, hãy đóng agy trước khi dừng gateway.
+Gateway cũng có thể dừng trong lúc agy đang chạy (`switch off`, crash, cập nhật). Khi đó cổng của nó
+bỏ trống, và một chương trình khác có thể chiếm cổng. Vì vậy agy đã route không bao giờ nói chuyện
+trực tiếp với cổng gateway. Shim chạy agy sau một relay (`agy-relay.mjs`) giữ cổng loopback riêng
+suốt thời gian agy chạy. Với mỗi kết nối của agy, relay hỏi gateway bằng chứng danh tính trên chính
+socket đó, và chỉ gửi request trên socket ấy khi bằng chứng đúng. Nếu sai, agy nhận 502, và token
+vẫn nằm lại trong relay.
+
+Relay chỉ chấp nhận bằng chứng ký bằng `gateway.secret`, một khóa ngẫu nhiên nằm cạnh `admin.token`.
+Không trang và không route nào của gateway trả về khóa này. Trang dashboard chứa `admin.token`, nên
+bằng chứng ký bằng `admin.token` thì chương trình nào tải trang cũng làm giả được. Nếu gateway đang
+chạy cũ hơn relay, agy nhận 502 kèm hướng dẫn khởi động lại (`switch off`, rồi `switch on`).
 
 ### Chế độ blindfold (tùy chọn)
 

package/agy-relay-lib.mjs

@@ -0,0 +1,86 @@
+// Pure helpers of agy-relay.mjs, kept apart so tests can import them without starting a relay.
+
+// The switcher writes 127.0.0.1 only. localhost can resolve to ::1, which no proof covers.
+export function gatewayPort(raw) {
+  let u;
+  try { u = new URL(raw); } catch { return 0; }
+  if (u.protocol !== 'http:' || u.hostname !== '127.0.0.1') return 0;
+  const port = Number(u.port);
+  return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : 0;
+}
+
+// One complete HTTP/1.1 answer at the start of `buf`: { status, text, rest }, or null while it is
+// still incomplete. An answer with no length cannot share its socket, so it counts as a failure.
+export function readAnswer(buf) {
+  const end = buf.indexOf('\r\n\r\n');
+  if (end < 0) return null;
+  const lines = buf.subarray(0, end).toString('latin1').split('\r\n');
+  const status = Number(lines[0].split(' ')[1]);
+  const headers = {};
+  for (const line of lines.slice(1)) {
+    const i = line.indexOf(':');
+    if (i > 0) headers[line.slice(0, i).trim().toLowerCase()] = line.slice(i + 1).trim();
+  }
+  const rest = buf.subarray(end + 4);
+  if (/close/i.test(headers.connection || '')) return { status: 0, text: '', rest };
+  if (headers['content-length'] !== undefined) {
+    const n = Number(headers['content-length']);
+    if (!Number.isInteger(n) || n < 0) return { status: 0, text: '', rest };
+    if (rest.length < n) return null;
+    return { status, text: rest.subarray(0, n).toString('utf8'), rest: rest.subarray(n) };
+  }
+  if (/chunked/i.test(headers['transfer-encoding'] || '')) {
+    const parts = [];
+    let off = 0;
+    for (;;) {
+      const lineEnd = rest.indexOf('\r\n', off);
+      if (lineEnd < 0) return null;
+      const size = parseInt(rest.subarray(off, lineEnd).toString('latin1'), 16);
+      if (!Number.isInteger(size) || size < 0) return { status: 0, text: '', rest };
+      if (size === 0) {
+        if (rest.length < lineEnd + 4) return null;
+        return { status, text: Buffer.concat(parts).toString('utf8'), rest: rest.subarray(lineEnd + 4) };
+      }
+      if (rest.length < lineEnd + 2 + size + 2) return null;
+      parts.push(rest.subarray(lineEnd + 2, lineEnd + 2 + size));
+      off = lineEnd + 2 + size + 2;
+    }
+  }
+  return { status: 0, text: '', rest };
+}
+
+// The longest string cmd.exe takes after /c.
+export const CMD_LIMIT = 8191;
+const SAFE = /^[A-Za-z0-9#$*+\-./:?@\\_]$/;
+
+// One argument for a batch file, as the Rust standard library builds it since CVE-2024-24576
+// (make_bat_command_line): `"` becomes `""`, and `%` becomes `%%cd:~,%`, which expands to `%`, so
+// cmd.exe never expands a %name% or %name:x=y% that came from the argument.
+function batArg(arg) {
+  const quote = arg === '' || arg.endsWith('\\') || [...arg].some(c => !SAFE.test(c));
+  let out = quote ? '"' : '';
+  let backslashes = 0;
+  for (const c of arg) {
+    if (c === '\\') {
+      backslashes++;
+    } else {
+      if (c === '"') out += `${'\\'.repeat(backslashes)}"`;
+      else if (c === '%') out += '%%cd:~,';
+      backslashes = 0;
+    }
+    out += c;
+  }
+  if (quote) out += `${'\\'.repeat(backslashes)}"`;
+  return out;
+}
+
+// The cmd.exe arguments that run a .cmd/.bat with `args` unchanged: { args } or { error }.
+export function batCommandLine(script, args) {
+  if (script.includes('"') || script.endsWith('\\')) return { error: `the path of agy (${script}) cannot hold " or end with \\` };
+  for (const a of args) {
+    if (/[\r\n]/.test(a)) return { error: 'an argument holds a line break, which a .cmd or .bat agy cannot receive. Pipe the prompt on stdin instead.' };
+  }
+  const inner = `"${[`"${script.replace(/%/g, '%%cd:~,%')}"`, ...args.map(batArg)].join(' ')}"`;
+  if (inner.length > CMD_LIMIT) return { error: `the command line is longer than ${CMD_LIMIT} characters, the limit of cmd.exe. Pipe the prompt on stdin instead.` };
+  return { args: ['/e:ON', '/v:OFF', '/d', '/c', inner] };
+}

package/agy-relay.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// Runs agy behind a relay that holds its own loopback port for exactly as long as agy runs.
+//
+// agy sends its Google token in clear text to CLOUD_CODE_URL. The shim checks the gateway once,
+// at launch. A gateway that stops later frees its port, and another program can take it. So agy
+// talks only to this relay: for each connection it asks the gateway for its relay proof on the
+// socket it will use, and sends agy's bytes only after that proof holds.
+//
+// Usage: node agy-relay.mjs <gateway-url> <agy> [args...]
+import net from 'node:net';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { relayProof } from './state.mjs';
+import { gatewayPort, readAnswer, batCommandLine } from './agy-relay-lib.mjs';
+
+// The proof of a live gateway takes milliseconds; a squatter gains nothing from a longer wait.
+const PROOF_MS = 3000;
+const MAX_PROBE_ANSWER = 64 * 1024;
+
+// The gateway on a new socket: { sock } when it proved itself with the relay key (state.mjs),
+// otherwise { old: true } for a gateway built before relayProof, or {} for anything else. Only the
+// first case gets agy's bytes, on this same socket, so no other process can answer them.
+function provenSocket(port) {
+  return new Promise((resolve) => {
+    const nonce = crypto.randomBytes(16).toString('hex');
+    const sock = net.connect(port, '127.0.0.1');
+    let buf = Buffer.alloc(0);
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      sock.off('data', onData);
+      sock.off('error', onFail);
+      sock.off('close', onFail);
+      if (result.sock) return resolve(result);
+      sock.destroy();
+      resolve(result);
+    };
+    const onFail = () => finish({});
+    const onData = (chunk) => {
+      buf = Buffer.concat([buf, chunk]);
+      if (buf.length > MAX_PROBE_ANSWER) return finish({});
+      const answer = readAnswer(buf);
+      if (!answer) return;
+      // Nothing may follow the probe answer: those bytes would reach agy as its own answer.
+      if (answer.status !== 200 || answer.rest.length) return finish({});
+      let body;
+      try { body = JSON.parse(answer.text); } catch { return finish({}); }
+      if (!body || typeof body !== 'object' || Array.isArray(body)) return finish({});
+      if (body.proxy !== 'llm-switcher' || body.port !== port) return finish({});
+      // An absent field, never a falsy one: relayProof '' must still fail the check below.
+      if (!Object.hasOwn(body, 'relayProof')) return finish({ old: true });
+      const expected = relayProof(nonce, { port, pid: body.pid });
+      finish(Boolean(expected) && body.relayProof === expected ? { sock } : {});
+    };
+    const timer = setTimeout(onFail, PROOF_MS);
+    sock.on('data', onData);
+    sock.on('error', onFail);
+    sock.on('close', onFail);
+    sock.write(`GET /health?challenge=${nonce} HTTP/1.1\r\nHost: 127.0.0.1:${port}\r\nConnection: keep-alive\r\n\r\n`);
+  });
+}
+
+// agy shows a Code Assist error, and its request stays in this process.
+function refusal(message) {
+  const body = JSON.stringify({ error: { code: 502, status: 'UNAVAILABLE', message } });
+  return `HTTP/1.1 502 Bad Gateway\r\nContent-Type: application/json\r\nContent-Length: ${Buffer.byteLength(body)}\r\nConnection: close\r\n\r\n${body}`;
+}
+const NOT_PROVED = 'LLM Switcher: the gateway did not prove its identity, so this request was not sent. Run `switch on`, or `switch off agy`.';
+const OLD_GATEWAY = 'LLM Switcher: the running gateway is older than this relay. Restart it: `switch off`, then `switch on`.';
+
+function startRelay(port) {
+  // pauseOnConnect: agy's bytes stay unread until the gateway on this connection has proved itself.
+  const server = net.createServer({ pauseOnConnect: true }, async (client) => {
+    client.on('error', () => client.destroy());
+    const { sock: up, old } = await provenSocket(port);
+    if (client.destroyed) return up?.destroy();
+    if (!up) {
+      client.end(refusal(old ? OLD_GATEWAY : NOT_PROVED));
+      client.resume(); // read and drop the request; nothing of it leaves this process
+      return;
+    }
+    up.on('error', () => client.destroy());
+    client.on('close', () => up.destroy());
+    up.on('close', () => client.destroy());
+    client.pipe(up);
+    up.pipe(client);
+    client.resume();
+  });
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => resolve(server));
+  });
+}
+
+// A .cmd/.bat cannot start without cmd.exe. It is always the one in System32: a bare name would be
+// looked up in the current directory first.
+function launch(file, args, env) {
+  if (process.platform === 'win32' && /\.(cmd|bat)$/i.test(file)) {
+    const line = batCommandLine(file, args);
+    if (line.error) {
+      console.error(`[llm-switcher] cannot start agy: ${line.error}`);
+      process.exit(2);
+    }
+    const cmd = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'cmd.exe');
+    return spawn(cmd, line.args, { stdio: 'inherit', env, windowsVerbatimArguments: true });
+  }
+  return spawn(file, args, { stdio: 'inherit', env });
+}
+
+const [gatewayUrl, agy, ...args] = process.argv.slice(2);
+if (!agy) {
+  console.error('Usage: node agy-relay.mjs <gateway-url> <agy> [args...]');
+  process.exit(2);
+}
+if (args.some(a => a.includes('\0'))) {
+  console.error('[llm-switcher] cannot start agy: an argument holds a NUL character.');
+  process.exit(2);
+}
+
+const env = { ...process.env };
+delete env.CLOUD_CODE_URL;
+const port = gatewayPort(gatewayUrl);
+if (port) {
+  const server = await startRelay(port);
+  env.CLOUD_CODE_URL = `http://127.0.0.1:${server.address().port}`;
+} else {
+  console.error(`[llm-switcher] ${String(gatewayUrl)} is not the address of this switcher's gateway; agy uses its official endpoint.`);
+}
+
+const child = launch(agy, args, env);
+// Ctrl+C reaches agy and this relay together. agy decides what it means; the relay ends with agy.
+process.on('SIGINT', () => {});
+if (process.platform === 'win32') process.on('SIGBREAK', () => {});
+process.on('SIGTERM', () => child.kill());
+child.on('error', (err) => {
+  console.error(`[llm-switcher] cannot start agy (${agy}): ${err.message}`);
+  process.exit(127);
+});
+child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-switcher",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "Zero-dependency multi-protocol edge gateway & provider switcher for Claude Code and Codex, with OpenAI-compatible, Anthropic and Vertex upstreams",
   "keywords": [
     "llm",

package/proxy.mjs

@@ -22,7 +22,7 @@ import {
   getActiveMap, setTargetProfile, activateProfile, deactivateProfile, deactivateAll, deleteProfile,
   isProfileActive, profileAcceptsTarget, applyLaunchState, readLaunchFlags, redactConfig, MASKED_KEY,
   modelForSlot, primaryModel, codexPublicModel, isSafeModelName, parsePort, CODEX_MODEL_SLOTS,
-  ensureAdminToken, identityProof, reconcileBlindfold, checkBlindfoldTarget,
+  ensureAdminToken, ensureGatewaySecret, relayProof, identityProof, reconcileBlindfold, checkBlindfoldTarget,
   codexModelEntry, smallestWindows, publicModelWindows, model1MForSlot,
   contractLabSettings, STATE_DIR, stopRecordedBlindfold
 } from './state.mjs';
@@ -116,6 +116,8 @@ function checkRequestOrigin(req) {
 // The Host/Origin guard stops browser pages only. A local process that is not the owner must
 // also present the token from admin.token (mode 0600) to use /api/*.
 const ADMIN_TOKEN = Buffer.from(ensureAdminToken());
+// The relay key. The gateway keeps no copy: relayProof() reads the file for each proof.
+ensureGatewaySecret();
 
 // `switch contract-probe` names the trace id of the exchange it drives, so it can print the id
 // before intact holds it. Only a process that can read admin.token is believed, and the marker
@@ -1315,7 +1317,9 @@ async function route(req, res) {
       proxy: 'llm-switcher',
       ...(challenge ? {
         pid: process.pid,
-        proof: identityProof(challenge, { role: 'gateway', port: PORT, pid: process.pid }, ADMIN_TOKEN.toString())
+        proof: identityProof(challenge, { role: 'gateway', port: PORT, pid: process.pid }, ADMIN_TOKEN.toString()),
+        // The only proof agy-relay.mjs accepts: its key is not on the dashboard page.
+        relayProof: relayProof(challenge, { port: PORT, pid: process.pid })
       } : {}),
       port: PORT,
       configLoaded: Boolean(loadConfig()),

package/shim.mjs

@@ -40,6 +40,9 @@ const ROUTE_NOTIFIER = path.join(path.dirname(fileURLToPath(import.meta.url)), '
 // agy sends its Google token in clear text to CLOUD_CODE_URL. Its shim asks this helper for the
 // gateway's identity proof first, so a process that took the port never receives the token.
 const GATEWAY_CHECK = path.join(path.dirname(fileURLToPath(import.meta.url)), 'verify-gateway.mjs');
+// The launch check covers the start only. A routed agy then runs behind this relay, which proves
+// the gateway on every connection, so a port freed later never receives the token.
+const AGY_RELAY = path.join(path.dirname(fileURLToPath(import.meta.url)), 'agy-relay.mjs');
 
 // CLIs to wrap. `claude` is the most important case (--resume); codex and agy have their own files.
 export const SHIMMED = ['claude', 'codex', 'agy'];
@@ -191,6 +194,13 @@ if [ -z "$REAL" ]; then
   exit 127
 fi
 
+${name !== 'agy' ? '' : `# A routed agy talks only to its relay, which lives as long as agy (agy-relay.mjs).
+if [ "$TOOL_ACTIVE" = "1" ] && [ -n "\${CLOUD_CODE_URL:-}" ]; then
+  GATEWAY_URL="$CLOUD_CODE_URL"
+  unset CLOUD_CODE_URL
+  exec node "${AGY_RELAY}" "$GATEWAY_URL" "$REAL" "$@"
+fi
+`}
 # No override of any kind: the tool keeps its own configuration and its own model names (F3, R1).
 exec "$REAL" "$@"
 `;
@@ -266,14 +276,26 @@ for /f "tokens=1 delims==" %%V in ('set LLM_SWITCHER_CODEX_ 2^>nul ^| findstr /b
 ${caBlock}
 
 REM Find the real binary: drop this shim's own directory so it never calls itself.
-for /f "delims=" %%i in ('where ${name}.cmd 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do (
+${name === 'agy' ? `set "REAL_BIN="
+for /f "delims=" %%i in ('where ${name}.cmd 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do if not defined REAL_BIN set "REAL_BIN=%%i"
+if not defined REAL_BIN for /f "delims=" %%i in ('where ${name}.exe 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do if not defined REAL_BIN set "REAL_BIN=%%i"
+if not defined REAL_BIN goto :NOT_FOUND
+REM A routed agy talks only to its relay, which lives as long as agy (agy-relay.mjs).
+if not "%TOOL_ACTIVE%"=="1" goto :RUN_PLAIN
+if not defined CLOUD_CODE_URL goto :RUN_PLAIN
+node "${AGY_RELAY}" "%CLOUD_CODE_URL%" "%REAL_BIN%" %*
+exit /b
+:RUN_PLAIN
+call "%REAL_BIN%" %*
+exit /b
+:NOT_FOUND` : `for /f "delims=" %%i in ('where ${name}.cmd 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do (
   call "%%i" %*
   exit /b
 )
 for /f "delims=" %%i in ('where ${name}.exe 2^>nul ^| findstr /v /i "\\.llm-switcher\\\\bin"') do (
   call "%%i" %*
   exit /b
-)
+)`}
 echo [llm-switcher] cannot find the real '${name}' on PATH.>&2
 exit /b 127
 

package/state.mjs

@@ -107,6 +107,38 @@ export function ensureAdminToken() {
   return token;
 }
 
+// The key of the proof that agy-relay.mjs checks. Random, never derived from admin.token: the
+// dashboard page carries admin.token, so a proof keyed by it can be made by anyone who loads /ui.
+export const gatewaySecretPath = path.join(path.dirname(configPath), 'gateway.secret');
+
+export function readGatewaySecret() {
+  try {
+    return fs.readFileSync(gatewaySecretPath, 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// A good secret is kept. A missing, empty or blank file is replaced through a rename, so a damaged
+// file never leaves agy without a key. Throws when it cannot write; never leaves a temporary file.
+export function ensureGatewaySecret() {
+  if (readGatewaySecret()) return;
+  const tmp = `${gatewaySecretPath}.${process.pid}.tmp`;
+  try {
+    fs.rmSync(tmp, { force: true });
+    fs.writeFileSync(tmp, crypto.randomBytes(32).toString('hex'), { mode: 0o600, flag: 'wx' });
+    fs.renameSync(tmp, gatewaySecretPath);
+  } catch (err) {
+    try { fs.rmSync(tmp, { force: true }); } catch {}
+    throw err;
+  }
+}
+
+export function relayProof(nonce, { port, pid }, secret = readGatewaySecret()) {
+  if (!secret) return '';
+  return crypto.createHmac('sha256', secret).update(['relay', port, pid, nonce].join('|')).digest('hex');
+}
+
 // `switch ui` must not put the token on a command line: /proc/<pid>/cmdline is readable by every
 // account. It opens this private file instead, which redirects to the dashboard with the token.
 export function writeDashboardLauncher(url) {

package/switch.mjs

@@ -232,8 +232,8 @@ async function stopProxy(port) {
   };
   // Our own unit needs no identity proof: its manager stops it. That also covers a unit that is
   // still starting (the port is free) and a hung gateway under the unit (the probe is silent).
-  const svc = installedService();
-  const ownUnit = svc && [port, null].includes(servicePort(svc));
+  const svc = serviceForPort(port);
+  const ownUnit = Boolean(svc);
   if (state === 'free') {
     if (!ownUnit) return 'not-running';
     serviceStop(svc);
@@ -271,7 +271,7 @@ async function changePort(newPortStr) {
   // Refuse before anything stops: the old gateway keeps running when the new port is taken.
   const target = await probeGateway(p);
   if (isHeld(target)) refuseForeignPort(p, 'this switcher', target);
-  const svc = installedService();
+  const svc = serviceForPort(oldPort);
   // The unit is rewritten below. It keeps the choice that `service install --no-autoupdate` made.
   const svcText = svc ? serviceText(svc) : null;
   const autoupdate = svcText === null || autoupdateFromServiceText(svcText);
@@ -688,6 +688,13 @@ function servicePort(kind) {
   return text === null ? null : portFromServiceText(text);
 }
 
+// The installed service runs the gateway of the port its definition names. A second instance
+// (LLM_SWITCHER_PORT) must never stop or rewrite it. A definition with no readable port counts.
+function serviceForPort(port) {
+  const svc = installedService();
+  return svc && [port, null].includes(servicePort(svc)) ? svc : null;
+}
+
 function reportBackup(backup) {
   if (backup) console.log(`[Service] The previous definition differed and is kept as ${backup}.`);
 }

package/tests/agy-relay.test.mjs

@@ -0,0 +1,316 @@
+// Tests for agy-relay.mjs: agy's Google token reaches a gateway only on a connection where that
+// gateway proved itself with the key of gateway.secret, also when the gateway stops in the middle
+// of an agy session.
+import { test, after } 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 net from 'node:net';
+import http from 'node:http';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const RELAY = path.join(ROOT, 'agy-relay.mjs');
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'agyrelay-'));
+after(() => fs.rmSync(TMP, { recursive: true, force: true }));
+
+// The directory of a relay run: admin.token, and gateway.secret unless `secret` is false.
+const TOKEN = 'b'.repeat(64);
+function stateDir(name, { secret = true } = {}) {
+  const dir = path.join(TMP, name);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'admin.token'), TOKEN);
+  if (secret) fs.writeFileSync(path.join(dir, 'gateway.secret'), crypto.randomBytes(32).toString('hex'));
+  return dir;
+}
+const MAIN = stateDir('main');
+const { identityProof } = await import(pathToFileURL(path.join(ROOT, 'state.mjs')).href);
+
+// Stands in for agy: FAKE_CALLS requests with its Google token, then one more once `signal` exists.
+const FAKE_AGY = path.join(TMP, 'fake-agy.mjs');
+fs.writeFileSync(FAKE_AGY, `
+import fs from 'node:fs';
+import http from 'node:http';
+const [, , code, signal] = process.argv;
+const call = () => new Promise((resolve) => {
+  const req = http.request(process.env.CLOUD_CODE_URL + '/v1internal:loadCodeAssist', {
+    method: 'POST', agent: false, headers: { authorization: 'Bearer google-secret', 'content-type': 'application/json' }
+  }, (res) => { let b = ''; res.on('data', d => { b += d; }); res.on('end', () => { console.log('STATUS ' + res.statusCode + ' ' + b); resolve(); }); res.on('error', () => resolve()); });
+  req.on('error', (e) => { console.log('ERROR ' + e.message); resolve(); });
+  req.end('{}');
+});
+console.log('CCU ' + (process.env.CLOUD_CODE_URL || ''));
+if (process.env.CLOUD_CODE_URL) for (let i = 0; i < Number(process.env.FAKE_CALLS || 1); i++) await call();
+if (signal) { while (!fs.existsSync(signal)) await new Promise(r => setTimeout(r, 50)); await call(); }
+process.exit(Number(code) || 0);
+`);
+
+const relayHmac = (key, port, pid, nonce) => crypto.createHmac('sha256', key).update(['relay', port, pid, nonce].join('|')).digest('hex');
+
+// The answer of a gateway fixture to the identity probe. 'real' signs with the raw bytes of the
+// gateway.secret file; every other kind is one way to be wrong.
+function probeAnswer(kind, challenge, port, dir) {
+  const pid = 4242;
+  const secretFile = path.join(dir, 'gateway.secret');
+  const secret = fs.existsSync(secretFile) ? fs.readFileSync(secretFile) : Buffer.from('no-secret');
+  let status = 200;
+  let body = { status: 'ok', proxy: 'llm-switcher', port, pid, proof: identityProof(challenge, { role: 'gateway', port, pid }, TOKEN) };
+  if (kind === 'real' || kind === 'extra') body.relayProof = relayHmac(secret, port, pid, challenge);
+  if (kind === 'squatter') body.relayProof = relayHmac(TOKEN, port, pid, challenge);
+  if (kind === 'replay') Object.assign(body, { relayProof: relayHmac(secret, port, pid, 'stale-nonce'), nonce: 'stale-nonce', challenge: 'stale-nonce' });
+  if (kind === 'status500') { status = 500; body.relayProof = relayHmac(secret, port, pid, challenge); }
+  if (kind === 'oversize') Object.assign(body, { relayProof: relayHmac(secret, port, pid, challenge), pad: 'x'.repeat(70 * 1024) });
+  if (kind === 'empty') body.relayProof = '';
+  if (kind === 'null') body = null;
+  if (kind === 'number') body = 7;
+  if (kind === 'array') body = [];
+  const text = JSON.stringify(body);
+  let out = `HTTP/1.1 ${status} X\r\nContent-Type: application/json\r\nContent-Length: ${Buffer.byteLength(text)}\r\nConnection: keep-alive\r\n\r\n${text}`;
+  if (kind === 'extra') out += 'HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nContent-Length: 13\r\n\r\nINJECTED-BODY';
+  return out;
+}
+
+// A raw gateway fixture on `port`. `kinds` is one kind, or one kind per connection in order (the
+// last repeats). It records every challenge and every byte that arrives after its probe answer.
+function gateway(kinds, { port = 0, dir = MAIN } = {}) {
+  const list = [].concat(kinds);
+  const seen = { challenges: [], bytes: '' };
+  let conn = 0;
+  const server = net.createServer((sock) => {
+    const kind = list[Math.min(conn++, list.length - 1)];
+    sock.on('error', () => {});
+    let buf = '';
+    let probed = false;
+    sock.on('data', (d) => {
+      if (kind === 'silent') { seen.bytes += d; return; }
+      if (probed) {
+        seen.bytes += d;
+        buf += d;
+        // 'real' answers each forwarded request once its 2-byte body is in.
+        const end = buf.indexOf('\r\n\r\n');
+        if (kind === 'real' && end >= 0 && buf.length >= end + 6) {
+          buf = '';
+          const answer = '{"answeredBy":"real"}';
+          sock.write(`HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: ${answer.length}\r\nConnection: keep-alive\r\n\r\n${answer}`);
+        }
+        return;
+      }
+      buf += d;
+      const end = buf.indexOf('\r\n\r\n');
+      if (end < 0) return;
+      const head = buf.slice(0, end);
+      const rest = buf.slice(end + 4);
+      buf = '';
+      probed = true;
+      seen.challenges.push((head.match(/challenge=([0-9a-f]+)/) || [])[1] || '');
+      sock.write(probeAnswer(kind, seen.challenges.at(-1), server.address().port, dir));
+      if (rest) seen.bytes += rest;
+    });
+  });
+  return new Promise((resolve) => server.listen(port, '127.0.0.1', () => resolve({ server, seen, port: server.address().port })));
+}
+
+function runRelay(gatewayUrl, args = [], { env = {}, dir = MAIN } = {}) {
+  const child = spawn(process.execPath, [RELAY, gatewayUrl, process.execPath, FAKE_AGY, ...args], {
+    env: { ...process.env, LLM_SWITCHER_CONFIG: path.join(dir, 'config.json'), CLOUD_CODE_URL: gatewayUrl, ...env }
+  });
+  let out = '', err = '';
+  child.stdout.on('data', d => { out += d; });
+  child.stderr.on('data', d => { err += d; });
+  const done = new Promise((resolve) => {
+    const timer = setTimeout(() => child.kill(), 30000);
+    child.on('close', (code) => { clearTimeout(timer); resolve({ code, out, err }); });
+  });
+  return { child, done, out: () => out };
+}
+
+const statuses = (out) => out.split('\n').filter(l => l.startsWith('STATUS')).map(l => Number(l.split(' ')[1]));
+const ccuPort = (out) => Number((out.match(/CCU http:\/\/127\.0\.0\.1:(\d+)/) || [])[1]);
+
+test('agy talks to its own relay port, and the relay forwards to a gateway that proved itself with gateway.secret', async (t) => {
+  const g = await gateway('real');
+  t.after(() => g.server.close());
+  const { code, out } = await runRelay(`http://127.0.0.1:${g.port}`).done;
+  assert.equal(code, 0);
+  assert.ok(ccuPort(out) > 0 && ccuPort(out) !== g.port, `agy gets the relay port, not the gateway port: ${out}`);
+  assert.match(out, /STATUS 200 .*"answeredBy":"real"/);
+  assert.match(g.seen.bytes, /Bearer google-secret/);
+});
+
+// Every way a listener on the gateway port can be wrong: agy gets a 502, and its token never leaves.
+for (const kind of ['squatter', 'replay', 'extra', 'status500', 'oversize', 'old']) {
+  test(`a gateway that answers the probe as '${kind}' gets a 502 and never receives the token`, async (t) => {
+    const g = await gateway(kind);
+    t.after(() => g.server.close());
+    const { code, out } = await runRelay(`http://127.0.0.1:${g.port}`).done;
+    assert.equal(code, 0);
+    assert.deepEqual(statuses(out), [502], out);
+    assert.doesNotMatch(g.seen.bytes, /google-secret/);
+    assert.doesNotMatch(out, /INJECTED-BODY/, 'bytes after the probe answer never reach agy');
+    if (kind === 'old') assert.match(out, /switch off.*switch on/, 'an old gateway gets the restart hint');
+  });
+}
+
+test('a silent listener only ever sees the probe, never the token', async (t) => {
+  const g = await gateway('silent');
+  t.after(() => g.server.close());
+  const { out } = await runRelay(`http://127.0.0.1:${g.port}`).done;
+  assert.deepEqual(statuses(out), [502]);
+  assert.match(g.seen.bytes, /^GET \/health\?challenge=/);
+  assert.doesNotMatch(g.seen.bytes, /google-secret/);
+});
+
+test('one relay sends a fresh challenge on every connection', async (t) => {
+  const g = await gateway('replay');
+  t.after(() => g.server.close());
+  await runRelay(`http://127.0.0.1:${g.port}`, [], { env: { FAKE_CALLS: '2' } }).done;
+  assert.equal(g.seen.challenges.length, 2);
+  assert.notEqual(g.seen.challenges[0], g.seen.challenges[1]);
+  assert.match(g.seen.challenges[0], /^[0-9a-f]{32}$/);
+});
+
+test('without gateway.secret the relay trusts no proof, not even one keyed by admin.token', async (t) => {
+  const dir = stateDir('nosecret', { secret: false });
+  for (const kind of ['empty', 'squatter']) {
+    const g = await gateway(kind, { dir });
+    t.after(() => g.server.close());
+    const { out } = await runRelay(`http://127.0.0.1:${g.port}`, [], { dir }).done;
+    assert.deepEqual(statuses(out), [502], `${kind}: ${out}`);
+    assert.doesNotMatch(g.seen.bytes, /google-secret/, kind);
+  }
+});
+
+test('an answer that is not an object gets a 502, and the relay keeps serving agy', async (t) => {
+  const g = await gateway(['null', 'number', 'array', 'real']);
+  t.after(() => g.server.close());
+  const { code, out } = await runRelay(`http://127.0.0.1:${g.port}`, [], { env: { FAKE_CALLS: '4' } }).done;
+  assert.equal(code, 0);
+  assert.deepEqual(statuses(out), [502, 502, 502, 200], out);
+});
+
+test('a gateway replaced in the middle of an agy session never receives the token', async (t) => {
+  const real = await gateway('real');
+  const port = real.port;
+  const signal = path.join(TMP, 'go-swap');
+  const run = runRelay(`http://127.0.0.1:${port}`, ['0', signal]);
+  for (let i = 0; i < 200 && !/STATUS/.test(run.out()); i++) await new Promise(r => setTimeout(r, 50));
+  assert.match(run.out(), /STATUS 200 /, 'the first request went through the real gateway');
+  // The gateway stops, and a process that holds admin.token takes its port.
+  await new Promise(r => real.server.close(r));
+  const squatter = await gateway('squatter', { port });
+  t.after(() => squatter.server.close());
+  fs.writeFileSync(signal, '');
+  const { out } = await run.done;
+  assert.deepEqual(statuses(out), [200, 502]);
+  assert.doesNotMatch(squatter.seen.bytes, /google-secret/);
+});
+
+test('the relay works against the real proxy.mjs and the proof it computes', async (t) => {
+  const dir = stateDir('realproxy', { secret: false });
+  fs.rmSync(path.join(dir, 'admin.token'));
+  const mock = http.createServer((req, res) => { req.resume(); res.end('{"answeredBy":"code-assist-mock"}'); });
+  await new Promise(r => mock.listen(0, '127.0.0.1', r));
+  t.after(() => mock.close());
+  const port = await new Promise(r => { const s = net.createServer().listen(0, '127.0.0.1', () => { const p = s.address().port; s.close(() => r(p)); }); });
+  fs.writeFileSync(path.join(dir, 'config.json'), JSON.stringify({ port, activeProfiles: { claude: null, codex: null, agy: null }, profiles: {} }));
+  const proxy = spawn(process.execPath, [path.join(ROOT, 'proxy.mjs'), '--port', String(port)], {
+    env: { ...process.env, LLM_SWITCHER_CONFIG: path.join(dir, 'config.json'), LLM_SWITCHER_STATE_DIR: dir, CLAUDE_CONFIG_DIR: path.join(dir, 'claude'), LLM_SWITCHER_PORT: '', LLM_SWITCHER_CODE_ASSIST_URL: `http://127.0.0.1:${mock.address().port}` },
+    stdio: 'ignore'
+  });
+  t.after(() => proxy.kill());
+  for (let i = 0; i < 50; i++) {
+    try { if ((await fetch(`http://127.0.0.1:${port}/health`)).ok) break; } catch {}
+    await new Promise(r => setTimeout(r, 100));
+  }
+  assert.ok(fs.existsSync(path.join(dir, 'gateway.secret')), 'the gateway made its secret at startup');
+  const { out } = await runRelay(`http://127.0.0.1:${port}`, [], { dir }).done;
+  assert.match(out, /STATUS 200 .*code-assist-mock/, out);
+});
+
+test('the relay exits with the exit code of agy', async (t) => {
+  const g = await gateway('real');
+  t.after(() => g.server.close());
+  const { code } = await runRelay(`http://127.0.0.1:${g.port}`, ['7']).done;
+  assert.equal(code, 7);
+});
+
+test('a gateway address that is not 127.0.0.1 with a port leaves agy on its official endpoint', async () => {
+  for (const bad of ['http://localhost:3456', 'http://127.0.0.1', 'https://127.0.0.1:3456', 'not a url']) {
+    const { code, out, err } = await runRelay(bad).done;
+    assert.equal(code, 0, bad);
+    assert.match(out, /^CCU $/m, `${bad}: agy gets no CLOUD_CODE_URL`);
+    assert.match(err, /official endpoint/, bad);
+  }
+});
+
+// An argv string cannot hold NUL on any platform: Node refuses it before a process exists, so it
+// can reach neither the relay nor agy. The relay's own NUL guard only backs this up.
+test('an argument with a NUL character cannot start a process at all', () => {
+  assert.throws(() => spawn(process.execPath, [RELAY, 'http://127.0.0.1:9', process.execPath, FAKE_AGY, 'a\0b']), { code: 'ERR_INVALID_ARG_VALUE' });
+});
+
+// ---- A .cmd agy on Windows: every argument arrives byte-identical through cmd.exe ----------------
+
+const WIN = process.platform === 'win32';
+function cmdFixture(name) {
+  const dir = path.join(TMP, name);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'argv.js'), `require('fs').writeFileSync(require('path').join(process.cwd(), 'argv.json'), JSON.stringify(process.argv.slice(2)));\n`);
+  fs.writeFileSync(path.join(dir, 'agy.cmd'), '@node "%~dp0argv.js" %*\r\n');
+  return dir;
+}
+function runCmdRelay(dir, args) {
+  const child = spawn(process.execPath, [RELAY, 'http://127.0.0.1', path.join(dir, 'agy.cmd'), ...args], {
+    cwd: dir, env: { ...process.env, LLM_SWITCHER_CONFIG: path.join(MAIN, 'config.json') }
+  });
+  let err = '';
+  child.stderr.on('data', d => { err += d; });
+  return new Promise((resolve) => child.on('close', (code) => resolve({ code, err })));
+}
+
+test('a .cmd agy receives every argument byte-identical, and cmd.exe runs nothing else', { skip: !WIN && 'cmd.exe only' }, async () => {
+  const dir = cmdFixture('cmdargs');
+  const args = ['%PATH%', '%PATH:a=%', '%CMDCMDLINE:~-1%&echo PWNED>marker', 'C:\\temp\\', 'a"b', 'a\\"b', 'say "hi there"',
+    '50% off', 'x&y', 'a|b', 'a^b', '<x>', '(x)', '!PATH!', 'héllo wörld', ''];
+  const { code, err } = await runCmdRelay(dir, args);
+  assert.equal(code, 0, err);
+  assert.deepEqual(JSON.parse(fs.readFileSync(path.join(dir, 'argv.json'), 'utf8')), args);
+  assert.equal(fs.existsSync(path.join(dir, 'marker')), false, 'no second command ran');
+});
+
+test('a .cmd agy in a directory with % in its name still starts', { skip: !WIN && 'cmd.exe only' }, async () => {
+  const dir = cmdFixture('50%off');
+  const { code, err } = await runCmdRelay(dir, ['ok']);
+  assert.equal(code, 0, err);
+  assert.deepEqual(JSON.parse(fs.readFileSync(path.join(dir, 'argv.json'), 'utf8')), ['ok']);
+});
+
+test('a .cmd agy gets no line break and no command line over the cmd.exe limit', { skip: !WIN && 'cmd.exe only' }, async () => {
+  for (const [name, args, hint] of [['crlf-n', ['a\nb'], /line break/], ['crlf-r', ['a\rb'], /line break/], ['toolong', ['x'.repeat(8200)], /8191/]]) {
+    const dir = cmdFixture(name);
+    const { code, err } = await runCmdRelay(dir, args);
+    assert.notEqual(code, 0, name);
+    assert.match(err, hint, name);
+    assert.match(err, /stdin/, name);
+    assert.equal(fs.existsSync(path.join(dir, 'argv.json')), false, `${name}: the fixture never ran`);
+  }
+  const dir = cmdFixture('long-ok');
+  const long = 'y'.repeat(4000);
+  const { code, err } = await runCmdRelay(dir, [long]);
+  assert.equal(code, 0, err);
+  assert.deepEqual(JSON.parse(fs.readFileSync(path.join(dir, 'argv.json'), 'utf8')), [long]);
+});
+
+test('an .exe agy gets a line break in an argument unchanged', async (t) => {
+  const dir = path.join(TMP, 'exe-newline');
+  fs.mkdirSync(dir, { recursive: true });
+  const script = path.join(dir, 'argv.mjs');
+  fs.writeFileSync(script, `import fs from 'node:fs'; fs.writeFileSync(${JSON.stringify(path.join(dir, 'argv.json'))}, JSON.stringify(process.argv.slice(2)));\n`);
+  const child = spawn(process.execPath, [RELAY, 'http://127.0.0.1', process.execPath, script, 'a\nb'], { env: { ...process.env, LLM_SWITCHER_CONFIG: path.join(MAIN, 'config.json') } });
+  const code = await new Promise(r => child.on('close', r));
+  assert.equal(code, 0);
+  assert.deepEqual(JSON.parse(fs.readFileSync(path.join(dir, 'argv.json'), 'utf8')), ['a\nb']);
+});

package/tests/agy.e2e.test.mjs

@@ -623,6 +623,20 @@ test('a Codex WS Bifrost stream cut before its end still ends the turn with resp
   }
 });
 
+test('no page or answer of the gateway carries the relay key', async () => {
+  const secret = fs.readFileSync(path.join(tmpDir, 'gateway.secret'), 'utf8').trim();
+  assert.match(secret, /^[0-9a-f]{64}$/, 'the gateway made its key at startup');
+  const token = fs.readFileSync(path.join(tmpDir, 'admin.token'), 'utf8').trim();
+  for (const p of ['/', '/ui', '/health?challenge=x', '/api/status']) {
+    const r = await fetch(url(p), { headers: { 'x-llm-switcher-token': token } });
+    assert.equal(r.status, 200, p);
+    const all = JSON.stringify([...r.headers]) + await r.text();
+    assert.equal(all.includes(secret), false, `${p} carries the relay key`);
+  }
+  const health = await (await fetch(url('/health?challenge=n9'))).json();
+  assert.match(health.relayProof, /^[0-9a-f]{64}$/, 'the gateway answers a relay proof');
+});
+
 test('with agy switched off, its agent turns go back to Google', async (t) => {
   const token = fs.readFileSync(path.join(tmpDir, 'admin.token'), 'utf8').trim();
   const switchAgy = (profile) => fetch(url('/api/switch'), { method: 'POST', headers: { 'content-type': 'application/json', 'x-llm-switcher-token': token }, body: JSON.stringify({ target: 'agy', profile }) });

package/tests/agy.unit.test.mjs

@@ -68,6 +68,9 @@ test('the agy shim reads only its own files, takes no CA, and scrubs a stale gat
   assert.match(posix, /if \[ "\$TOOL_ACTIVE" != "1" \] && \[ -n "\$_u" \]; then/);
   assert.match(shim.renderShim('claude', 'win32'), /NODE_EXTRA_CA_CERTS/, 'Claude keeps its CA block');
   assert.equal(shim.routeEvidence('agy', ' CLOUD_CODE_URL=http://127.0.0.1:3456 PATH=x'), true);
+  assert.match(win, /agy-relay\.mjs" "%CLOUD_CODE_URL%"/, 'a routed agy runs behind its relay');
+  assert.match(posix, /exec node "[^"]*agy-relay\.mjs" "\$GATEWAY_URL" "\$REAL" "\$@"/);
+  assert.doesNotMatch(shim.renderShim('codex', 'win32'), /agy-relay/);
 });
 
 test('the agy hook is merged into hooks.json, unquoted, and removed without touching other hooks', () => {

package/tests/cdp.mjs

@@ -47,7 +47,14 @@ export async function launchBrowser() {
     ...(process.platform === 'linux' || process.getuid?.() === 0 ? ['--no-sandbox'] : []),
     'about:blank'
   ];
-  const child = spawn(findChromium(), args, { stdio: ['ignore', 'ignore', 'pipe'], env: { ...process.env, HOME: dir } });
+  // POSIX: a process group of its own, so close() can stop the renderers and helpers too.
+  const child = spawn(findChromium(), args, { stdio: ['ignore', 'ignore', 'pipe'], env: { ...process.env, HOME: dir }, detached: process.platform !== 'win32' });
+  const stop = (signal) => {
+    try {
+      if (process.platform !== 'win32') process.kill(-child.pid, signal);
+      else child.kill(signal);
+    } catch { /* already gone */ }
+  };
   // The tail of what Chromium printed: the only clue when it starts on a machine no one can watch.
   let stderr = '';
   child.stderr.on('data', (d) => { stderr = (stderr + d).slice(-4000); });
@@ -61,7 +68,7 @@ export async function launchBrowser() {
   if (!port) {
     // SIGKILL and a wait: a Chromium left running holds this test process open.
     if (exited === null) {
-      child.kill('SIGKILL');
+      stop('SIGKILL');
       await new Promise(r => { child.once('exit', r); setTimeout(r, 3000); });
     }
     throw new Error(`Chromium did not open a debugging port (exit: ${exited ?? 'killed'})\n${stderr}`);
@@ -78,8 +85,10 @@ export async function launchBrowser() {
     },
     async close() {
       for (const p of pages) p.close();
-      child.kill();
+      // The whole group: a helper that outlives the main process keeps writing into the profile.
+      stop('SIGTERM');
       await new Promise(r => { child.once('exit', r); setTimeout(r, 2000); });
+      stop('SIGKILL');
       // On Windows a Chromium child process can hold a cache file for a moment after the exit (EBUSY).
       fs.rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
     }

package/tests/gateway-secret.test.mjs

@@ -0,0 +1,124 @@
+// The key of the relay proof: random, independent of admin.token, served by no route, and the only
+// key the relay accepts. Each case runs state.mjs in a child process, so it reads its own directory.
+import { test, after } 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 crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const STATE = pathToFileURL(path.join(ROOT, 'state.mjs')).href;
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'gwsecret-'));
+after(() => fs.rmSync(TMP, { recursive: true, force: true }));
+const TOKEN = 'c'.repeat(64);
+
+function dir(name) {
+  const d = path.join(TMP, name);
+  fs.mkdirSync(d, { recursive: true });
+  fs.writeFileSync(path.join(d, 'admin.token'), TOKEN);
+  return d;
+}
+// Runs `code` (an async function body that gets `s`, the state module) against directory `d`.
+function inState(d, code) {
+  const r = spawnSync(process.execPath, ['--input-type=module', '-e', `const s = await import(${JSON.stringify(STATE)}); const out = await (async () => { ${code} })(); process.stdout.write(JSON.stringify(out ?? null));`], {
+    env: { ...process.env, LLM_SWITCHER_CONFIG: path.join(d, 'config.json'), LLM_SWITCHER_STATE_DIR: d }, encoding: 'utf8'
+  });
+  if (r.status !== 0) throw new Error(r.stderr);
+  return JSON.parse(r.stdout);
+}
+const secretOf = (d) => fs.readFileSync(path.join(d, 'gateway.secret'), 'utf8');
+
+test('ensureGatewaySecret replaces a missing, empty or blank file and keeps a good one', () => {
+  const d = dir('ensure');
+  inState(d, 's.ensureGatewaySecret()');
+  const first = secretOf(d);
+  assert.match(first, /^[0-9a-f]{64}$/, 'hex only, no trailing newline');
+  inState(d, 's.ensureGatewaySecret()');
+  assert.equal(secretOf(d), first, 'an existing secret is kept');
+  for (const blank of ['', '  \n\t']) {
+    fs.writeFileSync(path.join(d, 'gateway.secret'), blank);
+    inState(d, 's.ensureGatewaySecret()');
+    assert.match(secretOf(d), /^[0-9a-f]{64}$/, `a file of ${JSON.stringify(blank)} is replaced`);
+  }
+  assert.deepEqual(fs.readdirSync(d).filter(f => f.endsWith('.tmp')), [], 'no temporary file is left');
+});
+
+test('the secret is random: never derived from admin.token or from the directory', () => {
+  const a = dir('indep-a');
+  const b = dir('indep-b');
+  inState(a, 's.ensureGatewaySecret()');
+  inState(b, 's.ensureGatewaySecret()');
+  const first = secretOf(a);
+  assert.notEqual(first, secretOf(b), 'two directories with the same admin.token');
+  assert.notEqual(first, TOKEN);
+  fs.rmSync(path.join(a, 'gateway.secret'));
+  inState(a, 's.ensureGatewaySecret()');
+  assert.notEqual(secretOf(a), first, 'the same directory and token again');
+});
+
+test('relayProof is an HMAC keyed by the raw bytes of gateway.secret', () => {
+  const d = dir('binding');
+  const raw = 'f'.repeat(64);
+  fs.writeFileSync(path.join(d, 'gateway.secret'), raw);
+  const out = inState(d, `return { secret: s.readGatewaySecret(), proof: s.relayProof('n1', { port: 3456, pid: 77 }) };`);
+  assert.equal(out.secret, raw);
+  assert.equal(out.proof, crypto.createHmac('sha256', raw).update('relay|3456|77|n1').digest('hex'));
+});
+
+test('without gateway.secret there is no proof at all, and no fallback to admin.token', () => {
+  const d = dir('nofallback');
+  const out = inState(d, `return { secret: s.readGatewaySecret(), proof: s.relayProof('n1', { port: 3456, pid: 77 }) };`);
+  assert.deepEqual(out, { secret: null, proof: '' });
+});
+
+test('ensureGatewaySecret throws when it cannot write, and leaves no temporary file', () => {
+  const d = dir('throws');
+  fs.mkdirSync(path.join(d, 'gateway.secret'));
+  assert.throws(() => inState(d, 's.ensureGatewaySecret()'));
+  assert.deepEqual(fs.readdirSync(d).filter(f => f.endsWith('.tmp')), []);
+});
+
+test('the blindfold proof keeps its exact formula', async () => {
+  const s = await import(STATE);
+  const proof = s.identityProof('n2', { role: 'blindfold', port: 3457, pid: 9, gatewayPort: 3456, activeTools: 'codex' }, TOKEN);
+  assert.equal(proof, crypto.createHmac('sha256', TOKEN).update('blindfold|3457|9|3456|codex|n2').digest('hex'));
+});
+
+test('only state.mjs touches gateway.secret: no other module of the package can read or serve it', () => {
+  const files = [...fs.readdirSync(ROOT).filter(f => f.endsWith('.mjs')).map(f => path.join(ROOT, f)),
+    ...fs.readdirSync(path.join(ROOT, 'blindfold')).filter(f => f.endsWith('.mjs')).map(f => path.join(ROOT, 'blindfold', f))];
+  assert.ok(files.length > 10, 'the scan found the package modules');
+  for (const f of files) {
+    if (path.basename(f) === 'state.mjs') continue;
+    const src = fs.readFileSync(f, 'utf8');
+    for (const name of ['gateway.secret', 'readGatewaySecret', 'gatewaySecretPath']) {
+      assert.equal(src.includes(name), false, `${path.relative(ROOT, f)} mentions ${name}`);
+    }
+  }
+  const proxy = fs.readFileSync(path.join(ROOT, 'proxy.mjs'), 'utf8');
+  assert.match(proxy, /ensureGatewaySecret\(\);/, 'the gateway makes its secret at startup and keeps no copy');
+  assert.match(proxy, /relayProof\(/);
+});
+
+test('gateway.secret stays out of git and out of the npm package', () => {
+  assert.ok(fs.readFileSync(path.join(ROOT, '.gitignore'), 'utf8').split(/\r?\n/).includes('gateway.secret'));
+});
+
+test('the .cmd command line: cmd.exe switches, quoting and the 8191 limit', async () => {
+  const { batCommandLine, CMD_LIMIT } = await import(pathToFileURL(path.join(ROOT, 'agy-relay-lib.mjs')).href);
+  const ok = batCommandLine('C:\\a\\agy.cmd', ['x']);
+  assert.deepEqual(ok.args.slice(0, 4), ['/e:ON', '/v:OFF', '/d', '/c']);
+  assert.equal(batCommandLine('C:\\a\\agy.cmd', ['50%']).args[4].includes('50%%cd:~,%'), true);
+  assert.equal(CMD_LIMIT, 8191);
+  // The /c string is `"` + `"C:\a\agy.cmd"` + ` ` + the argument + `"`: 17 code units around it.
+  const room = CMD_LIMIT - '""C:\\a\\agy.cmd" "'.length;
+  assert.equal(batCommandLine('C:\\a\\agy.cmd', ['z'.repeat(room)]).args[4].length, CMD_LIMIT);
+  assert.ok(batCommandLine('C:\\a\\agy.cmd', ['z'.repeat(room + 1)]).error);
+  // Counted in UTF-16 code units, not bytes: é is one unit and two UTF-8 bytes.
+  assert.ok(batCommandLine('C:\\a\\agy.cmd', ['é'.repeat(room - 2)]).args, 'non-ASCII is not refused early');
+  assert.ok(batCommandLine('C:\\a\\agy".cmd', []).error);
+  assert.ok(batCommandLine('C:\\a\\', []).error);
+});

package/tests/shim.test.mjs

@@ -534,7 +534,9 @@ for (const [kind, routed] of [['forged', false], ['silent', false], ['real', tru
     const port = server.address().port;
     const { out, err, ms } = await runAgyWindowsShim(port);
     if (routed) {
-      assert.match(out, new RegExp(`CCU=\\[http://127\\.0\\.0\\.1:${port}\\]`));
+      // agy gets the port of its own relay, which proves the gateway on every connection.
+      const relayPort = Number((out.match(/CCU=\[http:\/\/127\.0\.0\.1:(\d+)\]/) || [])[1]);
+      assert.ok(relayPort > 0 && relayPort !== port, `agy must get the relay port, not ${port}: ${out}`);
       assert.doesNotMatch(err, NOTICE);
     } else {
       assert.match(out, /CCU=\[\]/, 'the token must not go to a port that did not prove itself');
@@ -562,7 +564,8 @@ for (const [kind, routed] of [['forged', false], ['silent', false], ['real', tru
     });
     fs.rmSync(dir, { recursive: true, force: true });
     if (routed) {
-      assert.match(out.stdout, new RegExp(`CCU=\\[http://127\\.0\\.0\\.1:${port}\\]`));
+      const relayPort = Number((out.stdout.match(/CCU=\[http:\/\/127\.0\.0\.1:(\d+)\]/) || [])[1]);
+      assert.ok(relayPort > 0 && relayPort !== port, `agy must get the relay port, not ${port}: ${out.stdout}`);
       assert.doesNotMatch(out.stderr, NOTICE);
     } else {
       assert.match(out.stdout, /CCU=\[\]/);

package/tests/switch.test.mjs

@@ -621,3 +621,22 @@ test('R7e: saves work again after the file is fixed', async (t) => {
   assert.equal(fixed.status, 0, fixed.stdout + fixed.stderr);
   assert.ok(readCfg(ws).profiles.plain, 'the file writes again');
 });
+
+// A second instance (LLM_SWITCHER_PORT) must never stop the service of the first one: the unit
+// runs the gateway of another port. This test once stopped the real gateway of the machine.
+test('switch off stops the installed service only when that service owns the port', { skip: process.platform !== 'linux' && 'a systemd fake' }, async (t) => {
+  const ws = await workspace(t, await freePort());
+  const unitDir = path.join(ws.home, '.config', 'systemd', 'user');
+  fs.mkdirSync(unitDir, { recursive: true });
+  fs.writeFileSync(path.join(unitDir, 'llm-switcher.service'), '[Service]\nExecStart=/usr/bin/node /opt/llm-switcher/proxy.mjs --port 3456\n');
+  // A systemctl that only records what it was told.
+  const bin = path.join(ws.dir, 'fakebin');
+  fs.mkdirSync(bin);
+  const calls = path.join(ws.dir, 'systemctl.log');
+  fs.writeFileSync(path.join(bin, 'systemctl'), `#!/bin/sh\necho "$@" >> "${calls}"\nexit 0\n`, { mode: 0o755 });
+  const env = { PATH: `${bin}${path.delimiter}${process.env.PATH}` };
+  assert.equal((await run(ws, ['on', 'plain'], { env })).status, 0);
+  assert.equal((await run(ws, ['off'], { env })).status, 0);
+  const log = fs.existsSync(calls) ? fs.readFileSync(calls, 'utf8') : '';
+  assert.doesNotMatch(log, /\b(stop|restart)\b/, `systemctl was told to stop the instance on port 3456:\n${log}`);
+});

package/tests/update.e2e.test.mjs

@@ -196,7 +196,8 @@ test('the dashboard Update now button installs the release and reloads on the ne
     await page.waitFor(`document.getElementById('app-version')?.textContent === 'v9.9.12'`, 'the reloaded dashboard on the new version', 30000);
   } catch (err) {
     // A CI runner cannot be watched: put what the gateway and the page saw into the failure.
-    err.message += `\ngateway log:\n${fx.log()}\npage problems: ${JSON.stringify(page.problems)}`;
+    const stage = await page.evaluate(`document.getElementById('update-status')?.textContent || ''`).catch(() => '(page gone)');
+    err.message += `\nupdate status on the page: ${stage}\ngateway log:\n${fx.log()}\npage problems: ${JSON.stringify(page.problems)}`;
     throw err;
   }
   assert.equal(await page.evaluate(`document.getElementById('update-notice').hidden`), true);