handmux 0.5.0

package/src/claudeEvents.js

@@ -0,0 +1,212 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+// The hook-maintained state file: ONE JSON object keyed by tmux pane id, each value the pane's latest
+// event { ts, src, host, payload }. The hook writes it (handmux-write.js); the server only reads it.
+// Default lives under server/data (gitignored runtime data); override with CLAUDE_STATE_FILE.
+export const DEFAULT_STATE_FILE = process.env.CLAUDE_STATE_FILE || path.resolve(here, '../data/claude-state.json');
+
+// Build the 需要你 one-liner for a PermissionRequest, from the tool it's gating on (PermissionRequest
+// carries tool_name + tool_input, unlike the later permission_prompt Notification which only has an
+// English message).
+function permMsg(body) {
+  const t = body.tool_name;
+  if (t === 'AskUserQuestion') {
+    const q = body.tool_input && body.tool_input.questions && body.tool_input.questions[0];
+    const text = (q && (q.question || q.header)) || '';
+    return text ? `需要你回答：${text}` : '需要你回答';
+  }
+  if (t === 'ExitPlanMode') return '需要你批准计划';
+  return t ? `需要你授权：${t}` : '需要你';
+}
+
+// Build the 进行中 one-liner for a resume (PostToolUse after the user answered/approved), surfacing the
+// choice they just made — AskUserQuestion stores it in tool_input.answers, keyed by question.
+function resumeMsg(body) {
+  const a = (body.tool_input && body.tool_input.answers) || (body.tool_response && body.tool_response.answers);
+  if (a && typeof a === 'object') {
+    const picks = Object.values(a).flat().filter(Boolean).join('、');
+    if (picks) return `已答：${picks}`;
+  }
+  if (body.tool_name === 'ExitPlanMode') return '已批准计划';
+  return '';
+}
+
+// Map a hook event (src + raw Claude payload) to a notification "kind". Pure — no I/O, easy to test.
+//   stop                       → done       (turn finished; carries last message)
+//   prompt                     → working    (UserPromptSubmit; carries the prompt)
+//   end                        → end        (SessionEnd; the pane's claude is gone)
+//   notify + idle_prompt       → idle       (waited ~60s; carries the notification message)
+//   notify + permission_prompt → permission (blocked on a permission/选择 gate; carries the message)
+//   resume                     → working    (PostToolUse on AskUserQuestion/ExitPlanMode: the user just
+//                                             answered/approved → Claude is working again; un-sticks the
+//                                             pane from the `permission` state its prompt left behind, and
+//                                             carries the choice the user made, e.g. 已答：Red)
+//   permreq                    → permission (PermissionRequest: a real prompt just appeared — fires ~6s
+//                                             before the permission_prompt Notification and names the tool,
+//                                             so 需要你 shows faster and says what's being asked. Verified
+//                                             NOT to fire for auto-approved tools → no false 需要你 in auto)
+//   anything else              → null       (ignored: auth_success, elicitation_*, etc.)
+export function classifyEvent(src, body = {}) {
+  if (src === 'stop') return { kind: 'done', msg: body.last_assistant_message || '' };
+  if (src === 'prompt') return { kind: 'working', msg: body.prompt || '' };
+  if (src === 'resume') return { kind: 'working', msg: resumeMsg(body) };
+  if (src === 'permreq') return { kind: 'permission', msg: permMsg(body) };
+  if (src === 'end') return { kind: 'end' };
+  if (src === 'notify') {
+    if (body.notification_type === 'idle_prompt') return { kind: 'idle', msg: body.message || '' };
+    if (body.notification_type === 'permission_prompt') return { kind: 'permission', msg: body.message || '' };
+  }
+  return null;
+}
+
+// Which display VIEW a kind pushes as — and so what the device notification fires for. permission→需要你,
+// done→已完成. 已完成 fires at the COMPLETION MOMENT (done) only. The trailing idle reminder (~60s "still
+// waiting") is dropped UPSTREAM at the hook (handmux-write.cjs), so neither push nor the inbox ever sees
+// it — that's the single source of truth. The idle NO-OP in the loop below is defense-in-depth for one
+// that ever slips through. working / end / unclassifiable map to undefined → no push + re-arm the dedup.
+const PUSH_VIEW = { permission: 'needs', done: 'done' };
+const VIEW_LABEL = { needs: '需要你', done: '已完成' };
+
+// A 进行中 (working) is a LATCHED state: set by UserPromptSubmit, normally closed by Stop. But an ESC
+// interrupt / walk-away fires NO hook at all (verified across all 26 hook event types), so working never
+// gets closed and the blue dot would stick forever. There's no event signal for the interrupt — so we
+// expire working purely by age: latched longer than this with no done/needs ⇒ no-longer-working, drop it.
+// Generous (2h) so a genuinely long-running task keeps its dot for its whole run; a real turn re-lights on
+// its next event, and a new prompt resets the clock.
+const WORKING_TTL_MS = 2 * 60 * 60 * 1000;
+
+// Truncate a Claude message to a notification-friendly one-liner.
+function summarize(msg) {
+  const oneLine = (msg || '').replace(/\s+/g, ' ').trim();
+  return oneLine.length > 120 ? `${oneLine.slice(0, 117)}…` : oneLine;
+}
+
+// Read the hook's JSON state file. Tolerant of a missing / corrupt / half-written file (returns {}),
+// never throws — the hook replaces it atomically, but a read can still land on a transient state.
+function readStateFile(file) {
+  try {
+    const obj = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return obj && typeof obj === 'object' && !Array.isArray(obj) ? obj : {};
+  } catch { return {}; }
+}
+
+// Per-process event reader. Deps injected for testability:
+//   commands.listLivePanes() → [{ id, cmd, session, window, windowName }]  (one tmux call: liveness+location)
+//   push.sendToSession(session, payload, {ttl, urgency, topic})
+//   file: the hook-maintained JSON state file (DEFAULT_STATE_FILE).
+// The hook is the sole writer; the server reads the file fresh on every getStates and on every file
+// change (the watcher, for push). No persisted state of our own — the file IS the persistence.
+export function createClaudeEvents({ commands, push, file = DEFAULT_STATE_FILE, now = () => Date.now() } = {}) {
+  const lastPushed = {}; // pane → 'needs' | 'done' | null  (in-process push-transition dedup, by display view)
+  const dotClearedFor = {}; // pane → ts of the stuck 进行中 we already cleared @claude_dot for (clear once)
+  // The dedup above is in-process ONLY: a restart (e.g. ./deploy.sh) wipes it while the hook's state
+  // file on disk keeps every pane's latest 需要你/已完成. Without priming, the first read after boot
+  // would see an empty dedup and re-push every resting pane — a flood of "historical" notifications on
+  // every redeploy. prime() (run from start(), before any request is served) adopts the file's current
+  // resting states as already-notified, so only transitions that happen AFTER boot push.
+  function prime() {
+    const recorded = readStateFile(file);
+    for (const [pane, r] of Object.entries(recorded)) {
+      const c = r && typeof r.src === 'string' ? classifyEvent(r.src, r.payload || {}) : null;
+      const view = c ? PUSH_VIEW[c.kind] : undefined;
+      if (view) lastPushed[pane] = view; // resting 需要你/已完成 → treat as seen, don't replay
+    }
+  }
+
+  // Notify the device that a pane entered 需要你 / 已完成. Title carries the state label + session so the
+  // user can tell the two apart at a glance (the inbox shows the same label as a chip); body is the
+  // pane's one-line message, falling back to the bare label. 需要你 is high-urgency (wake the phone).
+  async function sendPush(pane, view, c, lp) {
+    const label = VIEW_LABEL[view];
+    const body = summarize(c.msg) || label;
+    const payload = { title: `${label} · ${lp.session}`, body, tag: `pane-${pane}`, data: { session: lp.session, window: lp.window, pane } };
+    // 可靠优先 TTL: a phone in Doze / briefly offline still gets the LATEST per pane when it wakes (the
+    // pane-topic collapses older ones, so no pileup). 需要你 holds for hours (you're being waited on);
+    // 已完成 ~30min (a stale "done" is less useful). A force-stopped app still can't be reached at all —
+    // that's an OS limit, not a TTL one.
+    const opts = { topic: `pane-${pane}`, ttl: view === 'needs' ? 14400 : 1800, urgency: view === 'needs' ? 'high' : 'normal' };
+    try { await push.sendToSession(lp.session, payload, opts); } catch { /* best effort */ }
+  }
+
+  // Read the state file, reconcile every recorded pane against live tmux, and in ONE pass: (1) fire push
+  // for 需要你/已完成 transitions (deduped, global — independent of any caller's session filter), and
+  // (2) build the pane→state roster the inbox shows. A pane is dropped from the roster when its latest
+  // event is `end`/unclassifiable, or when tmux says it's gone or no longer running claude (hard kill /
+  // crash / Ctrl-C-out with no SessionEnd). `allowedSessions` (session NAMES, or null) scopes only the
+  // OUTPUT — push and reconciliation run over every pane. On a tmux failure we degrade: no location, no
+  // reconciliation, no push (we'd have no session name to route to), roster returned best-effort.
+  async function getStates(allowedSessions = null) {
+    const allow = allowedSessions == null ? null : new Set(allowedSessions);
+    const recorded = readStateFile(file);
+    let live = null;
+    try { live = new Map((await commands.listLivePanes()).map((p) => [p.id, p])); } catch { /* tmux down */ }
+
+    const out = {};
+    for (const [pane, rec] of Object.entries(recorded)) {
+      const c = rec && typeof rec.src === 'string' ? classifyEvent(rec.src, rec.payload || {}) : null;
+      const lp = live ? live.get(pane) : null;
+      const gone = live ? (!lp || lp.cmd !== 'claude') : false;
+
+      // (1) push side-effect — runs for every pane regardless of the output filter. Push fires on entry
+      // into a 需要你 (permission) / 已完成 (done) view, deduped so a stay-put doesn't re-push. The idle
+      // reminder that trails a done is a NO-OP: 已完成 pings at the completion moment (done) only, so the
+      // 60s "still waiting" idle neither pushes nor disturbs the dedup (the pane is still in the same
+      // resting state). working / end / gone / unclassifiable re-arm the dedup for the next entry.
+      if (live) {
+        const kind = c ? c.kind : null;
+        const view = PUSH_VIEW[kind]; // 'needs' | 'done' | undefined
+        if (kind === 'idle') {
+          /* trailing idle reminder — no push, keep the dedup as the preceding done left it */
+        } else if (gone || !view) {
+          lastPushed[pane] = null; // 进行中 / 结束 / gone → re-arm for the next 需要你 / 已完成
+        } else if (lastPushed[pane] !== view && lp.session) {
+          lastPushed[pane] = view;
+          await sendPush(pane, view, c, lp);
+        }
+      }
+
+      // (2) roster — drop ended / dead / claude-exited panes; resolve location from the live tmux row.
+      if (!c || c.kind === 'end' || gone) continue;
+      // Expire a 进行中 latched past the TTL (an ESC-interrupt / walk-away that never got a Stop): drop it
+      // from the roster and clear the PC @claude_dot once, so the stuck blue dot goes away. See WORKING_TTL_MS.
+      if (c.kind === 'working' && now() - (rec.ts || 0) > WORKING_TTL_MS) {
+        if (live && typeof commands.runTmux === 'function' && dotClearedFor[pane] !== rec.ts) {
+          dotClearedFor[pane] = rec.ts;
+          try { await commands.runTmux(['set-option', '-w', '-t', pane, '@claude_dot', '']); } catch { /* best effort */ }
+        }
+        continue;
+      }
+      const loc = lp ? { session: lp.session, window: lp.window, windowName: lp.windowName } : {};
+      if (allow && !allow.has(loc.session)) continue;
+      out[pane] = { ...loc, kind: c.kind, msg: c.msg || '', ts: rec.ts || 0 };
+    }
+    return out;
+  }
+
+  // Watch the state file's directory (the hook replaces the file via rename, which changes the inode, so
+  // watching the file itself would go deaf after the first write — watch the dir and filter by name).
+  // On a change, re-run getStates so 需要你/已完成 push fires even when NO client is polling — that's
+  // the whole point of push (notify you while you're away). Debounced so a burst of writes pumps once.
+  let watcher = null;
+  let deb = null;
+  function start() {
+    if (watcher) return;
+    prime(); // boot baseline: don't replay the file's resting 需要你/已完成 as fresh push (see prime())
+    const dir = path.dirname(file);
+    const base = path.basename(file);
+    try { fs.mkdirSync(dir, { recursive: true }); } catch { /* ignore */ }
+    try {
+      watcher = fs.watch(dir, (_evt, fname) => {
+        if (fname && fname !== base) return;
+        clearTimeout(deb);
+        deb = setTimeout(() => { getStates().catch(() => {}); }, 120);
+      });
+    } catch { /* fs.watch unsupported → push falls back to evaluation on each /states poll */ }
+  }
+  function stop() { if (watcher) { watcher.close(); watcher = null; } clearTimeout(deb); }
+
+  return { getStates, start, stop };
+}

package/src/cli/cfNamed.js

@@ -0,0 +1,5 @@
+// Pure: detect a named cloudflared tunnel reaching a live edge connection. The hostname is known up front
+// (https://<cf-hostname>), so unlike quick-tunnel we don't scrape a URL — we just gate on cloudflared
+// logging a registered connection, so the QR isn't shown before the edge is reachable.
+const RE = /Registered tunnel connection/;
+export function cfNamedReady(text) { return RE.test(String(text || '')); }

package/src/cli/claudeHooks.js

@@ -0,0 +1,116 @@
+// Install/uninstall the Claude Code lifecycle hooks that feed the handmux inbox. This ports the idempotent
+// merge from scripts/install-hooks.sh into testable JS so the OSS CLI (and the phone, via the server) can
+// turn the inbox on — opt-in, since writing ~/.claude/settings.json edits another tool's config.
+//
+// Iron rule: only ever touch ~/.handmux/ and — after explicit opt-in — ~/.claude/. If ~/.claude is absent
+// (no Claude Code), skip and report 'no-claude'; never create it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+
+// The six events the inbox reads. src is the arg passed to handmux-notify.sh; only PostToolUse is scoped to
+// a matcher (the two "需要你" interaction tools) — every other Read/Bash/Edit must NOT wake the hook, or
+// many concurrent Claude panes would each spawn the hook on every tool call. Keep this table in sync with
+// the hook scripts in ../../hooks.
+export const HOOK_EVENTS = [
+  { event: 'Stop', src: 'stop' },
+  { event: 'Notification', src: 'notify' },
+  { event: 'UserPromptSubmit', src: 'prompt' },
+  { event: 'SessionEnd', src: 'end' },
+  { event: 'PostToolUse', src: 'resume', matcher: 'AskUserQuestion|ExitPlanMode' },
+  { event: 'PermissionRequest', src: 'permreq' },
+];
+
+const HOOK_MARK = 'handmux-notify.sh'; // identifies our hooks among the user's own
+
+// True if `settings.hooks[event]` already has one of our hooks (command references the dest script).
+function alreadyHas(hooks, event) {
+  return (hooks[event] || []).some((g) => (g.hooks || []).some(
+    (h) => typeof h.command === 'string' && h.command.includes(HOOK_MARK)));
+}
+
+// Pure: return a NEW settings object with our six hooks merged into settings.hooks, idempotently, leaving
+// the user's own hooks and other keys untouched. `dest` is the absolute path to the copied notify script.
+export function mergeHooks(settings, dest) {
+  const s = { ...(settings || {}) };
+  const hooks = (s.hooks && typeof s.hooks === 'object' && !Array.isArray(s.hooks)) ? { ...s.hooks } : {};
+  for (const e of HOOK_EVENTS) {
+    if (alreadyHas(hooks, e.event)) continue;
+    const groups = hooks[e.event] = [...(hooks[e.event] || [])];
+    groups.push({ matcher: e.matcher || '', hooks: [{ type: 'command', command: `${dest} ${e.src}`, async: true, timeout: 5 }] });
+  }
+  s.hooks = hooks;
+  return s;
+}
+
+// Pure: return a NEW settings object with all of OUR hooks removed (uninstall). An event group that ends up
+// empty is dropped; the user's own hooks and other keys are untouched.
+export function stripHooks(settings) {
+  const s = { ...(settings || {}) };
+  if (!s.hooks || typeof s.hooks !== 'object' || Array.isArray(s.hooks)) return s;
+  const hooks = {};
+  for (const [event, groups] of Object.entries(s.hooks)) {
+    const kept = (groups || [])
+      .map((g) => ({ ...g, hooks: (g.hooks || []).filter((h) => !(typeof h.command === 'string' && h.command.includes(HOOK_MARK))) }))
+      .filter((g) => (g.hooks || []).length > 0);
+    if (kept.length) hooks[event] = kept;
+  }
+  s.hooks = hooks;
+  return s;
+}
+
+// Path helpers (also used by the IO shell in the next task).
+function claudeDir(home = homedir()) { return path.join(home, '.claude'); }
+function settingsPath(home = homedir()) { return path.join(claudeDir(home), 'settings.json'); }
+
+// 'no-claude' → ~/.claude absent (don't prompt to enable). 'installed' → our hooks present. 'absent' →
+// Claude Code is here but our hooks aren't (offer to enable).
+export function hooksStatus(home = homedir()) {
+  if (!fs.existsSync(claudeDir(home))) return 'no-claude';
+  let settings = {};
+  try { settings = JSON.parse(fs.readFileSync(settingsPath(home), 'utf8')); } catch { /* missing/corrupt → {} */ }
+  const hooks = (settings && settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)) ? settings.hooks : {};
+  return Object.keys(hooks).some((ev) => alreadyHas(hooks, ev)) ? 'installed' : 'absent';
+}
+
+const SCRIPTS = ['handmux-notify.sh', 'handmux-write.cjs'];
+
+// Atomic JSON write (tmp + rename) so a crash can't leave a half-written settings.json.
+function writeJsonAtomic(file, obj) {
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+// Install (opt-in): copy the bundled hook scripts to ~/.claude/hooks/, write the env pointing at the state
+// file, and merge our six hooks into settings.json. Returns { status }. NEVER creates ~/.claude — if it's
+// absent the user doesn't run Claude Code, so we report 'no-claude' and do nothing.
+//   srcDir   = the bundled hooks dir (server/hooks)
+//   stateFile = the unified ~/.handmux/claude-state.json path the hook writes and the server reads
+export function installHooks(home = homedir(), { srcDir, stateFile } = {}) {
+  if (!fs.existsSync(claudeDir(home))) return { status: 'no-claude' };
+  const hooksDir = path.join(claudeDir(home), 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  for (const f of SCRIPTS) fs.copyFileSync(path.join(srcDir, f), path.join(hooksDir, f));
+  fs.chmodSync(path.join(hooksDir, 'handmux-notify.sh'), 0o755);
+  fs.writeFileSync(path.join(hooksDir, 'handmux-notify.env'), `HANDMUX_STATE=${stateFile}\n`, { mode: 0o600 });
+
+  const dest = path.join(hooksDir, 'handmux-notify.sh');
+  let settings = {};
+  try { settings = JSON.parse(fs.readFileSync(settingsPath(home), 'utf8')); } catch { /* missing/corrupt → {} */ }
+  writeJsonAtomic(settingsPath(home), mergeHooks(settings, dest));
+  return { status: 'installed' };
+}
+
+// Uninstall: strip our hooks from settings.json and remove the copied scripts/env. Best-effort on the file
+// deletes (a missing file is fine). Leaves ~/.claude and the user's own hooks intact.
+export function uninstallHooks(home = homedir()) {
+  let settings = {};
+  try { settings = JSON.parse(fs.readFileSync(settingsPath(home), 'utf8')); } catch { /* nothing to strip */ }
+  if (fs.existsSync(settingsPath(home))) writeJsonAtomic(settingsPath(home), stripHooks(settings));
+  const hooksDir = path.join(claudeDir(home), 'hooks');
+  for (const f of [...SCRIPTS, 'handmux-notify.env']) {
+    try { fs.unlinkSync(path.join(hooksDir, f)); } catch { /* already gone */ }
+  }
+  return { status: 'absent' };
+}

package/src/cli/cloudflareUrl.js

@@ -0,0 +1,9 @@
+// Pure: pull the first https://<sub>.trycloudflare.com out of a cloudflared log chunk. The quick-tunnel
+// hostname is random per run, so scraping it from cloudflared's startup log is how the supervisor learns
+// the public URL. Kept tiny + side-effect-free so it unit-tests against real captured log lines.
+const RE = /https:\/\/[a-z0-9][a-z0-9-]*\.trycloudflare\.com/;
+
+export function extractCloudflareUrl(text) {
+  const m = RE.exec(String(text || ''));
+  return m ? m[0] : null;
+}

package/src/cli/cloudflared.js

@@ -0,0 +1,53 @@
+// Resolve a usable `cloudflared` binary so `--tunnel cloudflare` is truly one-click (no brew/manual
+// install). Order: $PATH → ~/.handmux/bin/ → download the latest release for this OS/arch from GitHub.
+// `which`/`fetchImpl` are injectable so the pure mapping (assetFor) unit-tests offline.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { pocketHome } from './state.js';
+
+// Map Node's platform/arch to cloudflared's release asset. Linux/Windows ship a bare binary; macOS
+// ships a .tgz that contains a `cloudflared` executable.
+export function assetFor(platform = process.platform, arch = process.arch) {
+  const a = { x64: 'amd64', arm64: 'arm64', arm: 'arm', ia32: '386' }[arch] || arch;
+  if (platform === 'darwin') return { file: `cloudflared-darwin-${a}.tgz`, archive: 'tgz', bin: 'cloudflared' };
+  if (platform === 'win32') return { file: `cloudflared-windows-${a}.exe`, archive: null, bin: 'cloudflared.exe' };
+  return { file: `cloudflared-linux-${a}`, archive: null, bin: 'cloudflared' };
+}
+
+export function onPath(exec = 'cloudflared') {
+  const finder = process.platform === 'win32' ? 'where' : 'which';
+  const r = spawnSync(finder, [exec], { encoding: 'utf8' });
+  return r.status === 0 ? String(r.stdout).trim().split(/\r?\n/)[0] : null;
+}
+
+export async function resolveCloudflared(home, { which = onPath, fetchImpl, log = console } = {}) {
+  const found = which('cloudflared');
+  if (found) return found;
+
+  const dir = path.join(pocketHome(home), 'bin');
+  const asset = assetFor();
+  const dest = path.join(dir, asset.bin);
+  if (fs.existsSync(dest)) return dest;
+
+  const doFetch = fetchImpl || globalThis.fetch;
+  if (!doFetch) throw new Error('no fetch available to download cloudflared (Node 18+ required)');
+  fs.mkdirSync(dir, { recursive: true });
+  const url = `https://github.com/cloudflare/cloudflared/releases/latest/download/${asset.file}`;
+  log.log?.(`  downloading cloudflared (${asset.file}) …`);
+  const res = await doFetch(url, { redirect: 'follow' });
+  if (!res.ok) throw new Error(`cloudflared download failed: HTTP ${res.status} (${url})`);
+  const buf = Buffer.from(await res.arrayBuffer());
+
+  if (asset.archive === 'tgz') {
+    const tmp = path.join(dir, asset.file);
+    fs.writeFileSync(tmp, buf);
+    const r = spawnSync('tar', ['xzf', tmp, '-C', dir], { encoding: 'utf8' });
+    fs.unlinkSync(tmp);
+    if (r.status !== 0) throw new Error(`failed to extract cloudflared: ${r.stderr || r.status}`);
+  } else {
+    fs.writeFileSync(dest, buf);
+  }
+  fs.chmodSync(dest, 0o755);
+  return dest;
+}

package/src/cli/drivers.js

@@ -0,0 +1,59 @@
+// Tunnel driver registry. A driver only DESCRIBES how to expose the local server (what process to spawn,
+// how to read the public URL out of its output); the supervisor owns process lifecycle (spawn, restart,
+// kill). Declarative → unit-testable without spawning. matchUrl receives (chunk, cfg): cloudflare scrapes
+// a random URL from logs; ssh / cloudflare-named already KNOW the URL (cfg.publicUrl) and only gate it on
+// a readiness signal so the QR isn't shown before the tunnel is live.
+import { extractCloudflareUrl } from './cloudflareUrl.js';
+import { isTunnelConnected } from './sshTunnel.js';
+import { cfNamedReady } from './cfNamed.js';
+
+export const DRIVERS = {
+  none: {
+    name: 'none',
+    needsProcess: false,
+    proc: () => null,
+    matchUrl: () => null,
+  },
+  cloudflare: {
+    name: 'cloudflare',
+    needsProcess: true,
+    notFoundHint: 'cloudflared not found — install it (brew install cloudflared)',
+    proc: (cfg) => ({
+      cmd: cfg.cloudflaredBin || 'cloudflared',
+      // --grace-period 0s: drop the edge connection immediately on SIGTERM instead of draining for the 30s
+      // default, so `stop`/`restart` don't leave the tunnel lingering on Cloudflare's side (it would look
+      // "still running" remotely and overlap a restart). See supervisor.shutdown for the local-process side.
+      args: ['tunnel', '--grace-period', '0s', '--url', `http://localhost:${cfg.port}`],
+    }),
+    matchUrl: (chunk) => extractCloudflareUrl(chunk),
+  },
+  'cloudflare-named': {
+    name: 'cloudflare-named',
+    needsProcess: true,
+    notFoundHint: 'cloudflared not found — run `handmux setup` to provision the named tunnel',
+    proc: (cfg) => ({
+      cmd: cfg.cloudflaredBin || 'cloudflared',
+      // --grace-period 0s goes BEFORE the `run` subcommand (it's a `cloudflared tunnel` flag). Same reason as
+      // the quick tunnel: disconnect immediately on stop so the named tunnel doesn't linger on the edge.
+      args: ['tunnel', '--grace-period', '0s', 'run', cfg.cfTunnelName],
+    }),
+    matchUrl: (chunk, cfg) => (cfNamedReady(chunk) ? cfg.publicUrl : null),
+  },
+  ssh: {
+    name: 'ssh',
+    needsProcess: true,
+    notFoundHint: 'tunlite not found — install it (npm i -g tunlite / npx tunlite install)',
+    proc: (cfg) => ({
+      cmd: cfg.tunliteBin || 'tunlite',
+      args: ['run', '--to', cfg.sshHost, '-R', `${cfg.remotePort}:localhost:${cfg.port}`,
+        '--name', 'handmux', '--json', ...(cfg.sshJump ? ['--jump', cfg.sshJump] : [])],
+    }),
+    matchUrl: (chunk, cfg) => (isTunnelConnected(chunk) ? cfg.publicUrl : null),
+  },
+};
+
+export function getDriver(name) {
+  const d = DRIVERS[name];
+  if (!d) throw new Error(`unknown tunnel: ${name}`);
+  return d;
+}

package/src/cli/options.js

@@ -0,0 +1,169 @@
+// Pure CLI option handling: a tiny hand-rolled flag parser (no dependency) + config resolution.
+// Resolution order is flags > config file > env > built-in default. The token is ALWAYS materialised
+// (generated when unset) so a public tunnel can never come up token-less.
+import crypto from 'node:crypto';
+
+export const TUNNELS = ['none', 'cloudflare', 'cloudflare-named', 'ssh'];
+
+const camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+
+// argv = process.argv.slice(2). `command` is the first bare word; flags are `--key value`,
+// `--key` (boolean true), `--no-key` (boolean false), and `-f` (alias for --foreground).
+export function parseArgs(argv) {
+  const [command = 'help', ...rest] = argv;
+  const flags = {};
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === '-f') { flags.foreground = true; continue; }
+    if (!a.startsWith('--')) continue;
+    const key = a.slice(2);
+    if (key.startsWith('no-')) { flags[camel(key.slice(3))] = false; continue; }
+    const next = rest[i + 1];
+    if (next === undefined || next.startsWith('--')) { flags[camel(key)] = true; }
+    else { flags[camel(key)] = next; i++; }
+  }
+  return { command, flags };
+}
+
+// ssh 回退公网地址:SSH 不生成 URL,无 --public-url 时用 host:remotePort(去掉 user@ 与 :sshPort)。
+export function sshPublicFallback(sshHost, remotePort) {
+  const host = String(sshHost).replace(/^[^@]*@/, '').replace(/:\d+$/, '');
+  return `http://${host}:${remotePort}`;
+}
+
+export function resolveConfig(flags = {}, fileCfg = {}, env = process.env, gen = defaultGen) {
+  const pick = (k, ...fallbacks) => {
+    for (const v of [flags[k], fileCfg[k], ...fallbacks]) if (v !== undefined && v !== null) return v;
+    return undefined;
+  };
+  const tunnel = pick('tunnel', 'none');
+  if (!TUNNELS.includes(tunnel)) throw new Error(`unknown tunnel: ${tunnel} (use: ${TUNNELS.join(', ')})`);
+
+  const port = Number(pick('port', env.HANDMUX_PORT, 19999));
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`bad port: ${pick('port', env.HANDMUX_PORT, 19999)}`);
+
+  const cfg = {
+    tunnel,
+    port,
+    name: pick('name', env.HANDMUX_APP_NAME) || null,
+    host: pick('host', env.HANDMUX_HOST, '0.0.0.0'),
+    token: pick('token', env.HANDMUX_TOKEN) || gen(),
+    previewDomain: pick('previewDomain', env.HANDMUX_PREVIEW_DOMAIN) || null,
+    foreground: !!pick('foreground', false),
+    qr: pick('qr', true) !== false,
+    // Unified config — what used to live in .env. The supervisor injects these into the server child's
+    // environment (HANDMUX_STATIC_DIR / VAPID_* / XFYUN_* …), which is exactly where the server reads them.
+    staticDir: pick('staticDir', env.HANDMUX_STATIC_DIR) || null,
+    uploadExts: pick('uploadExts', env.HANDMUX_UPLOAD_EXTS) || null,
+    previewTtl: pick('previewTtl', env.HANDMUX_PREVIEW_TTL) || null,
+    vapid: fileCfg.vapid || null,   // { public, private, subject } — push notifications
+    xfyun: fileCfg.xfyun || null,   // { appId, apiKey, apiSecret } — voice input
+    // An explicit public URL is honoured for ANY tunnel mode — including 'none', so someone who runs their
+    // own tunnel/reverse-proxy can still have handmux advertise (print + QR) their real domain. The
+    // tunnel-specific blocks below only fill a *fallback* when it wasn't given.
+    //
+    // Guard: a publicUrl in the FILE was set for the file's tunnel, so it only carries over when the
+    // resolved tunnel still matches (or the file pins no tunnel). Otherwise a `--tunnel B` override would
+    // advertise tunnel A's URL. A flag/env publicUrl is explicit for THIS run and always wins.
+    publicUrl: resolvePublicUrl(flags, fileCfg, env, tunnel),
+    // tunnel-specific (null unless the relevant tunnel is selected)
+    sshHost: null, remotePort: null, sshJump: null,
+    cfHostname: null, cfTunnelName: null,
+  };
+
+  if (tunnel === 'ssh') {
+    cfg.sshHost = pick('sshHost', env.HANDMUX_SSH_HOST) || null;
+    if (!cfg.sshHost) throw new Error('ssh tunnel needs --ssh-host user@host (or HANDMUX_SSH_HOST)');
+    const rp = Number(pick('remotePort', env.HANDMUX_REMOTE_PORT, port));
+    if (!Number.isInteger(rp) || rp < 1 || rp > 65535) throw new Error(`bad remote-port: ${pick('remotePort', env.HANDMUX_REMOTE_PORT, port)}`);
+    cfg.remotePort = rp;
+    cfg.sshJump = pick('sshJump', env.HANDMUX_SSH_JUMP) || null;
+    cfg.publicUrl = cfg.publicUrl || sshPublicFallback(cfg.sshHost, rp);
+  }
+
+  if (tunnel === 'cloudflare-named') {
+    cfg.cfHostname = pick('cfHostname', env.HANDMUX_CF_HOSTNAME) || null;
+    if (!cfg.cfHostname) throw new Error('cloudflare-named needs --cf-hostname handmux.example.com (or HANDMUX_CF_HOSTNAME)');
+    cfg.cfTunnelName = pick('cfTunnelName', env.HANDMUX_CF_TUNNEL_NAME) || 'handmux';
+    cfg.publicUrl = cfg.publicUrl || `https://${cfg.cfHostname}`;
+  }
+
+  return cfg;
+}
+
+// publicUrl resolution with the cross-tunnel guard (see resolveConfig). flag > file(if tunnel matches) > env.
+function resolvePublicUrl(flags, fileCfg, env, tunnel) {
+  if (flags.publicUrl != null) return flags.publicUrl;
+  const fileTunnel = fileCfg.tunnel;
+  const fileApplies = fileTunnel == null || fileTunnel === tunnel;
+  if (fileApplies && fileCfg.publicUrl != null) return fileCfg.publicUrl;
+  if (env.HANDMUX_PUBLIC_URL != null) return env.HANDMUX_PUBLIC_URL;
+  return null;
+}
+
+// Default token: 8 chars from a typing-friendly alphabet (lowercase + digits, look-alikes 0/o/1/l dropped)
+// so it's quick to thumb in on a phone. A user-supplied token (flag/config/env) is used verbatim — any
+// length, never regenerated. 8 chars over a 32-char alphabet ≈ 40 bits, fine for a single secret URL.
+const TOKEN_ALPHABET = '23456789abcdefghijkmnpqrstuvwxyz';
+function defaultGen() {
+  let s = '';
+  for (let i = 0; i < 8; i++) s += TOKEN_ALPHABET[crypto.randomInt(TOKEN_ALPHABET.length)];
+  return s;
+}
+
+// Trace one key's value back to its source through the same flag > file > env > default precedence
+// resolveConfig uses. `null`/`undefined` at a layer is "unset" (skip), matching pick(). Returns the
+// winning value and a human origin label (the file path for a file hit, so the user sees exactly where).
+function trace(flags, fileCfg, env, cfgPath, key, envKey, def) {
+  if (flags[key] != null) return { value: flags[key], origin: 'flag' };
+  if (fileCfg[key] != null) return { value: fileCfg[key], origin: cfgPath || 'file' };
+  if (envKey && env[envKey] != null) return { value: env[envKey], origin: 'env' };
+  return { value: def, origin: 'default' };
+}
+
+// Build the rows for `handmux config`: the value each key WOULD resolve to plus where it came from.
+// Lenient (never throws — unlike resolveConfig — so a half-finished config still prints) and secret-safe
+// (token masked; push/voice shown only as on/off). Tunnel-specific rows appear only for the live tunnel.
+export function explainConfig(flags = {}, fileCfg = {}, cfgPath = null, env = process.env) {
+  const rows = [];
+  const mask = (s) => (String(s).length <= 8 ? '••••' : `••••${String(s).slice(-4)}`);
+  const add = (key, t, display) => rows.push({ key, origin: t.origin, display: display ?? String(t.value) });
+
+  const tunnel = trace(flags, fileCfg, env, cfgPath, 'tunnel', null, 'none');
+  add('tunnel', tunnel);
+  add('port', trace(flags, fileCfg, env, cfgPath, 'port', 'HANDMUX_PORT', 19999));
+  add('host', trace(flags, fileCfg, env, cfgPath, 'host', 'HANDMUX_HOST', '0.0.0.0'));
+
+  const name = trace(flags, fileCfg, env, cfgPath, 'name', 'HANDMUX_APP_NAME', null);
+  add('name', name, name.value == null ? '(default)' : String(name.value));
+
+  const token = trace(flags, fileCfg, env, cfgPath, 'token', 'HANDMUX_TOKEN', null);
+  add('token', token, token.value == null ? '(generated each start)' : mask(token.value));
+
+  // publicUrl honours the same cross-tunnel guard as resolveConfig (file value only when tunnel matches).
+  const t = tunnel.value;
+  let pub = trace(flags, fileCfg, env, cfgPath, 'publicUrl', 'HANDMUX_PUBLIC_URL', null);
+  if (pub.origin !== 'flag' && pub.origin !== 'env' && fileCfg.tunnel != null && fileCfg.tunnel !== t) {
+    pub = { value: null, origin: 'default' };
+  }
+  add('publicUrl', pub, pub.value == null ? '(none — derived from tunnel if any)' : String(pub.value));
+
+  const preview = trace(flags, fileCfg, env, cfgPath, 'previewDomain', 'HANDMUX_PREVIEW_DOMAIN', null);
+  add('previewDomain', preview, preview.value == null ? '(off)' : String(preview.value));
+
+  if (t === 'ssh') {
+    add('sshHost', trace(flags, fileCfg, env, cfgPath, 'sshHost', 'HANDMUX_SSH_HOST', null));
+    add('remotePort', trace(flags, fileCfg, env, cfgPath, 'remotePort', 'HANDMUX_REMOTE_PORT', '(= port)'));
+    const jump = trace(flags, fileCfg, env, cfgPath, 'sshJump', 'HANDMUX_SSH_JUMP', null);
+    add('sshJump', jump, jump.value == null ? '(none)' : String(jump.value));
+  }
+  if (t === 'cloudflare-named') {
+    add('cfHostname', trace(flags, fileCfg, env, cfgPath, 'cfHostname', 'HANDMUX_CF_HOSTNAME', null));
+    add('cfTunnelName', trace(flags, fileCfg, env, cfgPath, 'cfTunnelName', 'HANDMUX_CF_TUNNEL_NAME', 'handmux'));
+  }
+
+  // Integrations live only in the file (secrets); show presence, never the keys.
+  rows.push({ key: 'push (vapid)', origin: fileCfg.vapid ? (cfgPath || 'file') : 'default', display: fileCfg.vapid ? 'on' : 'off' });
+  rows.push({ key: 'voice (xfyun)', origin: fileCfg.xfyun ? (cfgPath || 'file') : 'default', display: fileCfg.xfyun ? 'on' : 'off' });
+  return rows;
+}

package/src/cli/probe.js

@@ -0,0 +1,16 @@
+// Read-only reachability check: after the tunnel reports live, GET the public URL from THIS machine to
+// confirm the whole chain (edge/reverse-proxy → tunnel → server) actually answers. Touches no remote
+// config — it just fills the "tunnel connected but page won't load" blind spot.
+export async function probe(url, { fetchImpl = globalThis.fetch, timeoutMs = 6000 } = {}) {
+  if (!url) return false;
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    await fetchImpl(url, { method: 'GET', redirect: 'manual', signal: ac.signal });
+    return true;            // any HTTP response (even 401/404) means the chain is reachable
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(t);
+  }
+}