@agfpd/iapeer 0.2.59 → 0.2.61

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.59",
+  "version": "0.2.61",
   "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

@@ -0,0 +1,249 @@
+import { describe, expect, test } from 'bun:test'
+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
+// known-ahead and records coverage CORRECTLY — the live proof that it measures right before we
+// trust any pty verdict for a flip. Pure: no tmux, no @xterm, booleans in, gate stats out.
+
+const mkSample = (peer: string, runtime: string, over: Partial<PeerSample> = {}): PeerSample => ({
+  peer,
+  runtime,
+  occupancy: { pty: false, tmux: false },
+  readyGate: { pty: false, tmux: false },
+  liveness: { pty: true, tmux: true },
+  bytesFed: 0,
+  hasHistory: false,
+  ...over,
+})
+
+describe('classifyDirection (tmux authoritative; true = active/ready/alive pole)', () => {
+  test('equal → agree', () => {
+    expect(classifyDirection(true, true)).toBe('agree')
+    expect(classifyDirection(false, false)).toBe('agree')
+  })
+  test('pty under-reports (false vs true) → pty-behind (the stale class)', () => {
+    expect(classifyDirection(false, true)).toBe('pty-behind')
+  })
+  test('pty over-reports (true vs false) → pty-ahead', () => {
+    expect(classifyDirection(true, false)).toBe('pty-ahead')
+  })
+})
+
+describe('classifySampleState (coverage regimes — idle must be distinguishable, false-green lesson)', () => {
+  test('tmux occupancy → composer-busy (regardless of bytes)', () => {
+    expect(classifySampleState(true, 0)).toBe('composer-busy')
+    expect(classifySampleState(true, 999)).toBe('composer-busy')
+  })
+  test('no occupancy + output churn → model-advancing (non-trivial regime)', () => {
+    expect(classifySampleState(false, 4096)).toBe('model-advancing')
+  })
+  test('no occupancy + no churn → idle', () => {
+    expect(classifySampleState(false, 0)).toBe('idle')
+  })
+})
+
+describe('GateTracker — direction is scored hard vs benign per the adjudicated criterion', () => {
+  test('pty-BEHIND is ALWAYS hard (zero tolerance) and closes the verdict gate', () => {
+    const g = new GateTracker()
+    g.sample(0, mkSample('p', 'claude', { occupancy: { pty: false, tmux: true } }))
+    const s = g.summary()
+    expect(s.verdicts.occupancy.behind).toBe(1)
+    expect(s.verdicts.occupancy.gateClean).toBe(false)
+    expect(s.hardViolations.some(v => v.kind === 'behind' && v.verdict === 'occupancy')).toBe(true)
+  })
+
+  test('boot-window pty-AHEAD that self-heals within budget → BENIGN (latency recorded)', () => {
+    const g = new GateTracker({ settleTicks: 3, convergeBudgetTicks: 3 })
+    // tick0: readyGate ahead (pty ready, tmux not) — peer just born → boot window
+    g.sample(0, mkSample('p', 'claude', { readyGate: { pty: true, tmux: false } }))
+    // tick1: readyGate agrees (both ready) → transient closes, latency 1, boot+within budget → benign
+    g.sample(1, mkSample('p', 'claude', { readyGate: { pty: true, tmux: true } }))
+    const rg = g.summary().verdicts.readyGate
+    expect(rg.aheadBenign).toBe(1)
+    expect(rg.aheadHard).toBe(0)
+    expect(rg.gateClean).toBe(true)
+    expect(rg.selfHeal.count).toBe(1)
+    expect(rg.selfHeal.max).toBe(1)
+  })
+
+  test('READY-GATE non-converging pty-AHEAD is HARD, never benign (refinement #3: false-ready = msg-loss)', () => {
+    const g = new GateTracker({ settleTicks: 3, convergeBudgetTicks: 3 })
+    // hold readyGate ahead (pty ready, tmux NEVER ready → stays in boot window, never converges)
+    for (let t = 0; t <= 5; t++) g.sample(t, mkSample('p', 'codex', { readyGate: { pty: true, tmux: false } }))
+    const rg = g.summary().verdicts.readyGate
+    expect(rg.aheadHard).toBeGreaterThanOrEqual(1)
+    expect(rg.aheadBenign).toBe(0)
+    expect(rg.gateClean).toBe(false)
+    expect(g.summary().hardViolations.some(v => v.kind === 'ahead-nonconverged' && v.verdict === 'readyGate')).toBe(true)
+  })
+
+  test('STEADY-STATE pty-AHEAD is HARD immediately (cannot be a boot self-heal)', () => {
+    const g = new GateTracker({ settleTicks: 2, convergeBudgetTicks: 3 })
+    // boot the peer: readyGate true for settleTicks
+    g.sample(0, mkSample('p', 'claude', { readyGate: { pty: true, tmux: true } }))
+    g.sample(1, mkSample('p', 'claude', { readyGate: { pty: true, tmux: true } })) // bootDone now
+    // steady-state occupancy ahead → hard 'ahead-steady'
+    g.sample(2, mkSample('p', 'claude', { readyGate: { pty: true, tmux: true }, occupancy: { pty: true, tmux: false } }))
+    const occ = g.summary().verdicts.occupancy
+    expect(occ.aheadHard).toBeGreaterThanOrEqual(1)
+    expect(g.summary().hardViolations.some(v => v.kind === 'ahead-steady' && v.verdict === 'occupancy')).toBe(true)
+  })
+
+  test('full agreement → clean gate, zero hard violations', () => {
+    const g = new GateTracker()
+    for (let t = 0; t < 5; t++) g.sample(t, mkSample('p', 'claude', { readyGate: { pty: true, tmux: true } }))
+    const s = g.summary()
+    expect(s.hardViolations).toHaveLength(0)
+    expect(s.verdicts.readyGate.gateClean).toBe(true)
+    expect(s.verdicts.occupancy.gateClean).toBe(true)
+    expect(s.verdicts.liveness.gateClean).toBe(true)
+  })
+})
+
+describe('GateTracker — coverage matrix (clean counts only over traversed cells)', () => {
+  test('births split fresh vs wake-resume by history-at-first-sight', () => {
+    const g = new GateTracker()
+    g.tickStart(1)
+    g.sample(0, mkSample('fresh-peer', 'claude', { hasHistory: false }))
+    g.tickStart(2)
+    g.sample(1, mkSample('woke-peer', 'codex', { hasHistory: true })) // history at first sight = wake-resume
+    const cov = g.summary().coverage
+    expect(cov.births['claude/fresh']).toBe(1)
+    expect(cov.births['codex/wake-resume']).toBe(1)
+  })
+
+  test('a peer that died and reappeared is a restart', () => {
+    const g = new GateTracker()
+    g.sample(0, mkSample('p', 'claude'))
+    g.peerGone('p')
+    g.sample(5, mkSample('p', 'claude'))
+    expect(g.summary().coverage.restarts['claude']).toBe(1)
+  })
+
+  test('state cells, fleet width, and history samples are recorded', () => {
+    const g = new GateTracker()
+    g.tickStart(3) // fleet width 3 this tick
+    g.sample(0, mkSample('p', 'claude', { occupancy: { pty: true, tmux: true } })) // composer-busy
+    g.sample(1, mkSample('p', 'claude', { bytesFed: 4096 })) // model-advancing
+    g.sample(2, mkSample('p', 'claude', { bytesFed: 0 })) // idle
+    g.sample(3, mkSample('h', 'codex', { hasHistory: true }))
+    const cov = g.summary().coverage
+    expect(cov.fleetWidthMax).toBe(3)
+    expect(cov.byRuntimeState['claude/composer-busy']).toBe(1)
+    expect(cov.byRuntimeState['claude/model-advancing']).toBe(1)
+    expect(cov.byRuntimeState['claude/idle']).toBe(1)
+    expect(cov.historySamples['codex']).toBe(1)
+    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

@@ -0,0 +1,372 @@
+// Gate-grade instrumentation for the tmux→pty fidelity burn-in (cutover Block 1).
+//
+// PURE classifiers + one stateful tracker, with NO tmux and NO @xterm import — the observer
+// loop feeds it booleans, so all classification is hermetically unit-testable. That is exactly
+// the synthetic acceptance boris requires: PROVE the instrument classifies known-behind vs
+// known-ahead and records coverage correctly BEFORE we trust any pty verdict for a flip.
+//
+// It operationalizes the adjudicated gate criterion (NOT a flat sample count):
+//   • DIRECTION — pty-BEHIND (pty=False,tmux=True: a stale frame while live tmux moved on) is
+//     the reattach-stale class → ZERO tolerance, always hard. pty-AHEAD (pty=True,tmux=False)
+//     is benign ONLY when it (a) opened in the boot window, (b) self-heals within the converge
+//     budget, and (c) is not steady-state. Anything else → hard. For READY-GATE a non-converging
+//     ahead is a FALSE-ready (early-delivery → msg-loss class), so it is hard, never benign.
+//   • COVERAGE — which matrix cells the burn-in actually traversed {runtime × {idle,
+//     model-advancing, composer-busy}} + births (fresh vs wake-resume-with-history) + restarts +
+//     history-bearing samples + fleet width. "Clean" counts only over traversed cells (idle
+//     alone is a false green).
+
+export type Verdict = 'occupancy' | 'readyGate' | 'liveness'
+export const VERDICTS: Verdict[] = ['occupancy', 'readyGate', 'liveness']
+
+export type Direction = 'agree' | 'pty-behind' | 'pty-ahead'
+
+/**
+ * Direction of a (pty, tmux) verdict pair. tmux is AUTHORITATIVE; `true` is the
+ * active/ready/alive pole. pty UNDER-reporting it (pty=false, tmux=true) is BEHIND — the
+ * stale-frame class (zero tolerance). pty OVER-reporting (pty=true, tmux=false) is AHEAD.
+ */
+export function classifyDirection(ptyVal: boolean, tmuxVal: boolean): Direction {
+  if (ptyVal === tmuxVal) return 'agree'
+  return tmuxVal ? 'pty-behind' : 'pty-ahead'
+}
+
+export type SampleState = 'idle' | 'model-advancing' | 'composer-busy'
+
+/**
+ * Per-sample fleet state for the coverage matrix. composer-busy when tmux (authoritative) sees
+ * human occupancy; else model-advancing when output churned this tick (the model is actively
+ * rendering — the NON-trivial fidelity regime, not at rest); else idle. The split is what keeps
+ * an idle burn-in from reading as a false green (boris's acceptance lesson).
+ */
+export function classifySampleState(occTmux: boolean, bytesFedThisTick: number): SampleState {
+  if (occTmux) return 'composer-busy'
+  if (bytesFedThisTick > 0) return 'model-advancing'
+  return 'idle'
+}
+
+export interface VerdictSample {
+  /** null when the tmux side was unavailable this tick (capture failed) — skipped, not scored. */
+  pty: boolean
+  tmux: boolean | null
+}
+
+export interface PeerSample {
+  peer: string
+  runtime: string
+  occupancy: VerdictSample
+  readyGate: VerdictSample
+  liveness: VerdictSample
+  /** Bytes appended to this peer's pane-log since the previous tick (drives state coverage). */
+  bytesFed: number
+  /** The model already carries scrollback (transcript taller than the pane) — a history-bearing
+   *  peer; at first sight this means it woke WITH resume-history (vs a fresh empty birth). */
+  hasHistory: boolean
+}
+
+export interface GateConfig {
+  /** Consecutive tmux-ready ticks after which a peer is considered booted (out of the boot
+   *  window). Default 3. */
+  settleTicks?: number
+  /** Max ticks an ahead-transient may stay open and still count as a benign self-heal.
+   *  Default 3. */
+  convergeBudgetTicks?: number
+}
+
+export interface HardViolation {
+  peer: string
+  runtime: string
+  verdict: Verdict
+  tick: number
+  kind: 'behind' | 'ahead-steady' | 'ahead-nonconverged'
+  detail?: string
+}
+
+interface OpenAhead {
+  startTick: number
+  bootWindow: boolean
+  flaggedNonConverged: boolean
+}
+
+interface PeerState {
+  runtime: string
+  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>
+}
+
+interface VerdictTally {
+  samples: number
+  agree: number
+  behind: number
+  aheadBenign: number
+  aheadHard: number
+  aheadLatencies: number[]
+}
+
+export class GateTracker {
+  private readonly settleTicks: number
+  private readonly budget: number
+  private peers = new Map<string, PeerState>()
+  private goneOnce = new Set<string>()
+  private tally: Record<Verdict, VerdictTally>
+  private hard: HardViolation[] = []
+  // coverage
+  private fleetWidthMax = 0
+  private stateCells = new Map<string, number>() // `${runtime}/${state}` → count
+  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 = {}) {
+    this.settleTicks = cfg.settleTicks ?? 3
+    this.budget = cfg.convergeBudgetTicks ?? 3
+    const mk = (): VerdictTally => ({ samples: 0, agree: 0, behind: 0, aheadBenign: 0, aheadHard: 0, aheadLatencies: [] })
+    this.tally = { occupancy: mk(), readyGate: mk(), liveness: mk() }
+  }
+
+  /** Once per tick, before the per-peer samples — records the concurrent fleet width. */
+  tickStart(nPeers: number): void {
+    if (nPeers > this.fleetWidthMax) this.fleetWidthMax = nPeers
+  }
+
+  /** The observer dropped a peer (session gone) — a later reappearance is a restart. */
+  peerGone(addr: string): void {
+    if (this.peers.delete(addr)) this.goneOnce.add(addr)
+  }
+
+  private inc(map: Map<string, number>, key: string): void {
+    map.set(key, (map.get(key) ?? 0) + 1)
+  }
+
+  /** Record one peer's sample at `tick`. Updates boot state, classifies every verdict's
+   *  direction, manages ahead-transients, and accumulates the coverage matrix. */
+  sample(tick: number, s: PeerSample): void {
+    this.runtimesSeen.add(s.runtime)
+    let ps = this.peers.get(s.peer)
+    if (!ps) {
+      // First sight this lifetime → a birth (or a restart if we saw it die before).
+      const birthType = s.hasHistory ? 'wake-resume' : 'fresh'
+      this.inc(this.births, `${s.runtime}/${birthType}`)
+      if (this.goneOnce.has(s.peer)) {
+        this.inc(this.restarts, s.runtime)
+        this.goneOnce.delete(s.peer)
+      }
+      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)
+    }
+
+    // Boot-window: a peer is booted once tmux-ready has held true for settleTicks in a row.
+    if (s.readyGate.tmux === true) {
+      ps.readyStreak++
+      if (ps.readyStreak >= this.settleTicks) ps.bootDone = true
+    } else if (s.readyGate.tmux === false) {
+      ps.readyStreak = 0
+    }
+    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}`)
+    if (s.hasHistory) this.inc(this.historySamples, s.runtime)
+
+    // Per-verdict direction + transient bookkeeping.
+    this.scoreVerdict('occupancy', tick, ps, bootWindow, s.runtime, s.peer, s.occupancy)
+    this.scoreVerdict('readyGate', tick, ps, bootWindow, s.runtime, s.peer, s.readyGate)
+    this.scoreVerdict('liveness', tick, ps, bootWindow, s.runtime, s.peer, s.liveness)
+  }
+
+  private scoreVerdict(
+    verdict: Verdict,
+    tick: number,
+    ps: PeerState,
+    bootWindow: boolean,
+    runtime: string,
+    peer: string,
+    vs: VerdictSample,
+  ): void {
+    if (vs.tmux === null) return // tmux side unavailable → not scored
+    const t = this.tally[verdict]
+    t.samples++
+    const dir = classifyDirection(vs.pty, vs.tmux)
+
+    // An open ahead-transient that exceeds the converge budget is a hard violation the moment
+    // it overruns (logged once), regardless of how it later resolves.
+    const open = ps.open[verdict]
+    if (open && !open.flaggedNonConverged && tick - open.startTick > this.budget) {
+      open.flaggedNonConverged = true
+      t.aheadHard++
+      this.hard.push({ peer, runtime, verdict, tick, kind: 'ahead-nonconverged', detail: `ahead open ${tick - open.startTick} ticks > budget ${this.budget}` })
+    }
+
+    if (dir === 'agree') {
+      t.agree++
+      if (open) {
+        // transient closed → measure self-heal latency; benign iff it opened in the boot
+        // window AND healed within budget (and was not already flagged non-converged).
+        const latency = tick - open.startTick
+        t.aheadLatencies.push(latency)
+        if (!open.flaggedNonConverged) {
+          if (open.bootWindow && latency <= this.budget) t.aheadBenign++
+          else {
+            t.aheadHard++
+            this.hard.push({ peer, runtime, verdict, tick, kind: open.bootWindow ? 'ahead-nonconverged' : 'ahead-steady', detail: `latency ${latency}, boot=${open.bootWindow}` })
+          }
+        }
+        ps.open[verdict] = null
+      }
+      return
+    }
+
+    if (dir === 'pty-behind') {
+      // The stale-frame class — always hard, zero tolerance. A behind also closes any open
+      // ahead-transient as an abnormal resolution (not a benign heal).
+      t.behind++
+      this.hard.push({ peer, runtime, verdict, tick, kind: 'behind' })
+      ps.open[verdict] = null
+      return
+    }
+
+    // pty-ahead: open a transient if none is open. Steady-state ahead is hard immediately
+    // (it cannot be a boot self-heal); boot-window ahead waits to see if it converges.
+    if (!open) {
+      if (!bootWindow) {
+        t.aheadHard++
+        this.hard.push({ peer, runtime, verdict, tick, kind: 'ahead-steady' })
+        // still open it so we can measure when it clears, but it is already counted hard
+        ps.open[verdict] = { startTick: tick, bootWindow: false, flaggedNonConverged: true }
+      } else {
+        ps.open[verdict] = { startTick: tick, bootWindow: true, flaggedNonConverged: false }
+      }
+    }
+  }
+
+  /** True iff no hard divergence has been recorded for `verdict` (the per-verdict gate bar). */
+  verdictGateClean(verdict: Verdict): boolean {
+    const t = this.tally[verdict]
+    return t.behind === 0 && t.aheadHard === 0
+  }
+
+  summary(): GateSummary {
+    const latStats = (xs: number[]): { count: number; max: number; mean: number } =>
+      xs.length ? { count: xs.length, max: Math.max(...xs), mean: +(xs.reduce((a, b) => a + b, 0) / xs.length).toFixed(2) } : { count: 0, max: 0, mean: 0 }
+    const verdicts = {} as Record<Verdict, VerdictGateStat>
+    for (const v of VERDICTS) {
+      const t = this.tally[v]
+      verdicts[v] = {
+        samples: t.samples,
+        agree: t.agree,
+        behind: t.behind,
+        aheadBenign: t.aheadBenign,
+        aheadHard: t.aheadHard,
+        selfHeal: latStats(t.aheadLatencies),
+        gateClean: this.verdictGateClean(v),
+      }
+    }
+    return {
+      verdicts,
+      hardViolations: this.hard.slice(),
+      coverage: {
+        fleetWidthMax: this.fleetWidthMax,
+        runtimes: [...this.runtimesSeen].sort(),
+        byRuntimeState: Object.fromEntries([...this.stateCells].sort()),
+        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
+  behind: number
+  aheadBenign: number
+  aheadHard: number
+  selfHeal: { count: number; max: number; mean: number }
+  gateClean: boolean
+}
+
+export interface GateCoverage {
+  fleetWidthMax: number
+  runtimes: string[]
+  byRuntimeState: Record<string, number>
+  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 {
+  verdicts: Record<Verdict, VerdictGateStat>
+  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[]
+}