@fradser/pi-agent-teams 0.6.0 → 0.7.0

package/README.md

@@ -36,9 +36,13 @@ Review the assigned scope for exploitable security problems. Do not edit files.
 
 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 |
 |---|---|---|
-| 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 |
@@ -90,7 +94,7 @@ send_message({ to, message, status? })
 - 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.
+- 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.
 
@@ -105,7 +109,7 @@ Only the leader creates tasks. Idle teammates self-claim pending tasks whose dep
 | `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 |
+| `/agent-teams` | User | Management console: session teammates, persistent agent roles, board, details, shutdown |
 
 That is **7 unique tool names**. There are no `teammate_run`, `teammate_fanout`, `teammate_cancel`, `teammate_retry`, or `teammate_message` tools.
 
@@ -127,17 +131,17 @@ Runtime state lives in `~/.pi/agent/teammate/<sessionKey>/` and dies with the se
 ```
 agent-teams/
 ├── index.ts              — package-root extension entry point
-├── agents/               — bundled declarative agent definitions
+├── references/           — role templates consulted when generating new agents
 ├── src/
 │   ├── index.ts          — composition root and session lifecycle
-│   ├── tools.ts          — leader tools and /teammate command
+│   ├── 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 /teammate console
+│   ├── 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

package/package.json

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

@@ -2,10 +2,12 @@
  * 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/<name>.md
- *   4. project-local — <cwd>/.pi/agents/<name>.local.md (personal override)
+ *   1. user          — ~/.pi/agent/agents/ (respects PI_CODING_AGENT_DIR)
+ *   2. project       — <cwd>/.pi/agents/<name>.md
+ *   3. project-local — <cwd>/.pi/agents/<name>.local.md (personal override)
+ *
+ * There are no built-in roles: references/agent-roles.md ships template
+ * shapes that the leader consults when generating a new definition on demand.
  *
  * Frontmatter fields:
  *   name        — unique agent id (required)
@@ -22,7 +24,7 @@ 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 type AgentScope = "user" | "project" | "project-local";
 
 export interface AgentDefinition {
   name: string;
@@ -44,7 +46,11 @@ export interface AgentDefinition {
   source: string;
 }
 
-const BUNDLED_AGENTS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "agents");
+/** Shipped role templates: reference material for generating new definitions
+ * on demand — never discovered and never spawnable directly. */
+export const AGENT_REFERENCE_PATH = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)), "..", "references", "agent-roles.md",
+);
 
 /** Files named `xxx.local.md` in the project agents directory are personal
  * overrides: same teammate name as `xxx.md`, project-local scope, never git-
@@ -62,13 +68,40 @@ function parseFrontmatter(raw: string): { fields: Record<string, string | string
   const fields: Record<string, string | string[]> = {};
   const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
   if (!match) return { fields, body: raw.trim() };
-  for (const line of match[1].split("\n")) {
+  const lines = match[1].split("\n");
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
     const separator = line.indexOf(":");
     if (separator <= 0) continue;
     const key = line.slice(0, separator).trim();
     // Strip inline YAML comments (# ...) and surrounding whitespace/quotes.
     let value = line.slice(separator + 1).replace(/\s+#.*$/, "").trim();
     if (key === "tools") {
+      if (value === "") {
+        // YAML block sequence: "- item" lines, flush-left or indented,
+        // possibly interleaved with blank or comment-only lines.
+        const items: string[] = [];
+        index += 1;
+        while (index < lines.length) {
+          const trimmed = lines[index].trim();
+          if (trimmed === "" || trimmed.startsWith("#")) {
+            index += 1;
+            continue;
+          }
+          if (!/^-.+/.test(trimmed)) break;
+          const rawItem = trimmed.replace(/^-\s*/, "");
+          const item = rawItem
+            .replace(/\s+#.*$/, "")
+            .trim()
+            .replace(/^["']|["']$/g, "");
+          // "- # comment" is a comment-only entry, not a tool.
+          if (item && !rawItem.trimStart().startsWith("#")) items.push(item);
+          index += 1;
+        }
+        index -= 1; // The for-loop steps past the last consumed line.
+        fields.tools = items;
+        continue;
+      }
       const tools = value
         .replace(/^\[|\]$/g, "")
         .split(",")
@@ -133,11 +166,10 @@ function scopeIsGitManaged(scope: AgentScope): boolean {
 
 /**
  * Resolve all agent definitions visible from the given cwd, with later scopes
- * overriding earlier ones per name: project-local > project > user > bundled.
+ * overriding earlier ones per name: project-local > project > user.
  */
 export function discoverAgents(cwd?: string): Map<string, AgentDefinition> {
   const agents = new Map<string, AgentDefinition>();
-  loadDir("bundled", BUNDLED_AGENTS_DIR, agents);
   loadDir("user", agentsDir("user", cwd), agents);
   loadDir("project", agentsDir("project", cwd), agents);
   return agents;
@@ -158,7 +190,7 @@ 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, project, or project-local scopes)";
+  if (agents.size === 0) return "(none defined yet — create one on demand from the shipped templates)";
   const lines: string[] = [];
   for (const agent of agents.values()) {
     const extras = [

package/src/follow-up-queue.ts

@@ -3,6 +3,7 @@ export const TEAMMATE_REPORT_MESSAGE_TYPE = "agent-teams-report";
 export interface FollowUpReport {
   teammate?: string;
   agent?: string;
+  spawnId?: string;
   body: string;
   finished?: boolean;
   runId?: string;

package/src/guidance.ts

@@ -1,4 +1,4 @@
-import { formatAgentGuidance } from "./agents.ts";
+import { AGENT_REFERENCE_PATH, formatAgentGuidance } from "./agents.ts";
 
 export const WORKER_GUIDANCE = `
 ## Resident Teammate Protocol
@@ -39,22 +39,31 @@ delegation, synthesis, and the final user-facing answer. Teammates are named
 resident child processes with isolated contexts; they do not see this
 conversation unless you put the needed context in their prompts.
 
-### Agents are declarative files
+### Agents are declarative files, created on demand
 
 Agents live in Markdown files with frontmatter (name, description, tools,
 optional model, optional verify, optional worktree); the body is the role
-prompt. Discovery precedence per name: project-local
-\`<cwd>/.pi/agents/<name>.local.md\` > project
-\`<cwd>/.pi/agents/<name>.md\` > user \`~/.pi/agent/agents\` > bundled package
-agents. Same-name project/project-local pairs deduplicate into one
-definition, with project-local winning; project definitions are git-managed,
-while project-local and user definitions are personal/non-git-managed. Model
-and worktree behavior are role attributes: define a role variant when they
-need to differ.
+prompt. There are no built-in roles. Discovery precedence per name:
+project-local \`<cwd>/.pi/agents/<name>.local.md\` > project
+\`<cwd>/.pi/agents/<name>.md\` > user \`~/.pi/agent/agents\`. Same-name
+project/project-local pairs deduplicate into one definition, with
+project-local winning; project definitions are git-managed, while
+project-local and user definitions are personal/non-git-managed. Model and
+worktree behavior are role attributes: define a role variant when they need
+to differ.
 
 Available agents:
 ${agents}
 
+When an assignment or user request needs an agent whose name has no
+definition yet, create it first: derive it from the shipped abstract role
+reference at \`${AGENT_REFERENCE_PATH}\` — its definition anatomy, archetype
+axes, and invariants (read it before inventing a novel role) — tailor it to
+the task, and write
+the definition to \`<cwd>/.pi/agents/<name>.md\` for a git-managed project
+role or \`<name>.local.md\` for a personal override; discovery picks it up
+immediately and spawning can proceed.
+
 ### Build a team in one step per teammate
 
 Use teammate_spawn(name, agent, optional kickoff prompt) to start a resident
@@ -63,13 +72,18 @@ inbox messages and claimable board tasks, and can message peers directly.
 A session-wide cap of 8 living teammates applies. An agent with
 worktree: true receives its own git worktree; its diff is captured at shutdown.
 
+Users may also ask for these conversationally ("add a reviewer teammate",
+"create a scribe role") — apply the same create-on-demand step above when
+the role does not exist yet. The human-facing management surface is the
+/agent-teams command; never simulate or describe menu flows to the user.
+
 ### Coordinate through one messaging primitive and the board
 
 send_message is the only messaging tool. Address a teammate by name to steer
 it or hand work to it; working teammates receive it immediately and idle
 teammates wake automatically. The reserved recipient name "leader" is only
 for worker reports, not for leader calls. Peer traffic never reaches your
-context — inspect it in /teammate instead.
+context — inspect it in /agent-teams instead.
 
 Create shared work with task_create(subject, description?, dependsOn?,
 verify?). Idle teammates notice claimable work automatically and self-claim;
@@ -85,7 +99,7 @@ working teammate produces no output for a while; that notice is information,
 not a verdict — decide whether to keep waiting, steer again with send_message,
 or teammate_shutdown it. To carry wedged work forward, spawn a successor whose
 prompt composes context from the original kickoff, the teammate's past reports
-(leader mailbox or /teammate detail view), its board claims, and any live
+(leader mailbox or /agent-teams detail view), its board claims, and any live
 transcript tail. The harness never reclaims, restarts, or replaces a teammate
 on its own.
 

package/src/index.ts

@@ -14,7 +14,7 @@ import { resetState } from "./state.ts";
 import { ensureTeamWidget, refreshTeamUI, stopUiTimers } from "./ui.ts";
 import { registerLeaderTools, registerTeamCommand } from "./tools.ts";
 import { registerWorkerCapabilities, workerBinding } from "./worker.ts";
-import { formatAgentMessagePrefix } from "@fradser/pi-kit";
+import { formatAgentMessagePrefix, formatExpandHint } from "@fradser/pi-kit";
 import { FollowUpQueue, groupReportsByTeammate, TEAMMATE_REPORT_MESSAGE_TYPE, type FollowUpReport } from "./follow-up-queue.ts";
 import { Box, Markdown, Text } from "@earendil-works/pi-tui";
 
@@ -23,6 +23,9 @@ const STATE_DIR_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 let leaderPi: ExtensionAPI | undefined;
 let leaderCtx: ExtensionContext | undefined;
 let followUpQueue: FollowUpQueue | undefined;
+// One "Teammate finished" announcement per spawn incarnation; repeated
+// terminal reports from the same resident stay ordinary report rows.
+const announcedFinishKeys = new Set<string>();
 
 const REPORT_COLORS = ["success", "warning", "error", "mdLink"] as const;
 export const TEAMMATE_FINISHED_ENTRY_TYPE = "agent-teams-teammate-finished";
@@ -61,7 +64,7 @@ export default function (pi: ExtensionAPI) {
     }
     if (!expanded) {
       const groups = groupReportsByTeammate(reports);
-      const hint = theme.fg("dim", ` · ${keyHint("app.tools.expand", "to expand")}`);
+      const hint = formatExpandHint(keyHint("app.tools.expand", "to expand"), theme);
       for (const group of groups) {
         const prefix = theme.fg("customMessageLabel", theme.bold(formatAgentMessagePrefix("from", group.reports.length)));
         const name = theme.fg(reportColor(group.teammate), `@${group.teammate}`);
@@ -88,7 +91,7 @@ export default function (pi: ExtensionAPI) {
     if (event.message.role !== "custom" || event.message.customType !== TEAMMATE_REPORT_MESSAGE_TYPE) return;
     const reports = extractReports(event.message.details);
     for (const report of reports) {
-      if (!report.finished) continue;
+      if (!markTeammateFinished(announcedFinishKeys, report)) continue;
       pi.appendEntry(TEAMMATE_FINISHED_ENTRY_TYPE, {
         teammate: report.teammate ?? report.agent,
         agent: report.agent,
@@ -99,6 +102,7 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     resetState();
     followUpQueue?.reset();
+    announcedFinishKeys.clear();
     leaderCtx = ctx;
     followUpQueue = new FollowUpQueue({
       isIdle: () => Boolean(leaderCtx?.isIdle()),
@@ -158,3 +162,21 @@ function extractReports(details: unknown): FollowUpReport[] {
   if (typed && "teammate" in typed) return [typed as FollowUpReport];
   return [];
 }
+
+/**
+ * Announce a finished entry only on the first terminal report of a spawn
+ * incarnation. Reports without a spawn identity key on the session scope so
+ * crash diagnostics always stay visible. Returns true when the caller should
+ * append the finished entry.
+ */
+export function markTeammateFinished(
+  seen: Set<string>,
+  report: Pick<FollowUpReport, "teammate" | "agent" | "spawnId" | "finished">,
+): boolean {
+  if (!report.finished) return false;
+  const name = report.teammate ?? report.agent ?? "teammate";
+  const key = `${name}:${report.spawnId ?? "session"}`;
+  if (seen.has(key)) return false;
+  seen.add(key);
+  return true;
+}

package/src/team-machine.ts

@@ -125,6 +125,8 @@ const pendingShutdowns = new Set<string>();
 const verifyingTasks = new Map<string, { worker: string; spawnId: string }>();
 /** Idle nudges already fired per teammate incarnation (one per transition). */
 const idleNudgesSent = new Set<string>();
+/** Self-finalize requests delivered per teammate incarnation before escalating to the leader. */
+const selfFinalizeAttempts = new Set<string>();
 const pendingDeliveries = new Map<string, InboxMessage[]>();
 const liveWorktrees = new Map<string, ReturnType<typeof createWorktree>>();
 
@@ -163,6 +165,7 @@ export function shutdownTeamMachine(): void {
   pendingShutdowns.clear();
   verifyingTasks.clear();
   idleNudgesSent.clear();
+  selfFinalizeAttempts.clear();
   pendingDeliveries.clear();
 }
 
@@ -408,7 +411,7 @@ function checkStalledTeammates(now = Date.now()): void {
     const silence = stallSilenceMs(teammate, now);
     if (silence === undefined) continue;
     if (silence < STALL_NOTICE_MS || teammate.stallNoticeSentAt !== undefined) continue;
-    const body = `@${teammate.name} has produced no RPC output for ${formatSilenceDuration(silence)}. The child may be blocked in a provider or tool call; steer delivery is uncertain. Decide: keep waiting, steer again, or shut it down (and respawn a successor with context from the original kickoff, its mailbox reports, board claims, and the /teammate detail transcript).`;
+    const body = `@${teammate.name} has produced no RPC output for ${formatSilenceDuration(silence)}. The child may be blocked in a provider or tool call; steer delivery is uncertain. Decide: keep waiting, steer again, or shut it down (and respawn a successor with context from the original kickoff, its mailbox reports, board claims, and the /agent-teams detail transcript).`;
     updateTeammate(teammate.name, { stallNoticeSentAt: now });
     deliverToLeader({ from: "harness", subject: `Possible stall: @${teammate.name}`, body });
     sendUpdate({ teammate: teammate.name, agent: teammate.agent, body, finished: false });
@@ -428,9 +431,24 @@ export function hasUnfinalizedReport(name: string): boolean {
 /** One light reminder per idle transition when work looks unfinished. */
 function nudgeIfUnfinalized(name: string, spawnId: string): void {
   const key = `${name}:${spawnId}`;
-  if (idleNudgesSent.has(key) || !hasUnfinalizedReport(name)) return;
+  // The terminal report may have been written to the outbox file but not yet
+  // drained into the leader mailbox by the next tick; drain before deciding.
+  drainTeammateOutboxes();
+  if (!hasUnfinalizedReport(name)) return;
+  if (!selfFinalizeAttempts.has(key)) {
+    // First miss: give the worker one chance to fix its own bookkeeping
+    // before bothering the leader. The inbox message wakes it on the next tick.
+    selfFinalizeAttempts.add(key);
+    deliverFeedback(
+      name,
+      "Assignment not finalized",
+      'Your latest message to the leader carried no terminal status. Send send_message(to="leader", message=...) now with status="completed" or status="failed" summarizing your final result.',
+    );
+    return;
+  }
+  if (idleNudgesSent.has(key)) return;
   idleNudgesSent.add(key);
-  const reminder = `@${name} is now idle but its last report was not marked status="completed" or "failed". Its conclusions may be stuck in the mailbox — ask it to finalize or inspect the /teammate console.`;
+  const reminder = `@${name} is now idle but its last report was not marked status="completed" or "failed". Its conclusions may be stuck in the mailbox — ask it to finalize or inspect the /agent-teams console.`;
   deliverToLeader({ from: "harness", subject: `Idle without terminal report: @${name}`, body: reminder });
   sendUpdate({ teammate: name, body: reminder, finished: false });
 }
@@ -464,6 +482,8 @@ export async function shutdownTeammate(name: string): Promise<{ ok: true; body:
     pendingShutdowns.delete(name);
     const released = releaseTasksOf(name, "Teammate was shut down.");
     updateTeammate(name, { status: "stopped", activeTool: undefined });
+    idleNudgesSent.delete(`${name}:${teammate.spawnId}`);
+    selfFinalizeAttempts.delete(`${name}:${teammate.spawnId}`);
     publishStateSnapshot();
     notifyChange();
     return { ok: true, body: summarizeShutdown(name, released.length, 0, undefined) };
@@ -493,6 +513,7 @@ async function handleTeammateClose(name: string, spawnId: string, result: Worker
   // A stopped teammate must not keep the poll loop or its queue alive.
   pendingDeliveries.delete(name);
   idleNudgesSent.delete(`${name}:${teammate.spawnId}`);
+  selfFinalizeAttempts.delete(`${name}:${teammate.spawnId}`);
   updateTeammate(name, {
     status: "stopped",
     activeTool: undefined,
@@ -614,6 +635,7 @@ function applyOutboxRecord(teammate: Teammate, record: unknown): boolean {
     sendUpdate({
       teammate: teammate.name,
       agent: teammate.agent,
+      spawnId: teammate.spawnId,
       body: record.body,
       finished: true,
     });

package/src/tools.ts

@@ -1,5 +1,5 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { formatAgentMessagePrefix, formatAgentTaskName, formatToolEventLabel } from "@fradser/pi-kit";
+import { keyHint, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { formatAgentMessagePrefix, formatAgentTaskName, formatExpandHint, formatToolEventLabel, safeDisplayText } from "@fradser/pi-kit";
 import {
   createBoardTask,
   formatSilenceDuration,
@@ -12,13 +12,8 @@ import { listTasks, livingTeammates } from "./state.ts";
 import { LEADER_RECIPIENT, SendMessageParams, TeammateShutdownParams, TeammateSpawnParams, TaskCreateParams } from "./types.ts";
 import { registerTaskListTool } from "./worker.ts";
 import { openTeamConsole, refreshTeamUI } from "./ui.ts";
+import { discoverAgents } from "./agents.ts";
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-function isValidAgentName(name: string): boolean {
-  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) && !name.includes("..") && name !== "con";
-}
 
 function rosterSummary(): string {
   const alive = livingTeammates();
@@ -39,7 +34,7 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
     renderCall: () => new Text("", 0, 0),
     renderResult(result, _options, theme, context) {
       const text = result.content[0]?.type === "text" ? (result.content[0] as { type: string; text: string }).text : "";
-      if ((result as { isError?: boolean }).isError) {
+      if (context.isError) {
         return new Text(theme.fg("error", text.split("\n")[0] || "Failed to spawn teammate."), 0, 0);
       }
       const params = context.args as { name: string; agent: string; prompt?: string };
@@ -71,17 +66,24 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
     parameters: TeammateShutdownParams,
     renderShell: "self",
     renderCall: () => new Text("", 0, 0),
-    renderResult(result, _options, theme, context) {
+    renderResult(result, options, theme, context) {
       const text = result.content[0]?.type === "text" ? (result.content[0] as { type: string; text: string }).text : "";
-      if ((result as { isError?: boolean }).isError) {
+      if (context.isError) {
         return new Text(theme.fg("error", text.split("\n")[0] || "Failed to shut down teammate."), 0, 0);
       }
       const name = String((context.args as { name?: string }).name ?? "");
-      const line = `${theme.fg("toolTitle", theme.bold(formatToolEventLabel("event", `@${name} shut down`).trimEnd()))}`;
-      return {
-        render: (width: number) => [truncateToWidth(line, Math.max(1, width))],
-        invalidate: () => {},
+      const title = theme.fg("toolTitle", theme.bold(formatToolEventLabel("event", `@${name} shut down`, "agent")));
+      const render = (width: number) => {
+        if (width <= 0) return [];
+        if (!options.expanded) {
+          return [truncateToWidth(`${title}${formatExpandHint(keyHint("app.tools.expand", "to expand"), theme)}`, width)];
+        }
+        return [
+          truncateToWidth(title, width),
+          ...text.split("\n").map((line) => truncateToWidth(theme.fg("customMessageText", safeDisplayText(line)), width)),
+        ];
       };
+      return { render, invalidate: () => {} };
     },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const result = await shutdownTeammate(params.name);
@@ -97,10 +99,26 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
     label: "Send Message",
     description: "The only messaging primitive. Address a living teammate by name; working teammates receive a steer immediately and idle teammates wake with the message. status is reserved for worker reports to leader.",
     parameters: SendMessageParams,
-    renderCall(args, theme) {
-      const prefix = theme.fg("toolTitle", theme.bold(formatAgentMessagePrefix("to")));
-      const recipient = theme.fg("accent", `@${String(args.to ?? "")}`);
-      return new Text(`${prefix}${recipient}`, 0, 0);
+    // Canonical lifecycle rows (same as packages/monitor): empty call slot,
+    // ONE delivery row owned by renderResult.
+    renderShell: "self",
+    renderCall: () => new Text("", 0, 0),
+    renderResult(result, _options, theme, context) {
+      const text = result.content[0]?.type === "text" ? (result.content[0] as { type: string; text: string }).text : "";
+      if (context.isError) {
+        return new Text(theme.fg("error", text.split("\n")[0] || "Failed to send message."), 0, 0);
+      }
+      const to = String((context.args as { to?: string }).to ?? "");
+      const details = result.details as { queued?: boolean; stalledMs?: number } | undefined;
+      const suffix = details?.queued ? "queued" : "delivered";
+      let line = `${theme.fg("toolTitle", theme.bold(formatAgentMessagePrefix("to")))}${theme.fg("accent", `@${to}`)}${theme.fg("dim", ` · ${suffix}`)}`;
+      if (!details?.queued && details?.stalledMs !== undefined) {
+        line += theme.fg("dim", ` · stalled ${formatSilenceDuration(details.stalledMs)}`);
+      }
+      return {
+        render: (width: number) => width > 0 ? [truncateToWidth(line, width)] : [],
+        invalidate: () => {},
+      };
     },
     async execute(_toolCallId, params) {
       if (params.to === LEADER_RECIPIENT) throw new Error('The leader cannot send a message to itself.');
@@ -112,7 +130,12 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
       if (!result.queued && result.stalledMs !== undefined) {
         text += `\nWarning: @${params.to} has been stalled with no output for ${formatSilenceDuration(result.stalledMs)} — the control-stream write succeeded, but the teammate may be wedged. Consider teammate_shutdown if it stays silent.`;
       }
-      return { content: [{ type: "text", text }], details: {} };
+      return {
+        content: [{ type: "text", text }],
+        details: result.stalledMs !== undefined && !result.queued
+          ? { queued: result.queued, stalledMs: result.stalledMs }
+          : { queued: result.queued },
+      };
     },
   });
 
@@ -122,6 +145,22 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
     label: "Create Task",
     description: "Create one shared board task. Resident teammates self-claim it when dependencies are met; an optional verify command gates completion.",
     parameters: TaskCreateParams,
+    // Canonical lifecycle rows (same as packages/monitor): empty call slot,
+    // ONE created row owned by renderResult.
+    renderShell: "self",
+    renderCall: () => new Text("", 0, 0),
+    renderResult(result, _options, theme, context) {
+      const text = result.content[0]?.type === "text" ? (result.content[0] as { type: string; text: string }).text : "";
+      if (context.isError) {
+        return new Text(theme.fg("error", text.split("\n")[0] || "Failed to create task."), 0, 0);
+      }
+      const subject = String((context.args as { subject?: string }).subject ?? "");
+      const line = theme.fg("toolTitle", theme.bold(formatToolEventLabel("created", subject, "board")));
+      return {
+        render: (width: number) => width > 0 ? [truncateToWidth(line, width)] : [],
+        invalidate: () => {},
+      };
+    },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const tasks = listTasks();
       if (params.dependsOn?.some((dep) => !tasks.some((task) => task.id === dep))) {
@@ -137,81 +176,23 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
   registerTaskListTool(pi);
 }
 
+function teamStatusSummary(): string {
+  const roles = [...discoverAgents().keys()].map((name) => `@${name}`);
+  const rolesLine = roles.length > 0
+    ? `${roles.length} persistent agent role${roles.length === 1 ? "" : "s"}: ${roles.join(", ")}`
+    : "No agent roles discovered.";
+  return `${rosterSummary()}\n${rolesLine}`;
+}
+
 export function registerTeamCommand(pi: ExtensionAPI): void {
   pi.registerCommand("agent-teams", {
-    description: "Agent Teams menu: console and create agents from session history",
+    description: "Agent Teams management console: session teammates and persistent agent roles",
     handler: async (_args, ctx) => {
-      const choice = await ctx.ui.select("agent-teams", ["console", "project", "local"]);
-      if (!choice) return;
-      if (choice === "console") {
-        publishStateSnapshot();
-        if (ctx.mode !== "tui") { ctx.ui.notify(rosterSummary(), "info"); return; }
-        await openTeamConsole(ctx);
-        refreshTeamUI(ctx);
-        return;
-      }
-      await createAgentFromHistory(ctx, choice === "local");
+      publishStateSnapshot();
+      if (ctx.mode !== "tui") { ctx.ui.notify(teamStatusSummary(), "info"); return; }
+      await openTeamConsole(ctx);
+      refreshTeamUI(ctx);
     },
   });
 }
 
-interface GeneratedAgent { name?: string; description?: string; tools?: string[]; prompt?: string; content?: string; }
-
-function parseGeneratedAgents(raw: string): GeneratedAgent[] {
-  const cleaned = raw.trim().replace(/^```(?:json)?\s*|\s*```$/g, "");
-  const start = cleaned.indexOf("[");
-  const end = cleaned.lastIndexOf("]");
-  if (start < 0 || end <= start) return [];
-  try {
-    const value: unknown = JSON.parse(cleaned.slice(start, end + 1));
-    return Array.isArray(value) ? value.filter((item): item is GeneratedAgent => Boolean(item && typeof item === "object")) : [];
-  } catch { return []; }
-}
-
-function renderAgentDefinition(agent: GeneratedAgent): string {
-  const name = agent.name!.trim();
-  const description = (agent.description || "Agent created from session history").replace(/[\r\n]+/g, " ").trim();
-  const tools = Array.isArray(agent.tools) ? agent.tools.filter((tool) => typeof tool === "string" && tool.trim()).join(", ") : "";
-  return `---\nname: ${name}\ndescription: ${description}${tools ? `\ntools: ${tools}` : ""}\n---\n\n${(agent.prompt || "").trim()}`;
-}
-
-async function createAgentFromHistory(ctx: ExtensionContext, local: boolean): Promise<void> {
-  const branch = ctx.sessionManager?.getBranch?.() ?? [];
-  const history = branch.map((entry: any) => {
-    const text = typeof entry?.text === "string" ? entry.text : typeof entry?.content === "string" ? entry.content : "";
-    return text ? text : Array.isArray(entry?.content) ? entry.content.map((part: any) => part?.text ?? "").join("") : "";
-  }).filter(Boolean).slice(-20).join("\n\n");
-  const generated = await generateAgentPrompt(ctx, history);
-  if (!generated) return;
-  const dir = path.join(ctx.cwd || process.cwd(), ".pi", "agents");
-  fs.mkdirSync(dir, { recursive: true });
-  const definitions = parseGeneratedAgents(generated)
-    .filter((item) => typeof item.name === "string" && (item.content?.trim() || item.prompt?.trim()))
-    .map((item) => ({ name: item.name!.trim(), content: item.content?.trim() || renderAgentDefinition(item) }));
-  if (definitions.length === 0) { ctx.ui.notify("Model returned no usable agent definitions", "error"); return; }
-  let created = 0;
-  for (const definition of definitions) {
-    if (!isValidAgentName(definition.name)) continue;
-    const filename = `${definition.name}${local ? ".local" : ""}.md`;
-    try { fs.writeFileSync(path.join(dir, filename), definition.content, { encoding: "utf8", flag: "wx" }); created++; } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-    }
-  }
-  ctx.ui.notify(`Created ${created} agent definition${created === 1 ? "" : "s"}`, created ? "info" : "warning");
-}
-
-async function generateAgentPrompt(ctx: ExtensionContext, history: string): Promise<string | undefined> {
-  const model = ctx.model;
-  const registry = ctx.modelRegistry;
-  if (!model || !registry?.complete) {
-    ctx.ui.notify("No model available to generate an agent", "error");
-    return undefined;
-  }
-  const response = await registry.complete(model, {
-    systemPrompt: "Design a complementary resident coding agent team from session history. Return a JSON array of 2-4 complementary agent definitions. Each item must have name, description, tools, and prompt fields. Names use letters, digits, dots, dashes, underscores. Return JSON only, with no code fences.",
-    messages: [{ role: "user", content: `Session history:\n${history || "(empty)"}`, timestamp: Date.now() }],
-  }, { maxTokens: 2000, temperature: 0, cacheRetention: "none" });
-  const content = response.content?.filter((part: any) => part.type === "text").map((part: any) => part.text).join("\\n").trim();
-  if (!content) { ctx.ui.notify("Model returned no agent definition", "error"); return undefined; }
-  return content;
-}

package/src/types.ts

@@ -165,7 +165,7 @@ export interface InboxMessage {
 /** Spawn one named resident teammate. */
 export const TeammateSpawnParams = Type.Object({
   name: Type.String({ minLength: 1, description: "Teammate name, unique among living teammates; used for messaging and claiming" }),
-  agent: Type.String({ description: "Agent definition name (bundled, user, or project scope); its frontmatter pins model and optional worktree isolation" }),
+  agent: Type.String({ description: "Agent definition name (from user, project, or project-local scopes); its frontmatter pins model and optional worktree isolation" }),
   prompt: Type.Optional(Type.String({ description: "Optional kickoff prompt delivered as the teammate's first turn; omit to let it wait for messages or board claims" })),
 });
 

package/src/ui.ts

@@ -1,4 +1,5 @@
-/** Passive team widget and interactive full-screen console (roster + board). */
+/** Passive team widget and the /agent-teams management console
+ * (session teammates + persistent agent roles + board). */
 
 import { truncateToWidth, Key, matchesKey } from "@earendil-works/pi-tui";
 import { createPiThemeStyle, PI_SPINNER_FRAMES, PI_SPINNER_INTERVAL_MS } from "@fradser/pi-kit";
@@ -7,6 +8,7 @@ import {
   clampConsoleScroll, consoleScrollRange, maxConsoleBody, scrollConsoleDetail, wrapConsoleDetail,
 } from "./console-viewport.ts";
 import { fitTeammateRow, formatTeammateLabel, runningTeammateActivity } from "./activity.ts";
+import { discoverAgents, resolveAgent, type AgentDefinition } from "./agents.ts";
 import { getState, getTeammate, listTasks, listTeammates, livingTeammates } from "./state.ts";
 import {
   ensureLivePoll,
@@ -36,7 +38,7 @@ function colorFor(name: string): (typeof TEAM_COLORS)[number] {
 }
 
 function ensureSpinner(): void {
-  const working = livingTeammates().some((t) => t.status === "working" || t.status === "starting");
+  const working = livingTeammates().some(isWorking);
   if (working && !spinnerTimer) {
     spinnerTimer = setInterval(() => {
       spinnerFrame = (spinnerFrame + 1) % PI_SPINNER_FRAMES.length;
@@ -72,7 +74,7 @@ export function ensureTeamWidget(ctx?: { ui?: ExtensionUIContext; mode?: string
       placement: "belowEditor",
       render: (width: number) => {
         // Only WORKING teammates appear above the input box; idle and
-        // stopped teammates stay in the /teammate console instead.
+        // stopped teammates stay in the /agent-teams console instead.
         const working = livingTeammates().filter(isWorking);
         if (working.length === 0) return [];
         const lines: string[] = [];
@@ -171,6 +173,11 @@ function indent(text: string): string[] {
   return text.split("\n").map((line) => `  ${line}`);
 }
 
+function displaySource(sourcePath: string): string {
+  const relative = path.relative(process.cwd(), sourcePath);
+  return relative.startsWith("..") ? sourcePath : `./${relative}`;
+}
+
 function buildTeammateDetail(name: string): string[] {
   const teammate = getTeammate(name);
   if (!teammate) return ["(teammate removed from the roster)"];
@@ -231,6 +238,26 @@ function buildTaskDetail(taskId: string): string[] {
   ];
 }
 
+function buildRoleDetail(name: string): string[] {
+  const def = resolveAgent(name);
+  if (!def) return ["(agent definition not found)"];
+  return [
+    `@${def.name} (${def.scope})${def.gitManaged ? " [git-managed]" : " [local]"}`,
+    "",
+    "== role ==",
+    `  Source: ${displaySource(def.source)}`,
+    `  Description: ${def.description || "(none)"}`,
+    `  Tools: ${def.tools.join(", ") || "(role defaults)"}`,
+    `  Model: ${def.model ?? "(session default)"}`,
+    `  Verify: ${def.verify ?? "(none)"}`,
+    `  Worktree: ${def.worktree ? "true" : "false"}`,
+    `  Living instances: ${livingTeammates().filter((teammate) => teammate.agent === def.name).length}`,
+    "",
+    "== role prompt ==",
+    ...indent(cap(def.prompt)),
+  ];
+}
+
 // ── Full-screen console ───────────────────────────────────────────
 
 type ConsolePage = "roster" | "board";
@@ -239,11 +266,30 @@ interface RosterRow {
   key: string;
   kind: "teammate";
 }
+interface RoleRow {
+  key: string;
+  kind: "role";
+}
 interface BoardRow {
   key: string;
   kind: "task";
 }
-type ConsoleRow = RosterRow | BoardRow;
+type ConsoleRow = RosterRow | RoleRow | BoardRow;
+
+/** SGR mouse-wheel events carry a button code; return signed line delta. */
+function wheelDelta(data: string): number | undefined {
+  const match = /^\x1b\[<(\d+);\d+;\d+[Mm]$/.exec(data);
+  if (!match) return undefined;
+  const button = Number.parseInt(match[1], 10);
+  if ((button & 64) === 0) return undefined;
+  const direction = button & 3;
+  if (direction === 0) return -1;
+  if (direction === 1) return 1;
+  return undefined;
+}
+
+/** Chrome lines around the list viewport: border, header, spacer, footer, border. */
+const LIST_CHROME_LINES = 5;
 
 /** Full-screen Team Console — owns input via ctx.ui.custom. Pages: roster /
  * board; each row opens a scrolling detail view. */
@@ -253,16 +299,37 @@ export function openTeamConsole(ctx: { ui: ExtensionUIContext }): Promise<void>
     let mode: "list" | "detail" = "list";
     let selectedRoster = 0;
     let selectedBoard = 0;
-    let detailTitle = "";
+    let listOffset = 0;
+    let detailKind: ConsoleRow["kind"] = "teammate";
+    let detailKey = "";
     let offset = 0;
+    let confirmName: string | undefined;
     let closed = false;
     let renderTimer: ReturnType<typeof setInterval> | undefined;
+
+    // Definitions are reread lazily so mid-session role creation shows up,
+    // but never once per animation frame.
+    let rolesCache: AgentDefinition[] = [];
+    let rolesCacheAt = 0;
+    const ROLES_CACHE_TTL_MS = 2000;
+    const getRoles = (): AgentDefinition[] => {
+      const now = Date.now();
+      if (now - rolesCacheAt > ROLES_CACHE_TTL_MS) {
+        rolesCache = [...discoverAgents().values()].sort((a, b) => a.name.localeCompare(b.name));
+        rolesCacheAt = now;
+      }
+      return rolesCache;
+    };
+
     const requestRender = () => {
       if (!closed) tui.requestRender();
     };
     const startLiveRefresh = () => {
       if (renderTimer) return;
-      renderTimer = setInterval(requestRender, PI_SPINNER_INTERVAL_MS);
+      renderTimer = setInterval(() => {
+        // Redraw only while something can animate (spinner/activity/stall).
+        if (livingTeammates().some(isWorking)) requestRender();
+      }, PI_SPINNER_INTERVAL_MS);
       renderTimer.unref?.();
     };
     const stopLiveRefresh = () => {
@@ -276,8 +343,12 @@ export function openTeamConsole(ctx: { ui: ExtensionUIContext }): Promise<void>
 
     const currentRows = (): ConsoleRow[] =>
       page === "roster"
-        // The console is the full roster: idle and stopped stay visible here.
-        ? listTeammates().map((t) => ({ key: t.name, kind: "teammate" as const }))
+        // The console is the management surface: idle and stopped stay
+        // visible, and persistent agent roles are listed after the session.
+        ? [
+            ...listTeammates().map((t) => ({ key: t.name, kind: "teammate" as const })),
+            ...getRoles().map((def) => ({ key: def.name, kind: "role" as const })),
+          ]
         : listTasks().map((task) => ({ key: task.id, kind: "task" as const }));
 
     const windowLines = (full: string[], width: number): { lines: string[]; range: string } => {
@@ -293,48 +364,109 @@ export function openTeamConsole(ctx: { ui: ExtensionUIContext }): Promise<void>
     const headerLine = (): string => {
       const alive = livingTeammates();
       const tasks = listTasks();
-      return `team  ${alive.length} alive · board ${tasks.filter((task) => task.status === "pending").length}p/${tasks.filter((task) => task.status === "claimed").length}c/${tasks.filter((task) => task.status === "completed").length}d · ${page}`;
+      return `team  ${alive.length} alive · ${alive.filter(isWorking).length} working · ${getRoles().length} roles · board ${tasks.filter((task) => task.status === "pending").length}p/${tasks.filter((task) => task.status === "claimed").length}c/${tasks.filter((task) => task.status === "completed").length}d · ${page}`;
     };
 
-    const renderList = (width: number): string[] => {
+    interface ContentLine {
+      text: string;
+      /** Selectable row index, or -1 for section chrome. */
+      select: number;
+    }
+
+    const teammateRowText = (key: string, selected: boolean): string => {
+      const teammate = getTeammate(key)!;
+      const marker = selected ? style.accent("❯ ") : "  ";
+      const name = theme.bold(theme.fg(colorFor(teammate.name), `@${teammate.name}`));
+      if (isWorking(teammate)) {
+        const prefix = `${marker}${name} `;
+        const width = tui.terminal.columns;
+        const available = Math.max(0, width - prefix.length - PI_SPINNER_FRAMES[spinnerFrame].length - 2);
+        const status = theme.fg("warning", formatTeammateLabel(PI_SPINNER_FRAMES[spinnerFrame], runningTeammateActivity(teammate) + stallSuffix(teammate), available));
+        return `${prefix}${status}`;
+      }
+      if (teammate.status === "idle") {
+        return `${marker}${name} ${style.dim(`○ idle${teammate.currentTaskId ? ` · ${teammate.currentTaskId}` : ""}`)}`;
+      }
+      return `${marker}${name} ${theme.fg("warning", "■ stopped")}`;
+    };
+
+    const roleRowText = (key: string, selected: boolean): string => {
+      const def = getRoles().find((candidate) => candidate.name === key)!;
+      const marker = selected ? style.accent("❯ ") : "  ";
+      const name = theme.bold(theme.fg(colorFor(key), `@${key}`));
+      const live = livingTeammates().filter((teammate) => teammate.agent === key && teammate.status !== "stopped").length;
+      const liveTag = live > 0 ? style.success(`[${live} live]`) : style.dim("[0 live]");
+      return `${marker}${name} ${style.dim(def.scope)} ${style.dim(displaySource(def.source))} ${liveTag}`;
+    };
+
+    const taskRowText = (key: string, selected: boolean): string => {
+      const task = listTasks().find((candidate) => candidate.id === key)!;
+      const marker = selected ? style.accent("❯ ") : "  ";
+      const label = theme.fg(colorFor(key), `[${key}]`);
+      const holder = task.claimedBy ? style.dim(` @${task.claimedBy}`) : "";
+      const statusText = task.status === "completed"
+        ? style.success("✓")
+        : task.status === "claimed"
+          ? theme.fg("warning", "◐ claimed")
+          : style.dim("○ pending");
+      return `${marker}${label} ${statusText} ${theme.fg("customMessageText", task.subject)}${holder}`;
+    };
+
+    const buildContent = (): ContentLine[] => {
       const rows = currentRows();
+      const lines: ContentLine[] = [];
+      if (page === "board") {
+        if (rows.length === 0) {
+          lines.push({ text: style.dim("The task board is empty. Create tasks with task_create."), select: -1 });
+        }
+        rows.forEach((row, index) => lines.push({ text: taskRowText(row.key, index === currentPageSelection(rows.length)), select: index }));
+        return lines;
+      }
+      const teammates = rows.filter((row): row is RosterRow => row.kind === "teammate");
+      const roles = rows.filter((row): row is RoleRow => row.kind === "role");
+      const selection = currentPageSelection(rows.length);
+      lines.push({ text: style.dim("== teammates (this session) =="), select: -1 });
+      if (teammates.length === 0) {
+        lines.push({ text: style.dim("No teammates this session. Ask the model to spawn one."), select: -1 });
+      }
+      teammates.forEach((row, index) => lines.push({ text: teammateRowText(row.key, index === selection), select: index }));
+      lines.push({ text: "", select: -1 });
+      lines.push({ text: style.dim("== agent roles (persistent definitions) =="), select: -1 });
+      if (roles.length === 0) {
+        lines.push({ text: style.dim("No agent definitions discovered."), select: -1 });
+      }
+      roles.forEach((row, index) => lines.push({ text: roleRowText(row.key, teammates.length + index === selection), select: teammates.length + index }));
+      return lines;
+    };
+
+    const listViewport = (): number => Math.max(1, tui.terminal.rows - LIST_CHROME_LINES);
+
+    const renderList = (width: number): string[] => {
       const border = style.border("─".repeat(Math.max(1, width)));
-      const lines = [border, style.accent(truncateToWidth(headerLine(), width)), ""];
-      if (rows.length === 0) {
-        lines.push(style.dim(page === "roster"
-          ? "No living teammates. Spawn one with teammate_spawn."
-          : "The task board is empty. Create tasks with task_create."));
+      const content = buildContent();
+      const viewport = listViewport();
+      const selection = currentPageSelection(currentRows().length);
+      const selectedIndex = content.findIndex((line) => line.select === selection);
+      if (selectedIndex >= 0) {
+        if (selectedIndex < listOffset) listOffset = selectedIndex;
+        else if (selectedIndex >= listOffset + viewport) listOffset = selectedIndex - viewport + 1;
       }
-      rows.forEach((row, index) => {
-        const marker = index === currentPageSelection(rows.length) ? style.accent("❯ ") : "  ";
-        if (row.kind === "teammate") {
-          const teammate = getTeammate(row.key)!;
-          const name = theme.bold(theme.fg(colorFor(teammate.name), `@${teammate.name}`));
-          let status: string;
-          if (teammate.status === "working" || teammate.status === "starting") {
-            const prefix = `${marker}${name} `;
-            const available = Math.max(0, width - prefix.length - PI_SPINNER_FRAMES[spinnerFrame].length - 2);
-            status = theme.fg("warning", formatTeammateLabel(PI_SPINNER_FRAMES[spinnerFrame], runningTeammateActivity(teammate) + stallSuffix(teammate), available));
-          } else if (teammate.status === "idle") {
-            status = style.dim(`○ idle${teammate.currentTaskId ? ` · ${teammate.currentTaskId}` : ""}`);
-          } else {
-            status = theme.fg("warning", "■ stopped");
-          }
-          lines.push(`${marker}${name} ${status}`);
-        } else {
-          const task = listTasks().find((candidate) => candidate.id === row.key)!;
-          const label = theme.fg(colorFor(task.id), `[${task.id}]`);
-          const holder = task.claimedBy ? style.dim(` @${task.claimedBy}`) : "";
-          const statusText = task.status === "completed"
-            ? style.success("✓")
-            : task.status === "claimed"
-              ? theme.fg("warning", "◐ claimed")
-              : style.dim("○ pending");
-          lines.push(truncateToWidth(`${marker}${label} ${statusText} ${theme.fg("customMessageText", task.subject)}${holder}`, Math.max(10, width - 1)));
-        }
-      });
-      lines.push("", style.dim("↑↓ select · enter open · tab page · x shutdown · esc/q close"), border);
-      return lines.map((l) => truncateToWidth(l, Math.max(10, width - 1)));
+      listOffset = clampConsoleScroll(listOffset, content.length, viewport);
+      const footer = confirmName
+        ? theme.fg("warning", `Shut down @${confirmName}? Its claimed task returns to the board · y yes / n no`)
+        : style.dim(page === "roster"
+            ? "↑↓ select · enter open · tab board · x shutdown · esc/q close"
+            : "↑↓ select · enter open · tab roster · esc/q close");
+      return [
+        border,
+        style.accent(truncateToWidth(headerLine(), width)),
+        "",
+        ...content.slice(listOffset, listOffset + viewport)
+          .map((line) => truncateToWidth(line.text, Math.max(10, width - 1))),
+        "",
+        truncateToWidth(footer, Math.max(10, width - 1)),
+        border,
+      ];
     };
 
     const currentPageSelection = (rowCount: number): number => {
@@ -342,6 +474,9 @@ export function openTeamConsole(ctx: { ui: ExtensionUIContext }): Promise<void>
       return rowCount === 0 ? 0 : Math.min(selection, rowCount - 1);
     };
 
+    const detailTitle = (): string =>
+      detailKind === "task" ? `[${detailKey}]` : detailKind === "role" ? `@${detailKey} · role` : `@${detailKey}`;
+
     const renderDetail = (width: number): string[] => {
       const border = style.border("─".repeat(Math.max(1, width)));
       const source = detailSource();
@@ -349,7 +484,7 @@ export function openTeamConsole(ctx: { ui: ExtensionUIContext }): Promise<void>
       const footer = style.dim(`  ${detail.range} · ↑↓ scroll · pgup/pgdn page · home/end jump · esc back · q close`);
       const lines = [
         border,
-        style.accent(truncateToWidth(`agent-teams  ${detailTitle}`, width)),
+        style.accent(truncateToWidth(`agent-teams  ${detailTitle()}`, width)),
         "",
         ...detail.lines.map((line) => `  ${line}`),
         "",
@@ -359,10 +494,11 @@ export function openTeamConsole(ctx: { ui: ExtensionUIContext }): Promise<void>
       return lines.map((line) => truncateToWidth(line, Math.max(10, width - 1)));
     };
 
-    const detailSource = (): string[] =>
-      detailTitle.startsWith("[")
-        ? buildTaskDetail(detailTitle.slice(1, detailTitle.indexOf("]")))
-        : buildTeammateDetail(detailTitle.replace(/^@/, ""));
+    const detailSource = (): string[] => {
+      if (detailKind === "task") return buildTaskDetail(detailKey);
+      if (detailKind === "role") return buildRoleDetail(detailKey);
+      return buildTeammateDetail(detailKey);
+    };
 
     return {
       render: (width) => (mode === "list" ? renderList(width) : renderDetail(width)),
@@ -371,9 +507,22 @@ export function openTeamConsole(ctx: { ui: ExtensionUIContext }): Promise<void>
           handleDetailInput(data);
           return;
         }
+        if (confirmName) {
+          if (data === "y" || data === "Y") {
+            const name = confirmName;
+            confirmName = undefined;
+            void shutdownFromConsole(ctx, name);
+          } else if (data === "n" || data === "N" || matchesKey(data, Key.escape)) {
+            confirmName = undefined;
+          } else if (data === "q" || data === "Q") {
+            closeConsole(done);
+          }
+          return;
+        }
         const rows = currentRows();
         if (matchesKey(data, Key.tab)) {
           page = page === "roster" ? "board" : "roster";
+          listOffset = 0;
           return;
         }
         if (matchesKey(data, Key.down)) bumpSelection(1, rows.length);
@@ -384,20 +533,29 @@ export function openTeamConsole(ctx: { ui: ExtensionUIContext }): Promise<void>
           if (row) {
             mode = "detail";
             offset = 0;
-            detailTitle = row.kind === "teammate" ? `@${row.key}` : `[${row.key}]`;
+            detailKind = row.kind;
+            detailKey = row.key;
           }
           return;
         }
         if (data === "x" || data === "X") {
           const selection = currentPageSelection(rows.length);
           const row = rows[selection];
-          if (page === "roster" && row?.kind === "teammate") void shutdownFromConsole(ctx, row.key);
+          if (page === "roster" && row?.kind === "teammate" && getTeammate(row.key)?.status !== "stopped") {
+            confirmName = row.key;
+          }
           return;
         }
-        if (matchesKey(data, Key.escape) || data === "q" || data === "Q") {
-          closeConsole(done);
+        const wheel = wheelDelta(data);
+        if (wheel !== undefined) {
+          scrollList(wheel * 3);
           return;
         }
+        if (matchesKey(data, Key.pageUp)) scrollList(-listViewport());
+        else if (matchesKey(data, Key.pageDown)) scrollList(listViewport());
+        else if (matchesKey(data, Key.home)) listOffset = 0;
+        else if (matchesKey(data, Key.end)) listOffset = clampConsoleScroll(Number.MAX_SAFE_INTEGER, buildContent().length, listViewport());
+        else if (matchesKey(data, Key.escape) || data === "q" || data === "Q") closeConsole(done);
       },
       invalidate: () => requestRender(),
       dispose: () => {
@@ -418,6 +576,10 @@ export function openTeamConsole(ctx: { ui: ExtensionUIContext }): Promise<void>
       else selectedBoard = clampIndex(selectedBoard + delta, rowCount);
     }
 
+    function scrollList(delta: number): void {
+      listOffset = clampConsoleScroll(listOffset + delta, buildContent().length, listViewport());
+    }
+
     function handleDetailInput(data: string): void {
       const source = detailSource();
       const viewport = maxConsoleBody(tui.terminal.rows);
@@ -431,14 +593,9 @@ export function openTeamConsole(ctx: { ui: ExtensionUIContext }): Promise<void>
         return;
       }
       const total = wrapConsoleDetail(source, tui.terminal.columns).length;
-      const sgrWheel = /^\x1b\[<(\d+);(\d+);(\d+)[Mm]$/.exec(data);
-      if (sgrWheel) {
-        const button = Number.parseInt(sgrWheel[1], 10);
-        if ((button & 64) !== 0) {
-          const direction = button & 3;
-          if (direction === 0) offset = scrollConsoleDetail(offset, -3, total, viewport);
-          else if (direction === 1) offset = scrollConsoleDetail(offset, 3, total, viewport);
-        }
+      const wheel = wheelDelta(data);
+      if (wheel !== undefined) {
+        offset = scrollConsoleDetail(offset, wheel * 3, total, viewport);
         return;
       }
       if (matchesKey(data, Key.up)) offset = scrollConsoleDetail(offset, -1, total, viewport);

package/src/worker.ts

@@ -119,7 +119,9 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): void {
           body: params.message,
           status: params.status,
         });
-        return { content: [{ type: "text", text: "Queued message to leader." }], details: {} };
+        return { content: [{ type: "text", text: params.status
+          ? "Queued message to leader."
+          : 'Queued message to leader. Note: without status="completed" or status="failed" this report does not end your assignment.' }], details: {} };
       }
       if (params.status) throw new Error('status is valid only when to="leader".');
       if (params.to === binding.worker) throw new Error("You are already the recipient — no need to message yourself.");

package/agents/observer.md

@@ -1,10 +0,0 @@
----
-name: observer
-description: Read-only monitor of activity, logs, or processes; use when the task is to observe, watch, or report state rather than change it
-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 send_message(to="leader", message=...) with status="completed". You have no edit,
-write, or command tools.

package/agents/reviewer.md

@@ -1,13 +0,0 @@
----
-name: reviewer
-description: Read-only code or content reviewer; use after implementation or plan changes to check for correctness, regressions, and security
-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 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

@@ -1,10 +0,0 @@
----
-name: specialist
-description: Read-only domain expert for a specific technical area (security, performance, data, platform); use when a task needs deep domain judgment rather than broad implementation
-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
-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

@@ -1,11 +0,0 @@
----
-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 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
-send_message(to="leader", message=...) with status="completed". Do not touch
-files outside the assigned scope.