@chatpanel/bridge 0.2.12 → 0.2.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/bridge",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "type": "module",
   "description": "Local bridge that exposes the AI coding agents installed on your machine — Claude Code (CLI), Codex (CLI), and Gemini CLI — to the ChatPanel Chrome extension over a localhost SSE endpoint. Bring your own agent.",
   "keywords": [
@@ -37,6 +37,9 @@
     "build:bin": "bash scripts/build-binaries.sh"
   },
   "dependencies": {},
+  "optionalDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.1.0"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"

package/src/engines/claude.js

@@ -1,40 +1,54 @@
-// Claude Code engine — drives the Claude Code CLI (`claude --print`) directly,
-// the SAME way the Codex engine drives `codex exec`. No Agent SDK, no bundled
-// cli.js, no native `sharp` dependency — so it works in any environment that has
-// `claude` on PATH (npm install, native installer, or `npx`), and there's nothing
-// to resolve inside a compiled binary (the old "/$bunfs/root/cli.js" failure).
+// Claude Code engine — drives the Claude Code CLI (`claude --print`) the SAME
+// way the Codex engine drives `codex exec`, but with cross-platform launching so
+// it works no matter where `claude` lives:
 //
-// It uses your *local* Claude Code login. By default the agent can READ your code
-// (Read/Grep/Glob/WebFetch/…) but cannot write or run shell commands unless the
-// agent's permissionMode is 'acceptEdits' or 'bypassPermissions' in ChatPanel
-// Settings. The working directory comes from the agent config.
+//   • macOS / Linux / WSL-native Node — spawn the native `claude` on PATH.
+//   • Windows (native install) — run the package's cli.js with our own Node/Bun
+//     (npm's claude.cmd/.ps1 shims aren't directly spawnable → "spawn …ENOENT").
+//   • Windows host + claude only in WSL — cross the boundary via `wsl.exe`.
+//   • Last resort — the in-process Claude Agent SDK (bundled cli.js), if present.
+//
+// Resolution lives in env.js (resolveClaude); set CHATPANEL_CLAUDE_PATH to force
+// a specific executable. It uses your *local* Claude Code login. By default the
+// agent can READ your code but cannot write/run shell unless the agent's
+// permissionMode is 'acceptEdits'/'bypassPermissions' in ChatPanel Settings.
 
 import { spawn } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
-import { findAgentBin } from '../env.js';
+import { resolveClaude, toWslPath, isCompiledBinary } from '../env.js';
 
 const TIMEOUT_MS = Number(process.env.CHATPANEL_CLAUDE_TIMEOUT_MS) || 180_000;
 // Read-only tools allowed without approval in headless mode; writes/shell are
 // gated behind the agent's permission mode.
 const READONLY_TOOLS = ['Read', 'Grep', 'Glob', 'WebFetch', 'WebSearch', 'TodoWrite', 'Task'];
 
-let installed = false;
+let lastReason = 'Claude Code not found.';
 let lastProbe = 0;
+let cachedOk = false;
 export async function available() {
-  // Availability = "is claude findable on PATH" (mirrors the codex engine), NOT
-  // "does `claude --version` exit 0" (which fails when it just needs login).
-  if (!installed && Date.now() - lastProbe > 4000) {
+  // Availability = "can we launch claude somehow" (native / cli.js / WSL / SDK),
+  // NOT "does `claude --version` exit 0" (which fails when it just needs login).
+  if (!cachedOk && Date.now() - lastProbe > 4000) {
     lastProbe = Date.now();
     try {
-      installed = !!findAgentBin('claude');
+      const spec = resolveClaude();
+      if (spec) {
+        cachedOk = true;
+      } else if (!isCompiledBinary() && (await loadSdk())) {
+        cachedOk = true;
+      } else {
+        cachedOk = false;
+        lastReason =
+          process.platform === 'win32'
+            ? 'Claude Code not found on Windows PATH or in WSL. Install it (npm i -g @anthropic-ai/claude-code) and run `claude` once to log in — in Windows or in your WSL distro.'
+            : 'Claude Code not found on PATH. Install it (npm i -g @anthropic-ai/claude-code) and run `claude` once to log in.';
+      }
     } catch {
-      installed = false;
+      cachedOk = false;
     }
   }
-  return installed
-    ? { ok: true }
-    : { ok: false, reason: 'Claude Code not found on PATH. Install it (npm i -g @anthropic-ai/claude-code) and run `claude` once to log in.' };
+  return cachedOk ? { ok: true } : { ok: false, reason: lastReason };
 }
 
 // The bridge is stateless, so we replay the conversation as a single prompt.
@@ -51,15 +65,46 @@ function buildPrompt(messages) {
   return prompt;
 }
 
-// Spawn `claude` and stream its stream-json output, forwarding events via `emit`.
-// `extraArgs` lets complete() run a tool-free single shot. Resolves with the final
-// result text once the process closes 0.
+// Turn a launch spec + the claude CLI args into a concrete [bin, argv, options]
+// for spawn(). `cwd` is the resolved working dir (Windows path on win32), or null
+// to use the home directory.
+function buildSpawn(spec, args, cwd) {
+  if (spec.kind === 'wsl') {
+    // Run claude inside WSL's login shell so nvm/etc. PATH resolves it. The
+    // `'exec claude "$@"'` + 'chatpanel' ($0) trick passes our args through as a
+    // proper argv array — no manual quoting, even for multi-line system prompts.
+    const pre = [];
+    if (cwd) {
+      const wslCwd = toWslPath(cwd);
+      if (wslCwd) pre.push('--cd', wslCwd); // else: run in WSL home
+    }
+    const argv = [...pre, '-e', 'bash', '-lic', 'exec claude "$@"', 'chatpanel', ...args];
+    return ['wsl.exe', argv, { stdio: ['pipe', 'pipe', 'pipe'], env: process.env, windowsHide: true }];
+  }
+
+  const spawnCwd = cwd || os.homedir();
+  const opts = { cwd: spawnCwd, stdio: ['pipe', 'pipe', 'pipe'], env: process.env, windowsHide: true };
+  if (spec.kind === 'script') {
+    // Run cli.js with the interpreter already running the bridge (node/bun).
+    return [process.execPath, [spec.script, ...args], opts];
+  }
+  // kind === 'native' — direct executable (.exe / mac+linux binary), or a .cmd
+  // shim via the shell on Windows.
+  return [spec.bin, args, { ...opts, shell: !!spec.shell }];
+}
+
+// Spawn claude (however it resolves) and stream its stream-json output via
+// `emit`. Resolves with { streamedAny, resultText } once it closes 0. Returns
+// null (no spawn) when claude can't be resolved, so the caller can fall back.
 function runClaude({ prompt, args, cwd, emit }) {
-  const bin = findAgentBin('claude') || 'claude';
+  const spec = resolveClaude();
+  if (!spec) return null;
+  const [bin, argv, opts] = buildSpawn(spec, args, cwd);
+
   return new Promise((resolve, reject) => {
     let child;
     try {
-      child = spawn(bin, args, { cwd, stdio: ['pipe', 'pipe', 'pipe'], env: process.env });
+      child = spawn(bin, argv, opts);
     } catch (e) {
       return reject(new Error(`Failed to start claude: ${e.message}`));
     }
@@ -95,7 +140,7 @@ function runClaude({ prompt, args, cwd, emit }) {
     child.stderr.on('data', (d) => (stderr += d.toString()));
     child.on('error', (e) => {
       clearTimeout(timer);
-      reject(e);
+      reject(new Error(`Failed to start claude (${bin}): ${e.message}`));
     });
     child.on('close', (code) => {
       clearTimeout(timer);
@@ -140,7 +185,8 @@ function handleMessage(msg, emit, alreadyStreamed) {
 
 export async function chat({ messages, system, options }, emit) {
   const permissionMode = options.permissionMode || 'default';
-  const cwd = options.workingDir ? path.resolve(options.workingDir) : os.homedir();
+  // Explicit project dir, else null → CLI runs in home (or WSL home).
+  const cwd = options.workingDir ? path.resolve(options.workingDir) : null;
 
   const args = ['--print', '--output-format', 'stream-json', '--include-partial-messages', '--verbose'];
 
@@ -158,7 +204,9 @@ export async function chat({ messages, system, options }, emit) {
   // "Use my local skills & config" off → run clean.
   if (options.useLocalConfig === false) args.push('--setting-sources', '');
 
-  const { streamedAny, resultText } = await runClaude({ prompt: buildPrompt(messages), args, cwd, emit });
+  const run = runClaude({ prompt: buildPrompt(messages), args, cwd, emit });
+  if (run === null) return sdkChat({ messages, system, options }, emit); // no CLI → SDK
+  const { streamedAny, resultText } = await run;
   emit({ type: 'done', text: streamedAny ? '' : resultText });
 }
 
@@ -175,14 +223,16 @@ export async function complete({ prompt, system, model }) {
     '--system-prompt', system || "Continue the user's text briefly. Reply with only the continuation.",
   ];
   let text = '';
-  const { resultText } = await runClaude({
+  const run = runClaude({
     prompt,
     args,
-    cwd: os.homedir(),
+    cwd: null,
     emit: (e) => {
       if (e.type === 'delta') text += e.text;
     },
   });
+  if (run === null) return sdkComplete({ prompt, system, model }); // no CLI → SDK
+  const { resultText } = await run;
   return (text || resultText || '').trim();
 }
 
@@ -194,3 +244,82 @@ function toolSummary(block) {
   if (i.url) return i.url;
   return '';
 }
+
+// ---------------------------------------------------------------------------
+// Fallback: in-process Claude Agent SDK. Only reached when no native/WSL claude
+// CLI is resolvable (and we're not a compiled binary, where its bundled cli.js
+// is unreachable). The SDK ships its own cli.js and uses your ~/.claude login.
+
+let sdkPromise = null;
+function loadSdk() {
+  // Optional dependency — absent in lean/compiled installs; import().catch makes
+  // that a graceful "no fallback available" rather than a crash.
+  if (!sdkPromise) sdkPromise = import('@anthropic-ai/claude-agent-sdk').catch(() => null);
+  return sdkPromise;
+}
+
+async function sdkChat({ messages, system, options }, emit) {
+  const sdk = await loadSdk();
+  if (!sdk) throw new Error(lastReason);
+  const { query } = sdk;
+
+  const permissionMode = options.permissionMode || 'default';
+  const cwd = options.workingDir ? path.resolve(options.workingDir) : os.homedir();
+  const writesAllowed = permissionMode === 'acceptEdits' || permissionMode === 'bypassPermissions';
+  const readonly = new Set(READONLY_TOOLS);
+  const canUseTool = async (toolName) =>
+    readonly.has(toolName) || writesAllowed
+      ? { behavior: 'allow', updatedInput: undefined }
+      : { behavior: 'deny', message: `${toolName} blocked — set this agent's permission mode in ChatPanel to enable it.` };
+
+  let streamedAny = false;
+  let resultText = '';
+  const iterator = query({
+    prompt: buildPrompt(messages),
+    options: {
+      cwd,
+      permissionMode,
+      includePartialMessages: true,
+      canUseTool,
+      settingSources: options.useLocalConfig === false ? [] : ['user', 'project'],
+      systemPrompt: system
+        ? { type: 'preset', preset: 'claude_code', append: system }
+        : { type: 'preset', preset: 'claude_code' },
+      ...(options.model ? { model: options.model } : {}),
+      ...(process.env.CHATPANEL_MAX_TURNS ? { maxTurns: Number(process.env.CHATPANEL_MAX_TURNS) } : {}),
+    },
+  });
+  for await (const message of iterator) {
+    const r = handleMessage(message, emit, streamedAny);
+    if (r.streamed) streamedAny = true;
+    if (r.result != null) resultText = r.result;
+  }
+  emit({ type: 'done', text: streamedAny ? '' : resultText });
+}
+
+async function sdkComplete({ prompt, system, model }) {
+  const sdk = await loadSdk();
+  if (!sdk) throw new Error(lastReason);
+  const { query } = sdk;
+  let text = '';
+  const iterator = query({
+    prompt,
+    options: {
+      cwd: os.homedir(),
+      permissionMode: 'default',
+      allowedTools: [],
+      maxTurns: 1,
+      settingSources: [],
+      systemPrompt: system || "Continue the user's text briefly. Reply with only the continuation.",
+      model: model || 'haiku',
+    },
+  });
+  for await (const message of iterator) {
+    if (message.type === 'assistant') {
+      for (const block of message.message.content) if (block.type === 'text') text += block.text;
+    } else if (message.type === 'result' && message.subtype === 'success' && !text) {
+      text = message.result || '';
+    }
+  }
+  return text.trim();
+}

package/src/env.js

@@ -12,8 +12,9 @@ import { readdirSync, existsSync } from 'node:fs';
 
 let enriched = false;
 
-// The agent CLIs the bridge shells out to (Claude is the in-process SDK).
-const AGENT_CLIS = ['codex', 'gemini'];
+// The agent CLIs the bridge shells out to. Claude has its own richer resolution
+// (resolveClaude: native / cli.js / WSL / SDK) below.
+const AGENT_CLIS = ['codex', 'gemini', 'claude'];
 
 // Is `name` executable somewhere on the current PATH?
 function onPath(name) {
@@ -64,6 +65,125 @@ function shellWhich(name) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Claude Code launcher resolution.
+//
+// The Codex/Gemini engines can assume `spawn('codex', …)` runs a directly
+// executable file on the current OS's PATH. Claude needs more care:
+//   • On Windows, npm installs `claude.cmd` / `claude.ps1` / an extensionless
+//     bash shim — NONE of which Node's spawn() can execute directly (that's the
+//     "spawn C:\… ENOENT"). The runnable thing is the package's `cli.js`, which
+//     we run with our own Node/Bun.
+//   • A very common setup is "Windows host, `claude` only installed inside WSL."
+//     A Windows process can't see WSL's filesystem or PATH, so we cross the
+//     boundary explicitly via `wsl.exe`.
+// On macOS/Linux (and WSL-native Node) none of this applies: we return the same
+// native binary the old code spawned, so behavior there is unchanged.
+//
+// Returns one of:
+//   { kind: 'native', bin, shell }   → spawn(bin, args, { shell })
+//   { kind: 'script', script }       → spawn(process.execPath, [script, ...args])
+//   { kind: 'wsl' }                  → spawn('wsl.exe', [wsl prefix, ...args])
+//   null                             → not found (caller may fall back to SDK)
+export function resolveClaude() {
+  const override = process.env.CHATPANEL_CLAUDE_PATH;
+  if (override) {
+    const ext = path.extname(override).toLowerCase();
+    if (!isCompiledBinary() && /\.(c?js|mjs)$/.test(ext)) return { kind: 'script', script: override };
+    return { kind: 'native', bin: override, shell: process.platform === 'win32' && (ext === '.cmd' || ext === '.bat') };
+  }
+
+  if (process.platform === 'win32') {
+    const win = findClaudeWindows();
+    if (win) return win;
+    if (claudeInWsl()) return { kind: 'wsl' };
+    return null;
+  }
+
+  // macOS / Linux / WSL-native: same resolution the engine used before.
+  const bin = findAgentBin('claude');
+  return bin ? { kind: 'native', bin, shell: false } : null;
+}
+
+// Locate a runnable Claude Code on Windows. Prefer the package's cli.js (run
+// with our own Node/Bun — clean arg passing, no cmd.exe quoting), then a real
+// .exe, then a .cmd shim via the shell as a last resort.
+function findClaudeWindows() {
+  const dirs = (process.env.PATH || '').split(path.delimiter);
+  for (const d of dirs) {
+    if (!d) continue;
+    const hasShim = ['claude', 'claude.cmd', 'claude.exe', 'claude.ps1', 'claude.bat'].some((n) =>
+      existsSync(path.join(d, n)),
+    );
+    if (!hasShim) continue;
+    // Running cli.js with our own interpreter only works under a real Node/Bun,
+    // not inside a compiled single-file binary (which is not a JS interpreter).
+    if (!isCompiledBinary()) {
+      const js = claudeCliJs(d);
+      if (js) return { kind: 'script', script: js };
+    }
+    if (existsSync(path.join(d, 'claude.exe'))) return { kind: 'native', bin: path.join(d, 'claude.exe'), shell: false };
+    if (existsSync(path.join(d, 'claude.cmd'))) return { kind: 'native', bin: path.join(d, 'claude.cmd'), shell: true };
+    if (existsSync(path.join(d, 'claude.bat'))) return { kind: 'native', bin: path.join(d, 'claude.bat'), shell: true };
+  }
+  return null;
+}
+
+// The npm shim sits next to (or one level up from) the claude-code package.
+function claudeCliJs(dir) {
+  const rels = [
+    ['node_modules', '@anthropic-ai', 'claude-code', 'cli.js'],
+    ['..', 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js'],
+    ['..', 'lib', 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js'],
+  ];
+  for (const r of rels) {
+    const c = path.join(dir, ...r);
+    if (existsSync(c)) return c;
+  }
+  return null;
+}
+
+// Is `claude` reachable inside the default WSL distro's login shell? Cached;
+// re-probed (throttled) while not found so it self-heals once WSL/claude appear.
+let wslClaude = null;
+let wslProbe = 0;
+function claudeInWsl() {
+  if (wslClaude === null || (!wslClaude && Date.now() - wslProbe > 4000)) {
+    wslProbe = Date.now();
+    try {
+      const r = spawnSync('wsl.exe', ['-e', 'bash', '-lic', 'command -v claude'], {
+        encoding: 'utf8',
+        timeout: 8000,
+        windowsHide: true,
+      });
+      wslClaude = r.status === 0 && /\S/.test(stripBom(r.stdout || ''));
+    } catch {
+      wslClaude = false;
+    }
+  }
+  return wslClaude;
+}
+
+// Translate a Windows path to its WSL (/mnt/c/…) equivalent. Returns null on
+// failure so the caller can just run in WSL's home instead.
+export function toWslPath(winPath) {
+  try {
+    const r = spawnSync('wsl.exe', ['-e', 'wslpath', '-a', winPath], {
+      encoding: 'utf8',
+      timeout: 5000,
+      windowsHide: true,
+    });
+    const out = stripBom(r.stdout || '').trim();
+    return out.startsWith('/') ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+function stripBom(s) {
+  return s.replace(/^/, '').trim();
+}
+
 // Version managers install CLIs under versioned bin dirs that a lazy-loaded
 // shell (nvm/fnm) doesn't export into a non-interactive service PATH. Add them.
 function versionManagerBins(home) {

package/src/server.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 // ChatPanel Bridge — a tiny localhost server that exposes the coding agents
-// running on this machine (Claude Code via the Agent SDK, Codex and Gemini via
-// their CLIs) to the ChatPanel Chrome extension. Zero runtime dependencies
-// beyond the optional Claude Agent SDK.
+// running on this machine (Claude Code, Codex and Gemini, each via its CLI) to
+// the ChatPanel Chrome extension. Zero runtime dependencies.
 //
-//   GET  /health  → { ok, version, agents: [{id,label,available,reason}] }
+//   GET  /health  → { ok, version, agents: [...], update: {current,latest,…} }
+//   POST /update  → self-update to the latest release (compiled binary installs)
 //   POST /chat    → Server-Sent Events stream of { type, ... }:
 //                     {type:'delta', text}    incremental assistant text
 //                     {type:'tool',  name, summary}
@@ -19,10 +19,11 @@ import os from 'node:os';
 import * as claude from './engines/claude.js';
 import * as codex from './engines/codex.js';
 import * as gemini from './engines/gemini.js';
-import { installService, uninstallService, serviceStatus } from './service.js';
+import { installService, uninstallService, serviceStatus, restartService } from './service.js';
 import { enrichPath, findAgentBin } from './env.js';
+import { checkForUpdate, selfUpdate } from './update.js';
 
-const VERSION = '0.2.12';
+const VERSION = '0.2.13';
 const HOST = process.env.CHATPANEL_BRIDGE_HOST || '127.0.0.1';
 const PORT = Number(process.env.CHATPANEL_BRIDGE_PORT) || 4319;
 
@@ -81,7 +82,20 @@ async function handleHealth(res) {
       return { id, label, available: a.ok, reason: a.reason };
     }),
   );
-  json(res, 200, { ok: true, version: VERSION, agents });
+  const update = await checkForUpdate(VERSION).catch(() => ({ current: VERSION, updateAvailable: false }));
+  json(res, 200, { ok: true, version: VERSION, agents, update });
+}
+
+// POST /update — self-update (compiled-binary installs). Swaps the binary, replies,
+// then restarts the service into the new version. npm installs get instructions.
+async function handleUpdate(res) {
+  try {
+    const result = await selfUpdate(VERSION); // throws on npm install / no update / failure
+    json(res, 200, { ok: true, updated: true, from: result.from, to: result.to });
+    res.on('finish', () => setTimeout(() => restartService(), 400));
+  } catch (e) {
+    json(res, 400, { ok: false, error: String(e?.message || e) });
+  }
 }
 
 async function handleChat(req, res) {
@@ -187,6 +201,7 @@ const server = createServer(async (req, res) => {
     }
     if (req.method === 'POST' && url.pathname === '/chat') return handleChat(req, res);
     if (req.method === 'POST' && url.pathname === '/complete') return handleComplete(req, res);
+    if (req.method === 'POST' && url.pathname === '/update') return handleUpdate(res);
     json(res, 404, { error: 'Not found' });
   } catch (e) {
     json(res, 500, { error: e?.message || String(e) });
@@ -218,6 +233,7 @@ Usage:
   chatpanel-bridge --install    run automatically at login, in the background
   chatpanel-bridge --uninstall  remove the login auto-start
   chatpanel-bridge --status     show whether auto-start is set up
+  chatpanel-bridge --update     download & install the latest version, then restart
   chatpanel-bridge --version    print the version
 
 Env: CHATPANEL_BRIDGE_HOST, CHATPANEL_BRIDGE_PORT`);
@@ -269,4 +285,17 @@ function runCli() {
   return false;
 }
 
-if (!runCli()) startServer();
+if (process.argv.includes('--update')) {
+  (async () => {
+    try {
+      const r = await selfUpdate(VERSION);
+      log('info', `Updated v${r.from} → v${r.to}. Restarting the background service…`);
+      restartService();
+    } catch (e) {
+      log('error', 'Update failed: ' + (e?.message || e));
+      process.exitCode = 1;
+    }
+  })();
+} else if (!runCli()) {
+  startServer();
+}

package/src/service.js

@@ -12,7 +12,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 
 const LABEL = 'net.chatpanel.bridge';
 const DISPLAY = 'ChatPanel Bridge';
@@ -157,3 +157,37 @@ export function uninstallService() {
 export function serviceStatus() {
   return byPlatform(macStatus, winStatus, linStatus);
 }
+
+// Restart the installed service into a freshly-swapped binary (used by self-
+// update). Detached so it survives the restart killing the caller — works whether
+// invoked from inside the service (POST /update) or a CLI `--update`.
+//   • macOS  — `launchctl kickstart -k` kills + relaunches the LaunchAgent.
+//   • Linux  — `systemctl --user restart`.
+//   • Windows — kill the running bridge, wait ~2s (port frees), relaunch via the
+//               hidden VBS, then delete the renamed old-*.exe.
+export function restartService() {
+  try {
+    if (process.platform === 'darwin') {
+      const uid = typeof process.getuid === 'function' ? process.getuid() : 0;
+      spawn('launchctl', ['kickstart', '-k', `gui/${uid}/${LABEL}`], { detached: true, stdio: 'ignore' }).unref();
+      return true;
+    }
+    if (process.platform === 'linux') {
+      spawn('systemctl', ['--user', 'restart', 'chatpanel-bridge'], { detached: true, stdio: 'ignore' }).unref();
+      return true;
+    }
+    if (process.platform === 'win32') {
+      const vbs = winVbs();
+      const dir = path.dirname(process.execPath);
+      const cmd =
+        `taskkill /IM chatpanel-bridge.exe /F >nul 2>&1 & ` +
+        `timeout /t 2 >nul & wscript.exe "${vbs}" & ` +
+        `del /q "${path.join(dir, 'chatpanel-bridge.old-*.exe')}" >nul 2>&1`;
+      spawn('cmd', ['/c', cmd], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+      return true;
+    }
+  } catch {
+    /* fall through */
+  }
+  return false;
+}

package/src/update.js

@@ -0,0 +1,154 @@
+// In-app updater for the standalone binary.
+//
+// The bridge is a background service the user never opens, so the EXTENSION
+// surfaces "update available" (from /health) and offers a one-click Update that
+// calls POST /update. The bridge downloads the new binary, swaps it in, and the
+// service relaunches into the new version.
+//
+// Cross-platform swap + relaunch (users come from anywhere):
+//   • macOS  — atomic rename over the running file; KeepAlive relaunches on exit.
+//   • Linux  — atomic rename; `systemctl --user restart` relaunches.
+//   • Windows — can't overwrite a running .exe, so we RENAME the running exe aside
+//               and drop the new one in its place, then a detached helper waits for
+//               this process to exit (freeing the port) and relaunches it.
+//
+// No-ops for npx/node installs — npm owns those; only compiled binaries self-update.
+
+import os from 'node:os';
+import path from 'node:path';
+import { chmod, rename, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { isCompiledBinary } from './env.js';
+
+const REPO = 'chatpanel/chatpanel-bridge';
+const LATEST_API = `https://api.github.com/repos/${REPO}/releases/latest`;
+const CHECK_EVERY_MS = 6 * 60 * 60 * 1000; // 6h
+const CACHE = path.join(os.homedir(), '.chatpanel', 'update-check.json');
+const UA = { 'User-Agent': 'chatpanel-bridge-updater' };
+
+// Release asset name for THIS platform (matches release-binaries.yml outputs).
+// macOS publishes arm64 only; Intel Macs use `npx` (managed → no self-update).
+function assetName() {
+  if (process.platform === 'darwin') return process.arch === 'arm64' ? 'chatpanel-bridge-macos-arm64' : null;
+  if (process.platform === 'linux') return 'chatpanel-bridge-linux-x64';
+  if (process.platform === 'win32') return 'chatpanel-bridge-windows-x64.exe';
+  return null;
+}
+
+function parseVersion(s = '') {
+  const m = /(\d+(?:\.\d+){0,3})/.exec(s || '');
+  return m ? m[1] : null;
+}
+// >0 if a is newer than b.
+function cmp(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+async function readCache() {
+  try {
+    return JSON.parse(await readFile(CACHE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+async function writeCache(obj) {
+  try {
+    await mkdir(path.dirname(CACHE), { recursive: true });
+    await writeFile(CACHE, JSON.stringify(obj));
+  } catch {
+    /* best effort */
+  }
+}
+
+// Returns { current, latest, updateAvailable, mode, canSelfUpdate, assetUrl, npmCommand }.
+//   mode 'binary' → compiled standalone build (macOS/Linux curl install, or the
+//                   optional Windows .exe). POST /update self-replaces in place.
+//   mode 'npm'    → npx/node install (the default on Windows). The bridge can't
+//                   swap its own files; the extension shows `npmCommand` instead.
+// Both report updateAvailable so the user always gets the notice — only the action
+// differs. Throttled to CHECK_EVERY_MS unless `force`.
+export async function checkForUpdate(current, { force = false } = {}) {
+  const mode = isCompiledBinary() ? 'binary' : 'npm';
+  const want = assetName();
+
+  let latest = null;
+  let assetUrl = null;
+  const cache = await readCache();
+  if (!force && cache && Date.now() - cache.checkedAt < CHECK_EVERY_MS) {
+    latest = cache.latest;
+    assetUrl = cache.assetUrl;
+  } else {
+    try {
+      const res = await fetch(LATEST_API, { headers: { Accept: 'application/vnd.github+json', ...UA } });
+      if (res.ok) {
+        const data = await res.json();
+        latest = parseVersion(data.tag_name) || parseVersion(data.name);
+        assetUrl = want ? (data.assets || []).find((a) => a.name === want)?.browser_download_url || null : null;
+        await writeCache({ checkedAt: Date.now(), latest, assetUrl });
+      } else {
+        latest = cache?.latest || null;
+        assetUrl = cache?.assetUrl || null;
+      }
+    } catch {
+      latest = cache?.latest || null;
+      assetUrl = cache?.assetUrl || null;
+    }
+  }
+  const updateAvailable = !!latest && cmp(latest, current) > 0;
+  // One-click in-place update is only possible for a compiled binary with a
+  // matching release asset; npm installs update via the command.
+  const canSelfUpdate = mode === 'binary' && !!assetUrl;
+  return {
+    current,
+    latest,
+    updateAvailable,
+    mode,
+    canSelfUpdate,
+    assetUrl,
+    npmCommand: mode === 'npm' ? 'npm i -g @chatpanel/bridge@latest' : null,
+  };
+}
+
+// Download the latest binary and swap it in. Does NOT restart — the caller sends
+// its HTTP response first, then triggers restartService(). Throws on any failure,
+// leaving the running binary untouched.
+export async function selfUpdate(current) {
+  if (!isCompiledBinary()) {
+    throw new Error('Self-update applies only to the standalone binary. Update the npm/npx version with npm.');
+  }
+  const info = await checkForUpdate(current, { force: true });
+  if (!info.assetUrl) throw new Error('No downloadable build for this platform — use `npx @chatpanel/bridge`.');
+  if (!info.updateAvailable) {
+    throw new Error(info.latest ? `Already on the latest version (v${current}).` : 'Could not reach the update server.');
+  }
+
+  const target = process.execPath; // the running binary's own path
+  const dir = path.dirname(target);
+  const tmp = path.join(dir, `.chatpanel-bridge.new-${Date.now()}`);
+
+  const res = await fetch(info.assetUrl, { headers: UA });
+  if (!res.ok || !res.body) throw new Error(`Download failed (${res.status}).`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  if (buf.length < 1_000_000) throw new Error('Downloaded file looks too small — aborting to avoid a broken bridge.');
+
+  await writeFile(tmp, buf);
+  if (process.platform !== 'win32') await chmod(tmp, 0o755);
+
+  if (process.platform === 'win32') {
+    // A running .exe can't be overwritten, but it CAN be renamed. Move it aside,
+    // drop the new one in place; the old (renamed) file is cleaned up after exit.
+    const aside = path.join(dir, `chatpanel-bridge.old-${Date.now()}.exe`);
+    await rename(target, aside);
+    await rename(tmp, target);
+  } else {
+    // POSIX: atomic rename over the running file. The live process keeps the old
+    // inode; the path now points at the new binary.
+    await rename(tmp, target);
+  }
+  return { ok: true, from: current, to: info.latest };
+}