@agfpd/iapeer 0.2.63 → 0.2.65

package/src/supervisor/attached-marker.test.ts

@@ -0,0 +1,84 @@
+// Spawn-flip cutover Block 2, Ф0b-3 slice 3c-1 — the supervisor `.attached` marker (the gate signal
+// `hasAttachedSupervisorClient` reads to hold hosted delivery ONLY for a real attached human).
+// boris's three faces: (1) present ⟺ clients.size>0; (2) ALL detach paths incl. ABNORMAL (abrupt
+// terminate → error/close), not just a clean Ctrl-]; (3) CRASH-ROBUSTNESS — a crashed predecessor
+// skips shutdown-cleanup, so a stale marker must be cleared on daemon START. Real detached daemon over
+// a real unix socket (tick runtime — no codex needed); the marker is read CROSS-PROCESS, as in prod.
+import { afterEach, describe, expect, test } from 'bun:test'
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { frame, FRAME_RESIZE, sizePayload } from './protocol.ts'
+import { killSession, sessionAlive, sockPath, startSupervisorDaemon } from './index.ts'
+import { attachedPath } from './paths.ts'
+
+const [maj, min, pat] = (Bun.version || '0.0.0').split('.').map(Number) as [number, number, number]
+const bunPty = maj > 1 || (maj === 1 && (min > 3 || (min === 3 && pat >= 5)))
+const d = bunPty ? describe : describe.skip
+
+const sleep = (ms: number): Promise<void> => new Promise(r => setTimeout(r, ms))
+async function waitFor(pred: () => boolean, timeoutMs = 5000, step = 40): Promise<boolean> {
+  const end = Date.now() + timeoutMs
+  while (Date.now() < end) { if (pred()) return true; await sleep(step) }
+  return false
+}
+
+interface Client { end(): void; terminate(): void }
+async function attach(runDir: string, session: string): Promise<Client> {
+  const sock = await Bun.connect({
+    unix: sockPath(runDir, session),
+    socket: { open(s) { s.write(frame(FRAME_RESIZE, sizePayload(80, 24))) }, data() { /* */ } },
+  })
+  return {
+    end: () => { try { sock.end() } catch { /* */ } },
+    terminate: () => { try { sock.terminate() } catch { /* */ } },
+  }
+}
+
+const dirs: string[] = []
+const mkRunDir = (): string => { const d2 = mkdtempSync(join(tmpdir(), 'iapeer-attmark-')); dirs.push(d2); return d2 }
+afterEach(() => { for (const d2 of dirs.splice(0)) rmSync(d2, { recursive: true, force: true }) })
+
+d('supervisor .attached marker (the hosted occupancy gate signal)', () => {
+  test('present ⟺ clients.size>0 across multiple clients (no stuck "attached" on partial detach)', async () => {
+    const runDir = mkRunDir(), session = 'mk'
+    startSupervisorDaemon({ session, runtime: 'tick', runDir })
+    expect(await waitFor(() => sessionAlive(runDir, session))).toBe(true)
+    const marker = attachedPath(runDir, session)
+    expect(existsSync(marker)).toBe(false) // no client yet → absent
+    const c1 = await attach(runDir, session)
+    expect(await waitFor(() => existsSync(marker))).toBe(true) // ≥1 attached → present
+    const c2 = await attach(runDir, session)
+    await sleep(150)
+    expect(existsSync(marker)).toBe(true) // 2 attached → still present
+    c1.end()
+    await sleep(250)
+    expect(existsSync(marker)).toBe(true) // 1 still attached → NOT stuck-absent, NOT removed early
+    c2.end()
+    expect(await waitFor(() => !existsSync(marker))).toBe(true) // 0 attached → absent
+    killSession(runDir, session)
+  })
+
+  test('ABNORMAL detach (abrupt terminate, not a clean Ctrl-]) → marker still removed', async () => {
+    const runDir = mkRunDir(), session = 'ab'
+    startSupervisorDaemon({ session, runtime: 'tick', runDir })
+    expect(await waitFor(() => sessionAlive(runDir, session))).toBe(true)
+    const marker = attachedPath(runDir, session)
+    const c = await attach(runDir, session)
+    expect(await waitFor(() => existsSync(marker))).toBe(true)
+    c.terminate() // abrupt RST — daemon sees error/close, NOT a graceful protocol detach
+    expect(await waitFor(() => !existsSync(marker))).toBe(true) // the error/close path ALSO syncs the marker
+    killSession(runDir, session)
+  })
+
+  test('CRASH-ROBUSTNESS: a stale marker is cleared on daemon START (crash skips shutdown-cleanup)', async () => {
+    const runDir = mkRunDir(), session = 'cr'
+    const marker = attachedPath(runDir, session)
+    writeFileSync(marker, '') // a crashed predecessor left this present, with no live client
+    expect(existsSync(marker)).toBe(true)
+    startSupervisorDaemon({ session, runtime: 'tick', runDir }) // fresh daemon = 0 clients
+    expect(await waitFor(() => sessionAlive(runDir, session))).toBe(true)
+    expect(await waitFor(() => !existsSync(marker))).toBe(true) // start-cleanup removed the stale lie
+    killSession(runDir, session)
+  })
+})

package/src/supervisor/boot.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from 'bun:test'
+import { codexAdapter } from '../launch/adapters/codex.ts'
+import { claudeAdapter } from '../launch/adapters/claude.ts'
+import { nextBootAction, type BootAction } from './boot.ts'
+
+// Fed the REAL runtime adapters (codexAdapter/claudeAdapter) — not fakes — so the test proves the
+// supervisor answers the exact dialogs the launch primitive answers, with byte-correct keys.
+const bytesOf = (a: BootAction): Buffer => (a.kind === 'dialog' ? a.bytes : Buffer.alloc(0))
+
+describe('nextBootAction — codex startup dialogs answered off the model', () => {
+  test('dir-trust → Enter (CR)', () => {
+    const a = nextBootAction(codexAdapter, 'Do you trust the contents of this directory?\n  1. Yes, continue')
+    expect(a.kind).toBe('dialog')
+    expect(bytesOf(a)).toEqual(Buffer.from('\r'))
+  })
+
+  test('update offer → decline [2,Enter], and NOT ready while "Press enter to continue" is up', () => {
+    const pane = 'Update available! 9.9.9\nPress enter to continue'
+    const a = nextBootAction(codexAdapter, pane)
+    expect(a.kind).toBe('dialog')
+    expect(bytesOf(a)).toEqual(Buffer.from('2\r'))
+  })
+
+  test('hooks-review → [Down,Enter]; the cursor byte follows the model cursor mode', () => {
+    const pane = 'Hooks need review\n  1. Review  2. Trust all and continue'
+    expect(bytesOf(nextBootAction(codexAdapter, pane))).toEqual(Buffer.from('\x1b[B\r')) // normal
+    expect(bytesOf(nextBootAction(codexAdapter, pane, { appCursorKeys: true }))).toEqual(Buffer.from('\x1bOB\r')) // DECCKM
+  })
+
+  test('composer rendered, no startup screen → ready', () => {
+    expect(nextBootAction(codexAdapter, 'a rotating tip line\n› ').kind).toBe('ready')
+  })
+
+  test('splash up, composer not yet rendered → wait', () => {
+    expect(nextBootAction(codexAdapter, 'OpenAI Codex\n(loading session)').kind).toBe('wait')
+  })
+})
+
+describe('nextBootAction — claude startup dialogs answered off the model', () => {
+  test('folder-trust → Enter (CR)', () => {
+    const a = nextBootAction(claudeAdapter, 'Do you trust this folder?\n  1. Yes')
+    expect(a.kind).toBe('dialog')
+    expect(bytesOf(a)).toEqual(Buffer.from('\r'))
+  })
+
+  test('resume-picker before the cursor reaches option 2 → Down (mode-correct cursor byte)', () => {
+    const pane = 'Resume from summary\n  ❯ 1. Start fresh\n    2. Resume full session'
+    const a = nextBootAction(claudeAdapter, pane)
+    expect(a.kind).toBe('dialog')
+    expect(bytesOf(a)).toEqual(Buffer.from('\x1b[B')) // normal cursor mode
+    expect(bytesOf(nextBootAction(claudeAdapter, pane, { appCursorKeys: true }))).toEqual(Buffer.from('\x1bOB'))
+  })
+
+  test('resume-picker once the cursor IS on option 2 → Enter (never re-Downs past the proceed row)', () => {
+    const pane = 'Resume from summary\n    1. Start fresh\n  ❯ 2. Resume full session'
+    expect(bytesOf(nextBootAction(claudeAdapter, pane))).toEqual(Buffer.from('\r'))
+  })
+
+  test('input row + bypass banner → ready', () => {
+    expect(nextBootAction(claudeAdapter, '❯ \n  bypass permissions on').kind).toBe('ready')
+  })
+
+  test('splash up, input row not yet rendered → wait', () => {
+    expect(nextBootAction(claudeAdapter, 'Welcome to Claude Code\n  (starting)').kind).toBe('wait')
+  })
+})

package/src/supervisor/boot.ts

@@ -0,0 +1,34 @@
+// Supervisor BOOT-DRIVER decision (serving slice a) — the pure half of "answer the startup dialogs
+// off the model". A real codex/claude TUI stalls on trust/update/hooks/resume modals; under tmux the
+// launch primitive (index.ts boot loop, 384-411) answers them via capture-pane (read) + send-keys
+// (write). The supervisor reads its authoritative @xterm model (modelToPlainText) and writes raw pty
+// bytes (keysToBytes) — same decision, different surfaces. This module is the DECISION; daemon.ts
+// owns the loop (render → decide → write). PURE: no @xterm, no pty — feed it a viewport string + the
+// runtime's boot predicates and it returns the bytes to send, so it is unit-testable against the
+// real adapters.
+import { keysToBytes, type KeyEncoding } from './protocol.ts'
+
+/** The slice of a RuntimeAdapter the boot-driver consumes. codexAdapter / claudeAdapter satisfy it
+ *  structurally, so boot.ts stays decoupled from launch/types.ts. */
+export interface BootPredicates {
+  bootDialogKeys(pane: string): string[] | null
+  isInputReady(pane: string): boolean
+}
+
+export type BootAction =
+  | { kind: 'dialog'; keys: string[]; bytes: Buffer }
+  | { kind: 'ready' }
+  | { kind: 'wait' }
+
+/**
+ * One boot step, mirroring the launch primitive's order (index.ts:384-411): a visible startup dialog
+ * is answered FIRST (its keys clear it; bytes encoded for the model's current cursor mode), ELSE the
+ * input surface is checked for readiness, ELSE wait for the next frame. The caller loops this on a
+ * cadence, writing `action.bytes` to the pty on a 'dialog' and stopping on 'ready'.
+ */
+export function nextBootAction(adapter: BootPredicates, viewport: string, enc: KeyEncoding = {}): BootAction {
+  const keys = adapter.bootDialogKeys(viewport)
+  if (keys && keys.length) return { kind: 'dialog', keys, bytes: keysToBytes(keys, enc) }
+  if (adapter.isInputReady(viewport)) return { kind: 'ready' }
+  return { kind: 'wait' }
+}

package/src/supervisor/daemon.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
-import { mkdtempSync, rmSync } from 'node:fs'
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { FRAME_DATA, FRAME_RESIZE, frame, makeFramer, sizePayload } from './protocol.ts'
@@ -109,4 +109,69 @@ d('supervisor daemon (Bun-native pty, tick runtime)', () => {
     expect(fresh).toBe(true)
     second.close()
   })
+
+  // Serving seam (slice b): a serve-spec is written before spawn, the detached daemon reads it, and
+  // the composed argv + env + cwd reach the child VERBATIM (with the pty-host TERM layered on top and
+  // TMUX stripped). A probe child dumps the markers it actually received — proving the supervisor
+  // serves a launch-composed invocation faithfully (the parity foundation; the env-identity ABI rides
+  // in here at serving time).
+  test('serving seam: composed argv + env + cwd reach the child verbatim (slice b)', async () => {
+    const servingSession = 'ptsserve'
+    const childCwd = realpathSync(mkdtempSync(join(tmpdir(), 'iapeer-serve-cwd-')))
+    const out = join(runDir, 'serve-probe.out')
+    try {
+      const serve = {
+        // dump what the child ACTUALLY received: a composed env var, its cwd, TERM, and TMUX-presence
+        argv: [
+          'sh',
+          '-c',
+          'printf "%s\\n%s\\n%s\\n%s\\n" "$SERVE_MARKER" "$(pwd -P)" "$TERM" "${TMUX:-no-tmux}" > "$OUTFILE"; exec sleep 30',
+        ],
+        env: { SERVE_MARKER: 'identity-abi-xyz', OUTFILE: out, PATH: process.env.PATH ?? '', TMUX: 'should-be-stripped' },
+        cwd: childCwd,
+      }
+      const r = startSupervisorDaemon({ session: servingSession, runtime: 'claude', runDir, serve })
+      expect(r.state).toBe('started')
+      const wrote = await waitFor(() => existsSync(out) && readFileSync(out, 'utf8').trim().split('\n').length >= 4)
+      expect(wrote).toBe(true)
+      const [marker, pwd, term, tmux] = readFileSync(out, 'utf8').split('\n')
+      expect(marker).toBe('identity-abi-xyz') // composed env reached the child verbatim
+      expect(pwd).toBe(childCwd) // composed cwd honored
+      expect(term).toBe('xterm-256color') // pty-host TERM layered on top of the composed env
+      expect(tmux).toBe('no-tmux') // TMUX stripped — a served child never thinks it is inside tmux
+    } finally {
+      killSession(runDir, servingSession)
+      rmSync(childCwd, { recursive: true, force: true })
+    }
+  })
+
+  // Exit-cause (spawn-flip Ф0b-1 resilience-b): when the hosted child dies, the daemon records a
+  // `ev=session-exit … host=supervisor` line in exits.log — the cause the supervise-tick death
+  // classification + crash-loop accounting need (mirror of the tmux pane-died hook). Kill the child,
+  // assert the line lands.
+  test('exit-cause: the daemon records the hosted child death in exits.log (resilience-b)', async () => {
+    const exSession = 'ptsexit'
+    const exitLog = join(runDir, 'exits.log')
+    const childPidFile = join(runDir, 'exit-child.pid')
+    try {
+      const r = startSupervisorDaemon({
+        session: exSession,
+        runtime: 'tick',
+        runDir,
+        serve: { argv: ['sh', '-c', `echo $$ > '${childPidFile}'; exec sleep 30`], env: { PATH: process.env.PATH ?? '' }, cwd: runDir, exitLogPath: exitLog },
+      })
+      expect(r.state).toBe('started')
+      const got = await waitFor(() => existsSync(childPidFile))
+      expect(got).toBe(true)
+      process.kill(Number(readFileSync(childPidFile, 'utf8').trim()), 'SIGKILL')
+      const recorded = await waitFor(() => existsSync(exitLog) && /ev=session-exit identity=ptsexit.*host=supervisor/.test(readFileSync(exitLog, 'utf8')))
+      expect(recorded).toBe(true) // the death cause is in exits.log → crash-loop accounting has it
+    } finally {
+      try {
+        killSession(runDir, exSession)
+      } catch {
+        /* */
+      }
+    }
+  })
 })

package/src/supervisor/daemon.ts

@@ -9,7 +9,8 @@
 // `bun build --compile` (pure JS; the Bun-native pty has no native addon — PoC-proven).
 import { Terminal } from '@xterm/headless'
 import { SerializeAddon } from '@xterm/addon-serialize'
-import { existsSync, unlinkSync, writeFileSync } from 'node:fs'
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, unlinkSync, writeFileSync, writeSync } from 'node:fs'
+import { dirname } from 'node:path'
 import {
   BackpressureWriter,
   FRAME_DATA,
@@ -20,7 +21,11 @@ import {
   parseSize,
   stripQueries,
 } from './protocol.ts'
-import { pidPath, sockPath } from './paths.ts'
+import { attachedPath, pidPath, servePath, sockPath } from './paths.ts'
+import { nextBootAction, type BootPredicates } from './boot.ts'
+import { modelToPlainText } from '../shadow/render.ts'
+import { codexAdapter } from '../launch/adapters/codex.ts'
+import { claudeAdapter } from '../launch/adapters/claude.ts'
 
 /** Known runtime launchers; `tick` is a deterministic test stream (no TUI noise) for hermetic
  *  spawn/attach/reattach tests — it never needs a real claude/codex on the box. */
@@ -30,6 +35,20 @@ const KNOWN: Record<string, string> = {
 }
 const TICK_CMD = ['sh', '-c', 'i=0; while true; do printf "STREAMTICK_%d\\r\\n" "$i"; i=$((i+1)); sleep 0.3; done']
 
+// Boot-driver (serving slice a): the runtimes whose startup dialogs the supervisor knows how to
+// answer off its model. 'tick' (and any unknown runtime) has no entry → no driver → the hermetic
+// spawn/attach tests and the bare conduit are untouched.
+const BOOT_ADAPTERS: Record<string, BootPredicates> = { codex: codexAdapter, claude: claudeAdapter }
+// Poll cadence mirrors the launch primitive's proven 2 s boot loop (index.ts:377). The supervisor
+// model is strictly FRESHER than capture-pane (bytes land in @xterm synchronously as they arrive),
+// so 2 s leaves ample repaint time — the claude resume-picker never over-Downs, since bootDialogKeys
+// returns Enter (not another Down) the moment the moved cursor renders '❯ 2.'. A swallowed key
+// self-heals on the next tick (re-sent while the dialog is still up), same as the launch loop.
+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
+
 // Bun-native PTY (Bun ≥1.3.5) is not yet in @types/bun — type the slice we use.
 interface PtyChild {
   terminal: { write(d: Uint8Array | string): void; resize(cols: number, rows: number): void }
@@ -44,6 +63,22 @@ export interface SupervisorDaemonOptions {
   cwd?: string
   /** Override the runtime launcher (else KNOWN[runtime] if it exists, else the bare name). */
   bin?: string
+  /** SERVING SEAM (slice b): the composed runtime argv (buildLaunchInvocation). When set, the daemon
+   *  serves THIS verbatim instead of the bare [bin] — the supervisor is a HOST, not a composer
+   *  (launch/lifecycle composes argv+env; the supervisor, like tmux, just serves the invocation). */
+  argv?: string[]
+  /** SERVING SEAM (slice b): the composed child env (buildLaunchInvocation) — base for the child.
+   *  The pty-host env (TERM set, TMUX/TMUX_PANE stripped) is layered ON TOP. Unset → process.env. */
+  env?: Record<string, string>
+  /** PANE-LOG (slice c): absolute path the child's RAW output bytes are appended to — `<logDir>/
+   *  <identity>.log`, the SAME file + append semantics tmux `pipe-pane` writes today, so the observer
+   *  / shadow / readyGateViewport tail a served session's log identically. Unset → no pane-log
+   *  (throwaway/tick). */
+  paneLogPath?: string
+  /** EXIT-CAUSE (spawn-flip Ф0b resilience-b): exits.log path. On child exit the daemon appends a
+   *  `ev=session-exit … dead_status/dead_signal host=supervisor` line (mirroring the tmux pane-died
+   *  hook), so the supervise-tick death classification + crash-loop accounting have the cause. */
+  exitLogPath?: string
   cols?: number
   rows?: number
 }
@@ -63,14 +98,53 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
   xterm.loadAddon(ser)
 
   const bin = opts.bin ?? (KNOWN[runtime] && existsSync(KNOWN[runtime]!) ? KNOWN[runtime]! : runtime)
-  const CMD = runtime === 'tick' ? TICK_CMD : [bin]
-  const env = { ...process.env, TERM: 'xterm-256color' } as Record<string, string>
+  // SERVING SEAM (slice b): opts.argv (launch-composed, carries the system-prompt swap + PEER_START_ARGS)
+  // is served verbatim; else the bare conduit ([bin], or the deterministic tick stream for tests).
+  const CMD = opts.argv ?? (runtime === 'tick' ? TICK_CMD : [bin])
+  // pty-host env layered ON TOP of the composed child env (opts.env, = buildLaunchInvocation): force a
+  // real TERM and strip TMUX/TMUX_PANE so a served child never believes it is inside tmux. The identity
+  // ABI (PEER_IDENTITY, IAPEER_BEARER, …) rides in opts.env underneath, untouched.
+  const env = { ...(opts.env ?? process.env), TERM: 'xterm-256color' } as Record<string, string>
   delete env.TMUX
   delete env.TMUX_PANE
 
+  // PANE-LOG (slice c): append the child's RAW output bytes to <logDir>/<identity>.log, byte-identical
+  // to tmux `pipe-pane … 'cat >> <log>'`. The fd is opened once (append); every chunk is written as a
+  // raw Buffer (writeSync(fd, buf)) — NEVER via a string (Bun re-encodes a latin1 string to UTF-8 and
+  // corrupts multibyte glyphs like ❯/›; the canonical latin1/Buffer grabli). Parent dir 0700, matching
+  // launch's mkdir before pipe-pane. Unset paneLogPath → no log (throwaway/tick).
+  let paneLogFd = -1
+  if (opts.paneLogPath) {
+    try {
+      mkdirSync(dirname(opts.paneLogPath), { recursive: true, mode: 0o700 })
+      paneLogFd = openSync(opts.paneLogPath, 'a')
+    } catch {
+      paneLogFd = -1 // best-effort: a log open hiccup never blocks serving the session
+    }
+  }
+
   const clients = new Set<unknown>()
   const writers = new WeakMap<object, BackpressureWriter>()
   const framers = new WeakMap<object, (chunk: Uint8Array) => void>()
+  // ATTACHED-CLIENT MARKER (spawn-flip Ф0b-3 slice 3c): keep `<runDir>/<session>.attached` in sync with
+  // clients.size — present iff ≥1 operator is attached. The warm-deliver path (a DIFFERENT process)
+  // reads it to gate the hosted busy-composer hold: hold ONLY when a human is attached (their unfinished
+  // composer text), never for the AI's own composer output when no one is attached. Best-effort: a
+  // marker fs hiccup must never break the conduit.
+  const attachedMarker = attachedPath(runDir, session)
+  const syncAttached = (): void => {
+    try {
+      if (clients.size > 0) writeFileSync(attachedMarker, '')
+      else if (existsSync(attachedMarker)) unlinkSync(attachedMarker)
+    } catch {
+      /* */
+    }
+  }
+  // CRASH-ROBUSTNESS (boris): a crashed predecessor daemon skips shutdown-cleanup, so a STALE
+  // `.attached` could survive into this fresh daemon — and a stale-present marker would make the
+  // warm-deliver gate believe a human is attached when none is, holding deliveries forever (the
+  // anti-bug inverted). A fresh daemon has ZERO clients, so clear the marker on START (idempotent).
+  syncAttached()
   const writerFor = (s: { write(b: Buffer): number }): BackpressureWriter => {
     let w = writers.get(s as object)
     if (!w) {
@@ -96,13 +170,40 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
       name: 'xterm-256color',
       data(_t: unknown, d: Uint8Array | string) {
         const buf = Buffer.isBuffer(d) ? d : typeof d === 'string' ? Buffer.from(d, 'utf8') : Buffer.from(d)
+        // PANE-LOG: the RAW child bytes, exactly as pipe-pane writes them (before any query-stripping
+        // for clients) — written as a Buffer, never a string. The `s` below is for query DETECTION only.
+        if (paneLogFd >= 0)
+          try {
+            writeSync(paneLogFd, buf)
+          } catch {
+            /* best-effort */
+          }
         const s = buf.toString('latin1')
         xterm.write(buf) // authoritative model
         for (const r of capabilityResponses(s)) child.terminal.write(r) // answer capability queries
         const fwd = Buffer.from(stripQueries(s), 'latin1') // forward to clients sans queries (daemon is authoritative)
         if (fwd.length) for (const c of [...clients]) sendClient(c as { write(b: Buffer): number }, frame(FRAME_DATA, fwd))
       },
-      exit() {
+      exit(_t?: unknown, exitCode?: number | null, signalCode?: number | null) {
+        // resilience-b exit-cause (spawn-flip Ф0b): record WHY the hosted child died into exits.log,
+        // mirroring the tmux pane-died hook (ev=session-exit dead_status/dead_signal), so the daemon's
+        // supervise-tick death classification + crash-loop accounting have the cause. host=supervisor
+        // distinguishes the source. The Bun-native pty exit callback passes (exitCode, signalCode) like
+        // onExit; fall back to the subprocess props. Best-effort — never blocks shutdown.
+        if (opts.exitLogPath) {
+          try {
+            mkdirSync(dirname(opts.exitLogPath), { recursive: true, mode: 0o700 }) // ensure the exits.log dir exists
+            const c = child as { exitCode?: number | null; signalCode?: number | null }
+            const status = exitCode ?? c.exitCode ?? ''
+            const signal = signalCode ?? c.signalCode ?? ''
+            appendFileSync(
+              opts.exitLogPath,
+              `ts=${new Date().toISOString()} ev=session-exit identity=${session} dead_status=${status} dead_signal=${signal} host=supervisor\n`,
+            )
+          } catch {
+            /* best-effort */
+          }
+        }
         shutdown()
       },
     },
@@ -152,21 +253,24 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
       open(s: { write(b: Buffer): number }) {
         framers.set(s as object, makeFramer((t, p) => onClientFrame(s, t, p)))
         clients.add(s)
+        syncAttached() // ≥1 client now attached → marker present
         repaint(s) // UNCONDITIONAL repaint on attach (tmux-like)
       },
       data(s: object, d: Uint8Array) {
         framers.get(s)?.(d)
       },
       drain(s: object) {
-        if (!writers.get(s)?.flush()) clients.delete(s) // writable again → flush queued tail
+        if (!writers.get(s)?.flush()) { clients.delete(s); syncAttached() } // writable again → flush queued tail
       },
       close(s: object) {
         clients.delete(s)
         writers.delete(s)
+        syncAttached()
       },
       error(s: object) {
         clients.delete(s)
         writers.delete(s)
+        syncAttached()
       },
     },
   })
@@ -176,6 +280,12 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
   function shutdown(): void {
     if (down) return
     down = true
+    if (paneLogFd >= 0)
+      try {
+        closeSync(paneLogFd)
+      } catch {
+        /* */
+      }
     try {
       child.kill('SIGKILL')
     } catch {
@@ -186,7 +296,7 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
     } catch {
       /* */
     }
-    for (const f of [sock, pid]) {
+    for (const f of [sock, pid, servePath(runDir, session), attachedMarker]) {
       try {
         unlinkSync(f)
       } catch {
@@ -207,4 +317,33 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
       /* */
     }
   })
+
+  // ── boot-dialog driver (serving slice a) ────────────────────────────────────────
+  // For a real runtime, answer the startup dialogs (codex trust/update/hooks, claude trust/resume)
+  // off the AUTHORITATIVE @xterm model so the session reaches a ready input surface UNDER the
+  // supervisor — exactly what the launch primitive does over `tmux capture-pane` (read) + `send-keys`
+  // (write), but model-read (modelToPlainText) + raw pty-byte-write (keysToBytes). The cursor-key
+  // byte follows the model's live DECCKM mode (xterm.modes.applicationCursorKeysMode) — tmux keys off
+  // the same mode, so hooks-review/resume-picker Downs are byte-identical. DARK: the supervisor
+  // serves nothing on the live fleet; this drives only throwaway sessions until the serving flip.
+  const bootAdapter = BOOT_ADAPTERS[runtime]
+  if (bootAdapter) {
+    const driveDeadline = Date.now() + BOOT_DRIVE_MS
+    const driver = setInterval(() => {
+      if (down) {
+        clearInterval(driver)
+        return
+      }
+      let action
+      try {
+        const enc = { appCursorKeys: xterm.modes.applicationCursorKeysMode }
+        action = nextBootAction(bootAdapter, modelToPlainText(xterm, cols, rows), enc)
+      } catch {
+        return // transient model read — retry next tick
+      }
+      if (action.kind === 'dialog') child.terminal.write(action.bytes)
+      else if (action.kind === 'ready' || Date.now() > driveDeadline) clearInterval(driver)
+    }, BOOT_POLL_MS)
+    ;(driver as { unref?: () => void }).unref?.()
+  }
 }

package/src/supervisor/deliver.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'bun:test'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { deliverToHost } from './deliver.ts'
+import { killSession, startSupervisorDaemon } from './index.ts'
+
+// The deliver leaf is the host equivalent of tmux load-buffer/paste-buffer/send-keys: it must put the
+// message on the hosted child's pty input as a bracketed paste followed by a CR. Hermetic: a probe
+// child captures its raw stdin (stty raw bypasses the line discipline) so we assert the EXACT bytes
+// the child received. Guarded on Bun-native pty.
+const [maj, min, pat] = (Bun.version || '0.0.0').split('.').map(Number) as [number, number, number]
+const bunPty = maj > 1 || (maj === 1 && (min > 3 || (min === 3 && pat >= 5)))
+const d = bunPty ? describe : describe.skip
+const sleep = (ms: number): Promise<void> => new Promise(r => setTimeout(r, ms))
+
+d('deliverToHost (supervisor-socket delivery — bracketed paste + CR)', () => {
+  test('the child receives exactly: ESC[200~ <message> ESC[201~ CR', async () => {
+    const runDir = mkdtempSync(join(tmpdir(), 'iapeer-deliver-'))
+    const out = join(runDir, 'stdin.bin')
+    const msg = 'hello-deliver-❯'
+    const expected = `\x1b[200~${msg}\x1b[201~\r`
+    const n = Buffer.byteLength(expected, 'utf8')
+    try {
+      // probe child: raw mode (no line-discipline cooking), read exactly n bytes, dump to a file
+      const argv = ['sh', '-c', `stty raw -echo; head -c ${n} > '${out}'; sleep 5`]
+      const r = startSupervisorDaemon({ session: 'dlv', runtime: 'tick', runDir, serve: { argv, env: { PATH: process.env.PATH ?? '' }, cwd: runDir } })
+      expect(r.state).toBe('started')
+      await sleep(400) // let the probe reach raw mode
+      const res = await deliverToHost(runDir, 'dlv', msg)
+      expect(res.ok).toBe(true)
+      // wait for the child to have captured n bytes
+      const deadline = Date.now() + 3000
+      while (Date.now() < deadline && !(existsSync(out) && readFileSync(out).length >= n)) await sleep(50)
+      const got = existsSync(out) ? readFileSync(out) : Buffer.alloc(0)
+      expect(got.equals(Buffer.from(expected, 'utf8'))).toBe(true) // bracketed paste + CR, byte-exact
+    } finally {
+      try {
+        killSession(runDir, 'dlv')
+      } catch {
+        /* */
+      }
+      await sleep(300)
+      rmSync(runDir, { recursive: true, force: true })
+    }
+  })
+
+  test('no supervisor socket → a clean error, not a throw', async () => {
+    const runDir = mkdtempSync(join(tmpdir(), 'iapeer-deliver-none-'))
+    try {
+      const res = await deliverToHost(runDir, 'nope', 'x')
+      expect(res.ok).toBe(false)
+      expect(res.error).toContain('no supervisor socket')
+    } finally {
+      rmSync(runDir, { recursive: true, force: true })
+    }
+  })
+})