switchroom 0.8.1 → 0.10.0

package/README.md

@@ -60,7 +60,7 @@ So I built this.
 | Feature | What it does |
 |---|---|
 | **Progress cards** | Pinned, in-place, every tool call visible. The headline UX. |
-| **Claude Pro/Max auth** | OAuth, not API keys. No per-token billing. Multi-account fallback pool per agent. |
+| **Claude Pro/Max auth** | OAuth, not API keys. No per-token billing. Fleet-wide active account + fallback order; broker-owned refresh and credential fanout. |
 | **Approval kernel** | Inline allow/deny cards in Telegram for every gated tool. TTL'd grants, full audit trail. |
 | **Sub-agents** | Opus plans, Sonnet implements. Sub-agent work surfaces in the parent card. |
 | **Config cascade** | Defaults, then profiles, then per-agent YAML. Change one line, every agent updates. |
@@ -119,7 +119,7 @@ Each agent is a long-running service. They survive reboots, network drops, and y
 - **Auto-restart.** Agent containers come up with `restart: unless-stopped`, and each service has a healthcheck — a crashed or wedged agent is brought back automatically. No silent dropped work.
 - **Resume protocol.** When an agent reboots mid-turn, `start.sh` exports `SWITCHROOM_PENDING_TURN=true` plus the original chat / message ids. The agent's first action on boot is to acknowledge the gap and ask the user how to proceed (start over, summarise and continue, or drop it).
 - **Wake-audit.** On every fresh boot the agent checks for owed replies, orphan sub-agents, and stale in-progress todos. If everything's clean it stays quiet. If it owed you a reply, it tells you.
-- **Token refresh.** Runs unattended for weeks via a `refresh-tick` daemon. Multi-account fallback pool kicks in when the active slot hits its quota window.
+- **Token refresh.** The `switchroom-auth-broker` daemon owns the refresh loop and is the sole writer of every `credentials.json`. Per-account quota state fans out across the fleet in seconds; `auth.fallback_order` cycles when an account is exhausted.
 
 ## How it stacks up
 
@@ -138,75 +138,62 @@ The wedge against OpenClaw and NanoClaw isn't the substrate — it's the stock `
 
 ## Install
 
-Runs on the box you already have. The supported production runtime is Linux + Docker (Ubuntu 24.04 LTS with 4GB RAM is the canonical target; other Linux distros work with minor tweaks). `switchroom apply` scaffolds every agent and writes a `docker-compose.yml` from your `switchroom.yaml`; you bring the fleet up yourself with `docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d`. Five published images on GHCR (`switchroom-base`, `switchroom-agent`, `switchroom-broker`, `switchroom-kernel`, `switchroom-scheduler`) — no `docker build` on the operator's host. macOS (Docker Desktop) works for development but is not yet release-validated.
+Runs on the box you already have. The supported production runtime is Linux + Docker. **Canonical target: Ubuntu 24.04 LTS with ≥4 GiB RAM** (8 GiB recommended once you run more than one agent). Other Debian-derivatives work with the same script; non-apt distros need a manual prereq install. macOS (Docker Desktop) works for development but is not yet release-validated.
 
-> **Heads up on the package name.** The npm package was originally `switchroom-ai`. It's now just `switchroom`. The old name is deprecated and will stop receiving updates — `npm install -g switchroom` is the current path.
+> **Full new-user walkthrough — [`docs/install.md`](docs/install.md).** Zero to first Telegram message in ~15 minutes. Includes the [BotFather walkthrough](docs/botfather-walkthrough.md). Read that first if you're installing from scratch.
 
-### From inside Claude Code (the on-ramp)
+> **Heads up on the package name.** The npm package was originally `switchroom-ai`. It's now just `switchroom`. The old name is deprecated and will stop receiving updates — `npm install -g switchroom` is the current path.
 
-If you already use Claude Code, this is the shortest path. Inside any session:
+### Fresh Linux box — one script
 
-```
-/plugin marketplace add switchroom/switchroom
-/plugin install switchroom@switchroom
-/switchroom:setup
+```bash
+curl -fsSL https://github.com/switchroom/switchroom/raw/main/scripts/install-deps.sh | sudo bash
 ```
 
-`/switchroom:setup` walks you through deps, `switchroom setup` (Telegram + vault + first agent), and `switchroom agent start`. Day-to-day: `/switchroom:start`, `/switchroom:stop`, `/switchroom:status`. See [`docs/publishing.md`](docs/publishing.md).
+Installs Docker Engine + Compose v2, Node.js 20.11+, Bun, and the `@anthropic-ai/claude-code` + `switchroom` CLIs. Idempotent. Adds the invoking user to the `docker` group. Tested on Ubuntu 24.04 LTS and 26.04 LTS. Warns (does not block) on hosts under 4 GiB RAM.
 
-### One-liner (static binary)
+Then log out and back in so the docker group takes effect, and:
 
 ```bash
-curl -fsSL https://github.com/switchroom/switchroom/raw/main/install.sh | sh
+switchroom setup                       # interactive: Telegram + vault + first agent
+switchroom auth add me --from-oauth    # OAuth into your Claude Pro or Max account (one flow, fleet-wide)
+switchroom apply                       # write ~/.switchroom/compose/docker-compose.yml
+docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d
 ```
 
-Auto-detects your platform (linux / macos) and arch (amd64 / arm64), downloads the matching pre-built binary from the latest [GitHub release](https://github.com/switchroom/switchroom/releases/latest), verifies its SHA256, and drops it in `/usr/local/bin` (or `~/.local/bin` if not writable). Source is [`install.sh`](install.sh).
-
-The static binary still needs the `claude` CLI to run agents: `npm i -g @anthropic-ai/claude-code` (Node 20.11+).
+After the last command you talk to the agent from Telegram. You don't touch the server again.
 
-**Manual install** if you'd rather not pipe to sh:
+### Already have Docker + Node ≥ 20.11
 
 ```bash
-# Pick the artifact for your platform/arch from the latest release page
-curl -fsSL -o switchroom https://github.com/switchroom/switchroom/releases/latest/download/switchroom-linux-amd64
-chmod +x switchroom
-sudo mv switchroom /usr/local/bin/
+sudo npm install -g bun @anthropic-ai/claude-code switchroom
+switchroom setup
 ```
 
-Replace `switchroom-linux-amd64` with `switchroom-linux-arm64`, `switchroom-macos-amd64`, or `switchroom-macos-arm64` as needed. Verify against `switchroom-checksums.txt` from the same release.
+`bun` is a hard runtime dep — the `switchroom` CLI's entrypoint is a Bun script. A Node-only CLI build is on the roadmap but not yet shipped.
 
-**macOS Gatekeeper note.** Releases are not yet Apple-code-signed. After installing on macOS you may need to clear the quarantine xattr so the binary will run: `xattr -d com.apple.quarantine /usr/local/bin/switchroom`. The `install.sh` one-liner handles this automatically.
-
-**Mac (Sequoia+) one-time.** macOS 15 adds a second-stage notarization check that the `xattr` strip alone does not bypass — you may still see a Gatekeeper "cannot verify the developer" dialog the first time you run `switchroom`. `install.sh` attempts `sudo spctl --add /usr/local/bin/switchroom` automatically (best-effort, ignored if sudo isn't available). If the dialog still fires, run that `spctl --add` manually, or open System Settings → Privacy & Security → "Open Anyway" once.
+### From inside Claude Code (the on-ramp)
 
-Then:
+If you already use Claude Code, this is the shortest path. Inside any session:
 
-```bash
-switchroom setup                                        # interactive Telegram wiring
-switchroom agent create coach --profile health-coach    # scaffold your first agent
-switchroom auth login coach                             # link your Pro or Max session
-switchroom apply                                        # write docker-compose.yml
-docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d
+```
+/plugin marketplace add switchroom/switchroom
+/plugin install switchroom@switchroom
+/switchroom:setup
 ```
 
-After the last command you talk to the agent from Telegram. You don't touch the server again.
-
-### Already have node?
+`/switchroom:setup` walks you through deps, `switchroom setup` (Telegram + vault + first agent), and `switchroom agent start`. Day-to-day: `/switchroom:start`, `/switchroom:stop`, `/switchroom:status`. See [`docs/publishing.md`](docs/publishing.md).
 
-```bash
-npm install -g @anthropic-ai/claude-code switchroom
-switchroom setup
-```
+### Static binary (planned, not yet shipped)
 
-Node 20.11+. `switchroom setup` is the interactive first-time wizard. Scaffolds config, handles Telegram wiring, sets up the vault.
+Pre-built single-binary releases (no Node or Bun required on the host) are scaffolded in [`install.sh`](install.sh) and referenced from the GitHub Releases page, but **the release workflow that publishes those binaries does not yet exist**. Until v0.9, use the one-script or npm paths above. Tracking work: switching the release pipeline to actually upload `switchroom-linux-{amd64,arm64}` and `switchroom-macos-{amd64,arm64}` on every tag.
 
 ### One-shot happy path (no wizard)
 
-If you already have Telegram credentials in `~/.switchroom/switchroom.yaml`, skip `switchroom setup`. `agent create --profile` writes a minimal entry for you, and auth is scoped per-agent:
+If you already have Telegram credentials in `~/.switchroom/switchroom.yaml` and one Anthropic account already added, skip `switchroom setup`. `agent create --profile` writes a minimal entry; the new agent inherits the fleet-wide active account automatically — no per-agent OAuth flow:
 
 ```bash
 switchroom agent create coach --profile health-coach
-switchroom auth login coach
 switchroom apply && docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d
 ```
 
@@ -336,26 +323,29 @@ If the agent is already in yaml, `--profile` must match the existing `extends:`
 
 Model aliases: the bare names `opus`, `sonnet`, `haiku` are accepted alongside the full IDs (`claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5`). Use whichever reads cleaner in your config.
 
-### Authentication (multi-account slot pool)
+### Authentication (one OAuth, many agents)
 
-Each agent has a pool of Claude OAuth slots. The **active** slot is what the agent uses; other slots are automatic fallbacks when the active slot hits its quota window. Every `<slot>` option defaults to the active slot if omitted.
+The **Anthropic account is 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`. Per-account quota state fans out across the fleet in seconds. See [`docs/auth.md`](docs/auth.md) for the full operator guide.
 
 ```bash
-switchroom auth status                            # All agents, one table
-switchroom auth login <agent>                     # First-time OAuth into the active slot
-switchroom auth code <agent> <browser-code>       # Paste the code back from the browser
-switchroom auth cancel <agent>                    # Abandon a pending login
-switchroom auth reauth <agent> [--slot <s>]       # Fresh OAuth, replace existing token
-switchroom auth refresh <agent>                   # Alias for reauth (back-compat)
-switchroom auth refresh-tick [--threshold-ms N]   # Daemon: rotate tokens nearing expiry (cron/timer)
-
-switchroom auth add <agent> [--slot <name>]       # Add another account to the fallback pool
-switchroom auth use <agent> <slot>                # Switch the active slot
-switchroom auth list <agent> [--json]             # Show slots: health, quota status, expiry
-switchroom auth rm <agent> <slot> [--force]       # Remove a slot (refuses active/last slot)
+switchroom auth add <label> --from-oauth          # New account via OAuth (one flow per Anthropic account)
+switchroom auth add <label> --from-agent <name>   # Seed from an existing agent's creds
+switchroom auth add <label> --from-credentials <path>  # Import a credentials.json
+switchroom auth add <label> --from-oauth --replace     # Re-auth an existing label (drift recovery)
+
+switchroom auth list                              # Accounts + health + which one is fleet-active
+switchroom auth show [agent]                      # Full snapshot (fleet + agents + consumers), or one agent
+switchroom auth use <label>                       # Fleet-wide active swap
+switchroom auth rotate                            # Cycle to next non-exhausted in fallback_order
+switchroom auth rm <label>                        # Remove an account (refused if it's the only one)
+
+switchroom auth agent override <agent> <label>    # Edge case: one agent on a different account
+switchroom auth agent override <agent> --clear    # Back to fleet active
+
+switchroom auth refresh [label]                   # Diagnostic: force a refresh tick
 ```
 
-The fallback pool also works from Telegram. The switchroom MCP plugin exposes the same verbs as `/auth add|use|list|rm` inside the chat.
+The same surface is reachable from Telegram in any agent's chat: `/auth show` (read-only), `/auth use <label>`, `/auth rotate`. Mutating verbs are admin-gated against the per-agent `admin: true` flag (the same flag that gates `/agents`, `/restart`, `/update`, etc.). One knob to make an agent the fleet control panel.
 
 ### Workspace (agent bootstrap layer)
 
@@ -416,6 +406,8 @@ Overlay entries win on collision with built-in defaults. Unknown files that appe
 
 | Guide | Description |
 |---|---|
+| **[Install](docs/install.md)** | Zero-to-first-message new-user walkthrough |
+| **[BotFather walkthrough](docs/botfather-walkthrough.md)** | Step-by-step bot creation in Telegram |
 | **[Changelog](CHANGELOG.md)** | Release notes, every version |
 | **[Configuration](docs/configuration.md)** | Full field reference, cascade semantics, profiles |
 | **[Vault](docs/vault.md)** | Architecture, per-cron secrets, ACL, audit log, threat model |

package/bin/timezone-hook.sh

@@ -10,16 +10,18 @@
 # This hook fires on every UserPromptSubmit and prints a one-line hint that
 # Claude Code prepends to the prompt as additionalContext, so the LLM sees
 # fresh local time each turn. The resolved zone is passed in via
-# SWITCHROOM_TIMEZONE (baked into the agent's systemd unit at scaffold/
-# reconcile time). If unset we fall back to UTC — same default as the
-# resolver — so the hook never fails loudly.
+# SWITCHROOM_TIMEZONE (set in the agent container's `environment:` block by
+# the compose generator at `switchroom apply` time — see
+# src/agents/compose.ts). If unset we fall back to UTC — same default as
+# the resolver — so the hook never fails loudly.
 #
 # Stale-install detection: when SWITCHROOM_TIMEZONE is unset we also annotate
 # the hint with an in-band WARNING. This makes the failure visible to the
 # agent (and thus to the user), rather than silently emitting "UTC" while the
-# operator's real zone is Australia/Melbourne. Typical cause: an install
-# upgraded past the timezone-awareness PR without re-running
-# `switchroom systemd install` to refresh the unit files.
+# operator's real zone is Australia/Melbourne. Typical cause: the compose
+# env block is stale because `switchroom apply` hasn't run since the
+# operator added a `timezone:` cascade entry (or the agent container was
+# rebuilt from an image that predates the #1198 compose-TZ wiring fix).
 #
 # Failure modes are silent: hooks that error block the turn in Claude Code,
 # and a missing timezone hint is never worse than no hint at all.
@@ -46,7 +48,7 @@ ROUNDED=$(( NOW_UNIX - (NOW_UNIX % 900) ))
 NOW=$(TZ="$TZ_VAL" date -d "@$ROUNDED" '+%Y-%m-%d %H:%M %Z (UTC%:z)')
 
 if [ "$TZ_UNSET" = "1" ]; then
-  MSG="Current local time: $NOW ($TZ_VAL — WARNING: SWITCHROOM_TIMEZONE unset; systemd unit may be stale, run \`switchroom systemd install\` to refresh)"
+  MSG="Current local time: $NOW ($TZ_VAL — WARNING: SWITCHROOM_TIMEZONE unset; compose env may be stale, run \`switchroom apply && switchroom agent restart <agent>\` to refresh)"
 else
   MSG="Current local time: $NOW ($TZ_VAL)"
 fi