pi-extended-teams 2.2.10 → 2.3.1

package/extensions/index.ts

@@ -8,11 +8,14 @@ import { runReadAgentInProcess, sendMessageToRunningReadAgent } from "./agents/r
 import { createWriteAgentRuntime } from "./agents/write-agent.js";
 import { registerExtensionEvents } from "./events/register-events.js";
 import { createLifecycleRuntime } from "./team/lifecycle.js";
+import { createCombinedSessionCost } from "./team/session-cost.js";
 import { buildRoster as buildTeamRoster, formatRosterForPrompt, releaseAllClaimsForAgent, requireTeamContext as resolveTeamContext, requireWriteAgentTeam as resolveWriteAgentTeam } from "./team/roster.js";
 import { createWriterScreenState, registerWriterScreenShortcut, removeWriterScreenTab, upsertWriterScreenTab, type ActiveWriterTab } from "./team/writer-screens.js";
 import { registerFavoriteModelsCommand } from "./ui/favorite-models-command.js";
 import { registerExtensionsCommand } from "./ui/extensions-command.js";
-import { installAgentNavigation } from "./ui/agent-navigation.js";
+import { registerOnboardingCommand } from "./ui/onboarding-command.js";
+import { registerCheckpointsCommand } from "./ui/checkpoints-command.js";
+import { hasActiveReadAgentLifecycle, installAgentNavigation, orderAgentNavigationEntries } from "./ui/agent-navigation.js";
 import { buildReadHelperPrompt, registerCoordinationTools } from "./tools/coordination-tools.js";
 import { createReportProgressTool } from "./tools/agent-communication-tools.js";
 import { registerTaskRuntimeTools } from "./tools/task-runtime-tools.js";
@@ -22,24 +25,38 @@ import { parseQualifiedModel } from "../src/utils/model-resolution";
 import { formatAnimatedProgress, formatContextUsage, formatElapsed, formatModelLabel } from "./ui/renderers.js";
 import type { CompletedAgentReport, RunningReadAgent } from "./runtime/types.js";
 import { createPendingChildController } from "./runtime/pending-child-controller.js";
+import { createTeamHost } from "./runtime/team-host";
+import { registerLeadAttachment, type TeamExecutionOwner } from "./runtime/lead-attachment";
 import { createActiveAgentSleepController, runWithActiveAgentSleepAssertion } from "./runtime/active-agent-sleep.js";
 import { createTeammateInterrupter } from "./runtime/teammate-interrupt.js";
 export { panelBgFill, framePanel, frameWidget, frameWidgetFullWidth, logWindowStart } from "./ui/frame.js";
 import * as messaging from "../src/utils/messaging";
+import { requestCompletionGroupWake, observeCompletionGroupWakes } from "../src/results/completion-group-wake";
+import { recoverCompletionGroups } from "../src/results/completion-group-recovery";
 import * as teams from "../src/utils/teams";
 import * as runtime from "../src/utils/runtime";
 import * as teamPaths from "../src/utils/paths";
 import { listReadHelperQueue, removeQueuedReadHelperRequest } from "../src/utils/read-helper-queue";
 import type { Member } from "../src/utils/models";
+import { projectAgentStatus, projectLifecycleFence } from "../src/orchestration/status-projection";
 import { getTerminalAdapter } from "../src/adapters/terminal-registry";
 import { createSpawnResourcePlan, parentProjectTrustForSpawn } from "./resources/spawn-resource-plan.js";
-import { generateExtensionInstanceId, listLifecycleTombstones, onLifecycleTombstoneCleared, readLifecycleTombstone } from "../src/utils/lifecycle-tombstone";
+import { generateExtensionInstanceId, generateLifecycleRunId, listLifecycleTombstones, onLifecycleTombstoneCleared, readLifecycleTombstone } from "../src/utils/lifecycle-tombstone";
 
-export default function (pi: ExtensionAPI) {
+export default function (pi: ExtensionAPI): void {
+  if (process.env.PI_AGENT_NAME) { createExecutionRuntime(pi); return; }
+  registerLeadAttachment(pi, () => {
+    const host = createTeamHost();
+    return createExecutionRuntime(host.api as unknown as ExtensionAPI, host);
+  });
+}
+
+function createExecutionRuntime(pi: ExtensionAPI, host?: ReturnType<typeof createTeamHost>): TeamExecutionOwner {
   const isTeammate = !!process.env.PI_AGENT_NAME;
   const agentName = process.env.PI_AGENT_NAME || "team-lead";
   const extensionInstanceId = generateExtensionInstanceId();
   const envTeamName = process.env.PI_TEAM_NAME;
+  const combinedSessionCost = isTeammate ? undefined : createCombinedSessionCost(pi);
 
   // Teammates are explicitly bound by PI_TEAM_NAME. Lead sessions are adopted
   // later at session_start only when the persisted Pi session id matches.
@@ -60,6 +77,14 @@ export default function (pi: ExtensionAPI) {
   let readHelperQueueDrainPending = false;
   let sessionCtx: any = null;
   let extensionShuttingDown = false;
+  let executionClosing = false;
+  const pendingRootAdmissions = new Set<Promise<void>>();
+  function trackRootAdmission(): () => void {
+    let settle!: () => void;
+    const pending = new Promise<void>(resolve => { settle = resolve; });
+    pendingRootAdmissions.add(pending);
+    return () => { pendingRootAdmissions.delete(pending); settle(); };
+  }
   const lifecycleFenceClearUnsubscribe = onLifecycleTombstoneCleared((clearedTeamName) => {
     if (clearedTeamName === teamName) void drainReadHelperQueueOnce();
   });
@@ -75,6 +100,7 @@ export default function (pi: ExtensionAPI) {
   let teamActivityStatusSnapshotSignature: string | null = null;
   let teamActivityWidgetMounted = false;
   let teamActivityWidgetTui: { requestRender?: () => void } | null = null;
+  let presentationGeneration = 0;
   let teamActivityRenderInFlight = false;
   let teamActivityRenderDirty = false;
   let teamActivityRenderTimer: NodeJS.Timeout | null = null;
@@ -86,8 +112,10 @@ export default function (pi: ExtensionAPI) {
   // instead of unread count prevents a read message being replaced by a new one
   // at the same count from silently suppressing the new wake.
   const leadWakeNotifiedMessageKeys = new Set<string>();
-  const createCurrentSpawnResourcePlan = (input: { cwd: string; projectTrusted: boolean }) => {
-    return createSpawnResourcePlan({ ...input, pi });
+  const createCurrentSpawnResourcePlan = async (input: { cwd: string; projectTrusted: boolean }) => {
+    while (host && !host.ready) await host.whenAttached();
+    const projectTrusted = host ? parentProjectTrustForSpawn(sessionCtx, input.cwd) : input.projectTrusted;
+    return createSpawnResourcePlan({ ...input, projectTrusted, pi });
   };
   let teamToolsRuntime: TeamToolsRuntime | undefined;
   const pendingChildController = createPendingChildController();
@@ -172,11 +200,12 @@ export default function (pi: ExtensionAPI) {
     targetTeamName: string,
     targetAgentName: string,
     content: string,
-    expectedRecipientRunId?: string
+    expectedRecipientRunId?: string,
+    requireReceipt = false
   ): Promise<boolean> {
     const target = runningReadAgents.get(readAgentKey(targetTeamName, targetAgentName));
     if (expectedRecipientRunId !== undefined && target?.runId !== expectedRecipientRunId) return false;
-    const delivered = await sendMessageToRunningReadAgent(target, content);
+    const delivered = await sendMessageToRunningReadAgent(target, content, requireReceipt);
     if (delivered) renderReadAgentStatus();
     return delivered;
   }
@@ -229,13 +258,6 @@ export default function (pi: ExtensionAPI) {
     return !!status.lastHeartbeatAt && (now - status.lastHeartbeatAt) <= runtime.HEARTBEAT_STALE_MS;
   }
 
-  function hasActiveReadAgentLifecycle(agent: RunningReadAgent): boolean {
-    return agent.teardownState !== "stopping"
-      && agent.teardownState !== "quarantined"
-      && agent.teardownState !== "persistence_failed"
-      && agent.teardownState !== "finalized";
-  }
-
   function isVisibleRuntimeOnlyMember(
     member: Member,
     runtimeStatus: runtime.AgentRuntimeStatus | null,
@@ -337,11 +359,11 @@ export default function (pi: ExtensionAPI) {
   // message with display:false still reaches the model as a user turn (see
   // convertToLlm) but is never rendered, so team coordination stays silent.
   // Falls back to a visible user message on older pi builds without sendMessage.
-  function quietTrigger(content: string): void {
+  function quietTrigger(content: string, details?: Record<string, unknown>): void {
     const api = pi as any;
     if (typeof api.sendMessage === "function") {
       api.sendMessage(
-        { customType: "pi-extended-teams-wake", content, display: false },
+        { customType: "pi-extended-teams-wake", content, display: false, ...(details ? { details } : {}) },
         { triggerTurn: true, deliverAs: "followUp" }
       );
     } else {
@@ -378,9 +400,46 @@ export default function (pi: ExtensionAPI) {
     pi.events?.emit?.("pi-extended-teams:agent-progress", { teamName: progressTeamName, name, status, updatedAt });
   }
 
-  function wakeLeadForInboxReports(unread: any[]): void {
-    if (!teamName) return;
-    const keyedUnread = unread.map((message) => ({
+  const currentCompletionGroups = new Set<string>();
+  const observedWakeEntries = new Set<string>();
+  const groupWarnings = new Set<string>();
+  const sessionEntries = (ctx: any) => ctx?.sessionManager?.getEntries?.() ?? ctx?.sessionManager?.getBranch?.() ?? [];
+  function warnGroup(error: unknown): void {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!groupWarnings.has(message)) {
+      groupWarnings.add(message);
+      sessionCtx?.ui?.notify?.(message, "warning");
+    }
+  }
+  async function observeGroupHistory(ctx: any): Promise<void> {
+    if (!teamName || extensionShuttingDown) return;
+    const target = teamName;
+    const entries = sessionEntries(ctx).filter((entry: any) => !observedWakeEntries.has(`${target}:${entry.id}`));
+    const result = await observeCompletionGroupWakes(target, getPiSessionId(ctx) ?? "", entries);
+    for (const id of result.observed) observedWakeEntries.add(`${target}:${id}`);
+    for (const error of result.errors) warnGroup(error);
+  }
+  async function requestGroupInboxWakes(unread: any[]): Promise<void> {
+    if (!teamName || !sessionCtx || extensionShuttingDown) return;
+    const target = teamName;
+    const ctx = sessionCtx;
+    for (const message of unread.filter(item => item.metadata?.completionGroup)) {
+      try {
+        if (typeof (pi as any).sendMessage !== "function") throw new Error("Grouped wakes require Pi custom messages; use read_inbox for the saved index.");
+        await requestCompletionGroupWake(target, getPiSessionId(ctx) ?? "", message, (content, details) => {
+          if (extensionShuttingDown || ctx !== sessionCtx) throw new Error("Group wake unconfirmed: the lead session is closing.");
+          quietTrigger(content, details);
+        });
+      } catch (error) { warnGroup(error); }
+    }
+  }
+  async function wakeLeadForInboxReports(unread: any[]): Promise<void> {
+    if (!teamName || extensionShuttingDown) return;
+    const target = teamName;
+    const ctx = sessionCtx;
+    await requestGroupInboxWakes(unread);
+    if (extensionShuttingDown || target !== teamName || ctx !== sessionCtx) return;
+    const keyedUnread = unread.filter(message => !message.metadata?.completionGroup).map((message) => ({
       message,
       key: String(message?.id || `${message?.from || "unknown"}:${message?.timestamp || ""}:${message?.text || ""}`),
     }));
@@ -409,10 +468,13 @@ export default function (pi: ExtensionAPI) {
   }
 
   async function notifyLeadOfInboxReports(targetTeamName: string): Promise<void> {
-    if (isTeammate) return;
+    if (isTeammate || extensionShuttingDown) return;
+    const generation = presentationGeneration;
     const unread = await messaging.peekInbox(targetTeamName, agentName, true);
+    if (generation !== presentationGeneration) return;
     await renderLeadInboxStatus();
-    wakeLeadForInboxReports(unread);
+    if (generation !== presentationGeneration) return;
+    await wakeLeadForInboxReports(unread);
   }
 
   function getIdleReadAgentNudgeMessage(agent: RunningReadAgent, status: ReadAgentStatusDescription): string | null {
@@ -492,6 +554,7 @@ export default function (pi: ExtensionAPI) {
       return;
     }
 
+    const generation = presentationGeneration;
     teamActivityRenderInFlight = true;
     let renderError: unknown;
     try {
@@ -500,6 +563,7 @@ export default function (pi: ExtensionAPI) {
     } catch (error) {
       renderError = error;
     } finally {
+      if (generation !== presentationGeneration) return;
       teamActivityRenderInFlight = false;
       if (renderError) {
         teamActivityRenderDirty = false;
@@ -564,14 +628,17 @@ export default function (pi: ExtensionAPI) {
 
   async function renderTeamActivityStatusNow() {
     if (!sessionCtx?.ui) return;
+    const generation = presentationGeneration;
+    const isCurrent = () => generation === presentationGeneration && !extensionShuttingDown;
 
     const now = Date.now();
     const activityTeamName = teamName || null;
-    const runningAgents = activityTeamName
+    const sessionAgents = activityTeamName
       ? Array.from(runningReadAgents.values())
-        .filter(agent => agent.teamName === activityTeamName && hasActiveReadAgentLifecycle(agent))
+        .filter(agent => agent.teamName === activityTeamName)
         .sort((a, b) => a.name.localeCompare(b.name))
       : [];
+    const runningAgents = sessionAgents.filter(hasActiveReadAgentLifecycle);
     const readAgents = runningAgents.filter(agent => (agent.role || "read") === "read");
     const writeAgents = runningAgents.filter(agent => (agent.role || "read") === "write");
     const activityConfig = activityTeamName ? await teams.readConfig(activityTeamName).catch(() => null) : null;
@@ -579,17 +646,22 @@ export default function (pi: ExtensionAPI) {
     const activityTombstones = activityTeamName
       ? await listLifecycleTombstones(activityTeamName).catch(() => [])
       : [];
-    const runtimeOnlyMembers = activityTeamName
-      ? (await Promise.all(activityMembers
+    const unsettledAgents = sessionAgents.filter(agent => !hasActiveReadAgentLifecycle(agent)
+      && agent.teardownState !== "finalized"
+      && !activityTombstones.some(fence => fence.agentName === agent.name));
+    const runtimeOnlyCandidates = activityTeamName
+      ? await Promise.all(activityMembers
         .filter(member => member.name !== "team-lead")
         .filter(member => !runningReadAgents.has(readAgentKey(activityTeamName, member.name)))
         .map(async (member) => ({
           member,
           runtimeStatus: await runtime.readRuntimeStatus(activityTeamName, member.name).catch(() => null),
-        }))))
-        .filter((entry): entry is { member: Member; runtimeStatus: runtime.AgentRuntimeStatus } => isVisibleRuntimeOnlyMember(entry.member, entry.runtimeStatus, now))
-        .filter(({ member, runtimeStatus }) => member.lifecycleRunId === runtimeStatus.lifecycleRunId)
+        })))
       : [];
+    if (!isCurrent()) return;
+    const runtimeOnlyMembers = runtimeOnlyCandidates
+      .filter((entry): entry is { member: Member; runtimeStatus: runtime.AgentRuntimeStatus } => isVisibleRuntimeOnlyMember(entry.member, entry.runtimeStatus, now))
+      .filter(({ member, runtimeStatus }) => member.lifecycleRunId === runtimeStatus.lifecycleRunId);
     const runtimeOnlyMemberNames = new Set(runtimeOnlyMembers.map(({ member }) => member.name));
     const runtimeOnlyReadMembers = runtimeOnlyMembers.filter(({ member }) => memberActivityRole(member) === "read");
     const runtimeOnlyWriteMembers = runtimeOnlyMembers.filter(({ member }) => memberActivityRole(member) === "write");
@@ -618,6 +690,11 @@ export default function (pi: ExtensionAPI) {
         .filter(member => member.name !== "team-lead" && member.isActive !== false && memberActivityRole(member) === "write")
         .filter(member => !!(member.tmuxPaneId && terminal?.isAlive?.(member.tmuxPaneId)) && !runningReadAgents.has(readAgentKey(activityTeamName, member.name)) && !runtimeOnlyMemberNames.has(member.name)) ?? []
       : [];
+    const unobservedMembers = runtimeOnlyCandidates.filter(({ member }) => member.isActive !== false
+      && !runtimeOnlyMemberNames.has(member.name)
+      && !activeWriteMembers.some(writer => writer.name === member.name)
+      && !activityTombstones.some(fence => fence.agentName === member.name));
+    const activeCount = runningAgents.length + runtimeOnlyMembers.length + activeWriteMembers.length + unobservedMembers.length;
     navigationRuntimeAgents.clear();
     for (const { member, runtimeStatus } of runtimeOnlyReadMembers) {
       if (member.lifecycleRunId === runtimeStatus.lifecycleRunId) {
@@ -630,14 +707,16 @@ export default function (pi: ExtensionAPI) {
       }
     }
     const unreadLeadMessages = activityTeamName ? await messaging.readInbox(activityTeamName, agentName, true, false).catch(() => []) : [];
+    if (!isCurrent()) return;
     leadInboxUnreadCount = unreadLeadMessages.length;
     clearLeadInboxWidgetOnce();
 
-    if ((readAgents.length > 0 || writeAgents.length > 0 || runtimeOnlyReadMembers.length > 0 || runtimeOnlyWriteMembers.length > 0 || activeWriteMembers.length > 0 || activityTombstones.length > 0) && !readAgentStatusTimer) {
+    const hasVisibleAgents = activeCount > 0 || unsettledAgents.length > 0 || activityTombstones.length > 0;
+    if (hasVisibleAgents && !readAgentStatusTimer) {
       readAgentStatusTimer = setInterval(renderReadAgentStatus, 1000);
     }
 
-    if (readAgents.length === 0 && writeAgents.length === 0 && runtimeOnlyReadMembers.length === 0 && runtimeOnlyWriteMembers.length === 0 && activeWriteMembers.length === 0 && activityTombstones.length === 0) {
+    if (!hasVisibleAgents) {
       sessionCtx.ui.setStatus?.("01-pi-extended-teams-read", undefined);
       clearTeamActivityWidget();
       sessionCtx.ui.setWidget?.("01-pi-extended-teams-status", undefined);
@@ -648,7 +727,6 @@ export default function (pi: ExtensionAPI) {
       return;
     }
 
-    const activeCount = readAgents.length + writeAgents.length + runtimeOnlyReadMembers.length + runtimeOnlyWriteMembers.length + activeWriteMembers.length;
     const entries: TeamActivityStatusEntry[] = [];
     const footerStatuses: string[] = [];
     const statusCounts: Record<string, number> = {};
@@ -698,6 +776,7 @@ export default function (pi: ExtensionAPI) {
         joinedAt: member.joinedAt,
       });
       const runtimeStatus = await runtime.readRuntimeStatus(activityTeamName!, member.name).catch(() => null);
+      if (!isCurrent()) return;
       const elapsed = formatElapsed(now - (runtimeStatus?.startedAt || member.joinedAt));
       const modelLabel = formatModelLabel(member.model, member.thinking);
       const contextUsage = formatRunningContextUsage(runtimeStatus?.contextUsage);
@@ -742,16 +821,43 @@ export default function (pi: ExtensionAPI) {
       footerStatuses.push(formatAgentProgressStatus(agent.name, agent.model, agent.thinking, agent.modelSlot, elapsed, contextUsage, agent.latestProgress, now));
     }
 
+    for (const { member, runtimeStatus } of unobservedMembers) {
+      const projected = projectAgentStatus({ member, runtime: runtimeStatus, fence: { status: "absent" }, terminalAlive: null, now });
+      const telemetry = !projected.runtime ? "runtime telemetry unavailable"
+        : runtimeHeartbeatIsRecent(projected.runtime, now) ? "awaiting runtime readiness" : "heartbeat stale";
+      countStatus(projected.phase);
+      entries.push({ name: member.name, role: memberActivityRole(member), status: projected.phase, detail: telemetry });
+      footerStatuses.push(`(${member.name}) ${projected.phase} · ${telemetry}`);
+    }
+
+    for (const agent of unsettledAgents) {
+      const status = agent.teardownState === "persistence_failed" ? "persistence-failed"
+        : agent.teardownState === "quarantined" ? "quarantined" : "stopping";
+      const reason = agent.teardownError instanceof Error ? agent.teardownError.message
+        : agent.teardownResult?.error || "cleanup has not settled";
+      const detail = status === "stopping" ? "Finishing cleanup" : `Cleanup blocked: ${reason} · use check_teammate`;
+      countStatus(status);
+      entries.push({ name: agent.name, role: agent.role === "write" ? "write" : "read", status, detail });
+    }
+
     for (const { agentName: quarantinedName, result } of activityTombstones) {
+      if (result.status === "occupied" && result.tombstone.phase === "persistence_closed"
+        && runningAgents.some(agent => agent.name === quarantinedName && agent.runId === result.tombstone.runId)) {
+        const entryIndex = entries.findIndex(entry => entry.name === quarantinedName);
+        footerStatuses[entryIndex] += " · Finishing cleanup";
+        continue;
+      }
       const persistedMember = activityMembers.find(member => member.name === quarantinedName);
       const role = result.status === "occupied"
         ? result.tombstone.role
         : persistedMember ? memberActivityRole(persistedMember) : "read";
-      const detail = result.status === "occupied"
-        ? `inactive · run ${result.tombstone.runId} · ${result.tombstone.phase}`
-        : `inactive · corrupt lifecycle tombstone · ${result.error}`;
-      countStatus("quarantined");
-      entries.push({ name: quarantinedName, role, status: "quarantined", detail });
+      const projected = projectLifecycleFence(persistedMember ?? {}, result);
+      const reason = projected.error || (result.status === "occupied" && result.tombstone.phase === "timed_out" ? "cleanup timed out" : "cleanup failed");
+      const detail = projected.phase === "stopping"
+        ? "Finishing cleanup"
+        : `Cleanup blocked: ${reason} · use check_teammate`;
+      countStatus(projected.phase);
+      entries.push({ name: quarantinedName, role, status: projected.phase, detail });
     }
 
     wakeLeadForIdleReadAgents(idleNudgeMessages);
@@ -762,8 +868,8 @@ export default function (pi: ExtensionAPI) {
     sessionCtx.ui.setWidget?.("01-pi-extended-teams-status", undefined);
     updateTeamActivityWidget({
       activeCount,
-      readCount: readAgents.length + runtimeOnlyReadMembers.length,
-      writeCount: writeAgents.length + runtimeOnlyWriteMembers.length + activeWriteMembers.length,
+      readCount: readAgents.length + runtimeOnlyReadMembers.length + unobservedMembers.filter(({ member }) => memberActivityRole(member) === "read").length,
+      writeCount: writeAgents.length + runtimeOnlyWriteMembers.length + activeWriteMembers.length + unobservedMembers.filter(({ member }) => memberActivityRole(member) === "write").length,
       unreadCount: leadInboxUnreadCount,
       entries,
       statusCounts,
@@ -795,12 +901,13 @@ export default function (pi: ExtensionAPI) {
   }
 
   async function drainReadHelperQueueOnce() {
-    if (isTeammate || !sessionCtx || !teamName) return;
+    if (isTeammate || !sessionCtx || !teamName || (host && !host.ready)) return;
     if (readHelperQueueDraining) {
       readHelperQueueDrainPending = true;
       return;
     }
     readHelperQueueDraining = true;
+    const settled = trackRootAdmission();
     try {
       for (let drained = 0; drained < 10 && teamName; drained++) {
         const [nextQueued] = await listReadHelperQueue(teamName);
@@ -811,6 +918,8 @@ export default function (pi: ExtensionAPI) {
 
         try {
           const config = await teams.readConfig(queued.teamName);
+          const launchContext = sessionCtx;
+          if (!launchContext || (host && !host.ready)) return;
           if (config.members.some(member => member.name === queued.name)) {
             throw new Error(`Teammate ${queued.name} already exists in team ${queued.teamName}.`);
           }
@@ -819,7 +928,7 @@ export default function (pi: ExtensionAPI) {
           const parsedModel = parseQualifiedModel(level.model);
           const provider = parsedModel?.provider;
           const modelId = parsedModel?.model;
-          const model = provider && modelId ? sessionCtx.modelRegistry?.find?.(provider, modelId) : undefined;
+          const model = provider && modelId ? launchContext.modelRegistry?.find?.(provider, modelId) : undefined;
           if (!model) throw new Error(`Read helper model \"${level.model}\" from intent tier ${level.slot} is not available in the lead session.`);
 
           const helperPrompt = buildReadHelperPrompt(queued.teamName, queued.requester, queued.prompt);
@@ -841,9 +950,15 @@ export default function (pi: ExtensionAPI) {
             helperKind: "read_helper",
           };
 
+          member.lifecycleRunId = generateLifecycleRunId();
           await teams.addMember(queued.teamName, member);
+          if (executionClosing) {
+            await shutdownTeammate(queued.teamName, member);
+            await removeQueuedReadHelperRequest(queued.teamName, queued.id);
+            break;
+          }
           observeReadAgentLaunch(
-            runInProcessAgentWithSleepAssertion(queued.teamName, member, helperPrompt, sessionCtx, readAgentOptions())
+            runInProcessAgentWithSleepAssertion(queued.teamName, member, helperPrompt, launchContext, readAgentOptions())
           );
           await removeQueuedReadHelperRequest(teamName, queued.id);
         } catch (e) {
@@ -896,6 +1011,7 @@ export default function (pi: ExtensionAPI) {
         }
       }
     } finally {
+      settled();
       readHelperQueueDraining = false;
       if (readHelperQueueDrainPending) {
         readHelperQueueDrainPending = false;
@@ -948,10 +1064,13 @@ export default function (pi: ExtensionAPI) {
 
     leadInboxPollTimer = setInterval(async () => {
       if (!teamName) return;
+      const generation = presentationGeneration;
       try {
         const unread = await messaging.readInbox(teamName, agentName, true, false);
+        if (generation !== presentationGeneration) return;
         await renderLeadInboxStatus();
-        wakeLeadForInboxReports(unread);
+        if (generation !== presentationGeneration) return;
+        await wakeLeadForInboxReports(unread);
       } catch {
         // Ignore errors for lead polling
       }
@@ -965,10 +1084,12 @@ export default function (pi: ExtensionAPI) {
   function adoptTeamAsLead(name: string, ctx?: any): void {
     if (isTeammate || !name) return;
     const sessionId = getPiSessionId(ctx ?? sessionCtx);
+    registerLeadSession(name, sessionId);
+    // Private jobs retain cleanup ownership, not the public roster/inbox/UI scope.
+    if (name.startsWith("prompt-build-")) return;
     if (teamName !== name) {
       teamName = name;
     }
-    registerLeadSession(name, sessionId);
     ensureReadAgentStatusTicker();
     startLeadInboxPolling();
     startReadHelperQueueDraining();
@@ -978,11 +1099,12 @@ export default function (pi: ExtensionAPI) {
   pi.events?.on?.("pi-prompt:prompt-build:start", async (payload: any) => {
     if (isTeammate || !sessionCtx) return;
     const requestedTeamName = teamPaths.sanitizeName(payload?.teamName || `prompt-build-${Date.now()}`);
-
+    const launchContext = sessionCtx;
+    const settled = trackRootAdmission();
     try {
       const prompts = Array.isArray(payload?.prompts) ? payload.prompts : [];
       activePromptBuildTeamName = requestedTeamName;
-      const cwd = payload?.cwd || sessionCtx.cwd;
+      const cwd = payload?.cwd || launchContext.cwd;
       const agentNamePrefix = teamPaths.sanitizeName(payload?.agentNamePrefix || "prompt-branch");
       if (payload?.model || payload?.thinking || payload?.role) {
         throw new Error("Prompt-build agents must use model_slot only; direct model, thinking, or role is not allowed.");
@@ -992,7 +1114,7 @@ export default function (pi: ExtensionAPI) {
       if (level.role !== "read") throw new Error(`Prompt-build requires a read-* intent tier configured via /agents-favorite-models, got ${level.slot}.`);
 
       if (!teams.teamExists(requestedTeamName)) {
-        teams.createTeam(requestedTeamName, getPiSessionId(sessionCtx) || "local-session", "lead-agent", payload?.description || "pi-prompt prompt-build", level.model);
+        teams.createTeam(requestedTeamName, getPiSessionId(launchContext) || "local-session", "lead-agent", payload?.description || "pi-prompt prompt-build", level.model);
       }
       // Prompt-build teams are private fanout jobs owned by pi-prompt. Do not
       // adopt them as the lead's current team, or normal session context and
@@ -1017,21 +1139,25 @@ export default function (pi: ExtensionAPI) {
           thinking: level.thinking,
           modelSlot: level.slot,
         };
+        if (executionClosing) break;
+        member.lifecycleRunId = generateLifecycleRunId();
         await teams.addMember(requestedTeamName, member);
+        if (executionClosing) { await shutdownTeammate(requestedTeamName, member); break; }
         observeReadAgentLaunch(
-          runInProcessAgentWithSleepAssertion(requestedTeamName, member, prompt, sessionCtx, readAgentOptions())
+          runInProcessAgentWithSleepAssertion(requestedTeamName, member, prompt, launchContext, readAgentOptions())
         );
         pi.events?.emit?.("pi-prompt:prompt-build:progress", { teamName: requestedTeamName, status: "spawned", started: i + 1, total: prompts.length, text: `building prompt — ${i + 1}/${prompts.length} branches started` });
       }
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       pi.events?.emit?.("pi-prompt:prompt-build:error", { teamName: requestedTeamName, error: message });
-    }
+    } finally { settled(); }
   });
 
   function setSessionCtx(ctx: any): void {
+    if (host && !host.attached) return;
     extensionShuttingDown = false;
-    sessionCtx = ctx;
+    sessionCtx = host?.context ?? ctx;
     if (!isTeammate && !teamName) {
       const foundTeam = findLeadTeamForSession(getPiSessionId(ctx));
       if (foundTeam) adoptTeamAsLead(foundTeam, ctx);
@@ -1065,7 +1191,10 @@ export default function (pi: ExtensionAPI) {
     }
   }
 
-  async function cleanupExtensionRuntime(ctx: any, reason: unknown): Promise<void> {
+  function detachPresentation(): void {
+    presentationGeneration++;
+    teamActivityRenderInFlight = false;
+    navigationRuntimeAgents.clear();
     extensionShuttingDown = true;
     sessionCtx = null;
     stopLeadWatchdog();
@@ -1081,16 +1210,24 @@ export default function (pi: ExtensionAPI) {
     readHelperQueueFallbackTimer = null;
     readHelperQueueWatcher = null;
     leadPollingStarted = false;
-    leadWakeNotifiedMessageKeys.clear();
     readHelperQueueFallbackStarted = false;
     readHelperQueueWatchedTeam = null;
-    lifecycleFenceClearUnsubscribe();
     teamActivityRenderDirty = false;
     settleTeamActivityRenderWaiters();
+    teamActivityStatusSnapshot = null;
+    teamActivityStatusSnapshotSignature = null;
+    teamActivityWidgetMounted = false;
+    teamActivityWidgetTui = null;
+  }
 
+  async function cleanupExtensionRuntime(ctx: any, reason: unknown): Promise<void> {
+    detachPresentation();
+    leadWakeNotifiedMessageKeys.clear();
+    lifecycleFenceClearUnsubscribe();
     try {
       await stopRunningAgentsForShutdown(reason);
     } finally {
+      combinedSessionCost?.deactivate();
       activeAgentSleepController.dispose();
     }
 
@@ -1121,14 +1258,23 @@ export default function (pi: ExtensionAPI) {
   });
 
   if (!isTeammate) {
+    pi.on("context", async (_event: any, ctx: any) => { await observeGroupHistory(ctx); });
     pi.on("session_start", async (_event: any, ctx: any) => {
+      await observeGroupHistory(ctx);
+      if (teamName) {
+        try {
+          const config = await teams.readConfig(teamName);
+          for (const error of await recoverCompletionGroups(teamName, getPiSessionId(ctx) ?? "", config.members, sessionEntries(ctx), currentCompletionGroups)) warnGroup(error);
+          await requestGroupInboxWakes(await messaging.peekInbox(teamName, agentName, true));
+        } catch (error) { warnGroup(error); }
+      }
       installAgentNavigation(ctx, {
         getAgents: () => {
           const readers = Array.from(runningReadAgents.values())
             .filter(agent => !teamName || agent.teamName === teamName);
-          return [...readers, ...Array.from(navigationRuntimeAgents.values())
-            .filter(agent => !teamName || agent.teamName === teamName)]
-            .filter((agent, index, agents) => agents.findIndex(candidate => candidate.name === agent.name) === index);
+          const runtimeAgents = Array.from(navigationRuntimeAgents.values())
+            .filter(agent => !teamName || agent.teamName === teamName);
+          return orderAgentNavigationEntries(readers, runtimeAgents);
         },
         interruptAgent: async (name: string) => {
           const result = await interruptTeammate(name);
@@ -1188,6 +1334,8 @@ export default function (pi: ExtensionAPI) {
 
   registerFavoriteModelsCommand(pi);
   registerExtensionsCommand(pi);
+  if (!isTeammate) registerOnboardingCommand(pi);
+  if (!isTeammate) registerCheckpointsCommand(pi);
 
   registerWriterScreenShortcut(pi, {
     getTeamName: () => teamName,
@@ -1218,7 +1366,11 @@ export default function (pi: ExtensionAPI) {
       createNestedReadAgentTools: (binding: Parameters<TeamToolsRuntime["createNestedReadAgentTools"]>[0]) => {
         return teamToolsRuntime?.createNestedReadAgentTools(binding) ?? [];
       },
+      nestedChildSnapshot: (binding: Parameters<TeamToolsRuntime["nestedChildSnapshot"]>[0]) => {
+        return teamToolsRuntime?.nestedChildSnapshot(binding) ?? { running: 0, queued: 0 };
+      },
       pendingChildController,
+      beginCostRun: combinedSessionCost?.begin,
     };
   }
 
@@ -1233,6 +1385,7 @@ export default function (pi: ExtensionAPI) {
     startWriteAgent,
     shutdownTeammate,
     adoptTeamAsLead,
+    onCompletionGroupUse: groupId => { currentCompletionGroups.add(groupId); },
     buildRoster,
     isTeammate,
     agentName,
@@ -1240,6 +1393,8 @@ export default function (pi: ExtensionAPI) {
     getSessionCtx: () => sessionCtx,
     setSessionCtx,
     pendingChildController,
+    isHostAttached: () => !host || host.ready,
+    waitForHost: () => host?.whenAttached() ?? Promise.resolve(),
   });
 
   if (isTeammate) {
@@ -1251,7 +1406,7 @@ export default function (pi: ExtensionAPI) {
     }));
   }
 
-  registerCoordinationTools(pi, {
+  const coordination: Parameters<typeof registerCoordinationTools>[1] = {
     agentName,
     isTeammate,
     terminal,
@@ -1266,9 +1421,10 @@ export default function (pi: ExtensionAPI) {
     resetLeadWakeNotifiedCount: () => { leadWakeNotifiedMessageKeys.clear(); },
     deliverMessageToActiveAgent,
     extensionInstanceId,
-  });
+  };
+  if (isTeammate) registerCoordinationTools(pi, coordination);
 
-  registerTaskRuntimeTools(pi, {
+  const taskTools: Parameters<typeof registerTaskRuntimeTools>[1] = {
     isTeammate,
     terminal,
     runningReadAgents,
@@ -1277,6 +1433,47 @@ export default function (pi: ExtensionAPI) {
     cancelQueuedAgent: (targetTeamName, targetAgentName) => teamToolsRuntime?.cancelQueuedAgent(targetTeamName, targetAgentName) ?? false,
     shutdownTeammate,
     getTeamName: () => teamName,
-  });
-
+  };
+  if (isTeammate) registerTaskRuntimeTools(pi, taskTools);
+
+  return {
+    host: host!, coordination, taskTools,
+    hasWork: () => runningReadAgents.size > 0 || activeWritersTabs.length > 0 || pendingRootAdmissions.size > 0 || teamToolsRuntime?.hasPendingWork() === true,
+    async attach(binding) {
+      host!.attach(binding);
+      const ctx = host!.snapshot(binding.ctx);
+      const costAttached = combinedSessionCost?.attach(binding.pi, ctx);
+      await host!.emit("session_start", binding.event, ctx);
+      if (!host!.attached) return;
+      if (!costAttached) combinedSessionCost?.attach(binding.pi, ctx);
+    },
+    activate() {
+      host!.flush();
+      teamToolsRuntime?.resumeQueues();
+      void drainReadHelperQueueOnce();
+      if (teamName) void notifyLeadOfInboxReports(teamName).catch(warnGroup);
+    },
+    detach() {
+      sessionCtx?.ui?.setWidget?.("01-pi-extended-teams-readers", undefined);
+      sessionCtx?.ui?.setWidget?.("01-pi-extended-teams-status", undefined);
+      detachPresentation();
+      combinedSessionCost?.detach();
+      host?.detach();
+    },
+    async close(reason) {
+      teamToolsRuntime.closeAdmission();
+      executionClosing = true;
+      sessionCtx?.ui?.setWidget?.("01-pi-extended-teams-readers", undefined);
+      sessionCtx?.ui?.setWidget?.("01-pi-extended-teams-status", undefined);
+      detachPresentation();
+      host?.close();
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const admissions = Promise.race([
+        Promise.all([...pendingRootAdmissions]),
+        new Promise<never>((_resolve, reject) => { timer = setTimeout(() => reject(new Error("Team admission cleanup is still pending.")), 2_500); }),
+      ]).finally(() => clearTimeout(timer));
+      await Promise.all([host!.emit("session_shutdown", { reason }, undefined), admissions]);
+      if (runningReadAgents.size) throw new Error("Team cleanup is still fenced by unsettled agents.");
+    },
+  };
 }