switchroom 0.18.15 → 0.18.17

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/session-model-file.ts

@@ -1,32 +1,31 @@
 /**
- * Durable session-model stickiness — file helpers shared by the gateway.
+ * Session-scoped `/model` carrier — file helpers shared by the gateway.
  *
- * Two files in the bind-mounted agent state dir carry the contract
- * (reference/rfcs/session-model-stickiness.md):
+ * Contract: reference/rfcs/session-model-stickiness.md §0.1 (rev 4, operator
+ * decision 2026-07-12 — SESSION-SCOPED, superseding the rev-3 keep-by-default).
+ * Files in the bind-mounted agent state dir:
  *
- *   - `.session-model` — the DURABLE session override written on every
- *     positively-confirmed `/model` switch. One-line JSON
- *     `{"model","configuredDefaultAtWrite","ts"}`. It is NOT consumed by a
- *     keep-path boot; it survives every restart/deploy/crash and is cleared
- *     only by explicit user action (`/model default`) or invalidation
- *     (corruption / the configured yaml default changed) — every clearing
- *     path notifies the operator chat via `.session-model-alert` (#3039).
+ *   - `.session-model` — a CONSUME-ONCE carrier written ONLY immediately
+ *     before a relaunch that applies the switch (the sr-* / sr→Claude paths
+ *     and a queued /model persisted at graceful shutdown). One-line JSON
+ *     `{"model","configuredDefaultAtWrite","ts"}`. start.sh applies it on the
+ *     single boot that reads it and then deletes it; every SUBSEQUENT restart
+ *     (deploy, /restart, /new, watchdog recovery, crash, raw docker restart)
+ *     finds no carrier and boots the configured default. Live Claude switches
+ *     do NOT write a carrier — they apply in-session and the explicit
+ *     `claude --model <configured>` flag reverts them on the next boot.
+ *     Cleared live by `/model default`; invalidation (corruption / the
+ *     configured yaml default changed at the apply-boot) drops it and notifies
+ *     the operator chat via `.session-model-alert`.
  *
- *   - `.relaunch-model-intent` — the ONE-SHOT intent bit for the next boot.
- *     One-line JSON `{"intent":"keep"|"revert","reason","ts"}`, atomic
- *     write, last-writer-wins. Boot default is KEEP (#3039 — operator
- *     decision 2026-07-11, superseding the earlier revert-by-default): a
- *     raw `docker restart` / host reboot / deploy / crash keeps a valid
- *     override. Only an explicit fresh "revert" intent reverts. start.sh
- *     consumes the file (rm -f) every boot; a stale (>10 min by the
- *     embedded ts) or corrupt intent counts as no intent (→ keep).
- *
- *   - `.session-effort` — the DURABLE effort override (#3039), same shape
- *     and lifecycle as `.session-model` with `level` in place of `model`:
- *     `{"level","configuredDefaultAtWrite","ts"}`. Written on every
- *     positively-confirmed `/effort` apply, resolved by start.sh into the
- *     relaunch's `--effort`, cleared only by `/effort default` or
- *     invalidation (with a boot alert).
+ *   - `.session-effort` — the CONSUME-ONCE effort carrier (#3186, session-
+ *     scoped like `.session-model`). Same shape with `level` in place of
+ *     `model`: `{"level","configuredDefaultAtWrite","ts"}`. Written ONLY by
+ *     the queued-command shutdown persist (a mid-turn `/effort` carried
+ *     across the bounce); start.sh resolves it into the apply-boot's
+ *     `--effort` and deletes it, so any subsequent restart reverts to the
+ *     configured `thinking_effort`. Live `/effort` applies record in memory
+ *     only. Cleared live by `/effort default`; invalidation alerts at boot.
  *
  * The `model` token is always a canonical `claude --model` token (alias,
  * `claude-*` id, or `sr-*` id) — NEVER a display label like "Opus 4.8".
@@ -38,12 +37,7 @@ import { join } from 'node:path'
 import { isValidModelArg } from './model-command.js'
 
 export const SESSION_MODEL_FILE = '.session-model'
-export const RELAUNCH_MODEL_INTENT_FILE = '.relaunch-model-intent'
 export const CONFIGURED_DEFAULT_MODEL_FILE = '.configured-default-model'
-/** Crashloop self-heal counter (start.sh stamps `<count> <epoch>` per fast boot). */
-export const SESSION_MODEL_BOOT_ATTEMPTS_FILE = '.session-model-boot-attempts'
-
-export type RelaunchModelIntent = 'keep' | 'revert'
 
 export interface SessionModelRecord {
   model: string
@@ -51,21 +45,6 @@ export interface SessionModelRecord {
   ts: number
 }
 
-/**
- * Classify a triggerSelfRestart reason into the intent the boot should honor.
- *
- * Since #3039 (operator contract 2026-07-11) EVERY restart reason keeps the
- * override: a restart — user-tapped, watchdog, deploy, or crash — is not
- * "clear my model". The override is cleared only by explicit user action
- * (`/model default`) or invalidation at boot, both of which run their own
- * paths. The 'revert' intent value remains recognised by start.sh (and this
- * classifier's signature keeps it) so an older gateway's stamp still parses,
- * but current code never emits it.
- */
-export function intentForRestartReason(_reason: string): RelaunchModelIntent {
-  return 'keep'
-}
-
 function atomicWrite(path: string, content: string): void {
   const tmp = `${path}.tmp-${process.pid}-${Date.now()}`
   writeFileSync(tmp, content, 'utf8')
@@ -104,8 +83,8 @@ export function parseSessionModel(text: string): SessionModelRecord | null {
 }
 
 /**
- * Write the durable session override. Throws on a non-canonical token —
- * callers must pass a `claude --model` token, never a display label
+ * Write the consume-once session-model carrier. Throws on a non-canonical
+ * token — callers must pass a `claude --model` token, never a display label
  * (regression guard for the "Opus 4.5 persisted" class).
  */
 export function writeSessionModelFile(
@@ -137,37 +116,10 @@ export function readSessionModelFile(agentDir: string): SessionModelRecord | nul
   return raw == null ? null : parseSessionModel(raw)
 }
 
-/** Delete the durable override (`/model default`, rollback). Best-effort. */
+/** Delete the session-model carrier (`/model default`, rollback). Best-effort. */
 export function clearSessionModelFile(agentDir: string): void {
   try {
     rmSync(join(agentDir, SESSION_MODEL_FILE), { force: true })
-    // #3042 item 4: also drop the kept-alert dedup sentinel so a future
-    // override of the same name re-alerts on its first kept boot.
-    rmSync(join(agentDir, '.session-model-kept-notified'), { force: true })
-    rmSync(join(agentDir, SESSION_MODEL_BOOT_ATTEMPTS_FILE), { force: true })
-  } catch {
-    /* best-effort */
-  }
-}
-
-/**
- * #3043 item 2: clear ONLY the crashloop boot-attempts counter — a positive
- * health signal from the gateway, not a carrier change.
- *
- * start.sh's self-heal (start.sh.hbs "Override crashloop self-heal") increments
- * the counter on every boot that re-enters within 150s with the override still
- * active, and clears a healthy override after 3 fast boots. That window can't
- * tell a genuine crashloop from three quick OPERATOR hand-bounces of a healthy
- * agent — both look like fast successive boots — so three deliberate restarts
- * would spuriously wipe a working override. A boot that reaches bridge
- * registration is proven healthy (the session came all the way up and the
- * bridge connected), so the gateway deletes the counter there. Only boots that
- * genuinely FAIL before the bridge registers now accumulate toward the 3-strike
- * clear. Best-effort; absent file is fine.
- */
-export function clearSessionModelBootAttempts(agentDir: string): void {
-  try {
-    rmSync(join(agentDir, SESSION_MODEL_BOOT_ATTEMPTS_FILE), { force: true })
   } catch {
     /* best-effort */
   }
@@ -186,94 +138,6 @@ export function restoreSessionModelFileRaw(agentDir: string, raw: string | null)
   }
 }
 
-/**
- * Stamp the one-shot relaunch intent. MUST be called synchronously BEFORE
- * the restart signal/dispatch it describes (write-before-kill invariant —
- * the next start.sh boot reads this to decide keep vs revert). Best-effort:
- * a failed write means the boot falls back to the default (keep, #3039) —
- * the user's choice is preserved either way.
- */
-export function writeRelaunchModelIntent(
-  agentDir: string,
-  intent: RelaunchModelIntent,
-  reason: string,
-): void {
-  try {
-    atomicWrite(
-      join(agentDir, RELAUNCH_MODEL_INTENT_FILE),
-      `${JSON.stringify({ intent, reason, ts: Date.now() })}\n`,
-    )
-  } catch (err) {
-    process.stderr.write(
-      `telegram gateway: relaunch-model-intent write failed (boot will revert): ${(err as Error)?.message ?? String(err)}\n`,
-    )
-  }
-}
-
-/**
- * Reason prefix the gateway's SIGTERM/SIGINT shutdown handler stamps on its
- * deploy-survival keep-intent (#3017/#3018). Distinguishable on purpose:
- * a gateway-only bounce (supervisor relaunch, bare gateway-unit restart)
- * leaves that stamp UNCONSUMED on disk — start.sh only runs on a container
- * boot — and the next gateway boot uses this prefix to recognise and clear
- * the stale stamp (see clearStaleGatewayShutdownIntent).
- */
-export const GATEWAY_SHUTDOWN_INTENT_REASON_PREFIX = 'gateway-shutdown:'
-
-export interface RelaunchModelIntentRecord {
-  intent: RelaunchModelIntent
-  reason: string
-  ts: number
-}
-
-/** Parsed `.relaunch-model-intent`, or null when absent / corrupt / malformed. */
-export function readRelaunchModelIntent(agentDir: string): RelaunchModelIntentRecord | null {
-  try {
-    const raw = readFileSync(join(agentDir, RELAUNCH_MODEL_INTENT_FILE), 'utf8')
-    const parsed = JSON.parse(raw) as Partial<RelaunchModelIntentRecord>
-    if (
-      (parsed.intent !== 'keep' && parsed.intent !== 'revert') ||
-      typeof parsed.reason !== 'string' ||
-      typeof parsed.ts !== 'number'
-    ) {
-      return null
-    }
-    return { intent: parsed.intent, reason: parsed.reason, ts: parsed.ts }
-  } catch {
-    return null
-  }
-}
-
-/**
- * Boot-time cleanup for the gateway-only-bounce hole (#3018 finding 4).
- *
- * A container-level stop/deploy consumes `.relaunch-model-intent` in start.sh
- * BEFORE any gateway boots. So if a freshly-booting GATEWAY still sees an
- * intent that a gateway shutdown handler stamped (reason carries
- * GATEWAY_SHUTDOWN_INTENT_REASON_PREFIX), the preceding bounce was
- * gateway-only — the container never restarted and the stamp is stale.
- * Left in place, it could convert a genuine crash within the 10-min
- * freshness window into a "keep", breaking the crash-reverts policy.
- * Clear it. Never touches a triggerSelfRestart / user-slash stamp (those
- * use their own un-prefixed reasons and precede a container bounce).
- * Returns true when a stale stamp was cleared.
- */
-export function clearStaleGatewayShutdownIntent(agentDir: string): boolean {
-  const rec = readRelaunchModelIntent(agentDir)
-  if (rec == null || !rec.reason.startsWith(GATEWAY_SHUTDOWN_INTENT_REASON_PREFIX)) return false
-  clearRelaunchModelIntent(agentDir)
-  return true
-}
-
-/** Remove a stamped intent (rollback of a failed dispatch). Best-effort. */
-export function clearRelaunchModelIntent(agentDir: string): void {
-  try {
-    rmSync(join(agentDir, RELAUNCH_MODEL_INTENT_FILE), { force: true })
-  } catch {
-    /* best-effort */
-  }
-}
-
 /**
  * The resolved configured default start.sh recorded this boot
  * (`.configured-default-model`, written before override resolution — the
@@ -288,12 +152,13 @@ export function readConfiguredDefaultModel(agentDir: string): string | null {
   }
 }
 
-// ─── Durable session-effort override (#3039) ────────────────────────────────
+// ─── Consume-once session-effort carrier (#3186) ────────────────────────────
 //
-// The `/effort` sibling of `.session-model`. Same lifecycle: written on every
-// positively-confirmed effort apply, honored by start.sh on every boot
-// (`--effort <level>`), cleared only by `/effort default` or invalidation
-// (configured `thinking_effort:` changed / corrupt file — both alert once).
+// The `/effort` sibling of `.session-model`, session-scoped. Written ONLY by
+// the queued-command shutdown persist (a mid-turn /effort carried across the
+// bounce); start.sh applies it on the single boot that reads it (`--effort
+// <level>`) and deletes it. Cleared live by `/effort default`; invalidation
+// (configured `thinking_effort:` changed / corrupt file) alerts once at boot.
 
 export const SESSION_EFFORT_FILE = '.session-effort'
 
@@ -330,8 +195,9 @@ export function parseSessionEffort(text: string): SessionEffortRecord | null {
 }
 
 /**
- * Write the durable effort override. Throws on a non-allowlisted level —
- * the value is passed verbatim to `claude --effort` at the next boot.
+ * Write the consume-once effort carrier. Throws on a non-allowlisted level —
+ * the value is passed verbatim to `claude --effort` at the next boot (the
+ * apply-boot, which consumes the file).
  */
 export function writeSessionEffortFile(
   agentDir: string,
@@ -347,7 +213,7 @@ export function writeSessionEffortFile(
   )
 }
 
-/** Parsed durable effort override, or null when absent/corrupt. */
+/** Parsed effort carrier, or null when absent/corrupt. */
 export function readSessionEffortFile(agentDir: string): SessionEffortRecord | null {
   try {
     return parseSessionEffort(readFileSync(join(agentDir, SESSION_EFFORT_FILE), 'utf8'))
@@ -356,7 +222,7 @@ export function readSessionEffortFile(agentDir: string): SessionEffortRecord | n
   }
 }
 
-/** Delete the durable effort override (`/effort default`). Best-effort. */
+/** Delete the effort carrier (`/effort default`, leftover hygiene). Best-effort. */
 export function clearSessionEffortFile(agentDir: string): void {
   try {
     rmSync(join(agentDir, SESSION_EFFORT_FILE), { force: true })