pi-extended-teams 2.1.16

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

@@ -0,0 +1,334 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import * as paths from "../../src/utils/paths.js";
+import { registerTaskRuntimeTools } from "./task-runtime-tools.js";
+import * as teams from "../../src/utils/teams.js";
+import * as runtime from "../../src/utils/runtime.js";
+import * as messaging from "../../src/utils/messaging.js";
+import * as reportEvents from "../../src/utils/report-events.js";
+import type { Member } from "../../src/utils/models.js";
+import type { RunningReadAgent } from "../runtime/types.js";
+
+let root = "";
+
+function registerTools(isTeammate: boolean) {
+  const tools = new Map<string, any>();
+  registerTaskRuntimeTools({ registerTool: (tool: any) => tools.set(tool.name, tool) }, {
+    isTeammate,
+    terminal: null,
+    runningReadAgents: new Map(),
+    readAgentKey: (teamName: string, agentName: string) => `${teamName}:${agentName}`,
+    shutdownTeammate: vi.fn(async () => ({
+      status: "settled" as const,
+      reason: "quit" as const,
+      extensionShutdown: "no_handlers" as const,
+      abort: "unavailable" as const,
+      delivery: "settled" as const,
+      dispose: "settled" as const,
+      cancelledDeliveries: 0,
+      persistenceClosed: true,
+      finalized: true,
+      removedMember: true,
+      releasedClaims: [],
+    })),
+    getTeamName: () => "team",
+  });
+  return tools;
+}
+
+describe("task runtime tools", () => {
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "task-runtime-tools-"));
+    vi.spyOn(paths, "lifecycleTombstonePath").mockImplementation((teamName, agentName) => {
+      return path.join(root, String(teamName), "lifecycle", "quarantine", `${String(agentName)}.json`);
+    });
+    vi.spyOn(paths, "reportEventsPath").mockImplementation((teamName) => {
+      return path.join(root, String(teamName), "reports.json");
+    });
+    vi.spyOn(paths, "reportFilesDir").mockReturnValue(path.join(root, "agent", "reports"));
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it("keeps stop_teammate lead-only while leaving diagnostics available", () => {
+    const leadTools = registerTools(false);
+    const teammateTools = registerTools(true);
+
+    expect(leadTools.has("stop_teammate")).toBe(true);
+    expect(leadTools.has("check_teammate")).toBe(true);
+    expect(teammateTools.has("stop_teammate")).toBe(false);
+    expect(teammateTools.has("check_teammate")).toBe(true);
+  });
+
+  it("reports timeout quarantine instead of claiming the agent stopped cleanly", async () => {
+    const tools = new Map<string, any>();
+    const teardown = {
+      status: "timed_out" as const,
+      reason: "quit" as const,
+      extensionShutdown: "emitted" as const,
+      abort: "timed_out" as const,
+      delivery: "timed_out" as const,
+      dispose: "deferred" as const,
+      cancelledDeliveries: 1,
+      persistenceClosed: true,
+      finalized: false,
+      removedMember: false,
+      releasedClaims: [],
+    };
+    const readConfig = vi.spyOn(teams, "readConfig").mockResolvedValue({
+      name: "team",
+      description: "",
+      createdAt: Date.now(),
+      leadAgentId: "lead",
+      leadSessionId: "session",
+      members: [{
+        agentId: "reader@team",
+        name: "reader",
+        agentType: "teammate",
+        role: "read",
+        joinedAt: Date.now(),
+        tmuxPaneId: "",
+        cwd: process.cwd(),
+        subscriptions: [],
+      }],
+    });
+    try {
+      registerTaskRuntimeTools({ registerTool: (tool: any) => tools.set(tool.name, tool) }, {
+        isTeammate: false,
+        terminal: null,
+        runningReadAgents: new Map(),
+        readAgentKey: (teamName, agentName) => `${teamName}:${agentName}`,
+        shutdownTeammate: vi.fn(async () => teardown),
+        getTeamName: () => "team",
+      });
+
+      const result = await tools.get("stop_teammate").execute("stop", { agent_name: "reader" });
+      expect(result.content[0].text).toContain("inactive but quarantined");
+      expect(result.content[0].text).not.toContain("Stopped agent");
+      expect(result.details).toMatchObject({ stopped: false, quarantined: true, teardown });
+    } finally {
+      readConfig.mockRestore();
+    }
+  });
+
+  it("limits post-roster persisted report recovery to the lead", async () => {
+    const leadTools = registerTools(false);
+    const teammateTools = registerTools(true);
+    vi.spyOn(teams, "readConfig").mockResolvedValue({
+      name: "team", description: "", createdAt: Date.now(), leadAgentId: "lead", leadSessionId: "session", members: [],
+    });
+    await reportEvents.appendTeamReportEvent("team", {
+      agentName: "finished-reader",
+      role: "read",
+      status: "completed",
+      report: "Durable completed report",
+      summary: "Done",
+      createdAt: Date.now(),
+      source: "read-agent",
+      metadata: { reportSource: "persisted-report_and_exit", recoverySessionFile: "/tmp/finished-reader.jsonl" },
+    });
+
+    const result = await leadTools.get("check_teammate").execute("check", { agent_name: "finished-reader" });
+
+    expect(result.content[0].text).toContain("Recovered its latest persisted completed report");
+    expect(result.content[0].text).toContain("Durable completed report");
+    expect(result.content[0].text).toContain("/tmp/finished-reader.jsonl");
+    expect(result.content[0].text).toContain(path.join(root, "team", "reports.json"));
+    expect(result.details).toMatchObject({
+      alive: false,
+      health: "completed",
+      removedMember: true,
+      completedReport: { agentName: "finished-reader", report: "Durable completed report" },
+    });
+
+    const listReports = vi.spyOn(reportEvents, "listTeamReportEvents");
+    await expect(teammateTools.get("check_teammate").execute("check", { agent_name: "finished-reader" }))
+      .rejects.toThrow("Agent finished-reader not found");
+    expect(listReports).not.toHaveBeenCalled();
+  });
+
+  it("uses lifecycle cleanup proof for a settled dead teammate", async () => {
+    const tools = new Map<string, any>();
+    const member: Member = {
+      agentId: "dead@team",
+      name: "dead",
+      agentType: "teammate",
+      role: "write",
+      joinedAt: Date.now() - 60_000,
+      tmuxPaneId: "%dead",
+      cwd: process.cwd(),
+      subscriptions: [],
+      isActive: true,
+    };
+    vi.spyOn(teams, "readConfig").mockResolvedValue({
+      name: "team", description: "", createdAt: Date.now(), leadAgentId: "lead", leadSessionId: "session", members: [member],
+    });
+    vi.spyOn(runtime, "readRuntimeStatus").mockResolvedValue(null);
+    vi.spyOn(messaging, "readInbox").mockResolvedValue([]);
+    const shutdownTeammate = vi.fn(async () => ({
+      status: "settled" as const,
+      reason: "quit" as const,
+      extensionShutdown: "no_handlers" as const,
+      abort: "unavailable" as const,
+      delivery: "settled" as const,
+      dispose: "settled" as const,
+      cancelledDeliveries: 0,
+      persistenceClosed: true,
+      finalized: true,
+      removedMember: true,
+      releasedClaims: ["src/dead.ts"],
+    }));
+    registerTaskRuntimeTools({ registerTool: (tool: any) => tools.set(tool.name, tool) }, {
+      isTeammate: false,
+      terminal: { isAlive: vi.fn(() => false) },
+      runningReadAgents: new Map(),
+      readAgentKey: (teamName, agentName) => `${teamName}:${agentName}`,
+      shutdownTeammate,
+      getTeamName: () => "team",
+    });
+
+    const result = await tools.get("check_teammate").execute("check", { agent_name: "dead" });
+
+    expect(shutdownTeammate).toHaveBeenCalledOnce();
+    expect(result.details).toMatchObject({
+      alive: false,
+      health: "dead",
+      removedMember: true,
+      releasedClaims: ["src/dead.ts"],
+    });
+  });
+
+  it.each([
+    ["stopping", "stopping"],
+    ["quarantined", "quarantined"],
+    ["persistence_failed", "persistence-failed"],
+  ] as const)("gives teardown state %s precedence and skips duplicate cleanup", async (teardownState, expectedHealth) => {
+    const tools = new Map<string, any>();
+    const member: Member = {
+      agentId: "reader@team", name: "reader", agentType: "teammate", role: "read",
+      joinedAt: Date.now(), tmuxPaneId: "", cwd: process.cwd(), subscriptions: [], isActive: false,
+    };
+    vi.spyOn(teams, "readConfig").mockResolvedValue({
+      name: "team", description: "", createdAt: Date.now(), leadAgentId: "lead", leadSessionId: "session", members: [member],
+    });
+    vi.spyOn(runtime, "readRuntimeStatus").mockResolvedValue({
+      teamName: "team", agentName: "reader", ready: true, startedAt: Date.now(), lastHeartbeatAt: Date.now(), currentAction: "working",
+    });
+    vi.spyOn(messaging, "readInbox").mockResolvedValue([]);
+    const state: RunningReadAgent = {
+      runId: "run", name: "reader", teamName: "team", startedAt: Date.now(), tokensUsed: 10,
+      status: "working", recentEvents: [], lastActivityAt: Date.now(), teardownState,
+    };
+    const shutdownTeammate = vi.fn();
+    registerTaskRuntimeTools({ registerTool: (tool: any) => tools.set(tool.name, tool) }, {
+      isTeammate: false,
+      terminal: null,
+      runningReadAgents: new Map([["team:reader", state]]),
+      readAgentKey: (teamName, agentName) => `${teamName}:${agentName}`,
+      shutdownTeammate,
+      getTeamName: () => "team",
+    });
+
+    const result = await tools.get("check_teammate").execute("check", { agent_name: "reader" });
+
+    expect(result.details).toMatchObject({ alive: false, health: expectedHealth, agentLoopReady: false, removedMember: false });
+    expect(result.content[0].text).toContain(expectedHealth);
+    expect(shutdownTeammate).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    { label: "fresh runtime heartbeat", isActive: true, heartbeatAge: 0, paneAlive: false, expectedAlive: true, expectedHealth: "healthy" },
+    { label: "stale ready file", isActive: true, heartbeatAge: runtime.HEARTBEAT_STALE_MS + 1, paneAlive: false, expectedAlive: false, expectedHealth: "dead" },
+    { label: "inactive stale ready file", isActive: false, heartbeatAge: runtime.HEARTBEAT_STALE_MS + 1, paneAlive: false, expectedAlive: false, expectedHealth: "dead" },
+    { label: "live legacy pane", isActive: true, heartbeatAge: runtime.HEARTBEAT_STALE_MS + 1, paneAlive: true, expectedAlive: true, expectedHealth: "idle" },
+    { label: "inactive legacy pane", isActive: false, heartbeatAge: 0, paneAlive: true, expectedAlive: false, expectedHealth: "dead" },
+  ])("classifies legacy diagnostics coherently: $label", async ({ isActive, heartbeatAge, paneAlive, expectedAlive, expectedHealth }) => {
+    const tools = new Map<string, any>();
+    const now = Date.now();
+    const member: Member = {
+      agentId: "legacy@team", name: "legacy", agentType: "teammate", role: "write",
+      joinedAt: now - 60_000, tmuxPaneId: "%legacy", cwd: process.cwd(), subscriptions: [], isActive,
+    };
+    vi.spyOn(teams, "readConfig").mockResolvedValue({
+      name: "team", description: "", createdAt: now, leadAgentId: "lead", leadSessionId: "session", members: [member],
+    });
+    vi.spyOn(runtime, "readRuntimeStatus").mockResolvedValue({
+      teamName: "team", agentName: "legacy", ready: true, startedAt: now - 60_000, lastHeartbeatAt: now - heartbeatAge,
+    });
+    vi.spyOn(messaging, "readInbox").mockResolvedValue([]);
+    const shutdownTeammate = vi.fn(async () => ({
+      status: "settled" as const, reason: "quit" as const, extensionShutdown: "no_handlers" as const,
+      abort: "unavailable" as const, delivery: "settled" as const, dispose: "settled" as const,
+      cancelledDeliveries: 0, persistenceClosed: true, finalized: true, removedMember: true, releasedClaims: [],
+    }));
+    registerTaskRuntimeTools({ registerTool: (tool: any) => tools.set(tool.name, tool) }, {
+      isTeammate: false,
+      terminal: { isAlive: vi.fn(() => paneAlive) },
+      runningReadAgents: new Map(),
+      readAgentKey: (teamName, agentName) => `${teamName}:${agentName}`,
+      shutdownTeammate,
+      getTeamName: () => "team",
+    });
+
+    const result = await tools.get("check_teammate").execute("check", { agent_name: "legacy" });
+
+    expect(result.details.alive).toBe(expectedAlive);
+    expect(result.details.health).toBe(expectedHealth);
+    expect(shutdownTeammate).toHaveBeenCalledTimes(expectedAlive ? 0 : 1);
+  });
+
+  it.each([
+    { status: "timed_out" as const, expectedHealth: "quarantined" },
+    { status: "persistence_failed" as const, expectedHealth: "persistence-failed" },
+    { status: "cleanup_failed" as const, expectedHealth: "cleanup-blocked" },
+  ])("maps lifecycle $status without destructive fallback", async ({ status, expectedHealth }) => {
+    const tools = new Map<string, any>();
+    const member: Member = {
+      agentId: "dead@team", name: "dead", agentType: "teammate", role: "read",
+      joinedAt: Date.now(), tmuxPaneId: "", cwd: process.cwd(), subscriptions: [], isActive: false,
+    };
+    vi.spyOn(teams, "readConfig").mockResolvedValue({
+      name: "team", description: "", createdAt: Date.now(), leadAgentId: "lead", leadSessionId: "session", members: [member],
+    });
+    vi.spyOn(runtime, "readRuntimeStatus").mockResolvedValue(null);
+    vi.spyOn(messaging, "readInbox").mockResolvedValue([]);
+    const shutdownTeammate = vi.fn(async () => ({
+      status,
+      reason: "quit" as const,
+      extensionShutdown: "no_handlers" as const,
+      abort: "unavailable" as const,
+      delivery: "settled" as const,
+      dispose: "deferred" as const,
+      cancelledDeliveries: 0,
+      persistenceClosed: status !== "persistence_failed",
+      finalized: false,
+      removedMember: false,
+      releasedClaims: ["src/already-released.ts"],
+      error: "blocked cleanup",
+    }));
+    registerTaskRuntimeTools({ registerTool: (tool: any) => tools.set(tool.name, tool) }, {
+      isTeammate: false,
+      terminal: null,
+      runningReadAgents: new Map(),
+      readAgentKey: (teamName, agentName) => `${teamName}:${agentName}`,
+      shutdownTeammate,
+      getTeamName: () => "team",
+    });
+
+    const result = await tools.get("check_teammate").execute("check", { agent_name: "dead" });
+
+    expect(shutdownTeammate).toHaveBeenCalledOnce();
+    expect(result.details).toMatchObject({
+      alive: false,
+      health: expectedHealth,
+      removedMember: false,
+      releasedClaims: ["src/already-released.ts"],
+      error: "blocked cleanup",
+    });
+  });
+});

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

@@ -0,0 +1,227 @@
+import { Type } from "@sinclair/typebox";
+import * as teams from "../../src/utils/teams";
+import * as runtime from "../../src/utils/runtime";
+import * as messaging from "../../src/utils/messaging";
+import * as reportEvents from "../../src/utils/report-events";
+import * as paths from "../../src/utils/paths";
+import { formatTeammateStatusForModel, renderTeammateStatus } from "../ui/renderers";
+import type { RunningReadAgent } from "../runtime/types";
+import type { Member } from "../../src/utils/models";
+import type { ReadAgentTeardownResult } from "../agents/read-agent-session-lifecycle";
+import type { ShutdownTeammateOptions } from "../team/lifecycle";
+import { readLifecycleTombstone } from "../../src/utils/lifecycle-tombstone";
+
+export interface TaskRuntimeToolsOptions {
+  isTeammate: boolean;
+  terminal: any;
+  runningReadAgents: Map<string, RunningReadAgent>;
+  readAgentKey(teamName: string, agentName: string): string;
+  shutdownTeammate(teamName: string, member: Member, options?: ShutdownTeammateOptions): Promise<ReadAgentTeardownResult>;
+  getTeamName(): string | null | undefined;
+}
+
+export function registerTaskRuntimeTools(pi: any, options: TaskRuntimeToolsOptions): void {
+  if (!options.isTeammate) {
+    pi.registerTool({
+      name: "stop_teammate",
+      label: "Stop Agent",
+      description: "Stop one active agent in the current Pi session, release its file claims, and remove it from the active roster. Use only when the user explicitly asks to cancel/stop an agent or the agent is no longer needed.",
+      parameters: Type.Object({
+        agent_name: Type.String(),
+        reason: Type.Optional(Type.String()),
+      }),
+      async execute(_toolCallId: string, params: any) {
+        const teamName = options.getTeamName();
+        if (!teamName) throw new Error("No active agent session. Spawn an agent first.");
+
+        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));
+        if (!member && runningState) {
+          member = {
+            agentId: `${params.agent_name}@${teamName}`,
+            name: params.agent_name,
+            agentType: "teammate",
+            lifecycleRunId: runningState.runId,
+            role: runningState.role === "write" ? "write" : "read",
+            model: runningState.model,
+            thinking: runningState.thinking as Member["thinking"],
+            modelSlot: runningState.modelSlot as Member["modelSlot"],
+            joinedAt: runningState.startedAt,
+            tmuxPaneId: "",
+            cwd: "",
+            subscriptions: [],
+          };
+        }
+        if (!member || member.name === "team-lead") {
+          const fence = await readLifecycleTombstone(teamName, params.agent_name);
+          if (fence.status !== "absent") {
+            return {
+              content: [{ type: "text", text: `Agent ${params.agent_name} is inactive but quarantined; lifecycle cleanup is still fenced.` }],
+              details: {
+                session: teamName,
+                agentName: params.agent_name,
+                stopped: false,
+                quarantined: true,
+                blocked: true,
+                reason: params.reason,
+                tombstone: fence.status === "occupied" ? fence.tombstone : undefined,
+                error: fence.status === "corrupt" ? fence.error : undefined,
+              },
+            };
+          }
+          return {
+            content: [{ type: "text", text: `Agent ${params.agent_name} is not active in this session.` }],
+            details: { session: teamName, agentName: params.agent_name, stopped: false, reason: "not-active" },
+          };
+        }
+
+        const teardown = await options.shutdownTeammate(teamName, member);
+        const stopped = teardown.status === "settled" && teardown.finalized && teardown.removedMember;
+        if (!stopped) {
+          const blocked = teardown.status === "persistence_failed" ? "persistence-failed"
+            : teardown.status === "timed_out" ? "quarantined"
+              : "cleanup-blocked";
+          return {
+            content: [{ type: "text", text: `Agent ${params.agent_name} is inactive but ${blocked}; lifecycle cleanup did not complete${teardown.error ? `: ${teardown.error}` : "."}` }],
+            details: {
+              session: teamName,
+              agentName: params.agent_name,
+              stopped: false,
+              quarantined: teardown.status === "timed_out",
+              blocked: true,
+              reason: params.reason,
+              teardown,
+            },
+          };
+        }
+        return {
+          content: [{ type: "text", text: `Stopped agent ${params.agent_name}${params.reason ? `: ${params.reason}` : "."}` }],
+          details: { session: teamName, agentName: params.agent_name, stopped: true, reason: params.reason, teardown },
+        };
+      },
+    });
+  }
+
+  pi.registerTool({
+    name: "check_teammate",
+    label: "Check Agent",
+    description: options.isTeammate
+      ? "Check one agent's active status in the current Pi session only for targeted diagnostics after it has been quiet for several minutes or appears unhealthy. Do not use immediately after sending a message or while waiting for normal work."
+      : "Check one agent's status in the current Pi session only for targeted diagnostics after it has been quiet for several minutes or appears unhealthy. If the agent already left the roster before its report reached you, this recovers its latest persisted report. Do not use immediately after sending a message, while waiting for normal work, or after a report has already arrived.",
+    parameters: Type.Object({ agent_name: Type.String() }),
+    async execute(_toolCallId: string, params: any) {
+      const teamName = options.getTeamName();
+      if (!teamName) throw new Error("No active agent session. Spawn an agent first.");
+
+      const config = await teams.readConfig(teamName);
+      const member = config.members.find(m => m.name === params.agent_name);
+      if (!member) {
+        const fence = await readLifecycleTombstone(teamName, params.agent_name);
+        if (fence.status !== "absent") {
+          const details = {
+            agentName: params.agent_name,
+            alive: false,
+            unreadCount: 0,
+            health: "quarantined",
+            agentLoopReady: false,
+            hasRecentHeartbeat: false,
+            startupStalled: false,
+            runtime: await runtime.readRuntimeStatus(teamName, params.agent_name).catch(() => null),
+            teardownState: "quarantined",
+            removedMember: false,
+            releasedClaims: [],
+            tombstone: fence.status === "occupied" ? fence.tombstone : undefined,
+            error: fence.status === "corrupt" ? fence.error : undefined,
+          };
+          return { content: [{ type: "text", text: formatTeammateStatusForModel(params.agent_name, details) }], details };
+        }
+        if (options.isTeammate) throw new Error(`Agent ${params.agent_name} not found`);
+        const latestReport = (await reportEvents.listTeamReportEvents(teamName, {
+          agentName: params.agent_name,
+          limit: 1,
+        })).at(-1);
+        if (latestReport) {
+          const reportPath = paths.reportEventsPath(teamName);
+          const report = String(latestReport.report || "").trim();
+          const recoverySessionFile = typeof latestReport.metadata?.recoverySessionFile === "string"
+            ? latestReport.metadata.recoverySessionFile
+            : undefined;
+          const text = [
+            `Agent ${params.agent_name} is no longer active. Recovered its latest persisted ${latestReport.status} report from ${reportPath}.`,
+            recoverySessionFile
+              ? `Its durable child transcript is available at ${recoverySessionFile}. Use the read tool on that path if the report is incomplete.`
+              : undefined,
+            report || "The persisted report body is empty; inspect the report event file above for metadata and any recovery pointer.",
+          ].filter(Boolean).join("\n\n");
+          const details = {
+            agentName: params.agent_name,
+            alive: false,
+            unreadCount: 0,
+            health: latestReport.status,
+            agentLoopReady: false,
+            hasRecentHeartbeat: false,
+            startupStalled: false,
+            removedMember: true,
+            releasedClaims: [],
+            reportPath,
+            completedReport: latestReport,
+          };
+          return { content: [{ type: "text", text }], details };
+        }
+        throw new Error(`Agent ${params.agent_name} not found and no persisted report is available.`);
+      }
+
+      const unreadCount = (await messaging.readInbox(teamName, params.agent_name, true, false)).length;
+      const runtimeStatus = await runtime.readRuntimeStatus(teamName, params.agent_name).catch(() => null);
+      const now = Date.now();
+      const hasRecentHeartbeat = !!runtimeStatus?.lastHeartbeatAt && (now - runtimeStatus.lastHeartbeatAt) <= runtime.HEARTBEAT_STALE_MS;
+      const runningState = options.runningReadAgents.get(options.readAgentKey(teamName, member.name));
+      const lifecycleHealth = runningState?.teardownState === "persistence_failed" ? "persistence-failed"
+        : runningState?.teardownState === "quarantined" ? "quarantined"
+          : runningState?.teardownState === "stopping" ? "stopping"
+            : undefined;
+      const memberActive = member.isActive !== false;
+      const legacyPaneAlive = memberActive && !!(member.tmuxPaneId && options.terminal?.isAlive?.(member.tmuxPaneId));
+      const inProcessAlive = !!runningState && !lifecycleHealth && runningState.teardownState !== "finalized";
+      const alive = inProcessAlive || (memberActive && (hasRecentHeartbeat || legacyPaneAlive));
+      const startupStalled = alive && unreadCount > 0 && (now - member.joinedAt) > runtime.STARTUP_STALL_MS && !(runtimeStatus?.ready);
+      let health = lifecycleHealth
+        ?? (!alive ? "dead" : startupStalled ? "stalled" : runtimeStatus?.ready && hasRecentHeartbeat ? "healthy" : runtimeStatus?.ready || legacyPaneAlive ? "idle" : "starting");
+      let teardown: ReadAgentTeardownResult | undefined = runningState?.teardownResult;
+      let lifecycleError: string | undefined;
+
+      if (!alive && !lifecycleHealth) {
+        try {
+          teardown = await options.shutdownTeammate(teamName, member);
+          if (teardown.status === "timed_out") health = "quarantined";
+          else if (teardown.status === "persistence_failed") health = "persistence-failed";
+          else if (teardown.status === "cleanup_failed" || !teardown.finalized) health = "cleanup-blocked";
+        } catch (error) {
+          lifecycleError = error instanceof Error ? error.message : String(error);
+          health = "cleanup-blocked";
+        }
+      }
+
+      const details = {
+        agentName: params.agent_name,
+        alive: lifecycleHealth ? false : alive,
+        unreadCount,
+        health,
+        agentLoopReady: !lifecycleHealth && alive && !!runtimeStatus?.ready,
+        hasRecentHeartbeat,
+        startupStalled,
+        runtime: runtimeStatus,
+        teardownState: runningState?.teardownState,
+        teardown,
+        releasedClaims: teardown?.releasedClaims ?? [],
+        removedMember: teardown?.removedMember ?? false,
+        error: teardown?.error ?? lifecycleError,
+      };
+      return { content: [{ type: "text", text: formatTeammateStatusForModel(params.agent_name, details) }], details };
+    },
+    renderResult(result: any, { expanded }: any, theme: any) {
+      return renderTeammateStatus(result, expanded, theme);
+    },
+  });
+}