pi-extended-teams 2.2.9 → 2.3.0

package/extensions/tools/team-tools.ts

@@ -12,12 +12,23 @@ import * as messaging from "../../src/utils/messaging";
 import * as writeQueue from "../../src/utils/write-queue";
 import { ACCEPTED_FAVORITE_MODEL_SLOTS, FAVORITE_MODEL_SLOTS, canonicalPersistedModelSlot, isFavoriteModelSlot, loadSettings, normalizeFavoriteModelSlot, requireFavoriteModelLevel, resolveModel, roleForFavoriteModelSlot, type AgentRole, type CanonicalFavoriteModelSlot } from "../../src/utils/settings";
 import type { Member } from "../../src/utils/models";
+import { CheckPolicySchema, normalizeCheckPolicy } from "../../src/results/check-policy";
+import { RepairPolicySchema, normalizeRepairPolicy } from "../../src/results/repair-policy";
+import { CheckpointPolicySchema } from "../../src/results/checkpoint-policy";
+import { createCheckpointAssignment, captureCheckpointAssignment, continuationPrompt } from "../../src/results/checkpoint-assignment";
+import { assertUnusedContinuationRecipient, freshContinuationName } from "../../src/results/continuation-recipient";
+import { readCheckpoint } from "../../src/results/specialist-checkpoint";
+import { CompletionGroup, CompletionGroupPolicySchema, completionGroupIdentity, normalizeCompletionGroupPolicy, type CompletionGroupBinding } from "../../src/results/completion-group";
+import { listStoredTeamReportEvents } from "../../src/utils/report-events";
+import { enqueueCompletionGroupDeliveries } from "../../src/results/completion-group-delivery";
+import { shouldSuppressLeadReportInjection } from "../../src/utils/workflow-metadata";
 
 import type { RunningReadAgent } from "../runtime/types";
 import type { ReadAgentTeardownResult } from "../agents/read-agent-session-lifecycle";
 import type { ShutdownTeammateOptions } from "../team/lifecycle";
 import {
   onLifecycleTombstoneCleared,
+  listLifecycleTombstones,
   readLifecycleTombstone,
   withLifecycleTombstoneLock,
   type LifecycleTombstoneLock,
@@ -55,6 +66,7 @@ export interface TeamToolsOptions {
   startWriteAgent(teamName: string, member: Member, prompt: string): Promise<string>;
   shutdownTeammate(teamName: string, member: Member, options?: ShutdownTeammateOptions): Promise<ReadAgentTeardownResult>;
   adoptTeamAsLead(teamName: string, ctx?: any): void;
+  onCompletionGroupUse?(groupId: string): void;
   buildRoster(teamName: string): Promise<any>;
   isTeammate: boolean;
   agentName: string;
@@ -71,13 +83,21 @@ export interface NestedReadAgentToolBinding {
   outerCtx: any;
 }
 
+export interface NestedChildSnapshot {
+  running: number;
+  queued: number;
+}
+
 export interface TeamToolsRuntime {
   createNestedReadAgentTools(binding: NestedReadAgentToolBinding): any[];
-  cancelQueuedAgent(teamName: string, agentName: string): boolean;
+  nestedChildSnapshot(binding: NestedReadAgentToolBinding): NestedChildSnapshot;
+  cancelQueuedAgent(teamName: string, agentName: string): boolean | Promise<boolean>;
 }
 
 interface SpawnTeammateOptions {
   once?: boolean;
+  signal?: AbortSignal;
+  completionGroup?: CompletionGroupBinding;
   nestedParent?: {
     teamName: string;
     name: string;
@@ -97,15 +117,21 @@ interface QueuedReadSpawn {
   ctx: any;
   requestedAt: number;
   nameReservationId?: string;
+  signal?: AbortSignal;
   pendingChildAcceptance?: PendingChildAcceptance;
   admissionError?: string;
   quarantineError?: string;
   launchCommitted?: boolean;
+  groupSettlement?: Promise<void>;
 }
 
 export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamToolsRuntime {
   if (options.isTeammate) {
-    return { createNestedReadAgentTools: () => [], cancelQueuedAgent: () => false };
+    return {
+      createNestedReadAgentTools: () => [],
+      nestedChildSnapshot: () => ({ running: 0, queued: 0 }),
+      cancelQueuedAgent: () => false,
+    };
   }
 
   function emitOrchestrationResponse(requestId: string | undefined, type: string, payload: Record<string, any>): void {
@@ -297,6 +323,20 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     return queuedReadSpawnsByTeam.get(teamName) ?? [];
   }
 
+  function nestedChildSnapshot(binding: NestedReadAgentToolBinding): NestedChildSnapshot {
+    const parent = {
+      teamName: binding.teamName,
+      parentName: binding.parent.name,
+      parentRunId: binding.parentRunId,
+    };
+    const queued = readQueue(binding.teamName).filter((child) => {
+      const childParent = pendingParentForMember(binding.teamName, child.member);
+      return childParent?.parentName === parent.parentName && childParent.parentRunId === parent.parentRunId;
+    }).length;
+    const pending = pendingChildController.pendingCount(parent);
+    return { running: Math.max(0, pending - queued), queued };
+  }
+
   async function listQueuedAgentStatuses(teamName: string): Promise<QueuedAgentStatus[]> {
     const readers = [...readQueue(teamName), ...(failedAdmissionsByTeam.get(teamName) ?? [])].map((queued, index) => ({
       name: queued.member.name,
@@ -342,17 +382,34 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       queued: readQueue(activeTeamName).length,
     });
   });
+  const checkpointAdmissions = new Map<string, { controller: AbortController; settled: Promise<void> }>();
+  function cancelCheckpointAdmission(teamName: string, name: string): Promise<void> | undefined {
+    const pending = checkpointAdmissions.get(options.readAgentKey(teamName, name));
+    pending?.controller.abort(new Error("Checkpoint preparation cancelled."));
+    return pending?.settled;
+  }
   let lifecycleProbeCleanedUp = false;
   let pendingChildCancelUnsubscribe = (): void => {};
-  pi.on?.("session_shutdown", () => {
+  pi.on?.("session_shutdown", async () => {
     if (lifecycleProbeCleanedUp) return;
     lifecycleProbeCleanedUp = true;
+    const settlements: Promise<void>[] = [];
+    for (const pending of checkpointAdmissions.values()) {
+      pending.controller.abort(new Error("Checkpoint preparation cancelled: session is closing."));
+      settlements.push(pending.settled);
+    }
     for (const [teamName, queue] of queuedReadSpawnsByTeam) {
-      for (const queued of queue) removeQueuedReadSpawnById(teamName, queued.id);
+      for (const queued of queue) {
+        const removed = removeQueuedReadSpawnById(teamName, queued.id);
+        if (removed?.groupSettlement) settlements.push(removed.groupSettlement);
+      }
+    }
+    try { await Promise.all(settlements); }
+    finally {
+      if (typeof lifecycleProbeUnsubscribe === "function") lifecycleProbeUnsubscribe();
+      pendingChildCancelUnsubscribe();
+      lifecycleFenceUnsubscribe();
     }
-    if (typeof lifecycleProbeUnsubscribe === "function") lifecycleProbeUnsubscribe();
-    pendingChildCancelUnsubscribe();
-    lifecycleFenceUnsubscribe();
   });
 
   function setReadQueue(teamName: string, queue: QueuedReadSpawn[]): void {
@@ -373,6 +430,17 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     };
   }
 
+  function settleQueuedGroup(queued: QueuedReadSpawn): Promise<void> | undefined {
+    const binding = queued.member.completionGroup;
+    if (!binding) return;
+    return Promise.resolve().then(async () => {
+      const group = new CompletionGroup(queued.teamName, binding.groupId);
+      await group.apply({ type: queued.admissionError ? "rejected" : "cancelled", ...binding,
+        queueId: queued.id, reason: queued.admissionError || "Queued assignment cancelled." });
+      await enqueueCompletionGroupDeliveries(group);
+    });
+  }
+
   function removeQueuedReadSpawnById(
     teamName: string,
     id: string,
@@ -386,6 +454,10 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     if (settlePendingAcceptance && removed.pendingChildAcceptance) {
       pendingChildController.settleAcceptance(removed.pendingChildAcceptance);
     }
+    if (settlePendingAcceptance) {
+      cancelCheckpointAdmission(teamName, removed.member.name);
+      removed.groupSettlement = settleQueuedGroup(removed);
+    }
     return removed;
   }
 
@@ -397,6 +469,9 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     for (const queued of removed) {
       releaseNestedReadName(teamName, queued.member.name, queued.nameReservationId);
       if (queued.pendingChildAcceptance) pendingChildController.settleAcceptance(queued.pendingChildAcceptance);
+      const pending = cancelCheckpointAdmission(teamName, queued.member.name);
+      const group = settleQueuedGroup(queued);
+      queued.groupSettlement = pending ? Promise.all([pending, group]).then(() => {}) : group;
     }
     return removed;
   }
@@ -561,6 +636,12 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       }
 
       try {
+        if (member.completionGroup) {
+          if (!member.lifecycleRunId) throw new Error("Grouped admission requires an actual lifecycle run.");
+          await new CompletionGroup(teamName, member.completionGroup.groupId).apply({
+            type: "running", ...member.completionGroup, runId: member.lifecycleRunId,
+          });
+        }
         if (lifecycleProbeCleanedUp) throw new Error("Agent session is closing; admission cancelled.");
         assertPending?.();
       } catch (error) {
@@ -608,9 +689,10 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
           sessionContextReference = null;
         }
       }
+      const continuedPrompt = continuationPrompt(member.checkpointAssignment, prompt);
       const launchPrompt = sessionContextReference
-        ? `${prompt}${sessionContextReference.promptSuffix}`
-        : prompt;
+        ? `${continuedPrompt}${sessionContextReference.promptSuffix}`
+        : continuedPrompt;
       const removeReference = () => {
         try {
           removeSessionContextReference(sessionContextReference);
@@ -622,6 +704,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       try {
         if (lifecycleProbeCleanedUp) throw new Error("Agent session is closing; admission cancelled.");
         assertPending?.();
+        if (member.checkpointAssignment?.parent) readCheckpoint(member.checkpointAssignment.parent.id);
         commitLaunch?.();
         const launch = options.runReadAgentInProcess(teamName, member, launchPrompt, ctx, options.readAgentOptions());
         return {
@@ -654,10 +737,21 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     releaseNameOnFailure = true,
     queuedAcceptance?: PendingChildAcceptance,
     assertPending?: () => void,
+    signal?: AbortSignal,
     commitLaunch?: () => void,
   ): Promise<boolean> {
     const key = options.readAgentKey(teamName, member.name);
+    if (checkpointAdmissions.has(key)) throw new Error(`Checkpoint admission for ${member.name} is already in progress.`);
     reserveReadAdmission(teamName, key, member.role || "read");
+    const controller = member.checkpointAssignment ? new AbortController() : undefined;
+    let settleCheckpoint = () => {};
+    if (controller) checkpointAdmissions.set(key, { controller, settled: new Promise<void>(resolve => { settleCheckpoint = resolve; }) });
+    const checkpointSignal = controller ? AbortSignal.any([controller.signal, AbortSignal.timeout(30_000), ...(signal ? [signal] : [])]) : undefined;
+    const finishCheckpoint = () => {
+      if (controller && checkpointAdmissions.get(key)?.controller === controller) checkpointAdmissions.delete(key);
+      settleCheckpoint();
+    };
+    const assertAdmissionPending = () => { checkpointSignal?.throwIfAborted(); assertPending?.(); };
 
     const releaseNameReservation = () => {
       releaseNestedReadName(teamName, member.name, nameReservationId);
@@ -688,7 +782,15 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     };
 
     try {
-      const admitted = await admitAndLaunchReadAgentMember(teamName, member, prompt, ctx, queuedAcceptance, assertPending, commitLaunch);
+      if (member.checkpointAssignment && checkpointSignal) {
+        if (lifecycleProbeCleanedUp) throw new Error("Agent session is closing; admission cancelled.");
+        assertAdmissionPending();
+        member.checkpointAssignment = await captureCheckpointAssignment(member.checkpointAssignment, member.cwd, checkpointSignal);
+      }
+      const admitted = await admitAndLaunchReadAgentMember(teamName, member, prompt, ctx, queuedAcceptance, assertAdmissionPending, () => {
+        finishCheckpoint();
+        commitLaunch?.();
+      });
       releaseNameReservation();
       void Promise.resolve(admitted.launch).then(
         () => drainAfterRun(admitted.pendingChildRun),
@@ -699,7 +801,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       settlePendingChild(queuedAcceptance);
       releaseReservationAndDrain();
       throw error;
-    }
+    } finally { finishCheckpoint(); }
   }
 
   async function enqueueReadSpawn(
@@ -709,13 +811,10 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     params: any,
     resolved: ReturnType<typeof resolveModel>,
     ctx: any,
-    nameReservationId?: string
+    nameReservationId?: string,
+    signal?: AbortSignal,
   ): Promise<QueuedReadSpawn> {
-    const append = (pendingChildAcceptance?: PendingChildAcceptance): QueuedReadSpawn => {
-      const queue = readQueue(teamName);
-      if (queue.some((queued) => queued.member.name === member.name)) {
-        throw new Error(`Nested read agent ${member.name} is already active or queued; nested delegation cannot replace an existing run.`);
-      }
+    const append = async (pendingChildAcceptance?: PendingChildAcceptance): Promise<QueuedReadSpawn> => {
       const queued: QueuedReadSpawn = {
         id: crypto.randomUUID(),
         teamName,
@@ -726,9 +825,21 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
         ctx,
         requestedAt: Date.now(),
         nameReservationId,
+        signal,
         pendingChildAcceptance,
       };
-      setReadQueue(teamName, [...queue, queued]);
+      if (member.completionGroup) {
+        const group = new CompletionGroup(teamName, member.completionGroup.groupId);
+        await group.apply({ type: "queued", ...member.completionGroup, queueId: queued.id });
+        if (lifecycleProbeCleanedUp) {
+          await group.apply({ type: "cancelled", ...member.completionGroup, reason: "Agent session is closing." });
+          throw new Error("Agent session is closing; admission cancelled.");
+        }
+      }
+      if (readQueue(teamName).some(item => item.member.name === member.name)) {
+        throw new Error(`Nested read agent ${member.name} is already active or queued; nested delegation cannot replace an existing run.`);
+      }
+      setReadQueue(teamName, [...readQueue(teamName), queued]);
       void drainQueuedReadSpawns(teamName);
       return queued;
     };
@@ -744,7 +855,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       if (!parent) throw new Error(`Nested read agent ${member.name} is missing exact parent identity.`);
       const pendingChildAcceptance = pendingChildController.acceptChild(parent, member.name);
       try {
-        return append(pendingChildAcceptance);
+        return await append(pendingChildAcceptance);
       } catch (error) {
         pendingChildController.settleAcceptance(pendingChildAcceptance);
         throw error;
@@ -785,7 +896,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
             if (activeAgentCount(teamName, role, true) >= capacity.maxConcurrent) continue;
             queued.member.joinedAt = Date.now();
             await startReadAgentMember(teamName, queued.member, queued.prompt, queued.ctx,
-              queued.nameReservationId, false, queued.pendingChildAcceptance, assertPending,
+              queued.nameReservationId, false, queued.pendingChildAcceptance, assertPending, queued.signal,
               () => { queued.launchCommitted = true; });
             removeQueuedReadSpawnById(teamName, queued.id, false);
             progressed = true;
@@ -799,10 +910,17 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
             }
             queued.admissionError = error instanceof Error ? error.message : String(error);
             failedAdmissionsByTeam.set(teamName, [...(failedAdmissionsByTeam.get(teamName) ?? []), queued].slice(-20));
-            removeQueuedReadSpawnById(teamName, queued.id);
-            await messaging.sendPlainMessage(teamName, "system", queued.member.parentAgentName || "team-lead",
-              `Queued agent ${queued.member.name} failed admission: ${queued.admissionError}`,
-              `Queued agent ${queued.member.name} failed`, "red").catch(() => {});
+            const removed = removeQueuedReadSpawnById(teamName, queued.id);
+            let groupSettlementFailed = false;
+            await removed?.groupSettlement?.catch(error => {
+              groupSettlementFailed = true;
+              queued.admissionError += ` Group settlement failed: ${error instanceof Error ? error.message : String(error)}`;
+            });
+            if (!queued.member.completionGroup || groupSettlementFailed) {
+              await messaging.sendPlainMessage(teamName, "system", queued.member.parentAgentName || "team-lead",
+                `Queued agent ${queued.member.name} failed admission: ${queued.admissionError}`,
+                `Queued agent ${queued.member.name} failed`, "red").catch(() => {});
+            }
           }
         }
       }
@@ -817,8 +935,38 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     return paths.sanitizeName(`session-${sessionId}`);
   }
 
+  let admittingPublicTeam: string | undefined;
+  let publicAdmissions = 0;
+  async function withPublicScope<T>(teamName: string, action: () => Promise<T>): Promise<T> {
+    if (teamName.startsWith("prompt-build-")) return action();
+    if (publicAdmissions > 0 && admittingPublicTeam !== teamName) {
+      throw new Error(`Cannot switch to ${teamName}: ${admittingPublicTeam} has unfinished agents being admitted.`);
+    }
+    admittingPublicTeam = teamName;
+    publicAdmissions += 1;
+    try {
+      return await action();
+    } finally {
+      if (--publicAdmissions === 0) admittingPublicTeam = undefined;
+    }
+  }
+
+  async function requireSettledPublicScope(nextTeamName: string): Promise<void> {
+    if (lifecycleProbeCleanedUp) throw new Error("Agent session is closing; admission cancelled.");
+    const current = options.getTeamName();
+    if (!current || current === nextTeamName || nextTeamName.startsWith("prompt-build-")) return;
+    const [config, fences, queued] = await Promise.all([
+      teams.readConfig(current), listLifecycleTombstones(current), listQueuedAgentStatuses(current),
+    ]);
+    const unfinished = config.members.some(member => member.name !== "team-lead")
+      || fences.length > 0 || queued.some(item => !item.failed)
+      || Array.from(options.runningReadAgents.values()).some(agent => agent.teamName === current && agent.teardownState !== "finalized");
+    if (unfinished) throw new Error(`Cannot switch from ${current} to ${nextTeamName}: unfinished agents must remain visible. Finish or stop them first.`);
+  }
+
   async function ensureCurrentSessionAgentGroup(ctx: any, explicitDefaultModel: string): Promise<string> {
     const sessionName = currentSessionAgentGroupName(ctx);
+    await requireSettledPublicScope(sessionName);
     if (teams.teamExists(sessionName)) {
       options.adoptTeamAsLead(sessionName, ctx);
       return sessionName;
@@ -837,10 +985,23 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
   }
 
   async function spawnTeammate(params: any, ctx: any, spawnOptions: SpawnTeammateOptions = {}): Promise<{ content: any[]; details: any }> {
+    const checkpointAssignment = createCheckpointAssignment(params.checkpoint, params.prompt, params.continue_from);
+    const assignedChecks = normalizeCheckPolicy(params.checks);
+    const repairPolicy = normalizeRepairPolicy(params.repair);
+    if (repairPolicy && !assignedChecks?.length) throw new Error("Repair policy requires explicitly assigned checks.");
     const safeName = paths.sanitizeName(params.name);
     const safeTeamName = paths.sanitizeName(params.team_name);
     const cwd = params.cwd || ctx.cwd;
     const teamConfig = await teams.readConfig(safeTeamName);
+    if (checkpointAssignment?.parent) {
+      requireSpawnLevel(params, `Continuation ${safeName}`);
+      if (safeName.toLowerCase() === checkpointAssignment.parent.author.agentName.toLowerCase()
+        || teamConfig.members.some(member => member.name.toLowerCase() === safeName.toLowerCase())
+        || options.runningReadAgents.has(options.readAgentKey(safeTeamName, safeName)) || findQueuedReadSpawn(safeTeamName, { name: safeName })) {
+        throw new Error(`Continuation recipient ${safeName} is not unused; choose a new prefix and retry.`);
+      }
+      assertUnusedContinuationRecipient(safeTeamName, safeName);
+    }
     failedAdmissionsByTeam.set(safeTeamName, (failedAdmissionsByTeam.get(safeTeamName) ?? []).filter(item => item.member.name !== safeName));
     let nestedNameReservationId: string | undefined;
     let nestedNameReservationTransferred = false;
@@ -871,7 +1032,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     }
 
     try {
-    if (spawnOptions.once) {
+    if (spawnOptions.once && !checkpointAssignment?.parent) {
       const existingOnceMember = teamConfig.members.find(m => m.agentType === "teammate" && (m.name === safeName || memberMatchesOperation(m, params)));
       if (existingOnceMember) {
         return {
@@ -910,6 +1071,9 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       }
     }
 
+    if (checkpointAdmissions.has(options.readAgentKey(safeTeamName, safeName)) && !findQueuedReadSpawn(safeTeamName, { name: safeName })) {
+      throw new Error(`Checkpoint admission for ${safeName} is already in progress.`);
+    }
     const existingMember = teamConfig.members.find(m => m.name === safeName && m.agentType === "teammate");
     if (existingMember) {
       const key = options.readAgentKey(safeTeamName, existingMember.name);
@@ -980,6 +1144,10 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       color: role === "read" ? "cyan" : "blue",
       thinking: chosenThinking,
       planModeRequired: params.plan_mode_required,
+      assignedChecks,
+      repairPolicy,
+      checkpointAssignment,
+      completionGroup: spawnOptions.completionGroup,
       metadata: operationMetadataFromParams(params),
       delegationDepth: spawnOptions.nestedParent ? 1 : 0,
       allowNestedReadAgents: !spawnOptions.nestedParent && spawnOptions.allowNestedReadAgents === true,
@@ -991,7 +1159,10 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     };
 
     if (role === "write") await writeQueue.removeQueuedWriteSpawnsByName(safeTeamName, safeName);
-    if (!spawnOptions.nestedParent) removeQueuedReadSpawnsByName(safeTeamName, safeName);
+    if (!spawnOptions.nestedParent) {
+      const removed = removeQueuedReadSpawnsByName(safeTeamName, safeName);
+      if (removed.some(item => item.groupSettlement)) await Promise.all(removed.map(item => item.groupSettlement));
+    }
     if (lifecycleProbeCleanedUp) throw new Error("Agent session is closing; admission cancelled.");
     const capacity = role === "write" ? settings.writeAgents : settings.readAgents;
     const activeCount = activeAgentCount(safeTeamName, role, true);
@@ -999,7 +1170,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       if (!capacity.queueOverflow) {
         throw new Error(`${role === "write" ? "Edit" : "Read"}-agent capacity reached (${activeCount}/${capacity.maxConcurrent}) and queueOverflow is disabled.`);
       }
-      const queued = await enqueueReadSpawn(safeTeamName, member, params.prompt, params, resolved, ctx, nestedNameReservationId);
+      const queued = await enqueueReadSpawn(safeTeamName, member, params.prompt, params, resolved, ctx, nestedNameReservationId, spawnOptions.signal);
       nestedNameReservationTransferred = !!nestedNameReservationId;
       const queuePosition = readQueue(safeTeamName).findIndex(item => item.id === queued.id) + 1;
       return {
@@ -1008,7 +1179,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       };
     }
 
-    const sessionContextAvailable = await startReadAgentMember(safeTeamName, member, params.prompt, ctx, nestedNameReservationId);
+    const sessionContextAvailable = await startReadAgentMember(safeTeamName, member, params.prompt, ctx, nestedNameReservationId, true, undefined, undefined, spawnOptions.signal);
     if (role === "write") {
       await writeTeamsDebugEvent(safeTeamName, "write-agent.spawn.success", {
         agentName: safeName, cwd, requestedRole: role, model: chosenModel,
@@ -1033,7 +1204,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     }
   }
 
-  pi.events?.on?.("pi-extended-teams:orchestration-request", async (payload: any) => {
+  async function handleOrchestrationRequest(payload: any): Promise<void> {
     const requestId = payload?.requestId;
     const type = String(payload?.type || "");
     const params = payload?.params || {};
@@ -1045,6 +1216,9 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       if (options.isTeammate) throw new Error("Teammates cannot satisfy orchestration requests directly.");
       if (!ctx) throw new Error("No active lead session context is available for orchestration request. If pi-extended-teams was registered after session_start, include the current Pi command context as payload.ctx.");
 
+      if (type === "ensure_team" || type === "spawn_teammate_once") {
+        await requireSettledPublicScope(paths.sanitizeName(params.team_name));
+      }
       if (type === "ensure_team") {
         const safeTeamName = paths.sanitizeName(params.team_name);
         if (teams.teamExists(safeTeamName)) {
@@ -1078,7 +1252,17 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
         const safeTeamName = paths.sanitizeName(params.team_name);
         if (!teams.teamExists(safeTeamName)) throw new Error(`Team ${params.team_name} does not exist`);
         options.adoptTeamAsLead(safeTeamName, ctx);
-        const result = await spawnTeammate(params, ctx, { once: true });
+        const prepared = params.continue_from === undefined ? params : { ...params, name: freshContinuationName(params.name || "agent") };
+        const result = await spawnTeammate(prepared, ctx, {
+          once: true,
+          allowNestedReadAgents: params.allow_nested_read_agents === true,
+        });
+        emitOrchestrationResponse(requestId, type, { ok: true, details: result.details, content: result.content });
+        return;
+      }
+
+      if (type === "spawn_agent") {
+        const result = await spawnPublicAgent(params, ctx);
         emitOrchestrationResponse(requestId, type, { ok: true, details: result.details, content: result.content });
         return;
       }
@@ -1087,6 +1271,11 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     } catch (error) {
       emitOrchestrationResponse(requestId, type, { ok: false, error: error instanceof Error ? error.message : String(error) });
     }
+  }
+  pi.events?.on?.("pi-extended-teams:orchestration-request", (payload: any) => {
+    if (payload?.type !== "ensure_team" && payload?.type !== "spawn_teammate_once") return handleOrchestrationRequest(payload);
+    return withPublicScope(String(payload?.params?.team_name || ""), () => handleOrchestrationRequest(payload))
+      .catch(error => emitOrchestrationResponse(payload?.requestId, payload?.type, { ok: false, error: error instanceof Error ? error.message : String(error) }));
   });
 
   const levelDescription = "Required intent tier. Configured favorites take priority; an unconfigured tier inherits the current lead model and thinking. Read tiers: read-collect gathers bounded facts without owning the conclusion; read-review is the normal default for focused review, verification, and bounded synthesis; read-analyze explains behavior or root cause across connected evidence; read-critical is only for irreducible high-stakes security, architecture, concurrency, migration, or data-correctness reasoning. Write tiers: write-patch makes a narrow localized change; write-feature implements a bounded feature with a known design; write-system owns a cross-cutting integration or refactor within explicitly claimed files; write-critical is only for high-risk security, concurrency, recovery, migration, or data-integrity changes. Prefer canonical tiers; legacy reading-*/writing-* aliases remain accepted for this minor release. Do not pass role, model, or thinking directly; see README.md.";
@@ -1094,6 +1283,10 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     name: Type.Optional(Type.String({ description: "Stable display name. Defaults to a generated agent name." })),
     prompt: Type.String({ description: "The agent's assignment, relevant prior context, evidence already gathered, constraints, and report shape." }),
     cwd: Type.Optional(Type.String({ description: "Working directory. Defaults to the lead session cwd." })),
+    checks: Type.Optional(CheckPolicySchema),
+    repair: Type.Optional(RepairPolicySchema),
+    checkpoint: Type.Optional(CheckpointPolicySchema),
+    continue_from: Type.Optional(Type.String({ description: "Continue this checkpoint as a fresh recipient/run with the current assignment and tier. name is a prefix, not a recipient to reuse." })),
     session_context: Type.Optional(StringEnum(["none", "lazy"] as const, { description: "Optional filtered snapshot of the lead's active session branch. Use lazy only when omitted session history may materially affect the lane; the child reads it on demand rather than receiving transcript content in its prompt.", default: "none" })),
     metadata: Type.Optional(Type.Record(Type.String(), Type.Any())),
     allow_nested_read_agents: Type.Optional(Type.Boolean({ description: "Opt in eligible depth-0 write-feature/write-critical agents to restricted read-only child spawning.", default: false })),
@@ -1112,18 +1305,23 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     return `agent-${Date.now().toString(36)}${position}-${crypto.randomUUID().slice(0, 8)}`;
   }
 
-  async function spawnPublicAgent(params: any, ctx: any): Promise<{ content: any[]; details: any }> {
+  function spawnPublicAgent(params: any, ctx: any, signal?: AbortSignal): Promise<{ content: any[]; details: any }> {
+    return withPublicScope(currentSessionAgentGroupName(ctx), () => spawnPublicAgentInScope(params, ctx, signal));
+  }
+
+  async function spawnPublicAgentInScope(params: any, ctx: any, signal?: AbortSignal): Promise<{ content: any[]; details: any }> {
     if (options.isTeammate) throw new Error("Only the lead session can spawn agents.");
     if (!ctx) throw new Error("No active Pi session context is available for spawn_agent.");
 
+    params = { ...params, checkpoint: createCheckpointAssignment(params.checkpoint, params.prompt, params.continue_from)?.policy };
+    const name = params.continue_from === undefined ? params.name || generatedAgentName() : freshContinuationName(params.name || "agent");
     const sessionDefaultModel = configuredFavoriteModelForSpawn(params, ctx);
     const sessionName = await ensureCurrentSessionAgentGroup(ctx, sessionDefaultModel);
-    const name = params.name || generatedAgentName();
     const result = await spawnTeammate({
       ...params,
       name,
       team_name: sessionName,
-    }, ctx, { allowNestedReadAgents: params.allow_nested_read_agents === true });
+    }, ctx, { allowNestedReadAgents: params.allow_nested_read_agents === true, signal });
 
     const outcome = result.details.queued
       ? `Agent ${name} queued at position ${result.details.queuePosition}.`
@@ -1253,7 +1451,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     description: "Spawn one agent by intent tier only. Configured favorites take priority; an unconfigured tier inherits the current lead model and thinking. Give it the relevant goal, decisions, prior attempts, inspected evidence, constraints, and expected delta rather than a context-free task. Use session_context=lazy only as an on-demand fallback when omitted session history may materially matter; it never replaces a good mission prompt. read-review is the normal read default; use read-collect for bounded fact gathering, read-analyze for connected explanation/root cause, and read-critical only for irreducible high-stakes reasoning. For edits, choose write-patch, write-feature, write-system, or the rare high-risk write-critical by scope and risk. After spawning, do not duplicate or take over its lane; work only on unrelated work, then end the turn so the automatic report can resume you. One get_agent_status snapshot is allowed when current status is needed; never sleep, busy-wait, repeatedly read inbox/status, or treat healthy silence as failure. Wait for the actual report before synthesizing; intervene only on a reported blocker/error, actual health failure, or explicit user cancellation. model_slot selects behavior, model, and thinking; do not pass role, model, or thinking directly.",
     parameters: Type.Object(publicAgentParams),
     async execute(_toolCallId: string, params: any, _signal: AbortSignal, _onUpdate: any, ctx: any) {
-      return spawnPublicAgent(params, ctx);
+      return spawnPublicAgent(params, ctx, _signal);
     },
   });
 
@@ -1264,11 +1462,15 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     parameters: Type.Object({
       defaults: Type.Optional(Type.Object({
         cwd: Type.Optional(Type.String()),
+        checks: Type.Optional(CheckPolicySchema),
+        repair: Type.Optional(RepairPolicySchema),
+        checkpoint: Type.Optional(CheckpointPolicySchema),
         model_slot: Type.Optional(StringEnum(ACCEPTED_FAVORITE_MODEL_SLOTS, { description: levelDescription })),
         metadata: Type.Optional(Type.Record(Type.String(), Type.Any())),
         session_context: Type.Optional(StringEnum(["none", "lazy"] as const, { description: "Shared lazy session-reference policy.", default: "none" })),
         allow_nested_read_agents: Type.Optional(Type.Boolean({ description: "Shared opt-in for eligible depth-0 write-feature/write-critical agents.", default: false })),
       })),
+      completion_group: Type.Optional(CompletionGroupPolicySchema),
       agents: Type.Array(Type.Object(publicSwarmAgentParams), { description: "Agents to spawn as one batch. Each one must have model_slot directly or inherit it from defaults." }),
     }),
     async execute(_toolCallId: string, params: any, _signal: AbortSignal, _onUpdate: any, ctx: any) {
@@ -1276,44 +1478,89 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       if (!ctx) throw new Error("No active Pi session context is available for spawn_swarm_agents.");
       if (!Array.isArray(params.agents) || params.agents.length === 0) throw new Error("spawn_swarm_agents requires at least one agent.");
 
-      const mergedAgents = params.agents.map((agent: any) => mergeSwarmAgentParams(params.defaults || {}, agent));
+      const groupPolicy = normalizeCompletionGroupPolicy(params.completion_group);
+      const sessionId = getPiSessionId(ctx);
+      if (groupPolicy && (!sessionId || !_toolCallId?.trim())) throw new Error("Completion groups require a bound session and runtime submission identity.");
+      const mergedAgents = params.agents.map((agent: any, index: number) => {
+        const merged = mergeSwarmAgentParams(params.defaults || {}, agent);
+        merged.checkpoint = createCheckpointAssignment(merged.checkpoint, merged.prompt, merged.continue_from)?.policy;
+        if (merged.continue_from !== undefined) merged.name = freshContinuationName(merged.name || "agent", JSON.stringify([sessionId, _toolCallId, index, merged.continue_from]));
+        return merged;
+      });
       const defaultModel = configuredFavoriteModelForSpawn(mergedAgents[0], ctx, "spawn_swarm_agents");
       for (let index = 0; index < mergedAgents.length; index += 1) {
         configuredFavoriteModelForSpawn(mergedAgents[index], ctx, `spawn_swarm_agents agent ${mergedAgents[index].name || index + 1}`);
       }
       const sessionName = await ensureCurrentSessionAgentGroup(ctx, defaultModel);
+      let group: CompletionGroup | undefined;
+      if (groupPolicy && sessionId) {
+        const identity = { teamName: sessionName, sessionId, submissionId: `tool:${_toolCallId}` };
+        const groupId = completionGroupIdentity(identity);
+        options.onCompletionGroupUse?.(groupId);
+        const config = await teams.readConfig(sessionName);
+        const reports = await listStoredTeamReportEvents(sessionName);
+        const inbox = await messaging.readInbox(sessionName, "team-lead", false, false);
+        const entries = ctx.sessionManager?.getBranch?.() ?? [];
+        const references = [...config.members.map(member => member.completionGroup),
+          ...readQueue(sessionName).map(queued => queued.member.completionGroup),
+          ...reports.map(report => report.completionGroup), ...inbox.map(message => message.metadata?.completionGroup),
+          ...entries.map((entry: any) => entry.message?.details?.completionGroup)];
+        if (references.some(binding => binding?.groupId === groupId)) new CompletionGroup(sessionName, groupId).read();
+        group = await CompletionGroup.create({ ...identity, policy: groupPolicy, members: mergedAgents.map((agent: any, index: number) => ({
+          name: paths.sanitizeName(agent.name || `agent-${crypto.createHash("sha256").update(`${_toolCallId}:${index}`).digest("hex").slice(0, 12)}`),
+          assignmentKey: crypto.createHash("sha256").update(JSON.stringify([agent, ctx.cwd])).digest("hex"),
+          suppressed: sessionName.startsWith("prompt-build-") || shouldSuppressLeadReportInjection(agent),
+        })) });
+        if (group && !group.created) return {
+          content: [{ type: "text", text: `Completion group ${group.groupId} already exists; no assignments replayed. State: ${group.journalPath}\n${AGENT_WAIT_CONTRACT}` }],
+          details: { session: sessionName, completionGroup: { groupId: group.groupId, journalPath: group.journalPath },
+            idempotent: true, spawned: [], failed: [], members: group.read().members },
+        };
+      }
       const spawned: any[] = [];
       const failed: Array<{ name: string; error: string }> = [];
 
       for (let index = 0; index < mergedAgents.length; index += 1) {
         const merged = mergedAgents[index];
-        const name = merged.name || generatedAgentName(index);
+        const name = group?.read().members[index].name || merged.name || generatedAgentName(index);
         try {
           const result = await spawnTeammate({
             ...merged,
             name,
             team_name: sessionName,
-          }, ctx, { allowNestedReadAgents: merged.allow_nested_read_agents === true });
+          }, ctx, { allowNestedReadAgents: merged.allow_nested_read_agents === true, completionGroup: group?.binding(index), signal: _signal });
           spawned.push({ ...result.details, name });
         } catch (error) {
-          failed.push({ name, error: error instanceof Error ? error.message : String(error) });
+          const message = error instanceof Error ? error.message : String(error);
+          failed.push({ name, error: message });
+          if (group) await group.apply({ type: "rejected", ...group.binding(index), runId: group.read().members[index].runId, reason: message });
         }
       }
+      if (group) {
+        await group.seal();
+        await enqueueCompletionGroupDeliveries(group);
+      }
 
       const lines = [`Spawned ${spawned.length}/${params.agents.length} agents in the current Pi session.`];
       for (const item of spawned) lines.push(`- ${item.name}: ${item.queued ? `queued at position ${item.queuePosition}` : `${item.role}, ${item.mode || "in-process"}`}`);
       for (const item of failed) lines.push(`- ${item.name}: failed — ${item.error}`);
       lines.push(AGENT_WAIT_CONTRACT);
-      return { content: [{ type: "text", text: lines.join("\n") }], details: { session: sessionName, spawned, failed } };
+      return { content: [{ type: "text", text: lines.join("\n") }], details: { session: sessionName, spawned, failed,
+        ...(group ? { completionGroup: { groupId: group.groupId, journalPath: group.journalPath } } : {}) } };
     },
   });
 
   return {
     createNestedReadAgentTools,
+    nestedChildSnapshot,
     cancelQueuedAgent: (teamName, agentName) => {
       // Retain the entry for admission bookkeeping, but let active teardown own cancellation after launch commits.
       if (readQueue(teamName).some(queued => queued.member.name === agentName && queued.launchCommitted)) return false;
-      return removeQueuedReadSpawnsByName(teamName, agentName).length > 0;
+      const pending = cancelCheckpointAdmission(teamName, agentName);
+      const removed = removeQueuedReadSpawnsByName(teamName, agentName);
+      return pending || removed.some(item => item.groupSettlement)
+        ? Promise.all([pending, ...removed.map(item => item.groupSettlement)]).then(() => !!pending || removed.length > 0)
+        : removed.length > 0;
     },
   };
 }