npm - handmux - Versions diffs - 0.17.5 → 0.17.7 - Mend

handmux 0.17.5 → 0.17.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/README.md +2 -0
package/README.zh-CN.md +2 -0
package/bin/handmux.js +131 -26
package/package.json +4 -4
package/public/assets/{index-CKy8gVDA.css → index-CiaHwIWj.css} +1 -1
package/public/assets/index-cjqG9l7v.js +330 -0
package/public/index.html +2 -2
package/src/cli/i18n/en.js +14 -2
package/src/cli/i18n/zh.js +14 -2
package/src/cli/pushCmd.js +7 -1
package/src/cli/service.js +30 -2
package/src/cli/state.js +41 -0
package/src/cli/supervisor.js +4 -0
package/src/cli/supervisorProcesses.js +57 -0
package/src/notifications.js +16 -1
package/src/push.js +21 -3
package/src/routes/push.js +22 -4
package/src/routes/transcript.js +19 -7
package/public/assets/index-BojPm0vc.js +0 -330

package/README.md CHANGED Viewed

@@ -124,6 +124,8 @@ No tunnel by default — the phone connects **straight to your own computer**, n
 > Tunnel config, server-side reverse proxy, autostart, voice/push credentials, and port previews → see the **[docs](https://handmux.com/docs)**.
+Once autostart is installed, `handmux start` / `stop` / `restart` coordinate with that same launchd/systemd service (including after an upgrade). A lifecycle lock prevents concurrent launches; `status` shows the running version and warns with PIDs if stale/duplicate supervisors exist, while `stop` reaps every copy.
 ## Requirements
 Your computer needs **Node ≥ 18** and **tmux ≥ 3.0**; the phone just needs a browser. On **Windows**, run it inside **WSL2** (a real Linux kernel + real tmux) — see the [docs](https://handmux.com/docs#windows).

package/README.zh-CN.md CHANGED Viewed

@@ -124,6 +124,8 @@ handmux push <title> <body> [选项]
 > 隧道配置、服务端反向代理、开机自启、语音 / 推送凭证、端口预览等细节 → 见 **[文档](https://handmux.com/docs)**。
+安装开机自启后，`handmux start` / `stop` / `restart` 会始终与同一个 launchd/systemd 服务协同（升级后也一样）。生命周期锁会阻止并发启动；`status` 显示实际运行版本，并列出未登记/重复 supervisor 的 PID；`stop` 会回收全部副本。
 ## 环境要求
 电脑需 **Node ≥ 18** 与 **tmux ≥ 3.0**;手机只要浏览器。**Windows** 请装进 **WSL2**(真 Linux 内核 + 真 tmux)——见 [文档](https://handmux.com/docs#windows)。

package/bin/handmux.js CHANGED Viewed

@@ -27,9 +27,10 @@ import { supervise, bareUrl, publicUrlWithToken } from '../src/cli/supervisor.js
 import { resolveCloudflared } from '../src/cli/cloudflared.js';
 import { resolveTunlite, checkSshAuth } from '../src/cli/tunlite.js';
 import { resolveNatapp, resolveCpolar } from '../src/cli/tunnelClients.js';
-import { installService, uninstallService } from '../src/cli/service.js';
+import { installService, uninstallService, isServiceInstalled, stopService } from '../src/cli/service.js';
 import { checkTmux, MIN_TMUX, tmuxInstallHint } from '../src/cli/tmuxVersion.js';
-import { readState, clearState, isAlive, pocketHome, logPath, configPath, claudeStatePath } from '../src/cli/state.js';
+import { readState, clearState, isAlive, acquireLifecycleLock, pocketHome, logPath, configPath, claudeStatePath } from '../src/cli/state.js';
+import { scanSupervisorPids, terminateSupervisorPids } from '../src/cli/supervisorProcesses.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';
@@ -136,17 +137,17 @@ async function preflightNgrok(cfg) {
 async function main() {
   switch (command) {
-    case 'start': return start();
+    case 'start': return withLifecycleLock(start);
     case 'open': return openCmd();
-    case 'stop': stop(); return;
-    case 'restart': { stop(); await sleep(600); return start(); }
-    case 'status': return status();
+    case 'stop': return withLifecycleLock(stopAndWait);
+    case 'restart': return withLifecycleLock(async () => { if (!await stopAndWait()) return; return start(); });
+    case 'status': await status(); process.exit(process.exitCode || 0);
     case 'logs': return logs();
     case 'push': process.exitCode = await pushCmd(); return;
     case 'config': return configCmd();
     case 'setup': return setupCmd();
     case 'hooks': return hooksCmd();
-    case 'service': return serviceCmd();
+    case 'service': return withLifecycleLock(serviceCmd);
     case 'update': case 'upgrade': return updateCmd();
     case '__supervise': return runSupervise();
     case '__update-check': return runUpdateCheck(HOME);
@@ -155,12 +156,28 @@ async function main() {
   }
 }
+async function withLifecycleLock(fn) {
+  let release;
+  try { release = acquireLifecycleLock(HOME); }
+  catch (e) {
+    console.error(e.ownerPid
+      ? t('lifecycle.busy', { pid: e.ownerPid })
+      : t('err.generic', { msg: e.message }));
+    process.exitCode = 1;
+    return;
+  }
+  try { return await fn(); }
+  finally { release(); }
+}
 // `handmux --version` / `-v` — print the package version (read from this package's package.json, so it
 // stays in lockstep with what npm installed; no hardcoded string to forget to bump).
 function version() {
-  console.log(requireOpt('../package.json').version);
+  console.log(currentVersion());
 }
+function currentVersion() { return 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.
@@ -203,12 +220,28 @@ async function start() {
   }
   if (!tmux.ok) console.warn(t('tmux.tooOld', { raw: tmux.raw, min: MIN_TMUX }));
+  // state.json cannot represent two supervisors. Refuse to add another when the real process table says
+  // the state is missing/stale or a historical duplicate already exists; `handmux stop` is the repair path.
+  const supervisors = scanSupervisorPids();
+  if (!supervisors.ok) {
+    console.error(t('lifecycle.scanFailed'));
+    process.exitCode = 1;
+    return;
+  }
   // 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);
+  const statePid = existing && isAlive(existing.supervisorPid) ? existing.supervisorPid : null;
+  if (supervisors.pids.length > 1 || (supervisors.pids.length === 1 && supervisors.pids[0] !== statePid)) {
+    console.error(t('start.instancesFound', { pids: supervisors.pids.join(', ') }));
+    console.error(t('start.instancesHint'));
+    process.exitCode = 1;
+    return;
+  }
   if (existing && isAlive(existing.supervisorPid)) {
     const changed = configChanges(cfg, existing);
     if (!changed.length) {
@@ -219,7 +252,8 @@ async function start() {
     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();
+      if (!await stopAndWait()) return;
+      return start();
     }
     console.log(t('start.running.hint'));
     await printAccess(existing);
@@ -260,11 +294,20 @@ async function start() {
     await waitAndPrint(false);
     return;
   }
+  // Once autostart is registered, the service manager must remain the sole owner of the supervisor.
+  // Rewriting + restarting the entry also refreshes baked config and upgrade-sensitive executable paths.
+  if (isServiceInstalled(HOME)) {
+    try { installService(supervisorArgs(cfg), { home: HOME, log: { log() {} } }); }
+    catch (e) { console.error(t('err.generic', { msg: e.message })); process.exit(1); }
+    console.log(t('start.starting', { tunnel: cfg.tunnel, port: cfg.port }));
+    await waitAndPrint(true);
+    return;
+  }
   fs.mkdirSync(pocketHome(HOME), { recursive: true });
   const out = fs.openSync(logPath(HOME), 'a');
-  const payload = Buffer.from(JSON.stringify(cfg)).toString('base64');
-  const child = spawn(process.execPath, [SELF, '__supervise', '--payload', payload],
+  const [supervisorBin, ...supervisorArgv] = supervisorArgs(cfg);
+  const child = spawn(supervisorBin, supervisorArgv,
     { detached: true, stdio: ['ignore', out, out] });
   child.unref();
   console.log(t('start.starting', { tunnel: cfg.tunnel, port: cfg.port }));
@@ -281,24 +324,68 @@ function reapOrphans(st) {
   }
 }
-function stop() {
+// A lifecycle command must not start the replacement while the previous supervisor can still own the
+// port/tunnel. Stop every real supervisor, not only the one last writer recorded in state.json, then rescan
+// until none remain. This both repairs historical duplicates and prevents restart from racing a straggler.
+async function stopAndWait() {
   const st = readState(HOME);
-  if (!st || !isAlive(st.supervisorPid)) {
-    // Supervisor already gone — but a non-graceful death may have orphaned its children. Reap them before
-    // dropping the state file, or nothing ever will.
+  const initial = scanSupervisorPids();
+  if (!initial.ok) {
+    console.error(t('lifecycle.scanFailed'));
+    process.exitCode = 1;
+    return false;
+  }
+  const managed = isServiceInstalled(HOME);
+  if (managed) {
+    try { stopService({ home: HOME }); }
+    catch (e) { console.error(t('err.generic', { msg: e.message })); process.exitCode = 1; return false; }
+  }
+  const seen = new Set(initial.pids);
+  if (st && isAlive(st.supervisorPid)) seen.add(st.supervisorPid);
+  if (!seen.size) {
     if (st) reapOrphans(st);
-    console.log(t('stop.notRunning'));
     clearState(HOME);
-    return;
+    console.log(managed ? t('stop.stoppedManaged') : t('stop.notRunning'));
+    return true;
+  }
+  const result = await terminateSupervisorPids([...seen]);
+  if (!result.ok) {
+    console.error(t(result.reason === 'scan' ? 'lifecycle.scanFailed' : 'stop.timeout', {
+      pids: result.remaining.join(', '),
+    }));
+    process.exitCode = 1;
+    return false;
   }
-  try { process.kill(st.supervisorPid, 'SIGTERM'); } catch { /* race: already gone */ }
-  console.log(t('stop.stopped', { pid: st.supervisorPid }));
+  clearState(HOME);
+  console.log(t(result.pids.length > 1 ? 'stop.stoppedMany' : 'stop.stopped', {
+    pid: result.pids[0], pids: result.pids.join(', '),
+  }));
+  return true;
 }
 async function status() {
   const st = readState(HOME);
-  if (!st || !isAlive(st.supervisorPid)) { console.log(t('status.stopped')); return; }
-  console.log(t('status.running'));
+  const installed = currentVersion();
+  const supervisors = scanSupervisorPids();
+  if (!supervisors.ok) console.warn(t('status.scanFailed'));
+  const stateAlive = !!(st && isAlive(st.supervisorPid));
+  if (supervisors.ok && supervisors.pids.length && !stateAlive) {
+    console.log(t('status.untracked', { version: installed, pids: supervisors.pids.join(', ') }));
+    console.log(t('status.cleanupHint'));
+    process.exitCode = 1;
+    return;
+  }
+  if (!stateAlive) { console.log(t('status.stopped', { version: installed })); return; }
+  const running = st.version || installed;
+  console.log(t('status.running', { version: running }));
+  if (running !== installed) console.log(t('status.installed', { version: installed }));
+  if (supervisors.ok && (supervisors.pids.length > 1
+      || (supervisors.pids.length > 0 && !supervisors.pids.includes(st.supervisorPid)))) {
+    const all = [...new Set([st.supervisorPid, ...supervisors.pids])].sort((a, b) => a - b);
+    console.warn(t('status.duplicates', { pids: all.join(', ') }));
+    console.warn(t('status.cleanupHint'));
+    process.exitCode = 1;
+  }
   await printAccess(st);
 }
@@ -356,13 +443,29 @@ async function serviceInstall() {
     try { await preflightNgrok(cfg); }
     catch (e) { console.error(t('err.generic', { msg: e.message })); process.exit(1); }
   }
-  const payload = Buffer.from(JSON.stringify(cfg)).toString('base64');
-  const args = [process.execPath, SELF, '__supervise', '--payload', payload];
+  // Converge a pre-existing manual run (and any old broken managed/manual pair) before loading the service.
+  // Otherwise the very first `service install` can itself create two supervisors fighting over one port.
+  const existing = readState(HOME);
+  const supervisors = scanSupervisorPids();
+  if (!supervisors.ok) {
+    console.error(t('lifecycle.scanFailed'));
+    process.exitCode = 1;
+    return;
+  }
+  if (isServiceInstalled(HOME) || supervisors.pids.length || (existing && isAlive(existing.supervisorPid))) {
+    if (!await stopAndWait()) return;
+  }
+  const args = supervisorArgs(cfg);
   try { installService(args, { home: HOME }); }
   catch (e) { console.error(t('err.generic', { msg: e.message })); process.exit(1); }
   console.log(t('service.installed'));
 }
+function supervisorArgs(cfg) {
+  const payload = Buffer.from(JSON.stringify(cfg)).toString('base64');
+  return [process.execPath, SELF, '__supervise', '--payload', payload];
+}
 async function setupCmd() {
   const target = flags.config ? path.resolve(flags.config) : configPath(HOME);
   // Is an instance already up? Then the run-action reads "Save & restart" and applying means a real restart
@@ -381,9 +484,11 @@ async function setupCmd() {
   }
   await maybeOfferStatusLine();
   if (doStart) {
-    Object.assign(flags, cfg);
-    if (running) { stop(); await sleep(600); }   // restart into the new config
-    return start();
+    return withLifecycleLock(async () => {
+      Object.assign(flags, cfg);
+      if (running && !await stopAndWait()) return; // restart into the new config
+      return start();
+    });
   }
   console.log(t(running ? 'setup.laterRestart' : 'setup.later'));
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "handmux",
-  "version": "0.17.5",
+  "version": "0.17.7",
   "description": "A mobile vibe-coding cockpit — built on tmux: drive your live session, Claude Code / Codex — anything a terminal can run — from your phone.",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -57,13 +57,13 @@
     "vitest": "^2.0.0"
   },
   "whatsNew": [
+    {"version":"0.17.7","date":"2026-07-20","zh":"单实例启动兜底 · WSL 状态命令修复","en":"Single-instance startup guard · WSL status fix"},
+    {"version":"0.17.6","date":"2026-07-20","zh":"推送结果可追踪 · 对话与权限操作更可靠","en":"Traceable push results · safer chats and permissions"},
     {"version":"0.17.5","date":"2026-07-20","zh":"通知开启修复 · 长会话与设置可靠性提升","en":"Notification setup fixed · stronger chat and settings reliability"},
     {"version":"0.17.4","date":"2026-07-19","zh":"HTTPS 本机预览修复 · 通知链接安全加固","en":"HTTPS localhost previews fixed · safer notification links"},
     {"version":"0.17.3","date":"2026-07-19","zh":"三修官方一键安装的 Claude 识别,真机已验证","en":"Third fix for native-install Claude detection, device-verified"},
     {"version":"0.17.0","date":"2026-07-18","zh":"对话视图(实验性)· 通知记录 · 本机地址一键预览","en":"Chat view (experimental) · notification inbox · one-tap localhost preview"},
     {"version":"0.16.0","date":"2026-07-15","zh":"分屏布局地图 · 手机也能建/删窗格","en":"Split-layout map · create & close panes from the phone"},
-    {"version":"0.15.0","date":"2026-07-14","zh":"键盘弹起终端自适应 · 全屏程序可上下滚动","en":"Keyboard-aware terminal · scroll inside full-screen apps"},
-    {"version":"0.14.0","date":"2026-07-13","zh":"终端文字选中拷贝 · 脚本复用推送通道","en":"Terminal select & copy · scripts reuse the push channel"},
-    {"version":"0.13.0","date":"2026-07-12","zh":"终端文件路径高亮可点","en":"Tappable, highlighted file paths"}
+    {"version":"0.15.0","date":"2026-07-14","zh":"键盘弹起终端自适应 · 全屏程序可上下滚动","en":"Keyboard-aware terminal · scroll inside full-screen apps"}
   ]
 }