switchroom 0.20.9 → 0.20.11

package/telegram-plugin/gateway/stale-pin-sweep.test.ts

@@ -22,7 +22,6 @@ import {
   createStalePinSweeper,
   isNothingToUnpinError,
   isPeerFloodError,
-  isPinRightsError,
   mayUnpinAllForumTopic,
   retryAfterSeconds,
   unexpiredStoreRepinIds,
@@ -38,6 +37,10 @@ import {
   type SweepCursor,
   type SweepStoreFsSeam,
 } from './stale-pin-sweep-store.js'
+// The sweep now imports its rights detector from the single source of truth
+// (status-pin.ts) — no second copy. The negative cache it shares with the live
+// pin path is that module's `PinRightsCache` (D3).
+import { isPinRightsError, PinRightsCache } from '../status-pin.js'
 
 // Synthetic ids (check-no-pii-secrets): DMs positive, groups negative.
 const DM = '900000001'
@@ -84,7 +87,10 @@ interface FakeOpts {
    * call-counted `popped` and an observation-counted `popped` disagree.
    */
   unpinAllTopicRemoves?: number[]
-  canPin?: boolean
+  /** Errors to throw from `unpinChatMessage`, consumed in order (null = normal).
+   *  The sweep classifies pin rights REACTIVELY from a real Telegram 400 here —
+   *  there is no proactive precheck to model. */
+  unpinErrors?: (unknown | null)[]
   /** Throws from `getChat`, consumed in order (null = normal read). */
   getChatErrors?: (unknown | null)[]
 }
@@ -93,6 +99,7 @@ function fakeChat(o: FakeOpts) {
   const stack = [...o.stack]
   const calls: string[] = []
   const pinErrors = [...(o.pinErrors ?? [])]
+  const unpinErrors = [...(o.unpinErrors ?? [])]
   const unpinAllErrors = [...(o.unpinAllErrors ?? [])]
   const getChatErrors = [...(o.getChatErrors ?? [])]
   return {
@@ -115,6 +122,10 @@ function fakeChat(o: FakeOpts) {
     },
     unpin: async (_chatId: string, messageId: number) => {
       calls.push(`unpin:${messageId}`)
+      // A real Telegram rejection (e.g. `400 not enough rights`) is injected
+      // here so the sweep's REACTIVE rights classifier is what gets exercised.
+      const err = unpinErrors.shift()
+      if (err != null) throw err
       // ALWAYS resolves ok:true — the whole point.
       if (o.unpinIsSilentNoop === true) return { ok: true }
       const at = stack.indexOf(messageId)
@@ -135,10 +146,6 @@ function fakeChat(o: FakeOpts) {
       }
       return { ok: true }
     },
-    canPinInChat: async () => {
-      calls.push('getChatMember')
-      return o.canPin !== false
-    },
   }
 }
 
@@ -165,6 +172,9 @@ function harness(
     allowUnpinAllForumTopic?: boolean
     /** Ids the gateway is on record as having pinned (the group drain's list). */
     recordedPinIds?: number[]
+    /** D3: shared per-process pin-rights negative cache seam. */
+    rightsBlocked?: (chatId: string) => boolean
+    recordRightsBlock?: (chatId: string) => void
   },
 ): Harness {
   const fake = fakeChat(o)
@@ -183,10 +193,11 @@ function harness(
     pinSilent: costed(fake.pinSilent),
     unpin: costed(fake.unpin),
     unpinAllForumTopicMessages: costed(fake.unpinAllForumTopicMessages),
-    canPinInChat: costed(fake.canPinInChat),
     protectedMessageIds: () => o.protectedMessageIds ?? [],
     recordedPinIds: () => o.recordedPinIds ?? [],
     eligible: () => o.eligible !== false,
+    rightsBlocked: o.rightsBlocked,
+    recordRightsBlock: o.recordRightsBlock,
     sleep: async (ms) => {
       sleeps.push(ms)
       if (o.clockAdvances !== false) clock += ms
@@ -552,8 +563,22 @@ describe('stale-pin sweep — forum topics', () => {
 // ─── group safety: rights + service-message spam ─────────────────────────────
 
 describe('stale-pin sweep — group safety', () => {
-  it('skips a group without pin rights WITHOUT writing anything', async () => {
-    const h = harness({ stack: [151, 152], canPin: false })
+  // The honest Telegram rejection a rights-less bot gets from EVERY pin verb.
+  const RIGHTS_400 = {
+    error_code: 400,
+    description: 'Bad Request: not enough rights to manage pinned messages in the chat',
+  }
+
+  it('ATTEMPTS the drain (no proactive precheck) and classifies a real 400 as rights', async () => {
+    // The pre-fix bug: a proactive getChatMember precheck against the wrapped
+    // (botInfo-less) bot always returned false, so a group forfeited WITHOUT a
+    // single unpin ever going out. The sweep must instead ATTEMPT the unpin and
+    // read Telegram's honest 400 — so `unpin:151` MUST appear in the call log.
+    const h = harness({
+      stack: [151, 152],
+      recordedPinIds: [151],
+      unpinErrors: [RIGHTS_400],
+    })
     const res = await createStalePinSweeper(h.deps).sweepTarget({
       chatId: GROUP,
       threadId: 5,
@@ -561,22 +586,31 @@ describe('stale-pin sweep — group safety', () => {
     })
 
     expect(res.status).toBe('skipped-no-rights')
-    expect(h.fake.calls).toEqual(['getChatMember']) // the precheck and nothing else
-    expect(h.fake.stack).toEqual([151, 152])
+    expect(h.fake.calls).toContain('unpin:151') // the drain was ATTEMPTED
+    expect(h.fake.stack).toEqual([151, 152]) // the rejected unpin popped nothing
   })
 
-  it('treats a throwing rights check as "no rights"', async () => {
-    const h = harness({ stack: [161] })
-    h.deps.canPinInChat = async () => {
-      throw new Error('Bad Request: chat not found')
+  it('increments attempts and eventually FORFEITS a rights-less group via the reactive path (no infinite retry)', async () => {
+    const fs = memFs()
+    const path = '/state/stale-pin-sweep.json'
+    // Every boot: a fresh process attempts the recorded unpin, Telegram answers
+    // 400 not enough rights, the sweep records skipped-no-rights and bumps
+    // attempts. After SWEEP_MAX_ATTEMPTS boots the cursor forfeits and stops
+    // re-burning the pin-op budget — the bounded reactive path, no precheck.
+    let last = ''
+    for (let boot = 0; boot < SWEEP_MAX_ATTEMPTS + 1; boot++) {
+      const chat = fakeChat({ stack: [161], unpinErrors: [RIGHTS_400] })
+      const res = await sweeperOver(fs, path, chat, { recordedPinIds: [161] }).sweepTarget({
+        chatId: GROUP,
+      })
+      last = res.status
     }
-    const res = await createStalePinSweeper(h.deps).sweepTarget({
-      chatId: GROUP,
-      threadId: 5,
-      isForum: true,
-    })
-    expect(res.status).toBe('skipped-no-rights')
-    expect(h.fake.calls).toEqual([])
+    // The final boot is past the attempt budget: it forfeits instead of
+    // attempting yet another doomed unpin.
+    expect(last).toBe('forfeited')
+    const cursor = loadSweepCursors(path, fs).find((c) => c.chatId === GROUP)
+    expect(cursor?.attempts).toBe(SWEEP_MAX_ATTEMPTS)
+    expect(cursor?.done).toBe(false)
   })
 
   it('NEVER pins in a group — a pin is the only op that emits a service message', async () => {
@@ -623,10 +657,74 @@ describe('stale-pin sweep — group safety', () => {
     expect(h.cursors().find((c) => c.chatId === GROUP)?.done).toBe(false)
   })
 
-  it('runs a DM sweep with NO rights precheck (getChatMember is meaningless there)', async () => {
+  it('runs a DM sweep straight into a drain (no rights gating whatsoever)', async () => {
     const h = harness({ stack: [181] })
-    await createStalePinSweeper(h.deps).sweepTarget({ chatId: DM })
+    const res = await createStalePinSweeper(h.deps).sweepTarget({ chatId: DM })
+    // No proactive precheck anywhere: the DM goes straight to the repin+unpin
+    // drain and clears the orphan.
     expect(h.fake.calls).not.toContain('getChatMember')
+    expect(res.status).toBe('drained')
+    expect(h.fake.stack).toEqual([])
+  })
+})
+
+// ─── D3: shared per-process pin-rights negative cache ─────────────────────────
+
+describe('stale-pin sweep — shared PinRightsCache (D3)', () => {
+  const RIGHTS_400 = {
+    error_code: 400,
+    description: 'Bad Request: not enough rights to manage pinned messages in the chat',
+  }
+
+  it('SKIPS a group the live path already blocked, without issuing any unpin', async () => {
+    const cache = new PinRightsCache()
+    cache.block(GROUP) // the live status-pin path already proved this chat rights-less
+    const h = harness({
+      stack: [201],
+      recordedPinIds: [201],
+      rightsBlocked: (c) => cache.isBlocked(c),
+      recordRightsBlock: (c) => {
+        cache.block(c)
+      },
+    })
+    const res = await createStalePinSweeper(h.deps).sweepTarget({ chatId: GROUP })
+
+    expect(res.status).toBe('skipped-no-rights')
+    // No doomed traffic: the shared cache short-circuited BEFORE any unpin.
+    expect(h.fake.calls.filter((c) => c.startsWith('unpin'))).toEqual([])
+  })
+
+  it('FEEDS the cache from its own reactive rights discovery so the live path skips too', async () => {
+    const cache = new PinRightsCache()
+    const h = harness({
+      stack: [202],
+      recordedPinIds: [202],
+      unpinErrors: [RIGHTS_400],
+      rightsBlocked: (c) => cache.isBlocked(c),
+      recordRightsBlock: (c) => {
+        cache.block(c)
+      },
+    })
+    const res = await createStalePinSweeper(h.deps).sweepTarget({ chatId: GROUP })
+
+    expect(res.status).toBe('skipped-no-rights')
+    expect(h.fake.calls).toContain('unpin:202') // it ATTEMPTED before classifying
+    expect(cache.isBlocked(GROUP)).toBe(true) // and recorded the block for the live path
+  })
+
+  it('does NOT skip a DM even when its chat id is in the cache (DMs are never rights-gated)', async () => {
+    const cache = new PinRightsCache()
+    cache.block(DM)
+    const h = harness({
+      stack: [203],
+      rightsBlocked: (c) => cache.isBlocked(c),
+      recordRightsBlock: (c) => {
+        cache.block(c)
+      },
+    })
+    const res = await createStalePinSweeper(h.deps).sweepTarget({ chatId: DM })
+    expect(res.status).toBe('drained')
+    expect(h.fake.stack).toEqual([])
   })
 })
 
@@ -945,7 +1043,6 @@ function sweeperOver(
     pinSilent: fake.pinSilent,
     unpin: fake.unpin,
     unpinAllForumTopicMessages: fake.unpinAllForumTopicMessages,
-    canPinInChat: fake.canPinInChat,
     protectedMessageIds: () => [],
     recordedPinIds: () => opts.recordedPinIds ?? [],
     eligible: () => true,
@@ -1045,7 +1142,7 @@ describe('stale-pin sweep — re-drain after the boot-seed prune (#3953)', () =>
     const path = '/state/stale-pin-sweep.json'
 
     // Session 1: the one recorded orphan is reaped, obligation discharged.
-    const s1 = await sweeperOver(fs, path, fakeChat({ stack: [77], canPin: true }), {
+    const s1 = await sweeperOver(fs, path, fakeChat({ stack: [77] }), {
       recordedPinIds: [77],
     }).sweepTarget({ chatId: GROUP })
     expect(s1.status).toBe('drained')

package/telegram-plugin/gateway/stale-pin-sweep.ts

@@ -132,6 +132,12 @@ import {
   upsertSweepCursor,
   SWEEP_MAX_ATTEMPTS,
 } from './stale-pin-sweep-store.js'
+// The single source of truth for the pin-rights concept. The sweep classifies
+// a rights failure REACTIVELY — it attempts the unpin and reads Telegram's
+// honest `400 "not enough rights"` — using the same detector the live status-pin
+// path uses, so the two paths can never disagree on what "no pin rights" means
+// (this file must stay Telegram-import-free; status-pin.ts is dependency-free).
+import { isPinRightsError } from '../status-pin.js'
 
 // ─── Rate gates (operator-mandated; do not inline these numbers) ─────────────
 
@@ -400,17 +406,6 @@ export function isPeerFloodError(err: unknown): boolean {
   return description(err).includes('peer_flood')
 }
 
-/**
- * The bot is not allowed to manage pins here. Verified live: a bot without
- * `can_pin_messages` gets `400 "not enough rights to manage pinned messages in
- * the chat"` from EVERY pin method — an honest, stable rejection, unlike the
- * silent-success unpin. So a rights failure is terminal for the chat, not a
- * retry.
- */
-export function isPinRightsError(err: unknown): boolean {
-  return description(err).includes('not enough rights')
-}
-
 /**
  * `unpinChatMessage` with NO `message_id` on an EMPTY stack answers `400
  * "message to unpin not found"`. That is a real, positive termination signal —
@@ -566,10 +561,18 @@ export interface StalePinSweepDeps {
   /** `unpinAllForumTopicMessages(chat, thread)` — the one topic-scoped verb. */
   unpinAllForumTopicMessages: (chatId: string, threadId: number) => Promise<unknown>
   /**
-   * `getChatMember(chat, self)` folded to "is administrator AND can_pin_messages".
-   * Consulted BEFORE any write in a group. A throw is treated as "no rights".
+   * The SHARED per-process pin-rights negative cache (status-pin.ts
+   * `PinRightsCache`), so the sweep and the live status-pin path agree on which
+   * chats are rights-less. `rightsBlocked` is TRUE only when a REAL Telegram
+   * `400 "not enough rights"` was already observed (by the live pin path or an
+   * earlier sweep) — never a proactive network probe — so consulting it cannot
+   * resurrect the deleted `getChatMember` precheck. When it returns true the
+   * sweep skips the doomed group drain; `recordRightsBlock` feeds the cache from
+   * the sweep's OWN reactive rights discoveries. Both optional: undefined ⇒ the
+   * sweep relies purely on its reactive classifier.
    */
-  canPinInChat: (chatId: string) => Promise<boolean>
+  rightsBlocked?: (chatId: string) => boolean
+  recordRightsBlock?: (chatId: string) => void
   /**
    * Message ids in this chat that must be RE-PINNED once the drain finishes:
    * live in-memory claims plus the deliberately-retained store rows (unexpired
@@ -1126,24 +1129,32 @@ export function createStalePinSweeper(deps: StalePinSweepDeps): StalePinSweeper
       }
     }
 
-    // RIGHTS PRECHECK, before ANY write, in every group. A bot without
-    // can_pin_messages is honestly rejected by Telegram, but burning a rejected
-    // write per orphan against the flood ledger is pointless. DMs need no
-    // precheck — getChatMember is not meaningful there.
-    if (kind !== 'dm') {
-      let allowed = false
-      try {
-        allowed = await deps.canPinInChat(target.chatId)
-      } catch {
-        allowed = false
-      }
-      if (!allowed) {
-        cursor.attempts++
-        cursor.lastStatus = 'skipped-no-rights'
-        cursor.updatedAt = deps.now()
-        commit(cursor)
-        return { status: 'skipped-no-rights', popped: 0, issued: 0 }
-      }
+    // NO proactive rights precheck. A `getChatMember`-based precheck was
+    // DELETED (see below): the sweep runs against the chat-lock-wrapped bot,
+    // which carries only `.api` and no `.botInfo`, so `self` was always null,
+    // the precheck always returned false, and every group target forfeited at
+    // SWEEP_MAX_ATTEMPTS without a single unpin ever going out
+    // (`getChatMember` appeared 0× in a 35MB live gateway log). Rights are now
+    // classified REACTIVELY and only from a real Telegram `400 "not enough
+    // rights"`: each drain primitive attempts the unpin and folds that error to
+    // `{ kind: 'rights' }` via `classify`, returning `skipped-no-rights`. The
+    // attempt is counted below BEFORE the drain, so a genuinely rights-less
+    // chat still increments `attempts` on every boot and forfeits at
+    // SWEEP_MAX_ATTEMPTS — no infinite retry — while a chat the bot CAN pin in
+    // is no longer wrongly skipped.
+    //
+    // Same-process negative cache (D3): if the LIVE status-pin path (or an
+    // earlier sweep) already observed a REAL `400 not enough rights` for this
+    // chat, skip the doomed group drain rather than re-attempting it. This is
+    // NOT a network probe — it is fed only by observed rights failures — so it
+    // does not resurrect the deleted precheck. DMs are never rights-gated. The
+    // attempt is still counted so the cursor forfeits at SWEEP_MAX_ATTEMPTS.
+    if (kind !== 'dm' && deps.rightsBlocked?.(target.chatId) === true) {
+      cursor.attempts++
+      cursor.lastStatus = 'skipped-no-rights'
+      cursor.updatedAt = deps.now()
+      commit(cursor)
+      return { status: 'skipped-no-rights', popped: 0, issued: 0 }
     }
 
     cursor.attempts++
@@ -1196,6 +1207,11 @@ export function createStalePinSweeper(deps: StalePinSweepDeps): StalePinSweeper
     cursor.updatedAt = deps.now()
     commit(cursor)
 
+    // Feed the shared negative cache (D3): a reactive `skipped-no-rights` is a
+    // real observed `400 not enough rights`, so record it so the live pin path
+    // and later sweeps of this chat skip the doomed attempt too.
+    if (result.status === 'skipped-no-rights') deps.recordRightsBlock?.(target.chatId)
+
     // Restore the deliberately-retained pins the blind DM drain cleared.
     // Rate-gated like any other write; a failure is logged and never fatal.
     //

package/telegram-plugin/gateway/throttle-tier-wiring.ts

@@ -73,6 +73,10 @@ export interface ThrottleBrokerClient {
     throttled_until: number
     escalated: boolean
     rolledTo?: string | null
+    /** True when the caller has a strict pin (`auth.strict`) — its null
+     *  `rolledTo` means "riding out the wall", not fleet all-blocked.
+     *  Absent on pre-flag brokers. */
+    caller_pinned_strict?: boolean
   }>
   claimNotification(key: string, windowMs: number): Promise<{ granted: boolean }>
 }
@@ -214,19 +218,22 @@ export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): Throttle
     client: ThrottleBrokerClient | null,
     account: string | null,
     rolledTo: string | null,
+    callerPinnedStrict: boolean,
     triggerAgent: string,
     armedAtMs: number,
   ): Promise<void> {
     deps.log(
       `[throttle-tier] escalated to wall account=${account ?? '?'} ` +
-        `rolledTo=${rolledTo ?? 'none (all blocked)'}`,
+        `rolledTo=${rolledTo ?? (callerPinnedStrict ? 'none (strict pin, riding it out)' : 'none (all blocked)')}`,
     )
     await broadcastDeduped(
       client,
       'throttle-escalation',
       account,
-      renderThrottleEscalationNotice({ account, agent: triggerAgent, rolledTo }),
+      renderThrottleEscalationNotice({ account, agent: triggerAgent, rolledTo, callerPinnedStrict }),
     )
+    // No nudge on a null rolledTo — for a strict pin a resume would replay
+    // the turn straight back into the wall it just hit.
     if (rolledTo) nudgeResume('throttle-escalation-resume', armedAtMs)
   }
 
@@ -240,6 +247,7 @@ export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): Throttle
     let account: string | null = null
     let escalated = false
     let rolledTo: string | null = null
+    let callerPinnedStrict = false
     try {
       client = await deps.getBrokerClient()
       if (client) {
@@ -247,6 +255,7 @@ export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): Throttle
         account = r.account
         escalated = r.escalated
         rolledTo = r.rolledTo ?? null
+        callerPinnedStrict = r.caller_pinned_strict ?? false
       } else {
         deps.log(
           `[throttle-tier] broker unreachable — notice only, no ledger record agent=${triggerAgent}`,
@@ -259,7 +268,7 @@ export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): Throttle
     }
 
     if (escalated) {
-      await announceEscalation(client, account, rolledTo, triggerAgent, armedAtMs)
+      await announceEscalation(client, account, rolledTo, callerPinnedStrict, triggerAgent, armedAtMs)
       return
     }
 
@@ -303,6 +312,7 @@ export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): Throttle
     let account: string | null = null
     let escalated = false
     let rolledTo: string | null = null
+    let callerPinnedStrict = false
     try {
       client = await deps.getBrokerClient()
       if (client) {
@@ -312,6 +322,7 @@ export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): Throttle
         account = r.account
         escalated = r.escalated
         rolledTo = r.rolledTo ?? null
+        callerPinnedStrict = r.caller_pinned_strict ?? false
       } else {
         deps.log(
           `[throttle-tier] broker unreachable — probe-only skipped agent=${triggerAgent}`,
@@ -324,7 +335,7 @@ export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): Throttle
     }
 
     if (escalated) {
-      await announceEscalation(client, account, rolledTo, triggerAgent, armedAtMs)
+      await announceEscalation(client, account, rolledTo, callerPinnedStrict, triggerAgent, armedAtMs)
       return
     }
 

package/telegram-plugin/slot-banner-driver.ts

@@ -22,6 +22,11 @@
 
 import type { BannerState } from './slot-banner.js';
 import { decideBannerAction } from './slot-banner.js';
+// Shared rights model (D5): the banner adopts the status-pin path's rights
+// detector, terminal-unpin classifier and per-process negative cache, so the two
+// pin owners agree on which chats are rights-less instead of the banner's old
+// drop-on-ANY-unpin. status-pin.ts is dependency-free.
+import { isPinRightsError, isUnpinTerminalError, type PinRightsCache } from './status-pin.js';
 
 /** Minimal subset of grammy's `bot.api` we depend on. Letting tests
  *  swap in `fake-bot-api.ts` without dragging in the full Bot type. */
@@ -72,6 +77,15 @@ export interface RefreshBannerArgs {
   /** Optional API-failure observer. Phase identifies which Bot API
    *  call failed so the caller can log meaningfully. Default: silent. */
   onError?: (phase: 'pin' | 'edit' | 'unpin', err: unknown) => void;
+  /** Shared per-process pin-rights negative cache (status-pin.ts
+   *  `PinRightsCache`), unifying the banner with the status-pin path on
+   *  rights-less chats (D5). When the chat is already known rights-less the pin
+   *  action is skipped so we never emit an un-pinnable notice; a real pin-rights
+   *  400 from the pin/unpin verb records the block and a confirmed pin clears
+   *  it. Fed ONLY from the pin/unpin verbs — a `sendMessage` failure is never
+   *  cached, because a send failure is not a pin-rights signal. Optional;
+   *  omitted in unit tests. */
+  rightsCache?: Pick<PinRightsCache, 'isBlocked' | 'block' | 'clear'>;
   /** Optional durable-persistence hooks so an orphaned banner pin is
    *  recoverable across a gateway crash. The gateway wires these to the
    *  shared status-pin store (a distinct `banner:` pinKey), mirroring the
@@ -127,20 +141,34 @@ export async function refreshBanner(
 
   if (action.kind === 'unpin') {
     try {
+      // allow-raw-pin: the slot banner is a sanctioned separate pin owner (see
+      // scripts/check-status-pin-single-path-allowlist.txt); its unpin is not
+      // routed through reconcileStatusPin.
       await args.bot.api.unpinChatMessage(args.ownerChatId, action.messageId);
     } catch (err) {
       args.onError?.('unpin', err);
+      // Feed the shared negative cache ONLY from a real pin-rights 400 on the
+      // unpin verb — never from any other failure class (D5).
+      if (isPinRightsError(err)) args.rightsCache?.block(String(args.ownerChatId));
+      // Adopt the status-pin terminal-vs-never-confirmed contract (#3664 Defect
+      // B) instead of drop-on-ANY-unpin: retain the claim when the unpin did
+      // NOT terminally land (transient flood/5xx/network), so the next refresh
+      // retries rather than orphaning a still-pinned banner with no record. A
+      // terminal 4xx (rights, message gone, bot kicked) — and a success — fall
+      // through to the drop below, because re-issuing cannot help.
+      if (!isUnpinTerminalError(err)) return args.prevState;
     }
-    // Even if unpin failed, drop our claim — the message may have been
-    // unpinned out-of-band (operator did it manually) and re-pinning
-    // would be more confusing than surfacing it again later. Drop the
-    // persisted record too (unpin-then-clear mirrors the status-pin store:
-    // a crash between unpin and clear just re-unpins next boot, idempotent).
+    // Terminal outcome: drop our claim and the persisted record. A crash
+    // between unpin and clear just re-unpins next boot (idempotent).
     safePersist(args.persist?.clear);
     return null;
   }
 
   if (action.kind === 'pin') {
+    // The banner is a PINNED notice: if this chat is already known rights-less
+    // (proved by the status-pin path or an earlier banner pin), skip the whole
+    // send+pin — an un-pinnable send is pure noise (D5).
+    if (args.rightsCache?.isBlocked(String(args.ownerChatId))) return args.prevState;
     let sent: { message_id: number };
     try {
       // sendRichMessage doesn't accept link_preview_options — omit it.
@@ -150,6 +178,8 @@ export async function refreshBanner(
         disable_notification: true,
       });
     } catch (err) {
+      // SEND failure — deliberately NOT a pin-rights signal, so the cache is
+      // NEVER written here even though the phase tag below is 'pin' (D5).
       args.onError?.('pin', err);
       return args.prevState;
     }
@@ -158,17 +188,24 @@ export async function refreshBanner(
     // unpins next boot — closing the persist-after-pin leak.
     safePersist(() => args.persist?.pending?.(String(args.ownerChatId), sent.message_id));
     try {
+      // allow-raw-pin: sanctioned banner pin owner (see the allowlist).
       await args.bot.api.pinChatMessage(args.ownerChatId, sent.message_id, {
         disable_notification: true,
       });
     } catch (err) {
       args.onError?.('pin', err);
+      // The PIN verb failing with a real pin-rights 400 IS the rights signal —
+      // record it so later refreshes skip the doomed send+pin (D5).
+      if (isPinRightsError(err)) args.rightsCache?.block(String(args.ownerChatId));
       // sendMessage succeeded but pin failed — don't claim the message, and
       // drop the pending record so we don't leave a phantom claim for a pin
       // that never landed.
       safePersist(args.persist?.clear);
       return args.prevState;
     }
+    // Pin confirmed — rights are present, so clear any stale block for this chat
+    // (mirrors the status-pin path clearing on a successful pin).
+    args.rightsCache?.clear(String(args.ownerChatId));
     // Pin confirmed — rewrite the record without the pending flag.
     safePersist(() => args.persist?.confirm?.(String(args.ownerChatId), sent.message_id));
     return { messageId: sent.message_id, slot: action.slot };

package/telegram-plugin/tests/auto-fallback-fleet.test.ts

@@ -190,6 +190,30 @@ describe('runFleetAutoFallback', () => {
     expect(failover).toHaveBeenCalledTimes(1);
   });
 
+  it('strict-pinned caller: null rolledTo yields the strict-pinned outcome, NOT all-blocked', async () => {
+    // agents.<name>.auth.strict — the broker marked the account but
+    // deliberately did not roll the caller. The all-blocked card here would
+    // claim fleet-wide exhaustion while its own snapshots show healthy
+    // accounts.
+    const failover = vi.fn(async () => ({
+      rolledTo: null, rolled: [], callerPinnedStrict: true,
+    }));
+    const out = await runFleetAutoFallback({
+      state: state('work@x', ['work@x']),
+      quotas: [qOk({ fiveHourUtilizationPct: 12, sevenDayUtilizationPct: 30 })],
+      failover,
+      triggerAgent: 'workbot',
+      now: NOW,
+      tz: 'UTC',
+      rateLimitTrigger: true,
+    });
+    expect(out.kind).toBe('strict-pinned');
+    expect(failover).toHaveBeenCalledTimes(1);
+    expect(out.announcement).toContain('strictly pinned');
+    expect(out.announcement).toContain('fleet is unaffected');
+    expect(out.announcement).not.toContain('blocked');
+  });
+
   it('idempotency: skips the swap WITHOUT calling failover when active probes healthy', async () => {
     const failover = vi.fn();
     const out = await runFleetAutoFallback({

package/telegram-plugin/tests/gateway-handler-registration-wiring.test.ts

@@ -57,6 +57,8 @@ const GOLDEN_REGISTRATIONS: readonly string[] = [
   'command:inject',
   'command:compact',
   'command:clear',
+  'command:private',
+  'command:public',
   'helper:registerModelEffortCommands',
   'command:agentstart',
   'command:agentstop',