indus-swarms 0.1.0

package/AGENTS.md

@@ -0,0 +1,14 @@
+# AGENTS.md
+
+Project-specific guidance for AI agents working in this repository.
+
+## Operating Intent (Critical)
+
+This project is **agent-driven**, not user-operated.
+
+- Treat the human as setting goals/outcomes, not executing operational steps.
+- Prefer autonomous agent flows (tool actions, policies, retries, task transitions).
+- Do **not** rely on manual user remediation as the default path.
+- UI panels and slash commands are primarily for observability/debugging and emergency override.
+- Quality-gate failures should be handled by agent policy (warn/followup/reopen/reopen_followup), not by asking the user to manually clear state.
+- Human-in-the-loop steps should happen only when explicitly required by policy or requested by the user.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Mustier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# indus-swarms (pi-agent-teams)
+
+A lightweight extension for the `indusagi` CLI that brings Claude-style agent teams to your Pi workflows. The leader process manages shared task lists, mailboxes, and team status while spawning autonomous teammates (workers) that claim, execute, and report on tasks.
+
+## What it provides
+
+1. **Team coordination primitives** — shared task list files, dependency tracking, and auto-claiming keep multiple agents working without manual juggling.
+2. **Messaging layer** — direct `DM` mailboxes, broadcasts, and steering instructions let you nudge teammates from the leader session.
+3. **Lifecycle control** — graceful shutdown, kill, prune, and cleanup keep team artifacts tidy; widgets show real-time status.
+4. **Model/workspace control** — spawn teammates with fresh or branched contexts, shared workspaces or per-agent git worktrees, and optional plan/approval flows.
+5. **Hook + widget support** — leader-side hooks can enforce quality gates and the `/tw` widget surfaces tasks, inboxes, and shortcuts like `m` for message and `t` to toggle task view.
+
+## Installation
+
+> Requires Node 20+ and the `indusagi` CLI. Install once per machine, then install the extension however you prefer:
+
+```bash
+npm install indusagi indusagi-coding-agent
+```
+
+**Option A — install from npm:**
+
+```bash
+indusagi install npm:@tmustier/pi-agent-teams
+```
+
+**Option A2 — install the renamed package (if published):**
+
+```bash
+indusagi install indus-swarms
+```
+
+**Option B — load directly for development:**
+
+```bash
+indusagi -e /Users/varunisrani/indusagi-ts/indus-swarms/extensions/teams/index.ts
+```
+
+**Option C — install from the local folder:**
+
+```bash
+indusagi install /Users/varunisrani/indusagi-ts/indus-swarms
+```
+
+Once installed, run `indusagi` as usual and the extension auto-discovers.
+
+If you prefer installing directly via npm (without `indusagi install`), run:
+```
+npm install indus-swarms
+```
+Then load it via
+```
+indusagi -e ./node_modules/indus-swarms/extensions/teams/index.ts
+```
+
+## Quick usage
+
+1. Start `indusagi`.
+2. Confirm the extension is active with `/team id` or `/team help`.
+3. Spawn teammates manually:
+   ```text
+   /team spawn alice shared
+   /team spawn bob branch worktree
+   ```
+4. Create tasks and assign them:
+   ```text
+   /team task add alice: Explore AGENTS.md
+   /team task list
+   /team task assign 1 bob
+   ```
+5. Communicate:
+   - `/team dm <name> <msg>` — mailbox DM
+   - `/team broadcast <msg>` — message everyone
+   - `/team steer <name> <msg>` — steering for RPC workers
+6. Monitor progress with `/tw` (or `/team panel`) and use shortcuts (`t` for current agent tasks, `m` for a DM, `k` to kill, etc.).
+7. When you are done:
+   ```text
+   /team shutdown
+   /team cleanup
+   ```
+
+Alternatively, `/swarm <task>` lets the model spawn teammates, delegate tasks, and coordinate the work for you.
+
+## Environment variables
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `INDUS_TEAMS_ROOT_DIR` | Root directory for all team artifacts (task lists, mailboxes, sessions). Defaults to `~/.indusagi/agent/teams` (legacy `~/.pi/agent/teams` also works). | `~/.indusagi/agent/teams` |
+| `INDUS_TEAMS_DEFAULT_AUTO_CLAIM` | Auto-claim new tasks when teammates idle. | `1` |
+| `INDUS_TEAMS_STYLE` | UI style (`normal`, `soviet`, `pirate`, or custom). | `normal` |
+| `INDUS_TEAMS_HOOKS_ENABLED` | Enable leader-side hooks/quality gates. | `0` |
+| `INDUS_TEAMS_HOOKS_DIR` | Directory holding `on_idle`, `on_task_completed`, `on_task_failed` hooks. | `<teamsRoot>/_hooks` |
+| `INDUS_TEAMS_HOOK_TIMEOUT_MS` | Hook timeout in milliseconds. | `60000` |
+| `INDUS_TEAMS_HOOKS_FAILURE_ACTION` | Policy when a hook fails (`warn`, `followup`, `reopen`, `reopen_followup`). | `warn` |
+| `INDUS_TEAMS_HOOKS_MAX_REOPENS_PER_TASK` | Max reopen count when hooks requeue tasks. | `3` |
+| `INDUS_TEAMS_HOOKS_FOLLOWUP_OWNER` | Owner of follow-up tasks created after hook failures (`member`, `lead`, `none`). | `member` |
+
+Add custom styles under `~/.indusagi/agent/teams/_styles/<style>.json` to override naming and lifecycle copy.
+
+## Development & tests
+
+```bash
+npm run check                     # typecheck + lint via tsx/eslint
+npm run smoke-test               # automated filesystem smoke test
+node scripts/e2e-rpc-test.mjs     # leader + RPC teammate handshake
+./scripts/start-tmux-team.sh      # helper that launches leader + tmux worker panes
+```
+
+Worker processes run `indusagi --mode rpc` with the same extension in worker mode via `scripts/lib/pi-workers.ts`.
+
+## Tips
+
+- Use `/team attach list` and `/team attach <teamId>` to reconnect to another leader session.
+- For structured automation, invoke the built-in `teams` tool manually via JSON (see `extensions/teams/leader-teams-tool.ts`).
+- Keep `PI_TEAMS_ROOT_DIR` isolated per experiment to easily clean team directories.
+
+## License
+
+MIT

package/docs/claude-parity.md

@@ -0,0 +1,151 @@
+# Claude Agent Teams parity roadmap (indus-swarms / pi-agent-teams)
+
+Last updated: 2026-02-10
+
+This document tracks **feature parity gaps** between:
+
+- Claude Code **Agent Teams** (official docs)
+  - https://code.claude.com/docs/en/agent-teams#control-your-agent-team
+  - https://code.claude.com/docs/en/interactive-mode#task-list
+
+…and this repository’s implementation:
+
+- `indus-swarms` (pi-agent-teams Pi extension)
+
+> Terminology note: this extension supports `PI_TEAMS_STYLE=<style>`.
+> This doc often uses “comrade” as a generic stand-in for “worker/teammate”, but **styles can customize terminology, naming, and lifecycle copy**.
+> Built-ins: `normal`, `soviet`, `pirate`. Custom styles live under `~/.pi/agent/teams/_styles/`.
+
+## Scope / philosophy
+
+- Target the **same coordination primitives** as Claude Teams:
+  - shared task list
+  - mailbox messaging
+  - long-lived workers
+- Prefer **inspectable, local-first artifacts** (files + lock files).
+- Avoid guidance that bypasses Claude feature gating; we only document behavior.
+- Accept that some Claude UX (terminal keybindings + split-pane integration) may not be achievable in Pi without deeper TUI/terminal integration.
+
+## Pi-specific extras (not Claude parity)
+
+These are intentional differences / additions:
+
+- **Configurable styles** (`/team style …`) for terminology + naming + lifecycle copy.
+- **Git worktrees** for isolation (`/team spawn <name> … worktree`).
+- **Session branching** (clone leader context into a teammate).
+- A **status widget + interactive panel** (`/tw`, `/team panel`).
+
+## Parity matrix (docs-oriented)
+
+Legend: ✅ implemented • 🟡 partial • ❌ missing
+
+| Area | Claude docs behavior | Pi Teams status | Notes / next step | Priority |
+| --- | --- | --- | --- | --- |
+| Enablement | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` + settings | N/A | Pi extension is available when installed/loaded. | — |
+| Team config | `~/.claude/teams/<team>/config.json` w/ members | ✅ | `extensions/teams/team-config.ts` (under `~/.pi/agent/teams/...` or `PI_TEAMS_ROOT_DIR`). | P0 |
+| Task list (shared) | `~/.claude/tasks/<taskListId>/` + states + deps | ✅ | File-per-task + deps (`blockedBy`/`blocks`); `/team task dep add|rm|ls`; self-claim skips blocked tasks. | P0 |
+| Self-claim | Comrades self-claim next unassigned, unblocked task; file locking | ✅ | `claimNextAvailableTask()` + locks; enabled by default (`PI_TEAMS_DEFAULT_AUTO_CLAIM=1`). | P0 |
+| Explicit assign | Lead assigns task to comrade | ✅ | `/team task assign` sets owner + pings via mailbox. | P0 |
+| “Message” vs “broadcast” | Send to one comrade or all comrades | ✅ | `/team dm` + `/team broadcast` use mailbox; `/team send` uses RPC. Recipients = config workers + RPC map + active task owners. | P0 |
+| Comrade↔comrade messaging | Comrades message each other directly | ✅ | Worker tool `team_message`; messages via mailbox + CC leader via `peer_dm_sent`. | P1 |
+| Display modes | In-process selection (Shift+Up/Down); split panes (tmux/iTerm) | ❌ | Pi has widget/panel + commands, but no terminal-level comrade navigation/panes. | P2 |
+| Delegate mode | Lead restricted to coordination-only tools | ✅ | `/team delegate [on|off]`; `tool_call` blocks `bash/edit/write`; widget shows `[delegate]`. | P1 |
+| Plan approval | Comrade can be “plan required” and needs lead approval to implement | ✅ | `/team spawn <name> plan` → read-only tools; sends `plan_approval_request`; `/team plan approve|reject`. | P1 |
+| Shutdown handshake | Lead requests shutdown; comrade can approve/reject | ✅ | Protocol: `shutdown_request` → `shutdown_approved` / `shutdown_rejected`. `/team shutdown <name>` (graceful), `/team kill <name>` (SIGTERM). Wording is style-controlled (e.g. “was asked to shut down”, “walked the plank”). | P1 |
+| Cleanup team | “Clean up the team” removes shared resources after comrades stopped | ✅ | `/team cleanup [--force]` deletes only `<teamsRoot>/<teamId>` after safety checks. | P1 |
+| Hooks / quality gates | `ComradeIdle`, `TaskCompleted` hooks | 🟡 | Optional leader-side hook runner (idle/task-complete/task-fail) via `PI_TEAMS_HOOKS_ENABLED=1` + scripts under `_hooks/`; inline failure surfacing + failure-action policies (`warn`/`followup`/`reopen`/`reopen_followup`) implemented; stable hook context payload exposed via `PI_TEAMS_HOOK_CONTEXT_JSON` + auto-remediation flow (reopen cap / follow-up owner policy / teammate notification). Runtime policy changes are agent-invocable via `teams` actions (`hooks_policy_get` / `hooks_policy_set`). | P2 |
+| Task list UX | Ctrl+T toggle; show all/clear tasks by asking | 🟡 | Widget + `/team task list` + `/team task show` + `/team task clear`; panel supports fast `t`/`shift+t` toggle into task-centric view (`Ctrl+T` is reserved by Pi for thinking blocks). | P0 |
+| Shared task list across sessions | `CLAUDE_CODE_TASK_LIST_ID=...` | ✅ | Worker env: `PI_TEAMS_TASK_LIST_ID` (manual workers). Leader: `/team task use <taskListId>` (persisted). Newly spawned workers inherit; existing workers need restart. | P1 |
+| Join/attach flow | Join existing team context from another running session | 🟡 | `/team attach list`, `/team attach <teamId> [--claim]`, `/team detach` plus claim heartbeat/takeover handshake added. Widget/panel now show attached-mode banner + detach hint. | P2 |
+
+## Prioritized roadmap
+
+### P0 (done): collaboration primitives parity
+
+1) **Task dependency commands + UX** ✅
+   - `/team task dep add <id> <depId>` / `dep rm ...` / `dep ls <id>`
+   - `task list` output shows blocked status + deps/blocks summary
+   - `/team task show <id>` shows full description + `metadata.result`
+
+2) **Broadcast messaging** ✅
+   - `/team broadcast <msg...>` (mailbox broadcast)
+
+3) **Task list hygiene** ✅
+   - `/team task clear [completed|all] [--force]` (safe delete within `teamsRoot/teamId`)
+
+### P1 (done): governance + lifecycle parity
+
+4) **Shutdown handshake** ✅
+   - `shutdown_request` → `shutdown_approved` / `shutdown_rejected`
+   - Worker rejects when busy (streaming + active task), auto-approves when idle
+   - `/team shutdown <name> [reason...]` (graceful), `/team kill <name>` (force)
+
+5) **Plan approval** ✅
+   - `/team spawn <name> ... plan` sets `PI_TEAMS_PLAN_REQUIRED=1`
+   - Worker starts read-only; submits `plan_approval_request`
+   - `/team plan approve|reject <name>`
+   - Agent-driven equivalent via `teams` tool: `plan_approve` / `plan_reject`
+
+6) **Delegate mode (leader)** ✅
+   - `/team delegate [on|off]` (or `PI_TEAMS_DELEGATE_MODE=1`)
+   - Blocks `bash/edit/write` while active
+
+7) **Cleanup** ✅
+   - `/team cleanup [--force]` deletes only `<teamsRoot>/<teamId>` after safety checks.
+
+8) **Peer-to-peer messaging** ✅
+   - Worker tool `team_message`
+   - Mailbox transport; leader CC notifications
+
+9) **Shared task list across sessions** ✅
+   - `/team task use <taskListId>` + persisted `config.json`
+
+### P2: UX + “product-level” parity
+
+10) **Hooks / quality gates** 🟡 (partial)
+   - Implemented: optional leader-side hook runner (opt-in + timeout + logs).
+   - Implemented: inline failure surfacing (task metadata + widget warning + task-panel/task-show quality-gate details).
+   - Implemented: hook-failure policy controls via `PI_TEAMS_HOOKS_FAILURE_ACTION` (`warn`, `followup`, `reopen`, `reopen_followup`).
+   - Implemented: runtime team-level policy overrides (via `teams` tool: `hooks_policy_get` / `hooks_policy_set`) layered over env defaults.
+   - Implemented: standardized hook context contract (`PI_TEAMS_HOOK_CONTEXT_VERSION=1`, `PI_TEAMS_HOOK_CONTEXT_JSON`).
+   - Implemented: autonomous remediation helpers (auto-reopen cap, follow-up owner policy, teammate remediation notification).
+   - Implemented: deterministic integration coverage (`scripts/integration-hooks-remediation-test.mts`) for failed hook -> reopen/follow-up/nudge flow.
+   - Still missing: broader contract versioning story + richer policy visualization UX.
+
+11) **Better comrade interaction UX (within Pi constraints)** 🟡 (partial)
+   - Implemented: panel overview shows selected teammate context (active/last completed task + last transcript event).
+   - Implemented: faster keyboard controls (`w/s`, `1-9`, `m/d`).
+   - Implemented: task-centric panel mode (`t`/`shift+t`) with owned-task drilldown, dependency/block visibility, and quick jump back to transcript (`Ctrl+T` reserved by Pi).
+   - Implemented: in-panel task mutations for selected task (`c` complete, `p` pending, `i` in-progress, `u` unassign).
+   - Implemented: in-panel reassignment flow (`r`) with teammate picker.
+   - Implemented: agent-invocable task mutations via `teams` tool (`task_assign`, `task_unassign`, `task_set_status`) so flows do not require manual panel interaction.
+   - Implemented: agent-invocable dependency/messaging actions via `teams` tool (`task_dep_add|rm|ls`, `message_dm|broadcast|steer`).
+   - Implemented: agent-invocable lifecycle actions via `teams` tool (`member_spawn|shutdown|kill|prune`).
+   - Implemented: agent-invocable governance actions via `teams` tool (`plan_approve|plan_reject`).
+   - Implemented: agent-invocable model policy introspection/check actions via `teams` tool (`model_policy_get|model_policy_check`) to validate spawn overrides before execution.
+   - Next: optional tmux split-pane integration and deeper dependency/task editing flows in panel.
+
+12) **Join/attach flow** 🟡 (partial)
+   - Implemented: `/team attach list`, `/team attach <teamId> [--claim]`, `/team detach`.
+   - Implemented: explicit attach claim handshake with heartbeat + force takeover (`--claim`).
+   - Implemented: attached-mode affordances in widget/panel (external team banner + `/team detach` hint).
+
+## Where changes would land (code map)
+
+- Leader orchestration: `extensions/teams/leader.ts`
+- Leader `/team` command dispatch: `extensions/teams/leader-team-command.ts`
+- Attach/discovery commands: `extensions/teams/leader-attach-commands.ts`, `extensions/teams/team-discovery.ts`, `extensions/teams/team-attach-claim.ts`
+- Leader LLM tool (`teams`): `extensions/teams/leader-teams-tool.ts`
+- Worker mailbox polling + self-claim + protocols: `extensions/teams/worker.ts`
+- Task store + locking: `extensions/teams/task-store.ts`, `extensions/teams/fs-lock.ts`
+- Mailbox store + locking: `extensions/teams/mailbox.ts`
+- Team config: `extensions/teams/team-config.ts`
+- Styles + naming: `extensions/teams/teams-style.ts`
+- Optional workspace isolation: `extensions/teams/worktree.ts`
+
+## Testing strategy
+
+- Keep tests hermetic by setting `PI_TEAMS_ROOT_DIR` to a temp directory.
+- Extend:
+  - `scripts/smoke-test.mts` (run via `npm run smoke-test`) for filesystem-only behaviors
+  - `scripts/e2e-rpc-test.mjs` for protocol flows (shutdown handshake, plan approval)

package/docs/field-notes-teams-setup.md

@@ -0,0 +1,107 @@
+# Field notes: using `indus-swarms` (pi-agent-teams) for real (setup + surprises)
+
+Date: 2026-02-07
+
+Goal: dogfood the Teams extension to implement its own roadmap (Claude parity), and capture anything that surprised/confused us while setting it up.
+
+> Terminology note: the extension supports `PI_TEAMS_STYLE=<style>`. Built-ins: `normal`, `soviet`, `pirate`. You can also add custom styles via `~/.pi/agent/teams/_styles/<style>.json`.
+
+## Test run: test1
+
+Decisions: tmux session `pi-teams-test1`; `PI_TEAMS_ROOT_DIR=~/projects/indus-swarms/test1`; `teamId=0baaa0e6-8020-4d9a-bf33-c1a65f99a2f7`; workers started manually in tmux (not `/team spawn`).
+
+First impressions:
+- Manual tmux workers are usable. Initially the leader showed “(no comrades)” because it only tracked RPC-spawned workers; now manual workers **upsert themselves into `config.json` on startup**, and the leader widget renders online workers from team config.
+- Pinning `PI_TEAMS_ROOT_DIR` made reruns/id discovery predictable (no “find the new folder” step).
+- tmux workflow feels close to Claude-style split panes; bootstrap ergonomics still need smoothing.
+- Surprise: `/team spawn <name> branch` failed once with `Entry <id> not found` (branch-from leaf missing on disk); `/team spawn <name> fresh` worked.
+- Surprise (automation): when driving the leader via `tmux send-keys`, back-to-back `/team ...` commands sometimes only executed the first one unless we inserted a small delay.
+
+## Setup (tmux-based)
+
+### Why tmux?
+
+- Pi sessions are long-lived and interactive.
+- Our harness (and many CI environments) dislike background processes that keep stdio open.
+- tmux gives us:
+  - a stable place to run a leader session
+  - optional separate panes/windows for worker sessions
+  - the ability to attach/detach without killing the team
+
+### Environment knobs used
+
+- `PI_TEAMS_ROOT_DIR` — isolate Teams artifacts from `~/.pi/agent/teams` while experimenting.
+  - Recommendation: use a *fresh, empty* temp directory per run so it’s easy to discover the current teamId by listing the directory.
+
+### Session bootstrap (manual)
+
+(There is also a helper script now: `./scripts/start-tmux-team.sh`.)
+
+1. Pick a temp Teams root:
+
+   ```bash
+   export PI_TEAMS_ROOT_DIR="/tmp/pi-teams-$(date +%Y%m%d-%H%M%S)"
+   mkdir -p "$PI_TEAMS_ROOT_DIR"
+   ```
+
+2. Start leader in tmux:
+
+   ```bash
+   tmux new -s pi-teams -c ~/projects/indus-swarms \
+     "PI_TEAMS_ROOT_DIR=$PI_TEAMS_ROOT_DIR indusagi -e ~/projects/indus-swarms/extensions/teams/index.ts"
+   ```
+
+3. In the leader session:
+
+   ```
+   /team help
+   /team spawn alice branch
+   /team spawn bob branch
+   /team task add alice: add /team broadcast command
+   /team task add bob: add task dependency commands
+   /team task list
+   ```
+
+4. Optional: start **interactive worker panes** (instead of leader-spawned RPC workers).
+
+   This currently requires discovering the leader’s `teamId` first (see “Surprises” below).
+
+## Surprises / confusion points (so far)
+
+- **TeamId discoverability**: the leader uses `sessionId` as `teamId`. That’s convenient internally, but not obvious externally.
+  - Workaround used: point `PI_TEAMS_ROOT_DIR` at a fresh directory and `ls` it to find the generated `<teamId>` folder.
+  - Note: the team directory isn’t necessarily created instantly on process start (we saw a short delay), so scripts may need a small retry loop.
+  - Update: implemented `/team id` and `/team env <name>` (prints env vars + a one-liner to start a manual worker).
+
+- **tmux vs `/team spawn`**: `/team spawn` uses `indusagi --mode rpc` subprocesses.
+  - Pros: simple, managed lifecycle.
+  - Cons: you don’t see a full interactive comrade UI like Claude’s split-pane mode.
+  - We manually started workers in separate tmux windows (setting `PI_TEAMS_WORKER=1`, `PI_TEAMS_TEAM_ID=...`, etc). This now shows up in the leader widget because workers upsert themselves into `config.json`, and the leader renders online workers from team config.
+  - Update: leader now renders comrades from `team config` and also auto-adds unknown senders on idle notifications (so manual tmux workers feel first-class).
+  - Improvement idea: optional spawn mode that starts a worker in a new tmux pane/window.
+
+- **Two messaging paths** (`/team send` vs `/team dm`):
+  - `/team send` = RPC prompt (immediate “user message”)
+  - `/team dm` = mailbox message (Claude-style)
+  - Improvement idea: clearer naming and/or a single “message” command with a mode flag.
+
+- **Runaway tasks / timeboxing**: a vague task prompt can turn into a long “research spiral”.
+  - In manual-tmux mode, there isn’t a great way (yet) for the leader to *steer* an in-flight run (unlike `/team steer` for RPC-spawned comrades).
+  - Improvement idea: add a mailbox-level “steer” protocol message that workers can treat as an in-flight follow-up if they’re currently running.
+
+- **Failure semantics are underspecified**: tool failures show up in the worker UI, but our task store currently only supports `pending|in_progress|completed`.
+  - Update: `/team stop <name>` now sends a mailbox `abort_request`; workers treat aborts as aborts and reset the task back to `pending` (keeping the `owner`) instead of marking it `completed` with an empty result.
+  - Improvement idea: add `failed` status (and have workers write `metadata.failureReason` + include it in idle notifications), and only mark `completed` when we have an explicit success signal.
+
+- **Worker shutdown + self-claim interaction**: when a worker receives SIGTERM it unassigns its non-completed tasks; other idle workers may immediately self-claim those now-unowned tasks.
+  - This is good for liveness, but surprising the first time you see task ownership “jump”.
+
+- **Nice surprise: results are persisted with the task**: on completion, the worker writes `metadata.result` + `metadata.completedAt` into the task JSON file.
+  - This made it easy to recover outputs even after closing tmux windows.
+
+## Next notes to capture
+
+- How easy it is to recover after restarting the leader
+- How often we hit file/lock contention
+- Whether auto-claim behavior matches expectations in mixed assigned/unassigned task lists
+- Whether worktree mode is essential in practice (and what breaks when no git repo exists)

package/docs/smoke-test-plan.md

@@ -0,0 +1,146 @@
+# indus-swarms (pi-agent-teams extension) — Runtime Smoke Test Plan
+
+## Prerequisites
+
+- `indusagi` CLI installed (`indusagi --version` → `0.12.x+`)
+- `node_modules/` present (run `npm install` or symlink from main repo)
+- `npx tsx` available for running `.mts` test scripts
+
+## 1. Automated Unit Smoke Test (no interactive session)
+
+Exercises all core primitives directly via `tsx`:
+
+```bash
+npx tsx scripts/smoke-test.mts
+# or: npm run smoke-test
+```
+
+**What it tests** (overview):
+
+| Module           | Coverage                                                        |
+|------------------|-----------------------------------------------------------------|
+| `names.ts`       | `sanitizeName` character replacement, edge cases                |
+| `fs-lock.ts`     | `withLock` returns value, cleans up lock file                   |
+| `mailbox.ts`     | `writeToMailbox`, `popUnreadMessages`, read-once semantics      |
+| `task-store.ts`  | CRUD, `startAssignedTask`, `completeTask`, `claimNextAvailable`,|
+|                  | `unassignTasksForAgent`, dependencies, `clearTasks`             |
+| `team-config.ts` | `ensureTeamConfig` (idempotent), `upsertMember`, `setMemberStatus`, `loadTeamConfig` |
+| `protocol.ts`    | Structured message parsers (valid + invalid JSON + wrong type)  |
+| `indusagi` CLI   | `indusagi --version` executes (skipped in CI if `indusagi` not on PATH)     |
+
+**Expected result:** `PASSED: <n>  FAILED: 0`
+
+## 2. Extension Loading Test
+
+Verify Pi can load the extension entry point without crashing:
+
+```bash
+indusagi --no-extensions -e extensions/teams/index.ts --help
+```
+
+**Expected:** exits 0, shows Pi help output (no TypeScript/import errors).
+
+## 3. Interactive Smoke Test (manual)
+
+### 3a. Launch Pi with the extension
+
+```bash
+# From the repo root:
+indusagi --no-extensions -e extensions/teams/index.ts
+```
+
+Or, if the extension is symlinked into `~/.pi/agent/extensions/indus-swarms`:
+
+```bash
+indusagi   # auto-loads from extensions dir
+```
+
+### 3b. Check extension is active
+
+```
+/team help
+```
+
+**Expected:** shows usage lines for `/team spawn`, `/team task`, etc.
+
+### 3c. Spawn a teammate ("comrade" in soviet style)
+
+```
+/team spawn agent1 fresh shared
+```
+
+**Expected:** notification "Spawned agent1" or similar, widget shows `Teammate agent1: idle` (or `Comrade agent1: idle` in soviet style).
+
+### 3d. Create and assign a task
+
+```
+/team task add agent1: Say hello
+/team task list
+```
+
+**Expected:** task #1 created, assigned to agent1, status `pending` → `in_progress`.
+
+### 3e. Verify mailbox delivery
+
+```
+/team dm agent1 ping from lead
+```
+
+**Expected:** "DM queued for agent1" notification.
+
+### 3f. Delegate via tool
+
+Ask the model:
+> "Delegate a task to agent1: write a haiku about coding"
+
+**Expected:** the `teams` tool is invoked, task created and assigned.
+
+### 3g. Shutdown
+
+```
+/team shutdown agent1
+/team kill agent1
+```
+
+**Expected:** agent1 goes offline, widget updates.
+
+Optional: stop all teammates without ending the leader session:
+
+```
+/team shutdown
+```
+
+**Expected:** all teammates stop; leader remains active until you exit it (e.g. ctrl+d).
+
+If old/manual teammates still show as idle (stale config entries), prune them:
+
+```
+/team prune
+# or: /team prune --all
+```
+
+## 4. Worker-side Smoke (verifying child process)
+
+To test the worker role directly:
+
+```bash
+PI_TEAMS_WORKER=1 \
+PI_TEAMS_TEAM_ID=test-team \
+PI_TEAMS_AGENT_NAME=agent1 \
+PI_TEAMS_LEAD_NAME=team-lead \
+PI_TEAMS_STYLE=normal \
+indusagi --no-extensions -e extensions/teams/index.ts --mode rpc
+```
+
+**Expected:** process starts in RPC mode, registers `team_message` tool, polls mailbox.
+
+## 5. Checklist Summary
+
+| # | Test                          | Method     | Status |
+|---|-------------------------------|------------|--------|
+| 1 | Unit primitives (60 asserts)  | Automated  | ✅     |
+| 2 | Extension loading             | CLI        | ✅     |
+| 3 | Interactive spawn/task/dm     | Manual     | 📋     |
+| 4 | Worker-side RPC               | Manual     | 📋     |
+
+✅ = verified in this run, 📋 = documented for manual execution.

package/eslint.config.js

@@ -0,0 +1,74 @@
+// @ts-check
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+	{
+		ignores: [
+			"node_modules/**",
+			"dist/**",
+			"build/**",
+			"coverage/**",
+			".artifacts/**",
+			".research/**",
+			".resume-sessions/**",
+		],
+	},
+
+	eslint.configs.recommended,
+	...tseslint.configs.recommended,
+
+	{
+		files: ["extensions/**/*.ts", "scripts/**/*.ts", "scripts/**/*.mts"],
+		rules: {
+			// ━━ Project invariants (AGENTS.md) ━━
+			"@typescript-eslint/no-explicit-any": "error",
+			"@typescript-eslint/no-non-null-assertion": "error",
+			"@typescript-eslint/ban-ts-comment": [
+				"error",
+				{
+					"ts-ignore": true,
+					"ts-expect-error": true,
+					"ts-nocheck": true,
+					"ts-check": false,
+				},
+			],
+
+			// Imports/types
+			"@typescript-eslint/consistent-type-imports": [
+				"error",
+				{ prefer: "type-imports", disallowTypeAnnotations: false },
+			],
+
+			// General correctness
+			eqeqeq: ["error", "always"],
+
+			// Prefer TS-aware unused-vars
+			"no-unused-vars": "off",
+			"@typescript-eslint/no-unused-vars": [
+				"warn",
+				{
+					argsIgnorePattern: "^_",
+					varsIgnorePattern: "^_",
+					caughtErrorsIgnorePattern: "^_",
+				},
+			],
+		},
+	},
+
+	// Scripts/tests: console is expected
+	{
+		files: ["scripts/**/*.ts", "scripts/**/*.mts"],
+		rules: {
+			"no-console": "off",
+		},
+	},
+
+	// Extension source: discourage stray console.log
+	{
+		files: ["extensions/**/*.ts"],
+		rules: {
+			"no-console": "warn",
+		},
+	},
+);

package/extensions/teams/README.md

@@ -0,0 +1,23 @@
+# pi-teams (extension)
+
+This directory contains the **Teams** extension entrypoint:
+
+- `index.ts` (leader/worker dispatch)
+
+The full project README (usage, commands, tests) lives at the repo root:
+
+- `../../README.md`
+
+## Storage root override
+
+By default, all Teams artifacts are stored under the Pi agent directory:
+
+- `~/.pi/agent/teams/<teamId>/...`
+
+For tests/CI (or if you want to keep Teams state separate), set:
+
+- `PI_TEAMS_ROOT_DIR=/absolute/path`
+
+Then the extension will store:
+
+- `<PI_TEAMS_ROOT_DIR>/<teamId>/...`