@agfpd/iapeer 0.4.133 → 0.4.135

package/src/launch/ptyHost.ts

@@ -10,11 +10,12 @@
 //   - the deliver client is a pure-protocol leaf (no @xterm);
 //   - sessionAlive comes from client.ts (no @xterm);
 //   - readiness reuses paneLogViewport, whose @xterm import is dynamic and only loads flag-on.
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
 import { deliverToHost, sendControlToHost, type DeliverResult } from '../supervisor/deliver.ts'
 import { attachedPath, defaultRunDir, pidPath, readGeometry } from '../supervisor/paths.ts'
 import { sessionAlive as hostDaemonAlive } from '../supervisor/client.ts'
-import { killSession as killSupervisorSession, listSessions as listSupervisorSessions } from '../supervisor/index.ts'
+import { killSession as killSupervisorSession, listSessions as listSupervisorSessions, type TerminationContext } from '../supervisor/index.ts'
 import { parseSessionName } from '../core/socket.ts'
 import type { TmuxRuntime } from '../core/constants.ts'
 import { paneLogViewport } from './readyGateModel.ts'
@@ -45,10 +46,83 @@ export function hostSessionAlive(identity: string, env: NodeJS.ProcessEnv = proc
   return hostDaemonAlive(hostRunDir(env), identity)
 }
 
+// ─── Runtime READINESS (incident 18.10) ──────────────────────────────────────
+// «Alive» (the supervisor daemon's pid) is not «the runtime is up». A codex process hung before main
+// (dyld, after a cask update) lived under a healthy supervisor for 35 min: `list` showed ●, a send
+// went «live» and was confirmed ok (the cooked tty echoed the paste into the pane-log), and the ledger
+// held the message as in-progress. The invariant: a session that never reached its runtime's ready
+// surface is NOT live for delivery/list. Operator controls still address the hung process.
+// The launch writes this marker (the hosting token) the moment its ready-gate passes; a marker from
+// another hosting (a replaced session) does not count.
+
+function readyPath(identity: string, env: NodeJS.ProcessEnv): string {
+  return join(hostRunDir(env), `${identity}.ready`)
+}
+
+/** Record that THIS hosting of the identity reached its runtime's ready surface. */
+export function markHostReady(identity: string, env: NodeJS.ProcessEnv = process.env, token = hostSessionToken(identity, env)): void {
+  if (!token || token !== hostSessionToken(identity, env)) throw new Error(`hosting changed before ready: ${identity}`)
+  writeFileSync(readyPath(identity, env), `${token}\n`, { mode: 0o600 })
+}
+
+export function clearHostReady(identity: string, env: NodeJS.ProcessEnv = process.env): void {
+  rmSync(readyPath(identity, env), { force: true })
+}
+
+/** When this hosting started (its supervisor pid-file mtime), or null. */
+export function hostStartedMs(identity: string, env: NodeJS.ProcessEnv = process.env, runDir = hostRunDir(env)): number | null {
+  try {
+    return statSync(pidPath(runDir, identity)).mtimeMs
+  } catch {
+    return null
+  }
+}
+
+/** Alive AND this very hosting reached ready. */
+export function hostSessionReady(identity: string, env: NodeJS.ProcessEnv = process.env, runDir = hostRunDir(env)): boolean {
+  if (!hostDaemonAlive(runDir, identity)) return false
+  const token = hostSessionToken(identity, env, runDir)
+  try {
+    return !!token && readFileSync(join(runDir, `${identity}.ready`), 'utf8').trim() === token
+  } catch {
+    return false
+  }
+}
+
+/**
+ * One-time compatibility for sessions that were already running when the readiness marker was
+ * introduced. Prove readiness in each current host, without trusting historical pane-log frames.
+ */
+export async function backfillHostReady(env: NodeJS.ProcessEnv = process.env): Promise<string[]> {
+  const out: string[] = []
+  for (const h of listHostedPeers(env)) {
+    const id = `${h.runtime}-${h.personality}`
+    if (existsSync(readyPath(id, env))) continue
+    const token = hostSessionToken(id, env)
+    // Migration must prove readiness too: blindly stamping legacy pids re-labels a dyld hang as live.
+    const { getAdapter } = await import('./index.ts')
+    const adapter = getAdapter(h.runtime)
+    if (h.runtime === 'opencode') {
+      const { opencodeControl } = await import('../opencode/control.ts')
+      const { opencodePaths } = await import('../opencode/config.ts')
+      const ping = await opencodeControl(join(opencodePaths(h.personality, { env }).dir, 'control.sock'), { op: 'ping' }, 1000)
+      if (!ping.ok) continue
+    } else if (adapter.kind !== 'router') {
+      const { captureHostViewport } = await import('../supervisor/capture.ts')
+      const view = await captureHostViewport(hostRunDir(env), id)
+      if (!view || !adapter.isInputReady(view, 'gated')) continue
+    }
+    markHostReady(id, env, token)
+    out.push(id)
+  }
+  return out
+}
+
 /** Reap a hosted session: SIGTERM the supervisor daemon (hard-kills its PTY-owned tree + cleans up).
  *  env sandboxes the run-dir: a test with an injected root must NEVER SIGTERM a real fleet peer. */
-export function killPtyHost(identity: string, env: NodeJS.ProcessEnv = process.env): void {
-  killSupervisorSession(hostRunDir(env), identity)
+export function killPtyHost(identity: string, env: NodeJS.ProcessEnv = process.env, context: TerminationContext = {}, runDir = hostRunDir(env)): void {
+  killSupervisorSession(runDir, identity, { ...context, sandbox: context.sandbox || env.IAPEER_TEST_SANDBOX === '1',
+    caller: context.caller ?? env.PEER_IDENTITY ?? (env.PEER_PERSONALITY ? `${env.PEER_RUNTIME ?? 'unknown'}-${env.PEER_PERSONALITY}` : undefined) })
 }
 
 /**
@@ -78,9 +152,9 @@ export function hostGeometry(identity: string, env: NodeJS.ProcessEnv = process.
  * session FAILS rather than landing in a fresh same-named session — the host equivalent of the tmux
  * `session_id:pane_id` token. null when no daemon pid is readable.
  */
-export function hostSessionToken(identity: string, env: NodeJS.ProcessEnv = process.env): string | null {
+export function hostSessionToken(identity: string, env: NodeJS.ProcessEnv = process.env, runDir = hostRunDir(env)): string | null {
   try {
-    const pid = readFileSync(pidPath(hostRunDir(env), identity), 'utf8').trim()
+    const pid = readFileSync(pidPath(runDir, identity), 'utf8').trim()
     return pid ? `host:${pid}` : null
   } catch {
     return null
@@ -93,9 +167,9 @@ export function hostSessionToken(identity: string, env: NodeJS.ProcessEnv = proc
  * scan (and the no-runtime delivery resolve) include hosted peers. Empty + cheap when flag-off (the
  * run-dir is empty).
  */
-export function listHostedPeers(env: NodeJS.ProcessEnv = process.env): Array<{ runtime: TmuxRuntime; personality: string }> {
+export function listHostedPeers(env: NodeJS.ProcessEnv = process.env, runDir = hostRunDir(env)): Array<{ runtime: TmuxRuntime; personality: string }> {
   const out: Array<{ runtime: TmuxRuntime; personality: string }> = []
-  for (const s of listSupervisorSessions(hostRunDir(env))) {
+  for (const s of listSupervisorSessions(runDir)) {
     if (!s.alive) continue
     const p = parseSessionName(s.session)
     if (p) out.push({ runtime: p.runtime, personality: p.personality })
@@ -206,3 +280,17 @@ export function deliverHosted(identity: string, message: string, env: NodeJS.Pro
 export function resubmitHosted(identity: string, env: NodeJS.ProcessEnv = process.env): Promise<DeliverResult> {
   return sendControlToHost(hostRunDir(env), identity, [Buffer.from('\r', 'utf8')])
 }
+
+/** Run backfillHostReady exactly once per host (sentinel in the run-dir). Every later hosting is a
+ *  launch that writes its own marker, so a repeat backfill could only mask a never-ready host. */
+export async function backfillHostReadyOnce(env: NodeJS.ProcessEnv = process.env): Promise<string[] | null> {
+  const sentinel = join(hostRunDir(env), 'ready-backfill.v1')
+  if (existsSync(sentinel)) return null
+  const stamped = await backfillHostReady(env)
+  try {
+    writeFileSync(sentinel, `${new Date().toISOString()} ${stamped.join(',')}\n`, { mode: 0o600 })
+  } catch {
+    /* best-effort */
+  }
+  return stamped
+}

package/src/lifecycle/index.ts

@@ -51,7 +51,8 @@ import {
   type LaunchSpec,
 } from '../launch/index.ts'
 import { composeSystemPrompt, gatherPromptInput } from '../launch/composeSystemPrompt.ts'
-import { hostSessionAlive, killPtyHost } from '../launch/ptyHost.ts'
+import { hostSessionAlive, hostSessionReady, hostStartedMs, killPtyHost, listHostedPeers } from '../launch/ptyHost.ts'
+import { sessionAlive as hostDaemonAlive } from '../supervisor/client.ts'
 import { appendLifecycleEvent, superviseLogVerbose } from './eventlog.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -59,6 +60,8 @@ import { appendLifecycleEvent, superviseLogVerbose } from './eventlog.ts'
 // ─────────────────────────────────────────────────────────────────────────────
 
 export interface LifecycleConfig {
+  /** Process-control namespace, bound when cfg is loaded; never re-resolve it from deps.env. */
+  supervisorRunDir?: string
   claudeBin: string
   codexBin: string
   /** OpenCode native binary (docs/20). Optional so hand-built test configs stay valid. */
@@ -110,6 +113,7 @@ export function loadLifecycleConfig(env: NodeJS.ProcessEnv = process.env): Lifec
     return Number.isFinite(n) && n > 0 ? n : dflt
   }
   return {
+    supervisorRunDir: join(root, STATE_DIR, 'supervisor'),
     claudeBin: env.IAPEER_CLAUDE_BIN ?? join(home, '.local', 'bin', 'claude'),
     codexBin: env.IAPEER_CODEX_BIN ?? 'codex',
     // The official installer's location is not on launchd's PATH; prefer it over a bare name.
@@ -1096,6 +1100,17 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
     }
     // Idempotent fast path inside the lock: a live session wins (a concurrent
     // wake already brought it up) — no second spawn.
+    // ALIVE but NOT READY while we hold the wake lock = no bring-up is in flight for it, yet it never
+    // reached its ready surface (a hung-before-main process, an abandoned bring-up). Not a session —
+    // replace it rather than report READY into a process that will never take input (18.10).
+    if (sessionAlive(sock, identity, env) && !hostSessionReady(identity, env)) {
+      killPtyHost(identity, env, { reason: 'wake-replace-never-ready' })
+      logWake({ identity, runtime, mode: 'replace', cause: 'alive-never-ready' })
+      // SIGTERM is asynchronous — wait (bounded) for the host to be gone, so the fast path below does
+      // not read the dying process as the live winner.
+      for (let i = 0; i < 25 && sessionAlive(sock, identity, env); i++) await new Promise(r => setTimeout(r, 200))
+      if (sessionAlive(sock, identity, env)) return { status: 'FAILED', woke: false, runtime, reason: 'never-ready host did not terminate; retry after recovery' }
+    }
     if (sessionAlive(sock, identity, env)) {
       writeSessionState(cfg, { identity, runtime, personality: args.personality, cwd, wokeAt: Date.now() })
       // taskDelivered:false — the winning concurrent wake delivered ITS OWN task as
@@ -1302,12 +1317,12 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
 // Reap — kill a session (used by idle-reap / supervise; H4-guarded by callers)
 // ─────────────────────────────────────────────────────────────────────────────
 
-export function killSession(_sock: string, identity: string, env: NodeJS.ProcessEnv = process.env): void {
+export function killSession(_sock: string, identity: string, env: NodeJS.ProcessEnv = process.env, reason = 'lifecycle-kill'): void {
   // pty-only: SIGTERM the supervisor daemon — its shutdown kills the PTY-owned tree and removes the
   // sock/pid/serve-spec/markers. Idempotent if the session is already gone. (`_sock` retained for
   // call-site compatibility; no tmux sockets exist.) env sandboxes the run-dir — a test with an
   // injected root must NEVER SIGTERM a real fleet peer's supervisor.
-  killPtyHost(identity, env)
+  killPtyHost(identity, env, { reason })
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1348,6 +1363,9 @@ export interface SuperviseDeps {
   /** 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
+  /** Readiness seam (default: launch's ready marker for THIS hosting; with only sessionAlive injected,
+   *  ready ≡ alive). */
+  sessionReady?: (identity: string) => boolean
   /** Reap seam (default: the real `killSession` = SIGTERM the supervisor daemon). Tests inject a no-op
    *  so exercising the reap path NEVER SIGTERMs a real process — the destructive-kill isolation guard. */
   killSession?: (sock: string, identity: string) => void
@@ -1361,7 +1379,9 @@ interface SuperviseCtx {
   lastTurnMt: (runtime: string, cwd: string, personality?: string) => number | null
   childActivityMt: (runtime: string, cwd: string) => number | null
   isAlive: (sock: string, identity: string) => boolean
-  kill: (sock: string, identity: string) => void
+  /** Has THIS hosting reached its runtime's ready surface (launch's ready marker)? */
+  isReady: (identity: string) => boolean
+  kill: (sock: string, identity: string, reason: string) => void
   verbose: boolean
   trace: (fields: Record<string, string | number | undefined>) => void
 }
@@ -1374,7 +1394,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, lastTurnMt, childActivityMt, isAlive, kill, verbose, trace } = ctx
+  const { cfg, env, nowMs, lastTurnMt, childActivityMt, isAlive, isReady, kill, verbose, trace } = ctx
   // H4 — FIRST, before any reap. A launchd-managed peer is read-only: never wake,
   // never kill, never sweep its PROCESS. Its stale `.session` however is the
   // DAEMON'S own supervisory record (written back when the peer was daemon-owned),
@@ -1448,13 +1468,27 @@ function superviseOnePeer(s: SessionState, ctx: SuperviseCtx): SuperviseOutcome
   // cleared above; no legitimate alive+stopped state exists. Park like the stop verb (.idle-reaped is
   // idempotent with it) — .stopped keeps the peer down until `start`, .idle-reaped makes it resume-clean.
   if (isStopped(cfg, s.identity)) {
-    kill(sock, s.identity)
+    kill(sock, s.identity, 'supervise-stop-enforced')
     setIdleReaped(cfg, s.identity)
     clearEphemeralArmed(cfg, s.identity)
     removeSessionState(cfg, s.identity)
     trace({ identity: s.identity, action: 'reaped-idle', reason: 'alive-but-stopped', outcome: 'operator-halt-enforced' })
     return { identity: s.identity, action: 'reaped-idle', reason: 'live session carried .stopped — operator halt enforced (stop-vs-wake race)' }
   }
+  // NEVER-READY (incident 18.10): a process that never reached its runtime's ready surface well past
+  // the boot + ready-gate deadlines is not a session — a codex hung before main lived 35 min under a
+  // healthy supervisor. Launch now tears such a host down itself; this is the backstop for a bring-up
+  // the launcher could not finish (daemon restarted mid-boot, a launcher crash). Reaped as a FAULT
+  // (recordDeath → the crash-loop guard bounds a boot that keeps hanging); its ledger entries then
+  // orphan and are redelivered to the next session.
+  const boundMs = (cfg.bootDeadlineSecs + cfg.readyGateSecs + 60) * 1000
+  if (!isReady(s.identity) && nowMs - s.wokeAt > boundMs) {
+    kill(sock, s.identity, 'supervise-never-ready')
+    recordDeath(cfg, s.identity, nowMs)
+    removeSessionState(cfg, s.identity)
+    trace({ identity: s.identity, action: 'reaped-gone', reason: 'never-ready', age: `${Math.floor((nowMs - s.wokeAt) / 1000)}s`, outcome: 'fresh-next-msg' })
+    return { identity: s.identity, action: 'reaped-gone', reason: 'alive but never reached its ready surface' }
+  }
   // 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%
@@ -1495,7 +1529,7 @@ function superviseOnePeer(s: SessionState, ctx: SuperviseCtx): SuperviseOutcome
   // Deliberate, policy-driven death: NO .idle-reaped (an ephemeral peer never resumes)
   // and NO recordDeath (the crash-loop ring counts faults, not policy reaps).
   if (ephemeral && hasEphemeralArmed(cfg, s.identity) && ageSecs > cfg.ephemeralQuietSecs) {
-    kill(sock, s.identity)
+    kill(sock, s.identity, 'supervise-ephemeral-done')
     clearEphemeralArmed(cfg, s.identity)
     removeSessionState(cfg, s.identity)
     trace({ identity: s.identity, action: 'reaped-ephemeral', age: `${ageSecs}s`, outcome: 'ephemeral-done' })
@@ -1521,7 +1555,7 @@ function superviseOnePeer(s: SessionState, ctx: SuperviseCtx): SuperviseOutcome
   // tool, no reply yet) keeps the pane-log fresh via the TUI render, so it is no longer
   // reaped mid-task — only a genuinely idle/wedged unarmed session crosses this bound.
   if (ephemeral && ageSecs > cfg.ephemeralUnarmedIdleSecs) {
-    kill(sock, s.identity)
+    kill(sock, s.identity, 'supervise-ephemeral-unarmed')
     clearEphemeralArmed(cfg, s.identity)
     removeSessionState(cfg, s.identity)
     trace({ identity: s.identity, action: 'reaped-ephemeral', age: `${ageSecs}s`, outcome: 'ephemeral-unarmed-bound' })
@@ -1550,7 +1584,7 @@ function superviseOnePeer(s: SessionState, ctx: SuperviseCtx): SuperviseOutcome
     // INITIATES. Its presence on the next wake = the session was parked cleanly =
     // RESUME-eligible (resolveWakeMode branch 3b). A crash/self-close (the dead
     // branch above) never writes it → that wakes FRESH (branch 3a).
-    kill(sock, s.identity)
+    kill(sock, s.identity, 'supervise-idle')
     setIdleReaped(cfg, s.identity)
     removeSessionState(cfg, s.identity)
     trace({ identity: s.identity, action: 'reaped-idle', age: `${ageSecs}s`, outcome: 'resume-eligible' })
@@ -1567,6 +1601,8 @@ const limitHoldTraced = new Set<string>()
 
 export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): SuperviseOutcome[] {
   const env = deps.env ?? process.env
+  // Legacy partial cfgs get a PRIVATE namespace, not the invoking host's fleet.
+  const runDir = cfg.supervisorRunDir ?? join(cfg.stateDir, 'supervisor')
   const nowMs = deps.nowMs ?? Date.now()
   const lastTurnMt =
     deps.lastTurnMtime ??
@@ -1574,8 +1610,12 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
   const childActivityMt =
     deps.childActivityMtime ?? ((rt: string, c: string) => getAdapter(rt as Runtime).childActivityMtime?.(c) ?? null)
   // Default seams bind the injected env so a sandboxed tick never reads/kills the real fleet.
-  const isAlive = deps.sessionAlive ?? ((sock: string, identity: string) => sessionAlive(sock, identity, env))
-  const kill = deps.killSession ?? ((sock: string, identity: string) => killSession(sock, identity, env))
+  const isAlive = deps.sessionAlive ?? ((_sock: string, identity: string) => hostDaemonAlive(runDir, identity))
+  // Readiness seam. A test that injects ONLY sessionAlive gets ready ≡ alive (its fixtures predate the
+  // marker); production reads launch's ready marker for this very hosting.
+  const isReady =
+    deps.sessionReady ?? (deps.sessionAlive ? (identity: string) => deps.sessionAlive!('', identity) : (identity: string) => hostSessionReady(identity, env, runDir))
+  const kill = deps.killSession ?? ((_sock: string, identity: string, reason: string) => killPtyHost(identity, env, { reason }, runDir))
   const verbose = superviseLogVerbose(env)
   // Pane-log volume ROTATION (launch/cmdlog.ts capPaneLogs): the per-identity pane-log
   // (<logDir>/<identity>.log) is the RAW TUI byte stream pipe-pane/the supervisor
@@ -1613,7 +1653,7 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
     })
   }
   const out: SuperviseOutcome[] = []
-  const ctx: SuperviseCtx = { cfg, env, nowMs, lastTurnMt, childActivityMt, isAlive, kill, verbose, trace }
+  const ctx: SuperviseCtx = { cfg, env, nowMs, lastTurnMt, childActivityMt, isAlive, isReady, kill, 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
@@ -1627,6 +1667,30 @@ export function superviseTick(cfg: LifecycleConfig, deps: SuperviseDeps = {}): S
       trace({ identity: s.identity, action: 'skipped-error', reason, outcome: 'peer-error-isolated' })
     }
   }
+  // NEVER-READY hosts with NO `.session` (18.10): the session state is written only AFTER a successful
+  // bring-up, so a bring-up that hung and was then abandoned (the launcher died mid-boot, a daemon
+  // restart) leaves a live host the loop above never sees — exactly how codex-linus, hung in dyld,
+  // stayed ● for 35 min. Walk the run-dir itself. H4: never a launchd-managed peer's host.
+  if (!deps.sessionAlive) {
+    const known = new Set(out.map(o => o.identity))
+    const boundMs = (cfg.bootDeadlineSecs + cfg.readyGateSecs + 60) * 1000
+    for (const h of listHostedPeers(env, runDir)) {
+      const identity = `${h.runtime}-${h.personality}`
+      if (known.has(identity)) continue
+      try {
+        if (isLaunchdManaged(h.personality, env)) continue
+        if (hostSessionReady(identity, env, runDir)) continue
+        const started = hostStartedMs(identity, env, runDir)
+        if (started === null || nowMs - started <= boundMs) continue
+        kill('', identity, 'supervise-never-ready-unsupervised')
+        recordDeath(cfg, identity, nowMs)
+        trace({ identity, action: 'reaped-gone', reason: 'never-ready-unsupervised', age: `${Math.floor((nowMs - started) / 1000)}s`, outcome: 'fresh-next-msg' })
+        out.push({ identity, action: 'reaped-gone', reason: 'unsupervised host never reached its ready surface' })
+      } catch {
+        /* per-host isolation, like the loop above */
+      }
+    }
+  }
   return out
 }
 

package/src/supervisor/capture.ts

@@ -0,0 +1,43 @@
+import { frame, FRAME_DATA, FRAME_RESIZE, makeFramer, sizePayload } from './protocol.ts'
+import { readGeometry, sockPath } from './paths.ts'
+
+/** Read the running host's OWN emulator, never the shared cross-session pane-log.
+ * Legacy hosts already implement same-size attach: no resize or input is sent to the child. */
+export async function captureHostViewport(runDir: string, session: string): Promise<string | null> {
+  const geometry = readGeometry(runDir, session)
+  if (!geometry) return null
+  const { cols, rows } = geometry
+  const bytes = await new Promise<Buffer | null>(resolve => {
+    let conn: Awaited<ReturnType<typeof Bun.connect>> | undefined
+    const chunks: Buffer[] = []
+    let settled = false
+    let quiet: ReturnType<typeof setTimeout> | undefined
+    const finish = () => {
+      if (settled) return
+      settled = true
+      clearTimeout(deadline)
+      clearTimeout(quiet)
+      conn?.end()
+      resolve(chunks.length ? Buffer.concat(chunks) : null)
+    }
+    const deadline = setTimeout(finish, 1500)
+    const consume = makeFramer((type, payload) => {
+      if (type !== FRAME_DATA) return
+      chunks.push(Buffer.from(payload))
+      clearTimeout(quiet)
+      quiet = setTimeout(finish, 80)
+    })
+    Bun.connect({ unix: sockPath(runDir, session), socket: {
+      open(s) { s.write(frame(FRAME_RESIZE, sizePayload(cols, rows))) },
+      data(_s, data) { consume(data) }, close() { finish() }, error() { finish() }, connectError() { finish() },
+    } }).then(s => { conn = s; if (settled) s.end() }).catch(finish)
+  })
+  if (!bytes) return null
+  const { Terminal } = await import('@xterm/headless')
+  const { modelToPlainText } = await import('./render.ts')
+  const term = new Terminal({ cols, rows, allowProposedApi: true })
+  try {
+    await new Promise<void>(r => term.write(bytes, r))
+    return modelToPlainText(term, cols, rows)
+  } finally { term.dispose() }
+}

package/src/supervisor/index.ts

@@ -5,7 +5,10 @@
 // serving is productionized (a later block) the daemon-spawn argv is repointed at the installed
 // binary; for now it self-spawns from source (bun + this file), which is what the tests exercise.
 import { spawn as nodeSpawn } from 'node:child_process'
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs'
+import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { formatEventLine } from '../storage/rotatelog.ts'
 import { fileURLToPath } from 'node:url'
 import { runSupervisorClient, sessionAlive } from './client.ts'
 import { defaultRunDir, logPath, ownershipVerdict, pidPath, pidStartToken, readPidFile, servePath, sockPath } from './paths.ts'
@@ -217,7 +220,30 @@ export function listSessions(runDir: string): Array<{ session: string; alive: bo
     })
 }
 
-export function killSession(runDir: string, session: string): boolean {
+export interface TerminationContext { reason?: string; caller?: string; sandbox?: boolean; targetPid?: number; targetToken?: string }
+
+/** Strict write-ahead audit: if attribution cannot be persisted, do not signal. No payload/env. */
+export function auditTermination(runDir: string, targets: string[], context: TerminationContext = {}): void {
+  const canonical = (p: string) => { try { return realpathSync(p) } catch { return resolve(p) } }
+  if ((context.sandbox || process.env.IAPEER_TEST_SANDBOX === '1') && canonical(runDir) === canonical(join(homedir(), '.iapeer/state/supervisor'))) {
+    throw new Error('refusing to signal the REAL supervisor run-dir under IAPEER_TEST_SANDBOX=1')
+  }
+  mkdirSync(runDir, { recursive: true, mode: 0o700 })
+  const fd = openSync(join(runDir, 'terminations.log'), 'a', 0o600)
+  try {
+    appendFileSync(fd, formatEventLine(Date.now(), {
+      ev: targets.length > 1 ? 'termination-batch' : 'termination-request',
+      targets: targets.join(','), caller: context.caller ?? process.env.PEER_IDENTITY ??
+        (process.env.PEER_PERSONALITY ? `${process.env.PEER_RUNTIME ?? 'unknown'}-${process.env.PEER_PERSONALITY}` : `uid:${process.getuid?.() ?? 'unknown'}`),
+      caller_pid: process.pid, caller_ppid: process.ppid,
+      target_pid: context.targetPid, target_token: context.targetToken,
+      reason: context.reason ?? `supervisor-kill:${process.argv[2] ?? 'api'}`,
+    }) + '\n')
+    fsyncSync(fd)
+  } finally { closeSync(fd) }
+}
+
+export function killSession(runDir: string, session: string, context: TerminationContext = {}): boolean {
   const rec = readPidFile(runDir, session)
   if (!rec) return false
   // В22 — verify the pid is STILL our daemon before SIGTERM. After an abnormal death + pid reuse, a bare
@@ -228,6 +254,7 @@ export function killSession(runDir: string, session: string): boolean {
   if (rec.token && !ownershipVerdict(pidStartToken(rec.pid), rec.token)) {
     return false // reused pid — NOT our session; do not signal it
   }
+  auditTermination(runDir, [session], { ...context, targetPid: rec.pid, targetToken: rec.token })
   try {
     process.kill(rec.pid, 'SIGTERM')
   } catch {

package/src/transport/index.ts

@@ -53,6 +53,7 @@ import {
   hostGeometry,
   hostRunDir,
   hostSessionAlive,
+  hostSessionReady,
   hostSessionToken,
   listHostedPeers,
   resubmitHosted,
@@ -103,22 +104,29 @@ function monotonicMs(): number {
 }
 
 function sessionAlive(_sock: string, address: string, env: NodeJS.ProcessEnv = process.env): boolean {
-  // pty-only: a peer's liveness is its supervisor daemon (a cheap pid-file check). `address` IS the
-  // identity. (`_sock` is retained for call-site compatibility; tmux sockets no longer exist.)
-  // env sandboxes the run-dir — an env-injected verb must not read the real fleet's liveness.
-  return hostSessionAlive(address, env)
+  // DELIVERY liveness = the hosting is alive AND its runtime reached its ready surface (incident
+  // 18.10: a codex hung before main lived under a healthy supervisor and took a message with a false
+  // ok). A not-yet-ready session routes as a MISS → the wake path, which waits on the in-flight
+  // bring-up (wake.lock) or replaces a failed one. `address` IS the identity; `_sock` is legacy.
+  return hostSessionReady(address, env)
 }
 
-/** Is the (runtime,personality) endpoint live right now? Public liveness predicate. */
-export function isPeerLive(runtime: string, personality: string, sockDir = resolveSockDir(), env: NodeJS.ProcessEnv = process.env): boolean {
-  const socketPath = buildSocketPath(runtime, personality, sockDir)
-  return sessionAlive(socketPath, buildProcessAddress(runtime, personality), env)
+/** Is the (runtime,personality) endpoint's PROCESS up right now (ready or not)? The operator-verb
+ *  guard (stop/remove/rename must still reach a hung process) — NOT a delivery predicate. */
+export function isPeerLive(runtime: string, personality: string, _sockDir = resolveSockDir(), env: NodeJS.ProcessEnv = process.env): boolean {
+  return hostSessionAlive(buildProcessAddress(runtime, personality), env)
+}
+
+/** Is the endpoint up AND its runtime ready (accepts input)? — what `list` shows as ●. */
+export function isPeerReady(runtime: string, personality: string, env: NodeJS.ProcessEnv = process.env): boolean {
+  return hostSessionReady(buildProcessAddress(runtime, personality), env)
 }
 
 export function listOnlinePeers(_sockDir = resolveSockDir(), env: NodeJS.ProcessEnv = process.env): OnlinePeer[] {
   // pty-only: every live peer is a supervisor-hosted session (no tmux sockets to scan).
   const out = new Map<string, OnlinePeer>()
   for (const h of listHostedPeers(env)) {
+    // Operator discovery includes booting/hung processes so interrupt/stop can still address them.
     out.set(buildProcessAddress(h.runtime, h.personality), { personality: h.personality, runtime: h.runtime })
   }
   return Array.from(out.values()).sort(
@@ -132,6 +140,8 @@ export function resolveDeliveryTarget(args: {
   sockDir?: string
   /** Б7 — injected env sandboxes the liveness reads (supervisor run-dir); default process.env (prod). */
   env?: NodeJS.ProcessEnv
+  /** Operator control can address a hung/booting process; delivery cannot. */
+  processOnly?: boolean
 }): Result<DeliveryTarget> {
   const env = args.env ?? process.env
   const sockDir = args.sockDir ?? resolveSockDir(env)
@@ -143,12 +153,13 @@ export function resolveDeliveryTarget(args: {
     const runtime = args.runtime
     const socketPath = buildSocketPath(runtime, args.personality, sockDir)
     const address = buildProcessAddress(runtime, args.personality)
-    if (!sessionAlive(socketPath, address, env)) {
+    if (!(args.processOnly ? hostSessionAlive(address, env) : sessionAlive(socketPath, address, env))) {
       return err(`peer offline: ${args.personality} (${args.runtime})`)
     }
     return ok({ runtime, personality: args.personality, address, socketPath })
   }
-  const matches = listOnlinePeers(sockDir, env).filter(peer => peer.personality === args.personality)
+  const matches = listOnlinePeers(sockDir, env).filter(peer => peer.personality === args.personality &&
+    (args.processOnly || hostSessionReady(buildProcessAddress(peer.runtime, peer.personality), env)))
   if (matches.length === 0) return err(`peer offline: ${args.personality}`)
   if (matches.length > 1) {
     return err(
@@ -1220,13 +1231,13 @@ export interface ControlResult {
  * live endpoints stays ambiguous → explicit refusal. An explicit runtime is exact.
  */
 export function resolveControlTarget(personality: string, runtime: string | undefined, env: NodeJS.ProcessEnv = process.env): Result<DeliveryTarget> {
-  if (runtime) return resolveDeliveryTarget({ personality, runtime, env })
+  if (runtime) return resolveDeliveryTarget({ personality, runtime, env, processOnly: true })
   const peer = findPeer(readPeersIndex({ env }), personality)
   if (peer) {
-    const anchored = resolveDeliveryTarget({ personality, runtime: peer.runtime, env })
+    const anchored = resolveDeliveryTarget({ personality, runtime: peer.runtime, env, processOnly: true })
     if (anchored.ok) return anchored
   }
-  return resolveDeliveryTarget({ personality, env })
+  return resolveDeliveryTarget({ personality, env, processOnly: true })
 }
 
 export async function routeControl(personality: string, runtime: string | undefined, command: ControlCommand): Promise<Result<ControlResult>> {

package/src/tray/render.ts

@@ -12,7 +12,7 @@
 // peer row hands off to `iapeer attach`, the terminal-handoff the API deliberately
 // keeps client-side).
 
-const GLYPH: Record<'live' | 'asleep' | 'stopped', string> = { live: '●', asleep: '○', stopped: '✕' }
+const GLYPH: Record<'live' | 'booting' | 'asleep' | 'stopped', string> = { live: '●', booting: '◐', asleep: '○', stopped: '✕' }
 
 const COLOR = {
   meta: '#8b949e',
@@ -31,7 +31,7 @@ const APPROVAL_CONTENT_MAX_CHARS = 8000
 
 export interface TrayRuntime {
   runtime: string
-  status: 'live' | 'asleep' | 'stopped'
+  status: 'live' | 'booting' | 'asleep' | 'stopped'
   attached?: boolean
 }
 
@@ -134,13 +134,14 @@ export function fmtClock(now: number): string {
 
 // ── peer status aggregation ─────────────────────────────────────────────────────
 
-function aggregate(p: TrayPeer): 'live' | 'asleep' | 'stopped' {
+function aggregate(p: TrayPeer): 'live' | 'booting' | 'asleep' | 'stopped' {
   if (p.runtimes.some(r => r.status === 'live')) return 'live'
+  if (p.runtimes.some(r => r.status === 'booting')) return 'booting'
   if (p.runtimes.some(r => r.status === 'asleep')) return 'asleep'
   return 'stopped'
 }
 
-const RANK: Record<'live' | 'asleep' | 'stopped', number> = { live: 0, asleep: 1, stopped: 2 }
+const RANK: Record<'live' | 'booting' | 'asleep' | 'stopped', number> = { live: 0, booting: 1, asleep: 2, stopped: 3 }
 
 // 🔒 launchd-managed peers (the human channel + service infra — arthur/timer/watcher) are
 // NON-clickable status rows. They form ONE contiguous block at the very TOP, before the first

package/src/tui/dashboard/app.tsx

@@ -23,8 +23,8 @@ const POLL_MS = 2000
 const HOST_POLL_MS = 10_000
 const LOG_LIMIT = 12
 
-const STATUS_GLYPH: Record<RuntimeLiveness, string> = { live: '●', asleep: '○', stopped: '✕' }
-const STATUS_COLOR: Record<RuntimeLiveness, string | undefined> = { live: 'green', asleep: undefined, stopped: 'red' }
+const STATUS_GLYPH: Record<RuntimeLiveness, string> = { live: '●', booting: '◐', asleep: '○', stopped: '✕' }
+const STATUS_COLOR: Record<RuntimeLiveness, string | undefined> = { live: 'green', booting: 'yellow', asleep: undefined, stopped: 'red' }
 
 function RuntimeCells({ row }: { row: PeerListing }): React.ReactElement {
   return (

package/src/uninstall/index.ts

@@ -226,9 +226,12 @@ async function waitJobGone(run: SysRunner, uid: number, label: string, timeoutMs
  *  wait for its pidfile-liveness to drop). Best-effort per session; reports laggards. */
 async function stopHostedSessions(env: NodeJS.ProcessEnv, timeoutMs = 8000): Promise<{ stopped: string[]; stuck: string[] }> {
   const identities = listHostedPeers(env).map(h => buildProcessAddress(h.runtime, h.personality))
+  const { auditTermination } = await import('../supervisor/index.ts')
+  const { hostRunDir } = await import('../launch/ptyHost.ts')
+  if (identities.length) auditTermination(hostRunDir(env), identities, { reason: 'uninstall-hosted-sessions', caller: env.PEER_IDENTITY, sandbox: env.IAPEER_TEST_SANDBOX === '1' })
   for (const id of identities) {
     try {
-      killPtyHost(id, env)
+      killPtyHost(id, env, { reason: 'uninstall-hosted-sessions' })
     } catch {
       /* verified-dead / permission — the wait below reports it */
     }
@@ -258,6 +261,10 @@ export async function executeUninstall(opts: UninstallOptions = {}): Promise<Uni
   }
 
   const uid = process.getuid?.() ?? 0
+  const { auditTermination } = await import('../supervisor/index.ts')
+  const { hostRunDir } = await import('../launch/ptyHost.ts')
+  const targets = plan.items.filter(i => i.present && i.action === 'bootout-remove-plist').map(i => i.path ?? i.what)
+  if (targets.length) auditTermination(hostRunDir(env), targets, { reason: 'uninstall', caller: env.PEER_IDENTITY, sandbox: env.IAPEER_TEST_SANDBOX === '1' })
   // Set when a launchd job survived bootout (В56) — ~/.iapeer must NOT be removed
   // from under a job launchd may respawn (KeepAlive) into the deleted tree.
   let jobStillLoaded: string | undefined

package/src/update/index.ts

@@ -39,6 +39,8 @@ import { IAPEER_VERSION } from '../core/version.ts'
 import { iapeerBinPath, stampBinaryHealthy } from '../install/index.ts'
 import { ensureExecutableSignature } from '../install/signature.ts'
 import { readPeersIndex } from '../registry/index.ts'
+import { auditTermination } from '../supervisor/index.ts'
+import { defaultRunDir } from '../supervisor/paths.ts'
 import {
   cycleDaemon,
   cycleLaunchdJob,
@@ -263,6 +265,9 @@ export function recycleFoundationOwnedInfraJobs(env: NodeJS.ProcessEnv = process
   if (env.IAPEER_TEST_SANDBOX === '1' || process.env.IAPEER_TEST_SANDBOX === '1') return []
   const out: InfraJobRecycleResult[] = []
   const index = readPeersIndex({ env })
+  const targets = index.peers.flatMap(peer => [...new Set([peer.runtime, ...peer.runtimes])].filter(isInfraRuntime)
+    .map(runtime => resolveAlwaysOnTarget(peer.personality, runtime, env)).filter(t => isFoundationOwnedPlist(t.path)).map(t => t.label))
+  if (targets.length) auditTermination(defaultRunDir(env), targets, { reason: 'update-recycle-infra', caller: env.PEER_IDENTITY })
   for (const peer of index.peers) {
     // Multi-infra (0.4.88): a personality can hold SEVERAL always-on channels
     // (e.g. arthur: telegram on the legacy base plist + web on the per-runtime