@dmsdc-ai/aigentry-telepty 0.6.2 → 0.6.4

package/CHANGELOG.md

@@ -2,7 +2,64 @@
 
 All notable changes to `@dmsdc-ai/aigentry-telepty` are documented here.
 
-## [Unreleased]
+## [0.6.4] - 2026-06-13
+
+### Added — inject consumption-evidence: consumed | queued | unknown (#53)
+
+- **`telepty inject` now distinguishes "delivered" from "consumed".** After the CR
+  (`pty_cr`), the daemon captures an output-ring watermark and `classifyInjectConsumption()`
+  / `verifyBodyConsumed()` (reusing the #52 echo-watermark technique) classify the result:
+  **consumed** (composer cleared + new turn rendered), **queued** (injected text persists
+  in a busy TUI composer), or **unknown** (conservative). The `/submit` response and CLI
+  output now carry this status; a `queued` result on a busy orchestrator TUI prints a
+  pull-fallback hint. Closes the "`Submitted` reads as success but the busy recipient never
+  consumed it" gap (observed 3+ times in a single orchestration wave). Backward-compatible
+  (accepted/retryable semantics and exit codes unchanged; response is a superset).
+
+## [0.6.3] - 2026-06-13
+
+### ⚠️ BREAKING — daemon binds 127.0.0.1 by default (#50)
+
+- **The daemon (and broker host) now binds `127.0.0.1` instead of `0.0.0.0`.** A fresh install no
+  longer exposes the inject/control API to the local network. **Cross-machine setups where a peer
+  dials this daemon directly over LAN will stop working after the daemon restarts** — opt back in
+  explicitly on the daemon host with `TELEPTY_BIND=0.0.0.0` (the legacy `HOST` env override is
+  still honored; `TELEPTY_BIND` wins when both are set). The startup banner now prints the bind
+  address and a one-line exposure hint. SSH-tunnel peers (`telepty connect`) and the #42 broker
+  node mode (outbound-only) are unaffected.
+
+### Added — `telepty uninstall` + npm preuninstall hook (#49)
+
+- **`telepty uninstall [--purge] [--dry-run]`**: stops running daemons (full discovery chain),
+  unloads **and removes** the launchd plists (`com.aigentry.telepty`, `com.aigentry.telepty-broker`)
+  on macOS, and reports the 3 state directories (`~/.telepty`, `~/.aigentry`,
+  `~/.config/aigentry-telepty`). **User data is kept by default** — the paths are printed; deletion
+  requires the explicit `--purge`. `--dry-run` reports without touching anything.
+- **npm `preuninstall` hook**: daemon stop + plist unload only, quietly; it can never fail (a broken
+  hook would break `npm rm` itself). Note: npm 7+ no longer executes uninstall lifecycle scripts —
+  the reliable path is running `telepty uninstall` before `npm rm -g`.
+
+### Fixed — blocked daemon restarts: actionable diagnostic, no per-command noise (#15)
+
+- When the running daemon cannot be stopped (no `daemon-state.json`, owned by a parent app such as
+  an aterm bundle, EPERM), the CLI used to retry the restart **3 times with backoff and repeat the
+  full mismatch + failure banner on every command**, even though sessions kept working. Now: the
+  discovery chain (state file → process-title scan → port-owner via `lsof`/`Get-NetTCPConnection`)
+  is checked once — if the port owner survives cleanup, the restart **fails fast** with one
+  actionable diagnostic naming the parent process (`Daemon (PID X) is owned by parent Y (pid Z) —
+  restart that app … or run: kill X && telepty daemon`), discovered via new
+  `findParentProcessInfo` (PPID lookup). An identical blocked state (same versions + blocking pid)
+  warns **once** and is then silent (`~/.telepty/restart-failure.json` marker) until the state
+  changes or a restart succeeds.
+
+### Fixed — `--help` is now always safe on payload subcommands (#51)
+
+- `telepty broadcast --help` used to **broadcast the literal string `--help` to every active
+  session**, and `telepty allow --help` spawned a junk `<dir>---help` session. A bare `-h`/`--help`
+  before an explicit `--` separator now always prints the subcommand usage with zero network or
+  fan-out side effects (broadcast/multicast/inject/allow + aliases). Sending the literal text
+  requires the explicit separator: `telepty broadcast -- --help`. Defense-in-depth: broadcast and
+  multicast refuse a payload that is exactly a help flag unless `--` was used.
 
 ## [0.6.2] - 2026-06-10
 

package/cli.js

@@ -11,7 +11,15 @@ const prompts = require('prompts');
 const updateNotifier = require('update-notifier');
 const pkg = require('./package.json');
 const { getConfig } = require('./auth');
-const { cleanupDaemonProcesses, readDaemonState, findPortOwnerPid } = require('./daemon-control');
+const {
+  cleanupDaemonProcesses,
+  clearRestartFailureMarker,
+  findParentProcessInfo,
+  findPortOwnerPid,
+  readDaemonState,
+  readRestartFailureMarker,
+  writeRestartFailureMarker
+} = require('./daemon-control');
 const { attachInteractiveTerminal, getTerminalSize, restoreTerminalModes } = require('./interactive-terminal');
 const { getRuntimeInfo } = require('./runtime-info');
 const { formatHostLabel, groupSessionsByHost, pickSessionTarget } = require('./session-routing');
@@ -434,13 +442,31 @@ async function waitForDaemonHealth(maxMs = 5000) {
   return null;
 }
 
+// telepty#15: actionable diagnostic for a daemon the CLI cannot stop (foreign
+// parent app owns it, EPERM, parent respawns it). Pure formatter, exposed for
+// unit-testing — `parent` is findParentProcessInfo's { ppid, command } or null.
+function formatDaemonStopDiagnostic({ pid, parent }) {
+  if (parent && parent.command) {
+    return `Daemon (PID ${pid}) is owned by parent ${parent.command} (pid ${parent.ppid}) — restart that app to update its bundled daemon, or run: kill ${pid} && telepty daemon`;
+  }
+  return `Daemon (PID ${pid}) could not be stopped — run: kill ${pid} && telepty daemon`;
+}
+
 async function restartDaemonGraceful(options = {}) {
   const maxAttempts = options.maxAttempts || 3;
   const requiredCapabilities = options.requiredCapabilities || [];
+  // Injectable seams (default to the real implementations) so the blocked-restart
+  // path is unit-testable without touching a real daemon or process table (#15;
+  // same pattern as ensureDaemonRunning #567).
+  const cleanup = options._cleanupDaemonProcesses || cleanupDaemonProcesses;
+  const startDaemon = options._startDetachedDaemon || startDetachedDaemon;
+  const waitHealth = options._waitForDaemonHealth || waitForDaemonHealth;
+  const portOwner = options._findPortOwnerPid || findPortOwnerPid;
+  const parentInfo = options._findParentProcessInfo || findParentProcessInfo;
 
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     // (a) Kill existing daemon processes
-    const results = cleanupDaemonProcesses();
+    const results = cleanup();
 
     // (b) Wait up to 3s for old processes to fully exit
     if (results.stopped.length > 0) {
@@ -453,11 +479,22 @@ async function restartDaemonGraceful(options = {}) {
       }
     }
 
+    // telepty#15 fail-fast: when the port is still owned by a process cleanup did
+    // not stop (state file absent and unkillable, EPERM, foreign parent), starting
+    // a new daemon can never bind — the old "3 attempts with backoff" was pure
+    // noise. Stop retrying and emit one actionable diagnostic instead.
+    const survivingOwner = portOwner(Number(PORT));
+    if (Number.isInteger(survivingOwner) && survivingOwner > 0 && survivingOwner !== process.pid) {
+      const diagnostic = formatDaemonStopDiagnostic({ pid: survivingOwner, parent: parentInfo(survivingOwner) });
+      console.error(`\x1b[31m❌ Daemon restart blocked: ${diagnostic}\x1b[0m`);
+      return { success: false, meta: null, attempt, blockedPid: survivingOwner, diagnostic };
+    }
+
     // (c) Start new daemon
-    startDetachedDaemon();
+    startDaemon();
 
     // (d) Wait for new daemon to respond with correct version
-    const meta = await waitForDaemonHealth(5000);
+    const meta = await waitHealth(5000);
     if (meta && meta.version === pkg.version) {
       const hasCapabilities = requiredCapabilities.every(c => (meta.capabilities || []).includes(c));
       if (hasCapabilities || requiredCapabilities.length === 0) {
@@ -711,6 +748,10 @@ async function ensureDaemonRunning(options = {}) {
   const getMeta = options._getDaemonMeta || getDaemonMeta;
   const fetchAuth = options._fetchWithAuth || fetchWithAuth;
   const doRestart = options._restartDaemonGraceful || restartDaemonGraceful;
+  const portOwner = options._findPortOwnerPid || findPortOwnerPid;
+  const readFailureMarker = options._readRestartFailureMarker || readRestartFailureMarker;
+  const writeFailureMarker = options._writeRestartFailureMarker || writeRestartFailureMarker;
+  const clearFailureMarker = options._clearRestartFailureMarker || clearRestartFailureMarker;
   const probe = options._probe || {};
   const attempts = probe.attempts || 3;
   const backoffMs = probe.backoffMs == null ? 200 : probe.backoffMs;
@@ -749,6 +790,21 @@ async function ensureDaemonRunning(options = {}) {
     return; // healthy + correct version + all capabilities → leave the daemon alone (#567)
   }
 
+  // telepty#15: a restart blocked by a daemon the CLI cannot stop (foreign parent
+  // app, EPERM) used to re-warn and re-fail on EVERY command. After warning once,
+  // an identical blocked state (same versions + same blocking pid) stays silent —
+  // sessions keep working through the old daemon — until the signature changes
+  // (daemon upgraded/killed, parent restarted) or a restart succeeds.
+  let signature = null;
+  if (decision.action === 'restart') {
+    const ownerPid = portOwner(Number(PORT));
+    signature = `${decision.reason}:${meta && meta.version ? meta.version : 'none'}->${pkg.version}:pid${ownerPid || 0}`;
+    const marker = readFailureMarker();
+    if (marker && marker.signature === signature) {
+      return; // already warned for exactly this blocked state — stay quiet
+    }
+  }
+
   // stderr (not stdout): banner must not contaminate `telepty list --json` (task #400, telepty#15)
   if (decision.action === 'restart' && decision.reason.startsWith('version-')) {
     process.stderr.write(`\x1b[33m⚙️ Daemon version mismatch (running v${meta.version}, installed v${pkg.version}). Restarting...\x1b[0m\n`);
@@ -759,7 +815,16 @@ async function ensureDaemonRunning(options = {}) {
   } else {
     process.stderr.write('\x1b[33m⚙️ Auto-starting local telepty daemon...\x1b[0m\n');
   }
-  await doRestart({ requiredCapabilities });
+  const result = await doRestart({ requiredCapabilities });
+  if (signature && result && result.success === false && result.blockedPid) {
+    writeFailureMarker({
+      signature: `${decision.reason}:${meta && meta.version ? meta.version : 'none'}->${pkg.version}:pid${result.blockedPid}`,
+      diagnostic: result.diagnostic || null,
+      warnedAt: new Date().toISOString()
+    });
+  } else if (result && result.success) {
+    clearFailureMarker();
+  }
 }
 
 async function manageInteractiveAttach(sessionId, targetHost) {
@@ -1013,9 +1078,70 @@ async function manageInteractive() {
   }
 }
 
+// telepty#51: trailing-payload subcommands (broadcast/multicast/inject/allow) collect
+// free-form text, which swallowed `--help`/`-h` as DATA — `telepty broadcast --help`
+// fanned the literal string out to every active session, and `telepty allow --help`
+// spawned a junk `<dir>---help` session. One shared interceptor (DRY) runs BEFORE each
+// payload parser: a bare `-h`/`--help` appearing before an explicit `--` separator
+// prints the subcommand usage and stops — zero network / fan-out side effects.
+// `telepty <subcommand> -- --help` remains the deliberate way to send the literal text.
+const TRAILING_PAYLOAD_HELP = {
+  allow: [
+    'Usage: telepty allow [--id <session_id>] [--idle-ttl <duration|off>] [--auto-restart] <command> [args...]',
+    '',
+    'Wrap a CLI so other sessions can inject into it. Aliases: enable, wrap.',
+    'Use `--` before the command to pass hyphenated arguments literally:',
+    '  telepty allow -- claude --help'
+  ],
+  inject: [
+    'Usage: telepty inject [--ref [file]] [--from <id>] [--reply-to <id>] [--submit] [--submit-force] [--submit-retry N] <session_id> "<prompt text>"',
+    '',
+    'Inject prompt text into a session. Use `--` before the prompt to send a payload',
+    'that starts with a hyphen: telepty inject my-session -- --help'
+  ],
+  multicast: [
+    'Usage: telepty multicast <id1,id2,...> "<prompt text>"',
+    '',
+    'Inject prompt text into multiple sessions. Use `--` before the prompt to send',
+    'a payload that starts with a hyphen: telepty multicast id1,id2 -- --help'
+  ],
+  broadcast: [
+    'Usage: telepty broadcast [--ref [file]] "<prompt text>"',
+    '',
+    'Inject prompt text into ALL active sessions. Use `--` before the prompt to send',
+    'a payload that starts with a hyphen: telepty broadcast -- --help'
+  ]
+};
+
+// True when a bare `-h`/`--help` token appears before the first `--` separator
+// (everything after `--` is literal payload by universal CLI convention).
+function helpRequested(argv) {
+  for (const arg of argv) {
+    if (arg === '--') return false;
+    if (arg === '--help' || arg === '-h') return true;
+  }
+  return false;
+}
+
+function interceptSubcommandHelp(cmd, argv) {
+  const canonical = (cmd === 'enable' || cmd === 'wrap') ? 'allow' : cmd;
+  const lines = TRAILING_PAYLOAD_HELP[canonical];
+  if (!lines || !helpRequested(argv)) return false;
+  console.log(lines.join('\n'));
+  return true;
+}
+
+// telepty#51 defense-in-depth: even if help interception regresses, broadcast/multicast
+// must never fan out a bare help flag to every session. Literal sends remain possible
+// via the explicit `--` separator (which sets hadSeparator at the call site).
+function isHelpLikePayload(payload) {
+  const text = String(payload || '').trim();
+  return text === '--help' || text === '-h';
+}
+
 async function main() {
   const cmd = args[0];
-  
+
   if (!cmd) {
     return manageInteractive();
   }
@@ -1047,6 +1173,53 @@ async function main() {
     return;
   }
 
+  if (cmd === 'uninstall') {
+    // telepty#49: stop the daemon, unload+remove the launchd plist (macOS), and
+    // report the state dirs. User data is KEPT by default — deleted only with
+    // --purge. --dry-run prints what would happen without touching anything.
+    const purge = args.includes('--purge');
+    const dryRun = args.includes('--dry-run');
+    const { runUninstall } = require('./src/uninstall');
+    const result = runUninstall({ purge, dryRun });
+    const would = dryRun ? 'Would ' : '';
+
+    if (dryRun) {
+      console.log('🔎 Dry run — nothing was stopped, unloaded, or deleted.');
+      console.log(`${would}stop any running telepty daemons (state file → process scan → port owner).`);
+    } else {
+      console.log(`Stopped ${result.stopped.length} telepty daemon(s).`);
+      if (result.failed.length > 0) {
+        console.log(`⚠️ Failed to stop ${result.failed.length} daemon(s) — run "telepty cleanup-daemons" or kill them manually.`);
+      }
+    }
+
+    for (const plist of result.plists) {
+      if (!plist.existed) continue;
+      if (dryRun) {
+        console.log(`${would}unload and remove launchd service: ${plist.path}`);
+      } else {
+        console.log(`Launchd service ${plist.removed ? 'unloaded and removed' : (plist.unloaded ? 'unloaded (file not removed)' : 'removal attempted')}: ${plist.path}`);
+      }
+    }
+
+    const existingDirs = result.stateDirs.filter((d) => d.exists);
+    if (purge) {
+      for (const dir of existingDirs) {
+        console.log(dryRun ? `${would}delete state directory: ${dir.path}` : `${dir.purged ? 'Deleted' : '⚠️ Failed to delete'} state directory: ${dir.path}`);
+      }
+    } else if (existingDirs.length > 0) {
+      console.log('State directories kept (user data — delete with `telepty uninstall --purge`):');
+      for (const dir of existingDirs) {
+        console.log(`  - ${dir.path}`);
+      }
+    }
+
+    if (!dryRun) {
+      console.log('\nNow remove the package: npm rm -g @dmsdc-ai/aigentry-telepty');
+    }
+    return;
+  }
+
   if (cmd === 'cleanup-daemons') {
     const results = cleanupDaemonProcesses();
     console.log(`Stopped ${results.stopped.length} telepty daemon(s).`);
@@ -1279,6 +1452,7 @@ async function main() {
   }
 
   if (cmd === 'allow' || cmd === 'enable' || cmd === 'wrap') {
+    if (interceptSubcommandHelp(cmd, args.slice(1))) return; // telepty#51: never wrap "--help" as a command
     // Parse arguments: telepty allow [--id <session_id>] <command> [args...]
     // Also supports legacy: telepty allow [--id <session_id>] -- <command> [args...]
     const allowArgs = args.slice(1);
@@ -2046,6 +2220,11 @@ async function main() {
   }
 
   if (cmd === 'inject') {
+    if (interceptSubcommandHelp(cmd, args.slice(1))) return; // telepty#51: help must never become the injected prompt
+    // telepty#51: an explicit `--` separator marks the rest as literal payload
+    // (e.g. `telepty inject my-session -- --help` sends the literal text).
+    const injectSepIndex = args.indexOf('--');
+    if (injectSepIndex !== -1) args.splice(injectSepIndex, 1);
     const { useRef, refFilePath } = parseRefOption(args);
 
     if (args.includes('--no-enter')) {
@@ -2244,7 +2423,21 @@ async function main() {
             : '';
           const attemptsNote = submitData.attempts > 1 ? ` (${submitData.attempts} attempts)` : '';
           const forcedNote = submitData.forced ? ' [forced]' : '';
-          console.log(`✅ Submitted via ${submitData.strategy}${attemptsNote}${gateNote}${lateNote}${forcedNote}.`);
+          const tail = `${attemptsNote}${gateNote}${lateNote}${forcedNote}`;
+          // #53: distinguish CONSUMED-as-a-turn from QUEUED-in-a-busy-composer. A bare
+          // "Submitted via pty_cr" only proves bytes reached the PTY; a busy recipient TUI
+          // parks the text without firing a turn, so report that instead of a false success.
+          const consumption = submitData.consumption
+            || (submitData.verify && submitData.verify.consumption) || null;
+          if (consumption === 'queued') {
+            console.log(`⚠️  Submitted via ${submitData.strategy}${tail}, but recipient is BUSY — text QUEUED, NOT consumed as a new turn. It will be processed after the current turn ends; if a reply is expected, fall back to pulling the recipient's state.`);
+          } else if (consumption === 'consumed') {
+            console.log(`✅ Submitted via ${submitData.strategy}${tail} — consumed as a new turn.`);
+          } else if (consumption === 'unknown') {
+            console.log(`✅ Submitted via ${submitData.strategy}${tail} (consumption=unknown — delivered to PTY; turn-consumption not observable).`);
+          } else {
+            console.log(`✅ Submitted via ${submitData.strategy}${tail}.`);
+          }
         } else if (submitRes && submitRes.status === 504) {
           // Soft failure: REPL never readied. Orchestrator scripts depend on
           // exit 0 here — surface a clear remediation hint but do not exit
@@ -2520,8 +2713,19 @@ async function main() {
   }
 
   if (cmd === 'multicast') {
+    if (interceptSubcommandHelp(cmd, args.slice(1))) return; // telepty#51: help must never fan out as data
+    const multicastSepIndex = args.indexOf('--');
+    const multicastHadSeparator = multicastSepIndex !== -1;
+    if (multicastHadSeparator) args.splice(multicastSepIndex, 1);
     const sessionIdsRaw = args[1]; const prompt = args.slice(2).join(' ');
     if (!sessionIdsRaw || !prompt) { console.error('❌ Usage: telepty multicast <id1,id2,...> "<prompt text>"'); process.exit(1); }
+    // telepty#51 defense-in-depth: a payload that is exactly a help flag is almost
+    // certainly a swallowed `--help`, never a real prompt. Refuse unless the caller
+    // opted into the literal send with an explicit `--`.
+    if (!multicastHadSeparator && isHelpLikePayload(prompt)) {
+      console.error('❌ Refusing to multicast a bare help flag. Use `telepty multicast --help` for usage, or `telepty multicast <ids> -- --help` to send the literal text.');
+      process.exit(1);
+    }
     const sessionRefs = sessionIdsRaw.split(',').map(s => s.trim()).filter(s => s);
     try {
       const discovered = await discoverSessions({ silent: true });
@@ -2561,10 +2765,21 @@ async function main() {
   }
 
   if (cmd === 'broadcast') {
+    if (interceptSubcommandHelp(cmd, args.slice(1))) return; // telepty#51: help must never fan out to every session
+    const broadcastSepIndex = args.indexOf('--');
+    const broadcastHadSeparator = broadcastSepIndex !== -1;
+    if (broadcastHadSeparator) args.splice(broadcastSepIndex, 1);
     const { useRef, refFilePath } = parseRefOption(args);
 
     const prompt = args.slice(1).join(' ');
     if (!prompt && !refFilePath) { console.error('❌ Usage: telepty broadcast [--ref [file]] "<prompt text>"'); process.exit(1); }
+    // telepty#51 defense-in-depth: a payload that is exactly a help flag is almost
+    // certainly a swallowed `--help`, never a real prompt. Refuse unless the caller
+    // opted into the literal send with an explicit `--`.
+    if (!broadcastHadSeparator && isHelpLikePayload(prompt)) {
+      console.error('❌ Refusing to broadcast a bare help flag to every session. Use `telepty broadcast --help` for usage, or `telepty broadcast -- --help` to send the literal text.');
+      process.exit(1);
+    }
     try {
       const discovered = await discoverSessions({ silent: true });
       const aggregate = { successful: [], failed: [] };
@@ -3787,6 +4002,7 @@ Discuss the following topic from your project's perspective. Engage with other s
 
 \x1b[1mOther:\x1b[0m
   telepty update                                 Update to latest version
+  telepty uninstall [--purge] [--dry-run]        Stop daemon + unload service; keep user data unless --purge
   telepty layout [grid|tall|stack]               Arrange terminal windows
   telepty status-report --phase <p> [options]    Emit structured status event
 
@@ -3821,4 +4037,8 @@ module.exports = {
   sanitizePathArg,        // #26: path-arg validation/normalization
   decideDaemonAction,     // #567: pure restart-decision policy (meta-primary; no I/O)
   ensureDaemonRunning,    // #567: orchestrator (injectable probes for unit-testing)
+  helpRequested,          // telepty#51: bare -h/--help before `--` → show help, not payload
+  isHelpLikePayload,      // telepty#51: defense-in-depth payload guard for broadcast/multicast
+  formatDaemonStopDiagnostic, // telepty#15: actionable can't-stop-daemon diagnostic (pure)
+  restartDaemonGraceful,  // telepty#15: injectable seams for the blocked-restart fail-fast path
 };

package/daemon-control.js

@@ -275,6 +275,85 @@ function probeTeleptyOnPort(port, opts) {
   });
 }
 
+// telepty#15: identify who launched a daemon we cannot stop (e.g. an older
+// daemon bundled inside a parent app such as aterm), so the CLI can print an
+// actionable diagnostic instead of retrying blindly. Returns
+// { ppid, command } for `pid`'s parent, or null when it cannot be resolved.
+function findParentProcessInfo(pid, opts) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  const o = opts || {};
+  const platform = o.platform || process.platform;
+  const exec = o.execSync || execSync;
+
+  try {
+    if (platform === 'win32') {
+      const script =
+        `$p = Get-CimInstance Win32_Process -Filter "ProcessId=${pid}"; ` +
+        `if ($p) { $pp = Get-CimInstance Win32_Process -Filter "ProcessId=$($p.ParentProcessId)"; ` +
+        `"$($p.ParentProcessId)|$(if ($pp) { $pp.Name } else { '' })" }`;
+      const output = String(exec(`powershell.exe -NoProfile -Command "${script}"`, {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore']
+      })).trim();
+      if (!output) return null;
+      const [ppidRaw, name] = output.split('|');
+      const ppid = Number(ppidRaw);
+      if (!Number.isInteger(ppid) || ppid <= 0) return null;
+      return { ppid, command: (name || '').trim() || null };
+    }
+
+    const ppidRaw = String(exec(`ps -p ${pid} -o ppid=`, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    })).trim();
+    const ppid = Number(ppidRaw);
+    if (!Number.isInteger(ppid) || ppid <= 0) return null;
+    const command = String(exec(`ps -p ${ppid} -o comm=`, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    })).trim() || null;
+    return { ppid, command };
+  } catch {
+    return null;
+  }
+}
+
+// telepty#15: once-per-mismatch warning marker. A daemon the CLI cannot stop
+// (foreign-owned port, EPERM, parent respawns it) used to produce the full
+// mismatch + 3-retries + failure banner on EVERY command. The CLI records the
+// blocked state's signature here after warning once; identical signatures are
+// then silent until the blocking pid / version pair changes or a restart
+// succeeds. `opts.file` is an injectable path so tests never touch ~/.telepty.
+const RESTART_FAILURE_FILE = path.join(TELEPTY_DIR, 'restart-failure.json');
+
+function readRestartFailureMarker(opts) {
+  const file = (opts && opts.file) || RESTART_FAILURE_FILE;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeRestartFailureMarker(marker, opts) {
+  const file = (opts && opts.file) || RESTART_FAILURE_FILE;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, JSON.stringify(marker, null, 2), { mode: 0o600 });
+  } catch {
+    // Best-effort: losing the marker only means a repeated warning, never a failure.
+  }
+}
+
+function clearRestartFailureMarker(opts) {
+  const file = (opts && opts.file) || RESTART_FAILURE_FILE;
+  try {
+    fs.rmSync(file, { force: true });
+  } catch {
+    // Best-effort (see writeRestartFailureMarker).
+  }
+}
+
 // Confirm via local process scan that `pid`'s command line looks like a
 // telepty daemon (fallback when HTTP probe fails — daemon may be stuck).
 function pidMatchesTeleptyCmdline(pid) {
@@ -343,11 +422,15 @@ module.exports = {
   claimDaemonState,
   cleanupDaemonProcesses,
   clearDaemonState,
+  clearRestartFailureMarker,
+  findParentProcessInfo,
   findPortOwnerPid,
   isLikelyTeleptyDaemon,
   isProcessRunning,
   listDaemonProcesses,
   pidMatchesTeleptyCmdline,
   probeTeleptyOnPort,
-  readDaemonState
+  readDaemonState,
+  readRestartFailureMarker,
+  writeRestartFailureMarker
 };

package/daemon.js

@@ -18,6 +18,7 @@ const { UnixSocketNotifier } = require('./src/mailbox/notifier');
 const { SessionStateManager, STATE_DISPLAY, stripAnsi: stripAnsiState } = require('./session-state');
 const { classifyReportPrompt, buildAutoSummary } = require('./src/report-enforcement');
 const submitGate = require('./src/submit-gate');
+const { sampleChildCpuSeconds } = require('./src/child-cpu'); // #52: quiet-thinking CPU recheck
 const readyRegistry = require('./src/prompt-symbol-registry');
 const lifecycle = require('./src/lifecycle');
 const { SURFACE_ORPHAN_SECONDS, SURFACE_MISMATCH_SECONDS, decideSurfaceGc, applySurfaceMismatchProbe } = lifecycle;
@@ -265,7 +266,25 @@ const PORT = process.env.PORT || 3848;
 // Reported by /api/meta so callers (e.g. the test harness) can read it back.
 let boundPort = Number(PORT);
 
-const HOST = process.env.HOST || '0.0.0.0';
+// telepty#50: bind loopback by default — a fresh install must not expose the
+// inject/control API to the local network. Network exposure is an explicit
+// opt-in: TELEPTY_BIND=0.0.0.0 (preferred) or the legacy HOST override.
+// BREAKING: cross-machine peers that dialed this daemon directly over LAN
+// need the opt-in on the daemon host after a restart (see CHANGELOG).
+function resolveBindHost(env) {
+  return env.TELEPTY_BIND || env.HOST || '127.0.0.1';
+}
+
+// One-line bind-address banner so operators can see (and fix) their exposure
+// posture at startup without reading docs.
+function formatBindHint(host) {
+  if (host === '127.0.0.1' || host === 'localhost' || host === '::1') {
+    return `   bind: ${host} (loopback only) — LAN peers cannot connect; opt in with TELEPTY_BIND=0.0.0.0`;
+  }
+  return `   bind: ${host} — reachable from the network (TELEPTY_BIND/HOST opt-in)`;
+}
+
+const HOST = resolveBindHost(process.env);
 process.title = 'telepty-daemon';
 
 // Singleton claim — guarded so a test require neither exits (when a daemon is running) nor
@@ -294,6 +313,13 @@ const IDLE_UNCONFIRMED_SETTLE_SECONDS = Number(process.env.TELEPTY_IDLE_UNCONFIR
 // Output advanced during the settle window while still idle-classified (sparse TUI redraw) →
 // re-settle, bounded so periodic idle redraws cannot starve the genuinely-unconsumed signal.
 const IDLE_UNCONFIRMED_SETTLE_MAX_REARMS = Math.max(0, Number(process.env.TELEPTY_IDLE_UNCONFIRMED_SETTLE_MAX_REARMS) || 3);
+// #52: codex quiet-thinking (no output, no spinner) outlasts the settle chain — the recheck
+// consults the same screen classifier that produced the false idle. Auxiliary heuristic: a
+// wrapped child whose CPU time advanced ≥ this delta across the settle window is working
+// (quiet thinking) — re-settle instead of notifying, on its own (larger) bound so a long
+// no-output stretch is survivable while a pathological always-busy child still signals.
+const IDLE_UNCONFIRMED_CPU_DELTA_SECONDS = Number(process.env.TELEPTY_IDLE_UNCONFIRMED_CPU_DELTA_SECONDS) || 0.1;
+const IDLE_UNCONFIRMED_CPU_MAX_REARMS = Math.max(0, Number(process.env.TELEPTY_IDLE_UNCONFIRMED_CPU_MAX_REARMS) || 24);
 
 function pendingReportHasSubmitEvidence(pendingReport) {
   return !!(pendingReport && (
@@ -303,6 +329,31 @@ function pendingReportHasSubmitEvidence(pendingReport) {
   ));
 }
 
+// #52: the TASK_IDLE_UNCONFIRMED semantic is "inject may NOT have been processed" — gate it
+// on CONSUMPTION evidence the daemon already owns instead of screen idleness. Evidence:
+//   - a screen-VERIFIED submit confirmation (body consumed from the composer, or a state
+//     transition observed after the CR) — 'force'/ambiguous accepts are NOT verification;
+//   - the injected body echoed in PTY frames appended after the inject (composer/transcript
+//     redraw), matched conservatively (submit-gate observeInjectEcho).
+// A definitively failed submit (accepted:false — body observed stuck in the composer /
+// no-land) is positive NON-consumption and can never be overridden by echo, so the
+// never-false-complete invariant of #48 holds: a genuinely unconsumed inject still signals.
+function observeConsumptionEvidence(pendingReport, session) {
+  const confirm = pendingReport.submitConfirm;
+  if (confirm && confirm.accepted === false) {
+    return { observed: false, reason: 'submit_failed' };
+  }
+  if (confirm && confirm.accepted === true && !confirm.ambiguous
+      && (confirm.reason === 'body_consumed' || /^state_(working|thinking)$/.test(String(confirm.reason)))) {
+    return { observed: true, reason: `submit_${confirm.reason}` };
+  }
+  const echo = submitGate.observeInjectEcho(session, pendingReport.injectedBodyPreview, {
+    sinceBytes: Number.isFinite(pendingReport.ringBytesAtInject) ? pendingReport.ringBytesAtInject : null,
+    stripAnsi: stripAnsiState,
+  });
+  return { observed: echo.observed === true, reason: echo.reason };
+}
+
 function getPendingReport(sessionId, registry = pendingReports) {
   if (typeof sessionId !== 'string') return null;
   if (sessionId === '__proto__' || sessionId === 'prototype' || sessionId === 'constructor') return null;
@@ -371,6 +422,9 @@ function fireAutoReport(targetId, targetSession, pendingReport, trigger, deps =
     const st = sessionStateManager.getState(sid);
     return st && st.state ? st.state : null;
   });
+  // #52: wrapped-child CPU sampler for the quiet-thinking recheck (DI for unit tests).
+  const _sampleChildCpu = deps.sampleChildCpu || ((sess) =>
+    sampleChildCpuSeconds(sess ? (sess.ptyPid || (sess.ptyProcess && sess.ptyProcess.pid) || null) : null));
 
   const elapsedNum = (_now() - new Date(pendingReport.injectedAt).getTime()) / 1000;
   const elapsed = elapsedNum.toFixed(1);
@@ -449,6 +503,7 @@ function fireAutoReport(targetId, targetSession, pendingReport, trigger, deps =
     const armSettle = () => {
       const liveAtArm = _sessions[targetId] || targetSession;
       const activityAtArm = liveAtArm ? liveAtArm.lastActivityAt : null;
+      const cpuAtArm = _sampleChildCpu(liveAtArm); // #52: null when unobservable
       pendingReport.unconfirmedSettleTimer = _setTimeout(() => {
         pendingReport.unconfirmedSettleTimer = null;
         const currentPending = getPendingReport(targetId, _pendingReports);
@@ -468,6 +523,18 @@ function fireAutoReport(targetId, targetSession, pendingReport, trigger, deps =
           armSettle();
           return;
         }
+        // #52: screen idle + output stalled, but the wrapped child's CPU time advanced
+        // across the settle window → quiet thinking (codex no-spinner blind spot). Treat
+        // as working: re-settle on its own bound instead of notifying.
+        const cpuNow = _sampleChildCpu(liveSession);
+        if (cpuAtArm != null && cpuNow != null
+            && (cpuNow - cpuAtArm) >= IDLE_UNCONFIRMED_CPU_DELTA_SECONDS
+            && (pendingReport.unconfirmedCpuRearms || 0) < IDLE_UNCONFIRMED_CPU_MAX_REARMS) {
+          pendingReport.unconfirmedCpuRearms = (pendingReport.unconfirmedCpuRearms || 0) + 1;
+          console.log(`[AUTO-REPORT] ${targetId} child CPU advanced ${(cpuNow - cpuAtArm).toFixed(2)}s during settle — quiet-thinking; re-settling (${pendingReport.unconfirmedCpuRearms}/${IDLE_UNCONFIRMED_CPU_MAX_REARMS})`);
+          armSettle();
+          return;
+        }
         pendingReport.unconfirmedSettleDone = true;
         fireAutoReport(targetId, liveSession || targetSession, currentPending, trigger, deps);
       }, settleMs);
@@ -477,6 +544,23 @@ function fireAutoReport(targetId, targetSession, pendingReport, trigger, deps =
     return;
   }
 
+  // #52: before emitting the unconfirmed-DELIVERY warning, check for inject-consumption
+  // evidence (screen-verified submit / post-inject echo). Idle-looking + consumed is at
+  // most a TASK_IDLE fact — not "inject may NOT have been processed". Suppression does not
+  // consume the once-only idleNotified guard, so a later evidence-backed genuine busy→idle
+  // transition can still report TASK_COMPLETE, and the pending entry stays armed until the
+  // worker's content REPORT arrives. Confirmed completions (confirmed === true) are
+  // untouched — this gate only ever silences a would-be false warning, never a signal that
+  // a genuinely unconsumed inject produced (no echo + no verified submit ⇒ falls through).
+  if (!confirmed) {
+    const _observeConsumption = deps.observeConsumptionEvidence || observeConsumptionEvidence;
+    const consumption = _observeConsumption(pendingReport, _sessions[targetId] || targetSession);
+    if (consumption.observed) {
+      console.log(`[AUTO-REPORT] ${targetId} idle-unconfirmed suppressed — inject consumption observed (${consumption.reason}, trigger=${trigger})`);
+      return;
+    }
+  }
+
   pendingReport.idleNotified = true;
   pendingReport.idleAt = new Date(_now()).toISOString();
 
@@ -1613,6 +1697,9 @@ async function deliverInjectionToSession(id, session, prompt, options = {}) {
 
 function appendToOutputRing(session, data) {
   if (!session.outputRing) session.outputRing = [];
+  // #52: monotonic byte counter — the inject-time watermark that scopes echo-evidence
+  // matching to frames appended AFTER the inject (survives ring trimming below).
+  session.outputRingTotalBytes = (session.outputRingTotalBytes || 0) + data.length;
   session.outputRing.push(data);
   // Keep total data under ~200KB limit by trimming old entries
   let totalLen = session.outputRing.reduce((sum, d) => sum + d.length, 0);
@@ -2728,6 +2815,9 @@ app.post('/api/sessions/:id/submit', async (req, res) => {
   const settleEnabled = req.body?.input_settle_gate !== false;
   let strategy = await gatedTerminalSubmit(id, session, injectedBody, settleEnabled);
   let submittedAtMs = Date.now();
+  // #53: outputRing watermark at the CR — scopes consumption-evidence matching to frames
+  // appended AFTER this submit (composer redraw / new-turn render), surviving ring trimming.
+  let ringBytesAtSubmit = session.outputRingTotalBytes || 0;
   let attempts = strategy ? 1 : 0;
   if (!strategy) {
     if (injectedBody) {
@@ -2749,12 +2839,15 @@ app.post('/api/sessions/:id/submit', async (req, res) => {
   // shot is enough. A retry is idempotent only when the body is still visible.
   let verify = null;
   let confirm = null;
+  let consumption = null;        // #53: 'consumed' | 'queued' | 'unknown'
+  let consumptionReason = null;
   if (injectedBody && injectedBody.length > 0) {
     confirm = await confirmSubmitAfterDispatch(id, session, injectedBody, submittedAtMs, verifyTimeoutMs);
     while (confirm && !confirm.accepted && confirm.retryable && attempts <= retries) {
       await new Promise(resolve => setTimeout(resolve, retryDelayMs));
       const retryStrategy = await gatedTerminalSubmit(id, session, injectedBody, settleEnabled);
       submittedAtMs = Date.now();
+      ringBytesAtSubmit = session.outputRingTotalBytes || 0;
       if (!retryStrategy) break;
       strategy = retryStrategy;
       attempts++;
@@ -2762,6 +2855,25 @@ app.post('/api/sessions/:id/submit', async (req, res) => {
     }
     verify = buildSubmitVerify(confirm);
 
+    // #53: consumption-evidence on the DELIVERY path. `confirm.accepted` can read a BUSY
+    // recipient's mid-turn output as success (the isAcceptedSubmitState last_output_at leak),
+    // so additionally classify whether the body was CONSUMED as a fresh turn vs QUEUED in a
+    // busy composer vs UNKNOWN — and surface it to the caller. Advisory + additive: it does
+    // NOT change accepted/retryable (back-compat); it only tells the sender what telepty can
+    // actually observe past the PTY layer. Conservative (never-false-consumed).
+    const consumptionResult = await submitGate.classifyInjectConsumption(session, injectedBody, {
+      submittedAtMs,
+      sinceBytes: ringBytesAtSubmit,
+      getState: () => sessionStateManager.getState(id),
+      stripAnsi: stripAnsiState,
+    });
+    consumption = consumptionResult.status;
+    consumptionReason = consumptionResult.reason;
+    if (verify) {
+      verify.consumption = consumptionResult.status;
+      verify.consumption_reason = consumptionResult.reason;
+    }
+
     if (confirm && !confirm.accepted) {
       const reason = gatedDispatchAfterTimeout ? 'gated_dispatch_unconsumed' : 'submit_unconfirmed';
       const failBody = {
@@ -2776,6 +2888,7 @@ app.post('/api/sessions/:id/submit', async (req, res) => {
         gate_wait_ms: gateResult.waited_ms,
         verify,
         confirm,
+        ...(consumption ? { consumption, consumption_reason: consumptionReason } : {}),
         gated_dispatch_after_timeout: true,
         ...(promptSymbol ? { prompt_symbol: promptSymbol } : {}),
       };
@@ -2798,6 +2911,7 @@ app.post('/api/sessions/:id/submit', async (req, res) => {
     gate_wait_ms: gateResult.waited_ms,
     verify,
     confirm,
+    ...(consumption ? { consumption, consumption_reason: consumptionReason } : {}),
     ...(gatedDispatchAfterTimeout ? { gated_dispatch_after_timeout: true } : {}),
     ...(promptSymbol ? { prompt_symbol: promptSymbol } : {}),
   };
@@ -3004,6 +3118,8 @@ app.post('/api/sessions/:id/inject', async (req, res) => {
         submitExpected: !!no_enter,
         noEnter: !!no_enter,
         injectedBodyPreview: prompt.slice(0, 500),
+        // #52: echo-evidence watermark — only frames appended after this inject count.
+        ringBytesAtInject: session.outputRingTotalBytes || 0,
         awaitingReport: true,
         idleNotified: false
       };
@@ -3762,6 +3878,7 @@ if (require.main === module || process.env.AIGENTRY_TELEPTY_DAEMON_MAIN === '1')
       const address = server.address();
       boundPort = (address && address.port) || Number(PORT);
       console.log(`🔐 aigentry-telepty broker listening on https://${HOST}:${boundPort} (/broker/*)`);
+      console.log(formatBindHint(HOST)); // telepty#50
       runStartupBootstrapRestore();
     });
   } else {
@@ -3769,6 +3886,7 @@ if (require.main === module || process.env.AIGENTRY_TELEPTY_DAEMON_MAIN === '1')
       const address = server.address();
       boundPort = (address && address.port) || Number(PORT);
       console.log(`🚀 aigentry-telepty daemon listening on http://${HOST}:${boundPort}`);
+      console.log(formatBindHint(HOST)); // telepty#50
       runStartupBootstrapRestore();
       // #42 node-mode (§2F-ii): start the broker-client if broker config is present.
       // Absent ⇒ no-op (default-OFF). Started after listen so sessions/delivery are live.
@@ -4151,4 +4269,6 @@ module.exports = {
   loadNodeBrokerConfig,           // node-mode: resolve broker.json / env config (or null)
   startNodeBrokerClient,          // node-mode: start createBrokerClient (default-OFF; in-process deliver)
   deliverInjectionToSession,      // §4.3: the in-process delivery wired into the broker-client
+  resolveBindHost,                // telepty#50: pure bind-address policy (loopback default, env opt-in)
+  formatBindHint,                 // telepty#50: startup bind/exposure banner line
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dmsdc-ai/aigentry-telepty",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "main": "daemon.js",
   "bin": {
     "aigentry-telepty": "install.js",
@@ -29,15 +29,17 @@
     "install.ps1",
     "mcp-server/",
     "scripts/postinstall.js",
+    "scripts/preuninstall.js",
     "src/",
     "skills/",
     "CHANGELOG.md"
   ],
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
-    "test": "node --require ./test-support/setup-env.js --test test/auth.test.js test/http-auth.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.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/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-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/install-service-generation.test.js test/install-broker-service.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.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/idle-unconfirmed-settle.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js && git diff --exit-code tests/snippet-protocol/v1/",
-    "test:watch": "node --require ./test-support/setup-env.js --test --watch test/auth.test.js test/http-auth.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.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/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-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/install-service-generation.test.js test/install-broker-service.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.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/idle-unconfirmed-settle.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js",
-    "test:ci": "node --require ./test-support/setup-env.js --test --test-reporter=spec test/auth.test.js test/http-auth.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.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/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-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/install-service-generation.test.js test/install-broker-service.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.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/idle-unconfirmed-settle.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js && git diff --exit-code tests/snippet-protocol/v1/",
+    "preuninstall": "node scripts/preuninstall.js",
+    "test": "node --require ./test-support/setup-env.js --test test/auth.test.js test/http-auth.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.test.js test/daemon-bind-default.test.js test/integration/daemon-launch.test.js test/cli.test.js test/subcommand-help.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/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/inject-consumption-evidence.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/install-service-generation.test.js test/install-broker-service.test.js test/uninstall.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.test.js test/daemon-restart-fallback-15.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/idle-unconfirmed-settle.test.js test/idle-unconfirmed-consumption.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js && git diff --exit-code tests/snippet-protocol/v1/",
+    "test:watch": "node --require ./test-support/setup-env.js --test --watch test/auth.test.js test/http-auth.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.test.js test/daemon-bind-default.test.js test/integration/daemon-launch.test.js test/cli.test.js test/subcommand-help.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/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/inject-consumption-evidence.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/install-service-generation.test.js test/install-broker-service.test.js test/uninstall.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.test.js test/daemon-restart-fallback-15.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/idle-unconfirmed-settle.test.js test/idle-unconfirmed-consumption.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js",
+    "test:ci": "node --require ./test-support/setup-env.js --test --test-reporter=spec test/auth.test.js test/http-auth.test.js test/broker-protocol.test.js test/broker-auth.test.js test/broker-server.test.js test/broker-client.test.js test/daemon-broker-wiring.test.js test/broker-cli.test.js test/broker-integration.test.js test/daemon.test.js test/daemon-singleton.test.js test/daemon-harness-port.test.js test/daemon-bind-default.test.js test/integration/daemon-launch.test.js test/cli.test.js test/subcommand-help.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/peer-inject-validator.test.js test/enforce-submit-gate.test.js test/submit-gate.test.js test/submit-via-pty.test.js test/submit-render-gate.test.js test/prompt-symbol-registry.test.js test/inject-submit-flags.test.js test/inject-submit-force-env.test.js test/inject-consumption-evidence.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/install-service-generation.test.js test/install-broker-service.test.js test/uninstall.test.js test/win-resolve-executable.test.js test/version-handshake.test.js test/ensure-daemon-running.test.js test/daemon-restart-fallback-15.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/idle-unconfirmed-settle.test.js test/idle-unconfirmed-consumption.test.js test/provenance.test.js test/inject-audit-broker-seam.test.js test/inject-provenance-daemon.test.js test/inject-audit-log.test.js test/inject-audit-daemon.test.js test/inject-audit-cli.test.js && git diff --exit-code tests/snippet-protocol/v1/",
     "typecheck": "tsc --noEmit",
     "regen-fixtures": "node scripts/regen-snippet-fixtures.js"
   },
@@ -59,7 +61,7 @@
   ],
   "author": "dmsdc-ai",
   "license": "ISC",
-  "description": "Universal terminal session bridge \u2014 connect any terminal to any terminal, any machine",
+  "description": "Universal terminal session bridge — connect any terminal to any terminal, any machine",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/dmsdc-ai/aigentry-telepty.git"

package/scripts/preuninstall.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+'use strict';
+
+// telepty#49 — npm preuninstall hook: stop the running daemon and unload the
+// launchd plist QUIETLY before the package files disappear, so `npm rm -g`
+// does not leave a live daemon answering on 3848 or a plist that launchd keeps
+// trying to resurrect. State directories and the plist file itself are left to
+// the explicit `telepty uninstall [--purge]` path.
+//
+// NOTE: npm 7+ no longer executes uninstall lifecycle scripts — this hook
+// covers npm 6 and package managers that still honor it. The documented,
+// reliable cleanup path is `telepty uninstall` (run it BEFORE `npm rm -g`).
+//
+// HARD RULE: this script must never fail — a broken preuninstall would break
+// `npm rm` itself, which is strictly worse than leaving a daemon running.
+
+try {
+  const { runPreuninstall } = require('../src/uninstall');
+  runPreuninstall();
+} catch {
+  // Swallow everything — see HARD RULE above.
+}
+process.exit(0);

package/src/child-cpu.js

@@ -0,0 +1,54 @@
+// src/child-cpu.js — wrapped-child CPU-time sampling for the #52 idle-unconfirmed recheck.
+//
+// codex quiet-thinking is TTY-silent but process-active: at settle-recheck time the
+// daemon samples the wrapped child's cumulative CPU time and treats an advancing value
+// as working evidence (screen idle && CPU advancing → re-settle instead of notifying).
+//
+// Constitution §1/§17: no new dependency — `ps -o time=` on POSIX (macOS/Linux), and a
+// clean null fallback on win32 / missing pid / exec failure so callers keep the prior
+// (#48) behavior whenever CPU is unobservable.
+//
+// Pure parse + DI exec/platform seams for unit tests.
+
+'use strict';
+
+// Parse a ps(1) TIME value into seconds. Accepted shapes:
+//   macOS:  MM:SS.cc        (e.g. "0:01.23")
+//   Linux:  [DD-]HH:MM:SS   (e.g. "00:00:05", "1-02:03:04")
+// Returns null for anything unparseable.
+function parsePsTimeSeconds(raw) {
+  const s = String(raw == null ? '' : raw).trim();
+  if (!s) return null;
+  const dayMatch = s.match(/^(\d+)-(.+)$/);
+  const days = dayMatch ? Number(dayMatch[1]) : 0;
+  const rest = dayMatch ? dayMatch[2] : s;
+  const parts = rest.split(':');
+  if (parts.length < 2 || parts.length > 3) return null;
+  if (parts.some((p) => !/^\d+(\.\d+)?$/.test(p))) return null;
+  const nums = parts.map(Number);
+  const seconds = parts.length === 3
+    ? nums[0] * 3600 + nums[1] * 60 + nums[2]
+    : nums[0] * 60 + nums[1];
+  return days * 86400 + seconds;
+}
+
+// Sample the cumulative CPU time (seconds) of `pid`, or null when unobservable
+// (no/invalid pid, win32, ps failure). Bounded: 500ms exec timeout.
+function sampleChildCpuSeconds(pid, opts = {}) {
+  const numericPid = Number(pid);
+  if (!Number.isInteger(numericPid) || numericPid <= 0) return null;
+  const platform = opts.platform || process.platform;
+  if (platform === 'win32') return null;
+  const execFileSync = opts.execFileSync || require('child_process').execFileSync;
+  try {
+    const out = execFileSync('ps', ['-o', 'time=', '-p', String(numericPid)], {
+      timeout: 500,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return parsePsTimeSeconds(String(out));
+  } catch (_err) {
+    return null;
+  }
+}
+
+module.exports = { parsePsTimeSeconds, sampleChildCpuSeconds };

package/src/submit-gate.js

@@ -379,6 +379,144 @@ async function awaitInputSettled(session, bodyText, opts = {}) {
   }
 }
 
+// #52: observe whether the injected body was ECHOED by the target TUI in frames
+// appended AFTER the inject (composer/transcript redraw) — consumption evidence that
+// gates the TASK_IDLE_UNCONFIRMED warning. Conservative by design (never-false-complete):
+//   - the normalized body must be ≥ minChars (short/common strings claim nothing);
+//   - matching samples fixed-length windows of the body (step minChars/2) so a echo
+//     wrapped across bordered composer lines is still observed, while requiring
+//     `needed` distinct window hits for long bodies;
+//   - only frames past the `sinceBytes` watermark count, and a window that ALSO appears
+//     in the pre-inject portion of the ring is discarded — a redraw of an identical
+//     earlier message is NOT fresh echo.
+// Pure: outputRing-only, DI stripAnsi — no I/O, no daemon coupling.
+function observeInjectEcho(session, bodyText, opts = {}) {
+  const minChars = Number.isFinite(opts.minChars) ? opts.minChars : 24;
+  const stripAnsi = typeof opts.stripAnsi === 'function' ? opts.stripAnsi : (s) => s;
+  const sinceBytes = Number.isFinite(opts.sinceBytes) ? opts.sinceBytes : null;
+
+  const body = normalize(bodyText);
+  if (body.length < minChars) {
+    return { observed: false, reason: body.length === 0 ? 'empty_body' : 'body_too_short' };
+  }
+  if (!session || !Array.isArray(session.outputRing) || session.outputRing.length === 0) {
+    return { observed: false, reason: 'no_ring' };
+  }
+
+  // Split the ring at the inject watermark: only post-inject frames may witness echo,
+  // and pre-inject frames veto windows that already existed on screen before the inject.
+  let preRaw = '';
+  let postRaw = '';
+  if (sinceBytes !== null && Number.isFinite(session.outputRingTotalBytes)) {
+    const appended = Math.max(0, session.outputRingTotalBytes - sinceBytes);
+    if (appended === 0) return { observed: false, reason: 'no_frames_since_inject' };
+    const all = session.outputRing.join('');
+    const splitAt = Math.max(0, all.length - appended);
+    preRaw = all.slice(0, splitAt);
+    postRaw = all.slice(splitAt);
+  } else {
+    // No watermark (legacy entry) — treat the whole ring as post-inject, with no veto.
+    postRaw = session.outputRing.join('');
+  }
+  const post = normalize(stripAnsi(postRaw));
+  const pre = normalize(stripAnsi(preRaw));
+
+  const step = Math.max(1, Math.floor(minChars / 2));
+  const windows = [];
+  for (let i = 0; i + minChars <= body.length; i += step) {
+    windows.push(body.slice(i, i + minChars));
+  }
+
+  const needed = body.length >= minChars * 2 ? 2 : 1;
+  let hits = 0;
+  for (const w of windows) {
+    if (post.indexOf(w) !== -1 && pre.indexOf(w) === -1) {
+      hits++;
+      if (hits >= needed) return { observed: true, reason: 'echo', windows_matched: hits };
+    }
+  }
+  return { observed: false, reason: 'no_echo', windows_matched: hits };
+}
+
+// #53: classify whether an injected+submitted body was CONSUMED as a new turn by the
+// recipient TUI, vs QUEUED in a busy composer, vs UNKNOWN. This is the DELIVERY-side dual
+// of #52 (which gates the IDLE signal on consumption evidence). A bare `Submitted via
+// pty_cr` only proves bytes reached the PTY master; a BUSY Claude Code TUI parks the CR'd
+// text in its composer ("Press up to edit queued messages") and never starts a turn, so the
+// sender must be able to tell `queued` from `consumed`.
+//
+// Hard boundary (#53): telepty cannot see inside the TUI's turn loop, so `consumed` is only
+// claimable from OBSERVABLE evidence, and never-false-consumed is conservative:
+//
+//   consumed — the recipient was NOT already busy at the CR and then began a FRESH turn:
+//              an idle→working/thinking transition whose since_ms ≥ submittedAtMs (a genuine
+//              new turn, NOT mere continued output from a turn already running — the leak
+//              that made `last_output_at ≥ submittedAtMs` read a busy queue as success).
+//   queued   — the injected body is still observably PARKED on screen after a short settle
+//              (windowed echo match — #52 technique — tolerates composer line-wrap/borders).
+//              A recipient already busy at the CR can only ever land here (fact 1: busy CR
+//              queues, never fires), never in `consumed`.
+//   unknown  — neither positive signal within the window (conservative default).
+//
+// Pure: DI getState + outputRing-only, DI now/sleep/stripAnsi — no I/O, no daemon coupling.
+async function classifyInjectConsumption(session, bodyText, opts = {}) {
+  const timeoutMs   = Number.isFinite(opts.timeoutMs)   ? opts.timeoutMs   : 1200;
+  const settleMs    = Number.isFinite(opts.settleMs)    ? opts.settleMs    : 250;
+  const intervalMs  = Number.isFinite(opts.intervalMs)  ? opts.intervalMs  : 80;
+  const minChars    = Number.isFinite(opts.minChars)    ? opts.minChars    : 24;
+  const stripAnsi   = typeof opts.stripAnsi === 'function' ? opts.stripAnsi : (s) => s;
+  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 sinceBytes  = Number.isFinite(opts.sinceBytes) ? opts.sinceBytes : null;
+
+  const body = normalize(bodyText);
+  if (body.length === 0)        return { status: 'unknown', reason: 'empty_body', waited_ms: 0 };
+  if (body.length < minChars)   return { status: 'unknown', reason: 'body_too_short', waited_ms: 0 };
+  if (!session || !Array.isArray(session.outputRing)) {
+    return { status: 'unknown', reason: 'no_ring', waited_ms: 0 };
+  }
+
+  // Was the recipient ALREADY busy when the CR was written? A busy claude-code TUI parks the
+  // CR'd text and never starts a turn (#53 fact 1), so we may observe `queued` there but must
+  // NEVER claim `consumed` — that is the hard boundary that produced the false success.
+  const initial = getState ? getState() : null;
+  const startedBusy = !!(initial && ACCEPTED_AFTER_SUBMIT_STATES.has(initial.state)
+    && Number.isFinite(initial.since_ms) && initial.since_ms < submittedAtMs);
+
+  const observeParked = () => observeInjectEcho(session, bodyText, { stripAnsi, sinceBytes, minChars });
+
+  const start = now();
+  while (true) {
+    // consumed — only from a non-busy start that produced a fresh idle→working/thinking turn.
+    if (!startedBusy && getState) {
+      const st = getState();
+      if (st && ACCEPTED_AFTER_SUBMIT_STATES.has(st.state)
+          && Number.isFinite(st.since_ms) && st.since_ms >= submittedAtMs) {
+        return { status: 'consumed', reason: `turn_started_${st.state}`, waited_ms: now() - start };
+      }
+    }
+
+    const elapsed = now() - start;
+    // Busy recipient cannot consume — short-circuit to `queued` as soon as the parked body
+    // settles, instead of waiting out the full window for a turn that will never come.
+    if (startedBusy && elapsed >= settleMs) {
+      const echo = observeParked();
+      if (echo.observed) return { status: 'queued', reason: 'busy_parked', waited_ms: elapsed };
+    }
+
+    if (elapsed >= timeoutMs) {
+      const echo = observeParked();
+      if (echo.observed) {
+        return { status: 'queued', reason: startedBusy ? 'busy_parked' : 'body_parked', waited_ms: elapsed };
+      }
+      return { status: 'unknown', reason: startedBusy ? 'busy_no_evidence' : 'no_turn', waited_ms: elapsed };
+    }
+    await sleep(intervalMs);
+  }
+}
+
 function isAcceptedSubmitState(state, submittedAtMs) {
   if (!state || !ACCEPTED_AFTER_SUBMIT_STATES.has(state.state)) return false;
   if (!Number.isFinite(submittedAtMs)) {
@@ -553,6 +691,8 @@ module.exports = {
   verifyBodyConsumed,
   confirmSubmitAccepted,
   observeBodyVisibility,
+  observeInjectEcho,
+  classifyInjectConsumption,
   awaitPromptSymbol,
   defaultReadScreen,
   isReady,

package/src/uninstall.js

@@ -0,0 +1,148 @@
+'use strict';
+
+// telepty#49 — uninstall hygiene. `npm rm -g` used to leave a live daemon (port
+// 3848 kept answering), a loaded launchd plist (launchd may resurrect a binary
+// that no longer exists), and 3 undocumented state directories behind.
+//
+// Two entry points share this module:
+//   - `telepty uninstall [--purge] [--dry-run]` (cli.js): full pass — stop
+//     daemons, unload+remove the launchd plists (macOS), and report the state
+//     dirs (kept by default; deleted only with --purge).
+//   - scripts/preuninstall.js (npm lifecycle): quiet partial pass — daemon stop
+//     + plist unload ONLY, never throws, so `npm rm` can never be broken by it.
+//
+// Every platform interaction (process cleanup, launchctl, fs) is injectable so
+// the logic is unit-testable without touching a live daemon or launchd.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// Daemon + broker service labels generated by install.js.
+const LAUNCHD_PLIST_NAMES = ['com.aigentry.telepty.plist', 'com.aigentry.telepty-broker.plist'];
+
+function stateDirPaths(homedir) {
+  return [
+    path.join(homedir, '.telepty'),
+    path.join(homedir, '.aigentry'),
+    path.join(homedir, '.config', 'aigentry-telepty')
+  ];
+}
+
+function launchdPlistPaths(homedir) {
+  return LAUNCHD_PLIST_NAMES.map((name) => path.join(homedir, 'Library', 'LaunchAgents', name));
+}
+
+// What an uninstall on this platform would touch. Pure (no I/O).
+function planUninstall(opts = {}) {
+  const platform = opts.platform || process.platform;
+  const homedir = opts.homedir || os.homedir();
+  return {
+    platform,
+    // launchd is macOS-only; on linux/windows the generated service (systemd
+    // unit / scheduled task) is reported as a manual step instead of guessed at.
+    plists: platform === 'darwin' ? launchdPlistPaths(homedir) : [],
+    stateDirs: stateDirPaths(homedir)
+  };
+}
+
+function runUninstall(opts = {}) {
+  const purge = Boolean(opts.purge);
+  const dryRun = Boolean(opts.dryRun);
+  const removePlists = opts.removePlists !== false;
+  const execFile = opts.execFileSync || execFileSync;
+  const fsx = opts.fs || fs;
+  // Late-require keeps module load free of side effects and the seam injectable.
+  const cleanup = opts.cleanupDaemonProcesses || require('../daemon-control').cleanupDaemonProcesses;
+  const plan = planUninstall(opts);
+
+  const result = {
+    dryRun,
+    purge,
+    platform: plan.platform,
+    stopped: [],
+    failed: [],
+    plists: [],
+    stateDirs: []
+  };
+
+  // (1) Stop running daemons via the full discovery chain (state file →
+  // process-title scan → port owner; daemon-control, telepty#15/#44).
+  if (!dryRun) {
+    try {
+      const stopResult = cleanup();
+      result.stopped = stopResult.stopped || [];
+      result.failed = stopResult.failed || [];
+    } catch {
+      // Best-effort: a failed scan must not block the rest of the uninstall.
+    }
+  }
+
+  // (2) launchd service (macOS): unload so launchd stops resurrecting the
+  // daemon, then remove the plist file (skipped for the preuninstall hook).
+  for (const plistPath of plan.plists) {
+    const entry = { path: plistPath, existed: false, unloaded: false, removed: false };
+    try {
+      entry.existed = fsx.existsSync(plistPath);
+    } catch {
+      entry.existed = false;
+    }
+    if (entry.existed && !dryRun) {
+      try {
+        execFile('launchctl', ['unload', plistPath], { stdio: ['ignore', 'ignore', 'ignore'] });
+        entry.unloaded = true;
+      } catch {
+        entry.unloaded = false; // already unloaded / not loaded — fine either way
+      }
+      if (removePlists) {
+        try {
+          fsx.rmSync(plistPath, { force: true });
+          entry.removed = true;
+        } catch {
+          entry.removed = false;
+        }
+      }
+    }
+    result.plists.push(entry);
+  }
+
+  // (3) State directories: user data stays by default — callers print the
+  // paths so the leftover is documented, not silent. Deleted only with --purge.
+  for (const dirPath of plan.stateDirs) {
+    const entry = { path: dirPath, exists: false, purged: false };
+    try {
+      entry.exists = fsx.existsSync(dirPath);
+    } catch {
+      entry.exists = false;
+    }
+    if (purge && entry.exists && !dryRun) {
+      try {
+        fsx.rmSync(dirPath, { recursive: true, force: true });
+        entry.purged = true;
+      } catch {
+        entry.purged = false;
+      }
+    }
+    result.stateDirs.push(entry);
+  }
+
+  return result;
+}
+
+// npm preuninstall lifecycle pass: daemon stop + plist unload only, quietly.
+// Never throws — breaking `npm rm` is strictly worse than leaving a daemon.
+function runPreuninstall(opts = {}) {
+  try {
+    return runUninstall({ ...opts, purge: false, dryRun: false, removePlists: false });
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  LAUNCHD_PLIST_NAMES,
+  planUninstall,
+  runPreuninstall,
+  runUninstall
+};