switchroom 0.18.14 → 0.18.17

package/telegram-plugin/gateway/gateway.ts

@@ -320,11 +320,14 @@ import {
   type ModelUnavailableDetection,
 } from '../model-unavailable.js'
 import {
+  build429ClassifiedMetric,
+  classify429Detail,
   decideThrottleTier,
-  isAccountScopedThrottle,
   throttleRetryInPlaceMaxMs,
 } from '../throttle-tier.js'
 import { createThrottleTierRunner } from './throttle-tier-wiring.js'
+import { parseLitellmNoticeWindowMs } from '../litellm-local-notice.js'
+import { createLitellmLocalNoticeRunner, decideRateLimitedSurface } from './litellm-local-notice-wiring.js'
 import { runFleetAutoFallback, renderFallbackFailureNotice, evaluateFallbackFailureNotice, evaluateAllBlockedNotice, type FallbackFailureNoticeState, type FallbackAllBlockedNoticeState } from '../auto-fallback-fleet.js'
 import { startRestartWatchdog } from './restart-watchdog.js'
 import { validateStringArray } from './access-validator.js'
@@ -435,6 +438,8 @@ import { injectSlashCommand as injectSlashCommandImpl } from '../../src/agents/i
 import { handleInjectCommand, type InjectDeps } from './inject-handler.js'
 import {
   parseModelCommand,
+  planModelCommand,
+  modelCommandReceiptLine,
   handleModelCommand,
   buildModelMenu,
   handleModelMenuCallback,
@@ -460,18 +465,9 @@ import {
   readSessionModelFileRaw,
   restoreSessionModelFileRaw,
   clearSessionModelFile,
-  clearSessionModelBootAttempts,
   readConfiguredDefaultModel,
-  writeRelaunchModelIntent,
-  clearRelaunchModelIntent,
-  intentForRestartReason,
-  readSessionModelFile,
-  RELAUNCH_MODEL_INTENT_FILE,
-  GATEWAY_SHUTDOWN_INTENT_REASON_PREFIX,
-  clearStaleGatewayShutdownIntent,
   writeSessionEffortFile,
   clearSessionEffortFile,
-  readSessionEffortFile,
 } from './session-model-file.js'
 import { discoverModels, selectModel } from '../../src/agents/model-picker.js'
 import { resolveMainModel, SWITCHROOM_DEFAULT_THINKING_EFFORT } from '../../src/agents/scaffold.js'
@@ -1096,16 +1092,10 @@ function triggerSelfRestart(
       )
       return false
     }
-    // Session-model stickiness (reference/rfcs/session-model-stickiness.md):
-    // boot default is REVERT, so every switchroom-managed bounce must stamp
-    // its intent BEFORE the SIGTERM is even scheduled (write-before-kill
-    // invariant — pinned by gateway-session-model-relaunch.test.ts). The
-    // per-reason table classifies recovery/model-switch bounces as "keep"
-    // and the deliberate inline restart button as "revert".
-    {
-      const smDir = resolveAgentDirFromEnv()
-      if (smDir) writeRelaunchModelIntent(smDir, intentForRestartReason(reason), reason)
-    }
+    // Session-scoped /model (reference/rfcs/session-model-stickiness.md §0.1):
+    // a `.session-model` carrier is consume-once — start.sh applies it on the
+    // apply-relaunch and deletes it, so no boot needs a keep/revert intent. A
+    // switchroom-managed bounce simply reverts to the configured default.
     process.stderr.write(
       `telegram gateway: restart-via-SIGTERM-PID1 agent=${targetAgent} reason=${reason} (docker)\n`,
     )
@@ -1117,10 +1107,6 @@ function triggerSelfRestart(
     return true
   }
   // Legacy systemd path.
-  if (targetAgent === selfAgent) {
-    const smDir = resolveAgentDirFromEnv()
-    if (smDir) writeRelaunchModelIntent(smDir, intentForRestartReason(reason), reason)
-  }
   process.stderr.write(
     `telegram gateway: restart-via-systemctl agent=${targetAgent} reason=${reason}\n`,
   )
@@ -1140,24 +1126,6 @@ function triggerSelfRestart(
   }
 }
 
-// #3018 finding 4: a gateway-only bounce (supervisor relaunch, bare gateway
-// unit restart) leaves the shutdown handler's deploy-survival keep-intent
-// stamp on disk UNCONSUMED — start.sh only runs on a container-level boot.
-// If this gateway boot still sees a gateway-shutdown-stamped intent, the
-// preceding bounce was gateway-only: clear it so a genuine crash inside the
-// 10-min freshness window can't be converted into a "keep" (crash-reverts
-// policy intact). A real container stop/deploy consumes the file in start.sh
-// before any gateway boots, so a legitimate deploy stamp is never touched;
-// triggerSelfRestart / user-slash stamps use un-prefixed reasons.
-{
-  const bootSmDir = resolveAgentDirFromEnv()
-  if (bootSmDir != null && clearStaleGatewayShutdownIntent(bootSmDir)) {
-    process.stderr.write(
-      'telegram gateway: cleared stale gateway-shutdown relaunch-model intent (previous bounce was gateway-only — container never restarted)\n',
-    )
-  }
-}
-
 // Cached lazily — the claude CLI binary doesn't change inside a running
 // gateway process; on `switchroom update` the gateway restarts, refreshing this.
 let cachedClaudeCliVersion: string | null | undefined = undefined
@@ -1409,6 +1377,11 @@ type Access = {
   parseMode?: 'html' | 'markdownv2' | 'text'
   disableLinkPreview?: boolean
   coalescingGapMs?: number
+  /** Cooldown window (ms) for the litellm-local 429 notice — the debounced
+   *  "fleet token limiter engaged" message (litellm-local-notice.ts). Default
+   *  15 min when unset/invalid (parseLitellmNoticeWindowMs). Projected from
+   *  channels.telegram.litellm_notice.window_ms by scaffold. */
+  litellmNoticeWindowMs?: number
   /** A2: max media attachments folded into one coalesced turn. Default 10
    *  (a full Telegram album / forwarded burst arrives as one turn). Set 1 to
    *  restore single-attachment behaviour. Projected from
@@ -1563,6 +1536,7 @@ function readAccessFile(): Access {
       parseMode: parsed.parseMode,
       disableLinkPreview: parsed.disableLinkPreview,
       coalescingGapMs: parsed.coalescingGapMs,
+      litellmNoticeWindowMs: parsed.litellmNoticeWindowMs,
       coalesceMaxAttachments: parsed.coalesceMaxAttachments,
       interruptSafeBoundary: parsed.interruptSafeBoundary,
       interruptMaxWaitMs: parsed.interruptMaxWaitMs,
@@ -7700,14 +7674,99 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
   // through to the existing calm rate-limited card unchanged — an
   // account-scoped throttle would be the wrong action for a server-wide
   // condition.
+  //
+  // Classification is three-way (classify429Detail, throttle-tier.ts):
+  // only `account-scoped` may enter the throttle tier. `litellm-local` —
+  // the LiteLLM proxy's OWN tpm/rpm/router limiter tripping before the
+  // request reached Anthropic — takes the calm path with NO broker mark and
+  // NO failover: the condition is proxy-local and says nothing about the
+  // account. Every rate-limited event ALSO emits one
+  // `rate_limit_429_classified` runtime metric (PostHog + JSONL), fired
+  // here — before the cooldown gate — so operators can correlate
+  // account-scoped 429s with fleet TPM even when the card is suppressed.
   let throttleEscalation: ModelUnavailableDetection | null = null
   let escalationFired = false
-  if (kind === 'rate-limited' && isAccountScopedThrottle(event.detail)) {
+  // True when decideRateLimitedSurface already consulted (and armed) the
+  // shared per-kind card cooldown for this event — the gate below must not
+  // re-consult it, or the arm from the first consult would self-suppress.
+  let rateLimitedCooldownConsulted = false
+  const rateLimit429Classification =
+    kind === 'rate-limited' ? classify429Detail(event.detail) : null
+  if (rateLimit429Classification != null && rateLimit429Classification !== 'account-scoped') {
+    // litellm-local / generic-transient: the calm path. NO broker
+    // mark-throttled, NO throttle-tier runner, NO failover — for a
+    // proxy-local cap trip those would bench an account that was never
+    // touched.
+    emitRuntimeMetric(
+      build429ClassifiedMetric({
+        agent,
+        detail: event.detail,
+        classification: rateLimit429Classification,
+        action: 'calm',
+        now: Date.now(),
+      }),
+    )
+    // Surface decision — extracted (decideRateLimitedSurface,
+    // litellm-local-notice-wiring.ts) so the ordering contract with the
+    // shared per-kind card cooldown is pinnable by tests: litellm-local
+    // resolves BEFORE the gate (never arms `${agent}:rate-limited`, never
+    // suppressed by a cooldown a recent 529/generic card armed);
+    // generic-transient consults the gate exactly once HERE.
+    const surface = decideRateLimitedSurface({
+      classification: rateLimit429Classification,
+      agent,
+      shouldEmitCard: (a) => shouldEmitOperatorEvent(a, 'rate-limited'),
+    })
+    if (surface === 'litellm-local-notice') {
+      process.stderr.write(
+        `telegram gateway: 429 classified litellm-proxy-local agent=${agent} — ` +
+          `calm path, no account attribution, no failover\n`,
+      )
+      // The dedicated debounced notice REPLACES the generic "🚦 Rate limited"
+      // card for this classification only: one calm message naming the fleet
+      // token limiter (LiteLLM tpm_limit/rpm_limit) instead of a card that
+      // reads like an Anthropic account problem. Classification, quota-ledger,
+      // and failover behavior are untouched (nothing fired above on this
+      // branch). Record into history ONLY when a notice actually posted — a
+      // suppressed low-stakes proxy throttle must not overwrite a more
+      // important most-recent event (e.g. credentials-expired) in the
+      // /status enrichment (operator-events-history keeps the most recent
+      // event per agent).
+      const outcome = litellmLocalNoticeRunner.onRateLimited('litellm-local', agent)
+      if (outcome === 'sent') {
+        try {
+          recordOperatorEvent(event)
+        } catch { /* history is best-effort */ }
+      }
+      return
+    }
+    if (surface === 'cooldown-suppressed') {
+      process.stderr.write(
+        `telegram gateway: operator-event suppressed (cooldown) agent=${agent} kind=${kind}\n`,
+      )
+      return
+    }
+    // 'generic-card' — the gate passed (and armed) above; fall through to
+    // the existing calm rate-limited card without re-consulting it.
+    rateLimitedCooldownConsulted = true
+  }
+  if (rateLimit429Classification === 'account-scoped') {
     const throttleDecision = decideThrottleTier({
       detail: event.detail,
       now: Date.now(),
       thresholdMs: throttleRetryInPlaceMaxMs(),
     })
+    emitRuntimeMetric(
+      build429ClassifiedMetric({
+        agent,
+        detail: event.detail,
+        classification: 'account-scoped',
+        // decideThrottleTier can't return 'none' for account-scoped wording;
+        // map the two live actions onto the metric's vocabulary.
+        action: throttleDecision.action === 'failover' ? 'failover' : 'throttle',
+        now: Date.now(),
+      }),
+    )
     if (throttleDecision.action === 'throttle') {
       // Reset is near (≤ threshold) or unparseable (60s default): DO NOT
       // fail over. Record throttled_until broker-side, post ONE lightweight
@@ -7754,7 +7813,7 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
     }
   }
 
-  if (!shouldEmitOperatorEvent(agent, kind)) {
+  if (!rateLimitedCooldownConsulted && !shouldEmitOperatorEvent(agent, kind)) {
     process.stderr.write(
       `telegram gateway: operator-event suppressed (cooldown) agent=${agent} kind=${kind}\n`,
     )
@@ -10332,16 +10391,6 @@ const ipcServer: IpcServer = createIpcServer({
     // this call is safe wherever it sits relative to the cron early-return
     // above (#3038 review finding 5).
     bridgeDeadWatchdog.noteBridgeRegistered(client.agentName)
-    // #3043 item 2: a REAL bridge registering is proof the boot came all the
-    // way up healthy — clear start.sh's crashloop boot-attempts counter so only
-    // boots that genuinely fail BEFORE the bridge registers accumulate toward
-    // the 3-strike override clear. Without this, three quick operator
-    // hand-bounces of a healthy agent (each <150s apart) spuriously wipe a
-    // working model override. Best-effort; no-op when the file is absent.
-    if (client.agentName != null) {
-      const smBootDir = resolveAgentDirFromEnv()
-      if (smBootDir != null) clearSessionModelBootAttempts(smBootDir)
-    }
     client.send({ type: 'status', status: 'agent_connected' })
 
     // Phase 2b PR 3a — bridgeUp cutover. The state machine's `bridgeUp`
@@ -21775,15 +21824,10 @@ function buildModelDeps(restartCtx?: ModelDepsRestartContext): ModelMenuDeps & M
         })
       }
       stampUserRestartReason(reason)
-      // Model-switch restarts are switchroom-managed relaunches: the session
-      // override (written by the caller before this dispatch) must survive
-      // the bounce, so stamp keep-intent BEFORE dispatch (boot default is
-      // revert). hostd shells through `switchroom agent restart`, which
-      // deliberately writes no intent of its own.
-      {
-        const smDir = resolveAgentDirFromEnv()
-        if (smDir) writeRelaunchModelIntent(smDir, 'keep', reason)
-      }
+      // Model-switch restarts are the APPLY-relaunch for a `.session-model`
+      // carrier the caller wrote immediately above: start.sh consumes it on
+      // the very next boot (this dispatch's boot), then reverts thereafter.
+      // No keep/revert intent is needed — the carrier is consume-once.
       await sweepBeforeSelfRestart()
       const hostdResp = await tryHostdDispatch(name, {
         v: 1,
@@ -21804,14 +21848,11 @@ function buildModelDeps(restartCtx?: ModelDepsRestartContext): ModelMenuDeps & M
         return
       }
       // hostd is configured but returned an error/denied result. No restart
-      // is coming, so the keep-intent stamped above must not linger — a
-      // crash within its 10-min freshness window would wrongly KEEP.
+      // is coming, so the carrier the caller wrote must not linger to be
+      // consumed by an unrelated later boot — scheduleModelRelaunch's catch
+      // rolls it back on this throw.
       if (hostdResp.result !== 'started' && hostdResp.result !== 'completed') {
         clearRestartMarker()
-        {
-          const smDir = resolveAgentDirFromEnv()
-          if (smDir) clearRelaunchModelIntent(smDir)
-        }
         throw new Error(
           `hostd restart failed (result=${hostdResp.result}): ${hostdResp.error ?? '(no details)'}`,
         )
@@ -21820,11 +21861,11 @@ function buildModelDeps(restartCtx?: ModelDepsRestartContext): ModelMenuDeps & M
     /**
      * Switch TO a model that needs a relaunch (sr-* LiteLLM/OpenRouter ids,
      * which claude's native `/model` picker rejects, and the sr-to-claude
-     * direction). Write the DURABLE `.session-model` override (start.sh
-     * applies it on every keep-relaunch boot and launches `claude --model
-     * <token>`), set the in-memory session-model so /status stays honest
-     * across the restart window, then run the SAME restart dispatch as
-     * scheduleRestart above — which stamps the keep-intent this boot needs.
+     * direction). Write the CONSUME-ONCE `.session-model` carrier (start.sh
+     * applies it on the very next boot — this dispatch's apply-relaunch — and
+     * deletes it, so it reverts on any subsequent restart), set the in-memory
+     * session-model so /status stays honest across the restart window, then
+     * run the SAME restart dispatch as scheduleRestart above.
      */
     scheduleModelRelaunch: async (model: string, reason: string) => {
       const agentDir = resolveAgentDirFromEnv()
@@ -21841,20 +21882,15 @@ function buildModelDeps(restartCtx?: ModelDepsRestartContext): ModelMenuDeps & M
       try {
         await deps.scheduleRestart(reason)
       } catch (err) {
-        // A restart already in flight OWNS the override we just wrote — its
-        // boot (stamped keep by the in-flight path's own intent, last-writer-
-        // wins) will apply our token, so the switch is queued, not lost: keep
-        // the file + override and let the caller tell the operator "~15s".
-        // Any OTHER dispatch failure means no restart is coming, so roll BOTH
-        // back — a lingering file/override would lie to /status and
-        // mis-launch the NEXT relaunch. The keep-intent goes with them
-        // (belt-and-braces: scheduleRestart's failure branch clears it too):
-        // a fresh keep on disk with no restart coming would wrongly KEEP
-        // across a crash inside its 10-min window.
+        // A restart already in flight OWNS the carrier we just wrote — its
+        // boot will consume+apply our token, so the switch is queued, not
+        // lost: keep the file + override and let the caller tell the operator
+        // "~15s". Any OTHER dispatch failure means no restart is coming, so
+        // roll BOTH back — a lingering carrier would lie to /status and be
+        // consumed (mis-applied) by an unrelated later boot.
         if ((err as { code?: string })?.code !== 'restart_in_flight') {
           restoreSessionModelFileRaw(agentDir, prevFileRaw)
           sessionModelSource.setOverride(prevOverride)
-          clearRelaunchModelIntent(agentDir)
         }
         throw err
       }
@@ -21875,19 +21911,24 @@ function modelMenuReplyMarkup(reply: ModelMenuReply): InlineKeyboard | undefined
 
 /**
  * Record a POSITIVELY-CONFIRMED typed `/model` switch: set the in-memory
- * override so `/status` reflects the live model and persist the sticky
- * `.session-model` carrier. Shared by the live `bot.command('model')` handler
- * and the deferred (queued mid-turn) apply so both record identically. Returns
- * a persist-warning suffix to append to the reply body (empty when clean).
+ * override so `/status` reflects the live model. Shared by the live
+ * `bot.command('model')` handler and the deferred (queued mid-turn) apply so
+ * both record identically. Returns a warning suffix to append to the reply
+ * body (currently always empty — kept for a stable signature).
  *
- * The `/status` honesty invariant lives here: only `reply.selectedModel`
- * (present only on a confirmed switch) records; an unverified inject records
- * nothing. `/model default` clears the carrier idempotently.
+ * Session-scoped (rev 4): a live Claude `/model` switch writes NO
+ * `.session-model` carrier — it applies in-session and the explicit
+ * `claude --model <configured>` flag reverts it on the next boot, so it lasts
+ * exactly until the next restart with no durable state. (sr-* switches never
+ * reach here — they go through scheduleModelRelaunch, which owns the
+ * consume-once carrier.) The `/status` honesty invariant lives here: only
+ * `reply.selectedModel` records; an unverified inject records nothing.
+ * `/model default` clears any in-memory override and any leftover carrier.
  */
 function recordTypedModelSwitch(
   reply: { text: string; selectedModel?: string },
   requestedModelArg: string | null,
-  deps: ModelCommandDeps,
+  _deps: ModelCommandDeps,
 ): string {
   const requested = requestedModelArg != null ? expandSrAlias(requestedModelArg) : null
   if (requested?.toLowerCase() === 'default') {
@@ -21898,28 +21939,14 @@ function recordTypedModelSwitch(
   }
   if (!reply.selectedModel) return ''
   sessionModelSource.setOverride(reply.selectedModel)
-  const smDir = resolveAgentDirFromEnv()
-  if (smDir && requested && isValidModelArg(requested) && !isSrModel(requested)) {
-    try {
-      writeSessionModelFile(
-        smDir,
-        requested,
-        readConfiguredDefaultModel(smDir) ??
-          resolveMainModel(deps.getConfiguredModel() ?? undefined),
-      )
-    } catch (err) {
-      process.stderr.write(
-        `telegram gateway: session-model persist failed (typed /model): ${(err as Error)?.message ?? String(err)}\n`,
-      )
-      return '\n⚠️ Couldn’t persist the sticky override — the switch is live now but won’t survive a relaunch.'
-    }
-  }
   return ''
 }
 
 /**
- * Record a model-MENU callback outcome (persist/clear sticky override) and
- * drive an sr-*→Claude graceful restart when the tap crosses that boundary.
+ * Record a model-MENU callback outcome (set the live in-memory override, clear
+ * a leftover carrier on a Default tap) and drive an sr-*→Claude graceful
+ * restart when the tap crosses that boundary — the only menu path that writes a
+ * consume-once `.session-model` carrier (a live Claude tap writes none, rev 4).
  * Extracted from the live `mdl:*` dispatcher so the deferred (queued mid-turn)
  * apply records + restarts identically. Does NOT edit any Telegram message —
  * callers own the card edit. Returns a restart notice when a session restart
@@ -21933,29 +21960,13 @@ function recordModelMenuSideEffects(
   prevSessionModel: string | null,
 ): { restartNotice?: string } {
   // Record a successful session switch so /status reflects what's actually
-  // running, and persist the STICKY override
-  // (reference/rfcs/session-model-stickiness.md): the canonical token (never
-  // the display label) goes to the durable `.session-model`; a confirmed
-  // "Default (recommended)" selection clears it instead.
+  // running. Session-scoped (rev 4): a live Claude menu tap writes NO
+  // `.session-model` carrier — it applies in-session (native picker) and
+  // reverts on the next boot. Only the sr→Claude transition below (which
+  // relaunches) writes the consume-once carrier. A confirmed "Default
+  // (recommended)" selection clears any leftover carrier.
   if (outcome.selectedModel) {
     sessionModelSource.setOverride(outcome.selectedModel)
-    const smDir = resolveAgentDirFromEnv()
-    if (smDir && outcome.selectedModelToken) {
-      try {
-        writeSessionModelFile(
-          smDir,
-          outcome.selectedModelToken,
-          readConfiguredDefaultModel(smDir) ??
-            resolveMainModel(modelDeps.getConfiguredModel() ?? undefined),
-        )
-      } catch (err) {
-        outcome.reply.text +=
-          '\n⚠️ Couldn’t persist the sticky override — the switch is live now but won’t survive a relaunch.'
-        process.stderr.write(
-          `telegram gateway: session-model persist failed (menu): ${(err as Error)?.message ?? String(err)}\n`,
-        )
-      }
-    }
   }
   if (outcome.clearedDefault) {
     const smDir = resolveAgentDirFromEnv()
@@ -21967,9 +21978,11 @@ function recordModelMenuSideEffects(
   // torn down — a graceful restart (same mechanism as /restart) is required.
   if (outcome.selectedModel && isSrToClaudeTransition(prevSessionModel, outcome.selectedModel)) {
     const agentName = getMyAgentName()
-    // Carry the requested Claude model across the restart via the SAME durable
-    // `.session-model` override a Claude → sr-* switch uses — otherwise boot
-    // launches the CONFIGURED default and the tapped model is silently dropped.
+    // Carry the requested Claude model across the restart via the SAME
+    // consume-once `.session-model` carrier a Claude → sr-* switch uses —
+    // otherwise this transition's apply-relaunch boots the CONFIGURED default
+    // and the tapped model is silently dropped. Applied on that one boot,
+    // then reverts on the next restart (rev 4).
     const agentDir = resolveAgentDirFromEnv()
     const token = outcome.selectedModelToken
     if (agentDir && token) {
@@ -22132,20 +22145,19 @@ function persistQueuedCommandForRestart(action: ShutdownResolutionAction): strin
     switch (action.persist) {
       case 'model': {
         // #3042 blocker 2a: this token was QUEUED, never confirmed by claude.
-        // Under the keep-by-default boot a garbage-but-shape-valid token
-        // persisted here would crashloop `claude --model <garbage>` with the
-        // gateway dead. Only offline-trustable tokens (static Claude aliases,
-        // curated sr-* alias targets) may be persisted unconfirmed; anything
-        // else gets the honest "couldn't verify — re-issue" card instead.
+        // The carrier is written immediately before the bounce, so the next
+        // boot IS its apply-relaunch: consume-once means a garbage token can
+        // crash at most one boot before it reverts, but we still gate on
+        // offline-trustable tokens (static Claude aliases, curated sr-* alias
+        // targets) to avoid even that one crash-boot; anything else gets the
+        // honest "couldn't verify — re-issue" card instead.
         if (!isOfflineTrustedModelToken(action.arg)) {
           return `↩️ Couldn’t verify \`${escapeHtmlForTg(action.cmd.targetLabel || action.arg)}\` as a known model without the live session — it was NOT saved. Re-issue \`/model ${escapeHtmlForTg(action.arg)}\` once the agent is back.`
         }
         const configured =
           readConfiguredDefaultModel(agentDir) ?? resolveMainModel(undefined)
+        // Consume-once carrier: applied by the next boot, then reverts.
         writeSessionModelFile(agentDir, expandSrAlias(action.arg), configured)
-        // Boot default is keep (#3039), but stamp explicit keep-intent for
-        // reason-honesty in the boot notice.
-        writeRelaunchModelIntent(agentDir, 'keep', 'queued /model carried across restart')
         break
       }
       case 'clear-model':
@@ -22235,17 +22247,50 @@ bot.command('model', async ctx => {
   const parsed = parseModelCommand(text) ?? { kind: 'show' as const }
   const chatId = String(ctx.chat!.id)
   const threadId = resolveThreadId(chatId, ctx.message?.message_thread_id)
+  // #3177 — durable receipt FIRST. A typed /model must NEVER be invisible: even
+  // if every downstream reply is shed/dropped, or the session is in a
+  // phantom-idle window (turn atom cleared while claude is still busy), the
+  // command leaves a greppable log line + a history row before any branch. This
+  // is the fix for the finn 2026-07-12 zero-trace swallow (no log, no reply, no
+  // ack, no deferred apply). `busyNow` folds BOTH busy signals (turn atom AND
+  // the authoritative delivery-machine/approval gate).
+  const busyNow = currentTurn !== null || turnInFlightForGate()
+  process.stderr.write(modelCommandReceiptLine(getMyAgentName(), parsed, busyNow) + '\n')
+  if (HISTORY_ENABLED && ctx.message?.message_id != null) {
+    try {
+      recordInbound({
+        chat_id: chatId,
+        thread_id: threadId ?? null,
+        message_id: ctx.message.message_id,
+        user: ctx.from?.username ?? (ctx.from?.id != null ? String(ctx.from.id) : null),
+        user_id: ctx.from?.id != null ? String(ctx.from.id) : null,
+        ts: ctx.message.date ?? Math.floor(Date.now() / 1000),
+        text,
+      })
+    } catch (err) {
+      process.stderr.write(`telegram gateway: /model recordInbound failed: ${(err as Error)?.message ?? String(err)}\n`)
+    }
+  }
   const deps = buildModelDeps({ chatId, threadId })
-  if (parsed.kind === 'show' && process.env.SWITCHROOM_MODEL_MENU !== '0') {
+  // Route on a pure disposition (#3177) that folds BOTH busy signals so a
+  // session busy by EITHER measure ack+queues instead of silently injecting
+  // into a busy pane. Every branch below produces a visible action.
+  const disposition = planModelCommand(parsed, {
+    currentTurnActive: currentTurn !== null,
+    turnInFlight: turnInFlightForGate(),
+    menuEnabled: process.env.SWITCHROOM_MODEL_MENU !== '0',
+  })
+  if (disposition.kind === 'menu') {
     const menu = await buildModelMenu(deps)
     await switchroomReply(ctx, menu.text, { html: true, reply_markup: modelMenuReplyMarkup(menu) })
     return
   }
-  // Mid-turn: instead of dead-ending ("Try again in a moment"), ACK + QUEUE +
-  // apply-on-idle + confirm (#3017). The typed set path either injects into
-  // claude's input box or triggers a carrier restart — both unsafe mid-turn.
-  if (parsed.kind === 'set' && deps.isBusy()) {
-    const target = expandSrAlias(parsed.model)
+  // Mid-turn (by either busy signal): instead of dead-ending ("Try again in a
+  // moment") or silently injecting into a busy pane, ACK + QUEUE + apply-on-idle
+  // + confirm (#3017/#3177). The typed set path either injects into claude's
+  // input box or triggers a carrier restart — both unsafe while busy.
+  if (disposition.kind === 'queue') {
+    const target = disposition.target
     const sent = await ctx.replyWithRichMessage(
       richMessage(hardenCardBreaks(pendingCmdAckText('model', target, escapeHtmlForTg))),
       threadId != null ? { message_thread_id: threadId } : {},
@@ -22285,39 +22330,38 @@ bot.command('model', async ctx => {
 // is blocklisted for `/effort` since #2471), session-scoped — boot re-pins
 // the configured default via start.sh's `--effort`. Implementation in
 // effort-command.ts so it's unit-testable without booting the bot.
+
+// The live session-effort override, in memory only (#3186, session-scoped
+// like /model rev 4). A confirmed live apply records here — NOT to the
+// `.session-effort` carrier — so it lasts exactly until the next restart
+// (start.sh's explicit `--effort <configured>` reverts it for free). Seeded
+// at boot from `.active-session-effort` (the effort sibling of
+// `.active-session-model`) so a queued-carrier apply-boot still shows the
+// honest live level on the /effort menu.
+let sessionEffortOverride: string | null = null
+
 function buildEffortDeps(): EffortCommandDeps {
   return {
-    // #3039: single persistence choke point — EVERY positively-confirmed
-    // effort apply (typed, menu tap, queued drain) durably records the level
-    // to `.session-effort`, which start.sh resolves into `--effort` on every
-    // boot. `/effort default` clears it via clearSessionEffort (the handler
-    // clears AFTER its restore-apply, so the wrapper's write is undone).
+    // Session-scoped (#3186): a positively-confirmed live apply records the
+    // level IN MEMORY only — no durable carrier. The `.session-effort`
+    // carrier is written solely by persistQueuedCommandForRestart (a queued
+    // mid-turn /effort carried across the bounce) and is consume-once at
+    // boot. `/effort default` clears via clearSessionEffort below.
     applyEffort: async (agent, level) => {
       const result = await applyEffort(agent, level)
-      if (result.ok) {
-        const agentDir = resolveAgentDirFromEnv()
-        if (agentDir) {
-          try {
-            writeSessionEffortFile(agentDir, level, getConfiguredEffortForPersist())
-          } catch (err) {
-            process.stderr.write(
-              `telegram gateway: session-effort persist failed level=${level}: ${(err as Error)?.message ?? String(err)}\n`,
-            )
-          }
-        }
-      }
+      if (result.ok) sessionEffortOverride = level
       return result
     },
     getAgentName: getMyAgentName,
     getConfiguredEffort: () => getConfiguredEffortForPersist(),
     clearSessionEffort: () => {
+      sessionEffortOverride = null
+      // Also drop any leftover queued-command carrier so the next boot can't
+      // consume a stale level the user just cleared.
       const agentDir = resolveAgentDirFromEnv()
       if (agentDir) clearSessionEffortFile(agentDir)
     },
-    getSessionEffort: () => {
-      const agentDir = resolveAgentDirFromEnv()
-      return agentDir ? (readSessionEffortFile(agentDir)?.level ?? null) : null
-    },
+    getSessionEffort: () => sessionEffortOverride,
     escapeHtml: escapeHtmlForTg,
   }
 }
@@ -22462,14 +22506,10 @@ bot.command('restart', async ctx => {
     // greeting card shows "Restarted  user: /restart from chat" instead
     // of whatever reason the downstream CLI would default to.
     stampUserRestartReason('user: /restart from chat')
-    // #3039: /restart is "bounce the session", NOT "clear my model" — the
-    // durable override survives every restart and is cleared only by
-    // `/model default`. Stamp keep for reason-honesty in the boot notice
-    // (absence of intent keeps anyway under the keep-by-default boot).
-    {
-      const smDir = resolveAgentDirFromEnv()
-      if (smDir) writeRelaunchModelIntent(smDir, 'keep', 'user: /restart from chat')
-    }
+    // Session-scoped (rev 4): /restart reverts any live /model override to the
+    // configured default. A consume-once `.session-model` carrier (if one was
+    // in flight) was already consumed by its own apply-relaunch, so nothing to
+    // do here — start.sh boots the configured default.
     await sweepBeforeSelfRestart()
     const hostdResp = await tryHostdDispatch(getMyAgentName(), {
       v: 1,
@@ -22628,12 +22668,8 @@ async function handleNewCommand(ctx: Context): Promise<void> {
   // Stamp user attribution so the next greeting shows "Restarted  user:
   // /new" / "user: /reset" rather than the downstream CLI default.
   stampUserRestartReason(`user: /${kind} from chat`)
-  // /new and /reset start a fresh CONVERSATION, not a fresh model choice:
-  // the sticky session-model override KEEPS across them (contract row 7).
-  // Boot default is revert, so the keep-intent must land before dispatch.
-  if (agentDir != null) {
-    writeRelaunchModelIntent(agentDir, 'keep', `user: /${kind} from chat`)
-  }
+  // Session-scoped (rev 4): /new and /reset are restarts, so they revert any
+  // live /model override to the configured default — no carrier to preserve.
   await sweepBeforeSelfRestart()
   const hostdResp = await tryHostdDispatch(getMyAgentName(), {
     v: 1,
@@ -23413,6 +23449,46 @@ const throttleTierRunner = createThrottleTierRunner({
   log: (m) => process.stderr.write(`telegram gateway: ${m}\n`),
 })
 
+// ─── litellm-local 429 notice — side-effect wiring ──────────────────────────
+// State machine + text + config parsing live in litellm-local-notice.ts
+// (pure); the sequencing (classification guard → per-agent cooldown →
+// broadcast + metric) lives in litellm-local-notice-wiring.ts so it is
+// unit-testable with injected deps. This block only binds the real gateway
+// dependencies. Deliberately NO broker surface: the litellm-local calm
+// path's invariant is that account state is never touched.
+const litellmLocalNoticeRunner = createLitellmLocalNoticeRunner({
+  listNoticeChats: () => loadAccess().allowFrom,
+  sendNotice: (chat_id, markdown) => {
+    // Topic routing — this notice REPLACES the generic operator-event card
+    // for the litellm-local classification, so it must land where that card
+    // would have: supergroup-mode agents route system notifications into the
+    // alerts/admin alias topic ('compact-watchdog' kind, same resolution as
+    // the emitGatewayOperatorEvent broadcast loop), while DM recipients get
+    // a thread-less send (topicForRecipient guards the #2096 "message
+    // thread not found" misrouting class).
+    const noticeTopic = resolveAgentOutboundTopic({ kind: 'compact-watchdog' })
+    const noticeSupergroup = resolveAgentSupergroupChatId()
+    const noticeThread = topicForRecipient({
+      recipientChatId: chat_id,
+      resolvedTopic: noticeTopic,
+      supergroupChatId: noticeSupergroup,
+    })
+    // Status notice, not the user's answer — silence the ping (same posture
+    // as the throttle-tier / fleet-fallback announcements).
+    void swallowingApiCall(
+      // allow-raw-bot-api: wrapped in swallowingApiCall (retry policy)
+      () => bot.api.sendRichMessage(chat_id, richMessage(markdown), {
+        disable_notification: true,
+        ...(noticeThread != null ? { message_thread_id: noticeThread } : {}),
+      }),
+      { chat_id: String(chat_id), verb: 'litellm-local-notice:notify' },
+    )
+  },
+  windowMs: () => parseLitellmNoticeWindowMs(loadAccess().litellmNoticeWindowMs),
+  emitMetric: (event) => emitRuntimeMetric(event),
+  log: (m) => process.stderr.write(`telegram gateway: ${m}\n`),
+})
+
 /**
  * Broadcast a fleet-fallback FAILURE notice to every authorized chat.
  *
@@ -25551,7 +25627,7 @@ bot.on('callback_query:data', async ctx => {
     // sr-* TARGET tap: switch TO a non-Claude (LiteLLM/OpenRouter) model.
     // Parity with the text `/model sr-*` path — claude's native picker rejects
     // unknown sr-* ids, so an in-place inject can't set them. Carry the token
-    // across a graceful restart (the durable `.session-model` override) and
+    // across a graceful restart (the consume-once `.session-model` carrier) and
     // relaunch `claude --model sr-*`. Session-only; reverts to the configured
     // default on the next restart. The sr-* → Claude direction is handled below
     // via the SELECT/alias outcome + isSrToClaudeTransition.
@@ -27960,46 +28036,36 @@ async function shutdown(signal: string): Promise<void> {
     } catch (err) {
       process.stderr.write(`telegram gateway: shutdown.clean_marker_write_failed err=${(err as Error).message}\n`)
     }
-    // #3017 — persist a Telegram-set model across a GRACEFUL deploy/restart.
-    // Boot default is REVERT, and an EXTERNAL deploy (SIGTERM to PID 1 from
-    // `switchroom apply` / `docker compose up`) never routes through
-    // triggerSelfRestart, so it stamps no `.relaunch-model-intent` and start.sh
-    // drops the user's `/model` choice (the overlord `fable`→`opus` revert on
-    // the v0.18.9 roll). A graceful OS-signal shutdown IS a clean, planned
-    // bounce — stamp keep-intent for an active `.session-model` override so the
-    // chosen model survives and start.sh re-confirms it via `.session-model-alert`
-    // on boot. Respect an intent an initiator already stamped (a /restart stamps
-    // 'revert' before SIGTERM): only stamp when none exists. A crash routes
-    // through the non-OS-signal branch and still reverts (safe side preserved).
-    try {
-      const smDir = resolveAgentDirFromEnv()
-      if (smDir != null) {
-        const hasOverride = readSessionModelFile(smDir) != null
-        const intentAlreadyStamped = existsSync(join(smDir, RELAUNCH_MODEL_INTENT_FILE))
-        if (hasOverride && !intentAlreadyStamped) {
-          // The GATEWAY_SHUTDOWN_INTENT_REASON_PREFIX makes this stamp
-          // recognisable at the next GATEWAY boot: a gateway-only bounce never
-          // runs start.sh, so a leftover stamp with this prefix is cleared at
-          // boot (clearStaleGatewayShutdownIntent) instead of lingering to
-          // convert a later genuine crash into a "keep" (#3018 finding 4).
-          writeRelaunchModelIntent(smDir, 'keep', `${GATEWAY_SHUTDOWN_INTENT_REASON_PREFIX} graceful ${signal} shutdown (deploy/rolling restart) — preserving user-chosen session model`)
-          process.stderr.write(`telegram gateway: shutdown.session_model_keep_stamped signal=${signal}\n`)
-        }
-      }
-    } catch (err) {
-      process.stderr.write(`telegram gateway: shutdown.session_model_keep_stamp_failed err=${(err as Error).message}\n`)
-    }
+    // Session-scoped (rev 4): a graceful deploy/restart REVERTS a live /model
+    // override to the configured default — there is no keep-intent to stamp.
+    // (A live Claude override never had a `.session-model` carrier; an in-flight
+    // sr-* carrier was already consumed by its own apply-relaunch.) A queued —
+    // not-yet-applied — /model IS still persisted just below so it applies as
+    // the agent boots (its apply-relaunch), then reverts on the next restart.
   } else {
     process.stderr.write(`telegram gateway: shutdown.clean_marker_skipped signal=${signal} (crash path — banner will fire on next boot)\n`)
   }
 
   // #3018 finding 3 + #3039: resolve any queued /model|/effort ack cards. The
   // gateway (and with it the in-memory queue) is going away — persist each
-  // typed choice to the durable boot carriers (`.session-model` /
-  // `.session-effort`) so it still deterministically applies as the agent
-  // boots, and edit the ack card to say so. Only an unresolvable menu-tag
-  // selection falls back to a re-issue note. Best-effort and time-bounded so
-  // a wedged Telegram API can't block shutdown.
+  // typed choice to the consume-once boot carriers (`.session-model` /
+  // `.session-effort`, #3184/#3186) so it still deterministically applies as
+  // the agent boots (that boot consumes the carrier; later restarts revert),
+  // and edit the ack card to say so. Only an unresolvable menu-tag selection
+  // falls back to a re-issue note. Best-effort and time-bounded so a wedged
+  // Telegram API can't block shutdown.
+  //
+  // DELIBERATE (rev 4, #3184 review LOW-3 — applies to BOTH carriers): this
+  // runs on EVERY shutdown path, including crashes (uncaughtException/
+  // unhandledRejection route here), not just the isOsSignal branch above. So
+  // a mid-turn queued /model or /effort + crash can apply on the
+  // crash-recovery boot — technically at odds with a literal "crash reverts"
+  // reading of the session-scoped contract. Intended: it preserves #3178's
+  // "a queued command never silently vanishes" guarantee (the ack card
+  // promised the switch), the model side is gated to offline-trusted tokens
+  // (the effort side is allowlist-gated at write, so a garbage level can't
+  // even cost one crash-boot), and the consume-once carriers bound it to
+  // exactly that one recovery boot — the following restart reverts to config.
   const orphanedCmdActions = pendingCmdShutdownResolutionActions(pendingSessionCommand, escapeHtmlForTg)
   const orphanedCmdEdits = orphanedCmdActions.map(a => ({
     chatId: a.cmd.ackChatId,
@@ -28844,6 +28910,23 @@ void (async () => {
               } catch { /* leave override as-is on a bad read */ }
             }
 
+            // Effort sibling (#3186): start.sh records the EFFECTIVE launched
+            // effort to `.active-session-effort` every boot. Re-hydrate the
+            // in-memory session-effort override so the /effort menu highlight
+            // stays honest after a queued-carrier apply-boot. Only an effort
+            // differing from the configured default counts as an override.
+            const activeEffortPath = join(smAgentDir, '.active-session-effort')
+            if (existsSync(activeEffortPath)) {
+              try {
+                const launchedEffort = readFileSync(activeEffortPath, 'utf8').trim()
+                const configuredEffort = getConfiguredEffortForPersist()
+                sessionEffortOverride =
+                  launchedEffort.length > 0 && launchedEffort !== configuredEffort
+                    ? launchedEffort
+                    : null
+              } catch { /* leave override as-is on a bad read */ }
+            }
+
             const alertPath = join(smAgentDir, '.session-model-alert')
             if (existsSync(alertPath)) {
               let alertText: string | null = null
@@ -29066,6 +29149,14 @@ void (async () => {
                     },
                   ),
               },
+              // #3084 follow-up: the feed's send/edit adapters transit the send
+              // gate, which SHEDS (resolves undefined) any call made during an
+              // open flood window. Give the feed the SAME on-disk window probe
+              // robustApiCall + the held-card sweep read, so a running/first-
+              // paint tick parks in cooldown instead of re-firing a shed send
+              // every ~6s for the whole ban (the worker-feed shed-contract bug:
+              // 565 `sent.message_id` crashes in one 6h ban).
+              floodWaitRemainingMs: probeFloodWaitRemainingMs,
               log: (msg) => process.stderr.write(`telegram gateway: ${msg}\n`),
             })
             subagentWatcher = startSubagentWatcher({