ac-teams 0.0.1 → 0.0.2

package/README.md

@@ -1,208 +1,53 @@
 # ac-teams
 
-Persistent Pi agents, shared tasks, and searchable messages, without a workflow engine or a background service. A member stays alive after an assignment so the same session can take more work.
+Persistent agent teams for [Pi](https://github.com/earendil-works/pi): shared tasks, searchable messages, and optional Git worktrees. Members stay alive between assignments and can resume their native Pi sessions after stopping. No workflow engine or background service.
 
-Local v0.0.1 implementation, tested on Linux with Pi 1.4.0. Not published to npm.
+## Install
 
-## Features at a glance
-
-Each column shows ac-teams alone or with one companion tool. A check mark (✓) means that setup provides the feature; a dash (-) means it does not.
-
-| Feature | Standalone ac-teams | + ACStack | + Herdr |
-| --- | --- | --- | --- |
-| Persistent Pi members and native session resume | ✓ | ✓ | ✓ |
-| Shared tasks, dependencies, and searchable messages | ✓ | ✓ | ✓ |
-| Optional isolated Git worktrees | ✓ | ✓ | ✓ |
-| Planning, review, and shipping skills | - | ✓ | - |
-| Terminal tabs, panes, and visible root sessions | - | - | ✓ |
-
-ACStack adds workflow guidance; Herdr adds terminal management. These are companion capabilities, not automatic integrations. ac-teams members run headlessly; Herdr does not automatically open a pane for each member.
-
-## Try it locally
-
-Requirements: Linux, Node 22.19 or newer, and an authenticated `pi` executable on `PATH`.
+Requires Linux, Node 22.19 or newer, and an authenticated `pi` executable on `PATH`. Interactive teams also require `tmux` on `PATH`. Tested with Pi 1.4.0.
 
 ```sh
-npm ci
-pi -e /absolute/path/to/ac-teams/src/index.ts
-```
-
-Load the extension once, either explicitly or through Pi package settings. Children load ac-teams explicitly and otherwise keep normal Pi extensions, skills, authentication, and cwd instructions. They receive their brief, not the parent's conversation.
-
-Use Pi's `/trust` command to approve each member's cwd before launching there. RPC children cannot answer Pi's initial trust prompt. ac-teams rejects readiness if project resources were skipped; it never auto-approves a project. A one-run approval in the root is not a saved approval for children or new worktrees.
-
-Other delegation tools can coexist. ac-teams warns when `Agent`, `SubagentWorkflow`, or `subagent` is active, but does not disable them. **Its limits cover only members launched through `team_agent`.** Use Pi's resource settings to disable other launchers if you want one team authority. Shell access and same-user extensions are not sandboxed.
-
-## Three tools, no prescribed workflow
-
-| Tool | Actions | Main rule |
-| --- | --- | --- |
-| `team_agent` | `launch`, `list`, `status`, `stop`, `resume`, `limits`, `cleanup` | A parent controls its descendants, not peers or ancestors |
-| `team_task` | `create`, `list`, `read`, `edit`, `claim`, `start`, `release`, `complete`, `reopen` | Checkout reserves work; dependencies gate starting, not ownership |
-| `team_message` | `send`, `history`, `search` | Recipients select who is notified, not who can read |
-
-`/teams` shows member status and native session/worktree locations. `/teams stop` stops every descendant. The root opens coordination state lazily on the first team request.
-
-### Give members bounded assignments
-
-Example `team_agent` arguments:
-
-```json
-{"action":"launch","brief":"Review src/parser.ts. Read only; do not delegate or edit. Send findings to root through team_message."}
+pi install npm:ac-teams@0.0.2
 ```
 
-`cwd` defaults to the requesting member's directory. `model` (`provider/model`) and `thinking` default to that member's current selection. An explicit override wins. Native Pi selects the model; provider/account rejections remain visible in member status and notify the parent. There is no automatic model retry.
-
-Launch returns a stable member ID, PID, cwd, and native session ID/path. Finishing a turn makes the member idle only after Pi reports `agent_settled`. It does not stop the process.
-
-Children can delegate through the same coordinator, subject to depth and capacity. Delegation still needs user authorization. Keep briefs bounded, agree on file ownership, and use separate worktrees for concurrent writers.
-
-### Share work without losing ownership
+Restart Pi after installation. Use Pi's `/trust` command to save approval for each project directory before launching members there; headless children cannot answer the initial trust prompt.
 
-```json
-{"action":"create","title":"Review parser errors","description":"Check malformed input and report concrete failures; no edits."}
-```
-
-Each task has three independent parts:
+## Use it
 
-- **Progress:** `status` is `todo`, `in_progress`, or `done`
-- **Ownership:** `owner` is one member ID, or absent
-- **Dependencies:** `dependencies` lists prerequisite task IDs. Returned `blockedBy` lists those not yet done; it is calculated, never stored as a status.
+Your Pi session is the root; its child agents are members. Ask Pi to delegate a bounded assignment, for example:
 
-Use the returned task ID with these actions:
+> Launch a member to review src/parser.ts without editing, and have it send findings back to me.
 
-| Action | Effect |
+| Tool | Purpose |
 | --- | --- |
-| `claim` | Reserve an unowned to-do task, even if blocked. Progress stays `todo`. |
-| `start` | The owner moves `todo` to `in_progress`, only when every dependency is `done`. |
-| `complete` | The owner moves `in_progress` to `done`, with `acceptance: true`. Ownership remains. |
-| `release` | Clear ownership. In-progress work returns to `todo`; done work stays `done`. |
-| `reopen` | Explicitly move `done` to `todo`, retaining any owner. Refused if a dependent is in progress or done. |
-
-Only the owner can start, complete, or release its work. An ancestor may explicitly release a stopped or interrupted descendant's ownership. The owner or root can reopen an owned task; any member can reopen an unowned one. Done tasks cannot be claimed until reopened.
-
-Include `dependencies` on creation or `edit`. Any member can edit unowned to-do work; only the owner can edit reserved to-do work. In-progress and done tasks cannot be edited. Unknown dependencies and cycles are rejected. An optional `revision` rejects stale mutations.
-
-`acceptance: true` asserts that the agent checked the acceptance criteria; it is not an independent test runner. Stop/crash retains ownership and progress. There is no automatic reassignment.
-
-### Send messages instead of polling
-
-```json
-{"action":"send","recipients":["root"],"text":"Parser review complete. No edits; two malformed-input cases need tests."}
-```
-
-Omit `recipients` to notify all other live members. Explicit sets must contain unique live member IDs; an invalid set rejects the whole send. All team members can read the full history, including direct messages.
-
-```json
-{"action":"history","after":0,"limit":20}
-```
-
-Use the last returned `seq` as the next `after` cursor. `search` adds a case-sensitive literal `query`; results remain cursor-paged. Reads never consume messages. Task and message result pages are limited to 100 items.
-
-New messages queue a compact Pi follow-up: an idle member wakes, while a busy member finishes its current work first. Notifications batch for 50 ms and reference history rather than copying every message into context. Notification acknowledgement means queued, not read or acted on. Messages survive crashes; exactly-once delivery or model execution does not. Avoid acknowledgement-only replies.
-
-## Limits are ceilings, not staffing targets
-
-Default: at most **10 live descendants**, counting starting, busy, idle, and stopping members. Root does not consume a slot. Default depth is **2**: root, child, grandchild. Use the fewest useful agents.
-
-Root policy precedence:
-
-1. Built-in defaults
-2. `~/.acstack/ac-teams/config.json`
-3. `.pi/ac-teams.json`, only with `--teams-project-config`
-4. Explicit `--teams-limit` and `--teams-depth` flags
-
-Config files accept only `limit` and `depth`, for example `{"limit":4,"depth":2}`. Limits must be 1–100; depth must be 0–10. A value above 10 requires an explicit root startup flag or interactive confirmation of a root `limits` tool request. Configuration alone cannot raise it. Lowering limits does not kill existing members; it blocks further launches until capacity fits.
+| `team_agent` | Launch, inspect, stop, and resume members; manage limits and worktrees |
+| `team_task` | Track shared work, ownership, and dependencies |
+| `team_message` | Send notifications and read or search team history |
 
-```sh
-pi -e /absolute/path/to/ac-teams/src/index.ts --teams-limit 4 --teams-depth 1
-```
-
-## Stop, resume, and keep work safe
-
-`stop` stops the member's descendants deepest-first, clears queued work, aborts the turn, and closes the owned RPC pipe. Hung processes escalate to SIGTERM and then SIGKILL, with a warning. Escalation requires a matching captured process-group identity; uncertain ownership is refused. This is snapshot-based cleanup, not OS containment: detached or uncaptured descendants and identity-check races remain outside the guarantee.
-
-`resume` needs a stopped descendant ID and a new brief. It starts a new process against the same native Pi session file; it does not reconstruct a transcript, reconnect to old stdio, or replay the previous assignment automatically. Resume is refused if the old process is live or its identity is uncertain.
-
-Root session switching, forking, and tree traversal are blocked while members are live. A member cannot switch away from its team binding. Stop members explicitly before replacing the root session.
-
-**Exit confirmation requires Pi's `session_before_exit` hook.** The prerequisite is implemented in the separate local Pi checkout described in [the implementation history](docs/implementation-plan.md#exit-confirmation-supported-hook-versus-package-interception), not in installed Pi 1.4.0. With that hook, native exit asks before stopping live members; cancellation leaves them running. Without it, shutdown performs cleanup but cannot ask first. Signals bypass confirmation.
-
-If the root crashes, closing its owned pipes and losing the coordinator connection makes ordinary RPC children shut down. This passed SIGTERM and SIGKILL probes with native child and grandchild processes. It is best effort, not a guarantee against a hung event loop, machine failure, or detached shell processes. Recovery refuses duplicate work when a previous member is still live or uncertain.
-
-### Optional worktrees
-
-Set `worktree: true` on launch. `base` defaults to the repository's HEAD; `target` records the branch/ref against which later cleanup must prove integration. Worktrees live under a sibling `.ac-teams-worktrees` directory. No fetch, merge, stash, or checkout of the original directory occurs.
-
-Stopping never deletes a worktree. `cleanup` is explicit and requires a stopped member, a clean tree including ignored/untracked files, and HEAD ancestry proven against the recorded target's current commit. Missing targets, dirty work, and uncertain/squashed integration retain the tree. Cleanup never forces removal and retains the branch. Cleanups and resumes exclude each other.
-
-Worktree creation copies committed content, not uncommitted project configuration. Approve the new cwd through native Pi trust before retrying a launch that could not load its project resources. A failed launch retains its created worktree and member record.
-
-## Local records and security boundaries
-
-Each root session uses `~/.acstack/ac-teams/teams/<session-id>/`:
-
-- `state.json` contains membership, policy, tasks, messages, claims, and notification cursors
-- `sessions/` contains native Pi-managed member transcripts
-- `owner.lock` and `coordinator.sock` coordinate the running root
-
-State schema 2 separates ownership from progress. On reopening an older team, the coordinator atomically migrates schema 1: `pending` becomes `todo`, `claimed` becomes `in_progress`, and `completed` becomes `done`. IDs, owners, dependencies, and revisions are preserved. Invalid snapshots are rejected without replacement. Older ac-teams code cannot reopen the migrated schema; stop old sessions before updating.
-
-Only the root writes state. Mutations validate a copy, flush a temporary snapshot, atomically rename it, and flush the directory before returning success. An exclusive process-identity lock prevents concurrent owners. Private team directories use 0700; state files and the authenticated Unix socket use 0600. Uncertain locks fail closed.
-
-This is a small-team store: each mutation rewrites the snapshot, and search scans local history. There is no database, compaction, retention policy, automatic deletion, or deduplication of repeated mutation requests. Inspect state before retrying an ambiguous failed request. Records and transcripts can contain sensitive project data. Permissions protect against other users, not agents running as the same OS user.
+`/teams` or `/teams panel` opens Tasks, Teammates, and Activity. `/teams teammate <name-or-id>` opens a teammate directly; subcommands and teammate names autocomplete. Use the task graph or list, send feedback, and open a member's full live Pi session.
 
-`npm audit` currently reports Pi 1.4.0's pinned `undici` dependency (including a high-severity advisory). ac-teams adds no HTTP client and cannot repair an existing host installation. The suggested npm fix downgrades Pi incompatibly; it has not been applied. Review the host dependency before deployment.
+The task summary sits above the input. The agent selector below status shows descriptive names, models, and context usage. `/teams config` toggles these displays independently.
 
-## Development and verification
+From an empty editor, press Down to select the team footer, then Enter to open a member. Ctrl+Shift+Left returns to Main without stopping the member. `/teams stop` stops every descendant.
 
-```sh
-npm ci
-npm run check
-npm test
-npm pack --dry-run
-```
-
-The deterministic suite covers task reservations, progress, dependency readiness, release/reopen rules, durable migration, real subprocesses, sockets, notification batching, shutdown escalation, worktree safety, and lifecycle races. It makes no model calls.
-
-Additional local checks on 2026-10-24:
-
-- Native Pi busy follow-up, idle wake with the same PID, and resume with the same session ID/path and a new PID
-- Normal project-extension loading and a 10-call model smoke using the existing default model; Pi reported an estimated $0.0861
-- Actual ac-teams exit confirmation, cancel/retry, and child cleanup in a real terminal using patched Pi and a model-free RPC child fixture
-- Native child/grandchild cleanup after coordinator SIGTERM and SIGKILL, without model calls
-- Independent review and executable checks of stop/start, cleanup/resume, and shutdown/socket races
-
-Not verified on macOS, Windows, or network filesystems. The package is Linux-only because safe process identity uses `/proc`. No dashboard, workflow DSL, daemon, or automatic merging is included.
-
-## Publish to npm
-
-The `publish-npm.yml` GitHub workflow follows acstack's staged-release approach: it runs typecheck, tests, and package checks, then submits the package for approval. It does not publish the release directly.
-
-Set the repository secret once using an interactive prompt, not a token pasted into a command or chat:
+Defaults allow up to **10 live members** and **two levels of delegation**. Use the fewest useful agents.
 
-```sh
-gh secret set NPM_TOKEN --repo ac8318740/ac-teams
-```
-
-Reuse acstack's token only if its permissions allow creating and staging `ac-teams`. GitHub cannot reveal the existing secret value. Otherwise, create a granular npm token with stage-publish access. npm requires 2FA on the publishing account.
+## Know the boundaries
 
-After the workflow reaches the repository's default branch, run it from GitHub Actions or dispatch it:
+- Members share your filesystem access. All members can read all team messages, including direct messages.
+- Limits cover only `team_agent`, not other delegation tools. Use separate worktrees for concurrent writers.
+- Stop retains tasks, sessions, and worktrees. Worktree deletion is explicit and requires clean, integrated work.
+- Exit confirmation needs Pi's `session_before_exit` hook, which installed Pi 1.4.0 lacks. Without it, shutdown cleans up but cannot ask first. Signals always bypass confirmation.
 
-```sh
-gh workflow run publish-npm.yml --repo ac8318740/ac-teams
-```
+See the [operations guide](docs/operations.md) for recovery guarantees, storage, and the Pi dependency security advisory.
 
-Pushing a `v<version>` tag also triggers it; the tag must match `package.json`. An already published version is a no-op. If the version is already staged, approve the existing submission rather than staging it again.
+## Guides
 
-Review and approve `ac-teams@0.0.1` in npm's **Staged Packages** tab using 2FA. The first staging of a new name creates a public `0.0.0-stage` placeholder; the requested version and its contents become public only after approval. See [npm's staged publishing documentation](https://docs.npmjs.com/staged-publishing/).
-
-After approval, install the published version through Pi:
-
-```sh
-pi install npm:ac-teams@0.0.1
-```
+- [Usage](docs/usage.md): tool actions, task rules, messages, and companion tools
+- [Operations](docs/operations.md): limits, stop/resume, worktrees, and security
+- [Development](docs/development.md): source setup, verification, and publishing
+- [Implementation history](docs/implementation-plan.md): design decisions and prior art
 
 ## License
 
-[MIT](LICENSE). No third-party extension implementation was copied. Pi and TypeBox remain peer dependencies; exit-guard prior art and license findings are recorded in the implementation history.
+[MIT](LICENSE).

package/docs/development.md

@@ -0,0 +1,89 @@
+# Develop and publish ac-teams
+
+Source setup is for contributors. For normal use, [install the npm package through Pi](../README.md#install).
+
+## Run from source
+
+Requirements: Linux, Node 22.19 or newer, and an authenticated `pi` executable on `PATH`. Interactive teams also need `tmux`. From a clone of this repository:
+
+```sh
+npm ci
+pi -e "$PWD/src/index.ts"
+```
+
+To work in another project, launch Pi there with the absolute path to `ac-teams/src/index.ts`. Load the extension once, either explicitly or through Pi package settings, not both. Save native Pi trust for each member's cwd as described in [operations](operations.md#save-project-trust-before-launching).
+
+## Run local checks
+
+```sh
+npm run check
+npm test
+npm pack --dry-run
+```
+
+The deterministic suite makes no model calls. It covers:
+
+- Task reservations, progress, dependencies, release/reopen rules, and durable migration
+- Subprocesses, sockets, notification batching, shutdown escalation, worktree safety, and lifecycle races
+- Graph navigation, task numbers and labels, UUID references, task summaries, display toggles, state colors, and narrow layouts
+- Draft retention, quiet resume, shutdown-time feedback, and maximum-length messages
+- Name validation and recovery, autocomplete, name/ID resolution, and model/context reports
+
+### Recorded native Pi verification
+
+Additional local checks on 2026-10-24, using Pi 1.4.0 unless noted:
+
+- Native Pi busy follow-up, idle wake with the same PID, and resume with the same session ID/path and a new PID
+- Normal project-extension loading and a 10-call model smoke using the existing default model; Pi reported an estimated $0.0861
+- Actual ac-teams exit confirmation, cancel/retry, and child cleanup in a real terminal using patched Pi and a model-free RPC child fixture
+- Native child/grandchild cleanup after coordinator SIGTERM and SIGKILL, without model calls
+- Independent review and executable checks of stop/start, cleanup/resume, and shutdown/socket races
+
+Terminal UI checks used real native Pi processes in an isolated full-size Herdr tab with a local deterministic model endpoint, not a paid provider:
+
+- Private tmux transport, native child/grandchild delegation, member-to-descendant switching, and single-key return to Main
+- Same PID across switching, unsent member draft retention, and a new PID with the same session ID/path after quiet resume
+- Real UUID task graphs, green/cyan/red state borders, and creator-directed feedback without direct task mutation
+- Root exit stopping native descendants and retaining task, message, and session records
+- Task summary above the input, agent selector below status, native subcommand/name autocomplete, and same-PID/session opening by name or ID
+- Pi-reported model display names and changing context estimates in the live selector
+
+Not verified on macOS, Windows, or network filesystems. The package is Linux-only because safe process identity uses `/proc`. No web dashboard, workflow DSL, daemon, or automatic merging is included.
+
+## Stage releases for npm approval
+
+[The GitHub workflow](https://github.com/ac8318740/ac-teams/actions/workflows/publish-npm.yml) automatically stages a release when `package.json` reaches `main`. Changes to the workflow itself also trigger staging, so installing this automation stages the current version. It runs typecheck, tests, and package checks first.
+
+This follows ACStack's automatic staged-release approach. Final publication still requires approval on npm with 2FA; merging alone does not make the version public.
+
+Only `main` can stage releases. The workflow rejects other branches and tags before checkout. The GitHub environment `npm` also restricts deployments to the branch `main`, with no allowed tags.
+
+Store `NPM_TOKEN` only in that environment, not as a repository secret. This keeps older workflows on other branches from accessing it. Set it using an interactive prompt, not a token pasted into a command or chat:
+
+```sh
+gh secret set NPM_TOKEN --repo ac8318740/ac-teams --env npm
+```
+
+Reuse acstack's token only if its permissions allow creating and staging `ac-teams`. GitHub cannot reveal the existing secret value. Otherwise, create a granular npm token with stage-publish access. npm requires 2FA on the publishing account.
+
+For a retry without another commit, run the workflow manually from `main` in GitHub Actions or dispatch it:
+
+```sh
+gh workflow run publish-npm.yml --repo ac8318740/ac-teams --ref main
+```
+
+Pushes to other branches, tags, and pull requests do not trigger staging. An already published version is a no-op. Like ACStack, the workflow treats npm's `Version uniqueness check failed unexpectedly` response as an apparent existing staged submission and directs you to approve it. Other staging errors fail the run.
+
+Review and approve the staged version in npm's **Staged Packages** tab using 2FA. The first staging of a new name creates a public `0.0.0-stage` placeholder. The requested version and its contents become public only after approval. See [npm's staged publishing documentation](https://docs.npmjs.com/staged-publishing/).
+
+After approval, install through Pi, replacing the version below for later releases:
+
+```sh
+pi install npm:ac-teams@0.0.2
+```
+
+## License and prior art
+
+[MIT](../LICENSE). No third-party extension implementation was copied. Pi and TypeBox remain peer dependencies; `grok-mermaid` is a runtime dependency for terminal diagrams. The [implementation history](implementation-plan.md) records design decisions, exit-guard prior art, and license findings.
+
+[Back to README](../README.md)

package/docs/implementation-plan.md

@@ -1,6 +1,6 @@
 # ac-teams implementation history
 
-**Status:** the local v0.0.1 implementation is built and verified on Linux as of 2026-10-24. [README.md](../README.md) describes the current contract, commands, verification, and limitations. No release, global installation, or change to installed Pi has been made.
+**Status:** v0.0.1 is built and verified on Linux as of 2026-10-24. The [README](../README.md) introduces the package and links to its current guides. This file records implementation decisions and the original proposal.
 
 The user approved implementation with these refinements:
 
@@ -11,11 +11,11 @@ The user approved implementation with these refinements:
 
 The smallest complete implementation uses one atomically replaced `state.json` for messages and tasks, rather than a separate message journal. Mutations are not request-deduplicated; ambiguous retries require inspection. Notification acknowledgement records queuing, not reading, and does not guarantee at-least-once model execution across crashes. Worktree cleanup is explicit, never automatic.
 
-Deterministic subprocess/socket/storage/Git tests, native Pi busy/idle/resume checks, an actual terminal confirmation test, model-free native SIGTERM/SIGKILL probes, package checks, and independent review passed. The paid smoke used 10 calls and Pi reported an estimated $0.0861. A host dependency advisory remains documented in the README.
+Deterministic subprocess/socket/storage/Git tests, native Pi busy/idle/resume checks, an actual terminal confirmation test, model-free native SIGTERM/SIGKILL probes, package checks, and independent review passed. The paid smoke used 10 calls and Pi reported an estimated $0.0861. The [operations guide](operations.md#pi-dependency-advisory) records the host dependency advisory.
 
 ## Original proposal
 
-The sections below preserve the design investigation and its proposed acceptance checks. Where they differ from the implementation, the current README and the refinements above take precedence. Their original future-tense recommendations are not additional pending work.
+The sections below preserve the design investigation and its proposed acceptance checks. Where they differ from the implementation, the [usage guide](usage.md), [operations guide](operations.md), and the refinements above take precedence. Their original future-tense recommendations are not additional pending work.
 
 ## Architecture: the root owns transport, not everyone's work
 
@@ -194,4 +194,4 @@ The evidence below describes the installed package; the separate local Pi patch
 
 A temporary, isolated real-Pi probe disabled all optional extensions/skills/templates/themes and sent no model prompt. It verified successful `get_state`, `get_commands`, `clear_queue`, and `abort` responses; continued availability between commands; native session ID/path reporting; and exit code 0 after stdin EOF. The first probe timed out because its Python text-buffered selector reader missed buffered lines; switching the probe to byte reads resolved that harness error.
 
-At the end of the initial investigation, extension coexistence/readiness, paid model turns, busy message delivery, concurrent claims, parent-death cleanup, native resume/rejoin, and worktree safety were still unverified. Those checks were subsequently exercised during implementation; see the current README for evidence and limits. Publishing, marketplace integration, and ACStack changes remain outside this local delivery.
+At the end of the initial investigation, extension coexistence/readiness, paid model turns, busy message delivery, concurrent claims, parent-death cleanup, native resume/rejoin, and worktree safety were still unverified. Those checks were subsequently exercised during implementation; see [recorded verification](development.md#recorded-native-pi-verification) and [operational limits](operations.md). Publishing, marketplace integration, and ACStack changes were outside the initial local delivery. Current [publishing instructions](development.md#stage-releases-for-npm-approval) are separate from that history.

package/docs/operations.md

@@ -0,0 +1,101 @@
+# Operate ac-teams
+
+ac-teams runs on Linux with Node 22.19 or newer and an authenticated `pi` executable on `PATH`. Interactive roots also require `tmux`: each team owns a private server and native member terminals. Headless roots retain RPC members. Both share your OS user's access, not a sandbox.
+
+## Save project trust before launching
+
+Use Pi's `/trust` command to approve each member's cwd before launching there. Children cannot complete the coordinator readiness handshake while waiting for Pi's initial trust prompt. ac-teams rejects readiness if project resources were skipped; it never auto-approves a project.
+
+A one-run approval in the root is not a saved approval for children or new worktrees. Worktree creation copies committed content, not uncommitted project configuration. Approve the new cwd through native Pi trust before retrying a launch that could not load its project resources. A failed launch retains its created worktree and member record.
+
+## Limits are ceilings, not staffing targets
+
+Default: at most **10 live descendants**, counting starting, busy, idle, and stopping members. Root does not consume a slot. Default depth is **2**: root, child, grandchild. Use the fewest useful agents.
+
+Root policy precedence, from lowest to highest:
+
+1. Built-in defaults
+2. `~/.acstack/ac-teams/config.json`
+3. `.pi/ac-teams.json`, only with `--teams-project-config`
+4. Explicit `--teams-limit` and `--teams-depth` flags
+
+Config files accept only `limit` and `depth`, for example `{"limit":4,"depth":2}`. Limits must be 1–100; depth must be 0–10.
+
+A limit above 10 requires an explicit root startup flag or interactive confirmation of a root `limits` tool request. Configuration alone cannot raise it. Lowering limits does not kill existing members; it blocks further launches until capacity fits.
+
+For an npm-installed extension, set startup limits with:
+
+```sh
+pi --teams-limit 4 --teams-depth 1
+```
+
+Other delegation tools remain outside these limits. See [companion tools](usage.md#companion-tools-add-guidance-or-terminal-management).
+
+## Display preferences are global
+
+`/teams config` saves task-summary and agent-selector visibility to `~/.acstack/ac-teams/display.json`:
+
+```json
+{"tasks":true,"agents":true}
+```
+
+Only these two boolean keys are accepted; omitted keys default to `true`. Saves atomically replace a private 0600 file. A malformed or unreadable preferences file produces a warning and is not overwritten; correct or remove it before saving settings again. These preferences are separate from resource policy in `config.json` and have no project override.
+
+## Stop and resume members
+
+`stop` stops the member's descendants deepest-first, clears queued work, and aborts the turn. It closes the owned RPC pipe or terminates the owned native terminal. Hung processes escalate to SIGTERM and then SIGKILL, with a warning. Escalation requires a matching captured process-group identity; the coordinator refuses uncertain ownership.
+
+This is snapshot-based cleanup, not OS containment. Detached or uncaptured descendants and identity-check races remain outside the guarantee.
+
+`resume` needs a stopped descendant ID and a new brief. It keeps the member's descriptive name; renaming during resume is rejected. It starts a new process against the same native Pi session file. It does not reconstruct a transcript, reconnect to old stdio, or replay the previous assignment automatically. The coordinator refuses tool-driven resume if the old process is live or its identity is uncertain.
+
+The interactive panel can instead quietly resume a saved member session without inventing a new brief. Feedback then arrives through the durable team mailbox.
+
+Root session switching, forking, and tree traversal are blocked while members are live. A member cannot switch away from its team binding. Stop members explicitly before replacing the root session.
+
+### Exit confirmation needs a Pi hook
+
+Exit confirmation requires Pi's `session_before_exit` hook. The prerequisite is implemented in the separate local Pi checkout described in [the implementation history](implementation-plan.md#exit-confirmation-supported-hook-versus-package-interception), not in installed Pi 1.4.0.
+
+With that hook, native exit asks before stopping live members; cancellation leaves them running. Without it, shutdown performs cleanup but cannot ask first. Signals bypass confirmation.
+
+### Crash recovery is best effort
+
+If the root crashes, closing its owned pipes and losing the coordinator connection makes ordinary RPC children shut down. Native members also monitor the authenticated coordinator connection and exit after it is lost. This passed SIGTERM and SIGKILL probes with native child and grandchild processes.
+
+It is not a guarantee against a hung event loop, machine failure, or detached shell processes. Recovery refuses duplicate work when a previous member is still live or uncertain. Tasks keep their ownership and progress after stop or crash; there is no automatic reassignment.
+
+## Worktree cleanup is explicit
+
+Set `worktree: true` on launch. `base` defaults to the repository's HEAD; `target` records the branch/ref against which later cleanup must prove integration. Worktrees live under a sibling `.ac-teams-worktrees` directory. No fetch, merge, stash, or checkout of the original directory occurs.
+
+Stopping never deletes a worktree. `cleanup` requires a stopped member, a clean tree including ignored/untracked files, and HEAD ancestry proven against the recorded target's current commit.
+
+Missing targets, dirty work, and uncertain/squashed integration retain the tree. Cleanup never forces removal and retains the branch. Cleanups and resumes exclude each other.
+
+## Local records contain sensitive project data
+
+Each root session uses `~/.acstack/ac-teams/teams/<session-id>/`:
+
+- `state.json` contains membership, policy, tasks, messages, claims, and notification cursors
+- `sessions/` contains native Pi-managed member transcripts
+- `owner.lock` and `coordinator.sock` coordinate the running root
+- Interactive teams also own `t.sock`, the private tmux socket, and per-member terminal environment files; shutdown removes those files
+
+New members also store their descriptive names and optional model/context reports. When an existing team opens, unnamed members receive stable, collision-free names such as `teammate-1`; their IDs and sessions do not change.
+
+State schema 3 adds stable task numbers and short labels. Opening a schema 1 or 2 team assigns numbers in stored task order and initial labels from up to three title words. Full titles, descriptions, UUIDs, owners, creators, dependencies, and revisions remain unchanged.
+
+Schema 1 also migrates progress: `pending` becomes `todo`, `claimed` becomes `in_progress`, and `completed` becomes `done`. Migration writes atomically and rejects invalid snapshots without replacement. Older ac-teams code cannot reopen schema 3; stop old sessions before updating.
+
+Only the root writes state. Mutations validate a copy, flush a temporary snapshot, atomically rename it, and flush the directory before returning success. An exclusive process-identity lock prevents concurrent owners. Private team directories use 0700; state files and the authenticated Unix socket use 0600. Uncertain locks fail closed.
+
+This is a small-team store: each mutation rewrites the snapshot, and search scans local history. There is no database, compaction, retention policy, automatic deletion, or deduplication of repeated mutation requests. Inspect state before retrying an ambiguous failed request.
+
+Records and transcripts can contain sensitive project data. Permissions protect against other users, not agents running as the same OS user. All members can read all team messages, including direct messages.
+
+### Pi dependency advisory
+
+The local verification recorded on 2026-10-24 found that `npm audit` reports Pi 1.4.0's pinned `undici` dependency, including a high-severity advisory. ac-teams adds no HTTP client and cannot repair an existing host installation. The suggested npm fix downgrades Pi incompatibly; it has not been applied. Review the host dependency before deployment.
+
+[Back to README](../README.md)

package/docs/usage.md

@@ -0,0 +1,128 @@
+# Use ac-teams
+
+ac-teams provides three tools without prescribing a workflow. Your Pi session is the root; its child agents are members. The root opens coordination state on the first team request.
+
+| Tool | Actions | Main rule |
+| --- | --- | --- |
+| `team_agent` | `launch`, `list`, `status`, `stop`, `resume`, `limits`, `cleanup` | A parent controls its descendants, not peers or ancestors |
+| `team_task` | `create`, `list`, `read`, `edit`, `claim`, `start`, `release`, `complete`, `reopen` | Claim reserves work; dependencies gate starting, not ownership |
+| `team_message` | `send`, `history`, `search` | Recipients select who receives notification, not who can read |
+
+In interactive Pi, `/teams` or `/teams panel` opens the team panel. `/teams teammate <name-or-id>` opens a live teammate directly; autocomplete suggests subcommands and teammate names. You can also enter an exact teammate ID. The older `/teams open <id>` form remains supported. Headless roots retain the status listing. `/teams stop` stops every descendant. See [operations](operations.md) for limits, recovery, and worktree cleanup.
+
+## Navigate without stopping members
+
+The agent selector sits below Pi's status lines. It shows each member's name, state, model display name, and context usage. It keeps Main pinned and shows at most five rows, including an overflow indicator when needed. A finished assignment leaves its member idle and selectable.
+
+Context shows Pi's reported token estimate, window size, and percentage, for example `Claude Opus 4.6 · 48k / 200k (24%)`. Reports refresh about once a second when they change. Unknown usage stays marked unknown, not zero. Stopped members retain their last report. These are context estimates, not billing totals.
+
+- Press Down from an empty editor to focus Main in the footer. Up/Down select members; Enter opens the selected live session; Esc returns to editing.
+- Ctrl+Shift+Left returns from a member to Main. Switching preserves the member's process, session, and draft. Returning does not stop it.
+- `/teams` opens three tabs. Tab moves between Tasks, Teammates, and Activity; Esc closes the panel.
+    - **Tasks:** Arrow keys select nodes in the dependency graph. G toggles graph/list, and Enter shows full details. Green means Done, red Blocked, cyan Working, and neutral Ready; written labels remain visible. Large or unsupported graphs fall back to the list.
+    - **Teammates:** Enter opens a live member, or quietly resumes a stopped member's saved session before opening it. Root can open any member; member views can open their descendants.
+    - **Activity:** Shows the latest 100 persistent team messages rather than every tool update. Use `team_message history` to read older messages.
+- N composes a task request for Main. C on a task sends feedback to its creator. Enter sends; Shift+Enter adds a newline; Esc cancels without losing the draft. These messages do not directly edit the task graph. Feedback resumes a stopped creator when possible; otherwise, the receipt explicitly reports delivery to Main instead.
+
+A task request is a proposal, not an instruction to create a task. Main receives guidance to review the agreed scope and existing work first: reuse a task that already covers the request, extend one when coherent and permitted, or create distinct in-scope work. It should clarify unresolved scope conflicts and explain its decision with task references.
+
+The send receipt confirms delivery, not acceptance or task creation. This is agent guidance, not an automatic semantic duplicate detector.
+
+Team tool results and messages are compact by default. Ctrl+O expands them into labeled fields. UI state colors do not replace the underlying progress, ownership, or dependency fields.
+
+## Show tasks and configure the displays
+
+The task summary sits above the input editor; the agent selector stays below the status lines. It shows completed/total counts and up to five numbered task labels, ordered by:
+
+1. In-progress work
+2. Ready prerequisites blocking other tasks, with the most dependents first
+3. Blocked work, marked `⊘` with prerequisite numbers such as `blocked by #3`
+4. Recently completed work, newest first
+
+Ordinary ready tasks remain in `/teams`; the summary is not the full task list. Completion time determines recent order for newly completed tasks. Older completed tasks without timestamps fall back to task-number order.
+
+Use `/teams config` to toggle **Task summary** and **Agent selector** independently. Up/Down select a setting; Space or Enter toggles it; Esc closes. Changes save immediately for the current and future sessions. Other running sessions are not updated automatically. Both displays default to On.
+
+Hiding a display does not stop agents, change tasks, or disable `/teams`. With the agent selector hidden, ordinary editor Down behavior returns. These global display preferences do not change the team's resource ceilings.
+
+## Give members bounded assignments
+
+Example `team_agent` arguments:
+
+```json
+{"action":"launch","name":"parser-review","brief":"Review src/parser.ts. Read only; do not delegate or edit. Send findings to root through team_message."}
+```
+
+Every launch needs a unique descriptive `name`: one or two lowercase words, hyphenated if two, at most 40 characters. For example, `parser-review` or `research`. `main`, `root`, and names matching an existing member's ID are reserved. Names remain stable across stop/resume; IDs remain the API references.
+
+`cwd` defaults to the requesting member's directory. `model` (`provider/model`) and `thinking` default to that member's current selection. An explicit override wins. Native Pi selects the model; provider/account rejections remain visible in member status and notify the parent. There is no automatic model retry.
+
+Launch returns the name, a stable member ID, PID, cwd, and native session ID/path. Interactive roots launch native Pi terminals in a team-private tmux server; headless roots keep the RPC transport. Finishing a turn makes the member idle only after Pi reports `agent_settled`. It does not stop the process.
+
+Children load ac-teams explicitly and otherwise keep normal Pi extensions, skills, authentication, and cwd instructions. They receive their brief, not the parent's conversation. Load ac-teams only once in the root, either through Pi package settings or an explicit extension path.
+
+Children can delegate through the same coordinator, subject to depth and capacity. Delegation still needs user authorization. Keep briefs bounded, agree on file ownership, and use separate worktrees for concurrent writers.
+
+## Track progress separately from ownership
+
+Example `team_task` arguments:
+
+```json
+{"action":"create","label":"Parser review","title":"Review parser errors and malformed input","description":"Check malformed input and report concrete failures; no edits."}
+```
+
+Each task has a stable team-local `number` and a 1–3-word `label` (at most 60 characters). The graph and list show `#3 Parser review`; details retain the full title, description, and UUID.
+
+Numbers follow creation order. Editing, filtering, or reopening tasks never changes their numbers. A concise title can supply an omitted label; longer titles need an explicit label.
+
+Interim and final goals are ordinary tasks. Use dependencies for real prerequisites, not to make the diagram connected. Independent tasks remain disconnected until they genuinely contribute to a dependent task.
+
+Progress and ownership remain separate:
+
+- **Progress:** `status` is `todo`, `in_progress`, or `done`
+- **Ownership:** `owner` is one member ID, or absent
+- **Dependencies:** `dependencies` lists prerequisite task IDs. Returned `blockedBy` lists those not yet done; the coordinator calculates it rather than storing it as a status.
+
+Use the returned task ID with these actions:
+
+| Action | Effect |
+| --- | --- |
+| `claim` | Reserve an unowned to-do task, even if blocked. Progress stays `todo`. |
+| `start` | The owner moves `todo` to `in_progress`, only when every dependency is `done`. |
+| `complete` | The owner moves `in_progress` to `done`, with `acceptance: true`. Ownership remains. |
+| `release` | Clear ownership. In-progress work returns to `todo`; done work stays `done`. |
+| `reopen` | Explicitly move `done` to `todo`, retaining any owner. Refuse if a dependent is in progress or done. |
+
+Only the owner can start, complete, or release its work. An ancestor may explicitly release a stopped or interrupted descendant's ownership. The owner or root can reopen an owned task; any member can reopen an unowned one. Done tasks cannot be claimed until reopened.
+
+Include `dependencies` on creation or `edit`. Any member can edit unowned to-do work; only the owner can edit reserved to-do work. In-progress and done tasks cannot be edited. The coordinator rejects unknown dependencies and cycles. An optional `revision` rejects stale mutations.
+
+`acceptance: true` asserts that the agent checked the acceptance criteria; it is not an independent test runner. Stop/crash retains ownership and progress. There is no automatic reassignment.
+
+## Send messages instead of polling
+
+Example `team_message` arguments:
+
+```json
+{"action":"send","recipients":["root"],"text":"Parser review complete. No edits; two malformed-input cases need tests."}
+```
+
+Omit `recipients` to notify all other live members. Explicit sets must contain unique live member IDs; an invalid set rejects the whole send. All team members can read the full history, including direct messages.
+
+```json
+{"action":"history","after":0,"limit":20}
+```
+
+Use the last returned `seq` as the next `after` cursor. `search` adds a case-sensitive literal `query`; results remain cursor-paged. Reads never consume messages. Task and message result pages are limited to 100 items.
+
+New messages queue a compact Pi follow-up: an idle member wakes, while a busy member finishes its current work first. Notifications batch for 50 ms and reference history rather than copying every message into context. Notification acknowledgement means queued, not read or acted on.
+
+Messages survive crashes; exactly-once delivery or model execution does not. Avoid acknowledgement-only replies.
+
+## Companion tools add guidance or terminal management
+
+ac-teams works alone. ACStack adds planning, review, and shipping skills; Herdr adds terminal tabs, panes, and visible root sessions. These are companion capabilities, not automatic integrations. ac-teams does not open a Herdr pane for each member. Interactive members use a team-private tmux server and open in the current terminal when selected; headless roots use RPC members.
+
+Other delegation tools can coexist. ac-teams warns when `Agent`, `SubagentWorkflow`, or `subagent` is active, but does not disable them. Its limits cover only members launched through `team_agent`. Use Pi's resource settings to disable other launchers if you want one team authority. Shell access and same-user extensions are not sandboxed.
+
+[Back to README](../README.md)

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "ac-teams",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Small, persistent teams for Pi",
   "type": "module",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/ac8318740/ac-teams.git" },
-  "files": ["src", "README.md", "LICENSE", "docs/implementation-plan.md"],
+  "files": ["src", "README.md", "LICENSE", "docs"],
   "os": ["linux"],
   "pi": { "extensions": ["./src/index.ts"] },
   "scripts": {
@@ -22,5 +22,8 @@
     "@types/node": "^22.0.0",
     "typebox": "^1.0.0",
     "typescript": "^5.9.0"
+  },
+  "dependencies": {
+    "grok-mermaid": "0.2.3"
   }
 }