switchroom 0.16.47 → 0.17.1

package/telegram-plugin/tests/busy-key-reaper.test.ts

@@ -0,0 +1,191 @@
+/**
+ * #2787 Mechanism B — gateway-glue coverage for the `claudeBusyKeys` orphan
+ * reaper and its lockstep shadow timestamp map.
+ *
+ * `gateway.ts` cannot be imported by a unit test — it boots the Telegram bot and
+ * the IPC listener on module load. So this harness wires the SAME containers the
+ * gateway owns (`claudeBusyKeys: Set`, `claudeBusyKeySince: Map`), the SAME
+ * delivery-confirm queue used as the reaper's proof gate, and the REAL
+ * `flushOnAgentDisconnect` used at bridge death — exactly as the gateway does
+ * (see `markClaudeBusyForInbound`, `reapOrphanBusyKeysNow`, the delivery-confirm
+ * sweep, and the `flushOnAgentDisconnect({ claudeBusyKeys, claudeBusyKeySince })`
+ * call). It reproduces the two real defects the pure-helper tests could not:
+ *
+ *   1. Lockstep across a disconnect → reconnect → re-mark: a stale
+ *      pre-disconnect timestamp must NOT survive to make a freshly-marked key
+ *      look orphan-old.
+ *   2. Slow-delivery safety: a merely-slow (up to ~5-min, #1922) delivery whose
+ *      key is still tracked in the confirm queue must NOT be reaped even long
+ *      past the grace, because `currentTurn == null` during the eager-mark→
+ *      enqueue window is not proof of idle.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import {
+  markBusyKeyLockstep,
+  reapOrphanBusyKeys,
+  clearBusyKeyLockstep,
+} from '../gateway/busy-key-reaper.js'
+import { flushOnAgentDisconnect } from '../gateway/disconnect-flush.js'
+import {
+  createDeliveryQueue,
+  trackDelivery,
+  ackDelivery,
+} from '../gateway/inbound-delivery-confirm.js'
+
+const TTL = 30_000
+
+/** The gateway's `reapOrphanBusyKeysNow` glue, reproduced verbatim: no turn in
+ *  flight, reap keyed on set membership + a delivery-queue proof gate. */
+function reap(
+  keys: Set<string>,
+  since: Map<string, number>,
+  q: ReturnType<typeof createDeliveryQueue>,
+  now: number,
+  ttlMs = TTL,
+): string[] {
+  return reapOrphanBusyKeys(keys, since, now, {
+    ttlMs,
+    hasPendingDelivery: (key) => q.pending.has(key),
+    log: () => {},
+  })
+}
+
+/** Minimal disconnect-flush deps carrying the two containers under test — the
+ *  real bridge-death path that clears busy keys. Mirrors the gateway's call. */
+function flushDeps(claudeBusyKeys: Set<string>, claudeBusyKeySince: Map<string, number>) {
+  return {
+    agentName: 'clerk',
+    activeStatusReactions: new Map(),
+    activeReactionMsgIds: new Map(),
+    activeTurnStartedAt: new Map<string, number>(),
+    claudeBusyKeys,
+    claudeBusyKeySince,
+    activeDraftStreams: new Map(),
+    clearActiveReactions: vi.fn(),
+    disposeProgressDriver: vi.fn(),
+    log: vi.fn(),
+  }
+}
+
+describe('#2787 Mechanism B — orphan reaper (gateway glue)', () => {
+  it('does NOT reap a slow-but-real delivery still tracked in the confirm queue, even far past the grace', () => {
+    const keys = new Set<string>()
+    const since = new Map<string, number>()
+    const q = createDeliveryQueue<{ text: string }>()
+
+    // Eager mark at delivery + track for ack (the normal user-inbound glue).
+    markBusyKeyLockstep(keys, since, '-100:4', 0)
+    trackDelivery(q, '-100:4', { text: 'slow but real' }, 0, '9001')
+
+    // currentTurn is still null 6 MINUTES later (the #1922 tail) — but the
+    // delivery is still pending its enqueue ack. The proof gate must protect it.
+    expect(reap(keys, since, q, 360_000)).toEqual([])
+    expect(keys.has('-100:4')).toBe(true)
+
+    // Once claude finally acks (enqueue lands), the queue entry clears; the
+    // gateway would then hold currentTurn and clear busy at turn_end.
+    expect(ackDelivery(q, '-100:4', '9001')).toBe(true)
+  })
+
+  it('reaps a TRUE orphan — busy-marked, no pending delivery, past the grace', () => {
+    const keys = new Set<string>()
+    const since = new Map<string, number>()
+    const q = createDeliveryQueue()
+
+    // A steer/interrupt inbound marks busy but is excluded from tracking
+    // (shouldTrackDelivery=false) — no queue entry. Its turn vanished without
+    // clearing busy: a genuine stuck marker.
+    markBusyKeyLockstep(keys, since, '555:_', 0)
+    expect(reap(keys, since, q, TTL)).toEqual(['555:_'])
+    expect(keys.has('555:_')).toBe(false)
+    expect(since.has('555:_')).toBe(false)
+  })
+
+  it('does not reap before the grace elapses', () => {
+    const keys = new Set<string>()
+    const since = new Map<string, number>()
+    const q = createDeliveryQueue()
+    markBusyKeyLockstep(keys, since, '555:_', 0)
+    expect(reap(keys, since, q, TTL - 1)).toEqual([])
+    expect(keys.has('555:_')).toBe(true)
+  })
+
+  it('disconnect → reconnect → re-mark: fresh timestamp, key NOT reaped as stale (the lockstep fix)', () => {
+    const keys = new Set<string>()
+    const since = new Map<string, number>()
+    const q = createDeliveryQueue()
+
+    // t=0 first mark.
+    markBusyKeyLockstep(keys, since, '-100:4', 0)
+
+    // Bridge dies at t=1000 — the REAL disconnect flush clears BOTH containers
+    // in lockstep (belt-and-suspenders to the set-membership guard).
+    flushOnAgentDisconnect(flushDeps(keys, since))
+    expect(keys.size).toBe(0)
+    expect(since.size).toBe(0)
+
+    // Reconnect and re-mark the SAME key at t=300_000 (well after the old stamp).
+    markBusyKeyLockstep(keys, since, '-100:4', 300_000)
+
+    // Pre-fix (stale t=0 stamp surviving the disconnect + a `!since.has` guard
+    // declining to re-stamp) the age would read 300_000ms ≫ grace and the key
+    // would be reaped THE INSTANT it was re-marked — re-opening the idle-drain
+    // while claude is about to process this very inbound. With the fix the stamp
+    // is fresh (t=300_000), so at t just past the re-mark it is NOT reaped.
+    expect(reap(keys, since, q, 305_000)).toEqual([]) // age 5s < 30s grace
+    expect(keys.has('-100:4')).toBe(true)
+
+    // ...and it DOES reap once the fresh grace genuinely elapses.
+    expect(reap(keys, since, q, 300_000 + TTL)).toEqual(['-100:4'])
+  })
+
+  it('disconnect while a delivery is pending: reconnect re-mark stays protected by the proof gate', () => {
+    const keys = new Set<string>()
+    const since = new Map<string, number>()
+    const q = createDeliveryQueue<{ text: string }>()
+
+    markBusyKeyLockstep(keys, since, '-100:4', 0)
+    trackDelivery(q, '-100:4', { text: 'inflight' }, 0, '42')
+
+    // Bridge flap: disconnect clears busy state; the offline buffer / re-deliver
+    // loop still owns the inbound. Reconnect re-marks + re-tracks it.
+    flushOnAgentDisconnect(flushDeps(keys, since))
+    markBusyKeyLockstep(keys, since, '-100:4', 5_000)
+    trackDelivery(q, '-100:4', { text: 'inflight' }, 5_000, '42')
+
+    // Even minutes later, still pending its ack → never reaped.
+    expect(reap(keys, since, q, 5_000 + 400_000)).toEqual([])
+    expect(keys.has('-100:4')).toBe(true)
+  })
+
+  it('prunes shadow-map entries whose key already left the set (no unbounded growth)', () => {
+    const keys = new Set<string>()
+    const since = new Map<string, number>()
+    const q = createDeliveryQueue()
+    // Simulate a direct clear that (hypothetically) left the map behind.
+    since.set('ghost:_', 0)
+    reap(keys, since, q, 999_999)
+    expect(since.has('ghost:_')).toBe(false)
+  })
+
+  it('re-mark of an already-busy key does NOT reset its timestamp (measures the true dangle)', () => {
+    const keys = new Set<string>()
+    const since = new Map<string, number>()
+    const q = createDeliveryQueue()
+    markBusyKeyLockstep(keys, since, 'k:_', 0)
+    markBusyKeyLockstep(keys, since, 'k:_', 20_000) // still busy → no re-stamp
+    expect(since.get('k:_')).toBe(0)
+    // Orphaned (no pending delivery) → reaps on the ORIGINAL stamp's grace.
+    expect(reap(keys, since, q, TTL)).toEqual(['k:_'])
+  })
+
+  it('clearBusyKeyLockstep removes from both containers', () => {
+    const keys = new Set<string>()
+    const since = new Map<string, number>()
+    markBusyKeyLockstep(keys, since, 'k:_', 0)
+    clearBusyKeyLockstep(keys, since, 'k:_')
+    expect(keys.has('k:_')).toBe(false)
+    expect(since.has('k:_')).toBe(false)
+  })
+})

package/telegram-plugin/tests/emission-authority-facade.test.ts

@@ -263,20 +263,21 @@ describe('claimOrDowngradePing — PR-4c over-ping decision moves into the faça
     expect(blockCode).not.toMatch(/\bawait\b/)
   })
 
-  it('claimOrDowngradePing appears EXACTLY ONCE in the gateway, inside the executeReply window (stream path untouched)', () => {
-    // The over-ping net exists ONLY in executeReply. executeStreamReply has no
-    // decideOverPing / firstPingAt / wasOverPingSuppressed and never calls
-    // claimOrDowngradePing — PR-4c does not touch the stream path.
+  it('claimOrDowngradePing appears EXACTLY ONCE in the gateway, inside the executeReply window', () => {
+    // The over-ping net exists ONLY in executeReply. The retired stream_reply
+    // tool (executeStreamReply) had no decideOverPing / firstPingAt /
+    // wasOverPingSuppressed and never called claimOrDowngradePing.
     const calls = [...gatewaySrc.matchAll(/\.claimOrDowngradePing\(/g)]
     expect(calls).toHaveLength(1)
     const callIdx = gatewaySrc.indexOf('.claimOrDowngradePing(')
     const execReplyIdx = gatewaySrc.indexOf('async function executeReply(')
-    const execStreamIdx = gatewaySrc.indexOf('async function executeStreamReply(')
+    // Upper bound: the next top-level function after executeReply.
+    const nextFnIdx = gatewaySrc.indexOf('\nasync function ', execReplyIdx + 1)
     expect(execReplyIdx).toBeGreaterThan(-1)
-    expect(execStreamIdx).toBeGreaterThan(execReplyIdx)
-    // The single call is inside executeReply (before executeStreamReply starts).
+    expect(nextFnIdx).toBeGreaterThan(execReplyIdx)
+    // The single call is inside executeReply.
     expect(callIdx).toBeGreaterThan(execReplyIdx)
-    expect(callIdx).toBeLessThan(execStreamIdx)
+    expect(callIdx).toBeLessThan(nextFnIdx)
   })
 })
 
@@ -370,20 +371,13 @@ describe('the 7 drain sites route through the façade with producers preserved v
   })
 })
 
-describe('the 2 lever-2 finalize blocks route through the façade', () => {
+describe('the lever-2 finalize block routes through the façade', () => {
   it('executeReply finalize routes via markSubstantiveFinalDelivered + finalizeCard (latch + clear preserved)', () => {
     const after = gatewaySrc.split('async function executeReply(')[1] ?? ''
-    const body = after.split('async function executeStreamReply(')[0] ?? after
+    const body = after.split('\nasync function ')[0]?.split('\nfunction ')[0] ?? after
     expect(body).toMatch(/markSubstantiveFinalDelivered\(\(\) => \{\s*\n\s*finalizeTurn\.finalAnswerEverDelivered = true/)
     expect(body).toMatch(/finalizeCard\(\(\) => \{\s*\n\s*clearActivitySummary\(finalizeTurn\)/)
   })
-
-  it('executeStreamReply finalize routes via markSubstantiveFinalDelivered + finalizeCard (latch + clear preserved)', () => {
-    const after = gatewaySrc.split('async function executeStreamReply(')[1] ?? ''
-    const body = after.split('\nasync function ')[0]?.split('\nfunction ')[0] ?? after
-    expect(body).toMatch(/markSubstantiveFinalDelivered\(\(\) => \{\s*\n\s*turn\.finalAnswerEverDelivered = true/)
-    expect(body).toMatch(/finalizeCard\(\(\) => \{\s*\n\s*clearActivitySummary\(turn\)/)
-  })
 })
 
 describe('per-turn construction — one façade per turn, explicit chat/thread key (PR-4e seam)', () => {

package/telegram-plugin/tests/emission-determinism-wiring.test.ts

@@ -52,8 +52,8 @@ describe('sticky finalAnswerEverDelivered latch (lever 1 precondition / R0)', ()
     // The latch is set true only at the points that set finalAnswerDelivered=true,
     // and only when the reply was substantive — so an ack never latches it.
     const setTrue = [...gatewaySrc.matchAll(/finalAnswerEverDelivered\s*=\s*true/g)]
-    // executeReply, executeStreamReply, silent-anchor merge, + the two lever-2
-    // finalize blocks (which are themselves substantive-gated).
+    // executeReply, silent-anchor merge, + the lever-2 finalize block
+    // (which is itself substantive-gated).
     expect(setTrue.length).toBeGreaterThanOrEqual(3)
     // Each `finalAnswerEverDelivered = true` must sit in a substantive context:
     // either guarded by `if (turn.finalAnswerSubstantive)` or inside an
@@ -125,14 +125,9 @@ describe('drain producers — narrative may not OPEN, liveness + tool may', () =
 })
 
 describe('lever 2 — finalize the card BEFORE a substantive reply send', () => {
-  /** executeReply body up to executeStreamReply. */
+  /** executeReply body up to the next top-level function. */
   function executeReplySrc(): string {
     const after = gatewaySrc.split('async function executeReply(')[1] ?? ''
-    return after.split('async function executeStreamReply(')[0] ?? after
-  }
-  /** executeStreamReply body up to the next top-level function. */
-  function executeStreamReplySrc(): string {
-    const after = gatewaySrc.split('async function executeStreamReply(')[1] ?? ''
     return after.split('\nasync function ')[0]?.split('\nfunction ')[0] ?? after
   }
 
@@ -148,27 +143,11 @@ describe('lever 2 — finalize the card BEFORE a substantive reply send', () =>
     expect(window).toMatch(/isSubstantiveFinalReply/)
   })
 
-  it('executeStreamReply finalizes before handleStreamReply, gated on substantive', () => {
-    const src = executeStreamReplySrc()
-    const clearIdx = src.indexOf('clearActivitySummary(')
-    const sendIdx = src.indexOf('const result = await handleStreamReply(')
-    expect(clearIdx).toBeGreaterThan(-1)
-    expect(sendIdx).toBeGreaterThan(-1)
-    expect(clearIdx).toBeLessThan(sendIdx)
-    // Window extended to 600 chars to account for the finalAnswerDeliveredAt stamp
-    // added inside the markSubstantiveFinalDelivered callback (Fix 2 / #2587).
-    const window = src.slice(Math.max(0, clearIdx - 600), clearIdx)
-    expect(window).toMatch(/isSubstantiveFinalReply/)
-  })
-
   it('acks do NOT finalize early — no unconditional clearActivitySummary before the reply send', () => {
-    // Both lever-2 finalize sites sit inside an isSubstantiveFinalReply guard.
+    // The lever-2 finalize site sits inside an isSubstantiveFinalReply guard.
     // An ack (non-substantive) falls through and never finalizes early, so the
     // reopen path keeps owning the card (the #2141 ack-then-work feed).
-    const replySrc = (() => {
-      const after = gatewaySrc.split('async function executeReply(')[1] ?? ''
-      return after.split('async function executeStreamReply(')[0] ?? after
-    })()
+    const replySrc = executeReplySrc()
     // The pre-loop clearActivitySummary must be the substantive-gated one.
     const preLoop = replySrc.split('for (let i = 0; i < chunks.length')[0] ?? ''
     const clears = [...preLoop.matchAll(/clearActivitySummary\(/g)]

package/telegram-plugin/tests/escalation-bridge-gate.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+import { shouldDeferEscalationForBridge } from "../gateway/escalation-bridge-gate.js";
+
+// Executable verification of #2788 Gap A: the obligation sweep's escalate branch
+// DIRECT-SENDS (bypassing the bridge), so during a transient bridge outage it
+// could fire a false "I may have missed this" even though the real reply is just
+// queued behind the flap. The gate defers the nudge while the bridge is down;
+// obligations survive bridge death, so the deferral is safe and self-healing.
+
+describe("shouldDeferEscalationForBridge — #2788 Gap A bridge-flap gate", () => {
+  it("DEFERS escalation while the bridge is down (no false 'I may have missed this')", () => {
+    expect(shouldDeferEscalationForBridge({ bridgeAlive: false })).toBe(true);
+  });
+
+  it("proceeds with escalation when the bridge is alive", () => {
+    expect(shouldDeferEscalationForBridge({ bridgeAlive: true })).toBe(false);
+  });
+
+  it("models the gateway wiring: getClient(agent)?.isAlive() === true drives the gate", () => {
+    // Bridge registered + alive → do not defer.
+    const aliveClient = { isAlive: () => true };
+    expect(
+      shouldDeferEscalationForBridge({ bridgeAlive: aliveClient.isAlive() === true }),
+    ).toBe(false);
+
+    // Bridge registered but a stale/dead socket → defer.
+    const deadClient = { isAlive: () => false };
+    expect(
+      shouldDeferEscalationForBridge({ bridgeAlive: deadClient.isAlive() === true }),
+    ).toBe(true);
+
+    // No client registered at all (getClient returns undefined) → defer.
+    const noClient: { isAlive: () => boolean } | undefined = undefined;
+    expect(
+      shouldDeferEscalationForBridge({ bridgeAlive: noClient?.isAlive() === true }),
+    ).toBe(true);
+  });
+});

package/telegram-plugin/tests/format-consistency.test.ts

@@ -16,11 +16,90 @@ import {
   normalizePunctuation,
   stripExcessBold,
   splitMarkdownChunks,
+  hardenCardBreaks,
   PARAGRAPH_SPACER,
 } from '../format.js'
 
 const SP = PARAGRAPH_SPACER // U+00A0
 
+describe('hardenCardBreaks — deterministic card line-break hardener', () => {
+  test('promotes lone field breaks to GFM hard breaks (the blob fix)', () => {
+    const out = hardenCardBreaks('Agent: assistant\nAuth: Max\nStatus: running')
+    expect(out).toBe('Agent: assistant  \nAuth: Max  \nStatus: running')
+  })
+
+  test('preserves `\\n\\n` block gaps (not promoted)', () => {
+    const out = hardenCardBreaks('**Header**\nfield one\n\n**Next**\nfield two')
+    expect(out).toBe('**Header**  \nfield one\n\n**Next**  \nfield two')
+  })
+
+  test('leaves GFM list items on their native single `\\n`', () => {
+    const out = hardenCardBreaks('- one\n- two\n- three')
+    expect(out).toBe('- one\n- two\n- three')
+  })
+
+  test('leaves GFM table rows untouched', () => {
+    const src = '| a | b |\n| - | - |\n| 1 | 2 |'
+    expect(hardenCardBreaks(src)).toBe(src)
+  })
+
+  test('never touches a fenced code block interior', () => {
+    const src = '**Accounts**\n```\nalice  ok\nbob    ok\n```\n**Agents**'
+    // The fenced monospace table keeps its single `\n`s; the header lines that
+    // face the fence are not hard-broken (fence line is a block construct).
+    expect(hardenCardBreaks(src)).toBe(src)
+  })
+
+  test('does not hard-break across a heading or blockquote', () => {
+    expect(hardenCardBreaks('# Title\nbody')).toBe('# Title\nbody')
+    expect(hardenCardBreaks('> quote\nbody')).toBe('> quote\nbody')
+  })
+
+  test('collapses 3+ newline runs to a single `\\n\\n` gap', () => {
+    expect(hardenCardBreaks('a\n\n\n\nb')).toBe('a\n\nb')
+  })
+
+  test('is idempotent', () => {
+    const src = 'Agent: x\nAuth: y\n\n**H**\n🟢 Broker running\n🟢 Kernel up'
+    const once = hardenCardBreaks(src)
+    expect(hardenCardBreaks(once)).toBe(once)
+  })
+
+  test('no-op for single-line text', () => {
+    expect(hardenCardBreaks('just one line')).toBe('just one line')
+  })
+
+  // Regression (reviewer nit): a field line that STARTS with an inline code
+  // span used to be misclassified as a masked fenced-block open (fenced +
+  // inline masks shared one placeholder prefix), so its lone `\n` was never
+  // hardened and the card collapsed. Real victim: `/vault get` rendering
+  // `` `key` = `value` `` on one line.
+  test('hardens a line that STARTS with an inline code span', () => {
+    const out = hardenCardBreaks('`key` = `value`\n`k2` = `v2`')
+    expect(out).toBe('`key` = `value`  \n`k2` = `v2`')
+  })
+
+  test('/vault get shape (`key` =\\n`value`) hard-breaks onto two lines', () => {
+    const out = hardenCardBreaks('`sk-key` =\n`hunter2`')
+    expect(out).toBe('`sk-key` =  \n`hunter2`')
+  })
+
+  test('inline-span-leading fix does NOT disturb a real fenced block', () => {
+    // A genuine ``` fence between two inline-span-leading field lines: the
+    // field lines harden, the fence interior stays byte-for-byte intact.
+    const src = '`a` = 1\n```\nx = 1\ny = 2\n```\n`b` = 2'
+    const out = hardenCardBreaks(src)
+    expect(out).toContain('```\nx = 1\ny = 2\n```') // fence interior untouched
+    expect(out).not.toContain('x = 1  \n') // no hard break injected inside fence
+  })
+
+  test('mid-line inline spans still harden (unchanged behaviour)', () => {
+    expect(hardenCardBreaks('Model: `opus`\nAuth: `Max`')).toBe(
+      'Model: `opus`  \nAuth: `Max`',
+    )
+  })
+})
+
 describe('addParagraphSpacers — uniform block spacing', () => {
   test('still spaces prose→prose (existing behaviour)', () => {
     const out = addParagraphSpacers('Alpha.\n\nBravo.')

package/telegram-plugin/tests/gate-parity-probe.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Drift-catching scaffolding for the inbound-delivery state-machine
+ * cutover (#2794). The turn-in-flight gate is now machine-authoritative
+ * (`isMachineInTurn`), but the legacy imperative `claudeBusyKeys` set is
+ * still maintained in parallel. These tests assert the two AGREE on every
+ * well-formed turn schedule, and pin the ONE intended divergence (the
+ * orphan-dangle the machine self-heals) so future edits can't silently
+ * introduce a dangerous `machine_over_holds` drift without turning a test
+ * red.
+ *
+ * This is the "assertion that machine and shadow agree" from the #2794
+ * time-box plan: it turns the standing triple-maintenance drift risk into
+ * a CI gate.
+ */
+
+import { describe, expect, it, beforeEach } from 'vitest'
+import {
+  shadowEmit,
+  isMachineInTurn,
+  __shadowResetForTests,
+} from '../gateway/inbound-delivery-machine-shadow.js'
+import { TURN_TTL_MS, type ChatKey } from '../gateway/inbound-delivery-machine.js'
+import {
+  gateParityDivergence,
+  isDangerousGateDivergence,
+  probeGateParity,
+} from '../gateway/gate-parity-probe.js'
+
+const KEY_A = '111:_' as ChatKey
+const KEY_B = '222:_' as ChatKey
+
+/**
+ * Reference model of the imperative `claudeBusyKeys` set — a per-delivery
+ * Set stamped on a fresh-turn delivery and deleted on the matching
+ * turnEnd. This mirrors gateway.ts's markBusyKeyLockstep / claudeBusyKeys.delete
+ * lifecycle closely enough to detect real drift in the gate view.
+ */
+class BusyKeysModel {
+  private readonly keys = new Set<string>()
+  stampFreshTurn(key: string) {
+    this.keys.add(key)
+  }
+  endTurn(key: string) {
+    this.keys.delete(key)
+  }
+  get size() {
+    return this.keys.size
+  }
+}
+
+describe('gateParityDivergence classifier', () => {
+  it('agree → none (both idle, both busy)', () => {
+    expect(gateParityDivergence(false, 0)).toBe('none')
+    expect(gateParityDivergence(true, 1)).toBe('none')
+    expect(gateParityDivergence(true, 3)).toBe('none')
+  })
+
+  it('machine idle, busyKeys held → busykeys_dangle (benign self-heal)', () => {
+    expect(gateParityDivergence(false, 1)).toBe('busykeys_dangle')
+    expect(isDangerousGateDivergence('busykeys_dangle')).toBe(false)
+  })
+
+  it('machine in-flight, busyKeys empty → machine_over_holds (dangerous)', () => {
+    expect(gateParityDivergence(true, 0)).toBe('machine_over_holds')
+    expect(isDangerousGateDivergence('machine_over_holds')).toBe(true)
+  })
+
+  it('probeGateParity returns the machine value unchanged (no behaviour change)', () => {
+    const lines: string[] = []
+    const log = (l: string) => lines.push(l)
+    expect(probeGateParity(true, 1, log)).toBe(true)
+    expect(probeGateParity(false, 0, log)).toBe(false)
+    expect(probeGateParity(false, 1, log)).toBe(false)
+    expect(probeGateParity(true, 0, log)).toBe(true)
+    // Only the dangerous over-hold emits a drift line.
+    expect(lines).toHaveLength(1)
+    expect(lines[0]).toContain('gw-trace gate-drift kind=machine_over_holds')
+  })
+})
+
+describe('machine ↔ claudeBusyKeys parity on well-formed schedules', () => {
+  beforeEach(() => __shadowResetForTests())
+
+  it('single turn: agree at every step', () => {
+    const busy = new BusyKeysModel()
+    shadowEmit({ kind: 'bridgeUp', at: 1000 })
+    expect(gateParityDivergence(isMachineInTurn(), busy.size)).toBe('none')
+
+    // Fresh inbound → machine goes in_turn; imperative stamps the key.
+    shadowEmit({ kind: 'inbound', key: KEY_A, msg: { msgId: 1, isSteering: false, payload: null }, at: 2000 })
+    busy.stampFreshTurn(KEY_A)
+    expect(gateParityDivergence(isMachineInTurn(), busy.size)).toBe('none')
+    expect(isMachineInTurn()).toBe(true)
+
+    // turnEnd → both reopen.
+    shadowEmit({ kind: 'turnEnd', key: KEY_A, at: 3000, outboundEmitted: true })
+    busy.endTurn(KEY_A)
+    expect(gateParityDivergence(isMachineInTurn(), busy.size)).toBe('none')
+    expect(isMachineInTurn()).toBe(false)
+  })
+
+  it('sequential turns across two chats: no drift', () => {
+    const busy = new BusyKeysModel()
+    shadowEmit({ kind: 'bridgeUp', at: 1000 })
+
+    const schedule: Array<[ChatKey, number]> = [
+      [KEY_A, 2000],
+      [KEY_B, 4000],
+      [KEY_A, 6000],
+    ]
+    let t = 2000
+    for (const [key, start] of schedule) {
+      shadowEmit({ kind: 'inbound', key, msg: { msgId: t, isSteering: false, payload: null }, at: start })
+      busy.stampFreshTurn(key)
+      expect(gateParityDivergence(isMachineInTurn(), busy.size)).toBe('none')
+      shadowEmit({ kind: 'turnEnd', key, at: start + 500, outboundEmitted: true })
+      busy.endTurn(key)
+      expect(gateParityDivergence(isMachineInTurn(), busy.size)).toBe('none')
+      t = start + 500
+    }
+  })
+
+  it('mid-turn sibling inbound is buffered, not a new turn: parity holds', () => {
+    const busy = new BusyKeysModel()
+    shadowEmit({ kind: 'bridgeUp', at: 1000 })
+
+    shadowEmit({ kind: 'inbound', key: KEY_A, msg: { msgId: 1, isSteering: false, payload: null }, at: 2000 })
+    busy.stampFreshTurn(KEY_A)
+    // Sibling arrives mid-turn: machine buffers (no new activeTurn); the
+    // imperative gate is already busy so it does NOT stamp a fresh key.
+    shadowEmit({ kind: 'inbound', key: KEY_B, msg: { msgId: 2, isSteering: false, payload: null }, at: 2500 })
+    expect(gateParityDivergence(isMachineInTurn(), busy.size)).toBe('none')
+
+    shadowEmit({ kind: 'turnEnd', key: KEY_A, at: 3000, outboundEmitted: true })
+    busy.endTurn(KEY_A)
+    expect(gateParityDivergence(isMachineInTurn(), busy.size)).toBe('none')
+  })
+})
+
+describe('the ONE intended divergence: orphaned turnStart', () => {
+  beforeEach(() => __shadowResetForTests())
+
+  it('machine self-heals the dangle; imperative set holds the orphan (busykeys_dangle, benign)', () => {
+    const busy = new BusyKeysModel()
+    shadowEmit({ kind: 'bridgeUp', at: 1000 })
+
+    // Turn A opens; turn B opens before A's turnEnd ever lands. The
+    // imperative set stamps BOTH; only B's turnEnd arrives, leaving A as
+    // an orphan key — the gymbro/clerk 5-min dangle.
+    shadowEmit({ kind: 'turnStart', key: KEY_A, at: 2000 })
+    busy.stampFreshTurn(KEY_A)
+    shadowEmit({ kind: 'turnStart', key: KEY_B, at: 3000 })
+    busy.stampFreshTurn(KEY_B)
+    shadowEmit({ kind: 'turnEnd', key: KEY_B, at: 4000, outboundEmitted: true })
+    busy.endTurn(KEY_B)
+
+    // Machine still holds activeTurn=A (single-activeTurn); imperative
+    // holds A too → they agree here.
+    expect(gateParityDivergence(isMachineInTurn(), busy.size)).toBe('none')
+
+    // TTL tick past A's start: the machine self-heals to idle, but the
+    // imperative set NEVER gets A's turnEnd → orphan dangles forever.
+    shadowEmit({ kind: 'tick', now: 2000 + TURN_TTL_MS + 1 })
+    expect(isMachineInTurn()).toBe(false)
+    const d = gateParityDivergence(isMachineInTurn(), busy.size)
+    expect(d).toBe('busykeys_dangle')
+    // Benign: this is exactly the wedge the machine was made authoritative
+    // to kill — it must NOT trip the drift alarm.
+    expect(isDangerousGateDivergence(d)).toBe(false)
+  })
+})