@fradser/pi-agent-teams 0.7.0 → 0.8.2

package/src/team-machine.ts

@@ -5,14 +5,17 @@
  * 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 {
+  activeAssignmentConflict,
   applyClaimIntent,
+  assignTeammate,
   claimableTasks,
   clearStateDirty,
   clearWorkerRunEvents,
@@ -22,6 +25,7 @@ import {
   getPeerInboxOffset,
   getState,
   getTeammate,
+  getTeamDefaultModel,
   idleTeammates,
   isPeerDelivered,
   isValidTeammateName,
@@ -30,11 +34,13 @@ import {
   loadBoard,
   markPeerDelivered,
   markStateDirty,
+  normalizeResources,
   registerTeammate,
   releaseTask,
   releaseTasksOf,
   receiveWorkerMessage,
   setPeerInboxOffset,
+  setPeerDeliveryState,
   updateTeammate,
   updateTeammateProgress,
 } from "./state.ts";
@@ -61,24 +67,46 @@ import { isWorkerEvent } from "./types.ts";
 import {
   deliverPrompt,
   isCleanExit,
+  resolveWorkerTools,
   sendWorkerSteer,
   spawnResident,
   terminateAllTeammates,
   terminateTeammate,
+  unknownWorkerTools,
+  WORKER_TOOL_UNIVERSE,
   type WorkerProcessResult,
 } from "./spawner.ts";
-import { captureWorktreeDiff, cleanupWorktree, createWorktree } from "./worktree.ts";
-import { messageTitle, type InboxMessage, type Teammate } from "./types.ts";
+import { captureWorktreeDiff, cleanupWorktree, createWorktree, discardWorktree } from "./worktree.ts";
+import { messageTitle, type InboxMessage, type Teammate, type WorkerAssignment, type WorkerUsage } from "./types.ts";
 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;
 export const STALL_NOTICE_MS = readDurationEnv("PI_TEAMMATE_STALL_NOTICE_MS", DEFAULT_STALL_NOTICE_MS);
+/** Silence with zero lifetime model output and no tool running is the provider-
+ * hang signature: an in-flight request stuck on the model backend will not
+ * recover by waiting or steering, so flag it well before the general window so
+ * the leader can respawn early. Defaults to five minutes, independent of the
+ * notice-pace floor; 0 disables the tier. */
+const DEFAULT_SILENT_STALL_MS = 5 * 60 * 1000;
+export const SILENT_STALL_MS = readDurationEnv("PI_TEAMMATE_SILENT_STALL_MS", DEFAULT_SILENT_STALL_MS);
 /** Fully-consumed inboxes larger than this are truncated. */
 const INBOX_COMPACT_BYTES = 256 * 1024;
 
@@ -112,19 +140,67 @@ export function formatSilenceDuration(milliseconds: number): string {
   return `${minutes}m`;
 }
 
+/** True when the stream has delivered recognized model activity (text,
+ * thinking, tool-call, or tool execution events) at least once — the stall
+ * classifier. Usage totals stay diagnostics only: providers may omit them
+ * after real output, and an empty message_end artifact must not count. */
+export function hasModelOutput(teammate: Pick<Teammate, "modelOutputSeen">): boolean {
+  return teammate.modelOutputSeen === true;
+}
+
+/** Silence threshold for one teammate. A worker that has never received model
+ * output and runs no tool is almost certainly blocked on the provider rather
+ * than doing slow work; that signature uses the shorter silent-stall window. */
+export function stallThresholdMs(teammate: Pick<Teammate, "modelOutputSeen" | "activeTool">): number {
+  if (STALL_NOTICE_MS <= 0 || SILENT_STALL_MS <= 0) return STALL_NOTICE_MS;
+  if (!hasModelOutput(teammate) && !teammate.activeTool) return SILENT_STALL_MS;
+  return STALL_NOTICE_MS;
+}
+
+function usageLine(usage: WorkerUsage | undefined): string {
+  if (!usage) return "";
+  return ` Lifetime usage: ${usage.totalTokens} tokens, $${usage.cost.toFixed(4)}.`;
+}
+
+/** Stall notice body with the diagnostics a leader needs to decide: silence
+ * duration, spawn age, lifetime usage, and — for the zero-output provider-hang
+ * signature — the remedy that actually works (shutdown + respawn). */
+export function stallNoticeBody(
+  teammate: Pick<Teammate, "name" | "createdAt" | "activeTool" | "modelOutputSeen" | "usage">,
+  silenceMs: number,
+  now = Date.now(),
+): string {
+  const head = `@${teammate.name} has been silent for ${formatSilenceDuration(silenceMs)} (spawn age ${formatSilenceDuration(Math.max(0, now - teammate.createdAt))}).`;
+  if (!hasModelOutput(teammate) && !teammate.activeTool) {
+    return `${head} No model output received yet.${usageLine(teammate.usage)} An in-flight request stuck on the provider will not recover by steering; recovery usually means shutting this teammate down and respawning a successor (optionally pinning another model). Decide: keep waiting, steer again, or shut it down.`;
+  }
+  const toolNote = teammate.activeTool ? ` Tool still running: ${teammate.activeTool}.` : "";
+  return `${head}${toolNote}${usageLine(teammate.usage)} The child may be blocked in a provider or tool call; steer delivery is uncertain. Decide: keep waiting, steer again, or shut it down (and respawn a successor with context from the original kickoff, its mailbox reports, board claims, and the /agent-teams detail transcript).`;
+}
+
 let livePollTimer: ReturnType<typeof setInterval> | undefined;
 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 archiveQueuedReports: (spawnId: string) => FollowUpReport[] = () => [];
 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; submissionId: 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[]>();
@@ -134,19 +210,23 @@ const liveWorktrees = new Map<string, ReturnType<typeof createWorktree>>();
 
 export interface MachineHooks {
   sendUpdate: (report: FollowUpReport) => void;
+  /** Suppress reports whose delivery remains harness-owned when shutdown starts. */
+  archiveQueuedReports?: (spawnId: string) => FollowUpReport[];
   notifyChange: () => void;
 }
 
 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);
   sendUpdate = hooks.sendUpdate;
+  archiveQueuedReports = hooks.archiveQueuedReports ?? (() => []);
   notifyChange = hooks.notifyChange;
   // Resume: reload a persisted board; claims die with their holders.
   const persisted = readBoardFile(boardFile);
@@ -160,17 +240,59 @@ export function shutdownTeamMachine(): void {
   runtimeStateFile = "";
   boardFile = "";
   leaderCwd = "";
+  leaderModelRef = () => undefined;
+  setVerifyGateRunner(undefined);
   sendUpdate = () => {};
+  archiveQueuedReports = () => [];
   notifyChange = () => {};
   pendingShutdowns.clear();
   verifyingTasks.clear();
   idleNudgesSent.clear();
   selfFinalizeAttempts.clear();
   pendingDeliveries.clear();
+  verifyFailures.clear();
+  inconclusiveParks.clear();
+  verifyFailureParks.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. */
 export async function teardownTeammates(): Promise<string[]> {
+  // Session shutdown is an intentional lifecycle transition. Mark every
+  // resident before signalling so close callbacks do not misclassify normal
+  // session teardown as an unexpected crash and enqueue a follow-up turn.
+  for (const teammate of livingTeammates()) pendingShutdowns.add(teammate.name);
   const results = await terminateAllTeammates();
   const diagnostics: string[] = [];
   for (const result of results) {
@@ -201,7 +323,14 @@ function flushSnapshots(): void {
   const stateFile = requireStateFile();
   try {
     writeStateFile(stateFile, getState());
-    writeRoster(rosterPath(stateFile), livingTeammates().map((t) => ({ name: t.name, agent: t.agent, status: t.status })));
+    writeRoster(rosterPath(stateFile), livingTeammates().map((t) => ({
+      name: t.name,
+      agent: t.agent,
+      status: t.status,
+      tools: t.tools,
+      currentTaskId: t.currentTaskId,
+      assignment: t.assignment,
+    })));
     if (boardFile) writeBoardFile(boardFile, getState().tasks);
     clearStateDirty();
   } catch {
@@ -247,12 +376,51 @@ export function spawnTeammate(input: {
   name: string;
   agent: string;
   prompt?: string;
+  resources?: string[];
+  handoffFrom?: 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.` };
+  if (input.handoffFrom) {
+    const predecessor = getTeammate(input.handoffFrom);
+    if (!predecessor) return { ok: false, error: `Cannot hand off from @${input.handoffFrom}: teammate not found.` };
+    if (predecessor.status !== "stopped") {
+      return { ok: false, error: `Cannot hand off from living @${input.handoffFrom}. Shut it down or wait for it to stop before spawning a successor.` };
+    }
+  }
+  const resolved = resolveAgent(input.agent, leaderCwd);
+  // Reject tool ids the bare child could never grant before any side effect:
+  // a silent --tools drop here is how reviewers end up blind mid-audit.
+  const requestedTools = input.definition && inlineDefinitionApplies(resolved) ? input.definition.tools : resolved?.tools;
+  const unknownTools = unknownWorkerTools(requestedTools);
+  if (unknownTools.length > 0) return { ok: false, error: unknownWorkerToolsError(unknownTools) };
+  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;
@@ -265,16 +433,44 @@ export function spawnTeammate(input: {
   }
 
   const spawnId = randomUUID();
+  const effectiveKickoff = buildSuccessorHandoff(input.prompt, input.handoffFrom);
+  const directResources = effectiveKickoff?.trim()
+    ? resolveDirectResources(input.resources, input.handoffFrom)
+    : [];
+  const conflict = activeAssignmentConflict(directResources);
+  if (conflict) {
+    discardWorktreeQuietly(input.name);
+    return { ok: false, error: `Direct assignment resources conflict with @${conflict.name}'s ${conflict.assignment?.kind} assignment "${conflict.assignment?.id}".` };
+  }
   const registered = registerTeammate(newTeammate(input, spawnId, isolation, workerCwd));
   if (!registered.ok) {
     discardWorktreeQuietly(input.name);
     return { ok: false, error: registered.error };
   }
 
+  const spawnModel = resolveSpawnModel(agent.model, getTeamDefaultModel(), leaderModelRef());
+  // Record the grant before the first wake: a role derived without tools shows
+  // its narrow capability-only allowlist right on the spawn surface.
+  const assignment = directAssignment(effectiveKickoff, directResources, spawnId);
+  updateTeammate(input.name, {
+    model: spawnModel.model,
+    tools: resolveWorkerTools(agent.tools),
+    assignment,
+  });
+  // Flush before the kickoff is written: a fast child must not read a stale
+  // worker-readable roster missing its own entry or tool grant.
+  publishStateSnapshot();
+
   const started = spawnResident({
     workerName: input.name,
-    description: buildKickoffPrompt(input.name, input.agent, agent.prompt, input.prompt, isolation),
-    model: agent.model,
+    description: buildKickoffPrompt(
+      input.name,
+      input.agent,
+      agent.prompt,
+      effectiveKickoff,
+      isolation,
+    ),
+    model: spawnModel.model,
     tools: agent.tools,
     cwd: workerCwd,
     env: teammateEnv(stateFile, input, spawnId, agent.verify),
@@ -286,14 +482,48 @@ export function spawnTeammate(input: {
     return { ok: false, error: started.error };
   }
   updateTeammate(input.name, { pid: started.pid });
-  // A prompt-less spawn has no stream activity; it is idle from birth.
-  if (!input.prompt?.trim()) updateTeammate(input.name, { status: "idle" });
+  // Status stays "starting" until real stream events arrive: every spawned
+  // teammate runs a kickoff turn, so marking prompt-less spawns idle here used
+  // to mislabel an actively-running turn as idle and misroute deliveries
+  // (queued instead of steered, then lost inside the running turn).
   publishStateSnapshot();
   ensureLivePoll();
   notifyChange();
   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 execution-tool ids outside the teammate universe. */
+export function unknownWorkerToolsError(unknown: readonly string[]): string {
+  return [
+    `Unknown tool id${unknown.length === 1 ? "" : "s"} for a teammate: ${unknown.join(", ")}.`,
+    "A teammate child runs a bare pi process (--no-extensions), so only pi built-in tools plus the teammate capability set can be granted.",
+    `Valid ids: ${WORKER_TOOL_UNIVERSE.join(", ")}.`,
+    "MCP or project-extension tools cannot reach a teammate; perform that work in the leader session instead.",
+  ].join(" ");
+}
+
+/** 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 retrying teammate_spawn with name and an existing agent role id, or with name, a new agent role id, and an inline definition derived from references/agent-roles.md that includes description and prompt.',
+    `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.`;
@@ -309,6 +539,7 @@ function validateSpawnInput(input: { name: string }): string | undefined {
 
 function newTeammate(
   input: { name: string; agent: string },
+
   spawnId: string,
   isolation: Teammate["isolation"],
   workerCwd: string,
@@ -328,6 +559,46 @@ function newTeammate(
   };
 }
 
+export function directAssignment(
+  kickoff: string | undefined,
+  resources: string[],
+  spawnId: string,
+): WorkerAssignment | undefined {
+  if (!kickoff?.trim()) return undefined;
+  return {
+    id: `direct:${spawnId}`,
+    kind: "direct",
+    resources,
+  };
+}
+
+export function resolveDirectResources(resources: string[] | undefined, handoffFrom: string | undefined): string[] {
+  const explicit = normalizeResources(resources);
+  if (explicit.length > 0) return explicit;
+  const prior = handoffFrom ? getTeammate(handoffFrom) : undefined;
+  return normalizeResources(prior?.assignment?.resources ?? prior?.lastAssignment?.resources);
+}
+
+export function buildSuccessorHandoff(kickoff: string | undefined, handoffFrom: string | undefined): string | undefined {
+  if (!handoffFrom?.trim()) return kickoff;
+  const prior = getTeammate(handoffFrom);
+  const reports = getState().leaderMailbox
+    .filter((message) => message.from === handoffFrom)
+    .slice(-3)
+    .map((message) => `- ${message.subject}: ${truncated(message.body, 1000)}`)
+    .join("\n");
+  const assignment = prior?.assignment ?? prior?.lastAssignment;
+  const taskId = prior?.currentTaskId ?? prior?.lastTaskId;
+  const handoff = [
+    `=== SUCCESSOR HANDOFF FROM @${handoffFrom} ===`,
+    assignment ? `Prior assignment: ${assignment.kind} ${assignment.id}` : "Prior assignment: unavailable",
+    taskId ? `Prior board claim: ${taskId}` : "Prior board claim: none",
+    reports ? `Recent leader reports:\n${reports}` : "Recent leader reports: none",
+    "Verify current files yourself; do not claim the predecessor's board task unless the leader explicitly assigns it.",
+  ].join("\n");
+  return [kickoff?.trim(), handoff].filter(Boolean).join("\n\n");
+}
+
 function teammateEnv(
   stateFile: string,
   input: { name: string; agent: string },
@@ -348,7 +619,7 @@ function teammateEnv(
   };
 }
 
-function buildKickoffPrompt(
+export function buildKickoffPrompt(
   name: string,
   agentName: string,
   rolePrompt: string,
@@ -363,7 +634,7 @@ function buildKickoffPrompt(
   ].filter(Boolean).join(" ");
   const roleSection = `=== ROLE PROMPT (${agentName}) ===\n${rolePrompt}`;
   const taskSection = kickoff?.trim()
-    ? `=== KICKOFF TASK ===\n${kickoff.trim()}`
+    ? `=== KICKOFF TASK ===\n${kickoff.trim()}\n\nExecute this assigned task directly. Do not call task_list or check the task board unless this task explicitly instructs you to do so.`
     : "=== KICKOFF TASK ===\n(none yet — check the task board with task_list and claim suitable work with task_claim)";
   return `${header}\n\n${roleSection}\n\n${taskSection}`;
 }
@@ -372,7 +643,8 @@ function discardWorktreeQuietly(name: string): void {
   const handle = liveWorktrees.get(name);
   if (!handle || "error" in handle) return;
   liveWorktrees.delete(name);
-  cleanupWorktree(handle);
+  // A failed spawn never produced work; the empty branch goes too.
+  discardWorktree(handle);
 }
 
 function boardDirectory(): string {
@@ -385,6 +657,8 @@ function applyProgress(name: string, spawnId: string, progress: {
   liveThinking?: string;
   turns: number;
   finalResponse?: boolean;
+  modelOutputSeen?: boolean;
+  usage?: WorkerUsage;
 }): void {
   const teammate = getTeammate(name);
   // A stale callback from an older incarnation must not touch the current one.
@@ -395,6 +669,8 @@ function applyProgress(name: string, spawnId: string, progress: {
     liveThinking: progress.liveThinking,
     turns: progress.turns,
     sequenceEnded: progress.finalResponse === true ? true : undefined,
+    modelOutputSeen: progress.modelOutputSeen,
+    usage: progress.usage,
   });
   updateTeammate(name, { lastOutputAt: Date.now(), stallNoticeSentAt: undefined });
   if (progress.finalResponse && teammate.status !== "idle") {
@@ -404,20 +680,83 @@ function applyProgress(name: string, spawnId: string, progress: {
   ensureLivePoll();
 }
 
+export function formatAgentHealthReport(
+  state: "stalled",
+  teammate: Pick<Teammate, "name" | "agent">,
+  body: string,
+  silenceMs: number,
+): FollowUpReport {
+  return {
+    teammate: teammate.name,
+    agent: teammate.agent,
+    body,
+    finished: false,
+    health: { state, silenceMs },
+  };
+}
+
 function checkStalledTeammates(now = Date.now()): void {
   if (STALL_NOTICE_MS <= 0) return;
   for (const teammate of livingTeammates()) {
     if (teammate.status !== "working" && teammate.status !== "starting") continue;
     const silence = stallSilenceMs(teammate, now);
-    if (silence === undefined) continue;
-    if (silence < STALL_NOTICE_MS || teammate.stallNoticeSentAt !== undefined) continue;
-    const body = `@${teammate.name} has produced no RPC output for ${formatSilenceDuration(silence)}. The child may be blocked in a provider or tool call; steer delivery is uncertain. Decide: keep waiting, steer again, or shut it down (and respawn a successor with context from the original kickoff, its mailbox reports, board claims, and the /agent-teams detail transcript).`;
+    if (silence === undefined || teammate.stallNoticeSentAt !== undefined) continue;
+    if (silence < stallThresholdMs(teammate)) continue;
+    const body = stallNoticeBody(teammate, silence, now);
     updateTeammate(teammate.name, { stallNoticeSentAt: now });
     deliverToLeader({ from: "harness", subject: `Possible stall: @${teammate.name}`, body });
-    sendUpdate({ teammate: teammate.name, agent: teammate.agent, body, finished: false });
+    sendUpdate(formatAgentHealthReport("stalled", teammate, body, silence));
   }
 }
 
+interface VerifyFailureRecord {
+  count: number;
+  escalated: boolean;
+}
+
+/** One verdict-only retry per exact verify submission. */
+const inconclusiveVerifications = new Map<string, number>();
+/** Two inconclusive reviews park a holding until the leader explicitly steers it. */
+const inconclusiveParks = new Map<string, { worker: string; spawnId: string }>();
+/** Two explicit verify failures also require leader direction before retry. */
+const verifyFailureParks = new Map<string, { worker: string; spawnId: string }>();
+
+/** 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;
@@ -450,7 +789,13 @@ function nudgeIfUnfinalized(name: string, spawnId: string): void {
   idleNudgesSent.add(key);
   const reminder = `@${name} is now idle but its last report was not marked status="completed" or "failed". Its conclusions may be stuck in the mailbox — ask it to finalize or inspect the /agent-teams console.`;
   deliverToLeader({ from: "harness", subject: `Idle without terminal report: @${name}`, body: reminder });
-  sendUpdate({ teammate: name, body: reminder, finished: false });
+  sendUpdate({
+    teammate: name,
+    body: reminder,
+    origin: "harness",
+    harnessEvent: { type: "unfinalized-report", subject: `@${name} idle without terminal report` },
+    finished: false,
+  });
 }
 
 function failSpawn(name: string, error: string): void {
@@ -476,17 +821,28 @@ export async function shutdownTeammate(name: string): Promise<{ ok: true; body:
   const teammate = getTeammate(name);
   if (!teammate || teammate.status === "stopped") return { ok: false, error: `No living teammate named "${name}".` };
   pendingShutdowns.add(name);
+  archiveReportsForConsole(archiveQueuedReports(teammate.spawnId));
   const terminated = await terminateTeammate(name);
   if (!terminated) {
     // 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}`);
+      clearInconclusiveForHolding(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}`);
+    // No close event will fire for an already-gone child, so this branch is
+    // the only chance to put the shutdown summary on the delivery channel.
+    const summary = summarizeShutdown(name, released.length, 0, undefined);
+    deliverToLeader({ from: name, subject: "Teammate shut down", body: summary });
     publishStateSnapshot();
     notifyChange();
-    return { ok: true, body: summarizeShutdown(name, released.length, 0, undefined) };
+    return { ok: true, body: summary };
   }
   // Close finalization completes state transitions and reporting.
   return {
@@ -509,6 +865,12 @@ 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}`);
+    clearInconclusiveForHolding(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);
@@ -522,16 +884,27 @@ async function handleTeammateClose(name: string, spawnId: string, result: Worker
   clearWorkerRunEvents(name, teammate.spawnId);
   removeWorkerOutbox(requireStateFile(), name, teammate.spawnId);
 
-  deliverToLeader(requested
-    ? { from: name, subject: "Teammate shut down", body: summarizeShutdown(name, released.length, result.exitCode, result.usage) }
-    : { from: name, subject: "Teammate stopped unexpectedly", body: crashDiagnostic(name, result, released) });
-
-  if (!requested) {
-    sendUpdate({
+  if (requested) {
+    // The close handler drains a final outbox after shutdown was requested.
+    // Archive that spawn again so any report written during termination cannot
+    // become a delayed leader follow-up.
+    archiveReportsForConsole(archiveQueuedReports(spawnId));
+    const summary = summarizeShutdown(name, released.length, result.exitCode, result.usage);
+    deliverToLeader({ from: name, subject: "Teammate shut down", body: summary });
+    // A requested shutdown is already represented by the tool lifecycle row;
+    // keep its summary in the console mailbox without starting a leader turn.
+  } else {
+    deliverToLeader({ from: name, subject: "Teammate stopped unexpectedly", body: crashDiagnostic(name, result, released) });
+    const closeReport = {
       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,
-    });
+      origin: "harness" as const,
+      harnessEvent: { type: "unexpected-stop", subject: `@${name} stopped unexpectedly` },
+      finished: false,
+    };
+    recordTerminalReport(closeReport);
+    sendUpdate(closeReport);
   }
   publishStateSnapshot();
   ensureLivePoll();
@@ -552,6 +925,17 @@ function crashDiagnostic(name: string, result: WorkerProcessResult, released: Ar
   ].filter(Boolean).join("\n");
 }
 
+/** Retain reports the follow-up queue suppressed so the teammate detail view
+ * can show what was archived without turning it into another leader prompt. */
+function archiveReportsForConsole(reports: FollowUpReport[]): void {
+  for (const report of reports) {
+    if (!report.eventId) continue;
+    const message = getState().leaderMailbox.find((candidate) => candidate.id === report.eventId);
+    if (message) message.archived = true;
+  }
+  if (reports.length > 0) markStateDirty();
+}
+
 function summarizeShutdown(
   name: string,
   releasedCount: number,
@@ -572,17 +956,62 @@ async function finalizeWorktree(name: string): Promise<void> {
   }
   liveWorktrees.delete(name);
   const captured = captureWorktreeDiff(handle);
-  const patchNote = captured.ok && captured.diff.patch.trim()
-    ? `\n\n=== Worktree changes ===\n${captured.diff.diffStat}\n\n${captured.diff.patch}`
-    : captured.ok
-      ? "\n(no worktree changes)"
-      : `\n(worktree diff capture failed: ${captured.error})`;
-  cleanupWorktree(handle);
+  // Cleanup commits any remaining work onto the kept branch before removing
+  // the directory: staging alone would die with the worktree.
+  const cleaned = cleanupWorktree(handle);
+  if (!captured.ok) {
+    // The branch survives cleanup, so nothing is lost; wake the leader with
+    // the recovery path because this requires a decision.
+    const body = `Capturing @${name}'s worktree diff failed (${captured.error}). The branch ${handle.branch} was kept; inspect it manually.`;
+    deliverToLeader({ from: name, subject: "Worktree diff capture failed", body });
+    sendUpdate({
+      teammate: name,
+      origin: "harness",
+      harnessEvent: { type: "worktree-capture-failed", subject: `@${name} worktree diff capture failed` },
+      body,
+      finished: false,
+    });
+    return;
+  }
+  const changed = captured.diff.patch.trim().length > 0;
   deliverToLeader({
     from: name,
     subject: "Worktree diff captured",
-    body: `Teammate @${name}'s worktree diff:${patchNote}`,
+    body: changed
+      ? `Teammate @${name}'s worktree diff:\n\n=== Worktree changes ===\n${captured.diff.diffStat}\n\n${captured.diff.patch}`
+      : `Teammate @${name}'s worktree diff:\n(no worktree changes)`,
   });
+  // Changed work must reach the leader even though the worktree directory is
+  // gone: dispatch a bounded preview plus the branch retrieval command. A
+  // clean worktree carries no information and stays log-only.
+  if (changed) {
+    sendUpdate({
+      teammate: name,
+      spawnId: getTeammate(name)?.spawnId,
+      origin: "harness",
+      harnessEvent: { type: "worktree-changes", subject: `@${name} worktree changes captured` },
+      body: [
+        `Worktree changes captured for @${name} (${captured.diff.diffStat.trim() || "diff"}).`,
+        "",
+        truncated(captured.diff.patch),
+        "",
+        `Full diff: git diff ${handle.baseCommit}..${handle.branch}`,
+      ].join("\n"),
+      finished: false,
+    });
+  }
+  if (!cleaned.ok) {
+    const subject = cleaned.error?.includes("worktree left in place") ? "Worktree cleanup aborted" : "Worktree cleanup issue";
+    const body = `Cleaning up @${name}'s worktree reported problems (${cleaned.error ?? "unknown cleanup failure"}).`;
+    deliverToLeader({ from: name, subject, body });
+    sendUpdate({
+      teammate: name,
+      origin: "harness",
+      harnessEvent: { type: "worktree-cleanup-failed", subject: `@${name} worktree cleanup issue` },
+      body,
+      finished: false,
+    });
+  }
 }
 
 // ── Report outbox draining ────────────────────────────────────────
@@ -620,8 +1049,33 @@ function applyOutboxRecord(teammate: Teammate, record: unknown): boolean {
   if (!isWorkerEvent(record)) return false;
   if (record.worker !== teammate.name || record.spawnId !== teammate.spawnId) return false;
   const ids = getState().workerEventIds;
-  if (ids[`${teammate.spawnId}:${record.id}`]) return false;
-  ids[`${teammate.spawnId}:${record.id}`] = teammate.spawnId;
+  const eventKey = `${teammate.spawnId}:${record.id}`;
+  if (ids[eventKey]) return false;
+  ids[eventKey] = teammate.spawnId;
+  markStateDirty();
+
+  if (teammate.reportSequenceEnded) return false;
+  const archived = pendingShutdowns.has(teammate.name);
+  const terminal = record.status === "completed" || record.status === "failed";
+  if (terminal) {
+    const assignment = teammate.assignment;
+    if (assignment?.kind === "direct") {
+      assignTeammate(teammate.name, { ...assignment, closed: true }, undefined);
+    }
+    updateTeammate(teammate.name, {
+      reportSequenceEnded: true,
+      status: "idle",
+      activeTool: undefined,
+      sequenceEnded: true,
+    });
+    if (assignment?.kind === "board" && teammate.currentTaskId) {
+      deliverFeedback(
+        teammate.name,
+        "Board task still open",
+        `Your terminal leader report does not complete board task "${teammate.currentTaskId}". Submit it with task_submit, or submit failed to release it.`,
+      );
+    }
+  }
   receiveWorkerMessage({
     id: record.id,
     type: "message",
@@ -629,17 +1083,25 @@ function applyOutboxRecord(teammate: Teammate, record: unknown): boolean {
     spawnId: teammate.spawnId,
     body: record.body,
     status: record.status,
-  });
-  if (record.status === "completed" || record.status === "failed") {
-    // The assignment ends; the resident itself stays alive until sequence end.
-    sendUpdate({
-      teammate: teammate.name,
-      agent: teammate.agent,
-      spawnId: teammate.spawnId,
-      body: record.body,
-      finished: true,
-    });
-  }
+    timestamp: record.timestamp,
+  }, { archived });
+  // Every accepted teammate-authored report reaches the leader's context as
+  // its own turn; terminal statuses additionally end the report sequence.
+  const finished = terminal;
+  const report = {
+    teammate: teammate.name,
+    agent: teammate.agent,
+    spawnId: teammate.spawnId,
+    body: record.body,
+    origin: "teammate" as const,
+    eventId: record.id,
+    status: record.status,
+    timestamp: record.timestamp ?? Date.now(),
+    finished,
+    ...(archived ? { archived: true } : {}),
+  };
+  if (finished) recordTerminalReport(report);
+  sendUpdate(report);
   return true;
 }
 
@@ -680,10 +1142,14 @@ function parseInboxMessage(record: unknown): InboxMessage | undefined {
 }
 
 function dispatchInboxMessage(teammate: Teammate, message: InboxMessage): void {
-  const delivered = teammate.status === "working"
+  const routed = teammate.status === "working"
     ? sendWorkerSteer(teammate.name, formatDelivery([message]))
     : false;
-  if (delivered) return;
+  if (routed) {
+    setPeerDeliveryState(message.id, "routed");
+    return;
+  }
+  setPeerDeliveryState(message.id, "queued");
   const queued = pendingDeliveries.get(teammate.name) ?? [];
   queued.push(message);
   pendingDeliveries.set(teammate.name, queued);
@@ -691,9 +1157,76 @@ function dispatchInboxMessage(teammate: Teammate, message: InboxMessage): void {
 }
 
 /** Route the leader's addressed send_message through the same delivery path. */
-export function sendLeaderMessage(to: string, message: string): { ok: true; queued: boolean; stalledMs?: number } | { ok: false; error: string } {
+export type MessageRoutingOutcome = "steered" | "queued";
+
+export type SendLeaderMessageResult =
+  | { ok: true; outcome: MessageRoutingOutcome; priorTerminalReport?: string }
+  | { ok: true; outcome: "not-sent"; terminalReport: string }
+  | { ok: false; error: string };
+
+/** Body of the teammate's recorded terminal report, when its latest leader
+ * mailbox entry carries terminal status. Lets the leader read the report
+ * directly instead of steering the teammate into a duplicate resend. */
+function recordedTerminalReportBody(name: string): string | undefined {
+  const mailbox = getState().leaderMailbox;
+  for (let i = mailbox.length - 1; i >= 0; i--) {
+    const message = mailbox[i];
+    if (message.from !== name) continue;
+    return message.status === "completed" || message.status === "failed" ? message.body : undefined;
+  }
+  return undefined;
+}
+
+export function sendLeaderMessage(
+  to: string,
+  message: string,
+  options?: { reopen?: boolean; resources?: string[] },
+): SendLeaderMessageResult {
   const teammate = getTeammate(to);
   if (!teammate || teammate.status === "stopped") return { ok: false, error: `No living teammate named "${to}".` };
+  if (teammate.assignment?.kind === "direct" && teammate.assignment.closed && !options?.reopen) {
+    const prior = recordedTerminalReportBody(to);
+    if (prior) return { ok: true, outcome: "not-sent", terminalReport: prior };
+    return { ok: false, error: `@${to} has a closed direct assignment. Use reopen=true for an explicit next assignment.` };
+  }
+  // A board holder keeps its task after a terminal report. The leader must be
+  // able to steer it for verify feedback or an inconclusive decision without
+  // replacing its assignment.
+  const activeBoardHolder = teammate.assignment?.kind === "board" && !teammate.assignment.closed;
+  if (teammate.reportSequenceEnded && !options?.reopen && !activeBoardHolder) {
+    const prior = recordedTerminalReportBody(to);
+    if (prior) return { ok: true, outcome: "not-sent", terminalReport: prior };
+    return { ok: false, error: `@${to} already sent a terminal report. Use teammate_spawn for a new assignment or send_message with reopen=true for an explicit follow-up assignment.` };
+  }
+  const priorTerminalReport = teammate.reportSequenceEnded ? recordedTerminalReportBody(to) : undefined;
+  const boardParkKey = teammate.currentTaskId ? `${teammate.currentTaskId}:${teammate.spawnId}` : undefined;
+  if (options?.reopen && teammate.assignment && !teammate.assignment.closed) {
+    const action = teammate.assignment.kind === "board"
+      ? `task_submit or be released/superseded`
+      : "send a terminal report or be explicitly released";
+    return { ok: false, error: `@${to} still owns active ${teammate.assignment.kind} assignment "${teammate.assignment.id}". It must ${action} before a direct assignment can open.` };
+  }
+  const opensDirectAssignment = options?.reopen || teammate.assignment === undefined;
+  if (opensDirectAssignment) {
+    const resources = normalizeResources(options?.resources);
+    const conflict = activeAssignmentConflict(resources, to);
+    if (conflict) {
+      return { ok: false, error: `Direct assignment resources conflict with @${conflict.name}'s ${conflict.assignment?.kind} assignment "${conflict.assignment?.id}".` };
+    }
+    assignTeammate(to, {
+      id: `direct:${randomUUID()}`,
+      kind: "direct",
+      resources,
+    }, undefined);
+    updateTeammate(to, { reportSequenceEnded: false });
+  }
+  // A successfully accepted leader message is the explicit direction that
+  // unblocks a twice-inconclusive board holding; rejected reopen does nothing.
+  if (boardParkKey) {
+    inconclusiveParks.delete(boardParkKey);
+    verifyFailureParks.delete(boardParkKey);
+  }
+  if (activeBoardHolder) updateTeammate(to, { reportSequenceEnded: false });
   const envelope: InboxMessage = {
     id: randomUUID(),
     from: "leader",
@@ -701,19 +1234,13 @@ export function sendLeaderMessage(to: string, message: string): { ok: true; queu
     body: message,
     timestamp: Date.now(),
   };
-  const delivered = teammate.status === "working" && sendWorkerSteer(teammate.name, formatDelivery([envelope]));
-  if (delivered) {
-    // A control-stream write succeeds even when the child never reads it;
-    // surface prolonged silence so the leader knows delivery is uncertain.
-    const stalled = isStallThresholdReached(teammate, Date.now(), STALL_NOTICE_MS);
-    const silence = stallSilenceMs(teammate);
-    return { ok: true, queued: false, ...(stalled && silence !== undefined ? { stalledMs: silence } : {}) };
-  }
+  const steered = teammate.status === "working" && sendWorkerSteer(teammate.name, formatDelivery([envelope]));
+  if (steered) return { ok: true, outcome: "steered", ...(priorTerminalReport ? { priorTerminalReport } : {}) };
   const queued = pendingDeliveries.get(teammate.name) ?? [];
   queued.push(envelope);
   pendingDeliveries.set(teammate.name, queued);
   ensureLivePoll();
-  return { ok: true, queued: true };
+  return { ok: true, outcome: "queued", ...(priorTerminalReport ? { priorTerminalReport } : {}) };
 }
 
 function continueMaybeCompact(inbox: string, inboxName: string, offset: number): void {
@@ -770,22 +1297,69 @@ function applyClaimMarker(intent: import("./types").TaskIntent): void {
   if (!sender) return;
   const outcome = applyClaimIntent(intent);
   if (outcome.applied) {
+    verifyFailures.delete(`${intent.taskId}:${intent.spawnId}`);
+    clearInconclusiveForHolding(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 });
+    deliverFeedback(
+      intent.worker,
+      "Claim accepted",
+      `Your claim for task "${intent.taskId}" was accepted. You now own the board assignment and may start work; complete it with task_submit.`,
+    );
     return;
   }
   deliverFeedback(intent.worker, "Claim rejected", outcome.reason ?? "The task is no longer available.");
 }
 
 function applySubmissionMarker(intent: import("./types").TaskIntent): void {
+  if (intent.status !== "completed" && intent.status !== "failed") {
+    deliverFeedback(intent.worker, "Submission rejected", `Task "${intent.taskId}" has an invalid submission status.`);
+    return;
+  }
   const sender = findLivingTeammate(intent);
   if (!sender) return;
   const task = getState().tasks[intent.taskId];
-  if (!task || task.status !== "claimed" || task.claimedBy !== intent.worker) {
+  if (!task || (task.status !== "claimed" && task.status !== "superseded") || task.claimedBy !== intent.worker) {
     deliverFeedback(intent.worker, "Submission rejected", `Task "${intent.taskId}" is not currently yours.`);
     return;
   }
+  if (task.status === "superseded") {
+    if (intent.status !== "failed") {
+      deliverFeedback(intent.worker, "Submission rejected", `Task "${intent.taskId}" was superseded by "${task.supersededBy ?? "a replacement"}". Stop work and submit failed to acknowledge cancellation.`);
+      return;
+    }
+    releaseTask(intent.taskId, intent.result?.trim() || "Superseded task cancellation acknowledged.");
+    clearInconclusiveForHolding(intent.taskId, intent.spawnId);
+    verifyingTasks.delete(intent.taskId);
+    return;
+  }
+  const parkKey = `${intent.taskId}:${intent.spawnId}`;
+  if (intent.status === "completed" && (inconclusiveParks.has(parkKey) || verifyFailureParks.has(parkKey))) {
+    const reason = inconclusiveParks.has(parkKey)
+      ? "two inconclusive reviews"
+      : "two explicit verification failures";
+    deliverFeedback(
+      intent.worker,
+      "Submission rejected while verification is parked",
+      `Task "${intent.taskId}" has ${reason}. Wait for an explicit leader steer before submitting another completed outcome.`,
+    );
+    return;
+  }
+  if (intent.status === "completed" && verifyingTasks.has(intent.taskId)) {
+    deliverFeedback(
+      intent.worker,
+      "Submission rejected while verification is running",
+      `Task "${intent.taskId}" already has a completion review or verdict clarification in flight. Wait for it to pass, fail, or become inconclusive before submitting another completed outcome.`,
+    );
+    return;
+  }
   if (intent.status === "failed") {
     releaseTask(intent.taskId, intent.result?.trim() || "Teammate reported failure.");
+    verifyFailures.delete(`${intent.taskId}:${intent.spawnId}`);
+    clearInconclusiveForHolding(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 +1367,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 +1385,142 @@ 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 submissionId = `${intent.taskId}:${intent.spawnId}:${randomUUID()}`;
+  const token = randomUUID();
+  verifyingTasks.set(intent.taskId, { worker: intent.worker, spawnId: intent.spawnId, submissionId, token });
+  const input: VerifyReviewInput = {
+    verify,
+    taskSubject: task.subject,
+    workerResult: intent.result ?? "",
+    cwd: getTeammate(intent.worker)?.cwd || leaderCwd,
+  };
+  // A reviewer crash is a concrete failed gate. A missing verdict is handled
+  // separately as inconclusive so prose-format drift cannot count as a defect.
+  Promise.resolve()
+    .then(() => verifyGateRunner(input))
+    .then((outcome) => resolveGateOutcome(intent, task.subject, submissionId, token, outcome))
+    .catch((error) => resolveGateOutcome(intent, task.subject, submissionId, token, {
+      kind: "fail",
+      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,
+  submissionId: string,
+  token: string,
+  outcome: VerifyReviewOutcome,
+): void {
+  const active = verifyingTasks.get(intent.taskId);
+  if (active?.token !== token || active.submissionId !== submissionId) 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.kind === "pass") {
+    inconclusiveVerifications.delete(submissionId);
+    finishCompletion(intent, subject);
+  } else if (outcome.kind === "inconclusive") {
+    const detail = outcome.detail ?? "(reviewer omitted a machine-readable verdict)";
+    requestVerifyVerdict(intent, subject, submissionId, detail);
+  } else {
+    inconclusiveVerifications.delete(submissionId);
+    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.
+      verifyFailureParks.set(`${intent.taskId}:${intent.spawnId}`, { worker: intent.worker, spawnId: intent.spawnId });
+      if (reaction.escalateToLeader) {
+        notifyTaskOutcome(subject, `verify failed ${reaction.count} times for ${intent.taskId}: manual attention needed`, detail);
+        // The holder is parked and will not narrate further; the parked task
+        // reaches the leader through the delivery channel itself.
+        sendUpdate({
+          teammate: "task-board",
+          origin: "harness",
+          harnessEvent: { type: "verify-escalation", subject: `Verify gate failed · ${subject}` },
+          body: `Verify gate for "${subject}" (${intent.taskId}) failed ${reaction.count} consecutive times.\n\n${detail}\n\nThe task stays claimed by @${intent.worker}; decide how to proceed.`,
+          finished: false,
+        });
       }
-      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 requestVerifyVerdict(
+  intent: import("./types").TaskIntent,
+  subject: string,
+  submissionId: string,
+  detail: string,
+): void {
+  const attempts = inconclusiveVerifications.get(submissionId) ?? 0;
+  if (attempts === 0) {
+    inconclusiveVerifications.set(submissionId, 1);
+    const task = getState().tasks[intent.taskId];
+    if (!task) return;
+    const token = randomUUID();
+    verifyingTasks.set(intent.taskId, { worker: intent.worker, spawnId: intent.spawnId, submissionId, token });
+    const input: VerifyReviewInput = {
+      verify: `${task.verify ?? resolveAgent(getTeammate(intent.worker)?.agent ?? "", leaderCwd)?.verify ?? ""}\n\nThe previous review was inconclusive:\n${detail}\n\nReply with exactly one line: ${VERIFY_VERDICT_PASS} or ${VERIFY_VERDICT_FAIL} - <reasons>.`,
+      taskSubject: task.subject,
+      workerResult: intent.result ?? "",
+      cwd: getTeammate(intent.worker)?.cwd || leaderCwd,
+    };
+    Promise.resolve()
+      .then(() => verifyGateRunner(input))
+      .then((outcome) => resolveGateOutcome(intent, subject, submissionId, token, outcome))
+      .catch((error) => resolveGateOutcome(intent, subject, submissionId, token, {
+        kind: "fail",
+        detail: truncated(`(verdict clarification crashed) ${error instanceof Error ? error.message : String(error)}`),
+      }));
+    return;
+  }
+  inconclusiveParks.set(`${intent.taskId}:${intent.spawnId}`, { worker: intent.worker, spawnId: intent.spawnId });
+  notifyTaskOutcome(subject, `verify inconclusive for ${intent.taskId}: manual verdict needed`, detail);
+  deliverFeedback(
+    intent.worker,
+    `Verification inconclusive for ${intent.taskId}`,
+    `The reviewer twice omitted a machine-readable verdict. Your task remains claimed without a verify failure. Wait for leader direction; after a directed fix or clarified outcome, you may submit a new completed result for a fresh review.\n\n${detail}`,
+  );
+  sendUpdate({
+    teammate: "task-board",
+    origin: "harness",
+    harnessEvent: { type: "verify-inconclusive", subject: `Verify verdict missing · ${subject}` },
+    body: `Verification for "${subject}" (${intent.taskId}) was inconclusive twice. It remains claimed by @${intent.worker} without counting as a verify failure.\n\n${detail}`,
+    finished: false,
+  });
+}
+
+function clearInconclusiveForHolding(taskId: string, spawnId: string): void {
+  const prefix = `${taskId}:${spawnId}:`;
+  for (const key of inconclusiveVerifications.keys()) {
+    if (key.startsWith(prefix)) inconclusiveVerifications.delete(key);
+  }
+  inconclusiveParks.delete(`${taskId}:${spawnId}`);
+  verifyFailureParks.delete(`${taskId}:${spawnId}`);
 }
 
 function finishCompletion(intent: import("./types").TaskIntent, subject: string): void {
@@ -831,21 +1528,99 @@ 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}`);
+  clearInconclusiveForHolding(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 =
+  | { kind: "pass" }
+  | { kind: "fail"; detail?: string }
+  | { kind: "inconclusive"; 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 { kind: "pass" };
+    const failMatch = /^verdict:\s*fail\b[\s:-]*(.*)$/i.exec(candidate);
+    if (failMatch) {
+      return { kind: "fail", detail: truncated(failMatch[1].trim()) || "(no reasons given)" };
+    }
+  }
+  return {
+    kind: "inconclusive",
+    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 { kind: "fail", 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,30 +1643,87 @@ 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();
+export function wakeIdleTeammates(immediateTaskId?: string): string[] {
+  const notified: string[] = [];
   for (const teammate of idleTeammates()) {
     const deliveries = pendingDeliveries.get(teammate.name) ?? [];
-    const dueNotice = claimable.length > 0 && noticeDue(teammate);
+    // A terminal direct assignment stays closed until explicit reopen; a board
+    // holder must submit rather than drifting into more board work.
+    const boardEligible = teammate.assignment === undefined;
+    const fresh = boardEligible
+      ? freshClaimableTasks(teammate.noticedTaskIds, claimableTasks().filter((task) => !activeAssignmentConflict(task.resources, teammate.name)))
+      : [];
+    const immediateNotice = immediateTaskId !== undefined && fresh.some((task) => task.id === immediateTaskId);
+    const dueNotice = fresh.length > 0 && (immediateNotice || noticeDue(teammate));
     if (deliveries.length === 0 && !dueNotice) continue;
-    const prompt = buildWakePrompt(deliveries, claimable, dueNotice);
+    const prioritized = immediateTaskId === undefined
+      ? fresh
+      : [
+          ...fresh.filter((task) => task.id === immediateTaskId),
+          ...fresh.filter((task) => task.id !== immediateTaskId),
+        ];
+    const noticed = prioritized.slice(0, WAKE_NOTICE_TASK_LIMIT);
+    const prompt = buildWakePrompt(deliveries, noticed, dueNotice);
     if (!deliverPrompt(teammate.name, prompt)) continue;
+    for (const delivery of deliveries) setPeerDeliveryState(delivery.id, "routed");
+    notified.push(teammate.name);
     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, {
       status: "working",
       sequenceEnded: false,
+      // A generic peer/harness/board wake-up never opens a terminal direct
+      // assignment. Only leader send_message(reopen=true) owns that transition.
+      ...(teammate.assignment?.kind === "direct" && teammate.assignment.closed
+        ? {}
+        : { reportSequenceEnded: false }),
       lastOutputAt: Date.now(),
       stallNoticeSentAt: undefined,
       ...(dueNotice ? { lastNoticeAt: Date.now() } : {}),
     });
   }
+  return notified;
 }
 
 function noticeDue(teammate: Teammate): boolean {
@@ -921,17 +1753,91 @@ function formatDelivery(messages: InboxMessage[]): string {
 
 // ── Board helpers shared with tools.ts ────────────────────────────
 
+export interface BoardTaskCreationResult {
+  ok: true;
+  id: string;
+  notifiedTeammates: string[];
+  livingTeammates: number;
+  claimable: boolean;
+  resourceBlocked: boolean;
+  supersededTaskIds: string[];
+}
+
+export function formatBoardTaskCreation(subject: string, created: BoardTaskCreationResult): string {
+  const status = created.claimable ? "pending/claimable" : "pending/blocked";
+  const routing = created.notifiedTeammates.length > 0
+    ? `notified=${created.notifiedTeammates.map((name) => `@${name}`).join(",")}`
+    : created.livingTeammates === 0
+      ? "notified=none (no living teammates)"
+      : "notified=none (no eligible idle teammate)";
+  const superseded = (created.supersededTaskIds ?? []).length > 0
+    ? `SUPERSEDED · ${created.supersededTaskIds.join(", ")}`
+    : undefined;
+  const next = !created.claimable
+    ? created.resourceBlocked
+      ? "NEXT · waits for superseded holder or resource owner to release"
+      : "NEXT · waits for dependencies"
+    : created.livingTeammates === 0
+      ? "NEXT · leader: teammate_spawn"
+      : "NEXT · worker: task_claim";
+  return [
+    `BOARD · current session`,
+    `CREATED · ${created.id} · ${status} · ${subject}`,
+    `ROUTING · ${routing}`,
+    superseded,
+    next,
+  ].join("\n");
+}
+
+/** Create a task and synchronously offer it to currently-idle teammates.
+ *
+ * The normal poll loop still handles later dependency unlocks and queued mail,
+ * but task creation is a user-visible boundary: an idle teammate should not
+ * have to wait for a future timer tick before it can see newly-created work.
+ */
 export function createBoardTask(input: {
   subject: string;
   description?: string;
   dependsOn?: string[];
   verify?: string;
-}): { ok: true; id: string } | { ok: false; error: string } {
+  resources?: string[];
+  supersedes?: string[];
+}): BoardTaskCreationResult | { ok: false; error: string } {
   const created = createTask(input);
   if (!created.ok) return created;
+  for (const task of created.superseded) {
+    // A superseded holder intentionally retains its assignment/resource until
+    // it submits failed or stops; tell it to cease writes immediately.
+    if (task.claimedBy) {
+      deliverFeedback(
+        task.claimedBy,
+        `Task superseded: ${task.id}`,
+        `Task "${task.id}" was superseded by "${created.task.id}". Stop work immediately and task_submit with status="failed" to acknowledge cancellation and release its resources.`,
+      );
+    }
+    verifyingTasks.delete(task.id);
+    for (const key of [...verifyFailures.keys()]) {
+      if (key.startsWith(`${task.id}:`)) verifyFailures.delete(key);
+    }
+    for (const key of [...inconclusiveVerifications.keys()]) {
+      if (key.startsWith(`${task.id}:`)) inconclusiveVerifications.delete(key);
+    }
+    rearmTaskNotice(task.id);
+  }
+  publishStateSnapshot();
+  const resourceBlocked = activeAssignmentConflict(created.task.resources) !== undefined;
+  const notifiedTeammates = wakeIdleTeammates(created.task.id);
   publishStateSnapshot();
   notifyChange();
-  return { ok: true, id: created.task.id };
+  return {
+    ok: true,
+    id: created.task.id,
+    notifiedTeammates,
+    livingTeammates: livingTeammates().length,
+    claimable: claimableTasks().some((task) => task.id === created.task.id) && !resourceBlocked,
+    resourceBlocked,
+    supersededTaskIds: created.superseded.map((task) => task.id),
+  };
 }
 
 export function boardOverview(): Array<import("./types").BoardTask> {