switchroom 0.20.2 → 0.20.4

package/telegram-plugin/gateway/gateway.ts

@@ -754,6 +754,7 @@ import { shadowEmit, isMachineInTurn } from './inbound-delivery-machine-shadow.j
 // #2996 P8 PR-B — the extracted turn-end funnel (state stays here; logic moved).
 import { createTurnEndFunnel, type TurnEndReason } from './turn-end.js'
 import { createTurnStartSurfaces } from './turn-start-surfaces.js'
+import { sendWithProgressCap } from './progress-fallback-cap.js'
 // #2996 P8 PR-C1 — the extracted delivery-confirm sweep wiring.
 import { createDeliveryConfirmWiring } from './delivery-confirm-wiring.js'
 // #2996 P8 PR-C2 — the extracted obligation wiring.
@@ -972,7 +973,8 @@ import {
   DEFAULT_BRIDGE_DEAD_GRACE_MS,
 } from './bridge-dead-watchdog.js'
 import { findAgentProcessInContainer } from './boot-probes.js'
-import { applySubagentsSchema, getSubagentByJsonlId, resolveSubagentOriginTurnKey, listNonTerminalSubagentsForTurn } from '../registry/subagents-schema.js'
+import { applySubagentsSchema, getSubagentByJsonlId, listNonTerminalSubagentsForTurn } from '../registry/subagents-schema.js'
+import { resolveSubagentOriginChatDb, resolveRecentTurnFallbackChat, resolveWorkerSurfaceChat, resolveWorkerSurfaceForDecider, noteWorkerRecentTurnFloor } from './subagent-origin-surface.js'
 import type { InterruptedSubagent } from './resume-inbound-builder.js'
 import { resolveWorkerFeedDispatch, decideWorkerFeedDestination, handleWorkerResume, type WorkerFeedDispatch } from './worker-feed-dispatch.js'
 import {
@@ -1960,28 +1962,23 @@ function resolveSubagentOriginChat(
   agentId: string,
 ): { chatId: string; threadId?: number } | null {
   if (turnsDb == null) return null
-  try {
-    // Transitive walk: a NESTED (depth-2+) worker's own parent_turn_key is
-    // NULL by construction (its dispatching context is another sub-agent,
-    // not a gateway turn) — resolveSubagentOriginTurnKey follows the
-    // parent_agent_id chain to the ancestor row that WAS stamped at
-    // main-turn dispatch time, so nested cards + handbacks route to the
-    // originating chat/topic instead of falling back to the owner DM.
-    const originKey = resolveSubagentOriginTurnKey(turnsDb, agentId)
-    if (originKey == null) return null
-    const turn = getTurnByKey(turnsDb, originKey)
-    if (turn == null || turn.chat_id.length === 0) return null
-    const threadNum =
-      turn.thread_id != null && turn.thread_id.length > 0
-        ? Number(turn.thread_id)
-        : NaN
-    return {
-      chatId: turn.chat_id,
-      threadId: Number.isFinite(threadNum) ? threadNum : undefined,
-    }
-  } catch {
-    return null
-  }
+  // Transitive walk (jsonl stem → parent_turn_key chain → turns row) —
+  // extracted to subagent-origin-surface.ts so the resolution precedence is
+  // unit-testable against a real registry DB. Null on any miss; the callers
+  // keep their fallback ladders (now with the recent-turn floor).
+  return resolveSubagentOriginChatDb(turnsDb, agentId)
+}
+
+/**
+ * Recent-turn routing floor (msg-6897 misroute fix): the newest turn AT OR
+ * BEFORE the worker's dispatch time — where the operator dispatched it from.
+ * Used ONLY after origin resolution has missed; bounded by the dispatch time
+ * so a later turn in an unrelated (possibly shared) chat can never capture
+ * the worker's surface. Null-safe (no pre-dispatch turn → owner-DM fallback).
+ */
+function recentTurnFallbackChat(agentId: string): { chatId: string; threadId?: number } | null {
+  if (turnsDb == null) return null
+  return resolveRecentTurnFallbackChat(turnsDb, agentId)
 }
 
 /**
@@ -2062,41 +2059,26 @@ const workerFeedOriginDeferrals = new Map<string, number>()
 const WORKER_FEED_ORIGIN_DEFER_MAX = 10
 
 /**
- * Resolve a worker-feed destination chat with a guaranteed last resort.
- *
- * The universal-liveness contract is "any active work has a card, at any
- * nesting depth, with or without a parent turn open." Origin resolution
- * (`resolveSubagentOriginChat`) only succeeds when the ancestor turn row is
- * in `turnsDb` and history is enabled; a depth-2+ worker whose chain can't
- * be walked (history disabled, row reaped, ancestor never stamped) would
- * otherwise fall through `fleetChatId || allowFrom[0]` and, if those are
- * empty too, hit the `chatId.length === 0` skip in `workerActivityFeed.update`
- * — painting NOTHING, silently. That is the one path most likely to violate
- * "any and all active work has a card."
- *
- * This never returns `''`: the precedence is origin chat → fleet chat →
- * first allowed chat (the owner DM). The owner DM is the durable floor —
- * "wrong chat" beats "no card." A one-line routing-decision log flags the
- * fallback so an operator can see the misroute without it reading as an
- * error (it isn't one — the card surfaced).
+ * Resolve a worker-feed destination chat with a guaranteed last resort
+ * (universal-liveness: "any active work has a card" — the owner DM is the
+ * durable floor, "wrong chat" beats "no card"). The ladder itself
+ * (origin → fleet → recent-turn → owner DM) lives in
+ * `resolveWorkerSurfaceChat` (subagent-origin-surface.ts) — the ONE tested
+ * implementation, shared with the handback/progress deciders below so the
+ * precedence cannot diverge per call site again; this wrapper adds only the
+ * gateway's audit logs.
  */
 function resolveWorkerFeedChat(
   agentId: string,
   fleetChatId: string,
-  // Origin sources threadId; when origin is null the caller can pass the
-  // fallback chat's sibling forum-topic id so a misrouted card still lands
-  // in the origin topic instead of General (#3458 exhausted-defer paint).
-  fallbackThreadId?: number,
 ): { chatId: string; threadId?: number } {
-  const origin = resolveSubagentOriginChat(agentId)
-  if (origin != null && origin.chatId.length > 0) return origin
-  if (fleetChatId.length > 0) return { chatId: fleetChatId, threadId: fallbackThreadId }
-  const ownerDm = loadAccess().allowFrom[0] ?? ''
-  if (origin == null && fleetChatId.length === 0 && ownerDm.length > 0) {
-    // Origin unresolved and no fleet chat — the card lands in the owner DM.
-    noteWorkerFeedOwnerDmFallback(agentId)
-  }
-  return { chatId: ownerDm, threadId: origin?.threadId ?? fallbackThreadId }
+  const dest = resolveWorkerSurfaceChat(turnsDb, agentId, {
+    fleetChatId,
+    ownerDm: loadAccess().allowFrom[0] ?? '',
+  })
+  if (dest.via === 'recent-turn') noteWorkerRecentTurnFloor(agentId, dest)
+  if (dest.via === 'owner-dm') noteWorkerFeedOwnerDmFallback(agentId)
+  return { chatId: dest.chatId, ...(dest.threadId != null ? { threadId: dest.threadId } : {}) }
 }
 
 // ─── Periodic history reaper (#1073) ──────────────────────────────────────
@@ -2798,6 +2780,13 @@ const MIDFLIGHT_BUSY_ACK_ENABLED =
 // the finalAnswerDelivered-consumer interactions.
 const FEED_REOPEN_AFTER_ACK_ENABLED =
   process.env.SWITCHROOM_FEED_REOPEN_AFTER_ACK !== '0'
+// Feed-reopen-after-SUBSTANTIVE. Distinct from the ack kill switch above: a
+// turn that delivered a real answer EARLY and then kept doing tool work had
+// its feed go dark for the rest of the turn. Lets the feed RE-OPEN after >=2
+// post-answer labels WITHOUT clearing finalAnswerDelivered. Off (=0) → legacy.
+// See `feed-reopen-gate.ts` for the full rationale.
+const FEED_REOPEN_AFTER_SUBSTANTIVE_ENABLED =
+  process.env.SWITCHROOM_FEED_REOPEN_AFTER_SUBSTANTIVE !== '0'
 
 // Activity-feed heartbeat (PR1). The feed is pull-only — it only re-renders on
 // a tool_label event, so a long single step that emits no new label leaves the
@@ -3291,6 +3280,18 @@ export type CurrentTurn = {
   // Reset to false on every fresh-turn enqueue alongside
   // `finalAnswerDelivered`.
   finalAnswerSubstantive: boolean
+  // Post-SUBSTANTIVE feed-reopen counter — incremented on each tool label that
+  // arrives while `finalAnswerDelivered && finalAnswerSubstantive` (a real
+  // answer landed early, model still working). At `SUBSTANTIVE_REOPEN_MIN_LABELS`
+  // (>=2) the tool_label handler reopens the feed (see `feed-reopen-gate.ts`).
+  // Reset to 0 on every fresh-turn enqueue.
+  postSubstantiveToolLabelCount: number
+  // Post-SUBSTANTIVE feed-reopen lever-1 lift latch. Set true by the tool_label
+  // handler when the long-turn reopen fires (>=2 post-answer labels). The drain
+  // reads it as `mayOpenActivityCard`'s `postAnswerMainActivity` so the fresh
+  // card may OPEN below the already-delivered reply despite the sticky lever-1
+  // latch. Sticky for the rest of the turn; reset to false on fresh-turn enqueue.
+  postAnswerMainActivity: boolean
   // Sticky "a substantive final answer has been delivered this turn" latch
   // (design `docs/message-emission-determinism.md` §9 preamble / R0). Distinct
   // from the MUTABLE `finalAnswerDelivered`, which the ack-reopen path clears
@@ -12491,22 +12492,15 @@ async function executeProgressUpdate(args: Record<string, unknown>): Promise<unk
     }
   }
 
-  // Turn cap: max 5 calls per turn
+  // Attention cap: max 5 DELIVERIES per turn when a turn atom exists, else a
+  // rolling 15-min/chat fallback when the inbound minted none (handback /
+  // progress-inbound turns) so a worker can't send at the 20s floor forever
+  // and defeat the documented per-turn cap. Both count deliveries only. The
+  // slot is RESERVED before the send (via sendWithProgressCap below) so two
+  // truly-concurrent same-key calls can't both pass the check and overshoot
+  // the cap, and it is RELEASED if the send throws — so a thrown send never
+  // burns a slot even under concurrency (#4328 Fix 2 preserved).
   const turnStart = activeTurnStartedAt.get(key)
-  if (turnStart != null) {
-    const currentCount = progressUpdateTurnCount.get(key) ?? 0
-    if (currentCount >= 5) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: JSON.stringify({ ok: false, reason: 'turn_limit' }),
-          },
-        ],
-      }
-    }
-    progressUpdateTurnCount.set(key, currentCount + 1)
-  }
 
   // Issue #305 Option A — the card-injection path (route a sub-agent's
   // `progress_update` narrative into its row on the parent's pinned card)
@@ -12527,14 +12521,33 @@ async function executeProgressUpdate(args: Record<string, unknown>): Promise<unk
     ...(threadId != null ? { message_thread_id: threadId } : {}),
   }
 
-  const sent = await robustApiCall(
+  // Reserve the attention-cap slot, send, and release the slot on a throw. A
+  // successful send KEEPS the reservation (it IS the delivery record), so no
+  // extra counting runs after the send. `capped` short-circuits when the
+  // reservation is refused.
+  const capped = await sendWithProgressCap(
+    { key, now, turnStart, turnCount: progressUpdateTurnCount },
     (): Promise<{ message_id: number }> =>
-      literalText
-        // allow-raw-bot-api: literal progress-update send routed through robustApiCall
-        ? lockedBot.api.sendMessage(chat_id, text, sendOpts as never)
-        : lockedBot.api.sendRichMessage(chat_id, richMessage(text), sendOpts as never),
-    { verb: 'sendMessage', chat_id, threadId },
+      robustApiCall(
+        (): Promise<{ message_id: number }> =>
+          literalText
+            // allow-raw-bot-api: literal progress-update send routed through robustApiCall
+            ? lockedBot.api.sendMessage(chat_id, text, sendOpts as never)
+            : lockedBot.api.sendRichMessage(chat_id, richMessage(text), sendOpts as never),
+        { verb: 'sendMessage', chat_id, threadId },
+      ),
   )
+  if (capped.capped) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({ ok: false, reason: 'turn_limit' }),
+        },
+      ],
+    }
+  }
+  const sent = capped.result
 
   // Record in sent-message history. RecordOutboundArgs uses `texts`
   // (parallel array to message_ids), not `text` — the singular-name
@@ -12551,6 +12564,10 @@ async function executeProgressUpdate(args: Record<string, unknown>): Promise<unk
 
   progressUpdateLastSent.set(key, now)
 
+  // The delivery slot was already reserved before the send (sendWithProgressCap
+  // above), so there is nothing to count here — a successful send keeps its
+  // reservation and a thrown send released it.
+
   // Issue #203: progress_update is a user-visible signal — tick the
   // silent-gap tracker so it doesn't count as silent time.
   try {
@@ -13921,6 +13938,7 @@ function gatewayStreamRenderDeps() {
     CONTEXT_EXHAUSTION_COOLDOWN_MS,
     DELIVERY_CONFIRM_ENABLED,
     FEED_REOPEN_AFTER_ACK_ENABLED,
+    FEED_REOPEN_AFTER_SUBSTANTIVE_ENABLED,
     HANDBACK_PRETURN_ENABLED,
     HISTORY_ENABLED,
     LIVENESS_TERMINAL_HONESTY,
@@ -24335,28 +24353,19 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                   // when this group's LAST worker finishes; no per-worker unpin.
                 }
 
-                const handbackOrigin = resolveSubagentOriginChat(agentId)
+                // ONE ladder — origin → fleet → recent-turn floor → owner DM
+                // (resolveWorkerSurfaceForDecider: the tested precedence,
+                // shaped into the decider's fleetChatId/originThreadId slots,
+                // floor audited — msg-6897 misroute fix).
+                const hbOwnerDm = loadAccess().allowFrom[0] ?? ''
                 const decision = decideSubagentHandback({
                   handbackEnvValue: process.env.SWITCHROOM_SUBAGENT_HANDBACK,
                   outcome,
                   isBackground,
-                  // Route the handback (the worker's result → a synthesized
-                  // turn) back to the conversation the Task was dispatched
-                  // from, so the result lands where the user asked — not the
-                  // agent's DM. Falls back to fleetChatId/ownerChatId.
-                  fleetChatId: handbackOrigin?.chatId || fleetChatId,
-                  // Supergroup topic the Task was dispatched from. Plumbed
-                  // through so the handback turn (and the model's in-voice
-                  // "here's what the worker found" reply) land in the
-                  // originating topic — not the chat's last-seen topic.
-                  // Applied only when the origin chat resolved (DM fallback
-                  // is topic-less).
-                  ...(handbackOrigin?.threadId != null
-                    ? { originThreadId: handbackOrigin.threadId }
-                    : {}),
+                  ...resolveWorkerSurfaceForDecider(turnsDb, agentId, { fleetChatId, ownerDm: hbOwnerDm }),
                   // Owner-chat fallback: if the parent-turn chat can't be
                   // resolved, route to the owner chat.
-                  ownerChatId: loadAccess().allowFrom[0] ?? '',
+                  ownerChatId: hbOwnerDm,
                   taskDescription: description,
                   resultText,
                   // Plumb the JSONL agent id so the spool can mint a
@@ -24650,14 +24659,26 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                   // chat/thread resolution `resolveWorkerFeedChat` did) is now one
                   // pure, unit-tested function; the gateway keeps only the defer-map
                   // bookkeeping, the two audit logs, and the feed.update.
+                  const wfOrigin = resolveSubagentOriginChat(agentId)
+                  // msg-6897 misroute fix: with origin unresolved AND no live
+                  // turn to stamp from, the exhausted-defer paint previously
+                  // fell to the owner DM. Feed the most-recent turn's
+                  // chat/topic through the SAME stamp-fallback slot (#3458)
+                  // so the paint lands near the work instead.
+                  const wfStamp =
+                    stampTurn != null
+                      ? { chatId: stampTurn.sessionChatId, threadId: stampTurn.sessionThreadId }
+                      : wfOrigin == null
+                        ? recentTurnFallbackChat(agentId)
+                        : null
                   const dest = decideWorkerFeedDestination({
-                    origin: resolveSubagentOriginChat(agentId),
+                    origin: wfOrigin,
                     cardExists: workerActivityFeed?.has(agentId) === true,
                     priorDeferrals: workerFeedOriginDeferrals.get(agentId) ?? 0,
                     maxDeferrals: WORKER_FEED_ORIGIN_DEFER_MAX,
                     fleetChatId,
-                    stampChatId: stampTurn?.sessionChatId,
-                    stampThreadId: stampTurn?.sessionThreadId,
+                    stampChatId: wfStamp?.chatId,
+                    stampThreadId: wfStamp?.threadId,
                     ownerDm: loadAccess().allowFrom[0] ?? '',
                   })
                   if (dest.action === 'defer') {
@@ -24678,6 +24699,10 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                   }
                   // Card fell to the owner DM — log the misroute once per agent.
                   if (dest.ownerDmFallback) noteWorkerFeedOwnerDmFallback(agentId)
+                  // Recent-turn floor fed the stamp slot and won — audit once (msg-6897).
+                  if (stampTurn == null && wfOrigin == null && wfStamp != null && dest.chatId === wfStamp.chatId) {
+                    noteWorkerRecentTurnFloor(agentId, wfStamp)
+                  }
                   void workerActivityFeed?.update(
                     agentId,
                     dest.chatId,
@@ -24710,20 +24735,19 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                 // the pure decision (gate 1b → 'skeleton-liveness'), which drops
                 // it deterministically (controls-in-code, unit-tested) rather
                 // than an opaque inline return here.
-                const progressOrigin = resolveSubagentOriginChat(agentId)
+                // Same single ladder as the handback above
+                // (resolveWorkerSurfaceForDecider — msg-6897 misroute fix).
+                const pgOwnerDm = loadAccess().allowFrom[0] ?? ''
+                const progressSurface = resolveWorkerSurfaceForDecider(turnsDb, agentId, {
+                  fleetChatId,
+                  ownerDm: pgOwnerDm,
+                })
                 const decision = decideSubagentProgress({
                   skeleton: skeleton === true,
                   disableEnvValue: process.env.SWITCHROOM_DISABLE_SUBAGENT_PROGRESS,
                   isBackground,
-                  // Prefer the conversation the Task was dispatched from over
-                  // the owner DM (see resolveSubagentOriginChat).
-                  fleetChatId: progressOrigin?.chatId || fleetChatId,
-                  // Carry the dispatching topic so the progress wake lands in
-                  // it (applied only when the origin chat resolved).
-                  ...(progressOrigin?.threadId != null
-                    ? { originThreadId: progressOrigin.threadId }
-                    : {}),
-                  ownerChatId: loadAccess().allowFrom[0] ?? '',
+                  ...progressSurface,
+                  ownerChatId: pgOwnerDm,
                   subagentJsonlId: agentId,
                   taskDescription: description,
                   latestSummary,
@@ -24744,7 +24768,7 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                 // in (origin thread) so the right lane is yielded in a
                 // supergroup; chat-level for DM-shaped agents.
                 pendingProgress.clearPending(
-                  statusKey(decision.chatId, progressOrigin?.threadId),
+                  statusKey(decision.chatId, progressSurface.originThreadId),
                   'progress',
                 )
                 process.stderr.write(

package/telegram-plugin/gateway/narrative-lane.ts

@@ -374,6 +374,10 @@ export function createNarrativeLane(deps: NarrativeLaneDeps) {
             labeledToolCount: turn.labeledToolCount,
             crossTurnAnswerDelivered,
             postAnswerSubagentActivity: openFlags?.postAnswerSubagentActivity,
+            // Post-SUBSTANTIVE reopen: the tool_label handler latches this sticky
+            // on `turn` when the long-turn reopen fires, so the drain lifts lever 1
+            // and the fresh card opens BELOW the already-delivered substantive reply.
+            postAnswerMainActivity: turn.postAnswerMainActivity,
           })
         ) {
           break

package/telegram-plugin/gateway/progress-fallback-cap.ts

@@ -0,0 +1,195 @@
+/**
+ * Fallback attention cap for `progress_update` when the inbound minted no turn
+ * atom.
+ *
+ * The documented ceiling for `progress_update` is "at most 5 per turn" — but
+ * that cap is enforced only when a turn atom exists (`activeTurnStartedAt` set
+ * by `turn-start-surfaces.ts`). Some inbounds mint no turn atom at all —
+ * handback turns and the synthesized progress-inbound turns — so on those a
+ * worker could call `progress_update` at the unconditional 20s floor forever
+ * (~3/min, ~180/hr into one chat), which defeats the documented cap and pings
+ * the operator's phone indefinitely.
+ *
+ * This module restores the attention cap on that path with a rolling window:
+ * at most {@link PROGRESS_FALLBACK_MAX} DELIVERIES per
+ * {@link PROGRESS_FALLBACK_WINDOW_MS} per chat/topic key. It is not a ban
+ * defence — the 20s floor and the edit-flood fuse still pace sends; this only
+ * bounds how many phone-pinging progress messages a turn-less path can emit.
+ *
+ * State is a per-key list of delivery timestamps, pruned in place on every
+ * access; a key whose window empties is dropped from the map so it cannot grow
+ * unbounded across chats that have gone quiet. Because each window holds at
+ * most {@link PROGRESS_FALLBACK_MAX} entries, the per-key array is O(1).
+ */
+
+const recentSends = new Map<string, number[]>();
+
+/** Rolling window length. */
+export const PROGRESS_FALLBACK_WINDOW_MS = 15 * 60_000;
+/** Max deliveries per window per key — mirrors the 5-per-turn cap. */
+export const PROGRESS_FALLBACK_MAX = 5;
+
+/**
+ * Prune timestamps older than the window for `key`, persisting the result.
+ * Drops the key entirely when its window is empty so the map stays bounded.
+ */
+function prune(key: string, now: number): number[] {
+  const cutoff = now - PROGRESS_FALLBACK_WINDOW_MS;
+  const recent = (recentSends.get(key) ?? []).filter((ts) => ts > cutoff);
+  if (recent.length === 0) recentSends.delete(key);
+  else recentSends.set(key, recent);
+  return recent;
+}
+
+/**
+ * True when the rolling window for `key` is already at capacity — the caller
+ * should refuse the send with `turn_limit`. Read-only w.r.t. the delivery
+ * count (it only prunes aged-out entries); record a delivery separately via
+ * {@link recordProgressFallbackSend} AFTER the send lands.
+ */
+export function progressFallbackAtCap(key: string, now: number): boolean {
+  return prune(key, now).length >= PROGRESS_FALLBACK_MAX;
+}
+
+/**
+ * Record one successful fallback-path delivery. Call ONLY after the send has
+ * actually landed, so a thrown send never consumes a window slot.
+ *
+ * NOTE: this is the check-then-record shape (`progressFallbackAtCap` then
+ * `recordProgressFallbackSend`) which is NOT safe against two truly-concurrent
+ * same-key calls — both can pass the cap check before either records. The
+ * production path uses {@link reserveProgressSlot} / {@link sendWithProgressCap}
+ * instead, which reserve the slot BEFORE the await so the count is visible to a
+ * concurrent caller. These two remain for the direct unit tests of the window.
+ */
+export function recordProgressFallbackSend(key: string, now: number): void {
+  const recent = prune(key, now);
+  recent.push(now);
+  recentSends.set(key, recent);
+}
+
+/** A reserved cap slot; call {@link release} to hand it back (idempotent). */
+export interface ProgressSlotReservation {
+  release: () => void;
+}
+
+/**
+ * Reserve one fallback-window slot for `key` at `now`, or refuse when the
+ * window is already at capacity.
+ *
+ * Unlike {@link progressFallbackAtCap} + {@link recordProgressFallbackSend},
+ * this records the timestamp AT CHECK TIME (before the caller's `await`), so a
+ * second concurrent same-key call sees the reservation and cannot overshoot the
+ * cap. On send failure the caller must {@link ProgressSlotReservation.release |
+ * release} it, which removes exactly the one timestamp this reservation added —
+ * so a throw still burns no slot (#4328 Fix 2 preserved under concurrency).
+ *
+ * Returns `null` when the window is full (caller refuses with `turn_limit`).
+ */
+export function reserveProgressFallbackSlot(
+  key: string,
+  now: number,
+): ProgressSlotReservation | null {
+  const recent = prune(key, now);
+  if (recent.length >= PROGRESS_FALLBACK_MAX) return null;
+  recent.push(now);
+  recentSends.set(key, recent);
+
+  let released = false;
+  return {
+    release: () => {
+      if (released) return;
+      released = true;
+      const arr = recentSends.get(key);
+      if (!arr) return;
+      // Remove exactly ONE occurrence of the reserved timestamp — concurrent
+      // reservations may share the same `now`, and they are interchangeable.
+      const idx = arr.indexOf(now);
+      if (idx >= 0) arr.splice(idx, 1);
+      if (arr.length === 0) recentSends.delete(key);
+      else recentSends.set(key, arr);
+    },
+  };
+}
+
+/** Max `progress_update` deliveries per turn atom — mirrors the fallback cap. */
+export const PROGRESS_TURN_MAX = 5;
+
+/** Dependencies the unified reservation needs, threaded from the gateway. */
+export interface ProgressCapDeps {
+  /** The chat/topic status key. */
+  key: string;
+  /** `Date.now()` captured once by the caller. */
+  now: number;
+  /**
+   * `activeTurnStartedAt.get(key)` — presence selects the turn-scoped counter
+   * path; absence selects the rolling fallback window.
+   */
+  turnStart: number | undefined;
+  /** The live per-turn counter (`progressUpdateTurnCount`). */
+  turnCount: Map<string, number>;
+}
+
+/**
+ * Reserve one attention-cap slot BEFORE the send, race-safely, on whichever
+ * path applies:
+ *
+ * - turn atom present → increment `progressUpdateTurnCount` now (bounded at
+ *   {@link PROGRESS_TURN_MAX}); release decrements it.
+ * - turn atom absent → reserve a rolling-window slot via
+ *   {@link reserveProgressFallbackSlot}.
+ *
+ * Because the reservation mutates the shared count synchronously (no `await`
+ * between the read and the write), a second concurrent same-key call sees it
+ * and cannot push the count past the cap. Returns `null` when already at cap.
+ */
+export function reserveProgressSlot(
+  deps: ProgressCapDeps,
+): ProgressSlotReservation | null {
+  const { key, now, turnStart, turnCount } = deps;
+  if (turnStart != null) {
+    const current = turnCount.get(key) ?? 0;
+    if (current >= PROGRESS_TURN_MAX) return null;
+    turnCount.set(key, current + 1);
+    let released = false;
+    return {
+      release: () => {
+        if (released) return;
+        released = true;
+        turnCount.set(key, Math.max(0, (turnCount.get(key) ?? 0) - 1));
+      },
+    };
+  }
+  return reserveProgressFallbackSlot(key, now);
+}
+
+/**
+ * The reserve-then-confirm wrapper the gateway's `executeProgressUpdate` uses
+ * around its send. Reserves a cap slot (race-safe, before the await), runs
+ * `send`, and RELEASES the slot if `send` throws — so a failed delivery never
+ * consumes a slot even under concurrency.
+ *
+ * Returns `{ capped: true }` when already at cap (no send attempted), else
+ * `{ capped: false, result }` with the successful send's result. A successful
+ * send KEEPS the reservation (it is the delivery record); the caller records
+ * nothing extra.
+ */
+export async function sendWithProgressCap<T>(
+  deps: ProgressCapDeps,
+  send: () => Promise<T>,
+): Promise<{ capped: true } | { capped: false; result: T }> {
+  const reservation = reserveProgressSlot(deps);
+  if (reservation === null) return { capped: true };
+  try {
+    const result = await send();
+    return { capped: false, result };
+  } catch (err) {
+    reservation.release();
+    throw err;
+  }
+}
+
+/** Test-only: clear all fallback-window state. */
+export function _resetProgressFallbackCap(): void {
+  recentSends.clear();
+}