@fradser/pi-agent-teams 0.5.3 → 0.6.0

package/.memory/MEMORY.md

@@ -1,3 +1,5 @@
 # Memory Index
 
-- `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.
+- `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.

package/.memory/node-terminal-followups.md

@@ -1,6 +1,6 @@
 ---
 name: node-terminal-followups
-description: Background Agent Teams runs notify the main session after each non-summary teammate reaches a terminal outcome, including pre-spawn setup failures, then send a separate run summary when all nodes settle
+description: Background Agent Teams runs notify the main session after each non-summary teammate reaches a terminal outcome, with completion shown separately from the agent report and no automatic run summary
 type: project
 ---
 
@@ -13,5 +13,6 @@ The leader needs incremental results while independent teammates are still worki
 - `run-machine.ts` sends one node follow-up for each non-summary node in a background run when it reports `completed`/`failed`, when its child process reaches a terminal outcome, or when pre-spawn setup fails (agent/state-file/worktree setup).
 - `Node.nodeFollowUpSent` prevents duplicate follow-ups when a worker report is followed by process-close finalization; retry clears the marker.
 - The node follow-up uses the worker's full terminal report/body and does not stop remaining teammates.
-- The existing run-settled follow-up remains separate and is sent once after all nodes settle; foreground (`background=false`) runs continue to return their result inline without automatic node follow-ups.
+- Run settlement remains internal to leader state and foreground (`background=false`) runs continue to return their result inline, but background settlement does not enqueue a separate run-summary follow-up.
+- The transport content contains only `<agent-message from="<agent>">` plus the worker's full body. The completion notice is rendered separately as `Teammate @<agent> finished.` and is never embedded in the report content.
 - Worker turn budgets default to 100 assistant turns as a high safety cap; explicit lower budgets remain available for deliberately bounded tasks.

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

@@ -0,0 +1,21 @@
+---
+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
+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.
+
+**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.
+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.
+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]]

package/README.md

@@ -1,12 +1,14 @@
 # Agent Teams Pi Package
 
-Run-centric multi-agent system for Pi — declarative agents, single-call DAG dispatch, bounded child-process nodes, and one-way worker reports to the leader.
+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.
 
 **Display Name**: Agent Teams
 
 ## What This Package Does
 
-Agents are declarative Markdown files (bundled, user, and project scopes). A run is a dependency-aware task graph dispatched in **one call**: root nodes start immediately, concurrency is bounded, overlapping shared-workspace writes are deferred (advisory coordination across all runs in the session) unless worktree-isolated, and downstream nodes auto-start when their dependencies complete. Each node is a bounded child Pi process with per-spawn identity validation.
+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 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
 
@@ -16,96 +18,130 @@ pi install /path/to/pi-packages/packages/agent-teams
 
 Then run `/reload` in Pi.
 
-## Agents are declarative files
+## Agents Are Declarative Files
 
-Agent definitions are Markdown files with frontmatter; the body is the worker's role prompt.
+Agent definitions are Markdown files with frontmatter; the body is the role prompt.
 
 ```markdown
 ---
-name: security-auditor
-description: Read-only security reviewer; use after security-sensitive edits
+name: isolated-security-auditor
+description: Read-only security reviewer in an isolated worktree
 tools: read,bash
-model: provider/model   # optional
+model: provider/model       # optional
+verify: npm test            # optional role-default completion gate
+worktree: true              # optional role-default Git isolation
 ---
 Review the assigned scope for exploitable security problems. Do not edit files.
 ```
 
-Discovery precedence per name: **project `.pi/agents/` > user `~/.pi/agent/agents/` > bundled package `agents/`**. Bundled agents: `worker`, `reviewer`, `specialist`, `observer`. Available agents are dynamically injected into prompt guidance via `before_agent_start`.
+Discovery precedence per name (later overrides earlier):
+
+| Scope | Location | Git semantics |
+|---|---|---|
+| bundled | package `agents/` | shipped with the package |
+| 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 |
+
+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.
 
-## Dispatch a run in one call
+## Build a Team
 
 ```text
-teammate_run({
-  tasks: [
-    { id: "inspect", agent: "reviewer", prompt: "Review the auth middleware", paths: ["packages/api/src"], access: "read" },
-    { id: "fix", agent: "worker", prompt: "Apply the review findings", paths: ["packages/api"], access: "write", dependsOn: ["inspect"] },
-    { id: "verify", agent: "reviewer", prompt: "Verify the fix", paths: ["packages/api"], access: "read", dependsOn: ["fix"] },
-  ],
-  concurrency: 2,
-  worktree: false,
-  background: true
+teammate_spawn({
+  name: "security",
+  agent: "reviewer",
+  prompt: "Review the auth middleware"
 })
+
+teammate_spawn({ name: "backend", agent: "worker" })
 ```
 
-- `access` defaults to `read`; declare `write` explicitly.
-- `dependsOn` edges must form a DAG (duplicate ids, unknown references, and cycles are rejected before any worker starts).
-- `worktree: true` runs every node in its own git worktree and captures each diff for integration review.
-- `background` defaults to `true`: teammates always run in the background — the call returns the run id immediately, the model turn stays free, and each teammate's terminal outcome sends its full deliverable in an immediate follow-up while the remaining teammates continue. A final run-completion follow-up is sent after all nodes settle. The team leader does not sleep or busy-wait while tasks execute. Pass `background=false` to block and gather inline (it detaches after 5 minutes so the turn is never hung).
-- `turnBudget` defaults to a high safety cap of 100 assistant turns; use an explicit lower value only when a task needs tighter bounds. This protects against edge cases without interrupting normal work.
-- `timeoutMs` is a run-level hard cap: when exceeded, the run fails and live workers are terminated.
-- A session-wide cap of 8 worker processes applies in addition to each run's `concurrency` limit.
-- Multi-node runs append a `__summary` node by default (`summarize=false` to skip). Single-task runs stay compact unless `summarize=true`.
-- Completing a node hands its result to pending dependents through the spawned worker prompt. Workers have no peer-message or inbound-reply path.
+- 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.
+- 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.
+- `teammate_shutdown({ name })` stops one teammate and releases its claimed task back to the board.
 
-## Tools
+## 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"],
+  verify: "npm test"
+})
+```
+
+`send_message` has one schema everywhere:
 
-| Tool | Description |
-|---|---|
-| `teammate_run` | Dispatch a dependency-aware task graph in one call |
-| `teammate_cancel` | Cancel a run, or one node (`nodeId`) while the rest continues |
-| `teammate_retry` | Re-run only the failed/cancelled nodes of a settled run |
-| `/teammate` | Full-screen console: run/node status, node detail, worker reports, cancel node |
+```text
+send_message({ to, message, status? })
+```
+
+- Worker report: `to: "leader"`; use optional `status: "completed" | "failed"` for a terminal report.
+- 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.
+- The first non-empty line of `message` becomes the console title.
+- Peer traffic never enters the leader model context; inspect it in `/teammate` 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.
+
+## Tools
 
-Spawned workers receive one additional capability, `teammate_message`, for progress notes and final reports to the team leader.
+| Tool / command | Side | Description |
+|---|---|---|
+| `teammate_spawn(name, agent, prompt?)` | 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 |
+| `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 |
+| `/teammate` | User | Full-screen roster and board console, message/task details, shutdown |
 
-Messaging is deliberately one-way: workers append validated reports to their own outbox, and the leader drains them into one leader inbox. There is no peer mailbox, worker inbox, leader broadcast tool, or worker-to-worker delivery path. Dependency results are delivered through the DAG prompt (`=== UPSTREAM HANDOFF ===`) when the dependent starts.
+That is **7 unique tool names**. There are no `teammate_run`, `teammate_fanout`, `teammate_cancel`, `teammate_retry`, or `teammate_message` tools.
 
-## Reliability protocol
+## Reliability Protocol
 
-- **Per-spawn identity validation**: every worker event must match the node's current spawn id; stale events from an older process cannot affect a newer spawn.
-- **One-way message storage**: worker event ids and per-spawn identities are validated and deduplicated; every accepted report lands in the single leader inbox. No read flags, receipts, peer mailboxes, or leader-to-worker inboxes exist.
-- **One canonical terminal result per node**: built by the harness from node state + captured output after the child closes; a worker's message with status alone is not final delivery.
-- **Advisory write-conflict coordination (session-wide)**: the scheduler never starts a shared-workspace write node while another shared-workspace write node with overlapping paths is running — checked across **all runs in the session**, not just the same run. This is scheduling-level coordination, not isolation.
-- **`access`/`paths` are metadata, not enforcement**: they drive conflict scheduling and prompts; a worker's real capabilities come from its agent definition's `tools` list. A `read` node whose agent has `write`/`bash` tools can still write. Use `worktree: true` or a restricted agent tool list when you need actual isolation.
-- **Failure semantics**: a failed node cancels its not-yet-started transitive dependents and fails the run; other nodes finish. Cancelling a run or node reports the outcome in the tool call itself — it does not fire an extra completion follow-up.
+- **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.
+- **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.
+- **Failure semantics**: an unexpected crash marks the teammate stopped, reports a diagnostic, and releases its claimed tasks.
 
-## State and sessions
+## State and Sessions
 
-State is session-scoped and dies with the session (`~/.pi/agent/teammate/<sessionKey>/`); runs do not survive restarts. `background: true` runs notify via one follow-up; worker messages and node outcomes are recorded in the leader transcript and visible in `/teammate`. Agents, by contrast, live in files and survive across sessions — that is the persistent layer.
+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.
 
 ## Structure
 
 ```
 agent-teams/
-├── index.ts           — package-root extension entry point
-├── package.json       — Pi package manifest
-├── agents/            — bundled agent definitions (worker/reviewer/specialist/observer)
+├── index.ts              — package-root extension entry point
+├── agents/               — bundled declarative agent definitions
 ├── src/
-│   ├── index.ts       — composition root: Pi hooks and session lifecycle
-│   ├── tools.ts       — leader tool and /teammate command registration
-│   ├── run-machine.ts — DAG scheduler, worker lifecycle, persistence, session cap
-│   ├── ui.ts          — passive widget and /teammate console
-│   ├── worker.ts      — worker identity binding and report capability
-│   ├── guidance.ts    — static leader/worker protocol guidance
-│   ├── agents.ts      — declarative agent discovery (frontmatter parsing, scope precedence)
-│   ├── state.ts       — runs/nodes state machine, leader inbox, dirty tracking
-│   ├── spawner.ts     — child Pi worker spawner (JSON-mode, usage accounting)
-│   ├── statefile.ts   — leader snapshot + worker outbox IO
-│   ├── worktree.ts    — git worktree isolation
-│   ├── console-viewport.ts — console viewport math (wrap, scroll clamp, ranges)
-│   └── terminal.ts    — canonical per-node terminal result builder
-├── features/          — BDD contract
-└── tests/             — package E2E tests
+│   ├── index.ts          — composition root and session lifecycle
+│   ├── tools.ts          — leader tools and /teammate 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 /teammate console
+│   ├── guidance.ts       — static leader and worker protocols
+│   └── follow-up-queue.ts — serialized automatic report delivery
+├── features/             — BDD contract
+└── tests/                — package tests
 ```
 
 ## License

package/agents/observer.md

@@ -6,5 +6,5 @@ tools: read
 You are an observer agent. Observe and report on the assigned scope without
 changing anything. Take the required snapshots or readings, summarize what you
 observed, and report notable events or anomalies with timestamps and evidence
-via teammate_message to team-leader with status="completed". You have no edit,
+via send_message(to="leader", message=...) with status="completed". You have no edit,
 write, or command tools.

package/agents/reviewer.md

@@ -6,6 +6,8 @@ tools: read,bash
 You are a reviewer agent. Read the relevant code and tests first, then review
 the assigned scope for correctness, regressions, and security problems. Do not
 edit files. Report only confirmed findings with severity, evidence, exact
-paths, and a minimal fix recommendation via teammate_message to team-leader with
-status="completed". When no issue is confirmed, say so and list the checks
+paths, and a minimal fix recommendation via send_message(to="leader",
+message=...) with status="completed". Your LAST message to the leader MUST
+carry status="completed" (or status="failed"); a review without a terminal
+status is an unfinished review. When no issue is confirmed, say so and list the checks
 you performed.

package/agents/specialist.md

@@ -5,6 +5,6 @@ tools: read,bash
 ---
 You are a specialist agent. Apply deep domain judgment to the assigned scope:
 investigate, analyze, and produce findings or recommendations with evidence via
-teammate_message to team-leader with status="completed". Do not edit files.
+send_message(to="leader", message=...) with status="completed". Do not edit files.
 State your assumptions, the evidence you used, and the bounds of your expertise
 for this task.

package/agents/worker.md

@@ -3,9 +3,9 @@ name: worker
 description: General executor that implements changes and verifies them; use when a task needs code or file modifications, or when no more specific agent fits
 tools: read,bash,edit,write
 ---
-You are a worker agent. Implement the assigned task end to end within the
-declared paths and access scope, then verify your own work by running the
+You are a worker agent. Implement the assigned task end to end within your
+agent tool scope, then verify your own work by running the
 relevant tests or commands. Follow the task's ordered procedure. Report what
 you changed, what you verified, and any risks or follow-up work via
-teammate_message to team-leader with status="completed". Do not touch
+send_message(to="leader", message=...) with status="completed". Do not touch
 files outside the assigned scope.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fradser/pi-agent-teams",
-  "version": "0.5.3",
-  "description": "Multi-agent team system for Pi — DAG orchestration, leader inbox, and one-way worker reports",
+  "version": "0.6.0",
+  "description": "Multi-agent team system for Pi — resident teammates, shared task board, and peer-to-peer messaging",
   "keywords": [
     "pi-package",
     "teammates",
@@ -39,6 +39,6 @@
     ]
   },
   "dependencies": {
-    "@fradser/pi-kit": "0.1.1"
+    "@fradser/pi-kit": "0.2.0"
   }
 }

package/src/activity.ts

@@ -0,0 +1,86 @@
+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 type { Teammate } from "./types.ts";
+
+const ACTIVITY_THEME: MarkdownTheme = {
+  ...buildMarkdownThemeCallbacks(createPiThemeStyle({
+    fg: (_color, text) => text,
+  })),
+  hr: () => "---",
+};
+
+/** 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();
+}
+
+function extractLatestLine(text: string | undefined): string | undefined {
+  if (!text) return undefined;
+  const lines = text.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const trimmed = lines[i].replace(/\s+/g, " ").trim();
+    if (trimmed.length > 0 && !trimmed.startsWith("... [truncated") && !trimmed.startsWith("…[truncated")) {
+      return trimmed;
+    }
+  }
+  return undefined;
+}
+
+/** Extract the current teammate activity without imposing a display width. */
+export function runningTeammateActivity(teammate: Teammate): string {
+  const tool = teammate.activeTool?.replace(/\s+/g, " ").trim();
+  if (tool) return tool;
+
+  return extractLatestLine(teammate.liveThinking)
+    ?? extractLatestLine(teammate.liveText)
+    ?? "Working...";
+}
+
+export interface TeammateRowWidths {
+  lineWidth: number;
+  nameWidth: number;
+  activityWidth: number;
+}
+
+/** 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 availableWidth = Math.max(2, lineWidth - fixedWidth);
+  const nameWidth = Math.max(1, Math.min(visibleWidth(agent), Math.floor(availableWidth * 0.4)));
+  return {
+    lineWidth,
+    nameWidth,
+    activityWidth: Math.max(1, availableWidth - nameWidth),
+  };
+}
+
+/** 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 <= 0) return spinner;
+  return `${spinner} ${truncateToWidth(renderActivityMarkdown(activity, markdownTheme), maxActivityWidth)}`;
+}

package/src/agents.ts

@@ -2,42 +2,58 @@
  * Declarative agent definitions: Markdown files with YAML-style frontmatter.
  *
  * Discovery scopes (later scopes override earlier ones for the same name):
- *   1. bundled  — agents shipped with this package (agents/)
- *   2. user     — ~/.pi/agent/agents/  (respects PI_CODING_AGENT_DIR)
- *   3. project  — <cwd>/.pi/agents/
+ *   1. bundled       — agents shipped with this package (agents/)
+ *   2. user          — ~/.pi/agent/agents/ (respects PI_CODING_AGENT_DIR)
+ *   3. project       — <cwd>/.pi/agents/<name>.md
+ *   4. project-local — <cwd>/.pi/agents/<name>.local.md (personal override)
  *
  * Frontmatter fields:
  *   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)
+ *   worktree    — optional role-default Git worktree isolation (true/false)
  * The Markdown body is the worker's role prompt.
  */
 
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export type AgentScope = "bundled" | "user" | "project" | "project-local";
 
 export interface AgentDefinition {
   name: string;
   description: string;
   tools: string[];
   model?: string;
-  /** The Markdown body, trimmed; used as the worker role prompt. */
+  /** Role-default completion gate; task-level verify overrides this. */
+  verify?: string;
+  /** Whether this role always receives a dedicated Git worktree. */
+  worktree: boolean;
+  /** The Markdown body, trimmed; used as the teammate's role prompt. */
   prompt: string;
-  /** Scope that supplied this definition ("bundled" | "user" | "project"). */
-  scope: "bundled" | "user" | "project";
+  /** Scope that supplied this definition (precedence: project-local > project > user > bundled). */
+  scope: AgentScope;
+  /** 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;
 }
 
 const BUNDLED_AGENTS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "agents");
 
+/** Files named `xxx.local.md` in the project agents directory are personal
+ * overrides: same teammate name as `xxx.md`, project-local scope, never git-
+ * managed by convention. */
+export const LOCAL_DEFINITION_SUFFIX = ".local.md";
+
 function agentsDir(scope: "user" | "project", cwd?: string): string {
   if (scope === "user") {
-    const base = process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
-    return path.join(base, "agents");
+    return path.join(getAgentDir(), "agents");
   }
   return path.join(cwd || process.cwd(), ".pi", "agents");
 }
@@ -66,14 +82,20 @@ function parseFrontmatter(raw: string): { fields: Record<string, string | string
   return { fields, body: match[2].trim() };
 }
 
-function loadDir(scope: "bundled" | "user" | "project", dir: string, agents: Map<string, AgentDefinition>): void {
+function loadDir(baseScope: AgentScope, dir: string, agents: Map<string, AgentDefinition>): void {
   let entries: fs.Dirent[];
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
   } catch {
     return; // A missing agents directory is not an error.
   }
-  for (const entry of entries) {
+  // Dedup by name within the directory: plain .md first so a same-name
+  // xxx.local.md (personal override) overwrites it in the map.
+  const ordered = [...entries].sort((left, right) =>
+    Number(left.name.endsWith(LOCAL_DEFINITION_SUFFIX)) - Number(right.name.endsWith(LOCAL_DEFINITION_SUFFIX))
+    || left.name.localeCompare(right.name),
+  );
+  for (const entry of ordered) {
     if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
     const source = path.join(dir, entry.name);
     let raw: string;
@@ -83,25 +105,35 @@ function loadDir(scope: "bundled" | "user" | "project", dir: string, agents: Map
       continue;
     }
     const { fields, body } = parseFrontmatter(raw);
-    const name = typeof fields.name === "string" ? fields.name : entry.name.replace(/\.md$/, "");
+    const isLocal = baseScope === "project" && entry.name.endsWith(LOCAL_DEFINITION_SUFFIX);
+    const baseName = isLocal
+      ? entry.name.slice(0, -LOCAL_DEFINITION_SUFFIX.length)
+      : entry.name.replace(/\.md$/, "");
+    const name = typeof fields.name === "string" ? fields.name : baseName;
     if (!name || !body) continue;
-    const tools = Array.isArray(fields.tools) ? fields.tools : [];
-    const model = typeof fields.model === "string" && fields.model ? fields.model : undefined;
     agents.set(name, {
       name,
       description: typeof fields.description === "string" ? fields.description : "",
-      tools,
-      model,
+      tools: Array.isArray(fields.tools) ? fields.tools : [],
+      model: typeof fields.model === "string" && fields.model ? fields.model : undefined,
+      verify: typeof fields.verify === "string" && fields.verify ? fields.verify : undefined,
+      worktree: fields.worktree === "true",
       prompt: body,
-      scope,
+      scope: isLocal ? "project-local" : baseScope,
+      gitManaged: scopeIsGitManaged(isLocal ? "project-local" : baseScope),
       source,
     });
   }
 }
 
+/** Only the shared project layer is expected to be git-managed. */
+function scopeIsGitManaged(scope: AgentScope): boolean {
+  return scope === "project";
+}
+
 /**
  * Resolve all agent definitions visible from the given cwd, with later scopes
- * overriding earlier ones per name: project > user > bundled.
+ * overriding earlier ones per name: project-local > project > user > bundled.
  */
 export function discoverAgents(cwd?: string): Map<string, AgentDefinition> {
   const agents = new Map<string, AgentDefinition>();
@@ -126,13 +158,18 @@ export function hasAgent(name: string, cwd?: string): boolean {
  */
 export function formatAgentGuidance(cwd?: string): string {
   const agents = discoverAgents(cwd);
-  if (agents.size === 0) return "(none found in bundled, user, or project scopes)";
+  if (agents.size === 0) return "(none found in bundled, user, project, or project-local scopes)";
   const lines: string[] = [];
   for (const agent of agents.values()) {
-    const model = agent.model ? ` | Model: ${agent.model}` : "";
+    const extras = [
+      agent.model ? `Model: ${agent.model}` : "",
+      agent.verify ? `Verify: ${agent.verify}` : "",
+      agent.worktree ? "Worktree: true" : "",
+      agent.gitManaged ? "git-managed" : "local",
+    ].filter(Boolean);
     lines.push(`- **${agent.name}** (${agent.scope})`);
     if (agent.description) lines.push(`  ${agent.description}`);
-    lines.push(`  Tools: ${agent.tools.join(", ") || "(role defaults)"}${model}`);
+    lines.push(`  Tools: ${agent.tools.join(", ") || "(role defaults)"}${extras.length > 0 ? ` | ${extras.join(" | ")}` : ""}`);
   }
   return lines.join("\n");
 }