switchroom 0.8.1 → 0.11.0

package/skills/switchroom-runtime/SKILL.md

@@ -1,21 +1,49 @@
 ---
 name: switchroom-runtime
 description: |
-  Runtime operational protocols for switchroom Telegram agents — the conditional
-  procedures that only fire on specific boot signals or user phrases. Invoke when:
-  (1) the env var SWITCHROOM_PENDING_TURN=true is set on boot (interrupted-turn
-  resume protocol); (2) the sentinel file $TELEGRAM_STATE_DIR/.wake-audit-pending
-  exists (wake audit: check for owed replies, orphan sub-agents, stale todos
-  before answering); (3) the user asks why you restarted or what happened
-  ("why did you restart?", "did you crash?", "you went away") — surface the
-  audit trail from clean-shutdown.json + container/journal logs; (4) the user
-  asks how to stop you mid-turn ("how do I interrupt", "can I stop you",
-  "how do I cancel") and you need the implementation detail beyond the
-  one-line answer; (5) the user sends a short status check ("status?",
-  "still there?", "any update?") — treat as UX-failure signal, offer to file
-  RCA via /file-bug. Do NOT invoke 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
+  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
 ---
@@ -137,3 +165,27 @@ Your response should:
 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

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/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/dispatch.test.ts

@@ -41,7 +41,7 @@ describe('parseCommandName', () => {
 
 describe('ADMIN_COMMAND_NAMES', () => {
   it('contains the fleet-management admin commands', () => {
-    const required = ['agents', 'logs', 'restart', 'update', 'reconcile', 'stop', 'agentstart', 'grant', 'dangerous', 'permissions', 'vault']
+    const required = ['agents', 'logs', 'restart', 'update', 'reconcile', 'stop', 'agentstart', 'grant', 'dangerous', 'permissions', 'vault', 'audit']
     for (const cmd of required) {
       expect(ADMIN_COMMAND_NAMES.has(cmd)).toBe(true)
     }

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.)
  */
 
 /**
@@ -59,6 +61,8 @@ export const ADMIN_COMMAND_NAMES = new Set<string>([
   // Per-agent ops that read shared fleet state via the switchroom CLI
   'memory',
   'topics',
+  // Observability of privileged-verb history
+  'audit',
 ])
 
 /**