@tmustier/pi-agent-teams 0.1.1

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,166 @@
+# pi-agent-teams
+
+An experimental [Pi](https://pi.dev) extension that brings [Claude Code agent teams](https://code.claude.com/docs/en/agent-teams) to Pi. Spawn teammates, share a task list, and coordinate work across multiple Pi sessions.
+
+> **Status:** MVP (command-driven + status widget). See [`docs/claude-parity.md`](docs/claude-parity.md) for the full roadmap.
+
+## Features
+
+Core agent-teams primitives, matching Claude's design:
+
+- **Shared task list** — file-per-task on disk with three states (pending / in-progress / completed) and dependency tracking so blocked tasks stay blocked until their prerequisites finish.
+- **Auto-claim** — idle teammates automatically pick up the next unassigned, unblocked task. No manual dispatching required (disable with `PI_TEAMS_DEFAULT_AUTO_CLAIM=0`).
+- **Direct messages and broadcast** — send a message to one teammate or all of them at once, via file-based mailboxes.
+- **Graceful lifecycle** — spawn, stop, shutdown (with handshake), or kill teammates. The leader tracks who's online, idle, or streaming.
+- **LLM-callable delegate tool** — the model can spawn teammates and create/assign tasks in a single tool call, no slash commands needed.
+- **Team cleanup** — tear down all team artifacts (tasks, mailboxes, sessions, worktrees) when you're done.
+
+Additional Pi-specific capabilities:
+
+- **Git worktrees** — optionally give each teammate its own worktree so they work on isolated branches without conflicting edits.
+- **Session branching** — clone the leader's conversation context into a teammate so it starts with full awareness of the work so far, instead of from scratch.
+
+## Install
+
+**Option A — install from npm:**
+
+```bash
+pi install npm:@tmustier/pi-agent-teams
+```
+
+**Option B — load directly (dev):**
+
+```bash
+pi -e ~/projects/pi-agent-teams/extensions/teams/index.ts
+```
+
+**Option C — install from a local folder:**
+
+```bash
+pi install ~/projects/pi-agent-teams
+```
+
+Then run `pi` normally; the extension auto-discovers.
+
+Verify with `/team id` — it should print the current team info.
+
+## Quick start
+
+```
+# In a Pi session with the extension loaded:
+
+/team spawn alice                          # spawn a teammate (fresh session, shared workspace)
+/team spawn bob branch worktree            # spawn with leader context + isolated worktree
+
+/team task add alice: Fix failing tests    # create a task and assign it to alice
+/team task add Refactor auth module        # unassigned — auto-claimed by next idle teammate
+
+/team dm alice Check the edge cases too    # direct message
+/team broadcast Wrapping up soon           # message everyone
+
+/team shutdown alice                       # graceful shutdown (handshake)
+/team cleanup                              # remove team artifacts when done
+```
+
+Or let the model drive it with the delegate tool:
+
+```json
+{
+  "action": "delegate",
+  "contextMode": "branch",
+  "workspaceMode": "worktree",
+  "teammates": ["alice", "bob"],
+  "tasks": [
+    { "text": "Fix failing unit tests" },
+    { "text": "Refactor auth module" }
+  ]
+}
+```
+
+## Commands
+
+All commands live under `/team`.
+
+### Teammates
+
+| Command | Description |
+| --- | --- |
+| `/team spawn <name> [fresh\|branch] [shared\|worktree]` | Start a teammate |
+| `/team list` | List teammates and their status |
+| `/team send <name> <msg>` | Send a prompt over RPC |
+| `/team steer <name> <msg>` | Redirect an in-flight run |
+| `/team dm <name> <msg>` | Send a mailbox message |
+| `/team broadcast <msg>` | Message all teammates |
+| `/team stop <name> [reason]` | Abort current work (resets task to pending) |
+| `/team shutdown <name> [reason]` | Graceful shutdown (handshake) |
+| `/team shutdown` | Shutdown leader + all teammates |
+| `/team kill <name>` | Force-terminate |
+| `/team cleanup [--force]` | Delete team artifacts |
+| `/team id` | Print team/task-list IDs and paths |
+| `/team env <name>` | Print env vars to start a manual worker |
+
+### Tasks
+
+| Command | Description |
+| --- | --- |
+| `/team task add <text>` | Create a task (prefix with `name:` to assign) |
+| `/team task assign <id> <agent>` | Assign a task |
+| `/team task unassign <id>` | Remove assignment |
+| `/team task list` | Show tasks with status, deps, blocks |
+| `/team task show <id>` | Full description + result |
+| `/team task dep add <id> <depId>` | Add a dependency |
+| `/team task dep rm <id> <depId>` | Remove a dependency |
+| `/team task dep ls <id>` | Show deps and blocks |
+| `/team task clear [completed\|all]` | Delete task files |
+
+## Configuration
+
+| Environment variable | Purpose | Default |
+| --- | --- | --- |
+| `PI_TEAMS_ROOT_DIR` | Storage root (absolute or relative to `~/.pi/agent`) | `~/.pi/agent/teams` |
+| `PI_TEAMS_DEFAULT_AUTO_CLAIM` | Whether spawned teammates auto-claim tasks | `1` (on) |
+
+## Storage layout
+
+```
+<teamsRoot>/<teamId>/
+  config.json                          # team metadata + members
+  tasks/<taskListId>/
+    1.json, 2.json, ...                # one file per task
+    .highwatermark                      # next task ID
+  mailboxes/<namespace>/inboxes/
+    <agent>.json                        # per-agent inbox
+  sessions/                             # teammate session files
+  worktrees/<agent>/                    # git worktrees (when enabled)
+```
+
+## Development
+
+### Smoke test (no API keys)
+
+```bash
+node scripts/smoke-test.mjs
+```
+
+Filesystem-level test of the task store, mailbox, and team config.
+
+### E2E RPC test (spawns pi + one teammate)
+
+```bash
+node scripts/e2e-rpc-test.mjs
+```
+
+Starts a leader in RPC mode, spawns a worker, runs a shutdown handshake, verifies cleanup. Sets `PI_TEAMS_ROOT_DIR` to a temp directory so nothing touches `~/.pi/agent/teams`.
+
+### tmux dogfooding
+
+```bash
+./scripts/start-tmux-team.sh pi-teams alice bob
+tmux attach -t pi-teams
+```
+
+Starts a leader + one tmux window per worker for interactive testing.
+
+## License
+
+MIT (see [`LICENSE`](LICENSE)).

package/docs/claude-parity.md

@@ -0,0 +1,109 @@
+# Claude Agent Teams parity roadmap (pi-agent-teams)
+
+Last updated: 2026-02-07
+
+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:
+
+- `pi-agent-teams` (Pi extension)
+
+## Scope / philosophy
+
+- Target the **same coordination primitives** as Claude Teams:
+  - shared task list
+  - mailbox messaging
+  - long-lived teammates
+- 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.
+
+## 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 always available when installed/loaded. | — |
+| Team config | `~/.claude/teams/<team>/config.json` w/ members | ✅ | Implemented via `extensions/teams/team-config.ts` (stored 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 | Teammates can self-claim next unassigned, unblocked task; file locking | ✅ | Implemented: `claimNextAvailableTask()` + locks; enabled by default (`PI_TEAMS_DEFAULT_AUTO_CLAIM=1`). | P0 |
+| Explicit assign | Lead assigns task to teammate | ✅ | `/team task assign` sets owner + pings via mailbox. | P0 |
+| “Message” vs “broadcast” | Send to one teammate or all teammates | ✅ | `/team dm` + `/team broadcast` use mailbox; `/team send` uses RPC. Broadcast recipients = team config workers + RPC-spawned map + active task owners; manual tmux workers self-register into `config.json` on startup. | P0 |
+| Teammate↔teammate messaging | Teammates can message each other directly | ❌ | Worker needs peer discovery (read team config) + send command/tool. | P1 |
+| Display modes | In-process selection (Shift+Up/Down); split panes (tmux/iTerm) | ❌ | Pi has a widget + commands, but no terminal-level teammate navigation/panes. | P2 |
+| Delegate mode | Lead restricted to coordination-only tools | ❌ | Add a leader “delegate mode” switch that blocks edit/write/bash tools (soft or enforced). | P1 |
+| Plan approval | Teammate can be “plan required” and needs lead approval to implement | ❌ | Likely implement by spawning with read-only tool set until approved, then restart worker with full tools. | P1 |
+| Shutdown handshake | Lead requests shutdown; teammate can approve/reject | 🟡 | Implemented `shutdown_request` → `shutdown_approved` via mailbox + `/team shutdown <name>` (auto-approve; no reject yet). | P1 |
+| Cleanup team | “Clean up the team” removes shared resources after teammates stopped | ✅ | `/team cleanup [--force]` deletes only `<teamsRoot>/<teamId>` after safety checks. | P1 |
+| Hooks / quality gates | `TeammateIdle`, `TaskCompleted` hooks | ❌ | Add optional hook runner in leader on idle/task-complete events (script execution + exit-code gating). | P2 |
+| Task list UX | Ctrl+T toggle; show all/clear tasks by asking | 🟡 | Widget + `/team task list` show blocked/deps; `/team task show <id>`; `/team task clear [completed|all]`. No Ctrl+T toggle yet. | P0 |
+| Shared task list across sessions | `CLAUDE_CODE_TASK_LIST_ID=...` | 🟡 | Pi supports `PI_TEAMS_TASK_LIST_ID` env (worker side) but leader doesn’t expose a stable “named task list id” workflow yet. | P1 |
+
+## 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: governance + lifecycle parity
+
+4) **Shutdown handshake** 🟡
+   - Mailbox protocol: `shutdown_request` → `shutdown_approved` (no reject yet)
+   - Leader command: `/team shutdown <name> [reason...]` (graceful), keep `/team kill` as force
+
+5) **Plan approval**
+   - Spawn option: `--plan-required` / `/team spawn <name> plan` (naming TBD)
+   - Worker flow: produce plan → send approval request → wait → implement after approval
+   - Enforcement idea: start worker with tools excluding write/edit/bash, then restart same session with full tool set after approval
+
+6) **Delegate mode (leader)**
+   - A toggle (env or command) that prevents the leader from doing code edits and focuses it on coordination.
+   - In Pi, likely implemented as: leader tool wrapper refuses `bash/edit/write` while delegate mode is on.
+
+7) **Cleanup** ✅
+   - `/team cleanup [--force]` deletes only `<teamsRoot>/<teamId>` after safety checks.
+   - Refuses if RPC teammates are running or there are `in_progress` tasks unless `--force`.
+
+### P2: UX + “product-level” parity
+
+8) **Better teammate interaction UX**
+   - Explore whether Pi’s TUI API can support:
+     - selecting a teammate from the widget
+     - “entering” a teammate transcript view
+   - (Optional) tmux integration for split panes.
+
+9) **Hooks / quality gates**
+   - Support scripts that run on idle/task completion (similar to Claude hooks).
+
+10) **Join/attach flow**
+   - Allow a running session to attach to an existing team (discover + approve join).
+
+## Where changes would land (code map)
+
+- Leader orchestration + commands + tool: `extensions/teams/leader.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`
+- 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.mjs` for filesystem-only behaviors (deps, claiming, locking)
+  - `scripts/e2e-rpc-test.mjs` for protocol flows (shutdown handshake, plan approval)

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

@@ -0,0 +1,105 @@
+# Field notes: using `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.
+
+## Test run: test1
+
+Decisions: tmux session `pi-teams-test1`; `PI_TEAMS_ROOT_DIR=~/projects/pi-agent-teams/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 teammates)” 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/pi-agent-teams \
+     "PI_TEAMS_ROOT_DIR=$PI_TEAMS_ROOT_DIR pi -e ~/projects/pi-agent-teams/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 `pi --mode rpc` subprocesses.
+  - Pros: simple, managed lifecycle.
+  - Cons: you don’t see a full interactive teammate 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 teammates 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 teammates).
+  - 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/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>/...`

package/extensions/teams/cleanup.ts

@@ -0,0 +1,31 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export function assertTeamDirWithinTeamsRoot(teamsRootDir: string, teamDir: string): {
+	teamsRootAbs: string;
+	teamDirAbs: string;
+} {
+	const teamsRootAbs = path.resolve(teamsRootDir);
+	const teamDirAbs = path.resolve(teamDir);
+
+	const rel = path.relative(teamsRootAbs, teamDirAbs);
+	// rel === "" => same path (would delete the whole root)
+	// rel starts with ".." or is absolute => outside root
+	if (!rel || rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
+		throw new Error(
+			`Refusing to operate on path outside teams root. teamsRootDir=${teamsRootAbs} teamDir=${teamDirAbs}`,
+		);
+	}
+
+	return { teamsRootAbs, teamDirAbs };
+}
+
+/**
+ * Recursively delete the given teamDir, but only if it's safely inside teamsRootDir.
+ *
+ * Uses fs.rm({ recursive: true, force: true }) so it's idempotent.
+ */
+export async function cleanupTeamDir(teamsRootDir: string, teamDir: string): Promise<void> {
+	const { teamDirAbs } = assertTeamDirWithinTeamsRoot(teamsRootDir, teamDir);
+	await fs.promises.rm(teamDirAbs, { recursive: true, force: true });
+}

package/extensions/teams/fs-lock.ts

@@ -0,0 +1,71 @@
+import * as fs from "node:fs";
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((r) => setTimeout(r, ms));
+}
+
+export interface LockOptions {
+	/** How long to wait to acquire the lock before failing. */
+	timeoutMs?: number;
+	/** If lock file is older than this, consider it stale and remove it. */
+	staleMs?: number;
+	/** Poll interval while waiting for lock. */
+	pollMs?: number;
+	/** Optional label to help debugging (written into lock file). */
+	label?: string;
+}
+
+export async function withLock<T>(lockFilePath: string, fn: () => Promise<T>, opts: LockOptions = {}): Promise<T> {
+	const timeoutMs = opts.timeoutMs ?? 10_000;
+	const staleMs = opts.staleMs ?? 60_000;
+	const pollMs = opts.pollMs ?? 50;
+	const start = Date.now();
+
+	let fd: number | null = null;
+
+	while (fd === null) {
+		try {
+			fd = fs.openSync(lockFilePath, "wx");
+			const payload = {
+				pid: process.pid,
+				createdAt: new Date().toISOString(),
+				label: opts.label,
+			};
+			fs.writeFileSync(fd, JSON.stringify(payload));
+		} catch (err: any) {
+			if (err?.code !== "EEXIST") throw err;
+
+			// Stale lock handling
+			try {
+				const st = fs.statSync(lockFilePath);
+				const age = Date.now() - st.mtimeMs;
+				if (age > staleMs) {
+					fs.unlinkSync(lockFilePath);
+					continue;
+				}
+			} catch {
+				// ignore: stat/unlink failures fall through to wait
+			}
+
+			if (Date.now() - start > timeoutMs) {
+				throw new Error(`Timeout acquiring lock: ${lockFilePath}`);
+			}
+			await sleep(pollMs);
+		}
+	}
+
+	try {
+		return await fn();
+	} finally {
+		try {
+			if (fd !== null) fs.closeSync(fd);
+		} catch {
+			// ignore
+		}
+		try {
+			fs.unlinkSync(lockFilePath);
+		} catch {
+			// ignore
+		}
+	}
+}

package/extensions/teams/index.ts

@@ -0,0 +1,18 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { runLeader } from "./leader.js";
+import { runWorker } from "./worker.js";
+
+/**
+ * pi-teams
+ *
+ * Two roles in one extension (Claude-style):
+ * - Leader process: spawn teammates, manage task list + mailbox UI/commands
+ * - Worker process: poll mailbox + auto-claim tasks from shared task list
+ */
+
+const IS_WORKER = process.env.PI_TEAMS_WORKER === "1";
+
+export default function (pi: ExtensionAPI) {
+	if (IS_WORKER) runWorker(pi);
+	else runLeader(pi);
+}