@agfpd/iapeer 0.2.63 → 0.2.65

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.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { logReadyGateCrossCheck, readyGatePtyFlipEnabled, readyGateViewport } from './readyGateModel.ts'
+
+// The Ф1 ready-gate source swap is DARK by default and falls back to capture-pane UNCONDITIONALLY,
+// so the flip can never make readiness worse than tmux today. These prove exactly that contract.
+const tmps: string[] = []
+const mkLogDir = (): string => {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-rgm-'))
+  tmps.push(d)
+  return d
+}
+afterEach(() => {
+  while (tmps.length) rmSync(tmps.pop()!, { recursive: true, force: true })
+})
+const FALLBACK = '<<capture-pane-fallback>>'
+
+describe('readyGatePtyFlipEnabled (per-peer flip flag, canary-first)', () => {
+  test('absent marker → off; present marker → on', () => {
+    const d = mkLogDir()
+    expect(readyGatePtyFlipEnabled(d, 'codex-x')).toBe(false)
+    writeFileSync(join(d, 'codex-x.pty-readygate'), '')
+    expect(readyGatePtyFlipEnabled(d, 'codex-x')).toBe(true)
+  })
+})
+
+describe('readyGateViewport (Ф1 viewport-source swap, tmux-fallback)', () => {
+  test('flag OFF → the capture-pane fallback VERBATIM (byte-identical to today, no model built)', async () => {
+    const d = mkLogDir()
+    expect(await readyGateViewport({ logDir: d, identity: 'codex-x', fallback: FALLBACK, cols: 80, rows: 24 })).toBe(FALLBACK)
+  })
+
+  test('flag ON + a pane-log → the MODEL viewport (source swapped), not the fallback', async () => {
+    const d = mkLogDir()
+    writeFileSync(join(d, 'codex-x.pty-readygate'), '')
+    writeFileSync(join(d, 'codex-x.log'), '\x1b[24;1H› ready prompt here') // render a codex '›' prompt row
+    const v = await readyGateViewport({ logDir: d, identity: 'codex-x', fallback: FALLBACK, cols: 80, rows: 24 })
+    expect(v).not.toBe(FALLBACK) // the source was swapped to the model
+    expect(v).toContain('› ready prompt here') // the model rendered the prompt the predicate keys on
+  })
+
+  test('flag ON but the pane-log is MISSING → fallback (never worse than tmux)', async () => {
+    const d = mkLogDir()
+    writeFileSync(join(d, 'codex-x.pty-readygate'), '')
+    expect(await readyGateViewport({ logDir: d, identity: 'codex-x', fallback: FALLBACK, cols: 80, rows: 24 })).toBe(FALLBACK)
+  })
+
+  test('flag ON but geometry is unknown (0x0) → fallback', async () => {
+    const d = mkLogDir()
+    writeFileSync(join(d, 'codex-x.pty-readygate'), '')
+    writeFileSync(join(d, 'codex-x.log'), '\x1b[24;1H› ready')
+    expect(await readyGateViewport({ logDir: d, identity: 'codex-x', fallback: FALLBACK, cols: 0, rows: 0 })).toBe(FALLBACK)
+  })
+})
+
+describe('logReadyGateCrossCheck (serving-path soak observability)', () => {
+  test('appends a record with diverged computed; agreement → false, mismatch → true', () => {
+    const d = mkLogDir()
+    logReadyGateCrossCheck(d, { identity: 'codex-x', modelReady: true, captureReady: false, geom: '220x50', nowISO: '2026-06-14T00:00:00Z' })
+    logReadyGateCrossCheck(d, { identity: 'codex-x', modelReady: true, captureReady: true, geom: '220x50', nowISO: '2026-06-14T00:00:05Z' })
+    const lines = readFileSync(join(d, 'readygate-flip.jsonl'), 'utf8').trim().split('\n').map(l => JSON.parse(l))
+    expect(lines[0].diverged).toBe(true) // model ahead of capture
+    expect(lines[0].modelReady).toBe(true)
+    expect(lines[0].captureReady).toBe(false)
+    expect(lines[1].diverged).toBe(false) // agreement
+  })
+  test('no event-log dir → no-op (never blocks the ready-gate)', () => {
+    expect(() => logReadyGateCrossCheck(undefined, { identity: 'x', modelReady: true, captureReady: true, geom: '1x1', nowISO: 't' })).not.toThrow()
+  })
+})

package/src/launch/readyGateModel.ts

@@ -0,0 +1,140 @@
+// Ф1 READY-GATE viewport-source FLIP (cutover Block 3) — DARK / flag-gated, canary-first.
+//
+// The cold-wake ready-gate (launch index.ts step 6) decides "is the input surface ready?" by
+// running adapter.isInputReady on a VIEWPORT. Today that viewport is a `tmux capture-pane` scrape.
+// This is the FIRST migration mutation: swap the viewport SOURCE to the pty-MODEL (an @xterm/headless
+// emulation of the daemon's pane-log — the SAME raw child bytes tmux renders), keeping the SAME
+// production predicate (adapter.isInputReady) and an UNCONDITIONAL capture-pane fallback.
+//
+// Why this is low-radius (boris's frame): it is a viewport-SOURCE swap, NOT a predicate change.
+// The model verdict was validated 0-divergence vs capture-pane on the readiness predicate by the
+// burn-in gate (incl. the codex resume-with-history splash-off-screen center cell) before any peer
+// is flipped. It touches ONLY the isInputReady INPUT — dialog detection upstream and the delivery +
+// delivery-confirm downstream (submitIntoTui's submit-landed + deliverViaTmux's transcript-mtime
+// advance, the "real model advancement" final-arbiter) are untouched, so the canonical
+// harmless-false-glyph property is preserved by construction.
+//
+// FLAG: a per-peer marker `<logDir>/<identity>.pty-readygate`. Absent → capture-pane (byte-identical
+// to today). Present → the model viewport. Per-peer so the first flip is a single canary with the
+// whole fleet still on tmux; dynamic (touch/rm, no daemon restart). @xterm is dynamic-imported ONLY
+// when the flag is set, so the launch hot path stays @xterm-free with the flip off.
+
+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
+
+/**
+ * SERVING-path cross-check log (the post-flip soak gate). When a peer is flipped, the MODEL verdict
+ * is AUTHORITATIVE in the cold-wake ready-gate; this records, per evaluation, what capture-pane WOULD
+ * have said — so a soak can prove 0 model-vs-capture divergence IN THE SERVING PATH (the read-only
+ * burn-in measures continuously but never drove the actual ready decision). Append-only jsonl under
+ * the event-log dir. Best-effort: a log hiccup never affects the ready decision. No-op without a dir.
+ */
+export function logReadyGateCrossCheck(
+  eventLogDir: string | undefined,
+  rec: { identity: string; modelReady: boolean; captureReady: boolean; geom: string; nowISO: string },
+): void {
+  if (!eventLogDir) return
+  try {
+    appendFileSync(
+      join(eventLogDir, 'readygate-flip.jsonl'),
+      JSON.stringify({
+        ts: rec.nowISO,
+        identity: rec.identity,
+        modelReady: rec.modelReady,
+        captureReady: rec.captureReady,
+        diverged: rec.modelReady !== rec.captureReady,
+        geom: rec.geom,
+      }) + '\n',
+    )
+  } catch {
+    /* observability only — never block the ready-gate */
+  }
+}
+
+/** Per-peer ready-gate flip flag: the marker `<logDir>/<identity>.pty-readygate`. */
+export function readyGatePtyFlipEnabled(logDir: string, identity: string): boolean {
+  return existsSync(`${logDir}/${identity}.pty-readygate`)
+}
+
+export interface ReadyGateViewportOpts {
+  logDir: string
+  identity: string
+  /** The capture-pane scrape — returned verbatim when the flag is off OR any model build fails. */
+  fallback: string
+  cols: number
+  rows: number
+}
+
+/**
+ * Resolve the ready-gate viewport. Flag OFF → `fallback` (capture-pane) verbatim — zero work, the
+ * caller never even reaches here unless it pre-checked the flag, but this stays safe regardless.
+ * Flag ON → the pty-model viewport as plain text. ANY failure (unreadable/short log, @xterm hiccup)
+ * → `fallback`: the flip can never make readiness WORSE than capture-pane today (tmux is the floor).
+ */
+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 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 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, rows, allowProposedApi: true, scrollback: 3000 })
+      await new Promise<void>(res => term.write(buf, () => res()))
+      return term
+    } finally {
+      closeSync(fd)
+    }
+  } catch {
+    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
+}