@fradser/pi-agent-teams 0.7.0 → 0.8.0

package/src/team-machine.ts

@@ -5,12 +5,13 @@
  * engine described by the BDD contract.
  */
 
-import { exec } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { resolveAgent } from "./agents.ts";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { modelLabel, runPiWorker } from "@fradser/pi-kit";
+import { MODEL_INHERIT_ALIAS, discoverAgents, persistAgentDefinition, registerSessionAgent, resolveAgent, type AgentDefinition, type AgentDefinitionInput } from "./agents.ts";
 import {
   applyClaimIntent,
   claimableTasks,
@@ -22,6 +23,7 @@ import {
   getPeerInboxOffset,
   getState,
   getTeammate,
+  getTeamDefaultModel,
   idleTeammates,
   isPeerDelivered,
   isValidTeammateName,
@@ -74,7 +76,19 @@ import type { FollowUpReport } from "./follow-up-queue.ts";
 export const MAX_SESSION_WORKERS = 8;
 /** Harness coordination cadence: outbox drain every tick, notices paced. */
 const LIVE_POLL_MS = 500;
-export const NOTICE_PACE_MS = 2000;
+/** Minimum gap between claimable-task notices per teammate. One-shot noticing
+ *  makes repeats rare; this floor keeps any residual burst from stampeding
+ *  every idle teammate at once, and each wake costs a full worker turn. */
+const DEFAULT_NOTICE_PACE_MS = 5 * 60 * 1000;
+export const NOTICE_PACE_MS = readDurationEnv("PI_TEAMMATE_NOTICE_PACE_MS", DEFAULT_NOTICE_PACE_MS);
+/** Consecutive verify failures before the harness stops inviting resubmission and escalates to the leader instead. */
+export const VERIFY_FAILURE_ESCALATE_AFTER = 2;
+/** Claimable task ids remembered per teammate. markTasksNoticed prunes stale
+ *  ids on every notice, so slots are occupied only by currently-claimable
+ *  work; the cap is far above any realistic concurrent board size. */
+const MAX_NOTICED_TASK_IDS = 256;
+/** Claimable tasks listed in one wake-prompt board notice. */
+const WAKE_NOTICE_TASK_LIMIT = 10;
 /** Silence is not a work deadline: active stream output keeps a teammate alive.
  * The watchdog may only notify; termination decisions belong to the leader model. */
 const DEFAULT_STALL_NOTICE_MS = 30 * 60 * 1000;
@@ -117,14 +131,23 @@ let generation = 0;
 let runtimeStateFile = "";
 let boardFile = "";
 let leaderCwd = "";
+/** Live view of the leader session's current model, resolved at spawn time. */
+let leaderModelRef: () => string | undefined = () => undefined;
 let sendUpdate: (report: FollowUpReport) => void = () => {};
 let notifyChange: () => void = () => {};
 
 const pendingShutdowns = new Set<string>();
-/** Task ids under verification, bound to the claiming teammate incarnation. */
-const verifyingTasks = new Map<string, { worker: string; spawnId: string }>();
+/** Task ids under verification, bound to one exact submission via token so a
+ *  release/re-claim or newer submission invalidates any older in-flight gate. */
+const verifyingTasks = new Map<string, { worker: string; spawnId: string; token: string }>();
 /** Idle nudges already fired per teammate incarnation (one per transition). */
 const idleNudgesSent = new Set<string>();
+/** One finish entry per spawn incarnation; repeated terminal reports stay ordinary report rows. */
+const announcedFinishKeys = new Set<string>();
+/** Incarnations whose terminal report reached the leader pipeline, queued or dispatched. */
+const terminalReportKeys = new Set<string>();
+/** Consecutive verify failures per taskId:spawnId holder incarnation. */
+const verifyFailures = new Map<string, VerifyFailureRecord>();
 /** Self-finalize requests delivered per teammate incarnation before escalating to the leader. */
 const selfFinalizeAttempts = new Set<string>();
 const pendingDeliveries = new Map<string, InboxMessage[]>();
@@ -138,11 +161,12 @@ export interface MachineHooks {
 }
 
 export function initTeamMachine(
-  ctx: Pick<ExtensionContext, "sessionManager" | "cwd">,
+  ctx: Pick<ExtensionContext, "sessionManager" | "cwd" | "model">,
   hooks: MachineHooks,
 ): void {
   generation++;
   leaderCwd = ctx.cwd || process.cwd();
+  leaderModelRef = () => (ctx.model ? modelLabel(ctx.model) : undefined);
   const sessionFile = ctx.sessionManager?.getSessionFile();
   runtimeStateFile = stateFilePath(sessionFile, leaderCwd);
   boardFile = boardFilePath(sessionFile, leaderCwd);
@@ -160,6 +184,8 @@ export function shutdownTeamMachine(): void {
   runtimeStateFile = "";
   boardFile = "";
   leaderCwd = "";
+  leaderModelRef = () => undefined;
+  setVerifyGateRunner(undefined);
   sendUpdate = () => {};
   notifyChange = () => {};
   pendingShutdowns.clear();
@@ -167,6 +193,39 @@ export function shutdownTeamMachine(): void {
   idleNudgesSent.clear();
   selfFinalizeAttempts.clear();
   pendingDeliveries.clear();
+  verifyFailures.clear();
+  announcedFinishKeys.clear();
+  terminalReportKeys.clear();
+}
+
+// ── Spawn model resolution ────────────────────────────────────
+
+/** How a spawn's effective model was chosen. */
+export type SpawnModelSource = "pin" | "inherit" | "team-default" | "none";
+
+/**
+ * Resolve the effective spawn model. Precedence: explicit role pin beats the
+ * `inherit` alias (the leader session's current model), which beats the team
+ * default set from the console; with none of these Pi picks its own default.
+ * The value is resolved at spawn time so mid-session leader model switches
+ * apply to later spawns.
+ */
+export function resolveSpawnModel(
+  pinned: string | undefined,
+  teamDefault: string | undefined,
+  leaderModel: string | undefined,
+): { model?: string; source: SpawnModelSource } {
+  const pin = pinned?.trim();
+  if (pin && pin.toLowerCase() !== MODEL_INHERIT_ALIAS) return { model: pin, source: "pin" };
+  if (pin && leaderModel) return { model: leaderModel, source: "inherit" };
+  const fallback = teamDefault?.trim();
+  if (fallback) return { model: fallback, source: "team-default" };
+  return { model: undefined, source: "none" };
+}
+
+/** The leader session's current model reference, when one is selected. */
+export function currentLeaderModelRef(): string | undefined {
+  return leaderModelRef();
 }
 
 /** Terminate every resident teammate; returns unconfirmed-close diagnostics. */
@@ -247,12 +306,37 @@ export function spawnTeammate(input: {
   name: string;
   agent: string;
   prompt?: string;
+  definition?: Omit<AgentDefinitionInput, "name" | "tools"> & {
+    tools?: string[];
+    persist?: boolean;
+    persistScope?: "project" | "project-local";
+  };
 }): { ok: true; teammate: Teammate } | { ok: false; error: string } {
   const stateFile = requireStateFile();
   const invalid = validateSpawnInput(input);
   if (invalid) return { ok: false, error: invalid };
-  const agent = resolveAgent(input.agent, leaderCwd);
-  if (!agent) return { ok: false, error: `Agent "${input.agent}" not found in any scope.` };
+  const resolved = resolveAgent(input.agent, leaderCwd);
+  let agent: AgentDefinition | undefined = resolved;
+  if (input.definition && inlineDefinitionApplies(resolved)) {
+    try {
+      const generated = input.definition;
+      const roleInput: AgentDefinitionInput = {
+        name: input.agent,
+        description: generated.description,
+        tools: generated.tools ?? [],
+        model: generated.model,
+        verify: generated.verify,
+        worktree: generated.worktree,
+        prompt: generated.prompt,
+      };
+      agent = generated.persist
+        ? persistAgentDefinition(roleInput, generated.persistScope ?? "project-local", leaderCwd)
+        : registerSessionAgent(roleInput);
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+  if (!agent) return { ok: false, error: unknownAgentError(input.agent, leaderCwd) };
 
   let isolation: Teammate["isolation"] = "none";
   let workerCwd = leaderCwd;
@@ -271,10 +355,13 @@ export function spawnTeammate(input: {
     return { ok: false, error: registered.error };
   }
 
+  const spawnModel = resolveSpawnModel(agent.model, getTeamDefaultModel(), leaderModelRef());
+  updateTeammate(input.name, { model: spawnModel.model });
+
   const started = spawnResident({
     workerName: input.name,
     description: buildKickoffPrompt(input.name, input.agent, agent.prompt, input.prompt, isolation),
-    model: agent.model,
+    model: spawnModel.model,
     tools: agent.tools,
     cwd: workerCwd,
     env: teammateEnv(stateFile, input, spawnId, agent.verify),
@@ -294,6 +381,28 @@ export function spawnTeammate(input: {
   return { ok: true, teammate: getTeammate(input.name)! };
 }
 
+/** True when a spawn's inline definition should create or replace the role:
+ *  nothing resolved, or only a session-scoped generated role did. Filesystem
+ *  scopes are user-owned and always win over inline input. */
+export function inlineDefinitionApplies(resolved: AgentDefinition | undefined): boolean {
+  return !resolved || resolved.scope === "session";
+}
+
+/** Spawn failure for an unresolvable agent name. Definitions resolve live at
+ *  spawn time, so the available-agents list in the cached session guidance can
+ *  go stale (e.g. another session removed the file); name every checked scope
+ *  and the recovery path. */
+export function unknownAgentError(name: string, cwd: string): string {
+  const available = [...discoverAgents(cwd).keys()];
+  return [
+    `Agent "${name}" not found in any scope.`,
+    `Checked: ${cwd}/.pi/agents/<name>.local.md, ${cwd}/.pi/agents/<name>.md, ${path.join(getAgentDir(), "agents")}, and in-memory session roles.`,
+    'The available-agents list in your guidance may be stale: definition files can change mid-session (for example removed by a parallel session).',
+    'Recover by spawning with an inline definition derived from references/agent-roles.md, choose an existing role, or create the role first.',
+    `Available now: ${available.length > 0 ? available.join(", ") : "(none)"}.`,
+  ].join(' ');
+}
+
 function validateSpawnInput(input: { name: string }): string | undefined {
   if (!isValidTeammateName(input.name)) {
     return `Invalid teammate name "${input.name}". Use letters, digits, dots, dashes, underscores.`;
@@ -418,6 +527,47 @@ function checkStalledTeammates(now = Date.now()): void {
   }
 }
 
+interface VerifyFailureRecord {
+  count: number;
+  escalated: boolean;
+}
+
+/** Record one finish entry per spawn incarnation; later terminal reports from
+ *  the same resident stay ordinary report rows. */
+export function markTeammateFinished(
+  report: Pick<FollowUpReport, "teammate" | "agent" | "spawnId" | "finished">,
+): boolean {
+  if (!report.finished) return false;
+  const name = report.teammate ?? report.agent ?? "teammate";
+  const key = `${name}:${report.spawnId ?? "session"}`;
+  if (announcedFinishKeys.has(key)) return false;
+  announcedFinishKeys.add(key);
+  return true;
+}
+
+/** True when this teammate's current incarnation already announced its finish entry. */
+export function hasAnnouncedFinish(name: string): boolean {
+  const spawnId = getTeammate(name)?.spawnId;
+  return announcedFinishKeys.has(`${name}:${spawnId ?? "session"}`);
+}
+
+/** Remember at send time that this incarnation produced a terminal report, so
+ *  end-of-life suppression covers reports still queued for dispatch. */
+export function recordTerminalReport(
+  report: Pick<FollowUpReport, "teammate" | "agent" | "spawnId" | "finished">,
+): void {
+  if (!report.finished) return;
+  const name = report.teammate ?? report.agent ?? "teammate";
+  terminalReportKeys.add(`${name}:${report.spawnId ?? "session"}`);
+}
+
+/** True when this teammate's current incarnation has a terminal report in the
+ *  leader pipeline, whether or not its finish entry has been dispatched yet. */
+export function hasTerminalReport(name: string): boolean {
+  const spawnId = getTeammate(name)?.spawnId;
+  return terminalReportKeys.has(`${name}:${spawnId ?? "session"}`);
+}
+
 /** True when the teammate's last leader-bound report lacks a terminal status. */
 export function hasUnfinalizedReport(name: string): boolean {
   const mailbox = getState().leaderMailbox;
@@ -481,6 +631,11 @@ export async function shutdownTeammate(name: string): Promise<{ ok: true; body:
     // The child was already gone; synthesize the close bookkeeping.
     pendingShutdowns.delete(name);
     const released = releaseTasksOf(name, "Teammate was shut down.");
+    for (const task of released) {
+      verifyFailures.delete(`${task.id}:${teammate.spawnId}`);
+      verifyingTasks.delete(task.id);
+      rearmTaskNotice(task.id);
+    }
     updateTeammate(name, { status: "stopped", activeTool: undefined });
     idleNudgesSent.delete(`${name}:${teammate.spawnId}`);
     selfFinalizeAttempts.delete(`${name}:${teammate.spawnId}`);
@@ -509,6 +664,11 @@ async function handleTeammateClose(name: string, spawnId: string, result: Worker
   drainTeammateOutboxes();
 
   const released = releaseTasksOf(name, requested ? "Teammate was shut down." : "Teammate stopped unexpectedly.");
+  for (const task of released) {
+    verifyFailures.delete(`${task.id}:${teammate.spawnId}`);
+    verifyingTasks.delete(task.id);
+    rearmTaskNotice(task.id);
+  }
   pendingShutdowns.delete(name);
   // A stopped teammate must not keep the poll loop or its queue alive.
   pendingDeliveries.delete(name);
@@ -527,11 +687,14 @@ async function handleTeammateClose(name: string, spawnId: string, result: Worker
     : { from: name, subject: "Teammate stopped unexpectedly", body: crashDiagnostic(name, result, released) });
 
   if (!requested) {
-    sendUpdate({
+    const report = {
       teammate: name,
+      spawnId: teammate.spawnId,
       body: `@${name} stopped unexpectedly${released.length > 0 ? `; claimed task(s) ${released.map((t) => t.id).join(", ")} returned to the board` : ""}.`,
       finished: true,
-    });
+    };
+    recordTerminalReport(report);
+    sendUpdate(report);
   }
   publishStateSnapshot();
   ensureLivePoll();
@@ -632,13 +795,15 @@ function applyOutboxRecord(teammate: Teammate, record: unknown): boolean {
   });
   if (record.status === "completed" || record.status === "failed") {
     // The assignment ends; the resident itself stays alive until sequence end.
-    sendUpdate({
+    const report = {
       teammate: teammate.name,
       agent: teammate.agent,
       spawnId: teammate.spawnId,
       body: record.body,
       finished: true,
-    });
+    };
+    recordTerminalReport(report);
+    sendUpdate(report);
   }
   return true;
 }
@@ -770,6 +935,9 @@ function applyClaimMarker(intent: import("./types").TaskIntent): void {
   if (!sender) return;
   const outcome = applyClaimIntent(intent);
   if (outcome.applied) {
+    verifyFailures.delete(`${intent.taskId}:${intent.spawnId}`);
+    // A new holding must not inherit an in-flight gate from a previous one.
+    verifyingTasks.delete(intent.taskId);
     updateTeammate(intent.worker, { currentTaskId: intent.taskId });
     return;
   }
@@ -786,6 +954,9 @@ function applySubmissionMarker(intent: import("./types").TaskIntent): void {
   }
   if (intent.status === "failed") {
     releaseTask(intent.taskId, intent.result?.trim() || "Teammate reported failure.");
+    verifyFailures.delete(`${intent.taskId}:${intent.spawnId}`);
+    verifyingTasks.delete(intent.taskId);
+    rearmTaskNotice(intent.taskId);
     freeTeammateFromTask(intent.worker, intent.taskId);
     notifyTaskOutcome(task.subject, `${intent.worker} reported failure`, intent.result ?? "");
     return;
@@ -793,6 +964,17 @@ function applySubmissionMarker(intent: import("./types").TaskIntent): void {
   beginVerifyOrComplete(intent, task.verify ?? resolveAgent(sender.agent, leaderCwd)?.verify);
 }
 
+/** Fold one more verify failure into bookkeeping. The first failure invites a
+ *  fix-and-resubmit cycle; from the second the harness escalates to the leader
+ *  exactly once per holding and stays quiet after that. */
+export function reactToVerifyFailure(
+  previous: VerifyFailureRecord | undefined,
+): VerifyFailureRecord & { escalateToLeader: boolean } {
+  const count = (previous?.count ?? 0) + 1;
+  const escalated = previous?.escalated === true || count >= VERIFY_FAILURE_ESCALATE_AFTER;
+  return { count, escalated, escalateToLeader: escalated && previous?.escalated !== true };
+}
+
 function beginVerifyOrComplete(intent: import("./types").TaskIntent, verify: string | undefined): void {
   const task = getState().tasks[intent.taskId];
   if (!task) return;
@@ -800,30 +982,71 @@ function beginVerifyOrComplete(intent: import("./types").TaskIntent, verify: str
     finishCompletion(intent, task.subject);
     return;
   }
-  // The gate is bound to this claim: a crash/release/re-claim between submit
-  // and verify resolution must not let an old result complete a new holder.
-  verifyingTasks.set(intent.taskId, { worker: intent.worker, spawnId: intent.spawnId });
-  runVerifyCommand(verify)
-    .then((outcome) => {
-      verifyingTasks.delete(intent.taskId);
-      const current = getState().tasks[intent.taskId];
-      const stillHolds = current?.status === "claimed"
-        && current.claimedBy === intent.worker
-        && getTeammate(intent.worker)?.spawnId === intent.spawnId;
-      if (!stillHolds) return;
-      if (outcome.ok) finishCompletion(intent, task.subject);
-      else {
-        deliverFeedback(
-          intent.worker,
-          `Verify failed for ${intent.taskId}`,
-          [`The completion gate for "${task.subject}" failed.`, outcome.detail ?? "(no verify output)", "Fix the issues and resubmit with task_submit."].filter(Boolean).join("\n"),
-        );
-        notifyTaskOutcome(task.subject, `verify gate failed for ${intent.taskId}`, outcome.detail ?? "(no verify output)");
+  // The gate is bound to this exact submission via a unique token: a
+  // release/re-claim or newer submission between submit and verify resolution
+  // must not let the stale result complete the new holding.
+  const token = randomUUID();
+  verifyingTasks.set(intent.taskId, { worker: intent.worker, spawnId: intent.spawnId, token });
+  const input: VerifyReviewInput = {
+    verify,
+    taskSubject: task.subject,
+    workerResult: intent.result ?? "",
+    cwd: getTeammate(intent.worker)?.cwd || leaderCwd,
+  };
+  // A runner that throws synchronously or rejects is a failed gate, never a
+  // silent stuck claim: the holder gets feedback and escalation still applies.
+  Promise.resolve()
+    .then(() => verifyGateRunner(input))
+    .then((outcome) => resolveGateOutcome(intent, task.subject, token, outcome))
+    .catch((error) => resolveGateOutcome(intent, task.subject, token, {
+      ok: false,
+      detail: truncated(`(completion review crashed) ${error instanceof Error ? error.message : String(error)}`),
+    }));
+}
+
+/** Apply one gate outcome to its submission, guarded by the binding token. */
+function resolveGateOutcome(
+  intent: import("./types").TaskIntent,
+  subject: string,
+  token: string,
+  outcome: VerifyReviewOutcome,
+): void {
+  if (verifyingTasks.get(intent.taskId)?.token !== token) return;
+  verifyingTasks.delete(intent.taskId);
+  const current = getState().tasks[intent.taskId];
+  const stillHolds = current?.status === "claimed"
+    && current.claimedBy === intent.worker
+    && getTeammate(intent.worker)?.spawnId === intent.spawnId;
+  if (!stillHolds) return;
+  if (outcome.ok) {
+    finishCompletion(intent, subject);
+  } else {
+    const key = `${intent.taskId}:${intent.spawnId}`;
+    const reaction = reactToVerifyFailure(verifyFailures.get(key));
+    verifyFailures.set(key, reaction);
+    const detail = outcome.detail ?? "(no review output)";
+    if (reaction.count >= VERIFY_FAILURE_ESCALATE_AFTER) {
+      // An unfixable gate parks the task with its holder instead of
+      // looping: no further resubmit invitations, one leader escalation.
+      if (reaction.escalateToLeader) {
+        notifyTaskOutcome(subject, `verify failed ${reaction.count} times for ${intent.taskId}: manual attention needed`, detail);
       }
-      ensureLivePoll();
-      notifyChange();
-    })
-    .catch(() => verifyingTasks.delete(intent.taskId));
+      deliverFeedback(
+        intent.worker,
+        `Verify still failing for ${intent.taskId}`,
+        [`The completion gate for "${subject}" failed again (${reaction.count} consecutive failures).`, detail, "The task stays claimed by you. Do not resubmit or reclaim it; the leader has been notified and will decide next steps."].join("\n"),
+      );
+    } else {
+      deliverFeedback(
+        intent.worker,
+        `Verify failed for ${intent.taskId}`,
+        [`The completion gate for "${subject}" failed.`, detail, "Fix the issues and resubmit with task_submit."].join("\n"),
+      );
+      notifyTaskOutcome(subject, `verify gate failed for ${intent.taskId}`, detail);
+    }
+  }
+  ensureLivePoll();
+  notifyChange();
 }
 
 function finishCompletion(intent: import("./types").TaskIntent, subject: string): void {
@@ -831,21 +1054,92 @@ function finishCompletion(intent: import("./types").TaskIntent, subject: string)
   if (!task) return;
   const completed = completeTask(intent.taskId, intent.result);
   if (!completed) return;
+  verifyFailures.delete(`${intent.taskId}:${intent.spawnId}`);
   freeTeammateFromTask(intent.worker, intent.taskId);
   notifyTaskOutcome(subject, `${intent.worker} completed`, intent.result ?? "");
 }
 
-function runVerifyCommand(command: string): Promise<{ ok: boolean; detail?: string }> {
-  return new Promise((resolve) => {
-    exec(command, { cwd: leaderCwd, maxBuffer: 1024 * 1024 }, (error, _stdout, stderr) => {
-      const code = (error as { code?: number | string } | null)?.code;
-      if (error) {
-        resolve({ ok: false, detail: `verify exited with code ${code ?? "unknown"}: ${(stderr || error.message).slice(0, 4000)}` });
-        return;
-      }
-      resolve({ ok: true });
-    });
+// ── Verify gate: fresh one-shot reviewer with a VERDICT protocol ──
+
+/** The reviewer's reply must end with exactly one of these verdict lines. */
+export const VERIFY_VERDICT_PASS = "VERDICT: PASS";
+export const VERIFY_VERDICT_FAIL = "VERDICT: FAIL";
+
+export interface VerifyReviewInput {
+  /** The acceptance-gate prompt (task-level or agent-role default). */
+  verify: string;
+  /** Board subject of the gated task. */
+  taskSubject: string;
+  /** The claimer's own result summary; evidence, never trusted alone. */
+  workerResult: string;
+  /** Working directory to review: the holder's worktree root when isolated,
+   *  else the leader cwd — the reviewer must inspect the claimed work's tree. */
+  cwd: string;
+}
+
+export type VerifyReviewOutcome = { ok: boolean; detail?: string };
+
+/** Compose the reviewer prompt: fresh context, independent checks, explicit verdict line. */
+export function buildVerifyReviewPrompt(input: VerifyReviewInput): string {
+  const result = input.workerResult.trim().slice(0, 4000);
+  return [
+    "You are a fresh completion-gate reviewer for one teammate task on a shared board.",
+    `Task subject: ${input.taskSubject}`,
+    result ? `The claimer's result summary:\n${result}` : "The claimer provided no result summary.",
+    "Independently verify the work against the acceptance gate below using your tools; do not trust the summary alone. Do not modify any files.",
+    "Acceptance gate:",
+    input.verify.trim(),
+    "",
+    `End your final message with exactly one verdict line: "${VERIFY_VERDICT_PASS}" if the gate holds, or "${VERIFY_VERDICT_FAIL} - <reasons>" if it does not.`,
+  ].join("\n");
+}
+
+/** Parse the reviewer's reply into a gate outcome, scanning from the final
+ *  line upward. PASS must be an exact verdict line ("VERDICT: PASS", no
+ *  trailing content) so a contradictory suffix cannot sneak through; FAIL
+ *  carries its reasons. A missing or malformed verdict fails the gate so an
+ *  ambiguous review never completes a task. */
+export function parseVerifyVerdict(text: string): VerifyReviewOutcome {
+  const lines = text.trim().split("\n");
+  for (let index = lines.length - 1; index >= 0; index--) {
+    const candidate = lines[index].trim();
+    if (/^verdict:\s*pass$/i.test(candidate)) return { ok: true };
+    const failMatch = /^verdict:\s*fail\b[\s:-]*(.*)$/i.exec(candidate);
+    if (failMatch) {
+      return { ok: false, detail: truncated(failMatch[1].trim()) || "(no reasons given)" };
+    }
+  }
+  return { ok: false, detail: `(no ${VERIFY_VERDICT_PASS}/FAIL verdict line in the review)\n${truncated(text.trim())}` };
+}
+
+function truncated(text: string, cap = 4000): string {
+  const suffix = "\n…[truncated]";
+  return text.length <= cap ? text : text.slice(0, Math.max(0, cap - suffix.length)) + suffix;
+}
+
+/** Run the gate as a one-shot Pi worker: a brand-new context that inspects
+ *  the working tree itself before answering. Uses the team's model resolution
+ *  chain (team default, else Pi default) rather than any role pin. */
+export async function runVerifyReview(input: VerifyReviewInput): Promise<VerifyReviewOutcome> {
+  const outcome = await runPiWorker({
+    prompt: buildVerifyReviewPrompt(input),
+    cwd: input.cwd || leaderCwd,
+    model: resolveSpawnModel(undefined, getTeamDefaultModel(), leaderModelRef()).model,
   });
+  // A reviewer that did not exit cleanly produced no trustworthy verdict,
+  // even if partial output happens to contain a PASS line.
+  if (outcome.exitCode !== 0) {
+    return { ok: false, detail: truncated(`reviewer exited with code ${outcome.exitCode}: ${(outcome.stderr || outcome.text || "no output").trim()}`) };
+  }
+  return parseVerifyVerdict(outcome.text);
+}
+
+/** Active gate runner; tests inject a stub through setVerifyGateRunner. */
+let verifyGateRunner: (input: VerifyReviewInput) => Promise<VerifyReviewOutcome> = runVerifyReview;
+
+/** Replace the completion-gate runner (test seam); undefined restores the real reviewer. */
+export function setVerifyGateRunner(runner: ((input: VerifyReviewInput) => Promise<VerifyReviewOutcome>) | undefined): void {
+  verifyGateRunner = runner ?? runVerifyReview;
 }
 
 function freeTeammateFromTask(workerName: string, taskId: string): void {
@@ -868,20 +1162,56 @@ function findLivingTeammate(intent: import("./types").TaskIntent): Teammate | un
 
 // ── Wake-ups ──────────────────────────────────────────────────────
 
+/** Claimable tasks the teammate has not been notified about yet. */
+export function freshClaimableTasks<T extends { id: string }>(
+  noticedIds: readonly string[] | undefined,
+  tasks: readonly T[],
+): T[] {
+  const noticed = new Set(noticedIds ?? []);
+  return tasks.filter((task) => !noticed.has(task.id));
+}
+
+/** Retain only noticed ids that are still claimable, so a long board's history
+ *  can never evict a live one and resurrect an old wake-up. */
+export function retainLiveNoticedIds(noticedIds: readonly string[], claimableIds: ReadonlySet<string>): string[] {
+  return noticedIds.filter((id) => claimableIds.has(id));
+}
+
+function markTasksNoticed(name: string, taskIds: string[]): void {
+  if (taskIds.length === 0) return;
+  const teammate = getTeammate(name);
+  if (!teammate) return;
+  const live = retainLiveNoticedIds(teammate.noticedTaskIds ?? [], new Set(claimableTasks().map((task) => task.id)));
+  const merged = [...live, ...taskIds];
+  while (merged.length > MAX_NOTICED_TASK_IDS) merged.shift();
+  updateTeammate(name, { noticedTaskIds: merged });
+}
+
+/** A released task becomes noticeable again for every living teammate. */
+function rearmTaskNotice(taskId: string): void {
+  for (const teammate of livingTeammates()) {
+    if (teammate.noticedTaskIds?.includes(taskId)) {
+      updateTeammate(teammate.name, { noticedTaskIds: teammate.noticedTaskIds.filter((id) => id !== taskId) });
+    }
+  }
+}
+
 /**
  * Compose one wake-up prompt per idle teammate from queued inbox deliveries
- * plus a paced claimable-task notice. Teammates with nothing to do are never
- * woken.
+ * plus a board notice covering only claimable work that teammate has never
+ * been shown. Teammates with nothing new are never woken.
  */
 export function wakeIdleTeammates(): void {
-  const claimable = claimableTasks();
   for (const teammate of idleTeammates()) {
     const deliveries = pendingDeliveries.get(teammate.name) ?? [];
-    const dueNotice = claimable.length > 0 && noticeDue(teammate);
+    const fresh = freshClaimableTasks(teammate.noticedTaskIds, claimableTasks());
+    const dueNotice = fresh.length > 0 && noticeDue(teammate);
     if (deliveries.length === 0 && !dueNotice) continue;
-    const prompt = buildWakePrompt(deliveries, claimable, dueNotice);
+    const noticed = fresh.slice(0, WAKE_NOTICE_TASK_LIMIT);
+    const prompt = buildWakePrompt(deliveries, noticed, dueNotice);
     if (!deliverPrompt(teammate.name, prompt)) continue;
     pendingDeliveries.delete(teammate.name);
+    if (dueNotice) markTasksNoticed(teammate.name, noticed.map((task) => task.id));
     // A delivered prompt is fresh activity: restart the silence clock so a
     // long-idle teammate is never insta-flagged as stalled on wake.
     updateTeammate(teammate.name, {

package/src/tools.ts

@@ -3,6 +3,8 @@ import { formatAgentMessagePrefix, formatAgentTaskName, formatExpandHint, format
 import {
   createBoardTask,
   formatSilenceDuration,
+  hasAnnouncedFinish,
+  hasTerminalReport,
   publishStateSnapshot,
   sendLeaderMessage,
   shutdownTeammate,
@@ -26,7 +28,7 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
     name: "teammate_spawn",
     promptSnippet: "Spawn a named resident teammate",
     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. 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.
@@ -72,6 +74,9 @@ export function registerLeaderTools(pi: ExtensionAPI): void {
         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 ?? "");
+      // 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: () => {} };
       const title = theme.fg("toolTitle", theme.bold(formatToolEventLabel("event", `@${name} shut down`, "agent")));
       const render = (width: number) => {
         if (width <= 0) return [];
@@ -143,7 +148,7 @@ 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 shared board task. Resident teammates self-claim it when dependencies are met; 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.