seshmux 0.1.4 → 0.1.5

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,93 @@ 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;
+}
+
+// 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 +234,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);
@@ -158,33 +338,23 @@ async function main() {
 
   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 +367,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.
@@ -270,6 +445,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 +469,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 +482,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,

package/daemon/holder.js

@@ -0,0 +1,248 @@
+'use strict';
+/**
+ * seshmux PTY holder — a tiny detached process that OWNS one PTY.
+ *
+ * Why: the daemon used to `pty.spawn` directly, so it held the master fd. Kill
+ * the daemon (crash, restart, upgrade) and the fd closed, the child got SIGHUP,
+ * and the user's agent died. Only the tmux tier survived, because tmux owned
+ * the process. The holder is the tmux tier for machines without tmux: it sits
+ * between the daemon and the PTY, is spawned detached+setsid+unref'd, ignores
+ * SIGHUP, and keeps buffering output while no daemon is attached.
+ *
+ * Plain CJS, zero build step, node-pty is the only dep (same rules as daemon/).
+ *
+ * Wire (NDJSON, same framing helpers as the daemon protocol — this is the
+ * holder<->daemon link, NOT the frozen daemon<->server protocol):
+ *   holder -> daemon:  {event:'ready', ptyId}        first frame to the accepted client
+ *                      {event:'busy'}                a client is already attached; go away
+ *                      {event:'data', data}          replay (one frame) then live output
+ *                      {event:'exit', code}          the PTY exited
+ *   daemon -> holder:  {method:'write', data}
+ *                      {method:'resize', cols, rows}
+ *                      {method:'kill'}
+ *
+ * Exactly ONE client at a time (that's the no-double-attach guarantee). A
+ * client disconnect never touches the PTY.
+ *
+ * Argv: node holder.js '<json spec>' where spec =
+ *   { holderDir, ptyId, sock, cwd, args, cols, rows, env }
+ */
+
+const net = require('node:net');
+const fs = require('node:fs');
+const path = require('node:path');
+const pty = require('@homebridge/node-pty-prebuilt-multiarch');
+const {
+  RING_BUFFER_LINES,
+  RING_BUFFER_BYTES,
+  encode,
+  createDecoder,
+} = require('./protocol');
+
+// After the PTY exits we keep the socket up so a daemon that reconnects can
+// still learn the exit code. Long grace when nobody knew; short when a live
+// client already got the exit frame (or explicitly asked for the kill), so we
+// don't leave a node process loitering for a minute per closed session.
+const EXIT_GRACE_MS = 60 * 1000;
+const EXIT_GRACE_KNOWN_MS = 5 * 1000;
+
+// The daemon's death must not be ours. (detached+stdio:'ignore' covers the fd
+// side; this covers the signal side.)
+process.on('SIGHUP', () => {});
+
+const spec = JSON.parse(process.argv[2] || '{}');
+const { holderDir, ptyId, sock: sockPath, cwd, args, cols, rows, env } = spec;
+const jsonPath = path.join(holderDir, ptyId + '.json');
+
+const proc = pty.spawn(args[0], args.slice(1), {
+  name: 'xterm-256color',
+  cols: cols || 80,
+  rows: rows || 24,
+  cwd,
+  env: { ...process.env, ...(env || {}) },
+});
+
+// Same ring semantics (and same caps) as the daemon's — bytes are replayed
+// verbatim, never re-lined, so escape sequences survive.
+const ring = [];
+let ringLines = 0;
+let ringBytes = 0;
+
+function countNewlines(str) {
+  let n = 0;
+  for (let i = 0; i < str.length; i++) if (str.charCodeAt(i) === 10) n++;
+  return n;
+}
+
+function appendRing(chunk) {
+  ring.push(chunk);
+  ringLines += countNewlines(chunk);
+  ringBytes += chunk.length;
+  while (ring.length > 1 && (ringLines > RING_BUFFER_LINES || ringBytes > RING_BUFFER_BYTES)) {
+    const dropped = ring.shift();
+    ringLines -= countNewlines(dropped);
+    ringBytes -= dropped.length;
+  }
+}
+
+/** @type {net.Socket|null} the single attached client (the daemon) */
+let client = null;
+/** @type {{code:number}|null} */
+let exited = null;
+let exitKnown = false; // a client saw the exit, or asked for the kill
+let cleaning = false;
+let cleanupTimer = null;
+
+/** (Re)arm the post-exit grace. Shortened once a client has learned the exit —
+ *  a short-lived process can exit before the daemon even finishes connecting,
+ *  so the grace is re-armed on connect, not decided once at exit time. */
+function scheduleCleanup(ms) {
+  if (cleanupTimer) clearTimeout(cleanupTimer);
+  cleanupTimer = setTimeout(cleanup, ms);
+}
+
+function send(msg) {
+  if (client && !client.destroyed) client.write(encode(msg));
+}
+
+proc.onData((data) => {
+  appendRing(data);
+  send({ event: 'data', data });
+});
+
+proc.onExit(({ exitCode }) => {
+  exited = { code: exitCode };
+  if (client && !client.destroyed) exitKnown = true;
+  send({ event: 'exit', code: exitCode });
+  scheduleCleanup(exitKnown ? EXIT_GRACE_KNOWN_MS : EXIT_GRACE_MS);
+});
+
+/** Remove socket + json and go. Never leave orphan files behind. */
+function cleanup() {
+  if (cleaning) return;
+  cleaning = true;
+  try {
+    server.close();
+  } catch {
+    // ignore
+  }
+  for (const p of [sockPath, jsonPath]) {
+    try {
+      fs.unlinkSync(p);
+    } catch {
+      // ignore
+    }
+  }
+  process.exit(0);
+}
+
+function handle(msg) {
+  switch (msg && msg.method) {
+    case 'write':
+      try {
+        proc.write(msg.data);
+      } catch {
+        // pty already gone
+      }
+      return;
+    case 'resize':
+      try {
+        proc.resize(msg.cols || cols || 80, msg.rows || rows || 24);
+      } catch {
+        // pty already gone
+      }
+      return;
+    case 'kill':
+      exitKnown = true;
+      try {
+        proc.kill();
+      } catch {
+        // already dead
+      }
+      return;
+    default:
+      // ignore unknown
+  }
+}
+
+const server = net.createServer((s) => {
+  // Single-client rule: a second daemon can never attach the same holder.
+  if (client && !client.destroyed) {
+    s.write(encode({ event: 'busy' }));
+    s.end();
+    return;
+  }
+  client = s;
+  const decoder = createDecoder();
+  s.on('data', (chunk) => {
+    for (const m of decoder.push(chunk.toString('utf8'))) handle(m);
+  });
+  s.on('error', () => {
+    if (client === s) client = null;
+  });
+  s.on('close', () => {
+    if (client === s) client = null;
+    // The daemon that knew about the exit has gone; nothing left to tell.
+    if (exited && exitKnown) cleanup();
+  });
+
+  // ready -> replay -> live, all in this tick: nothing can slip into the gap.
+  s.write(encode({ event: 'ready', ptyId }));
+  const replay = ring.join('');
+  if (replay) s.write(encode({ event: 'data', data: replay }));
+  if (exited) {
+    exitKnown = true;
+    s.write(encode({ event: 'exit', code: exited.code }));
+    scheduleCleanup(EXIT_GRACE_KNOWN_MS); // this client now knows; don't loiter
+  }
+});
+
+for (const sig of ['SIGTERM', 'SIGINT']) {
+  process.on(sig, () => {
+    try {
+      proc.kill();
+    } catch {
+      // ignore
+    }
+    cleanup();
+  });
+}
+
+try {
+  fs.unlinkSync(sockPath);
+} catch {
+  // no stale socket — fine
+}
+
+server.listen(sockPath, () => {
+  try {
+    fs.chmodSync(sockPath, 0o600);
+  } catch {
+    // best effort
+  }
+  // Written AFTER listen, so a json on disk implies a socket to dial.
+  fs.writeFileSync(
+    jsonPath,
+    JSON.stringify({
+      ptyId,
+      pid: process.pid,
+      sock: sockPath,
+      cwd,
+      args,
+      cols: cols || 80,
+      rows: rows || 24,
+      startedAt: Date.now(),
+    })
+  );
+});
+
+server.on('error', () => {
+  // Can't listen (path too long, dir gone): the PTY is unreachable, so don't
+  // strand it — kill it and exit rather than leaving an invisible child.
+  try {
+    proc.kill();
+  } catch {
+    // ignore
+  }
+  cleanup();
+});

package/daemon/index.js

@@ -243,7 +243,10 @@ async function startDaemon(opts = {}) {
 
   fs.writeFileSync(pidPath, String(process.pid));
 
-  // Re-hydrate any surviving tmux-tier sessions (no-op if tmux absent).
+  // Adopt PTYs that outlived the previous daemon: holder tier first (ptyIds are
+  // preserved there, and they were already reserved in the PtyManager ctor),
+  // then tmux-tier sessions (no-op if tmux absent).
+  await ptyManager.rehydrateHolders();
   await ptyManager.rehydrateTmux();
 
   return { server, ptyManager, sockPath, pidPath, close };