@fradser/pi-agent-teams 0.10.0 → 1.0.0

package/src/worker.ts

@@ -1,5 +1,6 @@
+import { isTaskReplaced } from "@fradser/pi-tasks";
 /**
- * Teammate capabilities. A single addressed agent_event primitive covers
+ * Agent capabilities. A single addressed agent_event primitive covers
  * leader reports and peer mail. Task-list registration is shared by leader
  * and worker processes; claiming and submitting remain worker-only.
  */
@@ -8,34 +9,41 @@ import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { truncateTail, type ExtensionAPI, type MessageEndEvent } from "@earendil-works/pi-coding-agent";
+import { setOwnedTools } from "@fradser/pi-kit";
+import { isTaskStatus, resourcesConflict, type TaskStatus } from "@fradser/pi-tasks";
 import { messageRow, workerWorkRow } from "./tool-copy.ts";
 import { emptyToolCall, renderCoordinationRow, textOf } from "./tool-render.ts";
 import { resolveRecipient } from "./recipient.ts";
-import { appendInboxMessage, appendWorkerEvent, createTaskIntent, readBoardFile, readRoster } from "./statefile.ts";
+import { appendInboxMessage, appendWorkerEvent, readRoster } from "./statefile.ts";
+import { createTaskIntent, readTasksFile } from "@fradser/pi-tasks";
 import {
   AgentEventParams,
   LEADER_RECIPIENT,
   messageTitle,
   WorkerWorkToolParams,
-  type BoardTask,
+  type Task,
 } from "./types.ts";
 
-const BOARD_DISCLOSURE_TOOLS = ["work"] as const;
-type BoardDisclosure = "none" | "notice" | "claimed";
+const TASK_DISCLOSURE_TOOLS = ["task"] as const;
+/** Why the tasks tool is shown to this worker. `held` means it already
+ *  owns an assignment, which is a fact about this worker rather than a task
+ *  status — the two were never the same state and must not share a word. */
+type TaskDisclosure = "none" | "notice" | "held";
 
 export interface WorkerToolDisclosure {
-  update(prompt: string): void;
+  update(prompt?: string): void;
   reset(): void;
 }
 
 function createWorkerToolDisclosure(pi: ExtensionAPI): WorkerToolDisclosure {
-  let state: BoardDisclosure = "none";
+  let state: TaskDisclosure = "none";
   const apply = () => {
     if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
-    const active = pi.getActiveTools();
-    const withoutBoardControls = active.filter((tool) => !BOARD_DISCLOSURE_TOOLS.includes(tool as typeof BOARD_DISCLOSURE_TOOLS[number]));
-    const revealed = state === "notice" || state === "claimed" ? ["work"] : [];
-    pi.setActiveTools([...withoutBoardControls, ...revealed]);
+    const revealed = state === "notice" || state === "held" ? ["task"] : [];
+    // `work` is re-asserted from the owned set rather than the snapshot, so this
+    // disclosure write cannot deactivate a tool the harness has not published
+    // yet. See setOwnedTools.
+    setOwnedTools(pi, { owned: TASK_DISCLOSURE_TOOLS, toggled: revealed, enabled: revealed.length > 0 });
   };
   return {
     update(prompt) {
@@ -48,8 +56,8 @@ function createWorkerToolDisclosure(pi: ExtensionAPI): WorkerToolDisclosure {
       // able to acknowledge it; hiding work here strands its resource lease.
       if (binding && rosterEntry && rosterEntry.spawnId === binding.spawnId
         && rosterEntry.status !== "stopped" && assignment) {
-        state = "claimed";
-      } else if (!assignment && prompt.includes("=== BOARD NOTICE ===")) state = "notice";
+        state = "held";
+      } else if (!assignment && prompt?.includes("=== TASK NOTICE ===")) state = "notice";
       else state = "none";
       apply();
     },
@@ -66,7 +74,7 @@ export interface WorkerBinding {
   outbox: string;
   inbox: string;
   rosterFile: string;
-  boardFile: string;
+  tasksFile: string;
   claimsDir: string;
   submissionsDir: string;
 }
@@ -77,7 +85,7 @@ const REQUIRED_ENV = [
   "PI_TEAMMATE_OUTBOX_FILE",
   "PI_TEAMMATE_INBOX_FILE",
   "PI_TEAMMATE_ROSTER_FILE",
-  "PI_TEAMMATE_BOARD_FILE",
+  "PI_TEAMMATE_TASKS_FILE",
   "PI_TEAMMATE_CLAIMS_DIR",
   "PI_TEAMMATE_SUBMISSIONS_DIR",
 ] as const;
@@ -85,35 +93,40 @@ const REQUIRED_ENV = [
 export function workerBinding(): WorkerBinding | undefined {
   const values = REQUIRED_ENV.map((name) => process.env[name]);
   if (values.some((value) => !value)) return undefined;
-  const [worker, spawnId, outbox, inbox, rosterFile, boardFile, claimsDir, submissionsDir] = values as string[];
-  return { worker, spawnId, outbox, inbox, rosterFile, boardFile, claimsDir, submissionsDir };
+  const [worker, spawnId, outbox, inbox, rosterFile, tasksFile, claimsDir, submissionsDir] = values as string[];
+  return { worker, spawnId, outbox, inbox, rosterFile, tasksFile, claimsDir, submissionsDir };
 }
 
-function loadBoardTasks(binding: WorkerBinding): BoardTask[] {
-  const board = readBoardFile(binding.boardFile);
-  return Object.values(board?.tasks ?? {}).sort((a, b) => a.id.localeCompare(b.id));
+function loadWorkerTasks(binding: WorkerBinding): Task[] {
+  const tasks = readTasksFile(binding.tasksFile);
+  return Object.values(tasks?.tasks ?? {}).map(task => {
+    // Workers read the leader's file without restoring the shared store. Legacy
+    // files can still be present until its next mutation, so normalize status
+    // here without resetting an active participant's holding.
+    const raw: unknown = task.status;
+    const status = raw === "recovery_hold" ? "blocked"
+      : raw === "superseded" ? (task.supersededBy ? "pending" : "blocked")
+      : isTaskStatus(raw) ? raw : "blocked";
+    return { ...task, status, ...(raw === "superseded" && !task.supersededBy ? { replacementUnresolved: true } : {}) };
+  }).sort((a, b) => a.id.localeCompare(b.id));
 }
 
-function dependenciesMet(task: BoardTask, tasks: Map<string, BoardTask>): boolean {
+function dependenciesMet(task: Task, tasks: Map<string, Task>): boolean {
   return task.dependsOn.every((dep) => tasks.get(dep)?.status === "completed");
 }
 
-function taskCounts(tasks: BoardTask[], byId: Map<string, BoardTask>): string {
-  const counts = { pending: 0, claimed: 0, completed: 0, superseded: 0 };
-  for (const task of tasks) counts[task.status] += 1;
-  const claimable = tasks.filter((task) => task.status === "pending" && !task.recoveryRequired && dependenciesMet(task, byId)).length;
-  return `tasks=${tasks.length} · pending=${counts.pending} (${claimable} claimable) · claimed=${counts.claimed} · completed=${counts.completed} · superseded=${counts.superseded}`;
+function taskCounts(tasks: Task[], byId: Map<string, Task>): string {
+  const counts: Record<TaskStatus, number> = { pending: 0, in_progress: 0, blocked: 0, completed: 0, cancelled: 0 };
+  for (const task of tasks) if (!isTaskReplaced(task)) counts[task.status] += 1;
+  const claimable = tasks.filter((task) => !isTaskReplaced(task) && task.status === "pending" && dependenciesMet(task, byId)).length;
+  return `tasks=${tasks.length} · pending=${counts.pending} (${claimable} claimable) · in_progress=${counts.in_progress} · blocked=${counts.blocked} · completed=${counts.completed} · cancelled=${counts.cancelled} · superseded=${tasks.filter(isTaskReplaced).length}`;
 }
 
-function resourcesConflict(left: readonly string[] | undefined, right: readonly string[] | undefined): boolean {
-  return (left ?? []).some((a) => (right ?? []).some((b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`)));
-}
-
-function claimRejection(binding: WorkerBinding, task: BoardTask): string | undefined {
+function claimRejection(binding: WorkerBinding, task: Task): string | undefined {
   const self = readRoster(binding.rosterFile).find((entry) => entry.name === binding.worker);
   if (self?.assignment) {
     const state = self.assignment.closed ? "closed pending leader reopen" : "active";
-    return `You already own ${state} ${self.assignment.kind} assignment "${self.assignment.id}". Finish it through its matching protocol before claiming board work.`;
+    return `You already own ${state} ${self.assignment.kind} assignment "${self.assignment.id}". Finish it through its matching protocol before claiming task work.`;
   }
   const conflict = readRoster(binding.rosterFile).find((entry) => entry.name !== binding.worker
     && entry.assignment && !entry.assignment.closed
@@ -124,14 +137,19 @@ function claimRejection(binding: WorkerBinding, task: BoardTask): string | undef
   return undefined;
 }
 
-function taskStatusLabel(task: BoardTask, tasks: Map<string, BoardTask>): string {
-  if (task.status === "pending") return task.recoveryRequired ? "pending/recovery-required" : dependenciesMet(task, tasks) ? "pending/claimable" : "pending/blocked";
+function taskStatusLabel(task: Task, tasks: Map<string, Task>): string {
+  // `blocked` is a state of its own, so it is named as one. A task in it
+  // was attempted and the attempt did not stand: it is not claimable work, and
+  // calling it "pending" hid that from the participant reading this list.
+  if (isTaskReplaced(task)) return task.supersededBy ? `replaced-by=${task.supersededBy}` : "replacement-unresolved";
+  if (task.status === "blocked") return "blocked";
+  if (task.status === "pending") return dependenciesMet(task, tasks) ? "pending/claimable" : "pending/blocked";
   return task.status;
 }
 
-export function renderTaskBoard(tasks: BoardTask[]): string {
+export function renderTaskList(tasks: Task[]): string {
   const byId = new Map(tasks.map((task) => [task.id, task]));
-  const lines = [`BOARD · current session`, `SUMMARY · ${taskCounts(tasks, byId)}`];
+  const lines = [`TASKS · current session`, `SUMMARY · ${taskCounts(tasks, byId)}`];
   if (tasks.length === 0) return `${lines.join("\n")}\nTASKS\n(no tasks)`;
   lines.push("TASKS");
   for (const task of tasks) {
@@ -212,7 +230,7 @@ function createWorkerReports(pi: ExtensionAPI) {
       throw new Error("Work authority rejected: this turn belongs to a different assignment. Wait for its fresh assignment marker.");
     }
     const cancelled = cancellation && assignmentId && self.currentTaskId
-      && (self.assignment?.closed || loadBoardTasks(binding).some((task) => task.id === self.currentTaskId && task.status === "superseded"));
+      && (self.assignment?.closed || loadWorkerTasks(binding).some((task) => task.id === self.currentTaskId && isTaskReplaced(task)));
     if ((reportClosed || self.assignment?.closed) && !(cancelled && terminalOutcome !== "failed")) {
       throw new Error("Leader report rejected: this assignment already has a terminal report or is closed. Stop; no repeated acknowledgment is required.");
     }
@@ -240,7 +258,7 @@ function createWorkerReports(pi: ExtensionAPI) {
         pending = undefined;
       } else if (!current) {
         // The harness retired this attempt without a replacement marker: this is a
-        // fresh unassigned turn (peer mail, board notice, ordinary discussion).
+        // fresh unassigned turn (peer mail, tasks notice, ordinary discussion).
         // Holding the previous terminal state here would dead-end the worker.
         assignmentId = undefined;
         taskId = undefined;
@@ -300,14 +318,14 @@ function createWorkerReports(pi: ExtensionAPI) {
   };
 }
 
-export function registerWorkerCapabilities(pi: ExtensionAPI): WorkerToolDisclosure {
+export function registerChildCapabilities(pi: ExtensionAPI): WorkerToolDisclosure {
   const disclosure = createWorkerToolDisclosure(pi);
   const reports = createWorkerReports(pi);
   pi.registerTool({
-    name: "agent_event",
+    name: "message",
     promptSnippet: "Send an event or message to a participant",
     label: "Agent Event",
-    description: "Communication-only interface across Leader, Worker, and Peers. Work completion is reported automatically after settlement or uses work action=submit.",
+    description: "Communication-only interface across Leader, Worker, and Peers. Task completion is reported automatically after settlement or delivered with task action=complete.",
     parameters: AgentEventParams,
     renderShell: "self",
     renderCall: emptyToolCall,
@@ -325,11 +343,11 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): WorkerToolDisclosu
       if (!params.to || params.to === LEADER_RECIPIENT) {
         appendWorkerEvent(binding.outbox, {
           assignmentId: authority.assignmentId, id: randomUUID(), type: "message", worker: binding.worker, spawnId: binding.spawnId,
-          body: params.message, status: params.intent ?? "inform", timestamp: Date.now(),
+          body: params.body, status: params.kind ?? "inform", timestamp: Date.now(),
         });
         return {
-          content: [{ type: "text", text: `MESSAGING\nREPORT · to=leader · intent=${params.intent ?? "inform"}\nNEXT · harness will deliver this message; Work completion is automatic or uses work submit` }],
-          details: { to: LEADER_RECIPIENT, intent: params.intent ?? "inform", outcome: "queued" },
+          content: [{ type: "text", text: `MESSAGING\nREPORT · to=leader · kind=${params.kind ?? "inform"}\nNEXT · harness will deliver this message; Task completion is automatic or uses task complete` }],
+          details: { to: LEADER_RECIPIENT, kind: params.kind ?? "inform", outcome: "queued" },
         };
       }
       const recipient = resolveRecipient(params.to, readRoster(binding.rosterFile));
@@ -339,45 +357,49 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): WorkerToolDisclosu
       appendInboxMessage(recipientInbox, {
         id: randomUUID(),
         from: binding.worker,
-        subject: messageTitle(params.message),
-        body: params.message,
+        subject: messageTitle(params.body),
+        body: params.body,
         ...(recipient.spawnId ? { toSpawnId: recipient.spawnId } : {}),
       });
       return {
         content: [{ type: "text", text: `MESSAGING\nQUEUED · to=@${to}\nNEXT · harness will route the inbox message into a recipient turn` }],
-        details: { to, outcome: "queued", intent: params.intent ?? "inform" },
+        details: { to, outcome: "queued", kind: params.kind ?? "inform" },
       };
     },
   });
 
-  async function queueWorkClaim(id: string | undefined, presentation: "board" | "work") {
+  async function queueWorkClaim(id: string | undefined, presentation: "task" | "work") {
     const binding = workerBinding();
     if (!binding) throw new Error("This capability is available only inside a spawned teammate.");
     // Claims pass the same attempt authority as sends and submissions: a closed or
-    // terminal attempt must not queue new board work even when work is re-disclosed.
+    // terminal attempt must not queue new task work even when work is re-disclosed.
     reports.authorize(binding);
     const label = presentation === "work" ? "Work Item" : "Task";
     const empty = presentation === "work" ? "No claimable Work Item right now." : "No claimable task right now.";
-    const race = presentation === "work" ? "All candidate Work Items were claimed in the race. Check Work again." : "All candidate tasks were claimed in the race. Check the board again.";
-    const tasks = loadBoardTasks(binding);
+    const race = presentation === "work" ? "All candidate Work Items were claimed in the race. Check Work again." : "All candidate tasks were claimed in the race. Check the tasks again.";
+    const tasks = loadWorkerTasks(binding);
     const byId = new Map(tasks.map((task) => [task.id, task]));
     const candidates = id
       ? tasks.filter((task) => task.id === id)
-      : tasks.filter((task) => task.status === "pending" && !task.recoveryRequired && dependenciesMet(task, byId));
+      : tasks.filter((task) => !isTaskReplaced(task) && task.status === "pending" && dependenciesMet(task, byId));
     if (candidates.length === 0) {
-      // Say why nothing is claimable: a board whose only pending Work is held for
-      // Leader recovery must not read as an ordinary empty board.
-      const held = loadBoardTasks(binding).filter((task) => task.status === "pending" && task.recoveryRequired);
+      // Say why nothing is claimable: a task set whose only pending Work is held for
+      // Leader recovery must not read as an ordinary empty tasks.
+      const held = loadWorkerTasks(binding).filter((task) => task.status === "blocked");
       if (!id && held.length > 0) {
         throw new Error(`No claimable ${label.toLowerCase()} right now. Held for explicit leader recovery: ${held.map((task) => task.id).join(", ")}.`);
       }
-      throw new Error(id ? `${label} "${id}" was not found${presentation === "board" ? " on the board" : ""}.` : empty);
+      throw new Error(id ? `${label} "${id}" was not found${presentation === "task" ? " in the task list" : ""}.` : empty);
     }
     for (const task of candidates) {
-      if (task.recoveryRequired) {
+      if (task.status === "blocked") {
         if (id) throw new Error(`Work Item "${task.id}" requires explicit leader Work assignment after failure.`);
         continue;
       }
+      if (isTaskReplaced(task)) {
+        if (id) throw new Error(task.supersededBy ? `Work Item "${task.id}" was replaced by "${task.supersededBy}".` : `Work Item "${task.id}" has an unresolved replacement target.`);
+        continue;
+      }
       if (task.status !== "pending" || !dependenciesMet(task, byId)) continue;
       const rejected = claimRejection(binding, task);
       if (rejected) {
@@ -385,12 +407,12 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): WorkerToolDisclosu
         continue;
       }
       const won = createTaskIntent(binding.claimsDir, task.id, {
-        taskId: task.id, worker: binding.worker, spawnId: binding.spawnId, timestamp: Date.now(),
+        taskId: task.id, participant: binding.worker, spawnId: binding.spawnId, timestamp: Date.now(),
       });
       if (won) {
         const content = presentation === "work"
           ? `WORK · current session\nCLAIM INTENT QUEUED · ${task.id} · ${task.subject}\nREQUESTER · @${binding.worker}\nNEXT · wait for harness claim acceptance before starting Work`
-          : `BOARD · current session\nCLAIM INTENT QUEUED · ${task.id} · ${task.subject}\nREQUESTER · @${binding.worker}\nNEXT · wait for harness Claim accepted feedback; do not start work until it arrives`;
+          : `TASKS · current session\nCLAIM INTENT QUEUED · ${task.id} · ${task.subject}\nREQUESTER · @${binding.worker}\nNEXT · wait for harness Claim accepted feedback; do not start work until it arrives`;
         const details = presentation === "work"
           ? { action: "claim", outcome: "queued", id: task.id, subject: task.subject, worker: binding.worker }
           : { taskId: task.id, subject: task.subject, worker: binding.worker };
@@ -402,7 +424,7 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): WorkerToolDisclosu
   }
 
   pi.registerTool({
-    name: "work",
+    name: "task",
     renderShell: "self",
     renderCall: emptyToolCall,
     renderResult(result, options, theme, context) {
@@ -421,7 +443,7 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): WorkerToolDisclosu
       const binding = workerBinding();
       if (!binding) throw new Error("This capability is available only inside a spawned teammate.");
       if (params.action === "list") {
-        const tasks = loadBoardTasks(binding);
+        const tasks = loadWorkerTasks(binding);
         const byId = new Map(tasks.map((task) => [task.id, task]));
         const lines = tasks.map((task) => `- ${task.id} · ${taskStatusLabel(task, byId)} · ${task.subject}`);
         return Promise.resolve({ content: [{ type: "text", text: `WORK · current session\nWORK ITEMS\n${lines.join("\n") || "(none)"}` }], details: { action: "list", outcome: "listed", count: tasks.length } });
@@ -436,20 +458,20 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): WorkerToolDisclosu
     },
   });
 
-  async function queueWorkSubmission(input: { taskId: string; status: "completed" | "failed"; result?: string; presentation: "board" | "work" }) {
+  async function queueWorkSubmission(input: { taskId: string; status: "completed" | "failed"; result?: string; presentation: "task" | "work" }) {
     const binding = workerBinding();
     if (!binding) throw new Error("This capability is available only inside a spawned teammate.");
     const authority = reports.authorize(binding, input.status === "failed");
     if (!authority.assignmentId || authority.taskId !== input.taskId) throw new Error("This turn does not own the submitted Work Item.");
     const assignmentId = authority.assignmentId;
     const won = createTaskIntent(binding.submissionsDir, input.taskId, {
-      taskId: input.taskId, worker: binding.worker, spawnId: binding.spawnId, assignmentId,
+      taskId: input.taskId, participant: binding.worker, spawnId: binding.spawnId, assignmentId,
       status: input.status, result: input.result, timestamp: Date.now(),
     });
     if (!won) throw new Error(`A submission for "${input.taskId}" is already pending.`);
     reports.close(input.status);
     disclosure.reset();
-    const task = loadBoardTasks(binding).find((candidate) => candidate.id === input.taskId);
+    const task = loadWorkerTasks(binding).find((candidate) => candidate.id === input.taskId);
     const roleVerify = process.env.PI_TEAMMATE_VERIFY_DEFAULT?.trim();
     const verify = input.status === "completed"
       ? task?.verify
@@ -461,9 +483,9 @@ export function registerWorkerCapabilities(pi: ExtensionAPI): WorkerToolDisclosu
     const next = "NEXT · End this turn. The harness settles the outcome; do not repeat submission or cancellation acknowledgments.";
     const content = input.presentation === "work"
       ? `WORK · current session\nSUBMISSION INTENT QUEUED · ${input.taskId} · ${input.status === "completed" ? "success" : "failed"}\n${verify}\n${next}`
-      : `BOARD · current session\nSUBMITTED · ${input.taskId} · ${input.status}\n${verify}\n${next}`;
+      : `TASKS · current session\nSUBMITTED · ${input.taskId} · ${input.status}\n${verify}\n${next}`;
     // The subject rides along in details: a worker process never hydrates the
-    // leader's in-memory board, so its row cannot look the task up by itself.
+    // leader's in-memory tasks, so its row cannot look the task up by itself.
     const details = input.presentation === "work"
       ? { action: "submit", outcome: "queued", id: input.taskId, subject: task?.subject, status: input.status === "completed" ? "success" : "failed", verify: Boolean(task?.verify || roleVerify) }
       : { taskId: input.taskId, subject: task?.subject, status: input.status, verify: Boolean(task?.verify || roleVerify) };

package/src/agents.ts

@@ -1,296 +0,0 @@
-/**
- * Declarative agent definitions: Markdown files with YAML-style frontmatter.
- *
- * Discovery scopes (later scopes override earlier ones for the same name):
- *   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, 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.
- */
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-
-export type AgentScope = "user" | "project" | "project-local" | "session";
-
-export interface AgentDefinition {
-  name: string;
-  description: string;
-  tools: string[];
-  model?: string;
-  /** Role-default completion gate; task-level verify overrides this. */
-  verify?: string;
-  /** Whether this role always receives a dedicated Git worktree. */
-  worktree: boolean;
-  /** The Markdown body, trimmed; used as the teammate's role prompt. */
-  prompt: string;
-  /** Scope that supplied this definition (precedence: project-local > project > user > bundled). */
-  scope: AgentScope;
-  /** True only for the shared project scope that is expected to be git-managed.
-   * user and project-local definitions are machine/personal by definition. */
-  gitManaged: boolean;
-  /** Absolute path of the definition file; absent for session-only roles. */
-  source?: string;
-}
-
-export interface AgentDefinitionInput {
-  name: string;
-  description: string;
-  tools: string[];
-  model?: string;
-  verify?: string;
-  worktree?: boolean;
-  prompt: string;
-}
-
-/** Reserved model value meaning "use the leader session's current model",
- *  resolved at spawn time (Claude-Code-style inherit). */
-export const MODEL_INHERIT_ALIAS = "inherit";
-
-const sessionAgents = new Map<string, AgentDefinition>();
-const AGENT_NAME_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/i;
-
-function normalizeAgentInput(input: AgentDefinitionInput): AgentDefinitionInput {
-  const name = input.name.trim();
-  if (!AGENT_NAME_PATTERN.test(name)) {
-    throw new Error(`Invalid agent name "${name}". Use letters, digits, dots, dashes, underscores.`);
-  }
-  const prompt = input.prompt.trim();
-  if (!prompt) throw new Error(`Agent "${name}" prompt must not be empty.`);
-  return {
-    ...input,
-    name,
-    description: input.description.trim(),
-    tools: input.tools.map((tool) => tool.trim()).filter(Boolean),
-    model: input.model?.trim() || undefined,
-    verify: input.verify?.trim() || undefined,
-    worktree: input.worktree ?? false,
-    prompt,
-  };
-}
-
-/** Register a generated role for this session without writing a definition file. */
-export function registerSessionAgent(input: AgentDefinitionInput): AgentDefinition {
-  const normalized = normalizeAgentInput(input);
-  const definition: AgentDefinition = {
-    ...normalized,
-    worktree: normalized.worktree ?? false,
-    scope: "session",
-    gitManaged: false,
-    source: undefined,
-  };
-  sessionAgents.set(definition.name, definition);
-  return definition;
-}
-
-/** Persist a generated role only when the user explicitly requests it. */
-export function persistAgentDefinition(
-  input: AgentDefinitionInput,
-  scope: "project" | "project-local",
-  cwd = process.cwd(),
-): AgentDefinition {
-  const normalized = normalizeAgentInput(input);
-  const directory = agentsDir("project", cwd);
-  fs.mkdirSync(directory, { recursive: true });
-  const filename = `${normalized.name}${scope === "project-local" ? LOCAL_DEFINITION_SUFFIX : ".md"}`;
-  const source = path.join(directory, filename);
-  const frontmatter = [
-    "---",
-    `name: ${normalized.name}`,
-    `description: ${normalized.description.replace(/[\\r\\n]+/g, " ")}`,
-    `tools: ${normalized.tools.join(", ")}`,
-    ...(normalized.model ? [`model: ${normalized.model}`] : []),
-    ...(normalized.verify ? [`verify: ${normalized.verify.replace(/[\\r\\n]+/g, " ")}`] : []),
-    `worktree: ${normalized.worktree ? "true" : "false"}`,
-    "---",
-    normalized.prompt,
-    "",
-  ].join("\n");
-  fs.writeFileSync(source, frontmatter, { encoding: "utf8", mode: 0o600 });
-  sessionAgents.delete(normalized.name);
-  return {
-    ...normalized,
-    worktree: normalized.worktree ?? false,
-    scope,
-    gitManaged: scope === "project",
-    source,
-  };
-}
-
-/** Drop generated session roles; persistent user/project definitions remain discoverable. */
-export function clearSessionAgents(): void {
-  sessionAgents.clear();
-}
-
-/** Shipped role templates: reference material for generating new definitions
- * 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-
- * managed by convention. */
-export const LOCAL_DEFINITION_SUFFIX = ".local.md";
-
-function agentsDir(scope: "user" | "project", cwd?: string): string {
-  if (scope === "user") {
-    return path.join(getAgentDir(), "agents");
-  }
-  return path.join(cwd || process.cwd(), ".pi", "agents");
-}
-
-function parseFrontmatter(raw: string): { fields: Record<string, string | string[]>; body: 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() };
-  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(",")
-        .map((tool) => tool.trim().replace(/^["']|["']$/g, ""))
-        .filter(Boolean);
-      fields.tools = tools;
-      continue;
-    }
-    fields[key] = value.replace(/^["']|["']$/g, "");
-  }
-  return { fields, body: match[2].trim() };
-}
-
-function loadDir(baseScope: AgentScope, dir: string, agents: Map<string, AgentDefinition>): void {
-  let entries: fs.Dirent[];
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return; // A missing agents directory is not an error.
-  }
-  // Dedup by name within the directory: plain .md first so a same-name
-  // xxx.local.md (personal override) overwrites it in the map.
-  const ordered = [...entries].sort((left, right) =>
-    Number(left.name.endsWith(LOCAL_DEFINITION_SUFFIX)) - Number(right.name.endsWith(LOCAL_DEFINITION_SUFFIX))
-    || left.name.localeCompare(right.name),
-  );
-  for (const entry of ordered) {
-    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
-    const source = path.join(dir, entry.name);
-    let raw: string;
-    try {
-      raw = fs.readFileSync(source, "utf8");
-    } catch {
-      continue;
-    }
-    const { fields, body } = parseFrontmatter(raw);
-    const isLocal = baseScope === "project" && entry.name.endsWith(LOCAL_DEFINITION_SUFFIX);
-    const baseName = isLocal
-      ? entry.name.slice(0, -LOCAL_DEFINITION_SUFFIX.length)
-      : entry.name.replace(/\.md$/, "");
-    const name = typeof fields.name === "string" ? fields.name : baseName;
-    if (!name || !body) continue;
-    agents.set(name, {
-      name,
-      description: typeof fields.description === "string" ? fields.description : "",
-      tools: Array.isArray(fields.tools) ? fields.tools : [],
-      model: typeof fields.model === "string" && fields.model ? fields.model : undefined,
-      verify: typeof fields.verify === "string" && fields.verify ? fields.verify : undefined,
-      worktree: fields.worktree === "true",
-      prompt: body,
-      scope: isLocal ? "project-local" : baseScope,
-      gitManaged: scopeIsGitManaged(isLocal ? "project-local" : baseScope),
-      source,
-    });
-  }
-}
-
-/** Only the shared project layer is expected to be git-managed. */
-function scopeIsGitManaged(scope: AgentScope): boolean {
-  return scope === "project";
-}
-
-/**
- * Resolve all agent definitions visible from the given cwd, with later scopes
- * overriding earlier ones per name: project-local > project > user.
- */
-export function discoverAgents(cwd?: string): Map<string, AgentDefinition> {
-  const agents = new Map<string, AgentDefinition>();
-  loadDir("user", agentsDir("user", cwd), agents);
-  loadDir("project", agentsDir("project", cwd), agents);
-  // Generated roles fill gaps only: filesystem scopes keep precedence over
-  // session memory.
-  for (const [name, definition] of sessionAgents) if (!agents.has(name)) agents.set(name, definition);
-  return agents;
-}
-
-/** Resolve one agent by name, or undefined when no scope defines it. */
-export function resolveAgent(name: string, cwd?: string): AgentDefinition | undefined {
-  return discoverAgents(cwd).get(name);
-}
-
-/**
- * Format discovered agents as Markdown for prompt injection in before_agent_start.
- */
-export function formatAgentGuidance(cwd?: string): string {
-  const agents = discoverAgents(cwd);
-  if (agents.size === 0) return "(none defined; pass an inline definition when delegating)";
-  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.scope === "session" ? "in-memory" : agent.gitManaged ? "git-managed" : "local",
-    ].filter(Boolean);
-    lines.push(`- **${agent.name}** (${agent.scope})`);
-    if (agent.description) lines.push(`  ${agent.description}`);
-    lines.push(`  Tools: ${agent.tools.join(", ") || "(role defaults)"}${extras.length > 0 ? ` | ${extras.join(" | ")}` : ""}`);
-  }
-  return lines.join("\n");
-}