@agenticmail/claudecode 0.2.6 → 0.2.8

package/dist/{chunk-2GPBHK2M.js → chunk-2RVJ2Q3W.js}

@@ -1,6 +1,6 @@
 import {
   removeUserPromptSubmitHook
-} from "./chunk-DKTAW2N5.js";
+} from "./chunk-LO5EQSQA.js";
 import {
   removeMcpServer,
   stopDispatcher
@@ -10,7 +10,7 @@ import {
   deleteAccount,
   getAccountByName,
   resolveConfig
-} from "./chunk-SBP7MJP2.js";
+} from "./chunk-4VQP57SO.js";
 
 // src/uninstall.ts
 import { existsSync, readdirSync, readFileSync, unlinkSync } from "fs";

package/dist/{chunk-SBP7MJP2.js → chunk-4VQP57SO.js}

@@ -82,6 +82,33 @@ async function ensureAccount(apiUrl, masterKey, name, role = "assistant") {
 async function deleteAccount(apiUrl, masterKey, id) {
   await request(apiUrl, masterKey, `/accounts/${encodeURIComponent(id)}`, { method: "DELETE" });
 }
+async function listInboxForAgent(apiUrl, agentApiKey, opts = {}) {
+  const limit = Math.max(1, Math.min(opts.limit ?? 50, 100));
+  const url = `${apiUrl.replace(/\/$/, "")}/api/agenticmail/mail/inbox?limit=${limit}`;
+  const res = await fetch(url, {
+    headers: { "Authorization": `Bearer ${agentApiKey}` },
+    signal: AbortSignal.timeout(15e3)
+  });
+  if (!res.ok) {
+    throw new AgenticMailApiError(res.status, `mail/inbox HTTP ${res.status}`);
+  }
+  const data = await res.json();
+  return data?.messages ?? [];
+}
+async function listPendingTasksForAgent(apiUrl, agentApiKey) {
+  const url = `${apiUrl.replace(/\/$/, "")}/api/agenticmail/tasks/pending`;
+  const res = await fetch(url, {
+    headers: { "Authorization": `Bearer ${agentApiKey}` },
+    signal: AbortSignal.timeout(15e3)
+  });
+  if (!res.ok) {
+    if (res.status === 404) return [];
+    throw new AgenticMailApiError(res.status, `tasks/pending HTTP ${res.status}`);
+  }
+  const data = await res.json();
+  const rows = Array.isArray(data) ? data : data?.tasks ?? [];
+  return rows.filter((t) => (t.status ?? "").toLowerCase() === "pending");
+}
 
 // src/config.ts
 import { readFileSync, existsSync } from "fs";
@@ -255,6 +282,8 @@ export {
   getAccountByName,
   ensureAccount,
   deleteAccount,
+  listInboxForAgent,
+  listPendingTasksForAgent,
   resolveConfig,
   MANAGED_BY_MARKER,
   renderPersonaBody,

package/dist/{chunk-QSR32ZGW.js → chunk-JOK76WRC.js}

@@ -1,8 +1,10 @@
 import {
   listAccounts,
+  listInboxForAgent,
+  listPendingTasksForAgent,
   renderPersonaBody,
   resolveConfig
-} from "./chunk-SBP7MJP2.js";
+} from "./chunk-4VQP57SO.js";
 
 // src/persona-loader.ts
 import { existsSync, readFileSync } from "fs";
@@ -35,10 +37,129 @@ function loadPersonaForAgent(opts) {
   return { body, source: "generated" };
 }
 
-// src/dispatcher.ts
-import { mkdirSync, createWriteStream, rmSync } from "fs";
-import { join as join2 } from "path";
+// src/dispatcher-state.ts
+import { readFileSync as readFileSync2, writeFileSync, renameSync, mkdirSync, existsSync as existsSync2 } from "fs";
+import { dirname, join as join2 } from "path";
 import { homedir } from "os";
+var STATE_VERSION = 1;
+var SEEN_UIDS_CAP = 256;
+var FLUSH_INTERVAL_MS = 2e3;
+function emptyState() {
+  return { version: STATE_VERSION, savedAtMs: 0, accounts: {} };
+}
+function defaultStatePath() {
+  return join2(homedir(), ".agenticmail", "dispatcher-state.json");
+}
+var DispatcherState = class {
+  path;
+  state = emptyState();
+  dirty = false;
+  flushTimer = null;
+  constructor(opts) {
+    this.path = opts?.path ?? defaultStatePath();
+    this.load();
+  }
+  /** Read the state file from disk. Missing / corrupt → empty state. */
+  load() {
+    try {
+      if (!existsSync2(this.path)) return;
+      const raw = readFileSync2(this.path, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && parsed.version === STATE_VERSION) {
+        const accounts = {};
+        for (const [id, cursor] of Object.entries(parsed.accounts ?? {})) {
+          if (cursor && typeof cursor === "object" && typeof cursor.lastSeenUid === "number" && Array.isArray(cursor.seenUids)) {
+            const c = cursor;
+            accounts[id] = {
+              lastSeenUid: c.lastSeenUid,
+              seenUids: c.seenUids.filter((u) => Number.isFinite(u) && u > 0).slice(-SEEN_UIDS_CAP)
+            };
+          }
+        }
+        this.state = { version: STATE_VERSION, savedAtMs: parsed.savedAtMs ?? 0, accounts };
+      }
+    } catch {
+      this.state = emptyState();
+    }
+  }
+  /** Read the cursor for one account. Missing → undefined. */
+  getCursor(accountId) {
+    return this.state.accounts[accountId];
+  }
+  /** All known account ids in the persisted state. */
+  knownAccounts() {
+    return Object.keys(this.state.accounts);
+  }
+  /**
+   * Record that the dispatcher routed UID `uid` for `accountId`.
+   * Updates lastSeenUid (monotonic max) and appends to seenUids with
+   * bounding. Marks state dirty + schedules a debounced flush.
+   */
+  markSeen(accountId, uid) {
+    if (!Number.isFinite(uid) || uid <= 0) return;
+    let cur = this.state.accounts[accountId];
+    if (!cur) {
+      cur = { lastSeenUid: 0, seenUids: [] };
+      this.state.accounts[accountId] = cur;
+    }
+    if (uid > cur.lastSeenUid) cur.lastSeenUid = uid;
+    if (!cur.seenUids.includes(uid)) {
+      cur.seenUids.push(uid);
+      if (cur.seenUids.length > SEEN_UIDS_CAP) {
+        cur.seenUids = cur.seenUids.slice(-SEEN_UIDS_CAP);
+      }
+    }
+    this.scheduleFlush();
+  }
+  /** Drop the cursor for an account that vanished. */
+  forget(accountId) {
+    if (this.state.accounts[accountId]) {
+      delete this.state.accounts[accountId];
+      this.scheduleFlush();
+    }
+  }
+  scheduleFlush() {
+    this.dirty = true;
+    if (this.flushTimer) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      try {
+        this.flushNow();
+      } catch {
+      }
+    }, FLUSH_INTERVAL_MS);
+    this.flushTimer.unref?.();
+  }
+  /**
+   * Synchronously write state to disk via atomic rename. Safe to call
+   * from a shutdown handler — finishes before the process exits.
+   */
+  flushNow() {
+    if (!this.dirty) return;
+    const dir = dirname(this.path);
+    try {
+      mkdirSync(dir, { recursive: true });
+    } catch {
+    }
+    const out = { ...this.state, savedAtMs: Date.now(), version: STATE_VERSION };
+    const tmp = `${this.path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(out));
+    renameSync(tmp, this.path);
+    this.dirty = false;
+  }
+  /** Cancel the debounce timer (used during shutdown). */
+  stop() {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+};
+
+// src/dispatcher.ts
+import { mkdirSync as mkdirSync2, createWriteStream, rmSync } from "fs";
+import { join as join3 } from "path";
+import { homedir as homedir2 } from "os";
 import { ThreadCache, AgentMemoryStore, threadIdFor, normalizeSubject } from "@agenticmail/core";
 function extractSubject(event) {
   if (typeof event.subject === "string") return event.subject;
@@ -450,6 +571,21 @@ var Dispatcher = class {
    */
   threadCache;
   agentMemory;
+  /**
+   * Persistent dispatcher state — per-account `{ lastSeenUid, seenUids[] }`
+   * that survives a restart. On `start()` we use it to seed each
+   * channel's `seenUids` (so IMAP IDLE replays of old UIDs stay
+   * deduped) and to drive the catch-up scan (anything strictly
+   * newer than `lastSeenUid` got missed during downtime — route it
+   * through handleEvent like a synthetic SSE 'new' event).
+   *
+   * Writes are debounced inside the state module; we just call
+   * `markSeen(accountId, uid)` everywhere we decide on a UID.
+   */
+  state;
+  /** Tracks which accounts have already gone through catch-up + pending-task scan
+   *  so reconnects don't replay the same backlog. */
+  caughtUp = /* @__PURE__ */ new Set();
   /**
    * Coalesced wake queue. Keyed by `${accountId}::${threadId}`,
    * each entry holds the pending events + the timer that will
@@ -488,10 +624,13 @@ var Dispatcher = class {
     this.threadCache = new ThreadCache({ cacheDir: opts.threadCacheDir });
     this.agentMemory = new AgentMemoryStore({ memoryDir: opts.agentMemoryDir });
     this.wakeCoalesceMs = opts.wakeCoalesceMs ?? DEFAULT_WAKE_COALESCE_MS;
+    this.state = new DispatcherState({ path: opts.stateFilePath });
+    this.disableCatchupScan = !!opts.disableCatchupScan;
     if (!this.cfg.masterKey) {
       throw new Error("Dispatcher requires AgenticMail master key. Run `agenticmail setup` first.");
     }
   }
+  disableCatchupScan = false;
   /**
    * Charge one wake against the (agent, thread) budget. Returns true
    * if the wake should proceed, false if the circuit breaker is open.
@@ -590,6 +729,12 @@ var Dispatcher = class {
     this.channels.clear();
     for (const entry of this.wakeCoalesce.values()) clearTimeout(entry.timer);
     this.wakeCoalesce.clear();
+    try {
+      this.state.stop();
+      this.state.flushNow();
+    } catch (err) {
+      this.log("warn", `[dispatcher] could not flush state on stop: ${err.message}`);
+    }
     this.log("info", "[dispatcher] stopped");
   }
   /** Public for tests — directly hand an event to the routing path. */
@@ -620,9 +765,11 @@ var Dispatcher = class {
       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);
+        this.state.markSeen(account.id, event.uid);
         return;
       }
       if (ch) rememberBounded(ch.seenUids, event.uid);
+      this.state.markSeen(account.id, 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 ?? ""}"`);
@@ -711,6 +858,8 @@ var Dispatcher = class {
         ch.stopping = true;
         ch.controller?.abort();
         this.channels.delete(id);
+        this.state.forget(id);
+        this.caughtUp.delete(id);
         this.log("info", `[dispatcher] account "${ch.account.name}" removed \u2014 closed SSE channel`);
       }
     }
@@ -719,17 +868,19 @@ var Dispatcher = class {
         this.channels.get(account.id).account = account;
         continue;
       }
+      const persistedCursor = this.state.getCursor(account.id);
+      const seenUids = new Set(persistedCursor?.seenUids ?? []);
       const ch = {
         account,
         controller: null,
         stopping: false,
         backoffMs: this.reconnectBaseMs,
-        seenUids: /* @__PURE__ */ new Set(),
+        seenUids,
         seenTaskIds: /* @__PURE__ */ new Set(),
         suppressTaskMailUntilMs: 0
       };
       this.channels.set(account.id, ch);
-      this.log("info", `[dispatcher] opening SSE for "${account.name}" (${account.email})`);
+      this.log("info", `[dispatcher] opening SSE for "${account.name}" (${account.email})` + (persistedCursor ? ` (restored ${seenUids.size} seen UIDs, lastSeenUid=${persistedCursor.lastSeenUid})` : ""));
       void this.runChannel(ch);
     }
   }
@@ -863,6 +1014,88 @@ var Dispatcher = class {
       ch.backoffMs = Math.min(ch.backoffMs * 2, this.reconnectMaxMs);
     }
   }
+  /**
+   * One-shot backlog scan after a (re)connect: route unprocessed mail
+   * + pending tasks that arrived while the dispatcher was unreachable.
+   *
+   * Mail path: pull the newest 50 envelopes from `/mail/inbox`. For
+   * each UID strictly greater than the persisted `lastSeenUid` (and
+   * not already in the channel's `seenUids`), synthesise an SSE
+   * `new` event and hand it to `handleEvent`. The wake-budget
+   * circuit breaker still applies, so a runaway thread that hit
+   * the cap pre-restart STAYS muted — restart isn't a free reset.
+   *
+   * Tasks path: fetch `/tasks/pending`. Anything not in the
+   * channel's `seenTaskIds` becomes a synthetic task SSE event.
+   *
+   * Failures here are NEVER fatal — they're "best effort". The
+   * dispatcher continues processing live SSE traffic regardless.
+   */
+  async runCatchUp(ch) {
+    const account = ch.account;
+    try {
+      const envelopes = await listInboxForAgent(this.cfg.apiUrl, account.apiKey, { limit: 50 });
+      const cursor = this.state.getCursor(account.id);
+      if (!cursor) {
+        if (envelopes.length > 0) {
+          let maxUid = 0;
+          for (const e of envelopes) {
+            if (Number.isFinite(e.uid) && e.uid > 0) {
+              ch.seenUids.add(e.uid);
+              if (e.uid > maxUid) maxUid = e.uid;
+            }
+          }
+          if (maxUid > 0) this.state.markSeen(account.id, maxUid);
+          this.log("info", `[dispatcher] catch-up for "${account.name}": first run, seeded cursor at uid=${maxUid} (skipping ${envelopes.length} pre-existing messages)`);
+        }
+      } else {
+        const lastSeenUid = cursor.lastSeenUid;
+        const sorted = envelopes.filter((e) => Number.isFinite(e.uid) && e.uid > lastSeenUid && !ch.seenUids.has(e.uid)).sort((a, b) => a.uid - b.uid);
+        if (sorted.length > 0) {
+          this.log("info", `[dispatcher] catch-up for "${account.name}": replaying ${sorted.length} unprocessed UIDs (lastSeenUid=${lastSeenUid})`);
+          for (const env of sorted) {
+            const event = {
+              type: "new",
+              uid: env.uid,
+              subject: env.subject,
+              // Format `from` to match what extractFrom expects
+              // (top-level string OR nested under message). Use the
+              // first sender's address — that's what the live SSE
+              // path delivers.
+              from: env.from?.[0]?.address,
+              message: {
+                subject: env.subject,
+                from: env.from,
+                to: env.to
+              }
+            };
+            await this.handleEvent(account, event);
+          }
+        }
+      }
+    } catch (err) {
+      this.log("warn", `[dispatcher] catch-up mail scan failed for "${account.name}": ${err.message}`);
+    }
+    try {
+      const tasks = await listPendingTasksForAgent(this.cfg.apiUrl, account.apiKey);
+      const fresh = tasks.filter((t) => t.id && !ch.seenTaskIds.has(t.id));
+      if (fresh.length > 0) {
+        this.log("info", `[dispatcher] catch-up for "${account.name}": replaying ${fresh.length} pending tasks`);
+        for (const t of fresh) {
+          const event = {
+            type: "task",
+            taskId: t.id,
+            taskType: t.task_type ?? t.type,
+            task: t.description ?? t.task ?? "",
+            assignee: account.name
+          };
+          await this.handleEvent(account, event);
+        }
+      }
+    } catch (err) {
+      this.log("warn", `[dispatcher] catch-up task scan failed for "${account.name}": ${err.message}`);
+    }
+  }
   /** Single SSE attach. Returns when the stream closes for any reason. */
   async streamOne(ch) {
     const url = `${this.cfg.apiUrl.replace(/\/$/, "")}/api/agenticmail/events`;
@@ -877,6 +1110,12 @@ var Dispatcher = class {
       throw new Error(`SSE handshake HTTP ${res.status}`);
     }
     ch.backoffMs = this.reconnectBaseMs;
+    if (!this.caughtUp.has(ch.account.id) && !this.disableCatchupScan) {
+      this.caughtUp.add(ch.account.id);
+      void this.runCatchUp(ch).catch(
+        (err) => this.log("warn", `[dispatcher] catch-up scan failed for "${ch.account.name}": ${err.message}`)
+      );
+    }
     const reader = res.body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
@@ -1078,12 +1317,12 @@ var Dispatcher = class {
       kind: ctx.kind,
       trigger: { uid: ctx.uid, taskId: ctx.taskId, subject: ctx.subject, from: ctx.from }
     });
-    const logsDir = join2(homedir(), ".agenticmail", "worker-logs");
+    const logsDir = join3(homedir2(), ".agenticmail", "worker-logs");
     try {
-      mkdirSync(logsDir, { recursive: true });
+      mkdirSync2(logsDir, { recursive: true });
     } catch {
     }
-    const logPath = join2(logsDir, `${sanitizeId(workerId)}.log`);
+    const logPath = join3(logsDir, `${sanitizeId(workerId)}.log`);
     let logStream = null;
     try {
       logStream = createWriteStream(logPath, { flags: "a" });
@@ -1097,9 +1336,9 @@ var Dispatcher = class {
       }
     };
     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));
+    const cwdDir = join3(homedir2(), ".agenticmail", "worker-cwds", sanitizeId(workerId));
     try {
-      mkdirSync(cwdDir, { recursive: true });
+      mkdirSync2(cwdDir, { recursive: true });
     } catch {
     }
     let turnCount = 0;
@@ -1174,7 +1413,12 @@ var Dispatcher = class {
           }
         }
         const ch = this.channels.get(account.id);
-        if (ch) for (const uid of digestedUids) rememberBounded(ch.seenUids, uid);
+        if (ch) {
+          for (const uid of digestedUids) {
+            rememberBounded(ch.seenUids, uid);
+            this.state.markSeen(account.id, uid);
+          }
+        }
       }
       try {
         releaseAgentLock();

package/dist/{chunk-DKTAW2N5.js → chunk-LO5EQSQA.js}

@@ -5,8 +5,8 @@ function isAgenticMailHookCommand(command) {
   if (typeof command !== "string") return false;
   return command.includes("agenticmail-mail-hook") || command.includes("mail-hook.js");
 }
-var HOOK_EVENTS_TO_REGISTER = ["UserPromptSubmit", "Stop"];
-var HOOK_EVENTS_TO_REMOVE = ["UserPromptSubmit", "Stop", "PreToolUse"];
+var HOOK_EVENTS_TO_REGISTER = ["UserPromptSubmit", "Stop", "SessionStart"];
+var HOOK_EVENTS_TO_REMOVE = ["UserPromptSubmit", "Stop", "PreToolUse", "SessionStart"];
 function readSettings(path) {
   if (!existsSync(path)) return {};
   const raw = readFileSync(path, "utf-8");

package/dist/{chunk-ZTSWLNUP.js → chunk-OUYPF4ER.js}

@@ -1,6 +1,6 @@
 import {
   upsertUserPromptSubmitHook
-} from "./chunk-DKTAW2N5.js";
+} from "./chunk-LO5EQSQA.js";
 import {
   startDispatcher,
   upsertMcpServer
@@ -12,7 +12,7 @@ import {
   listAccounts,
   renderSubagentMarkdown,
   resolveConfig
-} from "./chunk-SBP7MJP2.js";
+} from "./chunk-4VQP57SO.js";
 
 // src/install.ts
 import { existsSync, mkdirSync, readdirSync, writeFileSync, readFileSync, unlinkSync } from "fs";

package/dist/{chunk-O4H76K3B.js → chunk-Q5BA2J2C.js}

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

package/dist/{chunk-PTLX7SQV.js → chunk-TV7VG7YM.js}

@@ -1,15 +1,15 @@
 import {
   uninstall
-} from "./chunk-2GPBHK2M.js";
+} from "./chunk-2RVJ2Q3W.js";
 import {
   install
-} from "./chunk-ZTSWLNUP.js";
+} from "./chunk-OUYPF4ER.js";
 import {
   status
-} from "./chunk-O4H76K3B.js";
+} from "./chunk-Q5BA2J2C.js";
 import {
   AgenticMailApiError
-} from "./chunk-SBP7MJP2.js";
+} from "./chunk-4VQP57SO.js";
 
 // src/http-routes.ts
 import { Router } from "express";

package/dist/cli.js

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 import {
   uninstall
-} from "./chunk-2GPBHK2M.js";
+} from "./chunk-2RVJ2Q3W.js";
 import {
   install
-} from "./chunk-ZTSWLNUP.js";
-import "./chunk-DKTAW2N5.js";
+} from "./chunk-OUYPF4ER.js";
+import "./chunk-LO5EQSQA.js";
 import {
   status
-} from "./chunk-O4H76K3B.js";
+} from "./chunk-Q5BA2J2C.js";
 import "./chunk-US5FT2UB.js";
 import {
   AgenticMailApiError
-} from "./chunk-SBP7MJP2.js";
+} from "./chunk-4VQP57SO.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-QSR32ZGW.js";
-import "./chunk-SBP7MJP2.js";
+} from "./chunk-JOK76WRC.js";
+import "./chunk-4VQP57SO.js";
 
 // src/dispatcher-bin.ts
 async function main() {

package/dist/dispatcher.d.ts

@@ -119,6 +119,17 @@ interface DispatcherOptions extends ResolveConfigOptions {
     /** Override the AgentMemoryStore disk root. Same rationale as
      *  threadCacheDir — only tests should set this. */
     agentMemoryDir?: string;
+    /** Override the dispatcher state file (per-account cursors used
+     *  for restart recovery). Tests use a tmpdir; production runs
+     *  against ~/.agenticmail/dispatcher-state.json. */
+    stateFilePath?: string;
+    /**
+     * Disable catch-up scan + pending-task scan on channel open.
+     * Default false. Tests that don't want the dispatcher hitting the
+     * inbox/tasks endpoints on first connect set this true. Has no
+     * effect on the persisted seenUids restore — that's always on.
+     */
+    disableCatchupScan?: boolean;
 }
 /** Minimal Claude Agent SDK query signature we use. */
 interface QueryFn {
@@ -180,6 +191,21 @@ declare class Dispatcher {
      */
     private threadCache;
     private agentMemory;
+    /**
+     * Persistent dispatcher state — per-account `{ lastSeenUid, seenUids[] }`
+     * that survives a restart. On `start()` we use it to seed each
+     * channel's `seenUids` (so IMAP IDLE replays of old UIDs stay
+     * deduped) and to drive the catch-up scan (anything strictly
+     * newer than `lastSeenUid` got missed during downtime — route it
+     * through handleEvent like a synthetic SSE 'new' event).
+     *
+     * Writes are debounced inside the state module; we just call
+     * `markSeen(accountId, uid)` everywhere we decide on a UID.
+     */
+    private state;
+    /** Tracks which accounts have already gone through catch-up + pending-task scan
+     *  so reconnects don't replay the same backlog. */
+    private caughtUp;
     /**
      * Coalesced wake queue. Keyed by `${accountId}::${threadId}`,
      * each entry holds the pending events + the timer that will
@@ -204,6 +230,7 @@ declare class Dispatcher {
      *  events to wake on" — the host has no liveness signal. */
     private processHeartbeatTimer;
     constructor(opts?: DispatcherOptions);
+    private disableCatchupScan;
     /**
      * Charge one wake against the (agent, thread) budget. Returns true
      * if the wake should proceed, false if the circuit breaker is open.
@@ -270,6 +297,24 @@ declare class Dispatcher {
     private handleSystemEvent;
     /** Watch one account's SSE stream forever; reconnect with backoff on drop. */
     private runChannel;
+    /**
+     * One-shot backlog scan after a (re)connect: route unprocessed mail
+     * + pending tasks that arrived while the dispatcher was unreachable.
+     *
+     * Mail path: pull the newest 50 envelopes from `/mail/inbox`. For
+     * each UID strictly greater than the persisted `lastSeenUid` (and
+     * not already in the channel's `seenUids`), synthesise an SSE
+     * `new` event and hand it to `handleEvent`. The wake-budget
+     * circuit breaker still applies, so a runaway thread that hit
+     * the cap pre-restart STAYS muted — restart isn't a free reset.
+     *
+     * Tasks path: fetch `/tasks/pending`. Anything not in the
+     * channel's `seenTaskIds` becomes a synthetic task SSE event.
+     *
+     * Failures here are NEVER fatal — they're "best effort". The
+     * dispatcher continues processing live SSE traffic regardless.
+     */
+    private runCatchUp;
     /** Single SSE attach. Returns when the stream closes for any reason. */
     private streamOne;
     /**

package/dist/dispatcher.js

@@ -1,7 +1,7 @@
 import {
   Dispatcher
-} from "./chunk-QSR32ZGW.js";
-import "./chunk-SBP7MJP2.js";
+} from "./chunk-JOK76WRC.js";
+import "./chunk-4VQP57SO.js";
 export {
   Dispatcher
 };

package/dist/http-routes.js

@@ -1,12 +1,12 @@
 import {
   createIntegrationRoutes
-} from "./chunk-PTLX7SQV.js";
-import "./chunk-2GPBHK2M.js";
-import "./chunk-ZTSWLNUP.js";
-import "./chunk-DKTAW2N5.js";
-import "./chunk-O4H76K3B.js";
+} from "./chunk-TV7VG7YM.js";
+import "./chunk-2RVJ2Q3W.js";
+import "./chunk-OUYPF4ER.js";
+import "./chunk-LO5EQSQA.js";
+import "./chunk-Q5BA2J2C.js";
 import "./chunk-US5FT2UB.js";
-import "./chunk-SBP7MJP2.js";
+import "./chunk-4VQP57SO.js";
 export {
   createIntegrationRoutes
 };

package/dist/index.js

@@ -1,20 +1,20 @@
 import {
   Dispatcher,
   loadPersonaForAgent
-} from "./chunk-QSR32ZGW.js";
+} from "./chunk-JOK76WRC.js";
 import {
   createIntegrationRoutes
-} from "./chunk-PTLX7SQV.js";
+} from "./chunk-TV7VG7YM.js";
 import {
   uninstall
-} from "./chunk-2GPBHK2M.js";
+} from "./chunk-2RVJ2Q3W.js";
 import {
   install
-} from "./chunk-ZTSWLNUP.js";
-import "./chunk-DKTAW2N5.js";
+} from "./chunk-OUYPF4ER.js";
+import "./chunk-LO5EQSQA.js";
 import {
   status
-} from "./chunk-O4H76K3B.js";
+} from "./chunk-Q5BA2J2C.js";
 import "./chunk-US5FT2UB.js";
 import {
   AgenticMailApiError,
@@ -27,7 +27,7 @@ import {
   renderPersonaBody,
   renderSubagentMarkdown,
   resolveConfig
-} from "./chunk-SBP7MJP2.js";
+} from "./chunk-4VQP57SO.js";
 export {
   AgenticMailApiError,
   Dispatcher,

package/dist/install.js

@@ -1,10 +1,10 @@
 import {
   install,
   selectExposableAgents
-} from "./chunk-ZTSWLNUP.js";
-import "./chunk-DKTAW2N5.js";
+} from "./chunk-OUYPF4ER.js";
+import "./chunk-LO5EQSQA.js";
 import "./chunk-US5FT2UB.js";
-import "./chunk-SBP7MJP2.js";
+import "./chunk-4VQP57SO.js";
 export {
   install,
   selectExposableAgents

package/dist/mail-hook.js

@@ -7,6 +7,8 @@ import { join, dirname } from "path";
 var AGENTICMAIL_DIR = join(homedir(), ".agenticmail");
 var CONFIG_PATH = join(AGENTICMAIL_DIR, "config.json");
 var CURSOR_PATH = join(AGENTICMAIL_DIR, "claudecode-hook-cursor.json");
+var SESSIONS_PATH = join(AGENTICMAIL_DIR, "claudecode-hook-sessions.json");
+var SESSIONS_CAP = 100;
 var HOOK_VERSION = "1";
 var HTTP_TIMEOUT_MS = 800;
 var GLOBAL_TIMEOUT_MS = 1500;
@@ -47,17 +49,95 @@ async function readStdinJson() {
     setTimeout(() => finish(() => null), 200).unref();
   });
 }
+function capabilitiesBlurb() {
+  return [
+    "\u{1F380} AgenticMail is available via MCP (mcp__agenticmail__*).",
+    "",
+    "When to reach for it:",
+    "  \xB7 Building anything that benefits from MULTIPLE specialized roles working in parallel \u2014 designer + developer + reviewer, researcher + writer + fact-checker, planner + executor + critic.",
+    "  \xB7 Coordinating long-running async work that survives across Claude Code restarts (email threads are durable; in-memory state is not).",
+    "  \xB7 Anywhere you would otherwise spawn the Task tool repeatedly for sub-tasks \u2014 prefer AgenticMail when those sub-tasks need to talk to EACH OTHER, not just back to you.",
+    "",
+    "High-leverage tools:",
+    "  \xB7 mcp__agenticmail__create_account({ name, role })       \u2014 spawn a fresh persistent agent identity with its own inbox + API key.",
+    '  \xB7 mcp__agenticmail__send_email({ to, cc, subject, text, wake }) \u2014 kick off the work. CC the whole team; use `wake: ["alice"]` to give exactly one agent the next turn while others stay informed.',
+    "  \xB7 mcp__agenticmail__call_agent({ agent, message }) / mcp__agenticmail__wait_for_email \u2014 blocking RPC when you need a specific answer back before continuing your own turn.",
+    "",
+    "Coordination pattern: one email thread = the shared workspace. Reply-all keeps the audit trail. Use `wake` to control whose turn it is.",
+    "",
+    "Other tools cover: inbox/folder management, drafts, templates, tasks, contacts, signatures, SMS, voice. Full list under mcp__agenticmail__* \u2014 discover on demand, don't front-load them all."
+  ].join("\n");
+}
+function loadSeenSessions() {
+  if (!existsSync(SESSIONS_PATH)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(SESSIONS_PATH, "utf-8"));
+    const arr = Array.isArray(parsed?.seen) ? parsed.seen : [];
+    return arr.filter((s) => typeof s === "string");
+  } catch {
+    return [];
+  }
+}
+function rememberSession(sessionId, seen) {
+  const next = seen.filter((s) => s !== sessionId);
+  next.push(sessionId);
+  while (next.length > SESSIONS_CAP) next.shift();
+  try {
+    if (!existsSync(dirname(SESSIONS_PATH))) mkdirSync(dirname(SESSIONS_PATH), { recursive: true });
+    writeFileSync(SESSIONS_PATH, JSON.stringify({ seen: next, hookVersion: HOOK_VERSION }, null, 2));
+  } catch {
+  }
+}
 async function main() {
   const input = await readStdinJson();
   const eventName = input?.hook_event_name ?? "UserPromptSubmit";
-  if (!existsSync(CONFIG_PATH)) return;
+  const sessionId = typeof input?.session_id === "string" ? input.session_id : "";
+  if (eventName === "SessionStart") {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: capabilitiesBlurb()
+      }
+    }));
+    return;
+  }
+  let blurbContext = "";
+  if (eventName === "UserPromptSubmit" && sessionId) {
+    const seen = loadSeenSessions();
+    if (!seen.includes(sessionId)) {
+      blurbContext = capabilitiesBlurb();
+      rememberSession(sessionId, seen);
+    }
+  }
+  const emitAndExit = (mailContext) => {
+    const combined = [blurbContext, mailContext].filter(Boolean).join("\n\n");
+    if (!combined) return;
+    if (eventName === "Stop") {
+      process.stdout.write(JSON.stringify({ decision: "block", reason: combined }));
+    } else {
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: eventName,
+          additionalContext: combined
+        }
+      }));
+    }
+  };
+  if (!existsSync(CONFIG_PATH)) {
+    emitAndExit("");
+    return;
+  }
   let cfg;
   try {
     cfg = JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
   } catch {
+    emitAndExit("");
+    return;
+  }
+  if (!cfg.masterKey) {
+    emitAndExit("");
     return;
   }
-  if (!cfg.masterKey) return;
   const apiHost = cfg.api?.host ?? "127.0.0.1";
   const apiPort = cfg.api?.port ?? 3829;
   const apiUrl = `http://${apiHost}:${apiPort}`;
@@ -67,15 +147,22 @@ async function main() {
       headers: { Authorization: `Bearer ${cfg.masterKey}` },
       signal: AbortSignal.timeout(HTTP_TIMEOUT_MS)
     });
-    if (!r.ok) return;
+    if (!r.ok) {
+      emitAndExit("");
+      return;
+    }
     const data = await r.json();
     bridge = (data.agents ?? []).find(
       (a) => a.name === "claudecode" || a.name === "claude" || a.role === "bridge"
     );
   } catch {
+    emitAndExit("");
+    return;
+  }
+  if (!bridge?.apiKey) {
+    emitAndExit("");
     return;
   }
-  if (!bridge?.apiKey) return;
   let cursorMs = 0;
   let lastCheckedMs = 0;
   if (existsSync(CURSOR_PATH)) {
@@ -96,10 +183,14 @@ async function main() {
       headers: { Authorization: `Bearer ${bridge.apiKey}` },
       signal: AbortSignal.timeout(HTTP_TIMEOUT_MS)
     });
-    if (!r.ok) return;
+    if (!r.ok) {
+      emitAndExit("");
+      return;
+    }
     const data = await r.json();
     messages = data.messages ?? [];
   } catch {
+    emitAndExit("");
     return;
   }
   const newOnes = messages.filter((m) => {
@@ -118,6 +209,7 @@ async function main() {
       } catch {
       }
     }
+    emitAndExit("");
     return;
   }
   newOnes.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
@@ -149,19 +241,7 @@ async function main() {
     );
   } catch {
   }
-  if (eventName === "Stop") {
-    process.stdout.write(JSON.stringify({
-      decision: "block",
-      reason: lines.join("\n")
-    }));
-  } else {
-    process.stdout.write(JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: eventName,
-        additionalContext: lines.join("\n")
-      }
-    }));
-  }
+  emitAndExit(lines.join("\n"));
 }
 var globalTimeout = new Promise((resolve) => {
   setTimeout(() => resolve(), GLOBAL_TIMEOUT_MS).unref();

package/dist/status.js

@@ -1,8 +1,8 @@
 import {
   status
-} from "./chunk-O4H76K3B.js";
+} from "./chunk-Q5BA2J2C.js";
 import "./chunk-US5FT2UB.js";
-import "./chunk-SBP7MJP2.js";
+import "./chunk-4VQP57SO.js";
 export {
   status
 };

package/dist/uninstall.js

@@ -1,9 +1,9 @@
 import {
   uninstall
-} from "./chunk-2GPBHK2M.js";
-import "./chunk-DKTAW2N5.js";
+} from "./chunk-2RVJ2Q3W.js";
+import "./chunk-LO5EQSQA.js";
 import "./chunk-US5FT2UB.js";
-import "./chunk-SBP7MJP2.js";
+import "./chunk-4VQP57SO.js";
 export {
   uninstall
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/claudecode",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "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",