pi-extended-teams 2.2.6 → 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.
@@ -55,6 +55,8 @@ This works well for multi-angle code review, root-cause investigation, parallel
 
 With the editor empty, press Down to open agent navigation. Use Down/Up to move, `l` to expand large tool logs, `m` to message an agent, `i` to interrupt its currently running tool command, `x` to stop the whole agent, and Escape to return.
 
+Inside Herdr, press `h` in an ordinary direct agent's preview to move it into a focused sibling Pi pane in the same workspace. Its conversation and team communication continue there. Nested helpers and delegation-enabled or workflow agents are excluded.
+
 Scroll the transcript with Page Up/Page Down or the mouse wheel, including under Herdr. Press End or scroll back to the bottom to follow new output.
 
 The lead can invoke the same command-only behavior with `interrupt_teammate({ agent_name: "agent" })`. It keeps the agent's session, task context, and file claims intact so you can send follow-up work. In-process cancellation is cooperative and may report that it is still pending; for tmux-backed agents, success means Pi's Escape key was delivered, not that command settlement was independently confirmed.
@@ -102,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/docs/access.md

@@ -8,13 +8,13 @@
 - Write teammates start a separate Pi process in a tmux pane. The extension builds and runs the local Pi launch command with the teammate's working directory, model and thinking configuration, selected extensions, and `PI_TEAM_NAME`, `PI_AGENT_NAME`, and `PI_LIFECYCLE_RUN_ID` environment variables.
 - Before launching a write teammate, the extension runs a bounded local `pi models --all` preflight through `sh -c` to determine whether the configured model is available.
 - On macOS, while at least one write teammate is active, the extension may run `/usr/bin/caffeinate -i -w <lead-pid>` to prevent idle system sleep. It terminates that helper when no write teammates remain or the extension is disposed.
-- In a Herdr session, the extension can invoke the configured `herdr` binary to split, start, and close panes when moving an agent. The binary path defaults to `herdr` and can be set with `HERDR_BIN_PATH`.
+- Inside Herdr, pressing `h` can move an eligible in-process agent into a sibling Pi pane. The extension calls the `herdr` executable to split, run, focus, or close that pane.
 
 ## Files and local state
 
 The extension reads settings from `~/.pi/agent/pi-extended-teams/settings.json` and `<project>/.pi/pi-extended-teams.json`. Model-provider compatibility also reads the legacy `~/.pi/pi-extended-teams.json` path. Predefined agents can be read from `~/.pi/agent/agents/` and `<project>/.pi/agents/`; team templates can be read or written at `~/.pi/teams.yaml`, `~/.pi/agent/teams.yaml`, and `<project>/.pi/teams.yaml`.
 
-For a team named `<team>`, coordination state is stored under `~/.pi/teams/<team>/`. This includes `config.json`, inboxes, runtime status, session-context references, lifecycle quarantine and tombstones, file claims, write and read-helper queues, shared memory, report events, lead-session metadata, debug logs, and private child transcripts under `agent-sessions/`. Task records are stored under `~/.pi/tasks/<team>/`, and agent reports may also be written under `~/.pi/agent/reports/`. Cleanup removes lifecycle and queue files when they are no longer needed.
+For a team named `<team>`, coordination state is stored under `~/.pi/teams/<team>/`. This includes `config.json`, inboxes, runtime status, session-context references, lifecycle quarantine and tombstones, file claims, write and read-helper queues, shared memory, report events, lead-session metadata, debug logs, and private child transcripts and handoff prompt snapshots under `agent-sessions/`. Task records are stored under `~/.pi/tasks/<team>/`, and agent reports may also be written under `~/.pi/agent/reports/`. Cleanup removes lifecycle and queue files when they are no longer needed.
 
 The extension reads project extension sources only when Pi marks the same working directory trusted. Teammates receive the working directory supplied at spawn time. A write teammate can use any filesystem access granted to its child Pi process and enabled tools. A read teammate's tools are restricted by the extension, but it still receives prompt and project context supplied by the lead.
 

package/extensions/agents/read-agent.ts

@@ -1,4 +1,9 @@
 import type { AgentSession } from "@mariozechner/pi-coding-agent";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { buildPiCommand, getPiLaunchCommand, shellQuote } from "../internal/pi-command";
+import { herdrCommand } from "../runtime/herdr";
 import * as runtime from "../../src/utils/runtime";
 import * as teams from "../../src/utils/teams";
 import * as messaging from "../../src/utils/messaging";
@@ -12,7 +17,7 @@ import { isPiPromptPlanningMember, shouldSuppressLeadReportInjection } from "../
 import { canonicalPersistedModelSlot, loadSettings, requireFavoriteModelLevel } from "../../src/utils/settings";
 import { parseQualifiedModel } from "../../src/utils/model-resolution";
 import { closePersistedRecipient } from "../team/recipient-closure";
-import { generateExtensionInstanceId, generateLifecycleRunId } from "../../src/utils/lifecycle-tombstone";
+import { generateExtensionInstanceId, generateLifecycleRunId, withLifecycleTombstoneLock } from "../../src/utils/lifecycle-tombstone";
 import { createLifecycleRuntime, type ShutdownTeammateOptions } from "../team/lifecycle";
 import {
   createSpawnResourcePlan,
@@ -585,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;
@@ -634,6 +641,7 @@ export async function runReadAgentInProcess(
     getTeamName: () => readTeamName,
   }).shutdownTeammate;
 
+  let handoffRequested = false;
   let submittedFinalReport: SubmittedAgentReport | undefined;
   let finalReportSubmissionInProgress = false;
   let childSessionManager: any;
@@ -660,6 +668,7 @@ export async function runReadAgentInProcess(
   const closeRecipient = async (): Promise<ReadAgentDeliveryCloseResult> => {
     if (pendingChildParent) pendingChildController?.cancelParent(pendingChildParent);
     const deliveryClose = closeReadAgentMessageDelivery(state);
+    if (handoffRequested) return deliveryClose;
     if (!state.recipientClosurePromise) {
       state.recipientClosurePromise = closePersistedRecipient(
         readTeamName,
@@ -959,7 +968,7 @@ export async function runReadAgentInProcess(
     } as Parameters<typeof createAgentSession>[0] & { modelRuntime?: unknown });
 
     state.session = session;
-    installReadAgentSessionLifecycle(session);
+    const sessionLifecycle = installReadAgentSessionLifecycle(session);
     try {
       if (typeof session.bindExtensions === "function") {
         await (session.bindExtensions as (bindings: { mode: "print" }) => Promise<void>)({ mode: "print" });
@@ -973,6 +982,96 @@ export async function runReadAgentInProcess(
       if (state.teardownState !== "persistence_failed") await state.teardownPromise;
       return;
     }
+    if (process.env.HERDR_ENV === "1" && (member.delegationDepth ?? 0) === 0
+      && !member.requestedBy && !member.parentAgentName && !member.allowNestedReadAgents
+      && !shouldSuppressLeadReportInjection(member)) {
+      let moving: Promise<void> | undefined;
+      let paneId: string | undefined;
+      let command = "";
+      let queued: string[] = [];
+      let released = false;
+      const release = Promise.all([finished, sessionLifecycle.finalized]).then(() => {
+        if (handoffRequested) { state.session = undefined; released = true; }
+      });
+      void release.catch(() => {});
+      const recordPane = (id: string | undefined) => withLifecycleTombstoneLock(readTeamName, member.name, async lock => {
+        const current = (await teams.readConfig(readTeamName)).members.find(item => item.name === member.name);
+        if (!current || current.lifecycleRunId !== state.runId || current.isActive === false || lock.read().status !== "absent") {
+          throw new Error("The agent is no longer available to move.");
+        }
+        await teams.updateMember(readTeamName, member.name, { herdrPaneId: id, tmuxPaneId: "" });
+      });
+      state.moveToHerdr = () => moving ??= (async () => {
+        if (!options.isCurrentReadAgentRun(key, state) || (!handoffRequested && !state.acceptingMessages)) {
+          throw new Error("The agent is already finishing.");
+        }
+        if (handoffRequested && !released) throw new Error("The current operation is still stopping. Try h after it settles.");
+        if (paneId) { herdrCommand("pane", "close", paneId); await recordPane(undefined); paneId = undefined; }
+        const sessionFile = childSessionManager.getSessionFile();
+        if (!sessionFile || !fs.existsSync(sessionFile)) throw new Error("The agent has no saved session yet.");
+        if (!handoffRequested) {
+          const promptDir = privateSessionDirectory ?? preparePrivateAgentSessionDirectory(readTeamName, member.name, state.runId);
+          const promptFile = path.join(promptDir, "herdr-system-prompt.txt");
+          fs.writeFileSync(promptFile, session.agent.state.systemPrompt.replace("running in-process so the lead can follow and control you from Pi", "running in a Herdr pane"), { mode: 0o600 });
+          const tools = session.agent.state.tools.map(tool => tool.name).join(",");
+          const identity = {
+            HOME: os.homedir(), PI_CODING_AGENT_DIR: agentDir,
+            PI_AGENT_NAME: member.name, PI_TEAM_NAME: readTeamName, PI_LIFECYCLE_RUN_ID: state.runId,
+            PI_EXTENDED_TEAMS_HERDR_RESUME: "1",
+          };
+          const currentModel = session.model ?? model;
+          const launch = buildPiCommand(getPiLaunchCommand(), `${currentModel.provider}/${currentModel.id}`,
+            session.thinkingLevel ?? member.thinking, resourcePlan.extensionPaths,
+            resourcePlan.trust.projectTrusted, resourcePlan.selfExtensionPath);
+          command = [
+            "env", ...Object.entries(identity).map(([name, value]) => `${name}=${shellQuote(value)}`), launch,
+            "--session", shellQuote(sessionFile), "--tools", shellQuote(tools), "--system-prompt", shellQuote(promptFile),
+          ].join(" ");
+          // Keep fresh-shell input below the PTY line limit without shortening the launch arguments.
+          const launchFile = path.join(promptDir, "herdr-launch.sh");
+          fs.writeFileSync(launchFile, `exec ${command}\n`, { mode: 0o600 });
+          command = `/bin/sh ${shellQuote(launchFile)}`;
+        }
+        paneId = JSON.parse(herdrCommand("pane", "split", "--current", "--direction", "right", "--cwd", member.cwd, "--focus")).result?.pane?.pane_id;
+        if (typeof paneId !== "string" || !paneId) throw new Error("Herdr did not return a pane ID.");
+        try {
+          if (!handoffRequested) {
+            handoffRequested = true;
+            state.stopRequested = true;
+            const delivery = closeReadAgentMessageDelivery(state);
+            const pending = session.clearQueue();
+            queued = [...pending.steering, ...pending.followUp];
+            signalReadAgentWake(state);
+            const shutdown = await sessionLifecycle.requestShutdown("resume", delivery.rawDeliverySettlement);
+            if (shutdown.status !== "settled" || shutdown.abort !== "settled" || shutdown.dispose !== "settled") {
+              throw new Error("The current operation has not stopped. Try h after it settles.");
+            }
+            await release;
+          }
+          if (queued.length) {
+            SessionManager.open(sessionFile).appendMessage({ role: "user", content: queued.join("\n\n"), timestamp: Date.now() });
+            queued = [];
+          }
+          const previousPid = (await runtime.readRuntimeStatus(readTeamName, member.name))?.pid;
+          await recordPane(paneId);
+          herdrCommand("pane", "run", paneId, command);
+          const deadline = Date.now() + 10000;
+          for (;;) {
+            const status = await runtime.readRuntimeStatus(readTeamName, member.name);
+            if (status?.lifecycleRunId === state.runId && status.pid && status.pid !== previousPid && status.pid !== process.pid) break;
+            if (Date.now() >= deadline) throw new Error("Pi did not resume. The saved session is retained; h can retry.");
+            await new Promise(resolve => setTimeout(resolve, 50));
+          }
+          if (options.isCurrentReadAgentRun(key, state)) options.runningReadAgents.delete(key);
+          options.renderReadAgentStatus();
+        } catch (error) {
+          herdrCommand("pane", "close", paneId);
+          await recordPane(undefined);
+          paneId = undefined;
+          throw error;
+        }
+      })().catch(error => { moving = undefined; throw error; });
+    }
     markReadAgentActivity(state, "started", "thinking");
     options.renderReadAgentStatus();
 
@@ -1262,6 +1361,7 @@ export async function runReadAgentInProcess(
     if (state.heartbeatTimer) clearInterval(state.heartbeatTimer);
     state.heartbeatTimer = undefined;
     closeReadAgentMessageDelivery(state);
+    if (handoffRequested) { state.resolveFinished?.(); return; }
     const teardown = await shutdownTeammate(readTeamName, member, { reason: "quit" });
     if (pendingChildController && pendingChildParent) {
       pendingChildController.forgetParent(pendingChildParent);

package/extensions/events/register-events.ts

@@ -220,10 +220,14 @@ export function registerExtensionEvents(pi: any, options: RegisterEventsOptions)
       }
 
       scheduleTeammateOneShot(() => {
-        options.quietTrigger("read_inbox to get your instructions, then begin your work.");
+        options.quietTrigger(process.env.PI_EXTENDED_TEAMS_HERDR_RESUME === "1"
+          ? "Continue your existing assignment. Read any new inbox messages, then finish and report_and_exit from this pane."
+          : "read_inbox to get your instructions, then begin your work.");
       }, 1000);
 
       if (teamName) {
+        const herdrResume = process.env.PI_EXTENDED_TEAMS_HERDR_RESUME === "1";
+        let notifiedInbox: string | undefined;
         let wakeInFlight = false;
         const wakeIfUnread = async () => {
           if (teammateInboxDisposed) return;
@@ -232,7 +236,7 @@ export function registerExtensionEvents(pi: any, options: RegisterEventsOptions)
             scheduleTeammateInboxWake(250);
             return;
           }
-          if (!ctx.isIdle()) {
+          if (!ctx.isIdle() && !herdrResume) {
             teammatePendingInboxWake = true;
             scheduleTeammateInboxWake(250);
             return;
@@ -246,7 +250,15 @@ export function registerExtensionEvents(pi: any, options: RegisterEventsOptions)
               lastHeartbeatAt: Date.now(),
             });
             if (unread.length > 0) {
-              options.quietTrigger(`You have ${unread.length} new inbox message(s). Read them with read_inbox and act.`);
+              const content = `You have ${unread.length} new inbox message(s). Read them with read_inbox and act.`;
+              if (herdrResume) {
+                const inboxVersion = JSON.stringify(unread);
+                if (inboxVersion !== notifiedInbox) {
+                  pi.sendMessage({ customType: "pi-extended-teams-wake", content, display: false },
+                    { triggerTurn: true, deliverAs: "steer" });
+                  notifiedInbox = inboxVersion;
+                }
+              } else options.quietTrigger(content);
             }
           } catch (e) {
             if (!teammateInboxDisposed) {

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/runtime/herdr.ts

@@ -0,0 +1,13 @@
+import { spawnSync } from "node:child_process";
+
+export function herdrCommand(...args: string[]): string {
+  if (process.env.HERDR_ENV !== "1") throw new Error("This action requires Herdr.");
+  const result = spawnSync("herdr", args, { encoding: "utf8", timeout: 5000 });
+  if (result.status !== 0) {
+    let code: string | undefined;
+    try { code = JSON.parse(result.stderr).error?.code; } catch { /* Non-JSON CLI failure. */ }
+    if (args[0] === "pane" && args[1] === "close" && code === "pane_not_found") return "";
+    throw new Error(result.stderr || result.error?.message || "Herdr command failed.");
+  }
+  return result.stdout;
+}

package/extensions/runtime/types.ts

@@ -47,6 +47,7 @@ export interface RunningReadAgent extends ManagedReadAgentLifecycleState {
   /** Fail finalization closed so runtime, member, fence, and transcript remain recoverable. */
   finalizationBlockedReason?: string;
   session?: AgentSession;
+  moveToHerdr?(): Promise<void>;
   finished?: Promise<void>;
 }
 

package/extensions/team/lifecycle.ts

@@ -20,7 +20,8 @@ import {
   type ReadAgentTeardownResult,
 } from "../agents/read-agent-session-lifecycle";
 import { releaseAllClaimsForAgent } from "./roster";
-import { cleanupPidFileProcess } from "../internal/session-files";
+import { cleanupPidFileProcess, unlinkPidFile } from "../internal/session-files";
+import { herdrCommand } from "../runtime/herdr";
 import { closePersistedRecipient } from "./recipient-closure";
 import { cleanupPrivateAgentSessionDirectory } from "../internal/agent-session-files";
 
@@ -65,7 +66,10 @@ export function createLifecycleRuntime(options: LifecycleRuntimeOptions) {
   async function finalizeTeammateRuntime(teamName: string, member: Member, expectedRunId: string): Promise<void> {
     const pidFile = path.join(paths.teamDir(teamName), `${member.name}.pid`);
     const pidFileExisted = fs.existsSync(pidFile);
-    const pidCleanup = cleanupPidFileProcess(pidFile, { skipPid: process.pid });
+    if (member.herdrPaneId) herdrCommand("pane", "close", member.herdrPaneId);
+    const pidCleanup = member.herdrPaneId
+      ? { pid: undefined, killError: undefined, unlinked: !pidFileExisted || unlinkPidFile(pidFile) }
+      : cleanupPidFileProcess(pidFile, { skipPid: process.pid });
     if (pidFileExisted && !pidCleanup.unlinked) {
       throw new Error(`Could not remove pid file for ${member.name}.`);
     }

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/coordination-tools.ts

@@ -147,6 +147,7 @@ export function registerCoordinationTools(pi: any, options: CoordinationToolsOpt
     async execute(_toolCallId: string, params: any, _signal: AbortSignal, _onUpdate: any, ctx: any) {
       const targetTeamName = requireCurrentSession(options);
       if (!options.isTeammate) throw new Error("report_and_exit is only available to spawned agents.");
+      if (process.env.PI_EXTENDED_TEAMS_HERDR_RESUME === "1" && !params.content.trim()) throw new Error("Final report content must not be empty.");
 
       const config = await teams.readConfig(targetTeamName);
       const member = config.members.find(m => m.name === options.agentName);
@@ -271,6 +272,7 @@ export function registerCoordinationTools(pi: any, options: CoordinationToolsOpt
     async execute(_toolCallId: string, params: any, _signal: AbortSignal, _onUpdate: any, _ctx: any) {
       const targetTeamName = requireCurrentSession(options);
       const targetAgent = params.agent_name || options.agentName;
+      if (process.env.PI_EXTENDED_TEAMS_HERDR_RESUME === "1" && targetAgent !== options.agentName) throw new Error("A resumed subagent can only read its own inbox.");
       const markAsRead = params.mark_as_read !== false;
       const unreadOnly = params.unread_only !== false;
       const msgs = await messaging.readInbox(targetTeamName, targetAgent, unreadOnly, markAsRead);

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));