switchroom 0.18.8 → 0.18.10

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',

package/telegram-plugin/bridge/bridge.ts

@@ -31,6 +31,7 @@ import { buildEffectiveToolSchemas, LINEAR_ENV } from './tool-filter.js'
 import type { InboundMessage, PermissionEvent, StatusEvent } from '../gateway/ipc-protocol.js'
 import { matchesAllowRule } from '../permission-rule.js'
 import { createOutstandingPermissionLedger } from './permission-ledger.js'
+import { appendCrashBreadcrumb } from './crash-breadcrumb.js'
 
 installPluginLogger()
 
@@ -107,7 +108,7 @@ const TOOL_SCHEMAS = [
         quote: { type: 'boolean', description: 'Opt out of the default quote-reply behavior. Default: true. Pass false to send a bare message with no quote reference. Ignored when reply_to is explicitly set.' },
         message_thread_id: { type: 'string', description: 'Forum topic thread ID. Auto-applied from the last inbound message in the same chat if not specified.' },
         origin_turn_id: { type: 'string', description: 'In a forum supergroup, pass back the origin_turn_id attribute from the <channel> message you are answering. It pins the reply to that message\'s topic even if another topic\'s turn started meanwhile. Omit in DMs / single-topic chats.' },
-        files: { type: 'array', items: { type: 'string' }, description: 'Absolute file paths to attach. Images send as photos; other types as documents. Max 50MB each.' },
+        files: { type: 'array', items: { type: 'string' }, description: 'Absolute file paths to attach. Images send as photos; other types as documents. Max 50MB each. Telegram rejects photos with extreme dimensions (aspect ratio over ~10:1, width+height over 10000px, or over 10MB) — very tall images like full-page screenshots are auto-rerouted as documents; crop or split them first if the user should see them inline as photos.' },
         format: { type: 'string', enum: ['html', 'markdownv2', 'text'], description: "Rendering mode. 'html' (default) converts markdown to Telegram HTML." },
         disable_web_page_preview: { type: 'boolean', description: 'Disable link preview thumbnails. Default: true.' },
         protect_content: { type: 'boolean', description: 'When true, Telegram prevents the message from being forwarded or saved.' },
@@ -895,8 +896,29 @@ process.on('SIGINT', () => {
   setTimeout(() => process.exit(0), 500)
 })
 
+// #3033 — the bridge process must survive stray errors, and when it can't,
+// it must leave a diagnosable trace. Claude Code NEVER respawns a dead MCP
+// server: if this process exits, the reply tool vanishes from the session
+// (`No such tool available`) and only a full container restart recovers the
+// chat surface (2026-07-11 clerk incident — the gateway crashed, its
+// supervisor brought it back in 1s, but the bridge had died in the same
+// window and the agent was mute for 7 minutes until the operator bounced
+// the container). Claude Code also drops MCP-server stderr after startup,
+// so both handlers persist a breadcrumb to STATE_DIR/bridge-crash.log.
+const CRASH_LOG_PATH = join(STATE_DIR, 'bridge-crash.log')
+
 process.on('unhandledRejection', (err) => {
   process.stderr.write(`telegram bridge: unhandled rejection: ${err}\n`)
+  appendCrashBreadcrumb(CRASH_LOG_PATH, 'unhandledRejection', err)
+})
+
+process.on('uncaughtException', (err) => {
+  // Log-and-continue, mirroring the unhandledRejection posture. Risky in
+  // general, but the alternative is strictly worse here: process death is
+  // unrecoverable by design (see above), while the IPC client's reconnect
+  // loop can heal any gateway-connection damage on its own.
+  process.stderr.write(`telegram bridge: uncaught exception (continuing): ${(err as Error)?.stack ?? err}\n`)
+  appendCrashBreadcrumb(CRASH_LOG_PATH, 'uncaughtException', err)
 })
 
 async function main(): Promise<void> {

package/telegram-plugin/bridge/crash-breadcrumb.ts

@@ -0,0 +1,42 @@
+/**
+ * crash-breadcrumb.ts — persistent last-gasp diagnostics for the MCP
+ * bridge process (#3033).
+ *
+ * Why this exists: Claude Code captures an MCP server's stderr only
+ * around connection startup — anything the bridge writes later is
+ * dropped. In the 2026-07-11 clerk incident the bridge process died
+ * within seconds of a gateway crash and the cause was unrecoverable:
+ * no stderr, no log, nothing. And a dead bridge is terminal — Claude
+ * Code never respawns a failed MCP server, so the chat surface stays
+ * down (`No such tool available: mcp__switchroom-telegram__reply`)
+ * until a full container restart.
+ *
+ * This module appends a bounded breadcrumb line to
+ * `STATE_DIR/bridge-crash.log` from the bridge's uncaughtException /
+ * unhandledRejection handlers so the NEXT incident is diagnosable.
+ * Append-only, best-effort, never throws.
+ */
+
+import { appendFileSync, statSync, renameSync } from 'node:fs'
+
+/** Rotate once past ~1MB — a crash-looping bridge must not fill the disk. */
+const MAX_LOG_BYTES = 1024 * 1024
+
+export function appendCrashBreadcrumb(
+  logPath: string,
+  kind: 'uncaughtException' | 'unhandledRejection',
+  err: unknown,
+  now: Date = new Date(),
+): void {
+  try {
+    try {
+      if (statSync(logPath).size > MAX_LOG_BYTES) renameSync(logPath, `${logPath}.1`)
+    } catch { /* first write, or rotation raced — append anyway */ }
+    const detail = err instanceof Error ? (err.stack ?? err.message) : String(err)
+    // Single line per event (stack newlines folded) — greppable, bounded.
+    const folded = detail.replace(/\s*\n\s*/g, ' | ').slice(0, 4000)
+    appendFileSync(logPath, `${now.toISOString()} ${kind} pid=${process.pid} ${folded}\n`)
+  } catch {
+    /* best-effort: a failing breadcrumb must never make the crash worse */
+  }
+}

package/telegram-plugin/chat-lock.ts

@@ -70,6 +70,19 @@ export function createChatLock(): ChatLock {
     const tracked = next.finally(() => {
       if (chains.get(key) === tracked) chains.delete(key)
     })
+    // `tracked` is a SECOND promise derived from `next`, retained only in
+    // the `chains` map for ordering. The caller awaits `next` (and handles
+    // its rejection); `tracked` is picked up by the NEXT queued call via
+    // `prior.then(fn, fn)`. But when this is the TAIL call on the key —
+    // the common single-reply case — nothing ever attaches a handler to
+    // `tracked`, so a rejected `next` surfaces as an UNHANDLED REJECTION
+    // and (per the gateway's unhandledRejection policy) crashes + reboots
+    // the whole gateway. This bit any failing send that was last in its
+    // (chat,thread) lane: sendPhoto PHOTO_INVALID_DIMENSIONS, sendMediaGroup,
+    // editMessageText MESSAGE_TOO_LONG, deleteMessage "can't be deleted",
+    // etc. Swallow the rejection on the internal tracking promise ONLY —
+    // the caller's `next` still carries the real error for normal handling.
+    tracked.catch(() => {})
     chains.set(key, tracked)
     return next
   }