switchroom 0.5.0 → 0.7.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
-  "version": "0.5.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, no Docker.",
+  "version": "0.7.8",
+  "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": {
     "switchroom": "./dist/cli/switchroom.js"
@@ -19,9 +19,10 @@
   "scripts": {
     "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",
     "test": "vitest run && bun test telegram-plugin/tests/history.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/foreman-state.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",
     "test:vitest": "vitest run",
-    "test:bun": "bun test src/vault/grants.test.ts src/vault/broker/server-grants.test.ts src/vault/broker/client-token.test.ts src/vault/broker/server-unlock.test.ts src/vault/broker/auto-unlock.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 telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/setup-state.test.ts telegram-plugin/tests/history.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/foreman-state.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",
+    "test:bun": "bun test src/watchdog/state.test.ts src/watchdog/policy.test.ts src/vault/grants.test.ts src/vault/broker/server-grants.test.ts src/vault/broker/client-token.test.ts src/vault/broker/server-unlock.test.ts src/vault/broker/auto-unlock.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/broker/server-approvals.test.ts telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/setup-state.test.ts telegram-plugin/tests/history.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/foreman-state.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",
     "test:watch": "vitest",
     "lint": "tsc --noEmit && node scripts/check-plugin-references.mjs",
     "lint:tsc": "tsc --noEmit",

package/profiles/_base/start.sh.hbs

@@ -1,7 +1,140 @@
 #!/bin/bash
+# --- Docker-mode tmux supervisor (#793 §2 / v0.7.5) ---
+# Under v0.6 systemd the unit's ExecStart is `tmux new-session -d ...
+# bash -l start.sh`, ExecStartPost spawns autoaccept-poll on the host,
+# and a sibling unit `switchroom-<name>-gateway.service` runs the
+# telegram-plugin gateway daemon — three pieces sitting OUTSIDE the
+# agent process. Under v0.7 docker the container's CMD is start.sh
+# directly under tini, with no tmux wrapper, no host-side
+# ExecStartPost, and no sibling gateway unit. Without this preamble
+# the first-run dev-channels acknowledgement prompt blocks claude
+# forever (no autoaccept), `switchroom agent attach` fails (no tmux
+# server with the expected socket name), and the telegram MCP sidecar
+# exits at boot with "no gateway socket; check `systemctl --user
+# status switchroom-telegram-gateway`" because the gateway daemon
+# isn't running anywhere.
+#
+# Fix: when we detect docker mode AND we're not already inside the
+# inner tmux pane (the SWITCHROOM_DOCKER_TMUX_INNER marker), spawn
+# the gateway daemon AND autoaccept-poll as supervised sidecars then
+# re-exec into tmux with this same script as the inner command.
+# Inside tmux the marker is set, so the preamble is a no-op and the
+# rest of the script runs normally.
+#
+# Socket name `switchroom-<agent>` and session name `<agent>` match
+# what `src/agents/autoaccept.ts:151` and
+# `src/agents/lifecycle.ts:attachAgent` expect — the contract is the
+# same one v0.6 systemd has always honored, just enforced inside the
+# container instead of by the host's user systemd manager.
+if [ "$SWITCHROOM_RUNTIME" = "docker" ] && [ -z "$SWITCHROOM_DOCKER_TMUX_INNER" ]; then
+  # Hoist TELEGRAM_STATE_DIR up here so the gateway daemon (forked
+  # below) finds gateway.sock / gateway.pid.json / history.db at the
+  # 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
+  # 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
+    while true; do
+      "$@" >> "$_logfile" 2>&1
+      local _exit=$?
+      local _now=$SECONDS
+      if [ $((_now - _window_start)) -ge 60 ]; then
+        _restarts=0
+        _window_start=$_now
+      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
+    done
+  }
+
+  # 1) Gateway daemon — the long-running Telegram bot client.
+  #    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_BROKER_SOCKET (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.
+  _gateway_bundle=/opt/switchroom/telegram-plugin/dist/gateway/gateway.js
+  if [ -f "$_gateway_bundle" ] && command -v bun >/dev/null 2>&1; then
+    _switchroom_supervise gateway /var/log/switchroom/gateway-supervisor.log \
+      bun "$_gateway_bundle" &
+  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.
+  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}}" &
+  fi
+
+  # 3) agent-scheduler (cron-fold-in cutover, default-on since Phase 4).
+  #    Long-running. The singleton switchroom-cron container is gone;
+  #    every agent runs cron in-container as a sibling of the gateway,
+  #    delivering fires through the SAME inbound path as Telegram
+  #    messages (synthesized turns tagged meta.source="cron"). The
+  #    bundle connects to the gateway socket above, so the gateway
+  #    must be up before fires can deliver; the supervisor's respawn
+  #    loop handles the early-boot race naturally.
+  #
+  #    Kill switch: an operator can opt OUT by setting
+  #    SWITCHROOM_INLINE_SCHEDULER=0 at the container level (compose
+  #    env or `docker run -e ...`). Default behaviour is enabled —
+  #    we used to gate on `=1`, the gate is now `!=0`.
+  if [ "$SWITCHROOM_INLINE_SCHEDULER" != "0" ] \
+     && [ -f /opt/switchroom/agent-scheduler/index.js ] \
+     && command -v bun >/dev/null 2>&1; then
+    _switchroom_supervise agent-scheduler /var/log/switchroom/agent-scheduler.log \
+      bun /opt/switchroom/agent-scheduler/index.js &
+  fi
+
+  export SWITCHROOM_DOCKER_TMUX_INNER=1
+  exec tmux -L "switchroom-{{name}}" \
+    new-session -A -s "{{name}}" -x 400 -y 50 \
+    bash -l "$0"
+fi
+
+{{#if hostHomeQ}}
+# Host ~/.switchroom symlink (#910). Container HOME=/state/agent/home,
+# but operator yaml prompts (cron, hooks, ad-hoc tool calls) widely use
+# ~/.switchroom/skills/..., ~/.switchroom/credentials/..., and
+# ~/.switchroom/agents/<self>/... — those expand against $HOME inside the
+# container. Bind mounts land at the host's absolute path
+# (/home/<user>/.switchroom/...), not under HOME. Symlinking
+# $HOME/.switchroom → <host-home>/.switchroom makes tilde paths resolve
+# to the bind-mounted location. Idempotent: ln -sfn refreshes the link
+# without following an existing symlink. Guard refuses to clobber a
+# real directory at $HOME/.switchroom.
+if [ ! -e "$HOME/.switchroom" ] || [ -L "$HOME/.switchroom" ]; then
+  ln -sfn {{{hostHomeQ}}}/.switchroom "$HOME/.switchroom" 2>/dev/null || true
+fi
+{{/if}}
+
 export NVM_DIR="$HOME/.nvm"
 [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
 export PATH="$HOME/.bun/bin:$PATH"
+# Layer 1 persistent-HOME PATH additions: user-space binary install dirs.
+# `pip install --user`, `npm install -g` (with NPM_CONFIG_PREFIX set in
+# compose.ts), `cargo install --root $HOME`, and manual `~/bin` drops
+# all land in these paths; survival across container restart is via the
+# /state/agent bind mount (HOME=/state/agent/home).
+export PATH="$HOME/.local/bin:$HOME/bin:$HOME/.npm-global/bin:$PATH"
 export CLAUDE_CONFIG_DIR="{{agentDir}}/.claude"
 unset CLAUDE_CODE_OAUTH_TOKEN
 if [ -f "$CLAUDE_CONFIG_DIR/.oauth-token" ]; then

package/profiles/_shared/telegram-style.md.hbs

@@ -73,7 +73,7 @@ If `SWITCHROOM_PENDING_TURN` is unset or empty, do nothing special — the previ
 
 **When stickers / GIFs land badly**: in lieu of an actual answer, decorating routine acknowledgements ("got it 👍 [+sticker]"), peppering a long thread, or any time the user is task-focused. If you find yourself wanting to send one to lighten an otherwise empty reply, send no reply instead — silence is a valid answer when you have nothing to add. Two stickers in a row is always wrong.
 
-**`!` interrupt marker.** The gateway treats a Telegram message starting with `!` (single bang, not `!!` or `!!!`) as a deliberate interrupt: SIGINT to the active turn, strip the `!`, deliver the rest as a fresh turn. Under tmux-default, the SIGINT is delivered via `tmux send-keys C-c` to whatever has focus in the agent's pane (typically the claude REPL, but if claude has spawned a child Bash for a tool call, the child gets the C-c — which usually matches operator intent); a `systemctl kill --signal=INT` cgroup-wide fallback fires only if send-keys fails. If the user sends `! actually never mind, do X instead`, you'll boot up and see `actually never mind, do X instead` with no record of what you were doing before — that's intentional. **If a user asks how to stop you mid-turn, tell them: "Start your message with `!` — it interrupts whatever I'm doing and treats the rest as a fresh request."** Doubled `!!` (typo / emphasis) reaches you verbatim. Empty `!` gets a "Send your replacement instruction now" reply from the gateway and never reaches you. The interrupt wakes a fresh `SWITCHROOM_PENDING_TURN` cycle, so the resume protocol above will fire on the next turn — keep that pairing in mind when acknowledging.
+**`!` interrupt marker.** The gateway treats a Telegram message starting with `!` (single bang, not `!!` or `!!!`) as a deliberate interrupt: SIGINT to the active turn, strip the `!`, deliver the rest as a fresh turn. Under tmux-default, the SIGINT is delivered via `tmux send-keys C-c` to whatever has focus in the agent's pane (typically the claude REPL, but if claude has spawned a child Bash for a tool call, the child gets the C-c — which usually matches operator intent); a cgroup-wide kill fallback (legacy systemd: `systemctl kill --signal=INT`) fires only if send-keys fails. If the user sends `! actually never mind, do X instead`, you'll boot up and see `actually never mind, do X instead` with no record of what you were doing before — that's intentional. **If a user asks how to stop you mid-turn, tell them: "Start your message with `!` — it interrupts whatever I'm doing and treats the rest as a fresh request."** Doubled `!!` (typo / emphasis) reaches you verbatim. Empty `!` gets a "Send your replacement instruction now" reply from the gateway and never reaches you. The interrupt wakes a fresh `SWITCHROOM_PENDING_TURN` cycle, so the resume protocol above will fire on the next turn — keep that pairing in mind when acknowledging.
 
 **Wake audit — every fresh boot, check what you owe before responding.** When `start.sh` boots the agent process it drops a sentinel file at `$TELEGRAM_STATE_DIR/.wake-audit-pending`. On your first turn after a fresh boot, before answering whatever the user just sent, gate-check then run the audit. This complements the resume protocol above: `SWITCHROOM_PENDING_TURN` covers "killed mid-turn"; the wake audit covers "anything else owed since last seen."
 
@@ -123,8 +123,8 @@ The marker's mtime defines "audit complete for this conversation up to now" —
 **"Why did you restart?" — read the audit trail, don't guess.** The `SWITCHROOM_PENDING_*` env vars are one-shot (cleared by start.sh on first read), so by the time a user asks "why did you restart?" they're long gone. Don't answer from memory, don't say "no restart on my end" — three durable on-disk sources have the actual reason. Check them in this order:
 
 1. **`$TELEGRAM_STATE_DIR/clean-shutdown.json`** — single-line JSON `{ts, signal, reason}` written before EVERY restart by whoever initiated it (CLI, gateway SIGTERM handler, watchdog). Fastest answer for "what was THIS boot's reason." Example: `cat "$TELEGRAM_STATE_DIR/clean-shutdown.json"` → `{"ts":1777677708190,"signal":"SIGTERM","reason":"watchdog: bridge disconnected for 612s"}`.
-2. **`journalctl --user -t switchroom-watchdog --since "2 hours ago"`** — the watchdog's audit log. Every action is one line tagged `[restart] / [skip] / [detect] / [error]` with full forensic context: `agent=NAME reason=KIND threshold=Ns observed=Ns pid=… state=… cpu=…% rss_mb=… jsonl_age=Ns tasks_age=Ns`. Use this to explain WHY the watchdog acted (or didn't) and what it observed.
-3. **`journalctl --user -u switchroom-$SWITCHROOM_AGENT_NAME --since "2 hours ago"`** — the agent unit's systemd-level history. Confirms restart timestamps, exit codes, and any `Restart=on-failure` auto-restarts that bypassed the CLI/watchdog paths.
+2. **Container/unit history** — under v0.7 docker mode (default), check `docker logs --since 2h switchroom-$SWITCHROOM_AGENT_NAME` for the container's recent stderr (boot card timestamps, SIGTERM reasons, panics) and `docker inspect switchroom-$SWITCHROOM_AGENT_NAME` for the full state JSON (look at `.State.StartedAt` for the last start time and `.State.RestartCount` for cumulative restarts). Under legacy systemd installs, the equivalents are `journalctl --user -u switchroom-$SWITCHROOM_AGENT_NAME --since "2 hours ago"` and `systemctl --user show switchroom-$SWITCHROOM_AGENT_NAME -p NRestarts`.
+3. **Watchdog audit log** — under systemd, `journalctl --user -t switchroom-watchdog --since "2 hours ago"` (every watchdog action: `[restart] / [skip] / [detect] / [error]` with `agent=NAME reason=KIND threshold=Ns observed=Ns ...`). Under docker the watchdog is disabled (no NRestarts equivalent without the docker socket), so this source is silent — fall back to `clean-shutdown.json` plus the container logs above.
 
 Quote the reason field verbatim when answering — don't paraphrase. If `clean-shutdown.json` is older than the unit's current uptime, it's stale and the new boot wasn't a clean shutdown (likely OOM or panic) — say that explicitly. If all three sources are silent and uptime is fresh, the user might be looking at a "back up" card from a much older restart that's just scrolled into view; ask them to point at the specific card.
 

package/profiles/default/CLAUDE.md

@@ -95,7 +95,7 @@ If `SWITCHROOM_PENDING_TURN` is unset or empty, do nothing special — the previ
 
 **When stickers / GIFs land badly**: in lieu of an actual answer, decorating routine acknowledgements ("got it 👍 [+sticker]"), peppering a long thread, or any time the user is task-focused. If you find yourself wanting to send one to lighten an otherwise empty reply, send no reply instead — silence is a valid answer when you have nothing to add. Two stickers in a row is always wrong.
 
-**`!` interrupt marker.** The gateway treats a Telegram message starting with `!` (single bang, not `!!` or `!!!`) as a deliberate interrupt: SIGINT to the active turn, strip the `!`, deliver the rest as a fresh turn. Under tmux-default, the SIGINT is delivered via `tmux send-keys C-c` to whatever has focus in the agent's pane (typically the claude REPL, but if claude has spawned a child Bash for a tool call, the child gets the C-c — which usually matches operator intent); a `systemctl kill --signal=INT` cgroup-wide fallback fires only if send-keys fails. If the user sends `! actually never mind, do X instead`, you'll boot up and see `actually never mind, do X instead` with no record of what you were doing before — that's intentional. **If a user asks how to stop you mid-turn, tell them: "Start your message with `!` — it interrupts whatever I'm doing and treats the rest as a fresh request."** Doubled `!!` (typo / emphasis) reaches you verbatim. Empty `!` gets a "Send your replacement instruction now" reply from the gateway and never reaches you. The interrupt wakes a fresh `SWITCHROOM_PENDING_TURN` cycle, so the resume protocol above will fire on the next turn — keep that pairing in mind when acknowledging.
+**`!` interrupt marker.** The gateway treats a Telegram message starting with `!` (single bang, not `!!` or `!!!`) as a deliberate interrupt: SIGINT to the active turn, strip the `!`, deliver the rest as a fresh turn. Under tmux-default, the SIGINT is delivered via `tmux send-keys C-c` to whatever has focus in the agent's pane (typically the claude REPL, but if claude has spawned a child Bash for a tool call, the child gets the C-c — which usually matches operator intent); a cgroup-wide kill fallback (legacy systemd: `systemctl kill --signal=INT`) fires only if send-keys fails. If the user sends `! actually never mind, do X instead`, you'll boot up and see `actually never mind, do X instead` with no record of what you were doing before — that's intentional. **If a user asks how to stop you mid-turn, tell them: "Start your message with `!` — it interrupts whatever I'm doing and treats the rest as a fresh request."** Doubled `!!` (typo / emphasis) reaches you verbatim. Empty `!` gets a "Send your replacement instruction now" reply from the gateway and never reaches you. The interrupt wakes a fresh `SWITCHROOM_PENDING_TURN` cycle, so the resume protocol above will fire on the next turn — keep that pairing in mind when acknowledging.
 
 **Wake audit — every fresh boot, check what you owe before responding.** When `start.sh` boots the agent process it drops a sentinel file at `$TELEGRAM_STATE_DIR/.wake-audit-pending`. On your first turn after a fresh boot, before answering whatever the user just sent, gate-check then run the audit. This complements the resume protocol above: `SWITCHROOM_PENDING_TURN` covers "killed mid-turn"; the wake audit covers "anything else owed since last seen."
 
@@ -145,8 +145,8 @@ The marker's mtime defines "audit complete for this conversation up to now" —
 **"Why did you restart?" — read the audit trail, don't guess.** The `SWITCHROOM_PENDING_*` env vars are one-shot (cleared by start.sh on first read), so by the time a user asks "why did you restart?" they're long gone. Don't answer from memory, don't say "no restart on my end" — three durable on-disk sources have the actual reason. Check them in this order:
 
 1. **`$TELEGRAM_STATE_DIR/clean-shutdown.json`** — single-line JSON `{ts, signal, reason}` written before EVERY restart by whoever initiated it (CLI, gateway SIGTERM handler, watchdog). Fastest answer for "what was THIS boot's reason." Example: `cat "$TELEGRAM_STATE_DIR/clean-shutdown.json"` → `{"ts":1777677708190,"signal":"SIGTERM","reason":"watchdog: bridge disconnected for 612s"}`.
-2. **`journalctl --user -t switchroom-watchdog --since "2 hours ago"`** — the watchdog's audit log. Every action is one line tagged `[restart] / [skip] / [detect] / [error]` with full forensic context: `agent=NAME reason=KIND threshold=Ns observed=Ns pid=… state=… cpu=…% rss_mb=… jsonl_age=Ns tasks_age=Ns`. Use this to explain WHY the watchdog acted (or didn't) and what it observed.
-3. **`journalctl --user -u switchroom-$SWITCHROOM_AGENT_NAME --since "2 hours ago"`** — the agent unit's systemd-level history. Confirms restart timestamps, exit codes, and any `Restart=on-failure` auto-restarts that bypassed the CLI/watchdog paths.
+2. **Container/unit history** — under v0.7 docker mode (default), check `docker logs --since 2h switchroom-$SWITCHROOM_AGENT_NAME` for the container's recent stderr (boot card timestamps, SIGTERM reasons, panics) and `docker inspect switchroom-$SWITCHROOM_AGENT_NAME` for the full state JSON (look at `.State.StartedAt` for the last start time and `.State.RestartCount` for cumulative restarts). Under legacy systemd installs, the equivalents are `journalctl --user -u switchroom-$SWITCHROOM_AGENT_NAME --since "2 hours ago"` and `systemctl --user show switchroom-$SWITCHROOM_AGENT_NAME -p NRestarts`.
+3. **Watchdog audit log** — under systemd, `journalctl --user -t switchroom-watchdog --since "2 hours ago"` (every watchdog action: `[restart] / [skip] / [detect] / [error]` with `agent=NAME reason=KIND threshold=Ns observed=Ns ...`). Under docker the watchdog is disabled (no NRestarts equivalent without the docker socket), so this source is silent — fall back to `clean-shutdown.json` plus the container logs above.
 
 Quote the reason field verbatim when answering — don't paraphrase. If `clean-shutdown.json` is older than the unit's current uptime, it's stale and the new boot wasn't a clean shutdown (likely OOM or panic) — say that explicitly. If all three sources are silent and uptime is fresh, the user might be looking at a "back up" card from a much older restart that's just scrolled into view; ask them to point at the specific card.
 

package/profiles/default/CLAUDE.md.hbs

@@ -107,7 +107,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 via systemd timers — they don't use your session or context. They fire on their own schedule (typically Sonnet for cost efficiency) and send output directly to Telegram.
+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 don't need to manage them — they're OS-level. 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 run automatically and are configured in switchroom.yaml under `schedule:`.
 {{/if}}

package/profiles/default/workspace/CLAUDE.md.hbs

@@ -116,6 +116,15 @@ When operating in a group chat (more than one person in the room):
 Quality > quantity. If you wouldn't send it in a real group chat with
 friends, don't send it.
 
+## Effort estimates
+
+When estimating implementation, research, or refactor work, estimate in
+**agent minutes** — wall-clock time for a current-generation Claude
+agent (the actual worker, not a human) to complete the work end-to-end
+including tests. A "12 dev hours" plan is the wrong unit; "~25 agent
+minutes" is the right one. Reserve human-time estimates only for work
+that explicitly requires the user's review or input.
+
 ## Scope
 
 {{#if agentConfig.purpose}}

package/skills/docx/VENDORED.md

@@ -7,7 +7,7 @@ Pinned to commit: 5128e1865d670f5d6c9cef000e6dfc4e951fb5b9
 ## Why vendored
 
 Switchroom ships this skill as a built-in default so every agent gets it
-on scaffold (and on `switchroom update` for pre-existing agents).
+on scaffold (and on `switchroom apply` for pre-existing agents).
 Vendoring keeps the skill content available offline and version-pinned.
 
 Opt out with:

package/skills/mcp-builder/VENDORED.md

@@ -7,7 +7,7 @@ Pinned to commit: 5128e1865d670f5d6c9cef000e6dfc4e951fb5b9
 ## Why vendored
 
 Switchroom ships this skill as a built-in default so every agent gets it
-on scaffold (and on `switchroom update` for pre-existing agents).
+on scaffold (and on `switchroom apply` for pre-existing agents).
 Vendoring keeps the skill content available offline and version-pinned.
 
 Opt out with:

package/skills/pdf/VENDORED.md

@@ -7,7 +7,7 @@ Pinned to commit: 5128e1865d670f5d6c9cef000e6dfc4e951fb5b9
 ## Why vendored
 
 Switchroom ships this skill as a built-in default so every agent gets it
-on scaffold (and on `switchroom update` for pre-existing agents).
+on scaffold (and on `switchroom apply` for pre-existing agents).
 Vendoring keeps the skill content available offline and version-pinned.
 
 Opt out with:

package/skills/pptx/VENDORED.md

@@ -7,7 +7,7 @@ Pinned to commit: 5128e1865d670f5d6c9cef000e6dfc4e951fb5b9
 ## Why vendored
 
 Switchroom ships this skill as a built-in default so every agent gets it
-on scaffold (and on `switchroom update` for pre-existing agents).
+on scaffold (and on `switchroom apply` for pre-existing agents).
 Vendoring keeps the skill content available offline and version-pinned.
 
 Opt out with:

package/skills/skill-creator/VENDORED.md

@@ -7,7 +7,7 @@ Pinned to commit: 5128e1865d670f5d6c9cef000e6dfc4e951fb5b9
 ## Why vendored
 
 Switchroom ships this skill as a built-in default so every agent gets it
-on scaffold (and on `switchroom update` for pre-existing agents).
+on scaffold (and on `switchroom apply` for pre-existing agents).
 Vendoring keeps the skill content available offline and version-pinned.
 
 Opt out with:

package/skills/switchroom-architecture/SKILL.md

@@ -12,7 +12,7 @@ Switchroom is a multi-agent orchestrator built on Claude Code. It manages multip
 
 **One `switchroom.yaml` to rule them all.** All agents are configured from a single file using a three-layer cascade. See [cascade.md](cascade.md) for full merge semantics.
 
-**Agents as systemd services.** Each agent runs as a long-lived `claude` process managed by a systemd user service (`switchroom-<name>.service`). The `start.sh` script sets environment variables and execs into `claude`. Claude Code handles session persistence and tool execution.
+**Agents as Docker containers.** Each agent runs as a long-lived `claude` process inside its own container (`switchroom-<name>`), supervised by Docker Compose with `restart: unless-stopped` and a healthcheck. The `start.sh` script sets environment variables and execs into `claude`. Claude Code handles session persistence and tool execution.
 
 **Telegram as the primary interface.** The `switchroom-telegram` MCP plugin connects Claude Code to Telegram, providing 10 tools for message handling. See [telegram.md](telegram.md) for details.
 
@@ -46,12 +46,13 @@ Switchroom is a multi-agent orchestrator built on Claude Code. It manages multip
 ## Lifecycle
 
 1. `switchroom agent create <name>` — scaffold agent from switchroom.yaml
-2. `systemctl --user start switchroom-<name>` — start the process
-3. Claude Code boots, loads CLAUDE.md + skills + .mcp.json
-4. MCP servers connect (Hindsight, switchroom-telegram, others)
-5. Telegram plugin polls for messages
-6. User sends message → plugin fires `UserPromptSubmit` hook → Claude responds
-7. `switchroom agent reconcile <name>` — re-apply switchroom.yaml (no CLAUDE.md touch)
+2. `switchroom apply` — write `~/.switchroom/compose/docker-compose.yml`
+3. `docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d` — start the container
+4. Claude Code boots, loads CLAUDE.md + skills + .mcp.json
+5. MCP servers connect (Hindsight, switchroom-telegram, others)
+6. Telegram plugin polls for messages
+7. User sends message → plugin fires `UserPromptSubmit` hook → Claude responds
+8. `switchroom agent reconcile <name>` — re-apply switchroom.yaml (no CLAUDE.md touch)
 
 ## Deep dives
 

package/skills/switchroom-cli/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: switchroom-cli
 description: "Run switchroom CLI operations on existing agents: logs, update, restart, version, config inspection, scheduled tasks, and Telegram plugin reference. Use when the user wants to: show logs (\"logs\", \"what happened\", \"check the journal\", \"why did it crash\"); update agents (\"update\", \"pull latest\", \"get new code\", \"upgrade\"); restart agents (\"restart\", \"reboot\", \"bounce\", \"kick\", \"it's stuck\"); check what's running (\"version\", \"what sha\", \"are agents up\", \"health summary\"); apply config changes (\"apply\", \"sync my config\", \"I just edited switchroom.yaml\"); inspect an agent's effective config (\"what model is X using\", \"how is <agent> configured\", \"show the cascade\"); list scheduled tasks (\"cron\", \"timers\", \"what runs automatically\", \"scheduled tasks\"); or ask about Telegram-plugin features (\"what MCP tools does the bot have\", \"how does reply work\"). Do NOT use for adding/removing agents (switchroom-manage), bootstrapping switchroom from scratch (switchroom-install), or \"something is broken\" diagnostics (switchroom-health).
-allowed-tools: Bash(switchroom *) Bash(systemctl --user *) Bash(journalctl *)
+allowed-tools: Bash(switchroom *) Bash(docker *) Bash(docker compose *)
 ---
 
 # Switchroom CLI operations
@@ -9,7 +9,7 @@ allowed-tools: Bash(switchroom *) Bash(systemctl --user *) Bash(journalctl *)
 This skill is the reference for running `switchroom` CLI commands against existing agents. Each section below is triggered by a distinct user intent — jump to the relevant one rather than walking top-to-bottom.
 
 **Three commands to know:**
-- `switchroom update` — picks up new code (pull, rebuild, reconcile, restart)
+- `switchroom apply` — reconcile every agent + (re)write `~/.switchroom/compose/docker-compose.yml`. Bring the fleet up afterwards with `docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d`. (Replaces the v0.6 `switchroom update` flow.)
 - `switchroom restart [agent]` — bounces a stuck or wedged agent
 - `switchroom version` — shows what's running (versions + health summary)
 
@@ -31,12 +31,12 @@ switchroom agent list
 
 ### Step 2 — Tail the logs
 
-Default is the last 20 lines. User can specify a number. Use the CLI if available; fall back to `journalctl` when it's not:
+Default is the last 20 lines. User can specify a number. Use the CLI if available; fall back to `docker compose logs` when it's not:
 
 ```bash
 switchroom agent logs <name> [--lines 50]
 # or, when switchroom CLI isn't reachable:
-journalctl --user -u switchroom-<name>.service -n 50 --no-pager
+docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml logs --tail 50 switchroom-<name>
 ```
 
 ### Step 3 — Present output
@@ -47,21 +47,26 @@ Include the last ~20 lines verbatim, then summarise what you see (crash, stall,
 
 ## Update — "update", "pull latest", "get new code", "upgrade"
 
-Pull the latest switchroom source, rebuild the CLI binary, reconcile all agents, and restart everything.
+Pull the latest switchroom source, then re-apply config and bring the fleet back up via docker compose.
 
 ```bash
-switchroom update
+cd ~/code/switchroom
+git pull
+bun install
+bun run build
+switchroom apply
+docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml pull
+docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d
 ```
 
-This is the single command for "running the latest code". It:
-1. `git pull` the switchroom repo
-2. Reinstalls deps if package.json changed
-3. Regenerates systemd units
-4. Reconciles all agent config from switchroom.yaml
-5. Restarts all agents that need it
-6. Prints a one-line health summary when done
+`switchroom apply` reconciles every agent declared in `switchroom.yaml`
+(scaffolding any missing workspaces, refreshing bootstrap files), then
+writes `~/.switchroom/compose/docker-compose.yml`. The CLI deliberately
+does not run `docker` for you — the operator owns the bring-up.
 
-**Idempotent**: running twice = first does work, second is a fast no-op.
+The v0.6 `switchroom update` verb is removed in v0.7+; calling it now
+prints this upgrade hint and exits 1. The shim is slated for full removal
+in v0.8.
 
 ---
 
@@ -230,8 +235,11 @@ 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:
+
 ```bash
-systemctl --user list-timers --all | grep switchroom
+docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml logs switchroom-<agent>-scheduler --tail 100
 ```
 
 ### Step 2 — Show declared schedule entries

package/skills/switchroom-health/SKILL.md

@@ -31,11 +31,11 @@ switchroom auth status 2>/dev/null || echo "FAIL: auth check failed"
 # and per-account health (healthy / quota-exhausted / expired / missing-refresh-token).
 switchroom auth account list 2>/dev/null || echo "INFO: no Anthropic accounts configured (legacy per-agent slot model in use)"
 
-# Check systemd units
-systemctl --user list-units "switchroom-*" --no-pager 2>/dev/null || echo "no switchroom systemd units"
+# Check docker-compose service health
+docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml ps 2>/dev/null || echo "no switchroom docker fleet"
 
-# Check for failed units
-systemctl --user list-units "switchroom-*" --state=failed --no-pager 2>/dev/null
+# Check for unhealthy or exited containers
+docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml ps --status exited --status unhealthy 2>/dev/null
 
 # Check MCP config exists for each agent
 for dir in ~/.switchroom/agents/*/; do
@@ -78,7 +78,7 @@ For each check, report:
 
 Group findings by category:
 1. **CLI & Auth** — switchroom installed, authenticated
-2. **Systemd units** — services running, no failed units
+2. **Docker fleet** — containers running, no unhealthy/exited services
 3. **Agent files** — start.sh, .mcp.json, settings.json present
 4. **Bot tokens** — Telegram credentials resolved
 5. **Memory backend** — Hindsight reachable
@@ -93,8 +93,8 @@ For common failures, give the exact fix:
 | Per-agent auth expired (slot model) | `switchroom auth login <agent>` |
 | Account expired (new model — `auth account list` shows red ✗) | `switchroom auth refresh-accounts` (one tick); if no refresh-token, the account needs re-adding |
 | Account quota-exhausted (yellow ⊘ in `auth account list`) | Auto-fallback handles it if the agent has multiple accounts; otherwise wait for the reset window or `switchroom auth enable <other-account> <agent>` |
-| Unit failed | `systemctl --user reset-failed switchroom-<name>`, then restart |
-| Missing .mcp.json | `switchroom update` (full reconcile + restart) or `switchroom agent reconcile <name>` (targeted) |
+| Container unhealthy | `docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml restart switchroom-<name>` |
+| Missing .mcp.json | `switchroom apply` (full reconcile + rewrite compose; bring up via `docker compose ... up -d`) or `switchroom agent reconcile <name>` (targeted) |
 | Bot token unresolved | Check vault: `switchroom vault list` |
 | Memory unreachable | Check Hindsight MCP server is running |
 

package/skills/switchroom-install/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: switchroom-install
-description: Install switchroom and its dependencies (bun, node, docker, tmux, claude CLI) on a fresh machine. Use for onboarding and first-time setup — when the user says 'install switchroom on this machine', 'set up switchroom for the first time', 'bootstrap switchroom from scratch', 'get switchroom running', 'how do I get started with switchroom', "I'm new to switchroom, where do I begin", or asks about switchroom dependencies or prerequisites. This is the onboarding entry point, not for managing existing agents.
+description: Install switchroom and its dependencies (docker, claude CLI, switchroom binary) on a fresh machine. Use for onboarding and first-time setup — when the user says 'install switchroom on this machine', 'set up switchroom for the first time', 'bootstrap switchroom from scratch', 'get switchroom running', 'how do I get started with switchroom', "I'm new to switchroom, where do I begin", or asks about switchroom dependencies or prerequisites. This is the onboarding entry point, not for managing existing agents.
 ---
 
 # Install Switchroom
 
 When the user asks to install, set up, bootstrap, or get started with switchroom — or when they're new to switchroom and want to know where to begin — walk them through this flow. Switchroom turns a Linux server + their Claude Pro/Max subscription into always-on Claude Code agents reachable from Telegram.
 
-Switchroom's dependencies are: **bun** (TypeScript runtime), **node** 22+ (via nvm), **docker** (for plugins), **tmux** (for agent sessions), and the **claude** Code CLI (authenticates against Claude Pro/Max). Always enumerate these explicitly when the user asks about dependencies or prerequisites.
+Switchroom v0.7+ ships as a self-contained static binary (no host bun or node runtime required) and runs the agent fleet in Docker containers pulled from GHCR. The two host dependencies are: **docker** (engine 24+ with the compose v2 plugin) and the **claude** Code CLI (used for OAuth login against your Pro/Max subscription).
 
 ## Step 0 — Detect existing install
 
@@ -17,11 +17,11 @@ Before doing anything, check whether switchroom is already installed:
 command -v switchroom && switchroom --version 2>/dev/null
 ```
 
-If switchroom is present, tell the user it's already installed and then — regardless — run the dependency audit in Step 2 so they see the state of **bun**, **node**, **docker**, **tmux**, and **claude**. Users who ask "install switchroom and its dependencies" want to see the dependency inventory even when switchroom itself is already installed. After the audit, offer `switchroom setup` (re-run the wizard), `switchroom doctor` (diagnose), or `switchroom agent list` (see what's running). Do not reinstall switchroom itself without explicit confirmation.
+If switchroom is present, tell the user it's already installed and then — regardless — run the dependency audit in Step 2 so they see the state of **docker** and **claude**. After the audit, offer `switchroom setup` (re-run the wizard), `switchroom doctor` (diagnose), or `switchroom agent list` (see what's running). Do not reinstall switchroom itself without explicit confirmation.
 
 ## Step 1 — Verify prerequisites
 
-Switchroom requires Ubuntu 24.04 LTS (or compatible Debian-based Linux) with ≥4GB RAM. Check:
+Switchroom requires Linux with Docker (Ubuntu 24.04 LTS canonical; ≥4GB RAM):
 
 ```bash
 . /etc/os-release && echo "$PRETTY_NAME"
@@ -29,56 +29,40 @@ free -h | awk '/^Mem:/ {print $2}'
 uname -m
 ```
 
-If the user is on macOS or Windows, stop and explain: switchroom runs on Linux servers (typically a $6/mo VPS). Point them at the README's "Quick Start" — they'll want to provision a Linux box first.
+If the user is on macOS or Windows, stop and explain: switchroom's release-validated production runtime is Linux. macOS (Docker Desktop) works for development but isn't yet release-gated. Windows users need WSL2.
 
-## Step 2 — Install system dependencies
+## Step 2 — Install host dependencies
 
 Only install what's missing. Check each first:
 
 ```bash
-# System packages
-for pkg in tmux expect docker.io; do
-  dpkg -s "$pkg" >/dev/null 2>&1 || echo "MISSING: $pkg"
-done
+# Docker
+command -v docker || echo "MISSING: docker"
+docker compose version >/dev/null 2>&1 || echo "MISSING: docker compose v2"
 
-# Bun
-command -v bun || echo "MISSING: bun"
-
-# Node 22+ (via nvm)
-node -v 2>/dev/null || echo "MISSING: node"
-
-# Claude Code CLI
+# Claude Code CLI (needed for switchroom auth login)
 command -v claude || echo "MISSING: claude"
 ```
 
-For anything missing, run the corresponding install step:
+For anything missing:
 
 ```bash
-# apt packages
-sudo apt update && sudo apt install -y tmux expect docker.io
-
-# bun
-curl -fsSL https://bun.sh/install | bash
+# Docker (Ubuntu/Debian)
+sudo apt update && sudo apt install -y docker.io docker-compose-plugin
+sudo usermod -aG docker "$USER"   # log out/in or `newgrp docker` to apply
 
-# nvm + node 22
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
-source ~/.bashrc
-nvm install 22
-
-# claude code
+# Claude Code CLI (needs Node 20.11+)
 npm install -g @anthropic-ai/claude-code
-
-# docker group (user needs to log out/in or newgrp)
-sudo usermod -aG docker "$USER"
 ```
 
 **Important:** After `usermod -aG docker`, the user needs a new shell for group membership to apply. Mention this explicitly.
 
-## Step 3 — Clone and build switchroom
+## Step 3 — Install the switchroom binary
+
+The recommended path is the static-binary one-liner — auto-detects platform/arch, downloads the matching pre-built binary from the latest GitHub release, verifies its SHA256, and installs to `/usr/local/bin` (or `~/.local/bin` if not writable):
 
 ```bash
-git clone https://github.com/mekenthompson/switchroom.git ~/code/switchroom
-cd ~/code/switchroom && bun install && bun link
+curl -fsSL https://github.com/switchroom/switchroom/raw/main/install.sh | sh
 ```
 
 Verify:
@@ -87,15 +71,27 @@ Verify:
 switchroom --version
 ```
 
+(For development against a source checkout, `git clone` + `bun install` + `bun link` still works — see `docs/operators/install.md`. Don't suggest the source path for first-time users.)
+
 ## Step 4 — Run setup wizard
 
-`switchroom setup` is an interactive wizard that configures the Telegram bot token, forum chat, and first agent. **It requires a terminal the user controls** — if you're running inside an agent session, you cannot drive it yourself. Tell the user:
+`switchroom setup` is an interactive wizard that wires the operator's Telegram bot token, sets up the vault, and scaffolds a first agent. DM-only by default — no forum chat ID required up front. **It requires a terminal the user controls** — if you're running inside an agent session, you cannot drive it yourself. Tell the user:
 
 > Run `switchroom setup` in your own terminal. It'll ask for your Telegram bot token and walk you through creating your first agent. Come back when it finishes and I can verify with `switchroom doctor`.
 
-## Step 5 — Verify
+## Step 5 — Apply and bring up the fleet
+
+After `switchroom setup` completes, three commands take you from config to a running fleet:
+
+```bash
+switchroom apply
+docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml pull
+docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d --remove-orphans
+```
+
+`switchroom apply` reconciles every agent declared in `switchroom.yaml` and writes `~/.switchroom/compose/docker-compose.yml`. The CLI deliberately does not run `docker` for you — operators own the bring-up. The first `pull` fetches the 5 GHCR images (~1-2 GB total); subsequent pulls are layer-only.
 
-After `switchroom setup` completes:
+## Step 6 — Verify
 
 ```bash
 switchroom doctor
@@ -112,5 +108,6 @@ Once the first agent is up and authenticated, the user can promote that agent's
 
 - **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** install switchroom system-wide (no `sudo npm install -g switchroom`). Switchroom is a bun-linked binary from a user-owned checkout.
+- **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** 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/`).