switchroom 0.14.18 → 0.14.20

package/telegram-plugin/gateway/interrupt-defer.ts

@@ -0,0 +1,100 @@
+// Problem B — deferred safe-boundary interrupt.
+//
+// A `!`-prefix interrupt SIGINTs the agent's in-flight turn (tmux C-c) and
+// then resumes with the replacement body as a fresh turn. Firing the SIGINT
+// the instant `!` arrives can land mid-tool-call — a C-c during a Write or a
+// Bash leaves the tool's work half-done. `reference/steer-or-queue-mid-flight.md`
+// names this exact anti-pattern: "Mid-tool-call is not 'amend time.'"
+//
+// We can't pause claude's internal loop (the unmodified-CLI constraint — the
+// only levers are SIGINT via tmux and observing the session JSONL). But we CAN
+// observe when a tool call starts and finishes, and defer the SIGINT to the
+// next clean boundary. This module is the pure, deterministic core of that
+// decision so it can be unit-tested without the gateway's IPC / timers.
+
+/** The session-event shape this tracker cares about. A structural subset of
+ *  the gateway's `SessionEvent` so tests don't need the full union. */
+export interface FlightEvent {
+  kind: string
+  toolUseId?: string | null
+}
+
+/**
+ * Tracks top-level tool calls in flight for the CURRENT turn, keyed by
+ * toolUseId. A `tool_use` adds; its matching `tool_result` removes; a
+ * `turn_end` or a fresh `enqueue` clears the slate (a new turn starts clean,
+ * and a killed turn may never emit the trailing `tool_result`).
+ *
+ * Sub-agent events (`sub_agent_*`) are intentionally ignored: the parent's
+ * `Task` tool_use already sits in the set and represents the user-observable
+ * wait, so the sub-agent's own tool calls don't independently gate the
+ * boundary. Telegram-surface tools are NOT excluded — treating every in-flight
+ * tool as "unsafe to C-c" is the conservative call, and the max-wait bound
+ * keeps a stuck reply tool from stranding the interrupt.
+ */
+export class ToolFlightTracker {
+  private readonly inFlight = new Set<string>()
+
+  onEvent(ev: FlightEvent): void {
+    switch (ev.kind) {
+      case 'tool_use':
+        if (typeof ev.toolUseId === 'string' && ev.toolUseId.length > 0) {
+          this.inFlight.add(ev.toolUseId)
+        }
+        break
+      case 'tool_result':
+        if (typeof ev.toolUseId === 'string' && ev.toolUseId.length > 0) {
+          this.inFlight.delete(ev.toolUseId)
+        }
+        break
+      case 'turn_end':
+      case 'enqueue':
+        this.inFlight.clear()
+        break
+      // dequeue / thinking / text / tool_label / sub_agent_* — no effect.
+      default:
+        break
+    }
+  }
+
+  /** True when at least one top-level tool call is open (unsafe boundary). */
+  isMidToolCall(): boolean {
+    return this.inFlight.size > 0
+  }
+
+  /** Count of in-flight tool calls — exposed for diagnostics/logging. */
+  inFlightCount(): number {
+    return this.inFlight.size
+  }
+
+  clear(): void {
+    this.inFlight.clear()
+  }
+}
+
+export type InterruptTiming = 'fire-now' | 'defer'
+
+/**
+ * Decide whether a `!` interrupt should fire immediately or wait for a safe
+ * boundary. Pure: the gateway feeds the live flag + tracker reading.
+ *
+ *  - flag off                  → fire-now (historical synchronous behaviour)
+ *  - flag on, no tool in flight → fire-now (already at a clean boundary)
+ *  - flag on, tool in flight    → defer (wait for tool_result / turn_end)
+ */
+export function decideInterruptTiming(opts: {
+  safeBoundaryEnabled: boolean
+  midToolCall: boolean
+}): InterruptTiming {
+  if (!opts.safeBoundaryEnabled) return 'fire-now'
+  return opts.midToolCall ? 'defer' : 'fire-now'
+}
+
+/** Floor for the deferred-interrupt max-wait. A non-positive or absent config
+ *  value falls back to the default; we never wait forever. */
+export const DEFAULT_INTERRUPT_MAX_WAIT_MS = 8000
+
+export function resolveInterruptMaxWaitMs(configured: number | undefined): number {
+  if (typeof configured === 'number' && configured > 0) return configured
+  return DEFAULT_INTERRUPT_MAX_WAIT_MS
+}

package/telegram-plugin/gateway/pending-inbound-buffer.ts

@@ -184,10 +184,16 @@ export function planBufferedRedelivery(
   return out
 }
 
+/** Meta keys that describe an attachment — the primary (image_path,
+ *  attachment_*) plus the A2 numbered siblings (image_path_2,
+ *  attachment_file_id_2, …) and attachment_count. */
+const ATTACHMENT_META_RE = /^(image_path|attachment_)/
+
 /** Collapse a >1 run into a single turn. The newest message anchors the
  *  turn (its messageId/ts/user/meta); texts join in arrival order; the
- *  single attachment (if any) rides along from whichever message carried
- *  it. Caller guarantees the run is mergeable + has at most one media. */
+ *  attachment(s) (if any) ride along from whichever message carried them.
+ *  Caller guarantees the run is mergeable + has at most one media-bearing
+ *  entry. */
 function mergeRun(run: InboundMessage[]): InboundMessage {
   const last = run[run.length - 1]!
   const mediaEntry = run.find(inboundHasMedia)
@@ -195,10 +201,21 @@ function mergeRun(run: InboundMessage[]): InboundMessage {
     ...last,
     text: run.map((m) => m.text).join('\n'),
   }
-  // Re-seat the single attachment/imagePath from the entry that owns it
-  // (which may not be `last`), or strip them if the run is text-only.
+  // Re-seat the attachment/imagePath from the entry that owns it (which may
+  // not be `last`), or strip them if the run is text-only.
   delete merged.imagePath
   delete merged.attachment
+  if (mediaEntry != null && mediaEntry !== last) {
+    // The media-bearing entry isn't the anchor, so `last.meta` lacks the
+    // attachment fields the agent reads (image_path / attachment_* and the
+    // A2 numbered siblings). Splice the owning entry's attachment meta keys
+    // into the merged meta so the agent still sees every attachment.
+    const splicedMeta: Record<string, string> = { ...merged.meta }
+    for (const [k, v] of Object.entries(mediaEntry.meta)) {
+      if (ATTACHMENT_META_RE.test(k)) splicedMeta[k] = v
+    }
+    merged.meta = splicedMeta
+  }
   if (mediaEntry?.imagePath != null) merged.imagePath = mediaEntry.imagePath
   if (mediaEntry?.attachment != null) merged.attachment = mediaEntry.attachment
   return merged

package/telegram-plugin/status-reactions.ts

@@ -53,6 +53,7 @@ export type ReactionState =
   | 'web'
   | 'tool'
   | 'compacting'
+  | 'awaiting'
   | 'done'
   | 'error'
   | 'stallSoft'
@@ -78,6 +79,7 @@ export const REACTION_VARIANTS: Record<ReactionState, string[]> = {
   coding:    ['👨‍💻', '✍', '⚡'],     // WORKING: writing / running code
   web:       ['⚡', '🤔', '👌'],      // WORKING: lookup in motion
   compacting:['✍', '🤔', '👀'],
+  awaiting:  ['🙏', '🤔', '👀'],      // BLOCKED ON HUMAN: parked on a permission card
   done:      ['👍', '💯', '🎉'],      // FINISHED: turn_end fired
   error:     ['😱', '😨', '🤯'],      // NON-TERMINAL — recovery allowed
   stallSoft: ['🥱', '😴', '🤔'],
@@ -180,6 +182,22 @@ export class StatusReactionController {
     this.scheduleState('compacting')
   }
 
+  /**
+   * 🙏 — the turn is parked on a human decision (a permission card is
+   * waiting for the operator to tap Allow/Deny). Immediate, non-terminal,
+   * and crucially SUSPENDS the stall watchdog: a turn blocked on the
+   * operator is not stalled, so it must NOT promote to 🥱/😨 while the
+   * card sits unanswered. The next working transition (setTool /
+   * setThinking, fired when the verdict resumes the turn) re-arms the
+   * watchdog normally. Bypasses debounce so 🙏 lands as soon as the card
+   * is posted.
+   */
+  setAwaiting(): void {
+    if (this.finished) return
+    this.scheduleState('awaiting', { immediate: true, skipStallReset: true })
+    this.clearStallTimers()
+  }
+
   /**
    * 😱 — non-terminal error indicator. Paints the error emoji but does
    * NOT end the controller — recovery to a working state is permitted

package/telegram-plugin/tests/coalesce-attachments.test.ts

@@ -0,0 +1,152 @@
+/**
+ * Unit tests for the A2 multi-attachment helpers
+ * (telegram-plugin/gateway/coalesce-attachments.ts).
+ *
+ * These pin the two pure pieces of the multi-attachment fold-in that live
+ * outside gateway.ts so they can be exercised without loadAccess()/IPC:
+ *   1. splitCoalescedAttachments — primary + capped extras, arrival order.
+ *   2. buildExtraAttachmentMeta — numbered meta fields starting at _2.
+ *
+ * The default cap (1) MUST reproduce the historical single-attachment shape:
+ * primary only, no extras, no numbered meta.
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  splitCoalescedAttachments,
+  buildExtraAttachmentMeta,
+  type ResolvedExtraAttachment,
+} from '../gateway/coalesce-attachments.js'
+
+interface Entry {
+  text: string
+  att?: string
+}
+
+const has = (e: Entry): boolean => e.att != null
+
+describe('splitCoalescedAttachments', () => {
+  it('default cap 1: keeps only the first attachment as primary, no extras', () => {
+    const entries: Entry[] = [
+      { text: 'a', att: 'photo-1' },
+      { text: 'b', att: 'photo-2' },
+    ]
+    const { primary, extras } = splitCoalescedAttachments(entries, has, 1)
+    expect(primary).toEqual({ text: 'a', att: 'photo-1' })
+    expect(extras).toEqual([])
+  })
+
+  it('picks the FIRST attachment-bearing entry as primary even when text-only entries precede it', () => {
+    const entries: Entry[] = [
+      { text: 'look' },
+      { text: 'at this', att: 'photo-1' },
+      { text: 'and this', att: 'photo-2' },
+    ]
+    const { primary, extras } = splitCoalescedAttachments(entries, has, 3)
+    expect(primary?.att).toBe('photo-1')
+    expect(extras.map((e) => e.att)).toEqual(['photo-2'])
+  })
+
+  it('preserves arrival order of extras', () => {
+    const entries: Entry[] = [
+      { text: '1', att: 'a' },
+      { text: '2', att: 'b' },
+      { text: '3', att: 'c' },
+    ]
+    const { primary, extras } = splitCoalescedAttachments(entries, has, 5)
+    expect(primary?.att).toBe('a')
+    expect(extras.map((e) => e.att)).toEqual(['b', 'c'])
+  })
+
+  it('caps extras at maxAttachments (overflow dropped here; bypassed upstream)', () => {
+    const entries: Entry[] = [
+      { text: '1', att: 'a' },
+      { text: '2', att: 'b' },
+      { text: '3', att: 'c' },
+      { text: '4', att: 'd' },
+    ]
+    const { primary, extras } = splitCoalescedAttachments(entries, has, 2)
+    expect(primary?.att).toBe('a')
+    expect(extras.map((e) => e.att)).toEqual(['b']) // total = cap of 2
+  })
+
+  it('returns undefined primary when no entry carries an attachment', () => {
+    const entries: Entry[] = [{ text: 'just' }, { text: 'text' }]
+    const { primary, extras } = splitCoalescedAttachments(entries, has, 3)
+    expect(primary).toBeUndefined()
+    expect(extras).toEqual([])
+  })
+
+  it('floors a cap of 0 / negative at 1 so the only attachment is never stripped', () => {
+    const entries: Entry[] = [{ text: '1', att: 'a' }, { text: '2', att: 'b' }]
+    expect(splitCoalescedAttachments(entries, has, 0).primary?.att).toBe('a')
+    expect(splitCoalescedAttachments(entries, has, -5).primary?.att).toBe('a')
+    expect(splitCoalescedAttachments(entries, has, 0).extras).toEqual([])
+  })
+})
+
+describe('buildExtraAttachmentMeta', () => {
+  it('returns an empty object for no extras (default single-attachment turn)', () => {
+    expect(buildExtraAttachmentMeta([])).toEqual({})
+  })
+
+  it('numbers a single photo extra as _2', () => {
+    const resolved: ResolvedExtraAttachment[] = [{ imagePath: '/inbox/p2.jpg' }]
+    expect(buildExtraAttachmentMeta(resolved)).toEqual({ image_path_2: '/inbox/p2.jpg' })
+  })
+
+  it('numbers multiple extras incrementally from _2', () => {
+    const resolved: ResolvedExtraAttachment[] = [
+      { imagePath: '/inbox/p2.jpg' },
+      { imagePath: '/inbox/p3.jpg' },
+    ]
+    expect(buildExtraAttachmentMeta(resolved)).toEqual({
+      image_path_2: '/inbox/p2.jpg',
+      image_path_3: '/inbox/p3.jpg',
+    })
+  })
+
+  it('emits full attachment metadata fields for a document extra', () => {
+    const resolved: ResolvedExtraAttachment[] = [
+      {
+        attachment: {
+          kind: 'document',
+          file_id: 'FID2',
+          size: 1234,
+          mime: 'application/pdf',
+          name: 'spec.pdf',
+        },
+      },
+    ]
+    expect(buildExtraAttachmentMeta(resolved)).toEqual({
+      attachment_kind_2: 'document',
+      attachment_file_id_2: 'FID2',
+      attachment_size_2: '1234',
+      attachment_mime_2: 'application/pdf',
+      attachment_name_2: 'spec.pdf',
+    })
+  })
+
+  it('omits optional metadata fields that are absent', () => {
+    const resolved: ResolvedExtraAttachment[] = [
+      { attachment: { kind: 'voice', file_id: 'FID2' } },
+    ]
+    expect(buildExtraAttachmentMeta(resolved)).toEqual({
+      attachment_kind_2: 'voice',
+      attachment_file_id_2: 'FID2',
+    })
+  })
+
+  it('handles a mix of photo and document extras with correct numbering', () => {
+    const resolved: ResolvedExtraAttachment[] = [
+      { imagePath: '/inbox/p2.jpg' },
+      { attachment: { kind: 'document', file_id: 'FID3', mime: 'text/plain' } },
+    ]
+    expect(buildExtraAttachmentMeta(resolved)).toEqual({
+      image_path_2: '/inbox/p2.jpg',
+      attachment_kind_3: 'document',
+      attachment_file_id_3: 'FID3',
+      attachment_mime_3: 'text/plain',
+    })
+  })
+})

package/telegram-plugin/tests/interrupt-defer.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Unit tests for the deferred safe-boundary interrupt core (Problem B).
+ *
+ * The gateway-side wiring (timer, SIGINT-via-tmux, sendToAgent resume,
+ * coalescing) is exercised by integration; these pin the pure decision:
+ *   - ToolFlightTracker correctly tracks open tool calls by toolUseId and
+ *     clears on turn_end / a fresh enqueue.
+ *   - decideInterruptTiming returns fire-now unless the flag is on AND a tool
+ *     is in flight.
+ *   - resolveInterruptMaxWaitMs never yields a non-positive / forever wait.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  ToolFlightTracker,
+  decideInterruptTiming,
+  resolveInterruptMaxWaitMs,
+  DEFAULT_INTERRUPT_MAX_WAIT_MS,
+} from '../gateway/interrupt-defer.js'
+
+describe('ToolFlightTracker', () => {
+  it('starts at a safe boundary (no tools in flight)', () => {
+    const t = new ToolFlightTracker()
+    expect(t.isMidToolCall()).toBe(false)
+    expect(t.inFlightCount()).toBe(0)
+  })
+
+  it('a tool_use opens an unsafe boundary; its tool_result closes it', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use', toolUseId: 'tu_1' })
+    expect(t.isMidToolCall()).toBe(true)
+    t.onEvent({ kind: 'tool_result', toolUseId: 'tu_1' })
+    expect(t.isMidToolCall()).toBe(false)
+  })
+
+  it('stays unsafe while ANY of several parallel tools is open', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use', toolUseId: 'a' })
+    t.onEvent({ kind: 'tool_use', toolUseId: 'b' })
+    t.onEvent({ kind: 'tool_use', toolUseId: 'c' })
+    expect(t.inFlightCount()).toBe(3)
+    t.onEvent({ kind: 'tool_result', toolUseId: 'b' })
+    t.onEvent({ kind: 'tool_result', toolUseId: 'a' })
+    expect(t.isMidToolCall()).toBe(true) // c still open
+    t.onEvent({ kind: 'tool_result', toolUseId: 'c' })
+    expect(t.isMidToolCall()).toBe(false)
+  })
+
+  it('turn_end clears any residual in-flight tools', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use', toolUseId: 'tu_1' })
+    t.onEvent({ kind: 'tool_use', toolUseId: 'tu_2' })
+    t.onEvent({ kind: 'turn_end' })
+    expect(t.isMidToolCall()).toBe(false)
+  })
+
+  it('a fresh enqueue clears the slate (new turn starts clean)', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use', toolUseId: 'tu_1' })
+    t.onEvent({ kind: 'enqueue' })
+    expect(t.isMidToolCall()).toBe(false)
+  })
+
+  it('ignores sub-agent and non-tool events', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'sub_agent_tool_use', toolUseId: 'sub_1' })
+    t.onEvent({ kind: 'thinking' })
+    t.onEvent({ kind: 'text' })
+    t.onEvent({ kind: 'tool_label', toolUseId: 'tu_x' })
+    expect(t.isMidToolCall()).toBe(false)
+  })
+
+  it('ignores tool_use with a missing / empty toolUseId', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use' })
+    t.onEvent({ kind: 'tool_use', toolUseId: null })
+    t.onEvent({ kind: 'tool_use', toolUseId: '' })
+    expect(t.isMidToolCall()).toBe(false)
+  })
+
+  it('tool_result for an unknown id is a harmless no-op', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use', toolUseId: 'real' })
+    t.onEvent({ kind: 'tool_result', toolUseId: 'never-opened' })
+    expect(t.isMidToolCall()).toBe(true) // 'real' still open
+  })
+
+  it('clear() resets the tracker', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use', toolUseId: 'tu_1' })
+    t.clear()
+    expect(t.isMidToolCall()).toBe(false)
+  })
+})
+
+describe('decideInterruptTiming', () => {
+  it('fires now when the flag is off, even mid-tool-call', () => {
+    expect(
+      decideInterruptTiming({ safeBoundaryEnabled: false, midToolCall: true }),
+    ).toBe('fire-now')
+  })
+
+  it('fires now when the flag is on but no tool is in flight', () => {
+    expect(
+      decideInterruptTiming({ safeBoundaryEnabled: true, midToolCall: false }),
+    ).toBe('fire-now')
+  })
+
+  it('defers only when the flag is on AND a tool is in flight', () => {
+    expect(
+      decideInterruptTiming({ safeBoundaryEnabled: true, midToolCall: true }),
+    ).toBe('defer')
+  })
+
+  it('fires now in the fully-off case', () => {
+    expect(
+      decideInterruptTiming({ safeBoundaryEnabled: false, midToolCall: false }),
+    ).toBe('fire-now')
+  })
+})
+
+describe('resolveInterruptMaxWaitMs', () => {
+  it('uses the configured value when positive', () => {
+    expect(resolveInterruptMaxWaitMs(3000)).toBe(3000)
+  })
+
+  it('falls back to the default when undefined', () => {
+    expect(resolveInterruptMaxWaitMs(undefined)).toBe(DEFAULT_INTERRUPT_MAX_WAIT_MS)
+  })
+
+  it('never returns a non-positive wait (no forever-wait)', () => {
+    expect(resolveInterruptMaxWaitMs(0)).toBe(DEFAULT_INTERRUPT_MAX_WAIT_MS)
+    expect(resolveInterruptMaxWaitMs(-1)).toBe(DEFAULT_INTERRUPT_MAX_WAIT_MS)
+  })
+
+  it('models the lifecycle: open tool → defer; tool_result → safe → fire', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use', toolUseId: 'w1' })
+    // `!` lands here, flag on:
+    expect(
+      decideInterruptTiming({ safeBoundaryEnabled: true, midToolCall: t.isMidToolCall() }),
+    ).toBe('defer')
+    // tool completes:
+    t.onEvent({ kind: 'tool_result', toolUseId: 'w1' })
+    expect(t.isMidToolCall()).toBe(false) // gateway fires the parked interrupt here
+  })
+})

package/telegram-plugin/tests/pending-inbound-buffer.test.ts

@@ -450,6 +450,42 @@ describe('planBufferedRedelivery — merge-on-drain (forwarded-burst across a tu
     expect(plan[0]!.merged.imagePath).toBe('/tmp/p.jpg')
   })
 
+  it('splices attachment meta from the media entry when it is NOT the anchor (A2 numbered fields survive)', () => {
+    // A coalesced multi-attachment message buffered, then a text-only
+    // follow-up. mergeRun anchors on `last` (the text), whose meta has no
+    // attachment fields — so the owning entry's image_path + numbered
+    // siblings + attachment_count must be spliced into the merged meta or
+    // the agent would never see the photos.
+    const photo = userMsg({ text: 'look', ts: 1, imagePath: '/tmp/a.jpg' })
+    photo.meta = {
+      image_path: '/tmp/a.jpg',
+      image_path_2: '/tmp/b.jpg',
+      attachment_count: '2',
+      user: 'alice',
+    }
+    const txt = userMsg({ text: 'at these', ts: 2 })
+    txt.meta = { user: 'alice' }
+    const plan = planBufferedRedelivery([photo, txt])
+    expect(plan).toHaveLength(1)
+    const meta = plan[0]!.merged.meta
+    expect(meta.image_path).toBe('/tmp/a.jpg')
+    expect(meta.image_path_2).toBe('/tmp/b.jpg')
+    expect(meta.attachment_count).toBe('2')
+    // Top-level primary still re-seated for inboundHasMedia detection.
+    expect(plan[0]!.merged.imagePath).toBe('/tmp/a.jpg')
+  })
+
+  it('does not need a meta splice when the media entry IS the anchor', () => {
+    const txt = userMsg({ text: 'intro', ts: 1 })
+    txt.meta = { user: 'alice' }
+    const photo = userMsg({ text: 'pic', ts: 2, imagePath: '/tmp/p.jpg' })
+    photo.meta = { image_path: '/tmp/p.jpg', user: 'alice' }
+    const plan = planBufferedRedelivery([txt, photo])
+    expect(plan).toHaveLength(1)
+    // Anchor is the photo, so its meta is inherited verbatim.
+    expect(plan[0]!.merged.meta.image_path).toBe('/tmp/p.jpg')
+  })
+
   it('preserves the run total — sum of originals equals input length (lossless)', () => {
     const msgs = [
       userMsg({ text: 'a', ts: 1 }),

package/telegram-plugin/tests/status-reactions.test.ts

@@ -341,6 +341,75 @@ describe('StatusReactionController', () => {
     expect(calls).toEqual(['👀'])
   })
 
+  // setAwaiting(): park on 🙏 while a permission card waits for the
+  // operator. A turn blocked on a human is NOT stalled, so the watchdog
+  // must stay quiet — but it re-arms once the verdict resumes work.
+  describe('setAwaiting() — park on a human permission decision', () => {
+    it('emits 🙏 immediately (bypasses debounce)', async () => {
+      const { emit, calls } = makeEmitter()
+      const ctrl = new StatusReactionController(emit)
+      ctrl.setQueued()
+      await flush()
+      ctrl.setAwaiting()
+      await flush()
+      expect(calls).toEqual(['👀', '🙏'])
+    })
+
+    it('suppresses stall promotion (no 🥱/😨) while the card sits unanswered', async () => {
+      const { emit, calls } = makeEmitter()
+      const ctrl = new StatusReactionController(emit)
+      ctrl.setQueued()
+      ctrl.setTool('Bash') // working: 👨‍💻
+      vi.advanceTimersByTime(3500)
+      await flush()
+      ctrl.setAwaiting()
+      await flush()
+      // Well past both stall thresholds — awaiting must not yawn or panic.
+      vi.advanceTimersByTime(120000)
+      await flush()
+      expect(calls).not.toContain('🥱')
+      expect(calls).not.toContain('😨')
+      expect(calls[calls.length - 1]).toBe('🙏')
+    })
+
+    it('re-arms the stall watchdog once a working transition resumes the turn', async () => {
+      const { emit, calls } = makeEmitter()
+      const ctrl = new StatusReactionController(emit)
+      ctrl.setQueued()
+      await flush()
+      ctrl.setAwaiting()
+      await flush()
+      vi.advanceTimersByTime(120000) // long human wait — no stall
+      await flush()
+      expect(calls).toEqual(['👀', '🙏'])
+
+      // Verdict dispatched → gateway calls setThinking() to un-park.
+      ctrl.setThinking()
+      vi.advanceTimersByTime(3500)
+      await flush()
+      expect(calls).toEqual(['👀', '🙏', '🤔'])
+
+      // A genuine post-approval hang must still promote to 🥱 — the
+      // watchdog was re-armed by the resuming transition.
+      vi.advanceTimersByTime(30000)
+      await flush()
+      expect(calls).toContain('🥱')
+    })
+
+    it('is a no-op after finalize (cannot resurrect a finished controller)', async () => {
+      const { emit, calls } = makeEmitter()
+      const ctrl = new StatusReactionController(emit)
+      ctrl.setQueued()
+      ctrl.finalize('done')
+      await flush()
+      const snapshot = [...calls]
+      ctrl.setAwaiting()
+      vi.advanceTimersByTime(5000)
+      await flush()
+      expect(calls).toEqual(snapshot)
+    })
+  })
+
   // hold(): freeze on a WORKING glyph while background sub-agent workers
   // outlive the parent turn, deferring the terminal 👍 (worker-reaction fix).
   describe('hold() — defer 👍 while a background worker runs', () => {