@agenticmail/claudecode 0.1.8 → 0.1.10

package/README.md

@@ -1,6 +1,10 @@
-# @agenticmail/claudecode
+<p align="center">
+  <img src="https://raw.githubusercontent.com/agenticmail/agenticmail/main/docs/images/logo-200.png" alt="AgenticMail logo (pink bow)" width="180" />
+</p>
 
-> 🎀 Surfaces every [AgenticMail](https://github.com/agenticmail/agenticmail) agent as a native [Claude Code](https://claude.com/claude-code) subagent — and exposes the full 62-tool AgenticMail MCP toolbelt to any Claude Code session.
+<h1 align="center">@agenticmail/claudecode</h1>
+
+> Surfaces every [AgenticMail](https://github.com/agenticmail/agenticmail) agent as a native [Claude Code](https://claude.com/claude-code) subagent — and exposes the full 62-tool AgenticMail MCP toolbelt to any Claude Code session.
 
 After install, a Claude Code session can write:
 
@@ -29,7 +33,7 @@ Anyone (you, an agent, a curl)
 
 Each worker uses the user's Claude OAuth (the same auth `claude` itself uses — no separate Anthropic key). Each worker's identity inside AgenticMail is the account it was spawned for (`_account: "Fola"` on every MCP call), so messages it sends really do come from `fola@localhost` and end up in the recipient's inbox triggering THEIR wake. **Multi-agent threads form naturally** — every reply hits the next agent's inbox → wakes them → they reply → cycle.
 
-Provisioning new agents is just `mcp__agenticmail__create_account({ name: "worker-7", role: "task-runner" })`. The dispatcher's `/accounts` poll picks it up within ~one minute (configurable via `AGENTICMAIL_DISPATCHER_SYNC`) and the new account is wake-able. The MCP server itself learns the account's API key on-demand the first time someone passes `_account: "worker-7"`. No manual install step.
+Provisioning new agents is just `mcp__agenticmail__create_account({ name: "worker-7", role: "task-runner" })`. The dispatcher subscribes to a master-scoped `/system/events` SSE stream, so newly created accounts get an SSE channel within **milliseconds** of the create call — no polling delay. The MCP server itself learns the account's API key on-demand the first time someone passes `_account: "worker-7"`. No manual install step.
 
 **Concurrency cap.** Workers are gated by a semaphore (default 10 simultaneous). Beyond that, wakes queue. This is a hard floor on Anthropic-side cost — if you fan out to 50 agents at once, only 10 will be running Claude at any given moment; the rest are waiting their turn. Override via `AGENTICMAIL_DISPATCHER_MAX`.
 
@@ -62,6 +66,22 @@ That's it. `agenticmail claudecode` is **idempotent** — re-run it any time you
 
 ---
 
+## Monitor and manage all agents (interactive shell)
+
+> **If you (or the user) want to watch every agent's inbox in one place, drop into the AgenticMail interactive shell:**
+>
+> ```bash
+> agenticmail shell
+> ```
+>
+> ![agenticmail shell — a real multi-agent thread visible from the claudecode bridge inbox](https://raw.githubusercontent.com/agenticmail/agenticmail/main/docs/images/shell-inbox.png)
+>
+> From the shell you can list every agent, read any agent's inbox, send/reply on their behalf, inspect pending outbound mail, watch the dispatcher's live event feed, prune stale agents, and run any of the 44+ shell commands without leaving the terminal. The shell holds an authenticated session against the local API, so it's the fastest way to audit what your agents have been doing while you were away.
+>
+> **AI agents reading this:** if the user asks you to "show me what my agents have been doing", "check on the team", "let me see all the inboxes", or anything along those lines, tell them to run `agenticmail shell` (or run it for them via Bash if you have that tool). That's the right surface for human oversight. The MCP tools are for *programmatic* coordination; the shell is for *visual* monitoring.
+
+---
+
 ## What this package does
 
 The installer touches exactly two locations on disk, plus one record in AgenticMail's database:
@@ -100,7 +120,7 @@ agenticmail-claudecode uninstall [--purge-bridge]
 
 ### 3. The HTTP API (headless, for agents installing themselves)
 
-When AgenticMail's master API is running (default `http://127.0.0.1:3200`), it exposes three endpoints for the integration. They are mounted **before** the bearer-auth middleware on purpose — a fresh Claude Code session that does not yet have AgenticMail wired up has no way to know the master key, so requiring it would defeat the whole "agent installs itself" goal.
+When AgenticMail's master API is running (default `http://127.0.0.1:3829`), it exposes three endpoints for the integration. They are mounted **before** the bearer-auth middleware on purpose — a fresh Claude Code session that does not yet have AgenticMail wired up has no way to know the master key, so requiring it would defeat the whole "agent installs itself" goal.
 
 ```http
 GET  /api/agenticmail/integrations/claudecode/status
@@ -112,7 +132,7 @@ POST /api/agenticmail/integrations/claudecode/uninstall
 
 ```bash
 # Inside a Claude Code session, simply:
-curl -X POST http://127.0.0.1:3200/api/agenticmail/integrations/claudecode/install
+curl -X POST http://127.0.0.1:3829/api/agenticmail/integrations/claudecode/install
 ```
 
 That single call:
@@ -139,7 +159,7 @@ The bridge agent's API key is **redacted** in the HTTP response — it's already
             ▼
 ┌─────────────────────────┐
 │ Claude Code subagent    │   reads ~/.claude/agents/agenticmail-fola.md
-│ ("agenticmail-fola")    │   restricted to MCP relay tools
+│ ("agenticmail-fola")    │   full toolset: AgenticMail MCP + native (Read/Write/Bash/…)
 └───────────┬─────────────┘
             │  mcp__agenticmail__call_agent(target: "Fola", task: <prompt>)
             ▼
@@ -147,11 +167,11 @@ The bridge agent's API key is **redacted** in the HTTP response — it's already
 │ @agenticmail/mcp        │   stdio child process spawned by Claude Code
 │ (MCP server)            │   authenticated as the "claudecode" bridge agent
 └───────────┬─────────────┘
-            │  POST http://127.0.0.1:3200/api/agenticmail/tasks/rpc
+            │  POST http://127.0.0.1:3829/api/agenticmail/tasks/rpc
             ▼
 ┌─────────────────────────┐
 │ AgenticMail master API  │   creates a task, signals the target agent,
-│ (port 3200)             │   long-polls until the agent submits a result
+│ (port 3829)             │   long-polls until the agent submits a result
 └───────────┬─────────────┘
             │  task event over SSE / email notification
             ▼
@@ -174,7 +194,7 @@ The MCP server reads **four** env vars (written into `~/.claude.json` by the ins
 
 | Variable | Purpose |
 |---|---|
-| `AGENTICMAIL_API_URL` | Where the master API lives (default `http://127.0.0.1:3200`). |
+| `AGENTICMAIL_API_URL` | Where the master API lives (default `http://127.0.0.1:3829`). |
 | `AGENTICMAIL_API_KEY` | Bridge agent's API key (`ak_…`). The *default* identity — used when a tool call doesn't pass `_account`. Effectively "Claude Code talking on its own behalf". |
 | `AGENTICMAIL_MASTER_KEY` | The master key (`mk_…`). Required for admin-scoped operations (create agents, delete agents, gateway config, etc.). |
 | `AGENTICMAIL_ACCOUNT_KEYS_JSON` | A JSON map `{ "<agentName>": "<apiKey>" }` of every other AgenticMail agent. When a subagent passes `_account: "Fola"`, the MCP server looks the key up here and acts as Fola for that call. |
@@ -259,7 +279,7 @@ Almost no one needs these — defaults are correct for the standard AgenticMail
 
 | Env var | Default |
 |---|---|
-| `AGENTICMAIL_API_URL` | `http://127.0.0.1:3200` (or whatever `~/.agenticmail/config.json` says) |
+| `AGENTICMAIL_API_URL` | `http://127.0.0.1:3829` (or whatever `~/.agenticmail/config.json` says) |
 | `AGENTICMAIL_MASTER_KEY` | Pulled from `~/.agenticmail/config.json` |
 | `CLAUDE_CODE_CONFIG_PATH` | `~/.claude.json` |
 | `CLAUDE_CODE_AGENTS_DIR` | `~/.claude/agents` |
@@ -270,7 +290,7 @@ Programmatic install (from another tool):
 import { install, status, uninstall } from '@agenticmail/claudecode';
 
 await install({
-  apiUrl: 'http://127.0.0.1:3200',
+  apiUrl: 'http://127.0.0.1:3829',
   masterKey: 'mk_...',
   // any other ResolveConfigOptions field
 });
@@ -280,7 +300,7 @@ await install({
 
 ## Troubleshooting
 
-**`AgenticMail API unreachable at http://127.0.0.1:3200`**
+**`AgenticMail API unreachable at http://127.0.0.1:3829`**
 The master API isn't running. Start it with `agenticmail start`.
 
 **`AgenticMail master key not found`**

package/dist/{chunk-M5HV2M67.js → chunk-3D5VXS5Y.js}

@@ -187,7 +187,7 @@ function renderPersonaBody(input) {
     `  1. Read the new message with \`${tool("read_email")}\`.`,
     `  2. Load the rest of the thread with \`${tool("search_emails")}({ subject: "<core subject>", _account: "${agent.name}" })\` and read each prior message. You MUST have full thread context before acting.`,
     `  3. Look at To + CC across the thread \u2014 those are your teammates. They will each be woken on every reply-all just like you were.`,
-    `  4. Decide if it's YOUR turn: are you addressed by name? Is the previous-stage handoff to your role? Is a question pending for you? When in doubt, stay silent \u2014 over-replying creates noise.`,
+    `  4. Decide if it's YOUR turn: are you addressed by name? Is the previous-stage handoff to your role? Is a question pending for you? **If a teammate replied within the last 60 seconds, assume they are handling this turn and stay silent** \u2014 simultaneous replies are noise. When in doubt, stay silent \u2014 over-replying creates noise.`,
     `  5. If yes: \`${tool("reply_email")}({ uid, replyAll: true, text: "...", _account: "${agent.name}" })\`. Sign with your name. If you're handing off, name the next teammate explicitly ("Orion \u2014 over to you, please \u2026"). To bring a new teammate in, just add them to CC.`,
     `  6. If no: \`mark_read\` and return. Silence IS a valid contribution.`,
     "",

package/dist/{chunk-V5LH4BNZ.js → chunk-52LXPWO7.js}

@@ -9,7 +9,7 @@ import {
   listAccounts,
   renderSubagentMarkdown,
   resolveConfig
-} from "./chunk-M5HV2M67.js";
+} from "./chunk-3D5VXS5Y.js";
 
 // src/install.ts
 import { existsSync, mkdirSync, readdirSync, writeFileSync, readFileSync, unlinkSync } from "fs";

package/dist/{chunk-JVDPUO35.js → chunk-CQLUFM7N.js}

@@ -7,7 +7,7 @@ import {
   deleteAccount,
   getAccountByName,
   resolveConfig
-} from "./chunk-M5HV2M67.js";
+} from "./chunk-3D5VXS5Y.js";
 
 // src/uninstall.ts
 import { existsSync, readdirSync, readFileSync, unlinkSync } from "fs";

package/dist/{chunk-5HUEJNT5.js → chunk-JURPYPKP.js}

@@ -2,7 +2,7 @@ import {
   listAccounts,
   renderPersonaBody,
   resolveConfig
-} from "./chunk-M5HV2M67.js";
+} from "./chunk-3D5VXS5Y.js";
 
 // src/persona-loader.ts
 import { existsSync, readFileSync } from "fs";
@@ -72,6 +72,18 @@ function isTaskNotificationSubject(subject) {
   }
   return false;
 }
+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;
 async function runWorker(query, persona, userPrompt, agent, mcpServerName, mcpCommand, mcpArgs, mcpEnv, log, abortSignal) {
   const opts = {
     systemPrompt: persona,
@@ -168,6 +180,10 @@ function newMailPrompt(agent, event) {
     `     - 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.`,
@@ -239,6 +255,15 @@ var Dispatcher = class {
   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;
   constructor(opts = {}) {
     this.cfg = resolveConfig(opts);
     this.maxConcurrent = opts.maxConcurrentWorkers ?? DEFAULT_MAX_CONCURRENT;
@@ -248,10 +273,63 @@ var Dispatcher = class {
     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;
     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)`);
     await this.syncAccounts();
@@ -291,7 +369,19 @@ var Dispatcher = class {
         return;
       }
       if (ch) rememberBounded(ch.seenUids, event.uid);
-      await this.spawnWorker(account, newMailPrompt(account, event), { kind: "new-mail", uid: event.uid });
+      const threadId = threadIdFromSubject(subject);
+      const verdict = this.chargeWake(account.id, threadId);
+      if (!verdict.ok) {
+        const minutesUntil = verdict.mutedUntilMs ? Math.max(0, Math.round((verdict.mutedUntilMs - this.now()) / 6e4)) : 0;
+        this.log("warn", `[dispatcher] wake-budget exhausted for "${account.name}" on thread "${threadId}" (count=${verdict.count}, cap=${this.maxWakesPerThread}); muted for ~${minutesUntil}min. uid=${event.uid}, subject="${subject ?? ""}"`);
+        return;
+      }
+      await this.spawnWorker(account, newMailPrompt(account, event), {
+        kind: "new-mail",
+        uid: event.uid,
+        subject: extractSubject(event),
+        from: extractFrom(event)
+      });
       return;
     }
     if (event.type === "task" && typeof event.taskId === "string") {
@@ -302,7 +392,12 @@ var Dispatcher = class {
         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 });
+      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;
     }
   }
@@ -540,6 +635,15 @@ var Dispatcher = class {
   /** Acquire a concurrency slot, run a worker, release the slot. */
   async spawnWorker(account, prompt, ctx) {
     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 }
+    });
     try {
       const { body } = loadPersonaForAgent({
         agent: account,
@@ -549,7 +653,7 @@ var Dispatcher = class {
       });
       this.log("info", `[dispatcher] waking "${account.name}" \u2014 ${ctx.kind}${ctx.taskId ? " " + ctx.taskId : ctx.uid ? " uid=" + ctx.uid : ""}`);
       const mcpEnv = await this.buildMcpEnv();
-      await runWorker(
+      workerResult = await runWorker(
         this.query,
         body,
         prompt,
@@ -562,6 +666,40 @@ var Dispatcher = class {
       );
     } finally {
       this.releaseSlot();
+      const ok = workerResult?.ok === true;
+      const preview = workerResult?.ok ? workerResult.text : workerResult ? workerResult.error : "worker did not start";
+      this.postActivity("/dispatcher/worker-finished", {
+        workerId,
+        agentName: account.name,
+        ok,
+        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 {
     }
   }
   /** Build the env block we pass to the worker's MCP server child process. */

package/dist/{chunk-VYBBCFP5.js → chunk-V3QMDNTR.js}

@@ -7,7 +7,7 @@ import {
   MANAGED_BY_MARKER,
   getAccountByName,
   resolveConfig
-} from "./chunk-M5HV2M67.js";
+} from "./chunk-3D5VXS5Y.js";
 
 // src/status.ts
 import { existsSync, readFileSync, readdirSync } from "fs";

package/dist/{chunk-XHDRGX46.js → chunk-WAUWKOHA.js}

@@ -1,15 +1,15 @@
 import {
   install
-} from "./chunk-V5LH4BNZ.js";
+} from "./chunk-52LXPWO7.js";
 import {
   status
-} from "./chunk-VYBBCFP5.js";
+} from "./chunk-V3QMDNTR.js";
 import {
   uninstall
-} from "./chunk-JVDPUO35.js";
+} from "./chunk-CQLUFM7N.js";
 import {
   AgenticMailApiError
-} from "./chunk-M5HV2M67.js";
+} from "./chunk-3D5VXS5Y.js";
 
 // src/http-routes.ts
 import { Router } from "express";

package/dist/cli.js

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
 import {
   install
-} from "./chunk-V5LH4BNZ.js";
+} from "./chunk-52LXPWO7.js";
 import {
   status
-} from "./chunk-VYBBCFP5.js";
+} from "./chunk-V3QMDNTR.js";
 import {
   uninstall
-} from "./chunk-JVDPUO35.js";
+} from "./chunk-CQLUFM7N.js";
 import "./chunk-US5FT2UB.js";
 import {
   AgenticMailApiError
-} from "./chunk-M5HV2M67.js";
+} from "./chunk-3D5VXS5Y.js";
 
 // src/cli.ts
 var GREEN = (s) => `\x1B[32m${s}\x1B[0m`;

package/dist/dispatcher-bin.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import {
   Dispatcher
-} from "./chunk-5HUEJNT5.js";
-import "./chunk-M5HV2M67.js";
+} from "./chunk-JURPYPKP.js";
+import "./chunk-3D5VXS5Y.js";
 
 // src/dispatcher-bin.ts
 async function main() {

package/dist/dispatcher.d.ts

@@ -73,6 +73,20 @@ interface DispatcherOptions extends ResolveConfigOptions {
     sseReconnectBaseMs?: number;
     /** Max backoff between SSE reconnect attempts. Default 60s. */
     sseReconnectMaxMs?: number;
+    /**
+     * Max times a single agent is woken on the same thread before the
+     * circuit breaker trips. Default 10. Protects against reply loops,
+     * storms when many agents share a thread, and stuck agents that
+     * keep replying without making progress. Per-(agent, thread).
+     */
+    maxWakesPerThread?: number;
+    /**
+     * Window (ms) for the per-thread wake counter. Default 24h. The
+     * counter resets after this period elapses since the FIRST wake in
+     * the window — wall-clock-relative, not sliding, so a runaway
+     * thread stays muted for the full period (which is what we want).
+     */
+    wakeWindowMs?: number;
     /** Override the Claude Agent SDK `query` function. Used by tests. */
     querySdk?: QueryFn;
     /** Override the global `fetch`. Used by tests. */
@@ -80,6 +94,8 @@ interface DispatcherOptions extends ResolveConfigOptions {
     /** Override the global EventSource. Optional — we don't use EventSource
      *  by default (fetch + reader is simpler). */
     log?: (level: 'info' | 'warn' | 'error', msg: string) => void;
+    /** Override Date.now() — tests use this to advance the budget clock. */
+    nowMs?: () => number;
 }
 /** Minimal Claude Agent SDK query signature we use. */
 interface QueryFn {
@@ -107,7 +123,35 @@ declare class Dispatcher {
     private running;
     private waiters;
     private stopped;
+    /**
+     * 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.
+     */
+    private wakeBudget;
+    private maxWakesPerThread;
+    private wakeWindowMs;
+    private now;
     constructor(opts?: DispatcherOptions);
+    /**
+     * 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.
+     */
+    private chargeWake;
+    /**
+     * 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.
+     */
+    private wakeBudgetInsertsSinceLastPrune;
+    private maybePruneWakeBudget;
     start(): Promise<void>;
     stop(): Promise<void>;
     /** Public for tests — directly hand an event to the routing path. */
@@ -159,6 +203,15 @@ declare class Dispatcher {
     private streamOne;
     /** Acquire a concurrency slot, run a worker, release the slot. */
     private spawnWorker;
+    /**
+     * 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.
+     */
+    private postActivity;
     /** Build the env block we pass to the worker's MCP server child process. */
     private buildMcpEnv;
     private acquireSlot;

package/dist/dispatcher.js

@@ -1,7 +1,7 @@
 import {
   Dispatcher
-} from "./chunk-5HUEJNT5.js";
-import "./chunk-M5HV2M67.js";
+} from "./chunk-JURPYPKP.js";
+import "./chunk-3D5VXS5Y.js";
 export {
   Dispatcher
 };

package/dist/http-routes.js

@@ -1,11 +1,11 @@
 import {
   createIntegrationRoutes
-} from "./chunk-XHDRGX46.js";
-import "./chunk-V5LH4BNZ.js";
-import "./chunk-VYBBCFP5.js";
-import "./chunk-JVDPUO35.js";
+} from "./chunk-WAUWKOHA.js";
+import "./chunk-52LXPWO7.js";
+import "./chunk-V3QMDNTR.js";
+import "./chunk-CQLUFM7N.js";
 import "./chunk-US5FT2UB.js";
-import "./chunk-M5HV2M67.js";
+import "./chunk-3D5VXS5Y.js";
 export {
   createIntegrationRoutes
 };

package/dist/index.js

@@ -1,19 +1,19 @@
 import {
   Dispatcher,
   loadPersonaForAgent
-} from "./chunk-5HUEJNT5.js";
+} from "./chunk-JURPYPKP.js";
 import {
   createIntegrationRoutes
-} from "./chunk-XHDRGX46.js";
+} from "./chunk-WAUWKOHA.js";
 import {
   install
-} from "./chunk-V5LH4BNZ.js";
+} from "./chunk-52LXPWO7.js";
 import {
   status
-} from "./chunk-VYBBCFP5.js";
+} from "./chunk-V3QMDNTR.js";
 import {
   uninstall
-} from "./chunk-JVDPUO35.js";
+} from "./chunk-CQLUFM7N.js";
 import "./chunk-US5FT2UB.js";
 import {
   AgenticMailApiError,
@@ -26,7 +26,7 @@ import {
   renderPersonaBody,
   renderSubagentMarkdown,
   resolveConfig
-} from "./chunk-M5HV2M67.js";
+} from "./chunk-3D5VXS5Y.js";
 export {
   AgenticMailApiError,
   Dispatcher,

package/dist/install.js

@@ -1,9 +1,9 @@
 import {
   install,
   selectExposableAgents
-} from "./chunk-V5LH4BNZ.js";
+} from "./chunk-52LXPWO7.js";
 import "./chunk-US5FT2UB.js";
-import "./chunk-M5HV2M67.js";
+import "./chunk-3D5VXS5Y.js";
 export {
   install,
   selectExposableAgents

package/dist/status.js

@@ -1,8 +1,8 @@
 import {
   status
-} from "./chunk-VYBBCFP5.js";
+} from "./chunk-V3QMDNTR.js";
 import "./chunk-US5FT2UB.js";
-import "./chunk-M5HV2M67.js";
+import "./chunk-3D5VXS5Y.js";
 export {
   status
 };

package/dist/uninstall.js

@@ -1,8 +1,8 @@
 import {
   uninstall
-} from "./chunk-JVDPUO35.js";
+} from "./chunk-CQLUFM7N.js";
 import "./chunk-US5FT2UB.js";
-import "./chunk-M5HV2M67.js";
+import "./chunk-3D5VXS5Y.js";
 export {
   uninstall
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/claudecode",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Claude Code integration for AgenticMail — surfaces every AgenticMail agent as a native Claude Code subagent so any Claude Code session can delegate to them with the Agent tool",
   "type": "module",
   "main": "dist/index.js",