pi-extended-teams 2.1.16

package/extensions/team/recipient-closure.ts

@@ -0,0 +1,120 @@
+import * as teams from "../../src/utils/teams";
+import {
+  generateExtensionInstanceId,
+  withLifecycleTombstoneLock,
+} from "../../src/utils/lifecycle-tombstone";
+
+export interface ClosePersistedRecipientOptions {
+  removeOnFailure?: boolean;
+  role?: "read" | "write";
+  reason?: string;
+  extensionInstanceId?: string;
+}
+
+const FALLBACK_EXTENSION_INSTANCE_ID = generateExtensionInstanceId();
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export async function closePersistedRecipient(
+  teamName: string,
+  agentName: string,
+  expectedRunId: string,
+  options: ClosePersistedRecipientOptions = {}
+): Promise<void> {
+  await withLifecycleTombstoneLock(teamName, agentName, async lifecycleLock => {
+    const tombstoneInput = {
+      team: teamName,
+      agent: agentName,
+      runId: expectedRunId,
+      role: options.role ?? "read",
+      reason: options.reason ?? "quit",
+      extensionInstanceId: options.extensionInstanceId ?? FALLBACK_EXTENSION_INSTANCE_ID,
+    } as const;
+
+    if (!teams.teamExists(teamName)) {
+      lifecycleLock.occupy(tombstoneInput);
+      lifecycleLock.updateMatching(expectedRunId, { phase: "persistence_closed", error: undefined });
+      return;
+    }
+
+    const readExpectedMember = async () => {
+      const config = await teams.readConfig(teamName);
+      const member = config.members.find(item => item.name === agentName);
+      if (member && member.lifecycleRunId !== expectedRunId) {
+        throw new Error(
+          `Refusing to close ${agentName} in ${teamName}: expected run ${expectedRunId}, found ${member.lifecycleRunId || "missing run id"}.`
+        );
+      }
+      return member;
+    };
+
+    // Establish run identity under the recipient lock before creating a fence.
+    // A wrong-run caller performs zero shared mutation. Unreadable persistence
+    // cannot establish safety, so it is fenced fail-closed before returning.
+    let initialMember: Awaited<ReturnType<typeof readExpectedMember>>;
+    try {
+      initialMember = await readExpectedMember();
+    } catch (error) {
+      if (error instanceof Error && error.message.startsWith("Refusing to close")) throw error;
+      lifecycleLock.occupy(tombstoneInput);
+      const message = `Could not close message admission for ${agentName} in ${teamName}: verification failed: ${errorText(error)}`;
+      lifecycleLock.updateMatching(expectedRunId, { phase: "cleanup_failed", error: message });
+      throw new Error(message);
+    }
+
+    lifecycleLock.occupy(tombstoneInput);
+    if (!initialMember) {
+      lifecycleLock.updateMatching(expectedRunId, { phase: "persistence_closed", error: undefined });
+      return;
+    }
+
+    let updateError: unknown;
+    try {
+      await teams.updateMember(teamName, agentName, { isActive: false });
+    } catch (error) {
+      updateError = error;
+    }
+
+    let closed = false;
+    let verificationError: unknown;
+    try {
+      const member = await readExpectedMember();
+      closed = !member || member.isActive === false;
+    } catch (error) {
+      verificationError = error;
+    }
+    if (closed) {
+      lifecycleLock.updateMatching(expectedRunId, { phase: "persistence_closed", error: undefined });
+      return;
+    }
+
+    let removalError: unknown;
+    if (options.removeOnFailure) {
+      try {
+        await readExpectedMember();
+        await teams.removeMemberMatchingRun(teamName, agentName, expectedRunId);
+      } catch (error) {
+        removalError = error;
+      }
+      try {
+        if (!(await readExpectedMember())) {
+          lifecycleLock.updateMatching(expectedRunId, { phase: "persistence_closed", error: undefined });
+          return;
+        }
+      } catch (error) {
+        verificationError = error;
+      }
+    }
+
+    const causes = [
+      updateError ? `inactive update failed: ${errorText(updateError)}` : "inactive update did not close membership",
+      verificationError ? `verification failed: ${errorText(verificationError)}` : undefined,
+      removalError ? `removal failed: ${errorText(removalError)}` : undefined,
+    ].filter(Boolean).join("; ");
+    const message = `Could not close message admission for ${agentName} in ${teamName}: ${causes}`;
+    lifecycleLock.updateMatching(expectedRunId, { phase: "cleanup_failed", error: message });
+    throw new Error(message);
+  });
+}

package/extensions/team/roster.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it, vi, afterEach } from "vitest";
+import { buildRoster, requireWriteAgentTeam } from "./roster.js";
+import * as teams from "../../src/utils/teams.js";
+import * as tasks from "../../src/utils/tasks.js";
+import * as claims from "../../src/utils/claims.js";
+import * as runtime from "../../src/utils/runtime.js";
+import * as messaging from "../../src/utils/messaging.js";
+import * as writeQueue from "../../src/utils/write-queue.js";
+import type { Member, TeamConfig, TaskFile } from "../../src/utils/models.js";
+import type { FileClaim } from "../../src/utils/claims.js";
+
+function member(name: string, overrides: Partial<Member> = {}): Member {
+  return {
+    agentId: `${name}@scale`,
+    name,
+    agentType: name === "team-lead" ? "lead" : "teammate",
+    role: name === "team-lead" ? undefined : "write",
+    joinedAt: Date.now(),
+    tmuxPaneId: name === "team-lead" ? "" : `%${name}`,
+    cwd: process.cwd(),
+    subscriptions: [],
+    ...overrides,
+  };
+}
+
+describe("write-agent authorization", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("rejects an identity that is absent from the session roster", async () => {
+    vi.spyOn(teams, "readConfig").mockResolvedValue({
+      name: "session",
+      description: "",
+      createdAt: Date.now(),
+      leadAgentId: "lead",
+      leadSessionId: "lead-session",
+      members: [member("team-lead")],
+    });
+
+    await expect(requireWriteAgentTeam("session", true, "missing-writer"))
+      .rejects.toThrow("Agent missing-writer is not a member of session session.");
+  });
+
+  it("preserves the legacy missing-role fallback only for a real roster member", async () => {
+    vi.spyOn(teams, "readConfig").mockResolvedValue({
+      name: "session",
+      description: "",
+      createdAt: Date.now(),
+      leadAgentId: "lead",
+      leadSessionId: "lead-session",
+      members: [member("team-lead"), member("legacy-writer", { role: undefined })],
+    });
+
+    await expect(requireWriteAgentTeam("session", true, "legacy-writer")).resolves.toBe("session");
+  });
+
+  it("rejects a real read member", async () => {
+    vi.spyOn(teams, "readConfig").mockResolvedValue({
+      name: "session",
+      description: "",
+      createdAt: Date.now(),
+      leadAgentId: "lead",
+      leadSessionId: "lead-session",
+      members: [member("team-lead"), member("reader", { role: "read" })],
+    });
+
+    await expect(requireWriteAgentTeam("session", true, "reader"))
+      .rejects.toThrow("File claim tools are only available to write agents.");
+  });
+});
+
+describe("team roster performance", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("indexes tasks and claims once instead of filtering full lists per member", async () => {
+    const members = [
+      member("team-lead"),
+      ...Array.from({ length: 300 }, (_unused, index) => member(`agent-${index}`)),
+    ];
+    const config: TeamConfig = {
+      name: "scale",
+      description: "",
+      createdAt: Date.now(),
+      leadAgentId: "lead",
+      leadSessionId: "session",
+      members,
+    };
+    const taskRows: TaskFile[] = [
+      { id: "1", subject: "active", description: "", status: "in_progress", owner: "agent-42", blocks: [], blockedBy: [] },
+      { id: "2", subject: "pending", description: "", status: "pending", owner: "agent-42", blocks: [], blockedBy: [] },
+      { id: "3", subject: "completed", description: "", status: "completed", owner: "agent-42", blocks: [], blockedBy: [] },
+      { id: "4", subject: "deleted", description: "", status: "deleted", owner: "agent-99", blocks: [], blockedBy: [] },
+      { id: "5", subject: "unowned", description: "", status: "pending", blocks: [], blockedBy: [] },
+    ];
+    const claimRows: FileClaim[] = [
+      { agent: "agent-42", path: "extensions/team/roster.ts", since: 1 },
+      { agent: "agent-99", path: "extensions/team/lifecycle.ts", since: 2 },
+    ];
+    const taskFilterSpy = vi.spyOn(taskRows, "filter");
+    const claimFilterSpy = vi.spyOn(claimRows, "filter");
+
+    vi.spyOn(teams, "readConfig").mockResolvedValue(config);
+    vi.spyOn(tasks, "listTasks").mockResolvedValue(taskRows);
+    vi.spyOn(claims, "listClaims").mockResolvedValue(claimRows);
+    vi.spyOn(writeQueue, "listWriteQueue").mockResolvedValue([]);
+    vi.spyOn(runtime, "readRuntimeStatus").mockResolvedValue({ ready: true } as any);
+    vi.spyOn(messaging, "readInbox").mockResolvedValue([]);
+
+    const roster = await buildRoster("scale", {
+      terminal: { isAlive: vi.fn(() => true) },
+      runningReadAgents: new Map(),
+      readAgentKey: (teamName: string, agentName: string) => `${teamName}:${agentName}`,
+    });
+
+    const agent42 = roster.members.find((item) => item.name === "agent-42");
+    expect(agent42?.tasks).toEqual([
+      { id: "1", subject: "active", status: "in_progress" },
+      { id: "2", subject: "pending", status: "pending" },
+    ]);
+    expect(agent42?.claims).toEqual(["extensions/team/roster.ts"]);
+    expect(roster.members.find((item) => item.name === "agent-99")?.tasks).toEqual([]);
+    expect(roster.members.find((item) => item.name === "agent-99")?.claims).toEqual(["extensions/team/lifecycle.ts"]);
+    expect(taskFilterSpy).not.toHaveBeenCalled();
+    expect(claimFilterSpy).not.toHaveBeenCalled();
+  });
+});

package/extensions/team/roster.ts

@@ -0,0 +1,165 @@
+import * as teams from "../../src/utils/teams";
+import * as tasks from "../../src/utils/tasks";
+import * as messaging from "../../src/utils/messaging";
+import * as runtime from "../../src/utils/runtime";
+import * as claims from "../../src/utils/claims";
+import * as writeQueue from "../../src/utils/write-queue";
+import type { TaskFile } from "../../src/utils/models";
+import type { FileClaim } from "../../src/utils/claims";
+import type { RunningReadAgent } from "../runtime/types";
+import { listLifecycleTombstones } from "../../src/utils/lifecycle-tombstone";
+
+type RosterTask = Pick<TaskFile, "id" | "subject" | "status">;
+
+export interface BuildRosterOptions {
+  terminal: any;
+  runningReadAgents: Map<string, RunningReadAgent>;
+  readAgentKey(teamName: string, agentName: string): string;
+}
+
+export function requireTeamContext(currentTeamName: string | null | undefined, explicitTeamName?: string): string {
+  const targetTeamName = explicitTeamName || currentTeamName;
+  if (!targetTeamName) {
+    throw new Error("No team name supplied and no current team context detected.");
+  }
+  return targetTeamName;
+}
+
+export async function requireWriteAgentTeam(
+  teamName: string | null | undefined,
+  isTeammate: boolean,
+  agentName: string
+): Promise<string> {
+  if (!teamName) {
+    throw new Error("No team context available for file claims.");
+  }
+  if (!isTeammate) {
+    throw new Error("claim_file and release_file are only available to teammates; leads should use list_file_claims.");
+  }
+
+  const teamConfig = await teams.readConfig(teamName);
+  const member = teamConfig.members.find(m => m.name === agentName);
+  if (!member) {
+    throw new Error(`Agent ${agentName} is not a member of session ${teamName}.`);
+  }
+  const role = member.role ?? "write";
+  if (role !== "write") {
+    throw new Error("File claim tools are only available to write agents.");
+  }
+
+  return teamName;
+}
+
+export async function releaseAllClaimsForAgent(teamName: string, agentName: string): Promise<string[]> {
+  return claims.releaseAllForAgent(teamName, agentName);
+}
+
+export function isWriteMemberAlive(member: any, terminal: any): boolean {
+  return !!(member.tmuxPaneId && terminal?.isAlive?.(member.tmuxPaneId));
+}
+
+export async function countWriteMembers(teamName: string, terminal?: any): Promise<number> {
+  const config = await teams.readConfig(teamName);
+  return config.members.filter(member => {
+    if (member.agentType !== "teammate" || (member.role ?? "write") !== "write") return false;
+    return terminal ? isWriteMemberAlive(member, terminal) : true;
+  }).length;
+}
+
+function indexOpenTasksByOwner(allTasks: TaskFile[]): Map<string, RosterTask[]> {
+  const tasksByOwner = new Map<string, RosterTask[]>();
+
+  for (const task of allTasks) {
+    if (!task.owner || task.status === "completed" || task.status === "deleted") continue;
+    const memberTasks = tasksByOwner.get(task.owner) ?? [];
+    memberTasks.push({ id: task.id, subject: task.subject, status: task.status });
+    if (memberTasks.length === 1) tasksByOwner.set(task.owner, memberTasks);
+  }
+
+  return tasksByOwner;
+}
+
+function indexClaimsByAgent(allClaims: FileClaim[]): Map<string, string[]> {
+  const claimsByAgent = new Map<string, string[]>();
+
+  for (const claim of allClaims) {
+    const memberClaims = claimsByAgent.get(claim.agent) ?? [];
+    memberClaims.push(claim.path);
+    if (memberClaims.length === 1) claimsByAgent.set(claim.agent, memberClaims);
+  }
+
+  return claimsByAgent;
+}
+
+export async function buildRoster(teamName: string, options: BuildRosterOptions) {
+  const config = await teams.readConfig(teamName);
+  const allTasks = await tasks.listTasks(teamName).catch(() => []);
+  const allClaims = await claims.listClaims(teamName).catch(() => []);
+  const queue = await writeQueue.listWriteQueue(teamName).catch(() => []);
+  const tasksByOwner = indexOpenTasksByOwner(allTasks);
+  const claimsByAgent = indexClaimsByAgent(allClaims);
+  const tombstones = await listLifecycleTombstones(teamName).catch(() => []);
+  const tombstoneByAgent = new Map(tombstones.map(entry => [entry.agentName, entry.result]));
+
+  const members = await Promise.all(config.members.map(async (member) => {
+    const role = member.role ?? (member.name === "team-lead" ? "lead" : "write");
+    const runtimeStatus = member.name === "team-lead" ? null : await runtime.readRuntimeStatus(teamName, member.name).catch(() => null);
+    const unreadCount = member.name === "team-lead" ? 0 : (await messaging.readInbox(teamName, member.name, true, false).catch(() => [])).length;
+    const memberTasks = tasksByOwner.get(member.name) ?? [];
+    const memberClaims = claimsByAgent.get(member.name) ?? [];
+    const readState = options.runningReadAgents.get(options.readAgentKey(teamName, member.name));
+    const alive = member.name === "team-lead"
+      ? true
+      : !!readState || !!runtimeStatus?.ready || (role === "write" && isWriteMemberAlive(member, options.terminal));
+
+    const tombstone = tombstoneByAgent.get(member.name);
+    return {
+      name: member.name,
+      role,
+      status: member.name === "team-lead" ? "lead" : tombstone ? "quarantined" : alive ? (readState?.status || "running") : "dead/idle",
+      model: member.model,
+      cwd: member.cwd,
+      unreadCount,
+      tasks: memberTasks,
+      claims: memberClaims,
+      tmuxPaneId: member.tmuxPaneId || undefined,
+      runtime: runtimeStatus,
+    };
+  }));
+
+  const knownNames = new Set(config.members.map(member => member.name));
+  for (const { agentName, result } of tombstones) {
+    if (knownNames.has(agentName)) continue;
+    members.push({
+      name: agentName,
+      role: result.status === "occupied" ? result.tombstone.role : "read",
+      status: "quarantined",
+      model: undefined,
+      cwd: "",
+      unreadCount: 0,
+      tasks: tasksByOwner.get(agentName) ?? [],
+      claims: claimsByAgent.get(agentName) ?? [],
+      tmuxPaneId: undefined,
+      runtime: await runtime.readRuntimeStatus(teamName, agentName).catch(() => null),
+    });
+  }
+
+  return {
+    teamName,
+    members,
+    writeQueue: queue.map((item, index) => ({ position: index + 1, id: item.id, name: item.name, requestedAt: item.requestedAt })),
+  };
+}
+
+export function formatRosterForPrompt(roster: Awaited<ReturnType<typeof buildRoster>>): string {
+  const lines = [`Agents for session ${roster.teamName}:`];
+  for (const member of roster.members) {
+    const taskText = member.tasks.length > 0 ? ` tasks=${member.tasks.map(task => `#${task.id}:${task.status}`).join(",")}` : "";
+    const claimText = member.claims.length > 0 ? ` claims=${member.claims.join(",")}` : "";
+    lines.push(`- ${member.name}: ${member.role}, ${member.status}, unread=${member.unreadCount}${taskText}${claimText}`);
+  }
+  if (roster.writeQueue.length > 0) {
+    lines.push(`Queued edit agents: ${roster.writeQueue.map(item => `${item.position}.${item.name}`).join(", ")}`);
+  }
+  return lines.join("\n");
+}

package/extensions/team/team-contracts.json

@@ -0,0 +1,43 @@
+{
+  "version": 1,
+  "updatedAt": "2026-07-12T00:00:00.000Z",
+  "source": "Leo Pereira session requirements",
+  "contracts": [
+    {
+      "id": "ui.team-activity-card",
+      "description": "Live team activity renders as a stable below-editor pi-emote-style card with always-open bounded details. It keeps the card design with its separator at the bottom (not an extra bar above the card), stays mounted while agents are active, and updates progress, elapsed time, and token counts in place without flicker. Each active writer row shows +N for its currently active, runtime-attributed depth-1 read helpers without changing global active/read/write counts; queued, completed, failed, stale, and historical helpers do not contribute. New progress phrases transition in one second by quickly fading/removing the old phrase and revealing the new phrase left-to-right, then resume the repeating one/two/three-dot animation. Completed reports arrive as messages/open reports and do not create report-ready or waiting-confirmation status rows."
+    },
+    {
+      "id": "ui.active-reader-writer-info",
+      "description": "Active reader and writer information remains available in the team activity card and Down-key live navigation, including elapsed/running time, current status/action, model, thinking level, and token count when available."
+    },
+    {
+      "id": "ui.agent-follow-navigation",
+      "description": "From an empty main editor, Down opens the first active agent in a full-window interactive live-follow view. Down moves to the next agent; Up moves to the previous agent and returns to main only from the first agent; Escape always returns to main. The view exposes transcript, thinking, progress, elapsed time, and tokens; pairs tool calls with their results in readable blocks; collapses large results with head/tail context and an expansion toggle; and provides an input for direct messages to the selected active agent. Pressing x stops the selected subagent while keeping the live view open."
+    },
+    {
+      "id": "helpers.requested-by-writer",
+      "description": "A read helper spawned for a writer records and displays requestedBy metadata as requested by <writer>."
+    },
+    {
+      "id": "writers.request-only-lead-spawns",
+      "description": "Nested delegation is off by default. Only explicitly opted-in depth-0 write-feature/write-critical agents receive restricted read-only spawn_agent/spawn_swarm_agents tools; they may request any canonical read tier and any count subject to global capacity. Read agents, depth-1 children, write-patch, and write-system remain denied. Children report to the requesting writer and cannot delegate."
+    },
+    {
+      "id": "messaging.push-on-completion",
+      "description": "Readers send completion messages to the lead; read helpers for writers send the full report to the requesting writer and a classified completion notice to the lead. Every newly unread agent message injects a deduplicated user-style follow-up into the lead prompt, even while the lead is busy, instead of relying on manual polling."
+    },
+    {
+      "id": "completion.remove-from-active-keep-history",
+      "description": "When a reader or writer is done it is removed from active UI/status, while its final report remains visible as a pushed report message in the lead session."
+    },
+    {
+      "id": "runtime.reload-disposes-background-handles",
+      "description": "Session shutdown clears the lead watchdog, teammate inbox poll/wake/title/initial-trigger timers, teammate inbox file watcher, and all active in-process agent sessions/heartbeats so extension reload cannot leave stale agents, model work, filesystem work, prompt wakes, or file descriptors active."
+    },
+    {
+      "id": "writers.tmux-closes-when-done",
+      "description": "Writer background tmux screens close only after the writer sends its final report and completes cleanup."
+    }
+  ]
+}

package/extensions/team/writer-screens.test.ts

@@ -0,0 +1,50 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createWriterScreenState, cycleWriterScreen, upsertWriterScreenTab } from "./writer-screens.js";
+import * as teams from "../../src/utils/teams.js";
+
+function ignorePersistedTeamConfig() {
+  vi.spyOn(teams, "readConfig").mockRejectedValue(new Error("not found"));
+}
+
+describe("writer screen cycling", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("cycles extension-owned writer tabs without reading the current tmux pane", async () => {
+    ignorePersistedTeamConfig();
+    const state = createWriterScreenState();
+    upsertWriterScreenTab(state, { teamName: "team", name: "writer-1", paneId: "%1", windowId: "@1", joinedAt: 1 });
+    upsertWriterScreenTab(state, { teamName: "team", name: "writer-2", paneId: "%2", windowId: "@2", joinedAt: 2 });
+
+    const terminal = {
+      getCurrentPaneId: vi.fn(() => "%lead"),
+      isAlive: vi.fn(() => true),
+      focusPane: vi.fn((_paneId: string) => true),
+    };
+
+    await expect(cycleWriterScreen("team", terminal, state)).resolves.toMatchObject({ ok: true, target: { name: "writer-1", paneId: "%1" } });
+    await expect(cycleWriterScreen("team", terminal, state)).resolves.toMatchObject({ ok: true, target: { name: "writer-2", paneId: "%2" } });
+
+    expect(terminal.focusPane.mock.calls.map(([paneId]) => paneId)).toEqual(["%1", "%2"]);
+    expect(terminal.getCurrentPaneId).not.toHaveBeenCalled();
+  });
+
+  it("prunes dead writer tabs before cycling", async () => {
+    ignorePersistedTeamConfig();
+    const state = createWriterScreenState();
+    upsertWriterScreenTab(state, { teamName: "team", name: "gone", paneId: "%gone" });
+    upsertWriterScreenTab(state, { teamName: "team", name: "writer", paneId: "%1" });
+
+    const terminal = {
+      isAlive: vi.fn((paneId: string) => paneId !== "%gone"),
+      focusPane: vi.fn((_paneId: string) => true),
+    };
+
+    const result = await cycleWriterScreen("team", terminal, state);
+
+    expect(result).toMatchObject({ ok: true, target: { name: "writer", paneId: "%1" } });
+    expect(state.activeWritersTabs.map(tab => tab.paneId)).toEqual(["%1"]);
+    expect(terminal.focusPane).toHaveBeenCalledWith("%1");
+  });
+});

package/extensions/team/writer-screens.ts

@@ -0,0 +1,156 @@
+import { Key } from "@mariozechner/pi-tui";
+import * as teams from "../../src/utils/teams";
+
+export interface ActiveWriterTab {
+  teamName: string;
+  name: string;
+  paneId: string;
+  windowId?: string;
+  joinedAt?: number;
+}
+
+export interface WriterScreenTarget extends ActiveWriterTab {
+  role: "write";
+}
+
+export interface WriterScreenCycleResult {
+  ok: boolean;
+  reason?: string;
+  target?: WriterScreenTarget;
+}
+
+export interface WriterScreenState {
+  activeWritersTabs: ActiveWriterTab[];
+  cursor: number;
+}
+
+export function createWriterScreenState(activeWritersTabs: ActiveWriterTab[] = []): WriterScreenState {
+  return { activeWritersTabs, cursor: -1 };
+}
+
+const defaultWriterScreenState = createWriterScreenState();
+
+function normalizeWriterTab(tab: ActiveWriterTab): ActiveWriterTab | null {
+  const teamName = tab.teamName?.trim();
+  const name = tab.name?.trim();
+  const paneId = tab.paneId?.trim();
+  if (!teamName || !name || !paneId) return null;
+  return {
+    ...tab,
+    teamName,
+    name,
+    paneId,
+    windowId: tab.windowId?.trim() || undefined,
+  };
+}
+
+function replaceActiveWriterTabs(state: WriterScreenState, nextTabs: ActiveWriterTab[]): void {
+  state.activeWritersTabs.splice(0, state.activeWritersTabs.length, ...nextTabs);
+  if (state.activeWritersTabs.length === 0) state.cursor = -1;
+  else if (state.cursor >= state.activeWritersTabs.length) state.cursor = state.activeWritersTabs.length - 1;
+}
+
+function isPaneAlive(terminal: any, paneId: string | undefined): paneId is string {
+  if (!paneId) return false;
+  if (!terminal?.isAlive) return true;
+  try {
+    return !!terminal.isAlive(paneId);
+  } catch {
+    return false;
+  }
+}
+
+async function readLiveWriterMemberNames(teamName: string): Promise<Set<string> | undefined> {
+  try {
+    const config = await teams.readConfig(teamName);
+    return new Set(
+      config.members
+        .filter(member => member.name !== "team-lead" && (member.role ?? "write") !== "read")
+        .map(member => member.name)
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+export function upsertWriterScreenTab(state: WriterScreenState, tab: ActiveWriterTab): void {
+  const normalized = normalizeWriterTab(tab);
+  if (!normalized) return;
+
+  const existingIndex = state.activeWritersTabs.findIndex((item) => (
+    item.teamName === normalized.teamName && (item.name === normalized.name || item.paneId === normalized.paneId)
+  ));
+
+  if (existingIndex >= 0) {
+    state.activeWritersTabs.splice(existingIndex, 1, normalized);
+    return;
+  }
+
+  state.activeWritersTabs.push(normalized);
+}
+
+export function removeWriterScreenTab(state: WriterScreenState, match: { teamName?: string; name?: string; paneId?: string }): void {
+  const nextTabs = state.activeWritersTabs.filter((tab) => {
+    if (match.teamName && tab.teamName !== match.teamName) return true;
+    if (match.name && tab.name !== match.name) return true;
+    if (match.paneId && tab.paneId !== match.paneId) return true;
+    return false;
+  });
+  replaceActiveWriterTabs(state, nextTabs);
+}
+
+export async function pruneWriterScreenTabs(teamName: string, terminal: any, state = defaultWriterScreenState): Promise<ActiveWriterTab[]> {
+  const liveWriterNames = await readLiveWriterMemberNames(teamName);
+  const nextTabs = state.activeWritersTabs.filter((tab) => {
+    if (tab.teamName !== teamName) return true;
+    if (liveWriterNames && !liveWriterNames.has(tab.name)) return false;
+    return isPaneAlive(terminal, tab.paneId);
+  });
+  replaceActiveWriterTabs(state, nextTabs);
+  return state.activeWritersTabs.filter(tab => tab.teamName === teamName);
+}
+
+export async function buildWriterScreenTargets(teamName: string, terminal: any, state = defaultWriterScreenState): Promise<WriterScreenTarget[]> {
+  const tabs = await pruneWriterScreenTabs(teamName, terminal, state);
+  return tabs.map(tab => ({ ...tab, role: "write" as const }));
+}
+
+export async function cycleWriterScreen(teamName: string | null | undefined, terminal: any, state = defaultWriterScreenState): Promise<WriterScreenCycleResult> {
+  if (!teamName) return { ok: false, reason: "No current team to cycle." };
+  if (!terminal?.focusPane) return { ok: false, reason: "The active terminal adapter cannot focus tmux screens." };
+
+  const targets = await buildWriterScreenTargets(teamName, terminal, state);
+  if (targets.length === 0) return { ok: false, reason: `No active writer screens for ${teamName}.` };
+
+  state.cursor = (state.cursor + 1) % targets.length;
+  const target = targets[state.cursor] ?? targets[0];
+  if (!target) return { ok: false, reason: `No focusable writer screens for ${teamName}.` };
+
+  const focused = terminal.focusPane(target.paneId);
+  if (!focused) {
+    removeWriterScreenTab(state, { teamName: target.teamName, name: target.name, paneId: target.paneId });
+    return { ok: false, reason: `Could not focus ${target.name} (${target.paneId}).`, target };
+  }
+
+  return { ok: true, target };
+}
+
+export function registerWriterScreenShortcut(pi: any, options: {
+  getTeamName(): string | null | undefined;
+  terminal: any;
+  state?: WriterScreenState;
+}): void {
+  pi.registerShortcut?.(Key.alt("tab"), {
+    description: "Cycle active writer-agent tmux screens",
+    handler: async (ctx: any) => {
+      const result = await cycleWriterScreen(options.getTeamName(), options.terminal, options.state ?? defaultWriterScreenState);
+      if (!result.ok) {
+        ctx.ui.notify(result.reason || "Could not cycle writer screens.", "warning");
+        return;
+      }
+
+      const target = result.target!;
+      ctx.ui.notify(`Switched to writer ${target.name} (${target.paneId}).`, "info");
+    },
+  });
+}