switchroom 0.14.14 → 0.14.15

package/telegram-plugin/gateway/gateway.ts

@@ -52,6 +52,8 @@ import {
 import { OutboundDedupCache } from '../recent-outbound-dedup.js'
 import { createInboundCoalescer, inboundCoalesceKey } from './inbound-coalesce.js'
 import { StatusReactionController } from '../status-reactions.js'
+import { DeferredDoneReactions } from '../reaction-defer.js'
+import { createWorkerActivityFeed } from '../worker-activity-feed.js'
 import { isTelegramReplyTool, isTelegramSurfaceTool } from '../tool-names.js'
 import { appendActivityLabel } from '../tool-activity-summary.js'
 import { toolLabel } from '../tool-labels.js'
@@ -1096,6 +1098,18 @@ if (!STATIC) setInterval(checkApprovals, 5000).unref()
 const chatThreadMap = new Map<string, number>()
 const activeStatusReactions = new Map<string, StatusReactionController>()
 const activeReactionMsgIds = new Map<string, { chatId: string; messageId: number }>()
+// Reactions whose terminal 👍 is deferred because a background sub-agent
+// worker was still running when the parent's `turn_end` fired. Painting 👍
+// then would read as "done / nothing happening" while the worker keeps
+// going. The controller is `hold()`-frozen on a working glyph; the entry
+// is promoted to 👍 by `deferredDoneReactions.promote()` (wired to the
+// watcher's `onFinish`) when the last worker completes. See
+// `reaction-defer.ts` for the promote/purge interaction the unit tests pin.
+const deferredDoneReactions = new DeferredDoneReactions<StatusReactionController>({
+  countRunningWorkers: () => countRunningWorkers(),
+  getActive: (key) => activeStatusReactions.get(key),
+  purge: (key) => purgeReactionTracking(key),
+})
 
 // #546 — outbound content-dedup window. PR #599 introduced the four read
 // sites (`outboundDedup.check` / `.record` in executeReply, executeStreamReply,
@@ -1898,10 +1912,34 @@ function finalizeStatusReaction(
   const key = statusKey(chatId, threadId)
   const ctrl = activeStatusReactions.get(key)
   if (!ctrl) return
+  // Don't paint the terminal 👍 while a background sub-agent worker is
+  // still running — it reads as "done / nothing happening" even though
+  // the text said work continues. `tryDefer` holds the working glyph
+  // (✍️/⚡) and registers the controller; the watcher's onFinish promotes
+  // it to 👍 once the last worker completes. Errors are terminal
+  // regardless: a failed/aborted turn shouldn't wait on a worker.
+  if (reason === 'done' && deferredDoneReactions.tryDefer(key, ctrl)) return
+  deferredDoneReactions.drop(key)
   ctrl.finalize(reason)
   purgeReactionTracking(key)
 }
 
+/**
+ * Count sub-agent workers currently running (excludes historical
+ * boot-leftover entries and any already-terminal worker). The registry
+ * deletes terminal entries after a short grace, so a worker that has
+ * fired its `done`/`failed` onFinish no longer counts here.
+ */
+function countRunningWorkers(): number {
+  const reg = subagentWatcher?.getRegistry()
+  if (reg == null) return 0
+  let n = 0
+  for (const e of reg.values()) {
+    if (e.state === 'running' && !e.historical) n++
+  }
+  return n
+}
+
 /**
  * Non-terminal error paint (😱). Distinct from `finalize('error')` —
  * recovery to a working state is allowed after this (#1713). Mid-turn
@@ -17219,6 +17257,45 @@ void (async () => {
         if (streamMode === 'checklist') {
           const watcherAgentDir = resolveAgentDirFromEnv()
           if (watcherAgentDir != null) {
+            // #PR2 — live worker-activity feed. A *background* sub-agent
+            // decouples from the parent turn, so when the turn ends nothing
+            // surfaces its ongoing jsonl activity and a long worker reads as
+            // silence. This feed posts ONE regular chat message per worker
+            // and edits it in place as work happens (current tool + elapsed),
+            // finalizing on completion — the same "live, growing message"
+            // shape the main agent's answer uses, NOT card chrome (the pinned
+            // card was deleted in #1126). Flag-gated; when ON it also
+            // supersedes the coarse 5-min bucket relay below to avoid
+            // double-surfacing the same progress beat.
+            const workerFeedEnabled = process.env.SWITCHROOM_WORKER_ACTIVITY_FEED === '1'
+            const workerActivityFeed = createWorkerActivityFeed({
+              bot: {
+                sendMessage: async (cid, text, sendOpts) => {
+                  const sent = await robustApiCall(
+                    () =>
+                      lockedBot.api.sendMessage(
+                        cid,
+                        text,
+                        sendOpts as Parameters<typeof lockedBot.api.sendMessage>[2],
+                      ),
+                    { chat_id: cid, verb: 'worker-feed' },
+                  )
+                  return sent as { message_id: number }
+                },
+                editMessageText: (cid, mid, text, editOpts) =>
+                  robustApiCall(
+                    () =>
+                      lockedBot.api.editMessageText(
+                        cid,
+                        mid,
+                        text,
+                        editOpts as Parameters<typeof lockedBot.api.editMessageText>[3],
+                      ),
+                    { chat_id: cid, verb: 'worker-feed' },
+                  ),
+              },
+              log: (msg) => process.stderr.write(`telegram gateway: ${msg}\n`),
+            })
             subagentWatcher = startSubagentWatcher({
               agentDir: watcherAgentDir,
               // Issue #1116 (Bug A): restrict project-dir enumeration to
@@ -17311,7 +17388,29 @@ void (async () => {
               // Gated to background completions: foreground sub-agents
               // need nothing here, and 'orphan' is a stale historical-at-
               // boot row, not a fresh completion the user is waiting on.
-              onFinish: ({ agentId, outcome, description, resultText }) => {
+              onFinish: ({ agentId, outcome, description, resultText, toolCount, durationMs }) => {
+                // Reaction promotion: if the parent turn already ended
+                // with this (or another) worker still running, its 👍 was
+                // deferred (held on ✍️/⚡). Now that a worker finished,
+                // promote to 👍 iff none remain running. Independent of the
+                // handback gating below, so it must run before any early
+                // return. Cheap no-op when nothing is deferred.
+                deferredDoneReactions.promote()
+                // #PR2 live worker-feed: force the terminal recap edit on
+                // the worker's live message. No-op when no message was ever
+                // posted (trivial workers stay silent; handback covers them).
+                // 'orphan' is a stale boot row, not a fresh completion — map
+                // it to 'done' so an already-posted message still finalizes.
+                if (workerFeedEnabled) {
+                  void workerActivityFeed.finish(agentId, {
+                    description,
+                    lastTool: null,
+                    toolCount,
+                    latestSummary: resultText,
+                    elapsedMs: durationMs,
+                    state: outcome === 'failed' ? 'failed' : 'done',
+                  })
+                }
                 // IO: resolve the fleet chat id and the background flag.
                 // The DECISION (gating + inbound build) is delegated to
                 // the pure `decideSubagentHandback` so it is unit-tested
@@ -17409,7 +17508,7 @@ void (async () => {
               // suppresses stale-after-restart delivery (a 4-h-old
               // "still working (5m)" would be a lie). Sweep on handback
               // lives in the `onFinish` block just above.
-              onProgress: ({ agentId, description, latestSummary, elapsedMs, prevBucketIdx, setBucketIdx }) => {
+              onProgress: ({ agentId, description, latestSummary, elapsedMs, prevBucketIdx, setBucketIdx, lastTool, toolCount }) => {
                 let fleetChatId = ''
                 let isBackground = false
                 try {
@@ -17431,6 +17530,28 @@ void (async () => {
                 }
                 if (!isBackground) return // skip overhead for foreground
 
+                // #PR2 live worker-feed: when ON, the worker's live chat
+                // message owns the progress beat. Push a running cue and
+                // return BEFORE the legacy bucket relay so the same activity
+                // isn't double-surfaced (in-message edit + injected
+                // "still working" inbound turn). Chat = owner DM, since the
+                // pinned-card fleet is gone and every agent is DM-shaped.
+                if (workerFeedEnabled) {
+                  void workerActivityFeed.update(
+                    agentId,
+                    fleetChatId || (loadAccess().allowFrom[0] ?? ''),
+                    {
+                      description,
+                      lastTool,
+                      toolCount,
+                      latestSummary,
+                      elapsedMs,
+                      state: 'running',
+                    },
+                  )
+                  return
+                }
+
                 const decision = decideSubagentProgress({
                   disableEnvValue: process.env.SWITCHROOM_DISABLE_SUBAGENT_PROGRESS,
                   isBackground,

package/telegram-plugin/reaction-defer.ts

@@ -0,0 +1,98 @@
+/**
+ * Deferred terminal-reaction bookkeeping for the "hold 👍 until background
+ * sub-agent workers finish" behaviour.
+ *
+ * The status reaction on a user's inbound message reflects CURRENT TURN
+ * ACTIVITY (see `status-reactions.ts`). When a turn dispatches a background
+ * worker (Agent/Task) and then ends, the parent's `turn_end` would paint
+ * the terminal 👍 immediately — reading as "done / nothing happening" even
+ * though the worker keeps running and the model's own text said work is
+ * ongoing. This helper holds the working glyph and defers the terminal 👍
+ * until the sub-agent watcher reports the last worker complete.
+ *
+ * Extracted as a pure, dependency-injected unit so the gateway-side
+ * interaction that bit us in review — `finalizeStatusReaction` defers, then
+ * `endCurrentTurnAtomic` purges the controller out of `activeStatusReactions`
+ * in the SAME `turn_end` sequence — is directly testable. The fix: promotion
+ * finalizes off the STORED controller reference (its emit closure still binds
+ * the right message id), not a re-lookup that the purge has already emptied.
+ */
+
+/** Minimal controller surface this helper drives. */
+export interface HoldableController {
+  /** Freeze on a working glyph, suppress stall promotion, stay non-terminal. */
+  hold(): void
+  /** Terminate to 👍 (done) / 😱 (error). Idempotent once finished. */
+  finalize(reason?: 'done' | 'error'): void
+}
+
+export interface DeferredDoneDeps<C extends HoldableController> {
+  /** Count of sub-agent workers still running (excludes historical/terminal). */
+  countRunningWorkers(): number
+  /** Current live controller registered for `key`, if any. */
+  getActive(key: string): C | undefined
+  /** Canonical turn-end cleanup for `key` (drops reaction/typing/etc state). */
+  purge(key: string): void
+}
+
+export class DeferredDoneReactions<C extends HoldableController> {
+  private readonly map = new Map<string, { ctrl: C }>()
+
+  constructor(private readonly deps: DeferredDoneDeps<C>) {}
+
+  /**
+   * Attempt to defer a terminal 'done' for `key`/`ctrl`. Returns true when
+   * deferred (the caller must NOT finalize or purge — the held controller
+   * owns the reaction until {@link promote}). Returns false when there is no
+   * running worker, in which case the caller finalizes normally.
+   */
+  tryDefer(key: string, ctrl: C): boolean {
+    if (this.deps.countRunningWorkers() > 0) {
+      ctrl.hold()
+      this.map.set(key, { ctrl })
+      // Race guard: a worker may have transitioned to done between the count
+      // above and this registration, having already fired its completion
+      // callback before the deferred entry existed. Re-check and promote now
+      // so the held reaction can't hang on a 👍 that will never come.
+      if (this.deps.countRunningWorkers() === 0) this.promote()
+      return true
+    }
+    this.map.delete(key)
+    return false
+  }
+
+  /** Drop any deferred entry for `key` without finalizing (e.g. on error). */
+  drop(key: string): void {
+    this.map.delete(key)
+  }
+
+  /**
+   * Promote every deferred reaction to the terminal 👍 — but only once no
+   * workers remain running. Finalize off the stored controller reference:
+   * the canonical `turn_end` path purges the key out of the active map right
+   * after deferring, so a key re-lookup would find nothing. `finalize()` is
+   * idempotent, and the controller's emit closure still targets the correct
+   * message. Only re-purge when the active map STILL points at this exact
+   * controller — if a newer turn replaced it, that turn owns the key now and
+   * must not be clobbered (and the turn_end path already purged, so we skip
+   * a redundant second purge).
+   */
+  promote(): void {
+    if (this.map.size === 0) return
+    if (this.deps.countRunningWorkers() > 0) return
+    for (const [key, { ctrl }] of this.map) {
+      ctrl.finalize('done')
+      if (this.deps.getActive(key) === ctrl) this.deps.purge(key)
+    }
+    this.map.clear()
+  }
+
+  /** Test/inspection hook. */
+  has(key: string): boolean {
+    return this.map.has(key)
+  }
+
+  get size(): number {
+    return this.map.size
+  }
+}

package/telegram-plugin/status-reactions.ts

@@ -141,6 +141,7 @@ export class StatusReactionController {
   private stallSoftTimer: ReturnType<typeof setTimeout> | null = null
   private stallHardTimer: ReturnType<typeof setTimeout> | null = null
   private finished = false
+  private held = false
   private readonly debounceMs: number
   private readonly stallSoftMs: number
   private readonly stallHardMs: number
@@ -219,10 +220,38 @@ export class StatusReactionController {
   cancel(): void {
     if (this.finished) return
     this.finished = true
+    this.held = false
     this.clearDebounceTimer()
     this.clearStallTimers()
   }
 
+  /**
+   * Freeze the controller in a WORKING state pending out-of-turn
+   * background work — sub-agent workers that are still running after the
+   * parent's `turn_end` fired. Painting the terminal 👍 here would read
+   * as "done / nothing happening" while the worker keeps going; instead
+   * we hold a working glyph (✍️/⚡) and let the gateway call `finalize()`
+   * once the last worker completes.
+   *
+   * Non-terminal: the controller stays live, so `finalize()` still works
+   * afterward. Suppresses stall promotion (🥱/😨) for the held window —
+   * the parent turn isn't stalled, a worker is legitimately busy, and the
+   * sub-agent watcher owns its own stall detection. Promotes a non-working
+   * current state (👀 read-receipt / 🤔 thinking) to an explicit working
+   * glyph so the user can tell work is ongoing.
+   */
+  hold(): void {
+    if (this.finished) return
+    this.held = true
+    this.clearStallTimers()
+    const working = this.resolveEmoji('tool')
+    if (working != null && working !== this.currentEmoji && working !== this.pendingEmoji) {
+      this.clearDebounceTimer()
+      this.pendingEmoji = working
+      this.enqueue(working)
+    }
+  }
+
   // ──────────────────────────────────────────────────────────────────────
 
   private scheduleState(
@@ -256,6 +285,7 @@ export class StatusReactionController {
   private finishWithState(state: ReactionState): void {
     if (this.finished) return
     this.finished = true
+    this.held = false
     this.clearStallTimers()
     // F1 fix (#553): if a non-terminal reaction is sitting in the
     // debounce window when the turn ends, flush it BEFORE the terminal
@@ -311,7 +341,7 @@ export class StatusReactionController {
 
   private resetStallTimers(): void {
     this.clearStallTimers()
-    if (this.finished) return
+    if (this.finished || this.held) return
     this.stallSoftTimer = setTimeout(() => {
       this.stallSoftTimer = null
       // Don't reset the stall timers when the stall transition itself fires —

package/telegram-plugin/subagent-watcher.ts

@@ -305,6 +305,11 @@ export interface SubagentWatcherConfig {
     elapsedMs: number
     prevBucketIdx: number | null
     setBucketIdx: (b: number) => void
+    /** Most recent tool the worker invoked, or null if none yet. Feeds
+     *  the live worker-activity feed (#PR2); the bucket relay ignores it. */
+    lastTool: { name: string; sanitisedArg: string } | null
+    /** Tool-use count observed so far. */
+    toolCount: number
   }) => void
   /** `Date.now` override for tests. */
   now?: () => number
@@ -522,6 +527,12 @@ export function readSubTail(
     elapsedMs: number
     prevBucketIdx: number | null
     setBucketIdx: (b: number) => void
+    /** Most recent tool the worker invoked (name + sanitised arg), or
+     *  null if no tool_use has been observed yet. For the live
+     *  worker-activity feed (#PR2) — the legacy bucket relay ignores it. */
+    lastTool: { name: string; sanitisedArg: string } | null
+    /** Tool-use count observed so far. */
+    toolCount: number
   }) => void,
 ): void {
   try {
@@ -675,6 +686,8 @@ export function readSubTail(
                 setBucketIdx: (b: number) => {
                   entry.lastProgressBucketIdx = b
                 },
+                lastTool: entry.lastTool,
+                toolCount: entry.toolCount,
               })
             } catch (cbErr) {
               log?.(`subagent-watcher: onProgress callback error ${entry.agentId}: ${(cbErr as Error).message}`)

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

@@ -0,0 +1,187 @@
+import { describe, it, expect, vi } from 'vitest'
+import { DeferredDoneReactions, type HoldableController } from '../reaction-defer.js'
+
+/** Fake controller recording hold/finalize calls; finalize is idempotent. */
+function makeCtrl() {
+  let finished = false
+  const ctrl: HoldableController & { held: number; doneCount: number } = {
+    held: 0,
+    doneCount: 0,
+    hold() {
+      this.held++
+    },
+    finalize(reason: 'done' | 'error' = 'done') {
+      if (finished) return
+      finished = true
+      if (reason === 'done') this.doneCount++
+    },
+  }
+  return ctrl
+}
+
+/**
+ * Harness modelling the gateway maps so the promote/purge interaction is
+ * exercised end-to-end. `purge` deletes from `active` exactly as
+ * `purgeReactionTracking` does, so a turn_end that purges right after a
+ * defer is faithfully simulated.
+ */
+function makeHarness(initialRunning = 0) {
+  const active = new Map<string, ReturnType<typeof makeCtrl>>()
+  let running = initialRunning
+  const purged: string[] = []
+  const deferred = new DeferredDoneReactions<ReturnType<typeof makeCtrl>>({
+    countRunningWorkers: () => running,
+    getActive: (key) => active.get(key),
+    purge: (key) => {
+      purged.push(key)
+      active.delete(key)
+    },
+  })
+  return {
+    active,
+    deferred,
+    purged,
+    setRunning: (n: number) => {
+      running = n
+    },
+  }
+}
+
+describe('DeferredDoneReactions', () => {
+  it('does not defer when no workers are running', () => {
+    const h = makeHarness(0)
+    const ctrl = makeCtrl()
+    h.active.set('k', ctrl)
+    expect(h.deferred.tryDefer('k', ctrl)).toBe(false)
+    expect(ctrl.held).toBe(0)
+    expect(h.deferred.size).toBe(0)
+  })
+
+  it('defers and holds while a worker runs', () => {
+    const h = makeHarness(1)
+    const ctrl = makeCtrl()
+    h.active.set('k', ctrl)
+    expect(h.deferred.tryDefer('k', ctrl)).toBe(true)
+    expect(ctrl.held).toBe(1)
+    expect(ctrl.doneCount).toBe(0)
+    expect(h.deferred.has('k')).toBe(true)
+  })
+
+  it('promotes to 👍 only once the last worker finishes', () => {
+    const h = makeHarness(2)
+    const ctrl = makeCtrl()
+    h.active.set('k', ctrl)
+    h.deferred.tryDefer('k', ctrl)
+
+    // First worker done — one still running → no promotion.
+    h.setRunning(1)
+    h.deferred.promote()
+    expect(ctrl.doneCount).toBe(0)
+    expect(h.deferred.has('k')).toBe(true)
+
+    // Last worker done → promote to 👍 and clear.
+    h.setRunning(0)
+    h.deferred.promote()
+    expect(ctrl.doneCount).toBe(1)
+    expect(h.deferred.size).toBe(0)
+  })
+
+  it('REGRESSION: promotes off the stored ref even after turn_end purged the active map', () => {
+    // This is the bug review #1999 caught: on the canonical turn_end path,
+    // finalizeStatusReaction defers, then endCurrentTurnAtomic →
+    // purgeReactionTracking deletes the controller from activeStatusReactions
+    // in the SAME sequence. A key re-lookup would find nothing and the held
+    // reaction would hang forever on the working glyph.
+    const h = makeHarness(1)
+    const ctrl = makeCtrl()
+    h.active.set('k', ctrl)
+    h.deferred.tryDefer('k', ctrl)
+
+    // Simulate endCurrentTurnAtomic purging the key out of the active map.
+    h.active.delete('k')
+
+    // Worker finishes.
+    h.setRunning(0)
+    h.deferred.promote()
+
+    // Must still reach 👍 via the stored controller reference.
+    expect(ctrl.doneCount).toBe(1)
+    // No double-purge: active map no longer holds the controller, so promote
+    // skips the redundant purge (turn_end already purged).
+    expect(h.purged).toEqual([])
+  })
+
+  it('purges via the helper when the active map still owns the controller (reply path)', () => {
+    // executeReply path keeps currentTurn (and the active map entry) alive,
+    // so promote must own the purge.
+    const h = makeHarness(1)
+    const ctrl = makeCtrl()
+    h.active.set('k', ctrl)
+    h.deferred.tryDefer('k', ctrl)
+
+    h.setRunning(0)
+    h.deferred.promote()
+
+    expect(ctrl.doneCount).toBe(1)
+    expect(h.purged).toEqual(['k'])
+  })
+
+  it('instance guard: a newer turn that replaced the key is never finalized or purged', () => {
+    const h = makeHarness(1)
+    const oldCtrl = makeCtrl()
+    h.active.set('k', oldCtrl)
+    h.deferred.tryDefer('k', oldCtrl)
+
+    // A fresh turn arrives on the same key with a brand-new controller.
+    const newCtrl = makeCtrl()
+    h.active.set('k', newCtrl)
+
+    h.setRunning(0)
+    h.deferred.promote()
+
+    // Old held controller still reaches its 👍 (its message's workers done)...
+    expect(oldCtrl.doneCount).toBe(1)
+    // ...but the new turn's controller is untouched and its key not purged.
+    expect(newCtrl.doneCount).toBe(0)
+    expect(h.purged).toEqual([])
+    expect(h.active.get('k')).toBe(newCtrl)
+  })
+
+  it('race guard: promotes immediately if the worker finished during defer', () => {
+    // countRunningWorkers returns >0 on the first call (so we defer) then 0
+    // on the re-check inside tryDefer — emulating a worker completing in the
+    // window between the two reads.
+    const active = new Map<string, ReturnType<typeof makeCtrl>>()
+    const ctrl = makeCtrl()
+    active.set('k', ctrl)
+    let calls = 0
+    const deferred = new DeferredDoneReactions<ReturnType<typeof makeCtrl>>({
+      countRunningWorkers: () => (calls++ === 0 ? 1 : 0),
+      getActive: (key) => active.get(key),
+      purge: (key) => active.delete(key),
+    })
+    expect(deferred.tryDefer('k', ctrl)).toBe(true)
+    // Race guard fired promote() inside tryDefer → already at 👍, map cleared.
+    expect(ctrl.doneCount).toBe(1)
+    expect(deferred.size).toBe(0)
+  })
+
+  it('drop() clears a deferred entry without finalizing (error path)', () => {
+    const h = makeHarness(1)
+    const ctrl = makeCtrl()
+    h.active.set('k', ctrl)
+    h.deferred.tryDefer('k', ctrl)
+    expect(h.deferred.has('k')).toBe(true)
+
+    h.deferred.drop('k')
+    expect(h.deferred.has('k')).toBe(false)
+    expect(ctrl.doneCount).toBe(0)
+  })
+
+  it('promote is a no-op when nothing is deferred', () => {
+    const h = makeHarness(0)
+    h.deferred.promote()
+    expect(h.purged).toEqual([])
+    expect(h.deferred.size).toBe(0)
+  })
+})

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

@@ -340,4 +340,83 @@ describe('StatusReactionController', () => {
     await flush()
     expect(calls).toEqual(['👀'])
   })
+
+  // 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', () => {
+    it('suppresses stall promotion (no 🥱/😨) while held', async () => {
+      const { emit, calls } = makeEmitter()
+      const ctrl = new StatusReactionController(emit)
+      ctrl.setQueued()
+      ctrl.setTool('Bash') // working: 👨‍💻
+      vi.advanceTimersByTime(3500)
+      await flush()
+
+      ctrl.hold()
+      await flush()
+      // Well past both stall thresholds — held must not yawn or panic.
+      vi.advanceTimersByTime(120000)
+      await flush()
+      expect(calls).not.toContain('🥱')
+      expect(calls).not.toContain('😨')
+    })
+
+    it('promotes a read/thinking glyph to a working glyph on hold', async () => {
+      const { emit, calls } = makeEmitter()
+      const ctrl = new StatusReactionController(emit)
+      ctrl.setQueued() // 👀 (read-receipt)
+      await flush()
+      expect(calls).toEqual(['👀'])
+
+      ctrl.hold() // should paint an explicit WORKING glyph (✍️)
+      await flush()
+      expect(calls[calls.length - 1]).toBe('✍')
+    })
+
+    it('finalize() still terminates to 👍 after hold (deferred terminal)', async () => {
+      const { emit, calls } = makeEmitter()
+      const ctrl = new StatusReactionController(emit)
+      ctrl.setQueued()
+      ctrl.setTool() // ✍
+      vi.advanceTimersByTime(3500)
+      await flush()
+
+      ctrl.hold()
+      await flush()
+      // Worker runs for a while, then completes → gateway finalizes.
+      vi.advanceTimersByTime(60000)
+      await flush()
+      ctrl.finalize('done')
+      await flush()
+      expect(calls[calls.length - 1]).toBe('👍')
+    })
+
+    it('does not double-paint when already on a working glyph', async () => {
+      const { emit, calls } = makeEmitter()
+      const ctrl = new StatusReactionController(emit)
+      ctrl.setQueued()
+      ctrl.setTool() // ✍
+      vi.advanceTimersByTime(3500)
+      await flush()
+      const before = calls.length
+
+      ctrl.hold() // already on ✍ → no new emit
+      await flush()
+      expect(calls.length).toBe(before)
+    })
+
+    it('hold() after finalize is a no-op (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.hold()
+      vi.advanceTimersByTime(120000)
+      await flush()
+      expect(calls).toEqual(snapshot)
+    })
+  })
 })