@dmsdc-ai/aigentry-telepty 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,116 @@ All notable changes to `@dmsdc-ai/aigentry-telepty` are documented here.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-30
+
+### Changed — Surface-ownership boundary (ADR 2026-05-30)
+
+- **Orchestrator Workspace Host now owns surface close/focus; telepty no longer
+  actuates them.** Daemon focus actuation and `focusSurface` are removed
+  (focus moves to the orchestrator `wh_focus` path). `closeSurface` is gated
+  behind `AIGENTRY_TELEPTY_SELF_CLOSE_SURFACE` — a no-op on the managed path,
+  opt-in for standalone use. The `isSurfaceAlive` cmux liveness probe,
+  `decideSurfaceGc`, and session-side zombie reclaim are retained; telepty now
+  emits a `surface_orphaned` bus event for the orchestrator reconciler to
+  actuate the close. INV-17 / #486 preserved (probe unknown → skip gate intact).
+
+### Fixed — Lifecycle / bootstrap / skill-loading (tasks #35 #20 #32 #17 #29 #31 #19)
+
+- **#35 / #20 — Codex skill loading.** Single-quote the `description` YAML
+  scalars in the bundled `SKILL.md` files so a Korean `키워드:` colon is no
+  longer parsed as a nested mapping; Codex now loads all bundled skills.
+- **#32 — auto-report consolidation.** Three byte-identical auto-report
+  builders are consolidated into one provenance-tagged `fireAutoReport`;
+  sub-1s elapsed is relabelled `TASK_IDLE_UNCONFIRMED` so a stuck target is
+  never reported as `TASK_COMPLETE`.
+- **#17 — surface-liveness GC.** New cmux surface-liveness probe
+  (`isSurfaceAlive`, INV-17 unknown-on-unreachable gate) plus `decideSurfaceGc`
+  and session-side SURFACE-GC reclaim of the headless zombie; the cli.js bridge
+  terminates (no reconnect) on a 1000 `Session destroyed` close.
+- **#29 — Warp bootstrap.** Non-cmux (Warp) owner-alive optimistic bootstrap
+  floor (mirrors `runStartupBootstrapRestore`) plus `TERM_PROGRAM=WarpTerminal`
+  backend classification — fixes inject-queues-forever on Warp.
+- **#31 — bootstrap timeout.** Actionable bootstrap-timeout
+  (`failBootstrapQueueOnTimeout` flushes the queue instead of hanging).
+- **#19 — Windows codex PATH.** Verified already-fixed by `874d14a`
+  (no code change).
+
+### Security — Snyk cli.js posture (task #26)
+
+- **Fixed — 3 path-traversal findings** (`fs.readFileSync`/`fs.readdirSync` on the
+  `--config=` / `--dir=` (`telepty session start`) and `--context` (`telepty
+  deliberate`) CLI path arguments). A new `sanitizePathArg()` rejects empty input,
+  null-byte injection, and `..` traversal segments, then normalizes via
+  `path.resolve()`; applied at each `fs.*` call site. Snyk path-traversal count is
+  now **0**.
+- **Hardened — self-update default** (`runUpdateInstall`): the default
+  `npm install -g` now runs via `execFileSync` with a fixed argument array (no
+  shell), removing the default-path command-injection surface.
+- **By-design waivers (operator-trusted, no privilege boundary; pre-existing
+  baseline, not introduced by this work):** two `IndirectCommandInjection`
+  findings remain and are accepted by design — (1) `pty.spawn` of the
+  operator/user-chosen CLI, which *is* the `telepty allow` feature; and (2) the
+  explicit `TELEPTY_UPDATE_COMMAND` self-update override, an operator-set env var
+  (setting it already implies shell control, so no boundary is crossed). Both are
+  annotated in code so they are not mistaken for an oversight. **Net: 0
+  newly-introduced and 0 non-by-design findings.**
+
+## [0.4.5] - 2026-05-26
+
+### Fixed — Stale-daemon, restart-recovery, force-bypass, codex matcher (tasks #469 #470 #471 #472)
+
+- **#469 — npm postinstall hook restarts a stale daemon (`scripts/postinstall.js`).**
+  `npm install -g @dmsdc-ai/aigentry-telepty@X` previously overwrote files but
+  never signalled the running `telepty-daemon`, so the daemon kept executing
+  the previously-loaded code (observed: PID 3222 ran 22 days through 4
+  upgrades). The new postinstall script reads `~/.telepty/daemon-state.json`,
+  compares the running daemon's reported version to the just-installed
+  `package.json` version, and on mismatch invokes the existing
+  `cleanupDaemonProcesses()` primitive plus a detached respawn. Skips on
+  `TELEPTY_SKIP_POSTINSTALL=1` and on non-global installs
+  (`npm_config_global!=='true'`).
+- **#470 — daemon restart re-bootstraps existing sessions
+  (`daemon.js` `runStartupBootstrapRestore()`).** After a daemon restart,
+  persisted-and-restored sessions remained `ready:false` indefinitely because
+  the bootstrap prompt-symbol probe only fired on owner-WebSocket reconnect.
+  On startup, each restored gated session whose `ownerPid` is still alive is
+  now actively probed (cmux path) or optimistically marked ready (non-cmux
+  path), with the chosen reason recorded for log attribution. Sessions whose
+  owner process is dead remain unready, matching the prior unready semantics.
+- **#471 — `force: true` bypasses the bootstrap gate (`daemon.js:1969`).**
+  The per-request `force` escape hatch (`cli.js --submit-force`,
+  `TELEPTY_SUBMIT_FORCE_DEFAULT=1` from 0.4.4) was parsed correctly but the
+  bootstrap gate enqueued it and returned 504 long before the force-bypass
+  block at L1998 could run. Surgical 1-line condition edit: gate fires only
+  when `!force`. The force-bypass code path is now exercisable as documented.
+- **#472 — codex prompt-symbol matcher normalized across environments
+  (`src/prompt-symbol-registry.js`).** On real cmux captures the codex `›`
+  glyph tail-renders on the same row as the model-status footer and DECRQM /
+  cursor-position-query fragments (`>4;0m>7u`, `0 q`) leak into the screen
+  buffer, so the prior strict line-leading scan permanently missed and the
+  session stuck at `ready:false`. New tolerant detector: (1) modal-UI
+  anti-pattern guard for resume picker, first-run directory-trust prompt and
+  generic press-enter-to-continue modals (treated as NOT ready); (2)
+  multi-signal match on `"OpenAI Codex (v"` plus `/gpt-[0-9.]+\s+\w+\s+fast/`
+  anywhere on the screen; (3) legacy strict line-leading scan preserved as a
+  back-compat fallback. `awaitPromptSymbol` now emits a single
+  `[bootstrap] <cli> ready via: <reason>` log line on stabilize, paired with
+  the #470 optimistic-ready logging for unified debuggability.
+
+### Notes — 0.4.5
+
+- **Tests** — `npm test` passes 416 / 416 (was 411 / 411 in 0.4.4; +5 new
+  cases in `test/release-0.4.5-bugfixes.test.js` covering #469/#470/#471/#472
+  including env-resistance regression guard on the existing noforce test).
+- **Snyk Code SAST** — all newly authored or modified JS files
+  (`scripts/postinstall.js`, `src/prompt-symbol-registry.js`,
+  `src/submit-gate.js`, new `daemon.js` line ranges, and
+  `test/release-0.4.5-bugfixes.test.js`) report 0 findings. The 55
+  pre-existing repo-wide findings in unchanged code are tracked separately as
+  task #474 (security cleanup track) and are not part of this release.
+- **Out of scope, tracked separately** — task #473 (session-ID reuse → stale
+  command metadata) is queued for a 0.4.6 dispatch and is not addressed here.
+
 ## [0.4.4] - 2026-05-25
 
 ### Added — TELEPTY_SUBMIT_FORCE_DEFAULT env var (task #453)

package/cli.js

@@ -5,7 +5,7 @@ const os = require('os');
 const fs = require('fs');
 const { constants: osConstants } = require('os');
 const WebSocket = require('ws');
-const { execSync, spawn } = require('child_process');
+const { execSync, execFileSync, spawn } = require('child_process');
 const readline = require('readline');
 const prompts = require('prompts');
 const updateNotifier = require('update-notifier');
@@ -488,13 +488,51 @@ async function promptWithRecovery(promptConfig) {
   return response;
 }
 
+// #26: validate a filesystem-path CLI argument before it reaches fs.*. Rejects empty input
+// and null-byte injection, then normalizes to a canonical absolute path (path.resolve folds
+// out any `..` traversal segments). telepty is a local CLI, so the path is operator-chosen and
+// arbitrary locations are legitimate — this hardens against malformed/encoded traversal input
+// rather than confining to a base directory.
+function sanitizePathArg(input, label = 'path') {
+  if (typeof input !== 'string' || input.length === 0 || input.includes('\0') || input.includes('..')) {
+    throw new Error(`Invalid ${label} path argument`);
+  }
+  return path.resolve(input);
+}
+
+// #29: per-session backend classification, exposed for unit-testing. `env` and the kitty-socket
+// probe are injected (findKittySocketCli is nested in main()), so a test can drive each branch
+// without real env/sockets. Behavior matches the original inline ternary exactly.
+function classifyBackend(env, findKitty) {
+  if (env.TERM_PROGRAM === 'WarpTerminal') return 'warp';
+  if (env.CMUX_WORKSPACE_ID) return 'cmux';
+  return findKitty() ? 'kitty' : 'pty';
+}
+
+// #17 (OQ-2): decide whether a daemon WS 'close' is the daemon's explicit session-destroy
+// (code 1000 'Session destroyed') — in which case the bridge must terminate, not reconnect.
+// Pure predicate, exposed for unit-testing; `reason` may be a Buffer (ws) or string.
+function isDaemonDestroyClose(code, reason) {
+  const reasonText = reason ? reason.toString() : '';
+  return code === 1000 && reasonText === 'Session destroyed';
+}
+
 function runUpdateInstall() {
   if (process.env.TELEPTY_SKIP_PACKAGE_UPDATE === '1') {
     return;
   }
 
-  const updateCommand = process.env.TELEPTY_UPDATE_COMMAND || 'npm install -g @dmsdc-ai/aigentry-telepty@latest';
-  execSync(updateCommand, { stdio: 'inherit' });
+  // #26: default self-update runs npm with a fixed arg array via execFileSync (no shell →
+  // no command injection). An explicit operator-supplied TELEPTY_UPDATE_COMMAND is a trusted
+  // env override (the operator deliberately chose to run a custom shell command — setting the
+  // env already implies shell control, so no privilege boundary is crossed). This execSync is
+  // accepted-by-design, consistent with the documented Snyk baseline waiver (CHANGELOG).
+  const override = process.env.TELEPTY_UPDATE_COMMAND;
+  if (override) {
+    execSync(override, { stdio: 'inherit' });
+    return;
+  }
+  execFileSync('npm', ['install', '-g', '@dmsdc-ai/aigentry-telepty@latest'], { stdio: 'inherit' });
 }
 
 async function repairLocalDaemon(options = {}) {
@@ -1082,7 +1120,9 @@ async function main() {
         return files.length > 0;
       } catch { return false; }
     }
-    const detectedBackend = process.env.CMUX_WORKSPACE_ID ? 'cmux' : (findKittySocketCli() ? 'kitty' : 'pty');
+    // #29: classify Warp first (TERM_PROGRAM=WarpTerminal) for honest telemetry + a named
+    // branch (Warp readiness uses the #29 owner-alive floor, not a cmux read-screen poll).
+    const detectedBackend = classifyBackend(process.env, findKittySocketCli);
 
     // Register session with daemon
     const terminalProgram = detectTerminalProgram(process.env);
@@ -1182,6 +1222,10 @@ async function main() {
       // Windows: walk %PATHEXT% so bare names (`claude`, `codex`, `gemini`)
       // resolve to their npm-global `.cmd`/`.ps1` shims. POSIX: no-op. (#25)
       const resolvedCommand = resolveWindowsExecutable(command, process.env);
+      // #26 (Snyk waiver, accepted-by-design): spawning the operator/user-chosen CLI IS the
+      // `telepty allow` feature — `command` comes from the local CLI invocation, not an
+      // untrusted boundary, so this is not an exploitable injection. Pre-existing baseline
+      // finding; not fixable without removing `telepty allow`.
       child = pty.spawn(resolvedCommand, cmdArgs, {
         name: 'xterm-256color',
         cols: process.stdout.columns || 80,
@@ -1401,8 +1445,19 @@ async function main() {
         }
       });
 
-      daemonWs.on('close', () => {
+      daemonWs.on('close', (code, reason) => {
         wsReady = false;
+        // #17 (OQ-2): the daemon explicitly destroyed this session (manual kill or the
+        // surface-gone GC) → close code 1000 'Session destroyed'. Terminate the bridge
+        // instead of reconnecting; otherwise the orphan bridge re-registers and defeats the
+        // GC. Daemon restarts / network drops use other codes (e.g. 1006) and still reconnect,
+        // preserving the #487/#488 survive-and-reattach guarantee.
+        if (isDaemonDestroyClose(code, reason)) {
+          if (closeAllowSession()) {
+            exitAllowSession(0);
+          }
+          return;
+        }
         scheduleReconnect();
       });
 
@@ -1464,8 +1519,11 @@ async function main() {
       return true;
     }
 
-    function exitAllowSession(code) {
-      setTimeout(() => process.exit(code), 25);
+    function exitAllowSession(code, exitCtx) {
+      if (exitCtx) {
+        logSessionDeath(exitCtx.exitCode, exitCtx.signal, exitCtx.duration);
+      }
+      process.exit(code);
     }
 
     // Intercept terminal title escape sequences and prefix with session ID
@@ -1562,14 +1620,25 @@ async function main() {
     }
     attachChildExitHandler();
 
-    for (const signalName of ['SIGTERM', 'SIGHUP', 'SIGQUIT']) {
+    process.on('SIGHUP', () => {
+      // Explicit no-op: decouples telepty-allow lifecycle from parent terminal app.
+      // Node default for SIGHUP is process.exit; this handler overrides that default.
+      // See ADR 2026-05-27-cmux-telepty-session-boundary §4.
+    });
+    process.stdout.on('error', () => {});
+
+    for (const signalName of ['SIGTERM', 'SIGQUIT']) {
       const handler = () => {
         closeAllowSession();
         try {
           child.kill(signalName);
         } catch {}
         const signalCode = osConstants.signals[signalName] || 1;
-        exitAllowSession(128 + signalCode);
+        exitAllowSession(128 + signalCode, {
+          exitCode: null,
+          signal: signalName,
+          duration: Date.now() - sessionStartTime
+        });
       };
       allowSignalHandlers.set(signalName, handler);
       process.on(signalName, handler);
@@ -2525,11 +2594,12 @@ async function main() {
     // Discover project folders (subdirectories with .git)
     let projects;
     if (configPath) {
-      projects = JSON.parse(fs.readFileSync(configPath, 'utf8')).projects;
+      projects = JSON.parse(fs.readFileSync(sanitizePathArg(configPath, 'config'), 'utf8')).projects;
     } else {
-      projects = fs.readdirSync(projectsDir, { withFileTypes: true })
-        .filter(d => d.isDirectory() && fs.existsSync(path.join(projectsDir, d.name, '.git')))
-        .map(d => ({ name: d.name, cwd: path.join(projectsDir, d.name) }));
+      const resolvedDir = sanitizePathArg(projectsDir, 'dir');
+      projects = fs.readdirSync(sanitizePathArg(projectsDir, 'dir'), { withFileTypes: true })
+        .filter(d => d.isDirectory() && fs.existsSync(path.join(resolvedDir, d.name, '.git')))
+        .map(d => ({ name: d.name, cwd: path.join(resolvedDir, d.name) }));
     }
 
     if (projects.length === 0) {
@@ -2836,7 +2906,7 @@ async function main() {
     let contextContent = null;
     if (contextPath) {
       try {
-        contextContent = fs.readFileSync(contextPath, 'utf-8');
+        contextContent = fs.readFileSync(sanitizePathArg(contextPath, 'context'), 'utf-8');
       } catch (err) {
         console.error(`Failed to read context file: ${err.message}`);
         process.exit(1);
@@ -3448,4 +3518,15 @@ Discuss the following topic from your project's perspective. Engage with other s
 `);
 }
 
-main();
+// Guard the entry point so a test can `require('./cli.js')` to reach the exported pure helpers
+// without dispatching the argv command. Behavior when run as the CLI is unchanged.
+if (require.main === module) {
+  main();
+}
+
+// Minimal test surface (no logic change) — pure decisions exposed for unit-testing.
+module.exports = {
+  classifyBackend,        // #29: TERM_PROGRAM/CMUX/kitty → backend string
+  isDaemonDestroyClose,   // #17 OQ-2: 1000 'Session destroyed' → terminate-not-reconnect
+  sanitizePathArg,        // #26: path-arg validation/normalization
+};

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');
@@ -27,10 +27,29 @@ const fs = require('fs');
 const SESSION_PERSIST_PATH = require('path').join(os.homedir(), '.config', 'aigentry-telepty', 'sessions.json');
 const SESSION_STALE_SECONDS = Math.max(1, Number(process.env.TELEPTY_SESSION_STALE_SECONDS || 60));
 const SESSION_CLEANUP_SECONDS = Math.max(SESSION_STALE_SECONDS, Number(process.env.TELEPTY_SESSION_CLEANUP_SECONDS || 300));
+// #17: grace window before a cmux session whose workspace was explicitly closed (bridge
+// survived → headless zombie) is reclaimed. Shorter than the 300s disconnect-GC: the surface
+// is confirmed gone (not merely disconnected). The window absorbs cmux transient hiccups.
+const SURFACE_ORPHAN_SECONDS = Math.max(5, Number(process.env.TELEPTY_SURFACE_ORPHAN_SECONDS || 30));
+// #17: pure verdict→action mapping for the surface-liveness GC, exposed for unit-testing.
+// Returns 'mark' (start the grace window), 'reclaim' (grace elapsed → teardown), 'recover'
+// (surface returned within grace → clear), or 'skip'. INV-17: 'unknown' (cmux unreachable)
+// always maps to 'skip' — GC nothing. Pure, no side effects; the caller performs the action.
+function decideSurfaceGc(liveness, session, nowMs, graceSeconds = SURFACE_ORPHAN_SECONDS) {
+  if (liveness === 'gone') {
+    if (!session.surfaceGoneAt) return 'mark';
+    const goneSeconds = Math.floor((nowMs - new Date(session.surfaceGoneAt).getTime()) / 1000);
+    return goneSeconds >= graceSeconds ? 'reclaim' : 'skip';
+  }
+  if (liveness === 'alive' && session.surfaceGoneAt) return 'recover';
+  return 'skip';
+}
 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));
+// Surface FOCUS is owned by the orchestrator's Workspace Host adapter (`wh_focus`), per the
+// 2026-05-30 surface-ownership verdict — telepty no longer foregrounds surfaces.
 const WRAPPED_SUBMIT_DELAY_MS = 500;
 
 // Session state machine manager — auto-detects session state from PTY output
@@ -73,30 +92,8 @@ sessionStateManager.onTransition((sessionId, from, to, detail) => {
     // Mark as idle-notified (but keep the entry — REPORT is still pending).
     // Entry is cleared when REPORT arrives (via inject endpoint) OR session dies.
     if (pendingReport.idleNotified) return; // only fire once
-    pendingReport.idleNotified = true;
-    pendingReport.idleAt = new Date().toISOString();
-
-    const elapsed = ((Date.now() - new Date(pendingReport.injectedAt).getTime()) / 1000).toFixed(1);
-
-    // New bus event: TASK_IDLE_NO_REPORT (richer observability)
-    broadcastSessionEvent('TASK_IDLE_NO_REPORT', sessionId, session, {
-      extra: {
-        source: pendingReport.source,
-        inject_id: pendingReport.injectId,
-        elapsed_secs: Number(elapsed),
-        injected_at: pendingReport.injectedAt
-      }
-    });
-    console.log(`[ENFORCE-REPORT] ${sessionId} idle after ${elapsed}s — awaiting REPORT from ${pendingReport.source}`);
-
-    // Legacy text-inject for back-compat (grandfather period 0.2.x)
-    const reportMsg = `TASK_COMPLETE: ${sessionId} is now idle after processing inject (${elapsed}s)`;
-    const srcId = resolveSessionAlias(pendingReport.source) || pendingReport.source;
-    const srcSession = sessions[srcId];
-    if (srcSession) {
-      deliverInjectionToSession(srcId, srcSession, reportMsg, { noEnter: false, source: 'auto_report' });
-      console.log(`[AUTO-REPORT] ${sessionId} → ${srcId}: idle after ${elapsed}s (legacy text-inject)`);
-    }
+    // real-idle: the state manager observed a genuine busy→idle transition.
+    fireAutoReport(sessionId, session, pendingReport, 'real-idle');
   }
 
   // Fire TASK_DEAD_NO_REPORT when session dies with a pending report
@@ -260,15 +257,68 @@ const PORT = process.env.PORT || 3848;
 const HOST = process.env.HOST || '0.0.0.0';
 process.title = 'telepty-daemon';
 
-const daemonClaim = claimDaemonState({ host: HOST, port: Number(PORT), version: pkg.version });
-if (!daemonClaim.claimed) {
-  const current = daemonClaim.current;
-  console.log(`[DAEMON] telepty daemon already running (pid ${current.pid}, port ${current.port}). Exiting.`);
-  process.exit(0);
+// Singleton claim — guarded so a test require neither exits (when a daemon is running) nor
+// overwrites a live daemon's on-disk state claim (when one is). Only the real daemon claims.
+if (require.main === module) {
+  const daemonClaim = claimDaemonState({ host: HOST, port: Number(PORT), version: pkg.version });
+  if (!daemonClaim.claimed) {
+    const current = daemonClaim.current;
+    console.log(`[DAEMON] telepty daemon already running (pid ${current.pid}, port ${current.port}). Exiting.`);
+    process.exit(0);
+  }
 }
 
 const pendingReports = {}; // {targetSessionId: {source, injectedAt, injectId}}
 const AUTO_REPORT_IDLE_SECONDS = Number(process.env.TELEPTY_AUTO_REPORT_IDLE_SECONDS) || 10;
+// #32: a legacy auto-report can fire ~0.0s after the inject (silence-timeout / ready-signal)
+// even when the inject never reached the target TUI — indistinguishable from a real completion
+// by the recipient. Below this elapsed floor the idle is NOT trusted as a processed-inject
+// completion; the text-inject is relabeled so a stuck/hung target is never reported as DONE.
+const AUTO_REPORT_MIN_REAL_SECONDS = Number(process.env.TELEPTY_AUTO_REPORT_MIN_REAL_SECONDS) || 1.0;
+
+// #32: single provenance-tagged auto-report path (was 3 byte-identical builders at the
+// onTransition-idle / silence-timeout / ready-signal sites). `trigger` distinguishes the
+// originating path; sub-floor elapsed is relabeled TASK_IDLE_UNCONFIRMED instead of TASK_COMPLETE.
+// Caller is responsible for the `!pendingReport.idleNotified` once-only guard.
+// `deps` is a thin DI seam (defaults = module globals) so the elapsed→label decision is
+// unit-testable with an injected clock and a captured deliver fn — behavior is byte-identical
+// for the production callers, which pass no deps.
+function fireAutoReport(targetId, targetSession, pendingReport, trigger, deps = {}) {
+  const _now = deps.now || Date.now;
+  const _broadcast = deps.broadcastSessionEvent || broadcastSessionEvent;
+  const _resolveAlias = deps.resolveSessionAlias || resolveSessionAlias;
+  const _sessions = deps.sessions || sessions;
+  const _deliver = deps.deliverInjectionToSession || deliverInjectionToSession;
+
+  pendingReport.idleNotified = true;
+  pendingReport.idleAt = new Date(_now()).toISOString();
+  const elapsedNum = (_now() - new Date(pendingReport.injectedAt).getTime()) / 1000;
+  const elapsed = elapsedNum.toFixed(1);
+
+  // Richer bus event (observability) — now also carries the trigger provenance.
+  _broadcast('TASK_IDLE_NO_REPORT', targetId, targetSession, {
+    extra: {
+      source: pendingReport.source,
+      inject_id: pendingReport.injectId,
+      elapsed_secs: Number(elapsed),
+      injected_at: pendingReport.injectedAt,
+      trigger
+    }
+  });
+  console.log(`[ENFORCE-REPORT] ${targetId} idle after ${elapsed}s (trigger=${trigger}) — awaiting REPORT from ${pendingReport.source}`);
+
+  const srcId = _resolveAlias(pendingReport.source) || pendingReport.source;
+  const srcSession = _sessions[srcId];
+  if (!srcSession) return;
+
+  const confirmed = elapsedNum >= AUTO_REPORT_MIN_REAL_SECONDS;
+  const injTag = pendingReport.injectId ? ` inject=${pendingReport.injectId}` : '';
+  const reportMsg = confirmed
+    ? `TASK_COMPLETE: ${targetId} is now idle after processing inject (${elapsed}s, via ${trigger}${injTag})`
+    : `TASK_IDLE_UNCONFIRMED: ${targetId} signaled idle ${elapsed}s after inject (via ${trigger}${injTag}) — inject may NOT have been processed; verify before treating as done`;
+  _deliver(srcId, srcSession, reportMsg, { noEnter: false, source: 'auto_report' });
+  console.log(`[AUTO-REPORT] ${targetId} → ${srcId}: ${confirmed ? 'TASK_COMPLETE' : 'TASK_IDLE_UNCONFIRMED'} after ${elapsed}s (trigger=${trigger})`);
+}
 
 const sessions = {};
 const handoffs = {};
@@ -657,30 +707,104 @@ function markBootstrapReady(sessionId, session, reason) {
   return true;
 }
 
-function scheduleBootstrapPromptPoll(sessionId, session) {
+// #31 (AC-31.4): a session stuck past the bootstrap timeout must surface an ACTIONABLE error
+// and stop queuing forever. Emit an actionable bootstrap_ready_timeout (hint + dropped count)
+// and FLUSH the queue: submit ops resolve 504, inject ops fail — instead of silently
+// accumulating until the process is killed. The caller can re-inject if the target recovers.
+function failBootstrapQueueOnTimeout(sessionId, session, detail = {}) {
+  const queued = Array.isArray(session.bootstrapQueue) ? session.bootstrapQueue.length : 0;
+  emitBootstrapEvent('bootstrap_ready_timeout', sessionId, session, {
+    ...detail,
+    actionable: true,
+    queued_dropped: queued,
+    hint: `Session '${sessionId}' did not become inject-ready within ${BOOTSTRAP_READY_TIMEOUT_MS}ms — the target CLI (e.g. codex MCP init) may be hung. Inspect the surface and re-spawn if needed; queued injects were flushed.`
+  });
+  if (queued === 0) return;
+  const drained = session.bootstrapQueue.splice(0, queued);
+  for (const op of drained) {
+    if (op.type === 'submit') {
+      resolveBootstrapSubmit(op, {
+        status: 504,
+        body: {
+          error: `bootstrap_ready_timeout — '${sessionId}' not ready within ${BOOTSTRAP_READY_TIMEOUT_MS}ms`,
+          reason: detail.reason || 'bootstrap_ready_timeout',
+          strategy: 'none',
+          attempts: 0,
+          gated: true,
+          bootstrap_queued: false,
+          bootstrap: buildBootstrapBlock(session)
+        }
+      });
+    }
+    emitBootstrapEvent('bootstrap_queue_failed', sessionId, session, {
+      op_id: op.op_id,
+      operation: op.type,
+      code: 'BOOTSTRAP_READY_TIMEOUT',
+      error: `target '${sessionId}' not ready within ${BOOTSTRAP_READY_TIMEOUT_MS}ms`
+    });
+  }
+}
+
+// #29: pure decision for the non-cmux owner-alive optimistic floor — returns true iff the
+// armed timer should flip bootstrapReady (not already ready; owner PID valid + alive; owner WS
+// open). `deps` injects the liveness predicates for unit-testing (defaults = module globals),
+// mirroring submit-gate.js's opts DI seam. No side effects — pure predicate.
+function shouldApplyOwnerAliveFloor(session, deps = {}) {
+  const _isBootstrapReady = deps.isBootstrapReady || isBootstrapReady;
+  const _isProcessRunning = deps.isProcessRunning || isProcessRunning;
+  const _isOpenWebSocket = deps.isOpenWebSocket || isOpenWebSocket;
+  if (_isBootstrapReady(session)) return false;          // bridge_ready already won
+  const ownerPid = Number(session.ownerPid);
+  if (!Number.isInteger(ownerPid) || ownerPid <= 0 || !_isProcessRunning(ownerPid)) return false;
+  if (!_isOpenWebSocket(session.ownerWs)) return false;
+  return true;
+}
+
+function scheduleBootstrapPromptPoll(sessionId, session, deps = {}) {
+  const _setTimeout = deps.setTimeout || setTimeout;
   if (!session || !isBootstrapGatedSession(session) || isBootstrapReady(session)) return;
-  if (session.bootstrapPromptPoll || session.backend !== 'cmux' || !session.cmuxWorkspaceId) return;
   if (!isOpenWebSocket(session.ownerWs)) return;
 
-  session.bootstrapPromptPoll = submitGate.awaitPromptSymbol(session, {
-    timeoutMs: BOOTSTRAP_READY_TIMEOUT_MS
-  }).then((result) => {
-    session.bootstrapPromptPoll = null;
-    if (result && result.ready && isOpenWebSocket(session.ownerWs)) {
-      markBootstrapReady(sessionId, session, 'cmux_prompt_symbol');
-    } else if (result && result.reason) {
-      emitBootstrapEvent('bootstrap_ready_timeout', sessionId, session, {
-        reason: result.reason,
-        waited_ms: result.waited_ms || 0
+  // cmux: rendered-screen prompt poll (the cmux-only read-screen primitive). Unchanged,
+  // including the #31 actionable bootstrap-timeout on miss/error.
+  if (session.backend === 'cmux' && session.cmuxWorkspaceId) {
+    if (session.bootstrapPromptPoll) return;
+    session.bootstrapPromptPoll = submitGate.awaitPromptSymbol(session, {
+      timeoutMs: BOOTSTRAP_READY_TIMEOUT_MS
+    }).then((result) => {
+      session.bootstrapPromptPoll = null;
+      if (result && result.ready && isOpenWebSocket(session.ownerWs)) {
+        markBootstrapReady(sessionId, session, 'cmux_prompt_symbol');
+      } else if (result && result.reason) {
+        failBootstrapQueueOnTimeout(sessionId, session, {
+          reason: result.reason,
+          waited_ms: result.waited_ms || 0
+        });
+      }
+    }).catch((error) => {
+      session.bootstrapPromptPoll = null;
+      failBootstrapQueueOnTimeout(sessionId, session, {
+        reason: 'prompt_symbol_error',
+        error: error.message || String(error)
       });
-    }
-  }).catch((error) => {
-    session.bootstrapPromptPoll = null;
-    emitBootstrapEvent('bootstrap_ready_timeout', sessionId, session, {
-      reason: 'prompt_symbol_error',
-      error: error.message || String(error)
     });
-  });
+    return;
+  }
+
+  // #29: non-cmux (warp/pty/kitty) has NO rendered-screen read primitive, so the cmux poll
+  // would early-return and bootstrapReady could stay false forever (inject queues forever on
+  // Warp). The fast path stays the bridge 'ready' frame; this arms an idempotent owner-alive
+  // optimistic FLOOR — byte-for-byte the shipped runStartupBootstrapRestore precedent
+  // (markBootstrapReady('startup_owner_alive') ~daemon.js:2997) — applied at the LIVE owner
+  // WS-connect path. markBootstrapReady is idempotent, so a late timer after bridge_ready is a
+  // harmless no-op. submit-gate.js read-screen guard stays cmux-only (untouched).
+  if (session.bootstrapOptimisticTimer) return;
+  session.bootstrapOptimisticTimer = _setTimeout(() => {
+    session.bootstrapOptimisticTimer = null;
+    if (!shouldApplyOwnerAliveFloor(session, deps)) return;
+    markBootstrapReady(sessionId, session, 'owner_alive');
+    console.log(`[BOOTSTRAP] Optimistic ready for ${sessionId} (ownerPid=${Number(session.ownerPid)}, backend=${session.backend || 'unknown'})`);
+  }, BOOTSTRAP_READY_TIMEOUT_MS);
 }
 
 async function waitForBootstrapSubmit(op, session, timeoutMs) {
@@ -1219,6 +1343,11 @@ async function teardownSessionById(id, options = {}) {
     try { session.ownerWs.close(1000, 'Session destroyed'); } catch {}
   }
 
+  // Surface close is the orchestrator's job (Workspace Host adapter), per the 2026-05-30
+  // verdict — this call is a NO-OP on the managed path. It actuates only for a standalone
+  // telepty that opted in via AIGENTRY_TELEPTY_SELF_CLOSE_SURFACE=1 (gate lives in closeSurface).
+  try { terminalBackend.closeSurface(session); } catch {}
+
   delete sessions[id];
   sessionStateManager.unregister(id);
   try { mailbox.purge(id); } catch {}
@@ -1966,7 +2095,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 || {}) }
@@ -2537,6 +2669,11 @@ app.delete('/api/sessions/:id', (req, res) => {
     } else if (session.ptyProcess) {
       session.ptyProcess.kill();
     }
+    // Surface close is the orchestrator's job (Workspace Host adapter), per the 2026-05-30
+    // verdict — NO-OP on the managed path. The orchestrator's session-cleanup.sh closes the
+    // surface on this normal CLI-exit (CLEANUP_REQUEST→wh_close). Actuates only for a standalone
+    // telepty with AIGENTRY_TELEPTY_SELF_CLOSE_SURFACE=1 (gate lives in closeSurface).
+    try { terminalBackend.closeSurface(session); } catch {}
     delete sessions[id];
     sessionStateManager.unregister(id);
     try { mailbox.purge(id); } catch {}
@@ -2880,9 +3017,51 @@ app.patch('/api/threads/:id', (req, res) => {
   res.json({ success: true, thread_id: thread.id, status: thread.status });
 });
 
-const server = app.listen(PORT, HOST, () => {
-  console.log(`🚀 aigentry-telepty daemon listening on http://${HOST}:${PORT}`);
-});
+// Bind the port only under the require.main guard — a test can `require('./daemon.js')` to
+// reach the exported decision functions without starting the daemon. `server` stays undefined
+// when required, so the WS upgrade/error handlers below attach only when run as the daemon.
+let server;
+if (require.main === module) {
+  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();
@@ -2922,12 +3101,15 @@ const mailboxDelivery = new DeliveryEngine(mailbox, {
     }
   },
 });
-// Startup sweep: break stale lock files before starting delivery
-const staleBroken = mailbox.breakStaleLocks();
-if (staleBroken > 0) {
-  console.log(`[MAILBOX] Startup sweep: broke ${staleBroken} stale lock(s)`);
+// Startup sweep: break stale lock files before starting delivery. Guarded so a test require
+// of this module neither breaks on-disk locks nor starts the delivery loop.
+if (require.main === module) {
+  const staleBroken = mailbox.breakStaleLocks();
+  if (staleBroken > 0) {
+    console.log(`[MAILBOX] Startup sweep: broke ${staleBroken} stale lock(s)`);
+  }
+  mailboxDelivery.start();
 }
-mailboxDelivery.start();
 
 const IDLE_THRESHOLD_SECONDS = 60;
 async function runIdleTtlSweep(nowMs = Date.now()) {
@@ -2961,13 +3143,14 @@ async function runIdleTtlSweep(nowMs = Date.now()) {
   }
 }
 
-setInterval(() => {
+// Guarded: timers must not run (and keep the event loop alive) on a test require.
+if (require.main === module) setInterval(() => {
   runIdleTtlSweep().catch((err) => {
     console.error(`[REAPER] Idle TTL sweep failed: ${err.message}`);
   });
 }, IDLE_REAPER_POLL_MS);
 
-setInterval(() => {
+if (require.main === module) setInterval(() => {
   const now = Date.now();
   for (const [id, session] of Object.entries(sessions)) {
     const idleSeconds = session.lastActivityAt ? Math.floor((now - new Date(session.lastActivityAt).getTime()) / 1000) : null;
@@ -3012,25 +3195,8 @@ setInterval(() => {
     // Skip if onTransition already fired the idle notification.
     const pendingRpt = pendingReports[id];
     if (pendingRpt && !pendingRpt.idleNotified && session.type !== 'wrapped' && idleSeconds !== null && idleSeconds >= AUTO_REPORT_IDLE_SECONDS) {
-      pendingRpt.idleNotified = true;
-      pendingRpt.idleAt = new Date().toISOString();
-      const elapsed = ((Date.now() - new Date(pendingRpt.injectedAt).getTime()) / 1000).toFixed(1);
-      // Fire new bus event + legacy text-inject
-      broadcastSessionEvent('TASK_IDLE_NO_REPORT', id, session, {
-        extra: {
-          source: pendingRpt.source,
-          inject_id: pendingRpt.injectId,
-          elapsed_secs: Number(elapsed),
-          injected_at: pendingRpt.injectedAt
-        }
-      });
-      const reportMsg = `TASK_COMPLETE: ${id} is now idle after processing inject (${elapsed}s)`;
-      const srcId = resolveSessionAlias(pendingRpt.source) || pendingRpt.source;
-      const srcSession = sessions[srcId];
-      if (srcSession) {
-        deliverInjectionToSession(srcId, srcSession, reportMsg, { noEnter: false, source: 'auto_report' });
-        console.log(`[AUTO-REPORT] ${id} → ${srcId}: idle after ${elapsed}s (threshold)`);
-      }
+      // silence-timeout: session has been quiet past the threshold without a REPORT.
+      fireAutoReport(id, session, pendingRpt, 'silence-timeout');
     }
     // Reset idle flag when activity resumes
     if (idleSeconds !== null && idleSeconds < IDLE_THRESHOLD_SECONDS) {
@@ -3060,6 +3226,49 @@ setInterval(() => {
       }
     }
 
+    // #17: CONNECTED-zombie GC via cmux surface-liveness. Post-08cd796 a wrapped cmux bridge
+    // SURVIVES its terminal app's death, so ownerWs stays OPEN and the 300s disconnect-GC
+    // (below) never fires. If the workspace was EXPLICITLY closed while cmux itself is alive,
+    // the session is a headless zombie → reclaim it after a grace window. INV-17: isSurfaceAlive
+    // returns 'unknown' when cmux is unreachable (app-quit/restart vanishes ALL surfaces at
+    // once), so this GCs NOTHING in that case — preserving the #486/#488 survival guarantee.
+    if (session.type === 'wrapped' && session.backend === 'cmux' && session.cmuxWorkspaceId
+        && isOpenWebSocket(session.ownerWs)) {
+      const liveness = terminalBackend.isSurfaceAlive(session);
+      const gcAction = decideSurfaceGc(liveness, session, now);
+      if (gcAction === 'mark') {
+        session.surfaceGoneAt = new Date().toISOString();
+        console.log(`[SURFACE-GC] cmux workspace gone for ${id} (${session.cmuxWorkspaceId}) — ${SURFACE_ORPHAN_SECONDS}s grace started`);
+      } else if (gcAction === 'reclaim') {
+        const goneSeconds = Math.floor((now - new Date(session.surfaceGoneAt).getTime()) / 1000);
+        console.log(`[SURFACE-GC] Reclaiming headless cmux zombie ${id} after ${goneSeconds}s surface-gone`);
+        emitSessionLifecycleEvent('session_cleanup', id, session, {
+          reason: 'SURFACE_GONE',
+          surfaceGoneSeconds: goneSeconds
+        });
+        // Surface-ownership verdict (2026-05-30): telepty reclaims the zombie SESSION but does
+        // NOT close the surface. Emit the orphan SIGNAL so the orchestrator's reconciler closes
+        // the surface (wh_close). telepty signals; the orchestrator actuates.
+        broadcastSessionEvent('surface_orphaned', id, session, {
+          extra: {
+            sid: id,
+            backend: session.backend || null,
+            cmuxWorkspaceId: session.cmuxWorkspaceId || null,
+            surfaceGoneSeconds: goneSeconds,
+            livenessVerdict: liveness
+          }
+        });
+        teardownSessionById(id, { force: true, timeoutMs: 5000, reason: 'SURFACE_GONE', source: 'surface_gc' })
+          .catch(err => console.error(`[SURFACE-GC] teardown failed for ${id}: ${err.message}`));
+        continue; // being destroyed — skip remaining checks for this session this tick
+      } else if (gcAction === 'recover') {
+        // Recovery within the grace window (mirrors the aterm socket-recover above).
+        console.log(`[SURFACE-GC] cmux workspace recovered for ${id} — clearing grace window`);
+        session.surfaceGoneAt = null;
+      }
+      // 'skip' (incl. 'unknown' — INV-17 gate) → leave surfaceGoneAt unchanged, GC nothing.
+    }
+
     if (healthStatus === 'STALE' && !session._staleEmitted) {
       session._staleEmitted = true;
       emitSessionLifecycleEvent('session_stale', id, session, {
@@ -3086,7 +3295,7 @@ setInterval(() => {
   }
 }, HEALTH_POLL_MS);
 
-server.on('error', async (error) => {
+if (server) server.on('error', async (error) => {
   clearDaemonState(process.pid);
 
   if (error && error.code === 'EADDRINUSE') {
@@ -3230,25 +3439,8 @@ wss.on('connection', (ws, req) => {
             // fired (pendingReports[sessionId].idleNotified === true).
             const pendingReport = pendingReports[sessionId];
             if (pendingReport && !pendingReport.idleNotified) {
-              pendingReport.idleNotified = true;
-              pendingReport.idleAt = new Date().toISOString();
-              const elapsed = ((Date.now() - new Date(pendingReport.injectedAt).getTime()) / 1000).toFixed(1);
-              // Fire new bus event + legacy text-inject
-              broadcastSessionEvent('TASK_IDLE_NO_REPORT', sessionId, activeSession, {
-                extra: {
-                  source: pendingReport.source,
-                  inject_id: pendingReport.injectId,
-                  elapsed_secs: Number(elapsed),
-                  injected_at: pendingReport.injectedAt
-                }
-              });
-              const reportMsg = `TASK_COMPLETE: ${sessionId} is now idle after processing inject (${elapsed}s)`;
-              const srcId = resolveSessionAlias(pendingReport.source) || pendingReport.source;
-              const srcSession = sessions[srcId];
-              if (srcSession) {
-                deliverInjectionToSession(srcId, srcSession, reportMsg, { noEnter: false, source: 'auto_report' });
-                console.log(`[AUTO-REPORT] ${sessionId} → ${srcId}: idle after ${elapsed}s (ready signal)`);
-              }
+              // ready-signal: cli.js bridge emitted a 'ready' WS frame.
+              fireAutoReport(sessionId, activeSession, pendingReport, 'ready-signal');
             }
           }
         } else {
@@ -3277,6 +3469,13 @@ wss.on('connection', (ws, req) => {
     activeSession.clients.delete(ws);
     if (activeSession.type === 'wrapped' && ws === activeSession.ownerWs) {
       activeSession.ownerWs = null;
+      // #29: cancel any pending owner-alive optimistic timer — the owner is gone, so the
+      // floor must not flip a disconnected session ready (hygiene; the timer also re-guards
+      // on isOpenWebSocket, but clearing avoids a dangling handle).
+      if (activeSession.bootstrapOptimisticTimer) {
+        clearTimeout(activeSession.bootstrapOptimisticTimer);
+        activeSession.bootstrapOptimisticTimer = null;
+      }
       markSessionDisconnected(activeSession);
       console.log(`[WS] Wrap owner disconnected from session ${sessionId} (Total: ${activeSession.clients.size})`);
       emitSessionLifecycleEvent('session_disconnect', sessionId, activeSession, {
@@ -3337,7 +3536,7 @@ busWss.on('connection', (ws, req) => {
   });
 });
 
-server.on('upgrade', (req, socket, head) => {
+if (server) server.on('upgrade', (req, socket, head) => {
   const url = new URL(req.url, 'http://' + req.headers.host);
   const token = url.searchParams.get('token');
   
@@ -3369,8 +3568,23 @@ function shutdown(code) {
   process.exit(code);
 }
 
-process.on('SIGINT', () => shutdown(0));
-process.on('SIGTERM', () => shutdown(0));
-process.on('exit', () => {
-  clearDaemonState(process.pid);
-});
+// Daemon-lifecycle signal/exit handlers — only when run as the daemon, so a test require does
+// not register them (and does not clear on-disk daemon-state at the test process's exit).
+if (require.main === module) {
+  process.on('SIGINT', () => shutdown(0));
+  process.on('SIGTERM', () => shutdown(0));
+  process.on('exit', () => {
+    clearDaemonState(process.pid);
+  });
+}
+
+// Minimal test surface (no logic change): expose the pure lifecycle decisions + DI-seamed
+// helpers so the daemon ACs are unit-testable without starting the daemon. Behavior for the
+// production call sites is unchanged. NOT a public API — internal/test use only.
+module.exports = {
+  fireAutoReport,                 // #32: provenance-tagged auto-report (deps DI: now/deliver/...)
+  failBootstrapQueueOnTimeout,    // #31: actionable bootstrap-timeout queue flush
+  shouldApplyOwnerAliveFloor,     // #29: owner-alive optimistic-floor decision (deps DI: isProcessRunning/...)
+  scheduleBootstrapPromptPoll,    // #29: arms the floor timer (deps DI: setTimeout/...)
+  decideSurfaceGc,                // #17: surface-liveness verdict→action (incl. INV-17 unknown→skip)
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-telepty",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "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/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 && 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: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 && 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).`);
+  }
+})();

package/skills/telepty/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty
-description: Overview of telepty — PTY multiplexer for AI session orchestration. Use this when user asks "what is telepty" or needs a getting-started guide. 키워드: 텔레프티, 텔레프티 개요, 시작하기, telepty 소개, 사용법, 가이드
+description: 'Overview of telepty — PTY multiplexer for AI session orchestration. Use this when user asks "what is telepty" or needs a getting-started guide. 키워드: 텔레프티, 텔레프티 개요, 시작하기, telepty 소개, 사용법, 가이드'
 ---
 
 # telepty — Overview

package/skills/telepty-allow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-allow
-description: Create telepty sessions by wrapping CLI processes. Covers the allow/enable/wrap command for session creation and PTY management. 키워드: 세션 생성, 세션 래핑, CLI 래핑, allow, 세션 만들기, PTY
+description: 'Create telepty sessions by wrapping CLI processes. Covers the allow/enable/wrap command for session creation and PTY management. 키워드: 세션 생성, 세션 래핑, CLI 래핑, allow, 세션 만들기, PTY'
 ---
 
 # telepty-allow — Create and Manage Sessions

package/skills/telepty-attach/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-attach
-description: Attach interactively to a telepty session to view output and send input in real-time. 키워드: 세션 접속, 세션 연결, 세션 들어가기, 어태치, attach, 실시간 보기
+description: 'Attach interactively to a telepty session to view output and send input in real-time. 키워드: 세션 접속, 세션 연결, 세션 들어가기, 어태치, attach, 실시간 보기'
 ---
 
 # telepty-attach — Interactive Session Attachment

package/skills/telepty-broadcast/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-broadcast
-description: Send messages to multiple telepty sessions at once. Covers broadcast (all sessions) and multicast (selected targets). 키워드: 전체 공지, 모든 세션에, 일괄 전송, 브로드캐스트, 멀티캐스트, 다중 주입
+description: 'Send messages to multiple telepty sessions at once. Covers broadcast (all sessions) and multicast (selected targets). 키워드: 전체 공지, 모든 세션에, 일괄 전송, 브로드캐스트, 멀티캐스트, 다중 주입'
 ---
 
 # telepty-broadcast — Multi-Target Messaging

package/skills/telepty-daemon/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-daemon
-description: Manage the telepty daemon — start, stop, repair, update, and TUI dashboard. Use when daemon is broken or needs maintenance. 키워드: 데몬 시작, 데몬 재시작, 데몬 종료, TUI, 대시보드, 데몬 상태, daemon
+description: 'Manage the telepty daemon — start, stop, repair, update, and TUI dashboard. Use when daemon is broken or needs maintenance. 키워드: 데몬 시작, 데몬 재시작, 데몬 종료, TUI, 대시보드, 데몬 상태, daemon'
 ---
 
 # telepty-daemon — Daemon Management

package/skills/telepty-inject/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-inject
-description: Send messages, commands, and keystrokes to telepty sessions. Covers inject, enter, send-key, and reply commands. 키워드: 세션에 메시지, 메시지 보내기, 전달, 주입, inject, 응답, 답장, 키 입력
+description: 'Send messages, commands, and keystrokes to telepty sessions. Covers inject, enter, send-key, and reply commands. 키워드: 세션에 메시지, 메시지 보내기, 전달, 주입, inject, 응답, 답장, 키 입력'
 ---
 
 # telepty-inject — Send Messages to Sessions

package/skills/telepty-list/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-list
-description: Discover telepty sessions, check status and health. Covers list, session info, and status commands. 키워드: 세션 목록, 활성 세션, 세션 조회, 세션 상태, 세션 확인, 리스트
+description: 'Discover telepty sessions, check status and health. Covers list, session info, and status commands. 키워드: 세션 목록, 활성 세션, 세션 조회, 세션 상태, 세션 확인, 리스트'
 ---
 
 # telepty-list — Discover Sessions and Check Status

package/skills/telepty-listen/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-listen
-description: Monitor telepty events and read session screen output. Covers listen (event bus) and read-screen commands. 키워드: 이벤트 모니터, 화면 확인, 화면 읽기, 이벤트 스트림, listen, read-screen, 모니터링
+description: 'Monitor telepty events and read session screen output. Covers listen (event bus) and read-screen commands. 키워드: 이벤트 모니터, 화면 확인, 화면 읽기, 이벤트 스트림, listen, read-screen, 모니터링'
 ---
 
 # telepty-listen — Event Monitoring and Screen Reading

package/skills/telepty-rename/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-rename
-description: Rename, delete, and clean up telepty sessions. Session lifecycle management. 키워드: 세션 이름 변경, 세션 삭제, 세션 정리, 세션 청소, rename, 라이프사이클
+description: 'Rename, delete, and clean up telepty sessions. Session lifecycle management. 키워드: 세션 이름 변경, 세션 삭제, 세션 정리, 세션 청소, rename, 라이프사이클'
 ---
 
 # telepty-rename — Session Lifecycle Management

package/skills/telepty-session/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telepty-session
-description: Multi-session orchestration — start multiple sessions at once and arrange terminal layouts. Covers session start and layout commands. 키워드: 멀티 세션 시작, 다중 세션, 세션 레이아웃, 세션 일괄 시작, 멀티 시작, layout
+description: 'Multi-session orchestration — start multiple sessions at once and arrange terminal layouts. Covers session start and layout commands. 키워드: 멀티 세션 시작, 다중 세션, 세션 레이아웃, 세션 일괄 시작, 멀티 시작, layout'
 ---
 
 # telepty-session — Multi-Session Orchestration

package/src/prompt-symbol-registry.js

@@ -33,19 +33,49 @@ const ENTRIES = {
       return { found: false };
     },
   },
-  // codex renders idle as " › <placeholder>" (column 2). Status footer
-  // ("gpt-5.5 …" or "gpt-5 …") sits 1–2 lines below.
+  // #472 (0.4.5): codex previously matched on a strict line-leading "^ › "
+  // shape; on real cmux captures the '›' tail-renders on the same row as the
+  // model-status footer and DECRQM/cursor-pos fragments leak in, so that
+  // strict matcher misses. Multi-signal tolerant matcher: picker anti-pattern
+  // first (resume-picker UI must NOT be considered ready), then a tolerant
+  // (a + b) signal pair, then the legacy strict scan as a back-compat
+  // fallback. Reason field surfaces which signal fired for log-attribution.
   codex: {
     symbol: '›',
     byteSeq: Buffer.from([0xE2, 0x80, 0xBA]),
     detect(screen) {
-      const lines = String(screen == null ? '' : screen).split('\n');
+      const text = String(screen == null ? '' : screen);
+
+      // Step 1: modal-UI anti-pattern. Resume picker, first-run directory
+      // trust prompt, and generic "Press enter to continue" modals are all
+      // pre-prompt UIs where Enter would not submit a user message. Treat
+      // any of them as NOT ready.
+      if (
+        /Resume a previous session/.test(text) ||
+        /^Filter:/m.test(text) ||
+        /Do you trust the contents/i.test(text) ||
+        /Press enter to continue/i.test(text)
+      ) {
+        return { found: false, reason: 'codex_modal_ui' };
+      }
+
+      // Step 2: multi-signal tolerant. The codex boot box contains
+      // "OpenAI Codex (v<version>)" and the status row contains
+      // "gpt-<ver> <profile> fast". Both present anywhere on the captured
+      // screen → ready, regardless of where the literal '›' rendered.
+      if (/OpenAI Codex \(v/.test(text) && /gpt-[0-9.]+\s+\w+\s+fast/.test(text)) {
+        return { found: true, reason: 'codex_multi_signal' };
+      }
+
+      // Step 3: legacy strict line-leading scan — preserved for back-compat
+      // on clean cmux captures where the original matcher already worked.
+      const lines = text.split('\n');
       for (let i = lines.length - 1; i >= 0; i--) {
         const line = lines[i];
         if (!/^ › /.test(line)) continue;
         const footer = (lines[i + 1] || '') + '\n' + (lines[i + 2] || '');
         if (/gpt-\d/.test(footer)) {
-          return { found: true, line_index: i, col: 2 };
+          return { found: true, line_index: i, col: 2, reason: 'codex_strict_line' };
         }
       }
       return { found: false };

package/src/submit-gate.js

@@ -227,7 +227,13 @@ async function awaitPromptSymbol(session, opts = {}) {
         if (lastSeenAt === null) {
           lastSeenAt = now();
         } else if (now() - lastSeenAt >= stabilityMs) {
-          return { ready: true, last_seen_at: lastSeenAt, waited_ms: now() - start };
+          // #472 (0.4.5): tag the success reason for debuggability — pairs
+          // with daemon.js startup-restore optimistic-ready logging so we
+          // can attribute every bootstrap_ready flip to a concrete signal.
+          if (match.reason && typeof console !== 'undefined' && console.log) {
+            console.log(`[bootstrap] ${session.command} ready via: ${match.reason}`);
+          }
+          return { ready: true, last_seen_at: lastSeenAt, waited_ms: now() - start, reason: match.reason };
         }
       } else {
         // symbol disappeared — reset the stability streak

package/terminal-backend.js

@@ -1,6 +1,15 @@
 'use strict';
 
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
+
+// #17/#30/#31: validate a cmux id before it flows into a cmux invocation. cmux ids are
+// UUIDs, typed short-refs (workspace:N / surface:N / pane:N / window:N / tab:N), or numeric
+// indexes. New surface-lifecycle methods shell out via execFileSync (arg arrays, no shell),
+// and this allowlist additionally rejects anything malformed.
+const CMUX_REF_RE = /^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:workspace|surface|pane|window|tab):\d+|\d+)$/;
+function isCmuxRef(id) {
+  return typeof id === 'string' && CMUX_REF_RE.test(id);
+}
 
 // Detect terminal environment at daemon level
 function detectTerminal() {
@@ -126,6 +135,63 @@ function clearCache() {
   lastCacheRefresh = 0;
 }
 
+// #17/#30: liveness of a session's cmux workspace surface (forced, cache-bypassing).
+//   'unknown' — non-cmux backend, missing/invalid id, OR cmux itself unreachable. The last
+//               case is the INV-17 gate: a cmux app-quit/restart makes ALL surfaces vanish at
+//               once, so an unreachable cmux means INDETERMINATE → caller must PRESERVE (GC
+//               nothing), preserving the #486/#488 survival guarantee.
+//   'gone'    — cmux reachable but this session's workspace UUID is absent from the live list
+//               (an explicit single-workspace close while the bridge survived).
+//   'alive'   — cmux reachable and the workspace is present.
+function isSurfaceAlive(session) {
+  if (!session || session.backend !== 'cmux') return 'unknown';
+  const wid = session.cmuxWorkspaceId;
+  if (!isCmuxRef(wid)) return 'unknown';
+  // INV-17 gate: cmux unreachable → INDETERMINATE.
+  try {
+    execFileSync('cmux', ['ping'], { timeout: 2000, stdio: ['pipe', 'pipe', 'pipe'] });
+  } catch {
+    return 'unknown';
+  }
+  // Enumerate live workspace UUIDs. A failure here (pinged OK but list errored) is still
+  // treated as INDETERMINATE rather than 'gone', so a transient cmux hiccup never GCs.
+  let listing;
+  try {
+    listing = execFileSync('cmux', ['--id-format', 'uuids', 'list-workspaces'], {
+      timeout: 5000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+    });
+  } catch {
+    return 'unknown';
+  }
+  const needle = String(wid).toLowerCase();
+  const present = listing.split('\n').some(line => line.toLowerCase().includes(needle));
+  return present ? 'alive' : 'gone';
+}
+
+// Terminal-surface CLOSE is owned by the orchestrator's Workspace Host adapter
+// (workspace-host.sh `wh_close`), per the 2026-05-30 surface-ownership verdict — telepty
+// probes liveness and emits `surface_orphaned`, it does not actuate surface close on the
+// managed path. This function is a STANDALONE-ONLY fallback (orchestrator-absent): it stays a
+// no-op unless AIGENTRY_TELEPTY_SELF_CLOSE_SURFACE=1, so a single-installed telepty can opt in
+// to closing its own orphan tab. Default off → no managed-path double-close.
+function closeSurface(session) {
+  if (process.env.AIGENTRY_TELEPTY_SELF_CLOSE_SURFACE !== '1') return true; // managed default: no-op
+  if (!session || session.backend !== 'cmux') return true; // kitty/headless: no-op
+  const wid = session.cmuxWorkspaceId;
+  if (!isCmuxRef(wid)) return true; // nothing addressable to close
+  try {
+    execFileSync('cmux', ['close-workspace', '--workspace', String(wid)], {
+      timeout: 5000, stdio: ['pipe', 'pipe', 'pipe']
+    });
+    console.log(`[BACKEND] cmux close-workspace ${wid} (self-close opt-in)`);
+    return true;
+  } catch (err) {
+    // Already-gone / transient: harmless no-op, never blocks the destroy.
+    console.log(`[BACKEND] cmux close-workspace ${wid} no-op (${err.message})`);
+    return true;
+  }
+}
+
 module.exports = {
   detectTerminal,
   findSurface,
@@ -133,5 +199,7 @@ module.exports = {
   cmuxSendEnter,
   refreshSurfaceCache,
   invalidateCache,
-  clearCache
+  clearCache,
+  isSurfaceAlive,
+  closeSurface
 };