@agfpd/iapeer 0.4.8 → 0.4.9

package/src/launch/canary.ts

@@ -1,239 +0,0 @@
-// Server-death canary — the SERVER-level catcher for the exit-cause gap the
-// pane-died hook structurally cannot close (контракт: pane-died needs a living
-// tmux event loop; SIGKILL/OOM to the tmux SERVER runs no hook). Raised from the
-// deferred backlog after the SECOND live case of the class (both: a healthy
-// session with active Bash subprocessing, the whole server gone silently, zero
-// system traces).
-//
-// Mechanism: one tiny detached `sh` per LIVE tmux server, holding a blocking
-// client `tmux -S <sock> wait-for iap-canary-<identity>` — a process OUTSIDE the
-// dying server, connected via its socket, so the server's death (any cause,
-// including SIGKILL) is observed the moment the connection drops. Protocol (v2 —
-// a live death proved v1's exit-code trust wrong twice over: the killer
-// took the SERVER and the canary CLIENT together, AND a TERMed tmux client
-// returns rc=0 — indistinguishable from a clean channel signal — so the rc-based
-// `0 || ≥128 → silent` guard silenced a real death):
-//   • DELIBERATE silence is an explicit act, never an exit-code inference:
-//     every deliberate teardown (idle-reap / stop / pre-clean / pane-died hook /
-//     bootout teardown) signals the channel (`wait-for -S`) AND dismisses the
-//     sh recorder (`dismissCanary` → TERM → trap → silent exit). POSIX trap
-//     semantics make this race-free: the trap runs before any recording.
-//   • When wait-for returns — ANY code — the script sleeps 2 s (a concurrent
-//     dismissal TERM wins here), then probes the ORIGINAL SERVER PID captured at
-//     arm time: still alive → exit silently (a lost canary is re-armed and logged
-//     by the supervise retrofit within a tick); gone with nobody having dismissed
-//     us → the death is real and unclaimed → ONE logfmt line `ev=server-exit`
-//     into exits.log (the per-peer death-cause home, next to pane-died's
-//     `ev=session-exit`) + a forensics snapshot (vm_stat / swap / top-RSS ps /
-//     fresh DiagnosticReports) captured within seconds — the evidence the 60 s
-//     supervise tick can never recover (zero system traces was the recurring
-//     investigation outcome). PID identity matters: a wake/attach can replace the
-//     tmux server on the same socket before the 2 s grace elapses; probing only
-//     the socket would mistake the successor for the dead original and lose the
-//     canary record (a live canary-gap).
-//     The raw wait_rc still ATTRIBUTES the death (cause=server-vanished /
-//     signaled-server-gone / client-killed-server-gone).
-// Residual blind spot (structural): a killer that SIGKILLs the sh recorder
-// itself leaves no in-process way to record. With v2 the ABSENCE of a record on
-// a server-dead reap narrows the diagnosis to exactly that shape; the canary
-// ensure-state lines in lifecycle.log (origin=launch/retrofit) evidence the
-// churn post-hoc.
-//
-// The canary is pure observability: it never wakes, reaps, restarts or otherwise
-// manages anything (H4-compatible by construction), it fires at most once, and
-// every failure to spawn/record is swallowed (never load-bearing). The daemon's
-// reaped-gone death-class (classifyGoneSession) remains the detection backstop
-// when no canary was running.
-
-import { spawn, spawnSync } from 'child_process'
-import { mkdirSync } from 'fs'
-import { join } from 'path'
-import { resolveExecutable } from './launchd.ts'
-import { cmdLogDirFor } from './cmdlog.ts'
-
-/** The exit-cause log file inside `exitLogDir` (sibling to lifecycle.log).
- *  Lives here (not index.ts) so canary ⇆ launch never import-cycle; index.ts
- *  re-exports it, keeping the public import surface unchanged. */
-export function exitLogPath(exitLogDir: string): string {
-  return `${exitLogDir}/exits.log`
-}
-
-/** The per-identity tmux wait-for channel the clean-teardown paths signal. */
-export function canaryChannel(identity: string): string {
-  return `iap-canary-${identity}`
-}
-
-/** Forensics snapshots live next to exits.log: `<exitLogDir>/server-deaths/`. */
-export function serverDeathsDir(exitLogDir: string): string {
-  return join(exitLogDir, 'server-deaths')
-}
-
-export interface CanaryScriptOptions {
-  identity: string
-  sock: string
-  /** Absolute tmux path — the detached canary may outlive any rich PATH. */
-  tmuxBin: string
-  exitLogFile: string
-  forensicsDir: string
-  /** The identity's tmux-cmdlog dir (<exitLogDir>/tmux-cmdlog/<identity>). When set,
-   *  the death forensics tail the dead server's `tmux-server-<SPID>.log` — the ONLY
-   *  witness of a client-COMMAND kill (`kill-server`/`kill-session`), which leaves zero
-   *  signals (so signal forensics see nothing) and is otherwise wiped by the respawn's
-   *  prepareCmdLogDir before anyone reads it. Best-effort: absent log → grep no-ops. */
-  cmdLogDir?: string
-}
-
-/**
- * Build the canary shell script (PURE — unit-testable). Quoting: identity is a
- * runtime-personality (`[a-z0-9-]`), sock/log paths are ~/.iapeer-style (no
- * single quotes) — same assumption as exitCauseHook. All forensic tools are
- * /usr/bin- or /bin-resident, so the script survives launchd's minimal PATH;
- * only tmux needs the baked absolute path.
- */
-export function canaryScript(o: CanaryScriptOptions): string {
-  const ch = canaryChannel(o.identity)
-  return [
-    // Server PID captured while alive — the postmortem grep key for system logs.
-    `SPID="$('${o.tmuxBin}' -S '${o.sock}' display-message -p '#{pid}' 2>/dev/null)"`,
-    // A signal to the SH WRAPPER is deliberate dismissal (dismissCanary) or host
-    // shutdown → silent. POSIX: the trap runs after the foreground command
-    // completes — so a TERM delivered during wait-for/sleep always exits us
-    // BEFORE any recording below (the race-free deliberate-silence guarantee).
-    `trap 'exit 0' HUP INT TERM`,
-    `'${o.tmuxBin}' -S '${o.sock}' wait-for '${ch}'`,
-    `rc=$?`,
-    // NO wait-for exit code is trusted as "deliberate" by itself — PROVEN live
-    // (a death postmortem): a TERM to the tmux CLIENT returns rc=0, identical
-    // to a clean channel signal, so an external killer sweeping server+client
-    // rides the clean-looking code straight past any rc-based guard (v1's
-    // `rc=0 || rc>=128 → silent` was exactly that hole). v2 contract instead:
-    //   • deliberate teardowns DISMISS this sh (TERM → trap above) — the sleep
-    //     below gives a concurrently-delivered dismissal time to win;
-    //   • then the ORIGINAL SERVER PID's liveness, not the exit code, decides: alive →
-    //     nothing to record (a lost canary is re-armed and logged by the
-    //     supervise retrofit within a tick); original server dead and nobody
-    //     dismissed us → the death is real and unclaimed → record it. IMPORTANT:
-    //     check the ORIGINAL SPID, not merely "some server answers on the same
-    //     socket". A wake/attach can replace the server inside this 2 s window;
-    //     socket-liveness would then silently swallow the predecessor's death.
-    `sleep 2`,
-    `if [ -n "$SPID" ] && kill -0 "$SPID" 2>/dev/null; then exit 0; fi`,
-    `if [ -z "$SPID" ] && '${o.tmuxBin}' -S '${o.sock}' has-session 2>/dev/null; then exit 0; fi`,
-    // The exit code still ATTRIBUTES the recorded death (raw wait_rc is kept):
-    //   rc=0   → signaled-server-gone   (channel signal or client-TERM, server died)
-    //   rc≥128 → client-killed-server-gone (client took a non-TERM kill)
-    //   else   → server-vanished        (connection drop — SIGKILL/OOM class)
-    `cause=server-vanished`,
-    `if [ "$rc" -eq 0 ]; then cause=signaled-server-gone; fi`,
-    `if [ "$rc" -ge 128 ]; then cause=client-killed-server-gone; fi`,
-    // The server is gone under us — record, within seconds of the death.
-    `ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"`,
-    `f='${o.forensicsDir}/${o.identity}'-"$(date +%s)".txt`,
-    `{`,
-    `  echo "server-death identity=${o.identity} ts=$ts server_pid=$SPID wait_rc=$rc cause=$cause"`,
-    `  echo '--- vm_stat'; vm_stat`,
-    `  echo '--- swapusage'; /usr/sbin/sysctl -n vm.swapusage`,
-    `  echo '--- ps-top-rss'; ps axo pid,ppid,rss,etime,command | sort -rn -k3 | head -25`,
-    `  echo '--- diagnosticreports-user'; ls -t "$HOME/Library/Logs/DiagnosticReports" 2>/dev/null | head`,
-    `  echo '--- diagnosticreports-system'; ls -t /Library/Logs/DiagnosticReports 2>/dev/null | head`,
-    // The death-class discriminator signal-forensics structurally cannot see: a tmux
-    // server killed by a CLIENT COMMAND (`kill-server`/`kill-session`) leaves zero
-    // signals. Its only witness is the dead server's own -v cmdlog, which the respawn
-    // wipes seconds later — captured HERE (canary fires ~+2 s, respawn ~+7 s) so the
-    // killer's `client-<pid> command: …` survives into the forensics.
-    ...(o.cmdLogDir
-      ? [
-          `  echo '--- cmdlog-tail (last client commands; a kill-server/kill-session here IS the killer)'`,
-          `  tail -c 131072 '${o.cmdLogDir}/tmux-server-'"$SPID"'.log' 2>/dev/null | grep -aE 'command:' | tail -30`,
-        ]
-      : []),
-    `} > "$f" 2>&1`,
-    `printf 'ts=%s ev=server-exit identity=${o.identity} server_pid=%s wait_rc=%s cause=%s forensics=%s\\n' "$ts" "$SPID" "$rc" "$cause" "$f" >> '${o.exitLogFile}'`,
-  ].join('\n')
-}
-
-export type CanaryEnsureState = 'spawned' | 'already' | 'skipped' | 'failed'
-
-export interface EnsureCanaryOptions {
-  identity: string
-  sock: string
-  /** Same gate as installExitHook: falsy → observability off, no canary. */
-  exitLogDir?: string
-  env?: NodeJS.ProcessEnv
-}
-
-/**
- * Ensure ONE canary is watching this identity's tmux server. Idempotent via a
- * pgrep on the wait-for channel (anchored so an identity can never match another
- * identity's prefix). Called from launch (newborn server) and from the supervise
- * tick's alive-branch (retrofits canaries onto a fleet launched by older code —
- * coverage within one tick of a deploy, no session restarts). Best-effort:
- * every failure returns a state, never throws.
- */
-export function ensureServerCanary(o: EnsureCanaryOptions): CanaryEnsureState {
-  if (!o.exitLogDir) return 'skipped'
-  const env = o.env ?? process.env
-  try {
-    const probe = spawnSync('pgrep', ['-f', `wait-for.*${canaryChannel(o.identity)}([^a-z0-9-]|$)`], {
-      stdio: 'ignore',
-      env: env as Record<string, string>,
-    })
-    if (probe.status === 0) return 'already'
-    const tmuxBin = resolveExecutable('tmux', env)
-    if (!tmuxBin) return 'failed'
-    const forensicsDir = serverDeathsDir(o.exitLogDir)
-    mkdirSync(forensicsDir, { recursive: true, mode: 0o700 })
-    mkdirSync(o.exitLogDir, { recursive: true, mode: 0o700 })
-    const script = canaryScript({
-      identity: o.identity,
-      sock: o.sock,
-      tmuxBin,
-      exitLogFile: exitLogPath(o.exitLogDir),
-      forensicsDir,
-      cmdLogDir: cmdLogDirFor(o.exitLogDir, o.identity),
-    })
-    const child = spawn('/bin/sh', ['-c', script], { detached: true, stdio: 'ignore', env })
-    child.unref()
-    return 'spawned'
-  } catch {
-    return 'failed' // observability is best-effort — never block a launch/tick
-  }
-}
-
-/**
- * Signal the canary that the upcoming server teardown is DELIBERATE (idle-reap /
- * stop / launch pre-clean / empty-server kill) so it exits silently instead of
- * recording a false server-death. Best-effort: no server / no canary on the
- * channel → harmless no-op.
- */
-export function signalCanaryClean(sock: string, identity: string): void {
-  try {
-    spawnSync('tmux', ['-S', sock, 'wait-for', '-S', canaryChannel(identity)], { stdio: 'ignore' })
-  } catch {
-    /* best-effort */
-  }
-}
-
-/** The pgrep/pkill ERE matching BOTH canary processes of ONE identity — the sh
- *  wrapper (its -c script quotes the channel: `…'iap-canary-<id>'…`) and the
- *  tmux client (argv ends with the bare channel). Anchored so an identity can
- *  never match another identity's prefix (claude-alice ≠ claude-alice-bob). */
-export function canaryProcessPattern(identity: string): string {
-  return `${canaryChannel(identity)}([^a-z0-9-]|$)`
-}
-
-/**
- * Dismiss this identity's canary BEFORE a deliberate server teardown: TERM the
- * sh wrapper (trap → silent exit, race-free — the trap always runs before the
- * v2 recording branch) and the tmux client. The explicit counterpart of the
- * channel signal: with v2 a signaled CLIENT alone is no longer read as
- * deliberate, so every deliberate path must dismiss the RECORDER (the sh).
- * Best-effort: no canary running → harmless no-op (pkill exits 1).
- */
-export function dismissCanary(identity: string): void {
-  try {
-    spawnSync('pkill', ['-f', canaryProcessPattern(identity)], { stdio: 'ignore' })
-  } catch {
-    /* best-effort */
-  }
-}

package/src/shadow/gate.ts

@@ -1,396 +0,0 @@
-// 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. The synthetic
-// acceptance: 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.
- */
-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
-  /** This peer reappeared after we saw it die (it was in goneOnce) — a gone→back resume/restart,
-   *  NOT a warm-continuous peer. The center cell's warm-exclusion discriminator. */
-  wasGoneReenroll: boolean
-  /** The center cell is evaluated exactly ONCE per life (first ready sample) — dedup guard. */
-  centerEvaluated: boolean
-  /** Previous tmux ready value, to annotate whether the not-ready→ready window was observed. */
-  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 (robust, first-sight): a gone→back-with-history peer whose readiness the MODEL
-  // matches tmux on at its first ready sample — the codex splash-off-screen case the ready-gate flip
-  // exists for. A model MISS there lands in readyGate.behind (dirty). PRIMARY eligibility counter.
-  private readyResumeCaught = new Map<string, number>() // runtime → count
-  // Diagnostic ONLY (not a threshold path): the subset of center hits where the not-ready→ready
-  // window was actually observed (prev===false) — "we caught the window", a stronger evidence note.
-  private readyResumeCaughtViaTransition = 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. A peer we saw DIE before (in goneOnce) reappearing is
-      // a gone→back cycle (a resume/restart, NOT a warm-continuous peer) — the discriminator the
-      // robust center cell keys on.
-      const birthType = s.hasHistory ? 'wake-resume' : 'fresh'
-      this.inc(this.births, `${s.runtime}/${birthType}`)
-      const reenrolled = this.goneOnce.has(s.peer)
-      if (reenrolled) {
-        this.inc(this.restarts, s.runtime)
-        this.goneOnce.delete(s.peer)
-      }
-      ps = {
-        runtime: s.runtime,
-        firstTick: tick,
-        readyStreak: 0,
-        bootDone: false,
-        bornWithHistory: s.hasHistory,
-        wasGoneReenroll: reenrolled,
-        centerEvaluated: false,
-        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 — cadence-ROBUST (first-sight, the SAME invariant births/restarts use), so a fast
-    // resume can't slip through a transition-polling gap. Counted ONCE per life (dedup: one resume =
-    // one center++) at the FIRST ready sample of a peer that (a) is a gone→back re-enroll (resume/
-    // restart, NOT warm-continuous — the warm-exclusion discriminator: a warm peer never entered
-    // goneOnce; also stricter than a transition, which a fresh peer's first boot would trip) and
-    // (b) re-enrolled WITH history (a resume-with-history). Parity there (rgPty===rgTmux===true) on a
-    // splash-off-screen frame validates the source swap; a model MISS is a pty-behind (the splash-blind
-    // bug) → readyGate.behind → dirty → ineligible. The observed not-ready→ready transition is kept as a
-    // DIAGNOSTIC annotation only ("we caught the window" — stronger evidence), NOT a second path to threshold.
-    if (s.readyGate.tmux !== null) {
-      if (ps.wasGoneReenroll && ps.bornWithHistory && !ps.centerEvaluated && s.readyGate.tmux === true) {
-        ps.centerEvaluated = true // evaluate exactly once, at the first ready sample
-        if (s.readyGate.pty === true) {
-          this.inc(this.readyResumeCaught, s.runtime)
-          if (ps.prevReadyTmux === false) this.inc(this.readyResumeCaughtViaTransition, s.runtime) // diagnostic: window caught
-        }
-      }
-      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()),
-        readyResumeCaughtViaTransition: Object.fromEntries([...this.readyResumeCaughtViaTransition].sort()),
-      },
-    }
-  }
-}
-
-/** Ready-gate FLIP eligibility — the 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. */
-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 → center-cell count: gone→back-with-history peers whose first-ready model verdict
-   *  matched tmux (robust, first-sight). The PRIMARY ready-gate-flip eligibility signal. */
-  readyResumeCaught: Record<string, number>
-  /** runtime → DIAGNOSTIC subset of readyResumeCaught where the not-ready→ready window was observed
-   *  (transition caught). Stronger evidence; NOT a separate threshold path. */
-  readyResumeCaughtViaTransition: 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[]
-}