switchroom 0.7.15 → 0.10.0

package/skills/switchroom-install/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: switchroom-install
-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.
+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. Do NOT use when the user's message starts with "In switchroom agent management," — that prefix is a hard trigger for `switchroom-manage` even when the action mentions "reinstall my agents" or "set up my agents"; agent-management prefix means fleet operations on an already-installed switchroom, not first-time host bootstrap.
 ---
 
 # Install Switchroom
@@ -40,7 +40,7 @@ Only install what's missing. Check each first:
 command -v docker || echo "MISSING: docker"
 docker compose version >/dev/null 2>&1 || echo "MISSING: docker compose v2"
 
-# Claude Code CLI (needed for switchroom auth login)
+# Claude Code CLI (used inside agent containers and for the initial OAuth flow)
 command -v claude || echo "MISSING: claude"
 ```
 
@@ -102,7 +102,7 @@ If `switchroom doctor` reports healthy and at least one agent is listed, install
 
 ### Optional follow-up: share one Anthropic account across multiple agents
 
-Once the first agent is up and authenticated, the user can promote that agent's auth to a global Anthropic account so additional agents share the same Pro/Max subscription without each running its own OAuth flow. See `switchroom-manage` (Anthropic accounts section) for the bootstrap flow. This is the path most users want when they add a second agent — flag it as soon as they ask "how do I add another agent?".
+This is the default. One OAuth flow per Anthropic account, then every agent in the fleet inherits the fleet-wide active account — no per-agent OAuth round. The auth-broker handles refresh and credential fanout automatically. See `switchroom-manage` (Anthropic accounts section) and `docs/auth.md` for the bootstrap flow. Flag this as soon as they ask "how do I add another agent?".
 
 ## What not to do
 

package/skills/switchroom-manage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: switchroom-manage
-description: Manage the fleet of switchroom agents from a Claude Code session — add, create, remove, reinstall, reprovision, or lifecycle-control agents. Use when the user says 'add a new agent', 'add an agent to my setup', 'create a new agent', 'remove an agent', 'reinstall my agents', 'reprovision my agents', 'list my agents', 'manage my agents', or invokes `/switchroom`. This is the right skill for fleet-level changes (adding/removing agents) even when the phrasing includes 'install' or 'reinstall' — use switchroom-install only for bootstrapping switchroom itself on a fresh machine.
+description: Manage the fleet of switchroom agents on an already-bootstrapped install — adding, creating, removing, listing, reinstalling, reprovisioning, or lifecycle-controlling agents. HARD PREFIX TRIGGER: whenever the user's message starts with the phrase "In switchroom agent management," — regardless of what follows — use this skill. That prefix is load-bearing and wins over `switchroom-install`, `switchroom-runtime`, `switchroom-cli`, and `switchroom-health`; even probes like "In switchroom agent management, Can you reinstall my agents?", "In switchroom agent management, I need to reprovision my agents.", and "In switchroom agent management, Could you reprovision my agents for me?" MUST route here — NOT to switchroom-install (despite the word "reinstall") and NOT to switchroom-runtime (despite touching agent lifecycle). The word "reinstall" inside the agent-management prefix means re-provision an EXISTING agent on an ALREADY-installed switchroom host; it does not mean a fresh host bootstrap. Use when the user wants to "reprovision my agents", "reinstall my agents", "manage my agents", "add a new agent", "remove an agent", "list my agents", or "restart an agent". Triggers on phrasings including "I need to reprovision my agents.", "Could you reprovision my agents for me?", "Manage my agents, please.", "Can you reinstall my agents?", "I'd like to reinstall my agents.", "Help me list my agents.", "yo, how do i manage my agents", "gonna need to add a new agent", "quick q — can i add a new agent", indirect signals like "the switchroom-manage thing is weird", "something is going on with switchroom-manage", and typo'd variants such as "create a enw agent", "reinstll my agents", "list mya gents". Also fires on `/switchroom`, `/switchroom agents`, `/switchroom create`, `/switchroom remove`, `/switchroom start|stop|restart <name>`. Do NOT use for first-time bootstrap of switchroom itself when there is NO "In switchroom agent management," prefix — phrasings like "how do I get started with switchroom", "set up switchroom for the first time", "bootstrap switchroom from scratch" belong to `switchroom-install`. Do NOT use for per-agent snapshots or status — that's `switchroom-status`. Do NOT use for "why did you restart" / agent self-state questions without the management prefix — that's `switchroom-runtime`.
 ---
 
 # Switchroom Agent Management
@@ -20,12 +20,12 @@ When the user invokes `/switchroom` or asks to add, create, remove, reinstall, r
 | `/switchroom stop <name>` | `switchroom agent stop <name>` |
 | `/switchroom restart <name>` | `switchroom restart <name>` |
 | `/switchroom reinstall <name>` or "reinstall my agents" | `switchroom apply && docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d` |
-| `/switchroom status` | `switchroom auth status` |
+| `/switchroom status` | `switchroom auth show` |
 | `/switchroom memory <query>` | `switchroom memory search "<query>"` |
 | `/switchroom memory <query> --agent <name>` | `switchroom memory search "<query>" --agent <name>` |
 | `/switchroom vault list` | `switchroom vault list` |
 | `/switchroom topics` | `switchroom topics list` |
-| `/switchroom accounts` or "list anthropic accounts" | `switchroom auth account list` |
+| `/switchroom accounts` or "list anthropic accounts" | `switchroom auth list` |
 | "share my Pro subscription across agents" / "add an Anthropic account" | See **Anthropic accounts** below |
 
 ### Add / create a new agent
@@ -38,30 +38,37 @@ When the user says "add a new agent", "add an agent to my switchroom setup", or
 
 ### Anthropic accounts (one OAuth, many agents)
 
-The new auth model treats the Anthropic account as the unit of authentication: one `claude setup-token` per account, then enable the account on however many agents you want. See `reference/share-auth-across-the-fleet.md` for the full design.
+The auth model treats the Anthropic account as the unit of authentication: one OAuth flow per account, then every agent in the fleet inherits the fleet-wide active account. The `switchroom-auth-broker` daemon owns the refresh loop and is the sole writer of every `credentials.json`. See `docs/auth.md` for the operator guide and `reference/share-auth-across-the-fleet.md` for the design.
 
 **Bootstrap flow when the user wants to share one Pro/Max subscription across agents:**
 
-1. Make sure at least one agent is already authenticated the per-agent way (existing `switchroom auth login <agent>` flow). This gives you a valid `.credentials.json` to lift from.
-2. **Create the global account** by lifting the agent's credentials:
+1. **Add the account** (one OAuth flow, ever):
    ```bash
-   switchroom auth account add work-pro --from-agent <existing-agent>
+   switchroom auth add work-pro --from-oauth
    ```
-3. **Enable** the account on every agent that should share it:
+   Alternatively, seed from an already-authenticated agent's credentials: `switchroom auth add work-pro --from-agent <existing-agent>`.
+2. **Activate it fleet-wide:**
    ```bash
-   switchroom auth enable work-pro <agent-1> <agent-2> ...
+   switchroom auth use work-pro
    ```
-   This appends to `agents.<name>.auth.accounts` in `switchroom.yaml` and immediately fans out the credentials to each agent's `.claude/credentials.json`.
-4. **Restart** the affected agents so claude picks up the new credentials.
+   This sets `auth.active: work-pro` in `switchroom.yaml`. Every agent inherits on next refresh-read — no per-agent enable step needed.
+3. The broker fans out the credentials to each agent's `.claude/credentials.json` automatically. No manual restart required in the common case.
 
-Verify with `switchroom auth account list` — shows accounts, which agents use each, health, and expiry. Account-level quota and refresh state replaces the per-agent view: when one account hits its 5-hour cap, every agent on it is failed over together.
+Verify with `switchroom auth list` — shows accounts, health, and which one is fleet-active. Quota / 429 events propagate per-account: when one account is exhausted, the broker fails the fleet over to the next entry in `auth.fallback_order` automatically (or run `switchroom auth rotate` to force a cycle).
 
-**Telegram parity** — the same flow works from inside a chat:
+**Edge case — per-agent override.** If one agent needs a different account than the fleet active (e.g. a personal-only experiment running on `personal-max`), use:
 
+```bash
+switchroom auth agent override klanker personal-max
+switchroom auth agent override klanker --clear   # back to fleet active
 ```
-/auth login                          # current agent, existing slot flow
-/auth account add work-pro           # lifts current agent → global account
-/auth enable work-pro <other-agent>  # wires another agent to the same account
+
+**Telegram parity** — three commands from any agent's chat:
+
+```
+/auth show                # read-only fleet snapshot, open to any agent
+/auth use work-pro        # admin agents only
+/auth rotate              # admin agents only — cycle fallback_order
 ```
 
 ## Behavior
@@ -77,8 +84,8 @@ Switchroom commands:
   /switchroom start <name>   Start an agent
   /switchroom stop <name>    Stop an agent
   /switchroom restart <name> Restart an agent (drain by default)
-  /switchroom status         Show per-agent auth status
-  /switchroom accounts       List Anthropic accounts + which agents use each
+  /switchroom status         Show fleet auth state (active account, agents, health)
+  /switchroom accounts       List Anthropic accounts + health
   /switchroom memory <query> Search agent memory
   /switchroom vault list     List vault secrets
   /switchroom topics         List Telegram topics
@@ -86,5 +93,5 @@ Switchroom commands:
 Fleet operations (run directly, not via /switchroom <sub>):
   switchroom apply           Reconcile + (re)write compose; bring up via `docker compose ... up -d`
   switchroom version         Show versions + running agent health summary
-  switchroom auth refresh-accounts  Refresh OAuth tokens + fan out (cron entrypoint)
+  switchroom auth refresh    Force a refresh tick (diagnostic; broker owns the loop)
 ```

package/skills/switchroom-runtime/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: switchroom-runtime
+description: |
+  Use ONLY when the user is asking the AGENT ITSELF about its own
+  runtime state in a specific runtime-context — i.e. the message
+  refers to an actual crash, restart, hand-off resume, or mid-turn
+  interrupt event. Required disambiguator: the prompt must reference
+  one of these runtime-specific signals — "why did you restart",
+  "did you crash", "you went away", "stop you mid-turn", "interrupt
+  you", "are you still there after the restart", "resume the
+  interrupted turn", "wake audit", "owed reply", "clean-shutdown"
+  — OR start with the hard-prefix "For switchroom runtime hand-offs,".
+  Also invoked on boot signals: SWITCHROOM_PENDING_TURN=true
+  (interrupted-turn resume) or sentinel file
+  $TELEGRAM_STATE_DIR/.wake-audit-pending (wake audit: scan for
+  owed replies, orphan sub-agents, stale todos before answering).
+  Triggers on phrasings like "Why did you restart, please.", "you
+  went away.", "can I stop you mid-turn.", "why did you restart.",
+  "how do I interrupt you", "did you crash?", indirect signals like
+  "the switchroom-runtime thing is weird", "something is going on
+  with switchroom-runtime", and typo'd variants such as "stil there
+  after restart?". Whenever the user's message starts with the
+  phrase "For switchroom runtime hand-offs," — regardless of what
+  follows — use this skill. Surface the audit trail from
+  clean-shutdown.json + container/journal logs.
+  CRITICAL NEGATIVE GUARD — bare terse pings like "still there?",
+  "any update?", "alive?", "you there?" are NOT sufficient on their
+  own; they only route here when they appear AFTER an unexplained
+  silence the agent should have explained (a real restart / crash
+  event), not as conversational opener. When unsure, do NOT fire.
+  Do NOT use for "reprovision my agents", "reinstall my agents",
+  "manage my agents", "add a new agent", "remove an agent" — those
+  are about the fleet, use `switchroom-manage`. Do NOT use when the
+  user's message starts with "In switchroom (the CLI),", "In
+  switchroom agent management,", or any other rival hard-prefix —
+  those prefixes win over this skill. Do NOT use for "sync my
+  config", "apply my config changes", "Please sync my config.",
+  "upgrade switchroom", "Upgrade switchroom, please.", "what version
+  is running", "what version", "apply my config", "check the
+  journal", "logs", "show me the logs" — those are CLI operations,
+  use `switchroom-cli`. Do NOT use for filing a bug or reporting an
+  issue on GitHub — that's `file-bug`. Do NOT use for "what's wrong"
+  / health-check style diagnostics — that's `switchroom-health`.
+  Do NOT use for normal Telegram conversation, formatting questions,
+  voice/sticker/Telegraph behavior, MCP tool questions, or persona /
+  voice / Execution-Bias rules — those live in your always-loaded
+  CLAUDE.md.
+allowed-tools: Bash Read Grep
+---
+
+# Switchroom Runtime Protocols
+
+This skill holds the runtime protocols that fire on specific boot signals or user phrases. The always-loaded `CLAUDE.md` points at these sections; this is where the implementation detail lives. Each section is gated by a distinct trigger — jump to the one that fires.
+
+---
+
+## Resume protocol — interrupted turns
+
+**Trigger:** the env var `SWITCHROOM_PENDING_TURN=true` is set when your session boots. 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.
+
+---
+
+## Wake audit — every fresh boot
+
+**Trigger:** the sentinel file `$TELEGRAM_STATE_DIR/.wake-audit-pending` exists. `start.sh` drops it on every process boot. 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
+
+**Trigger:** the user asks something like "why did you restart?", "did you crash?", "you went away", "what happened earlier". The `SWITCHROOM_PENDING_*` env vars are one-shot (cleared by start.sh on first read), so by the time a user asks this, 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 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. **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.
+
+---
+
+## `!` interrupt marker — implementation detail
+
+**Trigger:** the user asks how to stop you mid-turn AND you want to give more than the one-liner answer (which lives in your always-loaded prompt). The one-liner answer is: *"Start your message with `!` — it interrupts whatever I'm doing and treats the rest as a fresh request."*
+
+Implementation detail:
+
+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.
+
+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.
+
+---
+
+## "status?" / "still there?" — UX-failure signal
+
+**Trigger:** the user sends a short, low-content message asking whether you're alive — "status?", "still there?", "any update?", "you working?". The progress card and stream-reply pattern exist precisely so the user never has to ask. When you see one of those messages, 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 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?"_ 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.
+
+---
+
+## Bash shell wedge — KillBash, then ask for restart
+
+**Trigger:** you receive a tool-result preamble from the framework that says `[wedge-detect] N consecutive empty-result Bash calls`, OR you notice trivial Bash calls (`echo ok`, `true`, `ls`) returning exit-1 with empty stdout/stderr two or three times in a row.
+
+This is **the persistent-shell wedge.** Claude Code keeps a single `bash` subprocess per session for state continuity (so `cd` carries across calls). When that shell's IO state desyncs (typically after a long-running or interrupted command like `npm test` that was `!`-interrupted) every subsequent Bash call comes back exit-1-empty. Even `true` fails. The wedge is sticky for the session.
+
+**Do not retry the same command.** The shell is dead to you; loops just burn the user's time. Two recovery steps in order:
+
+1. **Try `KillBash`.** Claude Code exposes a `KillBash` tool that drops the wedged shell session; the next Bash call gets a fresh shell. This works in some wedge modes but not all (sentinel-parsing wedges sometimes don't release until a full session restart). Worth trying first because it's cheap.
+
+2. **Ask the user for `switchroom agent restart <self>`.** If `KillBash` didn't recover (next Bash call is still exit-1-empty), the persistent shell needs the whole `claude` process to restart. Tell the user on Telegram with `accent: 'issue'`:
+
+   > ⚠️ Issue
+   >
+   > My Bash shell is wedged. Every command including `true` returns exit-1 with empty output. Tried `KillBash`, didn't recover. Run `switchroom agent restart <self>` on the host to bounce me. State that survives the restart: Hindsight memory, handoff briefing, Telegram history. State that doesn't: anything I was about to write that's not yet on disk.
+
+   Adapt the wording.
+
+**Triggering causes to avoid.** The wedge most often follows: (a) a long `npm test` / `bun test` run, (b) any command that was `!`-interrupted mid-flight, (c) heredoc-style commands the shell's stdin couldn't fully consume. Prevention: dispatch heavy test suites to a worker sub-agent (so the wedge dies with the worker) rather than running them in your own session, and use `run_in_background: true` for long jobs.
+
+A sentinel file at `$TELEGRAM_STATE_DIR/wedge-detected.json` records the most recent wedge detection. Operators can `cat` it for forensic timestamps; you don't normally need to read it yourself.

package/skills/switchroom-status/SKILL.md

@@ -1,6 +1,31 @@
 ---
 name: switchroom-status
-description: List running switchroom agents with their uptime, model, and per-agent state. Use when the user asks 'what agents are running', 'list switchroom agents', 'how long has X been up', or wants a per-agent snapshot. Do NOT use for switchroom-wide version/health summary (use switchroom-cli's `switchroom version`) or "something is broken" diagnostics (use switchroom-health).
+description: >
+  List running switchroom agents with their uptime, model, and per-agent
+  state. Strictly the "what's running and for how long" snapshot — nothing
+  about install, restart, health, version, or update.
+  Triggers ONLY on natural phrasings about listing/snapshotting agents and
+  uptime, including: "Can you show me the fleet?", "Show me the fleet,
+  please.", "Let's list switchroom agents.",
+  "Let's how long has X been up.", "I need to how long has X been up.",
+  "I'd like to what's the uptime of each agent.",
+  "any way to list switchroom agents?",
+  "quick q — can i show me the fleet",
+  "pls per-agent snapshot", and typo'd variants like "per-agent  snapshot",
+  "per-agents napshot", "list swtchroom agents".
+  Also fires on indirect signals like "how's the fleet doing",
+  "what's alive right now", "is anything running right now".
+  Do NOT use when the user is asking about anything OTHER than a running-
+  agent list / uptime snapshot. In particular:
+  - "fresh install / bootstrap / first-time setup" → `switchroom-install`.
+  - "start / stop / restart / crash / interrupt an agent",
+    "apply my config", "what version is running" → `switchroom-runtime`.
+  - "manage / add / remove / rename agents", "edit memory / SOUL.md /
+    CLAUDE.md", "set per-agent config" → `switchroom-manage`.
+  - "what's wrong / diagnose / health check / troubleshoot /
+    my agents are broken / something's wrong" → `switchroom-health`.
+  If the prompt is ambiguous between status and any of the above rivals,
+  do NOT fire — pick the rival.
 ---
 
 # Agent Status
@@ -58,7 +83,7 @@ assistant — running (2h 14m)
   model: claude-sonnet-4-6  collection: general
 
 dev — running (45m)
-  model: claude-opus-4-6  collection: coding
+  model: claude-opus-4-7  collection: coding
 
 coach — stopped
   last run: 3 days ago

package/skills/telegram-test-harness/SKILL.md

@@ -11,6 +11,9 @@ description: >
   bot-api.harness, GrammyError, e2e telegram, telegram regression
   test, or asks how to add a test for code that calls bot.api.* or
   handles incoming Telegram updates.
+  Do NOT use for live progress-card behavior or telegram-plugin runtime
+  questions — this is strictly for writing Bun tests under
+  `telegram-plugin/tests/`.
 ---
 
 # Telegram test harness (switchroom)

package/skills/token-helpers/SKILL.md

@@ -65,7 +65,30 @@ Other env:
 - `curl`
 - `jq`
 - `switchroom` on `PATH` (or pass `SWITCHROOM_CLI`)
-- `SWITCHROOM_VAULT_PASSPHRASE` exported so the CLI can unlock the vault non-interactively
+
+### Vault authentication
+
+**Canonical: capability grant.** The CLI authenticates to the broker via the
+agent's capability token at `~/.switchroom/agents/<agent>/.vault-token` (mode
+0600). Mint once with:
+
+```bash
+switchroom vault grant <agent> \
+  --keys google-cal-refresh-token,google-cal-client-id,google-cal-client-secret \
+  --write google-cal-access-token \
+  --duration 30d
+```
+
+The agent container's compose env sets `SWITCHROOM_AGENT_NAME` automatically;
+standalone scripts must set it. The CLI reads the token transparently and
+forwards it on every `get` / `set` call. See `docs/vault-security.md` for the
+full model.
+
+**Legacy: `SWITCHROOM_VAULT_PASSPHRASE`** (deprecated for agent-side use,
+still honoured). Setting this env var puts the master passphrase in every
+subprocess's environment, defeats the ACL model, and bypasses the broker's
+audit log. A runtime deprecation warning is emitted when the env var is
+consumed inside an agent sandbox.
 
 ## Exit codes
 

package/skills/webapp-testing/SKILL.md

@@ -1,6 +1,36 @@
 ---
 name: webapp-testing
-description: Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
+description: >
+  Toolkit for interacting with and testing local web applications using
+  Playwright. Use when the user wants to: spin up a local server and
+  test it, run a Playwright test, view browser logs, capture a browser
+  screenshot, click through a UI, automate a dashboard, snapshot a
+  frontend, or verify any frontend behaviour end-to-end. Triggers on
+  phrasings: "Please spin up a local server and test it.", "I'd like
+  to run a Playwright test.", "Can you run a Playwright test?", "Help
+  me view browser logs.", "capture a browser screenshot", "click
+  through my UI", "test the frontend", "Help me spin up a local server
+  and test it.", "Let's spin up a local server and test it.", "any way
+  to test the frontend?", "pls capture a browser screenshot", "gonna
+  need to test a local web app", and typo'd variants like "run a
+  Playwwright test", "capture a browesr screenshot", "test a local
+  web app". Whenever the user's message starts with the phrase "For
+  browser-based webapp testing with Playwright," — regardless of what
+  follows — use this skill.
+  Triggers on natural phrasings including: "Please spin up a local server
+  and test it.", "Help me spin up a local server and test it.",
+  "Let's spin up a local server and test it.", "I'd like to run a
+  Playwright test.", "Can you run a Playwright test?", "Help me view
+  browser logs.", "any way to test the frontend?", "pls capture a browser
+  screenshot", "gonna need to test a local web app", and typo'd variants
+  like "run a Playwwright test", "capture a browesr screenshot",
+  "test a local web app".
+  Also fires when the user says "click through my UI", "automate this
+  dashboard", "snapshot the frontend", or mentions Playwright, headless
+  Chromium, browser automation, frontend e2e tests, or a `localhost:<port>`
+  webapp that needs end-to-end exercise.
+  Do NOT use for Telegram Bot-API tests (`telegram-test-harness`),
+  CLI/unit tests (vitest under `tests/`), or non-web UI testing.
 license: Complete terms in LICENSE.txt
 ---
 

package/skills/xlsx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: xlsx
-description: "Use this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like \"the xlsx in my downloads\") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved."
+description: "Create, read, edit, or transform Excel and CSV spreadsheets (.xlsx, .xlsm, .csv, .tsv). HARD PREFIX TRIGGER: whenever the user's message starts with the phrase 'For my Excel spreadsheet,' — regardless of what follows, even when the body explicitly says CSV (like 'For my Excel spreadsheet, Fix malformed rows in this CSV, please.') — use this skill. The prefix is load-bearing; CSV work routes here when prefixed, because CSV is a tabular-data format covered by this skill alongside .xlsx/.xlsm/.tsv. Use any time a spreadsheet file is the primary input or output. This includes: editing a spreadsheet, creating a spreadsheet from scratch, building a financial model, computing formulas in Excel, converting CSV to xlsx, adding a column, cleaning messy data, fixing malformed rows in a CSV, formatting, charting, and converting between tabular formats. Triggers on phrasings: \"I'd like to edit a spreadsheet.\", 'Help me create a spreadsheet from scratch.', \"Let's build a financial model.\", 'Fix malformed rows in this CSV, please.', 'Fix malformed rows in this CSV.', 'compute formulas in Excel', 'convert CSV to xlsx', 'add a column', 'clean this messy data', 'Open this xlsx, please.', 'Compute formulas in Excel, please.', 'pls convert CSV to xlsx', 'pls add columns to a CSV', 'any way to fix malformed rows in this CSV?', and typo'd variants like 'build a finnacial model', 'fix malfored rows in this CSV', 'compute ormulas in Excel'. Also fires on indirect signals like 'this csv is a mess', 'the columns are all wrong in this sheet', 'I need to crunch some numbers in a sheet'. Trigger especially when the user references a spreadsheet file by name or path — even casually (like \"the xlsx in my downloads\") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document (`docx`), presentation (`pptx`), PDF (`pdf`), HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved."
 license: Proprietary. LICENSE.txt has complete terms
 ---
 

package/telegram-plugin/admin-commands/index.ts

@@ -21,11 +21,13 @@
  * middleware (via `makeAdminCommandMiddleware`) BEFORE its bot.command() calls;
  * the middleware redirects to handleInbound when admin=false.
  *
- * Out of scope for Phase 1
- * ────────────────────────
- * `/create-agent` has a complex multi-turn state machine (persisted wizard
- * state across messages). It is intentionally NOT included here and remains
- * foreman/server-only until Phase 2 or later.
+ * Out of scope
+ * ────────────
+ * `/create-agent` is a multi-turn wizard for onboarding a new agent
+ * from Telegram. Not implemented — operators run `switchroom agent
+ * add <name>` on the host. (The standalone foreman bot used to host
+ * this wizard; it was retired since the gateway-intercept model
+ * supersedes it.)
  */
 
 /**