switchroom 0.5.0

package/package.json

@@ -0,0 +1,95 @@
+{
+  "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.",
+  "type": "module",
+  "bin": {
+    "switchroom": "./dist/cli/switchroom.js"
+  },
+  "main": "./dist/cli/switchroom.js",
+  "files": [
+    "dist",
+    "profiles",
+    "skills",
+    "telegram-plugin",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "bun bin/switchroom.ts",
+    "build": "node scripts/build.mjs",
+    "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:watch": "vitest",
+    "lint": "tsc --noEmit && node scripts/check-plugin-references.mjs",
+    "lint:tsc": "tsc --noEmit",
+    "lint:plugin-references": "node scripts/check-plugin-references.mjs",
+    "prepublishOnly": "npm run build && npm run lint && npm test"
+  },
+  "dependencies": {
+    "@grammyjs/runner": "^2.0.3",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@secretlint/core": "^12.2.0",
+    "@secretlint/secretlint-rule-preset-recommend": "^12.2.0",
+    "@secretlint/types": "^12.2.0",
+    "@xterm/headless": "^6.0.0",
+    "bcryptjs": "^3.0.3",
+    "chalk": "^5.4.0",
+    "commander": "^13.1.0",
+    "grammy": "^1.21.0",
+    "handlebars": "^4.7.8",
+    "posthog-node": "^5.29.2",
+    "yaml": "^2.7.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.30.0",
+    "@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"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/switchroom/switchroom.git"
+  },
+  "homepage": "https://github.com/switchroom/switchroom#readme",
+  "bugs": {
+    "url": "https://github.com/switchroom/switchroom/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "workspaces": [
+    "telegram-plugin"
+  ],
+  "keywords": [
+    "claude-code",
+    "claude-pro",
+    "claude-max",
+    "claude-subscription",
+    "anthropic",
+    "openclaw-alternative",
+    "nanoclaw-alternative",
+    "opencode-alternative",
+    "multi-agent",
+    "telegram",
+    "telegram-bot",
+    "orchestrator",
+    "ai-agent",
+    "self-hosted",
+    "oauth",
+    "24-7"
+  ],
+  "optionalDependencies": {
+    "@rollup/rollup-win32-x64-msvc": "^4.60.1"
+  }
+}

package/profiles/_base/settings.json.hbs

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": {{{json permissionAllow}}},
+    "deny": {{{json toolsDeny}}}{{#if defaultModeAcceptEdits}},
+    "defaultMode": "acceptEdits"{{/if}}
+  },
+  "enabledPlugins": {
+    "telegram@claude-plugins-official": {{#if useSwitchroomPlugin}}false{{else}}true{{/if}}
+  }{{#if hindsightEnabled}},
+  "autoMemoryEnabled": false{{/if}}{{#if mcpServers}},
+  "mcpServers": {{{json mcpServers}}}
+  {{/if}}{{#if skipPermissionPrompt}},
+  "skipDangerousModePermissionPrompt": true
+  {{/if}}
+}

package/profiles/_base/start.sh.hbs

@@ -0,0 +1,383 @@
+#!/bin/bash
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+export PATH="$HOME/.bun/bin:$PATH"
+export CLAUDE_CONFIG_DIR="{{agentDir}}/.claude"
+unset CLAUDE_CODE_OAUTH_TOKEN
+if [ -f "$CLAUDE_CONFIG_DIR/.oauth-token" ]; then
+  export CLAUDE_CODE_OAUTH_TOKEN="$(tr -d '\r\n' < "$CLAUDE_CONFIG_DIR/.oauth-token")"
+fi
+export TELEGRAM_STATE_DIR="{{agentDir}}/telegram"
+# SWITCHROOM_AGENT_NAME is the canonical "which agent am I" identifier the
+# telegram-plugin reads to detect self-restart commands. We can't rely on
+# basename(process.cwd()) inside the plugin because Claude Code spawns
+# MCP servers with cwd = $HOME regardless of the parent's cwd.
+export SWITCHROOM_AGENT_NAME="{{name}}"
+{{#if switchroomConfigPathQ}}
+# SWITCHROOM_CONFIG lets the agent's own shell tool invoke `switchroom`
+# without passing `--config` every time. The telegram-plugin MCP server
+# already gets this via .mcp.json env, but the Claude Code process
+# doesn't inherit that — so without this export, `switchroom auth status`
+# from Bash inside the agent fails with "No switchroom.yaml found".
+export SWITCHROOM_CONFIG={{{switchroomConfigPathQ}}}
+{{/if}}
+{{#if hindsightEnabled}}
+# Hindsight memory plugin (vendored at .claude/plugins/hindsight-memory/).
+# Reads env vars at hook startup; settings.json autoMemoryEnabled: false
+# disables Claude Code's built-in file-based auto-memory so we don't run
+# two memory systems against each other.
+# Values are POSIX-single-quoted in scaffold.ts for shell safety.
+export HINDSIGHT_API_URL={{{hindsightApiBaseUrlQ}}}
+export HINDSIGHT_BANK_ID={{{hindsightBankIdQ}}}
+export HINDSIGHT_AUTO_RECALL=true
+export HINDSIGHT_AUTO_RETAIN=true
+export HINDSIGHT_AGENT_NAME="{{name}}"
+{{#if (isNumber hindsightRecallMaxMemories)}}
+# Cap on memories injected per turn (memory.recall.max_memories cascade).
+# Plugin's settings.json default is 12; export only when the operator
+# overrode it via switchroom.yaml. 0 disables the cap entirely.
+export HINDSIGHT_RECALL_MAX_MEMORIES={{hindsightRecallMaxMemories}}
+{{/if}}
+# Per-session recall cache (#424 phase 4.1). Identical (prompt, bank)
+# within a session reuses the prior recall result instead of round-
+# tripping to Hindsight. Defaults to 600s (10 min); operators can
+# override via memory.recall.cache_ttl_secs in switchroom.yaml.
+# Setting it to 0 disables caching for that agent.
+{{#if (isNumber hindsightRecallCacheTtlSecs)}}
+export HINDSIGHT_RECALL_CACHE_TTL_SECS={{hindsightRecallCacheTtlSecs}}
+{{else}}
+export HINDSIGHT_RECALL_CACHE_TTL_SECS=600
+{{/if}}
+# Lexical-overlap relevance gate (#475). Drops memories whose Jaccard
+# overlap with the user's query is below this threshold (range 0.0–1.0).
+# Plugin default is 0.0 (gate disabled); export only when the operator
+# overrode it via memory.recall.min_overlap in switchroom.yaml. Try
+# 0.10–0.20 to start; observe `overlap_dropped` via
+# `switchroom memory recall-log <agent>`.
+{{#if (isNumber hindsightRecallMinOverlap)}}
+export HINDSIGHT_RECALL_MIN_OVERLAP={{hindsightRecallMinOverlap}}
+{{/if}}
+# Wait for Hindsight API to be reachable before launching Claude, otherwise
+# the MCP server connection fails at startup with "1 MCP server failed".
+HINDSIGHT_WAIT=0
+while [ $HINDSIGHT_WAIT -lt 30 ]; do
+  if curl -sf -o /dev/null --max-time 2 {{{hindsightApiBaseUrlQ}}}/mcp/; then
+    break
+  fi
+  sleep 1
+  HINDSIGHT_WAIT=$((HINDSIGHT_WAIT + 1))
+done
+{{/if}}
+{{#if userEnvQuoted}}
+# User-declared env vars from switchroom.yaml (agent + defaults merged).
+# Values are POSIX-single-quoted in scaffold.ts so arbitrary bytes
+# (including &, $, backtick, newline, embedded quotes) survive shell
+# parsing. Triple braces skip Handlebars HTML-escape of the quoted form.
+{{#each userEnvQuoted}}export {{@key}}={{{this}}}
+{{/each}}
+{{/if}}
+cd "{{agentDir}}"
+
+# Portable stat wrappers. Switchroom runs on Linux in production (GNU stat)
+# but developers sometimes run `switchroom agent start` ad-hoc on macOS
+# (BSD stat). Detect once and route through helpers.
+if stat -c %s "$0" >/dev/null 2>&1; then
+  _stat_size()  { stat -c %s "$1" 2>/dev/null || echo 0; }
+  _stat_mtime() { stat -c %Y "$1" 2>/dev/null || echo 0; }
+else
+  _stat_size()  { stat -f %z "$1" 2>/dev/null || echo 0; }
+  _stat_mtime() { stat -f %m "$1" 2>/dev/null || echo 0; }
+fi
+
+# Portable most-recent JSONL transcript lookup. `find -printf` is a GNU
+# extension (unsupported on BSD/macOS), and unquoted globs like
+# `ls -t *.jsonl` fall through when empty. Instead, iterate `find`
+# output and use the portable _stat_mtime helper above to order by mtime.
+# Each switchroom agent pins CLAUDE_CONFIG_DIR={{agentDir}}/.claude and
+# cwd={{agentDir}}, so there's one project dir per agent in practice —
+# the newest-across-project-dirs match is what `--continue` will resume.
+_find_latest_jsonl() {
+  local dir="$1"
+  [ -d "$dir" ] || return 0
+  find "$dir" -type f -name '*.jsonl' 2>/dev/null | while IFS= read -r f; do
+    printf '%s %s\n' "$(_stat_mtime "$f")" "$f"
+  done | sort -nr | head -1 | cut -d' ' -f2-
+}
+
+# Session resume policy. The mode is set at scaffold time from
+# session_continuity.resume_mode (default 'handoff' as of #362). Effective
+# behaviors:
+#
+#   handoff (default): never pass --continue. Claude starts fresh every
+#     restart and reads a briefing assembled from recent Telegram messages,
+#     Hindsight recall, and today's daily memory file. Prevents stale MCP
+#     servers / settings from being carried over across restarts.
+#   auto: if the latest JSONL transcript under
+#     $CLAUDE_CONFIG_DIR/projects/ is smaller than
+#     SWITCHROOM_RESUME_MAX_BYTES and newer than 7 days, pass
+#     --continue. Otherwise start fresh and let the handoff briefing
+#     inject a summary.
+#   continue: always pass --continue. Flaky for large transcripts;
+#     use only if you know your sessions stay small.
+#   none: never resume. Start completely fresh every launch, no briefing.
+#
+# In every mode, Hindsight auto-recall still surfaces long-term memories
+# on each UserPromptSubmit so recent context isn't lost.
+SWITCHROOM_RESUME_MODE="{{#if resumeMode}}{{{resumeMode}}}{{else}}handoff{{/if}}"
+SWITCHROOM_RESUME_MAX_BYTES="{{#if resumeMaxBytes}}{{{resumeMaxBytes}}}{{else}}2000000{{/if}}"
+{{#if sessionMaxIdleSecs}}# When session.max_idle is configured, auto-mode resume uses it as the
+# freshness window instead of the 7-day default. Lets chat-cadence
+# agents (e.g. health-coach) demand a fresher session — see #218.
+SWITCHROOM_SESSION_MAX_IDLE_SECS="{{{sessionMaxIdleSecs}}}"
+{{/if}}CONTINUE_FLAG=""
+
+{{#if resumeModeHasContinuePath}}_RESUME_LATEST_JSONL="$(_find_latest_jsonl "$CLAUDE_CONFIG_DIR/projects")"
+case "$SWITCHROOM_RESUME_MODE" in
+  continue)
+    if [ -n "$_RESUME_LATEST_JSONL" ]; then
+      CONTINUE_FLAG="--continue"
+    fi
+    ;;
+  auto)
+    if [ -n "$_RESUME_LATEST_JSONL" ]; then
+      _RESUME_SIZE="$(_stat_size "$_RESUME_LATEST_JSONL")"
+      _RESUME_MTIME="$(_stat_mtime "$_RESUME_LATEST_JSONL")"
+      _RESUME_AGE=$(( $(date +%s) - _RESUME_MTIME ))
+      _RESUME_MAX_AGE="${SWITCHROOM_SESSION_MAX_IDLE_SECS:-604800}"
+      if [ "$_RESUME_SIZE" -gt 0 ] && [ "$_RESUME_SIZE" -lt "$SWITCHROOM_RESUME_MAX_BYTES" ] && [ "$_RESUME_AGE" -lt "$_RESUME_MAX_AGE" ]; then
+        CONTINUE_FLAG="--continue"
+      fi
+    fi
+    ;;
+  handoff|none)
+    : # CONTINUE_FLAG stays empty
+    ;;
+  *)
+    : # Unknown mode, stay empty
+    ;;
+esac
+{{/if}}
+
+# --- /reset and /new override: force fresh session ---
+#
+# When the user runs /reset or /new in Telegram the gateway writes a
+# marker file here to signal "this boot must start a fresh Claude session
+# even if --continue would otherwise resume." Without this, auto-resume
+# picks up the just-closed JSONL and the SessionStart hook never fires,
+# which means no session-greeting panel and no feeling of "fresh start"
+# from the user side. Consume the marker so it only applies to one boot.
+_FORCE_FRESH=0
+if [ -f "{{agentDir}}/.force-fresh-session" ]; then
+  CONTINUE_FLAG=""
+  rm -f "{{agentDir}}/.force-fresh-session"
+  _FORCE_FRESH=1
+fi
+
+# --- Session-mode signal for the session-greeting panel ---
+#
+# Tells the SessionStart hook (session-greeting.sh) what kind of session
+# this is so it can render an appropriate "Session" row in the panel:
+#   continue  — resumed an in-flight JSONL via --continue (tool state kept)
+#   handoff   — fresh claude session BUT a prior handoff briefing exists
+#   fresh     — fresh by /reset or /new (force-fresh marker consumed)
+#   cold      — first boot or no prior state at all
+# Epoch of most recent prior session (from JSONL mtime) is exported too so
+# the greeting can show a "2h ago" time-ago hint.
+if [ "$_FORCE_FRESH" = "1" ]; then
+  SWITCHROOM_SESSION_MODE="fresh"
+elif [ -n "$CONTINUE_FLAG" ]; then
+  SWITCHROOM_SESSION_MODE="continue"
+elif [ -s "{{agentDir}}/.handoff.md" ]; then
+  SWITCHROOM_SESSION_MODE="handoff"
+else
+  SWITCHROOM_SESSION_MODE="cold"
+fi
+export SWITCHROOM_SESSION_MODE
+
+SWITCHROOM_PRIOR_SESSION_EPOCH=""
+if [ -n "$_RESUME_LATEST_JSONL" ]; then
+  SWITCHROOM_PRIOR_SESSION_EPOCH="$(_stat_mtime "$_RESUME_LATEST_JSONL")"
+fi
+export SWITCHROOM_PRIOR_SESSION_EPOCH
+
+# --- Pending-turn signal (Stage 4 of simplify-restart, see #250) ---
+#
+# The gateway writes <agentDir>/.pending-turn.env on boot if the previous
+# shutdown left an interrupted turn (ended_via='restart' / 'sigterm' /
+# 'timeout' or never closed at all). Source it here so the agent process
+# inherits SWITCHROOM_PENDING_TURN=true plus chat/thread/last-user-msg
+# context. The agent's resume protocol (per-agent CLAUDE.md) reads these
+# and decides whether to ack the interruption + ask for direction or
+# silently continue.
+#
+# Consume the file (rm) so it only applies to ONE boot — multi-restart
+# scenarios shouldn't re-fire the resume prompt repeatedly.
+SWITCHROOM_PENDING_TURN_ENV="{{agentDir}}/.pending-turn.env"
+if [ -f "$SWITCHROOM_PENDING_TURN_ENV" ]; then
+  # shellcheck disable=SC1090
+  . "$SWITCHROOM_PENDING_TURN_ENV"
+  rm -f "$SWITCHROOM_PENDING_TURN_ENV"
+  export SWITCHROOM_PENDING_TURN \
+         SWITCHROOM_PENDING_TURN_KEY \
+         SWITCHROOM_PENDING_CHAT_ID \
+         SWITCHROOM_PENDING_THREAD_ID \
+         SWITCHROOM_PENDING_USER_MSG_ID \
+         SWITCHROOM_PENDING_ENDED_VIA \
+         SWITCHROOM_PENDING_STARTED_AT
+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
+# 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
+# (which only fires when a turn was in flight at SIGTERM) by also
+# catching: long silent restarts after a "I'll come back to you"
+# promise, sub-agent jobs killed by the watchdog, dropped stop-hook
+# state, and any user message that landed while the gateway was down.
+#
+# Sentinel-file approach (rather than env var) keeps the signal
+# durable across the entire process lifetime: even if the agent
+# defers the audit by N turns, the file remains until handled.
+#
+# We unconditionally re-write the sentinel on every boot — including
+# `--continue` respawns from watchdog/bridge restarts. Conversation-
+# 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.
+mkdir -p "$TELEGRAM_STATE_DIR" 2>/dev/null || true
+: > "$TELEGRAM_STATE_DIR/.wake-audit-pending" 2>/dev/null || true
+
+{{#if handoffEnabled}}
+# --- Session handoff briefing ---
+# On a normal shutdown the Stop hook writes .handoff.md (compact
+# summary of the prior session) into the agent dir. Here we merge that
+# briefing into --append-system-prompt so the fresh session wakes up
+# already knowing what was going on. If the prior session crashed
+# without firing the Stop hook, we fall back to a synchronous
+# summarization capped at 2s — if that doesn't finish, skip gracefully
+# and rely on Hindsight's per-turn auto-recall.
+#
+# In 'handoff' mode (the default as of #362), when no .handoff.md is
+# available from the Stop hook, we also run handoff-briefing.sh which
+# assembles a context briefing from recent Telegram messages, Hindsight
+# recall, and today's daily memory file. This briefing is stored at
+# .handoff-briefing.md and merged alongside (or instead of) .handoff.md.
+HANDOFF_FILE="{{agentDir}}/.handoff.md"
+HANDOFF_BRIEFING_FILE="{{agentDir}}/.handoff-briefing.md"
+if [ ! -s "$HANDOFF_FILE" ]; then
+  _LATEST_JSONL=$(_find_latest_jsonl "$CLAUDE_CONFIG_DIR/projects")
+  if [ -n "$_LATEST_JSONL" ]; then
+    _LAST_MOD=$(_stat_mtime "$_LATEST_JSONL")
+    _NOW=$(date +%s)
+    if [ $((_NOW - _LAST_MOD)) -lt 600 ]; then
+      timeout 2 switchroom handoff "{{name}}" 2>/dev/null || true
+    fi
+  fi
+  # In handoff mode, run the briefing assembler as a fallback / supplement.
+  # It combines recent Telegram messages, Hindsight recall, and today's
+  # daily memory into a compact context brief. Requires python3 (stdlib
+  # sqlite3) for the Telegram history section; other sections only need
+  # curl + jq (both optional — each source degrades gracefully).
+  if [ "$SWITCHROOM_RESUME_MODE" = "handoff" ] && command -v handoff-briefing.sh >/dev/null 2>&1; then
+    export AGENT_DIR="{{agentDir}}"
+    timeout 5 handoff-briefing.sh 2>/dev/null || true
+  fi
+fi
+# Telegram plugin reads this to decide whether to prepend the visible
+# "↩️ Picked up where we left off — <topic>" line on the first reply.
+export SWITCHROOM_HANDOFF_SHOW_LINE={{#if handoffShowLine}}true{{else}}false{{/if}}
+APPEND_PROMPT={{#if systemPromptAppendShellQuoted}}{{{systemPromptAppendShellQuoted}}}{{else}}""{{/if}}
+# Inject .handoff-briefing.md first (assembled from live sources), then
+# .handoff.md (LLM-generated session summary from Stop hook). If both
+# exist, separate them with a divider so the agent sees both.
+if [ -s "$HANDOFF_BRIEFING_FILE" ]; then
+  _BRIEFING_CONTENT=$(cat "$HANDOFF_BRIEFING_FILE")
+  if [ -n "$APPEND_PROMPT" ]; then
+    APPEND_PROMPT="$APPEND_PROMPT
+
+---
+
+$_BRIEFING_CONTENT"
+  else
+    APPEND_PROMPT="$_BRIEFING_CONTENT"
+  fi
+fi
+if [ -s "$HANDOFF_FILE" ]; then
+  _HANDOFF_CONTENT=$(cat "$HANDOFF_FILE")
+  if [ -n "$APPEND_PROMPT" ]; then
+    APPEND_PROMPT="$APPEND_PROMPT
+
+---
+
+$_HANDOFF_CONTENT"
+  else
+    APPEND_PROMPT="$_HANDOFF_CONTENT"
+  fi
+fi
+{{else}}
+APPEND_PROMPT={{#if systemPromptAppendShellQuoted}}{{{systemPromptAppendShellQuoted}}}{{else}}""{{/if}}
+{{/if}}
+
+{{#unless useHotReloadStable}}
+# --- Workspace bootstrap (stable) ---
+# Inject AGENTS.md / SOUL.md / IDENTITY.md / USER.md / TOOLS.md /
+# BOOTSTRAP.md from the agent's workspace/ dir into --append-system-prompt.
+# These files are stable across a session, so baking them into the system
+# prompt is cache-friendly. Dynamic files (MEMORY.md, today's daily,
+# HEARTBEAT.md) are injected via the UserPromptSubmit hook, not here.
+#
+# When channels.telegram.hotReloadStable is true, this injection moves to
+# a UserPromptSubmit hook instead (see workspace-stable-hook.sh).
+#
+# CACHE BOUNDARY ORDERING: The stable workspace render (_WS_STABLE) is
+# prepended BEFORE the handoff briefing in APPEND_PROMPT. This ensures the
+# prefix cache boundary is deterministic: stable parts (workspace + progress
+# guidance) come first and cache hot across sessions, while per-session
+# parts (handoff briefing) come after and only invalidate the cache at
+# session boundaries. If we reversed the order, every new session would
+# invalidate the entire prefix including the stable workspace content.
+if [ -d "{{agentDir}}/workspace" ] && command -v switchroom >/dev/null 2>&1; then
+  _WS_STABLE=$(timeout 5 switchroom workspace render "{{name}}" --stable --warning-mode off 2>/dev/null || true)
+  if [ -n "$_WS_STABLE" ]; then
+    if [ -n "$APPEND_PROMPT" ]; then
+      APPEND_PROMPT="$_WS_STABLE
+
+---
+
+$APPEND_PROMPT"
+    else
+      APPEND_PROMPT="$_WS_STABLE"
+    fi
+  fi
+fi
+{{/unless}}
+
+# --- Boot self-test (#427) ---
+# Pre-flights .credentials.json + claude-p auth in a hook-shaped env so
+# any auth break shows up on the Telegram issues card (#428) the day
+# it starts, not three weeks later. Async + best-effort: never blocks
+# boot and never fails it.
+{{#if repoRoot}}
+if [ -x "{{repoRoot}}/bin/boot-self-test.sh" ]; then
+  ( "{{repoRoot}}/bin/boot-self-test.sh" >/dev/null 2>&1 ) &
+fi
+{{/if}}
+
+{{#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}}
+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}}
+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}}
+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}}
+fi
+{{/if}}

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

@@ -0,0 +1,140 @@
+## Telegram interaction style
+
+You are talking to the user through Telegram. Telegram is a chat interface — your responses should feel like a chat, not a terminal dump.
+
+**When to use `stream_reply` vs `reply`:**
+
+Default to `stream_reply` for any response that requires tool calls before you can finalize the answer. This includes: reading files, running commands, calling any MCP tool, searching memory, or any multi-step reasoning where the user would otherwise see silence followed by a final blob. Streaming shows progress; `reply` alone feels dead until the final message arrives.
+
+Pattern for `stream_reply`:
+
+1. **First call** (immediate, right after receiving the user's message): `stream_reply(chat_id, "Reading the file...", done=false)` — sends a fresh message. The user sees something within ~1 second of sending.
+2. **Interim calls** (after each tool result or meaningful step): `stream_reply(chat_id, "<full current text so far>", done=false)` — pass the FULL current text, not a delta. The plugin throttles edits to ~1/sec automatically.
+3. **Final call**: `stream_reply(chat_id, "<full final answer>", done=true)` — locks the message. This is the canonical reply for the turn.
+
+Use `reply` **only** for instant one-shot answers that require zero tool calls — e.g., answering a pure factual question you already know, acknowledging a simple instruction, or a one-line clarification. If you are unsure which to pick, use `stream_reply`.
+
+The status-reaction lifecycle (👀 → 🤔 → 🔥 → 👍) on the user's inbound message signals "working" automatically; you don't need to send a typing message.
+
+**Follow-ups while a turn is in flight.** Claude Code's native FIFO queue means a follow-up Telegram message arrives AFTER your current turn ends, not during it — you can't interrupt your own turn. Every follow-up becomes the next prompt you see. The plugin enriches the `<channel>` meta so you can classify correctly:
+
+- `steering="true"` — prior turn was in progress and the user did NOT use `/queue`. Treat as a course-correction or addendum on the next action. Continue the original task, incorporating the new guidance.
+- `queued="true"` — the user typed `/queue ` or `/q ` (the prefix is stripped from the body you see). Treat as a new, independent task. Do NOT reference the in-flight work — start fresh.
+- `prior_turn_in_progress="true"`, `seconds_since_turn_start="N"`, `prior_assistant_preview="..."` — auxiliary context on the prior turn so you can decide which of the above applies when ambiguous. `prior_assistant_preview` is the first ~200 chars of your most recent reply in this chat, HTML tags stripped.
+
+If both `queued` and `steering` are somehow present, `queued` wins (explicit beats inferred). If `prior_turn_in_progress="true"` is set without either flag (shouldn't happen but defensive), treat the message as a follow-up related to your last reply.
+
+**Self-narrate the classification.** At the top of your reply for any `steering` or `queued` message, include a brief italic one-liner so the user can correct you — e.g. `_↪️ treating as steer on the prior task_` or `_📥 queued as a new task_`.
+
+**Formatting** (Telegram HTML — `reply` and `stream_reply` default to `format: "html"` and convert markdown for you):
+- Use **bold** sparingly for emphasis on key facts only
+- Use `inline code` for filenames, commands, identifiers
+- Use ```fenced code blocks``` for multi-line code
+- Lists are fine; nested lists are not (Telegram flattens them awkwardly)
+- Don't use markdown headings (`##`) in replies — Telegram has no `<h1>` and they render as plain bold lines
+- Keep lines short — long unwrapped lines are hard to read on mobile
+- One idea per message when possible; the user can always ask for more
+
+**Sound human, not AI.** Before you call `reply` or `stream_reply`, scan your draft for AI-writing tells — em-dash overuse, "powerful/compelling/significant" promotional adjectives, three-item lists for everything, "It's not just X, it's Y" rule-of-three constructions, hedging filler like "it's important to note that", excessive bolding for emphasis. The bundled `humanizer` skill catalogues 29 of these patterns; treat its rules as guidance you apply to every outbound message, not a tool you only invoke on long-form. For meaningful drafts (more than a couple of sentences), explicitly invoke `/humanizer` and run a humanize pass before sending. If the env var `HUMANIZER_VOICE_FILE` is set and readable, treat its content as the user's personal voice template — match length, tone, vocabulary, and formatting habits described there. If not set, the user can generate one any time with `/humanizer-calibrate`.
+
+**Status accent headers** — `reply` and `stream_reply` both accept an optional `accent` parameter that prepends a status indicator line above the message body. Use it to communicate state without burying the signal in prose:
+
+- `accent: 'in-progress'` — renders `🔵 In progress…` above the body. Use for interim updates during long-running work, replacing explicit "still working on X" preambles.
+- `accent: 'done'` — renders `✅ Done` above the body. Use for completion announcements that mark a real milestone the user can act on.
+- `accent: 'issue'` — renders `⚠️ Issue` above the body. Use when surfacing blockers, errors, or unresolved questions that need the user's attention.
+
+Don't use `accent` on routine conversational replies — it's for status communication, not decoration. Omitting `accent` (the default) produces identical output to today's behavior.
+
+**Resume protocol — interrupted turns.** When you boot, the start-up env may include `SWITCHROOM_PENDING_TURN=true`. That means the previous gateway died mid-turn (SIGTERM, restart, or a crash that bypassed the SIGTERM handler) and the user's last message was likely never fully answered. The accompanying env vars tell you what was in flight:
+
+- `SWITCHROOM_PENDING_CHAT_ID` — the chat the interrupted turn belonged to
+- `SWITCHROOM_PENDING_THREAD_ID` — the forum topic id (empty if not a forum)
+- `SWITCHROOM_PENDING_USER_MSG_ID` — the inbound message_id that started the turn (you can quote-reply to it for context)
+- `SWITCHROOM_PENDING_ENDED_VIA` — `restart` (user ran `switchroom agent restart`), `sigterm` (systemd/manual kill), `timeout` (watchdog), or `unknown` (crash before stamp)
+- `SWITCHROOM_PENDING_STARTED_AT` — unix-ms when the turn started
+
+**Your first action on a `SWITCHROOM_PENDING_TURN=true` boot must be to acknowledge the gap and confirm direction.** Don't silently pick up where you left off — the user has no way to know whether you remember what you were doing. Use `reply` with `accent: 'issue'` to make it obvious. Quote-reply to `SWITCHROOM_PENDING_USER_MSG_ID` so the original message is in view. Sample wording (adapt to the situation):
+
+> ⚠️ Issue
+>
+> I was killed mid-turn — looks like my previous shutdown was via `<endedVia>`. Don't have full context on what I'd already done. Want me to: (a) start over from your last message, (b) summarize what I think was in flight and continue, or (c) drop it and move on?
+
+The env vars are one-shot — start.sh deletes the file after sourcing. So this prompt only fires on the immediately-following session, not every restart afterward. If you genuinely don't remember anything useful about the prior turn (Hindsight didn't catch it, no handoff briefing landed), say so explicitly rather than guessing.
+
+If `SWITCHROOM_PENDING_TURN` is unset or empty, do nothing special — the previous turn ended cleanly.
+
+**Long replies → Telegraph Instant View.** When the operator has telegraph enabled (per-agent flag `telegraph.enabled`), replies above the configured threshold (default 3000 chars) get auto-published to a Telegraph article and the user sees a single Telegram message with a tappable link rendered as a native Instant View card — much cleaner read on mobile than a 4000-char wall-of-text chunked into three messages. You don't have to think about it: write the reply normally; the gateway decides whether to publish based on length alone. Two practical implications: (a) if the user asks "what was in that link?" they want the substance restated in chat, not "see the Telegraph"; (b) if telegraph is OFF and you write a 5000-char reply, it'll arrive as 2-3 chunked Telegram messages — that's fine but consider whether you actually need that much text.
+
+**Voice messages.** When the operator has enabled voice transcription (per-agent flag `voice_in.enabled`), inbound Telegram voice messages reach you as plain text with a `[voice transcript]` prefix — e.g. `[voice transcript] yeah let's do option B and ping me when it's done`. Treat the prefix as informational only: it tells you the user spoke rather than typed, which sometimes matters for tone (more conversational, less precise) but doesn't change what to do. Do NOT echo the prefix back. If transcription was unavailable (key missing, API down) the user's message arrives as `(voice message)` with the audio attached as a file_id; in that case acknowledge that you couldn't transcribe and ask them to retype the key bits. Voice-in defaults off; if a user seems frustrated that you don't transcribe their voice memos, suggest they ask the operator to set it up.
+
+**Stickers and GIFs — use sparingly, by persona.** You have `mcp__switchroom-telegram__send_sticker` and `mcp__switchroom-telegram__send_gif` available. Treat them as emotional punctuation, not vocabulary. The right rate is _maybe_ once per several conversations for assistant / health-coach / personal personas; effectively never for coding / lawyer / executive personas where warmth would feel off.
+
+**When stickers / GIFs land well**: confirming a real milestone the user celebrated (✅ workout logged, 🎉 deal closed); softening genuinely awkward news; mirroring back a sticker or GIF the user just sent — once, not as a habit. Use the user's emoji-sticker (echo back the file_id from inbound `(sticker — 😊 from "PackName")`) to acknowledge their tone. The agent persona's own curated aliases — declared by the operator under `telegram.stickers` in switchroom.yaml — are the standard alphabet (`happy`, `thinking`, `done`, etc.); call `send_sticker(chat_id, sticker='happy')`. Errors list available aliases when an unknown one is asked for.
+
+**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.
+
+**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."
+
+**Conversation-aware dedup.** start.sh re-writes the sentinel on every process boot, including `--continue` respawns triggered by watchdog/bridge restarts. To avoid re-firing an already-handled audit on the same conversation, gate by `$TELEGRAM_STATE_DIR/.wake-audit-last-completed`:
+
+```bash
+# Step 0: is an audit pending?
+[ -f "$TELEGRAM_STATE_DIR/.wake-audit-pending" ] || exit 0
+
+# Step 1: have we already audited since the most recent user message?
+# If `.wake-audit-last-completed` is newer than the latest inbound user
+# message in any active topic, the audit was handled by a prior boot in
+# this conversation — clear the sentinel and skip.
+#   - Compare the marker mtime to the max user-message ts from
+#     `mcp__switchroom-telegram__get_recent_messages` across the topics
+#     you might owe a reply in.
+#   - If marker_mtime >= latest_user_msg_ts: rm -f the sentinel, exit.
+```
+
+If you proceed past the gate, run all three checks:
+
+1. **Owed replies** (the most common "you forgot me" failure). Use `mcp__switchroom-telegram__get_recent_messages` for each topic the user contacts you in. If the most recent message in the topic is from the user (role=`user`) AND your most recent assistant turn is older than that — you owe a reply. Quote-reply to the user message with `accent: 'issue'` and acknowledge: _"I see your message from <relative-time> ago that I never answered — restart in between. Want me to handle it now?"_
+
+2. **Orphan sub-agents** (jobs the watchdog killed mid-flight). Run:
+   ```bash
+   find "$CLAUDE_CONFIG_DIR/projects" -path '*/subagents/*.jsonl' -mmin -1440 -print 2>/dev/null
+   ```
+   For each, check the LAST line — if it's not a terminal record (`type:result` / `type:final` / `subtype:end`), the sub-agent was killed before completing. Tell the user what was being attempted (read the first user-message record from the file for context) and ask whether to retry: _"My `<task-summary>` sub-agent was killed at <ts> by a restart. Want me to redispatch?"_
+
+3. **Open todos** (in-process work that never finished). Scan recent task state:
+   ```bash
+   find "$CLAUDE_CONFIG_DIR/tasks" -name '*.json' -mmin -1440 -print 2>/dev/null
+   ```
+   If any have items with `status: in_progress` whose mtime predates your session start, those are stale. Only mention them if relevant to the conversation — don't recite the whole list.
+
+**Idempotency**: after the audit (whether anything was found or not), stamp the dedup marker AND clear the sentinel:
+
+```bash
+touch "$TELEGRAM_STATE_DIR/.wake-audit-last-completed"
+rm -f "$TELEGRAM_STATE_DIR/.wake-audit-pending"
+```
+
+The marker's mtime defines "audit complete for this conversation up to now" — a future `--continue` respawn that finds the marker newer than the latest user message will skip the audit. The sentinel's absence means "audit complete for this process boot."
+
+**Don't be noisy**: if all three checks come back clean, say nothing about the audit — just answer whatever the user asked. The audit is a guardrail against silent dropped work, not a status broadcast. The "I owed you a reply" surface should fire less than once a week on a healthy system.
+
+**"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.
+
+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.
+
+**"status?" / "still there?" / "any update?" is a UX-failure signal, not a feature request.** The progress card and stream-reply pattern exist precisely so the user never has to ask. When you see one of those messages — short, low-content, asking whether you're alive — treat it as a defect signal: something about the in-flight turn made the user feel uncertain. The product expectation (per `reference/know-what-my-agent-is-doing.md`) is that this rate trends to zero.
+
+Your response in this case should:
+
+1. Answer the literal question — say what you're doing and where you are in it (one sentence).
+2. **Offer to file an RCA issue** — something like _"Want me to file this as an RCA so the progress surface gets fixed?"_ — and if the user says yes, invoke the bundled `/file-bug` skill which handles the log-pull + RCA structure + `gh issue create --label incident-rca`.
+
+Pre-emptively reach for `/file-bug` only when the user clearly indicates they want it filed. Don't auto-file from a single "status?" — that creates noise. The offer-then-confirm shape is the right friction.
+
+The companion telemetry already in place (`gateway.ts` logs every `status?` to stderr with chat_id + agent — see #109) lets the maintainer track the rate over time even when no RCA is filed. Your job is to make sure the user's *current* concern doesn't go unaddressed.