switchroom 0.19.42 → 0.19.44

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

@@ -397,20 +397,166 @@ describe('stripExcessBold', () => {
     expect(stripExcessBold(input)).toBe(input)
   })
 
-  test('48/49-char pseudo-heading boundary honoured under global strip', () => {
-    // Heading length is measured WITH the `**` markers. 44 inner chars → 48
-    // total (exempt); 45 inner chars → 49 total (stripped).
-    const heading48 = '**' + 'H'.repeat(44) + '**' // length 48
-    const heading49 = '**' + 'H'.repeat(45) + '**' // length 49
-    expect(heading48.length).toBe(48)
-    expect(heading49.length).toBe(49)
-
-    const out48 = stripExcessBold(`${heading48}\n\n${boldDenseBody}`)
-    expect(out48).toContain(heading48)
-
-    const out49 = stripExcessBold(`${heading49}\n\n${boldDenseBody}`)
-    expect(out49).not.toContain(heading49)
-    expect(out49).toContain('H'.repeat(45))
+  test('64/65-char pseudo-heading boundary honoured under global strip', () => {
+    // Heading length is measured WITH the `**` markers. 60 inner chars → 64
+    // total (exempt); 61 inner chars → 65 total (stripped).
+    const heading64 = '**' + 'H'.repeat(60) + '**' // length 64
+    const heading65 = '**' + 'H'.repeat(61) + '**' // length 65
+    expect(heading64.length).toBe(64)
+    expect(heading65.length).toBe(65)
+
+    const out64 = stripExcessBold(`${heading64}\n\n${boldDenseBody}`)
+    expect(out64).toContain(heading64)
+
+    const out65 = stripExcessBold(`${heading65}\n\n${boldDenseBody}`)
+    expect(out65).not.toContain(heading65)
+    expect(out65).toContain('H'.repeat(61))
+  })
+
+  // ── #4021: long-but-legitimate bold section labels survive ───────────────
+  // At PSEUDO_HEADING_MAX_CHARS=48 a real section label of 50-63 chars was
+  // read as an over-bolded paragraph and flattened. The cap is 64.
+
+  test.each([
+    // [label, survives?]
+    ['**Deployment status across all three regions:**', true], // 46
+    ['**Deployment status across all three AWS regions:**', true], // 50
+    ['**What changed in the delivery path since last Tuesday:**', true], // 56
+    ['**What actually changed in the delivery path since Tue:**', true], // 56
+    ['**Everything that changed across the delivery path this week:**', true], // 62
+    ['**Everything that changed across the whole delivery path today:**', false], // 65
+  ])('bold section label %s survives=%s under global strip', (label, survives) => {
+    // Sanity: the fixtures must straddle the 64-char boundary.
+    expect(label.length <= 64).toBe(survives)
+
+    const out = stripExcessBold(`${label}\n\n${boldDenseBody}`)
+    const inner = label.slice(2, -2)
+    if (survives) {
+      expect(out).toContain(label)
+    } else {
+      expect(out).not.toContain(label)
+      expect(out).toContain(inner)
+    }
+    // Either way the body is still flattened — the ratio guard is intact.
+    expect(out).not.toContain('**alpha**')
+  })
+
+  // ── #4017: a message that is ALL pseudo-headings still strips ────────────
+  // Every block exempted meant `out === masked`: a 100%-bold digest stayed
+  // fully bold and onStrip never fired.
+
+  test('all-pseudo-heading message strips (no body to contrast against)', () => {
+    const input = [
+      '**Deploy status**',
+      '**Open incidents**',
+      '**Merged today**',
+      '**Blocked on review**',
+      '**Rollout window tomorrow**',
+      '**Next steps:**',
+    ].join('\n\n')
+    expect(input.length).toBeGreaterThan(100)
+
+    const calls: Array<{ rule: string; ratio: number }> = []
+    const out = stripExcessBold(input, (d) => calls.push(d))
+
+    expect(out).not.toContain('**')
+    expect(out).toContain('Deploy status')
+    expect(out).toContain('Next steps:')
+    // Blank-line gaps between the headings are preserved.
+    expect(out).toBe(input.replace(/\*\*/g, ''))
+    // …and the strip is logged.
+    expect(calls).toHaveLength(1)
+    expect(calls[0].rule).toBe('global')
+    expect(calls[0].ratio).toBeGreaterThan(0.3)
+  })
+
+  test.each([
+    [
+      'all headings, no body → strip',
+      `**Deploy status**\n\n**Open incidents this morning**\n\n**Merged today since the last release**\n\n**Next steps:**`,
+      false,
+    ],
+    [
+      'headings + bold-dense body → headings survive',
+      `**Deploy status**\n\n${boldDenseBody}`,
+      true,
+    ],
+    [
+      'headings around a bold-dense body → headings survive',
+      `**Deploy status**\n\n**Open incidents**\n\n${boldDenseBody}\n\n**Next steps:**`,
+      true,
+    ],
+  ])('all-heading guard: %s', (_name, input, headingSurvives) => {
+    expect(input.length).toBeGreaterThan(100)
+    const out = stripExcessBold(input)
+    expect(out.includes('**Deploy status**')).toBe(headingSurvives)
+    expect(out).toContain('Deploy status')
+  })
+
+  // ── #4114: a code-only block is NOT body for the all-heading guard ───────
+  // #4108's short-circuit tested `blocks.every(isPseudoHeadingBlock)` on every
+  // non-blank block. A masked code block satisfies neither side, so ONE code
+  // fence in an all-headings digest flipped `every(...)` to false, re-exempted
+  // every heading, and reproduced #4017 exactly: 100% bold, onStrip silent.
+  // Decision pinned here: masked code is not body — it is invisible to every
+  // other measurement in stripExcessBold (it is stripped before the ratio is
+  // taken), so it does not buy the headings an exemption either.
+
+  const HEADINGS = ['**Deploy status**', '**Open incidents**', '**Merged today**']
+  const TAIL = ['**Blocked on review**', '**Rollout window tomorrow**', '**Next steps:**']
+
+  test.each([
+    ['fenced code block', '```\nswitchroom agent restart klanker\n```'],
+    ['inline code span', '`switchroom agent restart klanker`'],
+    ['fenced block with a language tag', '```bash\nswitchroom agent restart klanker\n```'],
+    ['several inline spans on one line', '`alpha` `beta` `gamma` `delta` `epsilon`'],
+  ])('all-heading guard: headings + a code-only block (%s) still strips', (_name, code) => {
+    const input = [...HEADINGS, code, ...TAIL].join('\n\n')
+    expect(input.length).toBeGreaterThan(100)
+
+    const calls: Array<{ rule: string; ratio: number }> = []
+    const out = stripExcessBold(input, (d) => calls.push(d))
+
+    // Outcome 1: no bold survives — this is the assertion that fails on the
+    // real bug, where `out` was the input verbatim.
+    expect(out).not.toContain('**')
+    expect(out).toContain('Deploy status')
+    expect(out).toContain('Next steps:')
+    // Outcome 2: the code block itself is preserved byte-for-byte.
+    expect(out).toContain(code)
+    expect(out).toBe(input.replace(/\*\*/g, ''))
+    // Outcome 3: the strip is logged (the #4017 silence is what made this
+    // class of bug invisible in the first place).
+    expect(calls).toHaveLength(1)
+    expect(calls[0].rule).toBe('global')
+    expect(calls[0].ratio).toBeGreaterThan(0.3)
+  })
+
+  test('all-heading guard: real prose body CONTAINING inline code keeps headings', () => {
+    // The counterpart that stops the #4114 fix from over-correcting: a block
+    // with visible text around its code span IS body, so the headings keep
+    // their bold. Only blocks that are *nothing but* code are skipped.
+    const input = [
+      ...HEADINGS,
+      'Run `switchroom agent restart klanker` now, then check the gateway log for errors.',
+      ...TAIL,
+    ].join('\n\n')
+
+    const calls: Array<{ rule: string; ratio: number }> = []
+    const out = stripExcessBold(input, (d) => calls.push(d))
+
+    expect(out).toContain('**Deploy status**')
+    expect(out).toContain('**Next steps:**')
+    expect(calls).toHaveLength(0)
+  })
+
+  test('all-heading guard: a code-only block does not rescue a headings-only digest', () => {
+    // Degenerate shape: the code block is the ONLY non-heading block and sits
+    // last. Same verdict, so the rule does not depend on block position.
+    const input = [...HEADINGS, ...TAIL, '```\nok\n```'].join('\n\n')
+    const out = stripExcessBold(input)
+    expect(out).not.toContain('**')
+    expect(out).toContain('```\nok\n```')
   })
 
   test('multi-line fully-bolded block is NOT mislabelled a heading (global)', () => {

package/telegram-plugin/tests/handback-orphan-recovery.test.ts

@@ -0,0 +1,131 @@
+import { readFileSync } from 'node:fs'
+
+import { describe, expect, it, vi } from 'vitest'
+
+import {
+  createHandbackOrphanRecovery,
+  formatOrphanEscalation,
+} from '../gateway/handback-orphan-recovery.js'
+import type { HandbackOrphanEscalation, PreTurnCardRecord } from '../gateway/handback-preturn-signal.js'
+import type { InboundMessage } from '../gateway/ipc-protocol.js'
+
+/**
+ * Unit test for the gateway-side EFFECTS of deterministic handback-orphan
+ * recovery, extracted out of gateway.ts (switchroom#2996 ratchet). The seam's
+ * DECISION logic is covered by `handback-preturn-signal.test.ts`; this file
+ * asserts the three effects behave as the seam's contract requires:
+ *
+ *   - a genuine orphan's card is DELETED (never edited to a user-facing string)
+ *   - a delete failure is swallowed, so a reap is never wedged by a Telegram error
+ *   - the handback is re-injected through the pending-inbound buffer verbatim
+ *   - retry exhaustion emits greppable telemetry, NOT a chat message
+ *
+ * Uses injected spies + an injected `writeLog`, so it runs identically under
+ * vitest and bun (no fake timers, no module mocks).
+ */
+
+const record: PreTurnCardRecord = {
+  turnKey: 'preturn:chatA:_:1000',
+  chatId: 'chatA',
+  threadId: 7,
+  activityMessageId: 4242,
+  startedAt: 1000,
+  pinned: false,
+}
+
+const escalation: HandbackOrphanEscalation = {
+  statusKey: 'chatA:7',
+  chatId: 'chatA',
+  threadId: 7,
+  adoptTurnId: 'turn-abc',
+  reinjectCount: 2,
+  ageMs: 90_000,
+}
+
+function inbound(): InboundMessage {
+  return {
+    type: 'inbound',
+    chatId: 'chatA',
+    threadId: 7,
+    messageId: 900,
+    text: 'worker finished',
+    meta: { source: 'subagent_handback', handbackReinjectCount: '1' },
+  } as unknown as InboundMessage
+}
+
+describe('handback orphan recovery effects', () => {
+  it('deletes the frozen pre-turn card with its chat/message/thread identity', async () => {
+    const deleteMessage = vi.fn(async () => ({ ok: true }))
+    const r = createHandbackOrphanRecovery({
+      deleteMessage,
+      pushInbound: vi.fn(),
+      writeLog: vi.fn(),
+    })
+
+    await r.deleteCard(record)
+
+    expect(deleteMessage).toHaveBeenCalledTimes(1)
+    expect(deleteMessage).toHaveBeenCalledWith('chatA', 4242, 7)
+  })
+
+  it('swallows a delete failure so the reap is never wedged by a Telegram error', async () => {
+    const deleteMessage = vi.fn(async () => {
+      throw new Error('message to delete not found')
+    })
+    const r = createHandbackOrphanRecovery({
+      deleteMessage,
+      pushInbound: vi.fn(),
+      writeLog: vi.fn(),
+    })
+
+    await expect(r.deleteCard(record)).resolves.toBeUndefined()
+  })
+
+  it('re-injects the orphaned handback verbatim through the pending-inbound buffer', () => {
+    const pushInbound = vi.fn()
+    const r = createHandbackOrphanRecovery({
+      deleteMessage: vi.fn(async () => ({})),
+      pushInbound,
+      writeLog: vi.fn(),
+    })
+
+    const msg = inbound()
+    r.reinjectHandback(msg)
+
+    expect(pushInbound).toHaveBeenCalledTimes(1)
+    // Same object identity: the seam already stamped the retry counter on
+    // `meta`, and this effect must not rebuild or strip the inbound.
+    expect(pushInbound.mock.calls[0]?.[0]).toBe(msg)
+  })
+
+  it('escalates exhausted retries to telemetry with the fleet-health join keys, not to chat', () => {
+    const writeLog = vi.fn()
+    const pushInbound = vi.fn()
+    const deleteMessage = vi.fn(async () => ({}))
+    const r = createHandbackOrphanRecovery({ deleteMessage, pushInbound, writeLog })
+
+    r.escalateOrphan(escalation)
+
+    expect(writeLog).toHaveBeenCalledTimes(1)
+    const line = writeLog.mock.calls[0]?.[0] as string
+    expect(line).toContain('handback orphan escalation')
+    expect(line).toContain('key=chatA:7')
+    expect(line).toContain('turnId=turn-abc')
+    expect(line).toContain('reinjects=2')
+    expect(line).toContain('ageMs=90000')
+    expect(line.endsWith('\n')).toBe(true)
+    // Escalation is telemetry-only: it must not touch any chat transport.
+    expect(deleteMessage).not.toHaveBeenCalled()
+    expect(pushInbound).not.toHaveBeenCalled()
+  })
+
+  it('formatOrphanEscalation is a single line (one log record, not a multi-line blob)', () => {
+    const line = formatOrphanEscalation(escalation)
+    expect(line.trimEnd().split('\n')).toHaveLength(1)
+  })
+
+  it('the operator-facing "needs a nudge" string is gone from the recovery module', () => {
+    const src = readFileSync(new URL('../gateway/handback-orphan-recovery.ts', import.meta.url), 'utf8')
+    expect(src).not.toContain('it may need a nudge')
+  })
+})

package/telegram-plugin/tests/handback-preturn-signal.test.ts

@@ -1,9 +1,13 @@
+import { readFileSync } from 'node:fs'
+
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
 import {
   createHandbackPreturnSignal,
   isHandbackInbound,
+  HANDBACK_REINJECT_COUNT_META_KEY,
   PRETURN_TURNKEY_PREFIX,
+  type HandbackOrphanEscalation,
   type HandbackPreturnSignalDeps,
   type PreTurnCardRecord,
 } from '../gateway/handback-preturn-signal.js'
@@ -136,9 +140,13 @@ interface Harness {
   sched: ReturnType<typeof makeScheduler>
   sendChatAction: ReturnType<typeof vi.fn>
   openCard: ReturnType<typeof vi.fn>
-  finalizeCard: ReturnType<typeof vi.fn>
+  deleteCard: ReturnType<typeof vi.fn>
+  reinjectHandback: ReturnType<typeof vi.fn>
+  escalateOrphan: ReturnType<typeof vi.fn>
   records: Map<string, PreTurnCardRecord>
-  finalizedIds: number[]
+  deletedIds: number[]
+  reinjected: InboundMessage[]
+  escalations: HandbackOrphanEscalation[]
 }
 
 const harnesses: Harness[] = []
@@ -168,9 +176,19 @@ function makeHarness(overrides: Partial<HandbackPreturnSignalDeps> = {}): Harnes
     if (cur != null && cur.activityMessageId === activityMessageId) records.delete(turnKey)
   }
 
-  const finalizedIds: number[] = []
-  const finalizeCard = vi.fn<(r: PreTurnCardRecord) => void>((r) => {
-    finalizedIds.push(r.activityMessageId)
+  const deletedIds: number[] = []
+  const deleteCard = vi.fn<(r: PreTurnCardRecord) => void>((r) => {
+    deletedIds.push(r.activityMessageId)
+  })
+
+  const reinjected: InboundMessage[] = []
+  const reinjectHandback = vi.fn<(m: InboundMessage) => void>((m) => {
+    reinjected.push(m)
+  })
+
+  const escalations: HandbackOrphanEscalation[] = []
+  const escalateOrphan = vi.fn<(e: HandbackOrphanEscalation) => void>((e) => {
+    escalations.push(e)
   })
 
   const signal = createHandbackPreturnSignal({
@@ -179,7 +197,9 @@ function makeHarness(overrides: Partial<HandbackPreturnSignalDeps> = {}): Harnes
     startTypingLoop: (c, t) => typing.start(c, t),
     stopTypingLoop: (c, t) => typing.stop(c, t),
     openCard,
-    finalizeCard,
+    deleteCard,
+    reinjectHandback,
+    escalateOrphan,
     writeCardRecord,
     clearCardRecord,
     now: sched.now,
@@ -187,10 +207,28 @@ function makeHarness(overrides: Partial<HandbackPreturnSignalDeps> = {}): Harnes
     clearTimer: sched.clearTimer,
     debounceMs: 700,
     adoptTimeoutMs: 30_000,
+    // Default the delivered-window TTL to 0 so tests that exercise the reap
+    // MECHANICS (idle-orphan, #3544 typing, isClaudeBusy gate) see the reap fire
+    // at the adopt timeout exactly as before this fix. Tests that specifically
+    // assert the delivered-but-not-yet-streaming deferral opt into a real TTL.
+    deliveredTtlMs: 0,
     ...overrides,
   })
 
-  const h: Harness = { signal, typing, sched, sendChatAction, openCard, finalizeCard, records, finalizedIds }
+  const h: Harness = {
+    signal,
+    typing,
+    sched,
+    sendChatAction,
+    openCard,
+    deleteCard,
+    reinjectHandback,
+    escalateOrphan,
+    records,
+    deletedIds,
+    reinjected,
+    escalations,
+  }
   harnesses.push(h)
   return h
 }
@@ -283,7 +321,7 @@ describe('handback-preturn-signal — dead-air pre-turn emit→adopt→reap', ()
     expect(h.signal.pendingCount()).toBe(0)
   })
 
-  it('never-adopted handback self-reaps its frozen card past the TTL', async () => {
+  it('never-adopted handback self-reaps: DELETES the frozen card and re-injects (deterministic recovery, no nudge)', async () => {
     const h = makeHarness()
     h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatD', messageId: 77 }))
     await h.sched.advance(700)
@@ -291,10 +329,15 @@ describe('handback-preturn-signal — dead-air pre-turn emit→adopt→reap', ()
     expect(h.typing.activeCount()).toBe(1)
     expect(h.records.size).toBe(1)
 
-    // No enqueue ever arrives. Past the adopt TTL the orphan self-reaps.
+    // No enqueue ever arrives. Past the adopt TTL the orphan self-reaps into
+    // deterministic recovery: the frozen card is DELETED (never rewritten to a
+    // user-facing "needs a nudge" string) and the handback is re-injected.
     await h.sched.advance(30_000)
 
-    expect(h.finalizedIds).toEqual([resolvedId]) // finalized exactly THAT card
+    expect(h.deletedIds).toEqual([resolvedId]) // deleted exactly THAT card
+    expect(h.reinjected).toHaveLength(1) // re-injected for the machine to recover itself
+    expect(h.reinjected[0]!.meta[HANDBACK_REINJECT_COUNT_META_KEY]).toBe('1')
+    expect(h.escalations).toEqual([]) // first orphan → recover, do NOT escalate
     expect(h.typing.activeCount()).toBe(0) // typing stopped
     expect(h.records.size).toBe(0) // durable record cleared (at-most-once)
     expect(h.signal.pendingCount()).toBe(0) // map empty
@@ -326,18 +369,20 @@ describe('handback-preturn-signal — dead-air pre-turn emit→adopt→reap', ()
     // DEFER each time: no false orphan card, entry still live, typing still lit.
     await h.sched.advance(30_000)
     await h.sched.advance(30_000)
-    expect(h.finalizedIds).toEqual([]) // NEVER posted the "never started" nudge
+    expect(h.deletedIds).toEqual([]) // NEVER reaped: card intact
+    expect(h.reinjected).toEqual([]) // NEVER re-injected while enqueued
     expect(h.signal.pendingCount()).toBe(1) // still queued, not reaped
     expect(h.typing.activeCount()).toBe(1) // indicator kept while queued
 
     // The parent turn finally ends and the handback mints its own turn: it
-    // adopts the SAME card (an edit, not a second send / not an orphan finalize).
+    // adopts the SAME card (an edit, not a second send / not an orphan reap).
     busy = false
     const turnId = deriveTurnId('chatBusy', null, 700)!
     const adoption = h.signal.tryAdopt(turnId)
     expect(adoption).not.toBeNull()
     expect(adoption!.activityMessageId).toBe(resolvedId)
-    expect(h.finalizedIds).toEqual([]) // adopted, never finalized as orphan
+    expect(h.deletedIds).toEqual([]) // adopted, never reaped as orphan
+    expect(h.reinjected).toEqual([])
     expect(h.openCard).toHaveBeenCalledTimes(1) // no double-send
     expect(h.signal.pendingCount()).toBe(0)
   })
@@ -345,7 +390,7 @@ describe('handback-preturn-signal — dead-air pre-turn emit→adopt→reap', ()
   // The deferred reap is not a leak: once claude goes idle and the handback has
   // STILL not been adopted (genuine bridge-death / dropped inbound), the re-armed
   // reap finalizes honestly — the degenerate case the reap exists for.
-  it('finalizes a genuine orphan once claude goes idle, even after deferring while busy', async () => {
+  it('recovers a genuine orphan once claude goes idle, even after deferring while busy', async () => {
     let busy = true
     const h = makeHarness({ isClaudeBusy: () => busy })
     h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatIdleOrphan', messageId: 710 }))
@@ -354,19 +399,169 @@ describe('handback-preturn-signal — dead-air pre-turn emit→adopt→reap', ()
 
     // Busy: the first reap defers.
     await h.sched.advance(30_000)
-    expect(h.finalizedIds).toEqual([])
+    expect(h.deletedIds).toEqual([])
+    expect(h.reinjected).toEqual([])
     expect(h.signal.pendingCount()).toBe(1)
 
     // Claude goes idle but NO adopting turn ever mints (the inbound was dropped).
-    // The re-armed reap now finalizes the genuine orphan.
+    // The re-armed reap now recovers the genuine orphan: delete + re-inject.
     busy = false
     await h.sched.advance(30_000)
-    expect(h.finalizedIds).toEqual([resolvedId])
+    expect(h.deletedIds).toEqual([resolvedId])
+    expect(h.reinjected).toHaveLength(1)
     expect(h.typing.activeCount()).toBe(0)
     expect(h.records.size).toBe(0)
     expect(h.signal.pendingCount()).toBe(0)
   })
 
+  // ── #4027 coverage gap: delivered-but-not-yet-streaming is NOT an orphan ──
+  // A handback that WAS delivered into claude's queue but whose adopting turn
+  // has not started streaming yet reads as idle (`isClaudeBusy()` false) + un-
+  // adopted — which #4027 still finalized as a false "needs a nudge" card. The
+  // `deliveredAwaitingTurnStart` gate DEFERS the reap for the whole delivered
+  // TTL. This test FAILS on revert of the gate: without it the reap fires at the
+  // 30 s adopt timeout (idle, un-adopted) and reaps a healthy delivery.
+  it('does NOT reap a delivered-but-not-yet-streaming handback within the delivered TTL', async () => {
+    // Real delivered TTL, no busy signal — the ONLY thing that can defer the
+    // reap here is the delivered-window gate.
+    const h = makeHarness({ deliveredTtlMs: 300_000 })
+    h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatDeliv', messageId: 800 }))
+    await h.sched.advance(700)
+    const resolvedId = await h.openCard.mock.results[0]!.value
+    expect(h.records.size).toBe(1)
+
+    // Well past the 30 s adopt timeout but comfortably within the 5 min TTL: the
+    // reap must DEFER every tick — no delete, no re-inject, entry still live,
+    // typing still lit. (Pre-fix this fired a false orphan at 30 s.)
+    await h.sched.advance(120_000)
+    expect(h.deletedIds).toEqual([])
+    expect(h.reinjected).toEqual([])
+    expect(h.escalations).toEqual([])
+    expect(h.signal.pendingCount()).toBe(1)
+    expect(h.typing.activeCount()).toBe(1)
+
+    // The turn finally starts streaming and adopts the SAME card — an edit, not
+    // an orphan reap, and no double-send.
+    const turnId = deriveTurnId('chatDeliv', null, 800)!
+    const adoption = h.signal.tryAdopt(turnId)
+    expect(adoption).not.toBeNull()
+    expect(adoption!.activityMessageId).toBe(resolvedId)
+    expect(h.deletedIds).toEqual([])
+    expect(h.reinjected).toEqual([])
+    expect(h.openCard).toHaveBeenCalledTimes(1)
+    expect(h.signal.pendingCount()).toBe(0)
+  })
+
+  it('reaps a delivered handback ONCE the delivered TTL elapses (deterministic recovery, still no nudge)', async () => {
+    const h = makeHarness({ deliveredTtlMs: 300_000 })
+    h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatStuck', messageId: 801 }))
+    await h.sched.advance(700)
+    const resolvedId = await h.openCard.mock.results[0]!.value
+
+    // Within the TTL: deferred.
+    await h.sched.advance(120_000)
+    expect(h.deletedIds).toEqual([])
+
+    // Past the TTL a truly-stuck delivery finally reaps into recovery rather than
+    // hanging forever — delete + re-inject, never a nudge card.
+    await h.sched.advance(210_000)
+    expect(h.deletedIds).toEqual([resolvedId])
+    expect(h.reinjected).toHaveLength(1)
+    expect(h.escalations).toEqual([])
+    expect(h.signal.pendingCount()).toBe(0)
+  })
+
+  // ── deterministic-recovery retry cap: re-inject up to 2×, THEN escalate ──
+  // A genuine orphan whose re-injections keep coming back orphaned must not loop
+  // forever, and must NEVER fall back to a chat nudge. After `maxReinjects` it
+  // escalates to fleet-health telemetry (the `escalateOrphan` sink). The retry
+  // counter rides `HANDBACK_REINJECT_COUNT_META_KEY` on the inbound across the
+  // buffer round trip, so the cap survives the drop-and-recreate of the entry.
+  it('re-injects a persistently-orphaned handback up to the cap, then escalates (never a nudge)', async () => {
+    const sched = makeScheduler()
+    const sendChatAction = vi.fn<(c: string, t: number | null) => void>()
+    const typing = createTurnTypingLoop({
+      sendChatAction,
+      chatKey: (c, t) => chatKey(c, t),
+      refreshMs: 4000,
+    })
+    let msgSeq = 5000
+    const deletedIds: number[] = []
+    const reinjectedCounts: (string | undefined)[] = []
+    const escalations: HandbackOrphanEscalation[] = []
+    const records = new Map<string, PreTurnCardRecord>()
+
+    // eslint-disable-next-line prefer-const
+    let signal: ReturnType<typeof createHandbackPreturnSignal>
+    signal = createHandbackPreturnSignal({
+      chatKey: (c, t) => chatKey(c, t),
+      deriveTurnId,
+      startTypingLoop: (c, t) => typing.start(c, t),
+      stopTypingLoop: (c, t) => typing.stop(c, t),
+      openCard: async () => ++msgSeq,
+      deleteCard: (r) => {
+        deletedIds.push(r.activityMessageId)
+      },
+      // Simulate the buffer round trip: a re-injected orphan comes straight back
+      // through the release chokepoint carrying its stamped retry counter.
+      reinjectHandback: (m) => {
+        reinjectedCounts.push(m.meta[HANDBACK_REINJECT_COUNT_META_KEY])
+        signal.noteHandbackRelease(m)
+      },
+      escalateOrphan: (e) => {
+        escalations.push(e)
+      },
+      writeCardRecord: (r) => {
+        records.set(r.turnKey, r)
+      },
+      clearCardRecord: (turnKey, id) => {
+        const cur = records.get(turnKey)
+        if (cur != null && cur.activityMessageId === id) records.delete(turnKey)
+      },
+      now: sched.now,
+      setTimer: sched.setTimer,
+      clearTimer: sched.clearTimer,
+      debounceMs: 700,
+      adoptTimeoutMs: 30_000,
+      deliveredTtlMs: 0, // no delivered-window deferral: exercise the retry cap directly
+      maxReinjects: 2,
+    })
+
+    try {
+      signal.noteHandbackRelease(handbackInbound({ chatId: 'chatCap', messageId: 802 }))
+      // Drive several reap cycles: each orphan deletes its card, re-injects (up
+      // to the cap), which re-arms the seam via the simulated round trip.
+      await sched.advance(200_000)
+
+      // Exactly 2 re-injections, stamped 1 then 2, then a single escalation.
+      expect(reinjectedCounts).toEqual(['1', '2'])
+      expect(escalations).toHaveLength(1)
+      expect(escalations[0]!.reinjectCount).toBe(2)
+      // One card deleted per orphan cycle (initial + 2 re-injected), never edited
+      // to a "needs a nudge" string.
+      expect(deletedIds).toHaveLength(3)
+      expect(signal.pendingCount()).toBe(0)
+    } finally {
+      typing.stopAll()
+    }
+  })
+
+  // ── the user-facing "needs a nudge" string is GONE from the gateway source ──
+  // Part A of the fix removed the operator-facing card text entirely; the orphan
+  // path now deletes + re-injects. This is a durable regression guard: it FAILS
+  // if the string is reintroduced anywhere in the gateway source.
+  it('the "may need a nudge" user-facing string is absent from the gateway source', () => {
+    const gatewaySrc = readFileSync(
+      new URL('../gateway/gateway.ts', import.meta.url),
+      'utf8',
+    )
+    // The literal user-facing phrase must not appear as a rendered string. (The
+    // only surviving mentions are historical CODE COMMENTS explaining the removal
+    // — assert the load-bearing card fragment is gone from any send/edit call.)
+    expect(gatewaySrc).not.toContain('it may need a nudge')
+    expect(gatewaySrc).not.toContain('HANDBACK_PRETURN_ORPHAN_HTML')
+  })
+
   it('identity race: a user inbound on the same topic never mis-adopts the handback, no double-send', async () => {
     const h = makeHarness()
     h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatE', messageId: 200 }))