@dmsdc-ai/aigentry-telepty 0.4.3 → 0.4.5

package/daemon.js

@@ -6,7 +6,7 @@ const crypto = require('crypto');
 const { WebSocketServer } = require('ws');
 const { getConfig } = require('./auth');
 const pkg = require('./package.json');
-const { claimDaemonState, clearDaemonState } = require('./daemon-control');
+const { claimDaemonState, clearDaemonState, isProcessRunning } = require('./daemon-control');
 const { checkEntitlement } = require('./entitlement');
 const terminalBackend = require('./terminal-backend');
 const { FileMailbox } = require('./src/mailbox/index');
@@ -16,6 +16,8 @@ const { SessionStateManager, STATE_DISPLAY, stripAnsi: stripAnsiState } = requir
 const { classifyReportPrompt, buildAutoSummary } = require('./src/report-enforcement');
 const submitGate = require('./src/submit-gate');
 const readyRegistry = require('./src/prompt-symbol-registry');
+const lifecycle = require('./src/lifecycle');
+const { loadTeleptyConfig } = require('./src/config-file');
 
 const config = getConfig();
 const EXPECTED_TOKEN = config.authToken;
@@ -27,6 +29,7 @@ const SESSION_STALE_SECONDS = Math.max(1, Number(process.env.TELEPTY_SESSION_STA
 const SESSION_CLEANUP_SECONDS = Math.max(SESSION_STALE_SECONDS, Number(process.env.TELEPTY_SESSION_CLEANUP_SECONDS || 300));
 const DELIVERY_TIMEOUT_MS = Math.max(100, Number(process.env.TELEPTY_DELIVERY_TIMEOUT_MS || 5000));
 const HEALTH_POLL_MS = Math.max(100, Number(process.env.TELEPTY_HEALTH_POLL_MS || 10000));
+const IDLE_REAPER_POLL_MS = Math.max(100, Number(process.env.TELEPTY_IDLE_REAPER_POLL_MS || 60000));
 const BOOTSTRAP_READY_TIMEOUT_MS = Math.max(500, Number(process.env.TELEPTY_BOOTSTRAP_READY_TIMEOUT_MS || 30000));
 const WRAPPED_SUBMIT_DELAY_MS = 500;
 
@@ -139,7 +142,11 @@ function persistSessions() {
         lastConnectedAt: s.lastConnectedAt || null,
         lastDisconnectedAt: s.lastDisconnectedAt || null,
         lastStateReportAt: s.lastStateReportAt || null,
-        stateReport: s.stateReport || null
+        stateReport: s.stateReport || null,
+        idleTtl: s.idleTtl || null,
+        idleTtlMs: s.idleTtlMs == null ? null : s.idleTtlMs,
+        ownerPid: s.ownerPid || null,
+        ptyPid: s.ptyPid || null
       };
     }
     fs.mkdirSync(require('path').dirname(SESSION_PERSIST_PATH), { recursive: true });
@@ -266,6 +273,13 @@ const AUTO_REPORT_IDLE_SECONDS = Number(process.env.TELEPTY_AUTO_REPORT_IDLE_SEC
 const sessions = {};
 const handoffs = {};
 const threads = {};
+let teleptyConfig;
+try {
+  teleptyConfig = loadTeleptyConfig();
+} catch (err) {
+  console.error(`[CONFIG] Failed to load telepty config: ${err.message}`);
+  process.exit(1);
+}
 
 function broadcastBusEvent(event) {
   const serialized = JSON.stringify(event);
@@ -357,6 +371,53 @@ function getSessionHealthReason(session, healthStatus) {
   return session.ptyProcess && !session.ptyProcess.killed ? 'PTY_RUNNING' : 'PTY_EXITED';
 }
 
+function parseOptionalIdleTtl(body) {
+  if (!body || !Object.prototype.hasOwnProperty.call(body, 'idle_ttl')) {
+    return { present: false };
+  }
+  try {
+    return {
+      present: true,
+      raw: body.idle_ttl == null ? 'off' : String(body.idle_ttl),
+      ms: lifecycle.parseDuration(body.idle_ttl == null ? 'off' : body.idle_ttl, { fieldName: 'idle_ttl' })
+    };
+  } catch (err) {
+    return { present: true, error: err.message };
+  }
+}
+
+function applyProcessMetadata(session, body) {
+  if (!session || !body) return;
+  const ownerPid = Number(body.owner_pid);
+  const ptyPid = Number(body.pty_pid);
+  if (Number.isInteger(ownerPid) && ownerPid > 0) {
+    session.ownerPid = ownerPid;
+  }
+  if (Number.isInteger(ptyPid) && ptyPid > 0) {
+    session.ptyPid = ptyPid;
+  }
+}
+
+function applyIdleTtlMetadata(session, parsedIdleTtl) {
+  if (!session || !parsedIdleTtl || !parsedIdleTtl.present || parsedIdleTtl.error) return;
+  session.idleTtl = parsedIdleTtl.raw;
+  session.idleTtlMs = parsedIdleTtl.ms;
+}
+
+function applyTimestampMetadata(session, body) {
+  if (!session || !body) return;
+  for (const [field, prop] of [
+    ['created_at', 'createdAt'],
+    ['last_activity_at', 'lastActivityAt']
+  ]) {
+    if (!Object.prototype.hasOwnProperty.call(body, field)) continue;
+    const value = body[field] == null ? null : String(body[field]);
+    if (value && Number.isFinite(new Date(value).getTime())) {
+      session[prop] = value;
+    }
+  }
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1104,6 +1165,11 @@ function serializeSession(id, session, options = {}) {
     healthReason,
     disconnectedSeconds: disconnectedMs === null ? null : Math.floor(disconnectedMs / 1000),
     lastStateReportAt: session.lastStateReportAt || null,
+    idleTtl: session.idleTtl || null,
+    idleTtlMs: session.idleTtlMs == null ? null : session.idleTtlMs,
+    effectiveIdleTtlMs: lifecycle.effectiveIdleTtlMs(session, teleptyConfig),
+    ownerPid: session.ownerPid || null,
+    ptyPid: session.ptyPid || (session.ptyProcess && session.ptyProcess.pid) || null,
     transport,
     semantic,
     autoState: autoState ? {
@@ -1123,6 +1189,53 @@ function serializeSession(id, session, options = {}) {
   };
 }
 
+async function teardownSessionById(id, options = {}) {
+  const session = sessions[id];
+  if (!session) {
+    return { success: false, httpStatus: 404, error: 'Session not found' };
+  }
+
+  const timeoutMs = Math.max(0, Number(options.timeoutMs ?? 5000));
+  const force = options.force === true;
+  const reason = options.reason || (force ? 'manual_force' : 'manual');
+  session.isClosing = true;
+
+  const kill = await lifecycle.killSessionProcess(session, { timeoutMs, force });
+  emitSessionLifecycleEvent('session_closed', id, session, {
+    reason,
+    force,
+    pid: kill.pid,
+    signal: kill.signal || null,
+    escalated: kill.escalated === true,
+    source: options.source || 'daemon'
+  });
+
+  if (session.clients) {
+    session.clients.forEach(ws => {
+      try { ws.close(1000, 'Session destroyed'); } catch {}
+    });
+  }
+  if (session.ownerWs) {
+    try { session.ownerWs.close(1000, 'Session destroyed'); } catch {}
+  }
+
+  delete sessions[id];
+  sessionStateManager.unregister(id);
+  try { mailbox.purge(id); } catch {}
+  lifecycle.cleanupSessionArtifacts(id);
+  persistSessions();
+
+  return {
+    success: true,
+    session_id: id,
+    status: 'closed',
+    reason,
+    force,
+    timeout_ms: timeoutMs,
+    kill
+  };
+}
+
 // Detect terminal environment at daemon startup
 const DETECTED_TERMINAL = terminalBackend.detectTerminal();
 console.log(`[DAEMON] Terminal backend: ${DETECTED_TERMINAL}`);
@@ -1145,6 +1258,10 @@ for (const [id, meta] of Object.entries(_persisted)) {
       lastDisconnectedAt: meta.lastDisconnectedAt || meta.lastActivityAt || new Date().toISOString(),
       lastStateReportAt: meta.lastStateReportAt || null,
       stateReport: meta.stateReport || null,
+      idleTtl: meta.idleTtl || null,
+      idleTtlMs: meta.idleTtlMs == null ? null : meta.idleTtlMs,
+      ownerPid: meta.ownerPid || null,
+      ptyPid: meta.ptyPid || null,
       clients: new Set(), isClosing: false, outputRing: [], ready: true,     };
     initializeBootstrapState(sessions[id]);
     console.log(`[PERSIST] Restored session ${id} (awaiting reconnect)`);
@@ -1242,6 +1359,7 @@ app.post('/api/sessions/spawn', (req, res) => {
       id: session_id,
       type: 'spawned',
       ptyProcess,
+      ptyPid: ptyProcess.pid || null,
       command,
       cwd,
       createdAt: new Date().toISOString(),
@@ -1311,6 +1429,10 @@ app.post('/api/sessions/spawn', (req, res) => {
 app.post('/api/sessions/register', (req, res) => {
   const { session_id, command, cwd = process.cwd(), backend, cmux_workspace_id, cmux_surface_id, term_program, term } = req.body;
   if (!session_id) return res.status(400).json({ error: 'session_id is required' });
+  const parsedIdleTtl = parseOptionalIdleTtl(req.body);
+  if (parsedIdleTtl.error) {
+    return res.status(400).json({ error: parsedIdleTtl.error, code: 'INVALID_IDLE_TTL' });
+  }
   // Idempotent: allow re-registration (update command/cwd, keep clients)
   if (sessions[session_id]) {
     const existing = sessions[session_id];
@@ -1333,6 +1455,9 @@ app.post('/api/sessions/register', (req, res) => {
       existing.ready = true;
       markSessionConnected(existing);
     }
+    applyProcessMetadata(existing, req.body);
+    applyIdleTtlMetadata(existing, parsedIdleTtl);
+    applyTimestampMetadata(existing, req.body);
     initializeBootstrapState(existing);
     console.log(`[REGISTER] Re-registered session ${session_id} (type: ${existing.type}, updated metadata)`);
     return res.status(200).json({ session_id, type: existing.type, command: existing.command, cwd: existing.cwd, reregistered: true });
@@ -1360,12 +1485,17 @@ app.post('/api/sessions/register', (req, res) => {
     lastDisconnectedAt: delivery_type === 'aterm' ? null : new Date().toISOString(),
     lastStateReportAt: null,
     stateReport: null,
+    idleTtl: parsedIdleTtl.present ? parsedIdleTtl.raw : null,
+    idleTtlMs: parsedIdleTtl.present ? parsedIdleTtl.ms : null,
+    ownerPid: Number.isInteger(Number(req.body.owner_pid)) && Number(req.body.owner_pid) > 0 ? Number(req.body.owner_pid) : null,
+    ptyPid: Number.isInteger(Number(req.body.pty_pid)) && Number(req.body.pty_pid) > 0 ? Number(req.body.pty_pid) : null,
     clients: new Set(),
     isClosing: false,
     outputRing: [],
     ready: true,  // unknown commands remain injectable once registered (#150)
   };
   initializeBootstrapState(sessionRecord);
+  applyTimestampMetadata(sessionRecord, req.body);
   // Check for existing session with same base alias and emit replaced event
   const baseAlias = session_id.replace(/-\d+$/, '');
   const replaced = Object.keys(sessions).find(id => {
@@ -1836,7 +1966,10 @@ app.post('/api/sessions/:id/submit', async (req, res) => {
 
   console.log(`[SUBMIT] Session ${id} (${session.command})${retries > 0 ? `, retries: ${retries}, pre_delay: ${preDelayMs}ms` : ''}${gateOff ? ' [gate=off]' : ''}`);
 
-  if (isBootstrapGatedSession(session) && (!isBootstrapReady(session) || hasBootstrapBacklog(session) || session.bootstrapDraining)) {
+  // #471 (0.4.5): force=true must bypass the bootstrap gate. Without `!force`
+  // here the per-request escape hatch (cli.js --submit-force) is enqueued and
+  // 504s before the force-bypass block below ever runs.
+  if (!force && isBootstrapGatedSession(session) && (!isBootstrapReady(session) || hasBootstrapBacklog(session) || session.bootstrapDraining)) {
     const op = enqueueBootstrapOperation(id, session, {
       type: 'submit',
       body: { ...(req.body || {}) }
@@ -2364,6 +2497,35 @@ app.patch('/api/sessions/:id', (req, res) => {
   res.json({ success: true, old_id: id, new_id });
 });
 
+app.post('/api/sessions/:id/kill', async (req, res) => {
+  const requestedId = req.params.id;
+  const resolvedId = resolveSessionAlias(requestedId);
+  if (!resolvedId) return res.status(404).json({ error: 'Session not found', requested: requestedId });
+
+  try {
+    const timeoutSeconds = req.body && req.body.timeout != null
+      ? Number(req.body.timeout)
+      : (req.body && req.body.timeout_sec != null ? Number(req.body.timeout_sec) : 5);
+    if (!Number.isFinite(timeoutSeconds) || timeoutSeconds < 0) {
+      return res.status(400).json({ error: 'timeout must be a non-negative number of seconds', code: 'INVALID_TIMEOUT' });
+    }
+
+    const result = await teardownSessionById(resolvedId, {
+      force: req.body && req.body.force === true,
+      timeoutMs: Math.floor(timeoutSeconds * 1000),
+      reason: req.body && req.body.reason ? String(req.body.reason) : 'manual',
+      source: req.body && req.body.source ? String(req.body.source) : 'api'
+    });
+    if (!result.success) {
+      return res.status(result.httpStatus || 500).json({ error: result.error || 'Failed to kill session' });
+    }
+    console.log(`[KILL] Session ${resolvedId} closed (reason=${result.reason}, force=${result.force}, pid=${result.kill.pid || 'none'})`);
+    res.json(result);
+  } catch (err) {
+    res.status(500).json({ error: err.message || 'Failed to kill session' });
+  }
+});
+
 app.delete('/api/sessions/:id', (req, res) => {
   const requestedId = req.params.id;
   const resolvedId = resolveSessionAlias(requestedId);
@@ -2381,6 +2543,7 @@ app.delete('/api/sessions/:id', (req, res) => {
     delete sessions[id];
     sessionStateManager.unregister(id);
     try { mailbox.purge(id); } catch {}
+    lifecycle.cleanupSessionArtifacts(id);
     console.log(`[KILL] Session ${id} removed`);
     persistSessions();
     res.json({ success: true, status: 'closing' });
@@ -2389,6 +2552,7 @@ app.delete('/api/sessions/:id', (req, res) => {
     delete sessions[id];
     sessionStateManager.unregister(id);
     try { mailbox.purge(id); } catch {}
+    lifecycle.cleanupSessionArtifacts(id);
     persistSessions();
     console.log(`[KILL] Session ${id} force-removed (process cleanup error: ${err.message})`);
     res.json({ success: true, status: 'force-removed' });
@@ -2721,8 +2885,44 @@ app.patch('/api/threads/:id', (req, res) => {
 
 const server = app.listen(PORT, HOST, () => {
   console.log(`🚀 aigentry-telepty daemon listening on http://${HOST}:${PORT}`);
+  runStartupBootstrapRestore();
 });
 
+// #470 (0.4.5): when the daemon restarts under existing telepty allow workers,
+// persisted sessions are restored at daemon.js:1244 but bootstrapReady stays
+// false until the owner WS reconnects — leaving every survivor session stuck
+// at ready:false indefinitely. Re-probe on startup: for cmux sessions whose
+// owner PID is still alive, run the WS-independent prompt-symbol probe; for
+// non-cmux survivors, optimistically mark ready (the underlying CLI is alive
+// and no probe primitive is available).
+function runStartupBootstrapRestore() {
+  for (const [id, session] of Object.entries(sessions)) {
+    if (!isBootstrapGatedSession(session) || isBootstrapReady(session)) continue;
+    const ownerPid = Number(session.ownerPid);
+    if (!Number.isInteger(ownerPid) || ownerPid <= 0 || !isProcessRunning(ownerPid)) {
+      continue;
+    }
+    if (session.backend === 'cmux' && session.cmuxWorkspaceId) {
+      submitGate.awaitPromptSymbol(session, { timeoutMs: 5000 })
+        .then((result) => {
+          if (result && result.ready) {
+            markBootstrapReady(id, session, 'startup_restore');
+          } else {
+            markBootstrapReady(id, session, 'startup_owner_alive');
+            console.log(`[BOOTSTRAP] Optimistic ready for ${id} (ownerPid=${ownerPid}, probe=${result?.reason || 'timeout'})`);
+          }
+        })
+        .catch(() => {
+          markBootstrapReady(id, session, 'startup_owner_alive');
+          console.log(`[BOOTSTRAP] Optimistic ready for ${id} (ownerPid=${ownerPid}, probe=error)`);
+        });
+    } else {
+      markBootstrapReady(id, session, 'startup_owner_alive');
+      console.log(`[BOOTSTRAP] Optimistic ready for ${id} (ownerPid=${ownerPid}, backend=${session.backend || 'unknown'})`);
+    }
+  }
+}
+
 // --- Mailbox system initialization ---
 const mailbox = new FileMailbox();
 const mailboxNotifier = new UnixSocketNotifier({ coalesceMs: 25 });
@@ -2769,6 +2969,43 @@ if (staleBroken > 0) {
 mailboxDelivery.start();
 
 const IDLE_THRESHOLD_SECONDS = 60;
+async function runIdleTtlSweep(nowMs = Date.now()) {
+  const victims = lifecycle.selectIdleTtlVictims(sessions, teleptyConfig, { nowMs });
+  for (const victim of victims) {
+    const session = sessions[victim.id];
+    if (!session || session._idleTtlKilling) continue;
+    session._idleTtlKilling = true;
+    broadcastSessionEvent('tracing', victim.id, session, {
+      nowMs,
+      extra: {
+        action: 'idle_ttl_auto_kill',
+        reason: 'IDLE_TTL',
+        idle_duration: victim.idleSeconds,
+        idle_duration_seconds: victim.idleSeconds,
+        idle_ttl_ms: victim.ttlMs
+      }
+    });
+    try {
+      await teardownSessionById(victim.id, {
+        force: false,
+        timeoutMs: 5000,
+        reason: 'IDLE_TTL',
+        source: 'idle_reaper'
+      });
+      console.log(`[REAPER] Auto-killed ${victim.id} after ${victim.idleSeconds}s idle (ttl=${victim.ttlMs}ms)`);
+    } catch (err) {
+      session._idleTtlKilling = false;
+      console.error(`[REAPER] Failed to auto-kill ${victim.id}: ${err.message}`);
+    }
+  }
+}
+
+setInterval(() => {
+  runIdleTtlSweep().catch((err) => {
+    console.error(`[REAPER] Idle TTL sweep failed: ${err.message}`);
+  });
+}, IDLE_REAPER_POLL_MS);
+
 setInterval(() => {
   const now = Date.now();
   for (const [id, session] of Object.entries(sessions)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-telepty",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "main": "daemon.js",
   "bin": {
     "aigentry-telepty": "install.js",
@@ -28,14 +28,16 @@
     "install.sh",
     "install.ps1",
     "mcp-server/",
+    "scripts/postinstall.js",
     "src/",
     "skills/",
     "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node --test test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js && git diff --exit-code tests/snippet-protocol/v1/",
-    "test:watch": "node --test --watch test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js",
-    "test:ci": "node --test --test-reporter=spec test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js && git diff --exit-code tests/snippet-protocol/v1/",
+    "postinstall": "node scripts/postinstall.js",
+    "test": "node --test test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/telepty-kill.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js test/release-0.4.5-bugfixes.test.js && git diff --exit-code tests/snippet-protocol/v1/",
+    "test:watch": "node --test --watch test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/telepty-kill.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js test/release-0.4.5-bugfixes.test.js",
+    "test:ci": "node --test --test-reporter=spec test/auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/cli.test.js test/telepty-kill.test.js test/idle-ttl.test.js test/telepty-clean-older-than.test.js test/lifecycle-transport-agnostic.test.js test/skill-installer.test.js test/interactive-terminal.test.js test/runtime-info.test.js test/session-routing.test.js test/session-state.test.js test/mailbox-lock.test.js test/report-enforcement.test.js test/enforce-report.test.js test/submit-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/host-spec.test.js test/cross-host-inject.test.js test/cross-machine-ssh-routing.test.js test/init.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/win-kill-process.test.js test/daemon-control-port-owner.test.js test/banner-stderr-jq-safety.test.js test/bridge-supervisor-ipc.test.js test/bridge-j3-shim.test.js test/bridge-e2e.test.js test/release-0.4.5-bugfixes.test.js && git diff --exit-code tests/snippet-protocol/v1/",
     "regen-fixtures": "node scripts/regen-snippet-fixtures.js"
   },
   "keywords": [

package/scripts/postinstall.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+'use strict';
+
+// #469 (0.4.5): npm postinstall hook — restart a stale telepty-daemon after
+// `npm install -g`. Without this, the running daemon keeps executing the
+// previously-loaded code (verified: a daemon ran 22 days through 4 npm
+// upgrades), so user-facing upgrades quietly no-op until they manually kill
+// the daemon. Wires the existing daemon-shutdown primitive into npm's
+// lifecycle; does not add new shutdown logic.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn, execSync } = require('child_process');
+
+const pkg = require('../package.json');
+
+function shouldSkip() {
+  if (process.env.TELEPTY_SKIP_POSTINSTALL === '1') {
+    return 'TELEPTY_SKIP_POSTINSTALL=1';
+  }
+  // Only act on global installs. Local `npm install` (CI, dev) must not
+  // restart a user's daemon.
+  if (process.env.npm_config_global !== 'true') {
+    return 'non-global install';
+  }
+  return null;
+}
+
+function readDaemonState() {
+  const statePath = path.join(os.homedir(), '.telepty', 'daemon-state.json');
+  try {
+    return JSON.parse(fs.readFileSync(statePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function resolveTeleptyBin() {
+  try {
+    const cmd = os.platform() === 'win32' ? 'where telepty' : 'which telepty';
+    return execSync(cmd, { encoding: 'utf8' }).split('\n')[0].trim() || 'telepty';
+  } catch {
+    return 'telepty';
+  }
+}
+
+(function main() {
+  const skip = shouldSkip();
+  if (skip) {
+    console.log(`[telepty postinstall] Skipped (${skip}).`);
+    return;
+  }
+
+  const state = readDaemonState();
+  if (!state || !Number.isInteger(state.pid) || state.pid <= 0) {
+    console.log('[telepty postinstall] No running daemon detected — nothing to restart.');
+    return;
+  }
+
+  if (state.version === pkg.version) {
+    console.log(`[telepty postinstall] Running daemon already at ${pkg.version} (pid ${state.pid}). No restart needed.`);
+    return;
+  }
+
+  console.log(`[telepty postinstall] Detected stale daemon ${state.version || 'unknown'} (pid ${state.pid}); upgrading in-place to ${pkg.version}.`);
+
+  let stopped = 0;
+  try {
+    // Lazy require so a malformed install of daemon-control.js doesn't abort
+    // postinstall before the skip-check runs.
+    const { cleanupDaemonProcesses } = require('../daemon-control');
+    const result = cleanupDaemonProcesses();
+    stopped = result.stopped.length;
+    if (result.failed.length > 0) {
+      console.warn(`[telepty postinstall] Could not stop ${result.failed.length} daemon process(es).`);
+    }
+  } catch (err) {
+    console.warn(`[telepty postinstall] cleanupDaemonProcesses failed: ${err.message}`);
+  }
+
+  // launchd/systemd KeepAlive will respawn the daemon automatically on
+  // macOS/root-Linux. For other platforms (Windows, non-root Linux) or when
+  // the user disabled the service, spawn a fresh detached daemon so upgrades
+  // never silently leave the user without one.
+  try {
+    const bin = resolveTeleptyBin();
+    const child = spawn(bin, ['daemon'], { detached: true, stdio: 'ignore' });
+    child.unref();
+    console.log(`[telepty postinstall] Stopped ${stopped} stale daemon(s); spawned fresh ${pkg.version} daemon.`);
+  } catch (err) {
+    console.warn(`[telepty postinstall] Daemon respawn failed: ${err.message} (launchd/systemd may restart it automatically).`);
+  }
+})();