@fradser/pi-agent-teams 0.7.0 → 0.8.2

package/src/tool-render.ts

@@ -0,0 +1,48 @@
+import { keyHint, type Theme } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import {
+  createStaticToolLifecycleResultRenderer,
+  formatToolErrorLine,
+  type ToolLifecycleSpec,
+} from "@fradser/pi-kit";
+
+export interface ToolResultText {
+  content: Array<{ type: string; text?: string }>;
+  details?: unknown;
+}
+
+export function textOf(result: ToolResultText): string {
+  return result.content.find((part) => part.type === "text")?.text ?? "";
+}
+
+export function emptyToolCall(): Text {
+  return new Text("", 0, 0);
+}
+
+export function renderLifecycleResult(
+  result: ToolResultText,
+  options: { expanded?: boolean },
+  theme: Pick<Theme, "fg" | "bold" | "bg">,
+  context: { isError?: boolean },
+  spec: ToolLifecycleSpec,
+  details?: readonly string[],
+): { render: (width: number) => string[]; invalidate: () => void } | Text {
+  const text = textOf(result);
+  // One expansion-body rule: detail lines derive from the model-facing content
+  // unless a caller passes explicit lines (only when the human body must
+  // differ from what the model sees).
+  const effectiveDetails = details ?? text.split("\n").filter((line) => line.trim());
+  if (context.isError) return new Text(theme.fg("error", formatToolErrorLine(text)), 0, 0);
+  return createStaticToolLifecycleResultRenderer({
+    createSpec: () => ({ ...spec, details: effectiveDetails }),
+    expandHint: keyHint("app.tools.expand", "to expand"),
+    fit: truncateToWidth,
+    visibleWidth,
+    wrapDetail: (line, width) => wrapTextWithAnsi(line, Math.max(1, width)),
+    renderError: (line, currentTheme) => new Text(currentTheme.fg("error", line), 0, 0),
+  })(result, options, theme, context);
+}
+
+export function resultDetails(result: ToolResultText): string[] {
+  return textOf(result).split("\n").filter((line) => line.trim());
+}

package/src/tools.ts

@@ -1,19 +1,38 @@
-import { keyHint, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { formatAgentMessagePrefix, formatAgentTaskName, formatExpandHint, formatToolEventLabel, safeDisplayText } from "@fradser/pi-kit";
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { detailField, eventToolLifecycle, formatAgentTaskName, formatToolLifecycleTitle, notifyPi } from "@fradser/pi-kit";
 import {
   createBoardTask,
-  formatSilenceDuration,
+  formatBoardTaskCreation,
+  hasAnnouncedFinish,
+  hasTerminalReport,
   publishStateSnapshot,
   sendLeaderMessage,
   shutdownTeammate,
   spawnTeammate,
 } from "./team-machine.ts";
 import { listTasks, livingTeammates } from "./state.ts";
+
+const DYNAMIC_LEADER_TOOLS = ["teammate_shutdown", "send_message", "task_list"] as const;
+let leaderToolApi: Pick<ExtensionAPI, "getActiveTools" | "setActiveTools"> | undefined;
+
+/** Keep spawn as the entry point; reveal follow-on controls only when relevant. */
+export function refreshLeaderToolDisclosure(): void {
+  if (!leaderToolApi || typeof leaderToolApi.getActiveTools !== "function" || typeof leaderToolApi.setActiveTools !== "function") return;
+  const active = leaderToolApi.getActiveTools();
+  const withoutDynamic = active.filter((tool) => !DYNAMIC_LEADER_TOOLS.includes(tool as typeof DYNAMIC_LEADER_TOOLS[number]));
+  const revealed = [
+    ...(livingTeammates().length > 0 ? ["teammate_shutdown", "send_message"] : []),
+    ...(listTasks().length > 0 ? ["task_list"] : []),
+  ];
+  leaderToolApi.setActiveTools([...withoutDynamic, ...revealed]);
+}
+
 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 { emptyToolCall, renderLifecycleResult } from "./tool-render.ts";
 
 function rosterSummary(): string {
   const alive = livingTeammates();
@@ -21,36 +40,46 @@ function rosterSummary(): string {
   return alive.map((t) => `@${t.name} (${t.agent}, ${t.status}${t.currentTaskId ? `, task ${t.currentTaskId}` : ""})`).join("\n");
 }
 
+function spawnAssignment(params: { name: string; agent: string; prompt?: string }): string {
+  const prompt = params.prompt?.trim();
+  if (!prompt) return "check task board";
+  const normalizedPrompt = prompt.replace(/^@/, "").trim().toLowerCase();
+  const name = params.name.replace(/^@/, "").toLowerCase();
+  const agent = params.agent.replace(/^@/, "").toLowerCase();
+  if (normalizedPrompt === name || normalizedPrompt === agent) {
+    return "check task board";
+  }
+  return formatAgentTaskName(prompt, "check task board");
+}
+
 export function registerLeaderTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "teammate_spawn",
-    promptSnippet: "Spawn a named resident teammate",
+    promptSnippet: "Spawn a named resident teammate or sub-agent",
     label: "Spawn Teammate",
-    description: "Spawn one named resident teammate. Model and worktree behavior come from its declarative agent definition; the kickoff prompt is optional.",
+    description: "Spawn one named resident teammate / sub-agent. Use this tool whenever instructions, third-party skills, or workflows ask to launch or delegate work to an agent, sub-agent (subagent), worker, or teammate. Generated role definitions stay in memory by default; persist one only when the user explicitly asks to keep it for future sessions.",
     parameters: TeammateSpawnParams,
-    // Canonical lifecycle rows (same as packages/monitor): empty renderCall,
-    // ONE startup row owned by renderResult.
     renderShell: "self",
-    renderCall: () => new Text("", 0, 0),
+    renderCall: emptyToolCall,
     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 spawn teammate."), 0, 0);
-      }
+      const text = result.content.find((part) => part.type === "text")?.text ?? "";
+      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 };
-      const line = `${theme.fg("toolTitle", theme.bold(formatToolEventLabel("started", "", "agent").trimEnd()))} ${theme.fg("accent", `@${params.name}`)} ${theme.fg("dim", "·")} ${theme.fg("customMessageText", theme.bold(formatAgentTaskName(params.prompt ?? "", params.name)))}`;
-      return {
-        render: (width: number) => width > 0 ? [truncateToWidth(line, width)] : [],
-        invalidate: () => {},
-      };
+      const title = formatToolLifecycleTitle({
+        kind: "started",
+        tool: "agent",
+        subject: `@${params.name} started · ${spawnAssignment(params)}`,
+      });
+      return new Text(theme.fg("customMessageLabel", theme.bold(title)), 0, 0);
     },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const result = spawnTeammate(params);
       if (!result.ok) throw new Error(result.error);
       refreshTeamUI(ctx);
+      refreshLeaderToolDisclosure();
       const kickoffNote = params.prompt?.trim()
         ? "It received your kickoff prompt and is working on it."
-        : "It is idle: it wakes for inbox messages and claimable board tasks.";
+        : "It received the standard board-check kickoff and is running its first turn; it idles once that settles.";
       return {
         content: [{ type: "text", text: `@${params.name} is alive as ${params.agent}.\n${kickoffNote}\n\n${rosterSummary()}` }],
         details: { started: true },
@@ -65,30 +94,23 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
     description: "Gracefully stop one named teammate. Its claimed task returns to the board; its worktree diff is captured before teardown.",
     parameters: TeammateShutdownParams,
     renderShell: "self",
-    renderCall: () => new Text("", 0, 0),
+    renderCall: emptyToolCall,
     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 shut down teammate."), 0, 0);
-      }
       const name = String((context.args as { name?: string }).name ?? "");
-      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: () => {} };
+      // The finish entry already announced this end of life (or its terminal
+      // report is queued to); a second event row is noise.
+      if (hasAnnouncedFinish(name) || hasTerminalReport(name)) return { render: () => [], invalidate: () => {} };
+      return renderLifecycleResult(result, options, theme, context, eventToolLifecycle(
+        "agent",
+        `@${name} shut down`,
+        {},
+      ));
     },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const result = await shutdownTeammate(params.name);
       if (!result.ok) throw new Error(result.error);
       refreshTeamUI(ctx);
+      refreshLeaderToolDisclosure();
       return { content: [{ type: "text", text: result.body }], details: {} };
     },
   });
@@ -97,44 +119,57 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
     name: "send_message",
     promptSnippet: "Send a message to a teammate",
     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.",
+    description: "The only messaging primitive. Address a living teammate by name; working teammates receive a steer immediately and idle teammates wake with the message.",
     parameters: SendMessageParams,
     // 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);
-      }
+    renderCall: emptyToolCall,
+    renderResult(result, options, theme, context) {
       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: () => {},
-      };
+      const outcome = detailField<"steered" | "queued" | "not-sent">(result.details, "outcome") ?? "queued";
+      const subject = outcome === "not-sent" ? "terminal report available" : outcome;
+      return renderLifecycleResult(result, options, theme, context, eventToolLifecycle(
+        "message",
+        subject,
+        { label: `to @${to}`, detailLimit: outcome === "not-sent" ? "all" : undefined },
+      ));
     },
     async execute(_toolCallId, params) {
       if (params.to === LEADER_RECIPIENT) throw new Error('The leader cannot send a message to itself.');
-      if (params.status) throw new Error('status is reserved for worker reports to="leader".');
-      const result = sendLeaderMessage(params.to, params.message);
+      const result = sendLeaderMessage(params.to, params.message, {
+        reopen: params.reopen,
+        resources: params.resources,
+      });
       if (!result.ok) throw new Error(result.error);
-      const disposition = result.queued ? "Queued for its next wake-up." : "Delivered to its running turn.";
-      let text = `Message to @${params.to}: ${disposition}`;
-      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.`;
+      if (result.outcome === "not-sent") {
+        return {
+          content: [{
+            type: "text",
+            text: [
+              "ROUTING · not sent",
+              "NEXT · No new message was delivered. Read the recorded report below; use reopen=true only for a distinct new assignment.",
+              `NOTE · @${params.to} already sent a terminal report. Delivery to your context is automatic; asking it to resend produces a duplicate leader turn.`,
+              `RECORDED TERMINAL REPORT · ${result.terminalReport}`,
+            ].join("\n"),
+          }],
+          details: { outcome: "not-sent", terminalReportAvailable: true },
+        };
+      }
+      const action = result.outcome === "steered"
+        ? "active control stream accepted the steer"
+        : "harness will deliver the queued message on the next wake-up";
+      let text = `MESSAGING\n${result.outcome.toUpperCase()} · to=@${params.to}\nNEXT · ${action}`;
+      // A stray status field (copied from worker report patterns) must not
+      // block delivery — it carries no meaning on leader-sent messages.
+      if (params.status) text += `\nNOTE · status ignored for leader-directed steering`;
+      if (result.priorTerminalReport) {
+        text += `\nNOTE · @${params.to} already sent a terminal report (below); it reaches your context automatically. A steer asking it to repeat that report produces a duplicate delivery — use reopen only for a distinct new assignment.`;
+        text += `\nPRIOR TERMINAL REPORT · ${result.priorTerminalReport}`;
       }
       return {
         content: [{ type: "text", text }],
-        details: result.stalledMs !== undefined && !result.queued
-          ? { queued: result.queued, stalledMs: result.stalledMs }
-          : { queued: result.queued },
+        details: { outcome: result.outcome },
       };
     },
   });
@@ -143,37 +178,44 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
     name: "task_create",
     promptSnippet: "Create a shared board task",
     label: "Create Task",
-    description: "Create one shared board task. Resident teammates self-claim it when dependencies are met; an optional verify command gates completion.",
+    description: "Create one pending task on the current session board. Existing idle teammates are notified immediately and may self-claim it; this tool never spawns teammates. An optional verify prompt gates completion through a fresh reviewer.",
     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);
-      }
+    renderCall: emptyToolCall,
+    renderResult(result, options, theme, context) {
       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: () => {},
-      };
+      return renderLifecycleResult(result, options, theme, context, eventToolLifecycle(
+        "board",
+        subject,
+        { label: "created" },
+      ));
     },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const tasks = listTasks();
-      if (params.dependsOn?.some((dep) => !tasks.some((task) => task.id === dep))) {
-        throw new Error(`Unknown dependency id in [${params.dependsOn.join(", ")}].`);
+      const referenced = [...(params.dependsOn ?? []), ...(params.supersedes ?? [])];
+      if (referenced.some((id) => !tasks.some((task) => task.id === id))) {
+        throw new Error(`Unknown task id in [${referenced.join(", ")}].`);
       }
       const created = createBoardTask(params);
       if (!created.ok) throw new Error(created.error);
       refreshTeamUI(ctx);
-      return { content: [{ type: "text", text: `Created [${created.id}] "${params.subject}". Idle teammates are notified automatically.` }], details: {} };
+      refreshLeaderToolDisclosure();
+      return {
+        content: [{ type: "text", text: formatBoardTaskCreation(params.subject, created) }],
+        details: {
+          notifiedTeammates: created.notifiedTeammates,
+          livingTeammates: created.livingTeammates,
+          claimable: created.claimable,
+          supersededTaskIds: created.supersededTaskIds,
+        },
+      };
     },
   });
 
   registerTaskListTool(pi);
+  leaderToolApi = pi;
 }
 
 function teamStatusSummary(): string {
@@ -189,7 +231,7 @@ export function registerTeamCommand(pi: ExtensionAPI): void {
     description: "Agent Teams management console: session teammates and persistent agent roles",
     handler: async (_args, ctx) => {
       publishStateSnapshot();
-      if (ctx.mode !== "tui") { ctx.ui.notify(teamStatusSummary(), "info"); return; }
+      if (ctx.mode !== "tui") { notifyPi(ctx.ui, teamStatusSummary(), "info"); return; }
       await openTeamConsole(ctx);
       refreshTeamUI(ctx);
     },

package/src/types.ts

@@ -14,6 +14,15 @@ export const TeammateStatus = Type.Union(
 );
 export type TeammateStatus = Static<typeof TeammateStatus>;
 
+export interface WorkerAssignment {
+  id: string;
+  kind: "direct" | "board";
+  /** Resource tags prevent concurrent mutating assignments from overlapping. */
+  resources: string[];
+  /** A terminal direct assignment is closed until the leader explicitly reopens it. */
+  closed?: boolean;
+}
+
 /** A named, long-lived child Pi process on the team roster. */
 export interface Teammate {
   /** Unique among living teammates; also the mailbox and roster key. */
@@ -30,6 +39,14 @@ export interface Teammate {
   isolation: "worktree" | "none";
   /** Board task currently claimed by this teammate, if any. */
   currentTaskId?: string;
+  /** The one assignment this worker is allowed to execute. Direct assignments
+   * and board claims are mutually exclusive until the leader opens another. */
+  assignment?: WorkerAssignment;
+  /** Most recent assignment retained for successor handoff after release or shutdown. */
+  lastAssignment?: WorkerAssignment;
+  lastTaskId?: string;
+  /** Effective launch model reference ("provider/model"); absent when Pi picks its default. */
+  model?: string;
   /** Live assistant text assembled from the RPC stream. */
   liveText?: string;
   /** Current child tool name, if a tool is executing. */
@@ -40,10 +57,20 @@ export interface Teammate {
   turns?: number;
   /** The child finished its current sequence and awaits the next prompt. */
   sequenceEnded?: boolean;
+  /** Leader reports are closed until a new prompt starts after a terminal report. */
+  reportSequenceEnded?: boolean;
   /** When the harness last sent a claimable-task notice to this teammate. */
   lastNoticeAt?: number;
+  /** Claimable task ids already announced to this teammate; one notice per id until it re-arms. */
+  noticedTaskIds?: string[];
   usage?: WorkerUsage;
   error?: string;
+  /** Effective tool allowlist granted to the child process (role tools plus
+   *  the capability set). Absent only for legacy snapshots. */
+  tools?: string[];
+  /** True once recognized model/stream activity was observed for this
+   * incarnation; the stall classifier uses this, not usage totals. */
+  modelOutputSeen?: boolean;
   createdAt: number;
   updatedAt: number;
   stoppedAt?: number;
@@ -60,6 +87,7 @@ export const TaskStatus = Type.Union(
     Type.Literal("pending"),
     Type.Literal("claimed"),
     Type.Literal("completed"),
+    Type.Literal("superseded"),
   ],
   { description: "Board lifecycle of a task" },
 );
@@ -72,10 +100,16 @@ export interface BoardTask {
   description?: string;
   /** Task ids that must complete before this task is claimable. */
   dependsOn: string[];
-  /** Deterministic completion gate; overrides the agent-role default. */
+  /** Completion gate: a review prompt a fresh one-shot reviewer answers with
+   *  VERDICT: PASS or FAIL; overrides the agent-role default. */
   verify?: string;
+  /** Mutating work must use stable resource tags such as `firmware/sub-node`.
+   *  A resource conflicts with itself and any slash-prefixed descendant. */
+  resources: string[];
   status: TaskStatus;
   claimedBy?: string;
+  /** Replacement task that made this task obsolete. */
+  supersededBy?: string;
   result?: string;
   errorMessage?: string;
   createdAt: number;
@@ -114,6 +148,9 @@ export interface MailboxMessage {
   subject: string;
   body: string;
   status?: "in_progress" | "completed" | "failed";
+  /** The harness retained this report for console inspection after shutdown;
+   * it never initiated a leader follow-up. */
+  archived?: boolean;
   timestamp: number;
 }
 
@@ -126,6 +163,8 @@ export interface WorkerReportEvent {
   spawnId: string;
   body: string;
   status?: "in_progress" | "completed" | "failed";
+  /** Wall-clock time the teammate wrote the event. */
+  timestamp?: number;
 }
 
 export type WorkerEvent = WorkerReportEvent;
@@ -139,7 +178,8 @@ export function isWorkerEvent(value: unknown): value is WorkerReportEvent {
     && typeof event.worker === "string"
     && typeof event.spawnId === "string"
     && typeof event.body === "string"
-    && (event.status === undefined || ["in_progress", "completed", "failed"].includes(event.status));
+    && (event.status === undefined || ["in_progress", "completed", "failed"].includes(event.status))
+    && (event.timestamp === undefined || (typeof event.timestamp === "number" && Number.isFinite(event.timestamp)));
 }
 
 /** Derive a display title from the first non-empty line of a message. */
@@ -162,11 +202,26 @@ export interface InboxMessage {
 
 // ── Tool parameter schemas (typebox) ──────────────────────────────
 
-/** Spawn one named resident teammate. */
+/** Spawn one named resident teammate or sub-agent. */
 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 (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" })),
+  agent: Type.String({ description: "Agent definition name or role id; an inline definition may create this role in memory for the current session" }),
+  prompt: Type.Optional(Type.String({ description: "Optional kickoff prompt delivered as the agent / teammate's first turn; omit to let it wait for messages or board claims" })),
+  resources: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { description: "Stable resource tags owned by this direct assignment. Overlapping board claims are rejected until it closes." })),
+  handoffFrom: Type.Optional(Type.String({ minLength: 1, description: "Stopped teammate whose assignment, claim, and recent reports should be summarized in this successor kickoff." })),
+  definition: Type.Optional(Type.Object({
+    description: Type.String({ description: "Routing contract for the generated role" }),
+    tools: Type.Optional(Type.Array(Type.String(), { description: "Pi tool ids for the generated role; only pi built-ins (read, bash, edit, write, grep, find, ls, powershell) are grantable — teammates run without extensions, so MCP/extension ids fail the spawn" })),
+    model: Type.Optional(Type.String({ description: 'Optional provider/model pin, or "inherit" to run on the leader\'s current model' })),
+    verify: Type.Optional(Type.String({ description: "Role-default completion gate: a review prompt a fresh reviewer answers with VERDICT: PASS or FAIL" })),
+    worktree: Type.Optional(Type.Boolean({ description: "Whether this role receives a dedicated Git worktree" })),
+    prompt: Type.String({ minLength: 1, description: "Role prompt for this generated teammate / sub-agent" }),
+    persist: Type.Optional(Type.Boolean({ description: "Persist only when the user explicitly asks to keep this role for future sessions" })),
+    persistScope: Type.Optional(Type.Union([
+      Type.Literal("project"),
+      Type.Literal("project-local"),
+    ], { description: "Persistence scope; defaults to project-local when persist is true" })),
+  }, { description: "Optional generated role definition; kept in memory unless explicitly persisted" })),
 });
 
 /** Shut down one living teammate. */
@@ -180,7 +235,9 @@ export const TaskCreateParams = Type.Object({
   description: Type.Optional(Type.String({ description: "Full task description for the claiming teammate" }),
   ),
   dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Task ids that must complete before this task is claimable" })),
-  verify: Type.Optional(Type.String({ description: "Deterministic completion gate command; zero exit completes the task. Overrides any agent-role default verify." })),
+  verify: Type.Optional(Type.String({ description: "Completion gate: a fresh reviewer judges the acceptance criteria. Explicit PASS/FAIL completes or returns the task; an inconclusive review escalates without counting as failure." })),
+  resources: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { description: "Stable resource tags this task mutates, e.g. firmware/sub-node. Overlapping active tags cannot be claimed concurrently." })),
+  supersedes: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { description: "Obsolete task ids this new task replaces. Superseded work cannot be claimed or completed." })),
 });
 
 /** Shared leader/worker read-only board view. */
@@ -194,6 +251,8 @@ export const LEADER_RECIPIENT = "leader";
 export const SendMessageParams = Type.Object({
   to: Type.String({ minLength: 1, description: 'Recipient: a teammate name on the roster, or "leader" to report to the team leader' }),
   message: Type.String({ description: "Message content; the first line becomes the title shown in the console" }),
+  reopen: Type.Optional(Type.Boolean({ description: "Leader only: explicitly start a new assignment after the teammate reported completion" })),
+  resources: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { description: "Leader only: resource tags for a reopened direct assignment. Ignored for worker reports." })),
   status: Type.Optional(Type.Union([
     Type.Literal("in_progress"),
     Type.Literal("completed"),
@@ -218,10 +277,11 @@ export const TaskSubmitParams = Type.Object({
 export interface TeamState {
   teammates: Record<string, Teammate>;
   tasks: Record<string, BoardTask>;
+  /** Unified teammate model for this session; spawns without a role pin use it. */
+  defaultModel?: string;
   /** Single leader inbox for teammate reports and harness diagnostics. */
   leaderMailbox: MailboxMessage[];
   messageCounter: number;
-  taskCounter: number;
   /** Byte offsets consumed by the parent from each teammate's outbox. */
   workerEventOffsets: Record<string, number>;
   /** Report event ids already applied, keyed by teammate spawn. */
@@ -230,4 +290,7 @@ export interface TeamState {
   peerInboxOffsets: Record<string, number>;
   /** Delivered peer message ids per inbox, capped FIFO for deduplication. */
   peerDeliveredIds: Record<string, string[]>;
+  /** Harness-owned peer-delivery transition by message id. This records queueing
+   * or control-stream acceptance only; it never asserts recipient processing. */
+  peerDeliveryStates: Record<string, "queued" | "routed">;
 }