npm - @prjct.app/pi-team - Versions diffs - 0.5.4 → 0.5.6 - Mend

@prjct.app/pi-team 0.5.4 → 0.5.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,11 @@
+## [0.5.6](https://github.com/prjct-app/pi-team/compare/v0.5.5...v0.5.6) (2026-09-10)
+## [0.5.5](https://github.com/prjct-app/pi-team/compare/v0.5.4...v0.5.5) (2026-09-10)
+### Performance Improvements
+* carry the canonical payload serialization instead of recomputing it ([#24](https://github.com/prjct-app/pi-team/issues/24)) ([340c495](https://github.com/prjct-app/pi-team/commit/340c4954358e715c6aed5e37e9f0a78f33100877))
 ## [0.5.4](https://github.com/prjct-app/pi-team/compare/v0.5.3...v0.5.4) (2026-09-10)
 ### Performance Improvements

package/CONTRIBUTING.md CHANGED Viewed

@@ -4,6 +4,7 @@
 - Deliver changes through a pull request using `.github/pull_request_template.md`.
 - Use English for code, documentation, tests, issues, and pull requests.
 - Use strict TypeScript and only APIs documented by Pi 0.85.1.
+- Use immutable values: `npm run check` fails on any `let` under `src/`. See [AGENTS.md](AGENTS.md).
 - Do not import host internals, monkey-patch prototypes, or access real credentials, sessions, or user configuration in tests.
 - Keep runtime dependencies in `dependencies`; list Pi-provided packages in `peerDependencies` with a `*` range.
 - Run `npm run check`, `npm test`, and `npm pack --dry-run` before review.
@@ -11,7 +12,7 @@
 ## Package documentation
-Follow [docs/package.md](docs/package.md) and its versioned official references. Keep README examples consistent with registered commands, distinguish tested behavior from unverified compatibility, and verify `npm run check:package` before release.
+Follow [docs/package.md](docs/package.md) and its versioned official references. Keep README examples consistent with registered commands, distinguish tested behavior from unverified compatibility, and verify `npm run check:package` before release. Design detail belongs in [docs/architecture.md](docs/architecture.md), not the README.
 ## Releases

package/README.md CHANGED Viewed

@@ -2,37 +2,29 @@
 [![pi-team — extension for PI Agent](https://raw.githubusercontent.com/prjct-app/pi-clipboard/main/docs/covers/pi-team.png)](https://pi.dev)
-Coordinate independent PI Agent sessions with local team messaging, queued tasks, and shared results.
+Coordinate independent PI Agent sessions with local team messaging, queued tasks,
+and shared results.
-`@prjct.app/pi-team` · Team commands, messaging tools, and local mailbox storage; one extension.
+You open the terminals; `pi-team` lets those sessions send each other work, wake a
+free teammate, and return a result the requester can verify. Everything stays on
+this machine, in local files.
-- Local messaging between independent Pi sessions: queued **requests**, display-only **notes**, and correlated **results**.
-- Concurrent mailbox storage: many agents write at the same time without lock failures.
-- Automatic delivery when a teammate is idle; pending work survives restarts.
-- Automatic results verified against the original request, plus periodic review turns that chase unresolved work.
-- One `/team wake [message]` command requests an actionable status check-in from every teammate.
-- Automatic task-boundary compaction before the next team turn, keeping independent sessions focused and reusable.
-- Minimal live session widget, on-demand requester → assignee status, folded transcript previews, and one `/team` command surface.
-## Demo
-[![Watch the pi-team promotional demo](media/pi-team-demo/poster.png)](https://github.com/prjct-app/pi-team/raw/refs/heads/main/media/pi-team-demo/pi-team-demo.mp4)
-[Watch or download the 40-second demo](https://github.com/prjct-app/pi-team/raw/refs/heads/main/media/pi-team-demo/pi-team-demo.mp4). It shows the request flow, persistent local coordination, correlated results, and the two-command session setup. The soundtrack is an original instrumental composition with no voice-over or external samples.
+[![Watch the pi-team demo](media/pi-team-demo/poster.png)](https://github.com/prjct-app/pi-team/raw/refs/heads/main/media/pi-team-demo/pi-team-demo.mp4)
 ## Install
-Requires Pi installed separately and Node.js **22.19 or later**. Compatibility is tested with **Pi 0.85.1**; newer versions are not yet verified. This is an independent community package.
-Install with Pi's package manager:
+Requires Pi installed separately and Node.js **22.19 or later**. Tested against
+Pi **0.85.1**; newer versions are not yet verified. Independent community package.
 ```sh
 pi install npm:@prjct.app/pi-team
 ```
-For project-only installation, add `-l`: `pi install -l npm:@prjct.app/pi-team`. Restart Pi after installation. Do not install the same extension from both GitHub and npm: Pi treats those as different package identities.
+Add `-l` for project-only installation, and restart Pi afterwards. Manage it with
+the usual `pi list` / `pi update` / `pi remove` and `pi config`. Do not install the
+same extension from both GitHub and npm: Pi treats those as different packages.
-## Usage
+## Quickstart
 Open two interactive Pi terminals. In the first:
@@ -47,22 +39,28 @@ In the second:
 /team join demo reviewer
 ```
-Back in the first terminal:
+Back in the first:
 ```text
 /team note reviewer Please review the current README.
-/team wake Prioritize anything blocking the release.
+/team send reviewer Add a limits table to the README.
 ```
-A note appears in the transcript without starting model work. Use `/team send reviewer <task>` to queue work for one teammate, or `/team wake [message]` to queue the standard actionable check-in for everyone else in the team. Installation alone never joins a team. See the command reference below before enabling automatic reception.
+The note appears in the reviewer's transcript without starting any model work.
+The request wakes the reviewer once it is idle, and its result comes back to the
+coordinator. Installing alone never joins a team.
-Supported on Linux/macOS with local disk storage. Native Windows, shared network filesystems, and cross-machine messaging are not supported. Tests cover simulated Pi/model boundaries and real local processes; live model coordination still requires manual acceptance.
+Supported on Linux and macOS with local disk storage. Network filesystems,
+cross-machine messaging, and native Windows are not supported.
 ## Concepts
-A **team** is a named local mailbox on this machine. A session joins a team under
-an **alias**, which is its address; aliases are shared team addresses, not private
-identities. Messages come in three kinds:
+A **team** is a named local mailbox. A session joins under an **alias**: an
+address, not a privileged role or an automatic persona, and shared rather than
+private — anyone using this OS account can rejoin an offline alias and see its
+history. Each session keeps its own model, cwd, instructions, permissions, and
+conversation. Two agents editing the same files can still overwrite each other:
+this package does not manage file ownership.
 | Kind | Meaning |
 | --- | --- |
@@ -70,66 +68,14 @@ identities. Messages come in three kinds:
 | `note` | Display-only FYI. Appears in the transcript; never starts a model turn. |
 | `result` | The automatic reply to a request: outcome, final text, and observed files. Delivered to the emitter for verification. |
-Every message moves through visible states: `pending` (queued), `processing`
-(claimed by a live session), `completed` / `interrupted` (settled), and `seen`
-(notes already shown). The lifecycle of a request is: queued → claimed when the
-recipient is idle → worked on → result persisted and made available to the
-emitter → the recipient compacts before accepting another team turn → the
-emitter verifies the result against the original request and, if anything is
-missing, replies in the same thread with what remains to finish → the emitter
-compacts that result-review turn before accepting another team turn.
-### Status widget
-While joined, a minimal live widget above the editor shows only the session
-header:
-```text
-shop · pm · connected
-```
-The state is `connected`, `working`, `compacting`, `paused`, or `select a model`.
-A pending count is appended when work addressed to you is still queued. Run
-`/team status` to show the complete unresolved requester → assignee flow,
-including each task subject, assignee presence, and whether the request is queued
-or active. Subjects are visible team-wide for coordination, while request bodies
-remain limited to their sender and recipient.
-## Three terminals
-In the planning terminal:
-```text
-/team create shop
-/team join shop pm
-```
-In a backend worktree or repository:
-```text
-/team join shop backend
-```
-In a frontend worktree or repository:
-```text
-/team join shop frontend
-```
-Then tell PM: "Coordinate the login feature with backend and frontend. Agree on the
-API contract before implementation. Ask me before any push or deployment."
+While joined, a minimal widget above the editor shows `team · alias · state`,
+where state is `connected`, `working`, `compacting`, `paused`, or `select a
+model`, plus a pending count when work is queued for you.
 Membership is restored automatically when the same Pi session is resumed or
-reloaded, so a restarted terminal rejoins its team without any command.
-`/new` and `/fork` start unaffiliated sessions on purpose.
-`pm` is an address, not a privileged role or an automatic persona. Give each agent
-its responsibilities in its own session. Each retains its own model, cwd,
-instructions, permissions and conversation. Team names connect separate worktrees;
-they are not inferred from directory names. Two agents using the same files can
-still overwrite each other's edits: this package does not manage file ownership.
+reloaded. `/new` and `/fork` start unaffiliated sessions on purpose.
-### Commands
+## Commands
 | Command | Meaning |
 | --- | --- |
@@ -137,233 +83,102 @@ still overwrite each other's edits: this package does not manage file ownership.
 | `/team join shop backend` | Register this session and enable automatic reception |
 | `/team list` | List teams; refresh team-name completion |
 | `/team members` | Show aliases, cwd, and idle/busy/paused/offline status |
-| `/team status` | Show every unresolved requester → assignee relationship and task subject |
-| `/team wake [message]` | Queue an actionable check-in request for every teammate except this session; the message is optional |
+| `/team status` | Show every unresolved requester → assignee relationship |
+| `/team wake [message]` | Queue an actionable check-in for every other teammate |
 | `/team send backend Implement login` | Queue a request that can start work |
 | `/team note frontend API contract changed` | Display an FYI; never starts a model turn |
-| `/team inbox` | Show the most recent 20 sent/received records and their states |
+| `/team inbox` | Show the most recent 20 records and their states |
 | `/team pause` | Pause new work, without cancelling current work |
-| `/team resume` | Resume reception and reset the five-turn automatic budget |
-| `/team leave` | Leave; if processing a peer request, report its result first |
-Team names and aliases accept 1–48 lowercase letters, digits or hyphens, beginning
-with a letter. Unknown teams are rejected, never implicitly created. Duplicate
-live aliases are rejected. Tab completion supports subcommands, discovered team
-names and current teammate aliases. `/team list` refreshes teams created elsewhere.
-Sending to an offline **known** alias queues work until someone explicitly rejoins
-that alias. Sending to an unknown alias fails. An alias is a shared team address,
-not a private address for a particular human; anyone using this OS account can
-rejoin an offline alias and see its history. Use a new alias for a different role.
-`/team wake` sends a normal request to every known teammate except the sender,
-including offline aliases. Its standard prompt asks each agent to report current
-work, remaining work, blockers, and the next concrete step; request missing input
-through `team_send`; and finish authorized pending work instead of waiting. An
-optional message is appended as sender-provided context and does not replace the
-standard safety and authorization boundaries. Each recipient returns its own
-correlated result. If any teammate cannot be queued, the command reports the
-successful count and each failed alias instead of claiming complete delivery.
-### Agent tools
-- `team_members`: discover the current team, without leaking lease tokens.
-- `team_send`: send `{ to, kind: "request" | "note", subject, body }`.
-- `team_status`: read-only view of outstanding work: the team-wide unresolved
-  requester → assignee flow, requests you emitted (with recipient presence and
-  age), work queued for you, results awaiting your review, your currently
-  claimed task, and teammate presence.
+| `/team resume` | Resume reception and reset the automatic turn budget |
+| `/team leave` | Leave; if processing a request, report its result first |
+Names and aliases are 1–48 lowercase letters, digits, or hyphens, starting with a
+letter. Unknown teams are rejected, never implicitly created; duplicate live
+aliases are rejected. Sending to an offline **known** alias queues until someone
+rejoins it. Tab completion covers subcommands, discovered teams, and teammates.
+## Agent tools
+- `team_members` — discover teammates and their status.
+- `team_send` — send `{ to, kind: "request" | "note", subject, body }`.
+- `team_status` — outstanding work: what you emitted and is unresolved, what is
+  queued for you, results awaiting your review, and third-party team activity.
 Tools cannot create teams, join, resume reception, change permissions, or launch
-terminals. They require membership established by you. Requests return **queued**,
-not "task completed". Tools and manual commands use the same mailbox validation.
-## Delivery and results
-Requests and correlated results start a new turn only when the recipient is idle,
-has a selected model, no pending user messages or open extension prompt, an empty editor,
-and no task-boundary compaction in progress.
-A second readiness check handles a user starting work during a filesystem read.
-No running tool is interrupted. Notes are transcript-only; view them with
-`/team inbox`. They are not injected into the model's context.
-Incoming/outgoing messages show a folded preview. Use Pi's tool-output expansion
-shortcut (Ctrl+O by default) to read the full content. `/team inbox` refreshes the
-persisted state; an old transcript preview is an event snapshot, not a live receipt.
-For each processed request, the extension automatically sends **one** correlated
-result after `agent_settled`, not merely after an individual model/tool turn:
-- Last assistant **text**, capped at 3,000 characters. No thinking blocks.
-- Up to 50 absolute file paths observed in successful `edit`/`write` results.
-- An execution outcome: completed, failed, or interrupted.
-The assistant is instructed to include actual test results and blockers in its final
-text. The extension does **not** infer test success from a shell command or model
-claim. It does not automatically enumerate files changed through bash, custom tools,
-or other processes. The observed file list is not a Git diff or a complete change
-inventory. A completed run is not proof of task success; review the reported outcome
-and changes in the recipient worktree.
-Results may wake the requester so it can continue coordinating, but processing a
-result never produces another automatic reply. Delivered results quote the
-original request, and agents are instructed to verify the deliverable against it
-and reply in-thread with exactly what is missing when a result is incomplete or
-failed. Notes/acknowledgements never wake a model.
-### Task-boundary compaction
-After a request or correlated result-review turn settles and its mailbox outcome
-is safely persisted, the extension calls Pi's documented `ctx.compact()` API.
-That session claims no other peer message while compaction is running. The focused
-instructions preserve user-authored goals and constraints, team identity,
-unresolved requester → assignee relationships, concrete outcomes, blockers,
-files, tests, and next actions while asking Pi to discard verbose tool output,
-duplicated task payloads, completed traces, and private reasoning.
-Compaction changes model context, not extension registration or mailbox state:
-`/team` commands and team tools remain available, and each terminal continues as
-an independent Pi session rather than a spawned subagent. Pi still applies its
-configured `keepRecentTokens`, so this is compaction rather than a hard context
-reset. It uses a summarization model call now to reduce repeated context on later
-tasks. If compaction fails, the TUI warns and reception continues; Pi's normal
-context-threshold compaction remains available. User takeover skips this automatic
-step because the resulting turn is no longer an isolated team task.
-While you have emitted requests that stay unresolved past five minutes, an
-automatic review turn asks your agent every minute to chase the responsible
-teammate in-thread or report the blockage to you. Reviews quiet down after three
-turns without mailbox progress and re-arm on any change; they share the
-five-turn automatic budget, never start new work, and never retry interrupted
-work on their own. The one-minute cadence and five-minute threshold are fixed
-defaults; they are not user-configurable yet.
-User takeover during a peer task pauses reception and sends an interrupted
-notice instead of forwarding the unrelated final answer. Files observed after the
-takeover are not included. `/team leave` does not cancel the current run; quitting
-Pi or reloading while working produces an interrupted record, not a success report.
-## Limits and safety
-- At most five automatic peer turns per session before reception pauses. Use
-  `/team resume` to continue. No daily token or monetary budget is enforced.
-- At most eight non-result messages in an automatically linked conversation.
-- Duplicate sender/recipient/subject/body messages within one minute are refused.
-- Maximum 16 KB per outgoing body, 20 KB per serialized outgoing message, and
-  50 inbox slots per recipient. Pending/claimed deliveries occupy a slot until
-  settled, and each outgoing request reserves another slot for its automatic reply.
-  A send is rejected if the recipient is full, or if a request's sender cannot
-  reserve its reply. Notes need no reply reservation. Automatic replies are capped
-  at 32 KB; their observed file list is shortened with a notice when necessary.
-  Older teams may already be overcommitted; allow them to drain before sending
-  more work. Results for previously accepted requests are never discarded.
-- Maximum 100 aliases and 500 message records per team, reserving result capacity
-  for outstanding requests. History is not silently deleted. Create a fresh team
-  when full. Inbox display is limited to the latest 20; persisted records remain.
-- Peer messages explicitly identify their origin and are not user consent. Rules
-  instruct agents not to relay denied work, alter configuration, or evade plan mode.
-- Text is delivered as a custom message, never executed as a slash command or used
-  for automatic `@file` expansion. The session's normal tool policy still applies.
-- This is **not a sandbox or an authorization system**. Agents and processes under
-  the same OS user already have filesystem access. Prompt-level rules are not a
-  hard guarantee against a model that ignores instructions. Do not place untrusted
-  agents in a team or rely on team boundaries to protect secrets from that OS user.
-- Messages stay in local mailbox files but, when processed, their text is sent to
-  the recipient's configured model provider like normal prompt content. Results
-  are also shared with the requester. Do not send credentials or unrelated secrets.
-## Persistence and recovery
-Storage: `~/.pi/agent/teams/<team>/state.json` (respects `PI_CODING_AGENT_DIR`).
-Each team is one small JSON record stored with optimistic concurrency: readers
-never wait on a lock, and writers compare-and-swap a monotonically increasing
-revision, retrying against a fresh read on conflict. Many agents can therefore
-write at the same time instead of queueing for a team-wide lock. Every
-publication is written to a private temporary file, synced, hard-linked into a
-bounded `revisions/` history, and atomically renamed into place; the history
-doubles as recovery evidence for interrupted writes. Files are 0600 and team
-folders 0700; envelopes carry a content hash. Unsafe/symlinked roots or mailbox
-files and invalid schemas fail closed; corrupt files are preserved for manual
-recovery, not erased. Mailboxes written before envelope records migrate
-transparently on their first write.
-Presence lives outside the shared record: each member renews its own
-`presence/<alias>.json` every two seconds, so heartbeats add no write
-contention. Presence expires after 30 seconds, or sooner when the recorded
-process has exited. A lock abandoned by a crashed writer is reclaimed after ten
-seconds. Transient storage errors are reported but never pause reception; the
-next tick retries.
-Directory watchers provide prompt delivery; periodic polling recovers missed
-notifications. Watchers and timers only run for joined interactive sessions and are
-closed on shutdown. Teammates observing a disconnected peer holding a claim
-sweep it so its requester receives an interrupted result instead of waiting
-forever.
-Ownership tokens fence out replaced sessions. Pending messages survive disconnection.
-Claimed work is marked interrupted on disconnect/rejoin; it is **not automatically
-replayed**, since edits may already have happened. This favors avoiding duplicate
-side effects over guaranteed execution: a crash after claiming but before starting
-can also leave an interrupted task. There is no exactly-once guarantee for filesystem
-changes or model actions. If storage cannot record a result, reception pauses and
-reports an error; review before retrying.
-Membership, pause state, and pending task-boundary compaction are recorded in Pi
-session entries. Resuming the same session can rejoin; `/new` and `/fork` do not
-inherit membership. Explicit leave clears restoration. Before attempting to claim
-work, the extension records that restoration must pause, without pausing the live
-session. Successful result persistence clears this recovery-only pause; failures
-and interruptions retain it. If shutdown interrupts a post-task compaction, the
-same session retries compaction before claiming queued peer work.
-Thus even an abrupt process death during a task restores paused and requires
-`/team resume` before pending work starts. A crash just before a claim can
-conservatively require resume too. History and pending work remain in the team
-until explicitly managed outside this prototype.
-Local disks only: shared network filesystems, containers with separate home
-directories, cross-machine transport, and native Windows are not supported here.
-## Manage the package
-For an npm installation:
+terminals; they require membership you established. A request returns **queued**,
+never "task completed".
-```sh
-pi list
-pi update npm:@prjct.app/pi-team
-pi remove npm:@prjct.app/pi-team
-```
+## How delivery works
-Use `pi config` to enable or disable individual resources. Use `pi config -l` for project settings and add `-l` to removal when you installed locally.
+A request or result starts a turn only when the recipient is idle, has a selected
+model, no pending user message or open prompt, an empty editor, and no
+task-boundary compaction running. No running tool is interrupted.
-To pin version 0.1.3, use `pi install npm:@prjct.app/pi-team@0.1.3`. Pi skips pinned npm versions during package updates. For a Git installation, update or remove using the same `git:github.com/prjct-app/pi-team` source instead of the npm source.
+For each processed request the extension sends **one** result after the agent
+settles: the last assistant text capped at 3,000 characters (no thinking), up to
+50 absolute paths observed in successful `edit`/`write` calls, and an outcome of
+completed, failed, or interrupted.
-When switching from GitHub to npm, remove the Git installation first, then install the npm package and restart Pi.
+That file list is **not** a Git diff. Files changed through bash, custom tools, or
+other processes are not enumerated, and the extension never infers test success
+from a shell command or a model claim. **A completed run is not proof of success**:
+review the reported outcome and the recipient worktree.
-## Troubleshooting
+After each task the session compacts before accepting another, so independent
+sessions stay focused. While a request you emitted stays unresolved past five
+minutes, a review turn asks your agent to chase the teammate or tell you what is
+blocked. See [Architecture](docs/architecture.md) for both mechanisms.
-| Symptom or notice | Cause and action |
-| --- | --- |
-| A request stays queued | Run `/team status` to identify its requester, assignee, subject, and assignee presence. The recipient may be busy, paused, offline, missing a selected model, or typing in its editor. After five minutes, automatic review turns chase the teammate or surface the blockage to you. |
-| `Team auto-turn limit reached` | Five automatic peer turns ran without user input. Review the transcript, then `/team resume`. |
-| Automatic context compaction failed | The mailbox result was already persisted. Reception continues, and Pi can retry through its normal threshold compaction or `/compact`. |
-| `Membership expired or replaced` | Another live session took your alias, or your membership was fenced out. Rejoin with `/team join <team> <alias>`; choose a new alias if the old one is in use. |
-| `Recipient inbox full` / `Sender inbox full` | Fifty unsettled deliveries per member, with one slot reserved per outstanding request. Let the teammate drain its queue; notes are exempt from reply reservations. |
-| `Team history full (500 records)` | The team is at capacity; history is never silently deleted. Create a fresh team and rejoin. |
-| Repeated storage warnings | Transient read/write conflicts are retried automatically and never pause reception. If the same warning persists, check that the teams directory is a local disk and report the issue. |
-| A teammate went offline mid-task | Its claimed work is interrupted and the emitter receives that result; it is not replayed automatically. Review the worktree, then resend explicitly if still needed. |
+## Safety
-## Package and API documentation
+- **This is not a sandbox or an authorization system.** Agents and processes under
+  the same OS user already have filesystem access. Prompt-level rules are not a
+  hard guarantee against a model that ignores them. Do not place untrusted agents
+  in a team or rely on team boundaries to protect secrets from that OS user.
+- Peer messages are identified as untrusted data and **are not user consent**.
+  Agents are instructed not to relay denied work, change configuration, or evade
+  plan mode. Peer text is never executed as a slash command or expanded as a file
+  mention.
+- Messages stay in local files, but when processed their text goes to the
+  recipient's configured **model provider** like any prompt, and results go to the
+  requester. Do not send credentials or unrelated secrets.
+- User takeover during a peer task pauses reception and reports an interrupted
+  result instead of forwarding your unrelated work.
+## Limits
+| Limit | Value |
+| --- | --- |
+| Automatic peer turns before reception pauses | 5, then `/team resume` |
+| Messages in one automatically linked conversation | 8 non-result |
+| Unsettled deliveries per member | 50 slots, one reserved per outstanding request |
+| Records per team | 500, including reserved result capacity |
+| Members per team | 100 |
+| Outgoing body / serialized message | 16 KB / 20 KB |
+| Automatic result | 32 KB, file list shortened with a notice |
+| Presence lease | 30 s, renewed every 2 s |
+| Review threshold / cadence | 5 min unresolved, checked every 1 min |
+| Duplicate suppression | identical message within 1 min is refused |
+No daily token or monetary budget is enforced. History is never silently deleted:
+create a fresh team when one is full. Review cadence and the turn budget are fixed
+defaults, not user-configurable yet.
-Uses public commands, tools, lifecycle events, custom messages, persisted session entries, and `ExtensionContext.compact()`. Storage is self-contained (no runtime dependencies); Pi libraries remain peer dependencies.
+## Troubleshooting
-See [Package structure and compatibility](docs/package.md) for the manifest, dependency policy, shipped resources, and official references. This package follows the [official Pi package guide](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/packages.md) and [extension API guide](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/extensions.md) for the tested version.
+| Symptom | Cause and action |
+| --- | --- |
+| A request stays queued | Run `/team status`. The recipient may be busy, paused, offline, missing a model, or typing. After five minutes, review turns chase it or surface the blockage. |
+| `Team auto-turn limit reached` | Five automatic turns ran without user input. Review the transcript, then `/team resume`. |
+| Automatic compaction failed | The result was already persisted. Reception continues; Pi can still compact normally or via `/compact`. |
+| `Membership expired or replaced` | Another live session took your alias. Rejoin, choosing a new alias if the old one is in use. |
+| `Recipient inbox full` / `Sender inbox full` | Fifty unsettled deliveries per member, one slot reserved per outstanding request. Let the teammate drain; notes need no reservation. |
+| `Team history full (500 records)` | At capacity; history is never deleted. Create a fresh team and rejoin. |
+| Repeated storage warnings | Conflicts retry automatically and never pause reception. If one persists, check that the teams directory is on a local disk and report it. |
+| A teammate went offline mid-task | Its claimed work is interrupted and the emitter receives that result; it is not replayed. Review the worktree, then resend explicitly. |
 ## Development
-From a repository checkout:
 ```sh
 npm ci --ignore-scripts
 npm run check
@@ -371,8 +186,16 @@ npm test
 npm run check:package
 ```
-Pi loads the TypeScript entry point directly; no build step is required. To try this checkout for one run, use `pi -e .`. Tests use isolated temporary state and do not call model APIs. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution rules and [CHANGELOG.md](CHANGELOG.md) for release notes.
+Pi loads the TypeScript entry point directly; there is no build step. Use `pi -e .`
+to try a checkout. Tests use isolated temporary state and never call model APIs.
+`npm run check` also enforces that `src/` contains no `let`: session state is a
+single immutable record updated functionally, and reads go through its accessor at
+the point of use rather than being captured across an `await`.
+## More
-## License
+- [Architecture](docs/architecture.md) — storage, concurrency, recovery, context budget
+- [Package structure](docs/package.md) · [Releases](docs/releases.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md)
 [MIT](LICENSE).

package/docs/architecture.md ADDED Viewed

@@ -0,0 +1,160 @@
+# Architecture
+How pi-team stores state, coordinates concurrent sessions, and recovers from
+failure. For everyday use see the [README](../README.md).
+## Storage model
+Each team is one JSON record at `~/.pi/agent/teams/<team>/state.json`, honouring
+`PI_CODING_AGENT_DIR`. The record holds the member roster and the full message
+history. Team folders are `0700` and files `0600`; an unsafe, symlinked, or
+foreign-owned directory or record fails closed rather than being repaired.
+Records are wrapped in an envelope carrying a schema marker, a monotonically
+increasing revision, and a SHA-256 of the payload. A corrupt record is preserved
+for manual recovery, never erased. Mailboxes written before envelopes existed
+are read as revision 0 and rewritten as envelope records on their first write.
+## Concurrency
+Readers never take a lock. Every publication writes a private temporary file,
+hard-links it into a bounded `revisions/` history, and atomically renames it into
+place, so a concurrent read sees either the whole previous record or the whole
+next one. The history doubles as recovery evidence for an interrupted write.
+Writers compare-and-swap on the revision under a short-lived sibling lock.
+A conflict fails fast and the caller retries against a fresh read, so many agents
+write concurrently instead of queueing behind a team-wide lock. A lock abandoned
+by a crashed writer is reclaimed after ten seconds.
+Because every publication renames a **new inode** into place, readers can safely
+cache a parsed record keyed on `(inode, size, mtime)`: a write by any process
+changes the inode. Cached reads serve the polling loop; mutations always read
+uncached, so they never operate on the shared cached object.
+## Presence
+Presence lives outside the shared record. Each member rewrites only its own
+`presence/<alias>.json` every two seconds, so heartbeats add no write contention
+and never touch `state.json`.
+These files are deliberately non-durable: the atomic rename is kept, both fsyncs
+are not. Presence expires after 30 seconds and is rewritten every 2, so a write
+lost to a crash only makes a member look offline sooner — never alive longer.
+A member is also considered gone as soon as its recorded process has exited.
+## Request lifecycle
+A request is queued, claimed when the recipient is idle, worked on, and settled
+with a result delivered back to the emitter. The recipient compacts before
+accepting another team turn; the emitter verifies the result against its original
+request and replies in-thread only if something is missing.
+States are `pending`, `processing`, `completed`, `interrupted`, and `seen`
+(notes already displayed).
+## Sweeping orphaned claims
+A session that dies holding a claim would otherwise leave its requester waiting
+forever, so peers interrupt the claim on its behalf and the requester receives an
+`interrupted` result.
+Members are never removed from the record — leaving only marks them offline — so
+"someone is offline" is permanently true once anyone has ever left and cannot be
+used to decide when to sweep. A snapshot instead reports `sweepable`, true only
+when a member the record still counts as connected is actually dead **and** still
+holds a claim, which is the only case where sweeping changes anything. Everything
+else degrades correctly without it: rejoining re-admits a stale alias on its own,
+and displayed status comes from presence rather than the record.
+## Context budget
+What an extension puts in the model context is paid on every later turn and
+stays in the session branch, so injected values are bounded and any elision is
+stated rather than silent.
+| Carrier | In LLM context | Used for |
+| --- | --- | --- |
+| `before_agent_start` system prompt | yes, every turn | peer rules and team identity, carried exactly once |
+| `sendMessage` content | yes, and it persists | peer messages and review turns |
+| Tool results | yes, and they persist | `team_members`, `team_send`, `team_status` |
+| `appendEntry` | **no**, TUI only | notes, `/team inbox`, sent-message previews |
+Consequences worth knowing:
+- Peer rules are **not** repeated inside each message; they arrive once per turn
+  through the system prompt.
+- A delivered result quotes the original request excerpted to 500 characters,
+  with the id kept. Verification of a very long request works from an extract.
+- `team_status` lists are capped and report an `omitted` count. Its
+  `otherTeamWork` list carries only third-party work; anything addressed to or
+  emitted by this session is already in the other lists.
+- Each `team_status` call is a point-in-time snapshot. Earlier results in the
+  same conversation are stale but cannot be retracted, which is why each one is
+  kept small.
+## Task-boundary compaction
+Once a result is safely persisted, the extension calls Pi's `ctx.compact()`. That
+session claims no other peer message while compaction runs. The instructions
+preserve user-authored goals and constraints, team identity, unresolved
+requester → assignee relationships, outcomes, blockers, files, tests, and next
+actions, and discard verbose tool output, duplicated payloads, completed traces,
+and private reasoning.
+Compaction changes model context, not extension registration or mailbox state:
+`/team` commands and tools stay available, and each terminal remains an
+independent Pi session rather than a spawned subagent. Pi still applies its
+configured `keepRecentTokens`. If compaction fails, the TUI warns and reception
+continues. User takeover skips it, because the turn is no longer an isolated team
+task.
+## Recovery and guarantees
+Ownership tokens fence out replaced sessions. Pending messages survive
+disconnection. Claimed work is marked interrupted on disconnect or rejoin and is
+**not automatically replayed**, since edits may already have happened.
+This favours avoiding duplicate side effects over guaranteed execution. **There is
+no exactly-once guarantee** for filesystem changes or model actions: a crash after
+claiming but before starting also leaves an interrupted task. If storage cannot
+record a result, reception pauses and reports an error.
+Membership, pause state, and pending compaction are recorded in Pi session
+entries. Resuming the same session rejoins; `/new` and `/fork` do not inherit
+membership. Before claiming work the extension records that restoration must
+pause, without pausing the live session, so an abrupt process death during a task
+restores paused and requires `/team resume`. A crash just before a claim can
+conservatively require resume too.
+Directory watchers provide prompt delivery; polling every two seconds recovers
+missed notifications. Both run only for joined interactive sessions and close on
+shutdown. Transient storage errors are reported but never pause reception.
+## Design decisions and non-goals
+| Concern | Choice |
+| --- | --- |
+| Session creation | The user opens every terminal; nothing is spawned |
+| Discovery | Explicit named teams and aliases, never inferred from directories |
+| Transport | Local filesystem records; no broker, socket server, or daemon |
+| Presence | Per-member files outside the record; heartbeats never lock |
+| Concurrent writes | Compare-and-swap with retry; no team-wide lock |
+| Follow-up | Periodic review turns delegated to the agent, not programmatic retries |
+| Active recipient | Wait until fully idle; no steering between tools |
+| Offline recipient | Persist to a known alias until it rejoins |
+| Approval | Never supplied by peers; local policies always win |
+| Coordination | Direct messages and bulk check-ins; no task board or worktree manager |
+| Scope | Local disks only: no network filesystems, cross-machine transport, or native Windows |
+Not provided: file ownership between agents, a sandbox, an authorization system,
+or protection of secrets from other processes under the same OS user.
+## Pi interfaces used
+`registerCommand`, `registerTool`, `sendMessage`, `appendEntry`, custom entry and
+message renderers, `setWidget`, `getEditorText`, `isIdle`, `hasPendingMessages`,
+`compact`, session lifecycle events, UI prompt events, `tool_result`,
+`message_end`, and `agent_settled`. All public and documented; no host internals
+are imported, no prototypes patched, and peer text is never shell-evaluated or
+expanded as file mentions.

package/docs/package.md CHANGED Viewed

@@ -2,57 +2,40 @@
 ## Identity
-- npm name: `@prjct.app/pi-team`.
-- Initial version: `0.1.0`.
-- Source repository: [prjct-app/pi-team](https://github.com/prjct-app/pi-team).
-- Tested host: Pi `0.85.1`; Node.js `22.19+`.
-The npm name and repository name may differ. Repository URLs remain unchanged. Existing runtime command names, event names, persisted entry types, and settings keys are unchanged by the package rename.
-## Resource manifest
-```json
-{
-  "name": "@prjct.app/pi-team",
-  "keywords": [
-    "pi-package"
-  ],
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  }
-}
-```
-The `pi-package` keyword makes the package discoverable. Manifest paths are relative to the package root. The extension entry point is shipped as TypeScript because Pi loads it directly. There is no CLI binary or JavaScript build artifact to install separately.
+- npm name: `@prjct.app/pi-team`
+- Repository: [prjct-app/pi-team](https://github.com/prjct-app/pi-team)
+- Tested host: Pi `0.85.1`; Node.js `22.19+`
-## Dependencies
-Pi-provided libraries imported by this package are declared in `peerDependencies` with `*`, as required by Pi's package guide. They are not bundled. Exact Pi 0.85.1 development dependencies establish the tested baseline; the peer wildcard is not a claim that every Pi release is supported.
-Third-party runtime dependencies belong in `dependencies`. Companion extensions are installed separately only when communication uses Pi's event bus; this package does not import code from a separately installed companion. A package that directly imports another Pi package's resources must instead bundle it following the official guide.
+The npm name and repository name may differ. The package rename changed no
+runtime command names, event names, persisted entry types, or settings keys.
-## Public interfaces
+## Dependencies
-Uses public commands, tools, lifecycle events, custom messages, persisted session entries, and programmatic compaction through `ExtensionContext.compact()`. Storage is self-contained with optimistic-concurrency records; this package has no runtime dependencies. Pi libraries remain peer dependencies.
+Pi-provided libraries are declared in `peerDependencies` with `*`, as the Pi
+package guide requires, and are not bundled. The exact Pi 0.85.1 devDependencies
+establish the tested baseline; the peer wildcard is not a claim that every Pi
+release is supported. This package has **no runtime dependencies**: storage is
+self-contained.
-## Published contents
+Third-party runtime dependencies would belong in `dependencies`. A package that
+directly imports another Pi package's resources must bundle it instead.
-The `files` allowlist includes runtime resources, user documentation, and license files. Development tests, dependency folders, repository settings, and Git history are excluded. npm also includes `package.json` automatically. The npm lockfile remains in the repository for repeatable development installs.
+## Publishing
-Run `npm run check:package` to inspect the exact prospective tarball before release. Check that each manifest entry and each referenced local document exists in the packed file list. Only claim npm availability after verifying a successful registry publication.
+The `files` allowlist ships runtime resources, user documentation, and licence
+files; tests, dependencies, and repository settings are excluded. Run
+`npm run check:package` to inspect the exact prospective tarball, and confirm every
+manifest entry and referenced local document is present. Only claim npm
+availability after verifying a successful registry publication.
 ## Official references
-These links are pinned to the tested Pi version rather than the moving main branch:
-- [Packages: manifest, sources, dependencies, filtering, and deduplication](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/packages.md).
-- [Extensions: lifecycle, commands, tools, messages, and UI APIs](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/extensions.md).
-- [TUI: components, rendering, terminal widths, and image support](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/tui.md).
-The installed `@earendil-works/pi-coding-agent@0.85.1` package ships the same guides under `docs/`. The [current official guide](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) may describe changes beyond this tested baseline.
+Pinned to the tested version rather than the moving main branch:
-## Discovery metadata
+- [Packages](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/packages.md) — manifest, sources, dependencies, deduplication
+- [Extensions](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/extensions.md) — lifecycle, commands, tools, messages, UI
+- [TUI](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/tui.md) — components, rendering, widths
-The `pi-package` keyword identifies this package for the official Pi gallery. Focused keywords describe its actual features. The `pi.image` field points to its public cover, following the [official gallery metadata format](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/packages.md#gallery-metadata).
+The installed `@earendil-works/pi-coding-agent@0.85.1` ships the same guides under
+`docs/`. The [current guide](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md)
+may describe changes beyond this tested baseline.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@prjct.app/pi-team",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Coordinate independent PI Agent sessions with local team messaging, queued tasks, and shared results.",
   "type": "module",
   "keywords": [
@@ -63,10 +63,10 @@
     "index.ts",
     "src",
     "docs",
+    "!docs/cover.png",
     "README.md",
     "CONTRIBUTING.md",
     "LICENSE",
-    "CHANGELOG.md",
-    "docs/package.md"
+    "CHANGELOG.md"
   ]
 }

package/src/mailbox.ts CHANGED Viewed

@@ -150,15 +150,22 @@ export class Mailbox {
     for (const attempt of ATTEMPTS) {
       const record = await this.readState(team);
       const state = record.payload;
-      const before = JSON.stringify(state);
+      // The parser already produced this for the content hash. A pre-envelope
+      // record carries none, so that path serializes as before. A mismatch
+      // could only ever cause one redundant publication, never a lost write:
+      // `before` comes from the pre-action object and `after` from the
+      // post-action one, so they cannot coincide by accident.
+      const before = record.payloadJson ?? JSON.stringify(state);
       const presence = await this.readPresence(team);
       const swept = state.members.filter(member => member.status !== 'offline' && !this.alive(member, presence));
       for (const member of swept) this.disconnect(state, member);
       const result = action(state);
-      if (before === JSON.stringify(state)) return result;
+      const after = JSON.stringify(state);
+      if (before === after) return result;
       if (!Value.Check(StateSchema, state)) throw new Error('Invalid mailbox format; refusing to write');
       try {
-        await publish(this.recordPath(team), record.revision, state, this.normalize(team), { maxBytes: MAX_BYTES });
+        await publish(this.recordPath(team), record.revision, state, this.normalize(team),
+          { maxBytes: MAX_BYTES, payloadJson: after });
         await Promise.all(swept.map(member => unlink(this.presencePath(team, member.alias)).catch(() => {})));
         return result;
       } catch (error) {
@@ -223,7 +230,14 @@ export class Mailbox {
     await this.writePresence(member, status);
   }
-  /** Lock-free consistent view of the record with presence-based statuses. */
+  /**
+   * Lock-free consistent view of the record with presence-based statuses.
+   *
+   * The cached read returns a shared record, and the message objects below are
+   * the record's own, not copies. Never mutate them: it would corrupt both the
+   * process-wide cache and the `payloadJson` taken alongside it. `mutate` is
+   * safe because it reads uncached.
+   */
   async snapshot(member: Membership): Promise<Snapshot> {
     const record = await this.readState(member.team, true);
     this.owner(record.payload, member);

package/src/store.ts CHANGED Viewed

@@ -14,7 +14,13 @@ import { dirname, join } from 'node:path';
  * hard-links its envelope into a bounded revisions/ history, which doubles as
  * recovery evidence for interrupted writes.
  */
-export type Record<T> = { revision: number; payload: T };
+/**
+ * `payloadJson` is the canonical `JSON.stringify(payload)`, carried when the
+ * parser already had to compute it for the content hash. It is consistent by
+ * construction, never derived from the raw file text, and always optional: a
+ * pre-envelope record has none and callers fall back to serializing.
+ */
+export type Record<T> = { revision: number; payload: T; payloadJson?: string };
 /** Parse raw file bytes into a record, throwing on corruption. Never deletes. */
 export type Normalize<T> = (raw: string) => Record<T>;
 /**
@@ -46,10 +52,11 @@ export function envelope<T>(raw: string): Record<T> {
   if (typeof parsed.revision !== 'number' || !Number.isSafeInteger(parsed.revision) || parsed.revision < 1) {
     throw Object.assign(new Error('Invalid record revision.'), { code: 'CORRUPT_RECORD' });
   }
-  if (parsed.contentHash !== sha256(JSON.stringify(parsed.payload))) {
+  const payloadJson = JSON.stringify(parsed.payload);
+  if (parsed.contentHash !== sha256(payloadJson)) {
     throw Object.assign(new Error('Record hash mismatch; preserved for manual recovery.'), { code: 'CORRUPT_RECORD' });
   }
-  return { revision: parsed.revision, payload: parsed.payload as T };
+  return { revision: parsed.revision, payload: parsed.payload as T, payloadJson };
 }
 function assertSafeFile(path: string, info: { isFile(): boolean; size: number; mode: number; uid: number }, maxBytes: number): void {
@@ -162,7 +169,7 @@ async function pruneRevisions(dir: string, latest: number): Promise<void> {
  */
 export async function publish<T>(
   path: string, expectedRevision: number, payload: T, normalize: Normalize<T>,
-  options: { maxBytes: number; durability?: Durability },
+  options: { maxBytes: number; durability?: Durability; payloadJson?: string },
 ): Promise<Record<T>> {
   const durability = options.durability ?? 'full';
   await mkdir(dirname(path), { recursive: true, mode: 0o700 });
@@ -175,12 +182,15 @@ export async function publish<T>(
       throw Object.assign(new Error(`Record changed before the write; current revision is ${revision}.`), { code: 'STALE_REVISION' });
     }
     const next = revision + 1;
-    const payloadJson = JSON.stringify(payload);
+    // Supplied by callers that already serialized this exact object; it must
+    // equal JSON.stringify(payload). The record stays self-consistent either
+    // way, because the hash is taken over the string that gets embedded.
+    const payloadJson = options.payloadJson ?? JSON.stringify(payload);
     const text = `{"schemaVersion":1,"revision":${next},"contentHash":"${sha256(payloadJson)}","payload":${payloadJson}}`;
     if (Buffer.byteLength(text) > options.maxBytes) throw new Error('Record size limit exceeded.');
     const historyPath = join(dirname(path), 'revisions', `${next}.json`);
     const previous = await readRecord(historyPath, (raw: string) => envelope<T>(raw), options.maxBytes);
-    if (previous && (previous.revision !== next || sha256(JSON.stringify(previous.payload)) !== sha256(payloadJson))) {
+    if (previous && (previous.revision !== next || (previous.payloadJson ?? JSON.stringify(previous.payload)) !== payloadJson)) {
       throw new Error('An interrupted publication owns this revision; explicit recovery is required.');
     }
     if (!previous) await writeAtomic(historyPath, text, durability);
@@ -195,7 +205,7 @@ export async function publish<T>(
     cache.delete(path);
     counters.publishes++;
     await pruneRevisions(dirname(path), next).catch(() => {});
-    return { revision: next, payload };
+    return { revision: next, payload, payloadJson };
   } finally {
     await lock.close();
     await unlink(lockPath).catch(() => {});

package/docs/cover.png DELETED Viewed

Binary file

package/docs/reference.md DELETED Viewed

@@ -1,42 +0,0 @@
-# Reference and deliberate differences
-Verified against the live official Markdown documentation during implementation:
-- https://code.claude.com/docs/en/cross-session-messaging.md
-- https://code.claude.com/docs/en/agent-teams.md
-The closest reference is **cross-session messaging**: independently started sessions,
-discovery with `ListAgents`, communication with `SendMessage`, compact expandable
-previews, and per-session permission boundaries. Current documentation says local
-Claude Code sessions use per-session sockets/named pipes. The team feature adds a
-lead that spawns teammates, optional shared task coordination, and JSON mailboxes.
-These are distinct features; historical `TeamCreate` examples are not current.
-Our user-selected scope differs deliberately:
-| Concern | pi-team |
-| --- | --- |
-| Session creation | User opens all terminals |
-| Discovery | Explicit named team and aliases |
-| Transport | Local filesystem records with optimistic concurrency, no broker or socket server |
-| Presence | Per-member files outside the shared record; heartbeats never lock |
-| Concurrent writes | Compare-and-swap revisions with retry; no team-wide lock |
-| Follow-up | Periodic review turns delegated to the agent, not programmatic retries |
-| Active recipient | Wait until fully idle; no between-tool steering |
-| Offline recipient | Persist to a known alias until rejoin |
-| Results | Automatic last-text reply to requests, quoted against the original request |
-| Approval | Never supplied by peers; preserve local policies |
-| Coordination | Direct messages, `/team wake [message]` bulk check-ins, and task-boundary context compaction; no task board or worktree manager |
-| Limits | Bounded conversations, inboxes and automatic turns |
-| UI | Existing Pi loader plus a minimal session widget, on-demand requester → assignee flow through `/team status`, and expandable messages |
-Pi APIs used: `registerCommand`, `registerTool`, `sendMessage`, custom entry/message
-renderers, `setWidget`, `getEditorText`, `isIdle`, `hasPendingMessages`, `compact`,
-session lifecycle, UI prompt events, `tool_result`, `message_end`, and `agent_settled`.
-No monkey-patching of Pi internals, shell evaluation of peer messages, forwarding
-of thinking, or modifications to existing local extensions are required.
-Integration tests exercise the extension through a simulated Pi API, backed by real
-filesystem operations. The three-process scenario hosts PM/backend/frontend in
-separate Node processes, checks queued delivery and correlated responses, kills the
-backend, and checks recovery. This is not a live three-model behavioral evaluation.