switchroom 0.19.25 → 0.19.26

package/telegram-plugin/gateway/gateway.ts

@@ -197,7 +197,7 @@ import {
 import type { WebhookGatewayRecord } from '../../src/web/webhook-gateway-record.js'
 import { reconcilePin, type PinBotApi } from '../status-pin-driver.js'
 import type { PinState, DesiredPin } from '../status-pin.js'
-import { decidePinAction, PinRightsCache } from '../status-pin.js'
+import { PinRightsCache } from '../status-pin.js'
 import { formatTurnLifecycle, detectStatusSurfaceDegraded } from './status-surface-log.js'
 import { parseSourceMessageId } from './source-message-id.js'
 import {
@@ -637,6 +637,9 @@ import type { HostdRequest, HostdResponse } from '../../src/host-control/protoco
 import type { AgentAudit } from '../welcome-text.js'
 import { shouldSweepChatAtBoot } from './boot-sweep-filter.js'
 import { createBootSweepGate, runBootPinSweepSteps } from './boot-sweep-gate.js'
+import { runStatusPinReconcile } from './status-pin-retarget.js'
+import { createPeriodicSweepGuard } from './periodic-sweep-guard.js'
+import { withDeadline } from './with-deadline.js'
 import { createStatusPinApi, type PinCapableBot, type RobustApiSeam } from './status-pin-api.js'
 import {
   createDmPinSweeper,
@@ -666,11 +669,9 @@ import { buildCapturedDeliverySnapshot, createCapturedResumeDispatcher } from '.
 import {
   loadStatusPins,
   mutateStatusPinRow,
-  reconcileAndPersistStatusPin,
   runStatusPinBootCleanup,
   withPinReconcileLock,
   type PersistedStatusPin,
-  type StatusPinPersistOp,
 } from './status-pin-store.js'
 import {
   loadActivityCards,
@@ -9069,8 +9070,20 @@ async function runMidSessionCardReaper(): Promise<void> {
   }
 }
 
+// Single-flight: a pass awaits Telegram calls that can park behind a flood-wait
+// for longer than the interval, so ticks fanned out. See periodic-sweep-guard.ts.
+const midSessionReaperGuard = createPeriodicSweepGuard({
+  run: runMidSessionCardReaper,
+  onSkip: () => process.stderr.write(
+    'telegram gateway: mid-session reaper tick skipped — previous pass still running\n',
+  ),
+  onError: (err) => process.stderr.write(
+    `telegram gateway: mid-session reaper pass threw: ${(err as Error).message}\n`,
+  ),
+})
+
 const midSessionCardReaper = isGatewayMain ? setInterval(() => {  // #2996 P0c gate
-  void runMidSessionCardReaper()
+  void midSessionReaperGuard.tick()
 }, MID_SESSION_CARD_REAPER_INTERVAL_MS) : undefined
 midSessionCardReaper?.unref()
 
@@ -9131,12 +9144,12 @@ async function reconcileStatusPinInner(
   // older duplicate-pin concern (two edits both reading prev=null).
   const prev = statusPinState.get(pinKey) ?? null
 
-  const runReconcile = () =>
+  const runReconcileFrom = (from: PinState | null, want: DesiredPin) =>
     reconcilePin({
       api: statusPinApi(),
       chatId,
-      prevState: prev,
-      desired,
+      prevState: from,
+      desired: want,
       rightsCache: statusPinRightsCache,
       onPinRightsDisabled: (chat) => {
         // Logged ONCE per chat per process (#3024). Every subsequent auto-pin
@@ -9155,53 +9168,23 @@ async function reconcileStatusPinInner(
       },
     })
 
-  // Classify the action so we persist INTENT before the pin API call. Only a
-  // fresh `pin` of a message that isn't already our claim opens the leak window
-  // (the API call actually pins something new); everything else (unpin, noop,
-  // re-pin of the same id) clears / leaves the record and is safe to persist
-  // after. See reconcileAndPersistStatusPin for the ordering rationale.
-  const action = decidePinAction(prev, desired)
-  const op: StatusPinPersistOp =
-    action.kind === 'pin'
-      ? { kind: 'pin', messageId: action.messageId }
-      : { kind: 'clear' }
-
-  if (!statusPinPersistEnabled) {
-    // Persistence off (STATIC / feature-off): just reconcile + update Maps.
-    const next = await runReconcile()
-    if (next == null) {
-      statusPinState.delete(pinKey)
-      statusPinChatIds.delete(pinKey)
-      statusPinPinnedAt.delete(pinKey)
-    } else {
-      statusPinState.set(pinKey, next)
-      statusPinChatIds.set(pinKey, chatId)
-      if (!statusPinPinnedAt.has(pinKey)) statusPinPinnedAt.set(pinKey, Date.now())
-    }
-    return
-  }
-
-  // Persist-BEFORE-pin ordering lives in reconcileAndPersistStatusPin: for a
-  // pin it writes a `pending` record first, then confirms it after the API call
-  // lands (or drops it on failure). A crash in the window leaves a pending
-  // record boot cleanup will unpin. In-memory Maps are updated from the result.
-  const next = await reconcileAndPersistStatusPin({
-    path: STATUS_PIN_STORE_PATH,
-    fs: statusPinStoreFs,
+  // Persist ordering + the RETARGET two-leg expansion: status-pin-retarget.ts.
+  await runStatusPinReconcile({
     pinKey,
     chatId,
-    op,
-    applyPin: runReconcile,
+    prev,
+    desired,
+    // persist:null ⇒ no durable row (STATIC / feature-off).
+    persist: statusPinPersistEnabled
+      ? { path: STATUS_PIN_STORE_PATH, fs: statusPinStoreFs }
+      : null,
+    runPin: runReconcileFrom,
+    registries: {
+      state: statusPinState,
+      chatIds: statusPinChatIds,
+      pinnedAt: statusPinPinnedAt,
+    },
   })
-  if (next == null) {
-    statusPinState.delete(pinKey)
-    statusPinChatIds.delete(pinKey)
-    statusPinPinnedAt.delete(pinKey)
-  } else {
-    statusPinState.set(pinKey, next)
-    statusPinChatIds.set(pinKey, chatId)
-    if (!statusPinPinnedAt.has(pinKey)) statusPinPinnedAt.set(pinKey, Date.now())
-  }
 }
 
 // #3207: the per-worker `reconcileWorkerPin(agentId, …)` (keyed `wk:<agentId>`)
@@ -18053,7 +18036,7 @@ function broadcastTierNotice(markdown: string): void {
  *     the user must re-issue `/model <premium>`, which the notice says plainly.
  *   - Effort is NATIVE: no `.session-effort` carrier is written, so the restart
  *     sheds any live /effort override and the downgraded default boots at the
- *     configured `thinking_effort` (the fleet `low` pin, #1978).
+ *     configured `thinking_effort` (#1978 / thinking-effort-risk.ts).
  *   - Loop-bounded by the NATURAL on-default guard: after the downgrade boot the
  *     session runs the configured default (override gone), so a re-entry returns
  *     `skip` ('on-default') and never re-downgrades — even if the default is
@@ -22750,6 +22733,24 @@ async function shutdown(signal: string): Promise<void> {
     agentName,
   })
 
+  // Status-pin: unpin everything we own before we exit. `sweepBeforeSelfRestart`
+  // covered the gateway's OWN restart verbs, but SIGTERM/SIGINT — `docker
+  // restart`, a compose bounce, a host reboot: the common path — reached
+  // `process.exit(0)` with every live pin still pinned, leaving it at the top of
+  // the chat until the NEXT boot's cleanup won the mutex and built a bot
+  // (empirically: overlord logged `cleared 1/1 orphaned pin(s) from a prior
+  // session` on a routine 2026-07-27 restart). Runs after the drain (no live
+  // turn to race) and before `bot.api` goes away — `bot.stop()` only stops
+  // polling. Deadline-bounded on purpose: a flood-wait-parked unpin must not
+  // push shutdown into the `forceExitTimer` path, which skips the lock release.
+  try {
+    await withDeadline(unpinAllStatusPins(), 5_000, 'status-pin shutdown sweep timed out')
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: shutdown status-pin sweep incomplete: ${(err as Error).message}\n`,
+    )
+  }
+
   // Now finish the cleanup the drain didn't touch.
   inboundCoalescer.reset()
   pendingReauthFlows.clear()

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/status-pin-retarget.ts

@@ -0,0 +1,144 @@
+/**
+ * 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 `reconcilePin`, 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.
+ *
+ * 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`.
+ */
+
+import type { DesiredPin, 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>
+}
+
+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 the real Telegram pin/unpin for one leg (the gateway binds
+   * `reconcilePin`). Must never throw — API errors are absorbed inside.
+   */
+  runPin: (from: PinState | null, want: DesiredPin) => Promise<PinState | null>
+  registries: StatusPinRegistries
+}
+
+/**
+ * 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.
+ *
+ * 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
+
+  // 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.
+  const commit = (next: PinState | null): void => {
+    if (next == null) {
+      registries.state.delete(pinKey)
+      registries.chatIds.delete(pinKey)
+      registries.pinnedAt.delete(pinKey)
+      return
+    }
+    registries.state.set(pinKey, next)
+    registries.chatIds.set(pinKey, chatId)
+    if (!registries.pinnedAt.has(pinKey)) registries.pinnedAt.set(pinKey, Date.now())
+  }
+
+  // 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)
+    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(from, want),
+    })
+  }
+
+  const action = decidePinAction(prev, desired)
+
+  if (action.kind === 'repin' && desired.pinned) {
+    const afterUnpin = await runLeg(prev, { pinned: false })
+    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))
+    return
+  }
+
+  commit(await runLeg(prev, desired))
+}

package/telegram-plugin/status-no-truncate.ts

@@ -124,3 +124,52 @@ export const NESTED_PREFIX = '   ↳ '
  * assertion is what let #3662 ship green and inert.
  */
 export const WORKER_STEP_INDENT = '\u2800\u2800\u2800'
+
+/**
+ * Line-1 prefix that marks a card as structurally SUBORDINATE to the \ud83e\udd16 agent
+ * card (#3820). Worker cards carry it; the agent card never does.
+ *
+ * `\u2514\u2500` (U+2514 BOX DRAWINGS LIGHT UP AND RIGHT + U+2500 BOX DRAWINGS LIGHT
+ * HORIZONTAL) is ordinary ink to Telegram's server-side GFM parser: it is not
+ * a line-start block trigger (`#`, `>`, `-`/`+`/`*`, `N.` \u2014 see
+ * render/line-start-guard.ts for the full trigger set), so it can neither be
+ * promoted to a list/quote/heading nor left-trimmed the way a leading
+ * whitespace run is (the #3662 failure documented on WORKER_STEP_INDENT).
+ *
+ * LENGTH INVARIANT: exactly the same length as `SUBORDINATE_LINE_INDENT`, so
+ * the char-budget arithmetic in `fitCardToBudget` charges one flat per-line
+ * cost instead of special-casing line 1. `status-accent.test.ts` asserts it.
+ */
+export const SUBORDINATE_HEADER_PREFIX = '\u2514\u2500 '
+
+/**
+ * Left indent applied to EVERY line of a subordinate (worker) card after
+ * line 1 \u2014 the whole card block sits one level in from the agent card's left
+ * margin, so "parent vs child" is readable from the block's SHAPE at a glance
+ * on a phone, not from reading its label (#3820).
+ *
+ * Same U+2800 run as `WORKER_STEP_INDENT` and for the same live-verified
+ * reason (category So, not Zs \u2192 survives Telegram's inline left-trim; ASCII
+ * spaces and U+00A0 both render flat). Aliased rather than re-declared so the
+ * two indents can never drift to different glyphs.
+ *
+ * On the combined (2+ worker) card this composes with `WORKER_STEP_INDENT`:
+ * chrome / row headers land at one level, their steps at two.
+ */
+export const SUBORDINATE_LINE_INDENT = WORKER_STEP_INDENT
+
+/**
+ * Apply subordinate-card nesting to a card's pre-rendered lines: line 1 gets
+ * `SUBORDINATE_HEADER_PREFIX`, every later line gets `SUBORDINATE_LINE_INDENT`.
+ *
+ * Prefixes go OUTSIDE the markdown spans (lines arrive already wrapped in
+ * `**` / `_` / `~~`), exactly like `renderStepFeed`'s `indent` parameter, so a
+ * prefix can never land inside an emphasis run and break it.
+ *
+ * Pure; returns a new array. Empty in \u2192 empty out.
+ */
+export function nestSubordinateCardLines(lines: string[]): string[] {
+  return lines.map((line, i) =>
+    i === 0 ? `${SUBORDINATE_HEADER_PREFIX}${line}` : `${SUBORDINATE_LINE_INDENT}${line}`,
+  )
+}

package/telegram-plugin/status-pin-driver.ts

@@ -86,6 +86,12 @@ export interface ReconcilePinArgs {
  *              success and on a TERMINAL failure (never leave state stuck
  *              pinned). A never-confirmed failure returns prevState so the
  *              still-pinned message keeps a record to retry from (#3664).
+ *   - `repin`: the wanted message CHANGED — unpins the stale claim then pins
+ *              the new message, both in this one call, returning the new
+ *              claim. A never-confirmed unpin aborts the pin leg and retains
+ *              the old claim (the old message is still up and must keep a
+ *              record). Single-shot callers depend on this: they never
+ *              reconcile the key a second time.
  *   - `noop` : returns prevState unchanged.
  */
 export async function reconcilePin(
@@ -95,6 +101,28 @@ export async function reconcilePin(
 
   if (action.kind === 'noop') return args.prevState
 
+  if (action.kind === 'repin') {
+    // RETARGET: unpin the stale claim, then pin the new message — BOTH legs in
+    // this one call. Callers that reconcile a key exactly once (the foreground
+    // activity card) have no "next reconcile" to finish the job, so splitting
+    // it left nothing pinned. See the `repin` docblock in status-pin.ts.
+    const afterUnpin = await reconcilePin({
+      ...args,
+      desired: { pinned: false },
+    })
+    // A non-null result here 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 one now would leave two pins with
+    // a record of only one. Keep the retained claim and let the next reconcile
+    // / the mid-session reaper / the boot sweep retry.
+    if (afterUnpin != null) return afterUnpin
+    return reconcilePin({
+      ...args,
+      prevState: null,
+      desired: { pinned: true, messageId: action.pinMessageId },
+    })
+  }
+
   if (action.kind === 'unpin') {
     // Skip the unpin API call in a chat the bot can't manage pins in — the
     // call would fail with the same rights 400 and spam the log. The claim is

package/telegram-plugin/status-pin.ts

@@ -48,6 +48,29 @@ export type PinAction =
    *  or a TERMINAL failure; a never-confirmed failure keeps the claim so the
    *  still-pinned message can be retried (`isUnpinTerminalError`, #3664). */
   | { kind: 'unpin'; messageId: number }
+  /**
+   * RETARGET — the caller still wants something pinned for this key, but a
+   * DIFFERENT message than the one we claim (the surface was re-posted: an
+   * ack-first activity-card reopen, a worker-feed group-message rotation).
+   *
+   * This is ONE action, not two reconciles. It used to be reported as a plain
+   * `unpin`, on the assumption that "a subsequent desired-pin re-pins the new
+   * one on the next reconcile". That assumption holds only for callers that
+   * RE-DRIVE the reconcile (the worker feed's `syncPin`, called on every
+   * steady-state edit). The foreground activity card does not: it reconciles
+   * exactly once, when a card OPENs (`narrative-lane.ts` — the `else` branch
+   * only EDITs and never touches the pin). So a mid-turn card reopen (the
+   * ack-first path in `feed-reopen-gate.ts`, which nulls `activityMessageId`
+   * so a fresh card opens) unpinned the old card and left the NEW one
+   * unpinned for the rest of the turn — the pin vanished exactly when the
+   * turn still needed it.
+   *
+   * Executors MUST complete both legs: unpin `unpinMessageId`, then pin
+   * `pinMessageId`. `reconcilePin` owns the failure semantics (a
+   * never-confirmed unpin retains the OLD claim and skips the pin, so the last
+   * record of a provably-still-pinned message is never lost).
+   */
+  | { kind: 'repin'; unpinMessageId: number; pinMessageId: number }
 
 /**
  * Decide the single pin action for a key given the previously-claimed
@@ -71,10 +94,16 @@ export function decidePinAction(
   if (prev.messageId === desired.messageId) {
     return { kind: 'noop', reason: 'already pinned this message' }
   }
-  // The message we want pinned changed (the feed re-posted after a stale
-  // edit dropped its id). Unpin the old claim; a subsequent desired-pin
-  // re-pins the new one on the next reconcile.
-  return { kind: 'unpin', messageId: prev.messageId }
+  // The message we want pinned changed (the surface was re-posted). Report a
+  // RETARGET, not a bare unpin: the executor must drop the stale claim AND pin
+  // the new message in the same reconcile. Relying on "the next reconcile" to
+  // pin left every single-shot caller (the foreground activity card) with
+  // nothing pinned — see the `repin` docblock above.
+  return {
+    kind: 'repin',
+    unpinMessageId: prev.messageId,
+    pinMessageId: desired.messageId,
+  }
 }
 
 /** Extract a lowercased human description from any thrown value, preferring