@agfpd/iapeer 0.2.59 → 0.2.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.59",
+  "version": "0.2.60",
   "description": "Foundation core for the iapeer multi-agent ecosystem: identity, registry, storage, codec.",
   "type": "module",
   "bin": {

package/src/shadow/gate.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  GateTracker,
+  classifyDirection,
+  classifySampleState,
+  type PeerSample,
+} 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'])
+  })
+})

package/src/shadow/gate.ts

@@ -0,0 +1,306 @@
+// 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
+  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
+  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, 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
+
+    // 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()),
+      },
+    }
+  }
+}
+
+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>
+}
+
+export interface GateSummary {
+  verdicts: Record<Verdict, VerdictGateStat>
+  hardViolations: HardViolation[]
+  coverage: GateCoverage
+}

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, 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,49 @@ 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,
+      verdicts: gs.verdicts,
+      coverage: gs.coverage,
+      recentHard: gs.hardViolations.slice(-20),
     }, null, 2))
     if (opts.once) break
     await new Promise(r => setTimeout(r, interval))