handmux 0.5.2 → 0.6.0

package/README.md

@@ -72,6 +72,24 @@ handmux setup                       # or configure tunnel + name + notifications
 The printed links are token-free — safe to screenshot or share. Only the **QR** carries the token, and
 the `🔑 token` line is your password: paste it to sign in when you open a plain link instead of scanning.
 
+### On Windows? Use WSL2
+
+handmux drives **tmux**, which is Unix-only — there's no native Windows build. Run it inside **WSL2**
+(a real Linux kernel with real tmux) and everything above works unchanged:
+
+```powershell
+wsl --install     # one-time, in PowerShell (admin): installs WSL2 + Ubuntu, then reboot
+```
+
+Then open the Ubuntu terminal and follow the steps above (`apt install tmux`, install Node,
+`npm i -g handmux`). Two WSL-specific notes:
+
+- **Use a tunnel.** WSL2 is a NAT'd VM with its own IP, so the same-wifi LAN URL won't reach your
+  phone. Start with `handmux start --tunnel cloudflare` — the public link works regardless.
+- **Autostart needs systemd.** `handmux service` uses systemd; enable it once by adding
+  `[boot]` / `systemd=true` to `/etc/wsl.conf`, then `wsl --shutdown`. Without it, just run
+  `handmux start` in a terminal you keep open.
+
 ## Features
 
 Not just a remote shell — a full **mobile cockpit** for your terminal and your coding agents.

package/README.zh-CN.md

@@ -65,6 +65,22 @@ handmux setup                       # 或一次性配好隧道 + 名称 + 通知
 打印出来的明文链接不带 token,可安全截图/分享。只有**二维码**带 token;`🔑 token` 那行就是你的密码——
 开明文链接时把它粘进去就能登录。
 
+### Windows 用户?装进 WSL2
+
+handmux 靠 **tmux** 驱动,而 tmux 只有 Unix 版、没有原生 Windows 版。装进 **WSL2**(真正的 Linux 内核
++ 真 tmux),上面的一切原样适用:
+
+```powershell
+wsl --install     # 一次性,在 PowerShell(管理员)里:装好 WSL2 + Ubuntu,然后重启
+```
+
+然后打开 Ubuntu 终端,按上面的步骤来(`apt install tmux`、装 Node、`npm i -g handmux`)。两点 WSL 专属提醒:
+
+- **务必走隧道。** WSL2 是带独立 IP 的 NAT 虚拟机,同 wifi 的局域网地址手机连不到。直接用
+  `handmux start --tunnel cloudflare`,公网链接不受影响。
+- **自启需要 systemd。** `handmux service` 依赖 systemd;在 `/etc/wsl.conf` 里加 `[boot]` /
+  `systemd=true` 再 `wsl --shutdown` 启用一次即可。不启用的话,开个终端跑 `handmux start` 并保持窗口即可。
+
 ## 功能
 
 不止是个远程 shell——是给终端和你的编码 agent 配的一整个**手机驾驶舱**。

package/bin/handmux.js

@@ -31,8 +31,11 @@ import { checkTmux, MIN_TMUX, tmuxInstallHint } from '../src/cli/tmuxVersion.js'
 import { readState, clearState, isAlive, pocketHome, logPath, configPath, claudeStatePath } from '../src/cli/state.js';
 import { runSetup } from '../src/cli/setupWizard.js';
 import { hooksStatus, installHooks, uninstallHooks } from '../src/cli/claudeHooks.js';
+import { codexHooksStatus, installCodexHooks, uninstallCodexHooks } from '../src/cli/codexHooks.js';
 import { tmuxDotStatus, installTmuxDot, tmuxConfPath } from '../src/cli/tmuxConf.js';
 import { probe } from '../src/cli/probe.js';
+import { notifyUpdate, runUpdateCheck, PKG_NAME } from '../src/cli/updateCheck.js';
+import { t, initLocale, setLocale } from '../src/cli/i18n/index.js';
 
 const HOME = homedir();
 const SELF = fileURLToPath(import.meta.url);
@@ -41,6 +44,17 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
 const { command, flags } = parseArgs(process.argv.slice(2));
 
+// Resolve the CLI language ONCE, up front, so every command (help, errors, access block) prints in it.
+// Priority: --lang > config `lang` > shell locale (LANG/LC_*) > English. The config peek is lenient — a
+// missing/broken file just means "no language hint here"; the real validation happens per-command later.
+function peekConfigLang() {
+  try {
+    const p = flags.config ? path.resolve(flags.config) : configPath(HOME);
+    return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : {};
+  } catch { return {}; }
+}
+initLocale(flags, peekConfigLang(), process.env);
+
 // There is ONE config file location: ~/.handmux/config.json (written by `handmux setup`). `--config PATH`
 // points elsewhere — that's the only escape, and it covers dev/multi-config without any cwd magic (a
 // stray ./config.json never gets picked up silently). No file merging or inheritance: at most one file is
@@ -51,19 +65,32 @@ function resolveFileConfig() {
   let p = null;
   if (flags.config) {                                              // explicit: must exist
     p = path.resolve(flags.config);
-    if (!fs.existsSync(p)) { console.error(`✗ --config ${p}: not found`); process.exit(2); }
+    if (!fs.existsSync(p)) { console.error(t('err.configNotFound', { path: p })); process.exit(2); }
   } else {
     const homeP = configPath(HOME);
     if (fs.existsSync(homeP)) p = homeP;
   }
   if (!p) return { path: null, cfg: {} };
   try { return { path: p, cfg: JSON.parse(fs.readFileSync(p, 'utf8')) }; }
-  catch (e) { console.error(`✗ bad config ${p}: ${e.message}`); process.exit(2); }
+  catch (e) { console.error(t('err.badConfig', { path: p, msg: e.message })); process.exit(2); }
 }
 
 // Human-readable summary of which config file a run loaded.
 function describeConfig(p) {
-  return p || '(none — flags + defaults)';
+  return p || t('config.none');
+}
+
+// Which user-visible settings THIS run would use differ from what's already running (from state.json)?
+// Kept to the two people actually re-run `start` to change — the tunnel and the port; each row is ready to
+// drop straight into the `start.running.changedRow` message ({key, from, to}). Only compares fields the
+// running state actually recorded, so an older state.json can't manufacture phantom diffs.
+function configChanges(cfg, st) {
+  const out = [];
+  for (const key of ['tunnel', 'port']) {
+    const running = st[key];
+    if (running != null && String(cfg[key]) !== String(running)) out.push({ key, from: running, to: cfg[key] });
+  }
+  return out;
 }
 
 // 一次性 [Y/n] 提问(默认 Yes)。非 TTY 直接返回 false,绝不卡住。
@@ -80,11 +107,11 @@ async function confirm(question) {
 async function preflightSsh(cfg) {
   cfg.tunliteBin = resolveTunlite();                 // 抛出 → 调用方打印并退出
   if (checkSshAuth(cfg.sshHost, { bin: cfg.tunliteBin }) === 0) return;
-  if (process.stdin.isTTY && await confirm(`passwordless SSH to ${cfg.sshHost} is not set up. Configure it now?`)) {
+  if (process.stdin.isTTY && await confirm(t('ssh.confirmSetup', { host: cfg.sshHost }))) {
     spawnSync(cfg.tunliteBin, ['setup-key', cfg.sshHost], { stdio: 'inherit' });
     if (checkSshAuth(cfg.sshHost, { bin: cfg.tunliteBin }) === 0) return;
   }
-  throw new Error(`passwordless SSH not set up — run: ${cfg.tunliteBin} setup-key ${cfg.sshHost}`);
+  throw new Error(t('ssh.notSetup', { bin: cfg.tunliteBin, host: cfg.sshHost }));
 }
 
 async function main() {
@@ -98,7 +125,9 @@ async function main() {
     case 'setup': return setupCmd();
     case 'hooks': return hooksCmd();
     case 'service': return serviceCmd();
+    case 'update': case 'upgrade': return updateCmd();
     case '__supervise': return runSupervise();
+    case '__update-check': return runUpdateCheck(HOME);
     case 'version': case '--version': case '-v': return version();
     default: return help();
   }
@@ -110,59 +139,97 @@ function version() {
   console.log(requireOpt('../package.json').version);
 }
 
+// `handmux update` (alias `upgrade`) — run the plain global install for the user. We don't self-patch or
+// restart a running instance; on success we refresh the update cache so the "upgrade available" notice
+// clears, and remind them to `handmux restart` to actually run the new code.
+function updateCmd() {
+  console.log(t('update.running'));
+  const r = spawnSync('npm', ['install', '-g', `${PKG_NAME}@latest`], { stdio: 'inherit' });
+  if (r.status === 0) {
+    runUpdateCheck(HOME);
+    console.log(t('update.done'));
+    console.log(t('update.restartHint'));
+  } else {
+    console.log(t('update.failed', { pkg: PKG_NAME }));
+    process.exitCode = 1;
+  }
+}
+
+// Best-effort upgrade notice from the cached "latest version" (never blocks; refreshes in the background).
+function maybeNotifyUpdate() {
+  notifyUpdate(HOME, { version: requireOpt('../package.json').version, selfPath: SELF });
+}
+
 async function start() {
   const { path: cfgPath, cfg: fileCfg } = resolveFileConfig();
-  console.log(`config: ${describeConfig(cfgPath)}`);
+  console.log(t('config.loaded', { path: describeConfig(cfgPath) }));
   let cfg;
   try { cfg = resolveConfig(flags, fileCfg); }
-  catch (e) { console.error(`✗ ${e.message}`); process.exit(2); }
-
-  // Make a one-run tunnel override visible: it's easy to forget a --tunnel flag is shadowing the file.
-  if (flags.tunnel && fileCfg.tunnel && flags.tunnel !== fileCfg.tunnel) {
-    console.log(`  ↳ --tunnel ${flags.tunnel} overrides config (${fileCfg.tunnel}) for this run only`);
-  }
+  catch (e) { console.error(t('err.generic', { msg: e.message })); process.exit(2); }
 
   // tmux is the whole point — absent is fatal; an untested-old version only warns (rendering may drift).
   const tmux = checkTmux();
   if (!tmux.present) {
-    console.error('✗ tmux not found.');
-    console.error('  handmux runs on top of tmux (a terminal multiplexer) — it drives your real tmux');
-    console.error('  panes from your phone, so you need tmux on this machine first.');
+    console.error(t('tmux.notFound'));
+    console.error(t('tmux.explain1'));
+    console.error(t('tmux.explain2'));
     console.error('');
-    console.error(`  Install it:  ${tmuxInstallHint()}`);
-    console.error('  Then run `handmux start` again.');
+    console.error(t('tmux.install', { hint: tmuxInstallHint() }));
+    console.error(t('tmux.thenStart'));
     process.exit(1);
   }
-  if (!tmux.ok) console.warn(`⚠ tmux ${tmux.raw} is below the tested minimum ${MIN_TMUX}; terminal rendering may be off`);
+  if (!tmux.ok) console.warn(t('tmux.tooOld', { raw: tmux.raw, min: MIN_TMUX }));
 
+  // Already running? `start` never disrupts a live instance on its own. If this run's config matches
+  // what's running, just reassure + reprint the address. If it DIFFERS (e.g. you changed the tunnel and
+  // re-ran `start` expecting it to apply), spell out the difference and — interactively — offer to restart
+  // into it; otherwise point at `handmux restart`. The principle stays intact: we only restart on an
+  // explicit yes.
   const existing = readState(HOME);
   if (existing && isAlive(existing.supervisorPid)) {
-    console.log(`handmux already running (pid ${existing.supervisorPid}) — use 'handmux restart'`);
+    const changed = configChanges(cfg, existing);
+    if (!changed.length) {
+      console.log(t('start.running.same'));
+      await printAccess(existing);
+      return;
+    }
+    console.log(t('start.running.changedHead', { tunnel: existing.tunnel }));
+    for (const c of changed) console.log(t('start.running.changedRow', c));
+    if (process.stdin.isTTY && await confirm(t('start.running.switchQ'))) {
+      stop(); await sleep(600); return start();
+    }
+    console.log(t('start.running.hint'));
     await printAccess(existing);
     return;
   }
 
+  // Make a one-run tunnel override visible (printed only now that we're actually starting, so it can't be
+  // mistaken for a switch when the instance was already running): a --tunnel flag shadowing the file.
+  if (flags.tunnel && fileCfg.tunnel && flags.tunnel !== fileCfg.tunnel) {
+    console.log(t('start.overrides', { flag: flags.tunnel, file: fileCfg.tunnel }));
+  }
+
   // cloudflare needs a cloudflared binary; resolve (and auto-download) it up front so the failure is a
   // clear message here rather than a silent child that never prints a URL.
   if (cfg.tunnel === 'cloudflare') {
     try { cfg.cloudflaredBin = await resolveCloudflared(HOME); }
-    catch (e) { console.error(`✗ ${e.message}`); process.exit(1); }
+    catch (e) { console.error(t('err.generic', { msg: e.message })); process.exit(1); }
   }
   if (cfg.tunnel === 'cloudflare-named') {
     try { cfg.cloudflaredBin = await resolveCloudflared(HOME); }
-    catch (e) { console.error(`✗ ${e.message}`); process.exit(1); }
+    catch (e) { console.error(t('err.generic', { msg: e.message })); process.exit(1); }
     if (!fs.existsSync(path.join(HOME, '.cloudflared', 'config.yml'))) {
-      console.error('✗ named tunnel not provisioned — run `handmux setup` first'); process.exit(1);
+      console.error(t('err.namedNotProvisioned')); process.exit(1);
     }
   }
   if (cfg.tunnel === 'ssh') {
     try { await preflightSsh(cfg); }
-    catch (e) { console.error(`✗ ${e.message}`); process.exit(1); }
+    catch (e) { console.error(t('err.generic', { msg: e.message })); process.exit(1); }
   }
 
   if (cfg.foreground) {
     supervise(cfg, { home: HOME });
-    console.log(`starting handmux (tunnel: ${cfg.tunnel}, port: ${cfg.port}) — Ctrl-C to stop`);
+    console.log(t('start.foreground', { tunnel: cfg.tunnel, port: cfg.port }));
     await waitAndPrint(false);
     return;
   }
@@ -173,21 +240,21 @@ async function start() {
   const child = spawn(process.execPath, [SELF, '__supervise', '--payload', payload],
     { detached: true, stdio: ['ignore', out, out] });
   child.unref();
-  console.log(`starting handmux (tunnel: ${cfg.tunnel}, port: ${cfg.port}) …`);
+  console.log(t('start.starting', { tunnel: cfg.tunnel, port: cfg.port }));
   await waitAndPrint(true);
 }
 
 function stop() {
   const st = readState(HOME);
-  if (!st || !isAlive(st.supervisorPid)) { console.log('handmux not running'); clearState(HOME); return; }
+  if (!st || !isAlive(st.supervisorPid)) { console.log(t('stop.notRunning')); clearState(HOME); return; }
   try { process.kill(st.supervisorPid, 'SIGTERM'); } catch { /* race: already gone */ }
-  console.log(`stopped handmux (pid ${st.supervisorPid})`);
+  console.log(t('stop.stopped', { pid: st.supervisorPid }));
 }
 
 async function status() {
   const st = readState(HOME);
-  if (!st || !isAlive(st.supervisorPid)) { console.log('● handmux stopped'); return; }
-  console.log('● handmux running');
+  if (!st || !isAlive(st.supervisorPid)) { console.log(t('status.stopped')); return; }
+  console.log(t('status.running'));
   await printAccess(st);
 }
 
@@ -198,7 +265,7 @@ function runSupervise() {
 
 function logs() {
   const p = logPath(HOME);
-  if (!fs.existsSync(p)) { console.log('(no log yet — start handmux first)'); return; }
+  if (!fs.existsSync(p)) { console.log(t('logs.none')); return; }
   const lines = String(flags.lines || 200);
   const args = flags.follow ? ['-n', lines, '-f', p] : ['-n', lines, p];
   spawn('tail', args, { stdio: 'inherit' });
@@ -212,50 +279,50 @@ async function serviceCmd() {
   if (sub === 'install') return serviceInstall();
   if (sub === 'uninstall') {
     try { uninstallService({ home: HOME }); }
-    catch (e) { console.error(`✗ ${e.message}`); process.exit(1); }
+    catch (e) { console.error(t('err.generic', { msg: e.message })); process.exit(1); }
     return;
   }
-  console.error('usage: handmux service install [start-flags] | handmux service uninstall');
+  console.error(t('service.usage'));
   process.exit(2);
 }
 
 async function serviceInstall() {
   const { path: cfgPath, cfg: fileCfg } = resolveFileConfig();
-  console.log(`config: ${describeConfig(cfgPath)}`);
+  console.log(t('config.loaded', { path: describeConfig(cfgPath) }));
   let cfg;
   try { cfg = resolveConfig(flags, fileCfg); }
-  catch (e) { console.error(`✗ ${e.message}`); process.exit(2); }
+  catch (e) { console.error(t('err.generic', { msg: e.message })); process.exit(2); }
   if (cfg.tunnel === 'cloudflare' || cfg.tunnel === 'cloudflare-named') {
     try { cfg.cloudflaredBin = await resolveCloudflared(HOME); }
-    catch (e) { console.error(`✗ ${e.message}`); process.exit(1); }
+    catch (e) { console.error(t('err.generic', { msg: e.message })); process.exit(1); }
   }
   if (cfg.tunnel === 'ssh') {
     // 开机自启无 TTY:要求事先已配好免密,否则快速失败。
     cfg.tunliteBin = resolveTunlite();
     if (checkSshAuth(cfg.sshHost, { bin: cfg.tunliteBin }) !== 0) {
-      console.error(`✗ passwordless SSH not set up — run: ${cfg.tunliteBin} setup-key ${cfg.sshHost}`); process.exit(1);
+      console.error(t('err.generic', { msg: t('ssh.notSetup', { bin: cfg.tunliteBin, host: cfg.sshHost }) })); process.exit(1);
     }
   }
   const payload = Buffer.from(JSON.stringify(cfg)).toString('base64');
   const args = [process.execPath, SELF, '__supervise', '--payload', payload];
   try { installService(args, { home: HOME }); }
-  catch (e) { console.error(`✗ ${e.message}`); process.exit(1); }
-  console.log("handmux will now start at login. 'handmux service uninstall' to remove.");
+  catch (e) { console.error(t('err.generic', { msg: e.message })); process.exit(1); }
+  console.log(t('service.installed'));
 }
 
 async function setupCmd() {
   const target = flags.config ? path.resolve(flags.config) : configPath(HOME);
   const cfg = await runSetup({ home: HOME, target });
   if (!cfg) { process.exit(2); }
-  const hs = hooksStatus(HOME);
-  if (hs !== 'no-claude' && hs !== 'installed'
-      && await confirm('Enable Claude Code notifications (inbox)?')) {
-    installHooks(HOME, { srcDir: HOOKS_SRC, stateFile: claudeStatePath(HOME) });
-    console.log('✓ Claude hooks installed.');
+  // Offer to enable the inbox hooks when an agent is present but not yet wired (Claude 'absent', or Codex
+  // 'absent'). installAgentHooks() then wires every present agent (idempotent for any already installed).
+  const offerHooks = hooksStatus(HOME) === 'absent' || codexHooksStatus(HOME) === 'absent';
+  if (offerHooks && await confirm(t('hooks.confirmEnable'))) {
+    installAgentHooks();
     await maybeOfferTmuxDot();
   }
-  if (await confirm('Start handmux now?')) { Object.assign(flags, cfg); return start(); }
-  console.log("run 'handmux start' when you're ready.");
+  if (await confirm(t('setup.confirmStart'))) { Object.assign(flags, cfg); return start(); }
+  console.log(t('setup.later'));
 }
 
 // The per-window tmux status dot is the natural companion to the inbox hooks: the hook already writes a
@@ -265,37 +332,55 @@ async function setupCmd() {
 async function maybeOfferTmuxDot() {
   if (tmuxDotStatus(HOME) !== 'absent') return;
   if (!process.stdin.isTTY) {
-    console.log(`  Tip: to show a Claude status dot on each tmux window, run \`handmux hooks install\` from an interactive terminal — it wires ${tmuxConfPath(HOME)} for you (see tmux/README.md in the handmux package).`);
+    console.log(t('tmuxdot.tip', { conf: tmuxConfPath(HOME) }));
     return;
   }
-  if (await confirm('Also show a per-window Claude status dot in tmux? (adds a block to ~/.tmux.conf)')) {
+  if (await confirm(t('tmuxdot.confirm'))) {
     installTmuxDot(HOME);
-    console.log(`✓ tmux dot added → ${tmuxConfPath(HOME)}`);
-    console.log('  Apply with: tmux source-file ~/.tmux.conf  (it changes the shared tmux server — all clients, including your PC).');
+    console.log(t('tmuxdot.added', { path: tmuxConfPath(HOME) }));
+    console.log(t('tmuxdot.apply'));
   }
 }
 
-// `handmux hooks install|uninstall` — opt-in wiring of the Claude Code lifecycle hooks that drive the
-// inbox/push. Never creates ~/.claude; if Claude Code isn't present we say so and exit 0 (nothing to do).
+// Install the inbox hooks for every coding agent present on this host (Claude Code, Codex — the state file
+// is shared, entries are agent-tagged). Each is opt-in by the mere presence of its config dir. Prints a
+// per-agent line and returns how many were wired, so callers can gate the tmux-dot offer / the "reload"
+// hint. Codex's single `notify` slot may already hold the user's OWN program — we never clobber it, we warn.
+function installAgentHooks() {
+  let installed = 0;
+  if (hooksStatus(HOME) !== 'no-claude') {
+    installHooks(HOME, { srcDir: HOOKS_SRC, stateFile: claudeStatePath(HOME) });
+    console.log(t('hooks.installedClaude'));
+    installed++;
+  }
+  if (codexHooksStatus(HOME) !== 'no-codex') {
+    installCodexHooks(HOME, { srcDir: HOOKS_SRC, stateFile: claudeStatePath(HOME) });
+    console.log(t('hooks.installedCodex'));
+    installed++;
+  }
+  return installed;
+}
+
+// `handmux hooks install|uninstall` — opt-in wiring of the coding-agent lifecycle hooks that drive the
+// inbox/push. Never creates ~/.claude or ~/.codex; if neither agent is present we say so and exit 0.
 async function hooksCmd() {
   const sub = process.argv[3];
   if (sub === 'install') {
-    if (hooksStatus(HOME) === 'no-claude') {
-      console.log('Claude Code not detected (~/.claude missing) — nothing to install.');
+    if (hooksStatus(HOME) === 'no-claude' && codexHooksStatus(HOME) === 'no-codex') {
+      console.log(t('hooks.noAgents'));
       return;
     }
-    installHooks(HOME, { srcDir: HOOKS_SRC, stateFile: claudeStatePath(HOME) });
-    console.log('✓ Claude hooks installed → ~/.claude/settings.json');
-    console.log('  Restart or open a new Claude Code session to load them; the inbox lights up as panes report.');
+    if (installAgentHooks() > 0) console.log(t('hooks.installedHint'));
     await maybeOfferTmuxDot();
     return;
   }
   if (sub === 'uninstall') {
     uninstallHooks(HOME);
-    console.log('✓ Claude hooks removed.');
+    uninstallCodexHooks(HOME);
+    console.log(t('hooks.removed'));
     return;
   }
-  console.error('usage: handmux hooks install|uninstall');
+  console.error(t('hooks.usage'));
   process.exit(2);
 }
 
@@ -306,15 +391,15 @@ function configCmd() {
   const { path: cfgPath, cfg: fileCfg } = resolveFileConfig();
   let rows;
   try { rows = explainConfig(flags, fileCfg, cfgPath); }
-  catch (e) { console.error(`✗ ${e.message}`); process.exit(2); }
-  console.log(`config file: ${cfgPath || '(none — using defaults; run `handmux setup` to create one)'}`);
+  catch (e) { console.error(t('err.generic', { msg: e.message })); process.exit(2); }
+  console.log(t('configcmd.file', { path: cfgPath || t('configcmd.fileNone') }));
   console.log('');
   const w = Math.max(...rows.map((r) => r.key.length));
   for (const r of rows) {
     console.log(`  ${r.key.padEnd(w)}  ${r.display}  ${r.origin === 'default' ? '' : `· ${r.origin}`}`.trimEnd());
   }
   console.log('');
-  console.log('  origin: flag (this run only) · file · env · default');
+  console.log(t('configcmd.legend'));
 }
 
 // Poll state.json until the public URL (or an error) shows up, then print access info. cloudflare needs
@@ -334,26 +419,27 @@ async function waitAndPrint(exitWhenDone) {
 }
 
 async function printAccess(st) {
-  if (!st) { console.log('  (no state)'); return; }
-  if (st.error) { console.error(`  ✗ ${st.error}`); return; }
+  if (!st) { console.log(t('access.noState')); return; }
+  if (st.error) { console.error(t('access.error', { msg: st.error })); return; }
   const scan = bareUrl(st.publicUrl);
   console.log('');
-  console.log(`  tunnel   ${st.tunnel}   ·   pid ${st.supervisorPid}`);
-  console.log(`  🌐 open   ${scan || '(pending…)'}`);
-  if (st.tunnel === 'none' && st.lanUrl) console.log(`  📶 lan    ${bareUrl(st.lanUrl)}`);
-  console.log(`  💻 local  ${bareUrl(st.localUrl)}`);
-  console.log(`  🔑 token  ${st.token}`);
+  console.log(t('access.tunnel', { tunnel: st.tunnel, pid: st.supervisorPid }));
+  console.log(t('access.open', { url: scan || t('access.pending') }));
+  if (st.tunnel === 'none' && st.lanUrl) console.log(t('access.lan', { url: bareUrl(st.lanUrl) }));
+  console.log(t('access.local', { url: bareUrl(st.localUrl) }));
+  console.log(t('access.token', { token: st.token }));
   // The QR carries the token so a phone scan signs in one-tap; the PRINTED links above stay token-free
   // (safe to screenshot/share — paste the token shown above to sign in there).
   await maybeQr(st.publicUrl ? publicUrlWithToken(st.publicUrl, st.token) : scan, st);
   if (st.publicUrl && st.tunnel !== 'none') {
     const ok = await probe(st.publicUrl);
-    if (ok) console.log('  ✓ reachable');
-    else console.log(`  ⚠ tunnel up but ${st.publicUrl} did not answer — check the server-side reverse proxy / DNS`);
+    if (ok) console.log(t('access.reachable'));
+    else console.log(t('access.unreachable', { url: st.publicUrl }));
   }
   console.log('');
-  console.log(`  handmux status | stop`);
+  console.log(t('access.hint'));
   console.log('');
+  maybeNotifyUpdate();
 }
 
 // Best-effort QR (optional dependency). We borrow qrcode-terminal's QR *model* (vendored, dependency-free)
@@ -377,41 +463,7 @@ async function maybeQr(url, st) {
 }
 
 function help() {
-  console.log(`handmux — drive your tmux from your phone
-
-  handmux start            run it (defaults to LAN-only; no config needed)
-  handmux setup            configure tunnel / name / notifications (writes config; re-run to change)
-  handmux stop | restart | status
-  handmux logs [--follow] [--lines N]
-
-The model: 'start' runs · 'setup' configures (writes ~/.handmux/config.json) · re-run setup to change.
-A flag overrides one value for one run and never persists (flag > file > default).
-
-advanced (scripting / multiple configs):
-  handmux config                        show the effective config + where each value came from
-  handmux hooks install|uninstall         enable/disable Claude Code notifications (inbox)
-  handmux service install [start-flags]   start at login (launchd/systemd)
-  handmux service uninstall               remove the autostart entry
-  --config PATH             use this config file instead of ~/.handmux/config.json (dev / multi-config)
-  --version, -v            print the handmux version
-
-start flags (one-run overrides — for persistence use 'handmux setup'):
-  --tunnel none|cloudflare|cloudflare-named|ssh   expose method (default: none)
-  --ssh-host user@host[:port]   ssh tunnel target (tunlite)
-  --remote-port N               port bound on the ssh host (default: --port)
-  --public-url URL              public url to advertise (any tunnel, incl. none if you run your own;
-                                ssh defaults to http://host:remotePort)
-  --ssh-jump u@h[,…]            optional bastion for ssh
-  --cf-hostname H               public hostname for cloudflare-named
-  --cf-tunnel-name N            tunnel name for cloudflare-named (default: handmux)
-  --port N                  server port (default: 19999)
-  --host H                  bind host (default: 0.0.0.0)
-  --token S                 auth token (default: generated)
-  --name "My Box"           app name in the browser tab + home-screen icon label
-  --preview-domain D        enable dynamic previews (needs wildcard subdomain)
-  --foreground, -f          run in the foreground (don't daemonize)
-  --no-qr                   don't render the QR code
-`);
+  console.log(t('help.body'));
 }
 
 main();

package/hooks/handmux-notify.sh

@@ -1,5 +1,7 @@
 #!/bin/sh
-# handmux 上报 hook. $1 = stop | notify | prompt | end | resume | permreq. stdin = Claude 原始 payload(JSON).
+# handmux 上报 hook. $1 = stop | notify | prompt | end | resume | permreq. $2 = agent id(留空=claude;
+# Codex 传 'codex')—— Claude 与 Codex 的 hook payload 字段一致(stdin JSON),所以共用这一个脚本。
+# stdin = agent 原始 payload(JSON).
 # (resume  = PostToolUse on AskUserQuestion/ExitPlanMode:答完选项/批准计划 → 状态翻回进行中、带所选项。)
 # (permreq = PermissionRequest:真实弹框一出现就发、带 tool_name → 比 permission_prompt 早亮「需要你」。)
 # 只做一件事:把本次事件写进一个本地 JSON 状态文件(键=tmux pane,值=该 pane 最新事件)。不联网、
@@ -16,5 +18,5 @@ TS=$(perl -MTime::HiRes -e 'printf "%.0f", Time::HiRes::time()*1000' 2>/dev/null
 HOST=$(hostname 2>/dev/null || printf '')
 # payload 经 stdin 原样流给 node(不在 shell 里转义,避免坏数据);pane 含 '%' 直接进 JSON 字段,
 # 不再进 URL → 彻底告别旧的 "%110 被 url-decode 丢弃" 那类坑。
-node "$(dirname "$0")/handmux-write.cjs" "$FILE" "$PANE" "$1" "$TS" "$HOST" 2>/dev/null || true
+node "$(dirname "$0")/handmux-write.cjs" "$FILE" "$PANE" "$1" "$TS" "$HOST" "$2" 2>/dev/null || true
 exit 0

package/hooks/handmux-write.cjs

@@ -16,7 +16,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const [, , file, pane, src, ts, host = ''] = process.argv;
+const [, , file, pane, src, ts, host = '', agent = ''] = process.argv;
 if (!file || !pane || !src) process.exit(0);
 
 let payload = {};
@@ -28,6 +28,7 @@ try { payload = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { /* unr
 // write under the lock — the only place we can read the prior state safely — makes the call.
 const isIdle = src === 'notify' && payload && payload.notification_type === 'idle_prompt';
 let cleared = false; // set by update() when idle cleared an interrupted 进行中 → also clear @claude_dot below
+let noop = false;    // set when a codex PostToolUse resume had nothing to un-stick → skip the state + dot write
 
 // Synchronous nap without busy-spinning (the hook runs async, so a few ms is free). SharedArrayBuffer
 // may be unavailable in odd runtimes — fall back to a tiny busy loop so the lock retry still paces.
@@ -53,8 +54,20 @@ function update() {
     else return;                                             // resting → drop without writing
   } else if (src === 'end') {
     delete obj[pane];                                        // SessionEnd (clean exit) → drop the pane
+  } else if (src === 'resume' && agent === 'codex') {
+    // Codex fires PostToolUse on EVERY tool call, so its resume exists purely to un-stick a pane from 需要你
+    // back to 进行中 after the user approved a PermissionRequest. Apply it ONLY as that transition — a mid-
+    // turn tool call (pane already 进行中 / 已完成) is a no-op, so we don't rewrite the entry or repaint the
+    // dot on every command (the load Claude's matcher avoids). Claude's resume — no agent arg — is unaffected.
+    const prev = obj[pane];
+    const prevPerm = prev && (prev.src === 'permreq'
+      || (prev.src === 'notify' && (prev.payload || {}).notification_type === 'permission_prompt'));
+    if (!prevPerm) { noop = true; return; }
+    obj[pane] = { ts: Number(ts) || 0, src, host, payload, agent };
   } else {
-    obj[pane] = { ts: Number(ts) || 0, src, host, payload };
+    // agent tag lets the server dispatch classify + liveness per agent (Codex passes 'codex'); omitted for
+    // Claude so legacy entries stay byte-identical and default to claude server-side.
+    obj[pane] = { ts: Number(ts) || 0, src, host, payload, ...(agent ? { agent } : {}) };
   }
   const tmp = `${file}.${process.pid}.tmp`;
   fs.writeFileSync(tmp, JSON.stringify(obj));
@@ -86,7 +99,7 @@ function claudeDot(s, p) {
 }
 try {
   const dot = (src === 'end' || cleared) ? '' : claudeDot(src, payload);
-  if (dot !== null) {
+  if (dot !== null && !noop) {
     require('node:child_process').execFileSync('tmux', ['set-option', '-w', '-t', pane, '@claude_dot', dot], { stdio: 'ignore', timeout: 1000 });
   }
 } catch { /* 不在 tmux / tmux 不可达 → 忽略 */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handmux",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Mobile vibe coding — drive your real tmux session (and Claude Code) from your phone.",
   "type": "module",
   "license": "AGPL-3.0-only",