switchroom 0.19.26 → 0.19.27

package/telegram-plugin/tests/pinned-card-collapse.test.ts

@@ -33,7 +33,6 @@ import {
   STATUS_CARD_CHAR_BUDGET,
   STATUS_LINE_MAX,
   WORKER_STEP_INDENT,
-  SUBORDINATE_LINE_INDENT,
 } from '../status-no-truncate.js'
 
 /**
@@ -135,31 +134,28 @@ describe('combined worker card survives the pinned-bar collapse (#3666)', () =>
 
   it('kills the exact artifacts from the report', () => {
     const collapsed = collapsePreview(body)
-    // 1. the count/ordinal collision — glance line into row 1's ordinal.
-    //    Since #3820 a worker header also carries the card-level
-    //    SUBORDINATE_LINE_INDENT (the whole worker card nests under the 🤖
-    //    agent card), so this seam is separator + card indent.
+    // 1. the count/ordinal collision — glance line into row 1's ordinal. Since
+    //    #3842 the row header is FLUSH (the #3820 card-level indent is gone),
+    //    so the separator is the ONLY thing holding this seam apart.
     //    (The reported spelling was `3 running1.`; with the packed glance line
     //    the same seam now reads `… 512.3k tok` -> `1. Fix issue`, so assert on
     //    the CURRENT last token of line 1 — an assertion on the old spelling
     //    alone would be vacuously green.)
     expect(collapsed).not.toContain('running1.')
     expect(collapsed).not.toContain('tok1.')
-    expect(collapsed).toContain(`tok${NB}${SUBORDINATE_LINE_INDENT}1. Fix issue`)
-    // 2. the mid-word ✓ (model tag running into the step trail). Here the
-    //    separator and WORKER_STEP_INDENT (three U+2800 leading a step line)
-    //    stack, so the seam is separator + indent, asserted against both
-    //    constants rather than a hardcoded run of spaces.
+    expect(collapsed).toContain(`tok${NB}1. Fix issue`)
+    // 2. the mid-word ✓ (model tag running into the step trail). A step line
+    //    still leads with WORKER_STEP_INDENT (three U+2800), so this seam is
+    //    separator + step indent — asserted against the constant rather than a
+    //    hardcoded run.
     expect(collapsed).not.toContain('opus 5✓')
-    expect(collapsed).toContain(`opus 5${NB}${SUBORDINATE_LINE_INDENT}${WORKER_STEP_INDENT}✓`)
+    expect(collapsed).toContain(`opus 5${NB}${WORKER_STEP_INDENT}✓`)
     // 3. the step trail running into the next step, and into the next row's
-    //    header (post-#3820 that last seam is separator + card indent).
+    //    header (post-#3842 that last seam is the separator alone).
     expect(collapsed).not.toContain('gateway.ts→')
-    expect(collapsed).toContain(
-      `gateway.ts${NB}${SUBORDINATE_LINE_INDENT}${WORKER_STEP_INDENT}→`,
-    )
+    expect(collapsed).toContain(`gateway.ts${NB}${WORKER_STEP_INDENT}→`)
     expect(collapsed).not.toContain('search2.')
-    expect(collapsed).toContain(`search${NB}${SUBORDINATE_LINE_INDENT}2.`)
+    expect(collapsed).toContain(`search${NB}2.`)
   })
 
   it('leads with a self-contained glance that ends in a unit word, not a bare number', () => {
@@ -178,13 +174,10 @@ describe('combined worker card survives the pinned-bar collapse (#3666)', () =>
     // show the collapsed preview mashes again. Without this, the assertions
     // above could all be passing for reasons unrelated to the fix.
     //
-    // The control runs on the 🤖 AGENT card, not the worker card: since #3820
-    // every line of a worker card after line 1 carries a leading
-    // SUBORDINATE_LINE_INDENT, which separates its seams independently of the
-    // collapse separator — so a worker-card control would no longer isolate the
-    // separator's contribution. The agent card is the surface where the
-    // separator is still the ONLY thing holding the seams apart, which is
-    // exactly what this control must measure.
+    // The control runs on the 🤖 AGENT card. Post-#3842 the single-worker card
+    // is flush too, so either would isolate the separator's contribution; the
+    // agent card is kept because it has no step indent on ANY line, so no
+    // future indent change can quietly make this control vacuous.
     const agent = renderActivityFeed([
       'Reading gateway.ts',
       'Searching memory',
@@ -228,7 +221,9 @@ describe('single-worker / agent status card survives the collapse too (#3666)',
     expectNoMashedSeams(body)
     const collapsed = collapsePreview(body)
     expect(collapsed).not.toContain('toolsstarting')
-    expect(collapsed).toContain(`0 tools${NB}${SUBORDINATE_LINE_INDENT}starting`)
+    // #3842: the single-worker card is flush, so the separator alone holds the
+    // hand-rolled `starting…` seam apart — nothing else masks a regression.
+    expect(collapsed).toContain(`0 tools${NB}starting`)
   })
 
   it('the nested child block stays separated even though its indent is ASCII (#3668)', () => {

package/telegram-plugin/tests/pinned-message-handler.test.ts

@@ -3,7 +3,7 @@
  * extracted from gateway.ts (switchroom#2996 P6 cluster F). Asserts the
  * chat-scoped ownership guard (only OUR pins get their service message
  * deleted), the reconcile-store race retry, and best-effort logging on a
- * delete failure — against injected pin-state maps + a mock deleteServiceMessage.
+ * delete failure — against an injected claim registry + a mock deleteServiceMessage.
  */
 
 import { describe, it, expect, vi } from 'vitest'
@@ -11,13 +11,18 @@ import {
   handlePinnedMessage,
   type PinnedMessageHandlerDeps,
 } from '../gateway/pinned-message-handler.js'
+import type { StatusPinClaim } from '../gateway/status-pin-retarget.js'
+
+/** One claim, the single record the gateway now keeps per pin key (#3809). */
+function claim(messageId: number, chatId: string): StatusPinClaim {
+  return { messageId, chatId, pinnedAt: 1000 }
+}
 
 function makeDeps(over: Partial<PinnedMessageHandlerDeps> = {}) {
   const deleteServiceMessage = vi.fn(async () => {})
   const log = vi.fn()
   const deps: PinnedMessageHandlerDeps = {
-    statusPinState: new Map(),
-    statusPinChatIds: new Map(),
+    statusPinClaims: new Map(),
     deleteServiceMessage,
     log,
     ...over,
@@ -38,8 +43,7 @@ function ctxWith(chatId: number, pinnedMessageId: number | undefined, serviceMsg
 describe('handlePinnedMessage — ownership guard', () => {
   it('deletes the service message when the pin is ours in this chat', async () => {
     const { deps, deleteServiceMessage } = makeDeps({
-      statusPinState: new Map([['fg:a', { messageId: 555 }]]),
-      statusPinChatIds: new Map([['fg:a', '42']]),
+      statusPinClaims: new Map([['fg:a', claim(555, '42')]]),
     })
     await handlePinnedMessage(ctxWith(42, 555, 999), deps)
     expect(deleteServiceMessage).toHaveBeenCalledWith('42', 999)
@@ -47,8 +51,8 @@ describe('handlePinnedMessage — ownership guard', () => {
 
   it('does NOT delete when the pinned id matches but the tracked chat differs', async () => {
     const { deps, deleteServiceMessage } = makeDeps({
-      statusPinState: new Map([['fg:a', { messageId: 555 }]]),
-      statusPinChatIds: new Map([['fg:a', '99']]), // tracked in a DIFFERENT chat
+      // tracked in a DIFFERENT chat
+      statusPinClaims: new Map([['fg:a', claim(555, '99')]]),
     })
     await handlePinnedMessage(ctxWith(42, 555, 999), deps)
     expect(deleteServiceMessage).not.toHaveBeenCalled()
@@ -75,16 +79,13 @@ describe('handlePinnedMessage — reconcile-store race', () => {
     // #3354 bun-test failure). The handler waits 250ms before its single
     // re-check; populate the store inside that window and await the real
     // delay.
-    const state = new Map<string, { messageId: number }>()
-    const chatIds = new Map<string, string>()
+    const claims = new Map<string, StatusPinClaim>()
     const { deps, deleteServiceMessage } = makeDeps({
-      statusPinState: state,
-      statusPinChatIds: chatIds,
+      statusPinClaims: claims,
     })
     const p = handlePinnedMessage(ctxWith(42, 555, 999), deps)
     // Store catches up during the 250ms race window.
-    state.set('fg:a', { messageId: 555 })
-    chatIds.set('fg:a', '42')
+    claims.set('fg:a', claim(555, '42'))
     await p
     expect(deleteServiceMessage).toHaveBeenCalledWith('42', 999)
   })
@@ -93,8 +94,7 @@ describe('handlePinnedMessage — reconcile-store race', () => {
 describe('handlePinnedMessage — best-effort delete failure', () => {
   it('logs a concise reason when the delete throws', async () => {
     const { deps, log } = makeDeps({
-      statusPinState: new Map([['fg:a', { messageId: 555 }]]),
-      statusPinChatIds: new Map([['fg:a', '42']]),
+      statusPinClaims: new Map([['fg:a', claim(555, '42')]]),
       deleteServiceMessage: vi.fn(async () => {
         throw new Error('not enough rights')
       }),

package/telegram-plugin/tests/provider-credit-402.test.ts

@@ -0,0 +1,243 @@
+/**
+ * provider-credit-402.test.ts — outcome tests for the OpenRouter/OpenAI/
+ * Perplexity credit-error leak.
+ *
+ * THE BUG (audited 2026-07-28). OpenRouter answers an exhausted balance with
+ * HTTP 402 `payment_required` / "insufficient credits". None of switchroom's
+ * quota/credit wordings matched it — every one of them was an ANTHROPIC
+ * wording — so `classifyClaudeError` fell through to `unknown-4xx`.
+ * `unknown-4xx` is NOT in `OPERATOR_ACTIONABLE_KINDS`, so
+ * `decideOperatorEventAudience` broadcast it to EVERY allowlist chat: an end
+ * user got a card carrying the raw vendor error in a code span and a "🔐
+ * Reauth" button they cannot act on. That violates Ken's standing rule that an
+ * operator-actionable error must never reach an end user.
+ *
+ * These assert the OBSERVABLE RESULT, composing the SAME production functions
+ * in the SAME order `emitGatewayOperatorEvent` (gateway.ts ~:8134-8290) calls
+ * them — classify → resolveModelUnavailableFromOperatorEvent → render →
+ * decideOperatorEventAudience → renderUserFacingFailureNotice — so a
+ * regression anywhere along that chain fails here:
+ *
+ *   1. a real OpenRouter 402 body produces an OPERATOR card, and
+ *   2. the text a non-operator user sees is the brief plain-language notice,
+ *      carrying NO raw error text, NO vendor name, NO status code.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  classifyClaudeError,
+  renderOperatorEvent,
+  decideOperatorEventAudience,
+  isOperatorActionableKind,
+  renderUserFacingFailureNotice,
+  type OperatorEvent,
+} from '../operator-events.js'
+import { resolveModelUnavailableFromOperatorEvent } from '../model-unavailable.js'
+import { parseLlmError, isActionableKind } from '../llm-error-present.js'
+import { attributeProvider, detectProviderCreditExhaustion } from '../provider-credit.js'
+
+// ── Verbatim vendor shapes (docs verified 2026-07-28) ───────────────────────
+
+/**
+ * OpenRouter through LiteLLM. Wording per
+ * https://openrouter.ai/docs/api-reference/errors — 402, typed code
+ * `payment_required`, "insufficient credits. Add more credits and retry".
+ */
+const OPENROUTER_402 =
+  'litellm.APIError: OpenrouterException - {"error":{"code":402,"message":"Your account or API key has insufficient credits. Add more credits and retry the request.","metadata":{"provider_name":"openrouter"}}}'
+
+/** The per-key variant: the ACCOUNT has money, the key's `limit_remaining` is spent. */
+const OPENROUTER_402_PER_KEY =
+  'openrouter.ai returned 402: This request requires more credits, or fewer max_tokens.'
+
+/**
+ * OpenAI's exhausted balance. NOTE the status is 429, not 402
+ * (https://platform.openai.com/docs/guides/error-codes) — the case that makes
+ * "just match 402" insufficient.
+ */
+const OPENAI_INSUFFICIENT_QUOTA =
+  'litellm.RateLimitError: OpenAIException - {"error":{"message":"You exceeded your current quota, please check your plan and billing details.","type":"insufficient_quota","code":"insufficient_quota"}} (api.openai.com)'
+
+/** A genuine ANTHROPIC credit wall — must keep its own kind and its own card. */
+const ANTHROPIC_CREDIT =
+  '{"type":"error","error":{"type":"invalid_request_error","message":"Your credit balance is too low to access the Claude API."}}'
+
+/** An ordinary transient 429 — must NOT be dragged into the credit class. */
+const PLAIN_RATE_LIMIT =
+  '{"type":"error","error":{"type":"rate_limit_error","message":"Number of requests has exceeded your rate limit"}}'
+
+const ALLOW = ['5000000001' /* operator */, '5000000002' /* end user */, '5000000003']
+
+function makeEvent(detail: string): OperatorEvent {
+  const kind = classifyClaudeError({ message: detail, type: detail })
+  return {
+    kind,
+    agent: 'klanker',
+    detail,
+    suggestedActions: [],
+    firstSeenAt: new Date('2026-07-28T10:00:00Z'),
+  }
+}
+
+/**
+ * The gateway's observable outcome for one error string: what the OPERATOR
+ * sees and what a NON-OPERATOR user sees. Composed from the same production
+ * functions, in the gateway's order (gateway.ts ~:8134-8290).
+ */
+function route(detail: string): {
+  kind: string
+  firedFleetFailover: boolean
+  operatorText: string | null
+  operatorChats: string[]
+  userText: string | null
+  userChats: string[]
+} {
+  const ev = makeEvent(detail)
+  // The gateway renders the "⚠️ Model unavailable" card AND fires
+  // fireFleetAutoFallback iff this resolves to a quota_exhausted detection.
+  const mu = resolveModelUnavailableFromOperatorEvent(ev)
+  const firedFleetFailover = mu?.kind === 'quota_exhausted'
+  const { operatorChats, userNoticeChats } = decideOperatorEventAudience(
+    ev.kind,
+    ALLOW,
+    ALLOW[0],
+  )
+  return {
+    kind: ev.kind,
+    firedFleetFailover,
+    operatorText: operatorChats.length > 0 ? renderOperatorEvent(ev).text : null,
+    operatorChats,
+    userText: userNoticeChats.length > 0 ? renderUserFacingFailureNotice() : null,
+    userChats: userNoticeChats,
+  }
+}
+
+describe('OpenRouter 402 — the end-user leak is closed', () => {
+  it('produces an OPERATOR card and gives the user only the brief notice', () => {
+    const r = route(OPENROUTER_402)
+
+    // 1. Classified as the operator-only provider-credit kind.
+    expect(r.kind).toBe('provider-credit-exhausted')
+    expect(isOperatorActionableKind('provider-credit-exhausted')).toBe(true)
+
+    // 2. The full card goes to the OPERATOR ONLY.
+    expect(r.operatorChats).toEqual(['5000000001'])
+    expect(r.userChats).toEqual(['5000000002', '5000000003'])
+
+    // 3. The operator card is actionable and provider-correct.
+    expect(r.operatorText).toContain('OpenRouter')
+    expect(r.operatorText).toContain('openrouter/api-key') // vault key NAME
+    expect(r.operatorText).toContain('https://openrouter.ai/credits')
+
+    // 4. THE LEAK ASSERTION: nothing an end user receives carries the raw
+    //    vendor error, the vendor name, or the status code.
+    expect(r.userText).toBe(renderUserFacingFailureNotice())
+    for (const fragment of [
+      'insufficient credits',
+      'OpenRouter',
+      'openrouter',
+      '402',
+      'payment_required',
+      'litellm',
+      'api key',
+    ]) {
+      expect(r.userText!.toLowerCase()).not.toContain(fragment.toLowerCase())
+    }
+  })
+
+  it('never advertises an Anthropic remedy — /auth cannot buy OpenRouter credit', () => {
+    const { operatorText } = route(OPENROUTER_402)
+    // The `credit-exhausted` (Anthropic) card's recommendation sentence must
+    // not appear — the card may only NAME `/auth use` to rule it OUT.
+    expect(operatorText).not.toContain('Use `/auth use <label>`')
+    expect(operatorText).not.toContain('/auth add')
+    expect(operatorText).toContain('`/auth use` will NOT fix this')
+    // and no re-auth button: the key is valid, it is out of money
+    const rendered = renderOperatorEvent(makeEvent(OPENROUTER_402))
+    const buttons = rendered.keyboard.inline_keyboard.flat().map(b => b.text)
+    expect(buttons).toEqual(['❌ Dismiss'])
+    expect(JSON.stringify(rendered.keyboard)).not.toContain('reauth')
+  })
+
+  it('does NOT fire an Anthropic fleet failover (nothing about Anthropic is exhausted)', () => {
+    expect(route(OPENROUTER_402).firedFleetFailover).toBe(false)
+    expect(route(OPENROUTER_402_PER_KEY).firedFleetFailover).toBe(false)
+  })
+
+  it('covers the per-key credit-limit variant, not just a zero account balance', () => {
+    const r = route(OPENROUTER_402_PER_KEY)
+    expect(r.kind).toBe('provider-credit-exhausted')
+    expect(r.userChats.length).toBe(2)
+    expect(r.userText).toBe(renderUserFacingFailureNotice())
+  })
+})
+
+describe('OpenAI + Perplexity have the same gap and are covered', () => {
+  it('OpenAI insufficient_quota (HTTP 429!) is a credit wall, not a transient throttle', () => {
+    const r = route(OPENAI_INSUFFICIENT_QUOTA)
+    expect(r.kind).toBe('provider-credit-exhausted')
+    expect(r.operatorText).toContain('OpenAI')
+    expect(r.operatorText).toContain('openai/api-key')
+    // The bug this guards: 429 wording routing to "Rate limited … will retry
+    // automatically", which is false — nothing retries a spent balance.
+    expect(r.operatorText).not.toContain('Will retry automatically')
+    expect(r.userChats.length).toBe(2)
+  })
+
+  it('attributes a Perplexity balance error to the Perplexity console + key name', () => {
+    const entry = attributeProvider('api.perplexity.ai responded 401: insufficient credits')
+    expect(entry?.id).toBe('perplexity')
+    expect(entry?.vaultKey).toBe('perplexity/api-key')
+    expect(detectProviderCreditExhaustion('api.perplexity.ai: insufficient credits')).not.toBeNull()
+  })
+})
+
+describe('no collateral damage to the Anthropic paths', () => {
+  it('an Anthropic credit-balance wall keeps its own kind and its slot-switch remedy', () => {
+    const r = route(ANTHROPIC_CREDIT)
+    expect(r.kind).toBe('credit-exhausted')
+    expect(r.operatorText).toContain('/auth use')
+  })
+
+  it('an ordinary rate limit is untouched — still broadcast, still transient', () => {
+    const r = route(PLAIN_RATE_LIMIT)
+    expect(r.kind).toBe('rate-limited')
+    expect(r.operatorChats).toEqual(ALLOW)
+    expect(r.userChats).toEqual([])
+  })
+
+  it('a bare "402" substring in unrelated text is NOT a credit wall', () => {
+    // model ids, token counts and request ids routinely contain "402".
+    expect(detectProviderCreditExhaustion('model=gpt-402-turbo request_id=req_402x')).toBeNull()
+    expect(classifyClaudeError({ message: 'timeout after 402 ms', type: '' })).not.toBe(
+      'provider-credit-exhausted',
+    )
+  })
+
+  it('a structured HTTP 402 status is honoured even with no recognisable wording', () => {
+    expect(classifyClaudeError({ message: 'upstream refused', status: 402 })).toBe(
+      'provider-credit-exhausted',
+    )
+  })
+})
+
+describe('the user-facing LLM error surface', () => {
+  it('renders a diagnosis-free one-liner, never the raw 402 body', () => {
+    const parsed = parseLlmError(OPENROUTER_402)
+    expect(parsed.kind).toBe('provider_credit')
+    expect(parsed.providerId).toBe('openrouter')
+    expect(parsed.coreText).toBe(
+      'An upstream model provider is out of credit — the operator has been notified.',
+    )
+    expect(parsed.coreText).not.toContain('402')
+    expect(parsed.coreText).not.toContain('insufficient credits')
+    // Never claim a retry will fix it — a spent balance does not self-heal.
+    expect(parsed.coreText).not.toContain('retrying automatically')
+    expect(parsed.terminal).toBe(true)
+    expect(parsed.autoRetrying).toBe(false)
+  })
+
+  it('is always-actionable, so a dedup window can never silence it', () => {
+    expect(isActionableKind('provider_credit')).toBe(true)
+  })
+})

package/telegram-plugin/tests/status-pin-api.test.ts

@@ -7,7 +7,7 @@
  * claimed-but-never-painted pin, or (worse, Defect B's shape) a dropped claim
  * plus a deleted durable row for a message that is still pinned.
  *
- * The assertions below are OUTCOMES read off `reconcilePin`'s returned state
+ * The assertions below are OUTCOMES read off `executePinLeg`'s returned state
  * (does the gateway still hold a record of the pinned message?), not "was some
  * function called".
  */
@@ -20,7 +20,7 @@ import {
   type PinCapableBot,
 } from '../gateway/status-pin-api.js'
 import { SEND_GATE_SHED } from '../send-gate.js'
-import { reconcilePin } from '../status-pin-driver.js'
+import { executePinLeg } from '../status-pin-driver.js'
 
 /** A bot whose API always succeeds — so any failure below comes from the gate
  *  seam, never from Telegram. */
@@ -38,14 +38,14 @@ const shedRobust = async () => SEND_GATE_SHED as unknown
 describe('assertLanded — a shed send must not look like a landed one (#3664)', () => {
   it('a shed unpin does NOT drop the claim — the message is still pinned', async () => {
     const api = createStatusPinApi(liveBot, shedRobust)
-    const next = await reconcilePin({
+    const next = await executePinLeg({
       api,
       chatId: '-100123',
       prevState: { messageId: 715 },
-      desired: { pinned: false },
+      action: { kind: 'unpin', messageId: 715 },
       onError: () => {},
     })
-    // Without assertLanded the shed resolves success-shaped, reconcilePin
+    // Without assertLanded the shed resolves success-shaped, executePinLeg
     // returns null, and reconcileAndPersistStatusPin then DELETES the durable
     // row for a message that is provably still pinned — Defect B, reopened.
     expect(next).toEqual({ messageId: 715 })
@@ -53,11 +53,11 @@ describe('assertLanded — a shed send must not look like a landed one (#3664)',
 
   it('a shed pin does not claim the message', async () => {
     const api = createStatusPinApi(liveBot, shedRobust)
-    const next = await reconcilePin({
+    const next = await executePinLeg({
       api,
       chatId: '-100123',
       prevState: null,
-      desired: { pinned: true, messageId: 715 },
+      action: { kind: 'pin', messageId: 715 },
       onError: () => {},
     })
     // Claiming it would leave the gateway believing a pin exists that never
@@ -84,11 +84,11 @@ describe('assertLanded — a shed send must not look like a landed one (#3664)',
     const api = createStatusPinApi(liveBot, async () => undefined)
     await expect(api.unpinChatMessage('-100123', 715)).resolves.toBeUndefined()
 
-    const next = await reconcilePin({
+    const next = await executePinLeg({
       api,
       chatId: '-100123',
       prevState: { messageId: 715 },
-      desired: { pinned: false },
+      action: { kind: 'unpin', messageId: 715 },
       onError: () => {},
     })
     expect(next).toBeNull()
@@ -127,11 +127,11 @@ describe('assertBotReady — named backstop for a pre-ready caller (#3664)', ()
 
   it('a pre-ready unpin failure RETAINS the claim (it never reached Telegram)', async () => {
     const api = createStatusPinApi(() => undefined, passthrough)
-    const next = await reconcilePin({
+    const next = await executePinLeg({
       api,
       chatId: '-100123',
       prevState: { messageId: 715 },
-      desired: { pinned: false },
+      action: { kind: 'unpin', messageId: 715 },
       onError: () => {},
     })
     expect(next).toEqual({ messageId: 715 })

package/telegram-plugin/tests/status-pin-boot-recovery.test.ts

@@ -11,7 +11,7 @@
  * We cannot import gateway.ts directly (its module top-level runs the whole boot
  * IIFE incl. the startup mutex + bot.start). Instead we model the gateway's
  * status-pin subsystem faithfully with the SAME functions gateway.ts calls
- * (reconcileAndPersistStatusPin, reconcilePin, runStatusPinBootCleanup) over an
+ * (runStatusPinReconcile, executePinLeg, runStatusPinBootCleanup) over an
  * in-memory fs + a fake Telegram whose pin set we can inspect — so a regression
  * in the ordering / cleanup contract reds here.
  *
@@ -25,18 +25,28 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import {
   loadStatusPins,
+  type PersistedStatusPin,
   persistStatusPins,
   reconcileAndPersistStatusPin,
   runStatusPinBootCleanup,
   type StatusPinStoreFsSeam,
 } from "../gateway/status-pin-store.js";
-import { reconcilePin } from "../status-pin-driver.js";
-import type { PinState, DesiredPin } from "../status-pin.js";
-import { decidePinAction } from "../status-pin.js";
+import { executePinLeg } from "../status-pin-driver.js";
+import type { DesiredPin, PinState } from "../status-pin.js";
+import {
+  runStatusPinReconcile,
+  type StatusPinClaim,
+} from "../gateway/status-pin-retarget.js";
 import { makeFloodWaitActiveError } from "../retry-api-call.js";
 
 const PATH = "/state/agent/telegram/status-pins.json";
 
+/** Drop the #3810 claim-age stamp so a row's identity fields can be compared
+ *  literally. The age itself is asserted in status-pin-store.test.ts. */
+function idOnly(rows: PersistedStatusPin[]): Omit<PersistedStatusPin, "pinnedAt">[] {
+  return rows.map(({ pinnedAt: _age, ...rest }) => rest);
+}
+
 function memFs(seed: Record<string, string> = {}) {
   const files = new Map<string, string>(Object.entries(seed));
   const fs: StatusPinStoreFsSeam = {
@@ -78,33 +88,22 @@ function fakeTelegram() {
  * with injectable fs + api so a single test can span a "crash" and a fresh boot.
  */
 function makeGateway(fs: StatusPinStoreFsSeam, tg: ReturnType<typeof fakeTelegram>) {
-  const statusPinState = new Map<string, PinState>();
-  const statusPinChatIds = new Map<string, string>();
+  // ONE claim registry — the same single record the gateway keeps (#3809).
+  const statusPinClaims = new Map<string, StatusPinClaim>();
 
   async function reconcileStatusPin(pinKey: string, chatId: string, desired: DesiredPin) {
-    const prev = statusPinState.get(pinKey) ?? null;
-    const action = decidePinAction(prev, desired);
-    const op =
-      action.kind === "pin"
-        ? ({ kind: "pin", messageId: action.messageId } as const)
-        : ({ kind: "clear" } as const);
-    const next = await reconcileAndPersistStatusPin({
-      path: PATH,
-      fs,
+    const claim = statusPinClaims.get(pinKey);
+    const prev: PinState | null = claim == null ? null : { messageId: claim.messageId };
+    await runStatusPinReconcile({
       pinKey,
       chatId,
-      op,
-      applyPin: () =>
-        reconcilePin({ api: tg.api, chatId, prevState: prev, desired }),
-      log: () => {},
+      prev,
+      desired,
+      persist: { path: PATH, fs },
+      runPin: (action, from) =>
+        executePinLeg({ api: tg.api, chatId, prevState: from, action }),
+      claims: statusPinClaims,
     });
-    if (next == null) {
-      statusPinState.delete(pinKey);
-      statusPinChatIds.delete(pinKey);
-    } else {
-      statusPinState.set(pinKey, next);
-      statusPinChatIds.set(pinKey, chatId);
-    }
   }
 
   async function bootCleanup() {
@@ -116,7 +115,7 @@ function makeGateway(fs: StatusPinStoreFsSeam, tg: ReturnType<typeof fakeTelegra
     });
   }
 
-  return { statusPinState, reconcileStatusPin, bootCleanup };
+  return { statusPinClaims, reconcileStatusPin, bootCleanup };
 }
 
 describe("status-pin boot recovery (gateway wiring)", () => {
@@ -130,7 +129,7 @@ describe("status-pin boot recovery (gateway wiring)", () => {
 
     // Pin is live in Telegram and recorded on disk (confirmed).
     expect(tg.pinned.has("-100123:715")).toBe(true);
-    expect(loadStatusPins(PATH, fs)).toEqual([
+    expect(idOnly(loadStatusPins(PATH, fs))).toEqual([
       { pinKey: "fg:c:3", chatId: "-100123", messageId: 715 },
     ]);
 
@@ -144,7 +143,7 @@ describe("status-pin boot recovery (gateway wiring)", () => {
 
     expect(res).toEqual({ cleared: 1, retained: 0, kept: 0, total: 1 });
     expect(tg.pinned.has("-100123:715")).toBe(false); // orphan unpinned
-    expect(loadStatusPins(PATH, fs)).toEqual([]); // store emptied
+    expect(idOnly(loadStatusPins(PATH, fs))).toEqual([]); // store emptied
   });
 
   it("(B) pending pin (crash inside the persist-after-pin window) → recovered next boot", async () => {
@@ -171,7 +170,7 @@ describe("status-pin boot recovery (gateway wiring)", () => {
 
     // Orphan is live in Telegram; a PENDING record is on disk.
     expect(tg.pinned.has("-100123:715")).toBe(true);
-    expect(loadStatusPins(PATH, fs)).toEqual([
+    expect(idOnly(loadStatusPins(PATH, fs))).toEqual([
       { pinKey: "fg:c:3", chatId: "-100123", messageId: 715, pending: true },
     ]);
 
@@ -180,7 +179,7 @@ describe("status-pin boot recovery (gateway wiring)", () => {
     const res = await gw2.bootCleanup();
     expect(res).toEqual({ cleared: 1, retained: 0, kept: 0, total: 1 });
     expect(tg.pinned.has("-100123:715")).toBe(false);
-    expect(loadStatusPins(PATH, fs)).toEqual([]);
+    expect(idOnly(loadStatusPins(PATH, fs))).toEqual([]);
   });
 
   it("(C) #3664: a never-confirmed unpin (FLOOD_WAIT_ACTIVE) KEEPS the claim + the durable row, and the next boot clears the pin", async () => {
@@ -216,9 +215,9 @@ describe("status-pin boot recovery (gateway wiring)", () => {
     // The pin is STILL UP …
     expect(pinned.has("-100123:715")).toBe(true);
     // … and BOTH records survive: the in-memory claim …
-    expect(gw1.statusPinState.get("fg:c:3")).toEqual({ messageId: 715 });
+    expect(gw1.statusPinClaims.get("fg:c:3")?.messageId).toBe(715);
     // … and the durable row (what boot cleanup reads).
-    expect(loadStatusPins(PATH, fs)).toEqual([
+    expect(idOnly(loadStatusPins(PATH, fs))).toEqual([
       { pinKey: "fg:c:3", chatId: "-100123", messageId: 715 },
     ]);
 
@@ -226,8 +225,8 @@ describe("status-pin boot recovery (gateway wiring)", () => {
     floodOpen = false;
     await gw1.reconcileStatusPin("fg:c:3", "-100123", { pinned: false });
     expect(pinned.has("-100123:715")).toBe(false);
-    expect(gw1.statusPinState.has("fg:c:3")).toBe(false);
-    expect(loadStatusPins(PATH, fs)).toEqual([]);
+    expect(gw1.statusPinClaims.has("fg:c:3")).toBe(false);
+    expect(idOnly(loadStatusPins(PATH, fs))).toEqual([]);
   });
 
   it("(D) #3664: if the process dies while the flood window is open, the retained row lets the NEXT boot clear the orphan", async () => {
@@ -257,7 +256,7 @@ describe("status-pin boot recovery (gateway wiring)", () => {
     const res = await gw2.bootCleanup();
     expect(res).toEqual({ cleared: 1, retained: 0, kept: 0, total: 1 });
     expect(pinned.has("-100123:715")).toBe(false);
-    expect(loadStatusPins(PATH, fs)).toEqual([]);
+    expect(idOnly(loadStatusPins(PATH, fs))).toEqual([]);
   });
 
   it("clean shutdown (sweep DID run) leaves nothing for boot cleanup to do", async () => {
@@ -271,7 +270,7 @@ describe("status-pin boot recovery (gateway wiring)", () => {
     // Clean sweep: unpin the key.
     await gw1.reconcileStatusPin("fg:c:3", "-100123", { pinned: false });
     expect(tg.pinned.size).toBe(0);
-    expect(loadStatusPins(PATH, fs)).toEqual([]);
+    expect(idOnly(loadStatusPins(PATH, fs))).toEqual([]);
 
     const gw2 = makeGateway(fs, tg);
     expect(await gw2.bootCleanup()).toEqual({ cleared: 0, retained: 0, kept: 0, total: 0 });