pi-extended-teams 2.2.7 → 2.2.8

package/README.md

@@ -40,11 +40,11 @@ The current Pi session becomes the agent group automatically. There is no separa
 
 ## How it works
 
-- Read agents run in-process. Edit agents run in separate Pi sessions through the configured terminal adapter. Both stay connected to the lead session.
+- Public read and edit agents run in separate in-process Pi sessions. A write tier grants edit tools; it does not open a terminal pane. The terminal runtime remains available for existing integrations.
 - The activity card shows progress, intent tier, elapsed time, tokens, and tool activity.
 - You can open an agent's transcript, send it a message, interrupt a stuck tool command, or stop it.
 - Completed reports return to the lead automatically and remain recoverable when needed.
-- `get_agent_status` gives the lead or an eligible nested parent one read-only snapshot of owned active, queued, stalled, or recently completed read and edit agents.
+- `get_agent_status` gives the lead or an eligible nested parent one read-only snapshot of owned active, queued, stalled, or recently completed read and edit agents. It uses current-run evidence, preserves lifecycle quarantine, and does not perform cleanup.
 - Every spawn names an intent tier instead of choosing ad hoc model settings. Configured favorites take priority; unset tiers inherit the current lead model and thinking.
 - Edit agents can claim isolated files. Claims coordinate cooperative agents; they are not access control.
 - Lazy session context and nested read helpers are available when a bounded task needs them.
@@ -104,6 +104,8 @@ For an edit, choose a write tier and name the files it may claim. Never run over
 
 Global settings live at `~/.pi/agent/pi-extended-teams/settings.json`. Project overrides live at `.pi/pi-extended-teams.json`. Favorite intent tiers are global so `/agents-favorite-models` and spawning use the same choices. Configuring favorites is optional; an unset tier falls back to the current lead-session model and thinking level.
 
+Public read and edit spawns respect their role's concurrency limit and overflow setting. Enabled overflow queues accepted work; disabled overflow returns a capacity error. Quarantined requests stay fenced without blocking unrelated eligible work. `stop_teammate` can cancel a queued request before launch. Failed admissions trigger an attempted recipient notification and remain visible in status (up to 20 recent failures). The public queue and recent failure index are session-local, not restart-durable.
+
 Spawned sessions are private by default under `~/.pi/teams/<team>/agent-sessions/` and stay out of Pi's normal `/resume` picker.
 
 ## Security and data access

package/extensions/agents/read-agent.ts

@@ -590,7 +590,9 @@ export async function runReadAgentInProcess(
     resolveSessionCreation = resolve;
   });
   let lifecycleRunId = member.lifecycleRunId ?? generateLifecycleRunId();
-  if (teams.teamExists(readTeamName)) {
+  // Admitted runs can publish startup ownership without awaiting the compatibility lookup.
+  // writeRuntimeStatus validates their identity under lifecycle/config locks before work starts.
+  if (!member.lifecycleRunId && teams.teamExists(readTeamName)) {
     lifecycleRunId = await teams.ensureMemberLifecycleRunId(readTeamName, member.name, lifecycleRunId);
   }
   member.lifecycleRunId = lifecycleRunId;

package/extensions/index.ts

@@ -1274,6 +1274,7 @@ export default function (pi: ExtensionAPI) {
     runningReadAgents,
     readAgentKey,
     interruptTeammate,
+    cancelQueuedAgent: (targetTeamName, targetAgentName) => teamToolsRuntime?.cancelQueuedAgent(targetTeamName, targetAgentName) ?? false,
     shutdownTeammate,
     getTeamName: () => teamName,
   });

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

@@ -2,27 +2,22 @@ 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, type LifecycleTombstoneReadResult } from "../../src/utils/lifecycle-tombstone";
+import { readLifecycleTombstone } from "../../src/utils/lifecycle-tombstone";
+import { projectAgentStatus, type ActiveAgentPhase } from "../../src/orchestration/status-projection";
 import type { Member, TeamReportEvent } from "../../src/utils/models";
 import type { RunningReadAgent } from "../runtime/types";
 import { isWriteMemberAlive } from "../team/roster";
-import { describeReadAgentStatus } from "../ui/read-agent-status";
 import { formatElapsed } from "../ui/renderers";
 
-export type AgentStatusPhase =
-  | RunningReadAgent["status"]
-  | TeamReportEvent["status"]
-  | "queued"
-  | "stalled"
-  | "stopping"
-  | "quarantined"
-  | "persistence-failed";
+export type AgentStatusPhase = ActiveAgentPhase | TeamReportEvent["status"] | "queued";
 
 export interface QueuedAgentStatus {
   name: string;
   role: string;
   queuedAt: number;
   queuePosition: number;
+  error?: string;
+  failed?: boolean;
   parentAgentName?: string;
   parentLifecycleRunId?: string;
 }
@@ -85,55 +80,6 @@ function ownsReport(report: TeamReportEvent, scope?: AgentStatusScope): boolean
     && (typeof parentRunId !== "string" || parentRunId === scope.parentRunId);
 }
 
-function lifecycleMatches(member: Member, runId?: string): boolean {
-  return member.lifecycleRunId === runId;
-}
-
-function persistedLifecycleStatus(
-  member: Member,
-  result: LifecycleTombstoneReadResult,
-): Pick<AgentStatusSnapshot, "phase" | "error"> | undefined {
-  if (result.status === "absent") return undefined;
-  if (result.status === "corrupt") return { phase: "quarantined", error: result.error };
-
-  const tombstone = result.tombstone;
-  const runMismatch = member.lifecycleRunId && tombstone.runId !== member.lifecycleRunId
-    ? `Lifecycle fence belongs to run ${tombstone.runId}, not roster run ${member.lifecycleRunId}.`
-    : undefined;
-  const phase = tombstone.phase === "cleanup_failed" || tombstone.phase === "timed_out"
-    ? "quarantined"
-    : "stopping";
-  return { phase, error: runMismatch || tombstone.error };
-}
-
-function phaseForActiveAgent(
-  member: Member,
-  state: RunningReadAgent | undefined,
-  runtimeStatus: runtime.AgentRuntimeStatus | null,
-  persistedStatus: Pick<AgentStatusSnapshot, "phase" | "error"> | undefined,
-  now: number,
-  terminal: any,
-): AgentStatusPhase {
-  if (state?.teardownState === "persistence_failed") return "persistence-failed";
-  if (state?.teardownState === "quarantined") return "quarantined";
-  if (state?.teardownState === "stopping") return "stopping";
-  if (persistedStatus) return persistedStatus.phase;
-  if (state && state.teardownState !== "finalized") {
-    return describeReadAgentStatus(state, now).label === "hanging" ? "stalled" : state.status;
-  }
-
-  const heartbeatFresh = runtime.isHeartbeatFresh(runtimeStatus, now);
-  const paneAlive = member.isActive !== false && isWriteMemberAlive(member, terminal);
-  if (!heartbeatFresh && !paneAlive) {
-    if (member.isActive !== false && !runtimeStatus?.ready && now - member.joinedAt <= runtime.STARTUP_STALL_MS) return "starting";
-    return "stalled";
-  }
-
-  const action = runtimeStatus?.currentAction;
-  if (action) return action === "done" ? "finishing" : action;
-  return runtimeStatus?.ready ? "working" : "starting";
-}
-
 async function activeStatus(
   teamName: string,
   member: Member,
@@ -148,25 +94,24 @@ async function activeStatus(
       error: error instanceof Error ? error.message : String(error),
     })),
   ]);
-  const state = candidateState && lifecycleMatches(member, candidateState.runId)
-    ? candidateState
-    : undefined;
-  const runtimeStatus = candidateRuntimeStatus && lifecycleMatches(member, candidateRuntimeStatus.lifecycleRunId)
-    ? candidateRuntimeStatus
-    : null;
-  const persistedStatus = persistedLifecycleStatus(member, lifecycleResult);
+  const projected = projectAgentStatus({
+    member, activity: candidateState, runtime: candidateRuntimeStatus, fence: lifecycleResult,
+    terminalAlive: member.tmuxPaneId && options.terminal?.isAlive ? isWriteMemberAlive(member, options.terminal) : null,
+    now,
+  });
+  const { state, runtime: runtimeStatus } = projected;
   const progress = state?.latestProgress || runtimeStatus?.latestProgress;
   const progressUpdatedAt = state?.progressUpdatedAt || runtimeStatus?.progressUpdatedAt;
   return {
     name: member.name,
     role: member.role || state?.role || "read",
-    phase: phaseForActiveAgent(member, state, runtimeStatus, persistedStatus, now, options.terminal),
+    phase: projected.phase,
     progress,
     progressAgeMs: age(now, progressUpdatedAt),
     activeTool: state?.activeToolName || runtimeStatus?.activeToolName,
     activityAgeMs: age(now, state?.lastActivityAt),
     heartbeatAgeMs: age(now, runtimeStatus?.lastHeartbeatAt),
-    error: state?.lastError?.message || persistedStatus?.error || runtimeStatus?.lastError?.message,
+    error: projected.error,
   };
 }
 
@@ -174,7 +119,8 @@ function queuedStatus(item: QueuedAgentStatus, now: number): AgentStatusSnapshot
   return {
     name: item.name,
     role: item.role,
-    phase: "queued",
+    phase: item.failed ? "failed" : "queued",
+    error: item.error,
     queuePosition: item.queuePosition,
     queuedAgeMs: age(now, item.queuedAt),
   };

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

@@ -18,6 +18,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;
   shutdownTeammate(teamName: string, member: Member, options?: ShutdownTeammateOptions): Promise<ReadAgentTeardownResult>;
   getTeamName(): string | null | undefined;
 }
@@ -55,6 +56,12 @@ 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)) {
+          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 },
+          };
+        }
         const config = await teams.readConfig(teamName);
         let member = config.members.find(m => m.name === params.agent_name);
         const runningState = options.runningReadAgents.get(options.readAgentKey(teamName, params.agent_name));

package/extensions/tools/team-tools.ts

@@ -73,6 +73,7 @@ export interface NestedReadAgentToolBinding {
 
 export interface TeamToolsRuntime {
   createNestedReadAgentTools(binding: NestedReadAgentToolBinding): any[];
+  cancelQueuedAgent(teamName: string, agentName: string): boolean;
 }
 
 interface SpawnTeammateOptions {
@@ -97,11 +98,14 @@ interface QueuedReadSpawn {
   requestedAt: number;
   nameReservationId?: string;
   pendingChildAcceptance?: PendingChildAcceptance;
+  admissionError?: string;
+  quarantineError?: string;
+  launchCommitted?: boolean;
 }
 
 export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamToolsRuntime {
   if (options.isTeammate) {
-    return { createNestedReadAgentTools: () => [] };
+    return { createNestedReadAgentTools: () => [], cancelQueuedAgent: () => false };
   }
 
   function emitOrchestrationResponse(requestId: string | undefined, type: string, payload: Record<string, any>): void {
@@ -234,39 +238,38 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
 
   const pendingChildController = options.pendingChildController ?? createPendingChildController();
   const queuedReadSpawnsByTeam = new Map<string, QueuedReadSpawn[]>();
+  const failedAdmissionsByTeam = new Map<string, QueuedReadSpawn[]>();
   const readQueueDrainingTeams = new Set<string>();
-  const readAdmissionReservationsByTeam = new Map<string, Map<string, number>>();
+  const pendingQueueDrains = new Set<string>();
+  const readAdmissionReservationsByTeam = new Map<string, Map<string, { count: number; role: string }>>();
   const nestedReadNameReservationsByTeam = new Map<string, Map<string, string>>();
 
-  function activeAgentCount(teamName: string, role?: string): number {
-    let count = 0;
-    for (const agent of options.runningReadAgents.values()) {
-      if (agent.teamName !== teamName) continue;
-      if (role && (agent.role || "read") !== role) continue;
-      count += 1;
+  function activeAgentCount(teamName: string, role?: string, includeReservations = false): number {
+    const activeKeys = new Set<string>();
+    if (includeReservations) {
+      for (const [key, reservation] of readAdmissionReservationsByTeam.get(teamName) ?? []) {
+        if (!role || reservation.role === role) activeKeys.add(key);
+      }
     }
-    return count;
-  }
-
-  function activeReadCount(teamName: string): number {
-    const activeKeys = new Set(readAdmissionReservationsByTeam.get(teamName)?.keys() ?? []);
     for (const [key, agent] of options.runningReadAgents) {
-      if (agent.teamName === teamName && (agent.role || "read") === "read") activeKeys.add(key);
+      if (agent.teamName === teamName && (!role || (agent.role || "read") === role)) activeKeys.add(key);
     }
     return activeKeys.size;
   }
 
-  function reserveReadAdmission(teamName: string, key: string): void {
-    const reservations = readAdmissionReservationsByTeam.get(teamName) ?? new Map<string, number>();
-    reservations.set(key, (reservations.get(key) ?? 0) + 1);
+  function reserveReadAdmission(teamName: string, key: string, role: string): void {
+    const reservations = readAdmissionReservationsByTeam.get(teamName) ?? new Map<string, { count: number; role: string }>();
+    const pending = reservations.get(key);
+    if (pending && pending.role !== role) throw new Error(`Agent ${key} already has a ${pending.role} admission in progress.`);
+    reservations.set(key, { count: (pending?.count ?? 0) + 1, role });
     readAdmissionReservationsByTeam.set(teamName, reservations);
   }
 
   function releaseReadAdmission(teamName: string, key: string): void {
     const reservations = readAdmissionReservationsByTeam.get(teamName);
     if (!reservations) return;
-    const count = reservations.get(key) ?? 0;
-    if (count > 1) reservations.set(key, count - 1);
+    const reservation = reservations.get(key);
+    if (reservation && reservation.count > 1) reservation.count -= 1;
     else reservations.delete(key);
     if (reservations.size === 0) readAdmissionReservationsByTeam.delete(teamName);
   }
@@ -295,13 +298,15 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
   }
 
   async function listQueuedAgentStatuses(teamName: string): Promise<QueuedAgentStatus[]> {
-    const readers = readQueue(teamName).map((queued, index) => ({
+    const readers = [...readQueue(teamName), ...(failedAdmissionsByTeam.get(teamName) ?? [])].map((queued, index) => ({
       name: queued.member.name,
       role: queued.member.role || "read",
       queuedAt: queued.requestedAt,
       queuePosition: index + 1,
       parentAgentName: queued.member.parentAgentName,
       parentLifecycleRunId: queued.member.parentLifecycleRunId,
+      error: queued.admissionError || queued.quarantineError,
+      failed: !!queued.admissionError,
     }));
     const writers = (await writeQueue.listWriteQueue(teamName)).map((queued, index) => ({
       name: queued.name,
@@ -342,6 +347,9 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
   pi.on?.("session_shutdown", () => {
     if (lifecycleProbeCleanedUp) return;
     lifecycleProbeCleanedUp = true;
+    for (const [teamName, queue] of queuedReadSpawnsByTeam) {
+      for (const queued of queue) removeQueuedReadSpawnById(teamName, queued.id);
+    }
     if (typeof lifecycleProbeUnsubscribe === "function") lifecycleProbeUnsubscribe();
     pendingChildCancelUnsubscribe();
     lifecycleFenceUnsubscribe();
@@ -495,7 +503,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     else pendingChildController.settleAcceptance(identity);
   }
 
-  async function rollbackNestedChildAdmission(
+  async function rollbackAgentAdmission(
     teamName: string,
     member: Member,
     cause: unknown,
@@ -508,11 +516,11 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     }
     try {
       const removed = await teams.removeMemberMatchingRun(teamName, member.name, runId);
-      if (!removed) throw new Error(`matching child run ${runId} was not present`);
+      if (!removed) throw new Error(`matching agent run ${runId} was not present`);
     } catch (rollbackError) {
       const causeMessage = cause instanceof Error ? cause.message : String(cause);
       const rollbackMessage = rollbackError instanceof Error ? rollbackError.message : String(rollbackError);
-      throw new Error(`${causeMessage} Exact-run rollback for nested read agent ${member.name} failed: ${rollbackMessage}`);
+      throw new Error(`${causeMessage} Exact-run rollback for agent ${member.name} failed: ${rollbackMessage}`);
     } finally {
       settlePendingChild(pendingChild);
     }
@@ -530,7 +538,9 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     member: Member,
     prompt: string,
     ctx: any,
-    queuedAcceptance?: PendingChildAcceptance
+    queuedAcceptance?: PendingChildAcceptance,
+    assertPending?: () => void,
+    commitLaunch?: () => void,
   ): Promise<AdmittedReadAgentLaunch> {
     const addValidateAndLaunch = async (parentLifecycleLock?: LifecycleTombstoneLock): Promise<AdmittedReadAgentLaunch> => {
       let pendingAcceptance = queuedAcceptance;
@@ -542,17 +552,25 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       }
 
       try {
+        if (lifecycleProbeCleanedUp) throw new Error("Agent session is closing; admission cancelled.");
+        assertPending?.();
         await teams.addMember(teamName, member);
       } catch (error) {
         settlePendingChild(pendingAcceptance);
         throw error;
       }
 
+      try {
+        if (lifecycleProbeCleanedUp) throw new Error("Agent session is closing; admission cancelled.");
+        assertPending?.();
+      } catch (error) {
+        return rollbackAgentAdmission(teamName, member, error, pendingAcceptance);
+      }
       let pendingChildRun: PendingChildRun | undefined;
       if (member.delegationDepth === 1) {
         const runId = member.lifecycleRunId;
         if (!pendingAcceptance || !runId) {
-          return rollbackNestedChildAdmission(
+          return rollbackAgentAdmission(
             teamName,
             member,
             new Error(`Nested read agent ${member.name} did not receive an exact lifecycle run identity.`),
@@ -561,7 +579,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
         }
         pendingChildRun = pendingChildController.bindAcceptedChild(pendingAcceptance, member.name, runId);
         if (!pendingChildRun) {
-          return rollbackNestedChildAdmission(
+          return rollbackAgentAdmission(
             teamName,
             member,
             new Error(`Nested read agent ${member.name} lost its parent acceptance before launch.`),
@@ -572,7 +590,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
         try {
           await assertNestedChildAdmission(teamName, member, parentLifecycleLock);
         } catch (error) {
-          return rollbackNestedChildAdmission(teamName, member, error, pendingChildRun);
+          return rollbackAgentAdmission(teamName, member, error, pendingChildRun);
         }
       }
 
@@ -602,6 +620,9 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       };
 
       try {
+        if (lifecycleProbeCleanedUp) throw new Error("Agent session is closing; admission cancelled.");
+        assertPending?.();
+        commitLaunch?.();
         const launch = options.runReadAgentInProcess(teamName, member, launchPrompt, ctx, options.readAgentOptions());
         return {
           launch: sessionContextReference
@@ -612,10 +633,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
         };
       } catch (error) {
         removeReference();
-        if (member.delegationDepth === 1) {
-          return rollbackNestedChildAdmission(teamName, member, error, pendingChildRun);
-        }
-        throw error;
+        return rollbackAgentAdmission(teamName, member, error, pendingChildRun);
       }
     };
 
@@ -634,23 +652,24 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     ctx: any,
     nameReservationId?: string,
     releaseNameOnFailure = true,
-    queuedAcceptance?: PendingChildAcceptance
+    queuedAcceptance?: PendingChildAcceptance,
+    assertPending?: () => void,
+    commitLaunch?: () => void,
   ): Promise<boolean> {
     const key = options.readAgentKey(teamName, member.name);
-    const reservesReadCapacity = (member.role || "read") === "read";
-    if (reservesReadCapacity) reserveReadAdmission(teamName, key);
+    reserveReadAdmission(teamName, key, member.role || "read");
 
     const releaseNameReservation = () => {
       releaseNestedReadName(teamName, member.name, nameReservationId);
     };
     const releaseReservationAndDrain = () => {
       if (releaseNameOnFailure) releaseNameReservation();
-      if (reservesReadCapacity) releaseReadAdmission(teamName, key);
+      releaseReadAdmission(teamName, key);
       void drainQueuedReadSpawns(teamName);
     };
     const finishRun = (pendingChildRun: PendingChildRun | undefined) => {
       settlePendingChild(pendingChildRun);
-      if (reservesReadCapacity) releaseReadAdmission(teamName, key);
+      releaseReadAdmission(teamName, key);
       void drainQueuedReadSpawns(teamName);
     };
     const drainAfterRun = (pendingChildRun: PendingChildRun | undefined) => {
@@ -669,7 +688,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     };
 
     try {
-      const admitted = await admitAndLaunchReadAgentMember(teamName, member, prompt, ctx, queuedAcceptance);
+      const admitted = await admitAndLaunchReadAgentMember(teamName, member, prompt, ctx, queuedAcceptance, assertPending, commitLaunch);
       releaseNameReservation();
       void Promise.resolve(admitted.launch).then(
         () => drainAfterRun(admitted.pendingChildRun),
@@ -710,6 +729,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
         pendingChildAcceptance,
       };
       setReadQueue(teamName, [...queue, queued]);
+      void drainQueuedReadSpawns(teamName);
       return queued;
     };
 
@@ -733,55 +753,62 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
   }
 
   async function drainQueuedReadSpawns(teamName: string): Promise<void> {
-    if (readQueueDrainingTeams.has(teamName)) return;
+    if (lifecycleProbeCleanedUp) return;
+    if (readQueueDrainingTeams.has(teamName)) {
+      pendingQueueDrains.add(teamName);
+      return;
+    }
     readQueueDrainingTeams.add(teamName);
     try {
-      while (true) {
-        const next = readQueue(teamName)[0];
-        if (!next) return;
-        const settings = loadSettings({ projectDir: next.member.cwd });
-        if (activeReadCount(teamName) >= settings.readAgents.maxConcurrent) return;
-
-        const queued = readQueue(teamName)[0];
-        if (!queued) return;
-        const fence = await readLifecycleTombstone(teamName, queued.member.name);
-        if (fence.status !== "absent") return;
-        try {
-          const config = await teams.readConfig(teamName);
-          if (config.members.some((member) => member.name === queued.member.name)) {
+      let progressed = true;
+      while (progressed && !lifecycleProbeCleanedUp) {
+        progressed = false;
+        for (const queued of readQueue(teamName)) {
+          if (queued.admissionError) continue;
+          const role = queued.member.role || "read";
+          const settings = loadSettings({ projectDir: queued.member.cwd });
+          const capacity = role === "write" ? settings.writeAgents : settings.readAgents;
+          if (activeAgentCount(teamName, role, true) >= capacity.maxConcurrent) continue;
+          const assertPending = () => {
+            if (!readQueue(teamName).some(item => item.id === queued.id)) throw new Error(`Queued agent ${queued.member.name} was cancelled.`);
+          };
+          try {
+            const fence = await readLifecycleTombstone(teamName, queued.member.name);
+            if (fence.status !== "absent") {
+              queued.quarantineError = fence.status === "corrupt" ? fence.error : `Lifecycle run ${fence.tombstone.runId} is quarantined.`;
+              continue;
+            }
+            queued.quarantineError = undefined;
+            const config = await teams.readConfig(teamName);
+            assertPending();
+            if (config.members.some(member => member.name === queued.member.name)) throw new Error(`A teammate named ${queued.member.name} already exists.`);
+            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.launchCommitted = true; });
+            removeQueuedReadSpawnById(teamName, queued.id, false);
+            progressed = true;
+          } catch (error) {
+            if (!readQueue(teamName).some(item => item.id === queued.id)) continue;
+            queued.launchCommitted = false;
+            const latestFence = await readLifecycleTombstone(teamName, queued.member.name).catch(() => null);
+            if (latestFence && latestFence.status !== "absent") {
+              queued.quarantineError = "Lifecycle quarantine appeared before admission.";
+              continue;
+            }
+            queued.admissionError = error instanceof Error ? error.message : String(error);
+            failedAdmissionsByTeam.set(teamName, [...(failedAdmissionsByTeam.get(teamName) ?? []), queued].slice(-20));
             removeQueuedReadSpawnById(teamName, queued.id);
-            continue;
-          }
-          queued.member.joinedAt = Date.now();
-          await startReadAgentMember(
-            teamName,
-            queued.member,
-            queued.prompt,
-            queued.ctx,
-            queued.nameReservationId,
-            false,
-            queued.pendingChildAcceptance
-          );
-          removeQueuedReadSpawnById(teamName, queued.id, false);
-        } catch (error) {
-          const latestFence = await readLifecycleTombstone(teamName, queued.member.name);
-          if (latestFence.status !== "absent") {
-            await messaging.sendPlainMessage(
-              teamName,
-              "system",
-              "team-lead",
-              `Retained queued agent ${queued.member.name}: lifecycle quarantine appeared before admission.`,
-              `Queued agent ${queued.member.name} retained by quarantine`,
-              "yellow"
-            ).catch(() => {});
-            return;
+            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(() => {});
           }
-          // Invalid non-lifecycle requests may be dropped so later work can run.
-          removeQueuedReadSpawnById(teamName, queued.id);
         }
       }
     } finally {
       readQueueDrainingTeams.delete(teamName);
+      if (pendingQueueDrains.delete(teamName)) void drainQueuedReadSpawns(teamName);
     }
   }
 
@@ -800,7 +827,11 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     const { availableModels } = await getModelSelectionState(ctx, ctx.cwd, [explicitDefaultModel]);
     const defaultModel = requireQualifiedKnownModel(explicitDefaultModel, availableModels, "model_slot");
     if (!defaultModel) throw new Error("Agent sessions require a configured model_slot level before spawning.");
-    teams.createTeam(sessionName, getPiSessionId(ctx) || "local-session", "lead-agent", "Pi session agents", defaultModel);
+    try {
+      teams.createTeamIfAbsent(sessionName, getPiSessionId(ctx) || "local-session", "lead-agent", "Pi session agents", defaultModel);
+    } catch (error) {
+      if (!(error instanceof teams.TeamAlreadyExistsError)) throw error;
+    }
     options.adoptTeamAsLead(sessionName, ctx);
     return sessionName;
   }
@@ -810,6 +841,7 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     const safeTeamName = paths.sanitizeName(params.team_name);
     const cwd = params.cwd || ctx.cwd;
     const teamConfig = await teams.readConfig(safeTeamName);
+    failedAdmissionsByTeam.set(safeTeamName, (failedAdmissionsByTeam.get(safeTeamName) ?? []).filter(item => item.member.name !== safeName));
     let nestedNameReservationId: string | undefined;
     let nestedNameReservationTransferred = false;
 
@@ -958,90 +990,40 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
       helperKind: spawnOptions.nestedParent ? "read_helper" : undefined,
     };
 
-    if (role === "read") {
-      if (!spawnOptions.nestedParent) removeQueuedReadSpawnsByName(safeTeamName, safeName);
-      const currentReadCount = activeReadCount(safeTeamName);
-      if (currentReadCount >= settings.readAgents.maxConcurrent) {
-        if (!settings.readAgents.queueOverflow) {
-          throw new Error(`Read-agent capacity reached (${currentReadCount}/${settings.readAgents.maxConcurrent}) and queueOverflow is disabled.`);
-        }
-        const queued = await enqueueReadSpawn(
-          safeTeamName,
-          member,
-          params.prompt,
-          params,
-          resolved,
-          ctx,
-          nestedNameReservationId
-        );
-        nestedNameReservationTransferred = !!nestedNameReservationId;
-        const queuePosition = readQueue(safeTeamName).findIndex((item) => item.id === queued.id) + 1;
-        return {
-          content: [{ type: "text", text: `Read teammate ${params.name} queued at position ${queuePosition}; capacity is ${currentReadCount}/${settings.readAgents.maxConcurrent}.` }],
-          details: queuedReadResolutionDetails(queued, params, { queuePosition }),
-        };
+    if (role === "write") await writeQueue.removeQueuedWriteSpawnsByName(safeTeamName, safeName);
+    if (!spawnOptions.nestedParent) removeQueuedReadSpawnsByName(safeTeamName, safeName);
+    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);
+    if (activeCount >= capacity.maxConcurrent) {
+      if (!capacity.queueOverflow) {
+        throw new Error(`${role === "write" ? "Edit" : "Read"}-agent capacity reached (${activeCount}/${capacity.maxConcurrent}) and queueOverflow is disabled.`);
       }
-
-      const sessionContextAvailable = await startReadAgentMember(safeTeamName, member, params.prompt, ctx, nestedNameReservationId);
+      const queued = await enqueueReadSpawn(safeTeamName, member, params.prompt, params, resolved, ctx, nestedNameReservationId);
+      nestedNameReservationTransferred = !!nestedNameReservationId;
+      const queuePosition = readQueue(safeTeamName).findIndex(item => item.id === queued.id) + 1;
       return {
-        content: [{ type: "text", text: `Read teammate ${params.name} started in-process.` }],
-        details: spawnResolutionDetails(member, params, resolved, {
-          mode: "in-process",
-          terminalId: null,
-          queued: false,
-          sessionContextAvailable,
-        }),
+        content: [{ type: "text", text: `Agent ${params.name} queued at position ${queuePosition}; capacity is ${activeCount}/${capacity.maxConcurrent}.` }],
+        details: queuedReadResolutionDetails(queued, params, { queuePosition }),
       };
     }
 
-    await writeQueue.removeQueuedWriteSpawnsByName(safeTeamName, safeName);
-    const activeWriteCount = activeAgentCount(safeTeamName, "write");
-    await writeTeamsDebugEvent(safeTeamName, "write-agent.spawn.request", {
-      agentName: safeName,
-      cwd,
-      category: params.category ?? null,
-      requestedRole: role,
-      resolvedRole: role,
-      model: chosenModel,
-      modelSource: resolved.modelSource,
-      thinking: chosenThinking ?? null,
-      activeWriteCount,
-      maxConcurrent: settings.writeAgents.maxConcurrent,
-      queueOverflow: false,
-      mode: "in-process",
-      debugLogPath: debugLogPath ?? null,
-    }, settings);
-
-    if (activeWriteCount >= settings.writeAgents.maxConcurrent) {
-      await writeTeamsDebugEvent(safeTeamName, "write-agent.spawn.failure", {
-        agentName: safeName,
-        reason: "capacity-reached",
-        activeWriteCount,
-        maxConcurrent: settings.writeAgents.maxConcurrent,
-        mode: "in-process",
+    const sessionContextAvailable = await startReadAgentMember(safeTeamName, member, params.prompt, ctx, nestedNameReservationId);
+    if (role === "write") {
+      await writeTeamsDebugEvent(safeTeamName, "write-agent.spawn.success", {
+        agentName: safeName, cwd, requestedRole: role, model: chosenModel,
+        modelSource: resolved.modelSource, thinking: chosenThinking ?? null,
+        activeWriteCount: activeCount, maxConcurrent: capacity.maxConcurrent,
+        queueOverflow: capacity.queueOverflow, terminalId: null, mode: "in-process",
         debugLogPath: debugLogPath ?? null,
       }, settings);
-      throw new Error(`Edit-agent capacity reached (${activeWriteCount}/${settings.writeAgents.maxConcurrent}). Wait for an active edit agent to finish before spawning another.`);
     }
-
-    await writeTeamsDebugEvent(safeTeamName, "write-agent.spawn.success", {
-      agentName: safeName,
-      terminalId: null,
-      windowId: null,
-      mode: "in-process",
-      debugLogPath: debugLogPath ?? null,
-    }, settings);
-    const sessionContextAvailable = await startReadAgentMember(safeTeamName, member, params.prompt, ctx);
     options.renderReadAgentStatus();
     const debugSuffix = debugLogPath ? ` Debug log: ${debugLogPath}.` : "";
     return {
-      content: [{ type: "text", text: `Edit agent ${params.name} started in-process and is followable from Pi.${debugSuffix}` }],
+      content: [{ type: "text", text: `${role === "write" ? "Edit agent" : "Read teammate"} ${params.name} started in-process and is followable from Pi.${debugSuffix}` }],
       details: spawnResolutionDetails(member, params, resolved, {
-        mode: "in-process",
-        terminalId: null,
-        queued: false,
-        debugLogPath,
-        sessionContextAvailable,
+        mode: "in-process", terminalId: null, queued: false, debugLogPath, sessionContextAvailable,
       }),
     };
     } finally {
@@ -1326,5 +1308,12 @@ export function registerTeamTools(pi: any, options: TeamToolsOptions): TeamTools
     },
   });
 
-  return { createNestedReadAgentTools };
+  return {
+    createNestedReadAgentTools,
+    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;
+    },
+  };
 }

package/extensions/ui/read-agent-status.ts

@@ -1,8 +1,9 @@
 import type { RunningReadAgent } from "../runtime/types";
+import { AGENT_HANGING_MS } from "../../src/orchestration/status-projection";
 import { formatElapsed } from "./renderers.js";
 
 export const READ_AGENT_IDLE_NUDGE_MS = 5 * 60_000;
-export const READ_AGENT_HANGING_NUDGE_MS = 15 * 60_000;
+export const READ_AGENT_HANGING_NUDGE_MS = AGENT_HANGING_MS;
 
 export type ReadAgentStatusLabel = RunningReadAgent["status"] | "idle" | "hanging";
 export type ReadAgentIdleLevel = "none" | "soft" | "hard";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extended-teams",
-  "version": "2.2.7",
+  "version": "2.2.8",
   "description": "Control-first, session-connected subagents for Pi with live navigation and intent-tier routing",
   "repository": {
     "type": "git",

package/skills/teams.md

@@ -69,7 +69,7 @@ Inspect only the concurrent rotation path and focused tests. Report gaps, covera
 
 Then:
 
-1. Read agents run in-process; edit agents run in separate Pi sessions through the configured terminal adapter. Both report back to the lead.
+1. Public read and edit agents run in separate in-process Pi sessions and report back to the lead. A write tier grants edit tools, not a terminal pane. The terminal runtime remains available for existing integrations.
 2. The lead synthesizes the reports for the user.
 3. Finished agents leave the active status list; completed reports remain available in the session UI.
 
@@ -138,7 +138,7 @@ When the user says "agents", "use agents", "spawn agents", "send agents", "agent
 - When no unrelated work remains, end the turn. The extension resumes the lead when reports arrive.
 - One `get_agent_status` snapshot is allowed when current status is needed. Never call it repeatedly, sleep, busy-wait, or loop on inbox/status.
 - Trust quiet agents. Do not ping, message, or check an agent just because it has been quiet for less than several minutes; active status remains visible in the activity card and Down-key live view.
-- When new, changed, or previously omitted evidence affects an active owner, use `send_message` with an **Evidence delta** as defined below instead of replacing or stopping it. Active in-process read agents receive the message as a steering turn and can continue intelligently; active tmux writers wake through their inbox.
+- When new, changed, or previously omitted evidence affects an active owner, use `send_message` with an **Evidence delta** as defined below instead of replacing or stopping it. Active in-process agents receive the message as a steering turn; legacy terminal-backed agents receive inbox delivery.
 - Once a final report is accepted, new message admission is closed and the agent is self-exiting; teardown may still be finishing. Do not call `stop_teammate` after normal completion. If genuinely new work appears after the report, spawn a fresh bounded `read-collect` lane rather than trying to revive that closing session.
 - Do not wake the lead just to ping idle agents.
 - Use `check_teammate` only when `get_agent_status` shows a suspected stall or failure. It is a lifecycle diagnostic and may clean up an agent classified as dead.

package/src/orchestration/index.ts

@@ -6,6 +6,8 @@ import * as runtime from "../utils/runtime";
 import * as writeQueue from "../utils/write-queue";
 import * as reports from "../utils/report-events";
 import type { Member } from "../utils/models";
+import { readLifecycleTombstone } from "../utils/lifecycle-tombstone";
+import { isAgentActivity, projectAgentStatus } from "./status-projection";
 import { canonicalPersistedModelSlot, loadSettings, requireFavoriteModelLevel, roleForFavoriteModelSlot } from "../utils/settings";
 import type {
   BroadcastMessageOnceRequest,
@@ -19,7 +21,6 @@ import type {
   SpawnTeammatesOnceResponse,
   TeamObservation,
   TeammateResolutionDetails,
-  TeammateHealth,
   TeammateObservation,
 } from "./types";
 
@@ -41,11 +42,6 @@ export async function appendTeamReportEvent(teamName: string, event: reports.New
   return await next;
 }
 
-function readAgentIsKnownRunning(teamName: string, agentName: string, options: ObserveRuntimeOptions): boolean {
-  const key = options.readAgentKey?.(teamName, agentName) || `${teamName}:${agentName}`;
-  return !!options.runningReadAgents?.has(key);
-}
-
 function operationValue(source: { operationId?: string; workflowRunId?: string; metadata?: Record<string, any> }, key: "operationId" | "workflowRunId"): string | undefined {
   return source[key] || source.metadata?.[key] || source.metadata?.orchestration?.[key];
 }
@@ -268,40 +264,32 @@ async function observeKnownTeammate(
   const unreadCount = (await messaging.peekInbox(teamName, member.name, true).catch(() => [])).length;
   const runtimeStatus = member.name === "team-lead" ? null : await runtime.readRuntimeStatus(teamName, member.name).catch(() => null);
   const now = options.now ?? Date.now();
-  const hasRecentHeartbeat = runtime.isHeartbeatFresh(runtimeStatus, now);
-
-  let alive: boolean | null;
-  if (member.name === "team-lead") {
-    alive = true;
-  } else if (role === "read") {
-    alive = readAgentIsKnownRunning(teamName, member.name, options) || (!!runtimeStatus && hasRecentHeartbeat && member.isActive !== false);
-  } else if (member.tmuxPaneId && options.terminal?.isAlive) {
-    alive = options.terminal.isAlive(member.tmuxPaneId);
-  } else {
-    alive = null;
-  }
-
-  const startupStalled = alive === true && unreadCount > 0 && (now - member.joinedAt) > runtime.STARTUP_STALL_MS && !(runtimeStatus?.ready);
-  let health: TeammateHealth;
-  if (member.name === "team-lead") health = "lead";
-  else if (alive === null) health = "unknown";
-  else if (!alive) health = "dead";
-  else if (startupStalled) health = "stalled";
-  else if (runtimeStatus?.ready) health = hasRecentHeartbeat ? "healthy" : "idle";
-  else health = "starting";
+  const key = options.readAgentKey?.(teamName, member.name) || `${teamName}:${member.name}`;
+  const candidate = options.runningReadAgents?.get(key);
+  const fence = member.name === "team-lead" ? { status: "absent" as const }
+    : await readLifecycleTombstone(teamName, member.name).catch(error => ({
+      status: "corrupt" as const, error: error instanceof Error ? error.message : String(error),
+    }));
+  const projected = projectAgentStatus({
+    member, activity: isAgentActivity(candidate) ? candidate : undefined,
+    runtime: runtimeStatus, fence, now, unreadCount,
+    terminalAlive: member.tmuxPaneId && options.terminal?.isAlive ? options.terminal.isAlive(member.tmuxPaneId) : null,
+  });
 
   return {
     teamName,
     agentName: member.name,
     member,
     role,
-    alive,
-    health,
+    alive: member.name === "team-lead" ? true : projected.alive,
+    health: member.name === "team-lead" ? "lead" : projected.health,
+    phase: member.name === "team-lead" ? "lead" : projected.phase,
+    error: projected.error,
     unreadCount,
-    agentLoopReady: !!runtimeStatus?.ready,
-    hasRecentHeartbeat,
-    startupStalled,
-    runtime: runtimeStatus,
+    agentLoopReady: projected.agentLoopReady,
+    hasRecentHeartbeat: projected.hasRecentHeartbeat,
+    startupStalled: projected.startupStalled,
+    runtime: projected.runtime,
   };
 }
 

package/src/orchestration/status-projection.ts

@@ -0,0 +1,89 @@
+import type { Member } from "../utils/models";
+import type { LifecycleTombstoneReadResult } from "../utils/lifecycle-tombstone";
+import { isHeartbeatFresh, STARTUP_STALL_MS, type AgentRuntimeStatus } from "../utils/runtime";
+
+export const AGENT_HANGING_MS = 15 * 60_000;
+
+export type ActiveAgentPhase = "starting" | "thinking" | "working" | "finishing"
+  | "stalled" | "stopping" | "quarantined" | "persistence-failed";
+
+export interface AgentActivity {
+  runId: string;
+  status: "starting" | "thinking" | "working" | "finishing";
+  startedAt: number;
+  role?: string;
+  lastActivityAt?: number;
+  teardownState?: string;
+  handoffDetached?: boolean;
+  latestProgress?: string;
+  progressUpdatedAt?: number;
+  activeToolName?: string;
+  lastError?: { message: string };
+}
+
+export function isAgentActivity(value: unknown): value is AgentActivity {
+  return typeof value === "object" && value !== null
+    && "runId" in value && typeof value.runId === "string"
+    && "startedAt" in value && typeof value.startedAt === "number"
+    && "status" in value && typeof value.status === "string"
+    && ["starting", "thinking", "working", "finishing"].includes(value.status);
+}
+
+function lifecyclePhase(member: Member, fence: LifecycleTombstoneReadResult): { phase: ActiveAgentPhase; error?: string } | undefined {
+  if (fence.status === "absent") return;
+  if (fence.status === "corrupt") return { phase: "quarantined", error: fence.error };
+  const { tombstone } = fence;
+  const mismatch = member.lifecycleRunId && tombstone.runId !== member.lifecycleRunId
+    ? `Lifecycle fence belongs to run ${tombstone.runId}, not roster run ${member.lifecycleRunId}.`
+    : undefined;
+  return {
+    phase: tombstone.phase === "cleanup_failed" || tombstone.phase === "timed_out" ? "quarantined" : "stopping",
+    error: mismatch || tombstone.error,
+  };
+}
+
+export function projectAgentStatus(input: {
+  member: Member;
+  activity?: AgentActivity;
+  runtime: AgentRuntimeStatus | null;
+  fence: LifecycleTombstoneReadResult;
+  terminalAlive: boolean | null;
+  now: number;
+  unreadCount?: number;
+}) {
+  const { member, now } = input;
+  const state = input.activity?.runId === member.lifecycleRunId ? input.activity : undefined;
+  const runtime = input.runtime?.lifecycleRunId === member.lifecycleRunId ? input.runtime : null;
+  const persisted = lifecyclePhase(member, input.fence);
+  const hasRecentHeartbeat = isHeartbeatFresh(runtime, now);
+  const inProcess = !!state && state.teardownState !== "finalized" && !state.handoffDetached;
+  const externalAlive = member.isActive !== false && (hasRecentHeartbeat || input.terminalAlive === true);
+  const alive = inProcess || externalAlive ? true
+    : member.isActive === false || input.terminalAlive === false || member.role === "read" ? false : null;
+  const startupStalled = alive === true && (input.unreadCount ?? 0) > 0
+    && now - member.joinedAt > STARTUP_STALL_MS && !runtime?.ready;
+  const teardownPhase = state?.teardownState === "persistence_failed" ? "persistence-failed"
+    : state?.teardownState === "quarantined" ? "quarantined"
+      : state?.teardownState === "stopping" ? "stopping" : undefined;
+  const fencedPhase = teardownPhase ?? persisted?.phase;
+  let phase: ActiveAgentPhase;
+  if (fencedPhase) phase = fencedPhase;
+  else if (inProcess) phase = now - (state.lastActivityAt || state.startedAt) >= AGENT_HANGING_MS ? "stalled" : state.status;
+  else if (!externalAlive) phase = member.isActive !== false && !runtime?.ready && now - member.joinedAt <= STARTUP_STALL_MS ? "starting" : "stalled";
+  else phase = runtime?.currentAction === "done" ? "finishing" : runtime?.currentAction ?? (runtime?.ready ? "working" : "starting");
+
+  const health = fencedPhase === "quarantined" ? "quarantined"
+    : fencedPhase === "persistence-failed" ? "persistence-failed"
+      : fencedPhase ? "stopping"
+        : startupStalled || (phase === "stalled" && alive) ? "stalled"
+          : alive === null ? "unknown"
+            : !alive ? "dead"
+              : runtime?.ready ? hasRecentHeartbeat ? "healthy" : "idle"
+                : inProcess && state.status !== "starting" ? "healthy" : "starting";
+  return {
+    phase, alive, health, hasRecentHeartbeat, startupStalled,
+    agentLoopReady: !fencedPhase && alive === true && (!!runtime?.ready || (inProcess && state.status !== "starting")),
+    state, runtime,
+    error: persisted?.error || state?.lastError?.message || runtime?.lastError?.message,
+  };
+}

package/src/orchestration/types.ts

@@ -1,4 +1,5 @@
 import type { AgentRuntimeStatus } from "../utils/runtime";
+import type { ActiveAgentPhase, projectAgentStatus } from "./status-projection";
 import type { QueuedWriteSpawn } from "../utils/write-queue";
 import type { FileClaim } from "../utils/claims";
 import type { InboxMessage, Member, TaskFile, TeamConfig, TeamReportEvent, ThinkingLevel } from "../utils/models";
@@ -12,7 +13,7 @@ export interface OrchestrationOperationMetadata {
   metadata?: Record<string, any>;
 }
 
-export type TeammateHealth = "lead" | "healthy" | "idle" | "starting" | "stalled" | "dead" | "unknown";
+export type TeammateHealth = "lead" | ReturnType<typeof projectAgentStatus>["health"];
 
 export interface TeammateObservation {
   teamName: string;
@@ -21,6 +22,8 @@ export interface TeammateObservation {
   role: string;
   alive: boolean | null;
   health: TeammateHealth;
+  phase?: ActiveAgentPhase | "lead";
+  error?: string;
   unreadCount: number;
   agentLoopReady: boolean;
   hasRecentHeartbeat: boolean;