switchroom 0.18.29 → 0.18.31

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.18.29",
+  "version": "0.18.31",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {
@@ -24,9 +24,9 @@
     "build": "node scripts/build.mjs",
     "build:cli": "node scripts/build.mjs && bun build --compile --target=bun-linux-x64 --minify bin/switchroom.ts --outfile switchroom-linux-amd64",
     "pretest": "npm run build",
-    "test": "vitest run && bun test telegram-plugin/tests/history.test.ts telegram-plugin/tests/cross-turn-card-gate.test.ts telegram-plugin/tests/emission-authority-open-gate.test.ts telegram-plugin/tests/emission-authority-ping-gate.test.ts telegram-plugin/tests/emission-authority-card-drain-gate.test.ts telegram-plugin/tests/per-topic-current-turn.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/ipc-server-query-pending-permission.test.ts telegram-plugin/tests/ipc-server-check-pre-approved.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/registry/subagents-bugs.test.ts telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts telegram-plugin/tests/subagent-nested-dispatch.test.ts telegram-plugin/tests/nested-worker-visibility-harness.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/registry/api-registry.test.ts telegram-plugin/registry/turns-schema.test.ts telegram-plugin/tests/idle-footer-wiring.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/status-query-telemetry.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts telegram-plugin/tests/skill-proposal-card.test.ts",
+    "test": "vitest run && bun test telegram-plugin/tests/catch-all-forwarded-history.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/cross-turn-card-gate.test.ts telegram-plugin/tests/emission-authority-open-gate.test.ts telegram-plugin/tests/emission-authority-ping-gate.test.ts telegram-plugin/tests/emission-authority-card-drain-gate.test.ts telegram-plugin/tests/per-topic-current-turn.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/ipc-server-query-pending-permission.test.ts telegram-plugin/tests/ipc-server-check-pre-approved.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/registry/subagents-bugs.test.ts telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts telegram-plugin/tests/subagent-nested-dispatch.test.ts telegram-plugin/tests/nested-worker-visibility-harness.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/registry/api-registry.test.ts telegram-plugin/registry/turns-schema.test.ts telegram-plugin/tests/idle-footer-wiring.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/status-query-telemetry.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts telegram-plugin/tests/skill-proposal-card.test.ts",
     "test:vitest": "vitest run",
-    "test:bun": "bun test src/vault/grants.test.ts src/vault/grants-db.test.ts src/vault/write-grants.test.ts src/vault/broker/server-grants.test.ts src/vault/broker/server-write-grants.test.ts src/vault/broker/server-mint-grant-passphrase-attest.test.ts src/vault/broker/server-passphrase-attest.test.ts src/vault/broker/server-mint-grant-posture-attest.test.ts src/vault/broker/server-admin-only-keys.test.ts src/vault/broker/client-token.test.ts src/vault/broker/server-unlock.test.ts src/vault/broker/auto-unlock.test.ts src/vault/broker/drift-detection.test.ts tests/vault-broker-passphrase.test.ts src/cli/vault-get-broker.test.ts src/vault/resolver-via-broker.test.ts src/vault/broker/scope.test.ts src/vault/broker/server.test.ts src/litellm/provision-apply-e2e.test.ts src/drive/disconnect.test.ts src/drive/grants.test.ts src/drive/oauth.test.ts src/drive/onboarding.test.ts src/drive/reconciler.test.ts src/drive/vault-slots.test.ts src/drive/wrapper.test.ts src/vault/approvals/kernel.test.ts src/vault/approvals/approval-origin.test.ts src/vault/approvals/schema-idempotent.test.ts src/vault/broker/server-approvals.test.ts telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/boot-version-string.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/cross-turn-card-gate.test.ts telegram-plugin/tests/emission-authority-open-gate.test.ts telegram-plugin/tests/emission-authority-ping-gate.test.ts telegram-plugin/tests/emission-authority-card-drain-gate.test.ts telegram-plugin/tests/per-topic-current-turn.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/ipc-server-query-pending-permission.test.ts telegram-plugin/tests/ipc-server-check-pre-approved.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/registry/subagents-bugs.test.ts telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts telegram-plugin/tests/subagent-nested-dispatch.test.ts telegram-plugin/tests/nested-worker-visibility-harness.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/status-query-telemetry.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/tests/subagent-watcher-workflow-visibility.test.ts telegram-plugin/uat/load-env.test.ts telegram-plugin/uat/feed-matcher.test.ts telegram-plugin/uat/uat-driver.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts telegram-plugin/tests/skill-proposal-card.test.ts",
+    "test:bun": "bun test telegram-plugin/tests/catch-all-forwarded-history.test.ts src/vault/grants.test.ts src/vault/grants-db.test.ts src/vault/write-grants.test.ts src/vault/broker/server-grants.test.ts src/vault/broker/server-write-grants.test.ts src/vault/broker/server-mint-grant-passphrase-attest.test.ts src/vault/broker/server-passphrase-attest.test.ts src/vault/broker/server-mint-grant-posture-attest.test.ts src/vault/broker/server-admin-only-keys.test.ts src/vault/broker/client-token.test.ts src/vault/broker/server-unlock.test.ts src/vault/broker/auto-unlock.test.ts src/vault/broker/drift-detection.test.ts tests/vault-broker-passphrase.test.ts src/cli/vault-get-broker.test.ts src/vault/resolver-via-broker.test.ts src/vault/broker/scope.test.ts src/vault/broker/server.test.ts src/litellm/provision-apply-e2e.test.ts src/drive/disconnect.test.ts src/drive/grants.test.ts src/drive/oauth.test.ts src/drive/onboarding.test.ts src/drive/reconciler.test.ts src/drive/vault-slots.test.ts src/drive/wrapper.test.ts src/vault/approvals/kernel.test.ts src/vault/approvals/approval-origin.test.ts src/vault/approvals/schema-idempotent.test.ts src/vault/broker/server-approvals.test.ts telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/boot-version-string.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/cross-turn-card-gate.test.ts telegram-plugin/tests/emission-authority-open-gate.test.ts telegram-plugin/tests/emission-authority-ping-gate.test.ts telegram-plugin/tests/emission-authority-card-drain-gate.test.ts telegram-plugin/tests/per-topic-current-turn.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/ipc-server-query-pending-permission.test.ts telegram-plugin/tests/ipc-server-check-pre-approved.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/registry/subagents-bugs.test.ts telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts telegram-plugin/tests/subagent-nested-dispatch.test.ts telegram-plugin/tests/nested-worker-visibility-harness.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resume-inbound-builder.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/status-query-telemetry.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/tests/subagent-watcher-workflow-visibility.test.ts telegram-plugin/uat/load-env.test.ts telegram-plugin/uat/feed-matcher.test.ts telegram-plugin/uat/uat-driver.test.ts telegram-plugin/gateway/webhook-ingest-server.test.ts telegram-plugin/tests/skill-proposal-card.test.ts",
     "test:watch": "vitest",
     "lint": "tsc --noEmit && node scripts/check-plugin-references.mjs && bash scripts/check-bot-api-wrapping.sh && node scripts/check-bun-test-imports.mjs && node scripts/check-no-pii-secrets.mjs && node scripts/check-vault-test-hermeticity.mjs && node scripts/check-no-broadcast-delivery.mjs && node scripts/check-stale-tool-descriptions.mjs && node scripts/check-web-subscription-honest.mjs && node scripts/check-no-unpinned-npx-playwright.mjs",
     "lint:tsc": "tsc --noEmit",

package/profiles/_base/start.sh.hbs

@@ -1170,22 +1170,106 @@ fi
 # which the gateway relays to the operator chat once at boot. The normal apply
 # path is silent here — the gateway already acked the `/model` in chat.
 #
+# --- Live configured-default resolution (Defect B / drift fix) ---
+#
+# The apply-time bake ({{{modelQ}}}) is only the LAST-DITCH fallback: editing
+# `model:` in switchroom.yaml and restarting must take effect WITHOUT a full
+# `switchroom apply`. The launcher asks the SAME resolver the gateway's
+# /status uses (`switchroom agent effective-model`, which applies
+# resolveMainModel server-side) against the live mounted yaml — one resolver,
+# never re-implemented in shell, so what-you-see and what-runs cannot split.
+#
+# Fallback chain, never silent past step 1:
+#   1. live read of $SWITCHROOM_CONFIG (one bounded retry — a host-side
+#      in-place rewrite can present a torn file for a moment);
+#   2. `.configured-default-model` — the last-known-good live value this
+#      launcher recorded on every prior boot (read BEFORE it is overwritten);
+#   3. the apply-time bake.
+# Steps 2/3 append to `.session-model-alert` so the gateway tells the
+# operator once at boot. No SWITCHROOM_CONFIG mount at all means there is
+# nothing to read live — the bake IS the truth there (stderr note only; an
+# operator alert every boot forever would be noise with no action).
+#
+# The yaml file bind mount re-resolves by PATH at container start, so a
+# host-side atomic-rename write is always picked up by the NEXT boot — the
+# path this block runs on. Only mid-life reads by long-running processes can
+# see a stale inode; that pre-existing edge is out of scope here (tracked as
+# a follow-up on the drift fix).
+#
 # NB {{{modelQ}}} is already shell-single-quoted by the scaffold (it renders as
 # a quoted token, e.g. 'claude-sonnet-5'), so it is assigned BARE here — never
 # inside additional double quotes, which would embed the literal quote chars in
 # the value and break `claude --model`.
-_EFFECTIVE_MODEL={{{modelQ}}}
+_BAKED_MODEL={{{modelQ}}}
+_LKG_MODEL="$(cat "{{agentDir}}/.configured-default-model" 2>/dev/null | tr -d '[:space:]' || true)"
+_EFFECTIVE_MODEL=""
+if [ -n "$SWITCHROOM_CONFIG" ] && [ -f "$SWITCHROOM_CONFIG" ] && command -v switchroom >/dev/null 2>&1; then
+  _lm_live=""
+  for _lm_try in 1 2; do
+    _lm_live="$(timeout 20 switchroom --config "$SWITCHROOM_CONFIG" agent effective-model "{{name}}" 2>/dev/null | tail -n 1 | tr -d '[:space:]')" || _lm_live=""
+    # Shape gate — same regex as the .session-model carrier below (byte-kept
+    # with MODEL_ARG_RE); the tr above already guarantees single-line.
+    if [ -n "$_lm_live" ] && printf '%s' "$_lm_live" | grep -Eq '^[A-Za-z0-9][]A-Za-z0-9._[/-]{0,99}$'; then
+      break
+    fi
+    _lm_live=""
+    if [ "$_lm_try" -eq 1 ]; then sleep 1; fi
+  done
+  if [ -n "$_lm_live" ]; then
+    # Routing class (Claude passthrough vs sr-* router root) is baked into
+    # compose at render time, so a Claude<->sr-* class flip CANNOT be applied
+    # by a bare restart — half-applying would run the new model against the
+    # old routing. Detect the flip, keep the baked model, and tell the
+    # operator to run a real apply.
+    case "$_BAKED_MODEL" in sr-*) _lm_baked_class=router ;; *) _lm_baked_class=claude ;; esac
+    case "$_lm_live" in sr-*) _lm_live_class=router ;; *) _lm_live_class=claude ;; esac
+    if [ "$_lm_live_class" != "$_lm_baked_class" ]; then
+      echo "session-model: configured model class changed ('$_BAKED_MODEL' -> '$_lm_live', $_lm_baked_class -> $_lm_live_class) — routing is render-time, NOT applying; run 'switchroom apply' then restart" >&2
+      printf 'The configured model changed from `%s` to `%s`, which switches routing class — a restart alone cannot apply that. The agent booted on `%s`. Run `switchroom apply` on the host, then restart this agent.\n' "$_BAKED_MODEL" "$_lm_live" "$_BAKED_MODEL" >> "{{agentDir}}/.session-model-alert" 2>/dev/null || true
+      _EFFECTIVE_MODEL="$_BAKED_MODEL"
+    else
+      _EFFECTIVE_MODEL="$_lm_live"
+      if [ "$_lm_live" != "$_BAKED_MODEL" ]; then
+        echo "session-model: live configured model '$_lm_live' differs from apply-time bake '$_BAKED_MODEL' — using the live value (switchroom.yaml is the source of truth)" >&2
+      fi
+    fi
+  elif [ -n "$_LKG_MODEL" ] && printf '%s' "$_LKG_MODEL" | grep -Eq '^[A-Za-z0-9][]A-Za-z0-9._[/-]{0,99}$'; then
+    # Live read failed (torn write mid-read, yaml schema error, CLI wedge).
+    # Last-known-good beats the bake: it was live truth on a prior boot,
+    # while the bake can predate any number of yaml edits. Loud either way —
+    # a silent fallback here would resurrect Defect B as an intermittent flap.
+    _EFFECTIVE_MODEL="$_LKG_MODEL"
+    echo "session-model: live config read FAILED — using last-known-good configured model '$_LKG_MODEL' (apply-time bake: '$_BAKED_MODEL')" >&2
+    printf 'switchroom.yaml could not be read at boot, so the agent booted on the last-known-good configured model `%s`. If you just changed `model:`, check the yaml for errors and restart the agent.\n' "$_LKG_MODEL" >> "{{agentDir}}/.session-model-alert" 2>/dev/null || true
+  else
+    _EFFECTIVE_MODEL="$_BAKED_MODEL"
+    echo "session-model: live config read FAILED and no last-known-good value — using apply-time baked model '$_BAKED_MODEL'" >&2
+    printf 'switchroom.yaml could not be read at boot and no prior boot recorded a model, so the agent booted on the apply-time default `%s`. If you just changed `model:`, check the yaml for errors and restart the agent.\n' "$_BAKED_MODEL" >> "{{agentDir}}/.session-model-alert" 2>/dev/null || true
+  fi
+  unset _lm_live _lm_try _lm_baked_class _lm_live_class
+else
+  _EFFECTIVE_MODEL="$_BAKED_MODEL"
+fi
+unset _BAKED_MODEL _LKG_MODEL
 # Record the RESOLVED configured default (raw, unquoted) every boot, before
 # override resolution. The gateway copies this into the carrier's
 # `configuredDefaultAtWrite`, so both sides of the invalidation compare below
-# come from the same resolver. Overwrite, not consumed.
+# come from the same resolver. Overwrite, not consumed — and doubling as the
+# last-known-good live value the fallback chain above reads on the NEXT boot.
 printf '%s\n' "$_EFFECTIVE_MODEL" > "{{agentDir}}/.configured-default-model" 2>/dev/null || true
 
 # Rev-4 hygiene (#3184 review LOW-2): remove the files retired with the
-# keep/revert intent subsystem and the crashloop self-heal. Nothing reads them
-# anymore; without this rm they would linger in the bind-mounted state dir
-# forever after rollout. Idempotent — a cheap no-op once clean.
-rm -f "{{agentDir}}/.relaunch-model-intent" "{{agentDir}}/.session-model-boot-attempts" "{{agentDir}}/.session-model-kept-notified"
+# keep/revert intent subsystem. Nothing reads them anymore; without this rm they
+# would linger in the bind-mounted state dir forever after rollout. Idempotent —
+# a cheap no-op once clean.
+rm -f "{{agentDir}}/.relaunch-model-intent" "{{agentDir}}/.session-model-kept-notified"
+# `.session-model-boot-attempts` is REVIVED as LIVE state (#3284 bounded-retry
+# counter, see the resolution block below): the gateway clears it on a healthy
+# boot, and start.sh gives up + reverts once it exceeds the attempt bound. It is
+# meaningless without a carrier to belong to, so sweep it as stale ONLY when no
+# `.session-model` carrier is present (rollout leftover / completed apply / a
+# prior giveup that didn't get to delete it).
+[ -f "{{agentDir}}/.session-model" ] || rm -f "{{agentDir}}/.session-model-boot-attempts"
 
 # Migration shim (one release): a leftover one-shot `.session-model-override`
 # carrier from a pre-consume-once gateway means an OLD gateway wrote it
@@ -1207,11 +1291,34 @@ if [ -f "{{agentDir}}/.session-model" ]; then
   _smf="$(cat "{{agentDir}}/.session-model" 2>/dev/null || true)"
   _sm_model="$(printf '%s' "$_smf" | sed -n 's/.*"model"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')"
   _sm_cfg="$(printf '%s' "$_smf" | sed -n 's/.*"configuredDefaultAtWrite"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')"
-  # CONSUME-ONCE: delete the carrier now, before any apply/exec. The carrier
-  # governs exactly this one boot; a bad token can therefore crash at most one
-  # boot (the next boot has no carrier and reverts), so no crashloop self-heal
-  # is needed. Every branch below has already removed the file.
-  rm -f "{{agentDir}}/.session-model"
+  # BOUNDED-RETRY CONSUME (#3284) — the carrier is NO LONGER deleted here before
+  # the apply/exec. It used to be (pure consume-once), but a boot that reads the
+  # carrier may WEDGE before its gateway acquires the boot lock (the
+  # boot.lock_stale_recovered_boot_mismatch race, e.g. a proxy-only `fable`
+  # apply-boot) and never become the surviving healthy session. Deleting before
+  # apply handed the requested model to that loser: the retry boot found no
+  # carrier and silently reverted to the configured default. Instead:
+  #
+  #   - the GATEWAY deletes the carrier + the attempt counter once it ACQUIRES
+  #     the boot lock (boot.lock_acquired in gateway.ts — the healthy-boot signal
+  #     a wedged boot cannot fake), so a GOOD token survives a transient wedge
+  #     and RE-APPLIES on the retry boot instead of reverting;
+  #   - a persisted attempt counter (`.session-model-boot-attempts`) BOUNDS the
+  #     retries: a token that never reaches a healthy gateway (a genuinely BAD
+  #     token that crashes claude before lock-acquire) is given up after
+  #     _SM_MAX_ATTEMPTS boots — deleted, reverted, and alerted — so a bad token
+  #     can NEVER produce an unbounded wedge→retry→wedge crashloop. The original
+  #     "a bad token crashes at most one boot then reverts" guarantee becomes "at
+  #     most _SM_MAX_ATTEMPTS boots then reverts", still a hard finite bound.
+  #
+  # Every INVALIDATION / GIVEUP branch below deletes BOTH the carrier and the
+  # counter; only the APPLY branch keeps the carrier (for the gateway to clear)
+  # and persists the incremented counter. The delete-before-apply that used to
+  # sit here is GONE by design.
+  _SM_MAX_ATTEMPTS=3
+  _sm_attempts="$(cat "{{agentDir}}/.session-model-boot-attempts" 2>/dev/null | tr -dc '0-9' || true)"
+  [ -z "$_sm_attempts" ] && _sm_attempts=0
+  _sm_attempts=$(( _sm_attempts + 1 ))
   # Shape gate — kept BYTE-IDENTICAL with MODEL_ARG_RE in
   # telegram-plugin/gateway/model-command.ts. `/` is allowed for
   # OpenRouter-style `sr-vendor/model` ids; it is not a shell metachar inside
@@ -1222,35 +1329,78 @@ if [ -f "{{agentDir}}/.session-model" ]; then
   # `claude --model` (parity with parseSessionModel's single-string check).
   if [ "$(printf '%s' "$_sm_model" | wc -c)" -eq 0 ] || [ "$(printf '%s' "$_sm_model" | wc -l)" -ne 0 ] || ! printf '%s' "$_sm_model" | grep -Eq '^[A-Za-z0-9][]A-Za-z0-9._[/-]{0,99}$'; then
     # Invalid carrier: fall back to the configured default AND tell the
-    # operator once — never a silent stderr-only drop.
+    # operator once — never a silent stderr-only drop. Terminal → drop the
+    # carrier + counter (a corrupt token is never worth retrying).
+    rm -f "{{agentDir}}/.session-model" "{{agentDir}}/.session-model-boot-attempts"
     echo "session-model: ignoring malformed .session-model (failed shape gate) — using configured default '$_EFFECTIVE_MODEL'" >&2
     printf 'Your saved session model override could not be read (invalid or corrupt), so the agent booted on its configured default `%s`. Re-issue /model <name> if you want a different model.\n' "$_EFFECTIVE_MODEL" > "{{agentDir}}/.session-model-alert" 2>/dev/null || true
   elif [ "$_sm_cfg" != "$_EFFECTIVE_MODEL" ]; then
     # switchroom.yaml `model:` changed between the switch and this apply-boot →
     # the carrier is against a default that no longer exists. Invalidate +
-    # announce once.
+    # announce once. Terminal → drop the carrier + counter.
+    rm -f "{{agentDir}}/.session-model" "{{agentDir}}/.session-model-boot-attempts"
     echo "session-model: configured default changed ('$_sm_cfg' → '$_EFFECTIVE_MODEL') — dropping session override '$_sm_model'" >&2
     printf 'The configured default model changed (`%s` → `%s`), so your session override to `%s` was not applied — the agent booted on the new configured default. Re-issue /model %s if you still want it.\n' "$_sm_cfg" "$_EFFECTIVE_MODEL" "$_sm_model" "$_sm_model" > "{{agentDir}}/.session-model-alert" 2>/dev/null || true
   elif { [ "${_sm_model#sr-}" != "$_sm_model" ] || [ "$_sm_model" = fable ] || [ "$_sm_model" = claude-fable-5 ]; } && [ -z "$_LITELLM_OK" ]; then
     # Proxy-only override + LiteLLM unreachable at the apply-boot: booting the
     # override would 4xx (sr-* against Anthropic; `fable`/`claude-fable-5` is a
     # retired codename direct-to-Anthropic and ONLY resolves via the LiteLLM
-    # router — see the repoint case below). Consume-once means we can't retain it
-    # for a later relaunch, so boot the configured default and tell the operator
-    # to re-issue once the proxy is back. (Rev 5: Fable is now reachable via the
-    # carrier relaunch — the old live-inject path never launched it — so it needs
-    # the same down-guard as sr-*.)
+    # router — see the repoint case below). The litellm probe already waited out
+    # its full 120s window before we got here, so "still unreachable" is a real
+    # down-state, not the transient boot-lock wedge the bounded-retry counter
+    # covers — drop the carrier + counter (terminal) and tell the operator to
+    # re-issue once the proxy is back, rather than looping against a dead proxy.
+    # (Rev 5: Fable is now reachable via the carrier relaunch — the old
+    # live-inject path never launched it — so it needs the same down-guard as sr-*.)
+    rm -f "{{agentDir}}/.session-model" "{{agentDir}}/.session-model-boot-attempts"
     echo "session-model: LiteLLM proxy unreachable at boot — NOT applying proxy-only override '$_sm_model'; booting configured default '$_EFFECTIVE_MODEL' (re-issue /model when the proxy is back)" >&2
     printf 'LiteLLM proxy was unreachable at boot, so the session model override `%s` was not applied — the agent booted on its configured default `%s`. Re-issue /model %s once the proxy is reachable.\n' "$_sm_model" "$_EFFECTIVE_MODEL" "$_sm_model" > "{{agentDir}}/.session-model-alert" 2>/dev/null || true
+  elif [ "$_sm_attempts" -gt "$_SM_MAX_ATTEMPTS" ]; then
+    # CRASHLOOP BOUND (#3284). This carrier has now been read on more than
+    # _SM_MAX_ATTEMPTS boots WITHOUT the gateway ever reaching boot.lock_acquired
+    # to clear it — i.e. every apply-boot wedged/crashed before a healthy
+    # gateway. That is the signature of a genuinely bad token (one that will
+    # never boot), NOT the transient boot-lock race we retry for. Give up:
+    # drop the carrier + counter, revert to the configured default, and alert.
+    # This is the hard finite bound that guarantees no unbounded crashloop.
+    rm -f "{{agentDir}}/.session-model" "{{agentDir}}/.session-model-boot-attempts"
+    echo "session-model: override '$_sm_model' did not reach a healthy boot after $_SM_MAX_ATTEMPTS attempts — reverting to configured default '$_EFFECTIVE_MODEL'" >&2
+    printf 'Your session model override `%s` could not boot successfully after %s attempts, so the agent reverted to its configured default `%s`. Re-issue /model %s to try again.\n' "$_sm_model" "$_SM_MAX_ATTEMPTS" "$_EFFECTIVE_MODEL" "$_sm_model" > "{{agentDir}}/.session-model-alert" 2>/dev/null || true
   else
-    # Apply the carrier for THIS session. No boot alert — the gateway already
-    # acked the /model switch in chat, and the override reverts on next restart.
+    # Apply the carrier for THIS session and KEEP it: the gateway deletes the
+    # carrier + counter once it acquires the boot lock (healthy boot), so a
+    # transient wedge before that RE-APPLIES on the retry boot instead of
+    # reverting. Persist the incremented attempt counter so the crashloop bound
+    # above can fire if this token keeps wedging. No boot alert — the gateway
+    # already acked the /model switch in chat, and the override reverts on the
+    # next restart (once the gateway has cleared the carrier).
+    printf '%s\n' "$_sm_attempts" > "{{agentDir}}/.session-model-boot-attempts" 2>/dev/null || true
     _EFFECTIVE_MODEL="$_sm_model"
-    echo "session-model: applying session override '$_sm_model' this boot (consume-once — reverts on next restart)" >&2
+    echo "session-model: applying session override '$_sm_model' this boot (attempt $_sm_attempts/$_SM_MAX_ATTEMPTS — cleared by the gateway on a healthy boot, reverts on next restart)" >&2
   fi
-  unset _smf _sm_model _sm_cfg
+  unset _smf _sm_model _sm_cfg _sm_attempts _SM_MAX_ATTEMPTS
 fi
 
+# Configured-default LiteLLM guard. A proxy-only *configured* model with
+# LiteLLM unreachable at boot would exec against the /anthropic passthrough,
+# where `fable`/`claude-fable-5` is a retired codename and EVERY call 4xxs —
+# a total outage. The carrier block above already drops proxy-only OVERRIDES
+# on a down proxy; this extends the same guard to the configured default,
+# which the live-config read above makes a mainline path (pinning `model:
+# fable` in yaml is now the normal way to run Fable). Claude agents have a
+# safe same-class fallback (opus); sr-* configured defaults keep today's
+# loud-degraded behavior — there is no Claude fallback for them and the
+# repoint case below already leaves their routing to self-heal.
+case "$_EFFECTIVE_MODEL" in
+  fable|claude-fable-5)
+    if [ -z "$_LITELLM_OK" ]; then
+      echo "session-model: configured model '$_EFFECTIVE_MODEL' is proxy-only but LiteLLM is unreachable at boot — booting 'opus' until the proxy recovers" >&2
+      printf 'LiteLLM was unreachable at boot, so the configured model `%s` (proxy-only) could not be used — the agent booted on `opus` instead. Restart the agent once the proxy is back to return to `%s`.\n' "$_EFFECTIVE_MODEL" "$_EFFECTIVE_MODEL" >> "{{agentDir}}/.session-model-alert" 2>/dev/null || true
+      _EFFECTIVE_MODEL="opus"
+    fi
+    ;;
+esac
+
 # --- Session effort resolution (consume-once .session-effort carrier, #3186) ---
 #
 # The `/effort` sibling of the block above, session-scoped like /model

package/telegram-plugin/dist/bridge/bridge.js

@@ -22970,6 +22970,65 @@ import {
 import { homedir as homedir2 } from "os";
 import { basename, join as join3 } from "path";
 
+// text-voice-scrub.ts
+var NULL = "\x00";
+var FENCE_PH = `${NULL}VS_FENCE`;
+var INLINE_PH = `${NULL}VS_INLINE`;
+var HTML_CODE_PH = `${NULL}VS_HTMLCODE`;
+var HTML_PRE_PH = `${NULL}VS_HTMLPRE`;
+var URL_PH = `${NULL}VS_URL`;
+
+// model-unavailable.ts
+var transientUpstreamSignals = [
+  "not your usage limit",
+  "not your account",
+  "not your account's",
+  "temporarily limiting requests",
+  "temporarily rate",
+  "server is temporarily",
+  "would exceed your account\u2019s rate limit",
+  "would exceed your account's rate limit"
+];
+function isTransientUpstreamSignal(text) {
+  if (typeof text !== "string" || text.length === 0)
+    return false;
+  const sample = text.length > 16384 ? text.slice(0, 16384) : text;
+  const lower = sample.toLowerCase();
+  return transientUpstreamSignals.some((s) => lower.includes(s));
+}
+var litellmProxyLocal429Signals = [
+  "deployment over user-defined ratelimit",
+  "model rate limit exceeded. tpm limit",
+  "model rate limit exceeded. rpm limit",
+  "deployment over defined rpm limit",
+  "no deployments available for selected model",
+  "litellm rate limit handler",
+  "crossed tpm / rpm",
+  "max parallel request limit reached"
+];
+var litellmV3LimiterSignalPair = ["rate limit exceeded for ", "limit type:"];
+function isLitellmProxyLocal429(text) {
+  if (typeof text !== "string" || text.length === 0)
+    return false;
+  const sample = text.length > 16384 ? text.slice(0, 16384) : text;
+  const lower = sample.toLowerCase();
+  if (litellmProxyLocal429Signals.some((s) => lower.includes(s)))
+    return true;
+  return litellmV3LimiterSignalPair.every((s) => lower.includes(s));
+}
+function isLitellmProxyAuthMisconfig(text) {
+  if (typeof text !== "string" || text.length === 0)
+    return false;
+  const sample = text.length > 16384 ? text.slice(0, 16384) : text;
+  const lower = sample.toLowerCase();
+  if (lower.includes("x-api-key header is required"))
+    return true;
+  const isAuthErr = lower.includes("authentication_error") || lower.includes("authenticationerror");
+  if (!isAuthErr)
+    return false;
+  return lower.includes("fallback") && lower.includes("x-api-key");
+}
+
 // operator-events.ts
 function classifyClaudeError(raw) {
   try {
@@ -22987,6 +23046,12 @@ function classifyInner(raw) {
   const message = extractString(obj, "message") ?? extractString(getNestedObj(obj, "error"), "message") ?? (typeof raw === "string" ? raw : "") ?? "";
   const status = extractNumber(obj, "status") ?? extractNumber(obj, "statusCode") ?? extractNumber(obj, "status_code") ?? null;
   const sdkCode = extractString(obj, "error_code") ?? "";
+  if (isLitellmProxyAuthMisconfig(`${errorType}
+${errorCode}
+${sdkCode}
+${message}`)) {
+    return "proxy-misconfig";
+  }
   if (errorType === "authentication_error" || errorCode === "authentication_error" || sdkCode === "authentication_error" || message.toLowerCase().includes("authentication_error")) {
     const msg = message.toLowerCase();
     if (msg.includes("expired") || msg.includes("refresh")) {
@@ -23034,53 +23099,12 @@ function getNestedObj(obj, key) {
 }
 var DEFAULT_OPERATOR_EVENT_COOLDOWN_MS = 5 * 60000;
 var cooldownMap = new Map;
-
-// text-voice-scrub.ts
-var NULL = "\x00";
-var FENCE_PH = `${NULL}VS_FENCE`;
-var INLINE_PH = `${NULL}VS_INLINE`;
-var HTML_CODE_PH = `${NULL}VS_HTMLCODE`;
-var HTML_PRE_PH = `${NULL}VS_HTMLPRE`;
-var URL_PH = `${NULL}VS_URL`;
-
-// model-unavailable.ts
-var transientUpstreamSignals = [
-  "not your usage limit",
-  "not your account",
-  "not your account's",
-  "temporarily limiting requests",
-  "temporarily rate",
-  "server is temporarily",
-  "would exceed your account\u2019s rate limit",
-  "would exceed your account's rate limit"
-];
-function isTransientUpstreamSignal(text) {
-  if (typeof text !== "string" || text.length === 0)
-    return false;
-  const sample = text.length > 16384 ? text.slice(0, 16384) : text;
-  const lower = sample.toLowerCase();
-  return transientUpstreamSignals.some((s) => lower.includes(s));
-}
-var litellmProxyLocal429Signals = [
-  "deployment over user-defined ratelimit",
-  "model rate limit exceeded. tpm limit",
-  "model rate limit exceeded. rpm limit",
-  "deployment over defined rpm limit",
-  "no deployments available for selected model",
-  "litellm rate limit handler",
-  "crossed tpm / rpm",
-  "max parallel request limit reached"
-];
-var litellmV3LimiterSignalPair = ["rate limit exceeded for ", "limit type:"];
-function isLitellmProxyLocal429(text) {
-  if (typeof text !== "string" || text.length === 0)
-    return false;
-  const sample = text.length > 16384 ? text.slice(0, 16384) : text;
-  const lower = sample.toLowerCase();
-  if (litellmProxyLocal429Signals.some((s) => lower.includes(s)))
-    return true;
-  return litellmV3LimiterSignalPair.every((s) => lower.includes(s));
-}
+var OPERATOR_ACTIONABLE_KINDS = new Set([
+  "credentials-expired",
+  "credentials-invalid",
+  "credit-exhausted",
+  "proxy-misconfig"
+]);
 
 // tool-label-sidecar.ts
 import { existsSync as existsSync2, readFileSync, statSync as statSync2 } from "node:fs";