ac-teams 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Coote
+
+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

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# ac-teams
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+## Install
+
+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
+pi install npm:ac-teams@0.0.2
+```
+
+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.
+
+## Use it
+
+Your Pi session is the root; its child agents are members. Ask Pi to delegate a bounded assignment, for example:
+
+> Launch a member to review src/parser.ts without editing, and have it send findings back to me.
+
+| Tool | Purpose |
+| --- | --- |
+| `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 |
+
+`/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.
+
+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.
+
+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.
+
+Defaults allow up to **10 live members** and **two levels of delegation**. Use the fewest useful agents.
+
+## Know the boundaries
+
+- 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.
+
+See the [operations guide](docs/operations.md) for recovery guarantees, storage, and the Pi dependency security advisory.
+
+## Guides
+
+- [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).

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

@@ -0,0 +1,197 @@
+# ac-teams implementation history
+
+**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:
+
+- Warn about competing delegation tools instead of refusing coexistence. Keep normal child resources. Limits cover only ac-teams launches, not other launchers or same-user shell access.
+- Require explicit root opt-in before reading project policy. Configuration alone cannot authorize a limit above 10.
+- Stop, rather than detach, live members when exit is confirmed. Confirmation uses the separately implemented native Pi hook, not input interception.
+- Separate task progress (`todo`, `in_progress`, `done`), ownership, and dependency readiness. Checkout reserves even blocked work; `start` requires completed dependencies. Release clears ownership without reopening done work; reopening is explicit and protects active/done dependents. This supersedes the initial claim-as-progress design. Schema 1 snapshots migrate atomically to schema 2, preserving IDs, owners, dependencies, and revisions.
+
+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. 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 [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
+
+```text
+root Pi extension
+    |
+    +-- coordinator: durable state, local socket, event delivery
+    |       |
+    |       +-- owns RPC pipes --> child Pi session
+    |       +-- owns RPC pipes --> grandchild Pi session
+    |
+    +-- native root Pi session/transcript
+
+child extension -- authenticated local socket --> coordinator
+                     requests launch, tasks, messages, or stop
+```
+
+A child can delegate, but the coordinator launches every process. The recorded parent tree controls depth and stop permissions. Owning all RPC pipes at the root avoids a persistent service and makes root process death close every child's input pipe. Finishing an assignment changes an agent to idle; it does not close that pipe or exit the session.
+
+Use Node platform APIs, Pi's peer APIs, and its schema dependency. No database, process supervisor service, or orchestration dependency is needed for this size. Use a small JSONL RPC transport rather than Pi's exported `RpcClient`: v1 needs explicit pipe ownership, EOF shutdown, process identity, and bounded shutdown escalation. The installed client's `stop()` sends SIGTERM and then SIGKILL after one second; its public interface does not provide the required graceful EOF control.
+
+### Proposed source boundaries
+
+| File | Responsibility |
+| --- | --- |
+| `src/index.ts` | Register tools, guidance, flags, and Pi lifecycle handlers |
+| `src/coordinator.ts` | Team membership, authorization, single-writer mutations, socket requests, notifications |
+| `src/rpc-agent.ts` | Spawn Pi, correlate RPC responses, track settlement, stop processes |
+| `src/store.ts` | Private local storage, durable writes, message search and cursors |
+| `src/worktrees.ts` | Create optional worktrees and verify safe removal |
+
+Keep task rules in the coordinator initially; do not create a generic scheduler. Add the Pi package manifest, TypeScript configuration, and tests only after approval.
+
+## The three tools compose without prescribing a workflow
+
+Proposed names and actions:
+
+| Tool | Actions | Rules |
+| --- | --- | --- |
+| `team_agent` | Launch, list/status, stop, explicit resume, root limit update | Brief, cwd, optional worktree, model, and thinking level; return member and native session identifiers |
+| `team_message` | Send, history, search | Notify all teammates or a nonempty explicit recipient set; all members can read all messages |
+| `team_task` | Create, list/read, edit to-do work, claim, start, release, complete, reopen | Separate progress, ownership, and dependencies; blocked checkout is allowed, starting is gated |
+
+Children receive their launch brief and normal project instructions, not the parent's conversation. Startup guidance explains how to pull shared messages and tasks. It asks agents to use the fewest useful teammates, consider thinking level, state edit ownership, and notify their parent before an in-scope split. Scope expansion or changed shared commitments requires approval. There are no fixed manager roles or file locks.
+
+Stop authorization follows ancestry: a parent can stop its descendants, not a peer or ancestor. The user can override. Task ownership is separate: agents complete or release their own claims; a parent or the user can explicitly release an interrupted descendant's claim. Stop never silently releases or reruns work.
+
+### Launch controls and precedence
+
+- Defaults: depth 2, at most 10 live descendants including idle members. Root is depth 0 and does not consume a descendant slot.
+- Root settings resolve in order: built-in defaults, user ac-teams configuration, project ac-teams configuration, explicit root launch flags. Descendants receive the resolved team policy from the coordinator, not authority to rewrite it.
+- A ceiling above 10 requires explicit user authorization: a root startup flag, or a root tool request confirmed through the host UI. Configuration alone cannot silently raise it. In noninteractive mode, require the explicit startup override. Descendants cannot raise either ceiling.
+- Lowering a live ceiling does not stop existing agents. Reject new launches until the proposed membership fits. Lowering depth prevents further over-depth launches; it does not kill existing members.
+- Reserve a slot atomically before spawn; count starting and stopping processes until confirmed exited. Roll back failed startup reservations. Validate the requesting member and ancestry server-side, not from a caller-supplied depth.
+- Read the spawning member's current model and thinking level for each launch. Pass provider/model and thinking explicitly to Pi; an explicit launch override wins. Validate support and fail clearly rather than silently routing to another model.
+
+Configuration is convenience, not a security boundary. Members share OS-user access; shell access can bypass coordination policies.
+
+### Normal Pi resources, with explicit readiness checks
+
+Launch `pi --mode rpc` in the requested cwd, using the installed executable, a dedicated native session directory, and an explicit absolute `-e` path to ac-teams. Preserve normal package, extension, skill, model, authentication, and project-instruction loading. Do not use `--no-extensions` as the production shortcut.
+
+Before sending an assignment, require a child readiness handshake proving that ac-teams registered, joined the expected Team, and sees the coordinator's policy. The handshake also reports competing delegation tools/resources. Reject startup on conflicts, missing resources, trust restrictions, or timeout; never continue with an ungoverned child. Normalize package paths to avoid loading ac-teams twice.
+
+Known conflicts must be checked before spawning where discoverable from settings/resources, and again at child readiness before model work. A post-load readiness check cannot undo another extension's startup side effects. Supporting arbitrary unknown launchers or claiming full coexistence is outside v1; do not modify existing installations during this project.
+
+## Durable state and atomic ownership
+
+Store coordination data at `~/.acstack/ac-teams/teams/<team-id>/` regardless of cwd. Use private directories (0700) and private files/socket (0600). The product uses this directory name without depending on ACStack. Never send tasks or messages to GitHub, ACStack maps, or another tracker.
+
+- `state.json`: member identities and ancestry, policy, task state, claims, session paths, and notification progress.
+- `messages.jsonl`: append-only shared message history with monotonic sequence numbers and stable message IDs.
+- `sessions/`: native Pi-managed session files; store references instead of copying transcripts.
+- Coordinator socket and exclusive owner lock: runtime coordination only, with per-member credentials and validated request schemas.
+
+Only the root coordinator writes. Serialize mutations in one request queue. Validate and commit each reservation in the same critical section: the task is to-do and unowned. Checkout does not start work and can reserve a blocked task. Starting requires ownership and completed dependencies. Atomic snapshot replacement uses a same-directory temporary file, flush, rename, and directory flush. Append and flush a message before notifying recipients. A successful mutation response follows durable persistence; use request IDs to make retries idempotent.
+
+Validate dependency IDs and reject cycles. Freeze dependencies while a task is in progress or done; a reserved to-do task remains editable by its owner. Return unfinished prerequisites as derived `blockedBy`, not a stored progress value. Release clears ownership, returns in-progress work to to-do, and leaves done work done. Explicit reopening cannot invalidate in-progress or done dependents. A process crash marks the member interrupted but retains task progress and ownership visibly.
+
+An exclusive team lock prevents simultaneous roots writing the same state. Check process identity, not PID alone, before deciding a lock is stale. If identity or liveness is uncertain, refuse takeover and report recovery steps rather than killing processes or breaking the lock automatically. Test these filesystem assumptions on supported local Linux filesystems; do not promise network-filesystem locking guarantees.
+
+Retain all durable records until explicit user-authorized deletion. Refuse deletion while members are live. Do not log tokens or credentials. Document that coordination messages, launch briefs, and native transcripts can contain sensitive project data.
+
+## Delivery wakes agents without model polling
+
+Append each message once. Broadcast resolves to the other current members; an explicit recipient set selects notification targets, not access permissions. History/search remains team-wide, including messages between other members. Paginate by sequence/cursor and return bounded text matches without loading the entire history into the model.
+
+The coordinator pushes sequence references to connected member extensions. Use Pi's custom message delivery to wake an idle agent and queue a follow-up while busy. Batch pending references per member to avoid a model turn for each message. Reuse the same notification ID after reconnect and keep recipient progress for deduplication. Treat delivery as at-least-once; do not promise exactly-once model execution across crashes.
+
+An assignment is complete only after `agent_settled`, not the RPC prompt acknowledgement or an intermediate `agent_end`. Idle members remain available. Default notifications do not interrupt running tools; reserve steering for an explicit urgent instruction. Transport failure leaves pending notifications visible. No automatic model retry or task reassignment follows a crash.
+
+## Stop, exit, and resume guarantees
+
+| Situation | Proposed behavior | Guarantee boundary |
+| --- | --- | --- |
+| Parent requests stop | Stop descendants in that subtree, clear queued work, abort active work, close stdin, wait, then SIGTERM/SIGKILL on a timeout | Test graceful and forced paths; report forced exits |
+| Assignment settles | Record idle; keep process and RPC connection open | Supported by Pi RPC lifecycle |
+| Root native exit | Confirm while descendants are live, then stop them and retain records | Requires the local Pi pre-exit patch; installed Pi 1.4.0 supports cleanup only |
+| Intermediate member exits unexpectedly | Coordinator observes exit and stops its descendants; preserve interrupted claims | Requires root still functioning |
+| Root crashes or receives SIGKILL | Its owned pipes close; RPC children receive EOF and begin shutdown | Best effort; child/event-loop hangs or inherited pipe handles can defeat timely cleanup |
+| Machine failure | Processes stop; reconcile records on next open | No cleanup hook or guaranteed final write |
+| Native resume | Use `pi --session <path\|id>`; rejoin records after identity checks | Resume is a new process, not reconnection to old stdio |
+
+Track only ac-teams-owned processes. Never enumerate and stop unrelated Pi sessions. Descendant process-group cleanup must be tested; arbitrary shell-spawned detached processes are not covered by a universal kill guarantee.
+
+Expose session ID and path for every member. On explicit resume, verify that the old member is not still live, reserve capacity, and start the native session with the same membership binding. Keep its interrupted claims visible for explicit continuation or release. Never reconstruct a transcript or automatically replay its last assignment. A manually resumed member without its coordinator can inspect its transcript, but cannot launch team work until team recovery is explicit.
+
+Because this coordinator lives in the root, automatic attachment to an orphan's existing RPC pipes is not supported. If post-crash processes remain live or uncertain, block replacement instead of running duplicate work. Switching/forking the interactive root session must not silently abandon the old Team: reject cancellable switches with live descendants unless they are explicitly stopped; a cloned/forked session must not inherit authority to the original Team.
+
+## Exit confirmation: supported hook versus package interception
+
+The earlier recommendation to omit confirmation in v1 was too restrictive. Confirmation can be built; the distinction is whether it uses a supported lifecycle hook or intercepts selected exit routes.
+
+Verified installed behavior: `session_shutdown` has no cancellation result, and normal interactive shutdown stops the TUI before disposing extensions. `/quit` is handled directly by the interactive mode before extension command dispatch. `app.clear` and `app.exit` shortcuts are reserved, but `ctx.ui.onTerminalInput()` can consume raw input before built-in handling. Raw input interception is not a global shutdown gate: it must preserve editor, abort, paste, modal, and configured keybinding behavior, and cannot intercept another extension calling `ctx.shutdown()`.
+
+The Pi prerequisite is implemented locally in `/home/acoote/projects/pi`, branch `feat/cancellable-exit-hook`. It is not committed, published, or installed. The implementation uses no private-method replacement or copied third-party code.
+
+Verification passed: 73 focused tests, `npm run check`, and real-terminal checks for `/quit`, Ctrl+D, double Ctrl+C, extension-requested exit, cancellation/retry, and SIGTERM during confirmation. No model prompts were sent.
+
+Hook behavior and the proposed ac-teams integration contract:
+
+- Pi emits `session_before_exit` before interactive terminal teardown. Returning `{ cancel: true }` keeps Pi open; a handler error also cancels exit and is reported.
+- `/quit`, exit keybindings, and extension-requested graceful exit use the hook. Concurrent exit requests share one pending check; cancellation leaves Pi usable. Reload and session replacement do not emit it.
+- In ac-teams, prompt only for a root with live descendants, including idle members: cancel exit, or stop descendants and exit while retaining records. Any detach/keep-running choice needs a separate lifecycle decision; it is not implied by confirmation.
+- Do not prompt on SIGTERM, SIGHUP, terminal loss, noninteractive exit, or crashes. Preserve best-effort cleanup; SIGKILL and machine failure cannot run a hook.
+- Test exit routes, cancellation, repeated requests, busy agents, no-live-member exits, cleanup, and unavailable UI. Until Pi supports the hook, a package-only exit command or input guard must explicitly document its bypasses.
+
+Prior art checked on 2026-10-24:
+
+| Project | Actual mechanism | Reuse assessment |
+| --- | --- | --- |
+| [sidstack/pi-codex-agents](https://github.com/sidstack/pi-codex-agents/blob/ae789448a8b1724075343d3341e99d04c628a1a6/src/core/host.ts#L145-L198) | Exit menu for its managed sessions; replaces the owned interactive mode's private `shutdown` and signal methods | Closest working design reference, but not a drop-in supported hook. Do not import its daemon/UI architecture or private-method patch for this tools-only package. MIT |
+| [atayarani/pi-close-guard](https://github.com/atayarani/pi-close-guard/blob/54f9be0872b9881e57b0d1ddd34ba7608769f6c8/extensions/close-guard.ts) | Uses cancellable `session_before_switch` for `/new` and optionally `/resume`; explicitly excludes `/quit` | Useful confirm/cancel pattern, not an exit solution. MIT |
+| [j1nn0/pi-extensions, pi-exit](https://github.com/j1nn0/pi-extensions/tree/78b556daf6dcd02757aec77077f278c39944c71d/packages/pi-exit) | Dedicated exit command/tool and keyboard shortcut | Example of requesting exit, not vetoing built-in shutdown. MIT |
+| [getsimpledirect/vinci-code-cli](https://github.com/getsimpledirect/vinci-code-cli/blob/33b4ae7b6788c07a9c7e5109b083ae1e313aff4e/packages/coding-agent/src/core/extensions/runner.ts) | Defines `session_before_exit` in a fork for one-shot modes, without cancellation | A matching name does not supply the interactive cancellable behavior. MIT |
+
+No third-party implementation was copied or installed. If code is adapted, retain the relevant copyright and MIT permission notice and identify the project, source commit, and adapted files in third-party notices. Acknowledgment alone does not replace the license notice. Upstream API evidence was checked at [earendil-works/pi commit d0aa218](https://github.com/earendil-works/pi/blob/d0aa218cb16c333c008f6aa3dcd670ac8b68383c/packages/coding-agent/src/core/extensions/types.ts). These are static source findings, not runtime verification of third-party exit behavior.
+
+## Worktrees preserve work by default
+
+A launch can use its supplied cwd or request a worktree. For a worktree, resolve the repository and base commit before spawning. Default to that repository's current HEAD; accept an explicit base ref. Do not fetch, checkout, reset, merge, or stash another working tree. Use an ac-teams-specific branch name containing team/member identifiers and pass Git arguments without shell interpolation.
+
+Creation records repository, resolved base, branch, path, and an optional user-authorized integration target. Branch selection must reject collisions and invalid refs.
+
+Automatic worktree removal is allowed only after the member has stopped, the tree is clean including untracked files, and its HEAD is an ancestor of the recorded integration target's current commit. Recheck immediately before removal. Missing target, uncertain status, or squash/rebase integration without ancestry proof means retain the tree and explain why. Never use force removal. V1 does not delete branches automatically and never treats stopping an agent as permission to merge.
+
+## Implementation order and acceptance checks
+
+Each step adds focused tests before it is considered complete. Before writing tests, follow the test-conventions skill and choose ordinary unit/integration tests for this standalone package, not ACStack application conventions.
+
+1. **Package and child lifecycle.** Register the extension, root coordinator, readiness protocol, and RPC transport. Check normal cwd resources, explicit package loading, no parent-conversation inheritance, model/thinking inheritance and overrides, idle reuse across two assignments, and native session IDs/paths. Fail closed on both installed competing launchers. Bound output buffers and shutdown waits; always drain stderr.
+2. **Durable tasks and limits.** Race simultaneous claims and launches; exactly one claimant wins, dependencies and cycles are checked, team/depth caps include idle agents, and startup failures release only their reservations. Test owner permissions, lower-limit behavior, request retries, disk failure, truncated message-tail recovery, duplicate roots, and crash-preserved claims.
+3. **Messages and notifications.** Test broadcast and explicit multiple recipients, team-wide search, pagination, idle wake-up, busy follow-up, settlement, notification batching/deduplication, disconnection, and no periodic model polling. Define behavior for invalid/departed recipients explicitly and reject invalid recipient sets before append.
+4. **Failure and resume.** Exercise orderly stop, queued-work cancellation, intermediate failure, root SIGTERM/SIGKILL, EOF, a child ignoring termination, and explicit native resume. Check no unrelated process is touched, no duplicate member starts, and no interrupted claim silently changes owner. Document observed best-effort limits.
+5. **Worktrees and usage guidance.** Test clean and dirty repositories, branch collisions, integrated/unmerged heads, untracked files, absent targets, and safe cleanup. Add concise examples of child delegation and parent notification. An optional short Herdr skill may reference `herdr --skill`; it must not become a runtime dependency or a second messaging implementation.
+
+Use fake RPC peers for deterministic protocol tests and real Pi processes for lifecycle/resource checks. A small paid-model smoke test is needed for two real assignments, busy/idle messaging, and tool-guidance behavior; do not confuse the no-model probe below with that verification. No frontend or dashboard verification is required for this tools-only scope.
+
+## API evidence and investigation limits
+
+The evidence below describes the installed package; the separate local Pi patch is documented above. Package root: `/home/acoote/.npm-global/lib/node_modules/@earendil-works/pi-coding-agent/`.
+
+| Evidence | Supports |
+| --- | --- |
+| `docs/extensions.md`, `dist/core/extensions/types.d.ts:1229-1300` | Tool registration, extension flags, custom/user messages, model/thinking access |
+| `docs/sdk.md`, `dist/core/resource-loader.d.ts:70-124` | SDK session/resource APIs; normal cwd loading and explicit additional resources |
+| `dist/core/resource-loader.js:409-422` | Resource merging and extension loading; an after-load override is not proof of safe conflict prevention |
+| `docs/rpc.md`, `docs/rpc-commands.md` | Persistent JSONL RPC; prompt/steer/follow-up, clear queue, abort, state, and settlement |
+| `docs/rpc-extension-ui.md` | RPC UI requests require host responses; headless approval needs explicit policy |
+| `dist/modes/rpc/rpc-mode.js:579-650` | Shutdown on stdin EOF and native runtime disposal |
+| `dist/modes/rpc/rpc-client.js:89` | Exported client's limited stop sequence |
+| `dist/modes/interactive/interactive-mode.js:3444-3488`, `dist/core/extensions/types.d.ts:637` | Shutdown ordering, non-cancellable shutdown event, emergency-exit limits |
+| `docs/cli.md`, installed `pi --help`, `docs/sessions.md` | Native `--session <path\|id>` resume and session persistence |
+| `docs/packages.md`, `docs/configuration.md`, `docs/settings.md`, `docs/security.md` | Package resources, settings/trust, and extension security limits |
+| Installed `@tintinweb/pi-subagents` 0.22.0 and `pi-subagents` 0.81.0 | Independent delegation and lifecycle behavior; both MIT, neither required or copied |
+
+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 [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)