@dmsdc-ai/aigentry-telepty 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -2,7 +2,68 @@
 
 All notable changes to `@dmsdc-ai/aigentry-telepty` are documented here.
 
-## [Unreleased]
+## [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
+
+### Fixed — TASK_IDLE_UNCONFIRMED false positives (#48)
+
+- **`TASK_IDLE_UNCONFIRMED` fired ~0–0.5s after nearly every inject** even when the inject was
+  processed, destroying the signal's value. Two proven causes: (a) the bridge re-sends `ready` on
+  every TUI prompt-glyph redraw after an inject, and "working" evidence was only recorded on a
+  transition *into* working — so an inject landing on an already-working session left zero evidence
+  and the notifier fired on the first weak snapshot; (b) codex's spinner-less TUI (5s silence +
+  `›` prompt glyph) flips the real-idle classifier mid-work.
+- **Fix: settle-and-recheck.** A would-be `TASK_IDLE_UNCONFIRMED` is held for
+  `TELEPTY_IDLE_UNCONFIRMED_SETTLE_SECONDS` (default 5) and re-checked against the **live** session
+  state: working/thinking → suppressed; output advanced while idle-classified → bounded re-settle
+  (`TELEPTY_IDLE_UNCONFIRMED_SETTLE_MAX_REARMS`, default 3); still idle and stalled → notify, so the
+  genuine "inject not consumed" signal is preserved. The report label is pinned at arm time, so the
+  settle window can never promote a stale idle snapshot to `TASK_COMPLETE` (the never-false-complete
+  invariant is kept). Message format is unchanged.
 
 ## [0.6.1] - 2026-06-09
 

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')) {
@@ -2520,8 +2699,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 +2751,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 +3988,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 +4023,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
@@ -286,6 +305,21 @@ const AUTO_REPORT_IDLE_SECONDS = Number(process.env.TELEPTY_AUTO_REPORT_IDLE_SEC
 // by the recipient. Below this elapsed floor the idle is NOT trusted as a processed-inject
 // completion; the text-inject is relabeled so a stuck/hung target is never reported as DONE.
 const AUTO_REPORT_MIN_REAL_SECONDS = Number(process.env.TELEPTY_AUTO_REPORT_MIN_REAL_SECONDS) || 1.0;
+// #48: a momentary idle/ready snapshot right after an inject (the bridge re-sends 'ready' on a
+// TUI prompt-glyph redraw; codex's silence+glyph flips real-idle mid-work) is almost always a
+// transition-gap false positive — the session is, or moments later is, working. Before emitting
+// TASK_IDLE_UNCONFIRMED, hold for this settle window and recheck the LIVE session state.
+const IDLE_UNCONFIRMED_SETTLE_SECONDS = Number(process.env.TELEPTY_IDLE_UNCONFIRMED_SETTLE_SECONDS) || 5;
+// 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 && (
@@ -295,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;
@@ -358,6 +417,14 @@ function fireAutoReport(targetId, targetSession, pendingReport, trigger, deps =
   const _sessions = deps.sessions || sessions;
   const _pendingReports = deps.pendingReports || pendingReports;
   const _deliver = deps.deliverInjectionToSession || deliverInjectionToSession;
+  // #48: live auto-state lookup for the settle recheck (DI for unit tests).
+  const _getAutoState = deps.getAutoState || ((sid) => {
+    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);
@@ -390,25 +457,6 @@ function fireAutoReport(targetId, targetSession, pendingReport, trigger, deps =
     }
   }
 
-  pendingReport.idleNotified = true;
-  pendingReport.idleAt = new Date(_now()).toISOString();
-
-  // Richer bus event (observability) — now also carries the trigger provenance.
-  _broadcast('TASK_IDLE_NO_REPORT', targetId, targetSession, {
-    extra: {
-      source: pendingReport.source,
-      inject_id: pendingReport.injectId,
-      elapsed_secs: Number(elapsed),
-      injected_at: pendingReport.injectedAt,
-      trigger
-    }
-  });
-  console.log(`[ENFORCE-REPORT] ${targetId} idle after ${elapsed}s (trigger=${trigger}) — awaiting REPORT from ${pendingReport.source}`);
-
-  const srcId = _resolveAlias(pendingReport.source) || pendingReport.source;
-  const srcSession = _sessions[srcId];
-  if (!srcSession) return;
-
   // #537 / Bug B: a never-started worker (transient submit failure → claude startup
   // busy→idle settle at ~4.5s) must NOT be reported TASK_COMPLETE. When a submit was
   // expected, the elapsed floor and startup-polluted sawWorkingAfterInject are NOT trusted
@@ -428,13 +476,110 @@ function fireAutoReport(targetId, targetSession, pendingReport, trigger, deps =
   const idleEvidenceUnreliable = trigger === 'real-idle'
     && pendingReport.submitExpected
     && deps.idleEvidenceReliable === false;
-  const confirmed = trigger === 'ready-signal' && pendingReport.submitExpected
+  // #48: a settled recheck re-enters ONLY to emit the UNCONFIRMED label — pinned at arm time,
+  // so elapsed growing past the floor during the settle window can never promote a stale idle
+  // snapshot to TASK_COMPLETE (never a false complete).
+  const confirmed = pendingReport.unconfirmedSettleDone
     ? false
-    : idleEvidenceUnreliable
+    : trigger === 'ready-signal' && pendingReport.submitExpected
       ? false
-      : pendingReport.submitExpected
-        ? strongSubmitConfirmed
-        : (elapsedNum >= AUTO_REPORT_MIN_REAL_SECONDS || hasSubmitEvidence);
+      : idleEvidenceUnreliable
+        ? false
+        : pendingReport.submitExpected
+          ? strongSubmitConfirmed
+          : (elapsedNum >= AUTO_REPORT_MIN_REAL_SECONDS || hasSubmitEvidence);
+
+  // #48: settle-and-recheck before any UNCONFIRMED notification. The first weak idle/ready
+  // snapshot right after an inject is almost always a transition gap — the bridge re-sends
+  // 'ready' on a TUI prompt-glyph redraw (with no state transition, no evidence flag is ever
+  // set even though the session IS working), and codex's silence+glyph heuristic flips
+  // real-idle mid-work. Hold the notification for a settle window and recheck the LIVE
+  // session: notify only when it is still not working AND its output has not advanced.
+  // Suppression does NOT consume the once-only idleNotified guard, so a later genuine
+  // busy→idle transition re-enters this path (and an evidence-backed one reports COMPLETE).
+  if (!confirmed && !pendingReport.unconfirmedSettleDone) {
+    if (pendingReport.unconfirmedSettleTimer) return; // settle window already open
+    const settleMs = Math.max(50, Math.round(IDLE_UNCONFIRMED_SETTLE_SECONDS * 1000));
+    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);
+        // REPORT arrived / entry replaced / another path already notified — stand down.
+        if (currentPending !== pendingReport || currentPending.idleNotified) return;
+        const liveSession = _sessions[targetId] || targetSession;
+        const autoState = _getAutoState(targetId);
+        if (autoState === 'working' || autoState === 'thinking') {
+          console.log(`[AUTO-REPORT] ${targetId} idle-unconfirmed suppressed after settle — session is ${autoState} (trigger=${trigger})`);
+          return;
+        }
+        const activityNow = liveSession ? liveSession.lastActivityAt : null;
+        if (activityNow !== activityAtArm
+            && (pendingReport.unconfirmedSettleRearms || 0) < IDLE_UNCONFIRMED_SETTLE_MAX_REARMS) {
+          pendingReport.unconfirmedSettleRearms = (pendingReport.unconfirmedSettleRearms || 0) + 1;
+          console.log(`[AUTO-REPORT] ${targetId} output advanced during settle — re-settling (${pendingReport.unconfirmedSettleRearms}/${IDLE_UNCONFIRMED_SETTLE_MAX_REARMS})`);
+          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);
+    };
+    armSettle();
+    console.log(`[AUTO-REPORT] ${targetId} idle unconfirmed at ${elapsed}s (trigger=${trigger}) — settling ${IDLE_UNCONFIRMED_SETTLE_SECONDS}s before notify`);
+    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();
+
+  // Richer bus event (observability) — now also carries the trigger provenance.
+  _broadcast('TASK_IDLE_NO_REPORT', targetId, targetSession, {
+    extra: {
+      source: pendingReport.source,
+      inject_id: pendingReport.injectId,
+      elapsed_secs: Number(elapsed),
+      injected_at: pendingReport.injectedAt,
+      trigger
+    }
+  });
+  console.log(`[ENFORCE-REPORT] ${targetId} idle after ${elapsed}s (trigger=${trigger}) — awaiting REPORT from ${pendingReport.source}`);
+
+  const srcId = _resolveAlias(pendingReport.source) || pendingReport.source;
+  const srcSession = _sessions[srcId];
+  if (!srcSession) return;
+
   const injTag = pendingReport.injectId ? ` inject=${pendingReport.injectId}` : '';
   const reportMsg = confirmed
     ? `TASK_COMPLETE: ${targetId} is now idle after processing inject (${elapsed}s, via ${trigger}${injTag})`
@@ -1552,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);
@@ -2943,6 +3091,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
       };
@@ -3701,6 +3851,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 {
@@ -3708,6 +3859,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.
@@ -4090,4 +4242,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.1",
+  "version": "0.6.3",
   "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/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/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/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/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/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/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"
   },

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,65 @@ 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 };
+}
+
 function isAcceptedSubmitState(state, submittedAtMs) {
   if (!state || !ACCEPTED_AFTER_SUBMIT_STATES.has(state.state)) return false;
   if (!Number.isFinite(submittedAtMs)) {
@@ -553,6 +612,7 @@ module.exports = {
   verifyBodyConsumed,
   confirmSubmitAccepted,
   observeBodyVisibility,
+  observeInjectEcho,
   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
+};