switchroom 0.18.15 → 0.18.18

package/telegram-plugin/gateway/linear-activity.ts

@@ -297,11 +297,20 @@ export async function emitLinearAgentActivity(
   return { content: [{ type: 'text', text: `Linear ${type} emitted on session ${sessionId}` }] }
 }
 
+/** The exact HTML-comment carrying a capture's dedup key. Both the embed
+ *  (captureDedupMarker) and the dedup lookup match on this precise string, so a
+ *  re-capture is confirmed by exact-key equality, not fuzzy search relevance.
+ *  The trailing ` -->` and leading `: ` anchor the key so `abc` never matches
+ *  `abcd`. */
+export function captureDedupComment(dedupKey: string): string {
+  return `<!-- switchroom-capture: ${dedupKey} -->`
+}
+
 /** Hidden marker appended to a captured issue's description so a re-capture of
  *  the same Telegram message can be detected (dedup backstop; the gateway-side
  *  seen-set is the primary, race-free guard). */
 export function captureDedupMarker(dedupKey: string): string {
-  return `\n\n<!-- switchroom-capture: ${dedupKey} -->`
+  return `\n\n${captureDedupComment(dedupKey)}`
 }
 
 /**
@@ -390,19 +399,26 @@ export async function createLinearIssue(
   }
 
   // Dedup backstop: search for a prior capture of the same Telegram message.
+  // `searchIssues` is a relevance-ranked full-text search, so its top hit for a
+  // key can be an unrelated issue that merely shares tokens. We therefore only
+  // treat a result as a dedup match when its description carries the EXACT
+  // capture marker for this key, never the raw top hit.
   if (dedupKey) {
+    const marker = captureDedupComment(dedupKey)
     const search = await gql(
-      'query($term: String!) { searchIssues(term: $term) { nodes { id url title } } }',
+      'query($term: String!) { searchIssues(term: $term, first: 25) { nodes { id url title description } } }',
       { term: dedupKey },
     )
     if (search.ok) {
-      const hit = (search.data?.searchIssues?.nodes ?? [])[0] as { url?: string } | undefined
+      const nodes = (search.data?.searchIssues?.nodes ?? []) as Array<{ url?: string; description?: string }>
+      const hit = nodes.find((n) => typeof n.description === 'string' && n.description.includes(marker))
       if (hit?.url) {
         log(`telegram gateway: linear_create_issue: dedup hit key=${dedupKey} agent=${agent}\n`)
         return { content: [{ type: 'text', text: `Already filed: ${hit.url}` }] }
       }
     }
-    // a failed search is non-fatal — fall through to create (gateway seen-set is primary).
+    // a failed search or no exact-marker match is non-fatal — fall through to
+    // create (gateway seen-set is the primary, race-free guard).
   }
 
   // Resolve the team.

package/telegram-plugin/gateway/litellm-local-notice-wiring.ts

@@ -0,0 +1,200 @@
+/**
+ * litellm-local-notice-wiring.ts — side-effect runner for the debounced
+ * litellm-local 429 notice.
+ *
+ * The state machine, notice text, config parsing, and metric payload live in
+ * ../litellm-local-notice.ts (pure). This module owns the sequencing, with
+ * every dependency injected so the wiring is unit-testable without importing
+ * gateway.ts (same shape as throttle-tier-wiring.ts):
+ *
+ *   1. Guard — only the `litellm-local` classification is eligible
+ *      (isLitellmLocalNoticeEligible). account-scoped keeps the throttle
+ *      tier; generic-transient keeps the calm rate-limited card. The guard
+ *      lives HERE (not in the caller) so "a notice never fires for
+ *      non-litellm-local classifications" is mechanism, not discipline.
+ *   2. Per-agent cooldown — evaluate against the resolved window
+ *      (deps.windowMs(), re-read per event so an operator-tuned
+ *      channels.telegram.litellm_notice.window_ms takes effect after
+ *      apply+restart without re-creating the runner). Suppressed events are
+ *      counted silently.
+ *   3. ONE calm notice — broadcast to every authorized chat via the injected
+ *      send (the gateway binds it to swallowingApiCall, the standard
+ *      retry-wrapped path). The window is armed, the
+ *      `litellm_local_429_notice` metric emitted, and "posted" logged ONLY
+ *      when at least one send was actually ISSUED — an empty allowFrom or a
+ *      send callback that throws for every chat leaves the state untouched,
+ *      so the next event retries instead of silently claiming delivery.
+ *
+ * Deliberately NO broker calls, NO quota-ledger writes, NO failover, NO
+ * retry nudge: the litellm-local calm path's invariant is that account state
+ * is never touched (the request never reached Anthropic). Claude Code's own
+ * retry handles the turn.
+ */
+
+import {
+  buildLitellmLocalNoticeMetric,
+  evaluateLitellmLocalNotice,
+  initialLitellmLocalNoticeState,
+  isLitellmLocalNoticeEligible,
+  renderLitellmLocalNotice,
+  type LitellmLocalNoticeState,
+} from '../litellm-local-notice.js'
+import type { RateLimit429Classification } from '../throttle-tier.js'
+import type { RuntimeMetricEvent } from '../runtime-metrics.js'
+
+/**
+ * The user-facing surface decision for one terminal non-account-scoped
+ * `rate-limited` operator event — the gateway's ordering contract with the
+ * shared per-agent-per-kind card cooldown (shouldEmitOperatorEvent in
+ * operator-events.ts), extracted so it is pinnable by tests:
+ *
+ *   - `litellm-local` resolves BEFORE the shared gate is consulted. Two
+ *     load-bearing consequences: (a) it never ARMS `${agent}:rate-limited`
+ *     (shouldEmitOperatorEvent's true-return records the timestamp), so a
+ *     proxy-cap burst can't suppress a later genuine transient's card; and
+ *     (b) it is never SUPPRESSED by a cooldown that a recent 529 / generic
+ *     card armed — the notice runner owns its own per-agent debounce
+ *     instead.
+ *   - Every other classification consults (and on true, arms) the shared
+ *     gate exactly once — the caller must NOT re-consult it downstream.
+ */
+export function decideRateLimitedSurface(opts: {
+  classification: RateLimit429Classification
+  agent: string
+  /** The shared cooldown gate — gateway binds
+   *  (a) => shouldEmitOperatorEvent(a, 'rate-limited'). Consulted (and on
+   *  true, armed) only for non-litellm-local classifications. */
+  shouldEmitCard: (agent: string) => boolean
+}): 'litellm-local-notice' | 'generic-card' | 'cooldown-suppressed' {
+  if (isLitellmLocalNoticeEligible(opts.classification)) return 'litellm-local-notice'
+  return opts.shouldEmitCard(opts.agent) ? 'generic-card' : 'cooldown-suppressed'
+}
+
+export interface LitellmLocalNoticeRunnerDeps {
+  /** Chats the notice broadcasts to (access.allowFrom, resolved per call). */
+  listNoticeChats(): Array<string | number>
+  /** Fire-and-forget rich send (gateway wraps swallowingApiCall). */
+  sendNotice(chatId: string | number, markdown: string): void
+  /** Resolved cooldown window (ms), re-read per event —
+   *  parseLitellmNoticeWindowMs(loadAccess().litellmNoticeWindowMs). */
+  windowMs(): number
+  /** Runtime-metric sink (gateway binds emitRuntimeMetric). */
+  emitMetric(event: RuntimeMetricEvent): void
+  log(msg: string): void
+  now?: () => number
+}
+
+/**
+ * What one event produced:
+ *   - `sent`       — a notice was issued to ≥1 chat (window armed, metric
+ *                    emitted). The gateway records the event into the
+ *                    operator-event history ONLY on this outcome, so a
+ *                    suppressed low-stakes proxy throttle never overwrites a
+ *                    more important most-recent event (e.g.
+ *                    credentials-expired) in /status enrichment.
+ *   - `suppressed` — inside the cooldown window; counted silently.
+ *   - `skipped`    — ineligible classification, no authorized recipients,
+ *                    every send failed synchronously, or an internal error
+ *                    (logged). No debounce state change.
+ */
+export type LitellmLocalNoticeOutcome = 'sent' | 'suppressed' | 'skipped'
+
+export interface LitellmLocalNoticeRunner {
+  /**
+   * Run the notice path for one terminal rate-limited operator event.
+   * No-ops (returns 'skipped') unless `classification` is `litellm-local`.
+   * Never throws.
+   */
+  onRateLimited(
+    classification: RateLimit429Classification,
+    agent: string,
+  ): LitellmLocalNoticeOutcome
+  /** Test/debug view of internal state. */
+  inspect(): { state: LitellmLocalNoticeState }
+}
+
+export function createLitellmLocalNoticeRunner(
+  deps: LitellmLocalNoticeRunnerDeps,
+): LitellmLocalNoticeRunner {
+  const now = deps.now ?? (() => Date.now())
+  // In-memory only — the debounce resets on gateway restart, so a sustained
+  // throttle can produce one extra notice per restart. Accepted trade-off:
+  // persisting a courtesy-surface cooldown isn't worth state-file plumbing,
+  // and the failure mode is one duplicate calm message, not a storm.
+  let state = initialLitellmLocalNoticeState()
+
+  function onRateLimited(
+    classification: RateLimit429Classification,
+    agent: string,
+  ): LitellmLocalNoticeOutcome {
+    try {
+      if (!isLitellmLocalNoticeEligible(classification)) return 'skipped'
+      const windowMs = deps.windowMs()
+      const verdict = evaluateLitellmLocalNotice(state, agent, now(), windowMs)
+      if (!verdict.send) {
+        state = verdict.next
+        deps.log(
+          `[litellm-local-notice] suppressed (cooldown) agent=${agent} ` +
+            `suppressedSoFar=${state.suppressedCountByAgent[agent] ?? 0}`,
+        )
+        return 'suppressed'
+      }
+      const chats = deps.listNoticeChats()
+      const markdown = renderLitellmLocalNotice({
+        agent,
+        suppressedSinceLastNotice: verdict.suppressedSinceLastNotice,
+      })
+      let issued = 0
+      for (const chatId of chats) {
+        try {
+          deps.sendNotice(chatId, markdown)
+          issued++
+        } catch (err) {
+          deps.log(
+            `[litellm-local-notice] send failed chat=${chatId} agent=${agent}: ` +
+              `${(err as Error)?.message ?? err}`,
+          )
+        }
+      }
+      if (issued === 0) {
+        // Nothing actually went out (no authorized chats, or every send
+        // threw synchronously). Do NOT arm the window, emit the metric, or
+        // claim "posted" — the next event retries instead of the debounce
+        // silently absorbing events no one will ever hear about.
+        deps.log(
+          `[litellm-local-notice] no sends issued (chats=${chats.length}) agent=${agent} — ` +
+            `window not armed, will retry on the next event`,
+        )
+        return 'skipped'
+      }
+      state = verdict.next
+      deps.emitMetric(
+        buildLitellmLocalNoticeMetric({
+          agent,
+          suppressedCount: verdict.suppressedSinceLastNotice,
+          windowMs,
+        }),
+      )
+      deps.log(
+        `[litellm-local-notice] posted agent=${agent} chats=${issued} ` +
+          `suppressedSinceLast=${verdict.suppressedSinceLastNotice} windowMs=${windowMs}`,
+      )
+      return 'sent'
+    } catch (err) {
+      // The notice is a courtesy surface — a failure here must never break
+      // the operator-event path that invoked it. The log itself is wrapped
+      // too: a dead stderr sink must not void the never-throws contract.
+      try {
+        deps.log(
+          `[litellm-local-notice] error agent=${agent}: ${(err as Error)?.message ?? err}`,
+        )
+      } catch { /* sink dead — nothing left to do */ }
+      return 'skipped'
+    }
+  }
+
+  return {
+    onRateLimited,
+    inspect: () => ({ state }),
+  }
+}

package/telegram-plugin/gateway/model-command.ts

@@ -108,6 +108,82 @@ export function parseModelCommand(text: string): ParsedModelCommand | null {
   return { kind: 'set', model: arg }
 }
 
+/**
+ * The busy state a typed `/model` disposition is decided against. Two
+ * independent signals are folded here (#3177): `currentTurnActive` is the
+ * gateway's per-turn atom (`currentTurn !== null`), which is NULLED at
+ * `turn_end`; `turnInFlight` is the authoritative delivery-machine +
+ * pending-approval gate (`turnInFlightForGate()`). The atom can read idle
+ * while the session is still busy (the "recovered-late" / premature-turn-end
+ * window seen in finn's 2026-07-12 log), so a switch decided on the atom ALONE
+ * takes the direct-inject path and types `/model <name>` into a still-busy
+ * pane, where claude swallows it as literal text — a silent no-op. Folding
+ * BOTH signals means a session busy by EITHER measure ack+queues instead.
+ */
+export interface ModelCommandContext {
+  /** Gateway per-turn atom is non-null (`currentTurn !== null`). */
+  currentTurnActive: boolean
+  /** Authoritative busy gate (`turnInFlightForGate()`): machine-in-turn OR a pending approval. */
+  turnInFlight: boolean
+  /** Interactive picker menu is enabled (`SWITCHROOM_MODEL_MENU !== '0'`). */
+  menuEnabled: boolean
+}
+
+/**
+ * True when the session is busy by EITHER busy signal. A typed `/model` set
+ * MUST NOT take the direct-inject path while this holds — it would type into a
+ * busy pane and be swallowed as text. See ModelCommandContext.
+ */
+export function isModelCommandBusy(ctx: Pick<ModelCommandContext, 'currentTurnActive' | 'turnInFlight'>): boolean {
+  return ctx.currentTurnActive || ctx.turnInFlight
+}
+
+/**
+ * What the gateway should do with a parsed `/model` command. Pure so the
+ * routing decision is unit-testable without booting the bot. Every parsed
+ * shape maps to exactly one visible action — there is NO branch that silently
+ * does nothing (the #3177 swallow):
+ *
+ *  - `menu`  — bare `/model` with the picker enabled → render the dashboard.
+ *  - `queue` — a `set` while busy (by EITHER signal) → ack + enqueue for
+ *              apply-on-idle. `target` is the alias-expanded token.
+ *  - `apply` — run the handler now (idle `set`, or `show`/`help` text paths).
+ */
+export type ModelCommandDisposition =
+  | { kind: 'menu' }
+  | { kind: 'queue'; target: string }
+  | { kind: 'apply'; parsed: ParsedModelCommand }
+
+export function planModelCommand(
+  parsed: ParsedModelCommand,
+  ctx: ModelCommandContext,
+): ModelCommandDisposition {
+  if (parsed.kind === 'show' && ctx.menuEnabled) return { kind: 'menu' }
+  if (parsed.kind === 'set' && isModelCommandBusy(ctx)) {
+    return { kind: 'queue', target: expandSrAlias(parsed.model) }
+  }
+  return { kind: 'apply', parsed }
+}
+
+/**
+ * The unconditional durable log line the gateway writes at `/model` entry,
+ * BEFORE any branch or reply attempt (#3177 guarantee (b)). Even if every
+ * downstream reply is shed/dropped, this line — plus the paired history row —
+ * guarantees a typed `/model` is never invisible. Kept pure + shape-stable so
+ * the format is testable and greppable (`grep 'gw /model received'`).
+ */
+export function modelCommandReceiptLine(
+  agent: string,
+  parsed: ParsedModelCommand,
+  busy: boolean,
+): string {
+  const arg =
+    parsed.kind === 'set' ? parsed.model
+      : parsed.kind === 'show' ? '(show)'
+        : '(help)'
+  return `telegram gateway: gw /model received agent=${agent} kind=${parsed.kind} arg=${arg} busy=${busy}`
+}
+
 export interface ModelCommandDeps {
   /** Inject primitive — wired to injectSlashCommand in the gateway. */
   inject: (agent: string, command: string) => Promise<InjectResult>
@@ -175,7 +251,7 @@ export interface ModelCommandReply {
 }
 
 const PERSIST_NOTE =
-  '_Sticky — persists across restarts, deploys, and crashes until \`/model default\` clears it (or the configured \`model:\` in switchroom.yaml changes, which resets it and notifies you). To change the default, set \`model:\` in switchroom.yaml._'
+  '_Session-only — this override lasts until the agent’s next restart, then reverts to the configured \`model:\`. \`/model default\` clears it now. To change the default permanently, set \`model:\` in switchroom.yaml._'
 
 function helpText(deps: ModelCommandDeps, reason?: string): ModelCommandReply {
   const srAliasExamples = Object.keys(SR_MODEL_ALIASES).map(a => `\`${a}\``).join(' · ')
@@ -507,18 +583,19 @@ export const SR_MODEL_ALIASES: Record<string, string> = {
 
 /** Expand a short alias (case-insensitive) to its full sr-* id, or return the original. */
 /**
- * #3042 review blocker 2a: can `token` be trusted for a DURABLE, boot-applied
- * `.session-model` persist WITHOUT a live confirmation from claude?
+ * #3042 review blocker 2a: can `token` be trusted for a boot-applied
+ * `.session-model` carrier persist WITHOUT a live confirmation from claude?
  *
  * A queued typed `/model <arg>` that is persisted at shutdown was never
- * validated by claude's picker — and under the keep-by-default boot (#3039)
- * a garbage-but-shape-valid token (e.g. `claude-nonexistnet-9`) would make
- * every boot run `claude --model <garbage>` with the gateway dead. Only
- * tokens with a switchroom-known meaning are offline-trustable: the static
- * Claude aliases (claude resolves them itself) and the curated sr-* alias
- * TARGETS (present in the LiteLLM config by construction). Full `claude-*` /
- * arbitrary `sr-*` ids typed by hand are refused — they need the live
- * session to verify, so the operator is asked to re-issue after boot.
+ * validated by claude's picker. Under the consume-once carrier (rev 4) a
+ * garbage-but-shape-valid token (e.g. `claude-nonexistnet-9`) can crash at
+ * most ONE boot before the carrier is gone and the agent reverts — but we
+ * still avoid even that crash-boot. Only tokens with a switchroom-known
+ * meaning are offline-trustable: the static Claude aliases (claude resolves
+ * them itself) and the curated sr-* alias TARGETS (present in the LiteLLM
+ * config by construction). Full `claude-*` / arbitrary `sr-*` ids typed by
+ * hand are refused — they need the live session to verify, so the operator is
+ * asked to re-issue after boot.
  */
 export function isOfflineTrustedModelToken(token: string): boolean {
   // #3043 item 1: the live accept path normalizes case (isClaudeModel /
@@ -833,18 +910,19 @@ export interface ModelCallbackOutcome {
   /**
    * The canonical `claude --model` token (alias or full `claude-*` id) for a
    * Claude selection, when derivable — distinct from `selectedModel` (a display
-   * name for /status). The gateway persists this to the durable
-   * `.session-model` override so the confirmed switch survives
-   * switchroom-managed relaunches (and, on an sr-* → Claude transition, its own
+   * name for /status). Session-scoped (rev 4): a live Claude selection persists
+   * NO carrier (the switch applies in-session and reverts on the next boot);
+   * the gateway uses this token ONLY on an sr-* → Claude transition, writing it
+   * to the consume-once `.session-model` carrier so that transition's own
+   * apply-relaunch boots the tapped model (then reverts on the following
    * restart). Absent when the target has no derivable token.
    */
   selectedModelToken?: string
   /**
    * True when the confirmed selection was the "Default (recommended)" row —
-   * i.e. the session is now on the configured default and any sticky
-   * `.session-model` override must be CLEARED (there is no token to persist;
-   * persisting nothing while leaving a stale override would re-apply the old
-   * model on the next keep-relaunch).
+   * i.e. the session is now on the configured default and any leftover
+   * `.session-model` carrier must be CLEARED (a stale carrier would be
+   * consumed — mis-applied — by the next boot).
    */
   clearedDefault?: boolean
   /** Short toast for answerCallbackQuery. */

package/telegram-plugin/gateway/pending-session-command.ts

@@ -244,15 +244,17 @@ export interface PendingCommandCardEdit {
 }
 
 /**
- * What the gateway should DURABLY record for a queued command that can't
- * apply live because the session is going away (gateway shutdown or a pending
- * session relaunch). #3039: instead of telling the operator to re-issue, the
- * choice is persisted to the durable carriers (`.session-model` /
- * `.session-effort`) that start.sh honors on every boot — so the queued
- * command still deterministically applies, just via the relaunch.
+ * What the gateway should record for a queued command that can't apply live
+ * because the session is going away (gateway shutdown or a pending session
+ * relaunch). Instead of telling the operator to re-issue, the choice is
+ * persisted to the CONSUME-ONCE boot carriers (`.session-model` /
+ * `.session-effort`, #3184/#3186): start.sh applies each on the single boot
+ * that reads it — the queued command's apply-relaunch — and then deletes it,
+ * so the queued command still deterministically applies via the relaunch and
+ * any SUBSEQUENT restart reverts to the configured default.
  *
- *   - 'model'        — persist `arg` as the `.session-model` override
- *   - 'effort'       — persist `arg` as the `.session-effort` override
+ *   - 'model'        — persist `arg` as the `.session-model` carrier
+ *   - 'effort'       — persist `arg` as the `.session-effort` carrier
  *   - 'clear-model'  — the queued command was `/model default`: clear the carrier
  *   - 'clear-effort' — the queued command was `/effort default`: clear the carrier
  *   - null           — not offline-resolvable (a `mdl:s:<tag>` menu selection

package/telegram-plugin/gateway/premium-recovery-wiring.ts

@@ -0,0 +1,122 @@
+/**
+ * premium-recovery-wiring.ts — the gateway GLUE for the "premium model
+ * recovered" ping, behind injected deps so the never-storm orchestration is
+ * unit-testable without importing the whole gateway (mirrors
+ * tier-downgrade-wiring.ts).
+ *
+ * The pure recovery predicate (`decidePremiumRecovery`), the honest wording +
+ * button (`renderPremiumRecoveryPing`), and the fleet-dedup key
+ * (`premiumRecoveryClaimKey`) all live in premium-recovery.ts. This module owns
+ * the ORDER-SENSITIVE side effects the gateway performs off that verdict — the
+ * P0 at-most-once guarantee a review cares about:
+ *
+ *   - the marker is READ first; a missing/corrupt marker is a no-op (no send);
+ *   - the pure decision gates the send: `fire === false` → NO clear, NO send
+ *     (the marker survives for a later tick once the tier actually recovers);
+ *   - a fleet-wide `claim-notification` gates against a bounce / concurrent
+ *     tick; on `!granted` the marker is cleared (so it can't linger and
+ *     re-attempt every tick) and we bail with NO send;
+ *   - on a GRANTED claim the marker is cleared BEFORE the send (never-storm:
+ *     at-most-once is the hard requirement — a transient send fault is covered
+ *     by the caller's retry policy, a double-send is not recoverable);
+ *   - EXACTLY ONE send per recorded chat, each carrying the session-scoped
+ *     `mdl:alias:<premium>` switch-back button (the SAME apply path as the model
+ *     menu — it does not bypass handleModelMenuCallback).
+ *
+ * Behaviour is a faithful extraction of the former inline
+ * `maybePremiumRecoveryPing`; the ordering above is preserved exactly.
+ */
+
+import {
+  renderPremiumRecoveryPing,
+  premiumRecoveryClaimKey,
+  type PremiumRecoveryPing,
+} from '../premium-recovery.js'
+import { MODEL_CALLBACK_ALIAS } from './model-command.js'
+
+/** The one-tap switch-back keyboard (single callback button). */
+export interface PremiumRecoveryKeyboard {
+  inline_keyboard: Array<Array<{ text: string; callback_data: string }>>
+}
+
+/** The minimal marker view the ping orchestration needs. */
+export interface PremiumRecoveryMarkerView {
+  /** The dropped premium `/model` token to offer switching back to. */
+  premiumModel: string
+  /** Chat ids to ping (the downgrade notice's allowFrom); may be empty → fallback. */
+  chats: string[]
+}
+
+export interface PremiumRecoveryPingDeps {
+  /** Bind-mounted agent state dir, or null when unresolvable (→ no-op). */
+  getAgentDir: () => string | null
+  /** Read the parsed `.premium-recovery` marker, or null when absent/corrupt. */
+  readMarker: (agentDir: string) => PremiumRecoveryMarkerView | null
+  /** Delete the marker (consume-once). Best-effort. */
+  clearMarker: (agentDir: string) => void
+  /** The agent name (for the fleet-dedup claim key). */
+  getAgent: () => string
+  /** The pure recovery predicate, bound to THIS tick's live accounts. Returns
+   *  whether to fire (the marker is already known present when this is called). */
+  decide: () => boolean
+  /** Fleet-wide at-most-once claim for this premium token. Returns granted
+   *  (fail-open: true on any broker error → degrades to at-least-once). */
+  claimNotification: (claimKey: string) => Promise<boolean>
+  /** Fallback chats when the marker records none (parity with the inline path). */
+  fallbackChats: () => string[]
+  /** Send the recovery ping (with the switch-back keyboard) to ONE chat. */
+  sendToChat: (
+    chatId: string,
+    ping: PremiumRecoveryPing,
+    keyboard: PremiumRecoveryKeyboard,
+  ) => void
+  /** Structured logger (stderr in prod, captured in test). */
+  log: (msg: string) => void
+}
+
+/**
+ * Run the premium-recovery ping glue. No-op unless a marker is pending, the
+ * pure decision says fire, and the fleet claim is granted — then clears the
+ * marker BEFORE fanning out exactly one send per chat. Async because the claim
+ * is a broker round-trip; the caller `.catch`es (a convenience ping is never
+ * allowed to throw the quota-watch tick).
+ */
+export async function runPremiumRecoveryPing(deps: PremiumRecoveryPingDeps): Promise<void> {
+  const agentDir = deps.getAgentDir()
+  if (!agentDir) return
+  const marker = deps.readMarker(agentDir)
+  if (marker == null) return
+  // Pure decision gate: on `false` leave the marker in place (a later tick fires
+  // once the tier recovers) — no clear, no claim, no send.
+  if (!deps.decide()) return
+  const agent = deps.getAgent()
+  // Fleet-wide dedup: a fresh gateway boot or a second tick inside the window
+  // must not re-send. Fail-open — a convenience ping degrades to at-least-once,
+  // never lost.
+  const granted = await deps.claimNotification(
+    premiumRecoveryClaimKey(agent, marker.premiumModel),
+  )
+  if (!granted) {
+    // Another gateway already owns this recovery ping — consume our marker so it
+    // can't linger and re-attempt every tick, and bail (NO send).
+    deps.clearMarker(agentDir)
+    return
+  }
+  // Consume the marker BEFORE sending (never-storm: at-most-once is the hard
+  // requirement for this ping; a transient send fault is covered by the
+  // caller's retry policy, whereas a double-send is not recoverable).
+  deps.clearMarker(agentDir)
+  const ping = renderPremiumRecoveryPing(marker.premiumModel)
+  const keyboard: PremiumRecoveryKeyboard = {
+    inline_keyboard: [
+      [{ text: ping.buttonText, callback_data: `${MODEL_CALLBACK_ALIAS}${marker.premiumModel}` }],
+    ],
+  }
+  const chats = marker.chats.length > 0 ? marker.chats : deps.fallbackChats()
+  for (const chatId of chats) {
+    deps.sendToChat(chatId, ping, keyboard)
+  }
+  deps.log(
+    `[premium-recovery] ${marker.premiumModel} servable again — ping sent agent=${agent} chats=${chats.length}`,
+  )
+}