@agfpd/iapeer 0.2.59 → 0.2.61

package/src/shadow/index.ts

@@ -19,6 +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, evaluateReadyGateFlipEligibility, VERDICTS } from './gate.ts'
 
 const SEED_BYTES = 4 * 1024 * 1024
 const promptGlyph = (rt: string): string => (rt === 'claude' ? '❯' : '›')
@@ -72,16 +73,18 @@ export interface ShadowOptions {
   log?: (s: string) => void
 }
 
-function feed(o: Obs): Promise<void> {
+/** Feed the pane-log delta into the model; resolves with the byte count appended this tick
+ *  (drives the coverage state classifier: >0 ⇒ the model is advancing, not idle). */
+function feed(o: Obs): Promise<number> {
   const sz = fstatSync(o.fd).size
-  if (sz <= o.offset) return Promise.resolve()
+  if (sz <= o.offset) return Promise.resolve(0)
   const buf = Buffer.alloc(sz - o.offset)
   readSync(o.fd, buf, 0, buf.length, o.offset)
   o.offset = sz
-  return new Promise(res => o.term.write(buf, () => res()))
+  return new Promise(res => o.term.write(buf, () => res(buf.length)))
 }
 
-function enumerate(models: Map<string, Obs>, opts: ShadowOptions): void {
+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>()
@@ -98,7 +101,7 @@ function enumerate(models: Map<string, Obs>, opts: ShadowOptions): void {
       models.set(addr, { addr, sock, runtime: p.runtime, cols, rows, term, fd, offset })
     } catch { /* a peer racing spawn/teardown — skip this round */ }
   }
-  for (const [addr, o] of models) if (!live.has(addr)) { try { closeSync(o.fd) } catch { /* */ }; models.delete(addr) }
+  for (const [addr, o] of models) if (!live.has(addr)) { try { closeSync(o.fd) } catch { /* */ }; tracker?.peerGone(addr); models.delete(addr) }
 }
 
 /** Run the read-only fidelity observer. Resolves when once/maxMinutes/STOP completes. */
@@ -110,19 +113,20 @@ export async function runShadowFidelity(opts: ShadowOptions): Promise<void> {
   const interval = opts.intervalMs ?? 5000
   const log = opts.log ?? (() => { /* */ })
   const models = new Map<string, Obs>()
-  const tot = { samples: 0, occDiv: 0, occNt: 0, rgDiv: 0, livDiv: 0 }
+  const tracker = new GateTracker()
   const startedISO = new Date().toISOString(), t0 = Date.now()
-  enumerate(models, opts)
+  enumerate(models, opts, tracker)
   for (const o of models.values()) await feed(o)  // seed each model
   log(`shadow-fidelity: ${models.size} warm peers, interval ${interval}ms\n`)
   let i = 0
   for (;;) {
     if (opts.maxMinutes && Date.now() - t0 >= opts.maxMinutes * 60000) break
     if (existsSync(stopFile)) break
-    if (i > 0 && i % 15 === 0) enumerate(models, opts)
+    if (i > 0 && i % 15 === 0) enumerate(models, opts, tracker)
+    tracker.tickStart(models.size)
     for (const o of models.values()) {
       try {
-        await feed(o)
+        const bytesFed = await feed(o)
         const adapter = getAdapter(o.runtime)
         const capE = tmux(o.sock, 'capture-pane', '-e', '-p', '-t', o.addr); if (!capE.ok) continue
         const occTmux = composerCaptureHasHumanInput(capE.out, adapter.deliveryMarkers)
@@ -134,34 +138,53 @@ export async function runShadowFidelity(opts: ShadowOptions): Promise<void> {
         const ppid = tmux(o.sock, 'display', '-p', '-t', o.addr, '#{pane_pid}')
         const pid = ppid.ok ? Number(ppid.out.trim()) : NaN
         const livPty = Number.isFinite(pid) ? pidAlive(pid) : false
+        const hasHistory = o.term.buffer.active.baseY > 0
 
-        tot.samples++
-        const occDiv = occPty !== occTmux, rgDiv = rgTmux !== null && rgPty !== rgTmux, livDiv = livPty !== livTmux
-        const occNt = occPty || occTmux
-        if (occNt) tot.occNt++
-        if (occDiv) tot.occDiv++
-        if (rgDiv) tot.rgDiv++
-        if (livDiv) tot.livDiv++
-        if (occDiv || rgDiv || livDiv) {
+        // Feed the gate tracker — it scores DIRECTION (behind=hard / ahead=benign-if-boot-self-heal)
+        // and accumulates the COVERAGE matrix. The boolean booleans never leave this call.
+        tracker.sample(i, {
+          peer: o.addr, runtime: o.runtime,
+          occupancy: { pty: occPty, tmux: occTmux },
+          readyGate: { pty: rgPty, tmux: rgTmux },
+          liveness: { pty: livPty, tmux: livTmux },
+          bytesFed, hasHistory,
+        })
+
+        // DIRECTION-AWARE per-event divergence trail (gate scoring lives in the tracker; this is
+        // the forensic log). Occupancy carries the raw capture + model frames for root-cause.
+        const occDir = classifyDirection(occPty, occTmux)
+        const rgDir = rgTmux === null ? 'agree' : classifyDirection(rgPty, rgTmux)
+        const livDir = classifyDirection(livPty, livTmux)
+        if (occDir !== 'agree' || rgDir !== 'agree' || livDir !== 'agree') {
           appendFileSync(jsonl, JSON.stringify({
-            ts: new Date().toISOString(), peer: o.addr, geom: `${o.cols}x${o.rows}`,
-            occupancy: { pty: occPty, tmux: occTmux, diverged: occDiv, nontrivial: occNt },
-            readyGate: { pty: rgPty, tmux: rgTmux, diverged: rgDiv },
-            liveness: { pty: livPty, tmux: livTmux, diverged: livDiv },
-            ...(occDiv ? { capE: capE.out.slice(-2500), model: modelToPlainText(o.term, o.cols, o.rows).slice(-2500) } : {}),
+            ts: new Date().toISOString(), peer: o.addr, geom: `${o.cols}x${o.rows}`, hasHistory,
+            occupancy: { pty: occPty, tmux: occTmux, dir: occDir },
+            readyGate: { pty: rgPty, tmux: rgTmux, dir: rgDir },
+            liveness: { pty: livPty, tmux: livTmux, dir: livDir },
+            ...(occDir !== 'agree' ? { capE: capE.out.slice(-2500), model: modelToPlainText(o.term, o.cols, o.rows).slice(-2500) } : {}),
           }) + '\n')
-          log(`DIVERGE ${o.addr} occ=${occDiv} rg=${rgDiv} liv=${livDiv}${occNt && occDiv ? ' *** NON-TRIVIAL occ ***' : ''}\n`)
+          log(`DIVERGE ${o.addr} occ=${occDir} rg=${rgDir} liv=${livDir}\n`)
         }
       } catch { /* an observer error must NEVER escape — it is a passive sidecar */ }
     }
     i++
+    const gs = tracker.summary()
+    const totalSamples = VERDICTS.reduce((n, v) => n + gs.verdicts[v].samples, 0)
     writeFileSync(statsFile, JSON.stringify({
       startedISO, lastISO: new Date().toISOString(), elapsedMin: +((Date.now() - t0) / 60000).toFixed(1),
-      peers: models.size, samples: tot.samples,
-      occupancy: { divergences: tot.occDiv, nonTrivialSamples: tot.occNt },
-      readyGate: { divergences: tot.rgDiv },
-      liveness: { divergences: tot.livDiv },
-      fidelity: tot.samples ? +(1 - (tot.occDiv + tot.rgDiv + tot.livDiv) / (tot.samples * 3)).toFixed(6) : 1,
+      peers: models.size, samples: totalSamples,
+      // Gate (boris's criterion): clean iff zero hard divergences across all verdicts. Hard =
+      // every pty-behind + non-benign pty-ahead (steady-state or non-converging). Benign =
+      // 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),
     }, null, 2))
     if (opts.once) break
     await new Promise(r => setTimeout(r, interval))

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 {
+      /* */
+    }
+  })
+}