@wrongstack/core 0.286.0 → 0.287.0

package/dist/coordination/index.js

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 // src/utils/atomic-write.ts
 import { randomBytes } from "node:crypto";
 import * as fs from "node:fs/promises";
+import { watch as watchDir } from "node:fs";
 import * as path from "node:path";
 async function atomicWrite(targetPath, content, opts = {}) {
   const dir = path.dirname(targetPath);
@@ -71,7 +72,7 @@ async function withFileLock(targetPath, fn, opts = {}) {
         await fs.mkdir(dir, { recursive: true });
         continue;
       }
-      if (code !== "EEXIST") throw err;
+      if (code !== "EEXIST" && code !== "EPERM") throw err;
       try {
         const stat9 = await fs.stat(lockPath);
         if (Date.now() - stat9.mtimeMs > staleMs) {
@@ -81,7 +82,8 @@ async function withFileLock(targetPath, fn, opts = {}) {
       } catch {
         continue;
       }
-      if (Date.now() - started >= timeoutMs) {
+      const elapsed = Date.now() - started;
+      if (elapsed >= timeoutMs) {
         throw new FsError({
           message: `Timed out waiting for file lock: ${targetPath}`,
           code: "FS_ATOMIC_WRITE_FAILED",
@@ -89,7 +91,7 @@ async function withFileLock(targetPath, fn, opts = {}) {
           context: { timeoutMs }
         });
       }
-      await new Promise((resolve9) => setTimeout(resolve9, 25));
+      await waitForLockRelease(lockPath, timeoutMs - elapsed);
     }
   }
   try {
@@ -105,6 +107,50 @@ async function withFileLock(targetPath, fn, opts = {}) {
     }
   }
 }
+async function waitForLockRelease(lockPath, remainingMs) {
+  const parentDir = path.dirname(lockPath);
+  const lockName = path.basename(lockPath);
+  const intervalMs = Math.min(remainingMs, 100);
+  return new Promise((resolve9) => {
+    let settled = false;
+    let watcher = null;
+    const timer = setTimeout(() => {
+      settled = true;
+      watcher?.close();
+      resolve9();
+    }, intervalMs);
+    try {
+      watcher = watchDir(parentDir, (eventType, filename) => {
+        if (settled) return;
+        if (filename === lockName && (eventType === "rename" || eventType === "change")) {
+          settled = true;
+          clearTimeout(timer);
+          watcher?.close();
+          resolve9();
+        }
+      });
+    } catch {
+      clearTimeout(timer);
+      if (!settled) {
+        settled = true;
+        setTimeout(resolve9, Math.min(remainingMs, 25));
+      }
+      return;
+    }
+    fs.access(lockPath).then(
+      () => {
+      },
+      () => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timer);
+          watcher?.close();
+          resolve9();
+        }
+      }
+    );
+  });
+}
 var TRANSIENT_RENAME_CODES = /* @__PURE__ */ new Set(["EPERM", "EBUSY", "EACCES", "ENOTEMPTY"]);
 async function renameWithRetry(from, to) {
   if (process.platform !== "win32") {
@@ -587,11 +633,31 @@ function truncate(s, max) {
 
 // src/utils/wstack-paths.ts
 import { createHash } from "node:crypto";
+import * as fs2 from "node:fs";
 import * as os from "node:os";
 import * as path3 from "node:path";
+function canonicalProjectRoot(absRoot) {
+  const checkoutRoot = path3.resolve(absRoot);
+  const dotGit = path3.join(checkoutRoot, ".git");
+  try {
+    if (!fs2.statSync(dotGit).isFile()) return checkoutRoot;
+    const gitDirLine = fs2.readFileSync(dotGit, "utf8").trim();
+    const match = /^gitdir:\s*(.+)$/i.exec(gitDirLine);
+    if (!match?.[1]) return checkoutRoot;
+    const gitDir = path3.resolve(checkoutRoot, match[1].trim());
+    const commonDirFile = path3.join(gitDir, "commondir");
+    if (!fs2.statSync(commonDirFile).isFile()) return checkoutRoot;
+    const commonDir = path3.resolve(gitDir, fs2.readFileSync(commonDirFile, "utf8").trim());
+    if (path3.basename(commonDir).toLowerCase() !== ".git") return checkoutRoot;
+    return path3.dirname(commonDir);
+  } catch {
+    return checkoutRoot;
+  }
+}
 function projectSlug(absRoot) {
-  const base = slugify(path3.basename(absRoot));
-  const hash = createHash("sha256").update(path3.resolve(absRoot)).digest("hex").slice(0, 6);
+  const identityRoot = canonicalProjectRoot(absRoot);
+  const base = slugify(path3.basename(identityRoot));
+  const hash = createHash("sha256").update(identityRoot).digest("hex").slice(0, 6);
   return `${base}-${hash}`;
 }
 function slugify(name) {
@@ -1827,7 +1893,7 @@ var TOOLS = {
 };
 
 // src/coordination/agents/agent-prompts.ts
-import { readFileSync, statSync } from "node:fs";
+import { readFileSync as readFileSync2, statSync as statSync2 } from "node:fs";
 import * as os2 from "node:os";
 import * as path4 from "node:path";
 import { fileURLToPath } from "node:url";
@@ -1842,7 +1908,7 @@ function agentPrompt(id) {
   let resolved = "";
   for (const dir of agentPromptDirCandidates(envDir)) {
     try {
-      resolved = readFileSync(path4.join(dir, fileName), "utf8").trimEnd();
+      resolved = readFileSync2(path4.join(dir, fileName), "utf8").trimEnd();
       break;
     } catch {
     }
@@ -1872,7 +1938,7 @@ function agentPromptDirCandidates(envDir) {
 }
 function isDirectory(candidate) {
   try {
-    return statSync(candidate).isDirectory();
+    return statSync2(candidate).isDirectory();
   } catch {
     return false;
   }
@@ -3624,7 +3690,7 @@ function formatHumanPrompt(request) {
 
 // src/coordination/brain-ledger.ts
 import { appendFile, mkdir as mkdir2, readFile } from "node:fs/promises";
-import { dirname as dirname3 } from "node:path";
+import { dirname as dirname4 } from "node:path";
 var QUESTION_MAX = 200;
 var DETAIL_MAX = 240;
 var truncate2 = (s, max) => s === void 0 ? void 0 : s.length > max ? `${s.slice(0, max - 1)}\u2026` : s;
@@ -3876,7 +3942,7 @@ var BrainDecisionLedger = class {
   append(entry) {
     this.writeChain = this.writeChain.then(async () => {
       if (!this.dirReady) {
-        await mkdir2(dirname3(this.opts.filePath), { recursive: true });
+        await mkdir2(dirname4(this.opts.filePath), { recursive: true });
         this.dirReady = true;
       }
       await appendFile(this.opts.filePath, `${JSON.stringify(entry)}
@@ -3952,9 +4018,16 @@ var BrainMonitor = class {
   fileChurnThreshold;
   fileChurnWindowMs;
   cooldownMs;
+  /** Resolve the leader's own session id for event filtering. */
+  resolveLeaderSessionId() {
+    const id = this.opts.leaderSessionId;
+    return typeof id === "function" ? id() : id;
+  }
   start() {
     this.unsubscribers.push(
       this.opts.events.on("tool.executed", (e) => {
+        const leaderSid = this.resolveLeaderSessionId();
+        if (leaderSid && e.sessionId && e.sessionId !== leaderSid) return;
         this.lastProgressAt = Date.now();
         this.trackFileChurn(e.name, e.ok, e.input);
         if (e.ok) {
@@ -3978,17 +4051,25 @@ var BrainMonitor = class {
     );
     if (this.stallMs > 0) {
       this.unsubscribers.push(
-        this.opts.events.on("agent.run.started", () => {
+        this.opts.events.on("agent.run.started", (e) => {
+          const lsid = this.resolveLeaderSessionId();
+          if (lsid && e.sessionId && e.sessionId !== lsid) return;
           this.activeRuns += 1;
           this.lastProgressAt = Date.now();
         }),
-        this.opts.events.on("agent.run.completed", () => {
+        this.opts.events.on("agent.run.completed", (e) => {
+          const lsid = this.resolveLeaderSessionId();
+          if (lsid && e.sessionId && e.sessionId !== lsid) return;
           this.activeRuns = Math.max(0, this.activeRuns - 1);
         }),
-        this.opts.events.on("agent.run.error", () => {
+        this.opts.events.on("agent.run.error", (e) => {
+          const lsid = this.resolveLeaderSessionId();
+          if (lsid && e.sessionId && e.sessionId !== lsid) return;
           this.activeRuns = Math.max(0, this.activeRuns - 1);
         }),
-        this.opts.events.on("iteration.started", () => {
+        this.opts.events.on("iteration.started", (e) => {
+          const lsid = this.resolveLeaderSessionId();
+          if (lsid && e.sessionId && e.sessionId !== lsid) return;
           this.lastProgressAt = Date.now();
         })
       );
@@ -4010,6 +4091,8 @@ var BrainMonitor = class {
     }
     this.unsubscribers.push(
       this.opts.events.on("error", (e) => {
+        const lsid = this.resolveLeaderSessionId();
+        if (lsid && e.sessionId && e.sessionId !== lsid) return;
         const now = Date.now();
         this.errorTimestamps.push(now);
         this.errorTimestamps = this.errorTimestamps.filter(
@@ -4895,19 +4978,19 @@ var FLEET_ROSTER = {
     ALL_AGENT_DEFINITIONS.map((d) => [d.config.role, d.config])
   )
 };
-var DEFAULT_IDLE_TIMEOUT_MS = 15 * 60 * 1e3;
+var DEFAULT_IDLE_TIMEOUT_MS = 10 * 60 * 1e3;
 var FLEET_ROSTER_BUDGETS = {
-  "audit-log": { timeoutMs: 7.5 * 60 * 60 * 1e3, maxIterations: 5e3, maxToolCalls: 15e3 },
-  "bug-hunter": { timeoutMs: 10 * 60 * 60 * 1e3, maxIterations: 8e3, maxToolCalls: 2e4 },
-  "refactor-planner": { timeoutMs: 7.5 * 60 * 60 * 1e3, maxIterations: 6e3, maxToolCalls: 18e3 },
-  "security-scanner": { timeoutMs: 10 * 60 * 60 * 1e3, maxIterations: 8e3, maxToolCalls: 2e4 },
-  critic: { timeoutMs: 5 * 60 * 60 * 1e3, maxIterations: 4e3, maxToolCalls: 12e3 },
+  "audit-log": { timeoutMs: 3 * 60 * 60 * 1e3, maxIterations: 2500, maxToolCalls: 7500 },
+  "bug-hunter": { timeoutMs: 5 * 60 * 60 * 1e3, maxIterations: 4e3, maxToolCalls: 1e4 },
+  "refactor-planner": { timeoutMs: 4 * 60 * 60 * 1e3, maxIterations: 3e3, maxToolCalls: 9e3 },
+  "security-scanner": { timeoutMs: 5 * 60 * 60 * 1e3, maxIterations: 4e3, maxToolCalls: 1e4 },
+  critic: { timeoutMs: 3 * 60 * 60 * 1e3, maxIterations: 2e3, maxToolCalls: 6e3 },
   "shadow-agent": {
     idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
-    maxIterations: 2e3,
-    maxToolCalls: 5e3,
-    maxTokens: 6e4,
-    maxCostUsd: 1
+    maxIterations: 1e3,
+    maxToolCalls: 2500,
+    maxTokens: 3e4,
+    maxCostUsd: 0.5
   },
   ...Object.fromEntries(
     ALL_AGENT_DEFINITIONS.map((d) => [d.config.role, d.budget])
@@ -4915,8 +4998,8 @@ var FLEET_ROSTER_BUDGETS = {
 };
 var GENERIC_SUBAGENT_BUDGET = {
   idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
-  maxIterations: 5e3,
-  maxToolCalls: 15e3
+  maxIterations: 2500,
+  maxToolCalls: 7500
 };
 function applyRosterBudget(cfg) {
   const roleBudget = cfg.role ? FLEET_ROSTER_BUDGETS[cfg.role] : void 0;
@@ -4972,72 +5055,71 @@ function createDelegateTool(opts) {
     properties: {
       task: {
         type: "string",
-        description: "What the subagent should do \u2014 natural language, complete sentence(s). The subagent has its own tool slice, its own LLM call, and returns when its task is done."
+        description: "What the subagent should do \u2014 natural language, complete sentence(s)."
       },
       role: {
         type: "string",
-        description: rosterIds.length > 0 ? `Roster role (preferred). One of: ${rosterIds.join(", ")}. Picks a pre-tuned config (prompt, budgets, tools) for that role.` : "No roster is configured \u2014 pass `name` instead.",
-        enum: rosterIds.length > 0 ? rosterIds : void 0
+        description: rosterIds.length > 0 ? "Roster role id. Common: bug-hunter, security-scanner, refactor-planner, critic, audit-log, executor, shadow-agent, architect." : "No roster configured \u2014 pass `name` instead."
       },
       name: {
         type: "string",
-        description: "Display name for free-form subagents (not using a roster role). The subagent gets a large default budget (3h, 5000 iter, 15000 tool calls). Required when `role` is omitted."
+        description: "Display name for free-form subagents (no roster role). Required when `role` is omitted."
       },
       provider: {
         type: "string",
-        description: 'Provider id (e.g. "anthropic", "openai"). Defaults to the host provider when omitted.'
+        description: 'Provider id (e.g. "anthropic", "openai"). Defaults to host provider.'
       },
       model: {
         type: "string",
-        description: "Model id within the provider. Defaults to the host model when omitted."
+        description: "Model id within the provider. Defaults to host model."
       },
       systemPromptOverride: {
         type: "string",
-        description: "Optional extra prompt text appended to the role baseline."
+        description: "Extra prompt text appended to the role baseline."
       },
       timeoutMs: {
         type: "number",
         minimum: 1,
-        description: `Wall-clock budget for this delegate in milliseconds. No hard cap \u2014 set as high as the task realistically needs (a monorepo audit can take hours, a single-file lint takes seconds). Default ${Math.round(defaultTimeoutMs / 1e3 / 60)} minutes.`
+        description: `Wall-clock budget in ms (default ${Math.round(defaultTimeoutMs / 1e3 / 60)} min). No hard cap \u2014 set as high as the task needs.`
       },
       maxIterations: {
         type: "number",
         minimum: 1,
-        description: "Maximum LLM iterations the subagent may take. Unset = use the role/coordinator default. Raise this for tasks with many tool-think-tool cycles (deep code analysis, multi-file refactors)."
+        description: "Maximum LLM iterations. Unset = role default. Raise for deep multi-step tasks."
       },
       maxToolCalls: {
         type: "number",
         minimum: 1,
-        description: "Maximum number of tool invocations the subagent may make. Unset = use the role/coordinator default. Raise this for tasks that touch many files (large grep + read + report)."
+        description: "Maximum tool invocations. Unset = role default. Raise for file-heavy tasks."
       },
       idleTimeoutMs: {
         type: "number",
         minimum: 1,
-        description: "Idle timeout in ms: reap the subagent after this long with no activity. Resets on every iteration/tool call. Unset = use the role/coordinator default."
+        description: "Idle timeout in ms. Resets on activity. Unset = role default."
       },
       maxTokens: {
         type: "number",
         minimum: 1,
-        description: "Maximum total tokens (input + output) the subagent may use. Unset = use the role/coordinator default."
+        description: "Max total tokens (input+output). Unset = role default."
       },
       maxCostUsd: {
         type: "number",
         minimum: 0,
-        description: "Maximum estimated USD cost the subagent may incur. Unset = use the role/coordinator default."
+        description: "Max estimated USD cost. Unset = role default."
       },
       maxHandoffs: {
         type: "number",
         minimum: 0,
         maximum: 8,
-        description: "Maximum fresh-worker continuations after partial completion or budget exhaustion. Default 1; set 0 to disable. Each successor receives the prior structured/partial report and is told to continue only the remaining work."
+        description: "Max fresh-worker continuations after budget exhaustion. Default 1. Each gets the prior partial report."
       }
     },
     required: ["task"]
   };
   return {
     name: "delegate",
-    description: "Hand a discrete piece of work to a dedicated subagent and wait for its result. The subagent has its own context, its own LLM call, and a generous, auto-extending budget. If it reports explicit partial completion or still exhausts a recoverable budget, delegate can continue the remaining work with a fresh subagent (bounded by `maxHandoffs`, default 1). Workers may ask the leader to spawn a parallel helper through the mailbox, but cannot recursively spawn agents themselves. Use specialized roster roles when possible; otherwise pass `name` + `task`. Call multiple delegates in parallel through the provider's parallel-tool-call surface for independent work.",
-    usageHint: "Set `task` to a complete instruction. Either pick `role` from the roster or pass `name` for a free-form coding agent. Defaults are intentionally generous; override `timeoutMs`, `maxIterations`, `maxToolCalls`, or `maxHandoffs` only when the task warrants it. Returns the final TaskResult plus a `handoffs` history when fresh workers continued partial work. Requires Director mode in normal CLI sessions.",
+    description: "Hand a piece of work to a subagent and wait for its result. Has own context, LLM call, auto-extending budget. Can continue remaining work with a fresh subagent on partial completion (maxHandoffs, default 1). Workers cannot recursively spawn. Use roster roles when possible; otherwise pass `name` + `task`.",
+    usageHint: "Set `task` to a complete instruction. Pick `role` from roster or pass `name` for free-form. Override `timeoutMs`/`maxIterations`/`maxToolCalls` only when needed.",
     permission: "auto",
     mutating: false,
     managesOwnTimeout: true,
@@ -5064,10 +5146,9 @@ function createDelegateTool(opts) {
           director = await opts.host.promoteToDirector();
         }
         if (!director) {
-          const reason = opts.host.getPromotionBlockReason?.();
           return {
             ok: false,
-            error: reason ?? "Director could not be activated \u2014 multi-agent host already running in legacy non-director mode. Restart with `--director` for fleet support."
+            error: "Director could not be activated \u2014 fleet orchestration is unavailable."
           };
         }
         const timeoutMs = i.timeoutMs ?? defaultTimeoutMs;
@@ -5938,8 +6019,86 @@ var FleetContextOverflowError = class extends Error {
   }
 };
 
+// src/coordination/director/director-collab.ts
+var DirectorCollabController = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  deps;
+  /** Active collab sessions tracked by sessionId (see spawn).
+   *  The tuple holds the session and its Director-registered listener unsubs.
+   *  Calling the unsubs on cancel/premature-cleanup prevents listener accumulation
+   *  on CollabSession (EventEmitter) across many spawn() calls. */
+  activeSessions = /* @__PURE__ */ new Map();
+  async spawn(options) {
+    const session = new CollabSession(this.deps.director, this.deps.fleet, {
+      ...options,
+      onBudgetWarning: (alert) => {
+        return options.onBudgetWarning?.(alert) ?? "ignore";
+      }
+    });
+    const doneHandler = () => this.activeSessions.delete(session.sessionId);
+    const errorHandler = () => this.activeSessions.delete(session.sessionId);
+    session.on("session.done", doneHandler);
+    session.on("session.error", errorHandler);
+    const unsubs = [
+      () => session.off("session.done", doneHandler),
+      () => session.off("session.error", errorHandler)
+    ];
+    this.activeSessions.set(session.sessionId, { session, unsubs });
+    return session.start();
+  }
+  cancel(sessionId, reason = "Director cancelled") {
+    const entry = this.activeSessions.get(sessionId);
+    if (!entry || entry.session.isCancelled()) return;
+    for (const unsub of entry.unsubs) unsub();
+    entry.session.cancel(reason);
+    for (const [_role, subagentId] of entry.session.getSubagentIds()) {
+      this.deps.coordinator.stop(subagentId).catch((err) => {
+        this.deps.logger?.debug(
+          `stop subagent ${subagentId} failed (may have already completed)`,
+          {
+            subagentId,
+            err: err instanceof Error ? err.message : String(err)
+          }
+        );
+      });
+    }
+  }
+  onAlert(handler) {
+    return this.deps.fleet.filter("collab.warning", (e) => {
+      handler(e.payload);
+    });
+  }
+  activeSessionIds() {
+    return Array.from(this.activeSessions.keys());
+  }
+};
+
+// src/coordination/director/director-btw-notes.ts
+var DirectorBtwNotes = class {
+  notes = [];
+  /** Stash a note (trimmed; empty ignored). Returns the pending count. Cap 20. */
+  add(note) {
+    const trimmed = note.trim();
+    if (!trimmed) return this.notes.length;
+    this.notes = [...this.notes, trimmed].slice(-20);
+    return this.notes.length;
+  }
+  /** Read and clear all pending notes, in FIFO order (empty array when none). */
+  drain() {
+    const notes = this.notes;
+    this.notes = [];
+    return notes;
+  }
+  /** Peek at pending notes without consuming them. */
+  peek() {
+    return [...this.notes];
+  }
+};
+
 // src/utils/instruction-file.ts
-import { readFileSync as readFileSync2, statSync as statSync2 } from "node:fs";
+import { readFileSync as readFileSync3, statSync as statSync3 } from "node:fs";
 import * as path6 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 var textCache = /* @__PURE__ */ new Map();
@@ -5950,7 +6109,7 @@ function readBundledInstructionText(relativePath) {
   let resolved = "";
   for (const root of instructionRootCandidates()) {
     try {
-      resolved = readFileSync2(path6.join(root, relativePath), "utf8").trimEnd();
+      resolved = readFileSync3(path6.join(root, relativePath), "utf8").trimEnd();
       break;
     } catch {
     }
@@ -5977,7 +6136,7 @@ function instructionRootCandidates() {
 }
 function isDirectory2(candidate) {
   try {
-    return statSync2(candidate).isDirectory();
+    return statSync3(candidate).isDirectory();
   } catch {
     return false;
   }
@@ -9485,13 +9644,12 @@ var Director = class _Director {
    * coordinator from keeping workers alive for tasks that will never arrive.
    */
   workCompleteFlag = false;
-  /** Pending /btw notes stashed by the leader agent (see setLeaderBtwNote). */
-  _leaderBtwNotes = [];
-  /** Active collab sessions tracked by sessionId (see spawnCollab).
-   *  The tuple holds the session and its Director-registered listener unsubs.
-   *  Calling the unsubs on cancel/premature-cleanup prevents listener accumulation
-   *  on CollabSession (EventEmitter) across many spawnCollab() calls. */
-  _activeCollabSessions = /* @__PURE__ */ new Map();
+  /** Pending /btw notes stashed by the leader agent (see setLeaderBtwNote).
+   *  Owned by DirectorBtwNotes (R4); the public btw methods delegate to it. */
+  btwNotes = new DirectorBtwNotes();
+  /** Owns active collab-debug sessions (spawn/cancel/alert/list). Extracted
+   *  from Director in R4; the public collab methods below delegate to it. */
+  collab;
   /** Prevents large `ask_subagent` answers from bloating the leader's context window. */
   largeAnswerStore;
   constructor(opts) {
@@ -9568,92 +9726,103 @@ var Director = class _Director {
     );
     this.coordinator.setFleetBus(this.fleet);
     this.fleetManager?.setCoordinator(this.coordinator);
-    this.taskCompletedListener = (payload) => {
-      const r = payload.result;
-      const internalTask = this.internalTaskIds.delete(r.taskId);
-      if (!internalTask) {
-        this.completed.set(r.taskId, r);
-        if (this.completed.size > _Director.MAX_COMPLETED) {
-          const toDelete = this.completed.size - _Director.MAX_COMPLETED;
-          const keys = [...this.completed.keys()].slice(0, toDelete);
-          for (const k of keys) this.completed.delete(k);
-        }
-      }
-      const waiter = this.taskWaiters.get(r.taskId);
-      if (waiter) {
-        waiter.resolve(r);
-        this.taskWaiters.delete(r.taskId);
-      }
-      let anyConsumed = false;
-      for (const aw of [...this.anyWaiters]) {
-        if (!aw.ids.has(r.taskId)) continue;
-        if (aw.timer) clearTimeout(aw.timer);
-        this.anyWaiters.delete(aw);
-        aw.resolve(r);
-        anyConsumed = true;
-      }
-      const consumedInBand = !!waiter || anyConsumed;
-      if (internalTask) return;
-      const title = this.taskDescriptions.get(r.taskId) ?? payload.task.description ?? r.taskId;
-      if (!consumedInBand && this.taskResultNotifier) {
-        const resultText = typeof r.result === "string" ? r.result : r.result !== void 0 ? safeStringify(r.result) : void 0;
-        try {
-          void Promise.resolve(
-            this.taskResultNotifier({
-              taskId: r.taskId,
-              title,
-              status: r.status,
-              subagentId: r.subagentId,
-              subagentName: this.manifestEntries.get(r.subagentId)?.name,
-              resultText,
-              errorText: r.error ? `${r.error.kind}: ${r.error.message}` : void 0,
-              partialText: r.partial?.text,
-              report: r.report,
-              iterations: r.iterations,
-              toolCalls: r.toolCalls,
-              durationMs: r.durationMs
-            })
-          ).catch(() => {
-          });
-        } catch {
-        }
+    this.taskCompletedListener = (payload) => this.handleTaskCompleted(payload);
+    this.coordinator.on("task.completed", this.taskCompletedListener);
+    this.wireBudgetPolicy();
+    this.largeAnswerStore = new LargeAnswerStore(2e3);
+    this.collab = new DirectorCollabController({
+      director: this,
+      fleet: this.fleet,
+      coordinator: this.coordinator,
+      logger: this.logger
+    });
+  }
+  handleTaskCompleted(payload) {
+    const r = payload.result;
+    const internalTask = this.internalTaskIds.delete(r.taskId);
+    if (!internalTask) {
+      this.completed.set(r.taskId, r);
+      if (this.completed.size > _Director.MAX_COMPLETED) {
+        const toDelete = this.completed.size - _Director.MAX_COMPLETED;
+        const keys = [...this.completed.keys()].slice(0, toDelete);
+        for (const k of keys) this.completed.delete(k);
+      }
+    }
+    const waiter = this.taskWaiters.get(r.taskId);
+    if (waiter) {
+      waiter.resolve(r);
+      this.taskWaiters.delete(r.taskId);
+    }
+    let anyConsumed = false;
+    for (const aw of [...this.anyWaiters]) {
+      if (!aw.ids.has(r.taskId)) continue;
+      if (aw.timer) clearTimeout(aw.timer);
+      this.anyWaiters.delete(aw);
+      aw.resolve(r);
+      anyConsumed = true;
+    }
+    const consumedInBand = !!waiter || anyConsumed;
+    if (internalTask) return;
+    const title = this.taskDescriptions.get(r.taskId) ?? payload.task.description ?? r.taskId;
+    if (!consumedInBand && this.taskResultNotifier) {
+      const resultText = typeof r.result === "string" ? r.result : r.result !== void 0 ? safeStringify(r.result) : void 0;
+      try {
+        void Promise.resolve(
+          this.taskResultNotifier({
+            taskId: r.taskId,
+            title,
+            status: r.status,
+            subagentId: r.subagentId,
+            subagentName: this.manifestEntries.get(r.subagentId)?.name,
+            resultText,
+            errorText: r.error ? `${r.error.kind}: ${r.error.message}` : void 0,
+            partialText: r.partial?.text,
+            report: r.report,
+            iterations: r.iterations,
+            toolCalls: r.toolCalls,
+            durationMs: r.durationMs
+          })
+        ).catch(() => {
+        });
+      } catch {
       }
-      const failed = r.status !== "success";
-      const errorString = r.error ? `${r.error.kind}: ${r.error.message}` : void 0;
-      this.stateCheckpoint?.recordTaskStatus(r.taskId, {
-        status: failed ? r.status : "completed",
-        completedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        iterations: r.iterations,
-        toolCalls: r.toolCalls,
-        durationMs: r.durationMs,
-        error: errorString
-      });
-      this.stateCheckpoint?.setUsage(this.usage.snapshot());
-      void this.appendSessionEvent(
-        failed ? {
-          type: "task_failed",
-          ts: (/* @__PURE__ */ new Date()).toISOString(),
-          taskId: r.taskId,
-          title,
-          error: errorString ?? r.status
-        } : {
-          type: "task_completed",
-          ts: (/* @__PURE__ */ new Date()).toISOString(),
-          taskId: r.taskId,
-          title
-        }
-      );
-      if (this.fleetManager) {
-        void this.fleetManager.flushManifest();
-      } else {
-        this.scheduleManifest();
+    }
+    const failed = r.status !== "success";
+    const errorString = r.error ? `${r.error.kind}: ${r.error.message}` : void 0;
+    this.stateCheckpoint?.recordTaskStatus(r.taskId, {
+      status: failed ? r.status : "completed",
+      completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      iterations: r.iterations,
+      toolCalls: r.toolCalls,
+      durationMs: r.durationMs,
+      error: errorString
+    });
+    this.stateCheckpoint?.setUsage(this.usage.snapshot());
+    void this.appendSessionEvent(
+      failed ? {
+        type: "task_failed",
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        taskId: r.taskId,
+        title,
+        error: errorString ?? r.status
+      } : {
+        type: "task_completed",
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        taskId: r.taskId,
+        title
       }
-      this.armSubagentIdleRetirement(
-        r.subagentId,
-        this.retireSubagentOnTaskComplete ? 0 : this.subagentIdleTimeoutMs
-      );
-    };
-    this.coordinator.on("task.completed", this.taskCompletedListener);
+    );
+    if (this.fleetManager) {
+      void this.fleetManager.flushManifest();
+    } else {
+      this.scheduleManifest();
+    }
+    this.armSubagentIdleRetirement(
+      r.subagentId,
+      this.retireSubagentOnTaskComplete ? 0 : this.subagentIdleTimeoutMs
+    );
+  }
+  wireBudgetPolicy() {
     const extendCounts = /* @__PURE__ */ new Map();
     const progressBySubagent = /* @__PURE__ */ new Map();
     const lastTimeoutProgress = /* @__PURE__ */ new Map();
@@ -9773,7 +9942,6 @@ var Director = class _Director {
       }
       grantExtension();
     });
-    this.largeAnswerStore = new LargeAnswerStore(2e3);
   }
   /**
    * Record a granted budget extension and broadcast it on the FleetBus so
@@ -9831,10 +9999,7 @@ var Director = class _Director {
    * programmatically without going through the slash-command path.
    */
   setLeaderBtwNote(note) {
-    const trimmed = note.trim();
-    if (!trimmed) return this._leaderBtwNotes.length;
-    this._leaderBtwNotes = [...this._leaderBtwNotes, trimmed].slice(-20);
-    return this._leaderBtwNotes.length;
+    return this.btwNotes.add(note);
   }
   /**
    * Read and clear all pending /btw notes the leader has stashed.
@@ -9845,16 +10010,14 @@ var Director = class _Director {
    * to cancel the collab session or let it continue.
    */
   getLeaderBtwNotes() {
-    const notes = this._leaderBtwNotes;
-    this._leaderBtwNotes = [];
-    return notes;
+    return this.btwNotes.drain();
   }
   /**
    * Peek at pending /btw notes without consuming them.
    * Useful for UI to show "N pending notes" without clearing them.
    */
   peekLeaderBtwNotes() {
-    return [...this._leaderBtwNotes];
+    return this.btwNotes.peek();
   }
   /**
    * Drain (read + clear) all /btw notes in one call.
@@ -9874,18 +10037,7 @@ var Director = class _Director {
    * The CollabDebugReport will reflect 'cancelled' disposition when awaited.
    */
   cancelCollabSession(sessionId, reason = "Director cancelled") {
-    const entry = this._activeCollabSessions.get(sessionId);
-    if (!entry || entry.session.isCancelled()) return;
-    for (const unsub of entry.unsubs) unsub();
-    entry.session.cancel(reason);
-    for (const [_role, subagentId] of entry.session.getSubagentIds()) {
-      this.coordinator.stop(subagentId).catch((err) => {
-        this.logger?.debug(`stop subagent ${subagentId} failed (may have already completed)`, {
-          subagentId,
-          err: err instanceof Error ? err.message : String(err)
-        });
-      });
-    }
+    this.collab.cancel(sessionId, reason);
   }
   /**
    * Subscribe a callback to be notified whenever a collab session raises
@@ -9894,9 +10046,7 @@ var Director = class _Director {
    * Returns an unsubscribe function.
    */
   onCollabAlert(handler) {
-    return this.fleet.filter("collab.warning", (e) => {
-      handler(e.payload);
-    });
+    return this.collab.onAlert(handler);
   }
   /**
    * Returns all active (not yet settled) collab session ids.
@@ -9904,7 +10054,7 @@ var Director = class _Director {
    * the host to know what can be cancelled.
    */
   activeCollabSessions() {
-    return Array.from(this._activeCollabSessions.keys());
+    return this.collab.activeSessionIds();
   }
   /** Best-effort session-writer append. Swallows failures — the director
    *  must not break a fleet run because the session JSONL handle closed. */
@@ -9970,6 +10120,77 @@ var Director = class _Director {
       );
     }
     const config = { ...callerConfig };
+    this.resolveSpawnModel(config);
+    this.enforceSpawnCaps(config);
+    let result;
+    this.assignSpawnNickname(config);
+    this.applySpawnLineage(config);
+    result = await this.coordinator.spawn(config);
+    if (this.fleetManager) {
+      this.fleetManager.recordSpawn(result.subagentId, config, priceLookup);
+    } else {
+      this.spawnCount += 1;
+      this.subagentMeta.set(result.subagentId, {
+        provider: config.provider,
+        model: config.model
+      });
+      if (priceLookup && config.provider && config.model) {
+        this.priceLookups.set(`${config.provider}/${config.model}`, priceLookup);
+      }
+    }
+    const subagentBridge = new InMemoryAgentBridge(
+      { agentId: result.subagentId, coordinatorId: this.id },
+      this.transport
+    );
+    this.coordinator.setSubagentBridge(result.subagentId, subagentBridge);
+    this.subagentBridges.set(result.subagentId, subagentBridge);
+    this.fleet.emit({
+      subagentId: result.subagentId,
+      ts: Date.now(),
+      type: "subagent.spawned",
+      payload: {
+        subagentId: result.subagentId,
+        taskId: "",
+        // taskId will be set when assign() is called
+        name: config.name,
+        role: config.role,
+        provider: config.provider,
+        model: config.model
+      }
+    });
+    if (!this.fleetManager) {
+      this.manifestEntries.set(result.subagentId, {
+        subagentId: result.subagentId,
+        name: config.name,
+        role: config.role,
+        provider: config.provider,
+        model: config.model,
+        taskIds: []
+      });
+      const spawnedAt = (/* @__PURE__ */ new Date()).toISOString();
+      this.stateCheckpoint?.recordSpawn(
+        {
+          id: result.subagentId,
+          name: config.name,
+          role: config.role,
+          provider: config.provider,
+          model: config.model,
+          spawnedAt
+        },
+        this.spawnCount
+      );
+      void this.appendSessionEvent({
+        type: "agent_spawned",
+        ts: spawnedAt,
+        agentId: result.subagentId,
+        role: config.role ?? config.name
+      });
+      this.scheduleManifest();
+    }
+    this.armSubagentIdleRetirement(result.subagentId, this.subagentIdleTimeoutMs);
+    return result.subagentId;
+  }
+  resolveSpawnModel(config) {
     if (!config.model && this.modelMatrix) {
       const matrix = typeof this.modelMatrix === "function" ? this.modelMatrix() : this.modelMatrix;
       const resolution = resolveModelMatrixResolution(matrix, config.role);
@@ -9980,6 +10201,8 @@ var Director = class _Director {
         if (entry.modelRuntime) config.modelRuntime = entry.modelRuntime;
       }
     }
+  }
+  enforceSpawnCaps(config) {
     if (this.fleetManager) {
       const rejection = this.fleetManager.canSpawn(config);
       if (rejection) {
@@ -10022,7 +10245,8 @@ var Director = class _Director {
         }
       }
     }
-    let result;
+  }
+  assignSpawnNickname(config) {
     const needsNickname = config.name === config.role || !config.name || config.name === "subagent" || config.name === "adhoc";
     if (needsNickname) {
       const role = config.role ?? "subagent";
@@ -10034,6 +10258,8 @@ var Director = class _Director {
         this._usedNicknames.add(key);
       }
     }
+  }
+  applySpawnLineage(config) {
     const budget = this.fleetManager ? this.fleetManager.budgetSnapshot() : (() => {
       const total = this.usage.snapshot().total;
       const usedTokens = (total?.input ?? 0) + (total?.output ?? 0);
@@ -10062,70 +10288,6 @@ var Director = class _Director {
         ...Number.isFinite(budget.remainingCostUsd) ? { remainingCostUsd: budget.remainingCostUsd } : {}
       }
     };
-    result = await this.coordinator.spawn(config);
-    if (this.fleetManager) {
-      this.fleetManager.recordSpawn(result.subagentId, config, priceLookup);
-    } else {
-      this.spawnCount += 1;
-      this.subagentMeta.set(result.subagentId, {
-        provider: config.provider,
-        model: config.model
-      });
-      if (priceLookup && config.provider && config.model) {
-        this.priceLookups.set(`${config.provider}/${config.model}`, priceLookup);
-      }
-    }
-    const subagentBridge = new InMemoryAgentBridge(
-      { agentId: result.subagentId, coordinatorId: this.id },
-      this.transport
-    );
-    this.coordinator.setSubagentBridge(result.subagentId, subagentBridge);
-    this.subagentBridges.set(result.subagentId, subagentBridge);
-    this.fleet.emit({
-      subagentId: result.subagentId,
-      ts: Date.now(),
-      type: "subagent.spawned",
-      payload: {
-        subagentId: result.subagentId,
-        taskId: "",
-        // taskId will be set when assign() is called
-        name: config.name,
-        role: config.role,
-        provider: config.provider,
-        model: config.model
-      }
-    });
-    if (!this.fleetManager) {
-      this.manifestEntries.set(result.subagentId, {
-        subagentId: result.subagentId,
-        name: config.name,
-        role: config.role,
-        provider: config.provider,
-        model: config.model,
-        taskIds: []
-      });
-      const spawnedAt = (/* @__PURE__ */ new Date()).toISOString();
-      this.stateCheckpoint?.recordSpawn(
-        {
-          id: result.subagentId,
-          name: config.name,
-          role: config.role,
-          provider: config.provider,
-          model: config.model,
-          spawnedAt
-        },
-        this.spawnCount
-      );
-      void this.appendSessionEvent({
-        type: "agent_spawned",
-        ts: spawnedAt,
-        agentId: result.subagentId,
-        role: config.role ?? config.name
-      });
-      this.scheduleManifest();
-    }
-    this.armSubagentIdleRetirement(result.subagentId, this.subagentIdleTimeoutMs);
-    return result.subagentId;
   }
   /**
    * Synchronously ask a subagent something via the bridge. Sends a
@@ -10250,6 +10412,23 @@ var Director = class _Director {
     await atomicWrite(this.manifestPath, JSON.stringify(manifest, null, 2), { mode: 384 });
     return this.manifestPath;
   }
+  /**
+   * Cancel the pending manifest debounce timer and drain any in-flight
+   * manifest write so that, once this resolves, no Director-owned manifest
+   * write is armed or running.
+   *
+   * Unlike `shutdown()`, this does NOT tear down the coordinator, bridges,
+   * or waiters — it is the lightweight quiesce that `MultiAgentHost.stopAll()`
+   * needs. `stopAll()` flushes the FleetManager's manifest but never touched
+   * the Director's own writer, leaving its armed debounce timer to fire ~2s
+   * later. Under CPU starvation that late, un-awaited `atomicWrite` (temp
+   * sibling + rename) races a caller that deletes the manifest directory,
+   * producing an `ENOTEMPTY` on the parent `rmdir` (Windows especially).
+   */
+  async quiesceManifest() {
+    this.clearManifestTimer();
+    await this.manifestWriteChain.catch(() => void 0);
+  }
   /**
    * Tear down the director: stop every subagent, close every bridge
    * endpoint, and (when configured) write the final manifest. Idempotent
@@ -10261,8 +10440,17 @@ var Director = class _Director {
       this.coordinator.off("task.completed", this.taskCompletedListener);
       this.taskCompletedListener = null;
     }
-    for (const aw of this.anyWaiters) {
+    for (const aw of [...this.anyWaiters]) {
       if (aw.timer) clearTimeout(aw.timer);
+      const firstId = [...aw.ids][0];
+      aw.resolve({
+        taskId: firstId ?? "unknown",
+        subagentId: "director",
+        status: "stopped",
+        iterations: 0,
+        toolCalls: 0,
+        durationMs: 0
+      });
     }
     this.anyWaiters.clear();
     if (this.toolExecFilter) {
@@ -10276,6 +10464,17 @@ var Director = class _Director {
     for (const timer of this.subagentIdleTimers.values()) clearTimeout(timer);
     this.subagentIdleTimers.clear();
     await this.coordinator.stopAll();
+    for (const [id, waiter] of this.taskWaiters) {
+      waiter.resolve({
+        taskId: id,
+        subagentId: "director",
+        status: "stopped",
+        iterations: 0,
+        toolCalls: 0,
+        durationMs: 0
+      });
+    }
+    this.taskWaiters.clear();
     for (const b of this.subagentBridges.values()) {
       await b.stop().catch((err) => this.logShutdownError("subagent_bridge_stop", err));
     }
@@ -10283,6 +10482,7 @@ var Director = class _Director {
     await this.bridge.stop().catch((err) => this.logShutdownError("director_bridge_stop", err));
     if (this.fleetManager) {
       await this.fleetManager.flushManifest().catch((err) => this.logShutdownError("fleet_manifest_flush", err));
+      await this.manifestWriteChain.catch(() => void 0);
     } else if (this.manifestPath) {
       await this.writeManifest().catch((err) => this.logShutdownError("manifest_write", err));
     }
@@ -10748,22 +10948,7 @@ var Director = class _Director {
    * three agents complete or the session times out.
    */
   async spawnCollab(options) {
-    const session = new CollabSession(this, this.fleet, {
-      ...options,
-      onBudgetWarning: (alert) => {
-        return options.onBudgetWarning?.(alert) ?? "ignore";
-      }
-    });
-    const doneHandler = () => this._activeCollabSessions.delete(session.sessionId);
-    const errorHandler = () => this._activeCollabSessions.delete(session.sessionId);
-    session.on("session.done", doneHandler);
-    session.on("session.error", errorHandler);
-    const unsubs = [
-      () => session.off("session.done", doneHandler),
-      () => session.off("session.error", errorHandler)
-    ];
-    this._activeCollabSessions.set(session.sessionId, { session, unsubs });
-    return session.start();
+    return this.collab.spawn(options);
   }
   /**
    * Resume from a prior checkpoint snapshot (loaded via
@@ -13446,6 +13631,16 @@ var FleetManager = class {
   manifestTimer = null;
   manifestWriteChain = Promise.resolve();
   disposed = false;
+  /**
+   * Teardown freeze. Set by `closeManifest()` after the final manifest is
+   * flushed; makes any subsequent `scheduleManifest`/`writeManifest`/
+   * `flushManifest` a no-op so a late fire-and-forget write (e.g. the
+   * task-completion flush the Director issues via `void flushManifest()`)
+   * cannot land an `atomicWrite` in the manifest directory while a caller is
+   * deleting it. Cleared by `recordSpawn` so a stop-then-spawn-again host
+   * resumes writing.
+   */
+  closing = false;
   manifestDebounceMs;
   /** Fleet-wide cost cap. Infinity = no cap. Distinct from SubagentBudget limits,
    *  which track per-subagent spend — this field caps the entire fleet total. */
@@ -13627,6 +13822,7 @@ var FleetManager = class {
    * @param priceLookup Optional per-subagent pricing data
    */
   recordSpawn(subagentId, config, priceLookup) {
+    this.closing = false;
     this.spawnCount += 1;
     this.subagentMeta.set(subagentId, {
       provider: config.provider,
@@ -13664,6 +13860,7 @@ var FleetManager = class {
   }
   async writeManifest() {
     if (!this.manifestPath) return null;
+    if (this.closing) return this.manifestPath;
     this.clearManifestTimer();
     const write = this.manifestWriteChain.catch(() => void 0).then(() => this.writeManifestNow());
     this.manifestWriteChain = write.catch(() => void 0);
@@ -13712,7 +13909,7 @@ var FleetManager = class {
    * When `manifestDebounceMs` is 0, writes are synchronous (no debounce).
    */
   scheduleManifest() {
-    if (this.disposed) return;
+    if (this.disposed || this.closing) return;
     if (!this.manifestPath) return;
     if (this.manifestDebounceMs === 0) {
       void this.writeManifest().catch((err) => {
@@ -13743,6 +13940,22 @@ var FleetManager = class {
       process.emitWarning(`FleetManager manifest write failed: ${detail}`, "FleetManagerWarning");
     });
   }
+  /**
+   * Teardown flush for callers that will delete the manifest directory next
+   * (host `stopAll`/`dispose`). Writes the final manifest, then freezes the
+   * writer so no later fire-and-forget write can start, and drains anything
+   * still in flight. After this resolves it is safe to `rm -rf` the manifest
+   * directory: no `atomicWrite` (temp sibling + rename) can race the removal.
+   *
+   * The freeze is lifted by the next `recordSpawn`, so a stop-then-spawn-again
+   * host keeps persisting manifests.
+   */
+  async closeManifest() {
+    if (!this.manifestPath) return;
+    await this.flushManifest();
+    this.closing = true;
+    await this.manifestWriteChain.catch(() => void 0);
+  }
   clearManifestTimer() {
     if (!this.manifestTimer) return;
     clearTimeout(this.manifestTimer);
@@ -13969,6 +14182,42 @@ function parseMailboxMessage(value) {
 function parseMailboxMessageLine(line) {
   return parseMailboxMessage(JSON.parse(line));
 }
+function isAckRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && value["__ack"] === true;
+}
+function parseMailboxLine(line) {
+  try {
+    const parsed = JSON.parse(line);
+    if (isAckRecord(parsed)) return parsed;
+    return parseMailboxMessage(parsed);
+  } catch {
+    return null;
+  }
+}
+function applyAckToMessage(msg, ack) {
+  if (ack.read && !(ack.readerId in msg.readBy)) {
+    msg.readBy[ack.readerId] = ack.timestamp;
+  }
+  if (ack.completed && !msg.completed) {
+    msg.completed = true;
+    msg.completedBy = ack.completedBy ?? ack.readerId;
+    msg.completedAt = ack.timestamp;
+  }
+  if (ack.outcome !== void 0 && msg.outcome !== ack.outcome) {
+    msg.outcome = ack.outcome;
+  }
+  if (ack.deleted === true) {
+    msg.deletedAt = ack.timestamp;
+    msg.deletedBy = ack.deletedBy ?? ack.readerId;
+  }
+  if (ack.deleted === false) {
+    delete msg.deletedAt;
+    delete msg.deletedBy;
+  }
+}
+function serializeAckRecord(ack) {
+  return JSON.stringify(ack) + "\n";
+}
 
 // src/coordination/mailbox-types.ts
 function normalizeRecipient(to) {
@@ -14040,7 +14289,7 @@ var GlobalMailbox = class {
    * appended message). The chain runs each read to completion before
    * the next starts, in issue order — readers are read-only and never
    * conflict with each other on content, only on the cache mutation
-   * that follows the read. Pattern mirrors `DefaultMemoryStore.runSerialized`.
+   * that follows the read. Pattern mirrors a serialized mutation chain.
    */
   _readChain = Promise.resolve([]);
   /**
@@ -14051,7 +14300,7 @@ var GlobalMailbox = class {
    *
    * The index is rebuilt whenever the cache array is replaced
    * (`_setMessageCache`), extended when new messages are pushed
-   * (`_pushToCache`, `_readNewMessagesOnly`), and cleared on `close()`.
+   * (`_pushToCache`), and cleared on `close()`.
    * It is `null` when the cache itself is null (> MESSAGE_CACHE_MAX_ENTRIES
    * or never populated).
    *
@@ -14190,42 +14439,100 @@ var GlobalMailbox = class {
     const updated = await this.ackMany({ acks: [input] });
     return updated.length > 0 ? updated[0] : null;
   }
+  /** Diagnostic counters exposed for test/tool introspection. */
+  diag = {
+    ackManyCacheDesync: 0,
+    ackManyPreLockMtime: 0,
+    ackManyPostLockMtime: 0,
+    ackManyPreLockSize: 0,
+    ackManyPostLockSize: 0,
+    ackManyMessageCount: 0,
+    ackManyAckCount: 0,
+    cacheHitCount: 0,
+    cacheMissCount: 0,
+    cacheDesyncNoOp: 0,
+    applyAckTargetMissing: 0,
+    setMessageCacheCount: 0,
+    pushToCacheCount: 0
+  };
   async ackMany(input) {
     if (input.acks.length === 0) return [];
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const ackRecords = [];
     const updated = [];
+    const targetIds = /* @__PURE__ */ new Set();
     const byId = /* @__PURE__ */ new Map();
     for (const a of input.acks) {
       byId.set(a.messageId, a);
+      targetIds.add(a.messageId);
     }
-    await withFileLock(this.messagePath, async () => {
-      const all = await this._readMessagesFresh();
-      const now = (/* @__PURE__ */ new Date()).toISOString();
-      let changed = false;
-      for (const msg of all) {
-        const a = byId.get(msg.id);
-        if (!a) continue;
-        updated.push(msg);
-        if (a.read !== false && !(a.readerId in msg.readBy)) {
-          msg.readBy[a.readerId] = now;
-          changed = true;
-        }
-        if (a.completed && !msg.completed) {
-          msg.completed = true;
-          msg.completedBy = a.readerId;
-          msg.completedAt = now;
-          changed = true;
-        }
-        if (a.outcome !== void 0 && msg.outcome !== a.outcome) {
-          msg.outcome = a.outcome;
-          changed = true;
-        }
+    const preLockMtime = this._messageCacheMtime;
+    const preLockSize = this._messageCacheSize;
+    this.diag.ackManyPreLockMtime = preLockMtime;
+    this.diag.ackManyPreLockSize = preLockSize;
+    const all = await this._readMessagesCached();
+    for (const msg of all) {
+      const a = byId.get(msg.id);
+      if (!a) continue;
+      const needsRead = a.read !== false && !(a.readerId in msg.readBy);
+      const needsComplete = a.completed && !msg.completed;
+      const needsOutcome = a.outcome !== void 0 && msg.outcome !== a.outcome;
+      if (!needsRead && !needsComplete && !needsOutcome) {
+        updated.push({ ...msg, readBy: { ...msg.readBy } });
+        continue;
       }
-      if (changed) {
-        const serialized = all.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
-        await fsp11.writeFile(this.messagePath, serialized, "utf8");
+      const copy = { ...msg, readBy: { ...msg.readBy } };
+      if (needsRead) copy.readBy[a.readerId] = now;
+      if (needsComplete) {
+        copy.completed = true;
+        copy.completedBy = a.readerId;
+        copy.completedAt = now;
+      }
+      if (needsOutcome) copy.outcome = a.outcome;
+      updated.push(copy);
+      ackRecords.push({
+        __ack: true,
+        messageId: msg.id,
+        readerId: a.readerId,
+        timestamp: now,
+        read: a.read !== false,
+        completed: a.completed,
+        completedBy: a.completed ? a.readerId : void 0,
+        outcome: a.outcome
+      });
+    }
+    if (ackRecords.length === 0) {
+      if (updated.length > 0) {
+        for (const message of updated) {
+          this.publishHqMailboxEvent({
+            mailboxId: this.hqMailboxId,
+            action: message.completed ? "message.completed" : "message.read",
+            message
+          });
+        }
       }
+      return updated;
+    }
+    const serialized = ackRecords.map((a) => serializeAckRecord(a)).join("");
+    await withFileLock(this.messagePath, async () => {
+      await fsp11.appendFile(this.messagePath, serialized, "utf8");
       const { mtimeMs, size } = await this._statMessageFile();
-      this._setMessageCache(all, mtimeMs, size);
+      for (const ack of ackRecords) {
+        this._applyAckToCache(ack);
+      }
+      this._messageCacheMtime = mtimeMs;
+      this._messageCacheSize = size;
+      this.diag.ackManyPostLockMtime = mtimeMs;
+      this.diag.ackManyPostLockSize = size;
+      this.diag.ackManyMessageCount = this._messageCache?.length ?? -1;
+      this.diag.ackManyAckCount = ackRecords.length;
+      const expectedMinSize = preLockSize + serialized.length;
+      if (preLockSize > 0 && size > expectedMinSize) {
+        const extraBytes = size - expectedMinSize;
+        console.error(
+          `[MAILBOX-DIAG] ackMany: post-lock size ${size} exceeds expected ${expectedMinSize} by ${extraBytes}B (mtime ${preLockMtime}->${mtimeMs}). Cache may be missing cross-process messages. diag.ackManyCacheDesync=${++this.diag.ackManyCacheDesync}`
+        );
+      }
     });
     for (const message of updated) {
       this.publishHqMailboxEvent({
@@ -14268,87 +14575,87 @@ var GlobalMailbox = class {
     return count;
   }
   async softDelete(mailId, by) {
-    let updated = null;
+    const all = await this._readMessagesCached();
+    const target = all.find((m) => m.id === mailId);
+    if (target === void 0) return null;
+    if (target.deletedAt !== void 0) {
+      return { ...target, readBy: { ...target.readBy } };
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const ack = {
+      __ack: true,
+      messageId: mailId,
+      readerId: by,
+      timestamp: now,
+      read: true,
+      deleted: true,
+      deletedBy: by
+    };
     await withFileLock(this.messagePath, async () => {
-      const all = await this._readMessagesFresh();
-      const now = (/* @__PURE__ */ new Date()).toISOString();
-      let changed = false;
-      for (const m of all) {
-        if (m.id !== mailId) continue;
-        if (m.deletedAt !== void 0) {
-          updated = m;
-          continue;
-        }
-        m.deletedAt = now;
-        m.deletedBy = by;
-        updated = m;
-        changed = true;
-      }
-      if (changed) {
-        const serialized = all.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
-        await fsp11.writeFile(this.messagePath, serialized, "utf8");
-      }
+      await fsp11.appendFile(this.messagePath, serializeAckRecord(ack), "utf8");
       const { mtimeMs, size } = await this._statMessageFile();
-      this._setMessageCache(all, mtimeMs, size);
+      this._applyAckToCache(ack);
+      this._messageCacheMtime = mtimeMs;
+      this._messageCacheSize = size;
     });
-    if (updated !== null) {
-      const msg = updated;
-      this.publishHqMailboxEvent({
-        mailboxId: this.hqMailboxId,
-        action: "message.updated",
-        message: msg
-      });
-      this.publishHqMailboxSnapshot();
-      this.eventEmitter?.emit({
-        type: "message.deleted",
-        messageId: msg.id,
-        from: msg.from,
-        to: msg.to,
-        timestamp: msg.deletedAt ?? (/* @__PURE__ */ new Date()).toISOString()
-      });
-    }
-    return updated;
+    const msg = { ...target, readBy: { ...target.readBy } };
+    msg.deletedAt = now;
+    msg.deletedBy = by;
+    this.publishHqMailboxEvent({
+      mailboxId: this.hqMailboxId,
+      action: "message.updated",
+      message: msg
+    });
+    this.publishHqMailboxSnapshot();
+    this.eventEmitter?.emit({
+      type: "message.deleted",
+      messageId: msg.id,
+      from: msg.from,
+      to: msg.to,
+      timestamp: msg.deletedAt ?? now
+    });
+    return msg;
   }
   async restore(mailId) {
-    let updated = null;
+    const all = await this._readMessagesCached();
+    const target = all.find((m) => m.id === mailId);
+    if (target === void 0) return null;
+    if (target.deletedAt === void 0 && target.deletedBy === void 0) {
+      return { ...target, readBy: { ...target.readBy } };
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const ack = {
+      __ack: true,
+      messageId: mailId,
+      readerId: "",
+      timestamp: now,
+      read: true,
+      deleted: false
+    };
     await withFileLock(this.messagePath, async () => {
-      const all = await this._readMessagesFresh();
-      let changed = false;
-      for (const m of all) {
-        if (m.id !== mailId) continue;
-        if (m.deletedAt === void 0 && m.deletedBy === void 0) {
-          updated = m;
-          continue;
-        }
-        delete m.deletedAt;
-        delete m.deletedBy;
-        updated = m;
-        changed = true;
-      }
-      if (changed) {
-        const serialized = all.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
-        await fsp11.writeFile(this.messagePath, serialized, "utf8");
-      }
+      await fsp11.appendFile(this.messagePath, serializeAckRecord(ack), "utf8");
       const { mtimeMs, size } = await this._statMessageFile();
-      this._setMessageCache(all, mtimeMs, size);
+      this._applyAckToCache(ack);
+      this._messageCacheMtime = mtimeMs;
+      this._messageCacheSize = size;
     });
-    if (updated !== null) {
-      const msg = updated;
-      this.publishHqMailboxEvent({
-        mailboxId: this.hqMailboxId,
-        action: "message.updated",
-        message: msg
-      });
-      this.publishHqMailboxSnapshot();
-      this.eventEmitter?.emit({
-        type: "message.restored",
-        messageId: msg.id,
-        from: msg.from,
-        to: msg.to,
-        timestamp: (/* @__PURE__ */ new Date()).toISOString()
-      });
-    }
-    return updated;
+    const msg = { ...target, readBy: { ...target.readBy } };
+    delete msg.deletedAt;
+    delete msg.deletedBy;
+    this.publishHqMailboxEvent({
+      mailboxId: this.hqMailboxId,
+      action: "message.updated",
+      message: msg
+    });
+    this.publishHqMailboxSnapshot();
+    this.eventEmitter?.emit({
+      type: "message.restored",
+      messageId: msg.id,
+      from: msg.from,
+      to: msg.to,
+      timestamp: now
+    });
+    return msg;
   }
   // ── Agent registry ──────────────────────────────────────────────────────
   async registerAgent(input) {
@@ -14585,11 +14892,18 @@ var GlobalMailbox = class {
   }
   async getClientStatuses() {
     await this._ensureClientRegistry();
-    const registry = await this._readClientRegistry();
+    let registry = await this._readClientRegistry();
     const before = registry.size;
     this._pruneStaleClientsInPlace(registry);
     if (registry.size < before) {
-      await this._writeClientRegistry(registry);
+      await withFileLock(this.clientRegistryPath, async () => {
+        registry = await this._readClientRegistry({ fresh: true });
+        const postLockBefore = registry.size;
+        this._pruneStaleClientsInPlace(registry);
+        if (registry.size < postLockBefore) {
+          await this._writeClientRegistry(registry);
+        }
+      });
     }
     const now = Date.now();
     return Array.from(registry.values()).map((c) => ({
@@ -14795,75 +15109,22 @@ var GlobalMailbox = class {
       throw err;
     }
   }
-  /**
-   * Read only newly-appended bytes from the file and append them to the
-   * in-memory cache. This avoids re-reading and re-parsing the entire file
-   * when another process appended messages since our last read.
-   *
-   * Only safe when the file grew in size (messages are append-only). When
-   * the file was rewritten (ack/purge changed existing content), callers
-   * must fall back to {@link _readMessages}.
-   *
-   * @returns The (now up-to-date) message cache.
-   */
-  async _readNewMessagesOnly(fd, oldSize, newSize) {
-    const tailLen = newSize - oldSize;
-    const buf = Buffer.alloc(tailLen);
-    await fd.read(buf, 0, tailLen, oldSize);
-    const tail = buf.toString("utf8");
-    if (!tail.endsWith(LINE_SEPARATOR)) {
-      const lastSeparatorIdx = tail.lastIndexOf(LINE_SEPARATOR);
-      if (lastSeparatorIdx === -1) {
-        return this._messageCache;
-      }
-      const completeTail = tail.slice(0, lastSeparatorIdx + 1);
-      this._appendIncrementalLines(completeTail);
-      this._messageCacheSize = oldSize + lastSeparatorIdx + 1;
-      return this._messageCache;
-    }
-    this._appendIncrementalLines(tail);
-    this._messageCacheSize = newSize;
-    return this._messageCache;
-  }
-  _appendIncrementalLines(raw) {
-    for (const line of raw.split(LINE_SEPARATOR)) {
-      if (!line.trim()) continue;
-      const message = this._parseLine(line);
-      if (message === null) continue;
-      this._messageCache.push(message);
-      const idx = this._messageCache.length - 1;
-      if (this._recipientIndex !== null) {
-        let set = this._recipientIndex.get(message.to);
-        if (set === void 0) {
-          set = /* @__PURE__ */ new Set();
-          this._recipientIndex.set(message.to, set);
-        }
-        set.add(idx);
-      }
-      if (this._senderIndex !== null) {
-        let set = this._senderIndex.get(message.from);
-        if (set === void 0) {
-          set = /* @__PURE__ */ new Set();
-          this._senderIndex.set(message.from, set);
-        }
-        set.add(idx);
-      }
-    }
-  }
-  _parseLine(line) {
-    try {
-      return parseMailboxMessageLine(line);
-    } catch {
-      return null;
-    }
-  }
-  /** Parse a JSONL string into MailboxMessage[], including migration. */
+  /** Parse a JSONL string into MailboxMessage[], applying ack records. */
   _parseLines(raw) {
     const lines = raw.split(LINE_SEPARATOR).filter((l) => l.trim().length > 0);
     const messages = [];
+    const acks = [];
     for (const line of lines) {
-      const message = this._parseLine(line);
-      if (message !== null) messages.push(message);
+      const parsed = parseMailboxLine(line);
+      if (isAckRecord(parsed)) {
+        acks.push(parsed);
+      } else if (parsed !== null) {
+        messages.push(parsed);
+      }
+    }
+    for (const ack of acks) {
+      const target = messages.find((m) => m.id === ack.messageId);
+      if (target) applyAckToMessage(target, ack);
     }
     return messages;
   }
@@ -14946,16 +15207,6 @@ var GlobalMailbox = class {
       if (this._messageCache !== null && this._messageCacheMtime === st.mtimeMs && this._messageCacheSize === st.size) {
         return this._messageCache;
       }
-      if (this._messageCache !== null && this._messageCacheSize >= 0 && st.size > this._messageCacheSize) {
-        const fd = await fsp11.open(this.messagePath, "r");
-        try {
-          const updated = await this._readNewMessagesOnly(fd, this._messageCacheSize, st.size);
-          this._messageCacheMtime = st.mtimeMs;
-          return updated;
-        } finally {
-          await fd.close();
-        }
-      }
       const all = await this._readMessages();
       this._setMessageCache(all, st.mtimeMs, st.size);
       return all;
@@ -14996,6 +15247,21 @@ var GlobalMailbox = class {
     this._messageCacheSize = size;
     this._rebuildRecipientIndex();
   }
+  /**
+   * Fold a single ack record into the in-memory cache, mutating the target
+   * message in place. Called from `ackMany` after appending the record to
+   * disk so the cache reflects the ack without a full re-read + re-parse.
+   *
+   * An ack only touches `readBy`/`completed*`/`outcome` — none of which
+   * affect the recipient/sender indexes — so no index rebuild is needed.
+   * No-op when the cache is empty or the target message isn't cached.
+   */
+  _applyAckToCache(ack) {
+    const cache = this._messageCache;
+    if (cache === null) return;
+    const target = cache.find((m) => m.id === ack.messageId);
+    if (target !== void 0) applyAckToMessage(target, ack);
+  }
   /**
    * Build the recipient AND sender indexes from the current `_messageCache`.
    * Called only from `_setMessageCache` so both indexes are always in sync
@@ -15451,7 +15717,7 @@ function makeFleetStatusTool(opts = {}) {
   const resolveMailbox = opts.resolveMailbox ?? ((ctx) => new GlobalMailbox(opts.projectDir ?? defaultResolveProjectDir(ctx), opts.events));
   return {
     name: "fleet_status",
-    description: "Live snapshot of every agent working on this project (this process AND other terminals/TUIs/WebUIs): who is online, what task each is on, which tool is running, and progress counters. Check it before starting work that might overlap with a peer, when deciding whether to wait for someone or proceed, or when a task mentions another agent. Read-only. To talk to a peer, use mail_send with the returned id.",
+    description: "Live snapshot of every agent working on this canonical project (all clients, processes, sessions, branches, and linked Git worktrees): who is online, what task each is on, which tool is running, and progress counters. Check it before starting work that might overlap with a peer, when deciding whether to wait for someone or proceed, or when a task mentions another agent. Read-only. To talk to a peer, use mail_send with the returned id.",
     usageHint: "fleet_status  (optionally: onlineOnly=false to include recently-offline agents)",
     category: "Coordination",
     permission: "auto",
@@ -16115,7 +16381,7 @@ function makeMailSendTool(opts = {}) {
   const resolveMailbox = makeResolver(opts);
   return {
     name: "mail_send",
-    description: 'Send a mail to other agents working on this project (other terminals, TUIs, WebUIs). Use it to hand off work, ask questions, announce what you just did, or request a review (type="review" \u2014 passive ask, no immediate reply required). to="*" broadcasts to everyone; to="leader" reaches every leader process; an exact id like "leader@a1b2c3d4" reaches one agent. Recipients see your mail automatically before their next step. Pick the type that matches the intent: note (default), ask (blocking question), assign (task), steer (mid-task direction), result (completion notice), review (passive ask), btw/status/broadcast/control (informational).',
+    description: 'Send mail to any agent on this canonical project, across clients, processes, sessions, branches, and linked Git worktrees (CLI, TUI, WebUI, ACP/MCP/HTTP). Use it to hand off work, ask questions, announce what you just did, or request a review (type="review" \u2014 passive ask, no immediate reply required). to="*" broadcasts to everyone; to="leader" reaches every leader process; an exact id like "leader@a1b2c3d4" reaches one agent. Recipients see your mail automatically before their next step. Pick the type that matches the intent: note (default), ask (blocking question), assign (task), steer (mid-task direction), result (completion notice), review (passive ask), btw/status/broadcast/control (informational).',
     usageHint: 'mail_send to="<id>" type="review" body="please skim <file>"',
     category: "Coordination",
     permission: "auto",
@@ -16175,7 +16441,7 @@ function makeMailInboxTool(opts = {}) {
   const resolveMailbox = makeResolver(opts);
   return {
     name: "mail_inbox",
-    description: 'Read your unread mail from other agents on this project and mark it read. Covers mail addressed to you directly, to your base name (e.g. "leader"), and broadcasts ("*"). Urgent steer/btw mail is already injected automatically \u2014 use this to catch up on notes, questions, handoffs, results, and review requests (type="review" \u2014 passive asks where no reply is required). Best called after a long stretch of tool work. Set completed=true to finish every returned message in the same call.',
+    description: 'Read your unread project-wide mail from agents in any client, session, branch, or linked Git worktree and mark it read. Covers mail addressed to you directly, to your base name (e.g. "leader"), and broadcasts ("*"). Urgent steer/btw mail is already injected automatically \u2014 use this to catch up on notes, questions, handoffs, results, and review requests (type="review" \u2014 passive asks where no reply is required). Best called after a long stretch of tool work. Set completed=true to finish every returned message in the same call.',
     usageHint: 'mail_inbox  (optionally: limit=10, markRead=false to peek, completed=true outcome="handled")',
     category: "Coordination",
     permission: "auto",
@@ -16990,7 +17256,7 @@ function createMailboxHooks(opts) {
 var NULL_FLEET_BUS = new FleetBus();
 
 // src/coordination/package-author-tracker.ts
-import * as fs2 from "node:fs/promises";
+import * as fs3 from "node:fs/promises";
 import * as path16 from "node:path";
 var DEFAULT_MAX_ENTRIES = 1e4;
 var LOG_FILENAME = "package-authors.json";
@@ -16999,7 +17265,7 @@ function logPath(storageDir) {
 }
 async function loadLog(storageDir, projectRoot) {
   try {
-    const raw = await fs2.readFile(logPath(storageDir), "utf-8");
+    const raw = await fs3.readFile(logPath(storageDir), "utf-8");
     const parsed = JSON.parse(raw);
     if (!parsed.entries || !Array.isArray(parsed.entries)) {
       return { projectRoot, entries: [] };
@@ -17013,10 +17279,10 @@ async function loadLog(storageDir, projectRoot) {
   }
 }
 async function saveLog(storageDir, log) {
-  await fs2.mkdir(storageDir, { recursive: true });
+  await fs3.mkdir(storageDir, { recursive: true });
   const tmp = `${logPath(storageDir)}.tmp.${Date.now()}`;
-  await fs2.writeFile(tmp, JSON.stringify(log, null, 2) + "\n", "utf-8");
-  await fs2.rename(tmp, logPath(storageDir));
+  await fs3.writeFile(tmp, JSON.stringify(log, null, 2) + "\n", "utf-8");
+  await fs3.rename(tmp, logPath(storageDir));
 }
 function detectEcosystem(manifestPath) {
   const name = path16.win32.basename(manifestPath).toLowerCase();
@@ -17586,7 +17852,7 @@ var AdaptiveConcurrencyController = class {
 };
 
 // src/coordination/agent-monitor.ts
-import * as fs3 from "node:fs/promises";
+import * as fs4 from "node:fs/promises";
 import * as path18 from "node:path";
 var AgentMonitorService = class _AgentMonitorService {
   _fleetBus;
@@ -17830,9 +18096,9 @@ var AgentMonitorService = class _AgentMonitorService {
    * firehose (or, worse, only the first word).
    */
   _appendStreamDelta(subagentId, session, kind, text, iteration) {
-    const open7 = this._openStreams.get(subagentId);
-    if (open7 && open7.entry.kind === kind && open7.entry.iteration === iteration && open7.entry.content.length + text.length <= _AgentMonitorService._MAX_SEGMENT_CHARS) {
-      open7.entry.content += text;
+    const open6 = this._openStreams.get(subagentId);
+    if (open6 && open6.entry.kind === kind && open6.entry.iteration === iteration && open6.entry.content.length + text.length <= _AgentMonitorService._MAX_SEGMENT_CHARS) {
+      open6.entry.content += text;
       return;
     }
     this._closeStream(subagentId);
@@ -17856,12 +18122,12 @@ var AgentMonitorService = class _AgentMonitorService {
    * announce the completed entry on the local bus + HQ callback.
    */
   _closeStream(subagentId) {
-    const open7 = this._openStreams.get(subagentId);
-    if (!open7) return;
+    const open6 = this._openStreams.get(subagentId);
+    if (!open6) return;
     this._openStreams.delete(subagentId);
-    this._appendToFile(subagentId, open7.entry).catch(() => {
+    this._appendToFile(subagentId, open6.entry).catch(() => {
     });
-    this._emitEntry(open7.entry);
+    this._emitEntry(open6.entry);
   }
   _addEntry(subagentId, entry) {
     const session = this._sessions.get(subagentId);
@@ -17892,10 +18158,10 @@ var AgentMonitorService = class _AgentMonitorService {
   }
   async _appendToFile(subagentId, entry) {
     const dir = path18.join(this._transcriptsDir, subagentId);
-    await fs3.mkdir(dir, { recursive: true });
+    await fs4.mkdir(dir, { recursive: true });
     const filePath = path18.join(dir, "transcript.jsonl");
     const line = JSON.stringify(entry) + "\n";
-    await fs3.appendFile(filePath, line, { encoding: "utf8" });
+    await fs4.appendFile(filePath, line, { encoding: "utf8" });
   }
   _uid() {
     return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;