squadrant 0.13.5 → 0.14.1

package/README.md

@@ -1,310 +1,79 @@
 # Squadrant
 
-Multi-project orchestration layer for coding agents. One command session controls everything.
+Run your coding agents like an engineering team. You're the manager —
+Squadrant gives you **captains** who plan and delegate, and **crews** who
+write the code.
 
-> **Direction:** Squadrant is moving to support all major coding agents — Claude Code, Codex, Cursor, Gemini CLI — not just Claude Code. Claude Code is the reference implementation today; other agents land through the plugin system's driver abstractions and the upcoming cross-agent projection layer ([#31](https://github.com/tu11aa/squadrant/issues/31)). See [`docs/specs/2026-04-24-multi-agent-direction.md`](docs/specs/2026-04-24-multi-agent-direction.md).
-
-## How It Works
+## The mental model
 
 ```
-squadrant launch <project>          → Captain (per project, in cmux)
-squadrant launch --all              → Every Captain
-squadrant command --task briefing   → One-shot Command session in a split pane
-                                       (also: --task learnings-review | wiki-aggregate)
-Captain → squadrant crew spawn …    → Crew (new tab in the captain workspace, fresh agent CLI)
+You
+ │
+ ├── squadrant launch <project>   →  Captain (project A)
+ │                                     │
+ │                                     └── squadrant crew spawn  →  Crew, Crew, …
+ │
+ └── squadrant launch <project-2> →  Captain (project B)
+                                        └── …
 ```
 
-1. **`squadrant init`** — first-time setup
-2. **`squadrant launch <project>`** — start the project's captain in cmux
-3. **`squadrant launch --all`** — start every captain at once
-4. **`squadrant command --task briefing`** — on-demand Command session for cross-project work (optional; spawns in a split pane and exits when done)
-5. **`squadrant status`** — quick status check without spawning anything
+- **You** — set direction, make the calls only you can make.
+- **Captain** — one per project, lives in cmux, plans and delegates. Your
+  standing project lead.
+- **Crew** — a fresh interactive sub-session the captain spawns to actually
+  write the code, then reports back and signals when it's done or blocked.
 
-## Install
+One person, operating like an engineering org.
 
-```bash
-npm i -g squadrant               # global `squadrant` CLI (alias: `squad`)
-squadrant init
-squadrant doctor
-```
+> Squadrant is also moving to support every major coding agent — Claude Code,
+> Codex, Cursor, Gemini CLI — not just Claude Code. Claude Code is the
+> reference implementation today; other agents land through the plugin
+> system's driver abstractions and the upcoming cross-agent projection layer
+> ([#31](https://github.com/tu11aa/squadrant/issues/31)). See
+> [`docs/specs/2026-04-24-multi-agent-direction.md`](docs/specs/2026-04-24-multi-agent-direction.md).
 
-Or from source:
+## Why you'd want it
 
-```bash
-git clone https://github.com/tu11aa/squadrant.git
-cd squadrant
-pnpm install
-pnpm build                       # produces dist/index.js (the squadrant bin)
-npm link                         # symlinks the global `squadrant`/`squad` to dist/index.js
-squadrant init
-squadrant doctor
-```
+- **Run several projects at once** — one captain per project, each with its
+  own context, all supervised from the same session.
+- **Delegate instead of micromanage** — hand a task to a crew and let it
+  work; you don't watch every keystroke.
+- **Agents signal you, not the other way around** — crews report **CREW
+  DONE** / **CREW BLOCKED** / **CREW NEEDS INPUT** instead of you polling a
+  pane to see if it's finished.
+- **Drive it from your phone** — optional two-way Telegram bridge, so you can
+  delegate and get notified without being at your desk.
 
-> Squadrant was formerly published/developed as `claude-cockpit`; it was rebranded in 0.9.0 as it grew into a multi-agent orchestration layer.
+## What it feels like
 
-## Prerequisites
-
-- [Claude Code](https://claude.ai/code) >= 2.1.32
-- [cmux](https://cmux.dev) (macOS terminal for coding agents)
-- [Obsidian](https://obsidian.md) (status tracking)
-- Node.js >= 18
-
-### Required Integrations
-
-```bash
-# Claude Memory — cross-session continuity
-/plugin marketplace add thedotmack/claude-mem
-/plugin install claude-mem
-
-# Task Master — PRD decomposition (works via Max subscription)
-npm install -g task-master-ai
-
-# GSD — wave-based execution for crew (fresh context per step)
-npx get-shit-done-cc@latest --claude --global
 ```
+squadrant launch brove
+  → Captain boots in cmux
 
-See `core/plugins.md` for full plugin setup.
-
-### Obsidian Plugins
-
-See `obsidian/plugins.md` for Dataview, Templater setup.
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `squadrant init` | First-time setup — config, hub vault, scripts |
-| `squadrant launch <project>` | Start a specific project captain |
-| `squadrant launch --all` | Launch all captain workspaces |
-| `squadrant command [--task <briefing\|learnings-review\|wiki-aggregate>] [--agent <a>]` | Spawn a one-shot Command session in a split pane (no persistent Command). |
-| `squadrant status` | Show all project status (no Claude needed) |
-| `squadrant standup` | Daily standup summary (zero LLM tokens) |
-| `squadrant doctor` | Health check — verify dependencies |
-| `squadrant projects list` | List registered projects |
-| `squadrant projects add <name> <path>` | Register a project |
-| `squadrant projects remove <name>` | Unregister a project |
-| `squadrant dashboard [--once]` | Print a one-shot status grid for all projects to the terminal. |
-| `squadrant dashboard --pane [--direction <dir>] [--interval <s>]` | Open a refreshing sidebar pane in the current cmux workspace. |
-| `squadrant dashboard sync-hub [--json]` | Mirror spoke `status.md` files into `{hubVault}/projects/` for Obsidian Dataview. |
-| `squadrant runtime status <project>` | Check if a project's captain workspace is running |
-| `squadrant runtime send <project> <msg>` | Send a message to a captain workspace (auto-Enter) |
-| `squadrant runtime list` | List all workspaces from the active runtime |
-| `squadrant workspace read <project> <path>` | Read a scope-relative file from the project's spoke vault |
-| `squadrant workspace list <project> <dir>` | List entries in a spoke vault directory |
-| `squadrant workspace read --hub <path>` | Read from the hub vault |
-| `squadrant notify <message>` | Send a message to the user via the configured notifier |
-| `squadrant projection emit [--scope user\|project] [--project <name>] [--target <name>] [--all]` | Emit squadrant rules + skills to Cursor/Codex/Gemini config files |
-| `squadrant projection diff [same flags]` | Preview projection changes without writing |
-| `squadrant projection list` | Show registered projection targets and their destinations |
-| `squadrant crew spawn <project> <task> [--name <n>] [--direction tab\|right\|left\|up\|down] [--agent <a>]` | Spawn an interactive crew sub-session (tab in the captain workspace by default; `--direction` for a pane) |
-| `squadrant crew send <project> <name> <message>` | Send a follow-up turn to an existing crew |
-| `squadrant crew read <project> <name>` | Read a crew session's current screen |
-| `squadrant crew close <project> <name>` | Shutdown a crew session (closes its tab) |
-| `squadrant crew list <project>` | List live crews for a project |
-| `squadrant shutdown [project]` | Graceful shutdown |
-| `squadrant effort [max\|balance\|low]` | Get or set the global crew tokenomics dial (no arg prints current) |
-| `squadrant retro` | Generate a retro (weekly/sprint summary) from daily logs and git (zero tokens) |
-| `squadrant config check` | Detect config drift vs the current default schema |
-| `squadrant heal [--dry-run\|daemon]` | Targeted, idempotent remediation for squadrant components (daemon, health) |
-| `squadrant group dispatch …` | Cross-project intra-group operations (dispatch a task to a sibling project) |
-| `squadrant cmux …` | cmux integration helpers |
-| `squadrant feedback` | Open opt-in feedback issue |
-
-## Monorepo structure
-
-Six internal packages in a one-way dependency DAG. All are private (not published to npm).
-
-| Package | Owns | Notes |
-|---|---|---|
-| `@squadrant/shared` | Config schema, TypeScript types, constants | Leaf lib — zero internal deps |
-| `@squadrant/core` | Daemon logic, state-machine, protocol, `AgentDriver` interface, task/crew bus | No concrete drivers — pure interfaces + orchestration |
-| `@squadrant/agents` | AI driver seam — `claude`, `codex`, `opencode`, `gemini` drivers + registry | Implements `AgentDriver`. Add a new AI agent here. |
-| `@squadrant/workspaces` | Runtime (cmux), workspace (obsidian), notifier (cmux) drivers + registries | Implements surface/workspace/notifier seams |
-| `@squadrant/web` | Observability dashboard — bundled HTML/JS served by CLI | Read-only UI; inlined by CLI's tsup build |
-| `@squadrant/cli` | Commands, bin entry, daemon host, templates, plugin dir | Root — depends on all other packages |
-
-**Dependency DAG:** `shared ◄ core ◄ {agents, workspaces, web} ◄ cli`
-
-**Build outputs** (`pnpm build` via tsup, all internal packages inlined):
-- `dist/index.js` — CLI bin (`squadrant` command), entry: `packages/cli/src/index.ts`
-- `dist/squadrantd.js` — daemon process, entry: `packages/cli/src/daemon-host.ts`
-
-See the [architecture diagram](docs/diagrams/2026-06-18-squadrant-monorepo-architecture.html) for a visual overview.
-
-## Architecture
-
-### Roles
-
-- **Command** (Opus) — *on-demand* cross-project session. Spawned by `squadrant command --task <briefing|learnings-review|wiki-aggregate>` in a split pane; exits when the task completes. No persistent Command process.
-- **Captain** (Opus) — project leader, uses Agent Teams + git worktrees
-- **Crew** (Sonnet by default) — interactive sub-session running as a new tab in the captain's workspace (or a split pane via `--direction`). Each crew is named (`crew-1`, `crew-2`, …) and stays idle between turns waiting for the captain's next message — same model as a Claude Agent Team subagent. Spawn with `squadrant crew spawn`, send follow-ups with `squadrant crew send`, close when done. Works with any agent CLI (claude and opencode are fully interactive; codex/gemini currently print-mode). Uses GSD for complex tasks.
-
-### Model Routing
-
-Each role runs on the optimal model for cost/quality tradeoff. Configured in `config.json`:
-- Command/Captain/Review: Opus (coordination + quality)
-- Crew: Sonnet (execution)
-- Exploration: Haiku (cheap lookups)
-
-### Runtime Abstraction
-
-Workspaces run on a pluggable **runtime driver** (currently only `cmux`). Each project may override the global default via its `runtime` field. Bash scripts call `squadrant runtime <op>` to talk to the configured runtime instead of any specific binary. New runtimes (tmux, Docker, SSH) are added as driver files in `@squadrant/workspaces` (`packages/workspaces/runtimes/`) — see `docs/specs/archive/2026-04-20-plugin-system-runtime-design.md`.
-
-### Workspace Abstraction
-
-Vault storage (hub + per-project spokes) runs behind a pluggable **workspace driver** (currently only `obsidian`). Filesystem operations — `read`, `write`, `list`, `exists`, `mkdir` — go through the driver instead of `fs` directly. Each project may override the global default via its `workspace` field. Bash scripts call `squadrant workspace <op>` to read/write vault data without hardcoding paths. New backends (Notion, plain-md, S3) are added as driver files in `@squadrant/workspaces` (`packages/workspaces/workspaces/`) — see `docs/specs/archive/2026-04-21-plugin-system-workspace-design.md`.
-
-### Notifier Abstraction
-
-User-facing notifications run behind a pluggable **notifier driver** (currently only `cmux`). Escalations and other "tell the user" events go through `squadrant notify <message>`. The default `CmuxNotifier` delegates to `squadrant runtime send --command` — the abstraction exists as a swap-point for future Slack/Discord/email/pager drivers. Notifier is global (no per-project override). See `docs/specs/archive/2026-04-21-plugin-system-notifier-design.md`.
-
-### Crew Spawn (Interactive Sub-Sessions)
-
-Crew is the captain's equivalent of an Agent Team subagent — but runtime-agnostic. The captain spawns a crew via `squadrant crew spawn <project> "<task>" [--name <n>]`, which opens a new tab in the captain's cmux workspace, boots an interactive Claude session (no `-p`), and sends the task as the first turn. The crew works on it and **stays idle** waiting for follow-ups. The captain drives the session with `squadrant crew send/read/close/list`, addressing each crew by its tab title (`🔧 <project>:<name>`).
+You (in the captain pane): "build the export-to-CSV feature"
+  → Captain spawns a crew: squadrant crew spawn brove "build export-to-CSV"
 
-Pass `--direction right|left|up|down` to use a split pane instead of a tab. State lives in the surface buffer + git; tabs die with the captain workspace on `squadrant shutdown`. Non-Claude agents (codex/gemini) currently still launch in print-mode; full interactive support is a follow-up. See [`docs/specs/archive/2026-05-05-squadrant-thin-redirect-design.md`](docs/specs/archive/2026-05-05-squadrant-thin-redirect-design.md).
+  → Crew works in its own tab, writes the code, runs tests
 
-### Effort Dial (Tokenomics)
-
-`squadrant effort max|balance|low` is a single global dial that biases how aggressively crews consume tokens — a captain-discretion signal, not mechanical routing. `max` favors quality/tokens, `low` biases toward economy (e.g. preferring opencode for cheap work); `balance` sits between. Run `squadrant effort` with no argument to print the current setting. The value lives in config and is honored by captains via the captain-ops playbook ([#317](https://github.com/tu11aa/squadrant/issues/317) / [#381](https://github.com/tu11aa/squadrant/pull/381)).
-
-### Crew Lifecycle & Delivery
-
-- **Daemon-direct delivery** — crew turns and handoffs are delivered straight to the cmux surface by the daemon. The old `notify-relay` supervisor was deleted; there is no relay process to keep alive ([#332](https://github.com/tu11aa/squadrant/issues/332)).
-- **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`.
-
-The user-level projection now also inlines `templates/captain.generic.md` and `templates/crew.generic.md` as `## Captain Role` / `## Crew Role` sections inside the squadrant marker block, so non-Claude agents (Codex, Gemini, Cursor) load the same role descriptions Claude Code loads via `--append-system-prompt-file`. See `docs/specs/archive/2026-05-05-multi-agent-template-parity-plan.md` (#45).
-
-### Obsidian Vaults (Hub-and-Spoke)
-
-- **Hub vault** (`~/squadrant-hub`) — cross-project dashboard + hub wiki
-- **Spoke vaults** — per-project status, learnings, and wiki
-
-### Knowledge System (opt-in writes)
-
-- **Status (opt-in)** — captains record `{spokeVault}/status.md` via `write-status.sh` (also written by the captain session-end hook) when there's something worth noting (a blocker, "starting work on X"). Not on a schedule.
-- **Dashboard** — `squadrant dashboard --pane` opens a refreshing sidebar pane in cmux that lists every project's live state, queried from the squadrant daemon's task records. `squadrant dashboard sync-hub` mirrors each spoke `status.md` into `{hubVault}/projects/` so the hub vault's `dashboard.md` Dataview query renders the same data inside Obsidian.
-- **Handoff files** — captain writes when in-flight work needs to survive into tomorrow; skipped on uneventful sessions.
-- **Daily logs** — captain writes when the day produced something worth a log; not on a schedule.
-- **Learnings** — recorded when a captain encounters a genuinely surprising or reusable pattern.
-- **Wiki** — compiled, indexed knowledge pages in spoke vaults (`wiki/pages/`); promoted from learnings when worth maintaining.
-- **Hub Wiki** — cross-project knowledge aggregated by an on-demand `squadrant command --task wiki-aggregate` run.
-- Scripts: `wiki-ingest.sh`, `wiki-query.sh`, `wiki-log.sh`.
-
-### Session Continuity
-
-- **Handoff files** — captain writes context on shutdown, reads on startup
-- **Session freshness** — auto-detects new day or template changes, forces fresh context
-- **claude-mem** — cross-session memory via MCP plugin
+  → 🎉 CREW DONE — captain reviews, merges or follows up
+```
 
-## Config
+Full walkthrough, including your first captain and crew, step by step: see
+[QUICKSTART.md](QUICKSTART.md).
 
-`~/.config/squadrant/config.json`
+## Install
 
-```json
-{
-  "commandName": "command",
-  "hubVault": "~/squadrant-hub",
-  "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",
-      "captainName": "brove-captain",
-      "spokeVault": "~/squadrant-hub/spokes/brove",
-      "host": "local",
-      "runtime": "cmux",
-      "workspace": "obsidian",
-    }
-  },
-  "defaults": {
-    "maxCrew": 5,
-    "worktreeDir": ".worktrees",
-    "teammateMode": "in-process",
-    "permissions": {
-      "command": "default",
-      "captain": "acceptEdits"
-    },
-    "models": {
-      "command": "opus",
-      "captain": "opus",
-      "crew": "sonnet",
-      "exploration": "haiku",
-      "review": "opus"
-    }
-  }
-}
+```bash
+npm i -g squadrant               # global `squadrant` CLI (alias: `squad`)
+squadrant init
+squadrant doctor
 ```
 
-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).
+See [QUICKSTART.md](QUICKSTART.md) for prerequisites, the from-source build,
+and a guided first run.
+
+> Squadrant was formerly published/developed as `claude-cockpit`; it was
+> rebranded in 0.9.0 as it grew into a multi-agent orchestration layer.
 
 ## Supported Agents
 
@@ -316,7 +85,19 @@ The `telegram` block is **optional** — omit it and the Telegram bridge is neve
 | Gemini CLI | ✅ projection (skills + roles) | Captain/crew roles inlined into `~/.gemini/GEMINI.md` (#45). |
 | opencode | ✅ driver + projection (interactive crew) | `opencode run "<prompt>"` with `--format json` / `-m <model>`; AGENTS.md projects to `~/.config/opencode/AGENTS.md`. |
 
-Cross-agent config sync (one canonical source → agent-specific formats) is tracked in [#31](https://github.com/tu11aa/squadrant/issues/31).
+Cross-agent config sync (one canonical source → agent-specific formats) is
+tracked in [#31](https://github.com/tu11aa/squadrant/issues/31).
+
+## Where to go next
+
+- [QUICKSTART.md](QUICKSTART.md) — hands-on first run: install, first
+  captain, first crew, optional Telegram
+- [Architecture diagram](docs/diagrams/2026-06-18-squadrant-monorepo-architecture.html)
+  — visual overview of the monorepo
+- [docs/reference.md](docs/reference.md) — full command table, monorepo
+  structure, architecture deep-dive, Telegram integration, config schema
+- [CONTRIBUTING.md](CONTRIBUTING.md) — setup, branching, and conventions for
+  contributing
 
 ## Inspirations
 

package/dist/index.js

@@ -3773,6 +3773,8 @@ var init_cmux_store_source = __esm({
       debounceTimer;
       /** taskId → last reported snapshot (for snapshot() liveness floor). */
       cache = /* @__PURE__ */ new Map();
+      active = false;
+      lastError = null;
       constructor(opts = {}) {
         this.stateDir = opts.stateDir ?? process.env.CMUX_AGENT_HOOK_STATE_DIR ?? join13(homedir8(), ".cmuxterm");
         this.debounceMs = opts.debounceMs ?? 50;
@@ -3788,10 +3790,13 @@ var init_cmux_store_source = __esm({
       }
       start(deps) {
         this.deps = deps;
+        this.active = true;
+        this.lastError = null;
         this.scan();
         try {
           this.stopWatcher = this.watchDir(this.stateDir, () => this.scheduleDebounced());
         } catch (e) {
+          this.lastError = e.message;
           this.log(`cmux-store: failed to watch ${this.stateDir}: ${e.message}`);
         }
       }
@@ -3804,11 +3809,16 @@ var init_cmux_store_source = __esm({
         this.stopWatcher = void 0;
         this.deps = void 0;
         this.cache.clear();
+        this.active = false;
       }
       /** Returns the last-reported snapshot for a known crew (liveness floor). */
       snapshot(taskId) {
         return this.cache.get(taskId);
       }
+      /** Read-only source health (B4 — dashboard visibility into which sources are up). */
+      health() {
+        return { active: this.active, error: this.lastError };
+      }
       // ── private ─────────────────────────────────────────────────────────────────
       scheduleDebounced() {
         if (this.debounceTimer !== void 0) {
@@ -3989,6 +3999,7 @@ var init_native_hook_source = __esm({
       deps;
       /** taskId → last-reported snapshot, for snapshot() liveness floor. */
       cache = /* @__PURE__ */ new Map();
+      active = false;
       constructor(opts = {}) {
         this.hookInstall = opts.hookInstall ?? {};
         this.log = opts.log ?? (() => {
@@ -3996,15 +4007,21 @@ var init_native_hook_source = __esm({
       }
       start(deps) {
         this.deps = deps;
+        this.active = true;
       }
       stop() {
         this.deps = void 0;
         this.cache.clear();
+        this.active = false;
       }
       /** Returns the last-reported snapshot for a known crew (liveness floor poll). */
       snapshot(taskId) {
         return this.cache.get(taskId);
       }
+      /** Read-only source health (B4). Purely push-driven — never errors on its own. */
+      health() {
+        return { active: this.active, error: null };
+      }
       /**
        * Install squadrant-owned hooks into ~/.claude/settings.json.
        * Idempotent — safe to call on every project init or crew spawn.
@@ -5229,17 +5246,24 @@ var init_codex_app_server_source = __esm({
       deps;
       /** taskId → last reported snapshot (for snapshot() liveness floor). */
       cache = /* @__PURE__ */ new Map();
+      active = false;
       start(deps) {
         this.deps = deps;
+        this.active = true;
       }
       stop() {
         this.deps = void 0;
         this.cache.clear();
+        this.active = false;
       }
       /** Returns the last-reported snapshot for a known crew (liveness floor). */
       snapshot(taskId) {
         return this.cache.get(taskId);
       }
+      /** Read-only source health (B4). Purely push-driven — never errors on its own. */
+      health() {
+        return { active: this.active, error: null };
+      }
       /**
        * Feed a ControlEvent from CodexInteractiveDriver into this source.
        * The daemon wires: emit = (ev) => { source.observe(ev); handle(ev); }
@@ -8552,7 +8576,7 @@ function collect(snap) {
   ];
   const daemonStates = [];
   const projStates = [];
-  let errors = 0, behind = 0, crewAgeMs = 0;
+  let errors = 0, behind = 0, crewAgeMs = 0, undelivered = 0, maxDeferCount = 0;
   if (snap.daemon !== "unreachable") {
     const t0 = snap.daemon.tier0;
     daemonStates.push("alive");
@@ -8563,12 +8587,15 @@ function collect(snap) {
       projStates.push(c.state);
       if (c.kind === "crew" && c.lastSeenMs != null)
         crewAgeMs = Math.max(crewAgeMs, now - c.lastSeenMs);
+      if (c.kind === "crew" && c.detail?.startsWith("undelivered"))
+        undelivered++;
     }
     for (const p of snap.daemon.tier2.projects) {
       if (p.delivery.behind > 0)
         projStates.push("stale");
       if (p.store.corruptCount > 0)
         projStates.push("gone");
+      maxDeferCount = Math.max(maxDeferCount, p.deferral.maxDeferCount);
     }
     behind = liveDeliveryBehind(snap.daemon);
   }
@@ -8580,7 +8607,9 @@ function collect(snap) {
     overall: tally([...daemonStates, ...projStates, ...envStates]),
     errors,
     behind,
-    crewAgeMs
+    crewAgeMs,
+    undelivered,
+    maxDeferCount
   };
 }
 function sectionHead(title, sub) {
@@ -8607,11 +8636,14 @@ function renderOverview(snap, col) {
   const word = linkLost ? "LINK LOST" : MASTER_WORD[mc];
   const out = [`<section class="panel" data-panel="overview" role="tabpanel" aria-label="Overview">`];
   out.push(sectionHead("System Health", `${col.overall.alive} of ${col.overall.total} monitored components are alive \u2014 the ring shows the full breakdown by state.`));
+  if (col.undelivered > 0) {
+    out.push(banner("warn", `\u26A0 ${col.undelivered} CREW${col.undelivered > 1 ? "S" : ""} UNDELIVERED \u2014 first turn may not have landed; re-send the task or check the spawn (see Projects tab)`));
+  }
   out.push(`<div class="hero a-${mc}">`, `<div class="gauge">`, donut(col.overall), `<div class="gauge-core"><span class="gauge-n" data-countup="monitored" data-value="${col.overall.total}">${col.overall.total}</span><span class="gauge-word">${esc(word)}</span><span class="gauge-cap">monitored</span></div>`, `</div>`, `<div class="legend">`, legendRow("alive", col.overall.alive), legendRow("stale", col.overall.stale), legendRow("gone", col.overall.gone), ...col.overall.stopped > 0 ? [legendRow("stopped", col.overall.stopped)] : [], legendRow("unknown", col.overall.unknown), `</div>`, `</div>`);
   out.push(sectionHead("Health by Tier", "How many components are healthy in each layer of the stack."));
   out.push(`<div class="tier-grid">`, tierCard("Daemon", col.daemonT, "squadrantd process, build freshness & log volume (Tier 0)"), tierCard("Projects", col.projT, "captains, crews & message data plane (Tier 1/2)"), tierCard("Environment", col.envT, "agent CLIs, vaults & config integrity (Tier 3/4)"), `</div>`);
   out.push(sectionHead("Live Trends", "Magnitudes tracked over time \u2014 each sparkline builds as new updates arrive."));
-  out.push(`<div class="trend-grid">`, trendCard("errors", "Daemon log", `${col.errors}`, "errors the daemon logged in the last window"), trendCard("behind", "Delivery lag", `${col.behind}`, "messages captains have not read yet"), trendCard("crewAge", "Crew heartbeat", linkLost ? "\u2014" : fmtDur(col.crewAgeMs), "time since the quietest crew was last seen"), `</div>`);
+  out.push(`<div class="trend-grid">`, trendCard("errors", "Daemon log", `${col.errors}`, "errors the daemon logged in the last window"), trendCard("behind", "Delivery lag", `${col.behind}`, "messages captains have not read yet"), trendCard("crewAge", "Crew heartbeat", linkLost ? "\u2014" : fmtDur(col.crewAgeMs), "time since the quietest crew was last seen"), trendCard("defers", "Delivery defers", `${col.maxDeferCount}`, "highest in-flight retry count for any project's captain delivery (#484/#466)"), `</div>`);
   out.push(`</section>`);
   return out.join("");
 }
@@ -8647,10 +8679,12 @@ function renderProjects(snap, now) {
     const comps = d.tier1.filter((c) => c.project === project);
     const dp = d.tier2.projects.find((p) => p.project === project);
     const captainStopped = comps.some((c) => c.kind === "captain" && c.state === "stopped");
+    const deferralState = !captainStopped && dp && dp.deferral.stuck ? "gone" : !captainStopped && dp && dp.deferral.maxDeferCount > 0 ? "stale" : "alive";
     const rollupStates = [
       ...comps.map((c) => c.state),
       !captainStopped && dp && dp.delivery.behind > 0 ? "stale" : "alive",
-      dp && dp.store.corruptCount > 0 ? "gone" : "alive"
+      dp && dp.store.corruptCount > 0 ? "gone" : "alive",
+      deferralState
     ];
     const rollup = worst(rollupStates);
     out.push(`<article class="card" data-rollup="${rollup}">`);
@@ -8662,7 +8696,7 @@ function renderProjects(snap, now) {
     }
     if (dp) {
       const counts = Object.entries(dp.store.byState).map(([s, n]) => pill("unknown", `${n} ${s}`)).join("");
-      out.push(`<div class="dp-grid">`, `<div class="dp-block"><span class="dp-l">mailbox</span><span class="dp-v"><span class="mono">${dp.mailbox.maxSeq}</span> entries \xB7 ${fmtBytes(dp.mailbox.sizeBytes)} \xB7 rotated ${dp.mailbox.rotationCount} \xB7 oldest ${fmtAge(dp.mailbox.oldestEntryAgeMs)}</span></div>`, `<div class="dp-block"><span class="dp-l">captain delivery</span>${deliveryBar(dp.delivery.behind, dp.mailbox.maxSeq)}<span class="dp-v"><span class="mono">${dp.delivery.behind}</span> behind</span></div>`, `<div class="dp-block"><span class="dp-l">task store</span><span class="chips">${counts || `<span class="dim small">no tasks</span>`}${dp.store.corruptCount > 0 ? pill("gone", `${dp.store.corruptCount} corrupt`) : ""}</span></div>`, `</div>`);
+      out.push(`<div class="dp-grid">`, `<div class="dp-block"><span class="dp-l">mailbox</span><span class="dp-v"><span class="mono">${dp.mailbox.maxSeq}</span> entries \xB7 ${fmtBytes(dp.mailbox.sizeBytes)} \xB7 rotated ${dp.mailbox.rotationCount} \xB7 oldest ${fmtAge(dp.mailbox.oldestEntryAgeMs)}</span></div>`, `<div class="dp-block"><span class="dp-l">captain delivery</span>${deliveryBar(dp.delivery.behind, dp.mailbox.maxSeq)}<span class="dp-v"><span class="mono">${dp.delivery.behind}</span> behind${dp.deferral.maxDeferCount > 0 ? ` \xB7 <span class="mono">${dp.deferral.maxDeferCount}</span> deferred${dp.deferral.stuck ? ` ${pill("gone", "delivery stuck")}` : ""}` : ""}</span></div>`, `<div class="dp-block"><span class="dp-l">task store</span><span class="chips">${counts || `<span class="dim small">no tasks</span>`}${dp.store.corruptCount > 0 ? pill("gone", `${dp.store.corruptCount} corrupt`) : ""}</span></div>`, `</div>`);
     }
     out.push(`</article>`);
   }
@@ -8684,7 +8718,14 @@ function renderDaemon(snap) {
   const sweep = t0.sweep.ageMs == null ? "awaiting first sweep" : `last ${fmtAge(t0.sweep.ageMs)} \xB7 ${fmtDur(t0.sweep.cadenceMs)} cadence`;
   const sweepState = t0.sweep.ageMs == null ? "unknown" : "alive";
   const logState = t0.log.errorCount > 0 ? "stale" : "alive";
-  out.push(`<div class="instr-grid">`, instr("process", `<span class="mono">squadrantd</span> ${statePill("alive")}`, `<span class="instr-sub">pid ${t0.pid} \xB7 v${esc(t0.version)}</span>`), instr("uptime", `<span class="mono">${fmtDur(t0.uptimeMs)}</span>`), instr("build", `${pill(buildState, t0.build.state)}`, t0.build.state === "stale" ? remediation("npm run build && squadrant heal daemon") : ""), instr("sweep", `${pill(sweepState, sweep)}`), `</div>`);
+  const tg = t0.telegram;
+  const tgState = !tg.configured ? "unknown" : !tg.polling ? "gone" : tg.lastError ? "stale" : "alive";
+  const tgLabel = !tg.configured ? "not configured" : !tg.polling ? "poll loop stopped" : tg.lastError ? `polling \xB7 ${tg.lastError}` : `polling \xB7 last ok ${fmtAge(tg.lastSuccessfulPollAt == null ? null : snap.generatedAt - tg.lastSuccessfulPollAt)}`;
+  out.push(`<div class="instr-grid">`, instr("process", `<span class="mono">squadrantd</span> ${statePill("alive")}`, `<span class="instr-sub">pid ${t0.pid} \xB7 v${esc(t0.version)}</span>`), instr("uptime", `<span class="mono">${fmtDur(t0.uptimeMs)}</span>`), instr("build", `${pill(buildState, t0.build.state)}`, t0.build.state === "stale" ? remediation("npm run build && squadrant heal daemon") : ""), instr("sweep", `${pill(sweepState, sweep)}`), instr("telegram", `${pill(tgState, tgLabel)}`), ...t0.lifecycleSources.map((s) => {
+    const state = !s.active ? "gone" : s.error ? "stale" : "alive";
+    const label = !s.active ? "inactive" : s.error ? s.error : "active";
+    return instr(s.name, `${pill(state, label)}`);
+  }), `</div>`);
   out.push(`<div class="trend-grid">`, [
     `<div class="trend">`,
     `<div class="trend-head"><span class="trend-l">Log errors</span><span class="trend-v">${pill(logState, `${t0.log.errorCount}`)}</span></div>`,
@@ -8744,6 +8785,7 @@ function metricsBlob(col, linkLost) {
     errors: linkLost ? 0 : col.errors,
     behind: linkLost ? 0 : col.behind,
     crewAgeMs: linkLost ? 0 : col.crewAgeMs,
+    maxDeferCount: linkLost ? 0 : col.maxDeferCount,
     alive: col.overall.alive,
     stale: col.overall.stale,
     gone: col.overall.gone,
@@ -8963,7 +9005,7 @@ var CLIENT_JS = `
 (function(){
   var activeTab='overview';var hist={};var prev={};
   function pushHist(k,v,t){var a=hist[k]||(hist[k]=[]);if(a.length&&a[a.length-1].t===t)return;a.push({t:t,v:v});if(a.length>48)a.shift();}
-  function ingest(){var el=document.getElementById('squadrant-metrics');if(!el)return;var m;try{m=JSON.parse(el.textContent);}catch(e){return;}pushHist('errors',m.errors,m.t);pushHist('behind',m.behind,m.t);pushHist('crewAge',Math.round(m.crewAgeMs/1000),m.t);}
+  function ingest(){var el=document.getElementById('squadrant-metrics');if(!el)return;var m;try{m=JSON.parse(el.textContent);}catch(e){return;}pushHist('errors',m.errors,m.t);pushHist('behind',m.behind,m.t);pushHist('crewAge',Math.round(m.crewAgeMs/1000),m.t);pushHist('defers',m.maxDeferCount,m.t);}
   function sparkSVG(a){var W=100,H=28,p=2;if(!a.length)return'';var vs=a.map(function(x){return x.v;});var mx=Math.max.apply(null,vs),mn=Math.min.apply(null,vs);if(mx===mn)mx=mn+1;var n=a.length;var pts=a.map(function(x,i){var px=n>1?p+i/(n-1)*(W-2*p):W/2;var py=H-p-(x.v-mn)/(mx-mn)*(H-2*p);return[px,py];});var d=pts.map(function(pt,i){return(i?'L':'M')+pt[0].toFixed(1)+' '+pt[1].toFixed(1);}).join(' ');var last=pts[pts.length-1];var area=d+' L'+last[0].toFixed(1)+' '+H+' L'+pts[0][0].toFixed(1)+' '+H+' Z';return'<path class="spark-area" d="'+area+'"/><path class="spark-line" d="'+d+'"/><circle class="spark-dot" cx="'+last[0].toFixed(1)+'" cy="'+last[1].toFixed(1)+'" r="2"/>';}
   function drawSparks(){var ns=document.querySelectorAll('[data-spark]');for(var i=0;i<ns.length;i++){ns[i].innerHTML=sparkSVG(hist[ns[i].getAttribute('data-spark')]||[]);}}
   function applyTab(){var ts=document.querySelectorAll('[data-tab]');for(var i=0;i<ts.length;i++){var on=ts[i].getAttribute('data-tab')===activeTab;ts[i].setAttribute('aria-selected',on?'true':'false');ts[i].classList.toggle('on',on);}var ps=document.querySelectorAll('[data-panel]');for(var j=0;j<ps.length;j++){var on2=ps[j].getAttribute('data-panel')===activeTab;ps[j].hidden=!on2;}}