switchroom 0.18.32 → 0.19.0

package/dist/host-control/main.js

@@ -20687,7 +20687,23 @@ var AUDIT_ROOT = join2(homedir2(), ".switchroom", "audit");
 var import_handlebars = __toESM(require_lib(), 1);
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, existsSync as existsSync5, readdirSync as readdirSync2, statSync as statSync2, copyFileSync, mkdirSync as mkdirSync2, realpathSync } from "node:fs";
 import { resolve as resolve4, join as join3, sep as pathSep } from "node:path";
-var PROFILES_ROOT = resolve4(import.meta.dirname, "../../profiles");
+function resolveProfilesRoot() {
+  const envOverride = process.env.SWITCHROOM_PROFILES_ROOT?.trim();
+  if (envOverride) {
+    return resolve4(envOverride);
+  }
+  const candidates = [
+    resolve4(import.meta.dirname, "../../profiles"),
+    resolve4(import.meta.dirname, "profiles")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync5(candidate)) {
+      return candidate;
+    }
+  }
+  return candidates[0];
+}
+var PROFILES_ROOT = resolveProfilesRoot();
 import_handlebars.default.registerHelper("json", (value) => {
   return new import_handlebars.default.SafeString(JSON.stringify(value, null, 2));
 });
@@ -26647,7 +26663,7 @@ import { existsSync as existsSync9, readFileSync as readFileSync7 } from "node:f
 import { dirname as dirname4, join as join7 } from "node:path";
 
 // src/build-info.ts
-var VERSION = "0.18.32";
+var VERSION = "0.19.0";
 
 // src/cli/resolve-version.ts
 function readPackageVersion() {

package/dist/vault/approvals/kernel-server.js

@@ -19072,7 +19072,23 @@ var AUDIT_ROOT = join(homedir2(), ".switchroom", "audit");
 var import_handlebars = __toESM(require_lib(), 1);
 import { readFileSync as readFileSync3, writeFileSync, existsSync as existsSync4, readdirSync as readdirSync2, statSync as statSync2, copyFileSync, mkdirSync, realpathSync } from "node:fs";
 import { resolve as resolve4, join as join2, sep as pathSep } from "node:path";
-var PROFILES_ROOT = resolve4(import.meta.dirname, "../../profiles");
+function resolveProfilesRoot() {
+  const envOverride = process.env.SWITCHROOM_PROFILES_ROOT?.trim();
+  if (envOverride) {
+    return resolve4(envOverride);
+  }
+  const candidates = [
+    resolve4(import.meta.dirname, "../../profiles"),
+    resolve4(import.meta.dirname, "profiles")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync4(candidate)) {
+      return candidate;
+    }
+  }
+  return candidates[0];
+}
+var PROFILES_ROOT = resolveProfilesRoot();
 import_handlebars.default.registerHelper("json", (value) => {
   return new import_handlebars.default.SafeString(JSON.stringify(value, null, 2));
 });

package/dist/vault/broker/server.js

@@ -18780,7 +18780,23 @@ var AUDIT_ROOT = join(homedir2(), ".switchroom", "audit");
 var import_handlebars = __toESM(require_lib(), 1);
 import { readFileSync as readFileSync4, writeFileSync, existsSync as existsSync4, readdirSync as readdirSync2, statSync as statSync2, copyFileSync, mkdirSync, realpathSync } from "node:fs";
 import { resolve as resolve4, join as join2, sep as pathSep } from "node:path";
-var PROFILES_ROOT = resolve4(import.meta.dirname, "../../profiles");
+function resolveProfilesRoot() {
+  const envOverride = process.env.SWITCHROOM_PROFILES_ROOT?.trim();
+  if (envOverride) {
+    return resolve4(envOverride);
+  }
+  const candidates = [
+    resolve4(import.meta.dirname, "../../profiles"),
+    resolve4(import.meta.dirname, "profiles")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync4(candidate)) {
+      return candidate;
+    }
+  }
+  return candidates[0];
+}
+var PROFILES_ROOT = resolveProfilesRoot();
 import_handlebars.default.registerHelper("json", (value) => {
   return new import_handlebars.default.SafeString(JSON.stringify(value, null, 2));
 });
@@ -23429,6 +23445,23 @@ class VaultBroker {
           socket.write(encodeResponse(errorResponse("DENIED", aclResult.reason)));
           return;
         }
+        const existingForScope = this.secrets[req.key];
+        if (existingForScope !== undefined) {
+          const writeScope = checkEntryScope(existingForScope.scope, agentName);
+          if (!writeScope.allow) {
+            this.auditLogger.write({
+              ts: new Date().toISOString(),
+              op: "put",
+              key: req.key,
+              caller: auditCaller,
+              pid: auditPid,
+              cgroup: auditCgroup,
+              result: `denied:${writeScope.reason}`
+            });
+            socket.write(encodeResponse(errorResponse("DENIED", writeScope.reason)));
+            return;
+          }
+        }
       }
       const existing = this.secrets[req.key];
       if (existing === undefined && writeGrantId === null && !passphraseAttested) {
@@ -23458,7 +23491,16 @@ class VaultBroker {
         return;
       }
       const previousEntry = existing;
-      this.secrets[req.key] = req.entry;
+      let nextEntry = req.entry;
+      if (existing !== undefined && !passphraseAttested) {
+        const preservedFormat = "format" in existing && existing.format !== undefined ? { format: existing.format } : {};
+        nextEntry = {
+          ...req.entry,
+          ...preservedFormat,
+          ...existing.scope !== undefined ? { scope: existing.scope } : {}
+        };
+      }
+      this.secrets[req.key] = nextEntry;
       try {
         saveVault(this.passphrase, this.vaultPath, this.secrets);
       } catch (err) {

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.32",
+  "version": "0.19.0",
   "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": {
@@ -26,7 +26,7 @@
     "pretest": "npm run build",
     "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 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: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-scope-persist.test.ts src/vault/broker/server-tokenless-scope.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 && node scripts/check-gateway-line-ratchet.mjs",
     "lint:tsc": "tsc --noEmit",

package/profiles/_base/start.sh.hbs

@@ -96,6 +96,13 @@ if [ "$SWITCHROOM_RUNTIME" = "docker" ] && [ -z "$SWITCHROOM_DOCKER_TMUX_INNER"
   #
   # SWITCHROOM_AGENT_NAME is injected by compose env (compose.ts:1816)
   # so it is available here, before the inner-pass export at line ~320.
+  #
+  # Capture whether LiteLLM routing was configured at compose time BEFORE the
+  # missing-key fail-open below can strip SWITCHROOM_LITELLM. The routing-mode
+  # observability block (inner pass, pre-exec) reads this to distinguish
+  # "litellm never configured" (declared intent IS direct-oauth — no
+  # divergence) from "configured but stripped at boot" (real divergence).
+  export SWITCHROOM_LITELLM_DECLARED="${SWITCHROOM_LITELLM_DECLARED:-${SWITCHROOM_LITELLM:-}}"
   if [ -n "${SWITCHROOM_LITELLM:-}" ] && [ -z "$ANTHROPIC_CUSTOM_HEADERS" ] && command -v switchroom >/dev/null 2>&1; then
     sr_ll_key="$(switchroom vault get "litellm/$SWITCHROOM_AGENT_NAME/api-key" 2>/dev/null || true)"
     sr_ll_ok=""
@@ -1096,7 +1103,20 @@ fi
 # unreachable at boot, or claude would 4xx an unknown model against Anthropic.
 # Empty by default (proxy not confirmed live); set to "1" only on a successful
 # liveliness probe. Deliberately NOT unset with the sr_ll_* scratch vars.
+#
+# _LITELLM_UNREACHABLE distinguishes WHY _LITELLM_OK is empty (routing-cause
+# split, 2026-07-17 boot-race incident): "1" means the key was present and the
+# probe failed — routing was LEFT IN PLACE pointing at the proxy, so a
+# proxy-only model (fable/sr-*) can boot loud-degraded and self-heal per
+# request. Empty means either the key is MISSING (routing stripped — a
+# proxy-only model genuinely cannot work and must demote) or LiteLLM is not
+# configured at all (same conclusion). Deliberately NOT unset either.
 _LITELLM_OK=""
+_LITELLM_UNREACHABLE=""
+# Idempotent mirror of the outer-pass capture (first setter wins) — on the
+# non-docker path only this inner block runs, so capture here too, before the
+# missing-key fail-open below can strip SWITCHROOM_LITELLM.
+export SWITCHROOM_LITELLM_DECLARED="${SWITCHROOM_LITELLM_DECLARED:-${SWITCHROOM_LITELLM:-}}"
 if [ -n "${SWITCHROOM_LITELLM:-}" ] && command -v switchroom >/dev/null 2>&1; then
   sr_ll_key="$(switchroom vault get "litellm/$SWITCHROOM_AGENT_NAME/api-key" 2>/dev/null || true)"
   sr_ll_ok=""
@@ -1112,10 +1132,14 @@ if [ -n "${SWITCHROOM_LITELLM:-}" ] && command -v switchroom >/dev/null 2>&1; th
     # co-boots, the litellm proxy's heavy Python app is often not yet healthy
     # in the first few seconds. A single one-shot probe fails-open and takes
     # this agent dark (untracked) for the WHOLE session. Poll the liveliness
-    # endpoint every ~3s for up to 120s (hard budget) and only fall open if
+    # endpoint every ~3s for up to SWITCHROOM_LITELLM_BOOT_BUDGET seconds
+    # (default 240 — the INNER budget only; the outer/gateway-pass probe stays
+    # at 120s so gateway boot latency is not doubled) and only fall open if
     # it is STILL unreachable after that whole window.
     sr_ll_url="${SWITCHROOM_LITELLM_BASE:-${ANTHROPIC_BASE_URL%/anthropic}}/health/liveliness"
-    sr_ll_deadline=$(( $(date +%s) + 120 ))
+    sr_ll_budget="${SWITCHROOM_LITELLM_BOOT_BUDGET:-240}"
+    case "$sr_ll_budget" in *[!0-9]*|"") sr_ll_budget=240 ;; esac
+    sr_ll_deadline=$(( $(date +%s) + sr_ll_budget ))
     sr_ll_up=""
     while :; do
       if curl -fsS -m 5 -o /dev/null "$sr_ll_url" 2>/dev/null; then sr_ll_up="1"; break; fi
@@ -1127,8 +1151,9 @@ if [ -n "${SWITCHROOM_LITELLM:-}" ] && command -v switchroom >/dev/null 2>&1; th
       # leave it pointed at litellm so the fleet self-heals once the proxy is
       # back (the socat forwarder at 127.0.0.1:4010 reconnects per-connection).
       sr_ll_unreachable="1"
+      _LITELLM_UNREACHABLE="1"
       echo "==================== litellm UNREACHABLE ====================" >&2
-      echo "WARNING: litellm proxy unreachable at ${SWITCHROOM_LITELLM_BASE:-$ANTHROPIC_BASE_URL} after 120s of retries;" >&2
+      echo "WARNING: litellm proxy unreachable at ${SWITCHROOM_LITELLM_BASE:-$ANTHROPIC_BASE_URL} after ${sr_ll_budget}s of retries;" >&2
       echo "WARNING: Claude traffic will FAIL until it recovers — routing LEFT IN PLACE" >&2
       echo "WARNING: so it self-heals (socat forwarder reconnects per-connection)." >&2
       echo "WARNING: NOT falling back to untracked direct Anthropic OAuth." >&2
@@ -1136,7 +1161,7 @@ if [ -n "${SWITCHROOM_LITELLM:-}" ] && command -v switchroom >/dev/null 2>&1; th
     else
       sr_ll_ok="1"
     fi
-    unset sr_ll_url sr_ll_deadline sr_ll_up
+    unset sr_ll_url sr_ll_budget sr_ll_deadline sr_ll_up
   else
     sr_ll_ok="1"
   fi
@@ -1419,22 +1444,37 @@ if [ -f "{{agentDir}}/.session-model" ]; then
   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.
+# Configured-default LiteLLM guard, SPLIT BY CAUSE (2026-07-17 boot-race
+# incident: a slow LiteLLM co-boot demoted a configured-fable agent to opus on
+# the passthrough — silent divergence that persisted for the whole session).
+#
+#   - MISSING KEY / LiteLLM not configured (_LITELLM_UNREACHABLE empty):
+#     routing was STRIPPED (direct Anthropic OAuth), where `fable`/
+#     `claude-fable-5` is a retired codename and EVERY call 4xxs — a total
+#     outage. Claude agents have a safe same-class fallback: demote to opus,
+#     loudly (stderr + .session-model-alert).
+#   - PROXY UNREACHABLE, key present (_LITELLM_UNREACHABLE="1"): routing was
+#     LEFT IN PLACE pointing at the proxy. Do NOT demote — boot the declared
+#     fable model against the LiteLLM router root (the repoint case below
+#     includes the unreachable path) and run loud-degraded, the same policy as
+#     sr-* configured defaults: requests fail until the proxy heals, then work
+#     with ZERO divergence and no restart needed (per-request recovery — see
+#     the repoint comment below).
+#
+# The carrier block above already drops proxy-only OVERRIDES on a down proxy;
+# this guard covers only the configured default, which the live-config read
+# above makes a mainline path (pinning `model: fable` in yaml is the normal
+# way to run Fable).
 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"
+      if [ -n "$_LITELLM_UNREACHABLE" ]; then
+        echo "session-model: configured model '$_EFFECTIVE_MODEL' is proxy-only and LiteLLM is unreachable at boot — booting '$_EFFECTIVE_MODEL' anyway against the LiteLLM router (loud-degraded; requests fail until the proxy recovers, then self-heal per-request). NOT demoting to opus." >&2
+      else
+        echo "session-model: configured model '$_EFFECTIVE_MODEL' is proxy-only but no LiteLLM virtual key is available (routing stripped to direct Anthropic, where it would 4xx every call) — booting 'opus' instead" >&2
+        printf 'No LiteLLM virtual key was available at boot (routing stripped to direct Anthropic), so the configured model `%s` (proxy-only) cannot work — the agent booted on `opus` instead. Run `switchroom apply` on the host (it provisions the LiteLLM key), then restart this agent to return to `%s`.\n' "$_EFFECTIVE_MODEL" "$_EFFECTIVE_MODEL" >> "{{agentDir}}/.session-model-alert" 2>/dev/null || true
+        _EFFECTIVE_MODEL="opus"
+      fi
     fi
     ;;
 esac
@@ -1518,9 +1558,16 @@ printf '%s\n' "$_EFFECTIVE_EFFORT" > "{{agentDir}}/.active-session-effort" 2>/de
 # /v1/models (both `fable` and `claude-fable-5` served). Other Claude sessions
 # (opus/sonnet/haiku/default) keep the passthrough — it dodges the Opus SSE
 # re-chunk stall; Fable trades that for being routable at all.
+# Repoint fires when the proxy is LIVE (_LITELLM_OK) OR when it is unreachable
+# with the key present (_LITELLM_UNREACHABLE — routing left in place, cause
+# split above): a configured fable that survives the unreachable guard must
+# land on the ROUTER ROOT, not the model-agnostic passthrough, or it would
+# keep 4xxing even after the proxy heals. Missing-key boots never get here
+# with a proxy-only model (the guard above demoted fable to opus, and sr-*
+# had its routing stripped anyway).
 case "$_EFFECTIVE_MODEL" in
   sr-*|fable|claude-fable-5)
-    if [ -n "$_LITELLM_OK" ] && [ -n "$SWITCHROOM_LITELLM_BASE" ]; then
+    if { [ -n "$_LITELLM_OK" ] || [ -n "$_LITELLM_UNREACHABLE" ]; } && [ -n "$SWITCHROOM_LITELLM_BASE" ]; then
       export ANTHROPIC_BASE_URL="$SWITCHROOM_LITELLM_BASE"
       echo "session-model: effective model '$_EFFECTIVE_MODEL' is proxy-only (sr-*/fable) — routing via LiteLLM model router '$SWITCHROOM_LITELLM_BASE' (off /anthropic passthrough)" >&2
     fi
@@ -1531,6 +1578,46 @@ esac
 # welcome card honest. Overwrite (not consumed) — the gateway reads it at boot.
 printf '%s\n' "$_EFFECTIVE_MODEL" > "{{agentDir}}/.active-session-model" 2>/dev/null || true
 
+# --- Routing-mode observability (.routing-mode, 2026-07-17 boot-race incident) ---
+#
+# Deterministic record of WHERE this boot actually landed, written immediately
+# before exec claude (overwrite-per-boot, one line). Consumers: the gateway
+# boot card's "routing" row and any operator shell. _DECLARED_ROUTING is baked
+# at render time by declaredRoutingMode() — the POST-REPOINT mode this boot is
+# meant to land on (fable/claude-fable-5/sr-* declare router-root because the
+# repoint case below moves them there; only non-fable Claude models declare
+# passthrough) — the apply-time INTENT the landed mode is compared against.
+# Divergence (landed ≠ declared) appends a consume-once .session-model-alert
+# line the gateway relays to the operator, but ONLY when the (landed, declared)
+# PAIR differs from the PREVIOUS boot's pair — a persistently degraded agent
+# alerts once, not on every restart, yet a declared-only flip (operator changes
+# the configured model class while the agent stays stuck on the same wrong
+# landed mode) still re-alerts.
+_DECLARED_ROUTING={{{declaredRoutingQ}}}
+# When LiteLLM was never configured for this agent (no SWITCHROOM_LITELLM at
+# boot entry, captured before any strip), compose injects NO routing env — the
+# declared intent genuinely IS direct-oauth, not the model-class bake. This
+# keeps non-LiteLLM fleets from false-alerting divergence on every boot.
+if [ -z "${SWITCHROOM_LITELLM_DECLARED:-}" ]; then _DECLARED_ROUTING="direct-oauth"; fi
+case "${ANTHROPIC_BASE_URL:-}" in
+  "") _ROUTING_MODE="direct-oauth" ;;
+  */anthropic) _ROUTING_MODE="passthrough" ;;
+  *) _ROUTING_MODE="router-root" ;;
+esac
+_prev_routing_mode="$(sed -n 's/^mode=\([^ ]*\).*/\1/p' "{{agentDir}}/.routing-mode" 2>/dev/null | head -n 1 || true)"
+_prev_declared_routing="$(sed -n 's/.* declared=\([^ ]*\).*/\1/p' "{{agentDir}}/.routing-mode" 2>/dev/null | head -n 1 || true)"
+_routing_line="mode=$_ROUTING_MODE base=${ANTHROPIC_BASE_URL:-direct} model=$_EFFECTIVE_MODEL litellm_ok=${_LITELLM_OK:-0} declared=$_DECLARED_ROUTING ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+printf '%s\n' "$_routing_line" > "{{agentDir}}/.routing-mode" 2>/dev/null || true
+echo "routing: $_routing_line" >&2
+# Dedup on the (landed, declared) PAIR, not landed alone: a persistently
+# degraded agent alerts once, but if the operator flips the declared class
+# while the agent stays stuck on the same wrong landed mode, the pair changes
+# and we re-alert (LOW-2).
+if [ "$_ROUTING_MODE" != "$_DECLARED_ROUTING" ] && { [ "$_ROUTING_MODE" != "$_prev_routing_mode" ] || [ "$_DECLARED_ROUTING" != "$_prev_declared_routing" ]; }; then
+  printf 'Routing divergence: this agent landed on `%s` (base `%s`, model `%s`) but its declared routing is `%s`. Check `%s/.routing-mode` and the boot log for the cause (LiteLLM key/provision or proxy reachability).\n' "$_ROUTING_MODE" "${ANTHROPIC_BASE_URL:-direct}" "$_EFFECTIVE_MODEL" "$_DECLARED_ROUTING" "{{agentDir}}" >> "{{agentDir}}/.session-model-alert" 2>/dev/null || true
+fi
+unset _prev_routing_mode _prev_declared_routing _routing_line
+
 {{#if useSwitchroomPlugin}}
 if [ -n "$APPEND_PROMPT" ]; then
   exec claude $CONTINUE_FLAG --dangerously-load-development-channels server:switchroom-telegram --plugin-dir "{{securityPluginDir}}"{{#if hindsightEnabled}} --plugin-dir "{{agentDir}}/.claude/plugins/hindsight-memory"{{/if}} $SR_FLEET_ARG --model "$_EFFECTIVE_MODEL" $_EFFORT_ARG{{#if permissionMode}} --permission-mode {{permissionMode}}{{/if}}{{#if fallbackModelQ}} --fallback-model {{{fallbackModelQ}}}{{/if}} --append-system-prompt "$APPEND_PROMPT"{{#if dangerousMode}} --dangerously-skip-permissions{{/if}}{{#if extraCliArgs}}{{{extraCliArgs}}}{{/if}}