@agfpd/iapeer 0.2.63 → 0.2.65

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

package/src/supervisor/panelog.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from 'bun:test'
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Terminal } from '@xterm/headless'
+import { modelToPlainText } from '../shadow/render.ts'
+import { killSession, startSupervisorDaemon } from './index.ts'
+
+// Slice c — the supervisor pane-log must be a drop-in for tmux pipe-pane: the SAME raw child bytes to
+// <identity>.log (so observer/shadow/readyGateViewport read a served session identically), AND a model
+// built from it must render what tmux's capture-pane shows. Live tmux + Bun-native pty → guarded.
+const tmuxAvailable = spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0
+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 = tmuxAvailable && bunPty ? describe : describe.skip
+
+const sleep = (ms: number): Promise<void> => new Promise(r => setTimeout(r, ms))
+const readBuf = (p: string): Buffer => (existsSync(p) ? readFileSync(p) : Buffer.alloc(0))
+const modelOf = (bytes: Buffer, cols: number, rows: number): Promise<string> => {
+  const t = new Terminal({ cols, rows, allowProposedApi: true, scrollback: 1000 })
+  return new Promise<string>(res => t.write(bytes, () => res(modelToPlainText(t, cols, rows))))
+}
+
+d('supervisor pane-log ≡ tmux pipe-pane', () => {
+  test('RAW-BYTE-IDENTITY: the same child yields byte-identical logs (LF/CRLF + multibyte + ANSI)', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'panelog-bp-'))
+    const tmuxSock = join(dir, 't.sock')
+    const logTmux = join(dir, 'tmux.log')
+    const logSup = join(dir, 'sup.log')
+    const runDir = join(dir, 'run')
+    // bare \n, \r\n, multibyte ❯ › … é (the latin1 grabli), ANSI SGR — the byte classes that diverge
+    const child = ['sh', '-c', `sleep 0.5; printf 'L1\\nL2\\r\\ng:❯›…é\\n\\033[31mRED\\033[0m\\nTAB\\tEND\\n'; sleep 1`]
+    try {
+      spawnSync('tmux', ['-S', tmuxSock, 'new-session', '-d', '-s', 'p', '-x', '80', '-y', '24', ...child], { stdio: 'ignore' })
+      spawnSync('tmux', ['-S', tmuxSock, 'pipe-pane', '-o', '-t', 'p', `cat >> '${logTmux}'`], { stdio: 'ignore' })
+      startSupervisorDaemon({ session: 'bp', runtime: 'tick', runDir, serve: { argv: child, env: { PATH: process.env.PATH ?? '' }, cwd: dir, paneLogPath: logSup } })
+      await sleep(2300) // both children: sleep .5 + emit + sleep 1 ≈ exit ~1.5s; tmux's cat EOF-flushes
+      const a = readBuf(logTmux)
+      const b = readBuf(logSup)
+      expect(b.length).toBeGreaterThan(0)
+      expect(b.equals(a)).toBe(true) // byte-for-byte — raw Buffer passthrough, shared onlcr default
+      expect(b.includes(Buffer.from('❯›…é', 'utf8'))).toBe(true) // multibyte survived (no latin1 re-encode)
+    } finally {
+      spawnSync('tmux', ['-S', tmuxSock, 'kill-server'], { stdio: 'ignore' })
+      try {
+        killSession(runDir, 'bp')
+      } catch {
+        /* */
+      }
+      await sleep(300)
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  test('BINDING: a model from the supervisor pane-log renders what tmux capture-pane shows', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'panelog-bind-'))
+    const tmuxSock = join(dir, 't.sock')
+    const logSup = join(dir, 'sup.log')
+    const runDir = join(dir, 'run')
+    const COLS = 80,
+      ROWS = 24
+    // a static frame (clear+home, three lines incl. the ❯ ready glyph), then idle so capture-pane sees it
+    const child = ['sh', '-c', `printf '\\033[2J\\033[HLine one\\r\\n  ❯ ready prompt\\r\\nthird line ok\\r\\n'; sleep 30`]
+    try {
+      spawnSync('tmux', ['-S', tmuxSock, 'new-session', '-d', '-s', 'b', '-x', String(COLS), '-y', String(ROWS), ...child], { stdio: 'ignore' })
+      startSupervisorDaemon({ session: 'bind', runtime: 'tick', runDir, serve: { argv: child, env: { PATH: process.env.PATH ?? '' }, cwd: dir, paneLogPath: logSup } })
+      // let the frame render in both
+      let cap = ''
+      for (let i = 0; i < 30 && !/❯ ready prompt/.test(cap); i++) {
+        await sleep(200)
+        cap = spawnSync('tmux', ['-S', tmuxSock, 'capture-pane', '-p', '-t', 'b'], { encoding: 'utf8' }).stdout || ''
+      }
+      const modelSup = await modelOf(readBuf(logSup), COLS, ROWS)
+      // tmux capture-pane render (its own emulator) == @xterm model of the SUPERVISOR's pane-log
+      const norm = (s: string): string =>
+        s
+          .split('\n')
+          .map(l => l.replace(/\s+$/, ''))
+          .join('\n')
+          .replace(/\n+$/, '')
+      expect(norm(modelSup)).toBe(norm(cap))
+      expect(modelSup).toContain('❯ ready prompt') // the ready glyph survived into the model
+    } finally {
+      spawnSync('tmux', ['-S', tmuxSock, 'kill-server'], { stdio: 'ignore' })
+      try {
+        killSession(runDir, 'bind')
+      } catch {
+        /* */
+      }
+      await sleep(300)
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/supervisor/paths.ts

@@ -12,3 +12,12 @@ export function defaultRunDir(env: NodeJS.ProcessEnv = process.env): string {
 export const sockPath = (runDir: string, session: string): string => join(runDir, `${session}.sock`)
 export const pidPath = (runDir: string, session: string): string => join(runDir, `${session}.pid`)
 export const logPath = (runDir: string, session: string): string => join(runDir, `${session}.log`)
+/** Serving spec (cutover Block 2 slice b): the composed {argv, env, cwd} a detached daemon serves.
+ *  Written 0600 by startSupervisorDaemon BEFORE spawn (env can carry launch.env secrets), read by
+ *  the daemon CLI entry, removed on shutdown. Absent → a bare throwaway/tick session. */
+export const servePath = (runDir: string, session: string): string => join(runDir, `${session}.serve.json`)
+/** Attached-client marker (spawn-flip Ф0b-3 slice 3c): present iff ≥1 supervisor client is attached.
+ *  The daemon maintains it on every client add/delete; the warm-deliver path (a DIFFERENT process)
+ *  reads it to gate the hosted busy-composer hold — never paste over a HUMAN's unfinished input, but
+ *  never hold for the AI's own composer output when no operator is attached. */
+export const attachedPath = (runDir: string, session: string): string => join(runDir, `${session}.attached`)

package/src/supervisor/protocol.test.ts

@@ -1,4 +1,8 @@
 import { describe, expect, test } from 'bun:test'
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import {
   BackpressureWriter,
   FRAME_DATA,
@@ -6,12 +10,15 @@ import {
   TERM_RESET,
   capabilityResponses,
   frame,
+  keysToBytes,
   makeFramer,
   parseSize,
   sizePayload,
   stripQueries,
 } from './protocol.ts'
 
+const tmuxAvailable = spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0
+
 describe('frame protocol', () => {
   test('frame() lays out [type][len:u32be][payload]', () => {
     const f = frame(FRAME_DATA, 'hi')
@@ -129,3 +136,87 @@ describe('BackpressureWriter (port-dep #2: the ~90 KB-over-8 KB truncation that
     expect(w.isDead).toBe(true)
   })
 })
+
+describe('keysToBytes (tmux send-keys vocabulary → pty bytes, the boot key-set)', () => {
+  test('Enter → CR (the trust/proceed dialogs)', () => {
+    expect(keysToBytes(['Enter'])).toEqual(Buffer.from('\r'))
+  })
+  test('codex update-decline [2,Enter] → "2" + CR', () => {
+    expect(keysToBytes(['2', 'Enter'])).toEqual(Buffer.from('2\r'))
+  })
+  test('codex hooks-review [Down,Enter] in NORMAL cursor mode → CSI-B + CR', () => {
+    expect(keysToBytes(['Down', 'Enter'])).toEqual(Buffer.from('\x1b[B\r'))
+  })
+  test('[Down,Enter] under DECCKM application-cursor mode → SS3-B + CR (the mode-sensitivity boris flagged)', () => {
+    expect(keysToBytes(['Down', 'Enter'], { appCursorKeys: true })).toEqual(Buffer.from('\x1bOB\r'))
+  })
+  test('claude resume-picker [Down] → cursor-down only', () => {
+    expect(keysToBytes(['Down'])).toEqual(Buffer.from('\x1b[B'))
+  })
+  test('literal mode -l sends the rest verbatim (executeControl /compact)', () => {
+    expect(keysToBytes(['-l', '/compact'])).toEqual(Buffer.from('/compact'))
+  })
+  test('Escape (interrupt) → ESC', () => {
+    expect(keysToBytes(['Escape'])).toEqual(Buffer.from('\x1b'))
+  })
+  test('an unknown token falls through to literal text', () => {
+    expect(keysToBytes(['hello'])).toEqual(Buffer.from('hello'))
+  })
+})
+
+// boris's acceptance bar: the translator must be BYTE-IDENTICAL to real `tmux send-keys` for the
+// key-set the adapters actually return — not a "looks right" table. We capture exactly what tmux
+// delivers to a pane (raw mode bypasses the line discipline so no CR↔NL cooking) and compare.
+// Guarded by tmuxAvailable (a clean CI runner has no tmux → these skip, per the live-tmux lesson).
+function tmuxSendKeysBytes(keys: string[], appCursor: boolean, n: number): Buffer {
+  const dir = mkdtempSync(join(tmpdir(), 'pts-keys-'))
+  const sock = join(dir, 's.sock')
+  const out = join(dir, 'out.bin')
+  // The pane program: optionally emit DECCKM (CSI ? 1 h) as its OWN output so tmux tracks
+  // application-cursor mode; then raw mode (capture send-keys bytes verbatim); then read exactly n
+  // bytes and exit (head flushes on exit — a buffered cat would lose the tail on kill).
+  const pre = appCursor ? `printf '\\033[?1h'; ` : ''
+  const paneCmd = `${pre}stty raw -echo; head -c ${n} > '${out}'`
+  try {
+    const create = spawnSync(
+      'tmux',
+      ['-S', sock, 'new-session', '-d', '-s', 'k', '-x', '80', '-y', '24', 'sh', '-c', paneCmd],
+      { stdio: 'ignore' },
+    )
+    if (create.status !== 0) throw new Error('tmux new-session failed')
+    Bun.sleepSync(400) // let the pane reach raw mode + tmux process the DECCKM output
+    spawnSync('tmux', ['-S', sock, 'send-keys', '-t', 'k', ...keys], { stdio: 'ignore' })
+    const deadline = Date.now() + 3000
+    while (Date.now() < deadline) {
+      if (existsSync(out) && statSync(out).size >= n) break
+      Bun.sleepSync(50)
+    }
+    return existsSync(out) ? readFileSync(out) : Buffer.alloc(0)
+  } finally {
+    spawnSync('tmux', ['-S', sock, 'kill-server'], { stdio: 'ignore' })
+    try {
+      rmSync(dir, { recursive: true, force: true })
+    } catch {
+      /* */
+    }
+  }
+}
+
+describe.if(tmuxAvailable)('keysToBytes byte-identity vs real tmux send-keys (live)', () => {
+  test('NORMAL cursor mode: [Down,Enter]', () => {
+    const ours = keysToBytes(['Down', 'Enter'])
+    expect(tmuxSendKeysBytes(['Down', 'Enter'], false, ours.length)).toEqual(ours)
+  })
+  test('DECCKM application-cursor mode: [Down,Enter] → SS3', () => {
+    const ours = keysToBytes(['Down', 'Enter'], { appCursorKeys: true })
+    expect(tmuxSendKeysBytes(['Down', 'Enter'], true, ours.length)).toEqual(ours)
+  })
+  test('literal digit + Enter: [2,Enter]', () => {
+    const ours = keysToBytes(['2', 'Enter'])
+    expect(tmuxSendKeysBytes(['2', 'Enter'], false, ours.length)).toEqual(ours)
+  })
+  test('bare Enter', () => {
+    const ours = keysToBytes(['Enter'])
+    expect(tmuxSendKeysBytes(['Enter'], false, ours.length)).toEqual(ours)
+  })
+})

package/src/supervisor/protocol.ts

@@ -70,6 +70,55 @@ export function stripQueries(s: string): string {
   return s.replace(QUERY_RE, '')
 }
 
+// ── key-name → pty bytes (boot-driver, serving slice a) ─────────────────────────
+// Translate a tmux send-keys-style key list into the raw bytes a pty expects, so the supervisor
+// boot-driver can answer startup dialogs (codex trust/update/hooks, claude trust/resume-picker) off
+// the MODEL exactly as the launch primitive answers them via `tmux send-keys`. PURE — the byte
+// output is unit-comparable to real `tmux send-keys` (the acceptance bar: byte-identity, not a
+// "looks right" table).
+//
+// tmux semantics mirrored for the vocabulary our RuntimeAdapters actually emit (bootDialogKeys /
+// permissionDialogKeys / executeControl): a leading `-l` switches to LITERAL mode (every following
+// token sent verbatim, no key-name lookup); otherwise each token is a KEY NAME when known, else
+// literal text. Cursor keys depend on DECCKM application-cursor-keys mode — `\x1b[B` (normal) vs
+// `\x1bOB` (application) — which tmux keys off the terminal mode and the caller reads from the
+// @xterm model (term.modes.applicationCursorKeysMode), passing it in `enc`. Both codex hooks-review
+// (`['Down','Enter']`) and the claude resume-picker (`['Down']`) put a cursor key in the boot set,
+// so the mode is load-bearing — a hardcoded `\x1b[B` would corrupt the key under DECCKM.
+
+export interface KeyEncoding {
+  /** DECCKM application-cursor-keys mode (CSI ? 1 h). When set, arrow keys use SS3 (ESC O x)
+   *  instead of CSI (ESC [ x), matching what tmux send-keys emits in that mode. */
+  appCursorKeys?: boolean
+}
+
+const NAMED_KEYS: Record<string, string> = {
+  Enter: '\r',
+  Escape: '\x1b',
+  Tab: '\t',
+  Space: ' ',
+  BSpace: '\x7f',
+}
+
+/** Translate `keys` (tmux send-keys vocabulary) to the pty byte stream. See section header. */
+export function keysToBytes(keys: string[], enc: KeyEncoding = {}): Buffer {
+  const cur: Record<string, string> = enc.appCursorKeys
+    ? { Up: '\x1bOA', Down: '\x1bOB', Right: '\x1bOC', Left: '\x1bOD' }
+    : { Up: '\x1b[A', Down: '\x1b[B', Right: '\x1b[C', Left: '\x1b[D' }
+  let literal = false
+  let out = ''
+  for (const k of keys) {
+    if (!literal && k === '-l') {
+      literal = true
+      continue
+    }
+    if (!literal && k in NAMED_KEYS) out += NAMED_KEYS[k]
+    else if (!literal && k in cur) out += cur[k]
+    else out += k
+  }
+  return Buffer.from(out, 'utf8')
+}
+
 // ── port-dep #1: terminal reset on every client exit path ───────────────────────
 // The child sets a STACK of app-modes on the live terminal (alt-screen, bracketed-paste,
 // focus-events, theme-update, ALL mouse tracking, kitty-keyboard, scroll-region, hidden cursor).

package/src/transport/composerQueue.test.ts

@@ -144,6 +144,36 @@ describe('createComposerDeliveryQueue', () => {
     expect(failed.join('\n')).toMatch(/vanished|replaced/)
   })
 
+  test('async-correctness: concurrent enqueue with ASYNC predicates → each delivered exactly once, no dup/loss (Ф0b-3 3c-2)', async () => {
+    // The host-aware refactor makes shouldQueue/hasHumanInput/deliver awaitable. Inject ASYNC seams
+    // (a real yield window) and fire concurrent enqueues — the FIFO + per-identity drain guard must
+    // still deliver each envelope EXACTLY once (no race-doubled, no race-lost).
+    let held = true
+    const delivered: string[] = []
+    const q = createComposerDeliveryQueue({
+      pollMs: 5,
+      forceTimeoutMs: 2000,
+      shouldQueue: async () => { await sleep(4); return true },
+      hasHumanInput: async () => { await sleep(2); return held },
+      sessionToken: () => 'session-1:pane-1',
+      sessionAlive: () => true,
+      deliver: async (_target, envelope) => { await sleep(1); delivered.push(envelope); return ok(undefined) },
+      notifyFailed: () => { /* */ },
+    })
+
+    const acks = await Promise.all([
+      q.tryEnqueue(args('msg-A')),
+      q.tryEnqueue(args('msg-B')),
+      q.tryEnqueue(args('msg-C')),
+    ])
+    expect(acks.every(a => a?.ok)).toBe(true)
+    await sleep(40)
+    expect(delivered).toEqual([]) // all three held while busy
+    held = false
+    await sleep(80)
+    expect(delivered.slice().sort()).toEqual(['msg-A', 'msg-B', 'msg-C']) // each ONCE — no dup, no loss
+  })
+
   test('daemon close/restart failAll re-fails every queued-but-undelivered envelope', async () => {
     const delivered: string[] = []
     const failed: string[] = []

package/src/transport/hostControl.test.ts

@@ -0,0 +1,87 @@
+// Spawn-flip cutover Block 2, Ф0b-2 slice 3 — host-aware in-session control (interrupt / compact).
+//
+// executeControlOnTarget becomes host-aware: a supervisor-HOSTED target has no `tmux send-keys`, so
+// each control plan step is translated to pty bytes by keysToBytes (REUSED from the boot-driver) and
+// sent over the supervisor socket. These suites cover the host branch hermetically (a seam injects the
+// host-detect + the socket control-send) — asserting the BYTE TRANSLATION + dispatch. The live
+// "interrupt really interrupts a hosted turn" effect is proven separately against a real hosted codex.
+import { describe, expect, test } from 'bun:test'
+import { executeControlOnTarget, type ControlHostSeam, type DeliveryTarget } from './index.ts'
+
+const hostedCodex: DeliveryTarget = {
+  runtime: 'codex',
+  personality: 'ptyx',
+  address: 'codex-ptyx',
+  socketPath: '/tmp/nonexistent-iap-test.sock',
+}
+
+interface Captured {
+  session: string
+  chunks: Buffer[]
+  stepDelayMs?: number
+}
+
+function capturingSeam(captured: Captured[]): ControlHostSeam {
+  return {
+    hostAlive: () => true,
+    sendControl: async (_runDir, session, chunks, opts) => {
+      captured.push({ session, chunks, stepDelayMs: opts.stepDelayMs })
+      return { ok: true }
+    },
+  }
+}
+
+describe('executeControlOnTarget — hosted control over the socket (slice 3)', () => {
+  test('interrupt → a single bare ESC byte (\\x1b), no step delay', async () => {
+    const cap: Captured[] = []
+    const r = await executeControlOnTarget(hostedCodex, { name: 'interrupt' }, capturingSeam(cap))
+    expect(r.ok).toBe(true)
+    expect(cap).toHaveLength(1)
+    expect(cap[0].session).toBe('codex-ptyx')
+    expect(cap[0].chunks.map(b => b.toString('latin1'))).toEqual(['\x1b'])
+    expect(cap[0].stepDelayMs).toBeUndefined()
+  })
+
+  test('compact → "/compact" literal then Enter (CR), with the 300ms step delay', async () => {
+    const cap: Captured[] = []
+    const r = await executeControlOnTarget(hostedCodex, { name: 'compact' }, capturingSeam(cap))
+    expect(r.ok).toBe(true)
+    expect(cap[0].chunks.map(b => b.toString('latin1'))).toEqual(['/compact', '\r'])
+    expect(cap[0].stepDelayMs).toBe(300)
+  })
+
+  test('flag-off (hostAlive=false) → the socket control-send is NEVER touched (tmux path)', async () => {
+    let sendCalls = 0
+    const seam: ControlHostSeam = {
+      hostAlive: () => false,
+      sendControl: async () => {
+        sendCalls++
+        return { ok: true }
+      },
+    }
+    // tmux send-keys will fail against the bogus socket — incidental; the contract is that flag-off
+    // never reaches the host branch.
+    await executeControlOnTarget(hostedCodex, { name: 'interrupt' }, seam)
+    expect(sendCalls).toBe(0)
+  })
+
+  test('socket control-send fails → loud error, no false ok', async () => {
+    const seam: ControlHostSeam = {
+      hostAlive: () => true,
+      sendControl: async () => ({ ok: false, error: 'socket dead during control send' }),
+    }
+    const r = await executeControlOnTarget(hostedCodex, { name: 'interrupt' }, seam)
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.error.message).toContain('hosted control "interrupt" failed')
+      expect(r.error.message).toContain('socket dead')
+    }
+  })
+
+  test('unsupported command for the runtime → explicit refusal (router runtime, no control plan)', async () => {
+    const router: DeliveryTarget = { runtime: 'telegram', personality: 'tg', address: 'telegram-tg', socketPath: '/tmp/x.sock' }
+    const r = await executeControlOnTarget(router, { name: 'interrupt' }, capturingSeam([]))
+    expect(r.ok).toBe(false)
+    if (!r.ok) expect(r.error.message).toContain('does not support control command')
+  })
+})