@fradser/pi-agent-teams 0.7.0 → 0.8.2

package/.memory/MEMORY.md

@@ -3,3 +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.

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

@@ -1,17 +1,21 @@
 ---
 name: follow-up-queue
-description: Agent Teams serializes automatic teammate reports through Pi's void sendUserMessage API with lifecycle matching, retry backoff, and session invalidation
+description: Agent Teams serializes automatic teammate reports through Pi custom-message follow-ups, including reports arriving while the leader is active
 type: project
 ---
 
 ## Why
 
-Pi's extension `sendUserMessage` API returns `void`; asynchronous preflight failures are routed to the runtime error handler rather than thrown to the caller. Concurrent automatic reports can also race Pi's prompt startup and produce `Agent is already processing a prompt`.
+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.
 
 ## How to apply
 
 - `packages/agent-teams/src/follow-up-queue.ts` owns a FIFO report queue and one active dispatch.
-- A dispatch is matched by its exact prompt in `before_agent_start`, confirmed by `agent_start`, and released only by the corresponding `agent_settled` path. Reports arriving during an active leader run remain queued.
-- A watchdog restores a batch when no `agent_start` occurs; retries use bounded exponential backoff rather than a microtask spin.
-- `reset()` increments a generation and clears timers, so delayed callbacks from an old session cannot deliver to a replacement session.
-- Keep `sendMainSessionFollowUp` as a synchronous enqueue operation; do not call Pi's void API directly from worker completion paths.
+- `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`.

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

@@ -11,10 +11,10 @@ Exploratory / competitive-hypothesis work (multi-hypothesis debugging, three-way
 
 **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. `status` is invalid except for `to="leader"`. The first non-empty message line is the console title.
+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`; steering a silent working teammate returns `stalledMs` so the send_message result warns delivery is uncertain.
-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 stderr to the claimer. The board persists across restarts; runtime state does not.
+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.
 

package/README.md

@@ -6,7 +6,7 @@ Claude-Code-style collaborative agent teams for Pi: named resident teammates, a
 
 ## What This Package Does
 
-The team leader (your Pi session) spawns named teammates 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. The harness—not the leader model—polls for activity: it drains leader reports, routes peer mail, applies task claims and submissions, runs deterministic verify gates, and wakes idle teammates only when work or mail exists.
+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.
 
@@ -27,25 +27,39 @@ Agent definitions are Markdown files with frontmatter; the body is the role prom
 name: isolated-security-auditor
 description: Read-only security reviewer in an isolated worktree
 tools: read,bash
-model: provider/model       # optional
-verify: npm test            # optional role-default completion gate
+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.
 ```
 
-Discovery precedence per name (later overrides earlier):
+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 one on demand: it derives the definition from the task using
-the abstract role reference in `references/agent-roles.md` (definition
-anatomy, archetype axes, invariants), writes the file, and then spawns.
+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.
 
@@ -55,17 +69,20 @@ A teammate definition is just a Markdown file you own. Shared roles live in `.pi
 teammate_spawn({
   name: "security",
   agent: "reviewer",
-  prompt: "Review the auth middleware"
+  prompt: "Review the auth middleware",
+  resources: ["packages/api/auth"]
 })
 
 teammate_spawn({ name: "backend", agent: "worker" })
 ```
 
-- Spawn has exactly three parameters: `name`, `agent`, and optional kickoff `prompt`.
-- Without a kickoff prompt, the teammate idles until messaged or until claimable work appears.
+- 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; its diff is captured at shutdown.
+- 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
@@ -80,7 +97,9 @@ task_create({
   subject: "Fix auth middleware findings",
   description: "Address the confirmed security findings in packages/api/src/auth.ts",
   dependsOn: ["t_1"],
-  verify: "npm test"
+  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."
 })
 ```
 
@@ -90,22 +109,25 @@ task_create({
 send_message({ to, message, status? })
 ```
 
-- Worker report: `to: "leader"`; use optional `status: "completed" | "failed"` for a terminal report.
+- 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>"`; a working recipient gets a control-stream steer, an idle recipient wakes with the message.
+- 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. Idle teammates self-claim pending tasks whose dependencies are met. A task-level `verify` command overrides the claiming agent's frontmatter `verify`; zero exit completes the task, while failure returns stderr to the claimer for fix-and-resubmit.
+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?)` | Leader | Start one named resident teammate; model/worktree come from agent frontmatter |
+| `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, status?)` | Both | The only messaging primitive; `to: "leader"` is reserved for worker reports |
-| `task_create(subject, description?, dependsOn?, verify?)` | Leader | Add a shared board task |
+| `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 |
@@ -116,15 +138,19 @@ That is **7 unique tool names**. There are no `teammate_run`, `teammate_fanout`,
 ## Reliability Protocol
 
 - **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.
-- **Sent means written**: peer `send_message` succeeds only after the recipient inbox write succeeds. The harness owns delivery into a recipient turn.
+- **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.
-- **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.
-- **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 notice 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, and steering a silent teammate warns that delivery is uncertain.
+- **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. Claims held by dead teammates return to pending on reload.
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fradser/pi-agent-teams",
-  "version": "0.7.0",
+  "version": "0.8.2",
   "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.3.0"
+    "@fradser/pi-kit": "0.4.2"
   }
 }

package/references/agent-roles.md

@@ -72,6 +72,12 @@ 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>.
-Report <expected artifacts> with <evidence requirements> via
-send_message(to="leader", message=...) with status="completed".
+For bounded reviewer assignments, report findings, the recommendation,
+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".
 ```

package/src/agents.ts

@@ -13,8 +13,10 @@
  *   name        — unique agent id (required)
  *   description — routing contract: when the leader should choose this agent
  *   tools       — comma-separated list or YAML list of Pi tool ids
- *   model       — optional provider/model pin
- *   verify      — optional role-default completion gate command (zero exit passes)
+ *   model       — optional provider/model pin, or "inherit" for the leader's
+ *                 current model at spawn time
+ *   verify      — optional role-default completion gate: a review prompt a
+ *                 fresh one-shot reviewer answers with VERDICT: PASS/FAIL
  *   worktree    — optional role-default Git worktree isolation (true/false)
  * The Markdown body is the worker's role prompt.
  */
@@ -24,7 +26,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
-export type AgentScope = "user" | "project" | "project-local";
+export type AgentScope = "user" | "project" | "project-local" | "session";
 
 export interface AgentDefinition {
   name: string;
@@ -42,8 +44,97 @@ export interface AgentDefinition {
   /** True only for the shared project scope that is expected to be git-managed.
    * user and project-local definitions are machine/personal by definition. */
   gitManaged: boolean;
-  /** Absolute path of the definition file. */
-  source: string;
+  /** Absolute path of the definition file; absent for session-only roles. */
+  source?: string;
+}
+
+export interface AgentDefinitionInput {
+  name: string;
+  description: string;
+  tools: string[];
+  model?: string;
+  verify?: string;
+  worktree?: boolean;
+  prompt: string;
+}
+
+/** Reserved model value meaning "use the leader session's current model",
+ *  resolved at spawn time (Claude-Code-style inherit). */
+export const MODEL_INHERIT_ALIAS = "inherit";
+
+const sessionAgents = new Map<string, AgentDefinition>();
+const AGENT_NAME_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/i;
+
+function normalizeAgentInput(input: AgentDefinitionInput): AgentDefinitionInput {
+  const name = input.name.trim();
+  if (!AGENT_NAME_PATTERN.test(name)) {
+    throw new Error(`Invalid agent name "${name}". Use letters, digits, dots, dashes, underscores.`);
+  }
+  const prompt = input.prompt.trim();
+  if (!prompt) throw new Error(`Agent "${name}" prompt must not be empty.`);
+  return {
+    ...input,
+    name,
+    description: input.description.trim(),
+    tools: input.tools.map((tool) => tool.trim()).filter(Boolean),
+    model: input.model?.trim() || undefined,
+    verify: input.verify?.trim() || undefined,
+    worktree: input.worktree ?? false,
+    prompt,
+  };
+}
+
+/** Register a generated role for this session without writing a definition file. */
+export function registerSessionAgent(input: AgentDefinitionInput): AgentDefinition {
+  const normalized = normalizeAgentInput(input);
+  const definition: AgentDefinition = {
+    ...normalized,
+    worktree: normalized.worktree ?? false,
+    scope: "session",
+    gitManaged: false,
+    source: undefined,
+  };
+  sessionAgents.set(definition.name, definition);
+  return definition;
+}
+
+/** Persist a generated role only when the user explicitly requests it. */
+export function persistAgentDefinition(
+  input: AgentDefinitionInput,
+  scope: "project" | "project-local",
+  cwd = process.cwd(),
+): AgentDefinition {
+  const normalized = normalizeAgentInput(input);
+  const directory = agentsDir("project", cwd);
+  fs.mkdirSync(directory, { recursive: true });
+  const filename = `${normalized.name}${scope === "project-local" ? LOCAL_DEFINITION_SUFFIX : ".md"}`;
+  const source = path.join(directory, filename);
+  const frontmatter = [
+    "---",
+    `name: ${normalized.name}`,
+    `description: ${normalized.description.replace(/[\\r\\n]+/g, " ")}`,
+    `tools: ${normalized.tools.join(", ")}`,
+    ...(normalized.model ? [`model: ${normalized.model}`] : []),
+    ...(normalized.verify ? [`verify: ${normalized.verify.replace(/[\\r\\n]+/g, " ")}`] : []),
+    `worktree: ${normalized.worktree ? "true" : "false"}`,
+    "---",
+    normalized.prompt,
+    "",
+  ].join("\n");
+  fs.writeFileSync(source, frontmatter, { encoding: "utf8", mode: 0o600 });
+  sessionAgents.delete(normalized.name);
+  return {
+    ...normalized,
+    worktree: normalized.worktree ?? false,
+    scope,
+    gitManaged: scope === "project",
+    source,
+  };
+}
+
+/** Drop generated session roles; persistent user/project definitions remain discoverable. */
+export function clearSessionAgents(): void {
+  sessionAgents.clear();
 }
 
 /** Shipped role templates: reference material for generating new definitions
@@ -172,6 +263,9 @@ export function discoverAgents(cwd?: string): Map<string, AgentDefinition> {
   const agents = new Map<string, AgentDefinition>();
   loadDir("user", agentsDir("user", cwd), agents);
   loadDir("project", agentsDir("project", cwd), agents);
+  // Generated roles fill gaps only: filesystem scopes keep precedence over
+  // session memory.
+  for (const [name, definition] of sessionAgents) if (!agents.has(name)) agents.set(name, definition);
   return agents;
 }
 
@@ -197,7 +291,7 @@ export function formatAgentGuidance(cwd?: string): string {
       agent.model ? `Model: ${agent.model}` : "",
       agent.verify ? `Verify: ${agent.verify}` : "",
       agent.worktree ? "Worktree: true" : "",
-      agent.gitManaged ? "git-managed" : "local",
+      agent.scope === "session" ? "in-memory" : agent.gitManaged ? "git-managed" : "local",
     ].filter(Boolean);
     lines.push(`- **${agent.name}** (${agent.scope})`);
     if (agent.description) lines.push(`  ${agent.description}`);

package/src/follow-up-queue.ts

@@ -1,12 +1,30 @@
 export const TEAMMATE_REPORT_MESSAGE_TYPE = "agent-teams-report";
+export const TEAMMATE_HARNESS_MESSAGE_TYPE = "agent-teams-harness";
 
 export interface FollowUpReport {
   teammate?: string;
   agent?: string;
   spawnId?: string;
   body: string;
+  /** Worker-authored reports are the default; harness events use a separate envelope. */
+  origin?: "teammate" | "harness";
+  harnessEvent?: {
+    type: string;
+    subject: string;
+  };
   finished?: boolean;
+  /** Original append-only outbox event identifier, retained for session forensics. */
+  eventId?: string;
+  /** Original worker status, including omitted status, retained for session forensics. */
+  status?: "in_progress" | "completed" | "failed";
+  health?: {
+    state: "stalled";
+    silenceMs: number;
+  };
   runId?: string;
+  /** Wall-clock time the message was authored; rendered in the envelope so a
+   *  report delivered after a busy period keeps its original timestamp. */
+  timestamp?: number;
 }
 
 export interface FollowUpReportGroup {
@@ -18,20 +36,25 @@ export function groupReportsByTeammate(reports: FollowUpReport[]): FollowUpRepor
   const groups = new Map<string, FollowUpReportGroup>();
   for (const report of reports) {
     const teammate = report.teammate ?? report.agent ?? "teammate";
-    const group = groups.get(teammate);
+    if (report.health) {
+      groups.set(`health:${groups.size}:${teammate}`, { teammate, reports: [report] });
+      continue;
+    }
+    if (report.origin === "harness" || report.harnessEvent) {
+      groups.set(`harness:${groups.size}:${teammate}`, { teammate, reports: [report] });
+      continue;
+    }
+    const key = `message:${teammate}`;
+    const group = groups.get(key);
     if (group) {
       group.reports.push(report);
     } else {
-      groups.set(teammate, { teammate, reports: [report] });
+      groups.set(key, { teammate, reports: [report] });
     }
   }
   return [...groups.values()];
 }
 
-export function splitReportsByTeammate(reports: FollowUpReport[]): FollowUpReport[][] {
-  return groupReportsByTeammate(reports).map((group) => group.reports);
-}
-
 export interface FollowUpQueueOptions {
   isIdle: () => boolean;
   dispatch: (reports: FollowUpReport[], content: string) => void;
@@ -59,11 +82,13 @@ interface PendingDispatch {
 }
 
 /**
- * Serializes automatic reports sent through Pi's void sendUserMessage API.
+ * Serializes automatic reports sent through Pi's void sendMessage API.
  *
  * The API reports asynchronous preflight failures through the runtime error
  * channel, so this queue uses agent lifecycle events for success and a bounded
- * watchdog for attempts that never reach agent_start.
+ * watchdog for attempts that never reach agent_start. A report arriving during
+ * an active leader run is dispatched to Pi's native follow-up queue; this
+ * queue still serializes later reports until that run settles.
  */
 export class FollowUpQueue {
   private readonly isIdle: FollowUpQueueOptions["isIdle"];
@@ -81,6 +106,10 @@ export class FollowUpQueue {
   private watchdogTimer: ReturnType<typeof setTimeout> | undefined;
   private generation = 0;
   private deadLetter: FollowUpReport[] = [];
+  /** Reports suppressed after their teammate was intentionally stopped. They
+   * remain inspectable in runtime diagnostics but never begin a leader turn. */
+  private archived: FollowUpReport[] = [];
+  private archivedSpawnIds = new Set<string>();
 
   constructor(options: FollowUpQueueOptions) {
     this.isIdle = options.isIdle;
@@ -94,10 +123,31 @@ export class FollowUpQueue {
   }
 
   enqueue(report: FollowUpReport): void {
+    if (report.spawnId && this.archivedSpawnIds.has(report.spawnId)) {
+      this.archived.push(report);
+      return;
+    }
     this.pending.push({ reports: [report], attempts: 0, retrying: false });
     this.schedulePump();
   }
 
+  /** Archive pending reports from one stopped spawn before they can wake the leader.
+   * A dispatch already accepted by Pi cannot be retracted, so it is deliberately
+   * left alone; this method only changes transitions the harness still owns. */
+  archiveSpawn(spawnId: string): FollowUpReport[] {
+    this.archivedSpawnIds.add(spawnId);
+    const moved: FollowUpReport[] = [];
+    for (const batch of this.pending) {
+      const retained = batch.reports.filter((report) => report.spawnId !== spawnId);
+      const archived = batch.reports.filter((report) => report.spawnId === spawnId);
+      this.archived.push(...archived);
+      moved.push(...archived);
+      batch.reports = retained;
+    }
+    this.pending = this.pending.filter((batch) => batch.reports.length > 0);
+    return moved;
+  }
+
   /** Match the active dispatch to the prompt that Pi is about to start. */
   onBeforeAgentStart(prompt: string): void {
     if (!this.active || this.active.prepared || prompt !== this.active.content) return;
@@ -123,6 +173,8 @@ export class FollowUpQueue {
     this.generation++;
     this.pending = [];
     this.deadLetter = [];
+    this.archived = [];
+    this.archivedSpawnIds.clear();
     this.active = undefined;
     this.pumpScheduled = false;
     this.clearRetryTimer();
@@ -138,6 +190,14 @@ export class FollowUpQueue {
     return this.deadLetter.length;
   }
 
+  get archivedCount(): number {
+    return this.archived.length;
+  }
+
+  archivedReportsFor(spawnId: string): FollowUpReport[] {
+    return this.archived.filter((report) => report.spawnId === spawnId);
+  }
+
   private schedulePump(): void {
     if (this.pumpScheduled) return;
     this.pumpScheduled = true;
@@ -150,19 +210,13 @@ export class FollowUpQueue {
   }
 
   private pump(): void {
-    if (this.active || this.retryTimer || this.pending.length === 0 || !this.isIdle()) return;
+    if (this.active || this.retryTimer || this.pending.length === 0) return;
     const first = this.pending.shift();
     if (!first) return;
-    const batches = first.retrying ? [first] : [first, ...this.pending.splice(0)];
-    const allReports = batches.flatMap((batch) => batch.reports);
-    const groups = groupReportsByTeammate(allReports);
-    const reports = groups[0]?.reports ?? [];
-    const remainingGroups = groups.slice(1).map((group) => ({
-      reports: group.reports,
-      attempts: 0,
-      retrying: false,
-    }));
-    if (remainingGroups.length > 0) this.pending.unshift(...remainingGroups);
+    // One report per dispatch: every teammate-authored message becomes its own
+    // leader turn, in arrival order. Coalescing would blur when each message
+    // was sent and what the leader was expected to do about each one.
+    const reports = first.reports;
     const content = formatReports(reports);
     const queuedIntoActiveRun = !this.isIdle();
     this.active = {
@@ -226,9 +280,18 @@ export class FollowUpQueue {
 
 export function formatReports(reports: FollowUpReport[]): string {
   return reports
-    .map(({ teammate, body }) => {
+    .map((report) => {
+      const { teammate, body, timestamp, origin, harnessEvent } = report;
+      const at = timestamp !== undefined && Number.isFinite(timestamp)
+        ? ` at="${new Date(timestamp).toISOString()}"`
+        : "";
+      if (origin === "harness" || harnessEvent) {
+        const type = escapeAttribute(harnessEvent?.type ?? "event");
+        const subject = escapeAttribute(harnessEvent?.subject ?? "Agent Teams event");
+        return `<harness-event type="${type}" subject="${subject}"${at}>\n${body}\n</harness-event>`;
+      }
       const name = teammate ?? "teammate";
-      return `<agent-message from="${escapeAttribute(name)}">\n${body}\n</agent-message>`;
+      return `<agent-message from="${escapeAttribute(name)}"${at}>\n${body}\n</agent-message>`;
     })
     .join("\n\n");
 }