@agfpd/iapeer 0.4.26 → 0.4.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.26",
+  "version": "0.4.28",
   "description": "Run Claude Code and Codex CLI as local background agents that message each other, wake on demand, and share one memory.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/launch/adapters/claude.ts

@@ -24,6 +24,7 @@ import { homedir } from 'os'
 import { join } from 'path'
 import { readdirSync, realpathSync, statSync } from 'fs'
 import type { ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
+import { lastTimestampedEntryMs } from './transcriptTail.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Boot dialog + ready markers (lifecycle claudeBootDialog / claudeInputReady)
@@ -239,6 +240,38 @@ export const claudeAdapter: RuntimeAdapter = {
     return null
   },
 
+  /**
+   * MID-SESSION nag/upsell auto-dismiss (livability — distinct from bootDialogKeys,
+   * which the supervisor drives only until ready). claude pops a ONE-TIME interactive
+   * upsell modal AFTER the session is live that BLOCKS a headless peer (no human to
+   * answer):
+   *
+   *     Try the new fullscreen renderer?
+   *     · Flicker-free output …
+   *     ❯ 1. Yes, try it
+   *       2. Not now
+   *     Enter to confirm · Esc to cancel
+   *
+   * The default cursor sits on "1. Yes, try it", so a BARE Enter would ENABLE the
+   * fullscreen renderer — which switches claude to the alt-screen TUI and changes the
+   * surface the pane-log model + composer-occupancy + ready-gate all read off. We must
+   * DECLINE: type the literal '2' then Enter ('2','Enter' → "2\r"; '2' is not a named/
+   * cursor key, so it is emitted verbatim without a `-l` literal switch — and `-l`
+   * would wrongly make the following 'Enter' literal too). VERIFIED-SAFE on the live
+   * fleet: '2'+Enter cleared the modal on boris and doc and returned them to the
+   * composer; an arrow-step+Enter MIS-FIRED into "tui":"fullscreen" on scriber, and Esc/
+   * 'n' are unverified — so this is the ONLY accepted sequence. Match the FULL signature
+   * (title AND the "2. Not now" decline row) so a transcript merely DISCUSSING the
+   * fullscreen renderer can never trigger a stray keystroke. Future one-time CC upsells
+   * of this class extend the match here (each with its own verified-safe decline key).
+   */
+  nagDismissKeys(pane: string): string[] | null {
+    if (pane.includes('Try the new fullscreen renderer?') && pane.includes('2. Not now')) {
+      return ['2', 'Enter']
+    }
+    return null
+  },
+
   /**
    * Ready for the first message iff the input surface is rendered AND no startup
    * dialog is still up (lifecycle.claudeInputReady, index.ts:272-279;
@@ -280,6 +313,33 @@ export const claudeAdapter: RuntimeAdapter = {
     return newest > 0 ? newest : null
   },
 
+  /**
+   * IDLE-accounting signal: the content-timestamp of the last meaningful entry in the ACTIVE transcript
+   * (newest .jsonl by file mtime), read from its tail. Immune to the file re-save (file-mtime is fresh
+   * but the last ENTRY is not) and to the statusline pane-log tick (the transcript is untouched by a
+   * status redraw). null when the dir is absent/empty or no timestamped entry sits in the tail.
+   */
+  lastTurnMtime(cwd: string): number | null {
+    let entries: string[]
+    try {
+      entries = readdirSync(transcriptDir(cwd))
+    } catch {
+      return null
+    }
+    let best = { path: '', mt: 0 }
+    for (const name of entries) {
+      if (!name.endsWith('.jsonl')) continue
+      try {
+        const path = join(transcriptDir(cwd), name)
+        const mt = statSync(path).mtimeMs
+        if (mt > best.mt) best = { path, mt }
+      } catch {
+        /* race */
+      }
+    }
+    return best.path ? lastTimestampedEntryMs(best.path) : null
+  },
+
   /**
    * Resume preflight (fail-loud — never a silent fresh fallback): resolve the
    * newest transcript uuid for cwd via the claude-slug dir scan (lifecycle.

package/src/launch/adapters/codex.ts

@@ -38,6 +38,7 @@
 import { homedir } from 'os'
 import { join } from 'path'
 import { readFileSync, readdirSync, realpathSync, statSync } from 'fs'
+import { lastTimestampedEntryMs } from './transcriptTail.ts'
 import type { ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -114,9 +115,16 @@ function canonicalPath(p: string): string {
  * (the model produced its first turn); idle accounting reads the same proxy.
  */
 function newestCodexSessionMtime(cwd: string): number | null {
+  return newestCodexSession(cwd)?.mt ?? null
+}
+
+/** The newest ~/.codex/sessions/**\/*.jsonl whose recorded session cwd realpath-matches `cwd`, as
+ *  {path, mt}, or null when none. Shared by newestActivityMtime (file-mtime) and lastTurnMtime (needs
+ *  the PATH to read the tail). Codex nests its session logs in a date tree, so the scan recurses. */
+function newestCodexSession(cwd: string): { path: string; mt: number } | null {
   const root = join(homedir(), '.codex', 'sessions')
   const target = canonicalPath(cwd)
-  let newest = 0
+  let best = { path: '', mt: 0 }
   function visit(dir: string): void {
     let entries
     try {
@@ -134,14 +142,14 @@ function newestCodexSessionMtime(cwd: string): number | null {
       if (canonicalPath(codexSessionCwd(path) ?? '') !== target) continue
       try {
         const mt = statSync(path).mtimeMs
-        if (mt > newest) newest = mt
+        if (mt > best.mt) best = { path, mt }
       } catch {
         /* race — entry vanished between readdir and stat */
       }
     }
   }
   visit(root)
-  return newest > 0 ? newest : null
+  return best.path ? best : null
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -259,6 +267,17 @@ export const codexAdapter: RuntimeAdapter = {
     return newestCodexSessionMtime(cwd)
   },
 
+  /**
+   * IDLE-accounting signal: the content-timestamp of the last meaningful entry in the active codex
+   * session jsonl (newest cwd-matching file), read from its tail. codex entries (event_msg /
+   * response_item) carry a top-level `timestamp`, so this reflects real turn activity — immune to a
+   * file re-save and to a statusline pane-log tick. null when no cwd-matching session / no timestamp.
+   */
+  lastTurnMtime(cwd: string): number | null {
+    const s = newestCodexSession(cwd)
+    return s ? lastTimestampedEntryMs(s.path) : null
+  },
+
   /**
    * Resume preflight (fail-loud — never a silent fresh fallback). Codex resumes
    * via 'resume --last' with NO ref: it matches the newest session for cwd

package/src/launch/adapters/notifier.ts

@@ -68,6 +68,10 @@ export const notifierAdapter: RuntimeAdapter = {
     return null
   },
 
+  lastTurnMtime(_cwd: string): number | null {
+    return null // router — no transcript
+  },
+
   /** Nothing to resume: a router does not replay a transcript. */
   resolveResume(_cwd: string): { ok: boolean; ref?: string; reason?: string } {
     return { ok: true }

package/src/launch/adapters/telegram.ts

@@ -98,6 +98,10 @@ export const telegramAdapter: RuntimeAdapter = {
     return null
   },
 
+  lastTurnMtime(_cwd: string): number | null {
+    return null // router — no transcript
+  },
+
   /**
    * Nothing to resume: a router does not replay a transcript, so resume cannot
    * fail-loud the way claude/codex do — there is no prior session ref to resolve

package/src/launch/adapters/transcriptTail.ts

@@ -0,0 +1,64 @@
+// Shared transcript-tail reader for the idle-accounting signal.
+//
+// The RELIABLE "last real turn" time is the content-timestamp of the LAST meaningful transcript entry —
+// NOT the file mtime (a live claude session RE-SAVES its .jsonl without a new entry, so file-mtime is
+// falsely fresh at idle) and NOT the pane-log mtime (a statusline / footer re-render writes pty bytes at
+// idle, so the pane-log is falsely fresh too). The transcript ENTRY stream only advances on actual turn
+// activity (user/assistant/tool/turn_duration for claude; event_msg/response_item for codex), so the
+// last entry that carries a `timestamp` is the true idle signal — immune to both noise sources.
+
+import { openSync, readSync, closeSync, statSync } from 'fs'
+
+/**
+ * Content-timestamp (epoch ms) of the LAST jsonl entry carrying a `timestamp` field, read from the
+ * file's TAIL (cheap — only the last `tailBytes` are read). Metadata records without a `timestamp`
+ * (claude `mode` / `ai-title` / `bridge-session`) are skipped. Returns null when the file is
+ * unreadable or no timestamped entry sits in the tail (the caller then floors at wokeAt). A partial
+ * FIRST line in the tail buffer is harmless: we scan from the END and return on the first complete
+ * timestamped entry, so a truncated leading line is only ever reached (and skipped) when nothing
+ * matched.
+ */
+export function lastTimestampedEntryMs(path: string, tailBytes = 65536): number | null {
+  let fd: number
+  try {
+    fd = openSync(path, 'r')
+  } catch {
+    return null
+  }
+  try {
+    const size = statSync(path).size
+    const start = Math.max(0, size - tailBytes)
+    const len = size - start
+    if (len <= 0) return null
+    const buf = Buffer.allocUnsafe(len)
+    let read = 0
+    while (read < len) {
+      const n = readSync(fd, buf, read, len - read, start + read)
+      if (n <= 0) break
+      read += n
+    }
+    const lines = buf.subarray(0, read).toString('utf8').split(/\r?\n/)
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i].trim()
+      if (!line) continue
+      let obj: unknown
+      try {
+        obj = JSON.parse(line)
+      } catch {
+        continue // partial leading line / non-json → skip
+      }
+      const ts = (obj as { timestamp?: unknown })?.timestamp
+      if (typeof ts === 'string') {
+        const ms = Date.parse(ts)
+        if (!Number.isNaN(ms)) return ms
+      } else if (typeof ts === 'number' && Number.isFinite(ts)) {
+        return ts
+      }
+    }
+    return null
+  } catch {
+    return null
+  } finally {
+    closeSync(fd)
+  }
+}

package/src/launch/adapters/voicetalk.ts

@@ -81,6 +81,10 @@ export const voicetalkAdapter: RuntimeAdapter = {
     return null
   },
 
+  lastTurnMtime(_cwd: string): number | null {
+    return null // router — no transcript
+  },
+
   /** Nothing to resume: a router does not replay a transcript, so resume cannot
    *  fail-loud the way claude/codex do. Always {ok:true}. */
   resolveResume(_cwd: string): { ok: boolean; ref?: string; reason?: string } {

package/src/launch/types.ts

@@ -259,14 +259,35 @@ export interface RuntimeAdapter {
    */
   bootDialogKeys(pane: string): string[] | null
 
+  /**
+   * MID-SESSION nag/upsell auto-dismiss (livability). Distinct from bootDialogKeys:
+   * the boot-driver stops at ready, but claude/codex can pop a ONE-TIME interactive
+   * upsell modal AFTER the session is live (e.g. "Try the new fullscreen renderer?")
+   * that BLOCKS the pty waiting for a keypress no headless peer answers — it froze the
+   * live fleet until a human cleared it. A persistent supervisor watcher (daemon.ts)
+   * runs THIS off the authoritative model for the whole session and writes the keys.
+   * Return the send-keys args that dismiss with the VERIFIED-SAFE default (decline),
+   * else null. Match the FULL modal signature so ordinary content mentioning the
+   * feature can never trigger a stray keystroke into the composer. Optional — a runtime
+   * with no known mid-session nags (codex/router) omits it. tui only.
+   */
+  nagDismissKeys?(pane: string): string[] | null
+
   /** Is the input surface ready for the first message? (tui: ready marker present
    *  AND startup dialogs gone). Router runtimes return true (no input surface). */
   isInputReady(pane: string): boolean
 
-  /** Newest activity-proxy mtime for the ready-gate AND idle accounting:
-   *  claude transcript / codex session jsonl mtime; null for a router (no proxy). */
+  /** Newest activity-proxy FILE mtime — used by the READY-GATE (it waits for ANY transcript write past
+   *  baseline = "the model produced its first turn"). NOT for idle accounting: a live session re-saves
+   *  this file without a new entry, so it is falsely fresh at idle. null for a router (no proxy). */
   newestActivityMtime(cwd: string): number | null
 
+  /** Content-timestamp (epoch ms) of the LAST meaningful transcript ENTRY — the reliable IDLE-accounting
+   *  signal. Unlike newestActivityMtime (file mtime, re-touched at idle) and the pane-log mtime (a
+   *  statusline re-render ticks it at idle), the entry stream only advances on real turn activity.
+   *  superviseTick uses THIS for idle/quiet age. null for a router (no transcript). */
+  lastTurnMtime(cwd: string): number | null
+
   /** Resume preflight — validate a resume request fail-loud (never silent fresh).
    *  Returns the resolved ref (claude uuid) or ok:false with a reason. */
   resolveResume(cwd: string): { ok: boolean; ref?: string; reason?: string }

package/src/lifecycle/index.ts

@@ -344,21 +344,6 @@ export function clearEphemeralArmed(cfg: LifecycleConfig, identity: string): voi
   }
 }
 
-/** mtime (ms) of a hosted session's pane-log (`<logDir>/<identity>.log`) — the RAW TUI
- *  render byte-stream the supervisor appends for the session's whole life. It advances
- *  ~1s while the TUI is rendering a turn (the "esc to interrupt" elapsed counter ticks
- *  during BOTH model generation AND a tool run) and goes quiet at the prompt. So it is
- *  the truest active-turn liveness signal — the SAME mtime telegram-runtime reads for its
- *  typing/activity indicator — and unlike the transcript proxy it does NOT go quiet during
- *  a long model generation (no JSONL write until the message completes). null if absent. */
-function paneLogMtimeMs(cfg: LifecycleConfig, identity: string): number | null {
-  try {
-    return statSync(join(cfg.logDir, `${identity}.log`)).mtimeMs
-  } catch {
-    return null
-  }
-}
-
 function deathsPath(cfg: LifecycleConfig, identity: string): string {
   return join(cfg.stateDir, `${identity}.deaths`)
 }
@@ -1157,15 +1142,14 @@ export interface SuperviseOutcome {
 export interface SuperviseDeps {
   env?: NodeJS.ProcessEnv
   nowMs?: number
-  /** Activity proxy seam (default: the runtime adapter's transcript/session mtime). Tests inject a
-   *  controlled value to exercise the idle-age floor without a real transcript on disk. */
-  newestActivityMtime?: (runtime: string, cwd: string) => number | null
-  /** Liveness seam (default: the real `sessionAlive` = pty-host OR tmux-fallback). Tests inject a
-   *  fixed verdict so the idle path is exercised hermetically — no live tmux/pty session needed. */
+  /** IDLE-proxy seam (default: the runtime adapter's `lastTurnMtime` = content-ts of the last meaningful
+   *  transcript entry). This is the RELIABLE idle signal — NOT the transcript FILE mtime (re-saved at
+   *  idle) and NOT the pane-log mtime (a statusline re-render ticks it at idle); both falsely keep an
+   *  idle session young. Tests inject a controlled value to exercise the idle/quiet age hermetically. */
+  lastTurnMtime?: (runtime: string, cwd: string) => number | null
+  /** Liveness seam (default: the real `sessionAlive` = pty-host pid-file check). Tests inject a fixed
+   *  verdict so the idle path is exercised hermetically — no live pty session needed. */
   sessionAlive?: (sock: string, identity: string) => boolean
-  /** Pane-log mtime seam (default: the real pane-log file mtime). Tests inject a controlled value to
-   *  exercise the ephemeral active-turn vs idle distinction without a real pane-log on disk. */
-  paneLogMtime?: (identity: string) => number | null
 }
 
 /** Resolved per-tick context threaded into superviseOnePeer (deps already defaulted by superviseTick). */
@@ -1173,9 +1157,8 @@ interface SuperviseCtx {
   cfg: LifecycleConfig
   env: NodeJS.ProcessEnv
   nowMs: number
-  activityMtime: (runtime: string, cwd: string) => number | null
+  lastTurnMt: (runtime: string, cwd: string) => number | null
   isAlive: (sock: string, identity: string) => boolean
-  paneLogMt: (identity: string) => number | null
   verbose: boolean
   trace: (fields: Record<string, string | number | undefined>) => void
 }
@@ -1188,7 +1171,7 @@ interface SuperviseCtx {
  * returns exactly one outcome; the trace side-effects mirror the prior inline behaviour.
  */
 function superviseOnePeer(s: SessionState, ctx: SuperviseCtx): SuperviseOutcome {
-  const { cfg, env, nowMs, activityMtime, isAlive, paneLogMt, verbose, trace } = ctx
+  const { cfg, env, nowMs, lastTurnMt, isAlive, verbose, trace } = ctx
   // H4 — FIRST, before any reap. A launchd-managed peer is read-only.
   if (isLaunchdManaged(s.personality, env)) {
     if (verbose) trace({ identity: s.identity, action: 'skipped-launchd', outcome: 'read-only-h4' })
@@ -1240,34 +1223,24 @@ function superviseOnePeer(s: SessionState, ctx: SuperviseCtx): SuperviseOutcome
     trace({ identity: s.identity, action: 'reaped-gone', death: gone.death, reason: gone.reason, outcome: 'fresh-next-msg' })
     return { identity: s.identity, action: 'reaped-gone', reason: gone.reason }
   }
-  // Idle accounting via the PANE-LOG (TUI render-stream) mtime — the RELIABLE idle
-  // signal: it advances ~1s while the TUI renders ANY turn (model generation OR a tool
-  // run — the "esc to interrupt" elapsed counter ticks) and goes quiet ONLY at the
-  // prompt. NOT the transcript file mtime: a live claude session RE-TOUCHES its session
-  // .jsonl ~every 30-45min WITHOUT a real turn (a system/bridge re-save), so the
-  // transcript proxy is perpetually < idleSecs and a claude peer NEVER idle-reaps — the
-  // fleet-reap incident: a warm claude pile, last real turn hours ago, never reaped;
-  // codex's session file is NOT re-touched, so codex reaps (the claude-vs-codex split).
-  // The transcript stays the launch ready-gate's signal (it needs "a real turn produced
-  // output"); only this idle proxy moves to the pane-log. FLOORED at wokeAt: a session
-  // cannot be idle longer than it has been awake (a wake that produced no turn →
-  // mt=wokeAt → reaped idleSecs after the wake, never out from under an attaching op).
+  // Idle accounting via the LAST MEANINGFUL TRANSCRIPT ENTRY's content-timestamp (adapter.lastTurnMtime)
+  // — the only RELIABLE idle signal. The two raw mtimes both report FALSE freshness for an idle session:
+  //   • pane-log mtime — a statusline / footer re-render writes pty bytes at idle (the clock/usage/ctx%
+  //     redraw + Claude Code's own update-check/token-counter), so the pane-log ticks at the prompt. The
+  //     0.4.16 invariant "the pane-log goes quiet ONLY at the prompt" was broken by the statusline.
+  //   • transcript FILE mtime — a live claude session RE-SAVES its .jsonl without appending a new entry,
+  //     so the file is fresh while the last real turn was hours ago (the 0.4.16 re-touch).
+  // Both made real peers live idle 3-5h UNREAPED (incident 23.06: perplex/mrwriter/doc). The transcript
+  // ENTRY stream only advances on actual turn activity, so the last timestamped entry is the true last
+  // turn. The launch ready-gate keeps newestActivityMtime (file-mtime advance = "a turn produced
+  // output"). FLOORED at wokeAt: a freshly-woken session that produced no turn yet (lastTurn from a PRIOR
+  // session is old) must not be reaped out from under an attaching op — max(lastTurn, wokeAt) reaps it
+  // idleSecs after the wake, never before. null lastTurn (unreadable / churned out of the tail) → wokeAt
+  // governs (an old wokeAt = woken-long-ago = idle → reaped; a recent wokeAt = just-woken → protected).
   const ephemeral = isEphemeralPeer(s.cwd)
-  const plMt = paneLogMt(s.identity)
-  let mt: number
-  if (plMt !== null) {
-    mt = Math.max(plMt, s.wokeAt)
-  } else {
-    // Pane-log MISSING (a legacy pre-pane-log supervisor) → fall back to the transcript
-    // proxy, NEVER to wokeAt-as-activity: a wokeAt-only age would read an ACTIVE legacy
-    // session's idle from its hours-old wokeAt and reap it MID-WORK. The transcript is
-    // false-fresh at idle (so an IDLE legacy peer lingers warm until its next respawn
-    // earns a pane-log — bounded, self-heals), but an ACTIVE legacy peer keeps a
-    // genuinely-fresh transcript and is correctly protected. Safe direction preserved.
-    let tx = 0
-    try { tx = activityMtime(s.runtime, s.cwd) ?? 0 } catch { /* no adapter → wokeAt */ }
-    mt = Math.max(tx, s.wokeAt)
-  }
+  let lt = 0
+  try { lt = lastTurnMt(s.runtime, s.cwd) ?? 0 } catch { /* unreadable → wokeAt floor */ }
+  const mt = Math.max(lt, s.wokeAt)
   const ageSecs = Math.floor((nowMs - mt) / 1000)
   // wake_policy:ephemeral M2 — die-after-reply: an ARMED ephemeral session (the
   // daemon routed its outbound reply) is reaped after a QUIET window, checked
@@ -1337,9 +1310,8 @@ function superviseOnePeer(s: SessionState, ctx: SuperviseCtx): SuperviseOutcome
 export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): SuperviseOutcome[] {
   const env = deps.env ?? process.env
   const nowMs = deps.nowMs ?? Date.now()
-  const activityMtime = deps.newestActivityMtime ?? ((rt: string, c: string) => getAdapter(rt as Runtime).newestActivityMtime(c))
+  const lastTurnMt = deps.lastTurnMtime ?? ((rt: string, c: string) => getAdapter(rt as Runtime).lastTurnMtime(c))
   const isAlive = deps.sessionAlive ?? sessionAlive
-  const paneLogMt = deps.paneLogMtime ?? ((identity: string) => paneLogMtimeMs(cfg, identity))
   const verbose = superviseLogVerbose(env)
   // Pane-log volume cap (launch/cmdlog.ts capPaneLogs): the per-identity pane-log
   // (<logDir>/<identity>.log) is the RAW TUI byte stream pipe-pane/the supervisor
@@ -1356,7 +1328,7 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
   const trace = (fields: Record<string, string | number | undefined>): void =>
     appendLifecycleEvent(cfg.eventLogDir, { ev: 'supervise', ...fields }, { env, nowMs })
   const out: SuperviseOutcome[] = []
-  const ctx: SuperviseCtx = { cfg, env, nowMs, activityMtime, isAlive, paneLogMt, verbose, trace }
+  const ctx: SuperviseCtx = { cfg, env, nowMs, lastTurnMt, isAlive, verbose, trace }
   for (const s of readSessionStates(cfg)) {
     // Per-peer ISOLATION: a throw while evaluating ONE peer must NOT abort the whole sweep — that is
     // the silent fleet-wide reap-outage class (one malformed peer-state and NO peer gets reaped, the

package/src/supervisor/boot.ts

@@ -32,3 +32,25 @@ export function nextBootAction(adapter: BootPredicates, viewport: string, enc: K
   if (adapter.isInputReady(viewport)) return { kind: 'ready' }
   return { kind: 'wait' }
 }
+
+/** The slice of a RuntimeAdapter the MID-SESSION nag-watcher consumes — the optional
+ *  nagDismissKeys (claudeAdapter satisfies it; codex/router omit it → no nags). */
+export interface NagPredicate {
+  nagDismissKeys?(pane: string): string[] | null
+}
+
+export type NagAction = { kind: 'dismiss'; keys: string[]; bytes: Buffer } | { kind: 'none' }
+
+/**
+ * MID-SESSION nag/upsell step (livability) — the persistent sibling of nextBootAction. Unlike the
+ * boot-driver, which STOPS at ready, the daemon loops this for the WHOLE session: a one-time CC upsell
+ * modal (e.g. "Try the new fullscreen renderer?") can pop AFTER the session is live and BLOCK the pty on
+ * a keypress no headless peer answers. If the adapter recognizes the (FULL-signature) modal it returns
+ * the verified-safe DECLINE keys; the caller writes `action.bytes` to the pty (cooldown-guarded so a
+ * cleared modal is never double-answered). An adapter with no nagDismissKeys → always 'none'.
+ */
+export function nextNagAction(adapter: NagPredicate, viewport: string, enc: KeyEncoding = {}): NagAction {
+  const keys = adapter.nagDismissKeys?.(viewport)
+  if (keys && keys.length) return { kind: 'dismiss', keys, bytes: keysToBytes(keys, enc) }
+  return { kind: 'none' }
+}

package/src/supervisor/daemon.ts

@@ -25,7 +25,7 @@ import {
   stripQueries,
 } from './protocol.ts'
 import { attachedPath, geometryPath, pidPath, servePath, sockPath, writeGeometry } from './paths.ts'
-import { nextBootAction, type BootPredicates } from './boot.ts'
+import { nextBootAction, nextNagAction, type BootPredicates, type NagPredicate } from './boot.ts'
 import { modelToPlainText } from './render.ts'
 import { codexAdapter } from '../launch/adapters/codex.ts'
 import { claudeAdapter } from '../launch/adapters/claude.ts'
@@ -80,6 +80,12 @@ const BOOT_POLL_MS = 2000
 // Stop driving after this long even if readiness is never observed (a hung/unknown startup); the
 // driver is best-effort and never blocks the conduit, which keeps serving regardless.
 const BOOT_DRIVE_MS = 120_000
+// MID-SESSION nag-watcher cadence: same 2 s model poll as the boot-driver. After answering a nag, hold
+// this long before the next check so a just-dismissed modal (claude repaints it away within a frame) is
+// never re-answered — a stray keystroke would land in the now-visible composer. If the modal genuinely
+// survives the hold (our key did not take), the next tick re-fires, so retries stay bounded, not lost.
+const NAG_POLL_MS = 2000
+const NAG_COOLDOWN_MS = 4000
 
 // Bun-native PTY (Bun ≥1.3.5) is not yet in @types/bun — type the slice we use.
 interface PtyChild {
@@ -541,4 +547,38 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
     }, BOOT_POLL_MS)
     ;(driver as { unref?: () => void }).unref?.()
   }
+
+  // ── mid-session nag-watcher (livability) ────────────────────────────────────────
+  // The boot-driver above STOPS at ready. But claude/codex can pop a ONE-TIME upsell modal
+  // MID-SESSION (e.g. "Try the new fullscreen renderer?", which appears on the return-to-prompt
+  // boundary after a tool result) that BLOCKS the pty on a keypress no headless peer answers — it
+  // froze live fleet peers (boris, doc) until a human cleared it by hand. A PERSISTENT watcher answers
+  // the curated, verified-safe DECLINE for that class off the SAME authoritative @xterm model, for the
+  // WHOLE session lifetime, exactly like the boot-driver answers startup dialogs — model-read
+  // (modelToPlainText) + raw pty-byte-write (keysToBytes). Cooldown-guarded: after firing, hold
+  // NAG_COOLDOWN_MS so a just-dismissed modal is never double-answered (a stray keystroke would land in
+  // the now-visible composer). Only runs for a runtime whose adapter declares nagDismissKeys.
+  const nagAdapter = BOOT_ADAPTERS[runtime] as NagPredicate | undefined
+  if (nagAdapter?.nagDismissKeys) {
+    let nagFiredMs = 0
+    const nagWatch = setInterval(() => {
+      if (down) {
+        clearInterval(nagWatch)
+        return
+      }
+      if (Date.now() - nagFiredMs < NAG_COOLDOWN_MS) return // let a just-answered modal repaint away first
+      let action
+      try {
+        const enc = { appCursorKeys: xterm.modes.applicationCursorKeysMode }
+        action = nextNagAction(nagAdapter, modelToPlainText(xterm, cols, rows), enc)
+      } catch {
+        return // transient model read — retry next tick
+      }
+      if (action.kind === 'dismiss') {
+        child.terminal.write(action.bytes)
+        nagFiredMs = Date.now()
+      }
+    }, NAG_POLL_MS)
+    ;(nagWatch as { unref?: () => void }).unref?.()
+  }
 }