pi-extended-teams 2.2.9 → 2.3.0

package/extensions/team/session-cost.ts

@@ -0,0 +1,155 @@
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+export const COST_ENTRY_TYPE = "pi-extended-teams-cost-v1";
+export type CostOutcome = "completed" | "failed" | "cancelled";
+export interface AgentCostSnapshot { childSessionId: string; costUsd: number | null }
+export interface CostRun {
+  settle(snapshot: AgentCostSnapshot | undefined, outcome: CostOutcome): void;
+  exclude(): void;
+}
+interface Receipt {
+  rootSessionId: string;
+  teamName: string;
+  lifecycleRunId: string;
+  phase: "pending" | "final" | "excluded";
+  childSessionId?: string;
+  costUsd?: number | null;
+  outcome?: CostOutcome;
+}
+const object = (value: unknown): Record<string, unknown> =>
+  value !== null && typeof value === "object" ? value as Record<string, unknown> : {};
+const validCost = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value >= 0;
+const identity = (receipt: Receipt) => JSON.stringify([receipt.rootSessionId, receipt.teamName, receipt.lifecycleRunId]);
+
+export function recordedSessionCost(entries: readonly unknown[]): { usd: number; complete: boolean } {
+  let usd = 0;
+  let complete = true;
+  for (const item of entries) {
+    const entry = object(item);
+    const message = object(entry.message);
+    const summary = entry.type === "compaction" || entry.type === "branch_summary";
+    const assistant = entry.type === "message" && message.role === "assistant";
+    const tool = entry.type === "message" && message.role === "toolResult";
+    if (!summary && !assistant && !tool) continue;
+    const usage = summary ? entry.usage : message.usage;
+    if (tool && usage === undefined) continue; // Optional native nested-tool accounting.
+    const cost = object(object(usage).cost).total;
+    if (validCost(cost) && validCost(usd + cost)) usd += cost;
+    else complete = false; // Includes legacy summaries without recorded usage.
+  }
+  return { usd, complete };
+}
+
+export function createCombinedSessionCost(pi: Pick<ExtensionAPI, "on" | "appendEntry" | "events">) {
+  let scope: { root: string; ctx: ExtensionContext; failed: Set<string>; pending: Map<string, Receipt> } | undefined;
+  const receipts = (entries: readonly unknown[]) => {
+    const runs = new Map<string, Receipt>();
+    let complete = true;
+    for (const item of entries) {
+      const entry = object(item);
+      if (entry.type !== "custom" || entry.customType !== COST_ENTRY_TYPE) continue;
+      const data = object(entry.data);
+      if (![data.rootSessionId, data.teamName, data.lifecycleRunId].every(value => typeof value === "string" && value.length > 0)
+        || !["pending", "final", "excluded"].includes(String(data.phase))
+        || (data.phase === "final" && (!["completed", "failed", "cancelled"].includes(String(data.outcome))
+          || !(data.costUsd === null || (validCost(data.costUsd) && typeof data.childSessionId === "string" && data.childSessionId.length > 0))))) {
+        complete = false;
+        continue;
+      }
+      const receipt = data as unknown as Receipt;
+      const key = identity(receipt);
+      if (!runs.has(key) || runs.get(key)?.phase === "pending") runs.set(key, receipt);
+    }
+    return { runs, complete };
+  };
+  const total = () => {
+    try {
+      if (!scope || scope.ctx.sessionManager.getSessionId() !== scope.root) return { usd: 0, complete: false };
+      const entries = scope.ctx.sessionManager.getEntries();
+      const own = recordedSessionCost(entries);
+      const replay = receipts(entries);
+      let complete = own.complete && replay.complete && scope.failed.size === 0;
+      let usd = own.usd;
+      const sessions = new Set([scope.root]);
+      for (const [key, receipt] of new Map([...replay.runs, ...scope.pending])) {
+        if (receipt.phase === "excluded") continue;
+        if (scope.failed.has(key) || receipt.phase !== "final" || !validCost(receipt.costUsd) || !receipt.childSessionId) {
+          complete = false;
+          continue;
+        }
+        if (sessions.has(receipt.childSessionId)) continue;
+        sessions.add(receipt.childSessionId);
+        if (validCost(usd + receipt.costUsd)) usd += receipt.costUsd;
+        else complete = false;
+      }
+      return { usd, complete };
+    } catch { return { usd: 0, complete: false }; }
+  };
+  let displayTotal: ReturnType<typeof recordedSessionCost> | undefined;
+  // Synchronous display-only query: native usage and durable receipts stay untouched.
+  const unsubscribe = pi.events.on("pi-extended-teams:cost-request", (value) => {
+    const request = object(value);
+    if (scope && request.sessionId === scope.root && scope.ctx.sessionManager.getSessionId() === scope.root) {
+      request.result = displayTotal;
+    }
+  });
+  const refresh = () => {
+    displayTotal = scope ? total() : undefined;
+    try { pi.events.emit("pi-extended-teams:cost-changed", undefined); }
+    catch { /* Display observers must not affect lifecycle cleanup. */ }
+  };
+  pi.on("session_start", (_event, ctx) => {
+    scope = { root: ctx.sessionManager.getSessionId(), ctx, failed: new Set(), pending: new Map() };
+    refresh();
+  });
+  pi.on("turn_end", refresh);
+  pi.on("agent_end", refresh);
+  pi.on("session_compact", refresh);
+  pi.on("session_tree", refresh);
+  return {
+    total,
+    deactivate() {
+      scope = undefined;
+      unsubscribe();
+      refresh();
+    },
+    begin(rootSessionId: string, teamName: string, lifecycleRunId: string): CostRun {
+      const origin = scope;
+      if (!origin || origin.root !== rootSessionId) return { settle() {}, exclude() {} };
+      const pending: Receipt = { rootSessionId, teamName, lifecycleRunId, phase: "pending" };
+      const key = identity(pending);
+      const active = () => scope === origin && origin.ctx.sessionManager.getSessionId() === rootSessionId;
+      const append = (receipt: Receipt) => {
+        try {
+          if (!active()) return false;
+          pi.appendEntry(COST_ENTRY_TYPE, receipt);
+          origin.failed.delete(key);
+          origin.pending.delete(key);
+          refresh();
+          return true;
+        } catch {
+          origin.failed.add(key);
+          origin.pending.set(key, pending);
+          refresh();
+          return false;
+        }
+      };
+      try {
+        if (!receipts(origin.ctx.sessionManager.getEntries()).runs.has(key)) append(pending);
+      } catch { origin.failed.add(key); origin.pending.set(key, pending); refresh(); }
+      const finish = (receipt: Receipt) => {
+        try {
+          if (!active()) return;
+          const previous = origin.pending.get(key) ?? receipts(origin.ctx.sessionManager.getEntries()).runs.get(key);
+          if (previous?.phase !== "pending") return;
+          append(receipt);
+        } catch { origin.failed.add(key); refresh(); }
+      };
+      return {
+        settle: (snapshot, outcome) => finish({ ...pending, phase: "final", outcome,
+          childSessionId: snapshot?.childSessionId, costUsd: snapshot?.costUsd ?? null }),
+        exclude: () => finish({ ...pending, phase: "excluded" }),
+      };
+    },
+  };
+}

package/extensions/tools/agent-communication-tools.ts

@@ -4,16 +4,26 @@ import * as runtime from "../../src/utils/runtime";
 import * as claims from "../../src/utils/claims";
 import { formatInboxMessagesForModel, sanitizePlainTuiLine } from "../ui/renderers";
 import { createFileClaimTools } from "./file-claim-tools";
+import { normalizeReportedTaskDetails, ReportedTaskDetailsSchema, type ReportedTaskDetails, type ReportResult } from "../../src/results/report-result";
+import type { RepairRequest } from "../../src/results/verification-controller";
 
-export interface SubmittedAgentReport {
+export interface SubmittedAgentReport extends ReportedTaskDetails {
   content: string;
   summary?: string;
 }
 
-export interface AgentReportSubmissionResult {
-  accepted: boolean;
+export type AgentReportSubmissionResult = {
+  verification?: ReportResult["verification"];
   cancelledDeliveries?: number;
   deliveryOutcome?: "cancelled" | "none";
+} & ({ accepted: boolean; repairRequest?: never } | { accepted: false; repairRequest: RepairRequest });
+
+export function formatRepairRequest(request: RepairRequest): string {
+  return [
+    `Final report not accepted. Repair attempt ${request.attempt} is reserved (${request.id}).`,
+    "Use the observed failures below to repair only your assigned scope. Do not add checks or broaden side effects. If you cannot repair safely, report blocked or failed. Submit a new complete report when done; do not exit yet.",
+    ...request.checks.map(check => `${check.assignment.name}: ${check.state}; exit ${check.exitCode ?? "unknown"}; full log: ${check.logPath}${check.error ? `; ${check.error}` : ""}`),
+  ].join("\n");
 }
 
 export interface AgentCommunicationToolsOptions {
@@ -24,7 +34,8 @@ export interface AgentCommunicationToolsOptions {
   getLifecycleRunId(): string | undefined;
   authorizeWriteMember(teamName: string, agentName: string): Promise<void>;
   onProgress?(status: string, updatedAt: number): void;
-  onReportAndExit(report: SubmittedAgentReport): Promise<AgentReportSubmissionResult>;
+  repairEnabled?: boolean;
+  onReportAndExit(report: SubmittedAgentReport, signal?: AbortSignal, submissionId?: string): Promise<AgentReportSubmissionResult>;
 }
 
 function requireCurrentSession(options: Pick<AgentCommunicationToolsOptions, "getTeamName">): string {
@@ -139,17 +150,20 @@ export function createAgentCommunicationTools(options: AgentCommunicationToolsOp
   const reportAndExitTool = {
     name: "report_and_exit",
     label: "Report and Exit",
-    description: "Submit the complete final report to the lead and finish this nested agent run.",
+    description: options.repairEnabled
+      ? "Submit the complete report for verification. If repair is requested, stay in this run and follow the returned feedback; finish only after acceptance."
+      : "Submit the complete final report to the lead and finish this nested agent run.",
     parameters: Type.Object({
       content: Type.String({ minLength: 1, description: "Complete non-empty final report to send to the lead; do not replace required output with a summary." }),
       summary: Type.Optional(Type.String({ description: "Short report summary." })),
+      ...ReportedTaskDetailsSchema.properties,
     }),
-    async execute(_toolCallId: string, params: SubmittedAgentReport) {
+    async execute(_toolCallId: string, params: SubmittedAgentReport, signal?: AbortSignal) {
       const teamName = requireCurrentSession(options);
       const content = normalizeFinalReportContent(params.content);
       const summary = typeof params.summary === "string" && params.summary.trim() ? params.summary.trim() : undefined;
-      const result = await options.onReportAndExit({ content, summary });
-      const text = result.accepted
+      const result = await options.onReportAndExit({ content, summary, ...normalizeReportedTaskDetails(params) }, signal, _toolCallId);
+      const text = result.repairRequest ? formatRepairRequest(result.repairRequest) : result.accepted
         ? "Final report accepted. Finish immediately; the outer runner will release claims and stop this nested session."
         : "A final report was already accepted for this run. This duplicate was ignored; finish immediately.";
       return {
@@ -157,6 +171,8 @@ export function createAgentCommunicationTools(options: AgentCommunicationToolsOp
         details: {
           session: teamName,
           accepted: result.accepted,
+          ...(result.verification ? { verification: result.verification } : {}),
+          ...(result.repairRequest ? { repairRequest: result.repairRequest } : {}),
           ...(result.cancelledDeliveries === undefined ? {} : {
             cancelledDeliveries: result.cancelledDeliveries,
             deliveryOutcome: result.deliveryOutcome,

package/extensions/tools/agent-status-tool.ts

@@ -2,9 +2,11 @@ import { Type } from "@sinclair/typebox";
 import * as teams from "../../src/utils/teams";
 import * as runtime from "../../src/utils/runtime";
 import * as reportEvents from "../../src/utils/report-events";
-import { readLifecycleTombstone } from "../../src/utils/lifecycle-tombstone";
-import { projectAgentStatus, type ActiveAgentPhase } from "../../src/orchestration/status-projection";
+import { listLifecycleTombstones, readLifecycleTombstone } from "../../src/utils/lifecycle-tombstone";
+import { projectAgentStatus, projectLifecycleFence, type ActiveAgentPhase } from "../../src/orchestration/status-projection";
 import type { Member, TeamReportEvent } from "../../src/utils/models";
+import { createReportResult, effectiveTaskOutcome, type ReportResult } from "../../src/results/report-result";
+import { VerificationController } from "../../src/results/verification-controller";
 import type { RunningReadAgent } from "../runtime/types";
 import { isWriteMemberAlive } from "../team/roster";
 import { formatElapsed } from "../ui/renderers";
@@ -30,6 +32,7 @@ export interface AgentStatusScope {
 
 export interface AgentStatusSnapshot {
   name: string;
+  runId?: string;
   role: string;
   phase: AgentStatusPhase;
   progress?: string;
@@ -40,6 +43,13 @@ export interface AgentStatusSnapshot {
   queuePosition?: number;
   queuedAgeMs?: number;
   completedAgeMs?: number;
+  taskId?: string;
+  reportId?: string;
+  outcome?: ReportResult["outcome"];
+  effectiveOutcome?: ReportResult["outcome"];
+  repair?: ReportResult["repair"];
+  verification?: ReportResult["verification"]["state"];
+  acceptance?: ReportResult["acceptance"]["state"];
   summary?: string;
   error?: string;
 }
@@ -85,6 +95,7 @@ async function activeStatus(
   member: Member,
   options: AgentStatusToolOptions,
   now: number,
+  report?: TeamReportEvent,
 ): Promise<AgentStatusSnapshot> {
   const candidateState = options.runningReadAgents.get(options.readAgentKey(teamName, member.name));
   const [candidateRuntimeStatus, lifecycleResult] = await Promise.all([
@@ -102,6 +113,9 @@ async function activeStatus(
   const { state, runtime: runtimeStatus } = projected;
   const progress = state?.latestProgress || runtimeStatus?.latestProgress;
   const progressUpdatedAt = state?.progressUpdatedAt || runtimeStatus?.progressUpdatedAt;
+  const result = report?.result ?? (member.lifecycleRunId
+    ? (await VerificationController.observe(teamName, createReportResult(teamName, member.name, member.lifecycleRunId, {}))).result
+    : undefined);
   return {
     name: member.name,
     role: member.role || state?.role || "read",
@@ -111,7 +125,17 @@ async function activeStatus(
     activeTool: state?.activeToolName || runtimeStatus?.activeToolName,
     activityAgeMs: age(now, state?.lastActivityAt),
     heartbeatAgeMs: age(now, runtimeStatus?.lastHeartbeatAt),
-    error: projected.error,
+    ...(result?.repair ? resultStatus(result) : {}),
+    error: projected.error ?? result?.verification.error,
+  };
+}
+
+function resultStatus(result: ReportResult) {
+  return {
+    taskId: result.taskId, runId: result.runId, reportId: result.reportId,
+    outcome: result.outcome, verification: result.verification.state, acceptance: result.acceptance.state,
+    error: result.verification.error,
+    ...(result.repair ? { repair: result.repair, effectiveOutcome: effectiveTaskOutcome(result) } : {}),
   };
 }
 
@@ -131,6 +155,7 @@ function completedStatus(report: TeamReportEvent, now: number): AgentStatusSnaps
     name: report.agentName,
     role: report.role || "read",
     phase: report.status,
+    ...(report.result ? resultStatus(report.result) : {}),
     completedAgeMs: age(now, report.createdAt),
     summary: report.summary,
   };
@@ -145,6 +170,7 @@ export function formatAgentStatusesForModel(statuses: AgentStatusSnapshot[]): st
 
   const blocks = statuses.map(status => {
     const lines = [`${status.name}: ${status.phase} (${status.role})`];
+    if (status.runId) lines.push(`  run: ${status.runId}`);
     if (status.progress) lines.push(`  progress: ${status.progress}${status.progressAgeMs === undefined ? "" : ` (${formatElapsed(status.progressAgeMs)} ago)`}`);
     if (status.activeTool) lines.push(`  tool: ${status.activeTool}`);
     const activity = formatAge("activity", status.activityAgeMs)
@@ -155,6 +181,8 @@ export function formatAgentStatusesForModel(statuses: AgentStatusSnapshot[]): st
     if (queued) lines.push(`  ${queued}`);
     const completed = formatAge(status.phase === "failed" ? "failed" : "completed", status.completedAgeMs);
     if (completed) lines.push(`  ${completed}`);
+    if (status.reportId) lines.push(`  task: ${status.outcome ?? "unspecified"}; verification: ${status.verification}; acceptance: ${status.acceptance}`);
+    if (status.repair) lines.push(`  repair: ${status.repair.state}; effective task: ${status.effectiveOutcome ?? "unspecified"}; ledger: ${status.repair.journalPath}`);
     if (status.summary) lines.push(`  summary: ${status.summary}`);
     if (status.error) lines.push(`  error: ${status.error}`);
     return lines.join("\n");
@@ -188,9 +216,24 @@ export function createAgentStatusTool(options: AgentStatusToolOptions): any {
       }).catch(() => []))
         .filter(report => ownsReport(report, options.scope));
 
-      const activeStatuses = await Promise.all(activeMembers.map(member => activeStatus(teamName, member, options, now)));
-      const queuedStatuses = queued.map(item => queuedStatus(item, now));
-      const currentNames = new Set([...activeStatuses, ...queuedStatuses].map(status => status.name));
+      const activeStatuses = await Promise.all(activeMembers.map(member => activeStatus(teamName, member, options, now,
+        reports.filter(report => report.agentName === member.name && report.result?.runId === member.lifecycleRunId).at(-1))));
+      // Orphan fences lack parent metadata; only the lead can inspect them.
+      const fencedStatuses: AgentStatusSnapshot[] = options.scope ? [] : (await listLifecycleTombstones(teamName))
+        .filter(({ agentName }) => !rosterNames.has(agentName))
+        .map(({ agentName, result }) => {
+          const pending = queued.find(item => item.name === agentName);
+          return {
+            ...(pending ? queuedStatus(pending, now) : {}),
+            name: agentName,
+            runId: result.status === "occupied" ? result.tombstone.runId : undefined,
+            role: result.status === "occupied" ? result.tombstone.role : pending?.role || "unknown",
+            ...projectLifecycleFence({}, result),
+          };
+        });
+      const fencedNames = new Set(fencedStatuses.map(status => status.name));
+      const queuedStatuses = queued.filter(item => !fencedNames.has(item.name)).map(item => queuedStatus(item, now));
+      const currentNames = new Set([...activeStatuses, ...fencedStatuses, ...queuedStatuses].map(status => status.name));
       const completedByName = new Map<string, TeamReportEvent>();
       for (const report of reports) {
         if (currentNames.has(report.agentName)) continue;
@@ -198,7 +241,7 @@ export function createAgentStatusTool(options: AgentStatusToolOptions): any {
         completedByName.set(report.agentName, report);
       }
       const completedStatuses = Array.from(completedByName.values()).slice(-20).map(report => completedStatus(report, now));
-      const statuses = [...activeStatuses, ...queuedStatuses, ...completedStatuses];
+      const statuses = [...activeStatuses, ...fencedStatuses, ...queuedStatuses, ...completedStatuses];
       const selected = params.agent_name
         ? statuses.filter(status => status.name === params.agent_name)
         : statuses;

package/extensions/tools/coordination-tools.ts

@@ -7,7 +7,15 @@ import * as messaging from "../../src/utils/messaging";
 import * as runtime from "../../src/utils/runtime";
 import * as claims from "../../src/utils/claims";
 import * as reportEvents from "../../src/utils/report-events";
+import { checkpointReference, saveReportCheckpoint, resyncReportCheckpoint } from "../../src/results/checkpoint-report";
+import { createReportResult, effectiveTaskOutcome, normalizeReportedTaskDetails, ReportedTaskDetailsSchema, type ReportResult } from "../../src/results/report-result";
 import { canonicalPersistedModelSlot } from "../../src/utils/settings";
+import { normalizeCheckPolicy } from "../../src/results/check-policy";
+import { VerificationController } from "../../src/results/verification-controller";
+import { deliverCompletionGroupReport } from "../../src/results/completion-group-delivery";
+import { formatRepairRequest } from "./agent-communication-tools";
+import type { CheckRunnerOptions } from "../../src/results/check-runner";
+import { loadNativeCheckOperations } from "../internal/pi-check-operations";
 import { createFileClaimTools } from "./file-claim-tools";
 import { formatInboxMessagesForModel, renderInboxMessages } from "../ui/renderers";
 import { unlinkPidFile } from "../internal/session-files";
@@ -33,6 +41,7 @@ export interface CoordinationToolsOptions {
   resetLeadWakeNotifiedCount(): void;
   deliverMessageToActiveAgent?(teamName: string, recipient: string, content: string): Promise<boolean>;
   extensionInstanceId?: string;
+  loadCheckOperations?: CheckRunnerOptions["loadOperations"];
 }
 
 export function buildReadHelperPrompt(teamName: string, requester: string, prompt: string): string {
@@ -53,9 +62,26 @@ function requireCurrentSession(options: CoordinationToolsOptions): string {
 
 export function registerCoordinationTools(pi: any, options: CoordinationToolsOptions): void {
   const extensionInstanceId = options.extensionInstanceId ?? generateExtensionInstanceId();
-  const pendingWriterFinalization = new Map<string, { teamName: string; agentName: string; runId: string }>();
+  const pendingWriterFinalization = new Map<string, { teamName: string; agentName: string; runId: string; checkpointId?: string }>();
+  const verifyingReports = new Set<string>();
+  const blockedReports = new Set<string>();
+  const pendingRepairs = new Map<string, { controller: VerificationController; result: ReportResult }>();
+  let repairCancellation: Promise<void> | undefined;
+  const cancelPendingRepairs = () => repairCancellation ??= (async () => {
+    for (const [reportId, { controller }] of pendingRepairs) {
+      try {
+        await controller.cancel();
+        pendingRepairs.delete(reportId);
+      } catch (error) {
+        blockedReports.add(reportId);
+        throw error;
+      }
+    }
+  })().finally(() => { repairCancellation = undefined; });
 
+  pi.on?.("agent_settled", cancelPendingRepairs);
   pi.on?.("session_shutdown", async () => {
+    await cancelPendingRepairs();
     const pending = Array.from(pendingWriterFinalization.values());
     for (const item of pending) {
       let cleared = false;
@@ -77,6 +103,11 @@ export function registerCoordinationTools(pi: any, options: CoordinationToolsOpt
             throw new Error(`Refusing to remove replacement runtime run ${currentRuntime.lifecycleRunId || "unknown"} of ${item.agentName}.`);
           }
 
+          if (item.checkpointId) {
+            const report = await reportEvents.readStoredTeamReportEvent(item.teamName, createReportResult(item.teamName, item.agentName, item.runId, {}).reportId);
+            if (report?.checkpoint?.id !== item.checkpointId) throw new Error("Checkpoint report provenance is unavailable.");
+            await resyncReportCheckpoint(report);
+          }
           const pidFile = path.join(paths.teamDir(item.teamName), `${item.agentName}.pid`);
           const pidFileExisted = fs.existsSync(pidFile);
           const pidFileUnlinked = unlinkPidFile(pidFile);
@@ -143,10 +174,12 @@ export function registerCoordinationTools(pi: any, options: CoordinationToolsOpt
     parameters: Type.Object({
       content: Type.String({ description: "Final report to send to the lead." }),
       summary: Type.Optional(Type.String({ description: "Short report summary." })),
+      ...ReportedTaskDetailsSchema.properties,
     }),
     async execute(_toolCallId: string, params: any, _signal: AbortSignal, _onUpdate: any, ctx: any) {
       const targetTeamName = requireCurrentSession(options);
       if (!options.isTeammate) throw new Error("report_and_exit is only available to spawned agents.");
+      const reported = normalizeReportedTaskDetails(params);
       if (process.env.PI_EXTENDED_TEAMS_HERDR_RESUME === "1" && !params.content.trim()) throw new Error("Final report content must not be empty.");
 
       const config = await teams.readConfig(targetTeamName);
@@ -158,6 +191,7 @@ export function registerCoordinationTools(pi: any, options: CoordinationToolsOpt
         throw new Error(`Refusing stale report run ${processRunId} for ${options.agentName}; current roster run is ${runId}.`);
       }
       member.lifecycleRunId = runId;
+      const result = createReportResult(targetTeamName, options.agentName, runId, reported);
       let runtimeStatus = await runtime.readRuntimeStatus(targetTeamName, options.agentName).catch(() => null);
       if (runtimeStatus?.lifecycleRunId && runtimeStatus.lifecycleRunId !== runId) {
         throw new Error(`Refusing to report from stale run ${runId}; runtime status belongs to ${runtimeStatus.lifecycleRunId}.`);
@@ -165,17 +199,40 @@ export function registerCoordinationTools(pi: any, options: CoordinationToolsOpt
       if (runtimeStatus && !runtimeStatus.lifecycleRunId) {
         runtimeStatus = await runtime.writeRuntimeStatus(targetTeamName, options.agentName, runId, {});
       }
+      const checks = normalizeCheckPolicy(member.assignedChecks);
+      if (repairCancellation) await repairCancellation;
+      if (blockedReports.has(result.reportId)) throw new Error("Final report verification is blocked by uncertain persistence for this run.");
+      if (verifyingReports.has(result.reportId)) throw new Error("Final report verification is already in progress for this run.");
+      const previous = pendingRepairs.get(result.reportId)?.result;
+      if (previous) Object.assign(result, { verification: previous.verification, repair: previous.repair });
+      const controller = new VerificationController({ teamName: targetTeamName, result, cwd: member.cwd, checks, repair: member.repairPolicy });
+      verifyingReports.add(result.reportId);
+      try {
+        const decision = await controller.verify(`tool:${_toolCallId}`, {
+          loadOperations: options.loadCheckOperations ?? loadNativeCheckOperations, signal: _signal,
+        }).catch(error => { blockedReports.add(result.reportId); throw error; });
+        Object.assign(result, decision.result);
+        if (decision.request) pendingRepairs.set(result.reportId, { controller, result: structuredClone(result) });
+        else pendingRepairs.delete(result.reportId);
+        if (checks?.length && _signal?.aborted) {
+          await controller.cancel().catch(error => { blockedReports.add(result.reportId); throw error; });
+          pendingRepairs.delete(result.reportId);
+          throw new Error("Assigned check verification was cancelled.");
+        }
+        if (result.verification.state === "pending") throw new Error("Assigned checks have an unresolved execution claim; inspect the durable journal before finalizing this run.");
+        if (decision.request) return {
+          content: [{ type: "text", text: formatRepairRequest(decision.request) }],
+          details: { accepted: false, session: targetTeamName, repairRequest: decision.request, result },
+        };
+      } finally {
+        verifyingReports.delete(result.reportId);
+      }
       await closePersistedRecipient(targetTeamName, options.agentName, runId, {
         removeOnFailure: true,
         role: (member.role ?? "write") === "read" ? "read" : "write",
         reason: "quit",
         extensionInstanceId,
       });
-      pendingWriterFinalization.set(`${targetTeamName}:${options.agentName}`, {
-        teamName: targetTeamName,
-        agentName: options.agentName,
-        runId,
-      });
       const sessionUsage = summarizeSessionUsage(ctx);
       const tokensUsed = typeof sessionUsage.tokensUsed === "number" ? sessionUsage.tokensUsed : runtimeStatus?.tokensUsed;
       const costUsd = sessionUsage.costUsd;
@@ -198,8 +255,11 @@ export function registerCoordinationTools(pi: any, options: CoordinationToolsOpt
       try {
         const persistedReport = await reportEvents.appendTeamReportEvent(targetTeamName, {
           agentName: options.agentName,
+          checkpoint: checkpointReference(targetTeamName, member),
+          completionGroup: member.completionGroup,
           role: member?.role || "write",
           status: "completed",
+          result,
           report: params.content,
           summary: params.summary || "Final report",
           startedAt: runtimeStatus?.startedAt,
@@ -215,8 +275,18 @@ export function registerCoordinationTools(pi: any, options: CoordinationToolsOpt
         });
         reportPath = persistedReport.reportPath || "";
         if (!reportPath) throw new Error("The persisted report did not provide its standalone file path.");
-        await messaging.sendPlainMessage(targetTeamName, options.agentName, "team-lead", params.content, params.summary || "Final report", undefined, { metadata: reportMetadata });
+        await saveReportCheckpoint(targetTeamName, member, persistedReport, _signal);
+        if (persistedReport.checkpoint) result.checkpointId = persistedReport.checkpoint.id;
+        const leadReport = (checks?.length
+          ? `${params.content}\n\nHarness verification: ${result.verification.state}; lead acceptance: ${result.acceptance.state}${result.repair ? `; repair: ${result.repair.state}; effective task: ${effectiveTaskOutcome(result) ?? "unspecified"}` : ""}. Evidence: ${result.reportId}.`
+          : params.content) + (result.checkpointId ? `\n\nCheckpoint reference: ${result.checkpointId}.` : "");
+        const grouped = await deliverCompletionGroupReport(persistedReport);
+        if (member.completionGroup && !grouped) throw new Error("Grouped report provenance is unavailable.");
+        if (!grouped) {
+          await messaging.sendPlainMessage(targetTeamName, options.agentName, "team-lead", leadReport, params.summary || "Final report", undefined, { metadata: reportMetadata });
+        }
         releasedClaims = await options.releaseAllClaimsForAgent(targetTeamName, options.agentName);
+        pendingWriterFinalization.set(`${targetTeamName}:${options.agentName}`, { teamName: targetTeamName, agentName: options.agentName, runId, checkpointId: result.checkpointId });
       } catch (error) {
         pendingWriterFinalization.delete(`${targetTeamName}:${options.agentName}`);
         await withLifecycleTombstoneLock(targetTeamName, options.agentName, async lifecycleLock => {
@@ -232,7 +302,7 @@ export function registerCoordinationTools(pi: any, options: CoordinationToolsOpt
         try { ctx.shutdown(); } catch { process.exit(0); }
       }, 250);
 
-      return { content: [{ type: "text", text: `Final report sent. Released ${releasedClaims.length} file claim(s). Exiting.` }], details: { session: targetTeamName, releasedClaims, reportPath } };
+      return { content: [{ type: "text", text: `Final report ${member.completionGroup ? "saved to its completion group" : "sent"}. Released ${releasedClaims.length} file claim(s). Exiting.` }], details: { accepted: true, session: targetTeamName, releasedClaims, reportPath, result } };
     },
   });
 

package/extensions/tools/task-runtime-tools.ts

@@ -11,6 +11,7 @@ import type { ReadAgentTeardownResult } from "../agents/read-agent-session-lifec
 import type { ShutdownTeammateOptions } from "../team/lifecycle";
 import { readLifecycleTombstone } from "../../src/utils/lifecycle-tombstone";
 import type { TeammateInterruptResult } from "../runtime/teammate-interrupt";
+import { effectiveTaskOutcome } from "../../src/results/report-result";
 
 export interface TaskRuntimeToolsOptions {
   isTeammate: boolean;
@@ -18,7 +19,7 @@ export interface TaskRuntimeToolsOptions {
   runningReadAgents: Map<string, RunningReadAgent>;
   readAgentKey(teamName: string, agentName: string): string;
   interruptTeammate?(agentName: string): Promise<TeammateInterruptResult>;
-  cancelQueuedAgent?(teamName: string, agentName: string): boolean;
+  cancelQueuedAgent?(teamName: string, agentName: string): boolean | Promise<boolean>;
   shutdownTeammate(teamName: string, member: Member, options?: ShutdownTeammateOptions): Promise<ReadAgentTeardownResult>;
   getTeamName(): string | null | undefined;
 }
@@ -56,7 +57,7 @@ export function registerTaskRuntimeTools(pi: any, options: TaskRuntimeToolsOptio
         const teamName = options.getTeamName();
         if (!teamName) throw new Error("No active agent session. Spawn an agent first.");
 
-        if (options.cancelQueuedAgent?.(teamName, params.agent_name)) {
+        if (await options.cancelQueuedAgent?.(teamName, params.agent_name)) {
           return {
             content: [{ type: "text", text: `Cancelled queued agent ${params.agent_name}.` }],
             details: { session: teamName, agentName: params.agent_name, stopped: true, queued: true, reason: params.reason },
@@ -147,6 +148,10 @@ export function registerTaskRuntimeTools(pi: any, options: TaskRuntimeToolsOptio
       if (!member) {
         const fence = await readLifecycleTombstone(teamName, params.agent_name);
         if (fence.status !== "absent") {
+          const completedReport = !options.isTeammate && fence.status === "occupied"
+            ? (await reportEvents.listTeamReportEvents(teamName, { agentName: params.agent_name }))
+              .filter(report => report.result?.runId === fence.tombstone.runId && report.result.repair).at(-1)
+            : undefined;
           const details = {
             agentName: params.agent_name,
             alive: false,
@@ -157,12 +162,17 @@ export function registerTaskRuntimeTools(pi: any, options: TaskRuntimeToolsOptio
             startupStalled: false,
             runtime: await runtime.readRuntimeStatus(teamName, params.agent_name).catch(() => null),
             teardownState: "quarantined",
+            ...(completedReport ? { completedReport } : {}),
             removedMember: false,
             releasedClaims: [],
             tombstone: fence.status === "occupied" ? fence.tombstone : undefined,
             error: fence.status === "corrupt" ? fence.error : undefined,
           };
-          return { content: [{ type: "text", text: formatTeammateStatusForModel(params.agent_name, details) }], details };
+          const text = [formatTeammateStatusForModel(params.agent_name, details),
+            completedReport ? `Full report: ${completedReport.reportPath}; repair ledger: ${completedReport.result!.repair!.journalPath}` : undefined,
+            ...(completedReport?.checks?.map(check => `Check ${check.checkId}: ${check.state}; full log: ${check.logPath}`) ?? []),
+          ].filter(Boolean).join("\n\n");
+          return { content: [{ type: "text", text }], details };
         }
         if (options.isTeammate) throw new Error(`Agent ${params.agent_name} not found`);
         const latestReport = (await reportEvents.listTeamReportEvents(teamName, {
@@ -177,6 +187,14 @@ export function registerTaskRuntimeTools(pi: any, options: TaskRuntimeToolsOptio
             : undefined;
           const text = [
             `Agent ${params.agent_name} is no longer active. Recovered its latest persisted ${latestReport.status} report from ${reportPath}.`,
+            latestReport.result
+              ? `Task: ${latestReport.result.outcome ?? "unspecified"}; verification: ${latestReport.result.verification.state}; acceptance: ${latestReport.result.acceptance.state}. Report ID: ${latestReport.result.reportId}.`
+              : undefined,
+            latestReport.result?.repair
+              ? `Repair: ${latestReport.result.repair.state}; effective task: ${effectiveTaskOutcome(latestReport.result) ?? "unspecified"}; ledger: ${latestReport.result.repair.journalPath}.`
+              : undefined,
+            latestReport.checks?.map(check => `Check ${check.checkId}: ${check.state}; exit ${check.exitCode ?? "unknown"}; full log: ${check.logPath}`).join("\n"),
+            latestReport.result?.verification.error,
             recoverySessionFile
               ? `Its durable child transcript is available at ${recoverySessionFile}. Use the read tool on that path if the report is incomplete.`
               : undefined,
@@ -246,7 +264,8 @@ export function registerTaskRuntimeTools(pi: any, options: TaskRuntimeToolsOptio
         removedMember: teardown?.removedMember ?? false,
         error: teardown?.error ?? lifecycleError,
       };
-      return { content: [{ type: "text", text: formatTeammateStatusForModel(params.agent_name, details) }], details };
+      const text = [formatTeammateStatusForModel(params.agent_name, details), details.error].filter(Boolean).join("\n\n");
+      return { content: [{ type: "text", text }], details };
     },
     renderResult(result: any, { expanded }: any, theme: any) {
       return renderTeammateStatus(result, expanded, theme);