@agfpd/iapeer 0.2.64 → 0.2.66

package/src/launch/ptyHost.ts

@@ -0,0 +1,148 @@
+// Launch-side hosted-session orchestration (cutover Block 2 spawn-flip, Ф0a) — the supervisor-HOST
+// equivalent of the tmux bring-up half of launch(): start the session under the supervisor, wait for
+// readiness off its pane-log model (the supervisor's own boot-driver dismisses startup dialogs), and
+// deliver the first message over its socket. Flag-gated per-peer (.pty-host); when the flag is off
+// this module is never reached and launch is byte-identical (golden).
+//
+// @xterm STAYS OUT of the launch process by construction:
+//   - startSupervisorDaemon is dynamic-imported and @xterm-free (daemon.ts is deferred to the detached
+//     'daemon' subprocess) — it only SPAWNS the daemon, @xterm runs there;
+//   - the deliver client is a pure-protocol leaf (no @xterm);
+//   - sessionAlive comes from client.ts (no @xterm);
+//   - readiness reuses paneLogViewport, whose @xterm import is dynamic and only loads flag-on.
+import { existsSync, readFileSync } from 'node:fs'
+import { deliverToHost, type DeliverResult } from '../supervisor/deliver.ts'
+import { attachedPath, defaultRunDir, pidPath } from '../supervisor/paths.ts'
+import { sessionAlive as hostDaemonAlive } from '../supervisor/client.ts'
+import { killSession as killSupervisorSession } from '../supervisor/index.ts'
+import { paneLogViewport } from './readyGateModel.ts'
+import type { LaunchInvocation } from './invocation.ts'
+import type { RuntimeAdapter } from './types.ts'
+
+/** Match the tmux launch geometry (index.ts new-session -x 220 -y 50) so the served child + the
+ *  pane-log model render at the same size launch reads readiness at. */
+export const HOST_COLS = 220
+export const HOST_ROWS = 50
+
+/** Per-peer spawn-flip flag: marker `<logDir>/<identity>.pty-host`. Present → launch hosts the session
+ *  under the supervisor instead of `tmux new-session`. DISTINCT from `.pty-readygate` (the ready-gate
+ *  viewport-source flip): a readygate-flipped peer is still tmux-HOSTED and stays under observer
+ *  cross-check; only a `.pty-host` peer is supervisor-hosted (cross-check retires for it). */
+export function ptyHostEnabled(logDir: string, identity: string): boolean {
+  return existsSync(`${logDir}/${identity}.pty-host`)
+}
+
+/** The supervisor's run dir (session sockets/pids/serve-specs). Env-isolatable via IAPEER_ROOT. */
+export function hostRunDir(): string {
+  return defaultRunDir()
+}
+
+/**
+ * Is there a LIVE supervisor session for this identity? This is the RUNTIME-STATE host detector the
+ * warm surfaces (liveness / deliver / reap / attach / observer) route on — NOT the `.pty-host` marker.
+ * The marker is spawn-INTENT (read by launch at spawn); deriving warm routing from the live session
+ * means rolling the marker back (rm) on a STILL-RUNNING hosted session never tears it (rm affects only
+ * the NEXT spawn). Rollback of a RUNNING hosted session is therefore kill-then-rm, NOT rm-alone.
+ */
+export function hostSessionAlive(identity: string): boolean {
+  return hostDaemonAlive(hostRunDir(), identity)
+}
+
+/** Reap a hosted session: SIGTERM the supervisor daemon (its shutdown SIGKILLs the child + cleans up). */
+export function killPtyHost(identity: string): void {
+  killSupervisorSession(hostRunDir(), identity)
+}
+
+/**
+ * Is a HUMAN operator attached to this hosted session right now? (spawn-flip Ф0b-3 slice 3c). The
+ * supervisor daemon maintains a `.attached` marker present iff ≥1 client is connected (synced on every
+ * client add/detach incl. abnormal close/error/drain, and cleared on daemon start so a crashed
+ * predecessor's stale marker never lies). The warm-deliver busy-composer hold gates on THIS: hold for
+ * a human's unfinished composer input, but NEVER for the AI's own composer output when no one is
+ * attached. The host equivalent of `hasAttachedTmuxClient`.
+ */
+export function hasAttachedSupervisorClient(identity: string): boolean {
+  return existsSync(attachedPath(hostRunDir(), identity))
+}
+
+/**
+ * A session-REPLACEMENT token for a hosted session (spawn-flip Ф0b-3 slice 3c): the supervisor
+ * daemon's pid. A `/new` or restart spawns a NEW daemon (new pid), so a message queued against the old
+ * session FAILS rather than landing in a fresh same-named session — the host equivalent of the tmux
+ * `session_id:pane_id` token. null when no daemon pid is readable.
+ */
+export function hostSessionToken(identity: string): string | null {
+  try {
+    const pid = readFileSync(pidPath(hostRunDir(), identity), 'utf8').trim()
+    return pid ? `host:${pid}` : null
+  } catch {
+    return null
+  }
+}
+
+export interface HostStartResult {
+  ok: boolean
+  error?: string
+}
+
+/**
+ * Bring up the hosted session: start a detached supervisor daemon serving the composed invocation
+ * (argv+env from buildLaunchInvocation), writing the pane-log at `paneLogPath`. Returns ok/fail so
+ * launch can fall back to `tmux new-session` on failure (the unconditional spawn-fallback — a flipped
+ * peer is never worse than tmux ON SPAWN).
+ */
+export async function startPtyHost(b: {
+  identity: string
+  runtime: string
+  cwd: string
+  paneLogPath: string
+  exitLogPath?: string
+  invocation: LaunchInvocation
+}): Promise<HostStartResult> {
+  try {
+    const { startSupervisorDaemon } = await import('../supervisor/index.ts')
+    const r = startSupervisorDaemon({
+      session: b.identity,
+      runtime: b.runtime,
+      runDir: hostRunDir(),
+      serve: {
+        argv: b.invocation.argv,
+        env: b.invocation.env as Record<string, string>,
+        cwd: b.cwd,
+        paneLogPath: b.paneLogPath,
+        exitLogPath: b.exitLogPath,
+        cols: HOST_COLS,
+        rows: HOST_ROWS,
+      },
+    })
+    return r.state === 'failed' ? { ok: false, error: r.detail ?? 'supervisor host failed to come up' } : { ok: true }
+  } catch (e) {
+    return { ok: false, error: `pty-host bringup threw: ${(e as Error).message}` }
+  }
+}
+
+/**
+ * Wait for the hosted input surface to be ready: poll the pane-log model and run the adapter's
+ * isInputReady (the supervisor's boot-driver answers dialogs internally, so launch does NOT drive
+ * them). Returns true when ready, false on deadline / session death. Mirrors the tmux boot loop's
+ * 2 s cadence + bootDeadline.
+ */
+export async function waitHostReady(
+  b: { identity: string; logDir: string; adapter: RuntimeAdapter; bootDeadlineSecs: number },
+  sleep: (ms: number) => Promise<void>,
+): Promise<boolean> {
+  const log = `${b.logDir}/${b.identity}.log`
+  const iters = Math.max(1, Math.ceil(b.bootDeadlineSecs / 2))
+  for (let i = 0; i < iters; i++) {
+    await sleep(2000)
+    if (!hostSessionAlive(b.identity)) return false
+    const view = await paneLogViewport(log, HOST_COLS, HOST_ROWS)
+    if (view && b.adapter.isInputReady(view)) return true
+  }
+  return false
+}
+
+/** Deliver the first/next message to the hosted session over its supervisor socket. */
+export function deliverHosted(identity: string, message: string): Promise<DeliverResult> {
+  return deliverToHost(hostRunDir(), identity, message)
+}

package/src/launch/readyGateModel.ts

@@ -21,6 +21,7 @@
 
 import { appendFileSync, closeSync, existsSync, fstatSync, openSync, readSync } from 'node:fs'
 import { join } from 'node:path'
+import type { Terminal } from '@xterm/headless' // TYPE-ONLY (erased) — the runtime @xterm load is the dynamic import below
 
 const SEED_BYTES = 4 * 1024 * 1024
 
@@ -76,24 +77,64 @@ export interface ReadyGateViewportOpts {
 export async function readyGateViewport(opts: ReadyGateViewportOpts): Promise<string> {
   if (!readyGatePtyFlipEnabled(opts.logDir, opts.identity)) return opts.fallback
   if (!(opts.cols > 0 && opts.rows > 0)) return opts.fallback
-  const log = `${opts.logDir}/${opts.identity}.log`
-  if (!existsSync(log)) return opts.fallback
+  const view = await paneLogViewport(`${opts.logDir}/${opts.identity}.log`, opts.cols, opts.rows)
+  return view ?? opts.fallback // tmux-fallback is unconditional — never worse than today
+}
+
+/**
+ * Read a pane-log's tail into a headless @xterm and render the viewport as plain text — the SAME
+ * 0-divergence-validated model the ready-gate flip uses, shared with the spawn-flip hosted path (a
+ * supervisor-HOSTED session has no capture-pane, so its pane-log model is the ONLY readiness source).
+ * @xterm is dynamic-imported here so a flag-off launch never loads it. Returns null on any failure
+ * (unreadable/short log, @xterm hiccup) — the caller decides the fallback (capture-pane for the
+ * readygate flip; a retry/fail for hosted).
+ */
+async function loadPaneLogModel(log: string, cols: number, rows: number): Promise<Terminal | null> {
+  if (!(cols > 0 && rows > 0) || !existsSync(log)) return null
   try {
     const { Terminal } = await import('@xterm/headless')
-    const { modelToPlainText } = await import('../shadow/index.ts')
     const fd = openSync(log, 'r')
     try {
       const sz = fstatSync(fd).size
       const off = Math.max(0, sz - SEED_BYTES)
       const buf = Buffer.alloc(sz - off)
       readSync(fd, buf, 0, buf.length, off)
-      const term = new Terminal({ cols: opts.cols, rows: opts.rows, allowProposedApi: true, scrollback: 3000 })
+      const term = new Terminal({ cols, rows, allowProposedApi: true, scrollback: 3000 })
       await new Promise<void>(res => term.write(buf, () => res()))
-      return modelToPlainText(term, opts.cols, opts.rows)
+      return term
     } finally {
       closeSync(fd)
     }
   } catch {
-    return opts.fallback // tmux-fallback is unconditional — never worse than today
+    return null
   }
 }
+
+export async function paneLogViewport(log: string, cols: number, rows: number): Promise<string | null> {
+  const term = await loadPaneLogModel(log, cols, rows)
+  if (!term) return null
+  const { modelToPlainText } = await import('../shadow/render.ts')
+  return modelToPlainText(term, cols, rows)
+}
+
+/**
+ * Spawn-flip Ф0b-2 hosted composer-occupancy guard (slice 2): does the hosted session's composer hold
+ * human input? Reads the pane-log model — the SAME raw child bytes tmux renders — and runs the burn-in-
+ * validated `composerOccupancyFromModel` (REUSED, not reimplemented). The hosted equivalent of
+ * `targetComposerBlocksDelivery`'s capture-pane occupancy. @xterm loads dynamically here (flag-on
+ * hosted only; the leaf `composerOccupancyFromModel` import is type-only at runtime, so the warm path
+ * stays @xterm-free with the flip off). UNCERTAINTY → BUSY (true): a model-build failure mirrors the
+ * tmux predicate's capture-fail-is-busy stance — prefer a false-busy hold over a false-free paste into
+ * a human composer.
+ *
+ * NB (sequence, boris): this is the DETECTION primitive. The end-to-end gate (attached-supervisor-
+ * client + enqueue + host-aware drain) lands with the attach client in Ф0b-3 — until a human can
+ * attach to a hosted session there is no human composer to protect. The caller composes the pane-log
+ * path from logDir+identity (the threaded `logDir` finding), mirroring `waitHostReady`.
+ */
+export async function paneLogComposerOccupied(log: string, cols: number, rows: number, runtime: string): Promise<boolean> {
+  const term = await loadPaneLogModel(log, cols, rows)
+  if (!term) return true // uncertainty → busy: never paste into a maybe-occupied composer
+  const { composerOccupancyFromModel } = await import('../shadow/render.ts')
+  return composerOccupancyFromModel(term, cols, rows, runtime)
+}

package/src/lifecycle/index.ts

@@ -48,6 +48,7 @@ import {
 } from '../launch/index.ts'
 import { composeSystemPrompt, gatherPromptInput } from '../launch/composeSystemPrompt.ts'
 import { dismissCanary, ensureServerCanary, signalCanaryClean } from '../launch/canary.ts'
+import { hostSessionAlive, killPtyHost } from '../launch/ptyHost.ts'
 import { appendLifecycleEvent, superviseLogVerbose } from './eventlog.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -650,7 +651,12 @@ function tmux(sock: string, ...args: string[]): { ok: boolean; out: string; err:
   return { ok: r.status === 0, out: r.stdout ?? '', err: r.stderr ?? '' }
 }
 function sessionAlive(sock: string, identity: string): boolean {
-  return tmux(sock, 'has-session', '-t', identity).ok
+  // RUNTIME-STATE host detection (spawn-flip Ф0b), NOT the `.pty-host` marker: a peer with a LIVE
+  // supervisor session is hosted-and-alive; otherwise fall to tmux has-session. Routing liveness on
+  // the live supervisor session (not the spawn-intent marker) makes a marker rollback safe on a
+  // still-running hosted session — rm-marker only changes the NEXT spawn, never the running routing.
+  // Non-hosted peers: hostSessionAlive is a cheap pid-file miss → identical result to today (tmux).
+  return hostSessionAlive(identity) || tmux(sock, 'has-session', '-t', identity).ok
 }
 
 /** Death-class tag for a gone session (live case: iapeer-memory 10.06 — the WHOLE
@@ -1049,6 +1055,10 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
 // ─────────────────────────────────────────────────────────────────────────────
 
 export function killSession(sock: string, identity: string): void {
+  // Hosted peer (spawn-flip Ф0b): SIGTERM the supervisor daemon — its shutdown SIGKILLs the child and
+  // removes the sock/pid/serve-spec. The tmux teardown below is then a harmless no-op (no tmux session
+  // on this sock); for a non-hosted peer it is the real reap, byte-identical to today.
+  if (hostSessionAlive(identity)) killPtyHost(identity)
   tmux(sock, 'kill-session', '-t', identity)
   const sessions = tmux(sock, 'list-sessions', '-F', '#{session_name}').out
   if (!sessions.trim()) {

package/src/shadow/enumerate-skip.test.ts

@@ -0,0 +1,65 @@
+// Spawn-flip cutover Block 2, Ф0b-3 slice 3b — the fidelity observer SKIPS supervisor-hosted peers.
+//
+// The observer compares the pty-model vs LIVE TMUX. A `.pty-host`-designated peer has no tmux to
+// compare against, and during a flip a lingering tmux socket for it would surface FALSE divergences.
+// This proves the explicit skip fires IN enumerate even in that race (a live tmux session + a pane-log
+// present): the marked peer is NOT enrolled, while an unmarked sibling IS. Real-tmux, guarded (a clean
+// CI runner has no tmux; the release machine has it — same pattern as routesend-wake).
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { spawnSync } from 'node:child_process'
+import { closeSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { buildSocketPath } from '../core/socket.ts'
+import { enumerate } from './index.ts'
+
+const tmuxAvailable = spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0
+
+let sockDir: string
+let logDir: string
+const KEEP = 'keepobs' // unmarked → observed
+const SKIP = 'skipobs' // .pty-host marker → skipped
+const addrOf = (p: string) => `codex-${p}`
+const sockOf = (p: string) => buildSocketPath('codex', p, sockDir)
+
+function startTmux(personality: string): void {
+  const r = spawnSync(
+    'tmux',
+    ['-S', sockOf(personality), 'new-session', '-d', '-x', '80', '-y', '24', '-s', addrOf(personality), 'cat'],
+    { encoding: 'utf8' },
+  )
+  if (r.status !== 0) throw new Error(`tmux new-session failed: ${r.stderr}`)
+}
+function killTmux(personality: string): void {
+  spawnSync('tmux', ['-S', sockOf(personality), 'kill-server'], { stdio: 'ignore' })
+}
+
+beforeAll(() => {
+  sockDir = mkdtempSync(join(tmpdir(), 'iapeer-obs-sock-'))
+  logDir = mkdtempSync(join(tmpdir(), 'iapeer-obs-log-'))
+  if (!tmuxAvailable) return
+  // Both peers: a live tmux session + a pane-log (so enrolment is otherwise satisfied).
+  for (const p of [KEEP, SKIP]) {
+    startTmux(p)
+    writeFileSync(join(logDir, `${addrOf(p)}.log`), '')
+  }
+  // SKIP additionally carries the `.pty-host` designation — even WITH a live tmux session, the observer
+  // must not enroll it (the flip-transition race the skip guards against).
+  writeFileSync(join(logDir, `${addrOf(SKIP)}.pty-host`), '')
+})
+
+afterAll(() => {
+  if (tmuxAvailable) for (const p of [KEEP, SKIP]) killTmux(p)
+  rmSync(sockDir, { recursive: true, force: true })
+  rmSync(logDir, { recursive: true, force: true })
+})
+
+describe.if(tmuxAvailable)('observer enumerate skips supervisor-hosted (.pty-host) peers', () => {
+  test('a .pty-host peer is NOT enrolled even with a live tmux session + pane-log; an unmarked one IS', () => {
+    const models = new Map<string, any>()
+    enumerate(models, { sockDir, logDir, eventLogDir: logDir })
+    expect(models.has(addrOf(KEEP))).toBe(true) // unmarked → observed (live tmux + log present)
+    expect(models.has(addrOf(SKIP))).toBe(false) // .pty-host designation → skipped despite live tmux
+    for (const o of models.values()) { try { if (o.fd != null) closeSync(o.fd) } catch { /* */ } }
+  })
+})

package/src/shadow/index.ts

@@ -17,50 +17,20 @@ import { openSync, closeSync, fstatSync, readSync, existsSync, appendFileSync, w
 import { join } from 'node:path'
 import { tmux, composerCaptureHasHumanInput, listOnlinePeers } from '../transport/index.ts'
 import { getAdapter } from '../launch/index.ts'
+import { ptyHostEnabled } from '../launch/ptyHost.ts' // spawn-flip Ф0b-3: the observer skips supervisor-hosted peers
 import { buildSocketPath, buildProcessAddress } from '../core/socket.ts'
 import type { Runtime } from '../core/constants.ts'
 import { GateTracker, classifyDirection, evaluateReadyGateFlipEligibility, VERDICTS } from './gate.ts'
+// modelToPlainText lives in the leaf render.ts (shared with readyGateModel + the supervisor
+// boot-driver); re-exported here so existing importers of './index.ts' keep resolving.
+import { composerOccupancyFromModel, modelToPlainText } from './render.ts'
+export { composerOccupancyFromModel, modelToPlainText }
 
 const SEED_BYTES = 4 * 1024 * 1024
-const promptGlyph = (rt: string): string => (rt === 'claude' ? '❯' : '›')
 const pidAlive = (pid: number): boolean => {
   try { process.kill(pid, 0); return true } catch (e) { return (e as NodeJS.ErrnoException).code === 'EPERM' }
 }
 
-/** PTY composer-occupancy verdict: getCell on the model's viewport composer row (the row whose
- *  first visible cell is the prompt glyph); human input = a non-ghost (non-dim, non-grey246)
- *  visible cell after it. Mirrors composerCaptureHasHumanInput — validated 0-divergence vs it. */
-export function composerOccupancyFromModel(term: Terminal, cols: number, rows: number, runtime: string): boolean {
-  const b = term.buffer.active, top = b.baseY, bot = b.baseY + rows, g = promptGlyph(runtime)
-  let py = -1, px = -1
-  for (let y = top; y < bot; y++) {
-    const l = b.getLine(y); if (!l) continue
-    let fx = -1
-    for (let x = 0; x < cols; x++) { if ((l.getCell(x)?.getChars() || ' ').trim() !== '') { fx = x; break } }
-    if (fx < 0) continue
-    if (l.getCell(fx)!.getChars() === g) { py = y; px = fx }
-  }
-  if (py < 0) return false
-  const l = b.getLine(py)!
-  for (let x = px + 1; x < cols; x++) {
-    const c = l.getCell(x); if ((c?.getChars() || ' ').trim() === '') continue
-    if (!(c!.isDim() || (c!.isFgPalette() && c!.getFgColor() === 246))) return true
-  }
-  return false
-}
-
-/** The model's viewport as PLAIN text (mimics `capture-pane -p`, the input isInputReady takes). */
-export function modelToPlainText(term: Terminal, cols: number, rows: number): string {
-  const b = term.buffer.active, lines: string[] = []
-  for (let y = b.baseY; y < b.baseY + rows; y++) {
-    const l = b.getLine(y); if (!l) { lines.push(''); continue }
-    let s = ''
-    for (let x = 0; x < cols; x++) s += l.getCell(x)?.getChars() || ' '
-    lines.push(s.replace(/\s+$/, ''))
-  }
-  return lines.join('\n')
-}
-
 interface Obs { addr: string; sock: string; runtime: Runtime; cols: number; rows: number; term: Terminal; fd: number; offset: number }
 
 export interface ShadowOptions {
@@ -84,12 +54,18 @@ function feed(o: Obs): Promise<number> {
   return new Promise(res => o.term.write(buf, () => res(buf.length)))
 }
 
-function enumerate(models: Map<string, Obs>, opts: ShadowOptions, tracker?: GateTracker): void {
+export function enumerate(models: Map<string, Obs>, opts: ShadowOptions, tracker?: GateTracker): void {
   let peers: { runtime: Runtime; personality: string }[] = []
   try { peers = listOnlinePeers(opts.sockDir).filter(p => p.runtime === 'claude' || p.runtime === 'codex') } catch { return }
   const live = new Set<string>()
   for (const p of peers) {
-    const addr = buildProcessAddress(p.runtime, p.personality); live.add(addr)
+    const addr = buildProcessAddress(p.runtime, p.personality)
+    // SPAWN-FLIP Ф0b-3: NEVER measure a supervisor-HOSTED peer. The observer's premise is pty-model vs
+    // LIVE TMUX; a `.pty-host`-designated peer has no tmux to compare against, and during a flip a
+    // lingering tmux socket for it would surface false divergences. Skip by the migration DESIGNATION
+    // (marker), BEFORE `live` — a peer flipped while enrolled then falls out of `live` and is reaped.
+    if (ptyHostEnabled(opts.logDir, addr)) continue
+    live.add(addr)
     if (models.has(addr)) continue
     try {
       const sock = buildSocketPath(p.runtime, p.personality, opts.sockDir)

package/src/shadow/render.ts

@@ -0,0 +1,60 @@
+// Leaf render helper: @xterm model → plain text. Extracted from shadow/index.ts so consumers
+// (the shadow observer, the Ф1 ready-gate flip, and the Block-2 supervisor boot-driver) share ONE
+// definition without importing the observer's transport/launch graph. Type-only @xterm import →
+// no runtime dependency beyond the Terminal instance the caller already holds; hermetically testable.
+import type { Terminal } from '@xterm/headless'
+
+/**
+ * The model's VISIBLE viewport (baseY..baseY+rows) as PLAIN text — mimics `tmux capture-pane -p`,
+ * the surface the runtime adapters' pane predicates (isInputReady / bootDialogKeys) take. Trailing
+ * whitespace per line is trimmed (capture-pane does the same), cells coalesced left-to-right.
+ *
+ * 0-divergence-validated vs capture-pane on READY screens by the ready-gate burn-in; the supervisor
+ * boot-driver additionally validates it on BOOT-DIALOG screens (a different screen state the
+ * ready-gate observation never saw).
+ */
+export function modelToPlainText(term: Terminal, cols: number, rows: number): string {
+  const b = term.buffer.active,
+    lines: string[] = []
+  for (let y = b.baseY; y < b.baseY + rows; y++) {
+    const l = b.getLine(y)
+    if (!l) {
+      lines.push('')
+      continue
+    }
+    let s = ''
+    for (let x = 0; x < cols; x++) s += l.getCell(x)?.getChars() || ' '
+    lines.push(s.replace(/\s+$/, ''))
+  }
+  return lines.join('\n')
+}
+
+const promptGlyph = (rt: string): string => (rt === 'claude' ? '❯' : '›')
+
+/**
+ * PTY composer-occupancy verdict: getCell on the model's viewport composer row (the row whose first
+ * visible cell is the prompt glyph); human input = a non-ghost (non-dim, non-grey246) visible cell
+ * after it. Mirrors composerCaptureHasHumanInput — validated 0-divergence vs it by the burn-in. Lives
+ * in this leaf (type-only @xterm) so the spawn-flip hosted occupancy guard can reuse it WITHOUT
+ * pulling the @xterm-loading observer graph into the warm-deliver path; the Terminal instance is
+ * built by the caller (paneLogComposerOccupied dynamic-imports @xterm). Re-exported from
+ * shadow/index.ts so the observer's existing importers keep resolving.
+ */
+export function composerOccupancyFromModel(term: Terminal, cols: number, rows: number, runtime: string): boolean {
+  const b = term.buffer.active, top = b.baseY, bot = b.baseY + rows, g = promptGlyph(runtime)
+  let py = -1, px = -1
+  for (let y = top; y < bot; y++) {
+    const l = b.getLine(y); if (!l) continue
+    let fx = -1
+    for (let x = 0; x < cols; x++) { if ((l.getCell(x)?.getChars() || ' ').trim() !== '') { fx = x; break } }
+    if (fx < 0) continue
+    if (l.getCell(fx)!.getChars() === g) { py = y; px = fx }
+  }
+  if (py < 0) return false
+  const l = b.getLine(py)!
+  for (let x = px + 1; x < cols; x++) {
+    const c = l.getCell(x); if ((c?.getChars() || ' ').trim() === '') continue
+    if (!(c!.isDim() || (c!.isFgPalette() && c!.getFgColor() === 246))) return true
+  }
+  return false
+}

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