seshmux 0.1.4 → 0.1.6

package/README.md

@@ -52,6 +52,22 @@ npx seshmux
 
 Opens `http://127.0.0.1:4700` in your browser. No account, no config, no server to host.
 
+### Commands
+
+```bash
+seshmux                    # start (reuses a running instance if there is one)
+seshmux --port 4800        # bind a different port ($PORT works too)
+seshmux --no-open          # don't open a browser
+
+seshmux update             # check npm for a newer release and install it
+seshmux update --check     # just tell me, don't install
+seshmux --version
+
+seshmux --restart-daemon   # replace the session daemon (see below)
+```
+
+Updating also upgrades the session daemon, but only when nothing would be lost — see [Updates that never kill a session](#updates-that-never-kill-a-session).
+
 ### Requirements
 
 | Dependency | Required? | What it unlocks |

package/bin/seshmux.js

@@ -18,7 +18,7 @@ const http = require('node:http');
 const { randomBytes } = require('node:crypto');
 const path = require('node:path');
 const fs = require('node:fs');
-const { ensureDaemon, pidAlive, paths, configDir } = require('../daemon/ensure');
+const { ensureDaemon, pidAlive, paths, configDir, daemonInfo, canSafelyRestartDaemon } = require('../daemon/ensure');
 
 // The daemon's pid, from the pidfile it writes in the config dir. null when it isn't running.
 function readDaemonPid() {
@@ -30,6 +30,174 @@ function readDaemonPid() {
   }
 }
 
+// Stop the running daemon (if any) and start a fresh one. The ONLY kill+respawn path —
+// shared by --restart-daemon (explicit, may end plain PTYs) and the post-update auto-upgrade
+// (which only calls this once canSafelyRestartDaemon() says every live PTY is tmux-backed).
+// Returns false if the old daemon refused to die (we never start a second one).
+async function restartDaemon() {
+  const before = readDaemonPid();
+  if (before) {
+    try {
+      process.kill(before, 'SIGTERM');
+    } catch {
+      /* already gone */
+    }
+    for (let i = 0; i < 40 && pidAlive(before); i++) await new Promise((r) => setTimeout(r, 100));
+    if (pidAlive(before)) {
+      console.error(`[seshmux] daemon ${before} did not stop; not starting a second one`);
+      return false;
+    }
+  }
+  const { spawned } = await ensureDaemon();
+  console.log(`[seshmux] daemon ${spawned ? 'restarted' : 'already up'} (pid ${readDaemonPid() ?? '?'})`);
+  return true;
+}
+
+// Read the version FRESH every time, never once. `require` caches, and this supervisor
+// deliberately survives a self-update (it is what relaunches the server child) — so a cached
+// read meant the updated server was told it was still the OLD version, and the "update
+// available" banner stayed up forever. readFileSync, not require, precisely to dodge the cache.
+function currentVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+// Latest published version, or null (offline, 404, timeout — never throws, never blocks).
+function latestVersion(timeoutMs = 5000) {
+  return new Promise((resolve) => {
+    const req = require('node:https').get(
+      'https://registry.npmjs.org/seshmux/latest',
+      { timeout: timeoutMs },
+      (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          return resolve(null);
+        }
+        let body = '';
+        res.on('data', (c) => (body += c));
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(body).version || null);
+          } catch {
+            resolve(null);
+          }
+        });
+      },
+    );
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+
+// `seshmux update` / `seshmux update --check`.
+//
+// Installs the EXACT version the registry reported, with --prefer-online. Never `@latest`:
+// npm re-resolves that tag through its CACHED packument, so anyone whose cache predates the
+// release resolves latest -> X from the network and then dies with
+// "ETARGET: No matching version found for seshmux@X" from the cache. That bug shipped once
+// already (the in-app button announced updates it could not install); do not reintroduce it.
+async function runUpdate(checkOnly) {
+  const current = currentVersion();
+  const latest = await latestVersion();
+  if (!latest) {
+    console.error("[seshmux] couldn't reach the npm registry (offline?) — nothing changed");
+    process.exit(1);
+  }
+  if (!versionLess(current, latest)) {
+    console.log(`[seshmux] already on the latest version (v${current})`);
+    return;
+  }
+  console.log(`[seshmux] update available: v${current} -> v${latest}`);
+  if (checkOnly) return;
+
+  const code = await new Promise((resolve) => {
+    const child = spawn('npm', ['i', '-g', `seshmux@${latest}`, '--prefer-online'], { stdio: 'inherit' });
+    child.on('exit', (c) => resolve(c ?? 1));
+    child.on('error', () => resolve(1));
+  });
+  if (code !== 0) {
+    console.error(`[seshmux] install failed (npm exited ${code}) — still on v${current}`);
+    process.exit(code);
+  }
+
+  // The package on disk is new; the daemon still runs the old code. Upgrade it too, but only
+  // when nothing dies (holder- and tmux-tier PTYs re-attach; a pre-holder plain PTY would not).
+  await autoUpgradeDaemon(currentVersion()).catch(() => {});
+
+  console.log(`[seshmux] updated to v${latest}`);
+  if (await probeHealth(4700)) console.log('[seshmux] a seshmux is running — restart it to use the new version');
+}
+
+// Numeric-segment version compare ("0.10.0" > "0.9.0"). Mirror of server/lib/update.ts's
+// compareVersions — this file is plain CJS and cannot import the TS module.
+function versionLess(a, b) {
+  const pa = a.split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = b.split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d < 0;
+  }
+  return false;
+}
+
+// After a self-update the server is new but the daemon still runs the OLD code forever
+// (ensureDaemon reuses any daemon that answers hello). Upgrade it here — but ONLY when no live
+// session would die: tmux-tier PTYs rehydrate in the fresh daemon, plain-tier PTYs do not.
+// Unreachable daemon / unknown versions (dev) → do nothing.
+// Returns 'upgraded' | 'blocked' | 'noop'. quiet=true suppresses the blocked log (the retry
+// loop below would otherwise repeat it forever).
+async function autoUpgradeDaemon(ourVersion, quiet) {
+  const info = await daemonInfo(paths(configDir()).sock).catch(() => null);
+  if (!info || !info.version || !ourVersion || ourVersion === '0.0.0') return 'noop';
+  if (!versionLess(info.version, ourVersion)) return 'noop';
+
+  const { safe, plainCount } = canSafelyRestartDaemon(info.ptys);
+  if (!safe) {
+    if (!quiet) {
+      console.log(
+        `[seshmux] daemon stays on v${info.version} for now — ${plainCount} running session(s) are not tmux-backed ` +
+          'and a restart would end them. It will upgrade itself as soon as they finish.',
+      );
+    }
+    return 'blocked';
+  }
+  const tmuxCount = info.ptys.filter((p) => p.tmuxName && p.alive !== false).length;
+  console.log(
+    `[seshmux] upgrading daemon v${info.version} -> v${ourVersion}` +
+      (tmuxCount ? ` (${tmuxCount} tmux session(s) will re-attach)` : ''),
+  );
+  await restartDaemon();
+  return 'upgraded';
+}
+
+// A blocked upgrade must not stay blocked forever. Without tmux a PTY simply cannot outlive the
+// daemon that owns its master fd — that is the OS, not a bug we can fix — so the answer is NOT to
+// demand the user install tmux, it is to never need the restart at a bad moment. The daemon is
+// harmless while stale (protocol frozen at 1; newer RPCs degrade, they don't fail), so it can
+// simply WAIT for a safe moment: every live session ended, or all remaining ones are tmux-backed.
+// Then it upgrades itself, with nothing killed and nothing for the user to type.
+const UPGRADE_RETRY_MS = Number(process.env.SESHMUX_UPGRADE_RETRY_MS) || 60_000;
+function scheduleDaemonUpgrade(getVersion) {
+  let announced = false;
+  const tick = async () => {
+    const result = await autoUpgradeDaemon(getVersion(), announced).catch(() => 'noop');
+    if (result === 'blocked') {
+      announced = true; // say it once, then wait quietly
+      return;
+    }
+    clearInterval(timer); // upgraded, or nothing to do — stop checking
+  };
+  const timer = setInterval(tick, UPGRADE_RETRY_MS);
+  if (timer.unref) timer.unref(); // never hold the process open on this alone
+  tick();
+}
+
 // Absolute path to THIS cli entry, inherited by the server child. The MCP
 // bridge registration writes it into agent configs (`node <bin> mcp-bridge`) —
 // `npx seshmux` only resolves once the package is published to a registry.
@@ -147,6 +315,99 @@ function runMcpBridge(root) {
   child.on('exit', (code) => process.exit(code ?? 0));
 }
 
+// Is a binary on PATH? Shell-free.
+function have(bin) {
+  return new Promise((resolve) => {
+    execFile('which', [bin], (err, stdout) => resolve(!err && !!String(stdout).trim()));
+  });
+}
+
+// The package manager we can offer to install tmux with, or null when there is nothing to offer.
+async function tmuxInstaller() {
+  if (process.platform === 'darwin' && (await have('brew'))) return { cmd: 'brew', args: ['install', 'tmux'] };
+  if (await have('apt-get')) return { cmd: 'sudo', args: ['apt-get', 'install', '-y', 'tmux'] };
+  if (await have('dnf')) return { cmd: 'sudo', args: ['dnf', 'install', '-y', 'tmux'] };
+  return null;
+}
+
+// Resolves 'yes' | 'no' | 'none'. 'none' = the user never actually answered (stdin hit EOF, or
+// the terminal went away): rl.question's callback then NEVER fires, which would hang startup
+// forever. Booting the app matters more than this prompt, so no answer means "skip it, ask again
+// next time" — never a silent decline the user did not make.
+function askYesNo(question) {
+  return new Promise((resolve) => {
+    const rl = require('node:readline').createInterface({ input: process.stdin, output: process.stdout });
+    let done = false;
+    const finish = (v) => {
+      if (done) return;
+      done = true;
+      rl.close();
+      resolve(v);
+    };
+    rl.on('close', () => finish('none')); // EOF / ^D / stdin closed
+    rl.question(question, (answer) => finish(/^n/i.test(String(answer).trim()) ? 'no' : 'yes'));
+  });
+}
+
+// Without tmux, a session's PTY is owned by the daemon and dies with it — a crash or a daemon
+// restart ends the user's running agent. session-start.ts picks the tmux tier ONLY when tmux is
+// on PATH, so a tmux-less machine silently gets the fragile tier and nobody says a word. A real
+// user lost every session this way. Offer to fix it, once, and never nag again.
+//
+// NOT an npm postinstall: that needs a package manager we can't assume, is skipped entirely under
+// `npm ci --ignore-scripts` (standard in CI), would run in Docker images where tmux is pointless,
+// and shelling out to a system installer from an install hook is exactly what supply-chain
+// scanners flag. A first-run prompt asks the person who is actually there.
+async function offerTmux() {
+  if (await have('tmux')) return;
+  const ackFile = path.join(configDir(), 'tmux-declined');
+  if (fs.existsSync(ackFile)) return;
+
+  const durability =
+    '[seshmux] tmux is not installed.\n' +
+    '  Your agent sessions will end if seshmux restarts or crashes.\n' +
+    '  With tmux, they survive restarts, updates, and crashes.';
+
+  // Non-interactive (piped, CI, launched by a GUI): state it, never block on a prompt nobody
+  // can answer, and do not record a decline the user never made.
+  if (!process.stdin.isTTY) {
+    console.log(`${durability}\n  Install tmux to make sessions durable.`);
+    return;
+  }
+
+  const installer = await tmuxInstaller();
+  if (!installer) {
+    console.log(`${durability}\n  Install tmux with your package manager to make sessions durable.`);
+    return;
+  }
+
+  console.log(durability);
+  const answer = await askYesNo(`\n  Install tmux now with ${installer.cmd}? [Y/n] `);
+  if (answer === 'none') return; // no answer given — boot anyway, ask again next launch
+  if (answer === 'no') {
+    try {
+      fs.mkdirSync(path.dirname(ackFile), { recursive: true });
+      fs.writeFileSync(ackFile, 'declined\n');
+    } catch {
+      /* best effort — worst case we ask again next launch */
+    }
+    console.log('[seshmux] continuing without tmux (sessions are not crash-safe). Not asking again.');
+    return;
+  }
+
+  console.log(`[seshmux] ${installer.cmd} ${installer.args.join(' ')}…`);
+  await new Promise((resolve) => {
+    const child = spawn(installer.cmd, installer.args, { stdio: 'inherit' });
+    child.on('exit', resolve);
+    child.on('error', resolve);
+  });
+  console.log(
+    (await have('tmux'))
+      ? '[seshmux] tmux installed — new sessions will survive restarts and crashes.'
+      : '[seshmux] tmux install did not complete; continuing without it.',
+  );
+}
+
 async function main() {
   // Subcommand dispatch (before arg parsing / server flow).
   const argv = process.argv.slice(2);
@@ -155,36 +416,34 @@ async function main() {
     runMcpBridge(root);
     return;
   }
+  if (argv[0] === 'update') {
+    await runUpdate(argv.includes('--check'));
+    return;
+  }
+  if (argv[0] === 'version' || argv.includes('--version') || argv.includes('-v')) {
+    console.log(currentVersion());
+    return;
+  }
 
   const args = parseArgs(argv);
 
-  // --restart-daemon: the ONLY way to upgrade the daemon. ensureDaemon() treats any daemon that
-  // answers hello as 'ok' and reuses it (daemon/ensure.js classify()), which is what keeps your
-  // sessions alive across server updates — but it also means a daemon started months ago runs
-  // forever, missing every RPC added since. Restarting seshmux does NOT replace it. This does.
+  // --restart-daemon: the manual escape hatch for upgrading the daemon (the update flow does it
+  // automatically, but ONLY when no plain PTY would die — see autoUpgradeDaemon). ensureDaemon()
+  // treats any daemon that answers hello as 'ok' and reuses it (daemon/ensure.js classify()),
+  // which is what keeps your sessions alive across server updates — restarting seshmux does NOT
+  // replace the daemon. This does.
   //
-  // Destructive on purpose, so it is explicit and never automatic: tmux-tier sessions rehydrate
-  // from `tmux ls` and survive, but PLAIN-tier PTYs die with the daemon. Hence a flag the user
-  // types, not something the update flow does behind their back.
+  // Destructive on purpose: tmux-tier sessions rehydrate from `tmux ls` and survive, PLAIN-tier
+  // PTYs die with the daemon. The automatic path refuses to run in that case; this flag is the
+  // explicit "do it anyway, I accept losing them".
   if (args.restartDaemon) {
     const before = readDaemonPid();
     if (before) {
       console.log(`[seshmux] stopping daemon ${before} — tmux-backed sessions survive; any non-tmux PTYs will end`);
-      try {
-        process.kill(before, 'SIGTERM');
-      } catch {
-        /* already gone */
-      }
-      for (let i = 0; i < 40 && pidAlive(before); i++) await new Promise((r) => setTimeout(r, 100));
-      if (pidAlive(before)) {
-        console.error(`[seshmux] daemon ${before} did not stop; not starting a second one`);
-        process.exit(1);
-      }
     } else {
       console.log('[seshmux] no daemon running');
     }
-    const { spawned } = await ensureDaemon();
-    console.log(`[seshmux] daemon ${spawned ? 'restarted' : 'already up'} (pid ${readDaemonPid() ?? '?'})`);
+    if (!(await restartDaemon())) process.exit(1);
   }
 
   // If a healthy seshmux already runs on the requested port range, just open the
@@ -197,6 +456,11 @@ async function main() {
     return;
   }
 
+  // Ask about tmux BEFORE the daemon starts, so a yes takes effect for the very first session
+  // (session-start.ts picks the tmux tier only if tmux is on PATH at spawn time). Only reached
+  // when we are actually starting seshmux — never when we just hand off to a running instance.
+  await offerTmux().catch(() => {}); // never block startup on this
+
   // Ensure a responsive daemon BEFORE the server comes up. Spawns detached +
   // unref'd if needed; recovers a stale socket. Non-fatal if it can't start —
   // the app degrades to browse-only (no live terminals) rather than refusing.
@@ -242,20 +506,6 @@ async function main() {
   };
   if (isProd) env.NODE_ENV = 'production';
 
-  // Read the version FRESH on every spawn, never once. `require` caches, and this supervisor
-  // deliberately survives a self-update (it is what relaunches the server child) — so a cached
-  // read meant the updated server was told it was still the OLD version. The user updated, the
-  // new code ran, and the "update available" banner stayed up forever because current never
-  // moved. Re-reading the file each spawn means the relaunch after an update sees the new
-  // version. readFileSync, not require, precisely to dodge the module cache.
-  function currentVersion() {
-    try {
-      return JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version;
-    } catch {
-      return '0.0.0';
-    }
-  }
-
   function spawnServer() {
     env.SESHMUX_VERSION = currentVersion();
     return isProd
@@ -270,6 +520,11 @@ async function main() {
   let child = spawnServer();
   if (!args.noOpen) setTimeout(() => openBrowser(url), 1500);
 
+  // Also on plain startup, not just after an update: a previous run may have deferred the upgrade
+  // (sessions were running), or the user updated and quit before it could finish. Without this, a
+  // daemon that was stale once could stay stale forever.
+  scheduleDaemonUpgrade(currentVersion);
+
   // NOTE: shutdown kills the SERVER child only — never the daemon. The daemon is
   // detached and holds live PTYs across this process's death (update-safety).
   let shuttingDown = false;
@@ -289,7 +544,7 @@ async function main() {
   // and printed by the server before it exits.
   const RESTART_CODE = 75;
   let restartTimes = [];
-  const onExit = (code) => {
+  const onExit = async (code) => {
     if (shuttingDown) return;
     if (code === RESTART_CODE) {
       const now = Date.now();
@@ -302,7 +557,11 @@ async function main() {
         );
         process.exit(1);
       }
-      console.log('[seshmux] server restarting for update (session-safe; daemon untouched)…');
+      console.log('[seshmux] server restarting for update (session-safe)…');
+      // One-click means one click: the new package is on disk now, so upgrade the daemon too —
+      // but only if every live PTY is tmux-backed (it re-attaches). If a plain session would die,
+      // this defers and the retry loop finishes the job the moment that session ends.
+      scheduleDaemonUpgrade(currentVersion);
       child = spawnServer();
       child.on('exit', onExit);
       return;

package/daemon/ensure.js

@@ -109,6 +109,59 @@ function tryHello(sockPath, timeoutMs = HELLO_TIMEOUT_MS) {
   });
 }
 
+/**
+ * PURE predicate (unit-tested): may we restart the daemon without ending a live agent session?
+ * tmux-tier PTYs rehydrate from `tmux ls` in the fresh daemon and survive; PLAIN-tier PTYs
+ * (tmuxName null — machine without tmux) die with it. So: safe only when every LIVE pty is
+ * tmux-backed, or there are none. Dead entries can't be killed twice, so they don't block.
+ * @param {{tmuxName: string|null, alive?: boolean}[]} ptys — the daemon's `list` result
+ * @returns {{safe: boolean, plainCount: number}}
+ */
+function canSafelyRestartDaemon(ptys) {
+  const live = (ptys || []).filter((p) => p && p.alive !== false);
+  const plainCount = live.filter((p) => !p.tmuxName).length;
+  return { safe: plainCount === 0, plainCount };
+}
+
+/**
+ * One dial: hello + list. Resolves { version, ptys } or null if the daemon isn't reachable.
+ * Used by the supervisor's auto-upgrade decision (bin/seshmux.js) — never throws.
+ */
+function daemonInfo(sockPath, timeoutMs = HELLO_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let version = null;
+    const done = (v) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        sock.destroy();
+      } catch {
+        /* ignore */
+      }
+      resolve(v);
+    };
+    const timer = setTimeout(() => done(null), timeoutMs);
+    const decoder = createDecoder();
+    const sock = net.connect(sockPath);
+    sock.setEncoding('utf8');
+    sock.on('connect', () => {
+      sock.write(encode({ id: 1, method: 'hello' }));
+      sock.write(encode({ id: 2, method: 'list' }));
+    });
+    sock.on('data', (chunk) => {
+      for (const msg of decoder.push(chunk)) {
+        if (!msg || !msg.result) continue;
+        if (msg.id === 1) version = msg.result.version || null;
+        if (msg.id === 2) done({ version, ptys: msg.result.ptys || [] });
+      }
+    });
+    sock.on('error', () => done(null));
+    sock.on('close', () => done(null));
+  });
+}
+
 const sleep = (ms) =>
   new Promise((r) => {
     setTimeout(r, ms);
@@ -218,6 +271,8 @@ async function ensureDaemon(opts = {}) {
 
 module.exports = {
   classify,
+  canSafelyRestartDaemon,
+  daemonInfo,
   pidAlive,
   tryHello,
   ensureDaemon,