switchroom 0.11.1 → 0.12.0

package/examples/personal-google-workspace-mcp/README.md

@@ -6,9 +6,14 @@ tools to **your own Claude Code session on the host** (not to switchroom
 agents).
 
 It is intentionally **separate from the agent-side feature.** Agents get
-Workspace access via `switchroom auth google connect <agent>` (RFC G
-§4.5, available after Phase 3 lands). This example is for the
-operator's pair-design loop with their own host-side `claude`.
+Workspace access via `switchroom auth google connect` →
+`switchroom auth google account add` (RFC G §4.5, shipped) — see
+[`docs/google-workspace.md`](../../docs/google-workspace.md) for the
+fleet setup. **Do not reuse this example's OAuth client for the
+fleet:** different trust posture (approval-kernel-mediated vs.
+single-identity), and switchroom expects its own client. This example
+is only for the operator's pair-design loop with their own host-side
+`claude`.
 
 > **Why two paths?** Agents run inside switchroom containers with
 > approval-kernel-mediated tool access; the per-agent OAuth posture is

package/examples/switchroom.yaml

@@ -5,8 +5,22 @@
 #   2. profiles:  → named presets agents opt into via `extends:`
 #   3. agents:    → per-agent overrides (only express differences)
 #
-# Each agent gets its own Telegram topic in a forum group.
-# Create bots via @BotFather: /newbot for each agent.
+# ┌─ ONE TELEGRAM BOT PER AGENT — NON-NEGOTIABLE ───────────────────┐
+# │ Every agent MUST have its own Telegram bot + its own token.     │
+# │ Two agents sharing a token both long-poll getUpdates and        │
+# │ Telegram 409-Conflicts them in a loop — neither one replies.    │
+# │                                                                 │
+# │ For each agent: create a separate @BotFather bot (`/newbot`),   │
+# │ vault its token under its own key                               │
+# │ (`switchroom vault set telegram-<agent>-bot-token`), and give   │
+# │ the agent its own `bot_token: "vault:telegram-<agent>-bot-      │
+# │ token"`. This file ships ONE active agent (`assistant`); every  │
+# │ extra agent below is commented out WITH its own bot_token —     │
+# │ uncomment one only after you've minted its bot + vaulted its    │
+# │ token, then `switchroom apply` (no need to re-run setup).       │
+# └─────────────────────────────────────────────────────────────────┘
+#
+# See docs/botfather-walkthrough.md for the ~3-min-per-bot steps.
 
 switchroom:
   version: 1
@@ -14,6 +28,12 @@ switchroom:
   skills_dir: ~/.switchroom/skills           # shared skill pool (symlinked per agent)
 
 telegram:
+  # Single-agent fallback ONLY. This is the bot the one shipped agent
+  # (`assistant`) uses — `switchroom setup` stores your first
+  # BotFather token in the vault under `telegram-bot-token`. The
+  # moment you run more than one agent, this global token is NOT
+  # enough: give EACH agent its own `bot_token:` (see the agents
+  # section). Never let two agents resolve to the same token.
   bot_token: "vault:telegram-bot-token"
   # DM-only sentinel; v0.7+ defaults to per-agent DM-pair topology.
   # Legacy forum-mode installs keep a real chat id here.
@@ -155,52 +175,80 @@ profiles:
 
 # --- Agents ---
 # Minimal per-agent declarations. Everything else inherited.
+#
+# This file ships exactly ONE active agent so a fresh `switchroom
+# setup` → `apply` → `up` brings up a single, working bot (the
+# `assistant` below uses the single global telegram.bot_token that
+# setup vaulted). Every other agent is a commented-out TEMPLATE.
+#
+# To add any agent: (1) @BotFather `/newbot` → a NEW bot just for it;
+# (2) `switchroom vault set telegram-<agent>-bot-token` (paste that
+# bot's token); (3) uncomment its block below — note each already
+# carries its own `bot_token: "vault:telegram-<agent>-bot-token"`;
+# (4) `switchroom apply`. Do NOT re-run `switchroom setup` for this —
+# `apply` reads the vaulted per-agent token directly.
+#
+# Sharing one token across agents is the single most common
+# multi-agent install failure: both bots long-poll getUpdates and
+# Telegram 409-Conflicts them forever. One bot per agent, always.
 agents:
-  coach:
-    topic_name: "Fitness"
-    topic_emoji: "🏋️"
-    extends: advisor                    # inherits from inline profile above
-    soul:
-      name: Coach
-      style: motivational, direct       # overrides advisor.soul.style
-    memory:
-      collection: fitness
-    schedule:
-      - cron: "0 8 * * *"
-        prompt: "Good morning check-in: ask about sleep, energy, and plans for today"
-      - cron: "0 20 * * 0"
-        prompt: "Weekly review: summarize this week's activity and progress"
-
-  dev:
-    topic_name: "Code"
-    topic_emoji: "💻"
-    extends: coder                      # inherits from inline profile above
-    model: claude-opus-4-7              # override defaults.model for this agent
-    memory:
-      collection: coding
-    cli_args: ["--effort", "high"]      # escape hatch: extra exec claude flags
-
   assistant:
     topic_name: "General"
     topic_emoji: "💬"
     memory:
       collection: general
+    # Uses the global telegram.bot_token above (the one `switchroom
+    # setup` vaulted as `telegram-bot-token`). This is the ONLY agent
+    # allowed to rely on the global token — because it's the only one
+    # shipped active. Give every agent you add its own bot_token.
     # No `extends:` → uses the "default" filesystem profile (profiles/default/)
     # No tool/model overrides → inherits everything from defaults:
 
-  exec:
-    topic_name: "Executive"
-    topic_emoji: "📋"
-    extends: advisor
-    soul:
-      name: Friday
-      style: efficient, proactive, anticipates needs
-    skills: [daily-briefing, meeting-prep]
-    memory:
-      collection: executive
-    schedule:
-      - cron: "0 7 * * 1-5"
-        prompt: "Daily briefing: summarize today's calendar, pending tasks, and priorities"
+  # ── Additional agents — each needs its OWN BotFather bot ──────────
+  # Before uncommenting any block: create its bot, then
+  #   switchroom vault set telegram-coach-bot-token   # (etc.)
+  # The `bot_token:` line in each block points at that per-agent key.
+
+  # coach:
+  #   topic_name: "Fitness"
+  #   topic_emoji: "🏋️"
+  #   bot_token: "vault:telegram-coach-bot-token"   # its own bot
+  #   extends: advisor                    # inherits from inline profile above
+  #   soul:
+  #     name: Coach
+  #     style: motivational, direct       # overrides advisor.soul.style
+  #   memory:
+  #     collection: fitness
+  #   schedule:
+  #     - cron: "0 8 * * *"
+  #       prompt: "Good morning check-in: ask about sleep, energy, and plans for today"
+  #     - cron: "0 20 * * 0"
+  #       prompt: "Weekly review: summarize this week's activity and progress"
+
+  # dev:
+  #   topic_name: "Code"
+  #   topic_emoji: "💻"
+  #   bot_token: "vault:telegram-dev-bot-token"     # its own bot
+  #   extends: coder                      # inherits from inline profile above
+  #   model: claude-opus-4-7              # override defaults.model for this agent
+  #   memory:
+  #     collection: coding
+  #   cli_args: ["--effort", "high"]      # escape hatch: extra exec claude flags
+
+  # exec:
+  #   topic_name: "Executive"
+  #   topic_emoji: "📋"
+  #   bot_token: "vault:telegram-exec-bot-token"    # its own bot
+  #   extends: advisor
+  #   soul:
+  #     name: Friday
+  #     style: efficient, proactive, anticipates needs
+  #   skills: [daily-briefing, meeting-prep]
+  #   memory:
+  #     collection: executive
+  #   schedule:
+  #     - cron: "0 7 * * 1-5"
+  #       prompt: "Daily briefing: summarize today's calendar, pending tasks, and priorities"
 
   # Example admin agent — its gateway intercepts fleet-management slash
   # commands (/agents, /restart, /update, /logs, etc.) and runs them
@@ -209,12 +257,13 @@ agents:
   # on every agent regardless of admin status. See the three-tier
   # command model in docs/architecture.md.
   #
-  # Uncomment after creating a second BotFather bot and adding its
-  # token to the vault (`switchroom vault set telegram-admin-bot-token`).
+  # Like every agent it needs its OWN bot — create a separate BotFather
+  # bot and `switchroom vault set telegram-admin-bot-token` before
+  # uncommenting.
   # admin:
   #   topic_name: "Admin"
   #   topic_emoji: "🛠️"
-  #   bot_token: "vault:telegram-admin-bot-token"
+  #   bot_token: "vault:telegram-admin-bot-token"   # its own bot
   #   admin: true
   #   system_prompt_append: |
   #     You are the fleet admin agent. Always respond concisely.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "dev": "bun bin/switchroom.ts",
     "build": "node scripts/build.mjs",
     "build:cli": "node scripts/build.mjs && bun build --compile --target=bun-linux-x64 --minify bin/switchroom.ts --outfile switchroom-linux-amd64",
+    "pretest": "npm run build",
     "test": "vitest run && bun test telegram-plugin/tests/history.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/registry/api-registry.test.ts telegram-plugin/registry/turns-schema.test.ts telegram-plugin/tests/idle-footer-wiring.test.ts telegram-plugin/tests/subagent-tracker-hooks.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts",
     "test:vitest": "vitest run",
     "test:bun": "bun test src/watchdog/state.test.ts src/watchdog/policy.test.ts src/vault/grants.test.ts src/vault/write-grants.test.ts src/vault/broker/server-grants.test.ts src/vault/broker/server-write-grants.test.ts src/vault/broker/server-mint-grant-passphrase-attest.test.ts src/vault/broker/server-passphrase-attest.test.ts src/vault/broker/server-mint-grant-posture-attest.test.ts src/vault/broker/client-token.test.ts src/vault/broker/server-unlock.test.ts src/vault/broker/auto-unlock.test.ts src/vault/broker/drift-detection.test.ts tests/vault-broker-passphrase.test.ts src/cli/vault-get-broker.test.ts src/vault/resolver-via-broker.test.ts src/vault/broker/scope.test.ts src/vault/broker/server.test.ts src/drive/disconnect.test.ts src/drive/grants.test.ts src/drive/oauth.test.ts src/drive/onboarding.test.ts src/drive/reconciler.test.ts src/drive/vault-slots.test.ts src/drive/wrapper.test.ts src/vault/approvals/kernel.test.ts src/vault/approvals/schema-idempotent.test.ts src/vault/broker/server-approvals.test.ts telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/boot-version-string.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/uat/load-env.test.ts",
@@ -53,7 +54,6 @@
     "@types/bun": "^1.3.11",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "3.2.4",
-    "buildkite-test-collector": "^1.9.5",
     "typescript": "^5.7.0",
     "vitest": "^3.2.4"
   },

package/profiles/_base/start.sh.hbs

@@ -32,66 +32,88 @@ 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"
 
-  # Tiny in-process supervisor: runs cmd in a respawn loop. Caps at
-  # 10 restarts in 60s before giving up — protects against tight
-  # crash loops that would otherwise burn CPU and obscure the root
-  # cause in logs. The sidecar's own structured logging is written
+  # Tiny in-process supervisor: runs cmd in a respawn loop with
+  # exponential backoff (1→2→4…→60s cap) and NEVER permanently gives
+  # up. Rationale (RFC J / install-validation 2026-05-17): the
+  # gateway's hardest dependency is the vault-broker, which gets
+  # recreated+relocked by a routine `switchroom apply`. The old
+  # "10 restarts in 60s → give up forever" turned that transient
+  # outage into a dead agent until a human recreated the container —
+  # a direct violation of the always-on outcome. Backoff bounds CPU
+  # during an outage; indefinite retry means the agent self-heals
+  # within one backoff cycle the moment the broker is back. The ONLY
+  # non-retry path is EX_CONFIG=78 (genuine permanent misconfig).
+  # The sidecar's own structured logging is written
   # directly to its log file; this wrapper only handles process
   # lifecycle. Ampersand-backgrounded by callers below.
   _switchroom_supervise() {
     local _name="$1"; local _logfile="$2"; shift 2
-    local _restarts=0
-    local _window_start=$SECONDS
+    local _cap=60
+    local _delay=1
+    local _attempt=0
     while true; do
+      local _start=$SECONDS
       "$@" >> "$_logfile" 2>&1
       local _exit=$?
-      local _now=$SECONDS
+      local _ran=$((SECONDS - _start))
       # Exit 78 = sysexits EX_CONFIG, the "permanent config error, do
       # not restart" sentinel. The gateway uses this on a 401 from
       # Telegram (#1076 — revoked / wrong-typed bot token). Restarting
-      # would just re-hit the same 401, burn the 10-in-60 s budget,
-      # and leave the agent silently dead. The supervisor instead
-      # records the quarantine in the log and stops — the host CLI
-      # (`switchroom doctor`, `switchroom agent restart`) reads the
-      # quarantine marker at <TELEGRAM_STATE_DIR>/quarantine.json and
-      # surfaces it to the operator.
+      # just re-hits the same 401, so we quarantine and stop — the
+      # host CLI (`switchroom doctor`, `switchroom agent restart`)
+      # reads the marker at <TELEGRAM_STATE_DIR>/quarantine.json and
+      # surfaces it. This is the ONLY non-retry path: a transient
+      # dependency (vault-broker locked/recreating — RFC J) must never
+      # be terminal for an always-on agent.
       if [ $_exit -eq 78 ]; then
         echo "[supervise] $_name exit 78 (EX_CONFIG) — quarantined, not restarting. Operator action required." >> "$_logfile"
         return 0
       fi
-      if [ $((_now - _window_start)) -ge 60 ]; then
-        _restarts=0
-        _window_start=$_now
+      # A run that stayed up for at least the backoff cap means the
+      # dependency was healthy and this exit is a fresh transient
+      # blip — reset backoff so recovery latency is minimal. Only
+      # consecutive fast failures escalate the delay.
+      if [ $_ran -ge $_cap ]; then
+        _delay=1
+        _attempt=0
       fi
-      _restarts=$((_restarts + 1))
-      echo "[supervise] $_name exited (status=$_exit, restart=$_restarts in $((_now - _window_start))s window)" >> "$_logfile"
-      if [ $_restarts -ge 10 ]; then
-        echo "[supervise] $_name hit 10 restarts in <60s — giving up" >> "$_logfile"
-        return 1
-      fi
-      sleep 1
+      _attempt=$((_attempt + 1))
+      echo "[supervise] $_name exited (status=$_exit, ran=${_ran}s, attempt=$_attempt) — retrying in ${_delay}s (transient deps self-heal; never gives up)" >> "$_logfile"
+      sleep $_delay
+      _delay=$((_delay * 2))
+      [ $_delay -gt $_cap ] && _delay=$_cap
     done
   }
 
   # 1) Gateway daemon — the long-running Telegram bot client.
+  #    Honors channels.telegram.enabled (PR A schema, PR C wiring).
+  #    When the operator sets enabled:false, skip the gateway sidecar
+  #    entirely so the agent boots without bot-token requirements —
+  #    used by the CI smoke-test harness and any offline-dev setup.
+  #    Default behavior preserved: when the var is unset/empty, treat
+  #    as enabled (no operator action required for existing agents).
   #    Polls Telegram, writes gateway.sock for the in-claude MCP
   #    sidecar to bridge through. Mirrors the v0.6 sibling
   #    switchroom-<name>-gateway.service unit. Talks to the broker
   #    over SWITCHROOM_VAULT_BROKER_SOCK (set by compose) for the bot
   #    token. Failure modes: vault locked → gateway boots, fails to
-  #    fetch token, exits non-zero, supervisor respawns; bot token
-  #    invalid → 401 from Telegram, gateway exits, same loop. The
-  #    cap avoids an infinite vault-locked respawn storm.
+  #    fetch token, exits non-zero, supervisor backs off and keeps
+  #    retrying — it recovers on its own the moment the broker
+  #    unlocks (no human, no container recreate); bot token invalid
+  #    → 401 → gateway exits 78 → quarantined (operator action).
   _gateway_bundle=/opt/switchroom/telegram-plugin/dist/gateway/gateway.js
-  if [ -f "$_gateway_bundle" ] && command -v bun >/dev/null 2>&1; then
+  _telegram_enabled={{#if telegramEnabledFlag}}{{telegramEnabledFlag}}{{else}}true{{/if}}
+  if [ "$_telegram_enabled" = "true" ] && [ -f "$_gateway_bundle" ] && command -v bun >/dev/null 2>&1; then
     _switchroom_supervise gateway /var/log/switchroom/gateway-supervisor.log \
       bun "$_gateway_bundle" &
+  elif [ "$_telegram_enabled" != "true" ]; then
+    echo "[start.sh] channels.telegram.enabled=false — skipping gateway sidecar" >&2
   fi
 
   # 2) autoaccept-poll — first-run TUI prompt dispatcher. Single-shot
   #    by design (exits cleanly after idle-timeout once prompts have
-  #    fired); supervisor's restart cap means a flaky autoaccept won't
-  #    masquerade as a tight loop.
+  #    fired); the supervisor's exponential backoff keeps a flaky
+  #    autoaccept from busy-looping.
   if [ -f /opt/switchroom/autoaccept-poll.js ] && command -v bun >/dev/null 2>&1; then
     _switchroom_supervise autoaccept /var/log/switchroom/autoaccept.log \
       bun /opt/switchroom/autoaccept-poll.js "{{name}}" &
@@ -375,8 +397,8 @@ fi
 # --- Wake audit sentinel ---
 #
 # Every boot drops a `.wake-audit-pending` sentinel into the telegram
-# state dir. The agent's CLAUDE.md (`telegram-style.md.hbs` "Wake
-# audit" section) instructs it to detect this file at the start of
+# state dir. The agent's wake-audit protocol
+# (`skills/switchroom-runtime/SKILL.md`) instructs it to detect this file at the start of
 # its first turn after boot, run a three-signal check (owed reply /
 # orphan sub-agents / open todos), surface findings to the user, and
 # `rm -f` the file. This complements the SWITCHROOM_PENDING_TURN env
@@ -394,7 +416,7 @@ fi
 # level dedup (so the agent doesn't re-fire the same "owed reply"
 # audit twice on the same user message after a respawn) lives in the
 # agent's audit logic via `.wake-audit-last-completed`, not here. See
-# the "Conversation-aware dedup" block in telegram-style.md.hbs.
+# the "Conversation-aware dedup" block in skills/switchroom-runtime/SKILL.md.
 mkdir -p "$TELEGRAM_STATE_DIR" 2>/dev/null || true
 : > "$TELEGRAM_STATE_DIR/.wake-audit-pending" 2>/dev/null || true
 
@@ -514,16 +536,34 @@ if [ -x "{{repoRoot}}/bin/boot-self-test.sh" ]; then
 fi
 {{/if}}
 
+# --- Security-hooks plugin integrity check (sec WS8-F1 / #1416) ---
+# The image-baked, agent-unstrippable tool-safety plugin is loaded via
+# --plugin-dir below. If the image copy is missing/empty (bad build,
+# tampering, downgrade) we DON'T fail boot — Claude Code unions
+# plugin-dir hooks with the settings.json copy, which still protects —
+# but we surface it loudly to stderr so the gap is visible instead of
+# silently relying on the strippable fallback.
+SR_SECPLUGIN="{{securityPluginDir}}"
+for f in \
+  "$SR_SECPLUGIN/.claude-plugin/plugin.json" \
+  "$SR_SECPLUGIN/hooks/hooks.json" \
+  "$SR_SECPLUGIN/hooks/secret-guard-pretool.mjs" \
+  "$SR_SECPLUGIN/hooks/drive-write-pretool.mjs"; do
+  if [ ! -s "$f" ]; then
+    echo "WARNING sec WS8-F1 (#1416): security-hooks plugin artifact missing or empty: $f — tool-safety is running on the settings.json fallback only (strippable). Rebuild/redeploy the agent image." >&2
+  fi
+done
+
 {{#if useSwitchroomPlugin}}
 if [ -n "$APPEND_PROMPT" ]; then
-  exec claude $CONTINUE_FLAG --dangerously-load-development-channels server:switchroom-telegram{{#if hindsightEnabled}} --plugin-dir "{{agentDir}}/.claude/plugins/hindsight-memory"{{/if}}{{#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}}{{#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}}
 else
-  exec claude $CONTINUE_FLAG --dangerously-load-development-channels server:switchroom-telegram{{#if hindsightEnabled}} --plugin-dir "{{agentDir}}/.claude/plugins/hindsight-memory"{{/if}}{{#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}}{{#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}}
 fi
 {{else}}
 if [ -n "$APPEND_PROMPT" ]; then
-  exec claude $CONTINUE_FLAG --channels plugin:telegram@claude-plugins-official{{#if hindsightEnabled}} --plugin-dir "{{agentDir}}/.claude/plugins/hindsight-memory"{{/if}}{{#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}}{{#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}}
 else
-  exec claude $CONTINUE_FLAG --channels plugin:telegram@claude-plugins-official{{#if hindsightEnabled}} --plugin-dir "{{agentDir}}/.claude/plugins/hindsight-memory"{{/if}}{{#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}}{{#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}}
 fi
 {{/if}}

package/profiles/default/CLAUDE.md.hbs

@@ -122,6 +122,8 @@ A config-summary greeting card is sent automatically by the SessionStart hook
 ## Admin surface
 
 You're `admin: true`. Fleet operations live on the `hostd` MCP server: `agent_restart` / `agent_start` / `agent_stop` (lifecycle of any peer), `agent_logs` (peer container logs), `agent_exec` (read-only inspection inside any peer — argv[0] must be on the safe-command allowlist), `update_check` / `update_apply`. Treat these like a root shell on the host: confirm intent before destructive actions, refuse if unsure who's asking.
+
+Only `update_check` (a read-only dry-run) runs immediately. Every mutating / host verb — `update_apply`, `agent_exec`, `agent_restart` / `agent_start` / `agent_stop`, `agent_logs` — pauses for an **operator approval card in Telegram before it executes**: a human must tap approve. This is deliberate (you are a prompt-injectable process; the human in the loop is the safety boundary, not your own judgement). Expect the call to block until approved or denied; if denied, don't retry — relay the denial and stop.
 {{else}}
 ## Admin operations
 
@@ -137,7 +139,7 @@ Use your available tools when appropriate. If you lack the right tool for a task
 
 {{#if schedule}}
 ## Scheduled Tasks
-You have scheduled tasks configured. These run independently as one-shot `claude -p` calls on a schedule that fires across reboots. They don't use your session or context, they fire on their own (typically Sonnet for cost efficiency) and send output directly to Telegram.
+You have scheduled tasks configured. At fire time an in-container scheduler sidecar injects a synthesized inbound turn into **your running session** — a scheduled task arrives as an ordinary turn tagged `<channel source="cron">`, using your normal session, context, and model, and it shows up in your transcript and Hindsight memory like any other turn (it is *not* an isolated one-shot `claude -p` process). They survive reboots via the container restart policy plus an at-least-once boot replay.
 
-You don't need to manage them. If the user asks about scheduled tasks, explain that they run automatically and are configured in switchroom.yaml under `schedule:`.
+You don't need to manage them. If the user asks about scheduled tasks, explain that they fire into your session automatically and are configured in switchroom.yaml under `schedule:`.
 {{/if}}

package/skills/file-bug/SKILL.md

@@ -74,11 +74,13 @@ Switchroom's standard log map (resolve `<agent>` from the user or from `SWITCHRO
 |---|---|---|
 | Gateway events | `~/.switchroom/agents/<agent>/telegram/gateway.log` | Inbound/outbound messages, IPC, progress card, watcher, classifier output |
 | Claude stdout/stderr | `~/.switchroom/agents/<agent>/service.log` | The agent's own session output, tool calls, errors |
-| Systemd lifecycle | `journalctl --user -u switchroom-agent-<agent>` | Boot/restart/crash, exit codes |
-| Cron lifecycle | `journalctl --user -u switchroom-agent-<agent>-cron` | Scheduled-task firings |
-| Vault broker | `journalctl --user -u switchroom-vault-broker` | Audit log, ACL gates |
+| Container lifecycle | `docker logs switchroom-<agent>` | Boot/restart/crash, exit codes |
+| Cron firings | `docker logs switchroom-<agent>` (lines prefixed `agent-scheduler:`) | Scheduled-task firings (in-container sidecar since Phase 4) |
+| Vault broker | `docker logs switchroom-vault-broker` | Audit log, ACL gates |
 
-For each relevant source: extract the slice that brackets the symptom window. Use `awk '/<start-ts>/,/<end-ts>/'` or `journalctl --since "10 min ago"`. Do **not** paste raw multi-MB dumps; cap each excerpt at the lines that actually matter and signpost what was clipped.
+(v0.7+ agents run in Docker — there is no systemd/`journalctl` in-container; logs are `docker logs`. Only a legacy non-docker install would use `journalctl --user -u switchroom-…`.)
+
+For each relevant source: extract the slice that brackets the symptom window. Use `docker logs --since 10m switchroom-<agent>` or pipe through `awk '/<start-ts>/,/<end-ts>/'`. Do **not** paste raw multi-MB dumps; cap each excerpt at the lines that actually matter and signpost what was clipped.
 
 If the gateway.log doesn't have what you need, check whether `progress-card.log`, `bridge.log`, or `subagent-watcher.log` are configured separately on this agent (some setups split).
 

package/skills/switchroom-cli/SKILL.md

@@ -234,16 +234,32 @@ List cron jobs and scheduled tasks.
 
 ### Step 1 — Show live timers
 
-Cron timers in v0.7+ run inside the per-agent scheduler container. Inspect
-its log to see fired jobs:
+Since Phase 4 (#893) cron runs **in-container** as the `agent-scheduler`
+sidecar inside each agent — the old `switchroom-<agent>-scheduler` /
+`switchroom-cron` singleton container no longer exists. Inspect fired
+jobs in the agent's own log; scheduler lines are prefixed
+`agent-scheduler:`:
 
 ```bash
-docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml logs switchroom-<agent>-scheduler --tail 100
+docker logs --tail 100 switchroom-<agent> 2>&1 | grep agent-scheduler:
 ```
 
 ### Step 2 — Show declared schedule entries
 
-From `switchroom.yaml`, the `schedule:` array under each agent specifies `cron` + `prompt` + optional `model`. Read the relevant agent block and enumerate the entries with their next-fire times.
+From `switchroom.yaml`, the `schedule:` array under each agent specifies `cron` + `prompt`. (A `model:` field may appear but is **ignored** — since the v0.8 cron-fold-in the fire runs in the agent's existing session and uses the agent's configured model, not a per-task one. Don't tell the user a per-task model is honoured.) Cron expressions are evaluated in the agent's resolved timezone (the `switchroom.timezone` / per-agent `timezone` cascade), not hard-coded UTC. Read the relevant agent block and enumerate the entries with their next-fire times in that zone.
+
+### Step 3 — A schedule change is NOT live until the agent restarts
+
+The in-container `agent-scheduler` reads its entries **once at boot**. Editing the `schedule:` array in `switchroom.yaml`, or adding/removing an entry via the agent-config `schedule add` / `schedule remove` tools, writes the change to disk but does **not** register it in the running scheduler. The same is true for `skill_install` and `.mcp.json` changes — claude loads skills and MCP servers at process start.
+
+So whenever you (or the user) change a schedule, skill, or MCP config:
+
+- The `schedule add` / `skill_install` tool result includes `restart_required: true` and a `restart_hint`. **Surface it.** Tell the user plainly that the change is on disk but won't take effect until `switchroom agent restart <name>` (or `switchroom restart <name>` for the reconcile+restart path).
+- Never report a just-added schedule or skill as already active. It is staged, not live.
+
+### Step 4 — Missed runs while the agent was offline
+
+If the user asks whether scheduled runs were missed during downtime: the scheduler replays fires missed within the last ~30 min on boot, but runs older than that window are **not** re-run (cron is not a queue). It is not silent about this — on boot it emits a one-time notice listing every schedule that had a skipped run, delivered as a normal turn and recorded in `agent-scheduler:` log lines / `/state/agent/scheduler.jsonl`. Check those to answer honestly; never claim a run happened if the skip notice says it was dropped.
 
 ---
 

package/skills/switchroom-install/SKILL.md

@@ -107,7 +107,7 @@ This is the default. One OAuth flow per Anthropic account, then every agent in t
 ## What not to do
 
 - **Do not** run `switchroom setup` non-interactively or pipe input to it — it's designed for a human.
-- **Do not** edit `~/.switchroom/vault.enc` or any file under `~/.switchroom/` directly. Use the CLI.
-- **Do not** run `docker build` on the operator's host. The 5 fleet images are published on GHCR; `switchroom apply` writes a compose file that pulls them.
-- **Do not** suggest the legacy `switchroom up` / `switchroom init` / `switchroom update` verbs — they were removed in v0.7. The current flow is `switchroom apply && docker compose pull && docker compose up -d`.
+- **Do not** edit the vault (`~/.switchroom/vault/`) or any file under `~/.switchroom/` directly. Use the CLI.
+- **Do not** run `docker build` on the operator's host. The fleet images are published on GHCR; `switchroom apply` writes a compose file that pulls them.
+- **Do not** suggest the legacy `switchroom up` / `switchroom init` verbs — they were removed. NOTE: `switchroom update` is **current and canonical** — it is the one-shot upgrade path (pull images + apply + recreate + doctor); recommend it for "how do I update". A fresh install/redeploy is `switchroom apply && docker compose pull && docker compose up -d`.
 - **Do not** reinstall over an existing install without asking. If the user wants a clean slate, have them run `switchroom uninstall` first (or confirm they want to blow away `~/.switchroom/`).

package/telegram-plugin/auth-snapshot-format.ts

@@ -1,7 +1,7 @@
 /**
  * Format 2 — health-grouped /auth snapshot + causal auto-fallback
  * announcement. Pure functions; the gateway handles the live-API probe
- * (via `fetchAccountQuota({force: true})`) and the broker `listState`,
+ * (via the broker `probe-quota` op, #1336) and the broker `listState`,
  * then hands shaped data to these formatters.
  *
  * JTBD this module serves:
@@ -588,9 +588,9 @@ function escapeHtml(s: string): string {
  * results (same length, same order), return the AccountSnapshot[] the
  * formatters need.
  *
- * The gateway calls this after running `Promise.all(accounts.map(a =>
- * fetchAccountQuota(a.label, {force: true})))` — both arrays are
- * caller-provided, this is just a zip + classify.
+ * The gateway calls this after probing quota via the broker
+ * `probe-quota` op (#1336) — both arrays are caller-provided, this
+ * is just a zip + classify.
  */
 export function buildSnapshotsFromState(
   state: ListStateData,

package/telegram-plugin/card-format.ts

@@ -1,9 +1,9 @@
 /**
  * Shared formatters for Telegram status cards.
  *
- * Both the main progress card (`progress-card.ts`) and the pinned worker
- * card (`subagent-watcher.ts`) emit HTML to Telegram; before issue #94
- * each module had its own private copies of these helpers with subtly
+ * Both the main progress card (rendered via `stream-reply-handler.ts`)
+ * and the pinned worker card (`subagent-watcher.ts`) emit HTML to
+ * Telegram; before issue #94 each had its own private copies with subtly
  * different conventions:
  *
  *   - `formatDuration(500)` → progress-card returned `500ms`, watcher