@agfpd/iapeer 0.2.64 → 0.2.65

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 })
+    }
+  })
+})

package/src/supervisor/deliver.ts

@@ -0,0 +1,120 @@
+// Supervisor DELIVER client (cutover Block 2 spawn-flip, Ф0a) — hands a message to a supervisor-
+// HOSTED session over its unix socket: the host equivalent of tmux load-buffer → paste-buffer -p →
+// send-keys Enter. @xterm-FREE BY CONSTRUCTION — imports ONLY protocol.ts (pure frames + the proven
+// BackpressureWriter) + paths.ts (no @xterm) — so launch can deliver to a hosted session WITHOUT
+// pulling the @xterm daemon into the hot path. Bracketed-paste wraps the message (same intent as
+// tmux paste-buffer -p: the TUI takes it as one atomic paste, not retyped keystrokes), then a CR
+// submits — the SAME two-step the cold/warm tmux delivery uses. Backpressure-safe: a multi-KB
+// envelope past the socket buffer is queued + flushed on drain, never truncated (the same failure
+// mode that staled heavy reattach — protocol.ts port-dep #2).
+import { BackpressureWriter, FRAME_DATA, frame } from './protocol.ts'
+import { sockPath } from './paths.ts'
+import { existsSync } from 'node:fs'
+
+const sleep = (ms: number): Promise<void> => new Promise(r => setTimeout(r, ms))
+
+export interface DeliverResult {
+  ok: boolean
+  error?: string
+}
+
+/** Deliver `message` to a hosted session over its supervisor socket: connect → bracketed-paste →
+ *  (settle) → CR → close. submitDelayMs mirrors the tmux boot delivery's 300 ms paste→Enter settle. */
+export async function deliverToHost(
+  runDir: string,
+  session: string,
+  message: string,
+  opts: { submitDelayMs?: number } = {},
+): Promise<DeliverResult> {
+  const sock = sockPath(runDir, session)
+  if (!existsSync(sock)) return { ok: false, error: `no supervisor socket for "${session}"` }
+  let conn: Awaited<ReturnType<typeof Bun.connect>> | undefined
+  let writer: BackpressureWriter | undefined
+  try {
+    conn = await Bun.connect({
+      unix: sock,
+      socket: {
+        drain() {
+          writer?.flush()
+        },
+        data() {
+          /* the daemon forwards screen output; the deliver client ignores it */
+        },
+        error() {
+          /* surfaced via the writer's dead state */
+        },
+        close() {
+          /* */
+        },
+      },
+    })
+    const c = conn
+    writer = new BackpressureWriter(b => c.write(b))
+    const paste = `\x1b[200~${message}\x1b[201~` // bracketed paste — atomic, like paste-buffer -p
+    if (!writer.send(frame(FRAME_DATA, Buffer.from(paste, 'utf8')))) return { ok: false, error: 'socket dead during paste' }
+    if (!(await drainFully(writer))) return { ok: false, error: 'paste not fully flushed (socket stalled)' }
+    await sleep(opts.submitDelayMs ?? 300)
+    if (!writer.send(frame(FRAME_DATA, Buffer.from('\r', 'utf8')))) return { ok: false, error: 'socket dead during submit' }
+    if (!(await drainFully(writer))) return { ok: false, error: 'submit not fully flushed (socket stalled)' }
+    await sleep(50) // let the CR land before we close the connection
+    return { ok: true }
+  } catch (e) {
+    return { ok: false, error: `deliver to host failed: ${(e as Error).message}` }
+  } finally {
+    try {
+      conn?.end()
+    } catch {
+      /* */
+    }
+  }
+}
+
+/** Wait until the writer's queued tail has flushed (drain-driven), or time out. */
+async function drainFully(writer: BackpressureWriter, timeoutMs = 4000): Promise<boolean> {
+  const end = Date.now() + timeoutMs
+  while (writer.queuedBytes > 0 && !writer.isDead && Date.now() < end) await sleep(20)
+  return writer.queuedBytes === 0 && !writer.isDead
+}
+
+/**
+ * Send raw CONTROL bytes to a hosted session over its supervisor socket — the host equivalent of
+ * `tmux send-keys` for the control channel (interrupt / compact). Each chunk is ALREADY the exact
+ * keystrokes (translated from the send-keys vocabulary by keysToBytes upstream), sent as a FRAME_DATA
+ * write — NOT bracketed-pasted and NOT auto-submitted: an Escape must arrive as a bare ESC, never a
+ * pasted literal. `stepDelayMs` paces a multi-step plan after each step, mirroring executeControl's
+ * tmux loop (e.g. compact's '/compact' then a 300 ms settle then Enter). Backpressure-safe per step.
+ */
+export async function sendControlToHost(
+  runDir: string,
+  session: string,
+  chunks: Buffer[],
+  opts: { stepDelayMs?: number } = {},
+): Promise<DeliverResult> {
+  const sock = sockPath(runDir, session)
+  if (!existsSync(sock)) return { ok: false, error: `no supervisor socket for "${session}"` }
+  let conn: Awaited<ReturnType<typeof Bun.connect>> | undefined
+  let writer: BackpressureWriter | undefined
+  try {
+    conn = await Bun.connect({
+      unix: sock,
+      socket: { drain() { writer?.flush() }, data() { /* */ }, error() { /* */ }, close() { /* */ } },
+    })
+    const c = conn
+    writer = new BackpressureWriter(b => c.write(b))
+    for (const chunk of chunks) {
+      if (!writer.send(frame(FRAME_DATA, chunk))) return { ok: false, error: 'socket dead during control send' }
+      if (!(await drainFully(writer))) return { ok: false, error: 'control not fully flushed (socket stalled)' }
+      if (opts.stepDelayMs) await sleep(opts.stepDelayMs)
+    }
+    await sleep(50) // let the last chunk land before we close the connection
+    return { ok: true }
+  } catch (e) {
+    return { ok: false, error: `control to host failed: ${(e as Error).message}` }
+  } finally {
+    try {
+      conn?.end()
+    } catch {
+      /* */
+    }
+  }
+}

package/src/supervisor/index.ts

@@ -5,16 +5,35 @@
 // 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 { existsSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync } from 'node:fs'
+import { existsSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
-import { runSupervisorDaemon } from './daemon.ts'
 import { runSupervisorClient, sessionAlive } from './client.ts'
-import { defaultRunDir, logPath, pidPath, sockPath } from './paths.ts'
+import { defaultRunDir, logPath, pidPath, servePath, sockPath } from './paths.ts'
 
-export { runSupervisorDaemon } from './daemon.ts'
+// daemon.ts loads @xterm. It is dynamic-imported ONLY in the 'daemon' CLI case below (the detached
+// daemon process, where @xterm belongs), so importing THIS module — e.g. launch resolving
+// startSupervisorDaemon to host a flag-on peer — never pulls @xterm into the launch hot path.
 export { runSupervisorClient, sessionAlive } from './client.ts'
 export { defaultRunDir, sockPath, pidPath } from './paths.ts'
 
+/** The composed invocation a detached daemon serves (slice b): buildLaunchInvocation output + the
+ *  resolved cwd. Serialized to `<runDir>/<session>.serve.json` (0600) so the detached daemon process
+ *  picks it up — the seam by which launch hands the supervisor a real session at the spawn-flip. */
+export interface ServeSpec {
+  argv: string[]
+  env: Record<string, string>
+  cwd: string
+  /** Pane-log path (slice c): `<logDir>/<identity>.log` — where the daemon appends the child's raw
+   *  output, byte-identical to tmux pipe-pane, so the observer/shadow read a served session's log. */
+  paneLogPath?: string
+  /** Exit-cause log (spawn-flip Ф0b): exits.log — the daemon appends the child's death cause here. */
+  exitLogPath?: string
+  /** Pty geometry (spawn-flip Ф0a): match the tmux launch's 220x50 so the served child + the pane-log
+   *  model render at the SAME size launch reads readiness at. Unset → daemon default (80x30). */
+  cols?: number
+  rows?: number
+}
+
 export interface StartDaemonOptions {
   session: string
   runtime: string
@@ -23,10 +42,24 @@ export interface StartDaemonOptions {
    *  `daemon <session> <runtime> --run-dir <runDir>` is appended. Serving-prod injects the
    *  installed-binary argv here. */
   daemonArgv?: string[]
+  /** Composed invocation to SERVE (slice b). When set, written to the serve-spec file before spawn so
+   *  the detached daemon serves it; absent → a bare conduit (throwaway/tick). */
+  serve?: ServeSpec
   /** Max ms to wait for the daemon socket+pid to appear (default 5000). */
   timeoutMs?: number
 }
 
+/** Read the serve-spec for a detached daemon, or undefined for a bare session. */
+function readServeSpec(runDir: string, session: string): ServeSpec | undefined {
+  try {
+    const s = JSON.parse(readFileSync(servePath(runDir, session), 'utf8')) as ServeSpec
+    if (Array.isArray(s.argv) && s.env && typeof s.cwd === 'string') return s
+  } catch {
+    /* no / invalid serve spec → bare session */
+  }
+  return undefined
+}
+
 export interface StartDaemonResult {
   state: 'started' | 'already-running' | 'failed'
   pid?: number
@@ -45,6 +78,15 @@ export function startSupervisorDaemon(opts: StartDaemonOptions): StartDaemonResu
   } catch {
     /* */
   }
+  // Serving seam (slice b): persist the composed invocation BEFORE spawn so the detached daemon serves
+  // it. 0600 — env may carry launch.env secrets. A stale spec from a prior run is overwritten or cleared.
+  if (opts.serve) writeFileSync(servePath(runDir, session), JSON.stringify(opts.serve), { mode: 0o600 })
+  else
+    try {
+      unlinkSync(servePath(runDir, session))
+    } catch {
+      /* no stale spec */
+    }
   const out = openSync(logPath(runDir, session), 'a')
   const argv = opts.daemonArgv ?? selfArgv()
   const child = nodeSpawn(argv[0]!, [...argv.slice(1), 'daemon', session, runtime, '--run-dir', runDir], {
@@ -59,6 +101,13 @@ export function startSupervisorDaemon(opts: StartDaemonOptions): StartDaemonResu
     }
     Bun.sleepSync(80)
   }
+  // Failed to come up — drop the serve-spec we wrote so it can't mislead a later read.
+  if (opts.serve)
+    try {
+      unlinkSync(servePath(runDir, session))
+    } catch {
+      /* */
+    }
   return { state: 'failed', detail: `daemon did not come up; see ${logPath(runDir, session)}` }
 }
 
@@ -96,13 +145,34 @@ export async function runSupervisorCli(argv: string[]): Promise<number> {
   const [cmd, a, b] = argv
   const runDir = runDirFrom(argv)
   switch (cmd) {
-    case 'daemon':
-      runSupervisorDaemon({ session: a!, runtime: b || 'claude', runDir })
+    case 'daemon': {
+      // Serving seam (slice b): a serve-spec → serve the launch-composed argv/env/cwd; else bare.
+      const serve = readServeSpec(runDir, a!)
+      // @xterm loads HERE — in the detached daemon process only (dynamic import keeps it out of any
+      // caller that merely resolves startSupervisorDaemon, e.g. the launch hot path).
+      const { runSupervisorDaemon } = await import('./daemon.ts')
+      runSupervisorDaemon({
+        session: a!,
+        runtime: b || 'claude',
+        runDir,
+        ...(serve
+          ? {
+              argv: serve.argv,
+              env: serve.env,
+              cwd: serve.cwd,
+              paneLogPath: serve.paneLogPath,
+              exitLogPath: serve.exitLogPath,
+              cols: serve.cols,
+              rows: serve.rows,
+            }
+          : {}),
+      })
       // The daemon is event-driven: runSupervisorDaemon RETURNS after wiring the pty + socket
       // server, and the event loop keeps the process alive. Await a never-resolving promise so the
       // caller's `process.exit` does NOT fire — shutdown() (child-exit / SIGTERM) owns the exit.
       await new Promise<never>(() => {})
       return 0 // unreachable
+    }
     case 'start': {
       const r = startSupervisorDaemon({ session: a!, runtime: b || 'claude', runDir })
       console.log(`${r.state}${r.pid ? ` pid=${r.pid}` : ''}${r.detail ? ` — ${r.detail}` : ''}: ${a}`)