switchroom 0.18.9 → 0.18.11

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

@@ -4703,6 +4703,7 @@ var init_schema = __esm(() => {
         uid: exports_external.number().int().nonnegative().optional().describe("Optional UID to chown the consumer socket to (defaults to 0 = root, " + "suitable for sibling containers running as root)."),
         mirror_dir: exports_external.string().optional().describe("Optional host-side directory path. When set, the broker actively " + "writes the consumer's effective-account `.credentials.json` mirror " + "here — in addition to serving creds on demand via `get-credentials`. " + "Use this to eliminate the pull-latency gap: without a mirror the " + "consumer only gets failover creds at its next scheduled re-fetch " + "(up to 30 min). With a mirror the broker pushes failover creds " + "immediately when it detects exhaustion (consumer-quota-sensor tick, " + "or a mark-exhausted RPC on the pinned account). The directory must " + "be accessible to the broker container (bind-mounted from the host) " + "and to the consumer container; the broker writes " + "`<mirror_dir>/.credentials.json` atomically. Chown is attempted to " + "`uid` (default 0) — swallowed when CAP_CHOWN is absent.")
       })).optional().describe("Non-agent peers that hold a broker socket (RFC H §4.8). Each gets " + "its own `/run/switchroom/auth-broker/<name>/sock` chowned to its UID. " + "Consumers cannot be admins; a consumer name that collides with an " + "agent (whether that agent has `admin: true` or not) is a config " + "error caught at schema validation."),
+      proactive_failover_pct: exports_external.number().min(1).max(99).optional().describe("Soft-avoid threshold (percent) for proactive auth failover (#3031). " + "When set (e.g. 95), an account whose fresh 7-day utilization is at/" + "above this value — or whose 5h utilization is at/above min(pct+3, " + "98) — enters the SOFT-AVOID preference tier: the broker prefers a " + "fully-eligible fallback account on the serving path, without ever " + "blocking the account (the hard wall stays 99.5). Enter/exit uses " + "hysteresis (exit below pct-5 or on window reset) so the preference " + "does not flap between probe ticks. Accounts serving past the wall " + "via `allow_overage_accounts` are never soft-avoided. UNSET (the " + "default) disables the tier entirely — behavior is identical to a " + "fleet without this field."),
       allow_overage_accounts: exports_external.array(exports_external.string().min(1)).optional().describe("Opt-in list of account labels (bare strings matching `auth.active` / " + "`auth.fallback_order` entries) that may be served PAST the weekly " + "utilization wall when Anthropic overage billing is available for the " + "account (`overageStatus === 'allowed'`). Overage is REAL MONEY — " + "default is empty (no account gets this). An account in this list is " + "only kept eligible when its fresh quota snapshot reports " + "`overageStatus: 'allowed'` AND `overageDisabledReason` is NOT " + "'out_of_credits' (i.e. the overage credit has not been exhausted). " + "As soon as `overageDisabledReason` becomes 'out_of_credits', the " + "account is blocked immediately regardless of this flag. Overage lifts " + "ONLY the utilization wall — it cannot lift an active exhaustion mark " + "written by a real 429 (`mark-exhausted`).")
     }).optional().describe("Switchroom-auth-broker configuration (RFC H). Fleet-wide active account, " + "fallback order, admin-agent ACL, and ephemeral-consumer surface. " + "Required from the v0.8+ schema onwards; pre-v0.8 fleets are migrated " + "in-place by `switchroom apply` (see src/auth/migrate-schema.ts)."),
     drive: GoogleWorkspaceConfigSchema.describe("RFC D legacy key — use `google_workspace:` instead. Optional Google " + "Workspace onboarding configuration. When set, supplies Google OAuth " + "client credentials, the approver allowlist for `switchroom drive " + "connect`, and the optional tier knob. Env vars " + "(SWITCHROOM_GOOGLE_CLIENT_ID, SWITCHROOM_GOOGLE_CLIENT_SECRET, " + "SWITCHROOM_APPROVER_USER_ID) take precedence over this block when " + "set, preserving back-compat with the env-only flow shipped in #766."),
@@ -18859,6 +18860,7 @@ import { homedir as homedir2 } from "node:os";
 init_loader();
 
 // src/cli/agent-config.ts
+init_loader();
 init_merge();
 
 // src/vault/broker/acl.ts
@@ -18886,7 +18888,7 @@ import_handlebars.default.registerHelper("isNumber", (value) => {
   return typeof value === "number" && Number.isFinite(value);
 });
 var SHARED_FRAGMENTS_DIR = resolve4(PROFILES_ROOT, "_shared");
-var SHARED_FRAGMENTS = ["vault-protocol", "agent-self-service", "execution-discipline", "reply-discipline"];
+var SHARED_FRAGMENTS = ["vault-protocol", "agent-self-service", "execution-discipline", "reply-discipline", "dev-protocol"];
 for (const name of SHARED_FRAGMENTS) {
   const fragPath = join2(SHARED_FRAGMENTS_DIR, `${name}.md.hbs`);
   if (existsSync4(fragPath)) {

package/dist/vault/broker/server.js

@@ -4703,6 +4703,7 @@ var init_schema = __esm(() => {
         uid: exports_external.number().int().nonnegative().optional().describe("Optional UID to chown the consumer socket to (defaults to 0 = root, " + "suitable for sibling containers running as root)."),
         mirror_dir: exports_external.string().optional().describe("Optional host-side directory path. When set, the broker actively " + "writes the consumer's effective-account `.credentials.json` mirror " + "here — in addition to serving creds on demand via `get-credentials`. " + "Use this to eliminate the pull-latency gap: without a mirror the " + "consumer only gets failover creds at its next scheduled re-fetch " + "(up to 30 min). With a mirror the broker pushes failover creds " + "immediately when it detects exhaustion (consumer-quota-sensor tick, " + "or a mark-exhausted RPC on the pinned account). The directory must " + "be accessible to the broker container (bind-mounted from the host) " + "and to the consumer container; the broker writes " + "`<mirror_dir>/.credentials.json` atomically. Chown is attempted to " + "`uid` (default 0) — swallowed when CAP_CHOWN is absent.")
       })).optional().describe("Non-agent peers that hold a broker socket (RFC H §4.8). Each gets " + "its own `/run/switchroom/auth-broker/<name>/sock` chowned to its UID. " + "Consumers cannot be admins; a consumer name that collides with an " + "agent (whether that agent has `admin: true` or not) is a config " + "error caught at schema validation."),
+      proactive_failover_pct: exports_external.number().min(1).max(99).optional().describe("Soft-avoid threshold (percent) for proactive auth failover (#3031). " + "When set (e.g. 95), an account whose fresh 7-day utilization is at/" + "above this value — or whose 5h utilization is at/above min(pct+3, " + "98) — enters the SOFT-AVOID preference tier: the broker prefers a " + "fully-eligible fallback account on the serving path, without ever " + "blocking the account (the hard wall stays 99.5). Enter/exit uses " + "hysteresis (exit below pct-5 or on window reset) so the preference " + "does not flap between probe ticks. Accounts serving past the wall " + "via `allow_overage_accounts` are never soft-avoided. UNSET (the " + "default) disables the tier entirely — behavior is identical to a " + "fleet without this field."),
       allow_overage_accounts: exports_external.array(exports_external.string().min(1)).optional().describe("Opt-in list of account labels (bare strings matching `auth.active` / " + "`auth.fallback_order` entries) that may be served PAST the weekly " + "utilization wall when Anthropic overage billing is available for the " + "account (`overageStatus === 'allowed'`). Overage is REAL MONEY — " + "default is empty (no account gets this). An account in this list is " + "only kept eligible when its fresh quota snapshot reports " + "`overageStatus: 'allowed'` AND `overageDisabledReason` is NOT " + "'out_of_credits' (i.e. the overage credit has not been exhausted). " + "As soon as `overageDisabledReason` becomes 'out_of_credits', the " + "account is blocked immediately regardless of this flag. Overage lifts " + "ONLY the utilization wall — it cannot lift an active exhaustion mark " + "written by a real 429 (`mark-exhausted`).")
     }).optional().describe("Switchroom-auth-broker configuration (RFC H). Fleet-wide active account, " + "fallback order, admin-agent ACL, and ephemeral-consumer surface. " + "Required from the v0.8+ schema onwards; pre-v0.8 fleets are migrated " + "in-place by `switchroom apply` (see src/auth/migrate-schema.ts)."),
     drive: GoogleWorkspaceConfigSchema.describe("RFC D legacy key — use `google_workspace:` instead. Optional Google " + "Workspace onboarding configuration. When set, supplies Google OAuth " + "client credentials, the approver allowlist for `switchroom drive " + "connect`, and the optional tier knob. Env vars " + "(SWITCHROOM_GOOGLE_CLIENT_ID, SWITCHROOM_GOOGLE_CLIENT_SECRET, " + "SWITCHROOM_APPROVER_USER_ID) take precedence over this block when " + "set, preserving back-compat with the env-only flow shipped in #766."),
@@ -18095,6 +18096,7 @@ import { homedir as homedir2 } from "node:os";
 init_loader();
 
 // src/cli/agent-config.ts
+init_loader();
 init_merge();
 
 // src/config/google-workspace-acl.ts
@@ -18346,7 +18348,7 @@ import_handlebars.default.registerHelper("isNumber", (value) => {
   return typeof value === "number" && Number.isFinite(value);
 });
 var SHARED_FRAGMENTS_DIR = resolve4(PROFILES_ROOT, "_shared");
-var SHARED_FRAGMENTS = ["vault-protocol", "agent-self-service", "execution-discipline", "reply-discipline"];
+var SHARED_FRAGMENTS = ["vault-protocol", "agent-self-service", "execution-discipline", "reply-discipline", "dev-protocol"];
 for (const name of SHARED_FRAGMENTS) {
   const fragPath = join2(SHARED_FRAGMENTS_DIR, `${name}.md.hbs`);
   if (existsSync4(fragPath)) {

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.9",
+  "version": "0.18.11",
   "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": {

package/profiles/_base/start.sh.hbs

@@ -1067,21 +1067,21 @@ fi
 
 # --- Session model resolution (durable .session-model + .relaunch-model-intent) ---
 #
-# Contract: reference/rfcs/session-model-stickiness.md. A positively-
-# confirmed `/model X` switch persists as `{{agentDir}}/.session-model`
-# (one-line JSON written by the gateway). Whether THIS boot applies it is
-# decided by the one-shot `.relaunch-model-intent` file, stamped by the
-# gateway immediately before every switchroom-managed bounce:
+# Contract: reference/rfcs/session-model-stickiness.md (#3039 revision). A
+# positively-confirmed `/model X` switch persists as
+# `{{agentDir}}/.session-model` (one-line JSON written by the gateway) and is
+# honored on EVERY boot — deploy, watchdog bounce, raw `docker restart`,
+# host reboot, crash. It is cleared only by:
 #
-#   fresh (<10 min by embedded ts) "keep" intent  → apply the override
-#   anything else (revert / absent / stale / corrupt) → delete the override,
-#     boot the configured default, and (when an override was actually
-#     removed) write a `.session-model-alert` notice naming why.
+#   - explicit user action (`/model default` deletes it live; a fresh
+#     (<10 min) explicit "revert" `.relaunch-model-intent` reverts at boot)
+#   - invalidation: corrupt/malformed file, or the configured yaml `model:`
+#     changed since the switch
 #
-# Default is REVERT (operator decision 2026-07): a crash, OOM, raw
-# `docker restart`, host reboot, or deploy writes no intent and therefore
-# reverts to the yaml model. Watchdog/recovery bounces run gateway code and
-# stamp "keep" before SIGTERM, so a confirmed switch survives them.
+# Every clearing path writes `.session-model-alert`, which the gateway
+# relays to the operator chat once at boot — an override is never dropped
+# silently. Default (no intent / stale / corrupt intent) is KEEP (operator
+# decision 2026-07-11, superseding the earlier revert-by-default).
 #
 # 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
@@ -1117,14 +1117,18 @@ fi
 # Freshness clock is the EMBEDDED ts (ms), never file mtime — same clock the
 # gateway writes with.
 _sm_reason=""
+_sm_revert=""
 if [ -f "{{agentDir}}/.relaunch-model-intent" ]; then
   _int_raw="$(cat "{{agentDir}}/.relaunch-model-intent" 2>/dev/null || true)"
   rm -f "{{agentDir}}/.relaunch-model-intent"
   _int="$(printf '%s' "$_int_raw" | sed -n 's/.*"intent"[[:space:]]*:[[:space:]]*"\([a-z]*\)".*/\1/p')"
   _int_ts="$(printf '%s' "$_int_raw" | sed -n 's/.*"ts"[[:space:]]*:[[:space:]]*\([0-9]\{1,\}\).*/\1/p')"
   _sm_reason="$(printf '%s' "$_int_raw" | sed -n 's/.*"reason"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')"
-  if [ "$_int" = "keep" ] && [ -n "$_int_ts" ] && [ $(( $(date +%s) * 1000 - _int_ts )) -lt 600000 ]; then
-    _sm_keep="1"
+  # #3039: boot default is KEEP. Only a FRESH explicit "revert" intent
+  # (stamped by an explicit user/gateway revert path) clears the override.
+  # A stale or corrupt intent counts as no intent → keep.
+  if [ "$_int" = "revert" ] && [ -n "$_int_ts" ] && [ $(( $(date +%s) * 1000 - _int_ts )) -lt 600000 ]; then
+    _sm_revert="1"
   fi
   unset _int_raw _int _int_ts
 fi
@@ -1134,13 +1138,13 @@ if [ -f "{{agentDir}}/.session-model" ]; then
   _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')"
   _sm_ts="$(printf '%s' "$_smf" | sed -n 's/.*"ts"[[:space:]]*:[[:space:]]*\([0-9]\{1,\}\).*/\1/p')"
-  if [ -z "$_sm_keep" ]; then
-    # No fresh keep intent → deliberate restart, crash, external container
-    # restart, or deploy. Revert to the configured default and say so.
-    rm -f "{{agentDir}}/.session-model"
-    _sm_why="${_sm_reason:-no keep intent — crash, external container restart, or deploy}"
+  if [ -n "$_sm_revert" ]; then
+    # Explicit fresh revert intent — the ONLY boot path that clears a valid
+    # override by design (#3039). Everything else keeps.
+    rm -f "{{agentDir}}/.session-model" "{{agentDir}}/.session-model-kept-notified"
+    _sm_why="${_sm_reason:-explicit revert intent}"
     echo "session-model: reverting to configured default '$_EFFECTIVE_MODEL' — $_sm_why (session override '$_sm_model' cleared)" >&2
-    printf 'Session model override `%s` was cleared — this relaunch reverted to the configured default `%s` (%s). Re-issue /model %s to switch back.\n' "$_sm_model" "$_EFFECTIVE_MODEL" "$_sm_why" "$_sm_model" > "{{agentDir}}/.session-model-alert" 2>/dev/null || true
+    printf 'Session model override `%s` was cleared as requested (%s) — this relaunch booted the configured default `%s`. Re-issue /model %s to switch back.\n' "$_sm_model" "$_sm_why" "$_EFFECTIVE_MODEL" "$_sm_model" > "{{agentDir}}/.session-model-alert" 2>/dev/null || true
     unset _sm_why
   # Shape gate — kept BYTE-IDENTICAL with MODEL_ARG_RE in
   # telegram-plugin/gateway/model-command.ts. `/` is allowed for
@@ -1151,20 +1155,18 @@ if [ -f "{{agentDir}}/.session-model" ]; then
   # passes if ANY line matches — a multiline value must never reach
   # `claude --model` (parity with parseSessionModel's single-string check).
   elif [ "$(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
-    rm -f "{{agentDir}}/.session-model"
+    # Invalid carrier (#3039): fall back to the configured default AND tell
+    # the operator once — never a silent stderr-only drop.
+    rm -f "{{agentDir}}/.session-model" "{{agentDir}}/.session-model-kept-notified"
     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 since the switch → the override is
-    # against a default that no longer exists. Invalidate + announce.
-    rm -f "{{agentDir}}/.session-model"
+    # against a default that no longer exists (it may name a retired model).
+    # Invalidate + announce once (#3039 invalid-carrier fallback).
+    rm -f "{{agentDir}}/.session-model" "{{agentDir}}/.session-model-kept-notified"
     echo "session-model: configured default changed ('$_sm_cfg' → '$_EFFECTIVE_MODEL') — clearing session override '$_sm_model'" >&2
     printf 'The configured default model changed (`%s` → `%s`), so your session override to `%s` was cleared — 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 [ -n "$_sm_ts" ] && [ $(( $(date +%s) * 1000 - _sm_ts )) -gt 604800000 ]; then
-    # 7-day staleness bound (belt-and-braces vs version-rollback resurrection
-    # and long-forgotten overrides).
-    rm -f "{{agentDir}}/.session-model"
-    echo "session-model: session override '$_sm_model' is older than 7 days — expiring it, using configured default '$_EFFECTIVE_MODEL'" >&2
-    printf 'Session model override `%s` expired (older than 7 days) — the agent booted on its configured default `%s`. Re-issue /model %s if you still want it.\n' "$_sm_model" "$_EFFECTIVE_MODEL" "$_sm_model" > "{{agentDir}}/.session-model-alert" 2>/dev/null || true
   else
     case "$_sm_model" in
       sr-*)
@@ -1183,13 +1185,93 @@ if [ -f "{{agentDir}}/.session-model" ]; then
         ;;
     esac
     if [ "$_EFFECTIVE_MODEL" = "$_sm_model" ]; then
-      echo "session-model: keeping session override '$_sm_model' across this switchroom-managed relaunch${_sm_reason:+ ($_sm_reason)}" >&2
-      printf 'Session model override `%s` kept across this relaunch%s. It reverts on /restart, agent restart, crash, or an external container restart; /model default clears it now.\n' "$_sm_model" "${_sm_reason:+ ($_sm_reason)}" > "{{agentDir}}/.session-model-alert" 2>/dev/null || true
+      echo "session-model: keeping session override '$_sm_model' across this relaunch${_sm_reason:+ ($_sm_reason)}" >&2
+      # #3042 item 4: notify the chat ONCE per kept value — a watchdog bounce
+      # loop must not storm the operator with identical "kept" alerts. The
+      # sentinel is cleared on every path that clears the override.
+      if [ "$(cat "{{agentDir}}/.session-model-kept-notified" 2>/dev/null || true)" != "$_sm_model" ]; then
+        printf 'Session model override `%s` kept across this relaunch%s. It persists across restarts and deploys; /model default clears it.\n' "$_sm_model" "${_sm_reason:+ ($_sm_reason)}" > "{{agentDir}}/.session-model-alert" 2>/dev/null || true
+        printf '%s\n' "$_sm_model" > "{{agentDir}}/.session-model-kept-notified" 2>/dev/null || true
+      fi
     fi
   fi
   unset _smf _sm_model _sm_cfg _sm_ts
 fi
-unset _sm_keep _sm_reason
+unset _sm_keep _sm_reason _sm_revert
+
+# --- Override crashloop self-heal (#3042 review blocker 2b) ---
+#
+# Under keep-by-default an invalid-but-shape-valid persisted model (a typo
+# persisted at shutdown, or a confirmed model later retired) would make every
+# boot exec `claude --model <bad>` and die with the gateway dead — recovery
+# would need a host shell. Detect the loop from inside: when an override is
+# ACTIVE, stamp a boot-attempt counter just before exec; a healthy run makes
+# the next boot arrive much later (stamp stale → counter resets), while a
+# fast crashloop re-enters here within seconds (docker backoff caps ≈1 min).
+# Three consecutive fast boots with the same override → clear the carrier,
+# boot the configured default, and alert the chat once.
+_SM_CFG_RECORDED="$(cat "{{agentDir}}/.configured-default-model" 2>/dev/null | tr -d '[:space:]' || true)"
+if [ -n "$_SM_CFG_RECORDED" ] && [ "$_EFFECTIVE_MODEL" != "$_SM_CFG_RECORDED" ] && [ -f "{{agentDir}}/.session-model" ]; then
+  _bl_now="$(date +%s)"
+  _bl_cnt=0
+  _bl_prev=0
+  if [ -f "{{agentDir}}/.session-model-boot-attempts" ]; then
+    read -r _bl_cnt _bl_prev < "{{agentDir}}/.session-model-boot-attempts" 2>/dev/null || true
+  fi
+  case "$_bl_cnt" in (''|*[!0-9]*) _bl_cnt=0;; esac
+  case "$_bl_prev" in (''|*[!0-9]*) _bl_prev=0;; esac
+  if [ $(( _bl_now - _bl_prev )) -lt 150 ]; then _bl_cnt=$(( _bl_cnt + 1 )); else _bl_cnt=1; fi
+  if [ "$_bl_cnt" -ge 3 ]; then
+    echo "session-model: override '$_EFFECTIVE_MODEL' appears to be crashlooping the session ($_bl_cnt fast boots) — clearing it, booting configured default '$_SM_CFG_RECORDED'" >&2
+    printf 'Session model override `%s` was cleared automatically: the agent failed to stay up %s boots in a row with it active (the model may be invalid or retired). Booting the configured default `%s`. Re-issue /model <name> if you want a different model.\n' "$_EFFECTIVE_MODEL" "$_bl_cnt" "$_SM_CFG_RECORDED" >> "{{agentDir}}/.session-model-alert" 2>/dev/null || true
+    rm -f "{{agentDir}}/.session-model" "{{agentDir}}/.session-model-boot-attempts" "{{agentDir}}/.session-model-kept-notified"
+    _EFFECTIVE_MODEL="$_SM_CFG_RECORDED"
+  else
+    printf '%s %s\n' "$_bl_cnt" "$_bl_now" > "{{agentDir}}/.session-model-boot-attempts" 2>/dev/null || true
+  fi
+  unset _bl_now _bl_cnt _bl_prev
+else
+  # No active override this boot — a stale counter must not bite a future one.
+  rm -f "{{agentDir}}/.session-model-boot-attempts"
+fi
+unset _SM_CFG_RECORDED
+
+# --- Session effort resolution (durable .session-effort, #3039) ---
+#
+# The `/effort` sibling of the block above. A positively-confirmed `/effort`
+# apply persists `{{agentDir}}/.session-effort` (one-line JSON
+# {"level","configuredDefaultAtWrite","ts"} written by the gateway). It is
+# honored on every boot and cleared only by `/effort default` (live delete)
+# or invalidation here (corrupt file / configured `thinking_effort:` changed)
+# — each invalidation appends to `.session-model-alert` so the gateway's
+# boot relay tells the operator once.
+_EFFECTIVE_EFFORT={{#if thinkingEffort}}'{{thinkingEffort}}'{{else}}''{{/if}}
+if [ -f "{{agentDir}}/.session-effort" ]; then
+  _sef="$(cat "{{agentDir}}/.session-effort" 2>/dev/null || true)"
+  _se_level="$(printf '%s' "$_sef" | sed -n 's/.*"level"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')"
+  _se_cfg="$(printf '%s' "$_sef" | sed -n 's/.*"configuredDefaultAtWrite"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')"
+  # Allowlist gate — kept in sync with EFFORT_LEVELS in
+  # telegram-plugin/gateway/effort-command.ts. The level is passed verbatim
+  # to `claude --effort`.
+  if [ "$(printf '%s' "$_se_level" | wc -l)" -ne 0 ] || ! printf '%s' "$_se_level" | grep -Eq '^(low|medium|high|xhigh|max)$'; then
+    rm -f "{{agentDir}}/.session-effort"
+    echo "session-effort: ignoring malformed .session-effort (failed allowlist gate) — using configured default '${_EFFECTIVE_EFFORT:-<unset>}'" >&2
+    printf 'Your saved session effort override could not be read (invalid or corrupt), so the agent booted on its configured default effort. Re-issue /effort <level> if you want a different one.\n' >> "{{agentDir}}/.session-model-alert" 2>/dev/null || true
+  elif [ "$_se_cfg" != "$_EFFECTIVE_EFFORT" ]; then
+    rm -f "{{agentDir}}/.session-effort"
+    echo "session-effort: configured thinking_effort changed ('$_se_cfg' → '${_EFFECTIVE_EFFORT:-<unset>}') — clearing session override '$_se_level'" >&2
+    printf 'The configured default effort changed (`%s` → `%s`), so your session effort override `%s` was cleared — the agent booted on the new configured default. Re-issue /effort %s if you still want it.\n' "${_se_cfg:-<unset>}" "${_EFFECTIVE_EFFORT:-<unset>}" "$_se_level" "$_se_level" >> "{{agentDir}}/.session-model-alert" 2>/dev/null || true
+  else
+    _EFFECTIVE_EFFORT="$_se_level"
+    echo "session-effort: keeping session effort override '$_se_level' across this relaunch" >&2
+  fi
+  unset _sef _se_level _se_cfg
+fi
+if [ -n "$_EFFECTIVE_EFFORT" ]; then
+  _EFFORT_ARG="--effort $_EFFECTIVE_EFFORT"
+else
+  _EFFORT_ARG=""
+fi
 
 # sr-* passthrough→router repoint — ONE post-resolution gate covering BOTH the
 # /model override path AND the configured-default path (`model: sr-*` in
@@ -1222,14 +1304,14 @@ printf '%s\n' "$_EFFECTIVE_MODEL" > "{{agentDir}}/.active-session-model" 2>/dev/
 
 {{#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"{{#if thinkingEffort}} --effort {{thinkingEffort}}{{/if}}{{#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}}
+  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}}
 else
-  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"{{#if thinkingEffort}} --effort {{thinkingEffort}}{{/if}}{{#if permissionMode}} --permission-mode {{permissionMode}}{{/if}}{{#if fallbackModelQ}} --fallback-model {{{fallbackModelQ}}}{{/if}}{{#if dangerousMode}} --dangerously-skip-permissions{{/if}}{{#if extraCliArgs}}{{{extraCliArgs}}}{{/if}}
+  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}}{{#if dangerousMode}} --dangerously-skip-permissions{{/if}}{{#if extraCliArgs}}{{{extraCliArgs}}}{{/if}}
 fi
 {{else}}
 if [ -n "$APPEND_PROMPT" ]; then
-  exec claude $CONTINUE_FLAG --channels plugin:telegram@claude-plugins-official --plugin-dir "{{securityPluginDir}}"{{#if hindsightEnabled}} --plugin-dir "{{agentDir}}/.claude/plugins/hindsight-memory"{{/if}} $SR_FLEET_ARG --model "$_EFFECTIVE_MODEL"{{#if thinkingEffort}} --effort {{thinkingEffort}}{{/if}}{{#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}}
+  exec claude $CONTINUE_FLAG --channels plugin:telegram@claude-plugins-official --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}}
 else
-  exec claude $CONTINUE_FLAG --channels plugin:telegram@claude-plugins-official --plugin-dir "{{securityPluginDir}}"{{#if hindsightEnabled}} --plugin-dir "{{agentDir}}/.claude/plugins/hindsight-memory"{{/if}} $SR_FLEET_ARG --model "$_EFFECTIVE_MODEL"{{#if thinkingEffort}} --effort {{thinkingEffort}}{{/if}}{{#if permissionMode}} --permission-mode {{permissionMode}}{{/if}}{{#if fallbackModelQ}} --fallback-model {{{fallbackModelQ}}}{{/if}}{{#if dangerousMode}} --dangerously-skip-permissions{{/if}}{{#if extraCliArgs}}{{{extraCliArgs}}}{{/if}}
+  exec claude $CONTINUE_FLAG --channels plugin:telegram@claude-plugins-official --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}}{{#if dangerousMode}} --dangerously-skip-permissions{{/if}}{{#if extraCliArgs}}{{{extraCliArgs}}}{{/if}}
 fi
 {{/if}}

package/profiles/_shared/dev-protocol.md.hbs

@@ -0,0 +1,42 @@
+## Development Protocol
+
+How development work gets done here — orient, clarify, align, ship, communicate. These are procedural rules for any substantive coding, infra, or debugging task. For the long-form playbook (design reports, adversarial review structure, re-review verdicts), load the bundled `dev-protocol` skill before starting substantive development work.
+
+### Orient — ground before you build
+
+- **Validate, don't assume.** Read the actual code, config, and system state before forming a theory. Never assert a fact you haven't checked this turn.
+- **Root-cause in real source.** Verify against the source of truth — the repo's source files, not build artifacts, caches, or generated output that may be stale.
+- **Contradicting evidence wins.** When what you find contradicts your working theory (or the task description), report the contradiction — don't force-fit the evidence to the plan.
+- **Cite your ground.** Claims about the codebase carry references: PR numbers, commit hashes, `file:line`.
+
+### Clarify vs proceed
+
+- **Infer first.** Mine the codebase, history, and prior context before asking. Most "questions" are answerable by reading.
+- **If genuinely unsure, ask ONE question at a time** — the single question that unblocks the most work — not a questionnaire.
+- **Clarify during planning; act autonomously during execution.** Once the plan is agreed, don't drip questions mid-implementation — make the reasonable call, note the assumption, keep moving.
+
+### Design-align on larger tasks
+
+For tasks that are architecturally significant, cross-cutting, or ambiguous in approach:
+
+- **Design report before implementation.** Present an evidence-grounded design (what exists today with citations, what changes, why this approach) to the user and get alignment before writing the code.
+- **Red-team your own plan.** Adversarially review the design item by item — a per-item verdict backed by evidence, not a rubber stamp.
+- **Stage delivery.** Ship as focused, single-concern PRs rather than one omnibus change.
+
+### Pipeline — how a change ships
+
+- **Branch off fresh main.** Always pull before branching.
+- **Scoped tests + lint locally; CI is the full-suite authority.** Run the tests that cover what you touched plus `npm run lint` before pushing — but the merge gate is CI green, not your local run.
+- **Adversarial review of the diff.** Every change gets reviewed as an adversary would read it: what breaks, what's untested, what's inconsistent.
+- **Fix ALL findings — including lows.** A "low" you skip is a bug you shipped. Then **re-review the fix** before calling it done.
+- **Merge only on CI green.** No exceptions, no "it's probably fine".
+- **Durable fixes over hack patches.** Fix the root cause; a workaround needs an explicit reason and a filed follow-up.
+- **Deterministic mechanisms over model-dependent behavior.** If a guarantee can be enforced by code (a check, a hook, a schema), don't leave it to prompt discipline.
+- **Tests assert outcomes, not just code paths.** A test that exercises the code but wouldn't fail on the bug is not a test.
+
+### Communicate while you work
+
+- **Consolidated messages.** One substantive update beats five fragments — batch related findings and results.
+- **Always-visible progress.** Long-running work surfaces status the user can see; never go dark mid-task.
+- **No foreground watches over 30 seconds.** Anything longer runs in the background with a notification on completion.
+- **Max 15 parallel sub-agents.** Fan out for genuinely parallel work, but cap the swarm.

package/skills/dev-protocol/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: dev-protocol
+description: >
+  Use when starting substantive development work — a code change, refactor,
+  bug fix, infra change, or multi-step debugging task in any repo. Load BEFORE
+  writing code: it is the fleet development protocol (orient/ground, clarify
+  vs proceed, design-align on larger tasks, the branch→test→review→CI
+  pipeline, communication rules). Also use when deciding whether a task needs
+  a design report first, when dispatching an adversarial review of a diff, or
+  when writing a re-review verdict. Do NOT use for: quick lookups, answering
+  questions about code without changing it, or pure conversation.
+---
+
+# Development Protocol — the playbook
+
+The always-loaded CLAUDE.md "Development Protocol" section is the summary.
+This skill is the long-form procedure. Work through the five phases in order;
+they are checkpoints, not vibes.
+
+## 1. Orient — ground before you build
+
+Before forming any theory or plan:
+
+- **Read the real source.** The repo's source files at the current HEAD — not
+  build artifacts (`dist/`, generated files, caches), not your memory of the
+  code, not the task description's paraphrase. If a claim matters, open the
+  file.
+- **Verify the root cause, not the first plausible cause.** Reproduce or trace
+  the failure to a specific mechanism before fixing. "This line looks wrong"
+  is a lead; the fix ships only when you can say *why* it produced the
+  observed symptom.
+- **Report contradicting evidence.** If what you find contradicts the task
+  description, the ticket, or your own working theory — say so explicitly and
+  stop to re-plan. Never force-fit evidence to the plan you already had.
+- **Cite everything.** Claims about the codebase carry `file:line`, commit
+  hashes, or PR numbers. "The scaffold appends fragments at
+  `src/agents/scaffold.ts:4113`" is a claim; "the scaffold appends fragments
+  somewhere" is not.
+
+## 2. Clarify vs proceed
+
+- **Infer first.** Most questions are answerable from the codebase, git
+  history, existing tests, or docs. Exhaust those before asking.
+- **One question at a time.** If genuinely unsure after inferring, ask the
+  single question whose answer unblocks the most work. Phrase it as a
+  decision with a default: state what you found, the 2–3 viable options, which
+  you'd pick and why, and ask for confirmation — e.g. *"The config loader
+  supports both YAML and JSON overlays; the task says 'config file' without
+  specifying. I'd extend the YAML path since all existing overlays are YAML
+  (src/config/merge.ts:88) — confirm, or should JSON be covered too?"* Never
+  send a questionnaire.
+- **Phase discipline.** Clarify during *planning*. Once the plan is agreed,
+  execute autonomously: make the reasonable call on small ambiguities, record
+  the assumption in your report, and keep moving. Mid-execution questions are
+  reserved for discoveries that invalidate the plan.
+
+## 3. Design-align on larger tasks
+
+**Classify the task first.** Treat it as "larger" (design-align before
+implementing) when ANY of these hold:
+
+- It changes a public interface, schema, config shape, or on-disk format.
+- It cuts across 3+ modules or touches a load-bearing invariant.
+- Two or more genuinely different approaches exist and the choice is
+  expensive to reverse.
+- The task description is a goal ("make X reliable") rather than a change
+  ("add flag Y").
+- It will land as more than one PR.
+
+Small, single-concern, obvious-approach changes skip straight to phase 4.
+
+For larger tasks:
+
+1. **Design report before code.** Send the user an evidence-grounded report:
+   what exists today (with citations), what will change, the chosen approach
+   and its rejected alternatives, and the PR staging plan. Get alignment
+   before implementation.
+2. **Red-team your own plan adversarially.** Review the design item by item.
+   Each item gets a verdict — `SOUND`, `RISK`, or `WRONG` — backed by
+   evidence (a file you read, a test you ran, a documented behavior), not
+   intuition. Fix every `WRONG` and address every `RISK` before starting.
+3. **Stage delivery as focused single-concern PRs.** One concern per PR:
+   reviewable in one sitting, revertable in one command. Never bundle a
+   refactor with a behavior change.
+
+## 4. Pipeline — how a change ships
+
+1. **Branch off fresh main.** `git fetch && git checkout -b <branch> origin/main`.
+2. **Implement with durable fixes.** Fix root causes. A workaround is
+   acceptable only with an explicit reason stated and a follow-up filed.
+   Prefer deterministic mechanisms (a check, a hook, a schema, a lint gate)
+   over model-dependent behavior — if code can enforce the guarantee, don't
+   leave it to prompt discipline.
+3. **Tests assert outcomes.** Every test must fail if the bug it guards
+   returns. A test that merely exercises the code path without asserting the
+   observable outcome is not a test.
+4. **Scoped tests + lint locally.** Run the test files covering what you
+   touched, plus the repo's lint gate. Local runs are a fast filter; **CI is
+   the full-suite authority** — never claim done off a local run alone.
+5. **Adversarial review of the diff.** Dispatch a reviewer (sub-agent or
+   fresh pass) with this structure:
+   - Input: the full diff, the task statement, and the design report if one
+     exists.
+   - Charge: *find reasons this change is wrong* — correctness, missed edge
+     cases, untested behavior, inconsistency with surrounding code, docs
+     drift, security/data-loss risk.
+   - Output: a findings list, each with severity (high/medium/low), the
+     evidence (`file:line`), and a concrete fix.
+6. **Fix ALL findings — including lows.** A low you skip is a bug you
+   shipped. If a finding is genuinely invalid, rebut it with evidence in
+   writing; silence is not a rebuttal.
+7. **Re-review the fix.** The re-review verdict must contain, per original
+   finding: the finding ID, what changed (`file:line` of the fix), whether it
+   fully resolves the finding (`RESOLVED` / `PARTIAL` / `REBUTTED` with
+   evidence), and whether the fix introduced anything new. A bare "fixed" is
+   not a verdict.
+8. **Merge only on CI green.** No exceptions. A red or flaky CI run is a
+   blocker to investigate, not to override.
+
+## 5. Communicate while you work
+
+- **Consolidated messages.** Batch related findings and results into one
+  substantive update; never send five fragments where one message serves.
+- **Always-visible progress.** Long-running work surfaces status the user can
+  see (progress card, interim edit, explicit "still running: X"). Never go
+  dark mid-task.
+- **No foreground watches over 30 seconds.** Anything longer — builds, CI
+  waits, deploys — runs in the background with a notification on completion.
+  Don't block a turn polling.
+- **Max 15 parallel sub-agents.** Fan out for genuinely parallel work
+  (independent reviews, independent modules), but cap the swarm at 15.

package/telegram-plugin/README.md

@@ -276,7 +276,8 @@ Each plugin instance is bound to one agent (via `SWITCHROOM_AGENT_NAME` set by `
 |---------|-------------|
 | `/agents` | List all agents and their status |
 | `/agentstart [name]` | Start an agent (default: this agent) |
-| `/stop [name]` | Stop an agent (default: this agent) |
+| `/agentstop [name]` | Stop an agent's container (default: this agent) |
+| `/stop` | Cancel this agent's in-flight turn (bare `stop` as a message works too) |
 | `/restart [name\|all]` | Restart an agent (default: this agent; pass `all` for every agent) |
 | `/auth` | Show auth/token status |
 | `/topics` | Show topic-to-agent mappings |

package/telegram-plugin/admin-commands/dispatch.test.ts

@@ -1,4 +1,7 @@
 import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
 import {
   dispatchAdminCommand,
   parseCommandName,
@@ -41,12 +44,47 @@ describe('parseCommandName', () => {
 
 describe('ADMIN_COMMAND_NAMES', () => {
   it('contains the fleet-management admin commands', () => {
-    const required = ['agents', 'logs', 'restart', 'update', 'reconcile', 'stop', 'agentstart', 'grant', 'dangerous', 'permissions', 'vault', 'audit']
+    const required = ['agents', 'logs', 'restart', 'update', 'reconcile', 'agentstop', 'agentstart', 'grant', 'dangerous', 'permissions', 'vault', 'audit']
     for (const cmd of required) {
       expect(ADMIN_COMMAND_NAMES.has(cmd)).toBe(true)
     }
   })
 
+  it('replaced container-stop /stop with /agentstop (#3020 / #1394)', () => {
+    // 'stop' now cancels the in-flight turn on EVERY agent (like /interrupt),
+    // so it must NOT be admin-gated; container stop moved to 'agentstop',
+    // which MUST be admin-gated or any forum member could stop containers
+    // via non-admin agents (the #1394 hole).
+    expect(ADMIN_COMMAND_NAMES.has('stop')).toBe(false)
+    expect(ADMIN_COMMAND_NAMES.has('agentstop')).toBe(true)
+  })
+
+  it('stays in sync with the tier-2 command list in docs/architecture.md', () => {
+    // The doc's "Fleet-management commands" line is the operator-facing
+    // contract; ADMIN_COMMAND_NAMES is the enforcing set. Drift between the
+    // two either advertises an ungated verb or hides a gated one.
+    const __dirname = dirname(fileURLToPath(import.meta.url))
+    const doc = readFileSync(
+      resolve(__dirname, '..', '..', 'docs', 'architecture.md'),
+      'utf8',
+    )
+    const tier2Line = doc
+      .split('\n')
+      .find(l => l.startsWith('2. **Fleet-management commands**'))
+    expect(tier2Line, 'tier-2 line missing from docs/architecture.md').toBeTruthy()
+    const documented = new Set(
+      [...tier2Line!.matchAll(/`\/([a-z]+)(?:\s+<[^>]+>)?`/g)].map(m => m[1]!),
+    )
+    // Every documented tier-2 verb is enforced…
+    for (const cmd of documented) {
+      expect(ADMIN_COMMAND_NAMES.has(cmd), `doc lists /${cmd} but ADMIN_COMMAND_NAMES lacks it`).toBe(true)
+    }
+    // …and every enforced verb is documented.
+    for (const cmd of ADMIN_COMMAND_NAMES) {
+      expect(documented.has(cmd), `ADMIN_COMMAND_NAMES has '${cmd}' but the doc tier-2 line lacks /${cmd}`).toBe(true)
+    }
+  })
+
   it('does not contain per-agent auth ops (must work without model)', () => {
     // /auth, /reauth, /authfallback are handled by the gateway directly so
     // the user can re-authenticate even when the model is rate-limited or the
@@ -251,7 +289,7 @@ describe('classifyAdminGate', () => {
       })
     })
     it('blocks /agents, /update, /vault, /permissions', () => {
-      for (const c of ['agents', 'update', 'vault', 'permissions', 'stop', 'agentstart', 'reconcile', 'dangerous', 'memory', 'topics']) {
+      for (const c of ['agents', 'update', 'vault', 'permissions', 'agentstop', 'agentstart', 'reconcile', 'dangerous', 'memory', 'topics']) {
         const r = classifyAdminGate(`/${c}`, me)
         expect(r).toEqual({ action: 'block', reason: 'admin-required', cmd: c })
       }

package/telegram-plugin/admin-commands/index.ts

@@ -49,7 +49,12 @@ export const ADMIN_COMMAND_NAMES = new Set<string>([
   'agents',
   'logs',
   'restart',
-  'stop',
+  // #3020: container stop is /agentstop (pairs with /agentstart). Plain
+  // 'stop' is deliberately ABSENT — it cancels the in-flight turn on every
+  // agent (like /interrupt), so admin-gating it would break the kill switch
+  // on non-admin agents; and leaving container-stop off this list would let
+  // any forum member stop containers via non-admin agents (#1394).
+  'agentstop',
   'agentstart',
   'update',
   'reconcile',