handmux 0.5.2 → 0.6.0

package/src/cli/setupWizard.js

@@ -11,6 +11,7 @@ import webpush from 'web-push';
 import { configPath, pocketHome } from './state.js';
 import { resolveCloudflared } from './cloudflared.js';
 import { resolveTunlite, checkSshAuth } from './tunlite.js';
+import { t, setLocale, getLocale } from './i18n/index.js';
 
 // ~/.cloudflared/config.yml for a named tunnel: route the hostname to the local handmux port.
 export function cfConfigYaml({ tunnelName, credentialsFile, hostname, port }) {
@@ -50,7 +51,7 @@ export function findTunnelId(listJsonOut, name) {
 // old value instead of leaving a stale field behind. Anything NOT here (token, staticDir, previewDomain…)
 // is preserved untouched.
 const WIZARD_KEYS = [
-  'name', 'port', 'tunnel',
+  'lang', 'name', 'port', 'tunnel',
   'sshHost', 'remotePort', 'sshJump', 'cfHostname', 'cfTunnelName', 'publicUrl',
   'vapid', 'xfyun',
 ];
@@ -58,6 +59,7 @@ const WIZARD_KEYS = [
 // Wizard answers → the config fragment the user actually set (omit empty optional fields).
 export function configFromAnswers(a) {
   const cfg = { tunnel: a.tunnel, port: a.port };
+  if (a.lang) cfg.lang = a.lang;
   if (a.name) cfg.name = a.name;
   if (a.tunnel === 'ssh') {
     cfg.sshHost = a.sshHost;
@@ -102,32 +104,41 @@ function readExisting(file) {
 // (preserving fields it didn't ask about). Returns the resolved config (or null on abort). `home` and the
 // write `target` are injectable for tests / `--config`.
 export async function runSetup({ home = homedir(), target = configPath(home), log = console } = {}) {
-  if (!process.stdin.isTTY) { log.error('handmux setup needs an interactive terminal'); return null; }
+  if (!process.stdin.isTTY) { log.error(t('setup.needTty')); return null; }
   const cur = readExisting(target);
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    const name = await ask(rl, 'app name (shown in the browser tab / home-screen icon; blank = default)', cur.name || '');
+    // Language first — pick it, apply it immediately, so the rest of the wizard speaks the chosen language.
+    // Default reflects the locale already resolved (from config/shell); Enter keeps it.
+    log.log(t('setup.langQ'));
+    log.log(t('setup.lang1'));
+    log.log(t('setup.lang2'));
+    const langPick = await ask(rl, t('setup.choose').replace('1-4', '1-2'), getLocale() === 'zh' ? '2' : '1');
+    const lang = { 1: 'en', 2: 'zh' }[langPick] || getLocale();
+    setLocale(lang);
 
-    log.log('How should your phone reach this machine?');
-    log.log('  1) none              — same Wi-Fi / LAN only');
-    log.log('  2) cloudflare        — instant, random temporary https URL');
-    log.log('  3) cloudflare-named  — your domain, stable HTTPS (most hands-off)');
-    log.log('  4) ssh (tunlite)     — your own server / edge');
+    const name = await ask(rl, t('setup.askName'), cur.name || '');
+
+    log.log(t('setup.tunnelQ'));
+    log.log(t('setup.tunnel1'));
+    log.log(t('setup.tunnel2'));
+    log.log(t('setup.tunnel3'));
+    log.log(t('setup.tunnel4'));
     const curPick = { none: '1', cloudflare: '2', 'cloudflare-named': '3', ssh: '4' }[cur.tunnel] || '3';
-    const pick = await ask(rl, 'choose 1-4', curPick);
+    const pick = await ask(rl, t('setup.choose'), curPick);
     const tunnel = { 1: 'none', 2: 'cloudflare', 3: 'cloudflare-named', 4: 'ssh' }[pick];
-    if (!tunnel) { log.error('invalid choice'); return null; }
-    const port = Number(await ask(rl, 'server port', String(cur.port || 19999)));
+    if (!tunnel) { log.error(t('setup.invalid')); return null; }
+    const port = Number(await ask(rl, t('setup.askPort'), String(cur.port || 19999)));
 
-    const answers = { name, tunnel, port };
+    const answers = { lang, name, tunnel, port };
     if (tunnel === 'cloudflare-named') {
-      answers.cfHostname = await ask(rl, 'public hostname (e.g. handmux.example.com)', cur.cfHostname || '');
-      answers.cfTunnelName = await ask(rl, 'tunnel name', cur.cfTunnelName || 'handmux');
+      answers.cfHostname = await ask(rl, t('setup.askHostname'), cur.cfHostname || '');
+      answers.cfTunnelName = await ask(rl, t('setup.askTunnelName'), cur.cfTunnelName || 'handmux');
       await provisionCloudflareNamed({ home, hostname: answers.cfHostname, tunnelName: answers.cfTunnelName, port, log });
     } else if (tunnel === 'ssh') {
-      answers.sshHost = await ask(rl, 'ssh host (user@host[:port])', cur.sshHost || '');
-      answers.remotePort = Number(await ask(rl, 'remote port on the ssh host', String(cur.remotePort || port)));
-      answers.publicUrl = await ask(rl, 'public url (blank = http://host:remotePort)', cur.publicUrl || '');
+      answers.sshHost = await ask(rl, t('setup.askSshHost'), cur.sshHost || '');
+      answers.remotePort = Number(await ask(rl, t('setup.askRemotePort'), String(cur.remotePort || port)));
+      answers.publicUrl = await ask(rl, t('setup.askPublicUrl'), cur.publicUrl || '');
       await provisionSsh({ sshHost: answers.sshHost, log });
     }
 
@@ -137,7 +148,7 @@ export async function runSetup({ home = homedir(), target = configPath(home), lo
     const cfg = mergeConfig(cur, answers);
     fs.mkdirSync(path.dirname(target), { recursive: true });
     fs.writeFileSync(target, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
-    log.log(`✓ wrote ${target}`);
+    log.log(t('setup.wrote', { path: target }));
     if (tunnel === 'ssh') printSshServerHelp(answers, log);
     if (tunnel === 'cloudflare-named' || tunnel === 'ssh') printPreviewHelp(tunnel, log);
     return cfg;
@@ -149,27 +160,27 @@ export async function runSetup({ home = homedir(), target = configPath(home), lo
 // part of push setup, done for the user. Returns the vapid object, or undefined to leave push off.
 async function askPush(rl, existing, log) {
   if (existing) {
-    if (await askYesNo(rl, 'keep push notifications configured?', true)) return existing;
+    if (await askYesNo(rl, t('setup.pushKeep'), true)) return existing;
     return undefined;
   }
-  if (!await askYesNo(rl, 'set up push notifications now? (generates VAPID keys)', false)) return undefined;
+  if (!await askYesNo(rl, t('setup.pushSetup'), false)) return undefined;
   const { publicKey, privateKey } = webpush.generateVAPIDKeys();
-  const subject = await ask(rl, 'contact (mailto: or https URL, for the push service)', 'mailto:admin@example.com');
-  log.log('✓ generated VAPID keypair');
+  const subject = await ask(rl, t('setup.pushContact'), 'mailto:admin@example.com');
+  log.log(t('setup.pushGenerated'));
   return { public: publicKey, private: privateKey, subject };
 }
 
 // Voice input (iFlytek/xfyun) — three credentials from their console; no generation possible, just paste.
 async function askVoice(rl, existing, log) {
   if (existing) {
-    if (await askYesNo(rl, 'keep voice input configured?', true)) return existing;
+    if (await askYesNo(rl, t('setup.voiceKeep'), true)) return existing;
     return undefined;
   }
-  if (!await askYesNo(rl, 'set up voice input now? (needs iFlytek/xfyun keys)', false)) return undefined;
-  const appId = await ask(rl, 'xfyun appId');
-  const apiKey = await ask(rl, 'xfyun apiKey');
-  const apiSecret = await ask(rl, 'xfyun apiSecret');
-  if (!appId || !apiKey || !apiSecret) { log.log('  (skipped — missing fields)'); return undefined; }
+  if (!await askYesNo(rl, t('setup.voiceSetup'), false)) return undefined;
+  const appId = await ask(rl, t('setup.voiceAppId'));
+  const apiKey = await ask(rl, t('setup.voiceApiKey'));
+  const apiSecret = await ask(rl, t('setup.voiceApiSecret'));
+  if (!appId || !apiKey || !apiSecret) { log.log(t('setup.voiceSkipped')); return undefined; }
   return { appId, apiKey, apiSecret };
 }
 
@@ -178,7 +189,7 @@ async function provisionCloudflareNamed({ home, hostname, tunnelName, port, log
   const bin = await resolveCloudflared(home);
   const cfDir = path.join(home, '.cloudflared');
   if (!fs.existsSync(path.join(cfDir, 'cert.pem'))) {
-    log.log('→ logging in to Cloudflare (a browser will open) …');
+    log.log(t('setup.cfLogin'));
     spawnSync(bin, ['tunnel', 'login'], { stdio: 'inherit' });
   }
   // Idempotent: reuse the tunnel if it already exists (re-running setup, or after a stop), else create it.
@@ -188,47 +199,47 @@ async function provisionCloudflareNamed({ home, hostname, tunnelName, port, log
   let id = findTunnelId(listed.stdout, tunnelName);
   let credentialsFile = null;
   if (id) {
-    log.log(`✓ reusing existing tunnel ${tunnelName} (${id})`);
+    log.log(t('setup.cfReuse', { name: tunnelName, id }));
     credentialsFile = path.join(cfDir, `${id}.json`);
     if (!fs.existsSync(credentialsFile)) {
-      log.error(`⚠ credentials file ${credentialsFile} not found on this machine — the tunnel was likely`);
-      log.error(`  created elsewhere. Run \`${bin} tunnel delete ${tunnelName}\` and re-run setup to recreate it here.`);
+      log.error(t('setup.cfCredMissing1', { file: credentialsFile }));
+      log.error(t('setup.cfCredMissing2', { bin, name: tunnelName }));
     }
   } else {
-    log.log(`→ creating tunnel ${tunnelName} …`);
+    log.log(t('setup.cfCreate', { name: tunnelName }));
     const created = spawnSync(bin, ['tunnel', 'create', tunnelName], { encoding: 'utf8' });
     process.stdout.write(created.stdout || ''); process.stderr.write(created.stderr || '');
     const parsed = parseTunnelCreate(`${created.stdout || ''}\n${created.stderr || ''}`);
     id = parsed.id;
     credentialsFile = parsed.credentialsFile;
   }
-  log.log(`→ routing ${hostname} → tunnel …`);
+  log.log(t('setup.cfRoute', { host: hostname }));
   // --overwrite-dns: re-running setup (or pointing a hostname already routed) must not error on the DNS step.
   const routed = spawnSync(bin, ['tunnel', 'route', 'dns', '--overwrite-dns', tunnelName, hostname], { encoding: 'utf8' });
   if (routed.status !== 0) {
     process.stderr.write(routed.stderr || '');
-    log.error(`⚠ route dns failed — is ${hostname.split('.').slice(-2).join('.')}'s DNS hosted on Cloudflare?`);
-    log.error('  Add the domain on Cloudflare (free) and point its nameservers there, then re-run setup.');
+    log.error(t('setup.cfRouteFail', { domain: hostname.split('.').slice(-2).join('.') }));
+    log.error(t('setup.cfRouteFail2'));
   }
   fs.mkdirSync(cfDir, { recursive: true });
   fs.writeFileSync(path.join(cfDir, 'config.yml'),
     cfConfigYaml({ tunnelName, credentialsFile: credentialsFile || path.join(cfDir, `${id || tunnelName}.json`), hostname, port }));
-  log.log(`✓ wrote ${path.join(cfDir, 'config.yml')}`);
+  log.log(t('setup.wrote', { path: path.join(cfDir, 'config.yml') }));
 }
 
 // drive tunlite passwordless setup inline (one password) if not already set up.
 async function provisionSsh({ sshHost, log }) {
   const bin = resolveTunlite();
-  if (checkSshAuth(sshHost, { bin }) === 0) { log.log('✓ passwordless SSH already set up'); return; }
-  log.log(`→ setting up passwordless SSH to ${sshHost} (you'll enter the password once) …`);
+  if (checkSshAuth(sshHost, { bin }) === 0) { log.log(t('setup.sshReady')); return; }
+  log.log(t('setup.sshSetup', { host: sshHost }));
   spawnSync(bin, ['setup-key', sshHost], { stdio: 'inherit' });
 }
 
 function printSshServerHelp(a, log) {
   log.log('');
-  log.log('Server side (one-time): point a reverse proxy at the forwarded loopback port.');
-  log.log(`  nginx:  proxy_pass http://127.0.0.1:${a.remotePort};  (add client_max_body_size 60m; proxy_read_timeout 90s;)`);
-  log.log(`  caddy:  ${a.publicUrl || '<your-domain>'} {  reverse_proxy 127.0.0.1:${a.remotePort}  }`);
+  log.log(t('setup.sshHelp1'));
+  log.log(t('setup.sshHelpNginx', { port: a.remotePort }));
+  log.log(t('setup.sshHelpCaddy', { url: a.publicUrl || '<your-domain>', port: a.remotePort }));
   log.log('');
 }
 
@@ -237,12 +248,12 @@ function printSshServerHelp(a, log) {
 // (so deeper needs ACM), whereas on the ssh/own-edge path the user serves their own wildcard cert. Shown
 // only for wildcard-capable tunnels (a quick tunnel can't do wildcards at all).
 function printPreviewHelp(tunnel, log) {
-  log.log('Optional — dynamic port preview (open a dev server by port on your phone):');
-  log.log('  set  "previewDomain": "..."  in the config, and route the wildcard preview domain to the gateway.');
+  log.log(t('setup.previewHelp1'));
+  log.log(t('setup.previewHelp2'));
   if (tunnel === 'cloudflare-named') {
-    log.log("  TLS: Cloudflare's free cert covers ONE level (*.example.com); deeper (*.preview.example.com) needs Advanced Certificate Manager.");
+    log.log(t('setup.previewTlsCf'));
   } else {
-    log.log("  TLS: your edge serves the wildcard cert (e.g. a Let's Encrypt *.preview.your.domain).");
+    log.log(t('setup.previewTlsEdge'));
   }
   log.log('');
 }

package/src/cli/updateCheck.js

@@ -0,0 +1,90 @@
+// Update notifier for the globally-installed `handmux` CLI. There is NO self-updating server: the notice
+// is a hint, the upgrade is a plain `npm i -g handmux@latest` (the `handmux update` command runs that for
+// you). Two rules keep it unobtrusive and China-friendly:
+//   1. The hot path (start/status) NEVER touches the network — it prints from a cached "latest version"
+//      and, only if that cache is stale, spawns a DETACHED background worker to refresh it. So the first
+//      run after a new release is what surfaces it; the command itself is never delayed or blocked.
+//   2. The version query goes through the user's own npm (`npm view handmux version`), so it honours a
+//      configured China mirror / private registry instead of hard-coding registry.npmjs.org. Any failure
+//      (offline, blocked, npm missing) is swallowed — the notifier is best-effort, never an error.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { pocketHome } from './state.js';
+import { t } from './i18n/index.js';
+
+export const PKG_NAME = 'handmux';
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // refresh the cached "latest" at most once a day
+
+export function updateCachePath(home) { return path.join(pocketHome(home), 'update-check.json'); }
+
+export function readCache(home) {
+  try { return JSON.parse(fs.readFileSync(updateCachePath(home), 'utf8')); } catch { return null; }
+}
+
+export function writeCache(home, obj) {
+  try {
+    fs.mkdirSync(pocketHome(home), { recursive: true });
+    fs.writeFileSync(updateCachePath(home), JSON.stringify(obj));
+  } catch { /* best effort — a missing cache just means we re-check next time */ }
+}
+
+// "1.2.3" → [1,2,3]; a prerelease/build tail (`-rc.1`, `+meta`) is ignored. null if unparseable.
+function parts(v) {
+  const m = String(v || '').trim().match(/^v?(\d+)\.(\d+)\.(\d+)/);
+  return m ? [+m[1], +m[2], +m[3]] : null;
+}
+
+// -1 / 0 / 1 by numeric major.minor.patch. Unparseable inputs compare equal (→ no false "upgrade").
+export function compareVersions(a, b) {
+  const pa = parts(a), pb = parts(b);
+  if (!pa || !pb) return 0;
+  for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
+  return 0;
+}
+
+export function isNewer(latest, current) { return compareVersions(latest, current) > 0; }
+
+export function shouldRefresh(cache, now = Date.now(), interval = CHECK_INTERVAL_MS) {
+  return !cache || typeof cache.checkedAt !== 'number' || (now - cache.checkedAt) > interval;
+}
+
+// Query the latest published version via the user's own npm (honours their registry/mirror). Hard timeout;
+// any non-zero exit, empty/garbled output, or thrown error → null. Never throws.
+export function fetchLatestVersion({ timeoutMs = 4000, run = spawnSync } = {}) {
+  try {
+    const r = run('npm', ['view', PKG_NAME, 'version'], { timeout: timeoutMs, encoding: 'utf8' });
+    if (!r || r.status !== 0 || !r.stdout) return null;
+    const v = String(r.stdout).trim();
+    return parts(v) ? v : null;
+  } catch { return null; }
+}
+
+// The hidden `__update-check` worker (runs detached, prints nothing): refresh the cache. On a failed fetch
+// keep the previously-known latest but still stamp checkedAt, so a flaky network doesn't re-spawn every run.
+export function runUpdateCheck(home, { now = Date.now(), ...opts } = {}) {
+  const latest = fetchLatestVersion(opts) || (readCache(home)?.latest ?? null);
+  writeCache(home, { checkedAt: now, latest });
+}
+
+// Fire-and-forget notifier for a foreground command. Prints an upgrade line straight from the cache (no
+// network on this path), then — if the cache is stale — kicks off a detached refresh so the NEXT run is
+// current. Returns true if a notice was printed (handy for tests). `selfPath` is the CLI entry so the
+// background worker re-invokes this same binary.
+export function notifyUpdate(home, { version, selfPath, now = Date.now(), log = console.log, spawnFn = spawn } = {}) {
+  const cache = readCache(home);
+  let shown = false;
+  if (cache && cache.latest && isNewer(cache.latest, version)) {
+    log('');
+    log(t('update.available', { current: version, latest: cache.latest }));
+    log(t('update.how'));
+    shown = true;
+  }
+  if (selfPath && shouldRefresh(cache, now)) {
+    try {
+      const child = spawnFn(process.execPath, [selfPath, '__update-check'], { detached: true, stdio: 'ignore' });
+      child.unref?.();
+    } catch { /* best effort */ }
+  }
+  return shown;
+}

package/src/httpApi.js

@@ -21,11 +21,24 @@ import { safeUploadName } from './docPath.js';
 import { safePreviewName } from './previews.js';
 import { isAllowedUploadExt, DEFAULT_UPLOAD_EXTS } from './uploadTypes.js';
 import { hooksStatus, installHooks } from './cli/claudeHooks.js';
+import { codexHooksStatus, installCodexHooks } from './cli/codexHooks.js';
 import { claudeStatePath } from './cli/state.js';
+import { scanOrphans, takeoverOrphan, defaultProjectsDir } from './orphans.js';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const HOOKS_SRC = resolvePath(here, '../hooks'); // server/hooks (bundled scripts)
 
+// Summarize inbox-hook state across every coding agent for the phone: 'installed' if any agent is wired,
+// 'absent' if an agent is present but none wired (→ offer the one-tap enable), 'no-claude' if there's no
+// agent at all (→ hide the prompt).
+function combinedHooksStatus(home) {
+  const c = hooksStatus(home);      // 'no-claude' | 'installed' | 'absent'
+  const x = codexHooksStatus(home); // 'no-codex' | 'installed' | 'absent'
+  if (c === 'installed' || x === 'installed') return 'installed';
+  if (c !== 'no-claude' || x !== 'no-codex') return 'absent';
+  return 'no-claude';
+}
+
 const ALLOWED_KEYS = new Set([
   'Up', 'Down', 'Left', 'Right', 'Space', 'Enter', 'Escape', 'Tab', 'BTab', 'BSpace',
   'C-c', 'C-d', 'C-z', 'C-l', 'C-r', 'C-o', 'C-e',
@@ -437,16 +450,21 @@ export function createApiRouter({
   // Optional integrations are configured per-install (open-source installs ship without keys), so the
   // client asks what's actually available and hides controls that can't work — e.g. the mic when no
   // ASR engine is configured. Add more flags here as optional integrations land.
+  // `claudeHooks` (name kept for web back-compat) now summarizes EVERY coding agent: 'installed' if any is
+  // wired, 'absent' if an agent is present but none wired (→ offer enable), 'no-claude' if no agent at all.
   r.get('/config', (req, res) => {
-    res.json({ asr: isAsrConfigured(asrEnv), claudeHooks: hooksStatus(home) });
+    res.json({ asr: isAsrConfigured(asrEnv), claudeHooks: combinedHooksStatus(home) });
   });
 
-  // One-tap enable from the phone: install the Claude Code hooks on the host (token-gated, like every API
-  // here). Opt-in — the inbox only offers this when status is 'absent'. Never creates ~/.claude.
+  // One-tap enable from the phone: install the hooks for every present agent (Claude Code, Codex) on the
+  // host (token-gated, like every API here). Opt-in — the inbox only offers this when status is 'absent'.
+  // Never creates ~/.claude or ~/.codex; a user's own Codex `notify` is left untouched (see codexHooks.js).
   r.post('/hooks/install', (req, res) => {
     try {
-      const { status } = installHooks(home, { srcDir: HOOKS_SRC, stateFile });
-      res.json({ ok: status === 'installed', status });
+      let installed = 0;
+      if (hooksStatus(home) !== 'no-claude') { installHooks(home, { srcDir: HOOKS_SRC, stateFile }); installed++; }
+      if (codexHooksStatus(home) !== 'no-codex') { installCodexHooks(home, { srcDir: HOOKS_SRC, stateFile }); installed++; }
+      res.json({ ok: installed > 0, status: combinedHooksStatus(home) });
     } catch (e) { res.status(500).json({ ok: false, error: String(e) }); }
   });
 
@@ -512,6 +530,30 @@ export function createApiRouter({
     try { res.json(await claudeEvents.getStates(allowed)); } catch (e) { next(e); }
   });
 
+  // Orphan Claude sessions: `claude` processes running on this host but NOT inside a tmux pane, so
+  // handmux can't steer them. Surfaced at the bottom of the Inbox with a "takeover" (spawn
+  // `claude --resume` in tmux). Best-effort process scan (see orphans.js); never throws.
+  r.get('/orphans', async (req, res, next) => {
+    try { res.json(await scanOrphans({ projectsDir: defaultProjectsDir(home) })); } catch (e) { next(e); }
+  });
+
+  // Take over an orphan: spawn `claude --resume <sessionId>` in tmux and (default) SIGTERM the original.
+  // pid/sessionId are re-verified against a fresh scan server-side; sessionId must be a UUID (it's typed
+  // into a shell). target.mode 'new' (fresh session) or 'window' (into an existing session id).
+  r.post('/orphans/takeover', async (req, res, next) => {
+    const { pid, sessionId, kill, target } = req.body || {};
+    const t = target && target.mode === 'window' && isSessionId(target.session)
+      ? { mode: 'window', session: target.session } : { mode: 'new' };
+    try {
+      const out = await takeoverOrphan(
+        { commands, scanOpts: { projectsDir: defaultProjectsDir(home) } },
+        { pid, sessionId, target: t, kill: kill !== false },
+      );
+      if (out.error) return res.status(out.status).json({ error: out.error });
+      res.json(out);
+    } catch (e) { next(e); }
+  });
+
   // --- Preview registry (static dir OR dynamic port) -----------------------------------------
   // POST {name,dir} registers a static dir served at /preview/<name>/; POST {name,port} registers a
   // dynamic reverse-proxy reachable at https://<name>.<DOMAIN>/ (only when previewDomain is set). The

package/src/orphans.js

@@ -0,0 +1,138 @@
+// Detect "orphan" coding-agent sessions: a `claude`/`codex`/… process running on this host that is NOT
+// inside a tmux pane, so handmux can't see or steer it. We can't migrate a live process into tmux (reptyr
+// needs Linux ptrace+/proc — out on macOS — and breaks on multithreaded Node + child processes), so instead
+// we surface these in the Inbox and offer a "takeover": spawn the agent's `resume` command in a fresh tmux
+// pane (the agent's own persistence continues the conversation), then optionally kill the original.
+//
+// Detection is process-based, NOT a scan of the agents' session history (which is unbounded and can't tell
+// a live session from a dead one). Cost scales with the number of LIVE agent processes only.
+//
+// tmux membership is decided by TTY/PPID match against `tmux list-panes`, NOT by reading the process
+// environment: on macOS `ps eww` can't read another process's env (SIP), so `$TMUX` is a false signal.
+// A proc whose controlling tty is one of tmux's pane ttys (or whose parent is a pane's shell) is in tmux;
+// anything else with a real tty is an orphan.
+//
+// This module is now the agent-AGNOSTIC engine: which processes count, where a cwd's session lives, and how
+// to resume it all come from the driver descriptors in ./agents (parseAgentProcs tags each proc with its
+// agent; scan/takeover dispatch through getAgent). The pure parse/file helpers live in ./agents/scanUtils.
+import os from 'node:os';
+import path from 'node:path';
+import { AGENTS, getAgent } from './agents/index.js';
+import { isSessionId } from './tmux/commands.js';
+import {
+  defaultRun, parseAgentProcs, parsePaneMembership, findOrphans,
+  takeoverSessionName, isShell, lsofCwd, isSessionUuid,
+} from './agents/scanUtils.js';
+
+// Back-compat re-exports: these were originally defined here and are imported by tests and callers by this
+// path. They're all agent-agnostic (or Claude's, kept as the default) and now live in scanUtils / claude.
+export {
+  parsePaneMembership, findOrphans, encodeProjectDir, isSessionUuid,
+  lastUserSnippet, etimeToMs, takeoverSessionName,
+  resolveEncodedDirSession as resolveSession,
+} from './agents/scanUtils.js';
+export { projectsDir as defaultProjectsDir } from './agents/claude.js';
+
+// Parse `ps …` to LIVE Claude CLI procs only — the original Claude-specific helper, kept for the tests.
+// The general engine uses parseAgentProcs(psOut, AGENTS) directly.
+export function parseClaudeProcs(psOut) {
+  return parseAgentProcs(psOut, [getAgent('claude')]);
+}
+
+// Take over an orphan: spawn the agent's `resume <sessionId>` in a fresh tmux session (target.mode 'new')
+// or a new window of an existing session ('window'), so handmux can steer the continued conversation.
+// Everything is re-verified server-side — the client's pid/sessionId are inputs to a fresh scan, never
+// trusted directly. The original process is SIGTERM'd only AFTER the resumed agent is confirmed up
+// (foreground command is no longer the shell) AND re-confirmed still the same orphan (guards pid reuse):
+// `<agent> resume` appends to the SAME session file with no OS lock (verified for Claude), so two live
+// writers corrupt history — killing guarantees a single writer. Injectable deps make it unit-testable.
+export async function takeoverOrphan(
+  {
+    commands, scanFn = scanOrphans, scanOpts = {},
+    killProc = (pid, sig) => process.kill(pid, sig),
+    delay = (ms) => new Promise((r) => setTimeout(r, ms)),
+    pollTries = 16, pollMs = 400,
+  },
+  { pid, sessionId, target = { mode: 'new' }, kill = true } = {},
+) {
+  if (!Number.isInteger(pid) || pid <= 0) return { error: 'bad pid', status: 400 };
+  // Both agents use UUID session ids; validate up front (takeover types the id into a shell via send-keys).
+  if (!isSessionUuid(sessionId)) return { error: 'bad session id', status: 400 };
+
+  const o = (await scanFn(scanOpts)).find((x) => x.pid === pid);
+  if (!o) return { error: 'gone', status: 409 };            // no longer a live orphan
+  if (o.sessionId !== sessionId) return { error: 'session changed', status: 409 };
+  if (!o.cwd) return { error: 'no cwd', status: 409 };
+  const agent = getAgent(o.agent);
+  const cmd = agent.sessions.resumeCmd(sessionId);
+
+  let sid;
+  let wid;
+  let name; // the target session NAME — returned so the client can bind it into its session list
+  if (target.mode === 'window') {
+    if (!isSessionId(target.session)) return { error: 'bad target session', status: 400 };
+    sid = target.session;
+    name = (await commands.listSessions()).find((s) => s.id === sid)?.name || null;
+    wid = await commands.newWindow(sid, o.cwd, agent.procName, cmd);
+  } else {
+    const existing = new Set((await commands.listSessions()).map((s) => s.name));
+    for (let i = 1; i < 1000 && !name; i++) {
+      const cand = takeoverSessionName(o.cwdLabel, i, agent.takeoverPrefix);
+      if (!existing.has(cand)) name = cand;
+    }
+    sid = await commands.newSession(name, o.cwd, cmd);
+    wid = (await commands.listWindows(sid))[0]?.id;
+  }
+
+  let up = false;
+  let pane = null;
+  for (let i = 0; i < pollTries && !up; i++) {
+    await delay(pollMs);
+    try {
+      const p = (await commands.listPanes(wid))[0];
+      if (p) { pane = p.id; if (!isShell(p.command)) up = true; }
+    } catch { /* window/pane not ready yet */ }
+  }
+
+  let killed = false;
+  if (kill && up) {
+    const still = (await scanFn(scanOpts)).find((x) => x.pid === pid && x.sessionId === sessionId);
+    if (still) { try { killProc(pid, 'SIGTERM'); killed = true; } catch { /* already exited */ } }
+  }
+  // claudeUp kept in the response for back-compat with the existing web client; agentUp is the neutral name.
+  return { session: sid, name, window: wid, pane, agentUp: up, claudeUp: up, killed, agent: agent.id };
+}
+
+// Scan the host for orphan agent sessions across every registered driver. Best-effort: any failing
+// sub-command degrades to fewer/no results rather than throwing. `projectsDir`/`sessionsDir` override a
+// specific agent's session dir (each driver declares which option key it reads — used by tests and the
+// server, which pin the dir off the resolved $HOME).
+export async function scanOrphans({
+  run = defaultRun, home = os.homedir(), busyMs = 8000, now = Date.now, agents = AGENTS, ...dirOverrides
+} = {}) {
+  const [psOut, tmuxOut] = await Promise.all([
+    run('ps', ['-Ao', 'pid=,ppid=,stat=,etime=,tty=,args=']),
+    run('tmux', ['list-panes', '-a', '-F', '#{pane_tty}\t#{pane_pid}']),
+  ]);
+  const orphans = findOrphans(parseAgentProcs(psOut, agents), parsePaneMembership(tmuxOut));
+  const results = [];
+  for (const o of orphans) {
+    const agent = getAgent(o.agent);
+    const cwd = await lsofCwd(run, o.pid);
+    const dir = dirOverrides[agent.sessions.dirOptKey] || agent.sessions.dir(home);
+    const meta = cwd ? await agent.sessions.resolve(dir, cwd, { busyMs, now }) : {};
+    results.push({
+      pid: o.pid,
+      agent: agent.id,
+      agentLabel: agent.label,
+      cwd: cwd || '',
+      cwdLabel: cwd ? path.basename(cwd) : '',
+      sessionId: meta.sessionId || null,
+      state: meta.state || 'unknown',
+      snippet: meta.snippet || '',
+      lastActivity: meta.lastActivity || 0,
+      startedAt: o.etimeMs ? Math.round(now() - o.etimeMs) : 0,
+    });
+  }
+  return results;
+}

package/tmux/claude-tab-seed.py

@@ -40,11 +40,16 @@ DOT = {
     "working": "#[fg=#2f6fed,blink]●#[default] ",  # 蓝闪
 }
 
+# 冷启动只给【正在跑某个 agent】的窗补点。Claude 的 pane_current_command 是 "claude";Codex 的 PATH 入口
+# 是个 node 启动器,所以是 "node"(与 server 端 liveness 的 procNames 一致)。有状态条目 + 命令属于 agent
+# 才补点,避免给回到 shell 的窗残留脏点。
+AGENT_CMDS = {"claude", "codex", "node"}
+
 # window_id -> 最高优先级 kind
 top = {}
 for line in tmux("list-panes", "-a", "-F", "#{pane_current_command} #{pane_id} #{window_id}").splitlines():
     parts = line.split()
-    if len(parts) < 3 or parts[0] != "claude":
+    if len(parts) < 3 or parts[0] not in AGENT_CMDS:
         continue
     _, pane, win = parts[0], parts[1], parts[2]
     e = state.get(pane)