squadrant 0.9.2 → 0.11.0

package/README.md

@@ -174,6 +174,60 @@ Pass `--direction right|left|up|down` to use a split pane instead of a tab. Stat
 - **Semantic heartbeat** — crews emit a lifecycle signal the captain reads as **CREW IDLE / QUIET / STALLED**, distinguishing "waiting for you" from "wedged" without scraping the pane ([#354](https://github.com/tu11aa/squadrant/issues/354)).
 - **`stopped` project status + orphan reap** — when a captain goes away, the daemon reaps its orphaned crews and marks the project `stopped` (intentional shutdown) rather than leaving stale tabs or faulting ([#324](https://github.com/tu11aa/squadrant/issues/324) / [#323](https://github.com/tu11aa/squadrant/issues/323) / [#388](https://github.com/tu11aa/squadrant/pull/388)).
 
+### Telegram (Two-Way, opt-in)
+
+Drive squadrant from your phone ([#65](https://github.com/tu11aa/squadrant/issues/65)). When a `telegram` block is present in config, a daemon-internal bridge:
+
+- **Outbound** — pushes each project's crew lifecycle events (CREW DONE / FAILED / BLOCKED / APPROVAL / INPUT / TIMEOUT / IDLE) and other captain notifications to that project's Telegram forum topic, filtered by a per-project **crew tier** (see [Notification tuning](#notification-tuning-per-project) below). Best-effort: a Telegram failure never delays or breaks delivery to the captain pane.
+- **Inbound (project topic)** — a message you send in a project's topic is delivered into that project's **captain pane** as a labeled `📩 [from Telegram]` message; the captain decides what to do with it. With remote control enabled (see below), if no captain is alive the daemon **auto-launches** one, then delivers ([#403](https://github.com/tu11aa/squadrant/issues/403)).
+- **General command channel** — slash commands in the supergroup's **General topic** run a curated set of squadrant operations from your phone ([#402](https://github.com/tu11aa/squadrant/issues/402)). Available: `/help`, `/status`, `/projects`, `/crews <project>`, `/launch <project>`, `/effort [max|balance|low]`, `/config get <key>`, `/config set <key> <value>`, `/spawn <project> <task…>`. Each maps to a validated CLI argv run via async `execFile` — never a shell passthrough. Unknown commands and freeform text get a `/help` hint.
+
+Absent the config block, the bridge is never constructed — zero behavior change. No runtime SDK is added (plain `fetch`; `@grammyjs/types` is a dev-only type dependency).
+
+**Setup (recommended):**
+1. Create a bot with [@BotFather](https://t.me/BotFather) and copy its token.
+2. Run `squadrant telegram setup` — it prompts for the bot token (input hidden), validates it via the Bot API, auto-detects your supergroup id, captures your Telegram user-id, and offers to enable remote control.
+3. Bind a project to a topic: `squadrant telegram link <project>` (creates the forum topic and records the binding).
+4. Check wiring with `squadrant telegram status`.
+
+**Setup (manual):**
+Put the token + ids in config (or export `TELEGRAM_BOT_TOKEN`) — see the `telegram` block under [Config](#config). Then run `squadrant telegram link <project>`.
+
+#### Security model (#321) — fail-closed remote control
+
+The control surfaces (auto-launch + General command channel) are **off by default** and gated by two independent checks. A control action runs **only when both** hold:
+
+1. `remoteControl: true` — an explicit opt-in master switch (default `false`).
+2. `message.from.id ∈ users[]` — the sender's Telegram **user-id** is on the allowlist. An empty/absent `users` list ⇒ control is disabled (fail-closed). Chat membership alone is **never** enough for control.
+
+When remote control is off (the default after upgrade), behavior is **exactly v1**: project-topic messages queue to the captain pane (no auto-launch), and General-topic slash commands are rejected with `⛔ not authorized`. Inbound text is always treated as data; only the curated registry maps to actions, and `/config set` is restricted to a default-deny writable-key allowlist (currently just `defaults.effort`) — **secrets (`botToken`, `users`, `chats`, `supergroupId`) can never be written over Telegram.**
+
+#### Notification tuning (per-project)
+
+Notifications resolve through a **layered config**: built-in defaults → global `config.json` (`telegram.notify`) → per-project `~/.config/squadrant/projects/<name>.json`, merged per key (overriding one key never resets its siblings). Two axes are independent:
+
+- **Live mute (`active`)** — system-tracked *session* state in `telegram-state.json`. Flipped by engagement (any message into a topic auto-unmutes), `/mute` / `/unmute` (Telegram), or `squadrant telegram notify <project> on|off`. The live value wins over the config default when present.
+- **Deliberate preferences (`crew`, `cap`)** — persistent settings in the per-project config file. Written by `squadrant telegram notify <project> crew <tier>` / `cap <on|off>` (CLI) or `/notify crew <tier>` / `/notify cap <on|off>` (Telegram, fail-closed behind remote control).
+
+**Crew tiers** (cumulative) select which lifecycle events reach a topic when active:
+
+| Tier | Events delivered |
+|---|---|
+| `none` | nothing |
+| `done_only` | `task.done`, `task.failed` |
+| `alert_only` *(default)* | `done_only` + `task.blocked`, `task.approval.requested`, `task.input.requested`, `task.timeout` |
+| `all` | every lifecycle event (incl. progress/heartbeat noise) |
+
+**`cap`** (default `on`) gates explicit captain pushes via `squadrant telegram send` — set `cap off` for a project to stop the captain DM-ing you there (independent of idle-mute; an explicit push is not dropped just because the topic is idle-muted).
+
+Config (deliberate prefs) and state (live toggles) are kept separate by design: `/unmute` flips your session, it does **not** rewrite your config file. An absent `projects/<name>.json` behaves exactly as the global defaults — the layer is fully additive, no migration. See `docs/superpowers/specs/2026-06-23-per-project-layered-config-design.md`.
+
+#### Remote wake (#403) — operator-side
+
+Auto-launch boots a captain when the **daemon is already running**. Waking a *sleeping Mac* from your phone (Wake-on-LAN / a relay that nudges the machine) is operator-side infrastructure, out of scope for this repo — see [#403](https://github.com/tu11aa/squadrant/issues/403) for the end-to-end flow.
+
+> **Interim note (link ↔ daemon 409):** the Telegram Bot API allows only one `getUpdates` consumer at a time. The `setup` wizard polls `getUpdates` to detect your group/user-id, so run it with the daemon stopped. `link` uses only `createForumTopic`, so it's unaffected.
+
 ### Projection (Cross-Agent Config Sync)
 
 Squadrant rules (Karpathy principles, captain-ops) and per-project AGENTS.md emit to each supported agent's canonical path via `squadrant projection emit`. User-level projection pushes squadrant's skills to `~/.cursor/rules/squadrant-global.mdc`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`. Project-level projection pushes a managed project's own `AGENTS.md` into `{project}/CLAUDE.md`, `{project}/.cursor/rules/squadrant.mdc`, `{project}/GEMINI.md` — zero squadrant-global content leaks into the project repo. Shared files use `<!-- squadrant:start --> ... <!-- squadrant:end -->` markers; dedicated files overwrite. See `docs/specs/archive/2026-04-24-plugin-system-projection-design.md`.
@@ -213,6 +267,14 @@ The user-level projection now also inlines `templates/captain.generic.md` and `t
   "runtime": "cmux",
   "workspace": "obsidian",
   "notifier": "cmux",
+  "telegram": {
+    "botToken": "123456:ABC...",
+    "supergroupId": -1001234567890,
+    "chats": [-1001234567890],
+    "users": [987654321],
+    "remoteControl": true,
+    "pollMs": 1000
+  },
   "projects": {
     "brove": {
       "path": "~/projects/brove",
@@ -242,6 +304,8 @@ The user-level projection now also inlines `templates/captain.generic.md` and `t
 }
 ```
 
+The `telegram` block is **optional** — omit it and the Telegram bridge is never constructed. `botToken` may be left out of the file and supplied via the `TELEGRAM_BOT_TOKEN` env var instead. `chats` is the inbound `chat_id` allowlist; `users` is the per-user-id allowlist for **control** actions and `remoteControl` (default `false`) is the master opt-in for auto-launch + the General command channel — both must be set for any remote control to act (fail-closed, [#321](https://github.com/tu11aa/squadrant/issues/321)). `pollMs` (default `1000`) is the inbound long-poll cadence. See [Telegram (Two-Way, opt-in)](#telegram-two-way-opt-in).
+
 ## Supported Agents
 
 | Agent | Status | Notes |