@chatpanel/bridge 0.10.23 → 0.10.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/bridge",
-  "version": "0.10.23",
+  "version": "0.10.26",
   "type": "module",
   "description": "Local bridge that exposes the AI coding agents installed on your machine \u2014 Claude Code (CLI), Codex (CLI), and Antigravity CLI (formerly Gemini CLI, which remains available for business/enterprise) \u2014 to the ChatPanel Chrome extension over a localhost SSE endpoint. Bring your own agent.",
   "keywords": [

package/src/connectors.js

@@ -0,0 +1,100 @@
+// What an agent can already reach, read from its own configuration.
+//
+// A CLI agent brings connectors ChatPanel cannot see: a Slack MCP, a Jira MCP, a filesystem.
+// ChatPanel relays its own tools to that agent and says a great deal about them — all of it
+// restrictive, because each line was written to stop one substitution — so an agent asked
+// about an internal thread read the page, saw the reference, and told the user to go and look
+// it up, while holding a connector that reaches it.
+//
+// Knowing the names turns a guess into a fact. It lets the harness say "you have slack
+// connected — use it" instead of listing connectors the agent may not have, and lets routing
+// treat "can reach Slack" as a capability rather than a hope.
+//
+// NAMES ONLY, AND NEVER THE CREDENTIALS. A server's name is what the agent already knows and
+// what a prompt needs; its URL, argv and env are what a leak would be made of. This reads
+// config files that belong to the user's own agents and returns a list of strings.
+//
+// CONFIGURED, NOT PROVEN. A server listed here may still fail to start. That is honest and
+// useful — it is exactly what the agent itself will try — and probing for real would cost a
+// process spawn per agent on every health poll.
+
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+/** Read a file and parse it as JSON, or null. Missing and malformed are the same answer. */
+async function readJson(file) {
+  try { return JSON.parse(await readFile(file, 'utf8')); } catch { return null; }
+}
+
+/** Every key of a `{ mcpServers: { name: {...} } }` block, wherever it appears. */
+function fromMcpServers(obj) {
+  const m = obj && typeof obj === 'object' ? obj.mcpServers || obj.mcp_servers : null;
+  return m && typeof m === 'object' ? Object.keys(m) : [];
+}
+
+/**
+ * `[mcp_servers.NAME]` table headers out of a TOML file.
+ *
+ * Deliberately a regex rather than a TOML parser: the bridge is zero-runtime-dependency by
+ * design, and the only thing wanted here is the set of table names. Anything this misses
+ * simply is not reported, which is the safe direction — a missing name costs a sentence in a
+ * prompt, an invented one sends an agent looking for a connector it does not have.
+ */
+function fromToml(text) {
+  const out = [];
+  const re = /^\s*\[\s*mcp_servers\s*\.\s*([A-Za-z0-9._-]+)\s*\]/gm;
+  for (const m of String(text || '').matchAll(re)) out.push(m[1]);
+  return out;
+}
+
+async function readToml(file) {
+  try { return fromToml(await readFile(file, 'utf8')); } catch { return []; }
+}
+
+const home = () => os.homedir();
+const configHome = () => process.env.XDG_CONFIG_HOME || path.join(home(), '.config');
+
+// Where each agent keeps the list. One entry per agent id in the /health registry; an agent
+// with no entry simply reports nothing, which is what an unknown agent should do.
+const SOURCES = {
+  claude: async () => {
+    const [main, project] = await Promise.all([
+      readJson(path.join(home(), '.claude.json')),
+      readJson(path.join(process.cwd(), '.mcp.json')),
+    ]);
+    return [...fromMcpServers(main), ...fromMcpServers(project)];
+  },
+  codex: async () => readToml(path.join(process.env.CODEX_HOME || path.join(home(), '.codex'), 'config.toml')),
+  opencode: async () => {
+    for (const f of [
+      path.join(configHome(), 'opencode', 'opencode.json'),
+      path.join(home(), 'Library', 'Application Support', 'opencode', 'opencode.jsonc'),
+    ]) {
+      const j = await readJson(f);
+      const names = [...fromMcpServers(j), ...(j && j.mcp && typeof j.mcp === 'object' ? Object.keys(j.mcp) : [])];
+      if (names.length) return names;
+    }
+    return [];
+  },
+};
+
+/**
+ * The connector names an agent is configured with — deduped, sorted, and bounded.
+ *
+ * Bounded because this rides in a health response and then into a system prompt: a user with
+ * forty servers should cost a line, not a paragraph. Sorted so the value is stable across
+ * polls and a settings page does not reorder itself.
+ */
+export async function connectorsFor(agentId, { max = 24 } = {}) {
+  const read = SOURCES[agentId];
+  if (!read) return [];
+  try {
+    const names = await read();
+    return [...new Set(names.filter((n) => typeof n === 'string' && n && n.length <= 64))].sort().slice(0, max);
+  } catch {
+    // A config we cannot read is a config we say nothing about. Never a reason to fail a
+    // health check the extension needs in order to show the agent at all.
+    return [];
+  }
+}

package/src/engines/antigravity.js

@@ -16,7 +16,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { findAgentBin } from '../env.js';
 import { buildCliPrompt } from './prompt.js';
-import { killOnAbort } from '../proc.js';
+import { killOnAbort, spawnGroupOpts } from '../proc.js';
 import { pushExtraArgs, FORBIDDEN } from './args.js';
 
 const IDLE_MS = Number(process.env.CHATPANEL_AGY_TIMEOUT_MS) || 180_000;
@@ -110,7 +110,7 @@ export async function chat({ messages, system, options, images }, emit, { signal
   await new Promise((resolve, reject) => {
     let child;
     try {
-      child = spawn('agy', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env } });
+      child = spawn('agy', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env }, ...spawnGroupOpts });
     } catch (e) {
       cleanup();
       return reject(new Error(`Failed to start agy: ${e.message}`));

package/src/engines/codex.js

@@ -15,7 +15,7 @@
 // the agent to point it at a real project.
 
 import { spawn, spawnSync } from 'node:child_process';
-import { killOnAbort } from '../proc.js';
+import { killOnAbort, spawnGroupOpts } from '../proc.js';
 import { readFile, unlink, writeFile } from 'node:fs/promises';
 import { existsSync, mkdirSync, symlinkSync, readFileSync } from 'node:fs';
 import os from 'node:os';
@@ -180,7 +180,7 @@ export async function chat({ messages, system, options, images }, emit, { signal
   await new Promise((resolve, reject) => {
     let child;
     try {
-      child = spawn('codex', args, { cwd, stdio: ['pipe', 'pipe', 'pipe'], env });
+      child = spawn('codex', args, { cwd, stdio: ['pipe', 'pipe', 'pipe'], env, ...spawnGroupOpts });
     } catch (e) {
       cleanupImages();
       return reject(new Error(`Failed to start codex: ${e.message}`));

package/src/env.js

@@ -6,11 +6,13 @@
 // by (1) asking your login shell for its PATH and (2) adding common bin dirs.
 
 import os from 'node:os';
+import { spawnGroupOpts } from './proc.js';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { readdirSync, readFileSync, existsSync } from 'node:fs';
 
 let enriched = false;
+let envEnriched = false;
 
 // The agent CLIs the bridge shells out to. Claude has its own richer resolution
 // (resolveClaude: native / cli.js / WSL / SDK) below.
@@ -235,9 +237,15 @@ export function buildSpawnSpec(spec, args, cwd) {
       if (wslCwd) pre.push('--cd', wslCwd); // else: run in WSL home
     }
     const argv = [...pre, '-e', 'bash', '-lic', `exec ${spec.command} "$@"`, 'chatpanel', ...args];
-    return ['wsl.exe', argv, { stdio: ['pipe', 'pipe', 'pipe'], env: process.env, windowsHide: true }];
+    return ['wsl.exe', argv, { stdio: ['pipe', 'pipe', 'pipe'], env: process.env, windowsHide: true, ...spawnGroupOpts }];
   }
-  const opts = { cwd: cwd || os.homedir(), stdio: ['pipe', 'pipe', 'pipe'], env: process.env, windowsHide: true };
+  // Every spawned CLI leads its own process group, so Stop can signal the whole tree. An
+  // agent CLI is not one process — it runs shell commands and tools of its own — and killing
+  // only the pid we hold leaves those running after the user has stopped the turn.
+  const opts = {
+    cwd: cwd || os.homedir(), stdio: ['pipe', 'pipe', 'pipe'], env: process.env, windowsHide: true,
+    ...spawnGroupOpts,
+  };
   if (spec.kind === 'script') return [process.execPath, [spec.script, ...args], opts];
   if (spec.kind === 'cmd') return ['cmd.exe', ['/d', '/s', '/c', spec.bin, ...args], opts];
   return [spec.bin, args, opts]; // native
@@ -421,6 +429,64 @@ export function commandCandidateFiles(name, home = os.homedir(), platform = proc
   return unique([...fromDirs, ...agentCandidateBins(name, home, platform, env)]);
 }
 
+// Agent credentials a LaunchAgent/systemd unit does NOT inherit.
+//
+// enrichPath() repairs the minimal PATH a service gets; this is the same problem
+// one layer up. A CLI that authenticates from a FILE (claude, codex, copilot:
+// ~/.copilot) works fine under the service, but one that reads an API key from
+// the ENVIRONMENT (dsh -> DEEPSEEK_API_KEY) fails with a missing-credential
+// error that looks like a ChatPanel bug — the launchd job's environment is just
+// SSH_AUTH_SOCK and a bare PATH.
+//
+// So: ask the user's login shell for a NARROW allowlist of agent credential
+// variables and fill in only the ones we don't already have. These are the
+// user's own credentials, on their own machine, handed to CLIs the user
+// configured ChatPanel to launch — exactly what would happen had they run the
+// CLI from their terminal. Values are never logged, and /debug never dumps the
+// environment (it exposes only PATH/home, and only under CHATPANEL_BRIDGE_DEBUG).
+const AGENT_ENV_KEYS = [
+  'DEEPSEEK_API_KEY', 'DSH_HOME',
+  'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_BASE_URL',
+  'OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENAI_API_BASE',
+  'GEMINI_API_KEY', 'GOOGLE_API_KEY',
+  'OPENROUTER_API_KEY', 'GROQ_API_KEY', 'XAI_API_KEY', 'MISTRAL_API_KEY',
+];
+
+export function enrichAgentEnv() {
+  if (envEnriched) return;
+  envEnriched = true;
+  if (process.platform === 'win32') return; // service env is inherited there
+
+  const missing = AGENT_ENV_KEYS.filter((k) => !process.env[k]);
+  if (!missing.length) return;
+  try {
+    const shell = process.env.SHELL || '/bin/zsh';
+    // Emit NAME\tVALUE for each var that is actually set; trailing `true` keeps
+    // the exit status clean when the last test fails.
+    const script = `${missing
+      .map((k) => `[ -n "\${${k}:-}" ] && printf '%s\\t%s\\n' ${k} "\$${k}"`)
+      .join('; ')}; true`;
+    // -lic, not -lc: these keys are typically exported from ~/.zshrc (or ~/.bashrc),
+    // which a LOGIN-only shell does NOT source — that's interactive-only. TERM=dumb
+    // keeps prompt/banner noise down, and the parser below ignores any line that
+    // isn't a clean NAME<TAB>VALUE, so rc-file chatter is harmless.
+    const r = spawnSync(shell, ['-lic', script], {
+      encoding: 'utf8',
+      timeout: 6000,
+      env: { ...process.env, TERM: 'dumb' },
+    });
+    for (const line of String(r.stdout || '').split('\n')) {
+      const i = line.indexOf('\t');
+      if (i <= 0) continue;
+      const key = line.slice(0, i).trim();
+      const value = line.slice(i + 1);
+      if (AGENT_ENV_KEYS.includes(key) && !process.env[key] && value) process.env[key] = value;
+    }
+  } catch {
+    /* no login shell / timeout — agents that need a file-based login still work */
+  }
+}
+
 export function enrichPath() {
   if (enriched) return;
   enriched = true;

package/src/proc.js

@@ -1,18 +1,88 @@
+import { execFileSync } from 'node:child_process';
 // Terminate a spawned CLI child when an AbortSignal fires. The extension's Stop
 // button aborts the /chat request; server.js turns that disconnect into an abort on
 // this signal. Without this, the agent CLI (codex / claude / agy / custom) keeps
 // running to completion in the background after Stop — burning tokens and holding the
 // session — and only the 3-minute idle timer would eventually reap it.
 //
-// SIGTERM first so the CLI can flush + exit cleanly (its own child procs get the
-// signal via the process group where the platform delivers it), then SIGKILL after a
-// short grace if it's still alive. Returns a detach() to drop the listener once the
-// child exits normally.
+// SIGTERM first so the CLI can flush + exit cleanly, then SIGKILL after a short grace if
+// it's still alive. Returns a detach() to drop the listener once the child exits normally.
+//
+// THE SIGNAL MUST REACH THE GRANDCHILDREN. An agent CLI is not one process: codex runs shell
+// commands, claude runs tools, and each of those is a child of the child. `child.kill()`
+// signals exactly one pid, so Stop killed the CLI and left its shell running — a user pressed
+// Stop, watched the panel go quiet, and found the process still going.
+//
+// Signalling the process GROUP fixes that, and only works if the child leads a group of its
+// own — which is what spawnGroupOpts is for. Without that spawn option the child sits in the
+// bridge's own group, and a group kill would signal the bridge.
+
+/**
+ * Spawn options that make a child its own process-group leader, so the whole tree can be
+ * signalled together. No-op on Windows, which has no process groups in this sense — there
+ * the taskkill fallback in killTree covers it.
+ */
+export const spawnGroupOpts = process.platform === 'win32' ? {} : { detached: true };
+
+/**
+ * Every pid descended from `pid`, snapshotted from the process table.
+ *
+ * A process-group kill is not enough on its own. codex runs each shell step in its OWN
+ * process group (`sleep 90` came back with PGID == its own pid), so signalling the group we
+ * created deliberately misses it — and once its parent dies it reparents to init, where
+ * nothing connects it to the run that started it.
+ *
+ * So the tree is read BEFORE anything is signalled. Afterwards the links are gone.
+ */
+function descendantsOf(pid) {
+  if (!pid || process.platform === 'win32') return [];
+  let table = '';
+  try {
+    table = execFileSync('ps', ['-eo', 'pid=,ppid='], { encoding: 'utf8', timeout: 2000 });
+  } catch { return []; }
+  const kids = new Map();
+  for (const line of table.split('\n')) {
+    const [p, pp] = line.trim().split(/\s+/).map(Number);
+    if (!p || !pp) continue;
+    if (!kids.has(pp)) kids.set(pp, []);
+    kids.get(pp).push(p);
+  }
+  const out = [];
+  const walk = (root, depth = 0) => {
+    // A depth cap rather than a visited set: the table is a snapshot of a tree, and a cycle
+    // would mean the kernel lied. The cap is there so a malformed read cannot hang a Stop.
+    if (depth > 20) return;
+    for (const k of kids.get(root) || []) { out.push(k); walk(k, depth + 1); }
+  };
+  walk(pid);
+  return out;
+}
+
+/** Signal a child and everything it spawned. Falls back to the single process. */
+function killTree(child, sig, known = []) {
+  if (!child?.pid) return;
+  // Descendants first, while the parent is still alive to be traced through. Orphaned
+  // grandchildren are the ones the user cannot find or stop afterwards.
+  for (const pid of known.length ? known : descendantsOf(child.pid)) {
+    try { process.kill(pid, sig); } catch { /* already gone */ }
+  }
+  try {
+    // Negative pid = the whole group. Only valid for a detached child; the catch covers a
+    // child spawned without it, which is still better killed alone than not at all.
+    process.kill(-child.pid, sig);
+    return;
+  } catch { /* not a group leader, or already gone */ }
+  try { child.kill(sig); } catch { /* already exited */ }
+}
+
 export function killOnAbort(child, signal, { graceMs = 1500 } = {}) {
   if (!signal || !child) return () => {};
   const onAbort = () => {
-    try { child.kill('SIGTERM'); } catch { /* already exited */ }
-    const t = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ } }, graceMs);
+    // Snapshot ONCE, up front: by the time the grace period expires the parent is gone and
+    // the tree cannot be walked, so the escalation would have nothing left to aim at.
+    const tree = descendantsOf(child.pid);
+    killTree(child, 'SIGTERM', tree);
+    const t = setTimeout(() => killTree(child, 'SIGKILL', tree), graceMs);
     if (t.unref) t.unref(); // don't keep the event loop alive just for the grace timer
   };
   if (signal.aborted) { onAbort(); return () => {}; }

package/src/runs.js

@@ -0,0 +1,49 @@
+// Every in-flight run, so Stop is an INSTRUCTION rather than an inference.
+//
+// Cancellation used to depend on Node noticing the client's socket close and firing
+// `req.on('close')`. That is a signal about a socket, not about intent: it can arrive late,
+// and on a request whose body was already consumed it does not reliably arrive at all — so
+// a codex `shell:` step ran on for minutes after Stop with nothing left listening to it.
+//
+// A run registered here can be cancelled by name. The socket-close path stays as a safety
+// net for a panel that is closed or crashes, but the button no longer depends on it.
+const runs = new Map();
+
+export function startRun(id) {
+  const ac = new AbortController();
+  const children = new Set();
+  const run = {
+    id,
+    signal: ac.signal,
+    // Children are tracked as well as signalled, because an agent that spawns sub-agents
+    // spawns processes this module never sees at spawn time. Whoever creates one registers
+    // it, and Stop reaches all of them.
+    track(child) { if (child?.pid) { children.add(child); child.once?.('exit', () => children.delete(child)); } },
+    cancel(reason = 'stopped') {
+      if (run.cancelled) return false;
+      run.cancelled = reason;
+      ac.abort();
+      return true;
+    },
+    cancelled: null,
+    children,
+  };
+  runs.set(id, run);
+  return run;
+}
+
+export function endRun(id) { runs.delete(id); }
+
+export function cancelRun(id, reason = 'stopped') {
+  const run = runs.get(id);
+  return run ? run.cancel(reason) : false;
+}
+
+/** Used on shutdown: leaving a CLI running after the bridge exits is how orphans are made. */
+export function cancelAll(reason = 'shutdown') {
+  let n = 0;
+  for (const run of runs.values()) if (run.cancel(reason)) n += 1;
+  return n;
+}
+
+export const activeRuns = () => runs.size;

package/src/server.js

@@ -3,7 +3,7 @@
 // running on this machine (Claude Code, Codex and Antigravity, each via its CLI) to
 // the ChatPanel Chrome extension. Zero runtime dependencies.
 //
-//   GET  /health  → { ok, version, agents: [...], update: {current,latest,…} }
+//   GET  /health  → { ok, version, agents: [{id,label,available,reason,connectors}], update }
 //   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
@@ -27,18 +27,20 @@ import * as claude from './engines/claude.js';
 import * as codex from './engines/codex.js';
 import * as antigravity from './engines/antigravity.js';
 import { pi, opencode, kiro, copilot, deepseek } from './engines/cli-agents.js';
+import { connectorsFor } from './connectors.js';
 import * as custom from './engines/custom.js';
 import { installService, uninstallService, serviceStatus, restartService } from './service.js';
-import { AGENT_CLIS, enrichPath, findAgentBin, resolveCommand } from './env.js';
+import { AGENT_CLIS, enrichPath, enrichAgentEnv, findAgentBin, resolveCommand } from './env.js';
 import { stripHidden } from './sanitize.js';
 import { checkForUpdate, selfUpdate } from './update.js';
 import { callLocalMcp } from './mcp-local.js';
 import { assertPublicHttpUrl, assertPublicWebUrl } from './ssrf.js';
+import { startRun, endRun, cancelRun, cancelAll, activeRuns } from './runs.js';
 
 // Hardcoded (not read from package.json) so it survives Bun's single-file
 // --compile, where package.json isn't on a readable FS. CI fails the publish if
 // this drifts from package.json, so the two can't silently diverge.
-const VERSION = '0.10.23';
+const VERSION = '0.10.26';
 const HOST = process.env.CHATPANEL_BRIDGE_HOST || '127.0.0.1';
 const PORT = Number(process.env.CHATPANEL_BRIDGE_PORT) || 4319;
 
@@ -238,6 +240,10 @@ const PRIVILEGED_POST = new Set([
   '/agent-check',
   '/update',
   '/tool-result',
+  // Cancelling someone else's run is a denial of service, small but real — and every other
+  // endpoint that touches a run is already guarded. An unauthenticated hole next to nine
+  // guarded neighbours is a hole regardless of how little it grants.
+  '/cancel',
 ]);
 const PRIVILEGED_GET = new Set(['/debug']);
 
@@ -294,7 +300,13 @@ async function handleHealth(res) {
       .filter(([, e]) => !e.hidden)
       .map(async ([id, { engine, label }]) => {
         const a = await engine.available().catch((e) => ({ ok: false, reason: String(e?.message || e) }));
-        return { id, label, available: a.ok, reason: a.reason };
+        // WHAT THIS AGENT CAN ALREADY REACH, so the client stops guessing. A CLI agent brings
+        // its own connectors — a Slack MCP, a Jira MCP — that the extension cannot see, and
+        // an agent that was never told it may use them answers "go and look it up yourself".
+        // NAMES ONLY: a server's name is what a prompt needs; its URL, argv and env are what
+        // a leak would be made of. Additive, so an older extension ignores it.
+        const connectors = await connectorsFor(id).catch(() => []);
+        return { id, label, available: a.ok, reason: a.reason, connectors };
       }),
   );
   const update = await checkForUpdate(VERSION).catch(() => ({ current: VERSION, updateAvailable: false }));
@@ -341,10 +353,22 @@ async function handleChat(req, res) {
   // finish in the background. Older engines ignore the signal (harmless); the spawn
   // engines honor it via killOnAbort.
   let closed = false;
-  const ac = new AbortController();
-  req.on('close', () => { closed = true; ac.abort(); });
+  // A run id the client can cancel BY NAME. Emitted first, before anything else, so Stop
+  // works from the first millisecond rather than from whenever the engine gets going.
+  const runId = `run_${Math.random().toString(36).slice(2, 10)}`;
+  const run = startRun(runId);
+  const ac = { signal: run.signal, abort: () => run.cancel('client') };
+  // BOTH close events. On a request whose body was already consumed, req 'close' does not
+  // reliably signal a client disconnect — res 'close' does. Keeping both means a panel that
+  // crashes or is closed still tears the CLI down, while the Stop button no longer depends
+  // on either of them.
+  const onGone = () => { closed = true; run.cancel('disconnected'); };
+  req.on('close', onGone);
+  res.on('close', onGone);
+  res.on('error', onGone);
 
   const safeEmit = (obj) => { if (!closed) emit(obj); };
+  emit({ type: 'run', id: runId });
 
   // Browser-tools relay: when the extension sends page-tool specs, host an MCP
   // server for this turn and tell the engine to point the CLI at it.
@@ -374,11 +398,31 @@ async function handleChat(req, res) {
     log('error', `${body.agent} chat failed: ${e?.message || e}`);
     emit({ type: 'error', error: e?.message || String(e) });
   } finally {
+    endRun(runId);
     if (session) deleteSession(session.id);
     if (!res.writableEnded) res.end();
   }
 }
 
+/**
+ * POST /cancel { id } — stop a run by name.
+ *
+ * Stop is now an instruction, not something inferred from a socket. Answers 200 whether or
+ * not the run was still live: 'already finished' and 'cancelled' are the same outcome to the
+ * caller, and returning 404 would make a harmless race look like a failure.
+ */
+async function handleCancel(req, res) {
+  // readBody already PARSES. Wrapping it in JSON.parse threw on every call, so the id was
+  // always empty and Stop silently cancelled nothing — the unit tests covered the registry
+  // and not the handler that feeds it, which is exactly where this hid.
+  let body = {};
+  try { body = (await readBody(req)) || {}; } catch { /* an empty body cancels nothing */ }
+  const id = String(body.id || '').trim();
+  const cancelled = id ? cancelRun(id, 'stopped') : false;
+  if (cancelled) log('info', `cancel: ${id} stopped by client`);
+  return json(res, 200, { ok: true, cancelled });
+}
+
 // POST /mcp/<session> (per-run, bridge-injected) OR POST /mcp (stable: routes to
 // the active chat — for CLIs configured once, e.g. `opencode mcp add … …/mcp`).
 // JSON-RPC; tools/call relays to the extension and waits for /tool-result.
@@ -754,6 +798,7 @@ const server = createServer(async (req, res) => {
       if (req.method === 'GET') { res.writeHead(405); return res.end(); } // no server-initiated stream
       if (req.method === 'DELETE') { deleteSession(sid); res.writeHead(204); return res.end(); }
     }
+    if (req.method === 'POST' && url.pathname === '/cancel') return handleCancel(req, res);
     if (req.method === 'POST' && url.pathname === '/tool-result') return handleToolResult(req, res);
     if (req.method === 'POST' && url.pathname === '/mcp-local') return handleMcpLocal(req, res);
     if (req.method === 'POST' && url.pathname === '/mcp-remote') return handleMcpRemote(req, res);
@@ -828,6 +873,7 @@ function runMcpStdioProxy(url) {
 
 function startServer() {
   enrichPath(); // so codex/agy (Antigravity) are found even under a minimal service PATH
+  enrichAgentEnv(); // and so env-authenticated CLIs (dsh) have their key under launchd
   ensureToken(); // per-install bearer token for privileged routes (defense-in-depth)
   // Fail LOUD on a port clash. The bridge binds a FIXED 4319 so the extension always
   // finds it; if it's taken, say how to recover instead of dying on a raw stack trace.
@@ -840,6 +886,18 @@ function startServer() {
     log('error', `bridge server error: ${e?.message || e}`);
     process.exit(1);
   });
+  // Leaving a CLI running after the bridge exits is how orphans are made — and the user has
+  // no way to find or stop them, because the thing that spawned them is gone.
+  for (const sig of ['SIGINT', 'SIGTERM']) {
+    process.on(sig, () => {
+      const n = cancelAll('shutdown');
+      if (n) log('info', `shutdown: stopped ${n} running agent${n === 1 ? '' : 's'}`);
+      // Give SIGTERM a moment to land before the process goes; killTree escalates on its own.
+      setTimeout(() => process.exit(0), n ? 300 : 0).unref?.();
+      if (!n) process.exit(0);
+    });
+  }
+
   server.listen(PORT, HOST, async () => {
     log('info', `listening on http://${HOST}:${PORT}`);
     // M7: a non-loopback bind disables the anti-DNS-rebinding Host check (hostAllowed