@dmsdc-ai/aigentry-telepty 0.4.5 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,60 @@ 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)

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

@@ -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 {}
@@ -2540,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 {}
@@ -2883,10 +3017,16 @@ 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}`);
-  runStartupBootstrapRestore();
-});
+// 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
@@ -2961,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()) {
@@ -3000,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;
@@ -3051,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) {
@@ -3099,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, {
@@ -3125,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') {
@@ -3269,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 {
@@ -3316,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, {
@@ -3376,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');
   
@@ -3408,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.5",
+  "version": "0.5.0",
   "main": "daemon.js",
   "bin": {
     "aigentry-telepty": "install.js",

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/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
 };