switchroom 0.19.25 → 0.19.27

package/telegram-plugin/tests/periodic-sweep-guard.test.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect } from "vitest";
+import { createPeriodicSweepGuard } from "../gateway/periodic-sweep-guard.js";
+
+/**
+ * Single-flight guard for the interval-driven mid-session card reaper.
+ *
+ * Pre-fix the interval dispatched `void runMidSessionCardReaper()` directly, so
+ * a pass that parked behind a flood-wait (this gateway took a 62-minute flood
+ * ban on 2026-07-25) let EVERY subsequent tick start another concurrent pass —
+ * unbounded fan-out racing the same store rows and firing duplicate unpins into
+ * the rate limit that caused the stall. These assert the observable outcome:
+ * the number of times `run` actually started.
+ */
+describe("createPeriodicSweepGuard", () => {
+  /** A pass we can hold open, counting starts and completions. */
+  function heldRun() {
+    let release!: () => void;
+    let gate = new Promise<void>((r) => {
+      release = r;
+    });
+    let starts = 0;
+    let finishes = 0;
+    const run = async () => {
+      starts += 1;
+      await gate;
+      finishes += 1;
+    };
+    return {
+      run,
+      starts: () => starts,
+      finishes: () => finishes,
+      release: () => {
+        release();
+        // Re-arm so a later pass can be held again.
+        gate = new Promise<void>((r) => {
+          release = r;
+        });
+      },
+    };
+  }
+
+  it("runs the pass when idle", async () => {
+    let ran = 0;
+    const g = createPeriodicSweepGuard({
+      run: async () => {
+        ran += 1;
+      },
+    });
+    await g.tick();
+    expect(ran).toBe(1);
+    expect(g.isRunning()).toBe(false);
+    expect(g.skipped()).toBe(0);
+  });
+
+  it("SKIPS every tick that arrives while a pass is still in flight (the fan-out fix)", async () => {
+    const h = heldRun();
+    const skips: number[] = [];
+    const g = createPeriodicSweepGuard({ run: h.run, onSkip: () => skips.push(1) });
+
+    const inFlight = g.tick();
+    await Promise.resolve();
+    expect(g.isRunning()).toBe(true);
+    expect(h.starts()).toBe(1);
+
+    // Ten more interval ticks land during the stall. Pre-fix these were ten
+    // more concurrent passes; now they are dropped.
+    await Promise.all([
+      g.tick(),
+      g.tick(),
+      g.tick(),
+      g.tick(),
+      g.tick(),
+      g.tick(),
+      g.tick(),
+      g.tick(),
+      g.tick(),
+      g.tick(),
+    ]);
+    expect(h.starts()).toBe(1); // still exactly ONE pass ever started
+    expect(g.skipped()).toBe(10);
+    expect(skips).toHaveLength(10);
+
+    h.release();
+    await inFlight;
+    expect(h.finishes()).toBe(1);
+    expect(g.isRunning()).toBe(false);
+  });
+
+  it("re-arms after the in-flight pass settles, so the sweep is not disabled forever", async () => {
+    const h = heldRun();
+    const g = createPeriodicSweepGuard({ run: h.run });
+    const first = g.tick();
+    await Promise.resolve();
+    await g.tick(); // skipped
+    h.release();
+    await first;
+
+    const second = g.tick();
+    await Promise.resolve();
+    expect(h.starts()).toBe(2); // the NEXT tick genuinely ran
+    h.release();
+    await second;
+  });
+
+  it("absorbs a throwing pass: tick never rejects, the guard re-arms, onError sees it", async () => {
+    const seen: unknown[] = [];
+    let calls = 0;
+    const g = createPeriodicSweepGuard({
+      run: async () => {
+        calls += 1;
+        throw new Error(`boom ${calls}`);
+      },
+      onError: (e) => seen.push(e),
+    });
+
+    // A rejection escaping here reaches the gateway's `unhandledRejection`
+    // handler, which CRASHES the process — a cosmetic sweep must never do that.
+    await expect(g.tick()).resolves.toBeUndefined();
+    expect(g.isRunning()).toBe(false);
+    await expect(g.tick()).resolves.toBeUndefined();
+    expect(calls).toBe(2); // a throw does not wedge the running flag
+    expect(seen).toHaveLength(2);
+    expect((seen[0] as Error).message).toBe("boom 1");
+  });
+
+  it("a throwing observer cannot break the guard", async () => {
+    const h = heldRun();
+    const g = createPeriodicSweepGuard({
+      run: h.run,
+      onSkip: () => {
+        throw new Error("broken logger");
+      },
+    });
+    const first = g.tick();
+    await Promise.resolve();
+    await expect(g.tick()).resolves.toBeUndefined();
+    expect(g.skipped()).toBe(1);
+    h.release();
+    await first;
+  });
+
+  it("onError is optional — a throwing pass with no observer is still absorbed", async () => {
+    const g = createPeriodicSweepGuard({
+      run: async () => {
+        throw new Error("boom");
+      },
+    });
+    await expect(g.tick()).resolves.toBeUndefined();
+    expect(g.isRunning()).toBe(false);
+  });
+});

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

@@ -134,9 +134,9 @@ 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.
-    //    This seam is owned by the collapse separator (a worker HEADER carries
-    //    no leading indent, so nothing else separates it).
+    // 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
@@ -144,14 +144,14 @@ describe('combined worker card survives the pinned-bar collapse (#3666)', () =>
     expect(collapsed).not.toContain('running1.')
     expect(collapsed).not.toContain('tok1.')
     expect(collapsed).toContain(`tok${NB}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.
+    // 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}${WORKER_STEP_INDENT}✓`)
     // 3. the step trail running into the next step, and into the next row's
-    //    header (that last seam is separator-only: headers are unindented).
+    //    header (post-#3842 that last seam is the separator alone).
     expect(collapsed).not.toContain('gateway.ts→')
     expect(collapsed).toContain(`gateway.ts${NB}${WORKER_STEP_INDENT}→`)
     expect(collapsed).not.toContain('search2.')
@@ -170,20 +170,24 @@ describe('combined worker card survives the pinned-bar collapse (#3666)', () =>
   })
 
   it('CONTROL: the same lines joined without collapseSafe still mash (pre-fix shape)', () => {
-    // Discriminator: re-join the SAME rendered lines with the separator removed
-    // and show the collapsed preview mashes again. Without this, the assertions
+    // Discriminator: re-join rendered card lines with the separator removed and
+    // show the collapsed preview mashes again. Without this, the assertions
     // above could all be passing for reasons unrelated to the fix.
     //
-    // The seams asserted here are the ones the separator alone owns: a worker
-    // HEADER line carries no leading WORKER_STEP_INDENT, so the
-    // glance->row-1 and step->next-row seams have nothing else holding them
-    // apart. (The header->step and step->step seams are separated by the indent
-    // even pre-fix, which is why they are not the control.)
-    const lines = rawCardLines(body).map((l) => l.replace(new RegExp(NB + '$'), ''))
+    // 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',
+      'Running tests',
+    ])!
+    const lines = rawCardLines(agent).map((l) => l.replace(new RegExp(NB + '$'), ''))
     const preFix = stackCardLines(lines)
     const collapsed = collapsePreview(preFix)
-    expect(collapsed).toContain('tok1.')
-    expect(collapsed).toContain('search2.')
+    expect(collapsed).toContain('gateway.ts✓ Searching')
+    expect(collapsed).toContain('memory→ Running')
     // …and the property assertion itself would have failed on it.
     expect(() => expectNoMashedSeams(preFix)).toThrow()
   })
@@ -217,6 +221,8 @@ describe('single-worker / agent status card survives the collapse too (#3666)',
     expectNoMashedSeams(body)
     const collapsed = collapsePreview(body)
     expect(collapsed).not.toContain('toolsstarting')
+    // #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`)
   })
 

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 })