@fradser/pi-agent-teams 0.8.2 → 0.9.0

package/.memory/MEMORY.md

@@ -3,4 +3,4 @@
 - `openai_teammate_api_reference.md` — OpenAI external Teammate / Workspace Agents API reference (Workspace Agents API, Files API, file search, vector stores, Threads API). Reference only, not for Pi extension usage guidance.
 
 - `team-centric-design.md` — Agent Teams current architecture: named resident RPC teammates, shared task board with atomic self-claim, direct P2P inboxes, verify-gated completion, harness-driven wake-ups. Supersedes the deleted run-centric DAG design.
-- `follow-up-queue.md` — Leader-report FIFO handoff: dispatch the first report to Pi's native follow-up queue while the leader is active; native follow-up does not interrupt tool loops.
+- `follow-up-queue.md` — Teammate report steering handoff: hand reports immediately to Pi's steering channel without an internal serialized follow-up queue; delivers at safe tool boundaries.

package/.memory/follow-up-queue.md

@@ -1,21 +1,18 @@
 ---
 name: follow-up-queue
-description: Agent Teams serializes automatic teammate reports through Pi custom-message follow-ups, including reports arriving while the leader is active
+description: Agent Teams hands teammate reports immediately to Pi's steering channel without an internal serialized follow-up queue
 type: project
 ---
 
 ## Why
 
-Pi accepts a custom `sendMessage(..., { triggerTurn: true, deliverAs: "followUp" })` while the leader is streaming and retains it in its native follow-up queue. Agent Teams must not add an idle-only gate that delays that handoff until the entire leader run settles. Doing so leaves reports in the package queue during a leader tool-call loop instead of at least making them visible to Pi's proper queue.
-
-A native follow-up still runs only after the current tool/steering loop can naturally finish; it does not interrupt an in-flight tool or an unbounded leader loop. The leader guidance therefore forbids sleep-based polling, and urgent interruption needs an explicit steer/abort design rather than changing ordinary reports.
+Using `deliverAs: "followUp"` delayed teammate reports until the entire leader tool-calling turn finished, and an internal serialized queue holding subsequent reports until `agent_settled` meant multiple reports backlogged during active leader work and then flooded the leader across subsequent turns. Additionally, worker reports need to arrive promptly when the leader is working, at the next safe tool boundary, rather than waiting for the entire run to settle.
 
 ## How to apply
 
-- `packages/agent-teams/src/follow-up-queue.ts` owns a FIFO report queue and one active dispatch.
-- `pump()` dispatches the first pending report whether the leader is idle or active. Active leaders receive it through Pi's native `followUp` channel; idle leaders begin a new turn.
-- Keep only one package dispatch active. `agent_settled` releases it and schedules the next pending report, preserving FIFO and one-report-per-leader-turn semantics.
-- Match idle-started dispatches in `before_agent_start`/`agent_start`; a watchdog restores a dispatch when no start occurs. Active-run dispatches are already accepted by Pi's follow-up queue and wait for settlement.
-- `sendMainSessionFollowUp` only enqueues. Do not call Pi's void `sendMessage` directly from worker completion paths.
-- The team machine suppresses every report after the first accepted terminal status in a wake-up sequence; a new wake-up resets that boundary. Distinct intermediate reports, including identical bodies before terminal status, remain deliverable, and the same content is not suppressed across assignments.
-- Keep BDD coverage in `features/agent-teams.feature` and the busy-leader serialization regression in `tests/test_teammate_package.py`.
+- `packages/agent-teams/src/leader-reports.ts` provides report types, envelopes, and display grouping; the internal `FollowUpQueue` is removed.
+- Reports from `team-machine.ts` are handed directly to `leaderPi.sendMessage(..., { triggerTurn: true, deliverAs: "steer" })`.
+- Working leaders receive reports at the next safe tool boundary without interrupting in-flight tools; idle leaders wake immediately.
+- The leader guidance emphasizes that workers execute assignments autonomously without progress nagging; leader steering is reserved for newly discovered information that affects the worker's assignment.
+- Silence is console telemetry only; no heartbeat or stall notices reach the leader. Provider hangs surface through the terminal close-path diagnostic (repo ADR 0002).
+- Keep BDD coverage in `features/agent-teams.feature` and native delivery regressions in `tests/test_immediate_reports.py`.

package/.memory/team-centric-design.md

@@ -1,21 +1,25 @@
 ---
-name: teammate-resident-teams
-description: Agent Teams (packages/agent-teams) — team-centric: named resident RPC teammates, shared task board with atomic self-claim, unified addressed messaging, verify-gated completion, harness-driven wake-ups
+name: agent-teams-final-surface
+description: Final Agent Teams public surface and lifecycle rules
 type: project
 ---
 
-`packages/agent-teams` is a Claude-Code-style collaborative organization layer for Pi: the Pi session is the team leader; teammates are named resident child Pi processes in RPC mode; coordination runs through a shared local task board plus direct peer inbox messaging. It replaces the former run-centric DAG design (`teammate_run`/fanout/retry are deleted).
-
-**Why:**
-Exploratory / competitive-hypothesis work (multi-hypothesis debugging, three-way review with cross-challenge) cannot be represented cleanly by a static DAG because workers must exchange findings mid-task. One-step delegation avoids the old registry ceremony: `teammate_spawn(name, agent, prompt?)` carries the kickoff task and the board is optional. A later grilling decision identified tool count, conceptual overlap, and parameter breadth as separate problems: the surface was reduced from ten names to seven by making `send_message` the one addressed message primitive, registering `task_list` once for both sides, and moving model/worktree from spawn overrides into agent frontmatter.
+**Why:** Agent Teams uses one explicit coordination surface so Work authority,
+communication, and resident lifecycle cannot be confused.
 
 **How to apply:**
-1. **Seven tool names**: leader gets `teammate_spawn(name, agent, prompt?)`, `teammate_shutdown(name)`, `send_message(to, message, status?)`, `task_create`, and shared `task_list`; workers get the same `send_message`, shared `task_list`, `task_claim`, and `task_submit`. There is no `teammate_message`, cancel/retry/run/fanout, or polling tool.
-2. **Unified messaging**: `send_message(to="leader", message, status?)` is a worker report written to the validated outbox; `send_message(to="<peer>", message)` writes the recipient inbox directly; leader-addressed teammate messages route through a running control stream or idle wake queue. Synchronous routing outcomes are deliberately narrow: `steered` means the active control stream accepted the write, while `queued` means the harness still owns delivery into a recipient turn. Peer inbox and leader outbox writes are therefore queued, not delivered; no routing label claims the recipient read or processed the message. `status` is invalid except for `to="leader"`. The first non-empty message line is the console title.
-3. **Declarative role attributes**: agent frontmatter carries `model`, optional `verify`, and boolean `worktree`.Definitions live in one project directory with filename-based scopes: `<name>.local.md` is project-local (personal, never committed) and dedupes against its `<name>.md` counterpart (project scope, git-managed, team-shared); user-level sits in `~/.pi/agent/agents`; precedence is project-local > project > user > bundled and `resolveAgent` exposes scope + gitManaged for provenance. Spawn has no cwd/model/worktree override; create a role variant instead. `worktree: true` gives every instance of that role a dedicated Git worktree and diff capture at shutdown.
-4. **Residents/wake-ups (constitution: detect and notify, never terminate)**: long-lived RPC children, 8-process session cap; wake-up sequences have NO turn-count or duration caps — no configuration may automatically terminate a working teammate. Turn counts and silence durations are telemetry only. The 500ms harness poll drains outboxes, applies intents, routes inboxes, wakes only for queued deliveries or a paced claimable-task notice, and runs the stall heartbeat: 30 minutes without any RPC output (`PI_TEAMMATE_STALL_NOTICE_MS`, 0 disables) sends the leader one actionable notice per silence episode — that notice is the LAST automatic action; continuing, steering, shutting down, or respawning a context-carrying successor (original kickoff + mailbox reports + board claims + liveText tail) belongs to the leader model alone. Any stream event or prompt delivery resets `lastOutputAt` and clears `stallNoticeSentAt`. Stall diagnostics render independently as `[agent] event` health notices and never decorate a `[message]` routing row.
-5. **Board**: only leader writes `~/.pi/agent/tasks/<sessionKey>/board.json`; workers use exclusive-create claim/submission marker files. Task completion uses effective task verify or agent verify; failed verification returns the reviewer's findings to the claimer. The board persists across restarts; runtime state does not. `task_create` never spawns a teammate: it immediately offers newly claimable work to existing idle teammates and reports whether anyone was notified; with no living teammates it tells the leader to call `teammate_spawn`. Boards are keyed by the Pi session file (or cwd without one), so fresh sessions do not import another session's tasks unless they resume the same board directory.
-6. **Reliability/UI**: per-spawn identity validation, event/message dedup, crash releases claimed tasks, role worktree diff at shutdown. Widget above the input box shows ONLY working/starting teammates as spinner rows with live activity and hides when nobody is working; idle/stopped teammates live only in the /teammate console roster; spawn prints a legacy-style `[agent] started · @name · task` transcript line; `/teammate` offers roster/board pages and message/task detail.
-7. **Node-native TS**: relative imports use explicit `.ts` extensions (root tsconfig permits them), allowing node to strip-types modules in package tests.
 
-**Related:** [[pi-cli-print-json-usage]] [[no-global-input-interception]] [[pi-package-conventions]]
+1. Public model tools are `agent`, `work`, and `agent_event`; `/agent-teams`
+is the human management surface.
+2. `agent` uses strict `delegate`, `start`, `inspect`, and exact-session `stop`
+actions. Session handles include the resident and spawn incarnation.
+3. `work` owns create/list/assign/claim/submit/release/completed-only reopen/
+supersede. Claim and submit are marker intents; the single-writer harness owns
+acceptance and verification.
+4. `agent_event` is communication-only with `inform` or `request`. It never
+completes, releases, reopens, or reassigns Work.
+5. Worker capability grants contain only `agent_event` and `work` plus requested
+Pi built-ins. Verification freezes execution and archives deferred mail as Work
+history.
+6. Incompatible persisted runtime snapshots fail explicitly; no silent migration
+or legacy-tool fallback is allowed.

package/README.md

@@ -1,179 +1,137 @@
-# Agent Teams Pi Package
+# @fradser/pi-agent-teams
 
-Claude-Code-style collaborative agent teams for Pi: named resident teammates, a shared local task board with self-claim, and direct peer-to-peer messaging.
+Agent Teams provides one final coordination surface for Pi:
 
-**Display Name**: Agent Teams
-
-## What This Package Does
-
-The team leader (your Pi session) spawns named teammates (isolated resident agents / sub-agents) as long-lived child Pi processes in RPC mode. Each teammate has an isolated context, a peer inbox, and access to a shared task board. When third-party skills or engineering workflows instruct to spawn an agent, call a subagent, or delegate work to a worker agent, `teammate_spawn` is the tool to invoke. The harness—not the leader model—polls for activity: it drains leader reports, routes peer mail, applies task claims and submissions, judges verify prompts with fresh one-shot reviewers, and wakes idle teammates only when work or mail exists.
-
-The message surface is deliberately singular: `send_message` is the only messaging primitive. Workers report with `to: "leader"`; teammates address peers by name; the leader addresses teammates by name. The routing implementation varies by destination (outbox, inbox, or control stream), but callers use one schema.
-
-## Install
-
-```bash
-pi install /path/to/pi-packages/packages/agent-teams
+```text
+agent
+work
+agent_event
+/agent-teams
 ```
 
-Then run `/reload` in Pi.
-
-## Agents Are Declarative Files
+`agent` manages Agent sessions through strict actions:
 
-Agent definitions are Markdown files with frontmatter; the body is the role prompt.
-
-```markdown
----
-name: isolated-security-auditor
-description: Read-only security reviewer in an isolated worktree
-tools: read,bash
-model: provider/model       # optional; "inherit" = the leader's current model at spawn time
-verify: review prompt       # optional role-default gate; a fresh reviewer answers VERDICT: PASS/FAIL
-worktree: true              # optional role-default Git isolation
----
-Review the assigned scope for exploitable security problems. Do not edit files.
+```ts
+agent({ action: "delegate", name: "reviewer", prompt: "Audit authentication" })
+agent({ action: "start", name: "reviewer" })
+agent({ action: "inspect", name: "reviewer", session: "session:reviewer-...:spawn-..." })
+agent({ action: "stop", session: "session:reviewer-...:spawn-..." })
 ```
 
-Teammate model resolution at spawn time, in precedence order: an explicit
-`provider/model` pin wins; `inherit` pins the leader session's current model;
-without a pin, the unified teammate model set from `/agent-teams` (press `m`
-in the roster page for a type-to-filter picker) applies to this session;
-otherwise Pi picks its own default.
-
-Discovery precedence per name (later overrides earlier): user < project <
-project-local, with generated session roles filling only the names no file
-defines. A re-spawn that supplies an explicit inline definition replaces a
-previously generated session role of the same name; definition files are never
-overwritten by inline input.
-
-There are no built-in roles. When a needed role has no definition, the
-leader creates it in memory for the current session: it derives the definition
-from the task using the abstract role reference in `references/agent-roles.md`
-(definition anatomy, archetype axes, invariants), registers it, and then spawns.
-The role is not written to disk or reused in a later session unless the user
-explicitly requests persistence; only then may the leader set `definition.persist`
-and choose a project or project-local scope.
-
-| Scope | Location | Git semantics |
-|---|---|---|
-| user | `~/.pi/agent/agents/*.md` | system-level, never committed |
-| project | `<cwd>/.pi/agents/<name>.md` | **git-managed** — commit for the team |
-| project-local | `<cwd>/.pi/agents/<name>.local.md` | **local** — personal override, gitignore by convention |
-| session | in-memory registry | **ephemeral** — disappears at session start, no source file |
-
-A teammate definition is just a Markdown file you own. Shared roles live in `.pi/agents/<name>.md`; a personal tweak to that exact role is `<name>.local.md` in the SAME directory — same teammate name, local scope wins, and discovery deduplicates the pair into one entry (never two). `resolveAgent` reports each definition's `scope` and `gitManaged`; guidance lists both so the leader knows provenance.
-
-## Build a Team
-
-```text
-teammate_spawn({
-  name: "security",
-  agent: "reviewer",
-  prompt: "Review the auth middleware",
-  resources: ["packages/api/auth"]
-})
-
-teammate_spawn({ name: "backend", agent: "worker" })
+A delegate action can include an inline definition. It is session-local unless
+`persist: true` is explicitly supplied in that definition. Choose explicit minimal
+canonical tool IDs (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`,
+`powershell`); extension aliases such as `ffgrep` are not inherited. Omitted
+`tools` or `tools: []` grants only `agent_event` and `work`, never default shell
+or file access. Delegate/start results and inspection expose the recorded
+`session.tools` grant, with a coordination-only warning when applicable.
+Inspection uses the session's recorded grant, not a changed role definition;
+legacy records without a grant leave it unknown rather than claiming no tools.
+
+For an unknown role, provide a compact inline definition:
+
+```ts
+agent({ action: "delegate", name: "reader", prompt: "Read README.md and cite its install command",
+  definition: { description: "Read evidence", prompt: "Read the assigned file and cite evidence", tools: ["read"] } })
 ```
 
-- Spawn accepts `name`, `agent`, an optional kickoff `prompt`, optional `resources`, and optional `handoffFrom`. Resources are stable path-like tags used to prevent overlapping mutating assignments; they are advisory to the filesystem but enforced by the task/assignment state machine.
-- A kickoff creates one direct assignment. After its terminal report, that worker cannot claim board work until the leader explicitly sends `reopen: true` with a distinct next assignment.
-- `handoffFrom` builds a successor kickoff from the predecessor's latest assignment, board claim, and recent leader reports; it never silently transfers a board claim.
-- Without a kickoff prompt, the teammate idles until messaged or until eligible claimable work appears.
-- Teammates stay alive between tasks and consume no model tokens while idle.
-- A session-wide cap of 8 living teammates applies.
-- An agent declaring `worktree: true` gets its own Git worktree; at shutdown its changes are committed onto the worktree branch, the directory is removed, and the branch is kept so captured work stays retrievable (`git diff <base>..<branch>`).
-- `teammate_shutdown({ name })` stops one teammate and releases its claimed task back to the board.
-
-## Coordinate Through One Message Primitive and the Board
-
-```text
-send_message({
-  to: "security",
-  message: "Please challenge the backend finding against the current middleware."
-})
-
-task_create({
-  subject: "Fix auth middleware findings",
-  description: "Address the confirmed security findings in packages/api/src/auth.ts",
-  dependsOn: ["t_1"],
-  resources: ["packages/api/auth"],
-  supersedes: ["old-auth-patch"],
-  verify: "Every scenario in features/gallery.feature holds in the built gallery; no horizontal overflow at 400px."
-})
+`agent start` creates an unassigned resident without a synthetic Work ID or an
+initial model turn. Presence stays `starting` until a one-shot native readiness
+acknowledgement, then becomes `idle` and eligible for exact-session assignment.
+The public start call awaits that bounded acknowledgement before returning, so
+its exact returned session accepts an immediate assignment without a caller wait.
+Rejected readiness, timeout, or early exit fails the start call; a process ID is
+not readiness. Reassigning the same still-claimed Work to its exact current owner
+returns the existing Assignment Attempt without a second delivery. Later claimable-board notices can still wake
+the resident and activate deliberate autonomous claims. Start is not a permanent
+assignment-only scheduling mode.
+
+`work` is activated only in valid assignment/board contexts.
+
+`work` owns Work lifecycle. Leaders create/list/assign/release/reopen completed
+Work/supersede; Workers list/claim/submit/release their current Work.
+
+```ts
+work({ action: "create", subject: "Fix storage", resources: ["firmware/storage"] })
+work({ action: "assign", id: "fix-storage", target: { session: "session:worker-...:spawn-..." } })
+work({ action: "claim" })
+work({ action: "submit", outcome: "success", result: "Verification evidence" })
 ```
 
-`send_message` has one schema everywhere:
+`agent_event` is communication-only. It accepts a message, a recipient or bound
+reply route, and optional `inform`/`request` intent. Work lifecycle authority is
+never inferred from message text.
 
-```text
-send_message({ to, message, status? })
+```ts
+agent_event({ to: "session:reviewer-...:spawn-...", message: "The policy changed", intent: "inform" })
 ```
 
-- Worker report: `to: "leader"`; use optional `status: "completed" | "failed"` for a terminal report. Every accepted leader-bound report — intermediate or terminal — enters Pi's follow-up queue as its own turn, even while the leader is active; Pi processes it when the current run can naturally end. After the first accepted terminal report in a wake-up sequence, later reports are suppressed until a new wake-up; distinct intermediate reports, including identical bodies before terminal status, remain deliverable, and the same content is not suppressed across assignments. For bounded reviewer assignments, put findings, the recommendation, verification evidence, and remaining risks in one concise terminal report. Use earlier reports only for genuinely new blockers, plan-changing facts, or evidence that changes the conclusion; do not send a separate status-only assignment-complete message or repeat unchanged findings. A terminal report ends the current worker turn. After a terminal report, report to the leader again only for a new assignment or decision-useful fact.
-- Harness lifecycle events use a separate `<harness-event>` envelope. A requested `teammate_shutdown` stays in the tool lifecycle row and console mailbox; it does not start a leader follow-up turn. Unexpected stops and actionable harness events may still wake the leader.
-- Peer mail: `to: "<teammate-name>"`; `status` is invalid.
-- Leader steering or direct assignment: `to: "<teammate-name>"`; the synchronous routing result is `steered` only when the active control stream accepts the message, otherwise `queued` while the harness owns delivery on the next wake-up.
-- Peer mail and reports to the leader are written to an inbox or outbox first, so their synchronous routing result is `queued`; none of these labels claims the recipient has read, understood, or processed the message.
-- Teammate health is reported separately as an `[agent] event` such as `@name stalled · silent 5m`; health never appears as a message-routing suffix.
-- The first non-empty line of `message` becomes the console title.
-- Peer traffic never enters the leader model context; inspect it in `/agent-teams` instead.
-
-Only the leader creates tasks. `task_create` adds pending work to the current session's board; it never spawns a teammate. An idle teammate receives a board notice only when it owns no assignment and the task's resources do not overlap another active assignment. A worker that claims a task owns it until `task_submit` completes or releases it; a terminal leader report alone never completes a board task or authorizes more claims. `supersedes` marks obsolete pending/claimed tasks as `superseded`, retargets pending downstream dependencies to the replacement, and permanently removes obsolete work from notices, claims, and completion. A live holder retains its resource lock until it acknowledges cancellation with `task_submit(status="failed")` or stops; a resumed board clears dead holders. With no living teammates, the result explicitly tells the leader to call `teammate_spawn`; with no eligible idle recipient, the task remains pending until the leader creates/opens a compatible assignment. Boards are session-keyed, so a task created in another Pi session is not automatically imported into the current session. A task-level `verify` prompt overrides the claiming agent's frontmatter `verify`. The harness runs it as a fresh one-shot reviewer: explicit `VERDICT: PASS` completes; explicit `VERDICT: FAIL - <reasons>` returns findings to the claimer. A missing verdict is **inconclusive**: the harness requests one verdict-only clarification, then escalates without counting it as a verification failure. Write acceptance criteria a reviewer can check, not shell commands.
-
-## Tools
-
-| Tool / command | Side | Description |
-|---|---|---|
-| `teammate_spawn(name, agent, prompt?, resources?, handoffFrom?)` | Leader | Start one named resident teammate; model/worktree come from agent frontmatter |
-| `teammate_shutdown(name)` | Leader | Stop one teammate and release its claimed work |
-| `send_message(to, message, reopen?, resources?, status?)` | Both | The only messaging primitive; `to: "leader"` is reserved for worker reports |
-| `task_create(subject, description?, dependsOn?, verify?, resources?, supersedes?)` | Leader | Add a resource-scoped shared board task |
-| `task_list()` | Both | One shared board-view definition; leader view also includes the roster |
-| `task_claim(taskId?)` | Worker | Atomically self-claim a pending, unblocked task |
-| `task_submit(taskId, status, result?)` | Worker | Submit a claimed task outcome; completion passes through verify |
-| `/agent-teams` | User | Management console: session teammates, persistent agent roles, board, details, shutdown |
-
-That is **7 unique tool names**. There are no `teammate_run`, `teammate_fanout`, `teammate_cancel`, `teammate_retry`, or `teammate_message` tools.
-
-## Reliability Protocol
+Automatic final answers (including autonomously claimed Work) and explicit Work
+submission use the same attempt-bound acceptance pipeline. Explicit submission
+ends the worker turn without a second automatic submission. Successful results
+reach the Leader once, after execution settles and any verification gate passes.
+Execution failures are reported after settlement without claiming acceptance.
+`work list` includes bounded result evidence for deliberate recovery.
+Verification freezes execution and retains deferred mail as Work history.
+An ordinary final answer is a successful candidate, not independent verification;
+ungated acceptance does not independently verify its claims. If requested work
+cannot be performed, including missing tools, workers must explicitly submit
+`work({ action: "submit", outcome: "failed", result: "Blocker and unverified work" })`.
+Blocker prose is not classified as failure. Failed submission produces one failed
+report, not completion or dependent unlock; a rejecting verification gate also
+prevents acceptance. Leaders should delegate concrete acceptance criteria and an
+explicit verification gate where appropriate. Informational reports need no
+acknowledgment unless a decision or action changes.
+Do not narrate repeated reports. This guidance does not suppress event transport
+or infer lifecycle changes from communication.
+
+After delegation, continue independent work or end the turn: results resume the
+session automatically. Use `agent inspect` for deliberate diagnosis, not repeated
+polling or sleep loops. `agent_event` never creates or retries Work; messaging a
+completed assignment returns its recorded result without waking the worker.
+Recovery reuses the existing Work ID. Request explicit `work release` and await
+authoritative release before `work assign` to the chosen exact session; a queued
+release is not yet released authority. Do not create competing recovery Work via
+`agent delegate`. Read-only/no-write messages are steering, not cancellation or
+proof that the current tool batch stopped. Native steering takes effect at safe
+tool boundaries, before peer follow-up; it cannot undo already executed writes.
+Parked verification requires explicit Work release and reassignment; ordinary
+messages remain deferred. Exact session handles are incarnation-bound, so a stale
+handle cannot stop or inspect a replacement resident. Work persists for later inspection,
+but a different session file does not import another session's tasks automatically.
+
+## Coordination and delivery
+
+Leader guidance uses the same delivery contract before and after a team starts:
+
+- Delegate separable work with a task-scoped baseline, acceptance criteria and safe local checks. Use `work create` with `dependsOn` for prerequisites and shared `resources` tags for conflicting writes; then assign eligible Work. Independent delegation is not a substitute for dependencies.
+- Implementers own assigned local checks. One integration owner checks shared behavior against the integrated candidate. Determine isolation needs before verification; commands running locally may still access user data or production credentials.
+- Record a revision or scoped snapshot for the candidate and exclude unrelated dirty changes. Review and integration checks judge that same candidate; later edits invalidate affected evidence rather than automatically requiring every Agent to rerun every suite.
+- A completed review Work Item can report REWORK. It is not a PASS on the implementation. Review-only work ends with that report, without editing the implementation or waiting for repairs; the implementation owner owns remediation. Implementation delivery stays pending until required Work and blocking reviews have returned, findings are resolved, and applicable evidence matches the final candidate. If only results remain outstanding, yield without announcing completion.
+- Group related findings by root cause. Before a bounded recheck, preserve the prior report outside the result that reopen clears, and prepare the retained baseline, new candidate fingerprint, correction delta, prior findings and safe checks. If the description already references an authoritative current-attempt brief, update that brief before reopening and assigning, then keep it stable. Reopen/assign and the reopen reason do not change the old description or forward prior findings. A fixed conflicting description needs bounded follow-up Work with a refreshed description and `dependsOn` on the completed review. Messages to a closed assignment do not restart it; use a new broad review only when scope or risk changes.
+
+`verify` is an independent reviewer's acceptance prompt, **not a shell command**. It adds a model-based acceptance gate when appropriate; it does not replace tests or make ungated reports independently verified. The contract above is prompt guidance, not a new scheduler, automatic snapshot system, or cross-extension completion lock.
+
+Read [the role reference](references/agent-roles.md#assignment-brief) when preparing an assignment brief.
+
+## Message display
+
+Collapsed `[message]` rows use the current terminal width for their preview and
+reserve the complete configured expansion-key hint. Expanded rows show the full
+message once, inline after the recipient and delivery state, with natural wrapping
+and preserved line breaks. Literal JSON quotes and punctuation spacing remain
+unchanged; message content bypasses prose cleanup. Routing identifiers remain
+model-facing, not transcript copy; real extra notes are separate from the message
+and are not repeated previews.
+The renderer uses the same pi-kit lifecycle abstraction as `[context] researched`;
+only the content model differs: research has a distinct query and answer, while a
+sent message expands its inline text.
 
-- **Per-spawn identity validation**: every leader report must match the teammate's current spawn id; stale callbacks and events cannot affect a replacement with the same name.
-- **Queued means written**: peer `send_message` succeeds only after the recipient inbox write succeeds. The harness still owns delivery into a recipient turn; only an accepted active control-stream steer is labeled `steered`.
-- **One writer per state file**: only the leader process writes runtime and board snapshots (atomic tmp+rename). Workers append leader reports to their outbox, peer mail to recipient inboxes, and task intent via exclusive-create marker files.
-- **One assignment at a time**: direct assignments and board claims are mutually exclusive. A terminal direct report closes that assignment until an explicit `reopen`; a board claim stays open until `task_submit`.
-- **Resource-safe board work**: overlapping path-like resource tags cannot run concurrently. Superseded tasks stay visible for audit but cannot be claimed, completed, or re-noticed.
-- **Completion is gated, not self-reported**: a task completes only after its effective verify gate passes when one exists; no gate means the submission itself completes it. Explicit FAIL twice parks the task with its holder and escalates once. Missing verdict text is inconclusive, gets one clarification, then escalates without incrementing the failure count.
-- **No caps, heartbeat only**: teammates run without turn-count or duration ceilings. The harness heartbeat tracks silence per working teammate and — after 30 minutes without any RPC output (`PI_TEAMMATE_STALL_NOTICE_MS`, 0 disables) — sends the leader one actionable health event per silence episode. The notice is the last automatic action: continuing, steering, shutting down, or respawning a context-carrying successor belongs to the leader alone. Any output or prompt delivery re-arms it. Health events carry diagnostics separately from message routing: silence duration, spawn age, and lifetime token/cost usage. A teammate with zero lifetime model output and no tool running gets flagged much earlier (5 minutes, `PI_TEAMMATE_SILENT_STALL_MS`, 0 disables): an in-flight request stuck on the provider will not recover by steering, so that notice names shutdown plus respawn as the effective remedy.
-- **One-shot board notices**: an idle teammate is told about a claimable task exactly once; declined tasks never re-wake it, and released tasks re-arm. Notices are paced at least five minutes apart per teammate (`PI_TEAMMATE_NOTICE_PACE_MS` overrides in milliseconds).
-- **One end-of-life line per teammate**: the first terminal report of a spawn incarnation renders the finish entry; shutting that incarnation down afterwards adds no second event row. Requested shutdown is process cleanup only, not proof of assignment completion; wait for the worker's terminal status report when possible. After the first accepted terminal report, later reports are suppressed until a new assignment prompt; distinct intermediate reports remain deliverable.
-- **Failure semantics**: an unexpected crash marks the teammate stopped, reports a diagnostic, and releases its claimed tasks.
-
-## State and Sessions
-
-Runtime state lives in `~/.pi/agent/teammate/<sessionKey>/` and dies with the session (`state.json`, report outboxes, peer inboxes, roster). The task board lives in `~/.pi/agent/tasks/<sessionKey>/board.json` and persists for later inspection; nothing auto-deletes it. The board key is derived from the Pi session file (or cwd when no session file exists), so a fresh session with a different session file does not import another session's tasks automatically; resume the same board directory to continue them. Claims held by dead teammates return to pending on reload.
-
-## Structure
+## Install
 
+```bash
+pi install npm:@fradser/pi-agent-teams
 ```
-agent-teams/
-├── index.ts              — package-root extension entry point
-├── references/           — role templates consulted when generating new agents
-├── src/
-│   ├── index.ts          — composition root and session lifecycle
-│   ├── tools.ts          — leader tools and /agent-teams command
-│   ├── worker.ts         — worker tools plus the shared task_list registration
-│   ├── team-machine.ts   — resident lifecycle, mail routing, intents, verify, wake-ups
-│   ├── state.ts          — roster, board, leader inbox state machine
-│   ├── spawner.ts        — resident RPC process spawner (uncapped sequences)
-│   ├── agents.ts         — agent discovery and frontmatter parsing
-│   ├── statefile.ts      — runtime/board/mail IO and marker-file intents
-│   ├── ui.ts             — passive widget and /agent-teams management console
-│   ├── guidance.ts       — static leader and worker protocols
-│   └── follow-up-queue.ts — serialized automatic report delivery
-├── features/             — BDD contract
-└── tests/                — package tests
-```
-
-## License
 
-MIT
+Run `/reload` after installation. `/agent-teams` is the human management
+surface for Presence, Work, diagnostics, and exact-session stop controls.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fradser/pi-agent-teams",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Multi-agent team system for Pi — resident teammates, shared task board, and peer-to-peer messaging",
   "keywords": [
     "pi-package",
@@ -39,6 +39,6 @@
     ]
   },
   "dependencies": {
-    "@fradser/pi-kit": "0.4.2"
+    "@fradser/pi-kit": "0.5.0"
   }
 }

package/references/agent-roles.md

@@ -13,8 +13,14 @@ Frontmatter:
 - `name` — unique id among discovered roles.
 - `description` — the routing contract: when the leader should choose this
   role, phrased as "use when ...". This is the most load-bearing field.
-- `tools` — the minimal set; follows the mutability axis (see below).
-- optional `model`, `verify`, `worktree`.
+- `tools` — the explicit minimal set; follows the mutability axis (see below).
+  Canonical built-ins are `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`,
+  `powershell` (kept in sync with `src/worker-tools.ts`).
+  Omitted tools or `[]` grant only coordination tools (`agent_event`, `work`),
+  not file or shell access. No aliases or implicit default `bash`.
+- optional `model`, `verify`, `worktree`. `verify` is an independent completion-gate
+  reviewer prompt, not a shell command. State the evidence and acceptance criteria
+  the gate should inspect; a concrete local gate is not a second broad project review.
 
 The Markdown body is the role prompt, built from five parts:
 
@@ -23,10 +29,37 @@ The Markdown body is the role prompt, built from five parts:
    observation targets, depending on the judgment axis.
 3. Boundaries — what must never be touched or changed.
 4. Evidence — what every claim or finding must carry.
-5. Terminal report — delivery via `send_message(to="leader", message=...)`;
-   the last message to the leader MUST
-   carry status="completed" (or status="failed"); work without a terminal
-   status counts as unfinished work.
+5. Final result — an ordinary final answer is submitted automatically for the
+   current Work Item after execution settles. A Worker may explicitly use
+   `work({ action: "submit", outcome, result? })`; communication events never
+   carry completion authority.
+
+## Assignment brief
+
+Keep task-specific coordination in the Work description, not a permanently growing role:
+
+- **Scope and baseline** — owned files or resources, originating requirements, and
+  the exact task delta, including untracked files and pre-existing dirty changes to exclude.
+- **Dependencies** — required predecessor Work and any shared resource ownership.
+  Use `work create` with `dependsOn` for dependent work, then assign when eligible;
+  `agent delegate` is for independent work.
+- **Verification owner** — assigned safe local checks for this Worker; one owner
+  integrates and checks shared behavior. Determine isolation needs before commands run.
+- **Candidate and result** — identify the revision or scoped snapshot checked, commands
+  and outcomes, findings and limitations. Reviewer output keeps Standards and Spec
+  verdicts separate when both apply; REWORK is a valid completed review, not acceptance
+  of the implementation. Review-only assignments finish with that report, without
+  editing the implementation or waiting for repairs. Missing access or tools is failed
+  execution, not REWORK evidence.
+- **Recheck handoff** — preserve the prior report outside the Work result before reopen
+  clears it. A reusable description should point to an authoritative brief for the current
+  attempt: refresh its candidate fingerprint, correction delta, baseline, findings and safe
+  checks before reopening/assignment, then keep it stable. A fixed conflicting description
+  requires bounded follow-up Work with the refreshed description and `dependsOn` on the
+  completed review. Reopen/assign and the reopen reason do not update the old description.
+
+Leader delivery and pending-review rules are injected by the shared Leader guidance;
+these brief fields make those rules actionable without redefining Work lifecycle here.
 
 ## Archetype axes
 
@@ -55,12 +88,18 @@ as long as every invariant below holds.
 Non-negotiable in every generated definition:
 
 - Tool sets match the mutability axis: read-only roles never receive
-  `edit` or `write`.
+  `edit` or `write`. A `bash` grant is not read-only — a shell can still write,
+  so "read-only" here bounds the tools, not the file system, and the completion
+  gate relies on the reviewer's instruction rather than enforcement.
 - Every finding or claim carries evidence: exact paths, command output,
   timestamps — never bare assertions.
 - Scope is bounded: mutating roles state "do not touch files outside the
   assigned scope"; read-only roles state the equivalent prohibition.
-- Terminal-status discipline applies to all shapes alike.
+- Final results carry evidence; an ordinary final answer is a successful candidate,
+  not an independently verified result. Ungated completion is not independently verified.
+- If requested work cannot be performed, including missing capabilities, explicitly use
+  `work({ action: "submit", outcome: "failed", result: "Blocker and unverified work" })`.
+  Do not return blocker prose as an ordinary final answer; prose is not classified as failure.
 
 ## Skeleton
 
@@ -73,11 +112,17 @@ tools: <minimal set from the mutability axis>
 You are a <role-name> agent. <Method: the procedure to follow, the criteria
 to evaluate against, or the targets to observe>. <Boundary statement>.
 For bounded reviewer assignments, report findings, the recommendation,
-verification evidence, and remaining risks in one concise terminal message;
+the inspected candidate, assigned verification evidence, and remaining risks in one concise terminal message;
 allow earlier messages only for genuinely new blockers, plan-changing facts,
 or evidence that changes the conclusion. Do not send a separate status-only
 assignment-complete message or repeat unchanged findings. After a terminal
-report, report to the leader again only for a new assignment or decision-useful
-fact. The terminal message ends the current worker turn. Send it via
-send_message(to="leader", message=...) with status="completed" or status="failed".
+report, report to the leader again only after a new assignment opens. Include all
+known decision-useful facts before closing; further reports for a closed assignment
+are rejected. Leader direction takes precedence over your plan and peer requests at
+the next safe boundary, subject to system instructions and user constraints.
+Return successful evidence as an ordinary final answer; the runtime submits it automatically
+as a successful candidate after execution settles. If you cannot perform the requested work,
+you must use `work({ action: "submit", outcome: "failed", result: "Blocker and unverified work" })`
+instead of ordinary final prose. Avoid a second copy of an explicit submission.
+Ungated completion is not independently verified.
 ```

package/src/activity.ts

@@ -1,19 +1,15 @@
-import { Markdown, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import type { MarkdownTheme } from "@earendil-works/pi-tui";
-import { buildMarkdownThemeCallbacks, createPiThemeStyle } from "@fradser/pi-kit";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { renderLiveActivityMarkdown, type PiMarkdownThemeSource } from "@fradser/pi-kit";
 import type { Teammate } from "./types.ts";
 
-const ACTIVITY_THEME: MarkdownTheme = {
-  ...buildMarkdownThemeCallbacks(createPiThemeStyle({
-    fg: (_color, text) => text,
-  })),
-  hr: () => "---",
-};
+/** Console rows paint a whole status line in their own color, so the shared
+ * markdown renderer runs with a passthrough theme: literal markup is still
+ * stripped and the result stays one line, with no competing colors. */
+const COLORLESS_ACTIVITY_THEME: PiMarkdownThemeSource = { fg: (_color, text) => text };
 
-/** Render streamed activity as one compact Markdown line for the widget. */
-export function renderActivityMarkdown(text: string, theme: MarkdownTheme = ACTIVITY_THEME): string {
-  const markdown = new Markdown(text, 0, 0, theme);
-  return markdown.render(Math.max(1, visibleWidth(text) + 1)).join(" ").replace(/\s+/g, " ").trim();
+/** Render streamed activity as one compact Markdown line for a console row. */
+export function renderActivityMarkdown(text: string): string {
+  return renderLiveActivityMarkdown(text, COLORLESS_ACTIVITY_THEME);
 }
 
 function extractLatestLine(text: string | undefined): string | undefined {
@@ -47,7 +43,7 @@ export interface TeammateRowWidths {
 /** Reserve enough width for the live activity before truncating the identity. */
 export function teammateRowWidths(spinner: string, agent: string, width: number): TeammateRowWidths {
   const lineWidth = Math.max(10, width - 1);
-  const fixedWidth = visibleWidth(` ${spinner}  · `);
+  const fixedWidth = visibleWidth(`${spinner}  · `);
   const availableWidth = Math.max(2, lineWidth - fixedWidth);
   const nameWidth = Math.max(1, Math.min(visibleWidth(agent), Math.floor(availableWidth * 0.4)));
   return {
@@ -57,30 +53,13 @@ export function teammateRowWidths(spinner: string, agent: string, width: number)
   };
 }
 
-/** Fit one widget row to its terminal width while keeping it on one line. */
-export function fitTeammateRow(
-  spinner: string,
-  agent: string,
-  activity: string,
-  width: number,
-  formatActivity: (text: string) => string = (text) => text,
-  markdownTheme: MarkdownTheme = ACTIVITY_THEME,
-): string {
-  const sizes = teammateRowWidths(spinner, agent, width);
-  const nameText = truncateToWidth(agent, sizes.nameWidth);
-  const activityText = formatActivity(truncateToWidth(renderActivityMarkdown(activity, markdownTheme), sizes.activityWidth));
-  const line = ` ${spinner} ${nameText} · ${activityText}`;
-  return truncateToWidth(line, sizes.lineWidth);
-}
-
 /** Fit a console status label to the requested activity width. */
 export function formatTeammateLabel(
   spinner: string,
   activity: string,
   maxActivityWidth?: number,
-  markdownTheme: MarkdownTheme = ACTIVITY_THEME,
 ): string {
-  if (maxActivityWidth === undefined) return `${spinner} ${renderActivityMarkdown(activity, markdownTheme)}`;
+  if (maxActivityWidth === undefined) return `${spinner} ${renderActivityMarkdown(activity)}`;
   if (maxActivityWidth <= 0) return spinner;
-  return `${spinner} ${truncateToWidth(renderActivityMarkdown(activity, markdownTheme), maxActivityWidth)}`;
+  return `${spinner} ${truncateToWidth(renderActivityMarkdown(activity), maxActivityWidth)}`;
 }