switchroom 0.19.26 → 0.19.27

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/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

@@ -34,7 +34,7 @@
  *   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 `reconcilePin`, not re-invented here: a
+ * 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
@@ -42,24 +42,45 @@
  * 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 `runLeg` / `commit`.
+ * wiring of `runPin` / `commit`.
  */
 
-import type { DesiredPin, PinState } from '../status-pin.js'
+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'
 
-/** The three parallel in-memory maps the gateway keys by pinKey. */
-export interface StatusPinRegistries {
-  /** The claim: which message we believe is pinned for this key. */
-  state: Map<string, PinState>
-  /** Which chat that claim lives in (the `wk:` reaper needs it to unpin). */
-  chatIds: Map<string, string>
-  /** When the claim was FIRST taken — the reaper's TTL age. */
-  pinnedAt: Map<string, number>
+/**
+ * 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 {
@@ -72,48 +93,56 @@ export interface StatusPinReconcileArgs {
   /** Durable-store binding, or null when persistence is off (STATIC). */
   persist: { path: string; fs: StatusPinStoreFsSeam } | null
   /**
-   * Execute the real Telegram pin/unpin for one leg (the gateway binds
-   * `reconcilePin`). Must never throw — API errors are absorbed inside.
+   * Execute ONE already-decided leg against Telegram (the gateway binds
+   * `executePinLeg`). Must never throw — API errors are absorbed inside.
    */
-  runPin: (from: PinState | null, want: DesiredPin) => Promise<PinState | null>
-  registries: StatusPinRegistries
+  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 registries 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.
+ * 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, registries } = args
+  const { pinKey, chatId, prev, desired, persist, runPin, claims } = args
+  const now = args.now ?? Date.now
 
-  // Publish a leg's outcome. `pinnedAt` is set only when absent so it keeps the
-  // FIRST-taken timestamp; clearing the claim drops it, so a re-pin ages fresh.
+  // 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) {
-      registries.state.delete(pinKey)
-      registries.chatIds.delete(pinKey)
-      registries.pinnedAt.delete(pinKey)
+      claims.delete(pinKey)
       return
     }
-    registries.state.set(pinKey, next)
-    registries.chatIds.set(pinKey, chatId)
-    if (!registries.pinnedAt.has(pinKey)) registries.pinnedAt.set(pinKey, Date.now())
+    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.
-  const runLeg = (from: PinState | null, want: DesiredPin): Promise<PinState | null> => {
-    if (persist == null) return runPin(from, want)
-    const legAction = decidePinAction(from, want)
+  //
+  // 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 }
@@ -124,21 +153,28 @@ export async function runStatusPinReconcile(args: StatusPinReconcileArgs): Promi
       pinKey,
       chatId,
       op,
-      applyPin: () => runPin(from, want),
+      applyPin: () => runPin(legAction, from),
+      now: now(),
     })
   }
 
   const action = decidePinAction(prev, desired)
 
-  if (action.kind === 'repin' && desired.pinned) {
-    const afterUnpin = await runLeg(prev, { pinned: false })
+  // 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(null, desired))
+    commit(await runLeg({ kind: 'pin', messageId: action.pinMessageId }, null))
     return
   }
 
-  commit(await runLeg(prev, desired))
+  commit(await runLeg(action, prev))
 }

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

@@ -70,6 +70,27 @@ export interface PersistedStatusPin {
    *  unpin fails (flood-wait exhausted / transient 5xx); the row is retained
    *  for retry until BOOT_UNPIN_MAX_ATTEMPTS, then forfeited. Absent = 0. */
   attempts?: number
+  /**
+   * Wall-clock ms the pin was FIRST claimed for this key+message (#3810).
+   *
+   * Why the store needs it: the mid-session `wk:` reaper folds in rows that
+   * exist on disk but have NO in-memory claim (`storeOnlyWorkerPinCandidates`).
+   * The store used to persist no timestamp, so those candidates were stamped
+   * `pinnedAt = now` on every pass — deliberately, to avoid a spurious unpin of
+   * a pin whose real age was unknown, but with the side effect that the TTL
+   * gate could NEVER fire for a store orphan. Combined with a `wk:<agentId>`
+   * whose turnsDb row is gone (verdict `'unknown'`, never `'terminal'`), such a
+   * row was never mid-session reaped AT ALL — it waited for the next boot, the
+   * exact "stale pin glued to the top of the chat" failure the reaper exists to
+   * prevent.
+   *
+   * Recording the real claim time removes the guess: a store orphan now ages
+   * honestly and the ordinary TTL applies. Optional so a v1/v2 snapshot still
+   * loads; a row without it keeps the old conservative `now` stamp (terminal-
+   * only reaping), which self-clears within one restart since every write from
+   * this version onward carries the field.
+   */
+  pinnedAt?: number
 }
 
 /** How many boots may retry a failing boot-cleanup unpin before the row is
@@ -80,13 +101,18 @@ export interface PersistedStatusPin {
 export const BOOT_UNPIN_MAX_ATTEMPTS = 5
 
 /** Envelope version. v1 had no `pending` field; a v1 row loads as a confirmed
- *  pin (pending undefined). v2 adds the optional `pending` flag. Both load
- *  fail-open — an unknown/newer version yields []. */
+ *  pin (pending undefined). v2 adds the optional `pending` flag. v3 adds the
+ *  optional `pinnedAt` claim timestamp (#3810). All load fail-open — an
+ *  unknown/newer version yields []. Every field added since v1 is optional, so
+ *  the versions are mutually readable and a downgrade degrades rather than
+ *  breaks. */
 interface SnapshotEnvelope {
-  v: 1 | 2
+  v: 1 | 2 | 3
   pins: PersistedStatusPin[]
 }
 
+const SNAPSHOT_VERSIONS = new Set([1, 2, 3])
+
 function isPinRow(x: unknown): x is PersistedStatusPin {
   if (x == null || typeof x !== 'object') return false
   const o = x as Record<string, unknown>
@@ -98,7 +124,8 @@ function isPinRow(x: unknown): x is PersistedStatusPin {
     typeof o.messageId === 'number' &&
     (o.pending === undefined || typeof o.pending === 'boolean') &&
     (o.expiresAt === undefined || typeof o.expiresAt === 'number') &&
-    (o.attempts === undefined || typeof o.attempts === 'number')
+    (o.attempts === undefined || typeof o.attempts === 'number') &&
+    (o.pinnedAt === undefined || typeof o.pinnedAt === 'number')
   )
 }
 
@@ -127,7 +154,7 @@ export function loadStatusPins(
   }
   if (parsed == null || typeof parsed !== 'object') return []
   const env = parsed as Record<string, unknown>
-  if ((env.v !== 1 && env.v !== 2) || !Array.isArray(env.pins)) return []
+  if (typeof env.v !== 'number' || !SNAPSHOT_VERSIONS.has(env.v) || !Array.isArray(env.pins)) return []
   return env.pins.filter(isPinRow)
 }
 
@@ -143,7 +170,7 @@ export function persistStatusPins(
   snapshot: readonly PersistedStatusPin[],
   log: (line: string) => void = (l) => process.stderr.write(l),
 ): void {
-  const env: SnapshotEnvelope = { v: 2, pins: [...snapshot] }
+  const env: SnapshotEnvelope = { v: 3, pins: [...snapshot] }
   const tmp = path + '.tmp'
   try {
     fs.writeFileSync(tmp, JSON.stringify(env))
@@ -427,16 +454,34 @@ export function reconcileAndPersistStatusPin(args: {
   /** Execute the real pin/unpin; returns the confirmed message id (pin) or
    *  null (cleared). Must never throw — API errors are swallowed inside. */
   applyPin: () => Promise<{ messageId: number } | null>
+  /** Clock for the `pinnedAt` stamp (#3810). Defaults to wall clock. */
+  now?: number
   log?: (line: string) => void
 }): Promise<{ messageId: number } | null> {
   const { path, fs, pinKey, chatId, op } = args
   const log = args.log ?? ((l: string) => process.stderr.write(l))
+  const now = args.now ?? Date.now()
+
+  /**
+   * The claim age to persist for `messageId`. Carried forward from the row
+   * already on disk when it names the SAME message (a steady-state re-write
+   * must not reset the age and hand a stale pin a fresh TTL lease); stamped
+   * `now` for a genuinely new pin. Mirrors the in-memory `pinnedAt` rule in
+   * `status-pin-retarget.ts` so disk and memory can't disagree about age.
+   */
+  const claimAge = (messageId: number): number => {
+    const existing = loadStatusPins(path, fs).find((p) => p.pinKey === pinKey)
+    return existing?.messageId === messageId && existing.pinnedAt != null
+      ? existing.pinnedAt
+      : now
+  }
 
   // Hold the per-path lock across the WHOLE op so no other writer (a banner
   // persist, or another key's reconcile) can rebuild/overwrite the file during
   // the applyPin await window and drop this key's pending/confirmed row.
   return withStoreLock(path, async () => {
     if (op.kind === 'pin') {
+      const pinnedAt = claimAge(op.messageId)
       // Persist INTENT first, marked pending — BEFORE the pin API call. If we
       // crash after the pin lands but before the confirm rewrite, this pending
       // record is what boot cleanup uses to unpin the orphan.
@@ -444,7 +489,7 @@ export function reconcileAndPersistStatusPin(args: {
         path,
         fs,
         pinKey,
-        { pinKey, chatId, messageId: op.messageId, pending: true },
+        { pinKey, chatId, messageId: op.messageId, pending: true, pinnedAt },
         log,
       )
       const next = await args.applyPin()
@@ -459,7 +504,7 @@ export function reconcileAndPersistStatusPin(args: {
         path,
         fs,
         pinKey,
-        { pinKey, chatId, messageId: next.messageId },
+        { pinKey, chatId, messageId: next.messageId, pinnedAt: claimAge(next.messageId) },
         log,
       )
       return next
@@ -488,11 +533,15 @@ export function reconcileAndPersistStatusPin(args: {
     if (next == null) {
       applyStatusPinRow(path, fs, pinKey, null, log)
     } else {
+      // Steady-state noop-clear (the worker feed calls syncPin on every edit):
+      // the pin is still up, so the row is preserved AND so is its original
+      // claim age — re-stamping it here would hand a genuinely old pin a fresh
+      // TTL lease on every feed edit and make it immortal (#3810).
       applyStatusPinRow(
         path,
         fs,
         pinKey,
-        { pinKey, chatId, messageId: next.messageId },
+        { pinKey, chatId, messageId: next.messageId, pinnedAt: claimAge(next.messageId) },
         log,
       )
     }