handmux 0.23.0 → 0.25.0

package/dist/src/cli/hookScaffold.js

@@ -0,0 +1,39 @@
+// Shared IO scaffolding for the Claude Code hook installer and statusLine capturer.
+import fs from 'node:fs';
+import path from 'node:path';
+export const HOOK_SCRIPTS = ['handmux-notify.sh', 'handmux-write.cjs'];
+const LEGACY_HOOK_SCRIPTS = ['handmux-codex-usage.cjs'];
+// Atomic write (tmp + rename) so a crash can't leave a half-written config file. Text in, text out — callers
+// pass raw TOML for config.toml, or use writeJsonAtomic for pretty-printed settings.json.
+export function writeFileAtomic(file, text) {
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, text);
+    fs.renameSync(tmp, file);
+}
+export const writeJsonAtomic = (file, value) => (writeFileAtomic(file, JSON.stringify(value, null, 2)));
+// Deploy the Claude notify/write scripts into `hooksDir` and point their env at the shared state file.
+export function deployHookScripts(hooksDir, srcDir, stateFile) {
+    fs.mkdirSync(hooksDir, { recursive: true });
+    for (const f of HOOK_SCRIPTS)
+        fs.copyFileSync(path.join(srcDir, f), path.join(hooksDir, f));
+    for (const f of LEGACY_HOOK_SCRIPTS) {
+        try {
+            fs.unlinkSync(path.join(hooksDir, f));
+        }
+        catch { /* absent */ }
+    }
+    fs.chmodSync(path.join(hooksDir, 'handmux-notify.sh'), 0o755);
+    fs.writeFileSync(path.join(hooksDir, 'handmux-notify.env'), [
+        `HANDMUX_STATE=${stateFile}`,
+        '',
+    ].join('\n'), { mode: 0o600 });
+}
+// Remove the deployed scripts + env (uninstall). Best-effort: a missing file is fine.
+export function removeHookScripts(hooksDir) {
+    for (const f of [...HOOK_SCRIPTS, ...LEGACY_HOOK_SCRIPTS, 'handmux-notify.env']) {
+        try {
+            fs.unlinkSync(path.join(hooksDir, f));
+        }
+        catch { /* already gone */ }
+    }
+}

package/dist/src/cli/i18n/en.js

@@ -0,0 +1,392 @@
+// English catalog (the fallback locale). Keys are grouped by command/area. `{var}` placeholders are filled
+// by translate(). Keep this in lockstep with zh.js — a missing zh key silently falls back to the line here.
+export default {
+    // generic
+    'err.generic': '✗ {msg}',
+    'err.configNotFound': '✗ --config {path}: not found',
+    'err.badConfig': '✗ bad config {path}: {msg}',
+    'err.namedNotProvisioned': '✗ named tunnel not provisioned — run `handmux setup` first',
+    'lifecycle.busy': '✗ another handmux lifecycle operation is running (pid {pid}); try again shortly.',
+    'lifecycle.scanFailed': '✗ could not inspect handmux supervisor processes; refusing to continue because that could create a duplicate.',
+    // config line printed at the top of start / service install
+    'config.loaded': 'config: {path}',
+    'config.none': '(none — flags + defaults)',
+    // shortcut editor
+    'shortcuts.title': 'Shared quick shortcuts',
+    'shortcuts.command': 'Command mode',
+    'shortcuts.chat': 'Chat mode',
+    'shortcuts.count': '{n} items',
+    'shortcuts.save': 'Save and exit',
+    'shortcuts.exit': 'Exit without saving',
+    'shortcuts.addKey': 'Add key',
+    'shortcuts.addText': 'Add text',
+    'shortcuts.back': 'Back',
+    'shortcuts.edit': 'Edit',
+    'shortcuts.move': 'Change position',
+    'shortcuts.addPositionPrompt': 'Place at',
+    'shortcuts.movePrompt': 'Move to (current: position {n})',
+    'shortcuts.positionFirst': 'First (position 1)',
+    'shortcuts.positionAfter': 'After {item} (position {n})',
+    'shortcuts.positionLast': 'Last (position {n})',
+    'shortcuts.delete': 'Delete',
+    'shortcuts.type': 'Shortcut type',
+    'shortcuts.key': 'Key',
+    'shortcuts.text': 'Text',
+    'shortcuts.textEnter': 'Text · sends with Enter',
+    'shortcuts.textOnly': 'Text · type only',
+    'shortcuts.textPrompt': 'Text to type',
+    'shortcuts.badText': 'Enter one non-empty line',
+    'shortcuts.enter': 'Press Enter after the text?',
+    'shortcuts.modifier': 'Modifier',
+    'shortcuts.noModifier': 'None',
+    'shortcuts.base': 'Base key',
+    'shortcuts.needTty': 'handmux shortcuts needs an interactive terminal.',
+    'shortcuts.wrote': 'Saved {path}',
+    'shortcuts.exited': 'No changes saved',
+    'shortcuts.applied': 'Applied immediately to the running handmux server.',
+    'shortcuts.applyFailed': 'Config was saved but could not be applied immediately: {msg}. Run `handmux restart`.',
+    // ssh preflight
+    'ssh.confirmSetup': 'passwordless SSH to {host} is not set up. Configure it now?',
+    'ssh.notSetup': 'passwordless SSH not set up — run: {bin} setup-key {host}',
+    // tmux presence / version
+    'tmux.notFound': '✗ tmux not found.',
+    'tmux.explain1': '  handmux runs on top of tmux (a terminal multiplexer) — it drives your real tmux',
+    'tmux.explain2': '  panes from your phone, so you need tmux on this machine first.',
+    'tmux.install': '  Install it:  {hint}',
+    'tmux.thenStart': '  Then run `handmux start` again.',
+    'open.usage': 'usage: handmux open <session>   attach the tmux session (creates it if missing)',
+    'open.insideTmux': "you're already inside tmux — switch sessions with tmux itself (e.g. `tmux switch-client -t <session>`), don't nest.",
+    'tmux.tooOld': '⚠ tmux {raw} is below the tested minimum {min}; terminal rendering may be off',
+    // start — already running
+    'start.running.same': 'handmux is already running — open the address below.',
+    'start.running.changedHead': 'handmux is already running (tunnel: {tunnel}). A running instance does NOT pick up config changes on its own:',
+    'start.running.changedRow': '  • {key}: {from} → {to} (what you asked for now)',
+    'start.running.switchQ': 'Switch to the new settings now? (restarts handmux)',
+    'start.running.hint': "Leaving it as-is. Run 'handmux restart' whenever you want to apply the new settings.",
+    'start.instancesFound': '✗ found an untracked or duplicate handmux supervisor (pid: {pids}).',
+    'start.instancesHint': '  refusing to launch another copy. Run `handmux stop` first to reap every instance.',
+    // start — launching
+    'start.overrides': '  ↳ --tunnel {flag} overrides config ({file}) for this run only',
+    'start.foreground': 'starting handmux (tunnel: {tunnel}, port: {port}) — Ctrl-C to stop',
+    'start.starting': 'starting handmux (tunnel: {tunnel}, port: {port}) …',
+    // stop / status
+    'stop.notRunning': 'handmux not running',
+    'stop.stopped': 'stopped handmux (pid {pid})',
+    'stop.stoppedMany': 'stopped duplicate handmux instances (pids: {pids})',
+    'stop.stoppedManaged': 'stopped the managed handmux service',
+    'stop.timeout': '✗ handmux (pids: {pids}) did not fully stop; refusing to start a second instance. Check `handmux status` / `handmux logs`.',
+    'status.stopped': '● handmux {version} stopped',
+    'status.running': '● handmux {version} running',
+    'status.installed': '  installed version {version} (takes effect after restart)',
+    'status.untracked': '⚠ handmux state is stale, but supervisor processes still exist (pids: {pids}); running version unknown, installed version {version}.',
+    'status.duplicates': '⚠ multiple handmux supervisors detected (pids: {pids}); the access details below only belong to the last state writer.',
+    'status.cleanupHint': '  run `handmux stop` to reap every copy.',
+    'status.scanFailed': '⚠ could not inspect supervisor processes; the status below comes from state.json only.',
+    // logs
+    'logs.none': '(no log yet — start handmux first)',
+    // update
+    'update.available': '  ⬆  handmux {latest} is available (you have {current})',
+    'update.how': '     upgrade:  handmux update   (or npm i -g handmux@latest)',
+    'update.howBrew': '     upgrade:  brew upgrade handmux',
+    'update.brew': 'This handmux was installed with Homebrew — upgrade it with:  brew upgrade handmux',
+    'update.running': 'Upgrading handmux (npm i -g handmux@latest)…',
+    'update.done': '✓ handmux updated.',
+    'update.restartHint': '  run `handmux restart` to run the new version.',
+    'update.failed': '✗ Upgrade failed. Try manually: npm i -g {pkg}@latest (may need sudo).',
+    // cloudflared auto-download
+    'cf.downloading': '  ↓ downloading cloudflared ({file}) …',
+    // natapp / cpolar client binaries
+    'client.downloading': '  ↓ downloading {name} ({file}) …',
+    'client.cpolarManual': '✗ cpolar not available — install it from https://www.cpolar.com/download (unzip the binary into ~/.handmux/bin/), then re-run.',
+    'client.cpolarAuthFail': '✗ cpolar rejected the authtoken — double-check it at https://dashboard.cpolar.com',
+    'client.natappManual': '✗ natapp not found — download it from https://natapp.cn (login first, it is not a public download), then put the `natapp` binary in {dir} (or anywhere on your PATH) and re-run.',
+    // access block (printAccess)
+    'access.noState': '  (no state)',
+    'access.error': '  ✗ {msg}',
+    'access.tunnel': '  tunnel   {tunnel}   ·   pid {pid}',
+    'access.open': '  🌐 open   {url}',
+    'access.pending': '(pending…)',
+    'access.lan': '  📶 lan    {url}',
+    'access.local': '  💻 local  {url}',
+    'access.token': '  🔑 token  {token}',
+    'access.reachable': '  ✓ reachable',
+    'access.unreachable': '  ⚠ tunnel up but {url} did not answer — check the server-side reverse proxy / DNS',
+    'access.hint': '  handmux status | stop',
+    // hooks
+    'hooks.confirmEnable': 'Enable Claude Code states and notifications (inbox)?',
+    'hooks.noClaude': 'Claude Code not detected (~/.claude missing) — nothing to install.',
+    'hooks.installedClaude': '✓ Claude integration enabled.',
+    'hooks.installedHint': '  Restart or open a new Claude Code session to load it.',
+    'hooks.removed': '✓ Claude integration disabled.',
+    'hooks.usage': 'usage: handmux hooks install|uninstall',
+    // Agent launchers and Handmux integration management
+    'agent.state.ready': 'ready',
+    'agent.state.not-installed': 'not installed',
+    'agent.state.not-enabled': 'not enabled',
+    'agent.state.needs-repair': 'needs repair',
+    'agent.state.conflict': 'conflict',
+    'agent.builtIn': ' (built-in)',
+    'agent.status': '{name}: {status}{detail}',
+    'agent.hint.install': '  Install {name} first, then run `handmux agent enable {name}`.',
+    'agent.hint.initializeClaude': '  Run Claude Code once to initialize ~/.claude, then run `handmux agent enable claude`.',
+    'agent.hint.enable': '  Run `handmux agent enable {name}`.',
+    'agent.hint.conflict': '  The integration target is owned by another extension; move it aside, then run `handmux agent enable {name}`.',
+    'agent.enabled': '✓ {name} integration enabled.',
+    'agent.alreadyReady': '= {name} integration is already ready.',
+    'agent.disabled': '✓ {name} integration disabled.',
+    'agent.alreadyDisabled': '= {name} integration is already disabled.',
+    'agent.codexBuiltIn': '= Codex integration is built in and already ready.',
+    'agent.codexDisable': 'Codex integration is built in and cannot be disabled. Run native `codex` directly to bypass Handmux.',
+    'agent.unknown': 'unknown Agent: {name}',
+    'agent.usage': 'usage: handmux agent [list] | handmux agent status|enable|disable <codex|pi|claude>',
+    // Pi Extension
+    'piExtension.confirmEnable': 'Enable the Pi integration with Handmux?',
+    'piExtension.installed': '✓ Pi integration enabled.',
+    'piExtension.reload': '  Open a new Pi session, or run /reload in Pi, to apply the change.',
+    // Claude statusLine usage capturer (powers the phone Usage page's 5h/weekly bars)
+    'statusline.confirmEnable': "Show Claude's 5h/weekly usage on the phone? (installs a Claude statusLine)",
+    'statusline.installed': '✓ Claude statusLine installed → ~/.claude/settings.json',
+    'statusline.reload': '  Open a new Claude session to load it; the Usage page fills in as it reports.',
+    'statusline.foreignHint': 'You already have a Claude statusLine — leaving it untouched. To also feed the phone Usage page, pipe it through our capturer:',
+    // service
+    'service.usage': 'usage: handmux service install [start-flags] | handmux service uninstall',
+    'service.installed': "handmux will now start at login. 'handmux service uninstall' to remove.",
+    // config command
+    'configcmd.file': 'config file: {path}',
+    'configcmd.fileNone': '(none — using defaults; run `handmux setup` to create one)',
+    'configcmd.legend': '  origin: flag (this run only) · file · env · default',
+    // setup wizard
+    'setup.confirmStart': 'Start handmux now?',
+    'setup.later': "run 'handmux start' when you're ready.",
+    'setup.laterRestart': "already running — run 'handmux restart' to apply the changes.",
+    'setup.needTty': 'handmux setup needs an interactive terminal',
+    'setup.langQ': 'Command-line language (handmux terminal output) / 命令行语言',
+    'setup.lang1': '  1) English',
+    'setup.lang2': '  2) 中文',
+    'setup.askName': 'app name (shown in the browser tab / home-screen icon; blank = default)',
+    'setup.tunnelQ': 'How should your phone reach this machine?',
+    'setup.tunnel1': '  1) none              — same Wi-Fi / LAN only',
+    'setup.tunnel2': '  2) cloudflare        — instant, random temporary https URL',
+    'setup.tunnel3': '  3) cloudflare-named  — your domain, stable HTTPS (most hands-off)',
+    'setup.tunnel4': '  4) ssh (tunlite)     — your own server / edge',
+    'setup.tunnel5': '  5) natapp            — China-usable tunnel (needs a natapp authtoken)',
+    'setup.tunnel6': '  6) cpolar            — China-usable tunnel (auto-installs; needs a cpolar authtoken)',
+    'setup.choose': 'choose 1-6',
+    'setup.invalid': 'invalid choice',
+    'setup.askPort': 'server port',
+    'setup.askHostname': 'public hostname (e.g. handmux.example.com)',
+    'setup.askTunnelName': 'tunnel name',
+    'setup.askSshHost': 'ssh host (user@host[:port])',
+    'setup.askRemotePort': 'remote port on the ssh host',
+    'setup.askPublicUrl': 'public url — http(s):// as appropriate (blank = http://host:remotePort)',
+    'setup.natappGuide': 'Where to get the authtoken: register free at https://natapp.cn → create a tunnel → copy its authtoken (the free tier is enough to start).',
+    'setup.cpolarGuide': 'Where to get the authtoken: register free at https://cpolar.com → open the dashboard → Verify → copy your authtoken.',
+    'setup.askAuthtoken': 'authtoken',
+    'setup.askFixed': 'use a fixed domain? (No = a free temporary domain, changes each restart)',
+    'setup.askNatappDomain': 'your reserved domain bound to this authtoken (e.g. myapp.natapp1.cc)',
+    'setup.askCpolarDomain': 'your reserved second-level subdomain or bound domain (e.g. myapp.cpolar.top)',
+    'setup.askCpolarRegion': 'cpolar region (cn = mainland China, faster domestically; blank = cpolar default)',
+    'setup.natappReady': '✓ natapp client ready',
+    'setup.cpolarReady': '✓ cpolar client ready',
+    // setup hub (menu model)
+    'setup.welcome': "handmux is open-source and runs no relay of its own — your phone always connects to your own computer, which keeps it private and secure; on the same Wi-Fi it's a pure direct link and works out of the box (pick 'Direct'). To reach it from outside too, the options below are built-in ways to do that with your own free account. Not sure? Press Enter on the highlighted option — you can change it anytime.",
+    'setup.hubTitle': 'Anything to change? (or just Save & start)',
+    'setup.secConnection': 'Connection',
+    'setup.secName': 'Name',
+    'setup.secPort': 'Port',
+    'setup.secToken': 'Token',
+    'setup.secBrowser': 'Web preview',
+    'setup.browserOff': 'not configured · Direct mode only',
+    'setup.askBrowserDomain': 'Web preview proxy domain (blank = Direct mode only)',
+    'setup.browserAbout': 'Enter a proxy domain (for example, preview.example.com) and route its wildcard subdomains to Handmux over HTTPS; leave it blank for Direct mode only.',
+    'setup.tokenAuto': 'auto · new each start',
+    'setup.tokenCustom': 'Set a custom token…',
+    'setup.tokenRandom': 'Generate a random one',
+    'setup.tokenReset': 'Reset to auto (new each start)',
+    'setup.askToken': 'Access token — it appears in the URL you open on the phone',
+    'setup.tokenGenerated': 'New token: {token}',
+    'setup.valToken': 'enter a token',
+    'setup.valTokenSpace': 'no spaces — the token goes in a URL',
+    'setup.secLanguage': 'CLI language / 命令行语言',
+    'setup.secPush': 'Push',
+    'setup.secVoice': 'Voice',
+    'setup.default': '(default)',
+    'setup.on': 'on',
+    'setup.off': 'off',
+    'setup.yes': 'Yes',
+    'setup.no': 'No',
+    'setup.escBack': '(Esc to go back)',
+    'setup.actStart': 'Save & start',
+    'setup.actRestart': 'Save & restart (apply now)',
+    'setup.actSave': 'Save',
+    'setup.actExit': 'Exit — discard changes',
+    'setup.exited': 'setup cancelled — no changes saved',
+    'setup.tunnelNone': 'Direct',
+    'setup.hintNone': 'no tunnel — reach this machine directly (same Wi-Fi, or its own public IP); simplest',
+    'setup.hintCf': 'reach it from anywhere, no signup (temporary URL; can be flaky in China)',
+    'setup.hintCfNamed': 'your domain, stable HTTPS (most hands-off)',
+    'setup.hintSsh': 'you already have a server to route through',
+    'setup.hintNatapp': 'reach it from anywhere, works in China (needs a free natapp account)',
+    'setup.hintCpolar': 'reach it from anywhere, works in China, auto-installs (needs a free cpolar account)',
+    'setup.domainQ': 'temporary or fixed domain?',
+    'setup.domainTemp': 'Free temporary domain',
+    'setup.domainTempHint': 'changes each restart',
+    'setup.domainFixed': 'Fixed / reserved domain',
+    'setup.valPort': 'port must be an integer 1–65535',
+    'setup.valRequired': '{label} is required',
+    'setup.valHost': 'enter a valid domain (e.g. myapp.example.com)',
+    'setup.valPreviewDomain': 'enter only a domain, e.g. preview.example.com; do not include http://, https://, a port, or *.',
+    'setup.valContact': 'use mailto:you@example.com or https://your.site (a real domain — Apple rejects fake ones)',
+    'setup.sumTemp': 'temporary',
+    'setup.sumFixed': 'fixed',
+    'setup.sumNoRelay': 'no relay',
+    // connection mini-hub (per-tunnel field rows)
+    'setup.connTunnel': 'Tunnel',
+    'setup.connMode': 'Mode',
+    'setup.connHostname': 'Hostname',
+    'setup.connTunnelName': 'Tunnel name',
+    'setup.connSshHost': 'SSH host',
+    'setup.connRemotePort': 'Remote port',
+    'setup.connPublicUrl': 'Public URL',
+    'setup.connJump': 'Jump host',
+    'setup.connDomain': 'Domain',
+    'setup.connRegion': 'Region',
+    'setup.connNone': '(not set)',
+    'setup.connAuto': '(auto)',
+    'setup.askSshJump': 'ssh jump host (user@host, blank = none)',
+    'setup.cfModeQ': 'cloudflare address',
+    'setup.cfTemp': 'Temporary (no login)',
+    'setup.cfTempHint': 'instant random https URL, changes each restart',
+    'setup.cfNamed': 'Named (your domain)',
+    'setup.cfNamedHint': 'stable HTTPS, needs a Cloudflare login',
+    'setup.wrote': '✓ wrote {path}',
+    'setup.pushKeep': 'keep push notifications configured?',
+    'setup.pushSetup': 'Turn on phone notifications? (get pinged when a coding agent finishes)',
+    'setup.pushAbout': 'handmux generates a private signing key for you and stores it in ~/.handmux/config.json — it never leaves this machine. The contact below is only an address the push service can reach you at; nobody else sees it.',
+    'setup.pushContact': 'contact for the push service — mailto: or https:// (the default is fine; keep the mailto: prefix)',
+    'setup.pushGenerated': '✓ generated a signing keypair (kept in your local config)',
+    'setup.pushContactLabel': 'Contact',
+    'setup.pushRegen': 'Regenerate keys',
+    'setup.pushRegenHint': 'resets every phone subscription',
+    'setup.pushRegenConfirm': 'Regenerate the keypair? Every phone that already subscribed stops getting notifications until it re-opens the web app and subscribes again. Only needed if the key leaked.',
+    'setup.pushRegenerated': '✓ regenerated keys — existing phones must re-subscribe',
+    'setup.pushOff': 'Turn off push',
+    'setup.voiceOff': 'Turn off voice',
+    'setup.voiceKeep': 'keep voice input configured?',
+    'setup.voiceSetup': 'Turn on voice input? (talk to your phone → text; needs an iFlytek/xfyun account)',
+    'setup.voiceAppId': 'xfyun appId',
+    'setup.voiceApiKey': 'xfyun apiKey',
+    'setup.voiceApiSecret': 'xfyun apiSecret',
+    'setup.voiceSkipped': '  (skipped — missing fields)',
+    'setup.cfLogin': '→ logging in to Cloudflare (a browser will open) …',
+    'setup.cfReuse': '✓ reusing existing tunnel {name} ({id})',
+    'setup.cfCredMissing1': '⚠ credentials file {file} not found on this machine — the tunnel was likely',
+    'setup.cfCredMissing2': '  created elsewhere. Run `{bin} tunnel delete {name}` and re-run setup to recreate it here.',
+    'setup.cfCreate': '→ creating tunnel {name} …',
+    'setup.cfRoute': '→ routing {host} → tunnel …',
+    'setup.cfRouteFail': "⚠ route dns failed — is {domain}'s DNS hosted on Cloudflare?",
+    'setup.cfRouteFail2': '  Add the domain on Cloudflare (free) and point its nameservers there, then re-run setup.',
+    'setup.sshReady': '✓ passwordless SSH already set up',
+    'setup.sshSetup': "→ setting up passwordless SSH to {host} (you'll enter the password once) …",
+    'setup.sshHelp1': 'Server side (one-time): point a reverse proxy at the forwarded loopback port.',
+    'setup.sshHelpNginx': '  nginx:  proxy_pass http://127.0.0.1:{port};  also set proxy_http_version 1.1, the Upgrade/Connection WebSocket headers, client_max_body_size 60m, and proxy_read_timeout 90s;',
+    'setup.sshHelpCaddy': '  caddy:  {url} {  reverse_proxy 127.0.0.1:{port}  }',
+    // workspace restore
+    'restore.usage': 'Usage: handmux restore [--dry-run] [--checkpoint <id>] [--session <name>] | handmux restore --list',
+    'restore.badFlag': 'Unknown restore option {flag}.',
+    'restore.unexpectedArgument': 'Unexpected restore argument: {value}.',
+    'restore.unknownShortFlag': 'Unknown restore option {flag}.',
+    'restore.flagBoolean': '{flag} does not take a value.',
+    'restore.checkpointValue': '--checkpoint needs an id value (or latest).',
+    'restore.checkpointId': '--checkpoint must be a valid id containing only letters, numbers, dots, underscores, or hyphens.',
+    'restore.sessionValue': '--session needs a non-empty session name.',
+    'restore.listExclusive': '--list must be used alone; it cannot be combined with --dry-run, --checkpoint, or --session.',
+    'restore.listRow': '{id}  {time}  {sessions} session(s) · {windows} window(s) · {panes} pane(s) · {agents} agent(s)',
+    'restore.listUnavailable': '{id}  unavailable: {error}',
+    'restore.listEmpty': 'No workspace checkpoints have been archived yet.',
+    'restore.selectCheckpoint': 'Choose a workspace checkpoint to restore',
+    'restore.selectHint': '{time} · {sessions} session(s) · {windows} window(s) · {panes} pane(s)',
+    'restore.noCheckpoint': 'No usable checkpoint exists yet. handmux is silently protecting the current workspace; retry after the next computer or tmux restart.',
+    'restore.selectionCancelled': 'No checkpoint was selected. Run `{command}` again when you are ready.',
+    'restore.planCheckpoint': 'Checkpoint: {time} ({id}; {sessions} sessions, {windows} windows, {panes} panes)',
+    'restore.planCurrent': 'Current: {sessions} live sessions',
+    'restore.planCreate': '+ {session}',
+    'restore.planRenamed': '+ {session} -> {target} (name already in use)',
+    'restore.planAlready': '= {session} (already restored)',
+    'restore.planUnavailable': '! {session} (unavailable: {reason})',
+    'restore.reason.linkedWindows': 'this checkpoint contains linked windows that cannot be restored safely by this version',
+    'restore.reason.invalidTopology': 'this checkpoint contains incomplete or invalid tmux topology',
+    'restore.reason.unknown': 'unsupported checkpoint topology ({reason})',
+    'restore.manualRecovery': 'Restore this session manually instead: {command}',
+    'restore.warning': 'Warning: {warning}',
+    'restore.sessionWarning': '  Warning for {session}: {warning}',
+    'restore.nonDestructive': 'No existing session or process will be stopped or modified.',
+    'restore.nonDestructivePast': 'Existing sessions were not modified.',
+    'restore.dryRunHint': 'Run `{command}` to continue.',
+    'restore.resultRestored': '✓ {session}',
+    'restore.resultRenamed': '✓ {session} restored as {target}',
+    'restore.resultAlready': '= {session} (already restored)',
+    'restore.sessionFailed': 'Checkpoint {checkpoint}; session {session}; stage {stage}: {error}',
+    'restore.operationFailed': 'Checkpoint {checkpoint}; stage {stage}: {error}',
+    'restore.retrySession': 'Retry only this session: {command}',
+    'restore.resultSummary': 'Restored {restored} session(s); {already} already present; {failed} failed.',
+    'restore.error': 'Checkpoint {checkpoint} failed during the restore command: {error}',
+    'restore.retry': 'Retry with `{command}` after fixing the reported cause.',
+    // help
+    'help.body': `handmux — drive your tmux from your phone
+
+  handmux start            run it (defaults to LAN-only; no config needed)
+  handmux open <session>   attach a tmux session, creating it if missing — incl. ones made on the phone
+  handmux setup            configure tunnel / name / notifications (writes config; re-run to change)
+  handmux shortcuts        configure shared command/chat quick shortcuts
+  handmux stop | restart | status
+  handmux logs [--follow] [--lines N]
+  handmux push <title> <body>   notify your phone from a script (--session X · --device K · --tag T · --url U)
+  handmux codex [args...]       launch a Codex TUI synchronized with chat view
+  handmux pi [args...]          launch Pi with its arguments unchanged
+  handmux agent [list]          show supported Agent integrations
+  handmux agent status|enable|disable <name>
+  handmux restore [--dry-run] [--checkpoint <id>] [--session <name>]
+  handmux restore --list
+  handmux update           upgrade to the latest published version (npm i -g handmux@latest)
+
+New here? run 'handmux setup' — it walks you through remote access + phone notifications.
+The model: 'start' runs · 'setup' configures (writes ~/.handmux/config.json) · re-run setup to change.
+
+more:
+  handmux config                          show the effective config + where each value came from
+  handmux service install|uninstall       start at login (launchd/systemd)
+  handmux help flags                      one-run flags + env vars (scripting / headless / Docker)
+  --config PATH · --lang en|zh · --version, -v
+`,
+    'help.flags': `handmux flags — one-run overrides & headless config
+
+Precedence: flag > file (~/.handmux/config.json) > env (HANDMUX_*) > default.
+A flag overrides one value for THIS run only and never persists — for persistence use 'handmux setup'.
+env vars are the headless interface (Docker / systemd / CI) and DO carry across runs.
+
+start flags (matching env var in parens):
+  --tunnel none|cloudflare|cloudflare-named|ssh|natapp|cpolar   expose method (default: none)
+  --port N                      server port (HANDMUX_PORT, default: 19999)
+  --host H                      bind host (HANDMUX_HOST, default: 0.0.0.0)
+  --token S                     auth token (HANDMUX_TOKEN, default: generated each start)
+  --name "My Box"               app name in the browser tab + home-screen icon (HANDMUX_APP_NAME)
+  --public-url URL              public url to advertise (HANDMUX_PUBLIC_URL; any tunnel, incl. none if
+                                you run your own; ssh defaults to http://host:remotePort; for
+                                natapp/cpolar this is your fixed/reserved domain — omit for a temporary one)
+  --ssh-host user@host[:port]   ssh tunnel target (HANDMUX_SSH_HOST)
+  --remote-port N               port bound on the ssh host (HANDMUX_REMOTE_PORT, default: --port)
+  --ssh-jump u@h[,…]            optional bastion for ssh (HANDMUX_SSH_JUMP)
+  --cf-hostname H               public hostname for cloudflare-named (HANDMUX_CF_HOSTNAME)
+  --cf-tunnel-name N            tunnel name for cloudflare-named (HANDMUX_CF_TUNNEL_NAME, default: handmux)
+  --authtoken T                 authtoken for natapp / cpolar (HANDMUX_AUTHTOKEN)
+  --cpolar-region R             cpolar edge region, e.g. cn (HANDMUX_CPOLAR_REGION)
+  --foreground, -f              run in the foreground (don't daemonize)
+  --no-qr                       don't render the QR code
+
+rarely needed (env or flag): --static-dir / --upload-exts
+  (HANDMUX_STATIC_DIR / HANDMUX_UPLOAD_EXTS)
+
+'handmux service install' accepts these same start flags — they're baked into the autostart entry.
+`,
+};

package/{src → dist/src}/cli/i18n/index.js

@@ -5,49 +5,51 @@
 // key falls back to English, so a partial translation degrades gracefully rather than printing blanks.
 import en from './en.js';
 import zh from './zh.js';
-
 const LOCALES = { en, zh };
 export const AVAILABLE = [
-  { code: 'en', label: 'English' },
-  { code: 'zh', label: '中文' },
+    { code: 'en', label: 'English' },
+    { code: 'zh', label: '中文' },
 ];
-
 // pure + testable: current-dict → English-fallback → key, then {var} interpolation (same as web).
 export function translate(dict, fallback, key, vars) {
-  let s = dict && dict[key] != null ? dict[key]
+    let s = dict && dict[key] != null ? dict[key]
         : fallback && fallback[key] != null ? fallback[key]
-        : key;
-  if (vars) s = s.replace(/\{(\w+)\}/g, (_, k) => (vars[k] != null ? vars[k] : `{${k}}`));
-  return s;
+            : key;
+    if (vars)
+        s = s.replace(/\{(\w+)\}/g, (_match, name) => (vars[name] != null ? String(vars[name]) : `{${name}}`));
+    return s;
 }
-
 // A POSIX locale string → the base language we might have a dict for: `zh_CN.UTF-8` → `zh`, `en` → `en`.
-const baseOf = (v) => String(v || '').toLowerCase().split(/[._@-]/)[0];
-
+const baseOf = (value) => String(value || '').toLowerCase().split(/[._@-]/)[0] ?? '';
 // pure + testable: explicit choice (flag/config) wins, else the first shell locale var that names a known
 // language, else English. `C`/`POSIX`/`C.UTF-8` carry no language → fall through to English.
 export function detectLang(flags = {}, fileCfg = {}, env = {}, available = LOCALES) {
-  const explicit = flags.lang ?? fileCfg.lang;
-  if (explicit != null) { const b = baseOf(explicit); if (available[b]) return b; }
-  for (const k of ['HANDMUX_LANG', 'LC_ALL', 'LC_MESSAGES', 'LANG']) {
-    const b = baseOf(env[k]);
-    if (b && available[b]) return b;
-  }
-  return 'en';
+    const explicit = flags.lang ?? fileCfg.lang;
+    if (explicit != null) {
+        const b = baseOf(explicit);
+        if (available[b])
+            return b;
+    }
+    for (const k of ['HANDMUX_LANG', 'LC_ALL', 'LC_MESSAGES', 'LANG']) {
+        const b = baseOf(env[k]);
+        if (b && available[b])
+            return b;
+    }
+    return 'en';
 }
-
 let current = 'en';
-
 // Resolve + install the active locale for the whole CLI process (called once at startup). Returns the code.
 export function initLocale(flags, fileCfg, env = process.env) {
-  current = detectLang(flags, fileCfg, env);
-  return current;
+    const detected = detectLang(flags, fileCfg, env);
+    current = detected === 'zh' ? 'zh' : 'en';
+    return current;
 }
-
 // Force a specific locale (e.g. right after the setup wizard's language question, so the rest of the wizard
 // speaks the chosen language). No-op for an unknown code.
-export function setLocale(code) { if (LOCALES[code]) current = code; }
+export function setLocale(code) {
+    if (code === 'en' || code === 'zh')
+        current = code;
+}
 export function getLocale() { return current; }
-
 // The one call sites use: translate `key` in the active locale, falling back to English then the key itself.
 export function t(key, vars) { return translate(LOCALES[current], en, key, vars); }