pi-extended-teams 2.1.16

package/src/utils/claims.ts

@@ -0,0 +1,169 @@
+/**
+ * File write-claim registry.
+ *
+ * Coordinates write intent across agents. Claims are advisory protocol state,
+ * not OS-level or tool-level sandbox enforcement. Cooperative write agents must
+ * claim before editing; the registry prevents two granted claims for the same
+ * path. Claims are held in a single lock-guarded `claims.json` per team so multi-file claims are
+ * atomic and all-or-nothing: if any requested path is held by another agent,
+ * none are granted.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { writeJsonAtomic } from "./atomic-json";
+import { withLock } from "./lock";
+import { claimsPath } from "./paths";
+
+export interface FileClaim {
+  agent: string;
+  path: string;
+  since: number;
+}
+
+/** Map of normalized file path -> claim. */
+type ClaimMap = Record<string, FileClaim>;
+
+export interface ClaimResult {
+  granted: string[];
+  conflicts: Array<{ path: string; heldBy: string }>;
+}
+
+/**
+ * Normalize a repository-relative path so "./a", "a", and "a/" map to the
+ * same claim key. Blank, absolute, and parent-traversal paths are rejected so a
+ * bad claim cannot accidentally reserve the repository root or escape it.
+ */
+export function normalizeClaimPath(p: string): string {
+  const raw = p.trim().replace(/\\/g, "/");
+  if (!raw) {
+    throw new Error("File claim path must not be empty.");
+  }
+  if (raw.startsWith("/") || /^[A-Za-z]:\//.test(raw)) {
+    throw new Error(`File claim path must be repository-relative: ${p}`);
+  }
+
+  const normalized = path.posix.normalize(raw).replace(/\/+$/, "");
+  if (!normalized || normalized === ".") {
+    throw new Error("File claim path must not refer to the repository root.");
+  }
+  if (normalized.split("/").includes("..")) {
+    throw new Error(`File claim path must not traverse outside the repository: ${p}`);
+  }
+
+  return normalized;
+}
+
+function readClaims(p: string): ClaimMap {
+  if (!fs.existsSync(p)) return {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(p, "utf-8"));
+    return parsed && typeof parsed === "object" ? (parsed as ClaimMap) : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeClaims(p: string, claims: ClaimMap): void {
+  writeJsonAtomic(p, claims);
+}
+
+/**
+ * Attempt to claim a set of paths for an agent.
+ *
+ * All-or-nothing: if any path is held by a *different* agent, nothing is
+ * granted and the conflicts are returned. Re-claiming a path the agent already
+ * holds is idempotent (refreshes `since`).
+ */
+export async function claimFiles(
+  teamName: string,
+  agent: string,
+  paths: string[],
+  now: number = Date.now()
+): Promise<ClaimResult> {
+  const p = claimsPath(teamName);
+  const normalized = Array.from(new Set(paths.map(normalizeClaimPath).filter(Boolean)));
+
+  return await withLock(p, async () => {
+    const claims = readClaims(p);
+    const conflicts: ClaimResult["conflicts"] = [];
+
+    for (const target of normalized) {
+      const existing = claims[target];
+      if (existing && existing.agent !== agent) {
+        conflicts.push({ path: target, heldBy: existing.agent });
+      }
+    }
+
+    if (conflicts.length > 0) {
+      return { granted: [], conflicts };
+    }
+
+    for (const target of normalized) {
+      claims[target] = { agent, path: target, since: claims[target]?.since ?? now };
+    }
+    writeClaims(p, claims);
+
+    return { granted: normalized, conflicts: [] };
+  });
+}
+
+/**
+ * Release specific paths, but only those held by this agent.
+ */
+export async function releaseFiles(
+  teamName: string,
+  agent: string,
+  paths: string[]
+): Promise<string[]> {
+  const p = claimsPath(teamName);
+  const normalized = new Set(paths.map(normalizeClaimPath).filter(Boolean));
+
+  return await withLock(p, async () => {
+    const claims = readClaims(p);
+    const released: string[] = [];
+
+    for (const target of normalized) {
+      if (claims[target]?.agent === agent) {
+        delete claims[target];
+        released.push(target);
+      }
+    }
+
+    if (released.length > 0) writeClaims(p, claims);
+    return released;
+  });
+}
+
+/**
+ * Release every claim held by an agent. Called on orderly exit and on
+ * watchdog-confirmed death.
+ */
+export async function releaseAllForAgent(teamName: string, agent: string): Promise<string[]> {
+  const p = claimsPath(teamName);
+
+  return await withLock(p, async () => {
+    const claims = readClaims(p);
+    const released: string[] = [];
+
+    for (const [target, claim] of Object.entries(claims)) {
+      if (claim.agent === agent) {
+        delete claims[target];
+        released.push(target);
+      }
+    }
+
+    if (released.length > 0) writeClaims(p, claims);
+    return released;
+  });
+}
+
+/**
+ * List all current claims.
+ */
+export async function listClaims(teamName: string): Promise<FileClaim[]> {
+  const p = claimsPath(teamName);
+  return await withLock(p, async () => {
+    return Object.values(readClaims(p));
+  });
+}

package/src/utils/hooks.test.ts

@@ -0,0 +1,75 @@
+import fs from "node:fs";
+import path from "node:path";
+import { runHook } from "./hooks";
+import { describe, it, expect, beforeAll, afterAll, vi } from "vitest";
+
+describe("runHook", () => {
+  const hooksDir = path.join(process.cwd(), ".pi", "team-hooks");
+
+  beforeAll(() => {
+    if (!fs.existsSync(hooksDir)) {
+      fs.mkdirSync(hooksDir, { recursive: true });
+    }
+  });
+
+  afterAll(() => {
+    // Optional: Clean up created scripts
+    const files = ["success_hook.sh", "fail_hook.sh"];
+    files.forEach(f => {
+      const p = path.join(hooksDir, f);
+      if (fs.existsSync(p)) fs.unlinkSync(p);
+    });
+  });
+
+  it("should return true if hook script does not exist", async () => {
+    const result = await runHook("test_team", "non_existent_hook", { data: "test" });
+    expect(result).toBe(true);
+  });
+
+  it("should return true if hook script succeeds", async () => {
+    const hookName = "success_hook";
+    const scriptPath = path.join(hooksDir, `${hookName}.sh`);
+    
+    // Create a simple script that exits with 0
+    fs.writeFileSync(scriptPath, "#!/bin/bash\nexit 0", { mode: 0o755 });
+
+    const result = await runHook("test_team", hookName, { data: "test" });
+    expect(result).toBe(true);
+  });
+
+  it("should return false if hook script fails", async () => {
+    const hookName = "fail_hook";
+    const scriptPath = path.join(hooksDir, `${hookName}.sh`);
+    
+    // Create a simple script that exits with 1
+    fs.writeFileSync(scriptPath, "#!/bin/bash\nexit 1", { mode: 0o755 });
+
+    // Mock console.error to avoid noise in test output
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    const result = await runHook("test_team", hookName, { data: "test" });
+    expect(result).toBe(false);
+
+    consoleSpy.mockRestore();
+  });
+
+  it("should pass the payload to the hook script", async () => {
+    const hookName = "payload_hook";
+    const scriptPath = path.join(hooksDir, `${hookName}.sh`);
+    const outputFile = path.join(hooksDir, "payload_output.txt");
+
+    // Create a script that writes its first argument to a file
+    fs.writeFileSync(scriptPath, `#!/bin/bash\necho "$1" > "${outputFile}"`, { mode: 0o755 });
+
+    const payload = { key: "value", "special'char": true };
+    const result = await runHook("test_team", hookName, payload);
+
+    expect(result).toBe(true);
+    const output = fs.readFileSync(outputFile, "utf-8").trim();
+    expect(JSON.parse(output)).toEqual(payload);
+
+    // Clean up
+    fs.unlinkSync(scriptPath);
+    if (fs.existsSync(outputFile)) fs.unlinkSync(outputFile);
+  });
+});

package/src/utils/hooks.ts

@@ -0,0 +1,35 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import fs from "node:fs";
+import path from "node:path";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Runs a hook script asynchronously if it exists.
+ * Hooks are located in .pi/team-hooks/{hookName}.sh relative to the CWD.
+ *
+ * @param teamName The name of the team.
+ * @param hookName The name of the hook to run (e.g., 'task_completed').
+ * @param payload The payload to pass to the hook script as the first argument.
+ * @returns true if the hook doesn't exist or executes successfully; false otherwise.
+ */
+export async function runHook(teamName: string, hookName: string, payload: any): Promise<boolean> {
+  const hookPath = path.join(process.cwd(), ".pi", "team-hooks", `${hookName}.sh`);
+
+  if (!fs.existsSync(hookPath)) {
+    return true;
+  }
+
+  try {
+    const payloadStr = JSON.stringify(payload);
+    // Use execFile: More secure (no shell interpolation) and asynchronous
+    await execFileAsync(hookPath, [payloadStr], {
+      env: { ...process.env, PI_TEAM: teamName },
+    });
+    return true;
+  } catch (error) {
+    console.error(`Hook ${hookName} failed:`, error);
+    return false;
+  }
+}

package/src/utils/lifecycle-tombstone.test.ts

@@ -0,0 +1,105 @@
+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 "./paths";
+import {
+  readLifecycleTombstone,
+  withLifecycleTombstoneLock,
+} from "./lifecycle-tombstone";
+
+let root = "";
+
+function tombstonePath(teamName: string, agentName: string): string {
+  return path.join(root, teamName, "lifecycle", "quarantine", `${agentName}.json`);
+}
+
+describe("lifecycle tombstone store", () => {
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "lifecycle-tombstone-"));
+    vi.spyOn(paths, "lifecycleTombstonePath").mockImplementation(tombstonePath);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it("atomically writes and reads a schema-v1 tombstone", async () => {
+    await withLifecycleTombstoneLock("team", "reader", async lock => {
+      const written = lock.occupy({
+        team: "team",
+        agent: "reader",
+        runId: "run-1",
+        role: "read",
+        reason: "quit",
+        extensionInstanceId: "extension-a",
+        now: 100,
+      });
+      expect(written).toMatchObject({
+        version: 1,
+        team: "team",
+        agent: "reader",
+        runId: "run-1",
+        phase: "closing",
+        timestamps: { createdAt: 100, updatedAt: 100 },
+      });
+    });
+
+    await expect(readLifecycleTombstone("team", "reader")).resolves.toMatchObject({
+      status: "occupied",
+      tombstone: { version: 1, runId: "run-1", extensionInstanceId: "extension-a" },
+    });
+    expect(fs.readdirSync(path.dirname(tombstonePath("team", "reader"))).filter(file => file.endsWith(".tmp"))).toEqual([]);
+  });
+
+  it("clears only a matching run and leaves a wrong-run request occupied", async () => {
+    await withLifecycleTombstoneLock("team", "reader", async lock => {
+      lock.occupy({
+        team: "team", agent: "reader", runId: "run-1", role: "read", reason: "quit", extensionInstanceId: "extension-a",
+      });
+      expect(lock.clearMatching("run-2")).toBe(false);
+    });
+    expect((await readLifecycleTombstone("team", "reader")).status).toBe("occupied");
+
+    await withLifecycleTombstoneLock("team", "reader", async lock => {
+      expect(lock.clearMatching("run-1")).toBe(true);
+    });
+    expect(await readLifecycleTombstone("team", "reader")).toEqual({ status: "absent" });
+  });
+
+  it("treats a tombstone unlinked mid-read as absent rather than corrupt", async () => {
+    const file = tombstonePath("team", "reader");
+    await withLifecycleTombstoneLock("team", "reader", async lock => {
+      lock.occupy({
+        team: "team", agent: "reader", runId: "run-1", role: "read", reason: "quit", extensionInstanceId: "extension-a",
+      });
+    });
+
+    // The owning run clears its fence between the existsSync probe and the open.
+    const realReadFileSync = fs.readFileSync;
+    vi.spyOn(fs, "readFileSync").mockImplementationOnce(((target: any, options: any) => {
+      if (target === file) fs.unlinkSync(file);
+      return realReadFileSync(target, options);
+    }) as typeof fs.readFileSync);
+
+    expect(await readLifecycleTombstone("team", "reader")).toEqual({ status: "absent" });
+  });
+
+  it("treats corrupt content as occupied and never overwrites or clears it", async () => {
+    const file = tombstonePath("team", "reader");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, "{ malformed");
+
+    await expect(readLifecycleTombstone("team", "reader")).resolves.toMatchObject({ status: "corrupt" });
+    await expect(withLifecycleTombstoneLock("team", "reader", async lock => {
+      lock.occupy({
+        team: "team", agent: "reader", runId: "run-1", role: "read", reason: "quit", extensionInstanceId: "extension-a",
+      });
+    })).rejects.toThrow("corrupt tombstone");
+    await withLifecycleTombstoneLock("team", "reader", async lock => {
+      expect(lock.clearMatching("run-1")).toBe(false);
+    });
+    expect(fs.readFileSync(file, "utf-8")).toBe("{ malformed");
+  });
+});

package/src/utils/lifecycle-tombstone.ts

@@ -0,0 +1,268 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { withLock } from "./lock";
+import { lifecycleTombstonePath } from "./paths";
+
+export const LIFECYCLE_TOMBSTONE_VERSION = 1 as const;
+
+export type LifecycleTombstonePhase =
+  | "closing"
+  | "persistence_closed"
+  | "timed_out"
+  | "finalizing"
+  | "cleanup_failed";
+
+export interface LifecycleTombstone {
+  version: typeof LIFECYCLE_TOMBSTONE_VERSION;
+  team: string;
+  agent: string;
+  runId: string;
+  role: "read" | "write";
+  reason: string;
+  phase: LifecycleTombstonePhase;
+  ownerPid: number;
+  extensionInstanceId: string;
+  timestamps: {
+    createdAt: number;
+    updatedAt: number;
+  };
+  timeout?: {
+    afterMs: number;
+    at: number;
+  };
+  error?: string;
+}
+
+export type LifecycleTombstoneReadResult =
+  | { status: "absent" }
+  | { status: "occupied"; tombstone: LifecycleTombstone }
+  | { status: "corrupt"; error: string };
+
+export interface CreateLifecycleTombstoneInput {
+  team: string;
+  agent: string;
+  runId: string;
+  role: "read" | "write";
+  reason: string;
+  phase?: LifecycleTombstonePhase;
+  ownerPid?: number;
+  extensionInstanceId: string;
+  now?: number;
+}
+
+export interface LifecycleTombstoneLock {
+  path: string;
+  read(): LifecycleTombstoneReadResult;
+  occupy(input: CreateLifecycleTombstoneInput): LifecycleTombstone;
+  updateMatching(runId: string, updates: Partial<Pick<LifecycleTombstone, "phase" | "timeout" | "error">>): LifecycleTombstone | null;
+  clearMatching(runId: string): boolean;
+}
+
+const clearListeners = new Set<(teamName: string, agentName: string, runId: string) => void>();
+
+export function generateLifecycleRunId(): string {
+  return crypto.randomUUID();
+}
+
+export function generateExtensionInstanceId(): string {
+  return crypto.randomUUID();
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function isLifecycleTombstone(value: unknown, teamName: string, agentName: string): value is LifecycleTombstone {
+  if (!value || typeof value !== "object") return false;
+  const item = value as Partial<LifecycleTombstone>;
+  return item.version === LIFECYCLE_TOMBSTONE_VERSION
+    && item.team === teamName
+    && item.agent === agentName
+    && isNonEmptyString(item.runId)
+    && (item.role === "read" || item.role === "write")
+    && isNonEmptyString(item.reason)
+    && ["closing", "persistence_closed", "timed_out", "finalizing", "cleanup_failed"].includes(String(item.phase))
+    && typeof item.ownerPid === "number"
+    && isNonEmptyString(item.extensionInstanceId)
+    && !!item.timestamps
+    && typeof item.timestamps.createdAt === "number"
+    && typeof item.timestamps.updatedAt === "number"
+    && (item.timeout === undefined || (
+      typeof item.timeout.afterMs === "number" && typeof item.timeout.at === "number"
+    ))
+    && (item.error === undefined || typeof item.error === "string");
+}
+
+function readUnlocked(teamName: string, agentName: string, tombstonePath: string): LifecycleTombstoneReadResult {
+  if (!fs.existsSync(tombstonePath)) return { status: "absent" };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(tombstonePath, "utf-8"));
+    if (!isLifecycleTombstone(parsed, teamName, agentName)) {
+      return { status: "corrupt", error: "Lifecycle tombstone schema or identity is invalid." };
+    }
+    return { status: "occupied", tombstone: parsed };
+  } catch (error) {
+    // clearMatching may unlink between the existence probe and this read.
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { status: "absent" };
+    return { status: "corrupt", error: `Lifecycle tombstone could not be read: ${errorText(error)}` };
+  }
+}
+
+function atomicWriteJson(filePath: string, value: unknown): void {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tempPath = path.join(dir, `.${path.basename(filePath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  let descriptor: number | undefined;
+  try {
+    descriptor = fs.openSync(tempPath, "wx", 0o600);
+    fs.writeFileSync(descriptor, JSON.stringify(value, null, 2));
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    fs.renameSync(tempPath, filePath);
+    try {
+      const dirDescriptor = fs.openSync(dir, "r");
+      try { fs.fsyncSync(dirDescriptor); } finally { fs.closeSync(dirDescriptor); }
+    } catch {
+      // Directory fsync is not supported on every platform/filesystem.
+    }
+  } catch (error) {
+    if (descriptor !== undefined) {
+      try { fs.closeSync(descriptor); } catch { /* preserve original error */ }
+    }
+    try { if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath); } catch { /* preserve original error */ }
+    throw error;
+  }
+}
+
+function occupiedError(teamName: string, agentName: string, result: Exclude<LifecycleTombstoneReadResult, { status: "absent" }>): Error {
+  if (result.status === "corrupt") {
+    return new Error(`Agent ${agentName} in ${teamName} is lifecycle-quarantined by a corrupt tombstone: ${result.error}`);
+  }
+  return new Error(
+    `Agent ${agentName} in ${teamName} is lifecycle-quarantined for run ${result.tombstone.runId} (${result.tombstone.phase}).`
+  );
+}
+
+export function assertLifecycleTombstoneAbsent(
+  teamName: string,
+  agentName: string,
+  result: LifecycleTombstoneReadResult
+): asserts result is { status: "absent" } {
+  if (result.status !== "absent") throw occupiedError(teamName, agentName, result);
+}
+
+export async function withLifecycleTombstoneLock<T>(
+  teamName: string,
+  agentName: string,
+  fn: (lock: LifecycleTombstoneLock) => Promise<T>
+): Promise<T> {
+  const tombstonePath = lifecycleTombstonePath(teamName, agentName);
+  let clearedRunId: string | undefined;
+  const result = await withLock(tombstonePath, async () => {
+    const lock: LifecycleTombstoneLock = {
+      path: tombstonePath,
+      read: () => readUnlocked(teamName, agentName, tombstonePath),
+      occupy: (input) => {
+        const current = readUnlocked(teamName, agentName, tombstonePath);
+        if (current.status === "corrupt") throw occupiedError(teamName, agentName, current);
+        if (current.status === "occupied") {
+          if (current.tombstone.runId !== input.runId) throw occupiedError(teamName, agentName, current);
+          return current.tombstone;
+        }
+        const now = input.now ?? Date.now();
+        const tombstone: LifecycleTombstone = {
+          version: LIFECYCLE_TOMBSTONE_VERSION,
+          team: input.team,
+          agent: input.agent,
+          runId: input.runId,
+          role: input.role,
+          reason: input.reason,
+          phase: input.phase ?? "closing",
+          ownerPid: input.ownerPid ?? process.pid,
+          extensionInstanceId: input.extensionInstanceId,
+          timestamps: { createdAt: now, updatedAt: now },
+        };
+        if (!isLifecycleTombstone(tombstone, teamName, agentName)) {
+          throw new Error(`Refusing to write invalid lifecycle tombstone for ${agentName} in ${teamName}.`);
+        }
+        atomicWriteJson(tombstonePath, tombstone);
+        return tombstone;
+      },
+      updateMatching: (runId, updates) => {
+        const current = readUnlocked(teamName, agentName, tombstonePath);
+        if (current.status !== "occupied" || current.tombstone.runId !== runId) return null;
+        const next: LifecycleTombstone = {
+          ...current.tombstone,
+          ...updates,
+          timestamps: { ...current.tombstone.timestamps, updatedAt: Date.now() },
+        };
+        atomicWriteJson(tombstonePath, next);
+        return next;
+      },
+      clearMatching: (runId) => {
+        const current = readUnlocked(teamName, agentName, tombstonePath);
+        if (current.status !== "occupied" || current.tombstone.runId !== runId) return false;
+        fs.unlinkSync(tombstonePath);
+        clearedRunId = runId;
+        return true;
+      },
+    };
+    return fn(lock);
+  });
+  if (clearedRunId) {
+    for (const listener of clearListeners) {
+      try { listener(teamName, agentName, clearedRunId); } catch { /* observers are best-effort */ }
+    }
+  }
+  return result;
+}
+
+export function readLifecycleTombstoneSnapshot(teamName: string, agentName: string): LifecycleTombstoneReadResult {
+  const tombstonePath = lifecycleTombstonePath(teamName, agentName);
+  return readUnlocked(teamName, agentName, tombstonePath);
+}
+
+export async function readLifecycleTombstone(teamName: string, agentName: string): Promise<LifecycleTombstoneReadResult> {
+  const tombstonePath = lifecycleTombstonePath(teamName, agentName);
+  // Existing/corrupt content is already a fail-closed answer and must be
+  // observable even while its owner holds the exact lock for slow cleanup.
+  if (fs.existsSync(tombstonePath)) return readUnlocked(teamName, agentName, tombstonePath);
+  // Absence needs the lock and a second read so admission cannot race creation.
+  return withLifecycleTombstoneLock(teamName, agentName, async lock => lock.read());
+}
+
+export async function listLifecycleTombstones(
+  teamName: string
+): Promise<Array<{ agentName: string; result: Exclude<LifecycleTombstoneReadResult, { status: "absent" }> }>> {
+  const quarantineDir = path.dirname(lifecycleTombstonePath(teamName, "placeholder"));
+  if (!fs.existsSync(quarantineDir)) return [];
+  const entries: Array<{ agentName: string; result: Exclude<LifecycleTombstoneReadResult, { status: "absent" }> }> = [];
+  for (const file of fs.readdirSync(quarantineDir).filter(item => item.endsWith(".json")).sort()) {
+    const agentName = file.slice(0, -".json".length);
+    const result = await readLifecycleTombstone(teamName, agentName);
+    if (result.status !== "absent") entries.push({ agentName, result });
+  }
+  return entries;
+}
+
+export async function updateMatchingLifecycleTombstone(
+  teamName: string,
+  agentName: string,
+  runId: string,
+  updates: Partial<Pick<LifecycleTombstone, "phase" | "timeout" | "error">>
+): Promise<LifecycleTombstone | null> {
+  return withLifecycleTombstoneLock(teamName, agentName, async lock => lock.updateMatching(runId, updates));
+}
+
+export function onLifecycleTombstoneCleared(
+  listener: (teamName: string, agentName: string, runId: string) => void
+): () => void {
+  clearListeners.add(listener);
+  return () => clearListeners.delete(listener);
+}