@fradser/pi-agent-teams 0.6.0 → 0.8.0

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

@@ -14,7 +14,7 @@ Exploratory / competitive-hypothesis work (multi-hypothesis debugging, three-way
 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.
+5. **Board**: only leader writes `~/.pi/agent/tasks/<sessionKey>/board.json`; workers use exclusive-create claim/submission marker files. Task completion uses effective task verify or agent verify; failed verification returns the reviewer's findings to the claimer. The board persists across restarts; runtime state does not.
 6. **Reliability/UI**: per-spawn identity validation, event/message dedup, crash releases claimed tasks, role worktree diff at shutdown. Widget above the input box shows ONLY working/starting teammates as spinner rows with live activity and hides when nobody is working; idle/stopped teammates live only in the /teammate console roster; spawn prints a legacy-style `[agent] started · @name · task` transcript line; `/teammate` offers roster/board pages and message/task detail.
 7. **Node-native TS**: relative imports use explicit `.ts` extensions (root tsconfig permits them), allowing node to strip-types modules in package tests.
 

package/README.md

@@ -6,7 +6,7 @@ Claude-Code-style collaborative agent teams for Pi: named resident teammates, a
 
 ## What This Package Does
 
-The team leader (your Pi session) spawns named teammates as long-lived child Pi processes in RPC mode. Each teammate has an isolated context, a peer inbox, and access to a shared task board. The harness—not the leader model—polls for activity: it drains leader reports, routes peer mail, applies task claims and submissions, runs deterministic verify gates, and wakes idle teammates only when work or mail exists.
+The team leader (your Pi session) spawns named teammates 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, judges verify prompts with fresh one-shot reviewers, and wakes idle teammates only when work or mail exists.
 
 The message surface is deliberately singular: `send_message` is the only messaging primitive. Workers report with `to: "leader"`; teammates address peers by name; the leader addresses teammates by name. The routing implementation varies by destination (outbox, inbox, or control stream), but callers use one schema.
 
@@ -27,21 +27,39 @@ Agent definitions are Markdown files with frontmatter; the body is the role prom
 name: isolated-security-auditor
 description: Read-only security reviewer in an isolated worktree
 tools: read,bash
-model: provider/model       # optional
-verify: npm test            # optional role-default completion gate
+model: provider/model       # optional; "inherit" = the leader's current model at spawn time
+verify: review prompt       # optional role-default gate; a fresh reviewer answers VERDICT: PASS/FAIL
 worktree: true              # optional role-default Git isolation
 ---
 Review the assigned scope for exploitable security problems. Do not edit files.
 ```
 
-Discovery precedence per name (later overrides earlier):
+Teammate model resolution at spawn time, in precedence order: an explicit
+`provider/model` pin wins; `inherit` pins the leader session's current model;
+without a pin, the unified teammate model set from `/agent-teams` (press `m`
+in the roster page for a type-to-filter picker) applies to this session;
+otherwise Pi picks its own default.
+
+Discovery precedence per name (later overrides earlier): user < project <
+project-local, with generated session roles filling only the names no file
+defines. A re-spawn that supplies an explicit inline definition replaces a
+previously generated session role of the same name; definition files are never
+overwritten by inline input.
+
+There are no built-in roles. When a needed role has no definition, the
+leader creates it in memory for the current session: it derives the definition
+from the task using the abstract role reference in `references/agent-roles.md`
+(definition anatomy, archetype axes, invariants), registers it, and then spawns.
+The role is not written to disk or reused in a later session unless the user
+explicitly requests persistence; only then may the leader set `definition.persist`
+and choose a project or project-local scope.
 
 | Scope | Location | Git semantics |
 |---|---|---|
-| 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 |
+| session | in-memory registry | **ephemeral** — disappears at session start, no source file |
 
 A teammate definition is just a Markdown file you own. Shared roles live in `.pi/agents/<name>.md`; a personal tweak to that exact role is `<name>.local.md` in the SAME directory — same teammate name, local scope wins, and discovery deduplicates the pair into one entry (never two). `resolveAgent` reports each definition's `scope` and `gitManaged`; guidance lists both so the leader knows provenance.
 
@@ -76,7 +94,7 @@ 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"
+  verify: "Every scenario in features/gallery.feature holds in the built gallery; no horizontal overflow at 400px."
 })
 ```
 
@@ -90,9 +108,9 @@ 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.
+Only the leader creates tasks. Idle teammates self-claim pending tasks whose dependencies are met. A task-level `verify` prompt overrides the claiming agent's frontmatter `verify`. The harness runs it as a fresh one-shot reviewer that inspects the work independently and answers `VERDICT: PASS` or `VERDICT: FAIL - <reasons>`; PASS completes the task, FAIL feeds the findings back to the claimer for fix-and-resubmit. Write acceptance criteria a reviewer can check, not shell commands.
 
 ## Tools
 
@@ -105,7 +123,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.
 
@@ -114,8 +132,10 @@ That is **7 unique tool names**. There are no `teammate_run`, `teammate_fanout`,
 - **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.
+- **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. A gate that keeps failing parks the task with its holder after the second consecutive failure and escalates to the leader once instead of looping.
 - **No caps, heartbeat only**: teammates run without turn-count or duration ceilings. The harness heartbeat tracks silence per working teammate and — after 30 minutes without any RPC output (`PI_TEAMMATE_STALL_NOTICE_MS`, 0 disables) — sends the leader one actionable notice per silence episode. The notice is the last automatic action: continuing, steering, shutting down, or respawning a context-carrying successor belongs to the leader alone. Any output or prompt delivery re-arms it, and steering a silent teammate warns that delivery is uncertain.
+- **One-shot board notices**: an idle teammate is told about a claimable task exactly once; declined tasks never re-wake it, and released tasks re-arm. Notices are paced at least five minutes apart per teammate (`PI_TEAMMATE_NOTICE_PACE_MS` overrides in milliseconds).
+- **One end-of-life line per teammate**: the first terminal report of a spawn incarnation renders the finish entry; shutting that incarnation down afterwards adds no second event row.
 - **Failure semantics**: an unexpected crash marks the teammate stopped, reports a diagnostic, and releases its claimed tasks.
 
 ## State and Sessions
@@ -127,17 +147,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.8.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.4.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,17 +2,21 @@
  * 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)
  *   description — routing contract: when the leader should choose this agent
  *   tools       — comma-separated list or YAML list of Pi tool ids
- *   model       — optional provider/model pin
- *   verify      — optional role-default completion gate command (zero exit passes)
+ *   model       — optional provider/model pin, or "inherit" for the leader's
+ *                 current model at spawn time
+ *   verify      — optional role-default completion gate: a review prompt a
+ *                 fresh one-shot reviewer answers with VERDICT: PASS/FAIL
  *   worktree    — optional role-default Git worktree isolation (true/false)
  * The Markdown body is the worker's role prompt.
  */
@@ -22,7 +26,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
-export type AgentScope = "bundled" | "user" | "project" | "project-local";
+export type AgentScope = "user" | "project" | "project-local" | "session";
 
 export interface AgentDefinition {
   name: string;
@@ -40,11 +44,104 @@ export interface AgentDefinition {
   /** True only for the shared project scope that is expected to be git-managed.
    * user and project-local definitions are machine/personal by definition. */
   gitManaged: boolean;
-  /** Absolute path of the definition file. */
-  source: string;
+  /** Absolute path of the definition file; absent for session-only roles. */
+  source?: string;
+}
+
+export interface AgentDefinitionInput {
+  name: string;
+  description: string;
+  tools: string[];
+  model?: string;
+  verify?: string;
+  worktree?: boolean;
+  prompt: string;
+}
+
+/** Reserved model value meaning "use the leader session's current model",
+ *  resolved at spawn time (Claude-Code-style inherit). */
+export const MODEL_INHERIT_ALIAS = "inherit";
+
+const sessionAgents = new Map<string, AgentDefinition>();
+const AGENT_NAME_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/i;
+
+function normalizeAgentInput(input: AgentDefinitionInput): AgentDefinitionInput {
+  const name = input.name.trim();
+  if (!AGENT_NAME_PATTERN.test(name)) {
+    throw new Error(`Invalid agent name "${name}". Use letters, digits, dots, dashes, underscores.`);
+  }
+  const prompt = input.prompt.trim();
+  if (!prompt) throw new Error(`Agent "${name}" prompt must not be empty.`);
+  return {
+    ...input,
+    name,
+    description: input.description.trim(),
+    tools: input.tools.map((tool) => tool.trim()).filter(Boolean),
+    model: input.model?.trim() || undefined,
+    verify: input.verify?.trim() || undefined,
+    worktree: input.worktree ?? false,
+    prompt,
+  };
+}
+
+/** Register a generated role for this session without writing a definition file. */
+export function registerSessionAgent(input: AgentDefinitionInput): AgentDefinition {
+  const normalized = normalizeAgentInput(input);
+  const definition: AgentDefinition = {
+    ...normalized,
+    worktree: normalized.worktree ?? false,
+    scope: "session",
+    gitManaged: false,
+    source: undefined,
+  };
+  sessionAgents.set(definition.name, definition);
+  return definition;
+}
+
+/** Persist a generated role only when the user explicitly requests it. */
+export function persistAgentDefinition(
+  input: AgentDefinitionInput,
+  scope: "project" | "project-local",
+  cwd = process.cwd(),
+): AgentDefinition {
+  const normalized = normalizeAgentInput(input);
+  const directory = agentsDir("project", cwd);
+  fs.mkdirSync(directory, { recursive: true });
+  const filename = `${normalized.name}${scope === "project-local" ? LOCAL_DEFINITION_SUFFIX : ".md"}`;
+  const source = path.join(directory, filename);
+  const frontmatter = [
+    "---",
+    `name: ${normalized.name}`,
+    `description: ${normalized.description.replace(/[\\r\\n]+/g, " ")}`,
+    `tools: ${normalized.tools.join(", ")}`,
+    ...(normalized.model ? [`model: ${normalized.model}`] : []),
+    ...(normalized.verify ? [`verify: ${normalized.verify.replace(/[\\r\\n]+/g, " ")}`] : []),
+    `worktree: ${normalized.worktree ? "true" : "false"}`,
+    "---",
+    normalized.prompt,
+    "",
+  ].join("\n");
+  fs.writeFileSync(source, frontmatter, { encoding: "utf8", mode: 0o600 });
+  sessionAgents.delete(normalized.name);
+  return {
+    ...normalized,
+    worktree: normalized.worktree ?? false,
+    scope,
+    gitManaged: scope === "project",
+    source,
+  };
+}
+
+/** Drop generated session roles; persistent user/project definitions remain discoverable. */
+export function clearSessionAgents(): void {
+  sessionAgents.clear();
 }
 
-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 +159,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,13 +257,15 @@ 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);
+  // Generated roles fill gaps only: filesystem scopes keep precedence over
+  // session memory.
+  for (const [name, definition] of sessionAgents) if (!agents.has(name)) agents.set(name, definition);
   return agents;
 }
 
@@ -158,14 +284,14 @@ 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 = [
       agent.model ? `Model: ${agent.model}` : "",
       agent.verify ? `Verify: ${agent.verify}` : "",
       agent.worktree ? "Worktree: true" : "",
-      agent.gitManaged ? "git-managed" : "local",
+      agent.scope === "session" ? "in-memory" : agent.gitManaged ? "git-managed" : "local",
     ].filter(Boolean);
     lines.push(`- **${agent.name}** (${agent.scope})`);
     if (agent.description) lines.push(`  ${agent.description}`);

package/src/follow-up-queue.ts

@@ -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
@@ -21,8 +21,9 @@ you consume nothing.
 - The shared task board is coordination state. Read it with task_list, claim
   pending tasks whose dependencies are met with task_claim (claims are
   atomic; losing a race means try another), and submit outcomes with
-  task_submit. Completion may pass through a verify gate: if it fails, stderr
-  feedback arrives in your inbox — fix and resubmit.
+  task_submit. Completion may pass through a verify gate: a fresh reviewer
+  checks the work independently, and on VERDICT: FAIL its findings arrive in
+  your inbox — fix and resubmit.
 - Coordinate file ownership with peers through send_message before writing.
 
 Do not use leader tools (spawning or shutting down teammates, creating
@@ -39,22 +40,40 @@ 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 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.
+### Agents are declarative files, with ephemeral generated roles by default
+
+Persistent agents live in Markdown files with frontmatter (name, description,
+tools, optional model — a provider/model pin or "inherit" for the leader's
+current model at spawn time — optional verify, optional worktree); the body
+is the role prompt. There are no built-in roles. Generated roles are session-scoped
+and held in memory by default: they have no filesystem source and disappear on
+the next session. Do not write
+an agent definition unless the user explicitly asks to keep the role for future
+sessions. 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}
 
+Definitions are resolved live at spawn time: if a spawn says a listed role is
+gone, its definition file changed mid-session — recreate it on demand instead
+of retrying.
+
+When an assignment or user request needs an agent whose name has no
+definition yet, create it in memory 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, register the session role, and spawn immediately. Only after an
+explicit request to keep the role for future sessions should you set
+\`definition.persist=true\` (optionally choosing \`persistScope\`) so the spawn
+writes \`<cwd>/.pi/agents/<name>.md\` or \`<name>.local.md\`.
+
 ### Build a team in one step per teammate
 
 Use teammate_spawn(name, agent, optional kickoff prompt) to start a resident
@@ -63,19 +82,26 @@ 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;
-dependencies unlock downstream tasks without your involvement. An explicit
-verify command makes completion deterministic: zero exit completes, failure
-feeds stderr back to the claimer for fix-and-resubmit.
+dependencies unlock downstream tasks without your involvement. The verify
+prompt is judged by a fresh one-shot reviewer that inspects the work itself:
+VERDICT: PASS completes, FAIL feeds the reviewer's findings back to the
+claimer for fix-and-resubmit. Write gates as acceptance criteria a reviewer
+can check (behavior, constraints, evidence), not as shell commands.
 
 ### Teammates are autonomous: recover, never punish
 
@@ -85,7 +111,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

@@ -8,13 +8,14 @@
 import { getMarkdownTheme, keyHint } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { buildTeamLeaderGuidance, WORKER_GUIDANCE } from "./guidance.ts";
-import { initTeamMachine, removeRuntimeDir, shutdownTeamMachine, teardownTeammates } from "./team-machine.ts";
+import { clearSessionAgents } from "./agents.ts";
+import { initTeamMachine, markTeammateFinished, removeRuntimeDir, shutdownTeamMachine, teardownTeammates } from "./team-machine.ts";
 import { cleanupExpiredStateDirs } from "./statefile.ts";
 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";
 
@@ -61,7 +62,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 +89,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(report)) continue;
       pi.appendEntry(TEAMMATE_FINISHED_ENTRY_TYPE, {
         teammate: report.teammate ?? report.agent,
         agent: report.agent,
@@ -97,6 +98,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("session_start", async (_event, ctx) => {
+    clearSessionAgents();
     resetState();
     followUpQueue?.reset();
     leaderCtx = ctx;