pi-messenger 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [0.11.0] - 2026-02-08
+
+### Added
+- **Test suite** — 53 tests across 7 Vitest suites covering store CRUD, state machine, config merging, agent discovery, model resolution, graceful shutdown, and live progress (including cwd isolation). Includes test helpers for temp directories and mock contexts.
+- **Per-agent runtime config** — Model override with 4-level priority: per-task > per-wave `model` param > config `crew.models.worker` > agent `.md` frontmatter. Environment variable override via `crew.work.env` config (not exposed as tool param to prevent API keys in logs).
+- **Graceful shutdown** — `AbortSignal` threaded from tool execute through to spawned workers. On abort: discovers worker name via PID-based registry scan, writes shutdown message to worker inbox, waits 30s grace period, SIGTERM, waits 5s, SIGKILL. Tasks reset to `todo` for retry. Workers instructed to release reservations and exit without committing.
+- **Live crew progress** — In-memory pub/sub store fed by worker JSONL events. Overlay Crew tab shows Active Workers section with tool name, call count, tokens, and elapsed time updating every second. Status bar shows active worker count during autonomous mode (`🔨N`).
+- **`shutdownGracePeriodMs` config** — Configurable grace period before SIGTERM (default: 30000).
+
+### Changed
+- **Dynamic overlay height** — Content area scales with terminal size (8-25 lines) instead of hardcoded 10. On a standard 24-row terminal, visible content goes from 10 to 15 lines.
+- **Handler signatures simplified** — Removed unused `state` and `dirs` parameters from plan and review handlers.
+
+### Fixed
+- **`deepMerge` crash** — Merging config with `models` key crashed when the target didn't have the key. Hardened for undefined target keys.
+- **Result/task association** — Worker results now matched by `taskId` field instead of array index, since `spawnAgents` returns in completion order not submission order.
+
+### Removed
+- `attemptsPerTask` field from `AutonomousState` — declared but never populated by any code.
+- `ARCHITECTURE.md` from repo (moved to external docs).
+
+## [0.10.0] - 2026-02-05
+
+### Fixed
+- **Crew spawner applies agent definitions** — Spawned crew workers now receive the agent's system prompt (`--append-system-prompt`), tool restrictions (`--tools`), and model override from their `.md` definitions. Previously a phantom `--agent` flag was passed that pi-core silently ignored, the agent name leaked into the prompt as noise, and the system prompts (worker's 6-phase protocol, reviewer's rubric, planner's exploration workflow) were never delivered. Tool restrictions also take effect: reviewers and interview generators are now limited to `read,bash` instead of getting all default builtins including `write` and `edit`.
+- **Crew spawner session cleanup** — Spawned workers now pass `--no-session` to avoid writing ephemeral session files to disk.
+
+### Added
+- **`--crew-install` / `--crew-uninstall` CLI flags** — `npx pi-messenger --crew-install` copies crew agent `.md` files and the `pi-messenger-crew` skill to user directories. `--crew-uninstall` removes them. Reads from the npm package (not the installed extension) to avoid version skew.
+
+### Changed
+- **README rewrite** — Installation section now shows real CLI commands instead of tool-call syntax. "How It Works" section explains pi extension API hooks (`pi.on()`, `pi.sendMessage()`, `{ block: true }`, `ctx.ui.custom()`) instead of listing directory trees.
+
 ## [0.9.0] - 2026-02-05
 
 ### Added

package/README.md

@@ -6,106 +6,76 @@
 
 **What if multiple agents in different terminals sharing a folder could talk to each other like they're in a chat room?** Join, see who's online and what they're doing. Claim tasks, reserve files, send messages. Built on [Pi's](https://github.com/badlogic/pi-mono) extension system. No daemon, no server, just files.
 
+[![npm version](https://img.shields.io/npm/v/pi-messenger?style=for-the-badge)](https://www.npmjs.com/package/pi-messenger)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)
 [![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-blue?style=for-the-badge)]()
 
-> ⚠️ **Beta** - Core messaging, presence, and file reservations are stable. **Crew task orchestration** (plan/work/review) is newer and not fully tested yet. Please [open an issue](https://github.com/nicobailon/pi-messenger/issues) if you encounter problems.
-
-Pi-messenger adds a `pi_messenger` tool that **agents use** for coordination. You don't type these commands - you ask your agent to do things, and it calls `pi_messenger` behind the scenes.
-
-## Quick Start
-
-### Multi-Agent Coordination
-
-Once joined (manually or via auto-join config), agents can coordinate:
-
-```typescript
-pi_messenger({ action: "reserve", paths: ["src/auth/"], reason: "Refactoring" })
-// → Reserved src/auth/ - other agents will be blocked
-
-// ... does the work ...
+## Installation
 
-pi_messenger({ action: "release" })
-// → Released all reservations
+```bash
+pi install npm:pi-messenger
 ```
 
-> **Tip:** Set `autoRegister: true` in your config to auto-join on startup. Otherwise, agents join with `pi_messenger({ action: "join" })`.
-
-### Crew Task Orchestration
-
-Ask your agent to plan and execute from a PRD:
-
-```typescript
-pi_messenger({ action: "plan" })
-// → Planner analyzes codebase, creates tasks
+Crew agents and the `pi-messenger-crew` skill are auto-installed on first use of `plan`, `work`, or `review`. To install them ahead of time:
 
-pi_messenger({ action: "work", autonomous: true })
-// → Workers execute tasks in waves until done
+```bash
+npx pi-messenger --crew-install
 ```
 
-> **Note:** Crew agents (planner, workers, reviewers) automatically join the mesh as their first action.
+This copies `crew/agents/*.md` to `~/.pi/agent/agents/` and `skills/pi-messenger-crew/` to `~/.pi/agent/skills/`.
 
-## Installation
+To remove the extension:
 
 ```bash
-pi install npm:pi-messenger
+npx pi-messenger --remove
 ```
 
-To remove:
+To also remove crew agents and skill:
 
 ```bash
-npx pi-messenger --remove
+npx pi-messenger --crew-uninstall
 ```
 
-After joining, your agent name appears in the status bar:
+## Quick Start
+
+Once joined (manually or via `autoRegister` config), agents can coordinate:
 
+```typescript
+pi_messenger({ action: "join" })
+pi_messenger({ action: "reserve", paths: ["src/auth/"], reason: "Refactoring" })
+pi_messenger({ action: "send", to: "GoldFalcon", message: "auth is done" })
+pi_messenger({ action: "release" })
 ```
-msg: SwiftRaven (2 peers) ●3
+
+For multi-agent task orchestration from a PRD:
+
+```typescript
+pi_messenger({ action: "plan" })                       // Planner analyzes codebase, creates tasks
+pi_messenger({ action: "work", autonomous: true })      // Workers execute tasks in waves until done
+pi_messenger({ action: "review", target: "task-1" })    // Reviewer checks implementation
 ```
 
 ## Features
 
-**Living Presence** - Agents have rich presence with status indicators (🟢 active, 🟡 idle, 🟠 away, 🔴 stuck), tool call counts, token usage, and auto-generated status messages like "on fire 🔥" or "debugging...".
+**Living Presence** - Status indicators (active, idle, away, stuck), tool call counts, token usage, and auto-generated status messages like "on fire" or "debugging...". Your agent name appears in the status bar: `msg: SwiftRaven (2 peers) ●3`
 
-**Activity Feed** - A unified timeline of everything happening: edits, commits, test runs, messages, task starts/completions. Crew events appear inline with a `[Crew]` prefix.
+**Activity Feed** - Unified timeline of edits, commits, test runs, messages, and task events. Query with `{ action: "feed" }`.
 
 **Discovery** - Agents register with memorable themed names (SwiftRaven, LunarDust, OakTree). See who's active, what they're working on, which model and git branch they're on.
 
-**Messaging** - Send messages between agents. Recipients wake up immediately and see the message as a steering prompt. Great for handoffs and coordination.
+**Messaging** - Send messages between agents. Recipients wake up immediately and see the message as a steering prompt.
 
 **File Reservations** - Claim files or directories. Other agents get blocked with a clear message telling them who to coordinate with. Auto-releases on exit.
 
-**Stuck Detection** - Agents idle too long with an open task or reservation are flagged as stuck. You get a notification so you can intervene.
+**Stuck Detection** - Agents idle too long with an open task or reservation are flagged as stuck. Peers get a notification.
 
-**Human as Participant** - Your interactive pi session appears in the agent list with `(you)`. Same activity tracking, same status messages. You can chat from the overlay.
-
-**Swarm Coordination** - Multiple agents work on the same spec file. Claim tasks atomically, mark them complete, see who's doing what.
+**Human as Participant** - Your interactive pi session appears in the agent list with `(you)`. Same activity tracking, same status messages. Chat from the overlay.
 
 ## Chat Overlay
 
 `/messenger` opens an interactive overlay with agent presence, activity feed, and chat:
 
-```
-╭─ Messenger ── 3 agents ── myapp ────────────────────╮
-│                                                      │
-│ 🟢 SwiftRaven (you)                                  │
-│    editing login.ts - 12 tools - 31.0k - on fire 🔥  │
-│                                                      │
-│ 🟡 GoldFalcon                             idle 2m    │
-│    8 tools - 24.1k - 📁 src/api/                     │
-│                                                      │
-│ 🔴 IronKnight                             stuck      │
-│    3 tools - 16.4k                                   │
-│                                                      │
-│ Activity                                             │
-│ 10:42 SwiftRaven editing login.ts                    │
-│ 10:40 GoldFalcon → SwiftRaven: "auth done?"          │
-│ 10:38 SwiftRaven committed "feat: add OAuth"         │
-│ 10:35 [Crew] GoldFalcon started task-03              │
-├──────────────────────────────────────────────────────┤
-│ > @GoldFalcon almost done                [Tab] [Enter]│
-╰──────────────────────────────────────────────────────╯
-```
+<img width="722" height="351" alt="pi-messenger chat overlay" src="https://github.com/user-attachments/assets/4d0f1db7-90dd-4ffb-9463-560426edebd9" />
 
 Chat input supports `@Name msg` for DMs and `@all msg` for broadcasts. Text without `@` broadcasts from the Agents tab or DMs the selected agent tab.
 
@@ -118,120 +88,19 @@ Chat input supports `@Name msg` for DMs and `@all msg` for broadcasts. Text with
 
 ## Crew: Task Orchestration
 
-Crew provides multi-agent task orchestration with a simplified PRD-based workflow.
-
-### Basic Workflow
-
-1. **Plan** - Planner analyzes your codebase and PRD, creates tasks
-2. **Work** - Workers implement tasks in parallel waves
-3. **Review** - Reviewer checks each implementation
-
-```typescript
-// Plan from your PRD (auto-discovers PRD.md, SPEC.md, etc.)
-pi_messenger({ action: "plan" })
-
-// Or specify PRD path explicitly
-pi_messenger({ action: "plan", prd: "docs/PRD.md" })
-
-// Execute tasks (spawns parallel workers)
-pi_messenger({ action: "work" })
-
-// Or run autonomously until done/blocked
-pi_messenger({ action: "work", autonomous: true })
-
-// Review a specific task
-pi_messenger({ action: "review", target: "task-1" })
-// → SHIP ✅ or NEEDS_WORK 🔄
-```
+Crew turns a PRD into a dependency graph of tasks, then executes them in parallel waves.
 
-### Crew API
-
-**Planning**
-| Action | Description | Example |
-|--------|-------------|---------|
-| `plan` | Create plan from PRD | `{ action: "plan" }` or `{ action: "plan", prd: "..." }` |
-| `status` | Show progress | `{ action: "status" }` |
-
-**Work Execution**
-| Action | Description | Example |
-|--------|-------------|---------|
-| `work` | Run ready tasks | `{ action: "work" }` |
-| `work` (auto) | Run until done/blocked | `{ action: "work", autonomous: true }` |
-
-**Task Management**
-| Action | Description | Example |
-|--------|-------------|---------|
-| `task.show` | Show task details | `{ action: "task.show", id: "task-1" }` |
-| `task.list` | List all tasks | `{ action: "task.list" }` |
-| `task.start` | Start task | `{ action: "task.start", id: "task-1" }` |
-| `task.done` | Complete task | `{ action: "task.done", id: "task-1", summary: "..." }` |
-| `task.block` | Block task | `{ action: "task.block", id: "task-1", reason: "..." }` |
-| `task.unblock` | Unblock task | `{ action: "task.unblock", id: "task-1" }` |
-| `task.ready` | List ready tasks | `{ action: "task.ready" }` |
-| `task.reset` | Reset task | `{ action: "task.reset", id: "task-1", cascade: true }` |
-
-**Review**
-| Action | Description | Example |
-|--------|-------------|---------|
-| `review` | Review implementation | `{ action: "review", target: "task-1" }` |
-
-**Maintenance**
-| Action | Description | Example |
-|--------|-------------|---------|
-| `crew.status` | Overall status | `{ action: "crew.status" }` |
-| `crew.validate` | Validate plan | `{ action: "crew.validate" }` |
-| `crew.agents` | List crew agents | `{ action: "crew.agents" }` |
-| `crew.install` | Install crew agents | `{ action: "crew.install" }` |
-
-### Planning Workflow
-
-The `plan` action runs a multi-pass planning loop: the planner drafts tasks, a reviewer checks them against the PRD, and the planner refines until SHIP or `planning.maxPasses` is reached. All passes and feedback are stored in `.pi/messenger/crew/planning-progress.md`.
+### Workflow
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  Your Project                                                    │
-│  ├── PRD.md            ◄── Planner discovers and reads these    │
-│  ├── DESIGN.md                                                   │
-│  ├── src/                                                        │
-│  └── ...                                                         │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  Planner (opus)                                                  │
-│  ├── Explores codebase structure and patterns                    │
-│  ├── Reads project documentation                                 │
-│  ├── Identifies gaps, edge cases, security concerns              │
-│  └── Drafts task breakdown with dependencies                     │
-└─────────────────────────────────────────────────────────────────┘
-                              │ append to
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  planning-progress.md (history + feedback)                       │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  Reviewer (gpt-5.2-high)                                          │
-│  ├── SHIP  ✅  or NEEDS_WORK 🔄                                  │
-│  └── Feeds back into the next planner pass                       │
-└─────────────────────────────────────────────────────────────────┘
-                              │ SHIP
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  Result: Tasks with Dependencies                                 │
-│  ├── task-1: Setup types        (no deps)                       │
-│  ├── task-2: Core logic         (depends on task-1)             │
-│  ├── task-3: API endpoints      (depends on task-1)             │
-│  └── task-4: Tests              (depends on task-2, task-3)     │
-└─────────────────────────────────────────────────────────────────┘
-```
+1. **Plan** — Planner explores the codebase and PRD, drafts tasks with dependencies. A reviewer checks the plan; the planner refines until SHIP or `maxPasses` is reached. History is stored in `planning-progress.md`.
+2. **Work** — Workers implement ready tasks (all dependencies met) in parallel waves. A single `work` call runs one wave. `autonomous: true` runs waves back-to-back until everything is done or blocked.
+3. **Review** — Reviewer checks each implementation: SHIP, NEEDS_WORK, or MAJOR_RETHINK.
 
-**No special format required** -- just put your docs in the project. The planner finds and reads markdown files, READMEs, and code comments.
+No special PRD format required — the planner auto-discovers `PRD.md`, `SPEC.md`, `DESIGN.md`, etc. in your project root and `docs/`.
 
-### How Work Execution Works
+### Wave Execution
 
-Crew doesn't run tasks sequentially. Tasks form a dependency graph, and the work handler executes them in **waves** based on what's ready:
+Tasks form a dependency graph. Independent tasks run concurrently:
 
 ```
 Wave 1:  task-1 (no deps)  ─┐
@@ -243,63 +112,7 @@ Wave 2:  task-2 (→ task-1) ─┤── task-1 done, task-2 unblocked
 Wave 3:  task-5 (→ task-2, task-4) ── both deps done
 ```
 
-A task is **ready** when its status is pending and all its dependencies are completed. Each wave picks all ready tasks (up to `concurrency.workers`), spawns parallel workers, waits for them to finish, then checks what's newly unblocked. Independent tasks — those that don't depend on each other — run concurrently in the same wave.
-
-The planner structures tasks to maximize this parallelism. Foundation work (types, config, schemas) has no dependencies so it starts immediately. Features that don't touch each other get separate dependency chains so they can run in parallel. Tasks that need shared work done first (tests, integration, docs) depend on the tasks that produce it.
-
-A single `work` call runs one wave. Autonomous mode (`autonomous: true`) runs waves back-to-back until everything is done or blocked.
-
-### Autonomous Mode
-
-Run tasks continuously until completion:
-
-```typescript
-pi_messenger({ action: "work", autonomous: true })
-```
-
-Autonomous mode:
-- Executes waves of parallel workers
-- Auto-blocks on failure
-- Stops when all tasks done or blocked
-- Respects `maxWaves` limit (default: 50)
-
-### Crew Overlay Tab
-
-The `/messenger` overlay includes a Crew tab showing task status:
-
-```
-╭─ Messenger ── 3 agents ── myapp ──────────────────────╮
-│ Agents │ ▸ Crew (2/5) │ ● GoldFalcon │ + All         │
-├──────────────────────────────────────────────────────┤
-│                                                      │
-│  📋 docs/PRD.md                              [2/5]   │
-│                                                      │
-│  ✓ task-1  Setup OAuth config                        │
-│  ✓ task-2  Implement token storage                   │
-│  ● task-3  Add Google provider (SwiftRaven)          │
-│  ○ task-4  Add GitHub provider → task-2              │
-│  ○ task-5  Write tests → task-3, task-4              │
-│                                                      │
-├──────────────────────────────────────────────────────┤
-│ ● AUTO Wave 2 │ 2/5 done │ 1 ready │ ⏱️ 3:42        │
-╰──────────────────────────────────────────────────────╯
-```
-
-### Crew Data Storage
-
-```
-.pi/messenger/crew/
-├── plan.json               # Plan metadata (PRD path, progress)
-├── plan.md                 # Planner output
-├── planning-progress.md    # Planning loop history + feedback
-├── tasks/
-│   ├── task-1.json         # Task metadata
-│   ├── task-1.md           # Task specification
-│   └── ...
-├── blocks/                 # Block context for blocked tasks
-├── artifacts/              # Debug artifacts
-└── config.json             # Project-level crew config
-```
+The planner structures tasks to maximize parallelism. Foundation work has no dependencies and starts immediately. Features that don't touch each other get separate chains. Autonomous mode stops when all tasks are done or blocked.
 
 ### Crew Configuration
 
@@ -309,128 +122,80 @@ Add to `~/.pi/agent/pi-messenger.json`:
 {
   "crew": {
     "concurrency": { "workers": 2 },
+    "models": { "worker": "claude-sonnet-4-20250514" },
     "review": { "enabled": true, "maxIterations": 3 },
     "planning": { "maxPasses": 3 },
-    "work": { "maxAttemptsPerTask": 5, "maxWaves": 50 }
+    "work": {
+      "maxAttemptsPerTask": 5,
+      "maxWaves": 50,
+      "shutdownGracePeriodMs": 30000,
+      "env": { "NODE_ENV": "test" }
+    }
   }
 }
 ```
 
 | Setting | Description | Default |
 |---------|-------------|---------|
-| `concurrency.workers` | Max parallel workers during work | `2` |
-| `review.enabled` | Enable review functionality | `true` |
-| `review.maxIterations` | Max review iterations per task | `3` |
-| `planning.maxPasses` | Max planner passes before accepting last output | `3` |
-| `work.maxAttemptsPerTask` | Retries before blocking a task | `5` |
-| `work.maxWaves` | Max waves in autonomous mode | `50` |
-
-### Crew Install
-
-Crew agents are **auto-installed** on first use of `plan`, `work`, or `review`. To manually install or update:
+| `concurrency.workers` | Max parallel workers per wave | `2` |
+| `models.worker` | Model for spawned workers (overridden by per-task or per-wave `model` param) | agent `.md` frontmatter |
+| `review.enabled` | Auto-review after task completion | `true` |
+| `review.maxIterations` | Max review/fix cycles per task | `3` |
+| `planning.maxPasses` | Max planner/reviewer refinement passes | `3` |
+| `work.maxAttemptsPerTask` | Auto-block after N failures | `5` |
+| `work.maxWaves` | Max autonomous waves | `50` |
+| `work.shutdownGracePeriodMs` | Grace period before SIGTERM on abort | `30000` |
+| `work.env` | Environment variables passed to spawned workers | `{}` |
 
-```typescript
-pi_messenger({ action: "crew.install" })
-```
-
-**What gets installed:**
-- **5 agents** in `~/.pi/agent/agents/` (planner, worker, reviewer, interview-generator, plan-sync)
-- **1 skill** in `~/.pi/agent/skills/` (pi-messenger-crew quick reference)
-
-To remove:
-```typescript
-pi_messenger({ action: "crew.uninstall" })
-```
+Crew agents (planner, worker, reviewer, interview-generator, plan-sync) are **auto-installed** on first use. Run `npx pi-messenger --crew-install` to manually install or update.
 
-## Tool Reference
+## API Reference
 
-### Action-Based API (Recommended)
+### Coordination
 
-**Coordination**
 | Action | Description |
 |--------|-------------|
 | `join` | Join the agent mesh |
 | `list` | List agents with presence info |
 | `status` | Show your status or crew progress |
-| `whois` | Detailed info about an agent |
-| `feed` | Show activity feed |
-| `set_status` | Set custom status message (omit `message` to clear) |
-| `send` | Send DM (requires `to` + `message`) |
-| `broadcast` | Broadcast to all (requires `message`) |
-| `reserve` | Reserve files (requires `paths`) |
-| `release` | Release reservations (optional `paths`, or releases all) |
-| `rename` | Change your name (requires `name`) |
-| `swarm` | Show swarm task status |
-| `claim` | Claim a swarm task (requires `taskId`) |
-| `unclaim` | Release a swarm claim (requires `taskId`) |
-| `complete` | Complete a swarm task (requires `taskId`) |
+| `whois` | Detailed info about an agent (`name` required) |
+| `feed` | Show activity feed (`limit` optional, default: 20) |
+| `set_status` | Set custom status message (`message` optional — omit to clear) |
+| `send` | Send DM (`to` + `message` required) |
+| `broadcast` | Broadcast to all (`message` required) |
+| `reserve` | Reserve files (`paths` required, `reason` optional) |
+| `release` | Release reservations (`paths` optional — omit to release all) |
+| `rename` | Change your name (`name` required) |
 
-```typescript
-pi_messenger({
-  action: string,              // Action to perform
-
-  // Coordination
-  name?: string,               // For whois, rename
-  message?: string,            // For send, broadcast, set_status
-  to?: string | string[],      // For send
-  paths?: string[],            // For reserve, release
-  reason?: string,             // For reserve, claim, task.block
-  limit?: number,              // For feed (default: 20)
-
-  // Plan
-  prd?: string,                // PRD file path
-
-  // Task identifiers
-  id?: string,                 // Task ID (task-N)
-  taskId?: string,             // Swarm task ID
-  target?: string,             // Target for review
-
-  // Creation
-  title?: string,              // For task.create
-  dependsOn?: string[],        // Task dependencies
-
-  // Completion
-  summary?: string,            // For task.done
-
-  // Work options
-  autonomous?: boolean,        // Run continuously
-  concurrency?: number,        // Override concurrency
-
-  // Reset
-  cascade?: boolean,           // Reset dependent tasks too
-})
-```
+### Crew
 
-### Legacy API
+| Action | Description |
+|--------|-------------|
+| `plan` | Create plan from PRD (`prd` optional — auto-discovers if omitted) |
+| `work` | Run ready tasks (`autonomous`, `concurrency` optional) |
+| `review` | Review implementation (`target` task ID required) |
+| `task.list` | List all tasks |
+| `task.show` | Show task details (`id` required) |
+| `task.start` | Start a task (`id` required) |
+| `task.done` | Complete a task (`id` required, `summary` optional) |
+| `task.block` | Block a task (`id` + `reason` required) |
+| `task.unblock` | Unblock a task (`id` required) |
+| `task.ready` | List tasks ready to work |
+| `task.reset` | Reset a task (`id` required, `cascade` optional) |
+| `crew.status` | Overall crew status |
+| `crew.validate` | Validate plan dependencies |
+| `crew.agents` | List available crew agents |
+| `crew.install` | Install/update crew agents |
+| `crew.uninstall` | Remove crew agents and skill |
+
+### Swarm (Spec-Based)
 
-```typescript
-pi_messenger({
-  // Join
-  join?: boolean,              // Join the agent mesh
-  spec?: string,               // Spec file to work on
-
-  // Swarm
-  swarm?: boolean,             // Get swarm status
-  claim?: string,              // Claim a task
-  unclaim?: string,            // Release without completing
-  complete?: string,           // Mark task complete
-  notes?: string,              // Completion notes
-
-  // Messaging
-  to?: string | string[],      // Recipient(s)
-  broadcast?: boolean,         // Send to all
-  message?: string,            // Message text
-
-  // Reservations
-  reserve?: string[],          // Paths to reserve
-  reason?: string,             // Why reserving/claiming
-  release?: string[] | true,   // Release reservations
-
-  // Other
-  rename?: string,             // Change your name
-  list?: boolean,              // List active agents
-})
-```
+| Action | Description |
+|--------|-------------|
+| `swarm` | Show swarm task status |
+| `claim` | Claim a task (`taskId` required) |
+| `unclaim` | Release a claim (`taskId` required) |
+| `complete` | Complete a task (`taskId` required) |
 
 ## Configuration
 
@@ -452,32 +217,30 @@ Create `~/.pi/agent/pi-messenger.json`:
 | `autoRegister` | Join mesh on startup | `false` |
 | `autoRegisterPaths` | Folders where auto-join is enabled (supports `*` globs) | `[]` |
 | `scopeToFolder` | Only see agents in same directory | `false` |
-| `nameTheme` | Name generation theme: `default`, `nature`, `space`, `minimal`, `custom` | `"default"` |
+| `nameTheme` | Name theme: `default`, `nature`, `space`, `minimal`, `custom` | `"default"` |
 | `nameWords` | Custom theme words: `{ adjectives: [...], nouns: [...] }` | — |
 | `feedRetention` | Max events kept in activity feed | `50` |
-| `stuckThreshold` | Seconds of inactivity before stuck detection | `900` (15m) |
+| `stuckThreshold` | Seconds of inactivity before stuck detection | `900` |
 | `stuckNotify` | Show notification when a peer appears stuck | `true` |
 | `autoStatus` | Auto-generate status messages from activity | `true` |
 | `crewEventsInFeed` | Include crew task events in activity feed | `true` |
 | `contextMode` | Context injection level: `full`, `minimal`, `none` | `"full"` |
 
+Config priority: project `.pi/pi-messenger.json` > user `~/.pi/agent/pi-messenger.json` > `~/.pi/agent/settings.json` `"messenger"` key > defaults.
+
 ## How It Works
 
-```
-~/.pi/agent/messenger/
-├── registry/           # Agent registrations (PID, cwd, model, activity, tokens)
-├── inbox/              # Message delivery
-├── feed.jsonl          # Activity feed (append-only, pruned on startup)
-├── claims.json         # Active task claims
-├── completions.json    # Completed tasks
-└── swarm.lock          # Atomic lock for claims
-```
+Pi-messenger is a [pi extension](https://github.com/badlogic/pi-mono) that hooks into the agent lifecycle. It uses `pi.on("tool_call")` and `pi.on("tool_result")` to track activity — every edit, commit, and test run gets logged. `pi.on("session_start")` handles auto-registration, `pi.on("session_shutdown")` cleans up, and `pi.on("agent_end")` drives autonomous crew mode by checking for ready tasks after each agent turn.
+
+Incoming messages wake the receiving agent via `pi.sendMessage()` with `triggerTurn: true` and `deliverAs: "steer"`, which injects the message as a steering prompt that resumes the agent. File reservations are enforced by returning `{ block: true }` from a `tool_call` hook on write/edit operations. The `/messenger` overlay uses `ctx.ui.custom()` for the chat TUI, and `ctx.ui.setStatus()` keeps the status bar updated with peer count and unread messages.
+
+Crew workers are spawned as `pi --mode json` subprocesses with the agent's system prompt, model, and tool restrictions from their `.md` definitions. Progress is tracked via JSONL streaming — the overlay subscribes to a live progress store that shows each worker's current tool, call count, and token usage in real time. Aborting a work run triggers graceful shutdown: each worker receives an inbox message asking it to stop, followed by a grace period before SIGTERM. The planner and reviewer work the same way — just pi instances with different agent configs.
 
-File-based coordination. No daemon. Activity tracking updates the registry every 10 seconds via debounced flushes. Dead agents detected via PID and cleaned up automatically - a "leave" event is logged when stale registrations are removed.
+All coordination is file-based, no daemon required. Global state (registry, inboxes, activity feed) lives in `~/.pi/agent/messenger/`. Per-project crew data (plan, tasks, artifacts) lives in `.pi/messenger/crew/` inside your project. Dead agents are detected via PID checks and cleaned up automatically.
 
 ## Credits
 
-- **[mcp_agent_mail](https://github.com/Dicklesworthstone/mcp_agent_mail)** by [@doodlestein](https://x.com/doodlestein) - Inspiration for agent-to-agent messaging
+- **[mcp_agent_mail](https://github.com/Dicklesworthstone/mcp_agent_mail)** by [@doodlestein](https://x.com/doodlestein) — Inspiration for agent-to-agent messaging
 - **[Pi coding agent](https://github.com/badlogic/pi-mono/)** by [@badlogicgames](https://x.com/badlogicgames)
 
 ## License

package/crew/agents/crew-worker.md

@@ -85,6 +85,15 @@ pi_messenger({
 })
 ```
 
+## Shutdown Handling
+
+If you receive a message saying "SHUTDOWN REQUESTED":
+1. Stop what you're doing
+2. Release reservations: `pi_messenger({ action: "release" })`
+3. Do NOT mark the task as done — leave it as in_progress for retry
+4. Do NOT commit anything
+5. Exit immediately
+
 ## Important Rules
 
 - ALWAYS join first, before any other pi_messenger calls