@fradser/pi-agent-teams 0.5.3 → 0.7.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,134 @@ 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):
+
+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.
+
+| 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 |
 
-## Dispatch a run in one call
+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_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
 
-| 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: "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:
+
+```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 `/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.
+
+## 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 |
+| `/agent-teams` | User | Management console: session teammates, persistent agent roles, board, 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
+├── references/           — role templates consulted when generating new agents
 ├── 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 /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

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.7.0",
+  "description": "Multi-agent team system for Pi — resident teammates, shared task board, and peer-to-peer messaging",
   "keywords": [
     "pi-package",
     "teammates",
@@ -24,7 +24,7 @@
   "files": [
     "index.ts",
     "src",
-    "agents",
+    "references",
     ".memory",
     "README.md"
   ],
@@ -39,6 +39,6 @@
     ]
   },
   "dependencies": {
-    "@fradser/pi-kit": "0.1.1"
+    "@fradser/pi-kit": "0.3.0"
   }
 }

package/references/agent-roles.md

@@ -0,0 +1,77 @@
+# Agent Role Reference
+
+Abstract reference for generating new agent definitions on demand. This file
+is NOT discoverable and CANNOT be spawned directly. Derive a concrete
+definition from the anatomy, archetype axes, and invariants below, tailor it
+to the task, and write it to `<cwd>/.pi/agents/<name>.md` (git-managed
+project role) or `<name>.local.md` (personal override).
+
+## Definition anatomy
+
+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`.
+
+The Markdown body is the role prompt, built from five parts:
+
+1. Identity — "You are a `<role>` agent."
+2. Method — the procedure to execute, the criteria to judge against, or the
+   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.
+
+## Archetype axes
+
+Pick a position on two axes before writing anything:
+
+| Axis | Values |
+|---|---|
+| Mutability | mutating (`edit`,`write` allowed) · read-only |
+| Judgment | execute a given procedure · evaluate against criteria · apply domain expertise · observe and report |
+
+Read-only plus each judgment value yields the four classical shapes:
+
+| Shape | Typical tools | Body emphasis |
+|---|---|---|
+| executor | `read,bash,edit,write` | implement end to end, then self-verify by running tests or commands; report changes made, verification performed, remaining risks |
+| reviewer | `read,bash` | only confirmed findings, with severity, evidence, exact paths, and a minimal fix recommendation; when nothing is found, say so and list the checks performed |
+| specialist | `read,bash` | deep domain analysis; state assumptions, the evidence used, and the bounds of expertise for this task |
+| observer | `read` | snapshots or readings; summarize observed state and anomalies with timestamps and evidence; change nothing |
+
+These shapes are starting points, not a fixed menu: a generated role may sit
+anywhere on the axes (for example a mutating specialist with a verify gate),
+as long as every invariant below holds.
+
+## Invariants
+
+Non-negotiable in every generated definition:
+
+- Tool sets match the mutability axis: read-only roles never receive
+  `edit` or `write`.
+- 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.
+
+## Skeleton
+
+```markdown
+---
+name: <role-name>
+description: <one-line capability>; use when <routing condition>
+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".
+```

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)}`;
+}