switchroom 0.18.30 → 0.18.32

package/dist/host-control/main.js

@@ -19265,7 +19265,8 @@ var MemoryBackendConfigSchema = exports_external.object({
     llm_model: exports_external.string().optional().describe("LiteLLM model name for Hindsight's LLM ops (retain/reflect/" + "consolidation) when the top-level `litellm.enabled` carve-out is " + "on. Defaults to a cheap OpenRouter model (routed via LiteLLM's " + "model-mapped path, not the Anthropic OAuth pass-through) to keep " + "background memory-op cost off the Claude subscription quota. Set " + "to a `claude-*` model name to route it back through the OAuth " + "pass-through instead. Has no effect when litellm is disabled."),
     api_key: exports_external.string().optional().describe("API key or vault reference for embedding provider"),
     docker_service: exports_external.boolean().default(true).describe("Whether to include Hindsight in docker-compose"),
-    url: exports_external.string().url("Hindsight URL must be a valid URL (no shell-special characters)").optional().describe("Hindsight MCP endpoint URL (e.g., http://localhost:18888/mcp/). Defaults to http://localhost:8888/mcp/.")
+    url: exports_external.string().url("Hindsight URL must be a valid URL (no shell-special characters)").optional().describe("Hindsight MCP endpoint URL (e.g., http://localhost:18888/mcp/). Defaults to http://localhost:8888/mcp/."),
+    mcp_transport: exports_external.enum(["shim", "http"]).optional().describe("How agents reach Hindsight's MCP surface. Default (unset or " + "'shim'): the lazy-connect stdio proxy `switchroom " + "hindsight-mcp-shim`, which always registers at session start " + "even when the hindsight container is down and reconnects " + "per-call. 'http' is the escape hatch that restores the legacy " + "direct Streamable-HTTP entry (session-fatal if the backend is " + "down when the agent session boots).")
   }).optional()
 });
 var VaultConfigSchema = exports_external.object({
@@ -19308,7 +19309,8 @@ var HostControlConfigSchema = exports_external.object({
   auto_release_check: AutoReleaseCheckSchema.default({}).describe("Pull-based release-triggered fleet restart (#1743). hostd polls " + "the remote release tag on a fixed interval and applies + " + "restarts the fleet (graceful) when a new release is detected. " + "Opt-in: default enabled=false.")
 });
 var WebServiceConfigSchema = exports_external.object({
-  managed: exports_external.boolean().default(false).describe("Whether `switchroom update` refreshes the web-service container " + "(dashboard + GitHub-webhook receiver) via `switchroom webd " + "install`. Default: false — existing installs run the web server " + "as the legacy `switchroom-web.service` systemd unit and must not " + "be surprised by a container takeover of host loopback 127.0.0.1:" + "8080 mid-update. Set true ONLY after cutting over to the " + "container (stop+disable the systemd unit, `switchroom webd " + "install`). The container runs in its own compose project " + "(`switchroom-web`), separate from the agent fleet, with " + "network_mode: host so it keeps owning loopback:8080 for the " + "cloudflared tunnel + tailscale serve consumers.")
+  managed: exports_external.boolean().default(false).describe("Whether `switchroom update` refreshes the web-service container " + "(dashboard + GitHub-webhook receiver) via `switchroom webd " + "install`. Default: false — existing installs run the web server " + "as the legacy `switchroom-web.service` systemd unit and must not " + "be surprised by a container takeover of host loopback 127.0.0.1:" + "8080 mid-update. Set true ONLY after cutting over to the " + "container (stop+disable the systemd unit, `switchroom webd " + "install`). The container runs in its own compose project " + "(`switchroom-web`), separate from the agent fleet, with " + "network_mode: host so it keeps owning loopback:8080 for the " + "cloudflared tunnel + tailscale serve consumers."),
+  port: exports_external.number().int().min(1).max(65535).default(8080).describe("Host loopback port the web server listens on (127.0.0.1:<port>). " + "Default: 8080. Set this when another service owns 8080 on the " + "host (e.g. UniFi OS Server) — `switchroom webd install` and the " + "`switchroom update` refresh-web step both honor it, so a custom " + "port survives updates instead of being silently reverted to " + "8080 by the regenerated compose file. Remember to point the " + "host-side consumers (cloudflared tunnel, `tailscale serve`) at " + "the same port.")
 });
 var FleetHealthConfigSchema = exports_external.object({
   owner_agent: exports_external.string().regex(/^[a-z0-9][a-z0-9_-]{0,50}$/, {
@@ -26645,7 +26647,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.30";
+var VERSION = "0.18.32";
 
 // src/cli/resolve-version.ts
 function readPackageVersion() {

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

@@ -4685,7 +4685,8 @@ var init_schema = __esm(() => {
       llm_model: exports_external.string().optional().describe("LiteLLM model name for Hindsight's LLM ops (retain/reflect/" + "consolidation) when the top-level `litellm.enabled` carve-out is " + "on. Defaults to a cheap OpenRouter model (routed via LiteLLM's " + "model-mapped path, not the Anthropic OAuth pass-through) to keep " + "background memory-op cost off the Claude subscription quota. Set " + "to a `claude-*` model name to route it back through the OAuth " + "pass-through instead. Has no effect when litellm is disabled."),
       api_key: exports_external.string().optional().describe("API key or vault reference for embedding provider"),
       docker_service: exports_external.boolean().default(true).describe("Whether to include Hindsight in docker-compose"),
-      url: exports_external.string().url("Hindsight URL must be a valid URL (no shell-special characters)").optional().describe("Hindsight MCP endpoint URL (e.g., http://localhost:18888/mcp/). Defaults to http://localhost:8888/mcp/.")
+      url: exports_external.string().url("Hindsight URL must be a valid URL (no shell-special characters)").optional().describe("Hindsight MCP endpoint URL (e.g., http://localhost:18888/mcp/). Defaults to http://localhost:8888/mcp/."),
+      mcp_transport: exports_external.enum(["shim", "http"]).optional().describe("How agents reach Hindsight's MCP surface. Default (unset or " + "'shim'): the lazy-connect stdio proxy `switchroom " + "hindsight-mcp-shim`, which always registers at session start " + "even when the hindsight container is down and reconnects " + "per-call. 'http' is the escape hatch that restores the legacy " + "direct Streamable-HTTP entry (session-fatal if the backend is " + "down when the agent session boots).")
     }).optional()
   });
   VaultConfigSchema = exports_external.object({
@@ -4728,7 +4729,8 @@ var init_schema = __esm(() => {
     auto_release_check: AutoReleaseCheckSchema.default({}).describe("Pull-based release-triggered fleet restart (#1743). hostd polls " + "the remote release tag on a fixed interval and applies + " + "restarts the fleet (graceful) when a new release is detected. " + "Opt-in: default enabled=false.")
   });
   WebServiceConfigSchema = exports_external.object({
-    managed: exports_external.boolean().default(false).describe("Whether `switchroom update` refreshes the web-service container " + "(dashboard + GitHub-webhook receiver) via `switchroom webd " + "install`. Default: false — existing installs run the web server " + "as the legacy `switchroom-web.service` systemd unit and must not " + "be surprised by a container takeover of host loopback 127.0.0.1:" + "8080 mid-update. Set true ONLY after cutting over to the " + "container (stop+disable the systemd unit, `switchroom webd " + "install`). The container runs in its own compose project " + "(`switchroom-web`), separate from the agent fleet, with " + "network_mode: host so it keeps owning loopback:8080 for the " + "cloudflared tunnel + tailscale serve consumers.")
+    managed: exports_external.boolean().default(false).describe("Whether `switchroom update` refreshes the web-service container " + "(dashboard + GitHub-webhook receiver) via `switchroom webd " + "install`. Default: false — existing installs run the web server " + "as the legacy `switchroom-web.service` systemd unit and must not " + "be surprised by a container takeover of host loopback 127.0.0.1:" + "8080 mid-update. Set true ONLY after cutting over to the " + "container (stop+disable the systemd unit, `switchroom webd " + "install`). The container runs in its own compose project " + "(`switchroom-web`), separate from the agent fleet, with " + "network_mode: host so it keeps owning loopback:8080 for the " + "cloudflared tunnel + tailscale serve consumers."),
+    port: exports_external.number().int().min(1).max(65535).default(8080).describe("Host loopback port the web server listens on (127.0.0.1:<port>). " + "Default: 8080. Set this when another service owns 8080 on the " + "host (e.g. UniFi OS Server) — `switchroom webd install` and the " + "`switchroom update` refresh-web step both honor it, so a custom " + "port survives updates instead of being silently reverted to " + "8080 by the regenerated compose file. Remember to point the " + "host-side consumers (cloudflared tunnel, `tailscale serve`) at " + "the same port.")
   });
   FleetHealthConfigSchema = exports_external.object({
     owner_agent: exports_external.string().regex(/^[a-z0-9][a-z0-9_-]{0,50}$/, {

package/dist/vault/broker/server.js

@@ -4685,7 +4685,8 @@ var init_schema = __esm(() => {
       llm_model: exports_external.string().optional().describe("LiteLLM model name for Hindsight's LLM ops (retain/reflect/" + "consolidation) when the top-level `litellm.enabled` carve-out is " + "on. Defaults to a cheap OpenRouter model (routed via LiteLLM's " + "model-mapped path, not the Anthropic OAuth pass-through) to keep " + "background memory-op cost off the Claude subscription quota. Set " + "to a `claude-*` model name to route it back through the OAuth " + "pass-through instead. Has no effect when litellm is disabled."),
       api_key: exports_external.string().optional().describe("API key or vault reference for embedding provider"),
       docker_service: exports_external.boolean().default(true).describe("Whether to include Hindsight in docker-compose"),
-      url: exports_external.string().url("Hindsight URL must be a valid URL (no shell-special characters)").optional().describe("Hindsight MCP endpoint URL (e.g., http://localhost:18888/mcp/). Defaults to http://localhost:8888/mcp/.")
+      url: exports_external.string().url("Hindsight URL must be a valid URL (no shell-special characters)").optional().describe("Hindsight MCP endpoint URL (e.g., http://localhost:18888/mcp/). Defaults to http://localhost:8888/mcp/."),
+      mcp_transport: exports_external.enum(["shim", "http"]).optional().describe("How agents reach Hindsight's MCP surface. Default (unset or " + "'shim'): the lazy-connect stdio proxy `switchroom " + "hindsight-mcp-shim`, which always registers at session start " + "even when the hindsight container is down and reconnects " + "per-call. 'http' is the escape hatch that restores the legacy " + "direct Streamable-HTTP entry (session-fatal if the backend is " + "down when the agent session boots).")
     }).optional()
   });
   VaultConfigSchema = exports_external.object({
@@ -4728,7 +4729,8 @@ var init_schema = __esm(() => {
     auto_release_check: AutoReleaseCheckSchema.default({}).describe("Pull-based release-triggered fleet restart (#1743). hostd polls " + "the remote release tag on a fixed interval and applies + " + "restarts the fleet (graceful) when a new release is detected. " + "Opt-in: default enabled=false.")
   });
   WebServiceConfigSchema = exports_external.object({
-    managed: exports_external.boolean().default(false).describe("Whether `switchroom update` refreshes the web-service container " + "(dashboard + GitHub-webhook receiver) via `switchroom webd " + "install`. Default: false — existing installs run the web server " + "as the legacy `switchroom-web.service` systemd unit and must not " + "be surprised by a container takeover of host loopback 127.0.0.1:" + "8080 mid-update. Set true ONLY after cutting over to the " + "container (stop+disable the systemd unit, `switchroom webd " + "install`). The container runs in its own compose project " + "(`switchroom-web`), separate from the agent fleet, with " + "network_mode: host so it keeps owning loopback:8080 for the " + "cloudflared tunnel + tailscale serve consumers.")
+    managed: exports_external.boolean().default(false).describe("Whether `switchroom update` refreshes the web-service container " + "(dashboard + GitHub-webhook receiver) via `switchroom webd " + "install`. Default: false — existing installs run the web server " + "as the legacy `switchroom-web.service` systemd unit and must not " + "be surprised by a container takeover of host loopback 127.0.0.1:" + "8080 mid-update. Set true ONLY after cutting over to the " + "container (stop+disable the systemd unit, `switchroom webd " + "install`). The container runs in its own compose project " + "(`switchroom-web`), separate from the agent fleet, with " + "network_mode: host so it keeps owning loopback:8080 for the " + "cloudflared tunnel + tailscale serve consumers."),
+    port: exports_external.number().int().min(1).max(65535).default(8080).describe("Host loopback port the web server listens on (127.0.0.1:<port>). " + "Default: 8080. Set this when another service owns 8080 on the " + "host (e.g. UniFi OS Server) — `switchroom webd install` and the " + "`switchroom update` refresh-web step both honor it, so a custom " + "port survives updates instead of being silently reverted to " + "8080 by the regenerated compose file. Remember to point the " + "host-side consumers (cloudflared tunnel, `tailscale serve`) at " + "the same port.")
   });
   FleetHealthConfigSchema = exports_external.object({
     owner_agent: exports_external.string().regex(/^[a-z0-9][a-z0-9_-]{0,50}$/, {

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.30",
+  "version": "0.18.32",
   "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": {
@@ -28,7 +28,7 @@
     "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: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 --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",
     "lint:plugin-references": "node scripts/check-plugin-references.mjs",
     "lint:bot-api-wrapping": "bash scripts/check-bot-api-wrapping.sh",
@@ -36,6 +36,7 @@
     "lint:no-pii": "node scripts/check-no-pii-secrets.mjs",
     "lint:web-subscription-honest": "node scripts/check-web-subscription-honest.mjs",
     "lint:no-broadcast-delivery": "node scripts/check-no-broadcast-delivery.mjs",
+    "lint:gateway-line-ratchet": "node scripts/check-gateway-line-ratchet.mjs",
     "prepublishOnly": "npm run build && npm run lint && npm test"
   },
   "dependencies": {

package/profiles/_base/start.sh.hbs

@@ -602,16 +602,54 @@ export HINDSIGHT_SENDER_BANKS_JSON={{{hindsightSenderBanksJsonQ}}}
 {{#if hindsightTopicFilterMode}}
 export HINDSIGHT_TOPIC_FILTER_MODE={{hindsightTopicFilterMode}}
 {{/if}}
-# Wait for Hindsight API to be reachable before launching Claude, otherwise
-# the MCP server connection fails at startup with "1 MCP server failed".
+# Give Claude Code a longer MCP server-startup budget (ms). The default can
+# race a Hindsight restart window; the boot gate below usually absorbs it,
+# but this keeps the in-session connect attempt itself patient too.
+# Documented Claude Code env var (MCP server startup timeout).
+export MCP_TIMEOUT="${MCP_TIMEOUT:-30000}"
+# Wait for Hindsight MCP to be READY before launching Claude, otherwise the
+# MCP server connection fails at startup with "1 MCP server failed" and the
+# session boots toolless (incident 2026-07-18: clerk booted toolless despite
+# a 30s bare-GET gate — the endpoint returned HTTP 200 mid-restart while a
+# real MCP initialize still failed). So: probe with an actual JSON-RPC
+# initialize POST and require a JSON-RPC result, not just HTTP 200.
+# Bounded at 120s of real wall-clock time (each probe costs up to ~3s of
+# curl timeout + 1s sleep, so an iteration count would overshoot — measure
+# elapsed seconds against the deadline instead; HINDSIGHT_WAIT holds real
+# elapsed seconds). On timeout we log a warning and boot anyway (degraded
+# beats never-boots — the plugin reconnects once Hindsight recovers).
 HINDSIGHT_WAIT=0
-while [ $HINDSIGHT_WAIT -lt 30 ]; do
-  if curl -sf -o /dev/null --max-time 2 {{{hindsightApiBaseUrlQ}}}/mcp/; then
+HINDSIGHT_READY=0
+_hs_start=$(date +%s)
+while [ $HINDSIGHT_WAIT -lt 120 ]; do
+  _hs_resp=$(curl -sf --max-time 3 -i \
+       -X POST {{{hindsightApiBaseUrlQ}}}/mcp/ \
+       -H "Content-Type: application/json" \
+       -H "Accept: application/json, text/event-stream" \
+       -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"switchroom-boot-gate","version":"1.0"}}}' \
+       2>/dev/null)
+  # Match on serverInfo — only present in a successful initialize result;
+  # a JSON-RPC *error* body could legitimately contain the substring "result".
+  if printf '%s\n' "$_hs_resp" | grep -q '"serverInfo"'; then
+    HINDSIGHT_READY=1
+    # Best-effort cleanup of the probe's server-side MCP session (one would
+    # leak per boot otherwise). Header may be absent on stateless servers.
+    _hs_sid=$(printf '%s\n' "$_hs_resp" | tr -d '\r' | sed -n 's/^[Mm][Cc][Pp]-[Ss]ession-[Ii][Dd]: *//p' | head -n 1)
+    if [ -n "$_hs_sid" ]; then
+      curl -s -o /dev/null --max-time 2 -X DELETE {{{hindsightApiBaseUrlQ}}}/mcp/ \
+        -H "Mcp-Session-Id: $_hs_sid" 2>/dev/null || true
+    fi
+    HINDSIGHT_WAIT=$(( $(date +%s) - _hs_start ))
     break
   fi
   sleep 1
-  HINDSIGHT_WAIT=$((HINDSIGHT_WAIT + 1))
+  HINDSIGHT_WAIT=$(( $(date +%s) - _hs_start ))
 done
+if [ "$HINDSIGHT_READY" = "1" ]; then
+  echo "start.sh: hindsight boot gate — MCP initialize OK after ${HINDSIGHT_WAIT}s" >&2
+else
+  echo "start.sh: WARNING hindsight boot gate TIMED OUT after ${HINDSIGHT_WAIT}s — MCP initialize never returned a JSON-RPC result; launching claude anyway (memory tools may be unavailable this session)" >&2
+fi
 {{/if}}
 {{#if userEnvQuoted}}
 # User-declared env vars from switchroom.yaml (agent + defaults merged).
@@ -1170,15 +1208,92 @@ 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
@@ -1304,6 +1419,26 @@ 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.
+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