@agenticmail/claudecode 0.2.4 → 0.2.6

package/dist/chunk-QSR32ZGW.js

@@ -0,0 +1,1367 @@
+import {
+  listAccounts,
+  renderPersonaBody,
+  resolveConfig
+} from "./chunk-SBP7MJP2.js";
+
+// src/persona-loader.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+function sanitizeSubagentName(name) {
+  return name.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function stripFrontmatter(raw) {
+  const text = raw.replace(/\r\n/g, "\n");
+  if (!text.startsWith("---\n")) return text;
+  const close = text.indexOf("\n---", 4);
+  if (close < 0) return text;
+  let cursor = close + 4;
+  while (cursor < text.length && (text[cursor] === "\n" || text[cursor] === "\r")) cursor++;
+  return text.slice(cursor);
+}
+function loadPersonaForAgent(opts) {
+  const { agent, agentsDir, subagentPrefix, mcpServerName } = opts;
+  const basename = sanitizeSubagentName(`${subagentPrefix}${agent.name}`);
+  const filePath = join(agentsDir, `${basename}.md`);
+  if (existsSync(filePath)) {
+    try {
+      const raw = readFileSync(filePath, "utf-8");
+      const body2 = stripFrontmatter(raw).trim();
+      if (body2) return { body: body2, source: "file", filePath };
+    } catch {
+    }
+  }
+  const body = renderPersonaBody({ name: basename, agent, mcpServerName });
+  return { body, source: "generated" };
+}
+
+// src/dispatcher.ts
+import { mkdirSync, createWriteStream, rmSync } from "fs";
+import { join as join2 } from "path";
+import { homedir } from "os";
+import { ThreadCache, AgentMemoryStore, threadIdFor, normalizeSubject } from "@agenticmail/core";
+function extractSubject(event) {
+  if (typeof event.subject === "string") return event.subject;
+  if (event.message && typeof event.message.subject === "string") return event.message.subject;
+  return void 0;
+}
+function extractFrom(event) {
+  if (typeof event.from === "string") return event.from;
+  if (event.message && Array.isArray(event.message.from)) {
+    const first = event.message.from[0];
+    if (first?.address) return first.address;
+    if (first?.name) return first.name;
+  }
+  return void 0;
+}
+function extractWakeAllowlist(event) {
+  const raw = event.wakeAllowlist;
+  if (raw === void 0) return void 0;
+  if (!Array.isArray(raw)) return void 0;
+  return raw.map((x) => String(x).trim().toLowerCase()).filter(Boolean);
+}
+function isAgentOnWakeAllowlist(accountName, list) {
+  if (list === void 0) return true;
+  if (list.length === 0) return false;
+  return list.includes(accountName.trim().toLowerCase());
+}
+var SEEN_CAP = 1024;
+function rememberBounded(set, item) {
+  set.add(item);
+  if (set.size > SEEN_CAP) {
+    const drop = Array.from(set).slice(0, Math.floor(SEEN_CAP / 2));
+    for (const x of drop) set.delete(x);
+  }
+}
+var DEFAULT_MAX_CONCURRENT = 50;
+var DEFAULT_SYNC_INTERVAL_MS = 3e4;
+var DEFAULT_RECONNECT_BASE_MS = 2e3;
+var DEFAULT_RECONNECT_MAX_MS = 6e4;
+var TASK_MAIL_SUPPRESS_WINDOW_MS = 3e4;
+var TASK_NOTIFICATION_SUBJECT_PREFIXES = ["[RPC]", "[Task]", "[Async-RPC]"];
+function isTaskNotificationSubject(subject) {
+  if (!subject) return false;
+  const head = subject.trimStart();
+  for (const prefix of TASK_NOTIFICATION_SUBJECT_PREFIXES) {
+    if (head.toLowerCase().startsWith(prefix.toLowerCase())) return true;
+  }
+  return false;
+}
+var THREAD_CLOSED_MARKERS = ["[FINAL]", "[DONE]", "[CLOSED]", "[WRAP]"];
+function isThreadClosedSubject(subject) {
+  if (!subject) return false;
+  const s = subject.toLowerCase();
+  return THREAD_CLOSED_MARKERS.some((m) => s.includes(m.toLowerCase()));
+}
+function threadIdFromSubject(subject) {
+  if (!subject) return "";
+  let s = subject.trim();
+  while (true) {
+    const next = s.replace(/^(re|fwd?|fw)(\[\d+\])?:\s*/i, "");
+    if (next === s) break;
+    s = next;
+  }
+  return s.toLowerCase().trim();
+}
+var DEFAULT_MAX_WAKES_PER_THREAD = 10;
+var DEFAULT_WAKE_WINDOW_MS = 24 * 60 * 60 * 1e3;
+var DEFAULT_WAKE_COALESCE_MS = 3e4;
+async function runWorkerWithCompaction(query, persona, initialPrompt, agent, mcpServerName, mcpCommand, mcpArgs, mcpEnv, log, observer, cwd, maxIterations = 4) {
+  let prompt = initialPrompt;
+  let lastResult = null;
+  const breadcrumbs = [];
+  const captureObserver = {
+    onMessage(tag, summary) {
+      observer.onMessage(tag, summary);
+      if (tag === "tool_use") breadcrumbs.push(`\u2713 ${summary}`);
+      else if (tag === "tool_result") breadcrumbs.push(`  \u2192 ${summary}`);
+    }
+  };
+  for (let iter = 0; iter < maxIterations; iter++) {
+    if (iter > 0) {
+      log("info", `[dispatcher] compaction iter ${iter + 1}/${maxIterations} for "${agent.name}"`);
+    }
+    lastResult = await runWorker(
+      query,
+      persona,
+      prompt,
+      agent,
+      mcpServerName,
+      mcpCommand,
+      mcpArgs,
+      mcpEnv,
+      log,
+      void 0,
+      captureObserver,
+      cwd
+    );
+    if (lastResult.ok) return lastResult;
+    if (!isContextOverflowError(lastResult.error)) return lastResult;
+    if (iter === maxIterations - 1) {
+      return { ok: false, error: `compaction budget exhausted (${maxIterations} iters): ${lastResult.error}` };
+    }
+    const checkpoint = breadcrumbs.slice(-40).join("\n");
+    prompt = [
+      initialPrompt,
+      "",
+      "## Resuming after context reset",
+      "",
+      "You hit the model context limit on the previous turn. Here is a",
+      "breadcrumb of what you already accomplished in that turn \u2014",
+      "do NOT redo any of these steps:",
+      "",
+      checkpoint || "(no breadcrumbs captured)",
+      "",
+      "Continue from where you left off. If you have already produced",
+      "the final deliverable on the previous turn (e.g. submit_result,",
+      "reply_email), do nothing this turn and end cleanly."
+    ].join("\n");
+    log("info", `[dispatcher] context overflow on "${agent.name}" \u2014 compacting (${breadcrumbs.length} breadcrumbs)`);
+  }
+  return lastResult ?? { ok: false, error: "worker did not run" };
+}
+function isContextOverflowError(msg) {
+  const m = msg.toLowerCase();
+  return m.includes("prompt is too long") || m.includes("context_length_exceeded") || m.includes("context length exceeded") || m.includes("max tokens") || m.includes("maximum context") || m.includes("token limit");
+}
+async function runWorker(query, persona, userPrompt, agent, mcpServerName, mcpCommand, mcpArgs, mcpEnv, log, abortSignal, observer, cwd) {
+  const opts = {
+    systemPrompt: persona,
+    mcpServers: {
+      [mcpServerName]: {
+        command: mcpCommand,
+        args: mcpArgs,
+        env: mcpEnv
+      }
+    },
+    // No `allowedTools` restriction.
+    //
+    // Earlier versions of the dispatcher locked workers to MCP-only tools
+    // ("you operate an email account, not a developer environment"). That
+    // was the wrong design: AgenticMail agents are real Claude Code
+    // subagents running under the host's OAuth, and the work humans
+    // delegate to them (write code, run tests, do research, edit files)
+    // demands the full native toolset (Read, Write, Edit, Bash, Glob,
+    // Grep, WebFetch, WebSearch, NotebookEdit, …). Restricting them
+    // turned "Zephyr implements the game" into "Zephyr emails source
+    // code as plaintext and the human has to copy-paste it" — which
+    // defeats the point of having agents in the first place.
+    //
+    // Omitting allowedTools lets the SDK fall through to its defaults
+    // (all built-in tools + every tool exposed by the MCP servers we
+    // declare above). Outbound mail is still guarded by AgenticMail's
+    // own outbound guard (HIGH-severity sends held for owner approval)
+    // and the worker is sandboxed by Claude Code's permission system
+    // just like any other subagent.
+    permissionMode: "bypassPermissions",
+    abortController: abortSignal ? wrapSignal(abortSignal) : void 0
+  };
+  if (cwd) opts.cwd = cwd;
+  const collectedText = [];
+  try {
+    for await (const msg of query({ prompt: userPrompt, options: opts })) {
+      const m = msg;
+      if (m.type === "assistant" && Array.isArray(m.message && m.message.content)) {
+        for (const block of m.message.content) {
+          const b = block;
+          if (b.type === "text" && typeof b.text === "string") {
+            collectedText.push(b.text);
+            if (observer) observer.onMessage("assistant", b.text.slice(0, 240).replace(/\s+/g, " ").trim());
+          } else if (b.type === "tool_use" && typeof b.name === "string") {
+            const inputSummary = (() => {
+              try {
+                return JSON.stringify(b.input).slice(0, 200);
+              } catch {
+                return "(uninspectable input)";
+              }
+            })();
+            if (observer) observer.onMessage("tool_use", `${b.name} ${inputSummary}`);
+          }
+        }
+      } else if (m.type === "user" && Array.isArray(m.message && m.message.content)) {
+        for (const block of m.message.content) {
+          const b = block;
+          if (b.type === "tool_result") {
+            const bodyStr = typeof b.content === "string" ? b.content : Array.isArray(b.content) ? b.content.map((c) => c.text ?? "").join(" ") : "";
+            if (observer) observer.onMessage("tool_result", bodyStr.slice(0, 240).replace(/\s+/g, " ").trim());
+          }
+        }
+      }
+      if (m.type === "result") {
+        const r = m;
+        if (typeof r.result === "string") {
+          collectedText.push(r.result);
+          if (observer) observer.onMessage("result", r.result.slice(0, 240).replace(/\s+/g, " ").trim());
+        }
+        if (r.usage && observer) {
+          const u = r.usage;
+          const summary = `in=${u.input_tokens ?? 0} out=${u.output_tokens ?? 0} cacheR=${u.cache_read_input_tokens ?? 0} cacheW=${u.cache_creation_input_tokens ?? 0}${typeof r.total_cost_usd === "number" ? ` cost=$${r.total_cost_usd.toFixed(4)}` : ""}`;
+          observer.onMessage("usage", summary);
+        }
+      }
+    }
+    const text = collectedText.join("\n").trim();
+    log("info", `[dispatcher] worker for "${agent.name}" finished (${text.length} chars output)`);
+    return { ok: true, text };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log("error", `[dispatcher] worker for "${agent.name}" failed: ${msg}`);
+    if (observer) observer.onMessage("error", msg);
+    return { ok: false, error: msg };
+  }
+}
+function wrapSignal(signal) {
+  const c = new AbortController();
+  if (signal.aborted) c.abort();
+  else signal.addEventListener("abort", () => c.abort(), { once: true });
+  return c;
+}
+function newMailPromptForBatch(agent, events) {
+  const lines = [];
+  const count = events.length;
+  lines.push(`You have ${count} new messages on this thread (coalesced \u2014 they arrived in a burst and you are seeing them in one turn).`);
+  lines.push("");
+  lines.push("### Burst details");
+  for (const ev of events) {
+    const f = extractFrom(ev) ?? "unknown";
+    const s = extractSubject(ev) ?? "(no subject)";
+    lines.push(`- UID ${ev.uid ?? "?"} \xB7 ${f} \xB7 "${s}"`);
+  }
+  lines.push("");
+  lines.push(`The LATEST message in the burst is UID ${events[events.length - 1].uid ?? "?"}.`);
+  lines.push("Read it first (and any others on the thread you have not yet seen). Then decide:");
+  lines.push("- If the burst is multiple replies converging on one ask, respond ONCE on the thread.");
+  lines.push("- If the burst is genuinely N independent asks addressed to you, handle them in one reply where possible.");
+  lines.push("- If your prior work already addressed the burst, do NOT repeat yourself \u2014 stay silent for this wake.");
+  lines.push("");
+  lines.push("Reuse the standard thread-aware coordination protocol below; the only difference is the batch shape.");
+  lines.push("");
+  const latest = events[events.length - 1];
+  lines.push(newMailPrompt(agent, latest));
+  return lines.join("\n");
+}
+function newMailPrompt(agent, event) {
+  const from = extractFrom(event) ?? "unknown sender";
+  const subject = extractSubject(event) ?? "(no subject)";
+  const uid = event.uid;
+  return [
+    `You have new mail.`,
+    ``,
+    `- From: ${from}`,
+    `- Subject: ${subject}`,
+    uid ? `- UID: ${uid}` : "",
+    ``,
+    `## Thread-aware coordination protocol`,
+    ``,
+    `You are ${agent.name}. Multiple agents may be CC'd on the same thread \u2014`,
+    `that is intentional: a thread is the shared workspace, and turn-taking is`,
+    `implicit from context (who was addressed last, whose stage of the workflow`,
+    `is next, who was @mentioned). Follow these steps in order:`,
+    ``,
+    `1. **Read this message.** read_email({ uid: ${uid ?? "<uid>"}, _account: "${agent.name}" }).`,
+    ``,
+    `2. **If this is a reply (Subject starts with "Re:" or an In-Reply-To header is present), load the rest of the thread.**`,
+    `   Use search_emails({ subject: "<core subject without Re:>", _account: "${agent.name}" })`,
+    `   to surface earlier messages in the thread, then read_email each prior UID.`,
+    `   You MUST read the full thread before deciding what to do.`,
+    ``,
+    `3. **CHECK YOUR PRIOR CONTRIBUTIONS to this thread.** When you searched`,
+    `   in step 2, look at how many of the messages were sent BY YOU`,
+    `   (from: ${agent.email}). If you have already contributed your work`,
+    `   to this thread, **do NOT redo it on a new wake**. Redelivering`,
+    `   identical content when a teammate posts an update is the most`,
+    `   common multi-agent failure mode \u2014 it triples noise and wastes`,
+    `   tokens. Only re-contribute if EITHER:`,
+    `     (a) the latest reply contains a NEW specific ask addressed to`,
+    `         you by name and you have not yet answered THAT ask, OR`,
+    `     (b) a teammate's reply genuinely changes the picture and your`,
+    `         prior work needs an explicit revision (not a re-post).`,
+    `   Otherwise stay silent.`,
+    ``,
+    `4. **Identify the participants.** Look at To + CC across the thread. Those`,
+    `   are your collaborators. Their names map to AgenticMail agents at`,
+    `   <name>@localhost. They will each be woken on every reply-all the same way you were.`,
+    ``,
+    `5. **Decide: is it MY turn?** Yes if any of:`,
+    `     - The latest message addresses you by name ("Vesper, please \u2026", "@${agent.name} \u2026").`,
+    `     - The previous-stage handoff is to your role (e.g. designer \u2192 developer, and you are the developer).`,
+    `     - You were directly asked a question and nobody has answered yet.`,
+    `   No if:`,
+    `     - The current ask is targeted at a teammate (their turn, not yours).`,
+    `     - **A teammate replied within the last 60 seconds.** They are likely`,
+    `       already handling this turn; jumping in creates simultaneous replies`,
+    `       and confusion. Assume good faith and stay silent unless their reply`,
+    `       was clearly off-target.`,
+    `     - You have nothing substantive to add right now.`,
+    `   When in doubt, stay silent \u2014 over-replying creates noise. Better to let`,
+    `   the right teammate take the turn than to step on theirs.`,
+    ``,
+    `6. **If it's your turn \u2014 do the actual work, THEN reply-all about it.**`,
+    `   You have full native tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch,`,
+    `   WebSearch, NotebookEdit, etc. If the task is "implement X", write the file`,
+    `   with Write or Edit and verify with Bash \u2014 do NOT paste source code into an`,
+    `   email body and call it shipped. The thread is for COORDINATION ("done,`,
+    `   see ./foo.py, runs with \`python3 foo.py\`"); the filesystem is for`,
+    `   DELIVERABLES. Then:`,
+    `     reply_email({ uid: ${uid ?? "<uid>"}, replyAll: true, text: "...", _account: "${agent.name}" })`,
+    `   Sign with your name. Be substantive but concise.`,
+    ``,
+    `   ## Reply addressing \u2014 CRITICAL for wake control`,
+    `   reply_email({ replyAll: true }) automatically builds the right shape:`,
+    `   the ORIGINAL SENDER ends up on To (so they wake by default),`,
+    `   every other participant ends up on Cc (so they see it without`,
+    `   waking). DO NOT pass a hand-rolled comma-separated address list`,
+    `   via send_email \u2014 that puts every recipient on To and re-wakes`,
+    `   the whole thread, defeating the wake gating. Trust replyAll.`,
+    ``,
+    `   If you want to wake someone OTHER than the original sender`,
+    `   (e.g. you are handing off to a different next actor), name them`,
+    `   explicitly in the reply body ("Orion \u2014 over to you, please\u2026")`,
+    `   AND pass \`wake: ["orion"]\` so the dispatcher gives them a`,
+    `   Claude turn instead. Example:`,
+    `     reply_email({ uid, replyAll: true, text: "Orion \u2014 your turn \u2026",`,
+    `                   wake: ["orion"], _account: "${agent.name}" })`,
+    `   If nobody specific is next (the work is complete and you're just`,
+    `   signing off), pass \`wake: []\` to deliver silently \u2014 every`,
+    `   participant still sees the reply, no Claude turn is spawned.`,
+    ``,
+    `7. **If you need additional help from a teammate not yet on the thread,**`,
+    `   include them by CC'ing in your reply-all \u2014 DO NOT spin up a separate`,
+    `   call_agent / message_agent side-channel. The thread is the workspace;`,
+    `   everyone stays in context.`,
+    ``,
+    `8. **If it's NOT your turn,** mark the message read with mark_read and return.`,
+    `   Do not reply just to acknowledge. Silence IS a valid contribution.`,
+    ``,
+    `## How threads end`,
+    ``,
+    `A thread is done when the host (or any participant) sends a wrap-up`,
+    `message with one of these markers in the subject: \`[FINAL]\`, \`[DONE]\`,`,
+    `\`[CLOSED]\`, \`[WRAP]\`. The dispatcher will stop waking workers on any`,
+    `further replies to that thread. If you are sending a wrap-up yourself`,
+    `(because the work is complete and no more contributions are needed),`,
+    `include one of those markers in your reply subject.`,
+    ``,
+    `When you finish, return a one-line summary of what you did:`,
+    `  "Contributed: <one-line description>"  OR  "Stayed silent \u2014 not my turn."`,
+    ``,
+    `## Fallback for non-thread mail`,
+    ``,
+    `If this is a fresh standalone email (not part of a thread, only addressed`,
+    `to you), handle it directly: answer the question, do the work, reply.`,
+    `Spam: trust the auto-filter unless something obviously slipped through.`
+  ].filter(Boolean).join("\n");
+}
+function taskPrompt(agent, event) {
+  const taskId = event.taskId ?? "(missing taskId)";
+  const taskText = event.task ?? "(no task description)";
+  const taskType = event.taskType ?? "generic";
+  const from = event.from ?? "unknown";
+  return [
+    `You have a pending task \u2014 handle it now.`,
+    ``,
+    `- Task ID: ${taskId}`,
+    `- Type: ${taskType}`,
+    `- From: ${from}`,
+    `- Task: ${taskText}`,
+    ``,
+    `Workflow:`,
+    `  1. Call claim_task({ id: "${taskId}", _account: "${agent.name}" }) to mark yourself as the owner.`,
+    `  2. Do the work using whatever pre-loaded or invoke-able MCP tools fit.`,
+    `  3. Call submit_result({ id: "${taskId}", result: { ... }, _account: "${agent.name}" }) with structured JSON.`,
+    `     The caller is waiting on a synchronous long-poll \u2014 submit_result is what wakes them.`,
+    ``,
+    `If you cannot complete the task, submit_result with { status: "failed", reason: "..." }. Never leave it unclaimed \u2014 that strands the caller until timeout.`
+  ].join("\n");
+}
+var Dispatcher = class {
+  cfg;
+  maxConcurrent;
+  syncIntervalMs;
+  reconnectBaseMs;
+  reconnectMaxMs;
+  query;
+  fetchImpl;
+  log;
+  channels = /* @__PURE__ */ new Map();
+  // keyed by account.id
+  accountSyncTimer = null;
+  systemChannelController = null;
+  running = 0;
+  waiters = [];
+  stopped = false;
+  /**
+   * Wake-budget store, keyed by `${accountId}::${threadId}`. See the
+   * comment block on WakeBudgetEntry for the failure modes this guards.
+   * Pruned opportunistically on each lookup — no separate timer.
+   */
+  wakeBudget = /* @__PURE__ */ new Map();
+  maxWakesPerThread;
+  wakeWindowMs;
+  now;
+  /**
+   * Layered wake-context system. ThreadCache holds the last K
+   * envelopes per thread (built passively on every SSE new-mail
+   * event, even when no agent wakes). AgentMemoryStore holds
+   * per-(agent, thread) markdown that workers write at end-of-
+   * wake via the save_thread_memory MCP tool. Both are read on
+   * worker spawn and injected into the wake prompt — see
+   * spawnWorker for the rendering.
+   */
+  threadCache;
+  agentMemory;
+  /**
+   * Coalesced wake queue. Keyed by `${accountId}::${threadId}`,
+   * each entry holds the pending events + the timer that will
+   * fire the spawn. A new event arriving while the entry exists
+   * EXTENDS the timer (debounce, not throttle) and appends to
+   * the event list. When the timer fires, a single Claude turn
+   * sees the union of new messages and replies once.
+   *
+   * Why debounce + not throttle: bursts of replies from one
+   * sender are typically a single logical handoff, not N
+   * separate actions. Throttling would still produce a stale
+   * wake after the burst settles; debouncing collapses the
+   * whole burst into one wake at the trailing edge.
+   */
+  wakeCoalesce = /* @__PURE__ */ new Map();
+  wakeCoalesceMs;
+  /** Wall-clock timestamp the dispatcher started. Surfaced via
+   *  process-heartbeat so check_activity can show uptime. */
+  startedAtMs = Date.now();
+  /** Periodic timer that posts a process-heartbeat to the API.
+   *  Without this, a hung dispatcher looks identical to "no
+   *  events to wake on" — the host has no liveness signal. */
+  processHeartbeatTimer = null;
+  constructor(opts = {}) {
+    this.cfg = resolveConfig(opts);
+    this.maxConcurrent = opts.maxConcurrentWorkers ?? DEFAULT_MAX_CONCURRENT;
+    this.syncIntervalMs = opts.accountSyncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS;
+    this.reconnectBaseMs = opts.sseReconnectBaseMs ?? DEFAULT_RECONNECT_BASE_MS;
+    this.reconnectMaxMs = opts.sseReconnectMaxMs ?? DEFAULT_RECONNECT_MAX_MS;
+    this.query = opts.querySdk ?? defaultQuery();
+    this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    this.log = opts.log ?? defaultLog;
+    this.maxWakesPerThread = opts.maxWakesPerThread ?? DEFAULT_MAX_WAKES_PER_THREAD;
+    this.wakeWindowMs = opts.wakeWindowMs ?? DEFAULT_WAKE_WINDOW_MS;
+    this.now = opts.nowMs ?? Date.now;
+    this.threadCache = new ThreadCache({ cacheDir: opts.threadCacheDir });
+    this.agentMemory = new AgentMemoryStore({ memoryDir: opts.agentMemoryDir });
+    this.wakeCoalesceMs = opts.wakeCoalesceMs ?? DEFAULT_WAKE_COALESCE_MS;
+    if (!this.cfg.masterKey) {
+      throw new Error("Dispatcher requires AgenticMail master key. Run `agenticmail setup` first.");
+    }
+  }
+  /**
+   * Charge one wake against the (agent, thread) budget. Returns true
+   * if the wake should proceed, false if the circuit breaker is open.
+   *
+   * Empty threadId means "no thread context" (a fresh standalone email
+   * with no Subject — rare); we always allow those since there is no
+   * thread to runaway on.
+   */
+  chargeWake(accountId, threadId) {
+    if (!threadId) return { ok: true };
+    const key = `${accountId}::${threadId}`;
+    const now = this.now();
+    let entry = this.wakeBudget.get(key);
+    if (entry && now - entry.firstWakeAtMs >= this.wakeWindowMs) {
+      entry = void 0;
+      this.wakeBudget.delete(key);
+    }
+    if (!entry) {
+      entry = { count: 1, firstWakeAtMs: now };
+      this.wakeBudget.set(key, entry);
+      this.maybePruneWakeBudget(now);
+      return { ok: true, count: 1 };
+    }
+    if (entry.count >= this.maxWakesPerThread) {
+      return {
+        ok: false,
+        count: entry.count,
+        mutedUntilMs: entry.firstWakeAtMs + this.wakeWindowMs
+      };
+    }
+    entry.count++;
+    return { ok: true, count: entry.count };
+  }
+  /**
+   * Drop wake-budget entries that have aged out of their window.
+   *
+   * Called inline from chargeWake, but at most once per ~1024 inserts so
+   * the cost stays bounded. We don't need a separate timer because the
+   * Map only grows on real wakes (capped by maxWakesPerThread per pair),
+   * and the prune is O(n) over the current entries — cheap enough.
+   */
+  wakeBudgetInsertsSinceLastPrune = 0;
+  maybePruneWakeBudget(now) {
+    this.wakeBudgetInsertsSinceLastPrune++;
+    if (this.wakeBudgetInsertsSinceLastPrune < 1024) return;
+    this.wakeBudgetInsertsSinceLastPrune = 0;
+    for (const [k, v] of this.wakeBudget) {
+      if (now - v.firstWakeAtMs >= this.wakeWindowMs) this.wakeBudget.delete(k);
+    }
+  }
+  async start() {
+    this.log("info", `[dispatcher] starting (maxConcurrent=${this.maxConcurrent}, syncEvery=${this.syncIntervalMs}ms)`);
+    this.startedAtMs = Date.now();
+    await this.syncAccounts();
+    this.accountSyncTimer = setInterval(() => {
+      this.syncAccounts().catch((err) => this.log("warn", `[dispatcher] account sync failed: ${err}`));
+    }, this.syncIntervalMs);
+    this.processHeartbeatTimer = setInterval(() => {
+      this.postActivity("/dispatcher/process-heartbeat", {
+        startedAtMs: this.startedAtMs,
+        uptimeMs: Date.now() - this.startedAtMs,
+        channels: this.channels.size,
+        coalesceQueueSize: this.wakeCoalesce.size,
+        running: this.running,
+        maxConcurrent: this.maxConcurrent
+      });
+    }, 3e4);
+    this.processHeartbeatTimer.unref?.();
+    this.postActivity("/dispatcher/process-heartbeat", {
+      startedAtMs: this.startedAtMs,
+      uptimeMs: 0,
+      channels: this.channels.size,
+      coalesceQueueSize: 0,
+      running: 0,
+      maxConcurrent: this.maxConcurrent
+    });
+    void this.runSystemChannel();
+  }
+  async stop() {
+    this.stopped = true;
+    if (this.accountSyncTimer) clearInterval(this.accountSyncTimer);
+    this.accountSyncTimer = null;
+    if (this.processHeartbeatTimer) clearInterval(this.processHeartbeatTimer);
+    this.processHeartbeatTimer = null;
+    if (this.systemChannelController) {
+      try {
+        this.systemChannelController.abort();
+      } catch {
+      }
+      this.systemChannelController = null;
+    }
+    for (const ch of this.channels.values()) {
+      ch.stopping = true;
+      ch.controller?.abort();
+    }
+    this.channels.clear();
+    for (const entry of this.wakeCoalesce.values()) clearTimeout(entry.timer);
+    this.wakeCoalesce.clear();
+    this.log("info", "[dispatcher] stopped");
+  }
+  /** Public for tests — directly hand an event to the routing path. */
+  async handleEvent(account, event) {
+    if (this.stopped) return;
+    if (event.type === "new" && typeof event.uid === "number") {
+      const ch = this.channels.get(account.id);
+      if (ch?.seenUids.has(event.uid)) return;
+      const subject = extractSubject(event);
+      const cacheThreadId = threadIdFor({ subject });
+      try {
+        const fromAddr = extractFrom(event) ?? "(unknown)";
+        const previewSource = event.preview ?? event.message?.preview ?? "";
+        this.threadCache.pushMessage(cacheThreadId, {
+          uid: event.uid,
+          from: fromAddr,
+          fromAddr,
+          subject: subject ?? "(no subject)",
+          preview: typeof previewSource === "string" ? previewSource : "",
+          date: (/* @__PURE__ */ new Date()).toISOString()
+        }, {
+          subject: normalizeSubject(subject),
+          rootFromAddr: fromAddr
+        });
+      } catch (err) {
+        this.log("warn", `[dispatcher] thread-cache push failed for "${account.name}" uid=${event.uid}: ${err.message}`);
+      }
+      if (ch && Date.now() < ch.suppressTaskMailUntilMs && isTaskNotificationSubject(subject)) {
+        this.log("info", `[dispatcher] suppressed task-notification mail wake for "${account.name}" (uid=${event.uid}, subject="${subject}") \u2014 task event already dispatched`);
+        rememberBounded(ch.seenUids, event.uid);
+        return;
+      }
+      if (ch) rememberBounded(ch.seenUids, event.uid);
+      if (isThreadClosedSubject(subject)) {
+        this.log("info", `[dispatcher] thread closed (subject="${subject ?? ""}") \u2014 skipping wake for "${account.name}" uid=${event.uid}`);
+        this.postSkipped(account, event, "thread-closed", `subject contains a thread-close marker: "${subject ?? ""}"`);
+        try {
+          this.threadCache.delete(cacheThreadId);
+        } catch {
+        }
+        try {
+          this.agentMemory.delete(account.id, cacheThreadId);
+        } catch {
+        }
+        return;
+      }
+      const allowlist = extractWakeAllowlist(event);
+      if (!isAgentOnWakeAllowlist(account.name, allowlist)) {
+        this.log("info", `[dispatcher] wake allowlist excludes "${account.name}" (list=${JSON.stringify(allowlist)}) \u2014 mail delivered, no Claude turn`);
+        this.postSkipped(account, event, "allowlist-excluded", `wake list ${JSON.stringify(allowlist)} did not include "${account.name}"`);
+        return;
+      }
+      const wakeOnCc = account.wakeOnCc !== false;
+      if (!wakeOnCc) {
+        const wasOnTo = event.wasOnTo === true;
+        if (!wasOnTo) {
+          this.log("info", `[dispatcher] "${account.name}" has wake_on_cc:false and was not on To \u2014 mail delivered, no Claude turn (uid=${event.uid})`);
+          this.postSkipped(account, event, "wake-on-cc", `"${account.name}" has wake_on_cc:false; not on To`);
+          return;
+        }
+      }
+      const threadId = threadIdFromSubject(subject);
+      await this.scheduleCoalescedWake(account, event, threadId);
+      return;
+    }
+    if (event.type === "task" && typeof event.taskId === "string") {
+      if (typeof event.assignee === "string" && event.assignee.toLowerCase() !== account.name.toLowerCase()) return;
+      const ch = this.channels.get(account.id);
+      if (ch?.seenTaskIds.has(event.taskId)) return;
+      if (ch) {
+        rememberBounded(ch.seenTaskIds, event.taskId);
+        ch.suppressTaskMailUntilMs = Date.now() + TASK_MAIL_SUPPRESS_WINDOW_MS;
+      }
+      await this.spawnWorker(account, taskPrompt(account, event), {
+        kind: "task",
+        taskId: event.taskId,
+        subject: typeof event.task === "string" ? event.task.slice(0, 120) : void 0,
+        from: typeof event.from === "string" ? event.from : void 0
+      });
+      return;
+    }
+  }
+  /**
+   * Should the dispatcher own a wake-channel for this account?
+   *
+   * We skip the bridge agent (default name "claudecode"). The bridge is
+   * the host session's own inbox proxy — when mail lands there, the
+   * HOST Claude Code session reads it via MCP (`list_inbox` /
+   * `wait_for_email` / `read_email`), NOT via a separately-spawned
+   * dispatcher worker. Spawning a worker for the bridge would:
+   *   1. Compete with the host (two Claude instances trying to "be"
+   *      Claude Code, both potentially replying autonomously).
+   *   2. Waste tokens — the host is already aware via its MCP polling.
+   *   3. Send the bridge into an autonomous loop if it ever replies-all
+   *      (because that mail would wake it again, ad infinitum).
+   *
+   * Role="bridge" is also skipped for symmetry with selectExposableAgents
+   * in install.ts — anything tagged as a bridge is host-managed.
+   */
+  shouldWatch(account) {
+    const bridgeName = this.cfg.bridgeAgentName.toLowerCase();
+    if (account.name.toLowerCase() === bridgeName) return false;
+    if (account.role === "bridge") return false;
+    return true;
+  }
+  /** Re-fetch /accounts; open SSE for new ones, close for vanished ones. */
+  async syncAccounts() {
+    let accounts;
+    try {
+      accounts = await listAccounts(this.cfg.apiUrl, this.cfg.masterKey);
+    } catch (err) {
+      this.log("warn", `[dispatcher] could not list accounts: ${err.message}`);
+      return;
+    }
+    accounts = accounts.filter((a) => this.shouldWatch(a));
+    const liveIds = new Set(accounts.map((a) => a.id));
+    for (const [id, ch] of this.channels) {
+      if (!liveIds.has(id)) {
+        ch.stopping = true;
+        ch.controller?.abort();
+        this.channels.delete(id);
+        this.log("info", `[dispatcher] account "${ch.account.name}" removed \u2014 closed SSE channel`);
+      }
+    }
+    for (const account of accounts) {
+      if (this.channels.has(account.id)) {
+        this.channels.get(account.id).account = account;
+        continue;
+      }
+      const ch = {
+        account,
+        controller: null,
+        stopping: false,
+        backoffMs: this.reconnectBaseMs,
+        seenUids: /* @__PURE__ */ new Set(),
+        seenTaskIds: /* @__PURE__ */ new Set(),
+        suppressTaskMailUntilMs: 0
+      };
+      this.channels.set(account.id, ch);
+      this.log("info", `[dispatcher] opening SSE for "${account.name}" (${account.email})`);
+      void this.runChannel(ch);
+    }
+  }
+  /**
+   * Subscribe to the API's master-scoped system events SSE.
+   *
+   * Pushes from /system/events arrive as JSON-per-frame just like the
+   * per-account stream:
+   *   { type: "connected" }
+   *   { type: "account_created", account: { id, name, email, apiKey, ... } }
+   *   { type: "account_deleted", accountId, name }
+   *
+   * On `account_created` we eagerly open a per-account SSE channel using
+   * the apiKey carried in the event payload — no extra round trip, the
+   * channel is live within milliseconds of the POST /accounts response.
+   *
+   * Reconnect with the same exponential backoff scheme as per-account
+   * channels. If the API is older and doesn't expose /system/events
+   * (404), we log once and stop trying — polling-only fallback still
+   * works.
+   */
+  async runSystemChannel() {
+    let backoff = this.reconnectBaseMs;
+    let giveUp = false;
+    while (!this.stopped && !giveUp) {
+      this.systemChannelController = new AbortController();
+      try {
+        const url = `${this.cfg.apiUrl.replace(/\/$/, "")}/api/agenticmail/system/events`;
+        const res = await this.fetchImpl(url, {
+          headers: {
+            "Authorization": `Bearer ${this.cfg.masterKey}`,
+            "Accept": "text/event-stream"
+          },
+          signal: this.systemChannelController.signal
+        });
+        if (res.status === 404) {
+          this.log("warn", "[dispatcher] /system/events not available on this API \u2014 falling back to polling-only account discovery (please upgrade @agenticmail/api to >=0.7.3)");
+          giveUp = true;
+          break;
+        }
+        if (!res.ok || !res.body) {
+          throw new Error(`system/events HTTP ${res.status}`);
+        }
+        backoff = this.reconnectBaseMs;
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        while (!this.stopped) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          let boundary;
+          while ((boundary = buffer.indexOf("\n\n")) !== -1) {
+            const frame = buffer.slice(0, boundary);
+            buffer = buffer.slice(boundary + 2);
+            for (const line of frame.split("\n")) {
+              if (!line.startsWith("data: ")) continue;
+              try {
+                const event = JSON.parse(line.slice(6));
+                this.handleSystemEvent(event);
+              } catch {
+              }
+            }
+          }
+        }
+      } catch (err) {
+        if (this.stopped) break;
+        this.log("warn", `[dispatcher] system-events stream error: ${err.message}; reconnecting in ${backoff}ms`);
+      }
+      if (this.stopped || giveUp) break;
+      await sleep(backoff);
+      backoff = Math.min(backoff * 2, this.reconnectMaxMs);
+    }
+  }
+  /** Apply an account-lifecycle event from /system/events. */
+  handleSystemEvent(event) {
+    const type = typeof event.type === "string" ? event.type : "";
+    if (type === "account_created" && event.account && typeof event.account === "object") {
+      const account = event.account;
+      if (!account.id || !account.name || !account.apiKey) {
+        this.log("warn", "[dispatcher] account_created event missing required fields; ignoring");
+        return;
+      }
+      if (!this.shouldWatch(account)) {
+        this.log("info", `[dispatcher] account_created "${account.name}" \u2014 skipping (bridge/role excluded)`);
+        return;
+      }
+      if (this.channels.has(account.id)) return;
+      const ch = {
+        account,
+        controller: null,
+        stopping: false,
+        backoffMs: this.reconnectBaseMs,
+        seenUids: /* @__PURE__ */ new Set(),
+        seenTaskIds: /* @__PURE__ */ new Set(),
+        suppressTaskMailUntilMs: 0
+      };
+      this.channels.set(account.id, ch);
+      this.log("info", `[dispatcher] account_created "${account.name}" (${account.email}) \u2014 opening SSE channel immediately`);
+      void this.runChannel(ch);
+      return;
+    }
+    if (type === "account_deleted" && typeof event.accountId === "string") {
+      const ch = this.channels.get(event.accountId);
+      if (!ch) return;
+      ch.stopping = true;
+      try {
+        ch.controller?.abort();
+      } catch {
+      }
+      this.channels.delete(event.accountId);
+      this.log("info", `[dispatcher] account_deleted "${ch.account.name}" \u2014 closed SSE channel`);
+      return;
+    }
+  }
+  /** Watch one account's SSE stream forever; reconnect with backoff on drop. */
+  async runChannel(ch) {
+    while (!ch.stopping && !this.stopped) {
+      try {
+        ch.controller = new AbortController();
+        await this.streamOne(ch);
+        if (!ch.stopping) {
+          this.log("warn", `[dispatcher] SSE for "${ch.account.name}" ended unexpectedly; reconnecting in ${ch.backoffMs}ms`);
+        }
+      } catch (err) {
+        if (ch.stopping) break;
+        this.log("warn", `[dispatcher] SSE error for "${ch.account.name}": ${err.message}; reconnecting in ${ch.backoffMs}ms`);
+      }
+      if (ch.stopping) break;
+      await sleep(ch.backoffMs);
+      ch.backoffMs = Math.min(ch.backoffMs * 2, this.reconnectMaxMs);
+    }
+  }
+  /** Single SSE attach. Returns when the stream closes for any reason. */
+  async streamOne(ch) {
+    const url = `${this.cfg.apiUrl.replace(/\/$/, "")}/api/agenticmail/events`;
+    const res = await this.fetchImpl(url, {
+      headers: {
+        "Authorization": `Bearer ${ch.account.apiKey}`,
+        "Accept": "text/event-stream"
+      },
+      signal: ch.controller.signal
+    });
+    if (!res.ok || !res.body) {
+      throw new Error(`SSE handshake HTTP ${res.status}`);
+    }
+    ch.backoffMs = this.reconnectBaseMs;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    while (!ch.stopping) {
+      const { value, done } = await reader.read();
+      if (done) return;
+      buffer += decoder.decode(value, { stream: true });
+      let boundary;
+      while ((boundary = buffer.indexOf("\n\n")) !== -1) {
+        const frame = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        for (const line of frame.split("\n")) {
+          if (!line.startsWith("data: ")) continue;
+          let event;
+          try {
+            event = JSON.parse(line.slice(6));
+          } catch {
+            continue;
+          }
+          this.handleEvent(ch.account, event).catch(
+            (err) => this.log("error", `[dispatcher] handleEvent threw for "${ch.account.name}": ${err}`)
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Enqueue (or extend) a wake for `(account, thread)`. First
+   * event creates the entry + starts the debounce timer; every
+   * subsequent event within the window APPENDS to the event
+   * list and EXTENDS the timer to `now + wakeCoalesceMs`.
+   *
+   * When the timer fires, `fireCoalescedWake` synthesises a
+   * single wake prompt covering every event that arrived in
+   * the burst and spawns one worker. The wake-budget is
+   * charged ONCE for the batch (a burst of 4 replies is one
+   * logical handoff, not four).
+   *
+   * When `wakeCoalesceMs` is 0 (test mode / opt-out), we skip
+   * the queue and spawn immediately to keep the pre-0.9.0
+   * one-event-per-wake semantics.
+   */
+  async scheduleCoalescedWake(account, event, threadId) {
+    if (this.wakeCoalesceMs <= 0) {
+      await this.fireWakeImmediately(account, event, threadId);
+      return;
+    }
+    const key = `${account.id}::${threadId}`;
+    const existing = this.wakeCoalesce.get(key);
+    if (!existing) {
+      const entry = {
+        events: [],
+        // empty — first event already fired
+        account,
+        threadId,
+        firstScheduledAt: this.now(),
+        timer: setTimeout(() => this.fireCoalescedWake(key), this.wakeCoalesceMs)
+      };
+      entry.timer.unref?.();
+      this.wakeCoalesce.set(key, entry);
+      await this.fireWakeImmediately(account, event, threadId);
+      return;
+    }
+    clearTimeout(existing.timer);
+    existing.events.push(event);
+    this.postActivity("/dispatcher/worker-queued", {
+      agentName: account.name,
+      agentId: account.id,
+      threadId,
+      queuedCount: existing.events.length,
+      fireAtMs: this.now() + this.wakeCoalesceMs,
+      reason: "coalescing subsequent burst events"
+    });
+    existing.timer = setTimeout(() => this.fireCoalescedWake(key), this.wakeCoalesceMs);
+    existing.timer.unref?.();
+    const elapsedFromFirst = this.now() - existing.firstScheduledAt;
+    if (elapsedFromFirst > this.wakeCoalesceMs * 5) {
+      clearTimeout(existing.timer);
+      this.fireCoalescedWake(key);
+    }
+  }
+  /**
+   * Pre-0.9.0 fast path used when coalescing is disabled. Same
+   * spawn that scheduleCoalescedWake/fireCoalescedWake would do
+   * for a single-event batch.
+   */
+  async fireWakeImmediately(account, event, threadId) {
+    const verdict = this.chargeWake(account.id, threadId);
+    if (!verdict.ok) {
+      this.log("warn", `[dispatcher] wake-budget exhausted for "${account.name}" on thread "${threadId}" \u2014 dropped uid=${event.uid}`);
+      this.postSkipped(account, event, "budget-exhausted", `wake budget exhausted for thread "${threadId}" (count=${verdict.count}, cap=${this.maxWakesPerThread})`);
+      return;
+    }
+    await this.spawnWorker(account, newMailPrompt(account, event), {
+      kind: "new-mail",
+      uid: event.uid,
+      subject: extractSubject(event),
+      from: extractFrom(event)
+    });
+  }
+  /**
+   * Timer callback for the coalesced wake. Builds a single wake
+   * prompt that summarises every event in the batch and fires
+   * one worker. Wake budget is charged once for the batch.
+   */
+  fireCoalescedWake(key) {
+    const entry = this.wakeCoalesce.get(key);
+    if (!entry) return;
+    this.wakeCoalesce.delete(key);
+    if (this.stopped) return;
+    if (entry.events.length === 0) return;
+    const verdict = this.chargeWake(entry.account.id, entry.threadId);
+    if (!verdict.ok) {
+      this.log("warn", `[dispatcher] wake-budget exhausted for "${entry.account.name}" on thread "${entry.threadId}" \u2014 dropped batch of ${entry.events.length}`);
+      return;
+    }
+    const lastEvent = entry.events[entry.events.length - 1];
+    const prompt = entry.events.length === 1 ? newMailPrompt(entry.account, lastEvent) : newMailPromptForBatch(entry.account, entry.events);
+    if (entry.events.length > 1) {
+      this.log("info", `[dispatcher] coalesced ${entry.events.length} wakes into one Claude turn for "${entry.account.name}" on thread "${entry.threadId}"`);
+    }
+    void this.spawnWorker(entry.account, prompt, {
+      kind: "new-mail",
+      uid: lastEvent.uid,
+      subject: extractSubject(lastEvent),
+      from: extractFrom(lastEvent)
+    });
+  }
+  /**
+   * Prepend the thread-context block (cache + memory) to the
+   * wake prompt for a given account. Returns the prompt
+   * unchanged when neither layer has content — the very first
+   * wake on a brand-new thread shouldn't show the agent an
+   * empty "Thread context" section that screams "you've seen
+   * this before" when there's nothing to see.
+   *
+   * Exposed as a separate method so tests can drive it
+   * directly without invoking the SDK.
+   */
+  composeWakePromptWithContext(account, ctx, prompt) {
+    if (ctx.kind !== "new-mail" && ctx.kind !== "task") return prompt;
+    const t = threadIdFor({ subject: ctx.subject });
+    let cacheBlock = "";
+    let memoryBlock = "";
+    try {
+      const entry = this.threadCache.read(t);
+      if (entry) {
+        const filtered = ctx.uid ? { ...entry, messages: entry.messages.filter((m) => m.uid !== ctx.uid) } : entry;
+        cacheBlock = filtered.messages.length > 0 ? this.threadCache.renderForPrompt(filtered) : "";
+      }
+    } catch {
+    }
+    try {
+      memoryBlock = this.agentMemory.renderForPrompt(this.agentMemory.read(account.id, t));
+    } catch {
+    }
+    if (!cacheBlock && !memoryBlock) return prompt;
+    const sections = [
+      "## Thread context",
+      "",
+      "You have seen this thread before. The two blocks below are",
+      "your shortcut to context \u2014 DO NOT re-read every prior message",
+      "on this thread. Read only the NEW event at the bottom of this",
+      "prompt and decide based on these blocks plus that event.",
+      ""
+    ];
+    if (cacheBlock) {
+      sections.push("### Facts (last messages on this thread, newest first)");
+      sections.push(cacheBlock);
+      sections.push("");
+    }
+    if (memoryBlock) {
+      sections.push("### Your own memory of this thread");
+      sections.push(memoryBlock);
+      sections.push("");
+    }
+    sections.push("## NEW event");
+    sections.push("");
+    sections.push(prompt);
+    sections.push("");
+    sections.push("---");
+    sections.push("At end of turn, call `save_thread_memory` with `threadId`,");
+    sections.push("a one-paragraph `summary` of where the thread stands, your");
+    sections.push("current `commitments`, any `openQuestions`, your `lastAction`,");
+    sections.push("and the newest `lastUid` you have digested. Future wakes on");
+    sections.push("this thread will load that memory into context for you.");
+    return sections.join("\n");
+  }
+  /** Acquire a concurrency slot, run a worker, release the slot. */
+  async spawnWorker(account, prompt, ctx) {
+    const releaseAgentLock = await this.acquireAgentSerial(account.id);
+    await this.acquireSlot();
+    const workerId = `${account.id}:${ctx.kind}:${ctx.uid ?? ctx.taskId ?? ""}:${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    let workerResult = null;
+    this.postActivity("/dispatcher/worker-started", {
+      workerId,
+      agentName: account.name,
+      agentEmail: account.email,
+      kind: ctx.kind,
+      trigger: { uid: ctx.uid, taskId: ctx.taskId, subject: ctx.subject, from: ctx.from }
+    });
+    const logsDir = join2(homedir(), ".agenticmail", "worker-logs");
+    try {
+      mkdirSync(logsDir, { recursive: true });
+    } catch {
+    }
+    const logPath = join2(logsDir, `${sanitizeId(workerId)}.log`);
+    let logStream = null;
+    try {
+      logStream = createWriteStream(logPath, { flags: "a" });
+    } catch {
+    }
+    const writeLog = (line) => {
+      try {
+        logStream?.write(`[${(/* @__PURE__ */ new Date()).toISOString()}] ${line}
+`);
+      } catch {
+      }
+    };
+    writeLog(`worker_started agent=${account.name} kind=${ctx.kind}${ctx.uid ? " uid=" + ctx.uid : ""}${ctx.taskId ? " task=" + ctx.taskId : ""}`);
+    const cwdDir = join2(homedir(), ".agenticmail", "worker-cwds", sanitizeId(workerId));
+    try {
+      mkdirSync(cwdDir, { recursive: true });
+    } catch {
+    }
+    let turnCount = 0;
+    let lastTool = "";
+    let lastUsage;
+    const digestedUids = /* @__PURE__ */ new Set();
+    const observer = {
+      onMessage: (tag, summary) => {
+        writeLog(`${tag} ${summary}`);
+        if (tag === "tool_use") {
+          lastTool = summary.split(" ")[0];
+          turnCount++;
+          const m = /read_email\b[^}]*"uid"\s*:\s*(\d+)/.exec(summary);
+          if (m) {
+            const uid = parseInt(m[1], 10);
+            if (Number.isFinite(uid) && uid > 0) digestedUids.add(uid);
+          }
+        }
+        if (tag === "usage") lastUsage = summary;
+      }
+    };
+    const heartbeatHandle = setInterval(() => {
+      this.postActivity("/dispatcher/worker-heartbeat", {
+        workerId,
+        agentName: account.name,
+        lastTool: lastTool || void 0,
+        turnCount
+      });
+    }, 3e4);
+    heartbeatHandle.unref?.();
+    try {
+      const { body } = loadPersonaForAgent({
+        agent: account,
+        agentsDir: this.cfg.agentsDir,
+        subagentPrefix: this.cfg.subagentPrefix,
+        mcpServerName: this.cfg.mcpServerName
+      });
+      this.log("info", `[dispatcher] waking "${account.name}" \u2014 ${ctx.kind}${ctx.taskId ? " " + ctx.taskId : ctx.uid ? " uid=" + ctx.uid : ""}`);
+      const mcpEnv = await this.buildMcpEnv();
+      const composedPrompt = this.composeWakePromptWithContext(account, ctx, prompt);
+      workerResult = await runWorkerWithCompaction(
+        this.query,
+        body,
+        composedPrompt,
+        account,
+        this.cfg.mcpServerName,
+        this.cfg.mcpCommand,
+        this.cfg.mcpArgs,
+        mcpEnv,
+        this.log,
+        observer,
+        cwdDir
+      );
+    } finally {
+      clearInterval(heartbeatHandle);
+      this.releaseSlot();
+      if (digestedUids.size > 0) {
+        const prefix = `${account.id}::`;
+        for (const [key, entry] of this.wakeCoalesce.entries()) {
+          if (!key.startsWith(prefix)) continue;
+          const before = entry.events.length;
+          entry.events = entry.events.filter((e) => !(typeof e.uid === "number" && digestedUids.has(e.uid)));
+          if (entry.events.length < before) {
+            this.log("info", `[dispatcher] dropped ${before - entry.events.length} queued wake(s) for "${account.name}" \u2014 UIDs already digested this turn`);
+          }
+          if (entry.events.length === 0) {
+            try {
+              clearTimeout(entry.timer);
+            } catch {
+            }
+            this.wakeCoalesce.delete(key);
+          }
+        }
+        const ch = this.channels.get(account.id);
+        if (ch) for (const uid of digestedUids) rememberBounded(ch.seenUids, uid);
+      }
+      try {
+        releaseAgentLock();
+      } catch {
+      }
+      const ok = workerResult?.ok === true;
+      const preview = workerResult?.ok ? workerResult.text : workerResult ? workerResult.error : "worker did not start";
+      writeLog(`worker_finished ok=${ok} chars=${preview.length}`);
+      try {
+        logStream?.end();
+      } catch {
+      }
+      try {
+        rmSync(cwdDir, { recursive: true, force: true });
+      } catch {
+      }
+      this.postActivity("/dispatcher/worker-finished", {
+        workerId,
+        agentName: account.name,
+        ok,
+        turnCount,
+        // Context-budget telemetry: the SDK-reported usage line
+        // (input/output/cache tokens + cost). Forwarded so
+        // check_activity can show real cost per worker and the
+        // cache+memory savings vs pre-0.9.0 become measurable.
+        usage: lastUsage,
+        resultPreview: typeof preview === "string" ? preview.slice(0, 240) : void 0
+      });
+    }
+  }
+  /**
+   * Fire-and-forget POST to the API's worker-activity endpoints.
+   *
+   * Failures are swallowed deliberately — the dispatcher must never
+   * block worker spawn or interrupt teardown because the API is briefly
+   * unreachable. The activity registry is best-effort observability, not
+   * load-bearing state.
+   */
+  postActivity(path, body) {
+    const url = `${this.cfg.apiUrl.replace(/\/$/, "")}/api/agenticmail${path}`;
+    try {
+      const result = this.fetchImpl(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.cfg.masterKey}`
+        },
+        body: JSON.stringify(body)
+      });
+      if (result && typeof result.catch === "function") {
+        void result.catch(() => {
+        });
+      }
+    } catch {
+    }
+  }
+  /**
+   * Post a "skipped wake" notification with the reason the
+   * dispatcher decided not to fire a Claude turn. Surfaced in
+   * `check_activity` so the host can see the decision instead
+   * of just observing silence ("did my mail land? did the
+   * dispatcher skip it? is the dispatcher even alive?").
+   *
+   * Reasons cover every filter that drops a wake:
+   *   - thread-closed       — subject had [FINAL]/[DONE]/[CLOSED]/[WRAP]
+   *   - allowlist-excluded  — sender's `wake` list did not include the agent
+   *   - wake-on-cc          — agent registered wake_on_cc:false and was on Cc
+   *   - dedup               — duplicate UID seen recently
+   *   - rpc-suppress        — RPC-notification mail right after a task event
+   *   - budget-exhausted    — per-(agent, thread) wake budget hit the cap
+   */
+  postSkipped(account, event, reason, detail) {
+    this.postActivity("/dispatcher/worker-skipped", {
+      agentId: account.id,
+      agentName: account.name,
+      uid: event.uid,
+      subject: extractSubject(event),
+      from: extractFrom(event),
+      reason,
+      detail
+    });
+  }
+  /** Build the env block we pass to the worker's MCP server child process. */
+  async buildMcpEnv() {
+    return {
+      AGENTICMAIL_API_URL: this.cfg.apiUrl,
+      AGENTICMAIL_MASTER_KEY: this.cfg.masterKey
+      // No AGENTICMAIL_API_KEY: workers should ALWAYS pass `_account`
+      // explicitly. Omitting the default key forces that discipline at
+      // the MCP-server level (any forgotten `_account` becomes a clear
+      // error rather than a silent identity drift).
+    };
+  }
+  acquireSlot() {
+    if (this.running < this.maxConcurrent) {
+      this.running++;
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.waiters.push(() => {
+        this.running++;
+        resolve();
+      });
+    });
+  }
+  releaseSlot() {
+    this.running--;
+    const next = this.waiters.shift();
+    if (next) next();
+  }
+  /**
+   * Per-agent serialization. At most ONE worker runs for any
+   * given agent at a time. When a new wake fires for an agent
+   * whose worker is still running, the new wake's spawnWorker
+   * waits on the prior worker's tail before proceeding.
+   *
+   * This is the fix for the "dispatcher crashed when sender
+   * broadcast to a 5-CC thread" failure mode: under the old
+   * design, 5 emails landing for vesper-on-3-different-threads
+   * in the same second spawned 5 simultaneous vesper workers,
+   * each opening its own IMAP connection, each calling the
+   * SDK, racing on the same inbox cache. With this gate they
+   * queue tail-to-head and run sequentially.
+   *
+   * `nextRun` is a chained promise: each new spawn calls
+   * `then()` on the previous tail so the order is preserved.
+   * When the chain resolves to a no-op (empty queue), the
+   * entry is garbage-collected from the map so memory stays
+   * bounded at #active-agents.
+   */
+  agentSerial = /* @__PURE__ */ new Map();
+  async acquireAgentSerial(agentId) {
+    const prev = this.agentSerial.get(agentId);
+    let release;
+    const next = new Promise((resolve) => {
+      release = resolve;
+    });
+    this.agentSerial.set(agentId, prev ? prev.then(() => next).catch(() => next) : next);
+    if (prev) await prev.catch(() => {
+    });
+    return () => {
+      release();
+      if (this.agentSerial.get(agentId) === next) this.agentSerial.delete(agentId);
+    };
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function sanitizeId(id) {
+  return id.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+function defaultLog(level, msg) {
+  const stream = level === "error" ? process.stderr : process.stdout;
+  stream.write(`[${(/* @__PURE__ */ new Date()).toISOString()}] [${level}] ${msg}
+`);
+}
+function defaultQuery() {
+  return (params) => {
+    let inner = null;
+    const init = async () => {
+      try {
+        const mod = await import("@anthropic-ai/claude-agent-sdk");
+        return mod.query(params);
+      } catch (err) {
+        throw new Error(
+          `Dispatcher needs @anthropic-ai/claude-agent-sdk installed in the package, but: ${err.message}`
+        );
+      }
+    };
+    return {
+      [Symbol.asyncIterator]() {
+        return {
+          async next() {
+            if (!inner) inner = await init();
+            const it = inner[Symbol.asyncIterator]();
+            const self = this;
+            self.next = it.next.bind(it);
+            return it.next();
+          }
+        };
+      }
+    };
+  };
+}
+
+export {
+  loadPersonaForAgent,
+  Dispatcher
+};