switchroom 0.19.26 → 0.19.27

package/telegram-plugin/provider-credit.ts

@@ -0,0 +1,237 @@
+/**
+ * provider-credit.ts — the ONE registry of "this paid third-party provider is
+ * out of credit / its billing is blocked" signals, plus the pure classifier
+ * both surfaces consult.
+ *
+ * WHY THIS EXISTS (the leak it closes)
+ * ------------------------------------
+ * Every quota/credit wording switchroom recognised was an ANTHROPIC wording
+ * (`model-unavailable.ts`'s `quotaSignals`, `operator-events.ts`'s
+ * `credit_balance_too_low` branch). OpenRouter — which serves the whole
+ * `gpt-oss-20b` group and every `openrouter/*` model in
+ * `docker/litellm-proxy/litellm-config.yaml` — answers an exhausted balance
+ * with HTTP 402 `payment_required` / "insufficient credits", which matched
+ * NONE of them. It fell through `classifyClaudeError` to `unknown-4xx`, and
+ * `unknown-4xx` is NOT in `OPERATOR_ACTIONABLE_KINDS`, so the card (with the
+ * raw provider error in a code span, and a "🔐 Reauth" button nobody can act
+ * on) was BROADCAST to every allowlist chat — an end user included.
+ *
+ * Ken's standing product rule: a raw API/auth error that is OPERATOR-actionable
+ * rather than USER-actionable must never reach an end user. So a provider
+ * credit wall must classify to an operator-only kind.
+ *
+ * WHAT THIS MODULE IS AND IS NOT
+ * ------------------------------
+ * It is DATA (`PROVIDER_CREDIT_REGISTRY` + `CREDIT_EXHAUSTION_SIGNALS`) plus
+ * two pure predicates over that data. It is deliberately NOT wired to the
+ * Anthropic quota path: `detectModelUnavailable`'s `quota_exhausted` kind is
+ * what fires `fireFleetAutoFallback` (swap the Anthropic ACCOUNT SLOT). An
+ * OpenRouter balance of $0 says nothing about any Anthropic account, and
+ * rotating Anthropic slots would not buy a single OpenRouter token — so
+ * teaching the Anthropic detector these wordings would fire a bogus fleet
+ * failover on every OpenRouter 402. See the explicit early-return for
+ * `provider-credit-exhausted` in `resolveModelUnavailableFromOperatorEvent`.
+ *
+ * PROVENANCE of each wording (verified against live vendor docs 2026-07-28):
+ *  - OpenRouter — https://openrouter.ai/docs/api-reference/errors:
+ *    "402: Your account or API key has insufficient credits. Add more credits
+ *    and retry the request." Typed error code `payment_required`. The limits
+ *    page (https://openrouter.ai/docs/api-reference/limits) documents the same
+ *    402 for both an exhausted ACCOUNT balance and an exhausted PER-KEY
+ *    `limit_remaining`.
+ *  - OpenAI — https://platform.openai.com/docs/guides/error-codes: 429 with
+ *    `code: "insufficient_quota"`, message "You exceeded your current quota,
+ *    please check your plan and billing details"; hard billing stop surfaces as
+ *    `billing_hard_limit_reached`. NOTE the status is 429, NOT 402 — which is
+ *    exactly why status alone is not a sufficient signal and the wording list
+ *    carries its own weight.
+ *  - Perplexity — https://docs.perplexity.ai/guides/usage-tiers: an exhausted
+ *    balance answers 401/403 with "insufficient credits"/"credit balance"; the
+ *    account is otherwise valid. Perplexity reaches switchroom through the MCP
+ *    tool surface, not through LiteLLM, so this registry is consumed there too
+ *    (`mcp-credential-failure.ts`) — one registry, both paths.
+ *
+ * Pure module: no IPC, no bot, no FS, no network. Trivially unit-testable.
+ */
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface ProviderCreditEntry {
+  /** Stable id — also the `mcp_servers.<name>` key where one exists. */
+  id: string
+  /** Human display name for the operator card. */
+  label: string
+  /**
+   * The VAULT KEY NAME the operator must top up / re-issue. A NAME only —
+   * this module never sees, reads, or renders a secret VALUE.
+   */
+  vaultKey: string
+  /** Where the operator actually fixes it. */
+  consoleUrl: string
+  /** The one-line remedy sentence rendered on the operator card. */
+  action: string
+  /**
+   * Lowercase substrings that ATTRIBUTE an error to this provider. Matched
+   * against the raw error text. Deliberately specific (hostnames, route
+   * prefixes, SDK exception names) so a passing mention can't misattribute.
+   */
+  markers: string[]
+}
+
+/**
+ * The providers whose credit exhaustion switchroom can recognise. Adding a
+ * provider is a DATA edit here — never a new conditional at a call site.
+ */
+export const PROVIDER_CREDIT_REGISTRY: readonly ProviderCreditEntry[] = [
+  {
+    id: 'openrouter',
+    label: 'OpenRouter',
+    vaultKey: 'openrouter/api-key',
+    consoleUrl: 'https://openrouter.ai/credits',
+    action: 'Top up the OpenRouter balance (or raise the key’s credit limit) in the OpenRouter console.',
+    markers: ['openrouter', 'openrouter.ai'],
+  },
+  {
+    id: 'openai',
+    label: 'OpenAI',
+    vaultKey: 'openai/api-key',
+    consoleUrl: 'https://platform.openai.com/settings/organization/billing',
+    action: 'Add credit / raise the billing limit in the OpenAI console.',
+    markers: ['api.openai.com', 'openai.', 'openaiexception', 'openai_api'],
+  },
+  {
+    id: 'perplexity',
+    label: 'Perplexity',
+    vaultKey: 'perplexity/api-key',
+    consoleUrl: 'https://www.perplexity.ai/settings/api',
+    action: 'Top up the Perplexity API balance (or re-issue the key) in the Perplexity console.',
+    markers: ['perplexity', 'api.perplexity.ai', 'pplx'],
+  },
+]
+
+// ─── Credit-exhaustion wording ───────────────────────────────────────────────
+
+/**
+ * Provider-agnostic markers of a CREDIT/BILLING wall — "there is no money
+ * left", as distinct from "you are going too fast" (rate limit) or "your key
+ * is wrong" (auth).
+ *
+ * Every entry is a multi-word phrase or an explicit vendor error CODE. A bare
+ * `'402'` is deliberately ABSENT: a three-digit substring appears in model ids,
+ * token counts, request ids and timestamps, and matching it would misclassify
+ * unrelated errors as a billing wall. HTTP 402 is honoured only as a STRUCTURED
+ * status field — see {@link isProviderCreditStatus}.
+ */
+export const CREDIT_EXHAUSTION_SIGNALS: readonly string[] = [
+  // OpenRouter (402)
+  'payment_required',
+  'payment required',
+  'insufficient credits',
+  'insufficient_credits',
+  'more credits are required',
+  'requires more credits',
+  'add more credits',
+  'out of credits',
+  // OpenAI (429 insufficient_quota / hard billing stop)
+  'insufficient_quota',
+  'exceeded your current quota',
+  'billing_hard_limit_reached',
+  'billing hard limit',
+  // Cross-vendor balance wordings (Perplexity, Brevo, and the generic shape)
+  'insufficient balance',
+  'insufficient_balance',
+  'credit balance is too low',
+  'credit balance too low',
+  'credit_balance_too_low',
+  'no credits remaining',
+  'quota exceeded for credits',
+]
+
+/** HTTP statuses that, on their own, mean "billing". Only 402 qualifies. */
+export const CREDIT_EXHAUSTION_STATUSES: readonly number[] = [402]
+
+const MAX_SCAN_CHARS = 16_384
+
+function sample(text: unknown): string {
+  if (typeof text !== 'string' || text.length === 0) return ''
+  return (text.length > MAX_SCAN_CHARS ? text.slice(0, MAX_SCAN_CHARS) : text).toLowerCase()
+}
+
+/**
+ * True when `status` is a structured HTTP status that means "out of credit".
+ * Structured only — never inferred from a substring (see the note on
+ * {@link CREDIT_EXHAUSTION_SIGNALS}).
+ */
+export function isProviderCreditStatus(status: unknown): boolean {
+  return typeof status === 'number' && CREDIT_EXHAUSTION_STATUSES.includes(status)
+}
+
+/** True when `text` carries an explicit credit/billing-exhaustion wording. */
+export function hasCreditExhaustionWording(text: unknown): boolean {
+  const lower = sample(text)
+  if (lower.length === 0) return false
+  return CREDIT_EXHAUSTION_SIGNALS.some(s => lower.includes(s))
+}
+
+/**
+ * Attribute an error string to a registered provider, or `null` when nothing
+ * in the text names one. `null` is a legitimate, honest outcome: the card then
+ * says "an upstream model provider" rather than guessing a vendor (and a wrong
+ * vendor name would send the operator to the wrong console).
+ */
+export function attributeProvider(text: unknown): ProviderCreditEntry | null {
+  const lower = sample(text)
+  if (lower.length === 0) return null
+  for (const entry of PROVIDER_CREDIT_REGISTRY) {
+    if (entry.markers.some(m => lower.includes(m))) return entry
+  }
+  return null
+}
+
+export interface ProviderCreditDetection {
+  /** The registry entry, when the text named a known provider. */
+  provider: ProviderCreditEntry | null
+  /** Which evidence fired — useful in logs and in the test assertions. */
+  via: 'status' | 'wording'
+}
+
+/**
+ * The single decision: is this error a THIRD-PARTY PROVIDER credit/billing
+ * wall? Returns `null` when it is not — callers then fall through to their
+ * existing classification unchanged.
+ *
+ * `status` is the structured HTTP status when the caller has one (an SDK throw,
+ * a LiteLLM error body with `"status": 402`). Omit it and the decision rests on
+ * wording alone.
+ *
+ * ANTHROPIC IS DELIBERATELY EXCLUDED. `credit_balance_too_low` is in the
+ * wording list because it is a genuine cross-vendor balance phrase, but an
+ * Anthropic-attributed credit wall already has its own `credit-exhausted` kind
+ * with slot-switch advice (`/auth use`). Callers keep that branch FIRST; this
+ * one only catches what that branch does not. See `classifyClaudeError`.
+ */
+export function detectProviderCreditExhaustion(
+  text: unknown,
+  status?: unknown,
+): ProviderCreditDetection | null {
+  if (isProviderCreditStatus(status)) {
+    return { provider: attributeProvider(text), via: 'status' }
+  }
+  if (hasCreditExhaustionWording(text)) {
+    return { provider: attributeProvider(text), via: 'wording' }
+  }
+  return null
+}
+
+/**
+ * The operator-facing remedy line for a detection. Names the provider, the
+ * VAULT KEY NAME (never a value) and the console to act in. Used by both the
+ * operator-event card and the MCP credential alert so the two speak with one
+ * voice.
+ */
+export function describeProviderCreditRemedy(provider: ProviderCreditEntry | null): string {
+  if (provider == null) {
+    return 'An upstream model provider reports no credit remaining. Check the provider console for the key the LiteLLM proxy uses.'
+  }
+  return `${provider.action} Vault key: \`${provider.vaultKey}\` → ${provider.consoleUrl}`
+}

package/telegram-plugin/scripts/bun-test-ci.sh

@@ -40,18 +40,48 @@ ATTEMPT_TIMEOUT="${BUN_TEST_ATTEMPT_TIMEOUT:-180}"
 KILL_AFTER="${BUN_TEST_KILL_AFTER:-30}"
 MAX_ATTEMPTS="${BUN_TEST_MAX_ATTEMPTS:-3}"
 
-# Same explicit dir list as the Buildkite/CI invocation — running `bun
-# test` with no args recurses into telegram-plugin/uat/scenarios/ which
-# need live Telegram creds. Keep this in sync with ci-tests-plugin.yml if
-# the surface changes. BUN_TEST_TARGETS (space-separated) overrides the
-# list — used only to exercise the watchdog against a narrow subset.
+# THE single source of truth for what the bun CI job runs — `bun test` with
+# no args recurses into telegram-plugin/uat/scenarios/, which needs live
+# Telegram creds. Both ci-tests-plugin.yml and ci-full.yml invoke this script
+# rather than re-typing the list (they used to keep hand-copied duplicates,
+# which is how a test file ends up in no runner at all — see
+# scripts/check-test-runner-coverage.mjs). BUN_TEST_TARGETS (space-separated)
+# overrides the list — used only to exercise the watchdog against a subset.
 if [ -n "${BUN_TEST_TARGETS:-}" ]; then
   # shellcheck disable=SC2206
   BUN_TEST_ARGS=(${BUN_TEST_TARGETS})
 else
   BUN_TEST_ARGS=(
-    admin-commands gateway registry secret-detect tests
+    # TRAILING SLASHES ARE LOAD-BEARING. A `bun test` positional is a plain
+    # SUBSTRING match on the file path, not a directory selector: the bare
+    # `gateway` this list used to carry also matched
+    # `uat/scenarios/vault-card-survives-gateway-restart-dm.test.ts`, quietly
+    # pulling a live-Telegram scenario into the ordinary bun-test job (it only
+    # stayed harmless because that scenario self-skips without creds). `gateway/`
+    # matches the directory and nothing else.
+    admin-commands/ gateway/ registry/ secret-detect/ tests/
     channel-envelope-safety.test.ts
+    # Hosted UAT unit tests: no creds, no live Telegram, no driver session.
+    # Named as specific files / the runners dir — never a bare `uat` — so the
+    # filter can NEVER widen into uat/scenarios/, which does hit real Telegram
+    # and must stay on the gated uat-host runner (ci-uat.yml) only.
+    #
+    # These ran in NEITHER CI runner before this change: vitest.config.ts
+    # excludes `**/telegram-plugin/uat/**` wholesale (right for scenarios/,
+    # collateral damage for these) and this list never named them. So
+    # feed-matcher.test.ts — whose own docblock calls it "the CI-verifiable
+    # floor" for the worker-feed matcher, and which #3821 extended with
+    # `stripCardNesting` assertions — was executed by nothing.
+    #
+    # They go on the BUN side rather than being un-excluded from vitest because
+    # three of them import `bun:test`, and uat/runners/skill-coverage.test.ts
+    # transitively imports uat/driver.ts → `@mtcute/node`, which vite's resolver
+    # cannot load out of the bun workspace layout (bun's resolver has no
+    # trouble). Fenced by scripts/check-test-runner-coverage.mjs.
+    uat/feed-matcher.test.ts
+    uat/load-env.test.ts
+    uat/uat-driver.test.ts
+    uat/runners/
   )
 fi
 

package/telegram-plugin/send-gate.ts

@@ -73,6 +73,7 @@ import {
   makeFloodWaitActiveError,
   isFloodWaitActiveError,
 } from './retry-api-call.js'
+import { withOutboundClass, type OutboundClass } from './outbound-class.js'
 
 /** Injectable time source. Default binds to real wall clock + setTimeout. */
 export interface Clock {
@@ -112,6 +113,20 @@ export type ChatType = 'private' | 'group' | 'supergroup' | 'channel'
  */
 export type PriorityClass = 'critical' | 'useful' | 'cosmetic'
 
+/**
+ * Compile-time lock: `PriorityClass` and `outbound-class.ts`'s `OutboundClass`
+ * must stay identical, because the gate publishes the former into the latter's
+ * AsyncLocalStorage so the edit-flood fuse (a grammY transformer, which sees
+ * only `(method, payload)`) can tell a repaint from a reply. Adding a class to
+ * one and not the other fails `tsc`, not review.
+ */
+type _ClassesMatch =
+  OutboundClass extends PriorityClass
+    ? PriorityClass extends OutboundClass ? true : never
+    : never
+const _classesMatch: _ClassesMatch = true
+void _classesMatch
+
 /**
  * Priority class an UNTAGGED non-edit send is admitted as. `critical` =
  * non-droppable (L2). See the `PriorityClass` doc above.
@@ -1130,7 +1145,13 @@ export function createSendGate(config: SendGateConfig): SendGate {
           // the fact that the only production caller is `robustApiCall`, whose
           // own request/retry timeouts bound every send — so `p.fn()` is
           // guaranteed to settle. No separate watchdog is needed here.
-          const res = await p.fn()
+          // Publish the class for the edit-flood fuse (a grammY transformer
+          // downstream of here, which otherwise cannot tell a cosmetic repaint
+          // from an approval-card edit). `p.priorityClass` is the COALESCED
+          // class — a cosmetic edit that a `useful` one superseded is sent as
+          // `useful`, which is exactly what should happen: the frame going out
+          // carries the higher-priority payload.
+          const res = await withOutboundClass(p.priorityClass, () => p.fn())
           // M1: only record the payload as on-screen AFTER a successful send,
           // so a FAILED edit can be retried with the same payload (not dropped
           // as a phantom no-op).
@@ -1363,7 +1384,8 @@ export function createSendGate(config: SendGateConfig): SendGate {
 
     try {
       // N4: count `sent` only AFTER a successful send, mirroring the edit path.
-      const res = await fn()
+      // Class published for the fuse — see the edit path's call above.
+      const res = await withOutboundClass(priority, () => fn())
       counters.sent++
       return res
     } catch (err) {

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

@@ -83,6 +83,16 @@ export const NESTED_PREFIX = '   ↳ '
  * (2+ worker) card — three U+2800 BRAILLE PATTERN BLANK, written as escapes so
  * the bytes are visible in source.
  *
+ * This is now the ONLY indent any card carries (#3842). #3820/#3821 also
+ * indented the whole worker card by one level and prefixed line 1 with `└─ `,
+ * which cost a level of horizontal space on a phone and asserted a
+ * parent/child relationship that is not always true (the worker card does not
+ * always sit below the agent card). That whole-card subordination is gone:
+ * every card is flush at the left margin, and this indent survives for the one
+ * job that genuinely needs it — telling one worker's step lines apart from the
+ * next worker's on the combined card, where the numbered row headers stay
+ * flush and their steps sit one level in.
+ *
  * ── Why not ASCII, and why not U+00A0 ────────────────────────────────
  * Card bodies reach Telegram as raw GFM markdown (`richMessage` →
  * `sendRichMessage` / `editMessageText({ markdown })`, #2669) and are parsed
@@ -125,51 +135,3 @@ export const NESTED_PREFIX = '   ↳ '
  */
 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

@@ -1,11 +1,23 @@
 /**
- * Status-pin driver — executes a PinAction against a Telegram Bot API.
+ * Status-pin driver — executes ONE already-decided `PinLegAction` against a
+ * Telegram Bot API.
  *
- * The pure decision lives in `status-pin.ts` (decidePinAction). This
- * module is the side-effecting half: takes the previously-claimed state
- * and the desired state, computes ONE action, executes it, and returns
- * the next state. The state itself stays in the caller (the gateway holds
- * a `Map<pinKey, PinState>` and re-passes the entry on every call).
+ * The pure decision lives in `status-pin.ts` (`decidePinAction`) and is taken
+ * exactly ONCE per leg, by the orchestrator (`gateway/status-pin-retarget.ts`).
+ * This module is the side-effecting half only: it is HANDED a leg action,
+ * executes it, and returns the next claim. The state itself stays in the caller
+ * (the gateway holds a `Map<pinKey, StatusPinClaim>` and re-passes the entry on
+ * every call).
+ *
+ * #3831 — why this takes an ACTION and not a `desired` state. It used to take
+ * `(prevState, desired)` and re-run `decidePinAction` itself, which meant one
+ * reconcile decided the same transition up to THREE times (orchestrator leg
+ * split → persist-op mapping → driver) and, worse, gave the driver a `repin`
+ * branch to implement. That branch expanded the retarget a SECOND time, with no
+ * per-leg persistence, and was unreachable from the gateway — a dead fork that
+ * a future caller wiring `reconcilePin` directly would have silently inherited.
+ * The parameter type is now `PinLegAction`, which cannot express `repin`, so
+ * the expansion exists in one place and cannot re-fork.
  *
  * Copied from `slot-banner-driver.ts`. The load-bearing contract (see
  * slot-banner-driver.ts:100-110):
@@ -36,8 +48,8 @@
  * job spec.
  */
 
-import type { PinState, DesiredPin, PinRightsCache } from './status-pin.js'
-import { decidePinAction, isPinRightsError, isUnpinTerminalError } from './status-pin.js'
+import type { PinState, PinLegAction, PinRightsCache } from './status-pin.js'
+import { isPinRightsError, isUnpinTerminalError } from './status-pin.js'
 
 /** Minimal subset of grammy's `bot.api` the pin driver depends on.
  *  Lets tests swap in a fake without dragging in the full Bot type. */
@@ -53,13 +65,13 @@ export interface PinBotApi {
   ): Promise<unknown>
 }
 
-export interface ReconcilePinArgs {
+export interface ExecutePinLegArgs {
   api: PinBotApi
   chatId: string
   /** State the caller is holding from the last reconcile. `null` on first. */
   prevState: PinState | null
-  /** What the caller wants pinned for this key right now. */
-  desired: DesiredPin
+  /** The single transition to execute, decided by the orchestrator. */
+  action: PinLegAction
   /** Optional API-failure observer. Default: silent. */
   onError?: (phase: 'pin' | 'unpin', err: unknown) => void
   /** Optional per-process rights-aware negative cache (issue #3024). When a
@@ -75,9 +87,9 @@ export interface ReconcilePinArgs {
 }
 
 /**
- * Execute the next pin-state transition for one key. Returns the new
- * `PinState` (or `null` when unpinned / nothing pinned). Always resolves;
- * never throws — API errors route through `onError`.
+ * Execute ONE decided pin transition for a key. Returns the new `PinState`
+ * (or `null` when unpinned / nothing pinned). Always resolves; never throws —
+ * API errors route through `onError`.
  *
  *   - `pin`  : pins the existing message SILENTLY; on failure the claim is
  *              NOT taken (returns prevState) so the next reconcile retries
@@ -86,43 +98,19 @@ 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.
+ *
+ * A RETARGET is NOT executable here by construction — `PinLegAction` has no
+ * `repin` member. `runStatusPinReconcile` splits it into an unpin leg and a pin
+ * leg, each persisted, and owns the abort rule (#3831).
  */
-export async function reconcilePin(
-  args: ReconcilePinArgs,
+export async function executePinLeg(
+  args: ExecutePinLegArgs,
 ): Promise<PinState | null> {
-  const action = decidePinAction(args.prevState, args.desired)
+  const { action } = args
 
   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

@@ -38,7 +38,21 @@ export type DesiredPin =
   /** Work is done (or never opened a message); nothing should be pinned. */
   | { pinned: false }
 
-export type PinAction =
+/**
+ * A SINGLE, directly-executable pin transition — the only shape the driver
+ * (`status-pin-driver.ts`) can execute.
+ *
+ * The type is deliberately narrower than `PinAction`: it structurally EXCLUDES
+ * `repin`. That exclusion is the mechanism (#3831) that keeps the retarget
+ * expansion — "a repin is an unpin leg then a pin leg, and a never-confirmed
+ * unpin aborts the pin leg" — defined in exactly ONE place
+ * (`gateway/status-pin-retarget.ts`). It used to be written twice, once in the
+ * driver with no per-leg persistence and once in the orchestrator with it; the
+ * driver copy was unreachable in production and silently carried the weaker
+ * semantics. A driver that cannot NAME a repin cannot re-grow a second copy of
+ * it — the compiler enforces what a comment could not.
+ */
+export type PinLegAction =
   | { kind: 'noop'; reason: string }
   /** Pin an EXISTING message. Caller pins, then records the message_id
    *  back into PinState. No new message is sent — this pins a message the
@@ -48,6 +62,9 @@ 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 }
+
+export type PinAction =
+  | PinLegAction
   /**
    * 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

package/telegram-plugin/tests/card-golden.test.ts

@@ -0,0 +1,69 @@
+/**
+ * GOLDEN SUITE — every status/progress card variant, pinned byte-for-byte.
+ *
+ * Why this exists: card rendering now flows through ONE layout core
+ * (`card-layout.ts`). That is the point — but it also means a change made for
+ * one card silently reshapes the other twenty. This suite is the alarm: it
+ * renders all variants in `card-variants.ts` through the real renderers and
+ * compares the exact wire text against a checked-in golden file. Any diff, in
+ * any card, fails.
+ *
+ * Regenerate deliberately (and read the diff in the PR):
+ *   UPDATE_CARD_GOLDEN=1 npx vitest run telegram-plugin/tests/card-golden.test.ts
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+import { CARD_VARIANTS, GOLDEN_DELIMITER, renderGoldenDocument } from './card-variants.js'
+
+const GOLDEN_PATH = join(dirname(fileURLToPath(import.meta.url)), 'card-variants.golden.txt')
+
+describe('card golden suite', () => {
+  it('every card variant renders exactly its pinned golden text', () => {
+    const actual = renderGoldenDocument()
+    if (process.env.UPDATE_CARD_GOLDEN === '1') {
+      writeFileSync(GOLDEN_PATH, actual, 'utf8')
+    }
+    const expected = readFileSync(GOLDEN_PATH, 'utf8')
+    // Compare per-variant first: a one-card regression should name that card,
+    // not dump a 21-card diff.
+    const split = (doc: string): Map<string, string> => {
+      const out = new Map<string, string>()
+      for (const chunk of doc.split(GOLDEN_DELIMITER).slice(1)) {
+        const nl = chunk.indexOf('\n')
+        out.set(chunk.slice(0, nl).trim(), chunk.slice(nl + 1))
+      }
+      return out
+    }
+    const exp = split(expected)
+    const act = split(actual)
+    for (const [name, body] of act) {
+      expect(exp.has(name), `golden has no entry for "${name}" — regenerate it`).toBe(true)
+      expect(body, `card "${name}" no longer renders its golden text`).toBe(exp.get(name))
+    }
+    // And the whole document, so a REMOVED or reordered variant also fails.
+    expect(actual).toBe(expected)
+  })
+
+  it('the golden covers every variant in the catalogue and nothing else', () => {
+    const golden = readFileSync(GOLDEN_PATH, 'utf8')
+    const namesInGolden = golden
+      .split(GOLDEN_DELIMITER)
+      .slice(1)
+      .map((c) => c.slice(0, c.indexOf('\n')).trim())
+    expect(namesInGolden).toEqual(CARD_VARIANTS.map((v) => v.name))
+    // Guards against a fixture that silently stops rendering (e.g. a renderer
+    // starting to return null) and thus stops asserting anything real.
+    expect(namesInGolden.length).toBeGreaterThanOrEqual(21)
+  })
+
+  it('no variant renders empty or null', () => {
+    for (const v of CARD_VARIANTS) {
+      const text = v.render()
+      expect(text, `variant "${v.name}" rendered null`).not.toBeNull()
+      expect((text ?? '').trim().length, `variant "${v.name}" rendered empty`).toBeGreaterThan(0)
+    }
+  })
+})