@agfpd/iapeer 0.2.60 → 0.2.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.60",
+  "version": "0.2.62",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "type": "module",
   "bin": {
@@ -33,6 +33,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
+    "@xterm/addon-serialize": "0.14.0",
     "@xterm/headless": "6.0.0",
     "proper-lockfile": "^4.1.2",
     "transliteration": "^2.6.1"

package/src/cli/index.ts

@@ -939,6 +939,7 @@ const USAGE = `usage: iapeer <verb> [args]
   shadow [--once | --minutes <m>] [--interval <ms>]              READ-ONLY tmux→pty fidelity observer (migration burn-in): compares pty-model verdicts vs live tmux on the warm fleet → ~/.iapeer/logs/iapeer/shadow-fidelity.json. Never delivers/mutates.
   shadow-install                                                 install + load the always-on shadow burn-in launchd job (com.iapeer.shadow-fidelity); idempotent, re-cycled by update/rollback
   shadow-uninstall                                               bootout + remove the shadow burn-in launchd job (the correct way to stop it; STOP file is respawned past by KeepAlive)
+  supervisor up|start|attach|list|kill <sess> [runtime]         DARK (cutover Block 2): detach-persistent pty-supervisor PoC port; serves nothing on the live fleet (throwaway validation only)
 `
 
 export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
@@ -1801,6 +1802,14 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         out(`shadow burn-in job ${r.action}: ${r.path}\n`)
         return 0
       }
+      case 'supervisor': {
+        // DARK (cutover Block 2): the detach-persistent pty-supervisor (PoC pts.mjs port). NOT
+        // wired into delivery/launch — it serves NOTHING on the live fleet; it is validated on
+        // throwaway `tick` sessions. The dynamic import keeps @xterm OUT of the daemon hot path
+        // (the daemon never loads this). Sub-commands: up|start|attach|list|kill|daemon.
+        const { runSupervisorCli } = await import('../supervisor/index.ts')
+        return await runSupervisorCli(rest)
+      }
       default: {
         // `iapeer <runtime>` (launch) — folder-launch the cwd's peer, ALWAYS fresh.
         if (verb && isRuntime(verb)) {

package/src/shadow/gate.test.ts

@@ -3,7 +3,10 @@ import {
   GateTracker,
   classifyDirection,
   classifySampleState,
+  evaluateReadyGateFlipEligibility,
+  type GateSummary,
   type PeerSample,
+  type VerdictGateStat,
 } from './gate.ts'
 
 // SYNTHETIC ACCEPTANCE (boris's Block-1 gate): prove the instrument classifies known-behind vs
@@ -141,3 +144,106 @@ describe('GateTracker — coverage matrix (clean counts only over traversed cell
     expect(cov.runtimes).toEqual(['claude', 'codex'])
   })
 })
+
+describe('GateTracker — center cell (codex×wake-resume×history readiness caught by the model)', () => {
+  test('a history-bearing peer whose readiness the model catches at the tmux transition → counted', () => {
+    const g = new GateTracker()
+    g.sample(0, mkSample('c', 'codex', { hasHistory: true, readyGate: { pty: false, tmux: false } }))
+    g.sample(1, mkSample('c', 'codex', { hasHistory: true, readyGate: { pty: true, tmux: true } })) // ready, model agreed
+    expect(g.summary().coverage.readyResumeCaught['codex']).toBe(1)
+  })
+  test('model MISSES readiness at the transition → NOT counted, and it is a pty-behind (dirty)', () => {
+    const g = new GateTracker()
+    g.sample(0, mkSample('c', 'codex', { hasHistory: true, readyGate: { pty: false, tmux: false } }))
+    g.sample(1, mkSample('c', 'codex', { hasHistory: true, readyGate: { pty: false, tmux: true } })) // tmux ready, model NOT
+    const s = g.summary()
+    expect(s.coverage.readyResumeCaught['codex']).toBeUndefined()
+    expect(s.verdicts.readyGate.behind).toBeGreaterThanOrEqual(1) // the exact splash-blind bug
+  })
+  test('a FRESH (no-history) peer ready transition is NOT a center-cell hit', () => {
+    const g = new GateTracker()
+    g.sample(0, mkSample('f', 'codex', { hasHistory: false, readyGate: { pty: false, tmux: false } }))
+    g.sample(1, mkSample('f', 'codex', { hasHistory: false, readyGate: { pty: true, tmux: true } }))
+    expect(g.summary().coverage.readyResumeCaught['codex']).toBeUndefined()
+  })
+})
+
+describe('evaluateReadyGateFlipEligibility (boris guardrail: the eligibility logic itself under test)', () => {
+  const stat = (over: Partial<VerdictGateStat> = {}): VerdictGateStat => ({
+    samples: 10,
+    agree: 10,
+    behind: 0,
+    aheadBenign: 0,
+    aheadHard: 0,
+    selfHeal: { count: 0, max: 0, mean: 0 },
+    gateClean: true,
+    ...over,
+  })
+  const mkSummary = (over: {
+    rgBehind?: number
+    rgAheadHard?: number
+    center?: Record<string, number>
+    births?: Record<string, number>
+    restarts?: Record<string, number>
+  } = {}): GateSummary => ({
+    verdicts: {
+      occupancy: stat(),
+      readyGate: stat({ behind: over.rgBehind ?? 0, aheadHard: over.rgAheadHard ?? 0 }),
+      liveness: stat(),
+    },
+    hardViolations: [],
+    coverage: {
+      fleetWidthMax: 2,
+      runtimes: ['claude', 'codex'],
+      byRuntimeState: {},
+      births: over.births ?? {},
+      restarts: over.restarts ?? {},
+      historySamples: {},
+      readyResumeCaught: over.center ?? {},
+    },
+  })
+  const COMPLETE = {
+    center: { codex: 1 },
+    births: { 'claude/fresh': 1, 'codex/wake-resume': 1 },
+    restarts: { codex: 1 },
+  }
+
+  test('incomplete (empty) → NOT eligible, reasons name every missing cell (actionable)', () => {
+    const e = evaluateReadyGateFlipEligibility(mkSummary())
+    expect(e.eligible).toBe(false)
+    expect(e.reasons.some(r => /center codex×wake-resume×history/.test(r))).toBe(true)
+    expect(e.reasons.some(r => /no codex birth/.test(r))).toBe(true)
+    expect(e.reasons.some(r => /no claude birth/.test(r))).toBe(true)
+    expect(e.reasons.some(r => /no restart/.test(r))).toBe(true)
+  })
+
+  test('complete + clean → eligible', () => {
+    const e = evaluateReadyGateFlipEligibility(mkSummary(COMPLETE))
+    expect(e.eligible).toBe(true)
+    expect(e.reasons).toHaveLength(0)
+  })
+
+  test('complete BUT dirty (readyGate behind) → NOT eligible, reason names the dirt', () => {
+    const e = evaluateReadyGateFlipEligibility(mkSummary({ ...COMPLETE, rgBehind: 2 }))
+    expect(e.eligible).toBe(false)
+    expect(e.reasons.some(r => /readyGate dirty: behind=2/.test(r))).toBe(true)
+  })
+
+  test('complete except the CENTER cell empty → NOT eligible, center reason only', () => {
+    const e = evaluateReadyGateFlipEligibility(mkSummary({ ...COMPLETE, center: {} }))
+    expect(e.eligible).toBe(false)
+    expect(e.reasons).toHaveLength(1)
+    expect(e.reasons[0]).toMatch(/center codex×wake-resume×history: 0/)
+  })
+
+  test('complete except no restart → NOT eligible, restart reason only', () => {
+    const e = evaluateReadyGateFlipEligibility(mkSummary({ ...COMPLETE, restarts: {} }))
+    expect(e.eligible).toBe(false)
+    expect(e.reasons).toEqual(['no restart observed'])
+  })
+
+  test('composer-busy is ORTHOGONAL — its absence never blocks ready-gate eligibility', () => {
+    // COMPLETE carries no composer-busy state anywhere; eligibility must still be true.
+    expect(evaluateReadyGateFlipEligibility(mkSummary(COMPLETE)).eligible).toBe(true)
+  })
+})

package/src/shadow/gate.ts

@@ -93,6 +93,11 @@ interface PeerState {
   firstTick: number
   readyStreak: number
   bootDone: boolean
+  /** History present at first sight ⇒ this peer woke WITH resume-history (vs a fresh empty birth)
+   *  — the population the center cell (codex×wake-resume×history) is measured on. */
+  bornWithHistory: boolean
+  /** Previous tmux ready value, to detect the false/none→true readiness transition. */
+  prevReadyTmux: boolean | null
   open: Record<Verdict, OpenAhead | null>
 }
 
@@ -118,6 +123,10 @@ export class GateTracker {
   private births = new Map<string, number>() // `${runtime}/${fresh|wake-resume}` → count
   private restarts = new Map<string, number>() // runtime → count
   private historySamples = new Map<string, number>() // runtime → count
+  // CENTER cell: a wake-resume-with-history peer whose readiness the MODEL caught at the tmux
+  // ready transition (rgTmux false/none→true with rgPty agreeing) — the codex splash-off-screen
+  // case the ready-gate flip exists for. A behind at that transition instead lands in readyGate.behind.
+  private readyResumeCaught = new Map<string, number>() // runtime → count
   private runtimesSeen = new Set<string>()
 
   constructor(cfg: GateConfig = {}) {
@@ -154,7 +163,15 @@ export class GateTracker {
         this.inc(this.restarts, s.runtime)
         this.goneOnce.delete(s.peer)
       }
-      ps = { runtime: s.runtime, firstTick: tick, readyStreak: 0, bootDone: false, open: { occupancy: null, readyGate: null, liveness: null } }
+      ps = {
+        runtime: s.runtime,
+        firstTick: tick,
+        readyStreak: 0,
+        bootDone: false,
+        bornWithHistory: s.hasHistory,
+        prevReadyTmux: null,
+        open: { occupancy: null, readyGate: null, liveness: null },
+      }
       this.peers.set(s.peer, ps)
     }
 
@@ -167,6 +184,20 @@ export class GateTracker {
     }
     const bootWindow = !ps.bootDone
 
+    // Center-cell signal: at the readiness transition (rgTmux false/none→true) of a
+    // wake-resume-with-history peer, did the MODEL catch readiness too (rgPty=true)? That is the
+    // codex splash-off-screen case the ready-gate flip exists for. (A model MISS at this transition
+    // is a pty-behind → readyGate.behind → dirty → ineligible, which is exactly right.)
+    if (s.readyGate.tmux !== null) {
+      // becameReady requires an OBSERVED not-ready→ready transition (prev === false), NOT
+      // first-sight-already-ready (prev === null): the center cell must capture a REAL resume
+      // splash→ready the observer witnessed (boris's representativeness guardrail), not a warm
+      // peer that was already up when the observer attached.
+      const becameReady = s.readyGate.tmux === true && ps.prevReadyTmux === false
+      if (becameReady && ps.bornWithHistory && s.readyGate.pty === true) this.inc(this.readyResumeCaught, s.runtime)
+      ps.prevReadyTmux = s.readyGate.tmux
+    }
+
     // Coverage.
     const state = classifySampleState(s.occupancy.tmux === true, s.bytesFed)
     this.inc(this.stateCells, `${s.runtime}/${state}`)
@@ -275,11 +306,37 @@ export class GateTracker {
         births: Object.fromEntries([...this.births].sort()),
         restarts: Object.fromEntries([...this.restarts].sort()),
         historySamples: Object.fromEntries([...this.historySamples].sort()),
+        readyResumeCaught: Object.fromEntries([...this.readyResumeCaught].sort()),
       },
     }
   }
 }
 
+/** Ready-gate FLIP eligibility — boris's verdict-scoped gate, operationalized so the burn-in
+ *  SELF-REPORTS instead of being eyeballed. NECESSARY input, NOT an auto-trigger: the flip stays
+ *  an explicit human decision (the representativeness of the filled cells — e.g. the splash truly
+ *  scrolled off-screen — is verified separately on top of this). Eligible iff:
+ *    • ready-gate is HARD-clean (behind=0 ∧ aheadHard=0), AND
+ *    • the CENTER cell is filled: codex woke WITH history and the model caught its readiness, AND
+ *    • a codex AND a claude birth were observed, AND
+ *    • a restart was observed.
+ *  composer-busy is ORTHOGONAL to readiness (a typing human already passed readiness) → excluded;
+ *  it gates the LATER occupancy flip. On !eligible `reasons` say WHICH cell is empty/dirty —
+ *  actionable, never a black-box "not yet". PURE → its own logic is unit-testable (boris's guardrail). */
+export function evaluateReadyGateFlipEligibility(s: GateSummary): FlipEligibility {
+  const reasons: string[] = []
+  const rg = s.verdicts.readyGate
+  if (rg.behind > 0 || rg.aheadHard > 0) reasons.push(`readyGate dirty: behind=${rg.behind} aheadHard=${rg.aheadHard}`)
+  const center = s.coverage.readyResumeCaught['codex'] ?? 0
+  if (center < 1) reasons.push(`center codex×wake-resume×history: ${center} readiness caught (need ≥1, representatively splash-off-screen)`)
+  const hasBirth = (rt: string): boolean => Object.keys(s.coverage.births).some(k => k.startsWith(`${rt}/`))
+  if (!hasBirth('codex')) reasons.push('no codex birth observed')
+  if (!hasBirth('claude')) reasons.push('no claude birth observed')
+  const restarts = Object.values(s.coverage.restarts).reduce((a, b) => a + b, 0)
+  if (restarts < 1) reasons.push('no restart observed')
+  return { verdict: 'readyGate', eligible: reasons.length === 0, reasons }
+}
+
 export interface VerdictGateStat {
   samples: number
   agree: number
@@ -297,6 +354,8 @@ export interface GateCoverage {
   births: Record<string, number>
   restarts: Record<string, number>
   historySamples: Record<string, number>
+  /** runtime → count of wake-resume-with-history readiness transitions the MODEL caught (center cell). */
+  readyResumeCaught: Record<string, number>
 }
 
 export interface GateSummary {
@@ -304,3 +363,10 @@ export interface GateSummary {
   hardViolations: HardViolation[]
   coverage: GateCoverage
 }
+
+export interface FlipEligibility {
+  verdict: 'readyGate'
+  eligible: boolean
+  /** On !eligible: one actionable line per unmet requirement (which cell is empty/dirty). */
+  reasons: string[]
+}

package/src/shadow/index.ts

@@ -19,7 +19,7 @@ import { tmux, composerCaptureHasHumanInput, listOnlinePeers } from '../transpor
 import { getAdapter } from '../launch/index.ts'
 import { buildSocketPath, buildProcessAddress } from '../core/socket.ts'
 import type { Runtime } from '../core/constants.ts'
-import { GateTracker, classifyDirection, VERDICTS } from './gate.ts'
+import { GateTracker, classifyDirection, evaluateReadyGateFlipEligibility, VERDICTS } from './gate.ts'
 
 const SEED_BYTES = 4 * 1024 * 1024
 const promptGlyph = (rt: string): string => (rt === 'claude' ? '❯' : '›')
@@ -122,7 +122,10 @@ export async function runShadowFidelity(opts: ShadowOptions): Promise<void> {
   for (;;) {
     if (opts.maxMinutes && Date.now() - t0 >= opts.maxMinutes * 60000) break
     if (existsSync(stopFile)) break
-    if (i > 0 && i % 15 === 0) enumerate(models, opts, tracker)
+    // Re-enroll every ~3 ticks (~15s), not 15 (~75s): a freshly-woken peer must be enrolled
+    // and sampled DURING its not-ready phase for a readiness transition (the center cell) to
+    // register — a 75s enroll-lag could first-sight it already-ready and miss the transition.
+    if (i > 0 && i % 3 === 0) enumerate(models, opts, tracker)
     tracker.tickStart(models.size)
     for (const o of models.values()) {
       try {
@@ -178,6 +181,10 @@ export async function runShadowFidelity(opts: ShadowOptions): Promise<void> {
       // boot-window ahead that self-heals within budget. Coverage proves the matrix was traversed.
       gateClean: VERDICTS.every(v => gs.verdicts[v].gateClean),
       hardTotal: gs.hardViolations.length,
+      // Ready-gate FLIP eligibility (first-flip verdict) self-reported: NECESSARY input, not an
+      // auto-trigger — the flip stays an explicit decision. On !eligible, `reasons` say which cell
+      // is empty/dirty (actionable). composer-busy is excluded (orthogonal — gates the later occupancy flip).
+      readyGateFlip: evaluateReadyGateFlipEligibility(gs),
       verdicts: gs.verdicts,
       coverage: gs.coverage,
       recentHard: gs.hardViolations.slice(-20),

package/src/supervisor/client.ts

@@ -0,0 +1,118 @@
+// Supervisor CLIENT — attaches a terminal to a running daemon over the unix socket (cutover
+// Block 2, ported from PoC pts.mjs). Detach key Ctrl-] (session keeps running). The two reattach
+// port-deps live here + in protocol.ts: #1 TERM_RESET on EVERY exit path (incl. SIGHUP window-close,
+// via writeSync which works inside a signal handler), and #2 backpressure is the daemon's side.
+import { existsSync, readFileSync, writeSync } from 'node:fs'
+import { FRAME_DATA, FRAME_RESIZE, TERM_RESET, frame, makeFramer, sizePayload } from './protocol.ts'
+import { pidPath, sockPath } from './paths.ts'
+
+const DETACH = 0x1d // Ctrl-]
+
+const pidAlive = (p: number): boolean => {
+  try {
+    process.kill(p, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+export function sessionAlive(runDir: string, session: string): boolean {
+  const pf = pidPath(runDir, session)
+  return existsSync(pf) && pidAlive(Number(readFileSync(pf, 'utf8')))
+}
+
+/** Attach an interactive terminal client to a live daemon session. Resolves when the client
+ *  detaches / the session ends (it calls process.exit on every terminal path). */
+export async function runSupervisorClient(runDir: string, session: string): Promise<void> {
+  if (!sessionAlive(runDir, session)) {
+    console.error(`no live session "${session}". start it: supervisor start ${session} <runtime>`)
+    process.exit(1)
+  }
+  let restored = false
+  // writeSync(1, …) works inside a signal handler (no event-loop dependency) — so a
+  // SIGHUP/window-close client still resets the terminal before it dies (port-dep #1).
+  const restore = (): void => {
+    if (restored) return
+    restored = true
+    try {
+      writeSync(1, TERM_RESET)
+    } catch {
+      /* */
+    }
+    try {
+      if (process.stdin.isTTY) process.stdin.setRawMode(false)
+    } catch {
+      /* */
+    }
+    try {
+      process.stdin.pause()
+    } catch {
+      /* */
+    }
+  }
+
+  const framer = makeFramer((type, payload) => {
+    if (type === FRAME_DATA) process.stdout.write(Buffer.from(payload))
+  })
+  // Ready the terminal BEFORE connecting, so the repaint snapshot renders the instant it arrives.
+  if (process.stdin.isTTY) process.stdin.setRawMode(true)
+  process.stdin.resume()
+
+  const curSize = (): Buffer => sizePayload(process.stdout.columns || 80, process.stdout.rows || 24)
+  const sock = await Bun.connect({
+    unix: sockPath(runDir, session),
+    socket: {
+      open(s) {
+        s.write(frame(FRAME_RESIZE, curSize())) // tell the daemon our size → repaint at our size
+      },
+      data(_s, d) {
+        framer(d)
+      },
+      close() {
+        restore()
+        process.stdout.write('\r\n[supervisor] session ended.\r\n')
+        process.exit(0)
+      },
+      error() {
+        restore()
+        process.exit(1)
+      },
+    },
+  })
+
+  process.stdin.on('data', b => {
+    if (b.includes(DETACH)) {
+      restore()
+      try {
+        sock.end()
+      } catch {
+        /* */
+      }
+      process.stdout.write(`\r\n[supervisor] detached — session still running. reattach: supervisor attach ${session}\r\n`)
+      process.exit(0)
+    }
+    sock.write(frame(FRAME_DATA, b))
+  })
+  process.on('SIGWINCH', () => {
+    try {
+      sock.write(frame(FRAME_RESIZE, curSize()))
+    } catch {
+      /* */
+    }
+  })
+  // Window-close (SIGHUP) / kill (SIGTERM) of the CLIENT: detach cleanly (session keeps running)
+  // and reset the terminal — the prior gap leaked the child's app-modes and broke the next reattach.
+  for (const sig of ['SIGHUP', 'SIGTERM'] as const) {
+    process.on(sig, () => {
+      restore()
+      try {
+        sock.end()
+      } catch {
+        /* */
+      }
+      process.exit(0)
+    })
+  }
+  process.on('exit', () => restore()) // last-resort sync net
+  process.stdout.write(`\x1b[2m[supervisor] attached to "${session}". detach: Ctrl-]  (session keeps running)\x1b[0m\r\n`)
+}

package/src/supervisor/daemon.test.ts

@@ -0,0 +1,112 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { FRAME_DATA, FRAME_RESIZE, frame, makeFramer, sizePayload } from './protocol.ts'
+import { killSession, listSessions, sessionAlive, sockPath, startSupervisorDaemon } from './index.ts'
+
+// Integration: a REAL Bun-native pty daemon over a real unix socket, driven by the deterministic
+// `tick` runtime (no claude/codex needed) — hermetic (temp run dir, throwaway session). Proves
+// boris's Block-2 acceptance points: spawn + responder-served boot + attach repaint + live
+// forward + detach-survival + REATTACH FRESHNESS (the heavy-reattach bug the port-deps fixed).
+// Gated on Bun-native PTY (≥1.3.5) so a runner without it skips rather than reds.
+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 = 50): Promise<boolean> {
+  const end = Date.now() + timeoutMs
+  while (Date.now() < end) {
+    if (pred()) return true
+    await sleep(step)
+  }
+  return false
+}
+const maxTick = (s: string): number => {
+  let m = -1
+  for (const x of s.matchAll(/STREAMTICK_(\d+)/g)) m = Math.max(m, Number(x[1]))
+  return m
+}
+
+interface Client {
+  text(): string
+  close(): void
+}
+async function attach(runDir: string, session: string, cols = 80, rows = 24): Promise<Client> {
+  const frames: Buffer[] = []
+  const framer = makeFramer((t, p) => {
+    if (t === FRAME_DATA) frames.push(Buffer.from(p))
+  })
+  const sock = await Bun.connect({
+    unix: sockPath(runDir, session),
+    socket: {
+      open(s) {
+        s.write(frame(FRAME_RESIZE, sizePayload(cols, rows)))
+      },
+      data(_s, dd) {
+        framer(dd)
+      },
+    },
+  })
+  return {
+    text: () => Buffer.concat(frames).toString('latin1'),
+    close: () => {
+      try {
+        sock.end()
+      } catch {
+        /* */
+      }
+    },
+  }
+}
+
+d('supervisor daemon (Bun-native pty, tick runtime)', () => {
+  let runDir: string
+  const session = 'ptstest'
+
+  beforeAll(() => {
+    runDir = mkdtempSync(join(tmpdir(), 'iapeer-supervisor-'))
+  })
+  afterAll(() => {
+    try {
+      killSession(runDir, session)
+    } catch {
+      /* */
+    }
+    rmSync(runDir, { recursive: true, force: true })
+  })
+
+  test('spawns a detached daemon that comes up live', () => {
+    const r = startSupervisorDaemon({ session, runtime: 'tick', runDir })
+    expect(r.state).toBe('started')
+    expect(sessionAlive(runDir, session)).toBe(true)
+    expect(listSessions(runDir).some(s => s.session === session && s.alive)).toBe(true)
+  })
+
+  test('attach forwards live child output (the pty conduit works end-to-end)', async () => {
+    const c = await attach(runDir, session)
+    const got = await waitFor(() => /STREAMTICK_\d+/.test(c.text()))
+    expect(got).toBe(true) // live STREAMTICK_N stream reached the client
+    c.close()
+  })
+
+  test('detach keeps the daemon alive (detach-persistence)', async () => {
+    await sleep(150)
+    expect(sessionAlive(runDir, session)).toBe(true)
+  })
+
+  test('REATTACH repaints the CURRENT frame, not a stale one (port-dep #2 freshness)', async () => {
+    const first = await attach(runDir, session)
+    await waitFor(() => maxTick(first.text()) >= 0)
+    const base = maxTick(first.text())
+    first.close()
+    await sleep(800) // the stream advances while detached
+    const second = await attach(runDir, session)
+    // the reattach repaint (serialize of the CURRENT screen) must reflect ticks emitted AFTER the
+    // first detach — a stale close-moment frame would show base, not a higher index.
+    const fresh = await waitFor(() => maxTick(second.text()) > base, 5000)
+    expect(fresh).toBe(true)
+    second.close()
+  })
+})

package/src/supervisor/daemon.ts

@@ -0,0 +1,210 @@
+// Supervisor DAEMON — holds the pty + child + headless-xterm model + capability responder
+// independent of any terminal; clients attach/detach over a unix socket (cutover Block 2, ported
+// from the validated PoC pts.mjs). DARK: reachable only via the `supervisor` CLI verb (dynamic
+// import), so @xterm never loads in the delivery hot path. NOT wired into launch/lifecycle — it
+// serves NOTHING on the live fleet yet; it is validated on throwaway sessions only.
+//
+// Loads @xterm/headless + @xterm/addon-serialize (the latter is the repaint source: a reattaching
+// client gets the full current screen even if the child is silent). Both bundle under
+// `bun build --compile` (pure JS; the Bun-native pty has no native addon — PoC-proven).
+import { Terminal } from '@xterm/headless'
+import { SerializeAddon } from '@xterm/addon-serialize'
+import { existsSync, unlinkSync, writeFileSync } from 'node:fs'
+import {
+  BackpressureWriter,
+  FRAME_DATA,
+  FRAME_RESIZE,
+  capabilityResponses,
+  frame,
+  makeFramer,
+  parseSize,
+  stripQueries,
+} from './protocol.ts'
+import { pidPath, sockPath } from './paths.ts'
+
+/** Known runtime launchers; `tick` is a deterministic test stream (no TUI noise) for hermetic
+ *  spawn/attach/reattach tests — it never needs a real claude/codex on the box. */
+const KNOWN: Record<string, string> = {
+  claude: '/Users/macmini/.local/bin/claude',
+  codex: '/opt/homebrew/bin/codex',
+}
+const TICK_CMD = ['sh', '-c', 'i=0; while true; do printf "STREAMTICK_%d\\r\\n" "$i"; i=$((i+1)); sleep 0.3; done']
+
+// Bun-native PTY (Bun ≥1.3.5) is not yet in @types/bun — type the slice we use.
+interface PtyChild {
+  terminal: { write(d: Uint8Array | string): void; resize(cols: number, rows: number): void }
+  kill(sig?: number | string): void
+}
+
+export interface SupervisorDaemonOptions {
+  session: string
+  runtime: string
+  runDir: string
+  /** Child working directory (default: runDir — a throwaway scratch for dark validation). */
+  cwd?: string
+  /** Override the runtime launcher (else KNOWN[runtime] if it exists, else the bare name). */
+  bin?: string
+  cols?: number
+  rows?: number
+}
+
+/** Run the supervisor daemon in THIS process (blocks until the child exits / SIGTERM). Spawn it
+ *  detached via startSupervisorDaemon (index.ts) for a real session; call directly in a test that
+ *  owns its own process. */
+export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
+  const { session, runtime, runDir } = opts
+  let cols = opts.cols ?? 80
+  let rows = opts.rows ?? 30
+  const sock = sockPath(runDir, session)
+  const pid = pidPath(runDir, session)
+
+  const xterm = new Terminal({ cols, rows, allowProposedApi: true, scrollback: 5000 })
+  const ser = new SerializeAddon()
+  xterm.loadAddon(ser)
+
+  const bin = opts.bin ?? (KNOWN[runtime] && existsSync(KNOWN[runtime]!) ? KNOWN[runtime]! : runtime)
+  const CMD = runtime === 'tick' ? TICK_CMD : [bin]
+  const env = { ...process.env, TERM: 'xterm-256color' } as Record<string, string>
+  delete env.TMUX
+  delete env.TMUX_PANE
+
+  const clients = new Set<unknown>()
+  const writers = new WeakMap<object, BackpressureWriter>()
+  const framers = new WeakMap<object, (chunk: Uint8Array) => void>()
+  const writerFor = (s: { write(b: Buffer): number }): BackpressureWriter => {
+    let w = writers.get(s as object)
+    if (!w) {
+      w = new BackpressureWriter(b => s.write(b))
+      writers.set(s as object, w)
+    }
+    return w
+  }
+  /** Backpressure-safe send to one client; drop it (and report false) if its socket is dead. */
+  const sendClient = (s: { write(b: Buffer): number }, buf: Buffer): boolean => {
+    const ok = writerFor(s).send(buf)
+    if (!ok) clients.delete(s)
+    return ok
+  }
+
+  const child = Bun.spawn(CMD, {
+    cwd: opts.cwd ?? runDir,
+    env,
+    // Bun-native PTY: a real pty pair, child output arrives via terminal.data(t, bytes).
+    terminal: {
+      cols,
+      rows,
+      name: 'xterm-256color',
+      data(_t: unknown, d: Uint8Array | string) {
+        const buf = Buffer.isBuffer(d) ? d : typeof d === 'string' ? Buffer.from(d, 'utf8') : Buffer.from(d)
+        const s = buf.toString('latin1')
+        xterm.write(buf) // authoritative model
+        for (const r of capabilityResponses(s)) child.terminal.write(r) // answer capability queries
+        const fwd = Buffer.from(stripQueries(s), 'latin1') // forward to clients sans queries (daemon is authoritative)
+        if (fwd.length) for (const c of [...clients]) sendClient(c as { write(b: Buffer): number }, frame(FRAME_DATA, fwd))
+      },
+      exit() {
+        shutdown()
+      },
+    },
+  } as unknown as Parameters<typeof Bun.spawn>[1]) as unknown as PtyChild
+  xterm.onData(resp => child.terminal.write(resp)) // @xterm auto-answers DA1/DSR → back to child
+
+  /** Repaint a (re)attaching client from the headless snapshot: clear+home, then the full grid.
+   *  Backpressure-safe — a ~90 KB heavy snapshot MUST NOT drop past the socket buffer (port-dep #2). */
+  const repaint = (s: { write(b: Buffer): number }): void => {
+    const snap = '\x1b[2J\x1b[3J\x1b[H' + ser.serialize()
+    sendClient(s, frame(FRAME_DATA, Buffer.from(snap, 'utf8')))
+  }
+
+  const onClientFrame = (s: { write(b: Buffer): number }, type: number, payload: Buffer): void => {
+    if (type === FRAME_DATA) {
+      child.terminal.write(payload) // keystrokes → child
+    } else if (type === FRAME_RESIZE) {
+      const sz = parseSize(payload)
+      cols = sz.cols
+      rows = sz.rows
+      try {
+        xterm.resize(cols, rows)
+        child.terminal.resize(cols, rows)
+      } catch {
+        /* transient */
+      }
+      repaint(s) // instant paint from the snapshot (delivered COMPLETE via backpressure)
+      // Best-effort SIGWINCH nudge for a SIGWINCH-reactive child; NOT load-bearing (the complete
+      // snapshot above is the real freshness fix).
+      try {
+        child.terminal.resize(cols, Math.max(1, rows - 1))
+        child.terminal.resize(cols, rows)
+      } catch {
+        /* */
+      }
+    }
+  }
+
+  try {
+    if (existsSync(sock)) unlinkSync(sock)
+  } catch {
+    /* */
+  }
+  const server = Bun.listen({
+    unix: sock,
+    socket: {
+      open(s: { write(b: Buffer): number }) {
+        framers.set(s as object, makeFramer((t, p) => onClientFrame(s, t, p)))
+        clients.add(s)
+        repaint(s) // UNCONDITIONAL repaint on attach (tmux-like)
+      },
+      data(s: object, d: Uint8Array) {
+        framers.get(s)?.(d)
+      },
+      drain(s: object) {
+        if (!writers.get(s)?.flush()) clients.delete(s) // writable again → flush queued tail
+      },
+      close(s: object) {
+        clients.delete(s)
+        writers.delete(s)
+      },
+      error(s: object) {
+        clients.delete(s)
+        writers.delete(s)
+      },
+    },
+  })
+  writeFileSync(pid, String(process.pid))
+
+  let down = false
+  function shutdown(): void {
+    if (down) return
+    down = true
+    try {
+      child.kill('SIGKILL')
+    } catch {
+      /* */
+    }
+    try {
+      server.stop(true)
+    } catch {
+      /* */
+    }
+    for (const f of [sock, pid]) {
+      try {
+        unlinkSync(f)
+      } catch {
+        /* */
+      }
+    }
+    process.exit(0)
+  }
+  process.on('SIGTERM', shutdown)
+  process.on('SIGINT', shutdown)
+  process.on('SIGHUP', () => {
+    /* daemon survives client window close */
+  })
+  process.on('uncaughtException', e => {
+    try {
+      console.error('[supervisor-daemon] uncaught', (e && (e as Error).stack) || e)
+    } catch {
+      /* */
+    }
+  })
+}

package/src/supervisor/index.ts

@@ -0,0 +1,137 @@
+// Supervisor entry + CLI dispatch (cutover Block 2, ported from PoC pts.mjs). DARK: this module
+// (and daemon.ts/client.ts) load @xterm — they are reachable ONLY via the `supervisor` CLI verb
+// (dynamic import) and are NOT imported by transport/lifecycle/launch/daemon. The supervisor
+// serves NOTHING on the live fleet; it is validated on throwaway `tick` sessions in-repo. When
+// 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 { fileURLToPath } from 'node:url'
+import { runSupervisorDaemon } from './daemon.ts'
+import { runSupervisorClient, sessionAlive } from './client.ts'
+import { defaultRunDir, logPath, pidPath, sockPath } from './paths.ts'
+
+export { runSupervisorDaemon } from './daemon.ts'
+export { runSupervisorClient, sessionAlive } from './client.ts'
+export { defaultRunDir, sockPath, pidPath } from './paths.ts'
+
+export interface StartDaemonOptions {
+  session: string
+  runtime: string
+  runDir: string
+  /** How to launch the detached daemon process (default: bun + this file). The trailing
+   *  `daemon <session> <runtime> --run-dir <runDir>` is appended. Serving-prod injects the
+   *  installed-binary argv here. */
+  daemonArgv?: string[]
+  /** Max ms to wait for the daemon socket+pid to appear (default 5000). */
+  timeoutMs?: number
+}
+
+export interface StartDaemonResult {
+  state: 'started' | 'already-running' | 'failed'
+  pid?: number
+  detail?: string
+}
+
+const selfArgv = (): string[] => [process.execPath, fileURLToPath(import.meta.url)]
+
+/** Start a detached supervisor daemon and wait until its socket is live. Idempotent. */
+export function startSupervisorDaemon(opts: StartDaemonOptions): StartDaemonResult {
+  const { session, runtime, runDir } = opts
+  if (sessionAlive(runDir, session)) return { state: 'already-running' }
+  mkdirSync(runDir, { recursive: true })
+  try {
+    if (existsSync(sockPath(runDir, session))) unlinkSync(sockPath(runDir, session))
+  } catch {
+    /* */
+  }
+  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], {
+    detached: true,
+    stdio: ['ignore', out, out],
+  })
+  child.unref()
+  const deadline = Date.now() + (opts.timeoutMs ?? 5000)
+  while (Date.now() < deadline) {
+    if (existsSync(sockPath(runDir, session)) && sessionAlive(runDir, session)) {
+      return { state: 'started', pid: Number(readFileSync(pidPath(runDir, session), 'utf8')) }
+    }
+    Bun.sleepSync(80)
+  }
+  return { state: 'failed', detail: `daemon did not come up; see ${logPath(runDir, session)}` }
+}
+
+export function listSessions(runDir: string): Array<{ session: string; alive: boolean; pid?: number }> {
+  if (!existsSync(runDir)) return []
+  return readdirSync(runDir)
+    .filter(f => f.endsWith('.sock'))
+    .map(f => f.replace(/\.sock$/, ''))
+    .map(session => {
+      const alive = sessionAlive(runDir, session)
+      return { session, alive, pid: alive ? Number(readFileSync(pidPath(runDir, session), 'utf8')) : undefined }
+    })
+}
+
+export function killSession(runDir: string, session: string): boolean {
+  const pf = pidPath(runDir, session)
+  if (!existsSync(pf)) return false
+  const pid = Number(readFileSync(pf, 'utf8'))
+  try {
+    process.kill(pid, 'SIGTERM')
+  } catch {
+    /* already gone */
+  }
+  return true
+}
+
+/** Parse a `--run-dir <dir>` flag out of an argv slice; returns the value or the default. */
+function runDirFrom(args: string[]): string {
+  const i = args.indexOf('--run-dir')
+  return i >= 0 && args[i + 1] ? args[i + 1]! : defaultRunDir()
+}
+
+/** CLI dispatch (also the `import.meta.main` entry used by the spawned daemon process). */
+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 })
+      // 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}`)
+      return r.state === 'failed' ? 1 : 0
+    }
+    case 'attach':
+      await runSupervisorClient(runDir, a!)
+      return 0
+    case 'up': {
+      const r = startSupervisorDaemon({ session: a!, runtime: b || 'claude', runDir })
+      if (r.state === 'failed') {
+        console.error(r.detail)
+        return 1
+      }
+      await runSupervisorClient(runDir, a!)
+      return 0
+    }
+    case 'list':
+      for (const s of listSessions(runDir)) console.log(`${s.session}\t${s.alive ? `running pid=${s.pid}` : 'dead'}`)
+      return 0
+    case 'kill':
+      console.log(killSession(runDir, a!) ? `killed "${a}"` : `no session "${a}"`)
+      return 0
+    default:
+      console.log('usage: supervisor up|start|attach|list|kill <session> [runtime] [--run-dir <dir>]   (detach: Ctrl-])')
+      return 0
+  }
+}
+
+if (import.meta.main) {
+  process.exit(await runSupervisorCli(process.argv.slice(2)))
+}

package/src/supervisor/paths.ts

@@ -0,0 +1,14 @@
+// Supervisor session paths — under a configurable run dir (NOT hardcoded). Prod resolves it to
+// ~/.iapeer/state/supervisor via the storage layer; tests pass a temp dir, so the daemon's
+// socket/pid files never touch a real location.
+import { join } from 'node:path'
+import { pluginStateDir } from '../storage/index.ts'
+
+/** Default run dir for the supervisor's session sockets/pids: ~/.iapeer/state/supervisor. */
+export function defaultRunDir(env: NodeJS.ProcessEnv = process.env): string {
+  return pluginStateDir('supervisor', { env })
+}
+
+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`)

package/src/supervisor/protocol.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  BackpressureWriter,
+  FRAME_DATA,
+  FRAME_RESIZE,
+  TERM_RESET,
+  capabilityResponses,
+  frame,
+  makeFramer,
+  parseSize,
+  sizePayload,
+  stripQueries,
+} from './protocol.ts'
+
+describe('frame protocol', () => {
+  test('frame() lays out [type][len:u32be][payload]', () => {
+    const f = frame(FRAME_DATA, 'hi')
+    expect(f[0]).toBe(FRAME_DATA)
+    expect(f.readUInt32BE(1)).toBe(2)
+    expect(f.subarray(5).toString()).toBe('hi')
+  })
+
+  test('makeFramer reassembles a frame split across chunk boundaries', () => {
+    const got: Array<{ t: number; p: string }> = []
+    const fr = makeFramer((t, p) => got.push({ t, p: p.toString() }))
+    const f = frame(FRAME_DATA, 'hello world')
+    fr(f.subarray(0, 3)) // partial header
+    fr(f.subarray(3, 8)) // rest of header + part of payload
+    expect(got).toHaveLength(0) // nothing complete yet
+    fr(f.subarray(8)) // tail
+    expect(got).toEqual([{ t: FRAME_DATA, p: 'hello world' }])
+  })
+
+  test('makeFramer splits multiple coalesced frames', () => {
+    const got: string[] = []
+    const fr = makeFramer((_t, p) => got.push(p.toString()))
+    fr(Buffer.concat([frame(FRAME_DATA, 'a'), frame(FRAME_DATA, 'bb'), frame(FRAME_DATA, 'ccc')]))
+    expect(got).toEqual(['a', 'bb', 'ccc'])
+  })
+
+  test('sizePayload/parseSize round-trip', () => {
+    expect(parseSize(sizePayload(132, 50))).toEqual({ cols: 132, rows: 50 })
+    expect(frame(FRAME_RESIZE, sizePayload(80, 24))[0]).toBe(FRAME_RESIZE)
+  })
+})
+
+describe('capability responder (the queries @xterm does not auto-answer)', () => {
+  test('secondary-DA-style XTVERSION query → version report', () => {
+    expect(capabilityResponses('\x1b[>0q')).toEqual(['\x1bP>|iapeer-pts(0.1)\x1b\\'])
+  })
+  test('OSC-11 theme query → an rgb background report', () => {
+    expect(capabilityResponses('\x1b]11;?\x07')[0]).toContain('\x1b]11;rgb:')
+  })
+  test('secondary DA (>c) → a DA2 report', () => {
+    expect(capabilityResponses('\x1b[>0c')).toEqual(['\x1b[>0;276;0c'])
+  })
+  test('plain output → no responses', () => {
+    expect(capabilityResponses('just some text\r\n')).toEqual([])
+  })
+  test('stripQueries removes DA1/DSR/theme but keeps real output', () => {
+    const s = 'before\x1b[0c\x1b[6nmid\x1b]11;?\x07after'
+    const out = stripQueries(s)
+    expect(out).toBe('beforemidafter')
+    expect(out).not.toContain('\x1b[6n')
+  })
+})
+
+describe('TERM_RESET (port-dep #1: clean every client exit path)', () => {
+  test('resets the leak-prone app-modes', () => {
+    expect(TERM_RESET).toContain('\x1b[?1049l') // leave alt-screen
+    expect(TERM_RESET).toContain('\x1b[?1000l') // mouse tracking off
+    expect(TERM_RESET).toContain('\x1b[?25h') // show cursor
+    expect(TERM_RESET).toContain('\x1b[<u') // pop kitty-keyboard
+  })
+})
+
+describe('BackpressureWriter (port-dep #2: the ~90 KB-over-8 KB truncation that staled reattach)', () => {
+  test('a fully-accepted write leaves nothing queued', () => {
+    const w = new BackpressureWriter(b => b.length)
+    expect(w.send(Buffer.alloc(100))).toBe(true)
+    expect(w.queuedBytes).toBe(0)
+  })
+
+  test('a heavy frame past the socket buffer is QUEUED, then fully delivered across drains', () => {
+    const CAP = 8192
+    let delivered = 0
+    const w = new BackpressureWriter(b => {
+      const n = Math.min(CAP, b.length)
+      delivered += n
+      return n
+    })
+    const heavy = Buffer.alloc(89305, 0x41) // the measured heavy-claude serialize size
+    expect(w.send(heavy)).toBe(true)
+    expect(delivered).toBe(CAP) // first write took only the socket buffer
+    expect(w.queuedBytes).toBe(89305 - CAP) // the rest is queued, NOT dropped
+    let guard = 0
+    while (w.queuedBytes > 0 && guard++ < 1000) w.flush() // drain events
+    expect(delivered).toBe(89305) // every byte eventually delivered (no truncation)
+    expect(w.queuedBytes).toBe(0)
+    expect(w.isDead).toBe(false)
+  })
+
+  test('coalesces a new send onto the pending tail (ordering preserved)', () => {
+    const CAP = 4
+    const chunks: string[] = []
+    const w = new BackpressureWriter(b => {
+      const n = Math.min(CAP, b.length)
+      chunks.push(b.subarray(0, n).toString())
+      return n
+    })
+    w.send(Buffer.from('ABCDEF')) // 'ABCD' written, 'EF' queued
+    w.send(Buffer.from('GH')) // coalesced onto 'EF' → 'EFGH'
+    let guard = 0
+    while (w.queuedBytes > 0 && guard++ < 100) w.flush()
+    expect(chunks.join('')).toBe('ABCDEFGH')
+  })
+
+  test('a dead socket (write throws) → send returns false and the writer is dead', () => {
+    const w = new BackpressureWriter(() => {
+      throw new Error('EPIPE')
+    })
+    expect(w.send(Buffer.alloc(10))).toBe(false)
+    expect(w.isDead).toBe(true)
+  })
+
+  test('a negative write count → dead', () => {
+    const w = new BackpressureWriter(() => -1)
+    expect(w.send(Buffer.alloc(10))).toBe(false)
+    expect(w.isDead).toBe(true)
+  })
+})

package/src/supervisor/protocol.ts

@@ -0,0 +1,155 @@
+// Supervisor wire/terminal PRIMITIVES — the pure, hermetically-testable core of the
+// detach-persistent pty-supervisor (cutover Block 2, ported from the validated PoC pts.mjs).
+//
+// PURE: no Bun, no @xterm, no socket — frames, the capability responder, the backpressure
+// writer (port-dep #2), and the terminal-reset string (port-dep #1) are all data-in/data-out,
+// so the two reattach port-deps that bit the PoC are unit-provable without spawning anything.
+
+const EMPTY = Buffer.alloc(0)
+
+// ── client/daemon frame protocol: [type:u8][len:u32be][payload] ──
+export const FRAME_DATA = 0
+export const FRAME_RESIZE = 1
+
+export function frame(type: number, payload: Buffer | string): Buffer {
+  const p = Buffer.isBuffer(payload) ? payload : Buffer.from(payload)
+  const h = Buffer.alloc(5)
+  h[0] = type
+  h.writeUInt32BE(p.length, 1)
+  return Buffer.concat([h, p])
+}
+
+/** Streaming frame de-chunker: reassembles frames across arbitrary TCP/unix chunk boundaries
+ *  (a frame may arrive split, or several may arrive coalesced). Calls onFrame per complete frame. */
+export function makeFramer(onFrame: (type: number, payload: Buffer) => void): (chunk: Uint8Array | Buffer) => void {
+  let buf: Buffer = EMPTY
+  return chunk => {
+    buf = buf.length ? Buffer.concat([buf, Buffer.from(chunk)]) : Buffer.from(chunk)
+    while (buf.length >= 5) {
+      const type = buf[0]!
+      const len = buf.readUInt32BE(1)
+      if (buf.length < 5 + len) break
+      onFrame(type, buf.subarray(5, 5 + len))
+      buf = buf.subarray(5 + len)
+    }
+  }
+}
+
+export function sizePayload(cols: number, rows: number): Buffer {
+  const b = Buffer.alloc(4)
+  b.writeUInt16BE(cols || 80, 0)
+  b.writeUInt16BE(rows || 24, 2)
+  return b
+}
+
+export function parseSize(payload: Buffer): { cols: number; rows: number } {
+  return { cols: payload.readUInt16BE(0), rows: payload.readUInt16BE(2) }
+}
+
+// ── capability responder ──────────────────────────────────────────────────────
+// The child (claude/codex TUI) emits terminal capability QUERIES (device attributes, cursor
+// position, theme) and BLOCKS its first paint until they are answered. tmux answers them; the
+// supervisor daemon must too. @xterm/headless auto-answers DA1/DSR via onData; these are the
+// ones it does NOT: secondary/tertiary DA (`>q`, `>c`) and the OSC-11 theme query.
+
+export const QUERY_RE = /\x1b\[0?c|\x1b\[>\d*[qc]|\x1b\[6n|\x1b\]11;\?(?:\x07|\x1b\\)/g
+
+/** Supplementary capability answers to write back INTO the child for queries @xterm does not
+ *  auto-answer. Returns the response strings (possibly empty). Pure — testable without a pty. */
+export function capabilityResponses(s: string): string[] {
+  const out: string[] = []
+  if (/\x1b\[>\d*q/.test(s)) out.push('\x1bP>|iapeer-pts(0.1)\x1b\\') // XTVERSION (DA2-style)
+  if (/\x1b\]11;\?(\x07|\x1b\\)/.test(s)) out.push('\x1b]11;rgb:1e1e/1e1e/1e1e\x07') // OSC-11 theme
+  if (/\x1b\[>\d*c/.test(s)) out.push('\x1b[>0;276;0c') // secondary DA
+  return out
+}
+
+/** Strip capability queries from a child-output chunk before forwarding to clients (the daemon
+ *  is the authoritative responder — clients must not see/answer the queries themselves). */
+export function stripQueries(s: string): string {
+  return s.replace(QUERY_RE, '')
+}
+
+// ── 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).
+// They persist in the window after the client goes. A SIGHUP/window-close client that ran NOTHING
+// leaked them → broke the NEXT reattach (mouse tracking eats the scroll wheel, kitty garbles keys,
+// leftover modes freeze the render). Reset to a clean base on EVERY exit path; the next attach's
+// repaint + the child's live re-render re-assert whatever the session actually needs.
+export const TERM_RESET =
+  '\x1b[?1049l' + // leave alt-screen (normal buffer)
+  '\x1b[?2004l' + // bracketed-paste off
+  '\x1b[?1004l' + // focus-event reporting off
+  '\x1b[?2031l' + // theme/color-scheme-update off
+  '\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?1015l' + // ALL mouse tracking off
+  '\x1b[<u' + // pop kitty-keyboard flags
+  '\x1b[r' + // reset scroll region (DECSTBM) to full
+  '\x1b[?25h' + // show cursor
+  '\x1b[?7h' // wraparound on (default)
+
+// ── port-dep #2: backpressure-safe socket writer ────────────────────────────────
+// Bun's sock.write() of a large buffer accepts only the socket buffer (~8 KB) and RETURNS the
+// count actually taken — the rest is DROPPED unless queued and re-sent on `drain`. The PoC's old
+// code ignored the return, so a heavy-claude repaint frame (~90 KB serialize) arrived TRUNCATED
+// (measured live: len=89305, only 8192 delivered) → the client's framer waited forever for a
+// frame that never completed → reattach showed the STALE close-moment frame. This writer queues
+// the unwritten tail and flushes it on drain, for BOTH the repaint snapshot and live forward.
+
+export interface SocketWrite {
+  /** Write up to buf.length bytes; return the count ACCEPTED (Bun semantics), or <0 on a dead socket. */
+  (buf: Buffer): number
+}
+
+/** Per-socket backpressure queue. send() coalesces+writes and queues the unaccepted tail;
+ *  flush() (call on the socket `drain` event) drains the queue. Dead once write throws / returns <0. */
+export class BackpressureWriter {
+  private pending: Buffer = EMPTY
+  private dead = false
+  constructor(private readonly write: SocketWrite) {}
+
+  /** Queue and send `buf`. Returns false iff the socket is dead (caller should drop the client). */
+  send(buf: Buffer): boolean {
+    if (this.dead) return false
+    const data = this.pending.length ? Buffer.concat([this.pending, buf]) : buf
+    let n: number
+    try {
+      n = this.write(data)
+    } catch {
+      this.dead = true
+      return false
+    }
+    if (n < 0) {
+      this.dead = true
+      return false
+    }
+    this.pending = n < data.length ? data.subarray(n) : EMPTY
+    return true
+  }
+
+  /** Flush the queued tail (call on `drain`). Returns false iff the socket died flushing. */
+  flush(): boolean {
+    if (this.dead) return false
+    if (!this.pending.length) return true
+    let n: number
+    try {
+      n = this.write(this.pending)
+    } catch {
+      this.dead = true
+      return false
+    }
+    if (n < 0) {
+      this.dead = true
+      return false
+    }
+    this.pending = n < this.pending.length ? this.pending.subarray(n) : EMPTY
+    return true
+  }
+
+  get isDead(): boolean {
+    return this.dead
+  }
+  get queuedBytes(): number {
+    return this.pending.length
+  }
+}