switchroom 0.17.6 → 0.18.3

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.17.6",
+  "version": "0.18.3",
   "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/settings.json.hbs

@@ -21,8 +21,8 @@
 {
   "permissions": {
     "allow": {{{json permissionAllow}}},
-    "deny": {{{json toolsDeny}}}{{#if defaultModeAcceptEdits}},
-    "defaultMode": "acceptEdits"{{/if}}
+    "deny": {{{json toolsDeny}}},
+    "defaultMode": "{{defaultMode}}"
   }{{#if hindsightEnabled}},
   "autoMemoryEnabled": false{{/if}}{{#if mcpServers}},
   "mcpServers": {{{json mcpServers}}}

package/profiles/_base/start.sh.hbs

@@ -33,6 +33,19 @@ if [ "$SWITCHROOM_RUNTIME" = "docker" ] && [ -z "$SWITCHROOM_DOCKER_TMUX_INNER"
   # same path the rest of start.sh + the MCP sidecar expects.
   export TELEGRAM_STATE_DIR="{{agentDir}}/telegram"
 
+  # SWITCHROOM_AGENT_NAME is the canonical "which agent am I" identity. It is
+  # normally supplied by the container env (compose.ts) so it is already
+  # present here, but the authoritative inner-pass export lives at line ~387,
+  # AFTER the gateway fork below. On any runtime where the compose env is NOT
+  # the source (non-docker / local dev), the forked gateway daemon would then
+  # start with the var UNSET — which collapses its worktree-ownership filter
+  # (worktree-watch-cwds.ts) to [], so a worktree-isolated background
+  # sub-agent gets NO live progress feed for its whole run (#1116 / #2893).
+  # Hoist the export here, before the fork, so the gateway ALWAYS has its
+  # identity on the fast path regardless of runtime. Idempotent with the
+  # compose env and the inner-pass export. Pinned by the scaffold-order test.
+  export SWITCHROOM_AGENT_NAME="{{name}}"
+
   # Gateway-consumed env MUST be exported HERE, before the gateway fork
   # below. The gateway daemon reads channels.telegram.* knobs (and any
   # agent env) from process.env at startup — e.g. SWITCHROOM_TG_STREAM_
@@ -57,9 +70,17 @@ if [ "$SWITCHROOM_RUNTIME" = "docker" ] && [ -z "$SWITCHROOM_DOCKER_TMUX_INNER"
   # ANTHROPIC_CUSTOM_HEADERS exported BEFORE the gateway fork below, or
   # discoverSrModels() returns [] and /model never shows OpenRouter entries.
   #
-  # Mirrors the INNER block's fail-open logic exactly:
-  #   - missing key   → log + skip export (gateway talks direct OAuth)
-  #   - proxy down    → log + strip ALL routing env (fail-open)
+  # Mirrors the INNER block's split boot contract EXACTLY (see the long note
+  # at the inner block for the full rationale). This OUTER pass runs BEFORE
+  # `exec tmux`, so whatever it does to the routing env is inherited by the
+  # inner pass — which is precisely why the old permanent strip-on-unreachable
+  # was so damaging: it removed SWITCHROOM_LITELLM here, and the inner
+  # self-heal block is gated on SWITCHROOM_LITELLM, so the entire inner fix
+  # was dead on the real docker path. The two boot failure modes:
+  #   - MISSING KEY → log LOUDLY + fail-open (strip routing; gateway direct OAuth)
+  #   - PROXY UNREACHABLE → log LOUDLY + KEEP routing in place (NO strip) so it
+  #     survives into the inner pass and self-heals when litellm returns. Boot
+  #     is non-fatal either way.
   #   - ANTHROPIC_CUSTOM_HEADERS already set → skip (idempotent)
   #
   # SWITCHROOM_AGENT_NAME is injected by compose env (compose.ts:1816)
@@ -67,11 +88,35 @@ if [ "$SWITCHROOM_RUNTIME" = "docker" ] && [ -z "$SWITCHROOM_DOCKER_TMUX_INNER"
   if [ -n "${SWITCHROOM_LITELLM:-}" ] && [ -z "$ANTHROPIC_CUSTOM_HEADERS" ] && command -v switchroom >/dev/null 2>&1; then
     sr_ll_key="$(switchroom vault get "litellm/$SWITCHROOM_AGENT_NAME/api-key" 2>/dev/null || true)"
     sr_ll_ok=""
+    sr_ll_unreachable=""
     if [ -z "$sr_ll_key" ]; then
-      echo "litellm(outer): no virtual key for agent '$SWITCHROOM_AGENT_NAME' — gateway will use direct OAuth (no tracking/guardrail)" >&2
-    elif command -v curl >/dev/null 2>&1 && [ -n "$ANTHROPIC_BASE_URL" ] \
-         && ! curl -fsS -m 5 -o /dev/null "${SWITCHROOM_LITELLM_BASE:-${ANTHROPIC_BASE_URL%/anthropic}}/health/liveliness" 2>/dev/null; then
-      echo "litellm(outer): proxy unreachable at ${SWITCHROOM_LITELLM_BASE:-$ANTHROPIC_BASE_URL} — falling back to direct OAuth (no tracking/guardrail this session)" >&2
+      echo "litellm(outer): WARNING — no virtual key for agent '$SWITCHROOM_AGENT_NAME'; gateway falling back to direct Anthropic OAuth (untracked, unguarded)." >&2
+    elif command -v curl >/dev/null 2>&1 && [ -n "$ANTHROPIC_BASE_URL" ]; then
+      # Bounded retry probe (co-boot race fix, 2026-07): when the whole stack
+      # co-boots, the litellm proxy's heavy Python app is often not yet healthy
+      # in the first few seconds. A single one-shot probe fails-open and takes
+      # this agent dark (untracked) for the WHOLE session. Poll the liveliness
+      # endpoint every ~3s for up to 120s (hard budget) and only fall open if
+      # it is STILL unreachable after that whole window.
+      sr_ll_url="${SWITCHROOM_LITELLM_BASE:-${ANTHROPIC_BASE_URL%/anthropic}}/health/liveliness"
+      sr_ll_deadline=$(( $(date +%s) + 120 ))
+      sr_ll_up=""
+      while :; do
+        if curl -fsS -m 5 -o /dev/null "$sr_ll_url" 2>/dev/null; then sr_ll_up="1"; break; fi
+        [ "$(date +%s)" -ge "$sr_ll_deadline" ] && break
+        sleep 3
+      done
+      if [ -z "$sr_ll_up" ]; then
+        # Proxy unreachable but the key is present. Do NOT strip: leave routing
+        # pointed at litellm so it survives into the inner (tmux) pass and
+        # self-heals once the proxy is back (socat forwarder reconnects
+        # per-connection). Boot continues.
+        sr_ll_unreachable="1"
+        echo "litellm(outer): WARNING — proxy unreachable at ${SWITCHROOM_LITELLM_BASE:-$ANTHROPIC_BASE_URL} after 120s of retries; gateway discovery will FAIL until it recovers — routing LEFT IN PLACE so it self-heals. NOT falling back to untracked direct Anthropic OAuth." >&2
+      else
+        sr_ll_ok="1"
+      fi
+      unset sr_ll_url sr_ll_deadline sr_ll_up
     else
       sr_ll_ok="1"
     fi
@@ -80,10 +125,17 @@ if [ "$SWITCHROOM_RUNTIME" = "docker" ] && [ -z "$SWITCHROOM_DOCKER_TMUX_INNER"
 x-litellm-customer-id: $SWITCHROOM_AGENT_NAME
 x-litellm-tags: agent:$SWITCHROOM_AGENT_NAME,profile:${SWITCHROOM_AGENT_PROFILE:-default}"
       export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
+    elif [ -n "$sr_ll_unreachable" ]; then
+      # Proxy unreachable at boot: routing intentionally LEFT IN PLACE (loud
+      # warning already emitted) so it survives into the inner pass and
+      # self-heals once litellm returns. NO unset — the permanent strip here
+      # was what made the inner self-heal fix inert on docker.
+      :
     else
+      # Missing-key fail-open: gateway talks direct OAuth, unproxied.
       unset ANTHROPIC_BASE_URL ANTHROPIC_SMALL_FAST_MODEL SWITCHROOM_LITELLM SWITCHROOM_LITELLM_BASE
     fi
-    unset sr_ll_key sr_ll_ok
+    unset sr_ll_key sr_ll_ok sr_ll_unreachable
   fi
 
   # Tiny in-process supervisor: runs cmd in a respawn loop with
@@ -433,6 +485,14 @@ export HINDSIGHT_RECALL_TYPES="{{hindsightRecallTypes}}"
 {{#if hindsightRecallSkipTrivial}}
 export HINDSIGHT_RECALL_SKIP_TRIVIAL={{hindsightRecallSkipTrivial}}
 {{/if}}
+# #2848 Stage B — directive-capture nudge (memory.directive_capture_nudge
+# cascade). On by default (plugin settings.json): recall.py regex-detects
+# correction / standing-rule-shaped inbound and nudges the model to persist
+# it with create_directive if durable. Export only when the operator overrode
+# it; set false to disable the nudge for this agent.
+{{#if hindsightDirectiveCaptureNudge}}
+export HINDSIGHT_DIRECTIVE_CAPTURE_NUDGE={{hindsightDirectiveCaptureNudge}}
+{{/if}}
 # PR6 — supergroup-mode topic tagging. JSON map of {alias: thread_id}
 # parsed by retain.py + recall.py to (a) stamp chat_id/thread_id/topic_alias
 # into retained memory metadata and (b) emit a "Current topic: …" preamble
@@ -885,12 +945,21 @@ fi
 # content-safety guardrails — it never alters the model or Claude's operation.
 # See reference/invariants.md § "Operator-controlled gateway carve-out".
 #
-# FAIL-OPEN (operator decision 2026-06-28): if the key is missing OR the proxy
-# is unreachable at boot, strip the routing env and fall back to the direct
-# broker-OAuth Anthropic path, logging the reason LOUDLY. Availability wins over
-# tracking/guardrails — a proxy outage must never take an agent dark. The
-# tradeoff is an explicit, logged guardrail lapse for that session, not a silent
-# one. Re-probed on every (re)boot, so recovery is automatic.
+# TWO boot failure modes, handled DIFFERENTLY (2026-07-08 — was a single
+# fail-open path that silently took an agent off-proxy for its whole lifetime):
+#   - MISSING KEY (no per-agent virtual key in the vault): fail-open — strip the
+#     routing env and fall back to the direct broker-OAuth Anthropic path,
+#     logging LOUDLY. Without a key there is nothing to authenticate to the
+#     proxy with, so there is no metered route to self-heal into.
+#   - PROXY UNREACHABLE at boot (key present, liveliness probe fails within the
+#     retry window): do NOT strip. Leave ANTHROPIC_BASE_URL / SWITCHROOM_LITELLM*
+#     pointed at the proxy (the socat forwarder at 127.0.0.1:4010 self-heals
+#     per-connection) and emit a LOUD warning. Claude traffic FAILS+retries until
+#     the proxy returns, then routes through it automatically — the metered path
+#     stays the metered path. We deliberately do NOT silently fall back to
+#     untracked direct Anthropic on a transient blip: an agent that boots during
+#     a brief litellm outage previously never routed through litellm again until
+#     a manual restart. Re-probed on every (re)boot.
 #
 # Static tags (x-litellm-customer-id / x-litellm-tags) give per-AGENT
 # attribution in LiteLLM. Per-SESSION is NOT achievable here: claude sends no
@@ -898,18 +967,57 @@ fi
 # per-session cost/issue tracking is handled out-of-band by correlating
 # LiteLLM's request log against switchroom's turn ledger, never by mutating the
 # claude protocol.
+# _LITELLM_OK is read by the session-model-override block below: an sr-*
+# (LiteLLM/OpenRouter) session override must be DROPPED when the proxy is
+# unreachable at boot, or claude would 4xx an unknown model against Anthropic.
+# Empty by default (proxy not confirmed live); set to "1" only on a successful
+# liveliness probe. Deliberately NOT unset with the sr_ll_* scratch vars.
+_LITELLM_OK=""
 if [ -n "${SWITCHROOM_LITELLM:-}" ] && command -v switchroom >/dev/null 2>&1; then
   sr_ll_key="$(switchroom vault get "litellm/$SWITCHROOM_AGENT_NAME/api-key" 2>/dev/null || true)"
   sr_ll_ok=""
+  sr_ll_unreachable=""
   if [ -z "$sr_ll_key" ]; then
-    echo "litellm: no virtual key for agent '$SWITCHROOM_AGENT_NAME' — falling back to direct OAuth (no tracking/guardrail)" >&2
-  elif command -v curl >/dev/null 2>&1 && [ -n "$ANTHROPIC_BASE_URL" ] \
-       && ! curl -fsS -m 5 -o /dev/null "${SWITCHROOM_LITELLM_BASE:-${ANTHROPIC_BASE_URL%/anthropic}}/health/liveliness" 2>/dev/null; then
-    echo "litellm: proxy unreachable at ${SWITCHROOM_LITELLM_BASE:-$ANTHROPIC_BASE_URL} — falling back to direct OAuth (no tracking/guardrail this session)" >&2
+    echo "==================== litellm FAIL-OPEN ====================" >&2
+    echo "WARNING: no litellm virtual key for agent '$SWITCHROOM_AGENT_NAME'." >&2
+    echo "WARNING: falling back to direct Anthropic OAuth (untracked, unguarded)" >&2
+    echo "WARNING: — cannot authenticate to the proxy without a key." >&2
+    echo "==========================================================" >&2
+  elif command -v curl >/dev/null 2>&1 && [ -n "$ANTHROPIC_BASE_URL" ]; then
+    # Bounded retry probe (co-boot race fix, 2026-07): when the whole stack
+    # co-boots, the litellm proxy's heavy Python app is often not yet healthy
+    # in the first few seconds. A single one-shot probe fails-open and takes
+    # this agent dark (untracked) for the WHOLE session. Poll the liveliness
+    # endpoint every ~3s for up to 120s (hard budget) and only fall open if
+    # it is STILL unreachable after that whole window.
+    sr_ll_url="${SWITCHROOM_LITELLM_BASE:-${ANTHROPIC_BASE_URL%/anthropic}}/health/liveliness"
+    sr_ll_deadline=$(( $(date +%s) + 120 ))
+    sr_ll_up=""
+    while :; do
+      if curl -fsS -m 5 -o /dev/null "$sr_ll_url" 2>/dev/null; then sr_ll_up="1"; break; fi
+      [ "$(date +%s)" -ge "$sr_ll_deadline" ] && break
+      sleep 3
+    done
+    if [ -z "$sr_ll_up" ]; then
+      # Proxy unreachable at boot but the key is present. Do NOT strip routing:
+      # leave it pointed at litellm so the fleet self-heals once the proxy is
+      # back (the socat forwarder at 127.0.0.1:4010 reconnects per-connection).
+      sr_ll_unreachable="1"
+      echo "==================== litellm UNREACHABLE ====================" >&2
+      echo "WARNING: litellm proxy unreachable at ${SWITCHROOM_LITELLM_BASE:-$ANTHROPIC_BASE_URL} after 120s of retries;" >&2
+      echo "WARNING: Claude traffic will FAIL until it recovers — routing LEFT IN PLACE" >&2
+      echo "WARNING: so it self-heals (socat forwarder reconnects per-connection)." >&2
+      echo "WARNING: NOT falling back to untracked direct Anthropic OAuth." >&2
+      echo "============================================================" >&2
+    else
+      sr_ll_ok="1"
+    fi
+    unset sr_ll_url sr_ll_deadline sr_ll_up
   else
     sr_ll_ok="1"
   fi
   if [ -n "$sr_ll_ok" ]; then
+    _LITELLM_OK="1"
     # Newline-separated Name: Value pairs (claude CLI ANTHROPIC_CUSTOM_HEADERS format).
     # Tags: agent:<name> for per-agent spend tracking; profile:<profile> for
     # fleet-level cost breakdown by role. Per-turn tags (cron vs telegram) are
@@ -923,24 +1031,109 @@ x-litellm-tags: agent:$SWITCHROOM_AGENT_NAME,profile:${SWITCHROOM_AGENT_PROFILE:
     # models configured in the proxy appear in the /model picker and can be
     # selected via --model. Without this, the CLI only knows its bundled list.
     export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
+  elif [ -n "$sr_ll_unreachable" ]; then
+    # Proxy unreachable at boot: routing intentionally LEFT IN PLACE (loud
+    # warning already emitted above) so it self-heals when litellm returns.
+    # _LITELLM_OK stays empty so any sr-* session model override is still
+    # dropped below (claude would 4xx an unknown model against a down endpoint).
+    # NO unset here — that permanent strip was the bug this branch fixes.
+    :
   else
-    # Fail-open: drop every routing var so the claude CLI talks to Anthropic
-    # directly on its OAuth credential (subscription path), unproxied.
+    # Missing key fail-open: drop every routing var so the claude CLI talks to
+    # Anthropic directly on its OAuth credential (subscription path), unproxied.
     unset ANTHROPIC_BASE_URL ANTHROPIC_SMALL_FAST_MODEL SWITCHROOM_LITELLM SWITCHROOM_LITELLM_BASE
   fi
-  unset sr_ll_key sr_ll_ok
+  unset sr_ll_key sr_ll_ok sr_ll_unreachable
+fi
+
+# --- Session-only model override (carrier: .session-model-override) ---
+#
+# The Telegram `/model <sr-*>` switch can't use claude's in-REPL `/model`
+# picker for non-Anthropic (LiteLLM/OpenRouter `sr-*`) models — the CLI's
+# native picker rejects unknown ids ("Model not found"). Instead the gateway
+# writes the chosen model token to `.session-model-override` and gracefully
+# restarts the agent; THIS boot picks it up and launches `claude --model
+# <token>` directly (no picker validation at launch — LiteLLM routes it).
+#
+# One-shot + session-only: the carrier is consumed (rm) on this one boot
+# regardless of validity, so the next restart reverts to the configured
+# default `{{{modelQ}}}`. Mirrors the `.force-fresh-session` marker's
+# gateway↔start.sh round-trip. See telegram-plugin/gateway/model-command.ts.
+# 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}}}
+if [ -f "{{agentDir}}/.session-model-override" ]; then
+  _override="$(tr -d '[:space:]' < "{{agentDir}}/.session-model-override" 2>/dev/null || true)"
+  rm -f "{{agentDir}}/.session-model-override"
+  # Shape gate — kept aligned with MODEL_ARG_RE in telegram-plugin/gateway/model-command.ts.
+  # `/` is allowed for OpenRouter-style `sr-vendor/model` ids; it is not a shell
+  # metachar inside the double-quoted `claude --model "$_EFFECTIVE_MODEL"` usage below.
+  if printf '%s' "$_override" | grep -Eq '^[A-Za-z0-9][]A-Za-z0-9._[/-]{0,99}$'; then
+    _EFFECTIVE_MODEL="$_override"
+    # LiteLLM-down guard for an sr-* OVERRIDE only (operator decision 2026-07):
+    # with the proxy unreachable at boot there IS a Claude configured default to
+    # fall back to, so DROP the override rather than boot on an unreachable sr-*
+    # model that would 4xx against Anthropic — log LOUDLY and write an alert
+    # sentinel the gateway turns into a Telegram message. (The passthrough→router
+    # repoint for a LIVE sr-* — override OR configured default — is done once,
+    # post-resolution, below.)
+    case "$_override" in
+      sr-*)
+        if [ -z "$_LITELLM_OK" ]; then
+          _EFFECTIVE_MODEL={{{modelQ}}}
+          echo "session-model: LiteLLM proxy unreachable at boot — DROPPING sr-* override '$_override', booting on configured default '$_EFFECTIVE_MODEL' instead (would otherwise 4xx against Anthropic)" >&2
+          echo "session-model: the requested sr-* model is UNAVAILABLE this session; re-issue /model $_override once LiteLLM is reachable" >&2
+          printf 'LiteLLM proxy was unreachable at boot, so the session-only model switch to `%s` was dropped — the agent booted on its configured default `%s` instead. Re-issue /model %s once LiteLLM is reachable.\n' "$_override" "$_EFFECTIVE_MODEL" "$_override" > "{{agentDir}}/.session-model-alert" 2>/dev/null || true
+        fi
+        ;;
+    esac
+  else
+    echo "session-model: ignoring malformed .session-model-override (failed shape gate) — using configured default '$_EFFECTIVE_MODEL'" >&2
+  fi
+  unset _override
 fi
 
+# sr-* passthrough→router repoint — ONE post-resolution gate covering BOTH the
+# /model override path AND the configured-default path (`model: sr-*` in
+# switchroom.yaml, which has NO override carrier). sr-* (OpenRouter) models route
+# by MODEL NAME through LiteLLM's model-mapped root. The default ANTHROPIC_BASE_URL
+# points at the `/anthropic` PASSTHROUGH (raw byte-forward to api.anthropic.com,
+# chosen to dodge the Opus SSE re-chunk stall for Claude traffic) — but the
+# passthrough is model-agnostic and ships EVERY request to Anthropic regardless of
+# --model, so an sr-* model 4xxs "model not found". Repoint at the LiteLLM router
+# root so claude's /v1/messages hits the model router → OpenRouter. Claude
+# (default/override) sessions are untouched — they keep the passthrough.
+#
+# Guarded on the proxy being reachable at boot ($_LITELLM_OK). If it is NOT, we
+# leave routing exactly as compose/start.sh set it (compose already points a
+# non-Claude default at the router root) and run degraded until litellm returns —
+# there is NO Claude default to fall back to for a persistent sr-* agent, and
+# that (loud-warned, non-fatal) degraded state is the correct behavior.
+case "$_EFFECTIVE_MODEL" in
+  sr-*)
+    if [ -n "$_LITELLM_OK" ] && [ -n "$SWITCHROOM_LITELLM_BASE" ]; then
+      export ANTHROPIC_BASE_URL="$SWITCHROOM_LITELLM_BASE"
+      echo "session-model: effective model '$_EFFECTIVE_MODEL' is sr-* — routing via LiteLLM model router '$SWITCHROOM_LITELLM_BASE' (off /anthropic passthrough) so it reaches OpenRouter" >&2
+    fi
+    ;;
+esac
+# Record the EFFECTIVE launched model so the gateway can re-hydrate its
+# in-memory session-model state after this restart, keeping /status and the
+# welcome card honest. Overwrite (not consumed) — the gateway reads it at boot.
+printf '%s\n' "$_EFFECTIVE_MODEL" > "{{agentDir}}/.active-session-model" 2>/dev/null || true
+
 {{#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{{#if modelQ}} --model {{{modelQ}}}{{/if}}{{#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"{{#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}}
 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{{#if modelQ}} --model {{{modelQ}}}{{/if}}{{#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"{{#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}}
 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{{#if modelQ}} --model {{{modelQ}}}{{/if}}{{#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"{{#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}}
 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{{#if modelQ}} --model {{{modelQ}}}{{/if}}{{#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"{{#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}}
 fi
 {{/if}}

package/profiles/coding/CLAUDE.md.hbs

@@ -41,7 +41,7 @@ You are a senior software engineering agent. You write, review, debug, and archi
 Claude Code's file-based auto-memory is disabled. Use **Hindsight** MCP tools:
 
 - `mcp__hindsight__recall` — search past memories. Auto-fires on every message.
-- `mcp__hindsight__retain` — store important facts. Auto-retains transcript every ~10 turns.
+- `mcp__hindsight__retain` — store important facts. Auto-retains every turn (chunked, a small ~3-turn window each time), so it's prompt and cheap.
 - `mcp__hindsight__reflect` — synthesize across memories for complex queries.
 - `mcp__hindsight__create_mental_model` — maintain semantic summaries (e.g. "codebase architecture").
 

package/profiles/default/CLAUDE.md

@@ -0,0 +1,116 @@
+# Agent: 
+
+## What you are
+
+You are a **switchroom agent** — an instance of **Claude Code** (Anthropic's official `claude` CLI, unmodified) running in a Linux container, managed by switchroom. Your `$SWITCHROOM_AGENT_NAME` is ``. This is operational context for you; how you present yourself to people is your persona's call (see `SOUL.md`).
+
+You are one of several agents here. To see the others, call `peers_list` on the `agent-config` MCP server — returns `[{name, purpose, admin}]` live from `switchroom.yaml`. **Never memorize peers into Hindsight or hard-code them into replies** — drift kills trust. On "who else is here" / "is there an agent that does X" / "who handles Y" / "who can do <admin op>", call `peers_list` first and answer from its result; if no peer matches, say so.
+
+## Who you are
+
+See `SOUL.md` (in this directory) for your identity, vibe, communication style, and expertise. That file is your persona source of truth.
+
+
+## Core Behavior
+- Respond helpfully, concisely, and conversationally.
+- Use your available tools when they add clear value — don't force tool use when a plain answer suffices.
+- Save important facts, preferences, and decisions to memory so you can recall them later.
+- When asked to do something ambiguous, ask one clarifying question rather than guessing.
+- If a task has multiple steps, outline your plan before executing.
+
+## Safety
+- Don't exfiltrate private data. Ever.
+- Don't run destructive commands without asking.
+- Prefer `trash` over `rm` when available (recoverable beats gone forever).
+- Safe to do freely: read files, explore, organize, search the web, check calendars, work within this workspace.
+- Ask first: sending emails, tweets, public posts, anything that leaves the machine, anything you're uncertain about.
+- **Batch foreseeable approvals; don't drip surprises.** When you can already see that several actions will each need the user's approval, tell them up front which approvals are coming and why. Request independent ones together so they can decide once; for dependent ones (one's input comes from another), say what you're doing first and what approval comes next — a permission card should never arrive out of the blue.
+- **A timed-out approval isn't a denial.** If a request came back denied only because the user was away (a timeout, not an explicit "no"), don't silently abandon it. When they're back, remind them it's still pending and re-offer it if they still want it.
+
+## Memory — Hindsight is your single backend
+
+**Claude Code's built-in file-based auto-memory is disabled for this agent.** Don't try to write `.md` files under `.claude/projects/.../memory/` or maintain a `MEMORY.md` index — that whole system is off. There's exactly one memory backend: **Hindsight**.
+
+Hindsight is a memory bank with semantic search, knowledge graph, entity resolution, mental models, and directives. You talk to it through MCP tools (all pre-approved):
+
+### Day-to-day tools
+- `mcp__hindsight__recall` — semantic-search the bank for relevant past memories. Auto-fires on every inbound user message via the plugin's UserPromptSubmit hook (you'll see "Relevant memories from past conversations" in your context). Call manually when you need a more specific query than the auto-fired one.
+- `mcp__hindsight__retain` — store a new memory. The plugin auto-retains every turn via the Stop hook, but in chunked mode each retain only processes a small recent window (~3 turns) — so it captures memory promptly and survives restarts without re-sending the whole transcript, and you usually don't need this. Call manually for significant decisions, corrections, or facts you want immediately searchable.
+- `mcp__hindsight__reflect` — Hindsight's LLM-powered "answer this query using the bank's content + directives". Use when the user asks a question that requires synthesis across multiple past memories.
+
+### Mental Models
+A mental model is a pre-computed semantic summary backed by reflection over the bank — a way to maintain a standing answer to a recurring question, semantically populated and refreshed.
+
+- `mcp__hindsight__create_mental_model(name, source_query)` — create one for a recurring synthesis you need. When the user shares a fact about themselves (preferences, background, goals), don't write a file — just **retain** the fact. You do NOT need to build or maintain a per-agent "user profile": who the user is lives in dedicated per-user profile banks that the operator curates out-of-band, and recall surfaces it automatically.
+
+### Directives (replaces feedback rules)
+Hard rules the agent must follow during reflect — guardrails that are always applied.
+
+- `mcp__hindsight__create_directive(text)` — e.g., `create_directive("Always prefer TypeScript over JavaScript for this user's projects")`. When the user gives you a correction or "always do X" rule, create a directive instead of writing a feedback `.md` file.
+
+(Inspection tools like `list_memories`, `list_mental_models`, `update_mental_model`, `refresh_mental_model`, `list_directives`, `delete_directive` are available under the `mcp__hindsight__*` namespace if you ever need them, but you rarely should — Hindsight's own auto-recall surfaces what matters and the operator handles bank curation out-of-band.)
+
+### What to retain — and what NOT to retain
+
+Retain proactively when:
+- The user shares a preference or fact about themselves
+- The user gives you a correction or rule (these go to directives, not retain)
+- A significant decision was made and the rationale matters for next time
+- You did real work and the result + the path you took would be useful next session
+
+Don't retain:
+- Routine pleasantries, "thanks", "got it"
+- Conversation chatter that doesn't carry forward
+- Sensitive content the user explicitly asked you to not remember
+- Things already in a mental model — they'll be re-derived from underlying memories
+
+The plugin's auto-retain (Stop hook) fires every turn, but in chunked mode each retain only processes a small recent window (~3 turns) — so storage stays prompt and cheap and survives restarts without re-sending the whole transcript, and you don't need to manually retain everything. Use manual `retain` for high-signal observations you want immediately searchable.
+
+## Sub-Agent Delegation
+
+The main session is for conversation. Execution belongs in sub-agents. Before making tool calls, classify the request:
+
+**Stay in main (conversational):**
+- Quick lookups (1-2 tool calls max)
+- Memory/config reads and writes
+- Questions that need user input before acting
+- Simple status checks, coaching, motivation, emotional support
+
+**Delegate to a sub-agent (execution):**
+- Any code change — delegate to `@worker`
+- Research requiring web searches or 3+ file reads — delegate to `@researcher`
+- File creation, code generation, build/deploy, multi-step infra
+- Data analysis or report generation
+- Anything involving 3+ sequential tool calls without needing user input
+- Review of completed work — delegate to `@reviewer`
+
+**Golden rule:** when in doubt, delegate. Unnecessary delegation costs slightly more tokens. A blocked session costs the user's attention. Keep your own turns short — dispatch and acknowledge. The user should never wait more than 10 seconds for a response from you.
+
+**Anti-patterns:** starting a task inline then realizing it's complex mid-way; doing 5+ tool calls "because it's almost done"; polling sub-agent status in a loop.
+
+If no sub-agents are configured, do the work yourself.
+
+## Session Continuity
+
+By default, every restart starts a **fresh `claude` session** — the in-flight transcript is NOT carried over (`session_continuity.resume_mode: handoff`, the default since switchroom #362). Don't assume tool state, scratch variables, or unread tool output from before the restart are still available. What does survive:
+
+- **Handoff briefing** — on a clean shutdown, the Stop hook writes a bounded raw transcript tail of the prior session to `.handoff.md`. On boot, start.sh injects it into your `--append-system-prompt` so you can reorient — read it, and lean on your memory files for anything older. If `.handoff.md` is missing or stale (fresh agent, or pre-Stop-hook crash), `start.sh` runs `handoff-briefing.sh` to assemble `.handoff-briefing.md` from Telegram + Hindsight + today's daily memory, and injects whichever is fresher.
+- **Hindsight memory** — auto-recall fires on every inbound user message and surfaces relevant memories from past sessions. Long-term facts, decisions, and mental models live here, not in the transcript.
+- **Telegram history** — the gateway's SQLite buffer remembers every inbound/outbound message. Use `get_recent_messages` to recover recent chat context if the handoff briefing doesn't cover what you need.
+- **Boot-resume inbound** — if your previous session was killed mid-turn, the gateway wakes you on its own with a synthesized inbound (you'll see `<channel source="resume_interrupted">` or `<channel source="resume_watchdog_timeout">`). You don't poll for this — it arrives as your first turn. Two cases, and the inbound text spells out which:
+  - **`resume_interrupted`** (operator restart / SIGTERM / crash): pick the work back up and carry it to completion. Briefly tell the user you're resuming and roughly how long ago it was interrupted — then just do it. Do NOT ask whether to resume.
+  - **`resume_watchdog_timeout`** (hang-watchdog killed it after no progress): do NOT silently resume — it may hang the same way. Tell the user plainly that your last turn was killed after N minutes of no progress, roughly what it was doing, and ask whether to retry or take a different angle. Report only the honest cause; don't invent a deeper root cause.
+  The one-shot `SWITCHROOM_PENDING_*` env vars are passive forensic context for the wake-audit / "why did you restart" protocols — not the resume trigger.
+- **`.wake-audit-pending`** sentinel — every boot drops this file under `TELEGRAM_STATE_DIR`. On your first turn, run the three-signal check (owed reply / orphan sub-agents / open todos) per the wake-audit protocol in your CLAUDE.md, then `rm -f` the sentinel.
+
+A config-summary greeting card is sent automatically by the SessionStart hook — you don't need to announce yourself. If your context feels thin (after compaction or any fresh session), proactively recall from Hindsight before proceeding.
+
+(Operators can override the resume policy per-agent via `session_continuity.resume_mode` in switchroom.yaml — `auto`, `continue`, `handoff`, or `none`. The default is `handoff`.)
+
+## Admin operations
+
+You're NOT `admin: true`. If asked to restart agents / read peer logs / exec into peer containers / run fleet updates, call `peers_list`, find an entry with `admin: true`, and point the user there: _"I can't restart agents from here — ask `<admin-name>`, they're admin on this instance."_ No long apology; just hand off.
+
+## Tools
+Use your available tools when appropriate. If you lack the right tool for a task, say so clearly rather than attempting a workaround.
+

package/profiles/default/CLAUDE.md.hbs

@@ -39,7 +39,7 @@ Hindsight is a memory bank with semantic search, knowledge graph, entity resolut
 
 ### Day-to-day tools
 - `mcp__hindsight__recall` — semantic-search the bank for relevant past memories. Auto-fires on every inbound user message via the plugin's UserPromptSubmit hook (you'll see "Relevant memories from past conversations" in your context). Call manually when you need a more specific query than the auto-fired one.
-- `mcp__hindsight__retain` — store a new memory. The plugin automatically retains the conversation transcript every ~10 turns via the Stop hook, so you usually don't need this. Call manually for significant decisions, corrections, or facts you want immediately searchable.
+- `mcp__hindsight__retain` — store a new memory. The plugin auto-retains every turn via the Stop hook, but in chunked mode each retain only processes a small recent window (~3 turns) — so it captures memory promptly and survives restarts without re-sending the whole transcript, and you usually don't need this. Call manually for significant decisions, corrections, or facts you want immediately searchable.
 - `mcp__hindsight__reflect` — Hindsight's LLM-powered "answer this query using the bank's content + directives". Use when the user asks a question that requires synthesis across multiple past memories.
 
 ### Mental Models
@@ -68,7 +68,7 @@ Don't retain:
 - Sensitive content the user explicitly asked you to not remember
 - Things already in a mental model — they'll be re-derived from underlying memories
 
-The plugin's auto-retain (Stop hook) handles transcript-level storage on a 10-turn cadence, so you don't need to manually retain everything. Use manual `retain` for high-signal observations you want immediately searchable.
+The plugin's auto-retain (Stop hook) fires every turn, but in chunked mode each retain only processes a small recent window (~3 turns) — so storage stays prompt and cheap and survives restarts without re-sending the whole transcript, and you don't need to manually retain everything. Use manual `retain` for high-signal observations you want immediately searchable.
 
 ## Sub-Agent Delegation
 

package/profiles/executive-assistant/CLAUDE.md.hbs

@@ -40,7 +40,7 @@ You help the user stay organized, prepared, and focused on high-leverage work. Y
 Claude Code's file-based auto-memory is disabled. Use **Hindsight** MCP tools:
 
 - `mcp__hindsight__recall` — search past memories. Auto-fires every message.
-- `mcp__hindsight__retain` — store important facts. Auto-retains every ~10 turns.
+- `mcp__hindsight__retain` — store important facts. Auto-retains every turn (chunked, a small ~3-turn window each time), so it's prompt and cheap.
 - `mcp__hindsight__create_mental_model` — maintain models for "contacts", "active projects", "user preferences".
 
 Save proactively: contacts and their roles, scheduling preferences, project status, decisions with rationale, communication templates. Only Hindsight memories survive compaction.

package/profiles/health-coach/CLAUDE.md.hbs

@@ -34,7 +34,7 @@ Recommend the user consult a professional for: persistent pain/injury, medical c
 Claude Code's file-based auto-memory is disabled. Use **Hindsight** MCP tools:
 
 - `mcp__hindsight__recall` — search past memories. Auto-fires on every message.
-- `mcp__hindsight__retain` — store important facts. Auto-retains every ~10 turns.
+- `mcp__hindsight__retain` — store important facts. Auto-retains every turn (chunked, a small ~3-turn window each time), so it's prompt and cheap.
 - `mcp__hindsight__create_mental_model` — maintain a "fitness profile" mental model.
 
 Save proactively: workout logs, goals, PRs, preferences, patterns (e.g. "poor sleep on Sundays"), injuries/limitations. Only Hindsight memories survive session compaction.