switchroom 0.12.21 → 0.12.23

package/telegram-plugin/tests/inbound-delivery-machine.test.ts

@@ -0,0 +1,475 @@
+/**
+ * Property tests for `inbound-delivery-machine.ts`.
+ *
+ * Per RFC `docs/rfcs/inbound-delivery-state-machine.md`: 5 invariants
+ * validated over arbitrary event schedules. A counterexample is the
+ * minimal evidence that the machine has a bug. The wedge-cluster
+ * bugs (v0.12.22 boot-wedge, overlapping-turn silence, #1564 sibling
+ * keys) become FAILING property tests if reintroduced.
+ *
+ * Schedules are generated by a seeded PRNG so failures are
+ * reproducible. We don't use fast-check (not a dependency) — the
+ * randomness is sufficient for the invariant shapes we're checking,
+ * and pure random + shrink-on-failure is documented in the RFC as
+ * acceptable for v1.
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  type ChatKey,
+  type Effect,
+  type Event,
+  type InboundMessage,
+  type PermissionVerdict,
+  type State,
+  initialState,
+  OUTBOUND_RECENT_MS,
+  transition,
+  TURN_TTL_MS,
+  __chatIdOfKeyForTests,
+} from '../gateway/inbound-delivery-machine'
+
+// ─────────────────────────────────────────────────────────────────────
+// Seeded PRNG (deterministic for reproducible failures)
+// ─────────────────────────────────────────────────────────────────────
+
+function mulberry32(seed: number): () => number {
+  let s = seed >>> 0
+  return () => {
+    s = (s + 0x6d2b79f5) >>> 0
+    let t = s
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Event generators
+// ─────────────────────────────────────────────────────────────────────
+
+const CHATS = ['c1', 'c2', 'c3'] as const
+const THREADS = ['_', '1', '2', '0'] as const // includes '_' AND '0' to flag any latent sibling-key handling
+
+function makeKey(chat: string, thread: string): ChatKey {
+  return `${chat}:${thread}` as ChatKey
+}
+
+interface ScheduleContext {
+  readonly rand: () => number
+  now: number
+  msgIdCounter: number
+  permIdCounter: number
+}
+
+function randomKey(ctx: ScheduleContext): ChatKey {
+  const c = CHATS[Math.floor(ctx.rand() * CHATS.length)]
+  const t = THREADS[Math.floor(ctx.rand() * THREADS.length)]
+  return makeKey(c, t)
+}
+
+function nextMsg(ctx: ScheduleContext, isSteering = false): InboundMessage {
+  const msgId = ++ctx.msgIdCounter
+  return { msgId, isSteering, payload: { id: msgId } }
+}
+
+function nextVerdict(ctx: ScheduleContext): PermissionVerdict {
+  const requestId = `req-${++ctx.permIdCounter}`
+  return { requestId, behavior: 'allow', payload: { requestId } }
+}
+
+function advanceTime(ctx: ScheduleContext, range: number): void {
+  ctx.now += Math.floor(ctx.rand() * range)
+}
+
+type EventKind = Event['kind']
+const EVENT_KINDS: readonly EventKind[] = [
+  'bridgeUp',
+  'bridgeDown',
+  'inbound',
+  'turnStart',
+  'turnEnd',
+  'modelOutbound',
+  'permVerdict',
+  'tick',
+]
+
+function generateEvent(ctx: ScheduleContext, prior: State): Event {
+  // Weight inbound + tick + turnEnd higher than rare ops so schedules
+  // exercise the steady-state hot path.
+  const r = ctx.rand()
+  let kind: EventKind
+  if (r < 0.3) kind = 'inbound'
+  else if (r < 0.45) kind = 'tick'
+  else if (r < 0.55) kind = 'turnEnd'
+  else if (r < 0.65) kind = 'modelOutbound'
+  else if (r < 0.75) kind = 'turnStart'
+  else if (r < 0.82) kind = 'permVerdict'
+  else if (r < 0.91) kind = 'bridgeUp'
+  else kind = 'bridgeDown'
+
+  switch (kind) {
+    case 'bridgeUp':
+      return { kind: 'bridgeUp', at: ctx.now }
+    case 'bridgeDown':
+      return { kind: 'bridgeDown', at: ctx.now }
+    case 'inbound': {
+      const isSteering = ctx.rand() < 0.1
+      return { kind: 'inbound', key: randomKey(ctx), msg: nextMsg(ctx, isSteering), at: ctx.now }
+    }
+    case 'turnStart':
+      return { kind: 'turnStart', key: randomKey(ctx), at: ctx.now }
+    case 'turnEnd': {
+      // Bias toward an actually-active key so turnEnd is meaningful
+      // most of the time.
+      const activeKeys = [...prior.perKey.entries()]
+        .filter(([, v]) => v.turnStartedAt != null)
+        .map(([k]) => k)
+      const key = activeKeys.length > 0 && ctx.rand() < 0.8
+        ? activeKeys[Math.floor(ctx.rand() * activeKeys.length)]
+        : randomKey(ctx)
+      return { kind: 'turnEnd', key, at: ctx.now, outboundEmitted: ctx.rand() < 0.85 }
+    }
+    case 'modelOutbound':
+      return { kind: 'modelOutbound', key: randomKey(ctx), at: ctx.now }
+    case 'permVerdict':
+      return { kind: 'permVerdict', verdict: nextVerdict(ctx), at: ctx.now }
+    case 'tick':
+      // Tick advances time meaningfully — sometimes a small step,
+      // sometimes a big one that crosses TURN_TTL_MS so the fallback
+      // path is exercised.
+      advanceTime(ctx, ctx.rand() < 0.1 ? TURN_TTL_MS * 2 : 5_000)
+      return { kind: 'tick', now: ctx.now }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Property: simulate a schedule and assert invariants
+// ─────────────────────────────────────────────────────────────────────
+
+interface TraceEntry {
+  readonly event: Event
+  readonly stateBefore: State
+  readonly stateAfter: State
+  readonly effects: readonly Effect[]
+}
+
+function runSchedule(seed: number, eventCount: number): TraceEntry[] {
+  const ctx: ScheduleContext = {
+    rand: mulberry32(seed),
+    now: 0,
+    msgIdCounter: 0,
+    permIdCounter: 0,
+  }
+  let state = initialState()
+  const trace: TraceEntry[] = []
+  for (let i = 0; i < eventCount; i++) {
+    const event = generateEvent(ctx, state)
+    const { state: stateAfter, effects } = transition(state, event)
+    trace.push({ event, stateBefore: state, stateAfter, effects })
+    state = stateAfter
+    // Advance clock a small amount between events so timestamps don't
+    // cluster at zero.
+    advanceTime(ctx, 1_000)
+  }
+  return trace
+}
+
+function formatCounterexample(seed: number, trace: TraceEntry[]): string {
+  const lines = [`seed=${seed}, len=${trace.length}`, '']
+  for (let i = 0; i < trace.length; i++) {
+    const t = trace[i]
+    lines.push(`#${i} ${t.event.kind} ${JSON.stringify(t.event)}`)
+    if (t.effects.length > 0) {
+      lines.push(`   → ${t.effects.map((e) => e.kind).join(', ')}`)
+    }
+  }
+  return lines.join('\n')
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Invariant #1 — Every inbound is delivered XOR persisted
+// ─────────────────────────────────────────────────────────────────────
+
+describe('Invariant #1 — every inbound is delivered XOR persisted', () => {
+  it('holds across 1000 random schedules of 50 events', () => {
+    for (let seed = 1; seed <= 1000; seed++) {
+      const trace = runSchedule(seed, 50)
+      for (let i = 0; i < trace.length; i++) {
+        const t = trace[i]
+        if (t.event.kind !== 'inbound') continue
+        const msgId = t.event.msg.msgId
+        const delivered = t.effects.some(
+          (e) => e.kind === 'deliverToBridge' && e.msg.msgId === msgId,
+        )
+        const buffered = t.effects.some(
+          (e) => e.kind === 'bufferInbound' && e.msg.msgId === msgId,
+        )
+        const persisted = t.effects.some(
+          (e) => e.kind === 'persistInbound' && e.msg.msgId === msgId,
+        )
+        // Contract: delivered XOR (buffered AND persisted). Never both
+        // delivered AND buffered. Never neither.
+        if (delivered && (buffered || persisted)) {
+          throw new Error(
+            `Invariant #1 violated at event #${i}: msg ${msgId} both delivered and buffered.\n` +
+            formatCounterexample(seed, trace.slice(0, i + 1)),
+          )
+        }
+        if (!delivered && !buffered) {
+          throw new Error(
+            `Invariant #1 violated at event #${i}: msg ${msgId} neither delivered nor buffered.\n` +
+            formatCounterexample(seed, trace.slice(0, i + 1)),
+          )
+        }
+        if (buffered && !persisted) {
+          throw new Error(
+            `Invariant #1 violated at event #${i}: msg ${msgId} buffered but not persisted.\n` +
+            formatCounterexample(seed, trace.slice(0, i + 1)),
+          )
+        }
+      }
+    }
+    expect(true).toBe(true)
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────
+// Invariant #2 — setTurnStarted has a matching clearTurnStarted
+// before the next end-of-life event (turnEnd, bridgeDown for active,
+// or tick past TURN_TTL).
+// ─────────────────────────────────────────────────────────────────────
+
+describe('Invariant #2 — turnStarted is matched by clearTurnStarted before EOL', () => {
+  it('holds across 1000 random schedules of 100 events', () => {
+    for (let seed = 1; seed <= 1000; seed++) {
+      const trace = runSchedule(seed, 100)
+      // For each turn started, track when it was started and find the
+      // matching clear. The clear must come strictly before:
+      //  - the next turnEnd for that key
+      //  - OR the next tick that crosses TURN_TTL
+      //  - OR bridgeDown (if the active turn — bridgeDown can clear
+      //    state implicitly per the RFC's state machine; we don't
+      //    require clear in that case, the bridge_dead state takes
+      //    over)
+      // Simpler equivalent: at the end of every schedule step, the
+      // perKey set should never contain a turnStartedAt entry that's
+      // STALE BEYOND TTL. The tick handler is the gate.
+      for (let i = 0; i < trace.length; i++) {
+        const t = trace[i]
+        for (const [k, v] of t.stateAfter.perKey) {
+          if (v.turnStartedAt == null) continue
+          const age = t.event.kind === 'tick'
+            ? t.event.now - v.turnStartedAt
+            : 0
+          // Note: we don't have a single "current time" outside
+          // tick events. Only ticks can detect TTL expiration; so
+          // a stale entry persists across non-tick events until a
+          // tick processes it. That's the design.
+          if (t.event.kind === 'tick' && age > TURN_TTL_MS) {
+            // Recent outbound suppresses fallback (invariant #5) — if
+            // suppressed, the entry stays. Confirm the suppression
+            // condition holds.
+            if (v.lastOutboundAt == null || t.event.now - v.lastOutboundAt >= OUTBOUND_RECENT_MS) {
+              throw new Error(
+                `Invariant #2 violated at event #${i}: key ${k} has stale turnStartedAt ` +
+                `(age=${age}ms > ${TURN_TTL_MS}ms) after a tick.\n` +
+                formatCounterexample(seed, trace.slice(0, i + 1)),
+              )
+            }
+          }
+        }
+      }
+    }
+    expect(true).toBe(true)
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────
+// Invariant #3 — per-chat sibling-key cleanup on turnEnd
+// ─────────────────────────────────────────────────────────────────────
+
+describe('Invariant #3 — turnEnd sweeps sibling keys for the same chatId', () => {
+  it('holds across 1000 random schedules of 100 events', () => {
+    for (let seed = 1; seed <= 1000; seed++) {
+      const trace = runSchedule(seed, 100)
+      for (let i = 0; i < trace.length; i++) {
+        const t = trace[i]
+        if (t.event.kind !== 'turnEnd') continue
+        const chatId = __chatIdOfKeyForTests(t.event.key)
+        // After turnEnd, no sibling key for this chatId should retain
+        // turnStartedAt != null.
+        for (const [k, v] of t.stateAfter.perKey) {
+          if (__chatIdOfKeyForTests(k) !== chatId) continue
+          if (v.turnStartedAt != null) {
+            throw new Error(
+              `Invariant #3 violated at event #${i}: turnEnd for ${t.event.key} ` +
+              `left sibling key ${k} with turnStartedAt=${v.turnStartedAt}.\n` +
+              formatCounterexample(seed, trace.slice(0, i + 1)),
+            )
+          }
+        }
+      }
+    }
+    expect(true).toBe(true)
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────
+// Invariant #4 — permVerdict delivered iff bridge alive
+// ─────────────────────────────────────────────────────────────────────
+
+describe('Invariant #4 — permVerdict delivered iff bridge alive', () => {
+  it('holds across 1000 random schedules of 50 events', () => {
+    for (let seed = 1; seed <= 1000; seed++) {
+      const trace = runSchedule(seed, 50)
+      for (let i = 0; i < trace.length; i++) {
+        const t = trace[i]
+        if (t.event.kind !== 'permVerdict') continue
+        const alive = t.stateBefore.global.kind !== 'bridge_dead'
+        const delivered = t.effects.some((e) => e.kind === 'deliverPermVerdict')
+        const persisted = t.effects.some((e) => e.kind === 'persistPermVerdict')
+        if (alive && !delivered) {
+          throw new Error(
+            `Invariant #4 violated at #${i}: bridge alive but permVerdict not delivered.\n` +
+            formatCounterexample(seed, trace.slice(0, i + 1)),
+          )
+        }
+        if (!alive && !persisted) {
+          throw new Error(
+            `Invariant #4 violated at #${i}: bridge dead but permVerdict not persisted.\n` +
+            formatCounterexample(seed, trace.slice(0, i + 1)),
+          )
+        }
+        if (delivered && persisted) {
+          throw new Error(
+            `Invariant #4 violated at #${i}: permVerdict both delivered and persisted.\n` +
+            formatCounterexample(seed, trace.slice(0, i + 1)),
+          )
+        }
+      }
+    }
+    expect(true).toBe(true)
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────
+// Invariant #5 — spurious-fallback suppression (the 2026-05-20
+// overlapping-turn silence bug becomes unrepresentable)
+// ─────────────────────────────────────────────────────────────────────
+
+describe('Invariant #5 — fallback poke suppressed if model recently broke silence', () => {
+  it('holds across 1000 random schedules of 100 events', () => {
+    for (let seed = 1; seed <= 1000; seed++) {
+      const trace = runSchedule(seed, 100)
+      for (let i = 0; i < trace.length; i++) {
+        const t = trace[i]
+        if (t.event.kind !== 'tick') continue
+        const now = t.event.now
+        for (const eff of t.effects) {
+          if (eff.kind !== 'firePoke' || eff.level !== 'fallback') continue
+          // Look up the key's lastOutboundAt at stateBefore.
+          const perKey = t.stateBefore.perKey.get(eff.key)
+          if (perKey == null) continue
+          if (perKey.lastOutboundAt == null) continue
+          const sinceOutbound = now - perKey.lastOutboundAt
+          if (sinceOutbound < OUTBOUND_RECENT_MS) {
+            throw new Error(
+              `Invariant #5 violated at #${i}: fallback fired for ${eff.key} ` +
+              `but model produced outbound only ${sinceOutbound}ms ago ` +
+              `(threshold ${OUTBOUND_RECENT_MS}ms).\n` +
+              formatCounterexample(seed, trace.slice(0, i + 1)),
+            )
+          }
+        }
+      }
+    }
+    expect(true).toBe(true)
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────
+// Targeted regression: the v0.12.22 boot-wedge case
+// ─────────────────────────────────────────────────────────────────────
+
+describe('Targeted regression — v0.12.22 boot-wedge', () => {
+  it('first inbound on a fresh bridge delivers, not buffers', () => {
+    let s = initialState()
+    s = transition(s, { kind: 'bridgeUp', at: 0 }).state
+    const { state: s2, effects } = transition(s, {
+      kind: 'inbound',
+      key: 'c1:_' as ChatKey,
+      msg: { msgId: 1, isSteering: false, payload: {} },
+      at: 100,
+    })
+    const delivered = effects.some((e) => e.kind === 'deliverToBridge')
+    const buffered = effects.some((e) => e.kind === 'bufferInbound')
+    expect(delivered).toBe(true)
+    expect(buffered).toBe(false)
+    expect(s2.global.kind).toBe('bridge_alive_in_turn')
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────
+// Targeted regression: the 2026-05-20 overlapping-turn silence case
+// ─────────────────────────────────────────────────────────────────────
+
+describe('Targeted regression — overlapping-turn silence (the post-v0.12.22 case)', () => {
+  it("suppresses fallback when model produced outbound in prior overlapping turn", () => {
+    let s = initialState()
+    s = transition(s, { kind: 'bridgeUp', at: 0 }).state
+
+    // Turn A starts and ends with an outbound at t=5000
+    s = transition(s, {
+      kind: 'inbound',
+      key: 'c1:_' as ChatKey,
+      msg: { msgId: 1, isSteering: false, payload: {} },
+      at: 1000,
+    }).state
+    s = transition(s, {
+      kind: 'turnEnd',
+      key: 'c1:_' as ChatKey,
+      at: 5000,
+      outboundEmitted: true,
+    }).state
+
+    // Turn B starts at t=6000 (immediately after A)
+    s = transition(s, {
+      kind: 'inbound',
+      key: 'c1:_' as ChatKey,
+      msg: { msgId: 2, isSteering: false, payload: {} },
+      at: 6000,
+    }).state
+
+    // Tick at t=310,000: turn B is 304s old (past TURN_TTL_MS=300_000).
+    // But the model emitted an outbound at t=5000 (less than 60s ago
+    // RELATIVE TO TURN B'S START, but 305s before now).
+    // Per invariant #5: suppress fallback iff lastOutbound is within
+    // OUTBOUND_RECENT_MS (60s) of NOW. 310_000 - 5_000 = 305_000 ms;
+    // not within the suppression window. So fallback SHOULD fire here.
+    const tickResult = transition(s, { kind: 'tick', now: 310_000 })
+    const fired = tickResult.effects.some(
+      (e) => e.kind === 'firePoke' && e.level === 'fallback',
+    )
+    expect(fired).toBe(true)
+
+    // Now reset and verify the suppression case: outbound at t=305_000,
+    // tick at t=310_000 — only 5s elapsed since outbound.
+    let s2 = initialState()
+    s2 = transition(s2, { kind: 'bridgeUp', at: 0 }).state
+    s2 = transition(s2, {
+      kind: 'inbound',
+      key: 'c2:_' as ChatKey,
+      msg: { msgId: 3, isSteering: false, payload: {} },
+      at: 1000,
+    }).state
+    // Model emitted an outbound very recently
+    s2 = transition(s2, { kind: 'modelOutbound', key: 'c2:_' as ChatKey, at: 305_000 }).state
+    // Tick: turn is 309s old, outbound was 5s ago → suppress
+    const suppress = transition(s2, { kind: 'tick', now: 310_000 })
+    const firedSuppressed = suppress.effects.some(
+      (e) => e.kind === 'firePoke' && e.level === 'fallback',
+    )
+    expect(firedSuppressed).toBe(false)
+  })
+})

package/telegram-plugin/uat/scenarios/jtbd-always-on-after-restart-dm.test.ts

@@ -0,0 +1,157 @@
+/**
+ * JTBD scenario — always-on vision: first message after restart replies
+ * quickly, NOT 5 minutes later via silence-poke fallback.
+ *
+ * Vision (`reference/vision.md`, see [[project_vision_reanchor_human_assistants]]):
+ * agents are always-on specialist exec-assistants. A 5-min blank
+ * window on the first message after restart is what BROKEN feels
+ * like to a user trying to use their assistant.
+ *
+ * ## The wedge this guards against
+ *
+ * Pre-v0.12.22, every agent restart produced ~5 min blank on the
+ * first user message in each thread:
+ *
+ *   1. User sends msg → handleInbound runs the fresh-turn branch
+ *      → activeTurnStartedAt.set(key, now) at gateway.ts:7357
+ *   2. The #1556 delivery gate further down (~7551) checks
+ *      activeTurnStartedAt.size > 0 to decide if a turn is "already
+ *      in flight" — sees the entry it just wrote → buffer-until-idle
+ *   3. Inbound stuck in pendingInboundBuffer. Bridge never sees it.
+ *      Claude never replies. activeTurnStartedAt[key] stays set.
+ *   4. ~300s later silence-poke framework-fallback fires, drains
+ *      the buffer, the reply finally lands — five minutes late.
+ *
+ * Documented in `feedback_5min_restart_wedge_violates_vision.md`.
+ * Fix is a one-line snapshot of the live size at receipt-time before
+ * the fresh-turn branch mutates the Map.
+ *
+ * ## What this UAT asserts
+ *
+ * After a deliberate restart, the FIRST message in a fresh thread
+ * gets a reply within a budget that excludes the silence-poke
+ * fallback floor (300s). Concretely we assert < 120s, which is
+ * generous for slow LLM replies but well below the wedge symptom.
+ *
+ * The test also makes a stricter observation log so a future
+ * regression that lands BETWEEN "wedge fixed" (~LLM latency) and
+ * "wedge present" (~5 min) is visible — e.g. some slow startup
+ * path that takes 60-90s would pass the contract but bear
+ * investigation.
+ *
+ * ## Why this scenario specifically
+ *
+ * - `smoke-dm-reply.test.ts` covers steady-state inbound→reply but
+ *   does NOT restart the agent first, so the wedge surfaces as a
+ *   "first message is slow" pattern that the smoke test would
+ *   silently absorb on warm runs.
+ * - `silent-end-recovery-dm.test.ts` covers mid-turn silent-end →
+ *   no-reply, but at 6 min budget — too generous to catch the
+ *   5-min wedge as a regression.
+ * - This is the FIRST UAT to explicitly tie the assertion to the
+ *   "always-on" vision and measure first-after-restart TTFO.
+ */
+
+import { describe, it, expect, beforeAll } from "vitest";
+import { execSync } from "node:child_process";
+import { spinUp } from "../harness.js";
+
+const AGENT = "test-harness";
+
+// Budget for the marker-safe restart itself (per
+// feedback_agent_restart_needs_sudo_when_running.md, restart blocks
+// ~30s as the gateway's bridge reattaches).
+const RESTART_BUDGET_MS = 90_000;
+
+// Hard contract: first-after-restart reply must land in under 2 min.
+// This is generous for slow LLM replies but well below the 5-min
+// silence-poke fallback floor — a regression of the #1556 wedge
+// would trip on TTFO ≥ 300s and fail the test.
+const HARD_REPLY_BUDGET_MS = 120_000;
+
+// Vision-aligned target: real expectation is well under 30s on a
+// healthy fleet. A pass between 30-120s is yellow — covered by the
+// contract but worth logging for forensic visibility.
+const VISION_REPLY_BUDGET_MS = 30_000;
+
+function canShellSudo(): boolean {
+  try {
+    execSync("sudo -n true", { stdio: "ignore", timeout: 2_000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function restartAgent(name: string): void {
+  // Marker-safe restart per memory feedback_compose_rollout.md +
+  // feedback_agent_restart_needs_sudo_when_running.md. Apply step
+  // self-elevates internally; restart needs the wrapper. We don't
+  // call apply here — the agent scaffolds are already current; only
+  // the in-memory state needs to reset.
+  execSync(
+    `sudo -n env PATH=$PATH HOME=$HOME switchroom agent restart ${name} --force`,
+    { stdio: ["ignore", "pipe", "pipe"], timeout: RESTART_BUDGET_MS },
+  );
+}
+
+// This scenario requires NOPASSWD sudo + the switchroom CLI on PATH on
+// the harness host. Skip on CI runners that don't expose those.
+const sudoOk = canShellSudo();
+
+(sudoOk ? describe : describe.skip)(
+  "uat: always-on after restart",
+  () => {
+    beforeAll(() => {
+      restartAgent(AGENT);
+      // Brief settle so the bridge sidecar finishes its reattach
+      // before we send the first inbound. The bridge-register log
+      // line is the earliest the agent can accept inbound.
+      return new Promise((r) => setTimeout(r, 5_000));
+    }, RESTART_BUDGET_MS + 10_000);
+
+    it(
+      "first message after fresh restart → reply within 2 min (NOT the 5-min wedge)",
+      async () => {
+        const sc = await spinUp({ agent: AGENT });
+        try {
+          const sendStart = Date.now();
+          await sc.sendDM("ping — JTBD always-on UAT");
+
+          const firstReply = await sc.expectMessage(/\S/, {
+            from: "bot",
+            timeout: HARD_REPLY_BUDGET_MS,
+          });
+          const ttfo = Date.now() - sendStart;
+
+          expect(firstReply.text.length).toBeGreaterThan(0);
+
+          // HARD CONTRACT: the wedge symptom is 300s+ TTFO. Anything
+          // ≥ HARD_REPLY_BUDGET_MS (120s) flags a regression of the
+          // #1556 self-blocking gate.
+          if (ttfo >= HARD_REPLY_BUDGET_MS) {
+            throw new Error(
+              `[always-on] first-post-restart reply took ${ttfo}ms — ` +
+              `matches the #1556 wedge symptom (5-min silence-poke fallback). ` +
+              `Vision broken; see feedback_5min_restart_wedge_violates_vision.md`,
+            );
+          }
+          expect(ttfo).toBeLessThan(HARD_REPLY_BUDGET_MS);
+
+          // Yellow-band log: passes the contract but degraded from the
+          // vision target. Worth investigating if this fires regularly.
+          if (ttfo >= VISION_REPLY_BUDGET_MS) {
+            console.warn(
+              `[always-on] first-post-restart TTFO=${ttfo}ms — passed ` +
+              `contract (${HARD_REPLY_BUDGET_MS}ms) but slower than the ` +
+              `vision target (${VISION_REPLY_BUDGET_MS}ms). Forensic flag.`,
+            );
+          }
+        } finally {
+          await sc.tearDown();
+        }
+      },
+      HARD_REPLY_BUDGET_MS + 10_000,
+    );
+  },
+);