@dmsdc-ai/aigentry-telepty 0.5.1 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-telepty",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "main": "daemon.js",
   "bin": {
     "aigentry-telepty": "install.js",
@@ -35,9 +35,10 @@
   ],
   "scripts": {
     "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/",
+    "test": "node --test test/auth.test.js test/http-auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/integration/daemon-launch.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/session-store-persistence.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/http-auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/integration/daemon-launch.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/session-store-persistence.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/http-auth.test.js test/daemon.test.js test/daemon-singleton.test.js test/integration/daemon-launch.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/session-store-persistence.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/",
+    "typecheck": "tsc --noEmit",
     "regen-fixtures": "node scripts/regen-snippet-fixtures.js"
   },
   "keywords": [
@@ -78,5 +79,9 @@
     "uuid": "^9.0.0",
     "ws": "^8.19.0",
     "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.41",
+    "typescript": "^6.0.3"
   }
 }

package/src/cli/session-view.js

@@ -0,0 +1,100 @@
+const { formatHostLabel } = require('../../session-routing');
+const lifecycle = require('../lifecycle');
+
+function detectTerminalProgram(env = process.env) {
+  const rawTermProgram = typeof env.TERM_PROGRAM === 'string' ? env.TERM_PROGRAM.trim() : '';
+  if (rawTermProgram) {
+    return rawTermProgram;
+  }
+
+  if (env.TMUX) {
+    return 'tmux';
+  }
+
+  const term = typeof env.TERM === 'string' ? env.TERM.toLowerCase() : '';
+  if (term.includes('kitty')) return 'kitty';
+  if (term.includes('ghostty')) return 'ghostty';
+  if (term.includes('tmux')) return 'tmux';
+
+  return null;
+}
+
+function formatSessionTerminal(session) {
+  const terminal = session.terminal || session.termProgram || null;
+  const term = session.term || null;
+  if (terminal && term) {
+    return `${terminal} (${term})`;
+  }
+  return terminal || term || 'unknown';
+}
+
+function formatSessionHealth(session) {
+  const status = session.healthStatus || 'UNKNOWN';
+  const reason = session.healthReason || null;
+  if (reason && reason !== status) {
+    return `${status} (${reason})`;
+  }
+  return status;
+}
+
+function enrichSessionIdle(session, nowMs = Date.now()) {
+  const idleSeconds = typeof session.idleSeconds === 'number'
+    ? session.idleSeconds
+    : lifecycle.computeIdleSeconds(session.lastActivityAt, nowMs);
+  return {
+    ...session,
+    idleSeconds,
+    idle_seconds: idleSeconds
+  };
+}
+
+function formatSessionStatusWithIdle(session) {
+  const base = formatSessionHealth(session);
+  const idleSeconds = typeof session.idleSeconds === 'number' ? session.idleSeconds : null;
+  if (idleSeconds !== null && idleSeconds > 60) {
+    return `${base} 💤 idle (${lifecycle.formatIdleDuration(idleSeconds)})`;
+  }
+  return base;
+}
+
+function printSessionInfo(session, options = {}) {
+  const host = options.host || session.host || '127.0.0.1';
+  console.log('\x1b[1mSession Info:\x1b[0m');
+  console.log(`  - ID: \x1b[36m${session.id}\x1b[0m`);
+  console.log(`    Host: ${formatHostLabel(host)}`);
+  console.log(`    Command: ${session.command}`);
+  console.log(`    Type: ${session.type || 'unknown'}`);
+  console.log(`    Status: ${formatSessionHealth(session)}`);
+  console.log(`    Terminal: ${session.terminal || session.termProgram || 'unknown'}`);
+  console.log(`    TERM: ${session.term || 'n/a'}`);
+  console.log(`    CWD: ${session.cwd}`);
+  console.log(`    Clients: ${session.active_clients ?? 0}`);
+  if (session.createdAt) {
+    console.log(`    Started: ${new Date(session.createdAt).toLocaleString()}`);
+  }
+  if (session.lastActivityAt) {
+    console.log(`    Last Activity: ${new Date(session.lastActivityAt).toLocaleString()}`);
+  }
+  if (typeof session.idleSeconds === 'number') {
+    console.log(`    Idle: ${session.idleSeconds}s`);
+  }
+  if (session.semantic && session.semantic.phase) {
+    console.log(`    Phase: ${session.semantic.phase}`);
+  }
+  if (session.semantic && session.semantic.current_task) {
+    console.log(`    Current Task: ${session.semantic.current_task}`);
+  }
+  if (session.semantic && session.semantic.blocker) {
+    console.log(`    Blocker: ${session.semantic.blocker}`);
+  }
+  console.log('');
+}
+
+module.exports = {
+  detectTerminalProgram,
+  formatSessionTerminal,
+  formatSessionHealth,
+  enrichSessionIdle,
+  formatSessionStatusWithIdle,
+  printSessionInfo
+};

package/src/lifecycle.js

@@ -6,6 +6,12 @@ const os = require('node:os');
 
 const { killWindowsProcess } = require('./win-kill-process');
 
+// #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));
+const SURFACE_MISMATCH_SECONDS = Math.max(1, Number(process.env.TELEPTY_SURFACE_MISMATCH_SECONDS || 10));
+
 const DURATION_RE = /^(\d+)(ms|s|m|h|d)$/i;
 const UNIT_MS = {
   ms: 1,
@@ -223,7 +229,110 @@ function selectCleanOlderThanTargets(sessions, options = {}) {
   return targets;
 }
 
+// #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';
+}
+
+function clearSurfaceMismatchState(session) {
+  if (!session) return;
+  session.surfaceMismatchAt = null;
+  session.surfaceMismatchObserved = null;
+  session.surfaceMismatchEmitted = false;
+}
+
+function getExpectedPtyPidFromProbe(session, probe) {
+  const candidates = [
+    probe && probe.expectedPtyPid,
+    session && session.ptyPid,
+    session && session.pty_pid,
+    session && session.ptyProcess && session.ptyProcess.pid,
+    session && session.pid
+  ];
+  for (const pid of candidates) {
+    const n = Number(pid);
+    if (Number.isInteger(n) && n > 0) return n;
+  }
+  return null;
+}
+
+function buildSurfaceMismatchExtra(sessionId, session, probe, mismatchSeconds) {
+  return {
+    sid: sessionId,
+    backend: 'cmux',
+    cmuxWorkspaceId: session && session.cmuxWorkspaceId ? session.cmuxWorkspaceId : null,
+    expectedPtyPid: getExpectedPtyPidFromProbe(session, probe),
+    observedSurface: probe && probe.observedSurface ? probe.observedSurface : null,
+    mismatchSeconds
+  };
+}
+
+function getSurfaceMismatchObservedKey(probe) {
+  if (!probe || typeof probe !== 'object') return null;
+  return probe.observedSurfaceKey || probe.observedSurface || null;
+}
+
+function applySurfaceMismatchProbe(sessionId, session, probe, options = {}) {
+  if (!session) return { action: 'skip', reason: 'missing_session' };
+  const nowMs = options.nowMs ?? Date.now();
+  const debounceSeconds = options.debounceSeconds ?? SURFACE_MISMATCH_SECONDS;
+
+  if (!probe || probe.status !== 'mismatch') {
+    const hadState = !!(session.surfaceMismatchAt || session.surfaceMismatchObserved || session.surfaceMismatchEmitted);
+    clearSurfaceMismatchState(session);
+    return { action: hadState ? 'recover' : 'skip', reason: (probe && (probe.reason || probe.status)) || 'not_mismatch' };
+  }
+
+  const observedKey = getSurfaceMismatchObservedKey(probe);
+  if (!observedKey) {
+    clearSurfaceMismatchState(session);
+    return { action: 'skip', reason: 'observed_surface_unknown' };
+  }
+
+  if (!session.surfaceMismatchAt || session.surfaceMismatchObserved !== observedKey) {
+    session.surfaceMismatchAt = new Date(nowMs).toISOString();
+    session.surfaceMismatchObserved = observedKey;
+    session.surfaceMismatchEmitted = false;
+    return { action: 'mark', reason: probe.reason || 'mismatch', mismatchSeconds: 0 };
+  }
+
+  const startedMs = new Date(session.surfaceMismatchAt).getTime();
+  if (!Number.isFinite(startedMs)) {
+    session.surfaceMismatchAt = new Date(nowMs).toISOString();
+    session.surfaceMismatchObserved = observedKey;
+    session.surfaceMismatchEmitted = false;
+    return { action: 'mark', reason: 'invalid_start_reset', mismatchSeconds: 0 };
+  }
+
+  const mismatchSeconds = Math.max(0, Math.floor((nowMs - startedMs) / 1000));
+  if (session.surfaceMismatchEmitted) {
+    return { action: 'skip', reason: 'already_emitted', mismatchSeconds };
+  }
+  if (mismatchSeconds < debounceSeconds) {
+    return { action: 'skip', reason: 'debouncing', mismatchSeconds };
+  }
+
+  const extra = buildSurfaceMismatchExtra(sessionId, session, probe, mismatchSeconds);
+  let event = null;
+  if (typeof options.emit === 'function') {
+    event = options.emit(extra);
+  }
+  session.surfaceMismatchEmitted = true;
+  return { action: 'emit', reason: probe.reason || 'mismatch', mismatchSeconds, extra, event };
+}
+
 module.exports = {
+  SURFACE_ORPHAN_SECONDS,
+  SURFACE_MISMATCH_SECONDS,
   parseDuration,
   computeIdleSeconds,
   formatIdleDuration,
@@ -233,5 +342,9 @@ module.exports = {
   cleanupSessionArtifacts,
   effectiveIdleTtlMs,
   selectIdleTtlVictims,
-  selectCleanOlderThanTargets
+  selectCleanOlderThanTargets,
+  decideSurfaceGc,
+  clearSurfaceMismatchState,
+  buildSurfaceMismatchExtra,
+  applySurfaceMismatchProbe
 };

package/src/protocol/http-auth.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const crypto = require('crypto');
+
+function createVerifyJwt(JWT_SECRET) {
+  function verifyJwt(token) {
+    if (!JWT_SECRET || !token) return false;
+    try {
+      // Simple HS256 JWT verification (no external deps)
+      const [headerB64, payloadB64, sigB64] = token.split('.');
+      if (!headerB64 || !payloadB64 || !sigB64) return false;
+      const expected = crypto.createHmac('sha256', JWT_SECRET)
+        .update(`${headerB64}.${payloadB64}`).digest('base64url');
+      if (sigB64 !== expected) return false;
+      const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString());
+      if (payload.exp && Date.now() / 1000 > payload.exp) return false;
+      return payload;
+    } catch { return false; }
+  }
+
+  return verifyJwt;
+}
+
+function createIsAllowedPeer(PEER_ALLOWLIST) {
+  function isAllowedPeer(ip) {
+    if (!ip) return false;
+    const cleanIp = ip.replace('::ffff:', '');
+    // Localhost always allowed (includes SSH tunnel traffic)
+    if (cleanIp === '127.0.0.1' || ip === '::1') return true;
+    // Peer allowlist
+    if (PEER_ALLOWLIST.length > 0) return PEER_ALLOWLIST.includes(cleanIp);
+    // No allowlist = allow all authenticated
+    return true;
+  }
+
+  return isAllowedPeer;
+}
+
+function createAuthMiddleware(options) {
+  const EXPECTED_TOKEN = options.expectedToken;
+  const isAllowedPeer = options.isAllowedPeer;
+  const verifyJwt = options.verifyJwt;
+
+  return (req, res, next) => {
+    const clientIp = req.ip;
+
+    if (isAllowedPeer(clientIp)) {
+      return next(); // Trust local and allowlisted peers (SSH tunnels arrive as localhost)
+    }
+
+    const token = req.headers['x-telepty-token'] || req.query.token;
+    if (token === EXPECTED_TOKEN) {
+      return next();
+    }
+
+    // JWT Bearer token
+    const authHeader = req.headers['authorization'] || '';
+    if (authHeader.startsWith('Bearer ') && verifyJwt(authHeader.slice(7))) {
+      return next();
+    }
+
+    console.warn(`[AUTH] Rejected unauthorized request from ${clientIp}`);
+    res.status(401).json({ error: 'Unauthorized: Invalid or missing token.', code: 'PERMISSION_DENIED' });
+  };
+}
+
+module.exports = {
+  createAuthMiddleware,
+  createIsAllowedPeer,
+  createVerifyJwt
+};

package/src/session-store/persistence.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+function defaultSessionPersistPath(homeDir = os.homedir()) {
+  return path.join(homeDir, '.config', 'aigentry-telepty', 'sessions.json');
+}
+
+function serializePersistedSessions(sessions) {
+  const data = {};
+  for (const [id, s] of Object.entries(sessions)) {
+    data[id] = {
+      id,
+      type: s.type,
+      command: s.command,
+      cwd: s.cwd,
+      backend: s.backend || null,
+      cmuxWorkspaceId: s.cmuxWorkspaceId || null,
+      cmuxSurfaceId: s.cmuxSurfaceId || null,
+      termProgram: s.termProgram || null,
+      term: s.term || null,
+      delivery: s.delivery || null,
+      deliveryEndpoint: s.deliveryEndpoint || null,
+      createdAt: s.createdAt,
+      lastActivityAt: s.lastActivityAt || null,
+      lastConnectedAt: s.lastConnectedAt || null,
+      lastDisconnectedAt: s.lastDisconnectedAt || null,
+      lastStateReportAt: s.lastStateReportAt || null,
+      stateReport: s.stateReport || null,
+      idleTtl: s.idleTtl || null,
+      idleTtlMs: s.idleTtlMs == null ? null : s.idleTtlMs,
+      ownerPid: s.ownerPid || null,
+      ptyPid: s.ptyPid || null
+    };
+  }
+  return data;
+}
+
+function savePersistedSessions(sessions, persistPath = defaultSessionPersistPath()) {
+  try {
+    const data = serializePersistedSessions(sessions);
+    fs.mkdirSync(path.dirname(persistPath), { recursive: true });
+    fs.writeFileSync(persistPath, JSON.stringify(data, null, 2));
+  } catch {}
+}
+
+function loadPersistedSessions(persistPath = defaultSessionPersistPath()) {
+  try {
+    if (!fs.existsSync(persistPath)) return {};
+    return JSON.parse(fs.readFileSync(persistPath, 'utf8'));
+  } catch { return {}; }
+}
+
+function buildRestoredWrappedSession(id, meta, options = {}) {
+  if (meta.type !== 'wrapped') return null;
+
+  const cwd = options.cwd || process.cwd();
+  const nowIso = options.nowIso || (() => new Date().toISOString());
+  return {
+    id, type: 'wrapped', ptyProcess: null, ownerWs: null,
+    command: meta.command || 'wrapped', cwd: meta.cwd || cwd,
+    backend: meta.backend || 'kitty',
+    cmuxWorkspaceId: meta.cmuxWorkspaceId || null,
+    cmuxSurfaceId: meta.cmuxSurfaceId || null,
+    termProgram: meta.termProgram || null,
+    term: meta.term || null,
+    createdAt: meta.createdAt || nowIso(),
+    lastActivityAt: meta.lastActivityAt || nowIso(),
+    lastConnectedAt: meta.lastConnectedAt || null,
+    lastDisconnectedAt: meta.lastDisconnectedAt || meta.lastActivityAt || nowIso(),
+    lastStateReportAt: meta.lastStateReportAt || null,
+    stateReport: meta.stateReport || null,
+    idleTtl: meta.idleTtl || null,
+    idleTtlMs: meta.idleTtlMs == null ? null : meta.idleTtlMs,
+    ownerPid: meta.ownerPid || null,
+    ptyPid: meta.ptyPid || null,
+    clients: new Set(), isClosing: false, outputRing: [], ready: true,     };
+}
+
+module.exports = {
+  defaultSessionPersistPath,
+  serializePersistedSessions,
+  savePersistedSessions,
+  loadPersistedSessions,
+  buildRestoredWrappedSession
+};

package/src/submit-gate.js

@@ -8,6 +8,7 @@
 // Exports:
 //   - awaitReplReady(sessionId, stateManager, opts) → Promise<{ ready, last_state, waited_ms, reason? }>
 //   - verifyBodyConsumed(session, bodyText, opts)   → Promise<{ consumed, waited_ms, reason? }>
+//   - confirmSubmitAccepted(session, bodyText, opts) → Promise<{ accepted, retryable, waited_ms, reason? }>
 //   - isReady(state, minConfidence)                  (test surface)
 //   - isFailed(state)                                (test surface)
 //   - READY_STATES, FAIL_STATES                      (test surface)
@@ -21,6 +22,7 @@ const READY_STATES = new Set(['idle', 'waiting']);
 
 // States where waiting will never produce readiness; resolve immediately.
 const FAIL_STATES = new Set(['dead', 'error', 'restarting']);
+const ACCEPTED_AFTER_SUBMIT_STATES = new Set(['working', 'thinking']);
 
 function isReady(state, minConfidence) {
   if (!state) return false;
@@ -167,6 +169,158 @@ async function verifyBodyConsumed(session, bodyText, opts = {}) {
   }
 }
 
+/**
+ * Confirm that a submitted prompt was accepted by the target TUI.
+ *
+ * Accepted signals short-circuit immediately:
+ *   - the injected body is absent from the current screen/output tail;
+ *   - the session transitions to working/thinking after the CR was sent.
+ *
+ * The only retryable failure is confirmed-unsubmitted: the body stayed visible
+ * for the whole bounded window. Ambiguous/no-observable cases are treated as
+ * success for back-compat, but marked `ambiguous` so callers can report that
+ * the success was optimistic. This keeps CR resend idempotent: resend only
+ * when `retryable === true`.
+ *
+ * @param {{ outputRing?: string[], backend?: string, cmuxWorkspaceId?: string|null }} session
+ * @param {string} bodyText
+ * @param {{ timeoutMs?: number, intervalMs?: number, tailBytes?: number, stripAnsi?: Function, readScreen?: Function, tailLines?: number, getState?: Function, submittedAtMs?: number, now?: Function, sleep?: Function }} [opts]
+ * @returns {Promise<{ accepted: boolean, retryable: boolean, waited_ms: number, reason?: string, ambiguous?: boolean, visibility?: object, state?: object }>}
+ */
+async function confirmSubmitAccepted(session, bodyText, opts = {}) {
+  const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 1500;
+  const intervalMs = Number.isFinite(opts.intervalMs) ? opts.intervalMs : 50;
+  const now = typeof opts.now === 'function' ? opts.now : () => Date.now();
+  const sleep = typeof opts.sleep === 'function' ? opts.sleep : (ms) => new Promise((r) => setTimeout(r, ms));
+  const getState = typeof opts.getState === 'function' ? opts.getState : null;
+  const submittedAtMs = Number.isFinite(opts.submittedAtMs) ? opts.submittedAtMs : now();
+  const start = now();
+
+  let lastVisibility = null;
+  let everVisible = false;
+
+  while (true) {
+    const state = getState ? getState() : null;
+    if (isAcceptedSubmitState(state, submittedAtMs)) {
+      return {
+        accepted: true,
+        retryable: false,
+        waited_ms: now() - start,
+        reason: `state_${state.state}`,
+        state,
+        visibility: lastVisibility || undefined,
+      };
+    }
+
+    const visibility = observeBodyVisibility(session, bodyText, opts);
+    lastVisibility = visibility;
+    if (visibility.reason === 'empty_body') {
+      return {
+        accepted: true,
+        retryable: false,
+        waited_ms: now() - start,
+        reason: 'empty_body',
+        visibility,
+      };
+    }
+    if (!visibility.observable) {
+      return {
+        accepted: true,
+        retryable: false,
+        waited_ms: now() - start,
+        reason: visibility.reason || 'no_observable',
+        ambiguous: true,
+        visibility,
+      };
+    }
+    if (visibility.visible) {
+      everVisible = true;
+    } else {
+      return {
+        accepted: true,
+        retryable: false,
+        waited_ms: now() - start,
+        reason: everVisible ? 'body_consumed' : 'body_absent',
+        visibility,
+      };
+    }
+
+    if (now() - start >= timeoutMs) {
+      return {
+        accepted: false,
+        retryable: true,
+        waited_ms: now() - start,
+        reason: 'body_still_visible',
+        visibility,
+        state: state || undefined,
+      };
+    }
+
+    await sleep(intervalMs);
+  }
+}
+
+function isAcceptedSubmitState(state, submittedAtMs) {
+  if (!state || !ACCEPTED_AFTER_SUBMIT_STATES.has(state.state)) return false;
+  if (!Number.isFinite(submittedAtMs)) {
+    return true;
+  }
+  if (Number.isFinite(state.since_ms) && state.since_ms >= submittedAtMs) {
+    return true;
+  }
+  const lastOutputMs = state.last_output_at ? new Date(state.last_output_at).getTime() : NaN;
+  if (Number.isFinite(lastOutputMs) && lastOutputMs >= submittedAtMs) {
+    return true;
+  }
+  if (Number.isFinite(state.since_ms) && state.since_ms < submittedAtMs) {
+    return false;
+  }
+  return false;
+}
+
+function observeBodyVisibility(session, bodyText, opts = {}) {
+  const needle = normalize(bodyText);
+  if (!needle) {
+    return { observable: true, visible: false, source: 'body', reason: 'empty_body' };
+  }
+
+  const stripAnsi = typeof opts.stripAnsi === 'function' ? opts.stripAnsi : (s) => s;
+  const screen = readCurrentScreen(session, opts);
+  if (typeof screen === 'string' && screen.length > 0) {
+    const haystack = normalize(stripAnsi(screen));
+    return {
+      observable: true,
+      visible: haystack.indexOf(needle) !== -1,
+      source: 'screen',
+    };
+  }
+
+  if (!session || !Array.isArray(session.outputRing)) {
+    return { observable: false, visible: false, source: 'none', reason: 'no_ring' };
+  }
+
+  const tailBytes = Number.isFinite(opts.tailBytes) ? opts.tailBytes : 8192;
+  const haystack = normalize(stripAnsi(readTail(session, tailBytes)));
+  return {
+    observable: true,
+    visible: haystack.indexOf(needle) !== -1,
+    source: 'output_ring',
+  };
+}
+
+function readCurrentScreen(session, opts = {}) {
+  const readScreen = typeof opts.readScreen === 'function'
+    ? opts.readScreen
+    : (session && session.backend === 'cmux' && session.cmuxWorkspaceId ? defaultReadScreen : null);
+  if (!readScreen || !session || !session.cmuxWorkspaceId) return null;
+  const tailLines = Number.isFinite(opts.tailLines) ? opts.tailLines : 30;
+  try {
+    return readScreen(session.cmuxWorkspaceId, tailLines);
+  } catch (_err) {
+    return null;
+  }
+}
+
 function normalize(s) {
   return String(s == null ? '' : s).replace(/\s+/g, ' ').trim();
 }
@@ -266,10 +420,13 @@ function defaultReadScreen(workspaceId, lines) {
 module.exports = {
   awaitReplReady,
   verifyBodyConsumed,
+  confirmSubmitAccepted,
+  observeBodyVisibility,
   awaitPromptSymbol,
   defaultReadScreen,
   isReady,
   isFailed,
   READY_STATES,
   FAIL_STATES,
+  ACCEPTED_AFTER_SUBMIT_STATES,
 };

package/src/transport/peer-relay.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const crypto = require('crypto');
+
+function relayPeersFromEnv(env = process.env) {
+  return (env.TELEPTY_RELAY_PEERS || '').split(',').map(s => s.trim()).filter(Boolean);
+}
+
+function createPeerRelay(options) {
+  const {
+    relayPeers,
+    relaySeen = new Set(),
+    machineId,
+    expectedToken,
+    getPort,
+    fetchImpl = fetch,
+    randomUUID = crypto.randomUUID,
+    timeoutSignal = (ms) => AbortSignal.timeout(ms)
+  } = options;
+
+  return function relayToPeers(msg) {
+    if (relayPeers.length === 0) return;
+    if (!msg.message_id) msg.message_id = randomUUID();
+    if (relaySeen.has(msg.message_id)) return; // already relayed
+    relaySeen.add(msg.message_id);
+    // Prevent unbounded growth
+    if (relaySeen.size > 10000) {
+      const arr = [...relaySeen];
+      arr.splice(0, 5000);
+      relaySeen.clear();
+      arr.forEach(id => relaySeen.add(id));
+    }
+
+    msg.source_host = msg.source_host || machineId;
+    msg._relayed_from = machineId;
+
+    for (const peer of relayPeers) {
+      fetchImpl(`http://${peer}:${getPort()}/api/bus/publish`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'x-telepty-token': expectedToken },
+        body: JSON.stringify(msg),
+        signal: timeoutSignal(3000)
+      }).catch(() => {}); // fire-and-forget
+    }
+  };
+}
+
+module.exports = {
+  createPeerRelay,
+  relayPeersFromEnv
+};