switchroom 0.19.25 → 0.19.27

package/telegram-plugin/gateway/outbound-send-path.ts

@@ -52,6 +52,7 @@ import {
 } from '../format.js'
 import { richMessage } from '../rich-send.js'
 import { journalExternalDelivery } from './outbox-sweep.js'
+import { queueFloodBlockedReply } from './flood-reply-queue.js'
 import { resolveChatIdFallback } from './chat-id-fallback.js'
 import { isFinalAnswerReply, isSubstantiveFinalReply, shouldJournalReplySiteDelivery } from '../final-answer-detect.js'
 import { decideOverPing, type OverPingDecision } from '../over-ping-safety-net.js'
@@ -1960,6 +1961,41 @@ export async function sendReply(
     threadId = _sendResult.threadId
     previewMessageId = _sendResult.previewMessageId
   } catch (err) {
+    // #3861 — a flood-blocked reply is QUEUED, never discarded. Pre-fix this
+    // catch re-wrapped `FLOOD_WAIT_ACTIVE` into a string and threw the answer
+    // away: `retryApiCall` fails fast BEFORE the wire while a long window is
+    // open, so during a multi-hour ban EVERY answer the agent composed for the
+    // operator was lost — the one content class the durable outbox did not
+    // cover. The undelivered text goes into the same outbox the sweep drains
+    // (it defers while the window is open, #3854) under a content-derived
+    // nonce, so a caller retry cannot double-deliver. `cosmetic` sends are
+    // still dropped by `queueFloodBlockedReply`; this site is `critical`.
+    const queued = queueFloodBlockedReply({
+      err,
+      chatId: chat_id,
+      threadId: threadId ?? null,
+      // Partial failure: queue only the chunks that never landed, so the user
+      // does not receive the already-delivered prefix a second time.
+      text: sentIds.length === 0 ? text : chunks.slice(sentIds.length).join('\n\n'),
+      priorityClass: 'critical',
+      originChatId: turn?.sessionChatId ?? null,
+      originThreadId: turn?.sessionThreadId ?? null,
+    })
+    if (queued != null) {
+      process.stderr.write(
+        `telegram gateway: reply flood-deferred — queued to outbox nonce=${queued.turnNonce} ` +
+          `chat=${chat_id} chars=${text.length} sent=${sentIds.length}/${chunks.length}\n`,
+      )
+      // The obligation is DISCHARGED by the durable enqueue. Without this the
+      // obligation tracker keeps re-prompting the agent to reply every few
+      // minutes for the whole ban — dozens of forced turns it physically
+      // cannot satisfy (and pre-#3861 each attempt destroyed its own answer).
+      if (turn != null && isSubstantiveFinalReply({ text, disableNotification: modelDisableNotification })) {
+        closeObligationOnSubstantiveReply(args, turn, replyRoutedOriginTurn)
+      }
+      // (the `finally` below stops the typing loop on this return path too)
+      return { content: [{ type: 'text', text: queued.notice }] }
+    }
     const msg = err instanceof Error ? err.message : String(err)
     throw new Error(`reply failed after ${sentIds.length} of ${chunks.length} chunk(s) sent: ${msg}`)
   } finally {

package/telegram-plugin/gateway/outbox-sweep.ts

@@ -45,6 +45,11 @@ import {
 import { isShownBlock } from '../shown-ledger.js'
 import { resolveSubagentOriginTurnKey } from '../registry/subagents-schema.js'
 import { createRetryApiCall, retryWithThreadFallback } from '../retry-api-call.js'
+import {
+  floodStatePath,
+  makeFloodWaitProbe,
+  makeFloodWaitRecorder,
+} from '../flood-circuit-breaker.js'
 
 export interface OutboxSweepDeps {
   /** Deliver `text` to the chat. Resolves to the primary message id (best-effort). */
@@ -67,12 +72,39 @@ export interface OutboxSweepDeps {
   now?: () => number
   log?: (line: string) => void
   quietMs?: number
+  /**
+   * Remaining ms of a KNOWN-OPEN Telegram flood window, or 0 when none — the
+   * SAME persisted breaker state (`flood-wait.json`) `robustApiCall` consults
+   * (`makeFloodWaitProbe`). When it reports an open window the sweep does not
+   * scan, claim, or send at all.
+   *
+   * Why the sweep needs its own check on top of the retry policy's: the retry
+   * policy only short-circuits windows LONGER than its in-process sleep ceiling
+   * (120s), and even then it does so per-CALL — it still costs a claim/release
+   * cycle and a log line every tick. The outbox is a safety net with no latency
+   * SLA; deferring the whole sweep while ANY window is open is strictly correct
+   * and is the only thing that makes "does not hit the wire" true.
+   *
+   * FAILS OPEN (a throwing probe ⇒ 0) for the same reason `makeFloodWaitProbe`
+   * does: a broken marker file must never permanently strand the outbox.
+   */
+  floodWaitRemainingMs?: () => number
 }
 
 export interface OutboxSweepSummary {
   scanned: number
   delivered: number
   skipped: number
+  /**
+   * Records whose send THREW this sweep (claim released, retried next tick).
+   * The tick-level backoff keys off this: a 5s fixed retry against a failing
+   * Telegram is how the 2026-07-27 sweep hit an open 4.4h ban 228 times.
+   */
+  sendFailures: number
+  /** True when the whole sweep was skipped because a flood window is open. */
+  floodDeferred?: boolean
+  /** Remaining ms of the window that caused `floodDeferred`. */
+  floodRemainingMs?: number
 }
 
 /**
@@ -81,7 +113,20 @@ export interface OutboxSweepSummary {
 export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSummary> {
   const now = deps.now?.() ?? Date.now()
   const log = deps.log ?? (() => {})
-  const summary: OutboxSweepSummary = { scanned: 0, delivered: 0, skipped: 0 }
+  const summary: OutboxSweepSummary = { scanned: 0, delivered: 0, skipped: 0, sendFailures: 0 }
+
+  // #3853 — do not sweep INTO a known-open flood window. Every record is
+  // preserved on disk and re-scanned on the next tick after the window closes,
+  // so this loses no delivery; issuing the send would only feed the ban.
+  const remainingMs = probeFloodWindow(deps.floodWaitRemainingMs)
+  if (remainingMs > 0) {
+    summary.floodDeferred = true
+    summary.floodRemainingMs = remainingMs
+    // NOT logged here: a 4.4h ban is ~3181 ticks, and one line per tick just
+    // moves the flood from the wire to the disk. `startOutboxSweep` logs the
+    // deferral at most once per DEFER_LOG_INTERVAL_MS.
+    return summary
+  }
 
   // Re-queue crashed claims first (claim-then-crash before send).
   reclaimStaleSending(deps.stateDir, now)
@@ -90,9 +135,27 @@ export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSum
   if (pending.length === 0) return summary
   const deliveredNonces = readDeliveredNonces(deps.stateDir)
 
-  for (const fileName of pending) {
-    const record = readOutboxRecord(fileName, deps.stateDir)
-    if (record == null) continue
+  // #3861 — deliver in CAPTURE order. `listPendingRecords` returns readdir
+  // order, which is filesystem-dependent (hash order on most Linux filesystems,
+  // i.e. effectively the nonce's hash). That was harmless while the outbox held
+  // at most one stray handback per turn; it is not harmless now that a
+  // multi-hour flood window can park a whole conversation's worth of queued
+  // replies, which would then land shuffled. Sort by `createdAt`, tie-broken by
+  // nonce so the order is total and deterministic.
+  const records = pending
+    .map((fileName) => readOutboxRecord(fileName, deps.stateDir))
+    .filter((r): r is OutboxRecord => r != null)
+    .sort((a, b) =>
+      a.createdAt !== b.createdAt
+        ? a.createdAt - b.createdAt
+        : a.turnNonce < b.turnNonce
+          ? -1
+          : a.turnNonce > b.turnNonce
+            ? 1
+            : 0,
+    )
+
+  for (const record of records) {
     summary.scanned++
 
     // Resolve destination (anchor → registry chain → per-session origin). Fails
@@ -209,12 +272,24 @@ export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSum
       // preserved on disk; no loss.
       releaseClaim(record.turnNonce, deps.stateDir)
       summary.skipped++
+      summary.sendFailures++
       log(`outbox-sweep: send failed nonce=${record.turnNonce}: ${(err as Error).message} — will retry\n`)
     }
   }
   return summary
 }
 
+/** Read the flood probe, failing OPEN on any throw. */
+function probeFloodWindow(probe: (() => number) | undefined): number {
+  if (probe == null) return 0
+  try {
+    const ms = probe()
+    return Number.isFinite(ms) && ms > 0 ? ms : 0
+  } catch {
+    return 0
+  }
+}
+
 /**
  * Parse a registry `turn_key` (`chatId:threadId`, `_` → null thread) into a
  * routable chat. Exported for the gateway wiring + tests.
@@ -230,6 +305,59 @@ export function chatFromTurnKey(turnKey: string): { chatId: string; threadId: nu
 /** How often the sweep ticks (aligned with the delivery-confirm sweep cadence). */
 export const OUTBOX_SWEEP_INTERVAL_MS = 5_000
 
+/** Ceiling on the exponential send-failure backoff. */
+export const OUTBOX_SWEEP_BACKOFF_MAX_MS = 5 * 60_000
+
+/**
+ * Minimum gap between two "flood window still open" log lines. A 4.4h ban is
+ * ~3181 ticks; logging each one just relocates the flood from the wire to the
+ * disk, so the deferral is reported once a minute instead.
+ */
+export const OUTBOX_SWEEP_DEFER_LOG_INTERVAL_MS = 60_000
+
+/**
+ * Exponential backoff over the fixed 5s sweep tick (#3853).
+ *
+ * The tick interval alone is not a retry policy. On 2026-07-27 the sweep held
+ * ONE undeliverable record and re-issued its `sendMessage` every 5s for the
+ * whole 4.4h ban — 228 requests into a window the breaker already knew was
+ * open, each one answered with the same counting-down `retry_after`. The flood
+ * probe (above) closes the case where the breaker HAS a window recorded; this
+ * closes the case where it does not — a persistent failure of any other kind
+ * must not be re-driven at 12 requests/minute forever.
+ *
+ * Pure and clock-injected so the schedule is asserted in tests rather than
+ * inferred from timer behaviour.
+ */
+export function createSweepBackoff(cfg: { baseMs?: number; maxMs?: number } = {}): {
+  ready: (now: number) => boolean
+  noteFailure: (now: number) => number
+  noteSuccess: () => void
+  failures: () => number
+} {
+  const baseMs = cfg.baseMs ?? OUTBOX_SWEEP_INTERVAL_MS
+  const maxMs = cfg.maxMs ?? OUTBOX_SWEEP_BACKOFF_MAX_MS
+  let failures = 0
+  let nextAllowedAt = 0
+  return {
+    ready: (now) => now >= nextAllowedAt,
+    noteFailure: (now) => {
+      failures++
+      // 5s, 10s, 20s, … capped. `failures - 1` so the FIRST failure still
+      // retries at the normal tick cadence — a one-off transient send error
+      // should not delay a real answer.
+      const delay = Math.min(maxMs, baseMs * Math.pow(2, failures - 1))
+      nextAllowedAt = now + delay
+      return delay
+    },
+    noteSuccess: () => {
+      failures = 0
+      nextAllowedAt = 0
+    },
+    failures: () => failures,
+  }
+}
+
 /**
  * Own the heartbeat-tick outbox sweep entirely, keeping the timer / chunking /
  * turn-key parse / dedup / registry-chain wiring OUT of `gateway.ts` (the line
@@ -336,21 +464,43 @@ export function startOutboxSweep(deps: {
     text: string,
   ) => OutboxDeliveryMarkup | undefined
   log?: (line: string) => void
+  /** Test seam — override the flood probe (default: the persisted breaker). */
+  floodWaitRemainingMs?: () => number
+  /** Test seam — override the tick backoff. */
+  backoff?: ReturnType<typeof createSweepBackoff>
 }): ReturnType<typeof setInterval> | undefined {
   if (!deps.isGatewayMain || process.env.SWITCHROOM_TG_OUTBOX_DELIVERY === '0') return undefined
-  const retry = createRetryApiCall({ log: deps.log })
+  // #3853 — the sweep is a full outbound machine and must consult the SAME
+  // persisted flood breaker every other outbound path does. Before this it was
+  // the one `createRetryApiCall` wiring with neither hook: it could not see an
+  // open ban (no `floodWaitRemainingMs`) and could not record one it caused (no
+  // `onFloodWait`). `scripts/check-retry-flood-hooks.mjs` now fails lint if any
+  // wiring omits either.
+  const floodProbe =
+    deps.floodWaitRemainingMs ?? makeFloodWaitProbe(floodStatePath(deps.stateDir))
+  const recordFloodWait = makeFloodWaitRecorder(floodStatePath(deps.stateDir))
+  const retry = createRetryApiCall({
+    log: deps.log,
+    floodWaitRemainingMs: floodProbe,
+    onFloodWait: (retryAfterSec) => recordFloodWait(retryAfterSec),
+  })
   const send = createOutboxSend({
     getBot: deps.getBot,
     retry,
     ...(deps.resolveReplyMarkup != null ? { resolveReplyMarkup: deps.resolveReplyMarkup } : {}),
   })
+  const backoff = deps.backoff ?? createSweepBackoff()
+  let lastDeferLogAt = 0
   const tick = () => {
     const bot = deps.getBot()
     if (bot == null) return
+    const now = Date.now()
+    if (!backoff.ready(now)) return
     void sweepOutbox({
       stateDir: deps.stateDir,
       log: deps.log,
       send,
+      floodWaitRemainingMs: floodProbe,
       textAlreadyDelivered: (chatId, threadId, text) => deps.dedupCheck(chatId, threadId ?? undefined, text),
       registryChainLookup: (taskId) => {
         const db = deps.getTurnsDb()
@@ -358,7 +508,34 @@ export function startOutboxSweep(deps: {
         const turnKey = resolveSubagentOriginTurnKey(db, taskId)
         return turnKey == null ? null : chatFromTurnKey(turnKey)
       },
-    }).catch((err) => deps.log?.(`outbox-sweep: tick failed: ${(err as Error).message}\n`))
+    })
+      .then((summary) => {
+        // A flood-deferred sweep is neither success nor failure: it never
+        // reached the wire, so it must not clear a backoff earned by real
+        // failures, and it must not deepen one either.
+        if (summary.floodDeferred === true) {
+          const at = Date.now()
+          if (at - lastDeferLogAt >= OUTBOX_SWEEP_DEFER_LOG_INTERVAL_MS) {
+            lastDeferLogAt = at
+            deps.log?.(
+              `outbox-sweep: deferred — Telegram flood window still open for ` +
+                `${Math.ceil((summary.floodRemainingMs ?? 0) / 1000)}s; not issuing any ` +
+                `send (would feed the ban)\n`,
+            )
+          }
+          return
+        }
+        if (summary.sendFailures > 0) {
+          const delay = backoff.noteFailure(Date.now())
+          deps.log?.(
+            `outbox-sweep: ${summary.sendFailures} send failure(s) — backing off ` +
+              `${Math.round(delay / 1000)}s before the next sweep (attempt ${backoff.failures()})\n`,
+          )
+        } else {
+          backoff.noteSuccess()
+        }
+      })
+      .catch((err) => deps.log?.(`outbox-sweep: tick failed: ${(err as Error).message}\n`))
   }
   const timer = setInterval(tick, OUTBOX_SWEEP_INTERVAL_MS)
   timer.unref?.()

package/telegram-plugin/gateway/periodic-sweep-guard.ts

@@ -0,0 +1,86 @@
+/**
+ * periodic-sweep-guard.ts — single-flight wrapper for an interval-driven sweep.
+ *
+ * Why this exists
+ * ---------------
+ * `runMidSessionCardReaper` (gateway.ts) is dispatched from a `setInterval` as
+ * `void run()`, every 5 minutes by default. Its body awaits REAL Telegram calls:
+ * `robustApiCall` finalize edits for orphaned activity cards, and
+ * `reconcileStatusPin` unpins for stale `wk:` pins. Both retry with backoff and
+ * both can park behind a flood-wait — this gateway took a 62-minute flood ban on
+ * 2026-07-25.
+ *
+ * With no guard, every tick started ANOTHER concurrent pass. During a stall that
+ * is unbounded fan-out: N passes reading the same `status-pins.json`, deciding
+ * the same reaps, and firing duplicate unpins into the very rate limit that was
+ * slowing them down. Concurrent passes also race each other in the store-orphan
+ * branch, which unpins and drops the row OUTSIDE the per-key reconcile lock.
+ *
+ * The guard is deliberately SKIP, not queue: a tick arriving while a pass is
+ * running is dropped. The reaper is a backstop with no deadline, and the next
+ * tick is at most one interval away — queuing would just rebuild the same
+ * pile-up with extra latency.
+ *
+ * It also absorbs a throw out of the pass. The gateway's `unhandledRejection`
+ * handler crashes the process, and a fire-and-forget cosmetic sweep must never
+ * be able to do that (the same rule `reconcileStatusPin` follows after a benign
+ * pin-rights 400 took the whole gateway down, marko 2026-07-01).
+ */
+
+export interface PeriodicSweepGuard {
+  /** Run the sweep unless a pass is already in flight. Never rejects. */
+  tick(): Promise<void>
+  /** True while a pass is in flight. Test/introspection seam. */
+  isRunning(): boolean
+  /** Passes skipped because one was already running. Test/introspection seam. */
+  skipped(): number
+}
+
+/**
+ * Wrap `run` so at most one pass is in flight at a time.
+ *
+ * `onSkip` / `onError` are optional observers (the gateway logs to stderr);
+ * both are themselves absorbed, so a broken logger cannot take down the one
+ * function whose job is to make the sweep un-crashable.
+ */
+export function createPeriodicSweepGuard(args: {
+  run: () => Promise<void>
+  onSkip?: () => void
+  onError?: (err: unknown) => void
+}): PeriodicSweepGuard {
+  let running = false
+  let skippedCount = 0
+
+  const notify = (fn: (() => void) | undefined): void => {
+    if (fn == null) return
+    try {
+      fn()
+    } catch {
+      /* an observer must never break the guard */
+    }
+  }
+
+  return {
+    async tick(): Promise<void> {
+      if (running) {
+        skippedCount += 1
+        notify(args.onSkip)
+        return
+      }
+      running = true
+      try {
+        await args.run()
+      } catch (err) {
+        notify(args.onError == null ? undefined : () => args.onError?.(err))
+      } finally {
+        running = false
+      }
+    },
+    isRunning(): boolean {
+      return running
+    },
+    skipped(): number {
+      return skippedCount
+    },
+  }
+}

package/telegram-plugin/gateway/pinned-message-handler.ts

@@ -5,7 +5,7 @@
  * silent status-pin fires. The pin call passes `disable_notification: true`,
  * which kills the PUSH notification but NOT the in-chat service message — so we
  * delete that service message as it lands, but ONLY for pins we own (tracked in
- * `statusPinState`). Manual/operator pins are never silent and are never
+ * `statusPinClaims`). Manual/operator pins are never silent and are never
  * touched. Only silent status pins reach here as an OUR-pin match, so the
  * ownership check is the guard.
  *
@@ -21,13 +21,12 @@
 
 import type { Context, Filter } from 'grammy'
 import { pinnedMessageIsOurs, type TrackedStatusPin } from './status-pin-store.js'
-import type { PinState } from '../status-pin.js'
+import type { StatusPinClaim } from './status-pin-retarget.js'
 
 export interface PinnedMessageHandlerDeps {
-  /** Live pinKey→PinState registry of pins we own. */
-  statusPinState: ReadonlyMap<string, PinState>
-  /** Companion pinKey→chatId registry (chat-scoped ownership). */
-  statusPinChatIds: ReadonlyMap<string, string>
+  /** Live pinKey→claim registry of pins we own. ONE record per key (#3809):
+   *  the chat id is a field of the claim, not a parallel map that can diverge. */
+  statusPinClaims: ReadonlyMap<string, StatusPinClaim>
   /**
    * Delete the pin service message. Bound in gateway.ts through
    * `robustApiCall(() => lockedBot.api.deleteMessage(...))` so the raw Bot API
@@ -50,16 +49,13 @@ export async function handlePinnedMessage(
   // Chat-scoped ownership (see pinnedMessageIsOurs): the match requires BOTH
   // the messageId AND that the tracked entry lives in THIS chat, so a pin id
   // colliding across chats can't delete a foreign (e.g. operator-manual) pin
-  // notice. statusPinChatIds is the companion pinKey→chatId map written on
-  // every desired-pinned reconcile.
-  const trackedPins = (): TrackedStatusPin[] => {
-    const out: TrackedStatusPin[] = []
-    for (const [pinKey, state] of deps.statusPinState) {
-      const c = deps.statusPinChatIds.get(pinKey)
-      if (c != null) out.push({ chatId: c, messageId: state.messageId })
-    }
-    return out
-  }
+  // notice. Each claim carries its own chat id (#3809), so the match can never
+  // silently degrade to messageId-only because a companion map went missing.
+  const trackedPins = (): TrackedStatusPin[] =>
+    [...deps.statusPinClaims.values()].map((c) => ({
+      chatId: c.chatId,
+      messageId: c.messageId,
+    }))
   const isOurs = () => pinnedMessageIsOurs(trackedPins(), chatId, pinnedId)
 
   if (!isOurs()) {

package/telegram-plugin/gateway/status-pin-retarget.ts

@@ -0,0 +1,180 @@
+/**
+ * status-pin-retarget.ts — orchestrates a status-pin RETARGET as two persisted
+ * legs, so a single-shot caller still ends up with the new surface pinned.
+ *
+ * The defect this closes
+ * ----------------------
+ * `decidePinAction(prev, { pinned: true, messageId: NEW })` with a claim on a
+ * DIFFERENT message used to report a bare `unpin`, documented as "a subsequent
+ * desired-pin re-pins the new one on the next reconcile". That is true only for
+ * callers that RE-DRIVE the reconcile:
+ *
+ *   - the worker-activity feed does (`syncPin` runs on every steady-state edit,
+ *     `worker-activity-feed.ts`), so its group-message rotation converges;
+ *   - the FOREGROUND activity card does NOT. `narrative-lane.ts` reconciles
+ *     `fg:<statusKey>` exactly once, inside the `activityMessageId == null`
+ *     OPEN branch; the `else` (edit) branch never touches the pin, and turn-end
+ *     only ever unpins (`turn-end.ts`).
+ *
+ * So when the ack-first reopen path (`feed-reopen-gate.ts`) nulls
+ * `activityMessageId` mid-turn and a FRESH card opens, that one reconcile
+ * unpinned the old card and stopped. The live card ran unpinned for the rest of
+ * the turn, and — because the retarget mapped to a `clear` persist op — the
+ * durable `status-pins.json` row was deleted too, so neither the mid-session
+ * reaper nor the next boot's sweep had anything left to reconcile from.
+ *
+ * Why TWO legs and not one
+ * ------------------------
+ * `reconcileAndPersistStatusPin` carries the persist-BEFORE-pin contract for a
+ * single op. Running the retarget as one `pin`-op leg would write a pending row
+ * naming the NEW id before the OLD one is unpinned — a crash in that window
+ * erases the only durable record of a message that is still pinned. Splitting
+ * it keeps each leg's crash-safety exactly as designed:
+ *
+ *   leg 1  unpin the stale claim, with the row still naming the OLD id;
+ *   leg 2  pin the new message from a null claim, with its own pending row.
+ *
+ * Failure semantics are inherited from `executePinLeg`, not re-invented here: a
+ * leg-1 result that is NON-NULL means the unpin was never confirmed (#3664
+ * Defect B — the old message is provably still pinned and the claim was
+ * deliberately retained). Pinning the new message then would leave two pins in
+ * the chat with a durable record of one, so leg 2 is skipped and the retained
+ * claim is left for the next reconcile / the mid-session reaper / the boot
+ * sweep to retry.
+ *
+ * THE SINGLE PATH (#3831)
+ * -----------------------
+ * This module is the ONLY decider. `status-pin-driver.ts` used to call
+ * `decidePinAction` itself and carry its OWN copy of the expansion above — a
+ * copy that recursed without the per-leg persistence, so which of the two
+ * implementations ran decided whether the durable row survived. That copy is
+ * deleted, and the driver's parameter type (`PinLegAction`) can no longer even
+ * express a repin, so a second one cannot grow back.
+ *
+ * Dependency-free apart from the pure decision, so it is provable in isolation
+ * (`telegram-plugin/tests/status-pin-retarget.test.ts`); the gateway owns the
+ * wiring of `runPin` / `commit`.
+ */
+
+import type { DesiredPin, PinLegAction, PinState } from '../status-pin.js'
+import { decidePinAction } from '../status-pin.js'
+import type { StatusPinPersistOp, StatusPinStoreFsSeam } from './status-pin-store.js'
+import { reconcileAndPersistStatusPin } from './status-pin-store.js'
+
+/**
+ * ONE in-memory claim for a pin key — the message we believe is pinned, the
+ * chat it lives in, and when the claim was FIRST taken (the reaper's TTL age).
+ *
+ * #3809 — these were three parallel `Map`s (`statusPinState` / `statusPinChatIds`
+ * / `statusPinPinnedAt`) written together but able to diverge. A `wk:` claim
+ * whose chatId entry went missing was skipped by the mid-session reaper on
+ * EVERY pass (it cannot unpin without a chat) and excluded from the durable
+ * store-orphan net (which skips keys that DO have an in-memory claim) — so it
+ * was permanently unreapable until the next boot, silently. Collapsing the
+ * three maps into one record makes the invariant STRUCTURAL: a claim without a
+ * chat id cannot be represented, so that gap cannot be reintroduced.
+ */
+export interface StatusPinClaim {
+  /** Telegram message_id we believe is pinned for this key. */
+  messageId: number
+  /** Chat the pin lives in. Never empty — the reconcile refuses an empty chat. */
+  chatId: string
+  /** Wall-clock ms the claim was FIRST taken (survives a same-id re-pin). */
+  pinnedAt: number
+}
+
+export interface StatusPinReconcileArgs {
+  pinKey: string
+  chatId: string
+  /** The claim held for this key when the reconcile started. */
+  prev: PinState | null
+  /** What the caller wants pinned for this key now. */
+  desired: DesiredPin
+  /** Durable-store binding, or null when persistence is off (STATIC). */
+  persist: { path: string; fs: StatusPinStoreFsSeam } | null
+  /**
+   * Execute ONE already-decided leg against Telegram (the gateway binds
+   * `executePinLeg`). Must never throw — API errors are absorbed inside.
+   */
+  runPin: (action: PinLegAction, from: PinState | null) => Promise<PinState | null>
+  /** The single claim registry, keyed by pinKey. */
+  claims: Map<string, StatusPinClaim>
+  /** Injectable clock for the `pinnedAt` stamp (tests). */
+  now?: () => number
+}
+
+/**
+ * Drive `prev → desired` for one pin key, expanding a RETARGET into its two
+ * legs. Every other action (pin / unpin / noop) is a single leg, unchanged.
+ *
+ * Each leg is committed to the claim registry as it lands, so the in-memory
+ * claim never lags the durable row — including the intermediate cleared state
+ * between a retarget's two legs, which is what lets a concurrent reader (the
+ * `wk:` reaper) see an honest snapshot rather than a claim on an unpinned id.
+ *
+ * Callers must hold the per-key reconcile lock (`withPinReconcileLock`); `prev`
+ * is read once by the caller and both legs run inside that critical section.
+ */
+export async function runStatusPinReconcile(args: StatusPinReconcileArgs): Promise<void> {
+  const { pinKey, chatId, prev, desired, persist, runPin, claims } = args
+  const now = args.now ?? Date.now
+
+  // Publish a leg's outcome into the single claim registry. `pinnedAt` is
+  // carried forward when a claim already exists so it keeps the FIRST-taken
+  // timestamp; clearing the claim drops it, so a re-pin ages fresh.
+  const commit = (next: PinState | null): void => {
+    if (next == null) {
+      claims.delete(pinKey)
+      return
+    }
+    const pinnedAt = claims.get(pinKey)?.pinnedAt ?? now()
+    claims.set(pinKey, { messageId: next.messageId, chatId, pinnedAt })
+  }
+
+  // One leg, with the persist ordering its action requires. Only a fresh `pin`
+  // opens the crash window that persist-BEFORE-pin closes; unpin / noop / re-pin
+  // of the same id clear or leave the row and are safe to persist after.
+  //
+  // The leg action is decided ONCE, below, and threaded through to both the
+  // persist-op mapping and the driver — the driver no longer re-derives it
+  // (#3831).
+  const runLeg = (
+    legAction: PinLegAction,
+    from: PinState | null,
+  ): Promise<PinState | null> => {
+    if (persist == null) return runPin(legAction, from)
+    const op: StatusPinPersistOp =
+      legAction.kind === 'pin'
+        ? { kind: 'pin', messageId: legAction.messageId }
+        : { kind: 'clear' }
+    return reconcileAndPersistStatusPin({
+      path: persist.path,
+      fs: persist.fs,
+      pinKey,
+      chatId,
+      op,
+      applyPin: () => runPin(legAction, from),
+      now: now(),
+    })
+  }
+
+  const action = decidePinAction(prev, desired)
+
+  // THE retarget expansion. This is the only copy in the codebase; the driver's
+  // parameter type (`PinLegAction`) cannot express a repin, so a second one
+  // cannot be written there again (#3831).
+  if (action.kind === 'repin') {
+    const afterUnpin = await runLeg(
+      { kind: 'unpin', messageId: action.unpinMessageId },
+      prev,
+    )
+    commit(afterUnpin)
+    // Never-confirmed unpin (#3664 Defect B): keep the retained claim, skip the
+    // pin leg. See the docblock.
+    if (afterUnpin != null) return
+    commit(await runLeg({ kind: 'pin', messageId: action.pinMessageId }, null))
+    return
+  }
+
+  commit(await runLeg(action, prev))
+}