@leadbay/mcp 0.17.3 → 0.18.0

package/dist/bin.js

@@ -553,6 +553,23 @@ var init_client = __esm({
         await this.resolveOrgId();
         await this.resolveTasteProfile();
       }
+      // ─── Notifications helpers ────────────────────────────────────────────
+      // Backend exposes `GET /notifications`, `POST /notifications/{id}/seen`,
+      // `POST /notifications/{id}/archive`, plus `GET /ws/ticket?v=1.0` to mint
+      // a one-shot WS URL. See backend/docs/adr/notifications.md for shape.
+      async listNotifications(args = {}) {
+        const params = new URLSearchParams();
+        params.set("archived", String(args.archived ?? false));
+        params.set("page", String(args.page ?? 0));
+        params.set("count", String(args.count ?? 50));
+        return this.request("GET", `/notifications?${params.toString()}`);
+      }
+      async acknowledgeNotification(notificationId, action = "seen") {
+        await this.requestVoid("POST", `/notifications/${notificationId}/${action}`);
+      }
+      async getWsTicket() {
+        return this.request("GET", "/auth/ws?v=1.0");
+      }
       makeError(code, message, hint, endpoint, retry_after, http_status) {
         const out = { error: true, code, message, hint };
         if (endpoint || this._region) {
@@ -5122,8 +5139,306 @@ var init_composite_file_names = __esm({
   }
 });
 
+// ../core/dist/notifications/revise-hint.js
+function reviseHintFor(kind) {
+  switch (kind) {
+    case "bulk_enrich":
+      return HINT_BULK_ENRICH;
+    case "bulk_qualify":
+      return HINT_BULK_QUALIFY;
+    case "import":
+      return HINT_IMPORT;
+    default:
+      return HINT_OTHER;
+  }
+}
+function inferKind(n) {
+  if (n.links.some((l) => l.type === "bulk_enrichment"))
+    return "bulk_enrich";
+  if (n.file_import_id)
+    return "import";
+  if (n.bulk_progress)
+    return "bulk_qualify";
+  return "other";
+}
+function anchorIdFor(n, kind) {
+  if (kind === "bulk_enrich") {
+    const link = n.links.find((l) => l.type === "bulk_enrichment");
+    return link ? String(link.id) : null;
+  }
+  if (kind === "import")
+    return n.file_import_id;
+  return null;
+}
+function toInboxEntry(n) {
+  const kind = inferKind(n);
+  return {
+    notification_id: n.id,
+    kind,
+    anchor_id: anchorIdFor(n, kind),
+    title: n.title,
+    bulk_progress: n.bulk_progress,
+    completed_at: n.updated_at,
+    revise_hint: reviseHintFor(kind)
+  };
+}
+var HINT_BULK_ENRICH, HINT_BULK_QUALIFY, HINT_IMPORT, HINT_OTHER;
+var init_revise_hint = __esm({
+  "../core/dist/notifications/revise-hint.js"() {
+    "use strict";
+    HINT_BULK_ENRICH = "Contact enrichment just finished. Revise any prior output that named these leads' contacts (outreach drafts, contact lists, recommended-lead lists with contact_count, NEXT STEPS asking the user to wait for emails / phones). Re-fetch contacts via leadbay_get_contacts for the affected leads.";
+    HINT_BULK_QUALIFY = "Lead qualification just finished. Revise any prior lead list / ranking / outreach shortlist that depended on ai_agent_lead_score for these leads \u2014 today's leads, top-of-inbox, followups maps, prepare-outreach shortlists. Re-pull qualification answers via leadbay_research_lead_by_id or re-rank via leadbay_pull_leads.";
+    HINT_IMPORT = "CSV / CRM import just finished. Revise any prior output that referenced 'leads available' before the import landed \u2014 lead lists pulled from the affected lens, 'what's new today', followup planning. Re-pull the affected lens via leadbay_pull_leads / leadbay_pull_followups.";
+    HINT_OTHER = "Background work just completed. If you referenced its subject in prior output, re-fetch the affected data and revise.";
+  }
+});
+
+// ../core/dist/notifications/inbox.js
+var DEFAULT_TTL_MS, NotificationsInbox;
+var init_inbox = __esm({
+  "../core/dist/notifications/inbox.js"() {
+    "use strict";
+    init_revise_hint();
+    DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
+    NotificationsInbox = class {
+      entries = /* @__PURE__ */ new Map();
+      ttl_ms;
+      now;
+      constructor(opts = {}) {
+        this.ttl_ms = opts.ttl_ms ?? DEFAULT_TTL_MS;
+        this.now = opts.now ?? Date.now;
+      }
+      // Upsert by notification id. Latest write wins so duplicate arrivals
+      // (WS event + REST catch-up landing the same row) collapse cleanly.
+      record(n) {
+        if (!n.bulk_progress)
+          return;
+        if (n.in_progress)
+          return;
+        const entry = toInboxEntry(n);
+        this.entries.set(entry.notification_id, {
+          entry,
+          recordedAt: this.now()
+        });
+      }
+      list() {
+        this.expireStale();
+        return [...this.entries.values()].map((e) => e.entry);
+      }
+      markSeen(notification_id) {
+        this.entries.delete(notification_id);
+      }
+      size() {
+        this.expireStale();
+        return this.entries.size;
+      }
+      expireStale() {
+        const cutoff = this.now() - this.ttl_ms;
+        for (const [id, e] of this.entries) {
+          if (e.recordedAt < cutoff)
+            this.entries.delete(id);
+        }
+      }
+    };
+  }
+});
+
+// ../core/dist/notifications/catch-up.js
+async function catchUpNotifications(client, inbox, opts = {}) {
+  const count = opts.count ?? DEFAULT_COUNT;
+  let added = 0;
+  try {
+    const page = await client.listNotifications({
+      archived: false,
+      page: 0,
+      count
+    });
+    for (const n of page.items) {
+      if (!n.bulk_progress)
+        continue;
+      if (n.in_progress)
+        continue;
+      if (n.first_seen_at)
+        continue;
+      const sizeBefore = inbox.size();
+      inbox.record(n);
+      if (inbox.size() > sizeBefore)
+        added += 1;
+    }
+    opts.logger?.info?.(`notifications.catch_up scanned=${page.items.length} seeded=${added}`);
+  } catch (err) {
+    opts.logger?.warn?.(`notifications.catch_up failed: ${err?.message ?? err?.code ?? err}`);
+  }
+  return added;
+}
+var DEFAULT_COUNT;
+var init_catch_up = __esm({
+  "../core/dist/notifications/catch-up.js"() {
+    "use strict";
+    DEFAULT_COUNT = 50;
+  }
+});
+
+// ../core/dist/notifications/ws-client.js
+var PING_INTERVAL_MS, RECONNECT_INITIAL_MS, RECONNECT_MAX_MS, NotificationsWsClient;
+var init_ws_client = __esm({
+  "../core/dist/notifications/ws-client.js"() {
+    "use strict";
+    init_catch_up();
+    PING_INTERVAL_MS = 3e4;
+    RECONNECT_INITIAL_MS = 1e3;
+    RECONNECT_MAX_MS = 3e4;
+    NotificationsWsClient = class {
+      client;
+      inbox;
+      logger;
+      ws = null;
+      pingTimer = null;
+      reconnectTimer = null;
+      reconnectDelay = RECONNECT_INITIAL_MS;
+      stopped = false;
+      constructor(opts) {
+        this.client = opts.client;
+        this.inbox = opts.inbox;
+        this.logger = opts.logger;
+      }
+      async start() {
+        this.stopped = false;
+        await catchUpNotifications(this.client, this.inbox, { logger: this.logger });
+        void this.connect();
+      }
+      stop() {
+        this.stopped = true;
+        if (this.pingTimer)
+          clearInterval(this.pingTimer);
+        if (this.reconnectTimer)
+          clearTimeout(this.reconnectTimer);
+        this.pingTimer = null;
+        this.reconnectTimer = null;
+        if (this.ws) {
+          try {
+            this.ws.close(1e3, "shutdown");
+          } catch {
+          }
+          this.ws = null;
+        }
+      }
+      async connect() {
+        if (this.stopped)
+          return;
+        let url;
+        try {
+          const ticket = await this.client.getWsTicket();
+          url = ticket.url;
+        } catch (err) {
+          this.logger?.warn?.(`notifications.ws ticket_fetch_failed: ${err?.message ?? err?.code ?? err}`);
+          this.scheduleReconnect();
+          return;
+        }
+        let ws;
+        try {
+          ws = new WebSocket(url);
+        } catch (err) {
+          this.logger?.warn?.(`notifications.ws construct_failed: ${err?.message ?? err}`);
+          this.scheduleReconnect();
+          return;
+        }
+        this.ws = ws;
+        ws.addEventListener("open", () => {
+          this.logger?.info?.("notifications.ws connected");
+          this.reconnectDelay = RECONNECT_INITIAL_MS;
+          void catchUpNotifications(this.client, this.inbox, {
+            logger: this.logger
+          });
+          this.pingTimer = setInterval(() => this.sendPing(), PING_INTERVAL_MS);
+        });
+        ws.addEventListener("message", (ev) => {
+          const text = typeof ev.data === "string" ? ev.data : String(ev.data ?? "");
+          if (!text)
+            return;
+          let msg;
+          try {
+            msg = JSON.parse(text);
+          } catch {
+            this.logger?.warn?.("notifications.ws non_json_frame");
+            return;
+          }
+          this.handleMessage(msg);
+        });
+        ws.addEventListener("error", (ev) => {
+          this.logger?.warn?.(`notifications.ws error: ${ev?.message ?? "(no detail)"}`);
+        });
+        ws.addEventListener("close", (ev) => {
+          this.logger?.info?.(`notifications.ws closed code=${ev.code} reason=${ev.reason || "(none)"}`);
+          if (this.pingTimer)
+            clearInterval(this.pingTimer);
+          this.pingTimer = null;
+          this.ws = null;
+          this.scheduleReconnect();
+        });
+      }
+      handleMessage(msg) {
+        if (msg.type === "pong")
+          return;
+        if (msg.type === "ping") {
+          this.sendRaw({ type: "pong" });
+          return;
+        }
+        if (msg.type !== "notification")
+          return;
+        const { type: _t, ...rest } = msg;
+        void _t;
+        const n = rest;
+        if (n.bulk_progress == null || n.in_progress) {
+          return;
+        }
+        this.inbox.record(n);
+        this.logger?.info?.(`notifications.ws terminal id=${n.id} kind=${n.file_import_id ? "import" : n.links.some((l) => l.type === "bulk_enrichment") ? "bulk_enrich" : "bulk_qualify"}`);
+      }
+      sendPing() {
+        this.sendRaw({ type: "ping" });
+      }
+      sendRaw(obj) {
+        if (!this.ws)
+          return;
+        if (this.ws.readyState !== WebSocket.OPEN)
+          return;
+        try {
+          this.ws.send(JSON.stringify(obj));
+        } catch (err) {
+          this.logger?.warn?.(`notifications.ws send_failed: ${err?.message ?? err}`);
+        }
+      }
+      scheduleReconnect() {
+        if (this.stopped)
+          return;
+        if (this.reconnectTimer)
+          return;
+        const delay = this.reconnectDelay;
+        this.reconnectDelay = Math.min(this.reconnectDelay * 2, RECONNECT_MAX_MS);
+        this.reconnectTimer = setTimeout(() => {
+          this.reconnectTimer = null;
+          void this.connect();
+        }, delay);
+        this.logger?.info?.(`notifications.ws reconnect_in_${delay}ms`);
+      }
+    };
+  }
+});
+
+// ../core/dist/notifications/index.js
+var init_notifications = __esm({
+  "../core/dist/notifications/index.js"() {
+    "use strict";
+    init_inbox();
+    init_ws_client();
+    init_catch_up();
+    init_revise_hint();
+  }
+});
+
 // ../core/dist/tool-descriptions.generated.js
-var leadbay_account_status, leadbay_add_leads_to_campaign, leadbay_add_note, leadbay_adjust_audience, leadbay_agent_memory_capture, leadbay_agent_memory_recall, leadbay_agent_memory_review, leadbay_answer_clarification, leadbay_bulk_enrich_status, leadbay_bulk_qualify_leads, leadbay_campaign_call_sheet, leadbay_campaign_progression, leadbay_clear_selection, leadbay_clear_user_prompt, leadbay_create_campaign, leadbay_create_custom_field, leadbay_create_lens, leadbay_create_lens_draft, leadbay_create_topup_link, leadbay_deselect_leads, leadbay_discover_leads, leadbay_dislike_lead, leadbay_dismiss_clarification, leadbay_enrich_contacts, leadbay_enrich_titles, leadbay_extend_lens, leadbay_followups_map, leadbay_get_clarification, leadbay_get_contacts, leadbay_get_enrichment_job_titles, leadbay_get_epilogue_responses, leadbay_get_lead_activities, leadbay_get_lead_notes, leadbay_get_lead_profile, leadbay_get_lens_filter, leadbay_get_lens_scoring, leadbay_get_prospecting_actions, leadbay_get_quota, leadbay_get_selection_ids, leadbay_get_taste_profile, leadbay_get_user_prompt, leadbay_get_web_fetch, leadbay_import_and_qualify, leadbay_import_leads, leadbay_import_status, leadbay_launch_bulk_enrichment, leadbay_like_lead, leadbay_list_campaigns, leadbay_list_lenses, leadbay_list_locations, leadbay_list_mappable_fields, leadbay_list_sectors, leadbay_login, leadbay_my_lenses, leadbay_new_lens, leadbay_open_billing_portal, leadbay_pick_clarification, leadbay_prepare_outreach, leadbay_preview_bulk_enrichment, leadbay_promote_lens, leadbay_pull_followups, leadbay_pull_leads, leadbay_qualify_lead, leadbay_qualify_status, leadbay_recall_ordered_titles, leadbay_refine_prompt, leadbay_remove_epilogue, leadbay_remove_leads_from_campaign, leadbay_remove_pushback, leadbay_report_friction, leadbay_report_outreach, leadbay_research_lead_by_id, leadbay_research_lead_by_name_fuzzy, leadbay_resolve_import_rows, leadbay_seed_candidates, leadbay_select_leads, leadbay_set_active_lens, leadbay_set_epilogue_status, leadbay_set_pushback, leadbay_set_user_prompt, leadbay_tour_plan, leadbay_update_lens, leadbay_update_lens_filter;
+var leadbay_account_status, leadbay_acknowledge_notification, leadbay_add_leads_to_campaign, leadbay_add_note, leadbay_adjust_audience, leadbay_agent_memory_capture, leadbay_agent_memory_recall, leadbay_agent_memory_review, leadbay_answer_clarification, leadbay_bulk_enrich_status, leadbay_bulk_qualify_leads, leadbay_campaign_call_sheet, leadbay_campaign_progression, leadbay_clear_selection, leadbay_clear_user_prompt, leadbay_create_campaign, leadbay_create_custom_field, leadbay_create_lens, leadbay_create_lens_draft, leadbay_create_topup_link, leadbay_deselect_leads, leadbay_discover_leads, leadbay_dislike_lead, leadbay_dismiss_clarification, leadbay_enrich_contacts, leadbay_enrich_titles, leadbay_extend_lens, leadbay_followups_map, leadbay_get_clarification, leadbay_get_contacts, leadbay_get_enrichment_job_titles, leadbay_get_epilogue_responses, leadbay_get_lead_activities, leadbay_get_lead_notes, leadbay_get_lead_profile, leadbay_get_lens_filter, leadbay_get_lens_scoring, leadbay_get_prospecting_actions, leadbay_get_quota, leadbay_get_selection_ids, leadbay_get_taste_profile, leadbay_get_user_prompt, leadbay_get_web_fetch, leadbay_import_and_qualify, leadbay_import_leads, leadbay_import_status, leadbay_launch_bulk_enrichment, leadbay_like_lead, leadbay_list_campaigns, leadbay_list_lenses, leadbay_list_locations, leadbay_list_mappable_fields, leadbay_list_sectors, leadbay_login, leadbay_my_lenses, leadbay_new_lens, leadbay_open_billing_portal, leadbay_pick_clarification, leadbay_prepare_outreach, leadbay_preview_bulk_enrichment, leadbay_promote_lens, leadbay_pull_followups, leadbay_pull_leads, leadbay_qualify_lead, leadbay_qualify_status, leadbay_recall_ordered_titles, leadbay_refine_prompt, leadbay_remove_epilogue, leadbay_remove_leads_from_campaign, leadbay_remove_pushback, leadbay_report_friction, leadbay_report_outreach, leadbay_research_lead_by_id, leadbay_research_lead_by_name_fuzzy, leadbay_resolve_import_rows, leadbay_seed_candidates, leadbay_select_leads, leadbay_set_active_lens, leadbay_set_epilogue_status, leadbay_set_pushback, leadbay_set_user_prompt, leadbay_tour_plan, leadbay_update_lens, leadbay_update_lens_filter;
 var init_tool_descriptions_generated = __esm({
   "../core/dist/tool-descriptions.generated.js"() {
     "use strict";
@@ -5162,9 +5477,52 @@ Show the user's account state \u2014 admin rights, language, last-active lens, c
 
 **After a user tops up, do NOT keep refusing \u2014 RETRY.** If the user signals they topped up / bought credits / added credits, the previous QUOTA_EXCEEDED is invalidated the moment the Stripe webhook lands. RE-CALL \`leadbay_account_status\` to pick up the new state AND retry the originally failed call. The retry itself does not require a successful account_status check first \u2014 a topped-up user has cleared the throttle whether or not your cached snapshot reflects it yet. If the retry hits the wall again, only then re-offer top-up / wait. **A stale quota snapshot is never a reason to gate-keep a topped-up user.**
 
+**\`notifications\` block.** The response now includes a top-level \`notifications\` array listing background work the user (or agent) initiated that has since completed (\`bulk_enrich\`, \`bulk_qualify\`, \`import\`). These are signals to revise prior agent outputs the just-finished work might have made stale \u2014 they're NOT a pending-task list for the user. After revising (or confirming nothing is affected), call \`leadbay_acknowledge_notification(notification_id)\`. Full handling protocol below.
+
+## GATE \u2014 INSPECT \`_meta.notifications\` ON EVERY RESPONSE
+
+Some Leadbay tool responses include a \`_meta.notifications\` array listing **background work the user (or you) initiated that has since completed**. The three relevant kinds:
+
+| Kind | What just finished |
+|---|---|
+| \`bulk_enrich\` | A bulk contact-enrichment job (emails / phone numbers attached to leads' contacts). |
+| \`bulk_qualify\` | A bulk lead-qualification job (web-fetch + AI rescore, producing \`ai_agent_lead_score\` and qualification answers). |
+| \`import\` | A CSV / CRM file import (rows resolved to leads in the user's pipeline). |
+
+**Your job when you see an entry: revise prior outputs the just-finished work might have made stale.** This is NOT a pending-task list. It's a "your earlier answer used data that has now changed" signal.
+
+| Kind | Outputs you've produced that may now be stale \u2014 refresh them |
+|---|---|
+| \`bulk_enrich\` | Outreach drafts mentioning these leads' contacts; contact lists; recommended-lead lists citing \`contact_count\`; NEXT STEPS that asked the user to wait for emails / phones. Re-fetch via \`leadbay_get_contacts(leadId)\` for the affected leads. |
+| \`bulk_qualify\` | Lead rankings / shortlists you produced without \`ai_agent_lead_score\`; "today's leads"; followup maps; prepare-outreach picks. Re-pull via \`leadbay_pull_leads\` / \`leadbay_research_lead_by_id\`. |
+| \`import\` | "Available leads" claims; pulls from the affected lens that ran before the import landed; followup planning that needed the imported set. Re-pull via \`leadbay_pull_leads\` / \`leadbay_pull_followups\`. |
+
+**After revising (or after confirming no prior output is affected):** call \`leadbay_acknowledge_notification(notification_id)\` so the entry stops resurfacing on every tool response. Ack-and-move-on is correct even when nothing was stale \u2014 that's how the inbox stays focused on what's actually pending.
+
+**Do NOT** interpret these entries as "things waiting for the user." The user expects you to handle them silently. They are signals to YOU \u2014 agent \u2014 that prior outputs need a refresh.
+
+**Don't poll.** When you launch a long operation (enrichment / qualification / import), simply continue the conversation \u2014 the next time you call any tool, the completed-work entry will appear in \`_meta.notifications\`. Status tools (\`leadbay_bulk_enrich_status\`, \`leadbay_qualify_status\`, \`leadbay_import_status\`) exist for the case where you want the answer NOW (mid-conversation), not for ambient polling.
+
+Also surfaced as a top-level \`notifications\` array on \`leadbay_account_status\` \u2014 same shape, same handling.
+
+
 WHEN TO USE: at the start of a session to know what the agent can/can't do, after a 429 to explain to the user which resource window was exhausted and when it resets (and to offer the top-up alternative), and after the user signals a top-up so the agent can resume the interrupted workflow.
 
 WHEN NOT TO USE: as a pre-flight gate before bulk ops \u2014 operations themselves return 429; this tool is for context, not gating. And: a recent quota snapshot showing "exhausted" is NOT a reason to refuse a write call when the user has just topped up \u2014 re-call this tool first, then proceed.
+`;
+    leadbay_acknowledge_notification = `Acknowledge a Leadbay notification \u2014 i.e. tell the MCP and the backend "I've seen this and acted on it." Wraps \`POST /1.5/notifications/{id}/seen\` (default) or \`/archive\` (when \`archive:true\`) and drops the entry from the local inbox so subsequent \`_meta.notifications\` payloads stop carrying it.
+
+**When to call.** After you read an entry from \`_meta.notifications\` or \`account_status.notifications\` and have revised whatever prior output the just-finished background work might have made stale (outreach drafts, lead lists, "available leads" claims, followup plans). Mark-seen tells the human team's pipeline you handled this and prevents the notification from re-surfacing on every subsequent tool response.
+
+If nothing you produced for the user is affected, ack anyway with \`archive:false\` \u2014 the entry should still clear so the inbox stays focused on what's actually pending.
+
+Use \`archive:true\` only when you want the row gone from the FE notification dropdown too (e.g. a non-actionable system notification that's already handled). Default behaviour is \`seen\` \u2014 same as the FE dropdown's "click to read" semantics.
+
+WHEN TO USE: immediately after you finish reviewing / revising in response to a \`_meta.notifications[]\` entry. Idempotent \u2014 calling twice with the same id is safe.
+
+WHEN NOT TO USE: before doing the revision work; for general "mark all read" sweeps (call once per notification id you've actually consumed).
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 `;
     leadbay_add_leads_to_campaign = `## WHEN TO USE
 
@@ -10199,9 +10557,23 @@ async function completeUploadedChunk(client, upload, mappings, dryRun, perPhaseB
   await pollPreprocess(client, importId, phaseBudget, ctx, signal);
   ctx?.logger?.info?.(`import-leads: preprocess done for importId=${importId}`);
   if (dryRun) {
-    return { importId, records: [] };
+    return { importId, records: [], notification_id: null };
+  }
+  let updateMappingsResp = null;
+  try {
+    updateMappingsResp = await client.request("POST", `/imports/${importId}/update_mappings`, mappings);
+  } catch (err) {
+    if (err?.code === "API_ERROR" || err?.code === "NOT_FOUND") {
+      ctx?.logger?.warn?.(`import-leads: update_mappings raw error (${err?.code}); retrying void`);
+      await client.requestVoid("POST", `/imports/${importId}/update_mappings`, mappings);
+    } else {
+      throw err;
+    }
+  }
+  const importNotificationId = updateMappingsResp?.notification_id ?? null;
+  if (importNotificationId) {
+    ctx?.logger?.info?.(`import-leads: notification_id=${importNotificationId} importId=${importId}`);
   }
-  await client.requestVoid("POST", `/imports/${importId}/update_mappings`, mappings);
   ctx?.logger?.info?.(`import-leads: mappings committed for importId=${importId}`);
   const phaseBudget2 = Math.min(perPhaseBudgetMs, Math.max(1, totalDeadline - Date.now()));
   await pollProcess(client, importId, phaseBudget2, ctx, signal);
@@ -10209,7 +10581,7 @@ async function completeUploadedChunk(client, upload, mappings, dryRun, perPhaseB
   const phaseBudget3 = Math.min(perPhaseBudgetMs, Math.max(1, totalDeadline - Date.now()));
   const records = await pollRecordsToTerminal(client, importId, phaseBudget3, chunk.length, ctx, signal);
   ctx?.logger?.info?.(`import-leads: ${records.length} records terminal for importId=${importId}`);
-  return { importId, records };
+  return { importId, records, notification_id: importNotificationId };
 }
 function reconcileOneChunk(prep, chunk, matched, notImported) {
   const seenInputIndex = /* @__PURE__ */ new Set();
@@ -10265,7 +10637,7 @@ function reconcileOneChunk(prep, chunk, matched, notImported) {
     }
   }
 }
-function buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled) {
+function buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled, notificationIds) {
   const leads = [];
   const not_imported = [];
   if (dryRun) {
@@ -10330,6 +10702,7 @@ function buildImportLeadsResult(client, prep, importIds, matched, notImported, d
     leads,
     not_imported,
     importIds,
+    notification_ids: notificationIds,
     region: client.region,
     cancelled: cancelled || void 0,
     dry_run: dryRun || void 0,
@@ -10355,17 +10728,21 @@ async function runImportInBackground(client, prep, uploadedChunks, opts, ctx, ha
     void (async () => {
       const bgCtx = { logger: ctx.logger, bulkTracker: tracker };
       const importIds = uploadedChunks.map((chunk) => chunk.importId);
+      const notificationIds = [];
       const matched = /* @__PURE__ */ new Map();
       const notImported = /* @__PURE__ */ new Map();
       try {
         const totalDeadline = Date.now() + opts.totalBudget;
         for (const upload of uploadedChunks) {
           const out = await completeUploadedChunk(client, upload, prep.mappings, opts.dryRun, opts.perPhaseBudget, totalDeadline, bgCtx, void 0);
+          if (out.notification_id && !notificationIds.includes(out.notification_id)) {
+            notificationIds.push(out.notification_id);
+          }
           if (!opts.dryRun) {
             reconcileOneChunk(prep, out, matched, notImported);
           }
         }
-        const result = buildImportLeadsResult(client, prep, importIds, matched, notImported, opts.dryRun, false);
+        const result = buildImportLeadsResult(client, prep, importIds, matched, notImported, opts.dryRun, false, notificationIds);
         await tracker.markImportComplete(handleId, {
           leads: result.leads,
           not_imported: result.not_imported,
@@ -10598,6 +10975,7 @@ var init_import_leads = __esm({
             leads: [],
             not_imported,
             importIds: [],
+            notification_ids: [],
             region: client.region,
             dry_run: dryRun || void 0,
             _meta: client.lastMeta ?? {
@@ -10652,6 +11030,10 @@ var init_import_leads = __esm({
             status: "running",
             handle_id: reservation.record.bulk_id,
             importIds: importIds2,
+            // Notifications fire from update_mappings, which the background
+            // task hasn't called yet at this point. They surface via the WS
+            // listener / catch-up REST on subsequent agent turns.
+            notification_ids: [],
             progress: {
               phase: reservation.record.status === "complete" ? "complete" : importIds2.length > 0 ? "preprocess" : "queued",
               records_processed: reservation.record.status === "complete" ? reservation.record.records_total : 0,
@@ -10672,6 +11054,7 @@ var init_import_leads = __esm({
         }
         ctx?.logger?.info?.(`import-leads(${prep.mode}): ${prep.validInputs.length} rows \u2192 ${chunks.length} chunk(s); dry_run=${dryRun}, totalBudgetMs=${totalBudget}`);
         const importIds = [];
+        const notificationIds = [];
         const matched = /* @__PURE__ */ new Map();
         const notImported = /* @__PURE__ */ new Map();
         let cancelled = false;
@@ -10683,6 +11066,9 @@ var init_import_leads = __esm({
           for (let i = 0; i < chunks.length; i++) {
             const chunk = chunks[i];
             const out = await runOneChunk(client, chunk, i, chunks.length, prep.header, prep.mappings, dryRun, perPhaseBudget, totalDeadline, ctx, signal, recordImportId);
+            if (out.notification_id && !notificationIds.includes(out.notification_id)) {
+              notificationIds.push(out.notification_id);
+            }
             if (!dryRun) {
               reconcileOneChunk(prep, out, matched, notImported);
             }
@@ -10703,7 +11089,7 @@ var init_import_leads = __esm({
             throw err;
           }
         }
-        return buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled);
+        return buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled, notificationIds);
       }
     };
   }
@@ -11411,6 +11797,70 @@ var init_agent_memory_review = __esm({
   }
 });
 
+// ../core/dist/tools/acknowledge-notification.js
+var UUID_RE, acknowledgeNotification;
+var init_acknowledge_notification = __esm({
+  "../core/dist/tools/acknowledge-notification.js"() {
+    "use strict";
+    init_tool_descriptions_generated();
+    UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    acknowledgeNotification = {
+      name: "leadbay_acknowledge_notification",
+      annotations: {
+        title: "Acknowledge a Leadbay notification",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      description: leadbay_acknowledge_notification,
+      write: true,
+      inputSchema: {
+        type: "object",
+        properties: {
+          notification_id: {
+            type: "string",
+            description: "UUID of the notification to acknowledge. Use the notification_id from `_meta.notifications[]` or `account_status.notifications[]`."
+          },
+          archive: {
+            type: "boolean",
+            description: "If true, archive the notification (won't appear in `archived=false` listings). If false / omitted, mark seen (resets firstSeenAt)."
+          }
+        },
+        required: ["notification_id"],
+        additionalProperties: false
+      },
+      outputSchema: {
+        type: "object",
+        properties: {
+          acknowledged: { type: "boolean" },
+          notification_id: { type: "string" },
+          action: { type: "string", enum: ["seen", "archive"] }
+        },
+        required: ["acknowledged", "notification_id", "action"]
+      },
+      execute: async (client, params, ctx) => {
+        if (!UUID_RE.test(params.notification_id)) {
+          return {
+            error: true,
+            code: "BAD_INPUT",
+            message: "notification_id must be a UUID",
+            hint: "Pass the notification_id verbatim from _meta.notifications[].notification_id or account_status.notifications[].notification_id."
+          };
+        }
+        const action = params.archive ? "archive" : "seen";
+        await client.acknowledgeNotification(params.notification_id, action);
+        ctx?.notificationsInbox?.markSeen(params.notification_id);
+        return {
+          acknowledged: true,
+          notification_id: params.notification_id,
+          action
+        };
+      }
+    };
+  }
+});
+
 // ../core/dist/tools/select-leads.js
 var selectLeads;
 var init_select_leads = __esm({
@@ -14760,6 +15210,11 @@ var init_account_status = __esm({
             type: ["object", "null"],
             description: "Per-resource quota state (llm_completion, ai_rescore, web_fetch, LENS_EXTRA_REFILL) across daily/weekly/monthly windows. Null if /quota_status failed (logged in stderr). Pre-check the LENS_EXTRA_REFILL entry before calling leadbay_extend_lens."
           },
+          notifications: {
+            type: "array",
+            description: "Terminal bulk-progress notifications the MCP knows about (background work the user or agent started that has since completed). Each entry carries notification_id, kind (bulk_enrich | bulk_qualify | import | other), bulk_progress counters, and a revise_hint pointing at prior agent outputs the just-finished work might have made stale. After revising affected outputs, call leadbay_acknowledge_notification(notification_id) to clear the entry. Empty array when nothing has completed.",
+            items: { type: "object" }
+          },
           _meta: {
             type: "object",
             properties: {
@@ -14819,6 +15274,13 @@ var init_account_status = __esm({
           // on /me are intentionally NOT surfaced — they're defunct (see
           // SHAPE-DRIFT.md probe round 4).
           quota,
+          // Inbox of terminal bulk-progress notifications. Same shape the MCP
+          // server attaches to `_meta.notifications` on every tool response —
+          // duplicated here as a top-level field so the agent's daily-rhythm
+          // check-in (this composite) sees them without having to read _meta.
+          // Empty array when the WS listener isn't wired (OpenClaw, tests) OR
+          // when nothing has completed since the last ack.
+          notifications: ctx?.notificationsInbox?.list() ?? [],
           _meta: {
             region: client.region
           }
@@ -14829,13 +15291,40 @@ var init_account_status = __esm({
 });
 
 // ../core/dist/composite/bulk-qualify-leads.js
-var PAGE_SIZE, DEFAULT_COUNT, MAX_COUNT, DEFAULT_PER_LEAD_BUDGET_MS, DEFAULT_TOTAL_BUDGET_MS2, bulkQualifyLeads;
+async function launchBulkQualify(client, leadIds, ctx) {
+  await client.acquireSelectionLock();
+  try {
+    try {
+      const qs = leadIds.map((id) => `leadIds=${encodeURIComponent(id)}`).join("&");
+      await client.requestVoid("POST", `/leads/selection/select?${qs}`);
+      try {
+        const resp = await client.request("POST", "/leads/selection/web_fetch?force_fetch=false", {});
+        return { resp, quotaExceeded: false };
+      } catch (err) {
+        if (err?.code === "QUOTA_EXCEEDED") {
+          ctx?.logger?.warn?.("bulk_qualify_leads: 429 on bulk /leads/selection/web_fetch \u2014 no leads queued");
+          return { resp: null, quotaExceeded: true };
+        }
+        throw err;
+      }
+    } finally {
+      try {
+        await client.requestVoid("POST", "/leads/selection/clear");
+      } catch (e) {
+        ctx?.logger?.warn?.(`bulk_qualify_leads: selection.clear failed: ${e?.message ?? e?.code}`);
+      }
+    }
+  } finally {
+    client.releaseSelectionLock();
+  }
+}
+var PAGE_SIZE, DEFAULT_COUNT2, MAX_COUNT, DEFAULT_PER_LEAD_BUDGET_MS, DEFAULT_TOTAL_BUDGET_MS2, bulkQualifyLeads;
 var init_bulk_qualify_leads = __esm({
   "../core/dist/composite/bulk-qualify-leads.js"() {
     "use strict";
     init_tool_descriptions_generated();
     PAGE_SIZE = 50;
-    DEFAULT_COUNT = 10;
+    DEFAULT_COUNT2 = 10;
     MAX_COUNT = 25;
     DEFAULT_PER_LEAD_BUDGET_MS = 9e4;
     DEFAULT_TOTAL_BUDGET_MS2 = 5 * 6e4;
@@ -14856,7 +15345,7 @@ var init_bulk_qualify_leads = __esm({
         properties: {
           count: {
             type: "number",
-            description: `How many fresh leads to qualify (default ${DEFAULT_COUNT}, max ${MAX_COUNT})`
+            description: `How many fresh leads to qualify (default ${DEFAULT_COUNT2}, max ${MAX_COUNT})`
           },
           leadIds: {
             type: "array",
@@ -14947,7 +15436,7 @@ var init_bulk_qualify_leads = __esm({
         ]
       },
       execute: async (client, params, ctx) => {
-        const wantCount = Math.min(params.count ?? DEFAULT_COUNT, MAX_COUNT);
+        const wantCount = Math.min(params.count ?? DEFAULT_COUNT2, MAX_COUNT);
         const perLeadBudget = params.per_lead_budget_ms ?? DEFAULT_PER_LEAD_BUDGET_MS;
         const totalBudget = params.total_budget_ms ?? DEFAULT_TOTAL_BUDGET_MS2;
         const totalDeadline = Date.now() + totalBudget;
@@ -15006,69 +15495,50 @@ var init_bulk_qualify_leads = __esm({
             per_lead_budget_ms: perLeadBudget,
             total_budget_ms: totalBudget
           });
-          const launched2 = [];
-          const failed2 = [];
+          let launchedCount = 0;
+          let notificationId = null;
           let quotaExceeded2 = false;
+          let failed2 = [];
           if (!reservation.reused) {
-            for (const leadId of candidates) {
-              if (quotaExceeded2)
-                break;
-              try {
-                await client.requestVoid("POST", `/leads/${leadId}/web_fetch?force_fetch=false`);
-                launched2.push(leadId);
-              } catch (err) {
-                if (err?.code === "QUOTA_EXCEEDED") {
-                  quotaExceeded2 = true;
-                } else if (err?.code === "NOT_FOUND") {
-                  failed2.push({ lead_id: leadId, error: "lead not found" });
-                } else {
-                  failed2.push({
-                    lead_id: leadId,
-                    error: err?.message ?? err?.code ?? "unknown"
-                  });
-                }
-              }
-            }
-            if (failed2.length === candidates.length || launched2.length > 0 || quotaExceeded2) {
-              await ctx.bulkTracker.markLaunched(reservation.record.bulk_id);
+            const launch = await launchBulkQualify(client, candidates, ctx);
+            quotaExceeded2 = launch.quotaExceeded;
+            notificationId = launch.resp?.notification_id ?? null;
+            const queuedIds = launch.resp?.queued_ids ?? [];
+            const skippedIds = launch.resp?.skipped_ids ?? [];
+            launchedCount = queuedIds.length;
+            const seen = /* @__PURE__ */ new Set([...queuedIds, ...skippedIds]);
+            failed2 = candidates.filter((id) => !seen.has(id)).map((id) => ({ lead_id: id, error: "not_queued" }));
+            if (queuedIds.length > 0 || quotaExceeded2 || skippedIds.length > 0 || failed2.length === candidates.length) {
+              await ctx.bulkTracker.markLaunched(reservation.record.bulk_id, notificationId);
             }
+          } else {
+            notificationId = reservation.record.notification_id ?? null;
+            launchedCount = reservation.record.lead_ids.length;
           }
           const out = {
             status: "running",
             handle_id: reservation.record.bulk_id,
             qualify_id: reservation.record.bulk_id,
             lead_ids: candidates,
-            launched_count: reservation.reused ? reservation.record.lead_ids.length : launched2.length,
+            launched_count: launchedCount,
             failed: failed2,
             quota_exceeded: quotaExceeded2,
             lens_id: lensId,
+            notification_id: notificationId,
             _meta: { region: client.region }
           };
           return out;
         }
-        const launched = [];
-        const failed = [];
-        let quotaExceeded = false;
-        for (const leadId of candidates) {
-          if (quotaExceeded)
-            break;
-          try {
-            await client.requestVoid("POST", `/leads/${leadId}/web_fetch?force_fetch=false`);
-            launched.push(leadId);
-          } catch (err) {
-            if (err?.code === "QUOTA_EXCEEDED") {
-              quotaExceeded = true;
-              ctx?.logger?.warn?.(`bulk_qualify_leads: 429 mid-fanout after launching ${launched.length}/${candidates.length} \u2014 stopping further launches but polling those already in flight`);
-            } else if (err?.code === "NOT_FOUND") {
-              failed.push({ lead_id: leadId, error: "lead not found" });
-            } else {
-              failed.push({
-                lead_id: leadId,
-                error: err?.message ?? err?.code ?? "unknown"
-              });
-            }
-          }
+        const inlineLaunch = await launchBulkQualify(client, candidates, ctx);
+        const quotaExceeded = inlineLaunch.quotaExceeded;
+        const launched = inlineLaunch.resp?.queued_ids ?? [];
+        const inlineSkipped = inlineLaunch.resp?.skipped_ids ?? [];
+        const inlineNotificationId = inlineLaunch.resp?.notification_id ?? null;
+        if (inlineNotificationId) {
+          ctx?.logger?.info?.(`bulk_qualify_leads: launched bulk progress_notification_id=${inlineNotificationId} queued=${launched.length} skipped=${inlineSkipped.length}`);
         }
+        const inlineFailedSeen = /* @__PURE__ */ new Set([...launched, ...inlineSkipped]);
+        const failed = candidates.filter((id) => !inlineFailedSeen.has(id)).map((id) => ({ lead_id: id, error: "not_queued" }));
         let progressDone = 0;
         const progressTotal = launched.length;
         if (progressTotal > 0) {
@@ -15904,6 +16374,7 @@ var init_import_and_qualify = __esm({
               ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
               qualify_id: null,
               import_ids: queued.importIds,
+              notification_ids: queued.notification_ids ?? [],
               imported: queued.leads.map((l) => ({
                 leadId: l.leadId,
                 ...l.domain ? { domain: l.domain } : {},
@@ -15928,6 +16399,7 @@ var init_import_and_qualify = __esm({
             ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
             qualify_id: null,
             import_ids: queued.importIds,
+            notification_ids: queued.notification_ids ?? [],
             imported: [],
             not_imported: [],
             qualified: [],
@@ -15965,6 +16437,7 @@ var init_import_and_qualify = __esm({
             ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
             qualify_id: null,
             import_ids: importResult.importIds,
+            notification_ids: importResult.notification_ids ?? [],
             imported: [],
             not_imported: importResult.not_imported.map(toNotImportedEntry),
             qualified: [],
@@ -16002,6 +16475,7 @@ var init_import_and_qualify = __esm({
             ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
             qualify_id: null,
             import_ids: importResult.importIds,
+            notification_ids: importResult.notification_ids ?? [],
             imported,
             not_imported,
             qualified: [],
@@ -16112,6 +16586,7 @@ var init_import_and_qualify = __esm({
           ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
           qualify_id: reservation.record.bulk_id,
           import_ids: importResult.importIds,
+          notification_ids: importResult.notification_ids ?? [],
           imported,
           not_imported,
           qualified,
@@ -16707,16 +17182,20 @@ var init_bulk_store = __esm({
           this.logger?.info?.(`bulk.import_failed bulk_id=${bulk_id}`);
         });
       }
-      async markLaunched(bulk_id) {
+      async markLaunched(bulk_id, notification_id) {
         return this.mutex.run(async () => {
           const all = this.prune(await this.readAll());
           const idx = all.findIndex((r) => r.bulk_id === bulk_id);
           if (idx < 0) {
             throw new Error(`bulk_id not found: ${bulk_id}`);
           }
-          all[idx] = { ...all[idx], status: "launched" };
+          all[idx] = {
+            ...all[idx],
+            status: "launched",
+            ...notification_id ? { notification_id } : {}
+          };
           await this.writeAll(all);
-          this.logger?.info?.(`bulk.launched bulk_id=${bulk_id}`);
+          this.logger?.info?.(`bulk.launched bulk_id=${bulk_id}${notification_id ? ` notification_id=${notification_id}` : ""}`);
           return all[idx];
         });
       }
@@ -16968,6 +17447,14 @@ var init_import_status = __esm({
 });
 
 // ../core/dist/composite/qualify-status.js
+async function readNotification(client, notificationId) {
+  try {
+    const page = await client.listNotifications({ archived: false, count: 50 });
+    return page.items.find((n) => n.id === notificationId) ?? null;
+  } catch {
+    return null;
+  }
+}
 var qualifyStatus;
 var init_qualify_status = __esm({
   "../core/dist/composite/qualify-status.js"() {
@@ -17129,6 +17616,16 @@ var init_qualify_status = __esm({
           const { _stillRunning, _failedCode, ...rest } = r;
           qualified.push(rest);
         }
+        let bulkProgress = null;
+        let inProgressFlag = null;
+        const notifId = record.notification_id ?? null;
+        if (notifId) {
+          const n = await readNotification(client, notifId);
+          if (n) {
+            bulkProgress = n.bulk_progress;
+            inProgressFlag = n.in_progress;
+          }
+        }
         const out = {
           qualify_id: record.bulk_id,
           launched_at: record.launched_at,
@@ -17140,6 +17637,9 @@ var init_qualify_status = __esm({
           still_running,
           failed,
           not_in_lens: [...notInLensSet],
+          notification_id: notifId,
+          bulk_progress: bulkProgress,
+          in_progress: inProgressFlag,
           region: client.region,
           _meta: client.lastMeta ?? {
             region: client.region,
@@ -17152,6 +17652,9 @@ var init_qualify_status = __esm({
           out.per_lead_budget_ms = record.per_lead_budget_ms;
         if (record.total_budget_ms !== void 0)
           out.total_budget_ms = record.total_budget_ms;
+        if (bulkProgress && bulkProgress.quota_hit_count > 0) {
+          out.quota_hit_hint = "Some leads hit the AI-credits quota during qualification. Top up via leadbay_create_topup_link to clear the throttle immediately, or wait until the daily/weekly window resets.";
+        }
         return out;
       }
     };
@@ -17429,6 +17932,7 @@ var init_enrich_titles = __esm({
                   bulk_id: res.record.bulk_id,
                   launched_at: res.record.launched_at,
                   durability: res.record.durability,
+                  notification_id: res.record.notification_id ?? null,
                   seconds_since_original_launch: bulkSecondsSinceOriginal ?? 0,
                   titles: params.titles,
                   email,
@@ -17444,8 +17948,9 @@ var init_enrich_titles = __esm({
               total: 3,
               message: `Launching enrichment for ${params.titles.length} title${params.titles.length === 1 ? "" : "s"}\u2026`
             });
+            let launchResp = null;
             try {
-              await client.requestVoid("POST", "/leads/selection/enrichment/launch", { titles: params.titles, email, phone });
+              launchResp = await client.request("POST", "/leads/selection/enrichment/launch", { titles: params.titles, email, phone });
             } catch (err) {
               const aborted = err?.name === "AbortError" || ctx?.signal?.aborted === true;
               if (bulkRecord && tracker) {
@@ -17469,9 +17974,10 @@ var init_enrich_titles = __esm({
               }
               throw err;
             }
+            const notificationId = launchResp?.notification_id ?? null;
             if (bulkRecord && tracker) {
               try {
-                await tracker.markLaunched(bulkRecord.bulk_id);
+                await tracker.markLaunched(bulkRecord.bulk_id, notificationId);
               } catch (e) {
                 ctx?.logger?.warn?.(`enrich_titles: tracker.markLaunched failed: ${e?.message ?? e}`);
                 return {
@@ -17499,8 +18005,9 @@ var init_enrich_titles = __esm({
               bulk_id: bulkRecord?.bulk_id,
               launched_at: bulkRecord?.launched_at,
               durability: bulkRecord?.durability,
-              message: bulkRecord ? "Enrichment job launched. Backend has no server-side bulk_id yet; MCP minted a client-side bulk_id (persisted to disk by default) so you can poll via leadbay_bulk_enrich_status." : "Enrichment job launched. No bulk_id tracker configured \u2014 poll leadbay_get_contacts per lead after ~60s; contact.enrichment.done flips to true.",
-              next_action: bulkRecord ? "Call leadbay_bulk_enrich_status({bulk_id}) after ~60s; pass include_contacts=true for the final read." : "Wait ~60s, then call leadbay_research_lead_by_id or leadbay_get_contacts on the leads you care about."
+              notification_id: notificationId,
+              message: notificationId ? "Enrichment job launched. The MCP is now listening for the backend notification \u2014 when enrichment finishes, a `_meta.notifications` entry will surface on your next tool response (also visible in `leadbay_account_status.notifications`)." : bulkRecord ? "Enrichment job launched. Backend did not return a notification id this time; poll via leadbay_bulk_enrich_status with the bulk_id." : "Enrichment job launched. No bulk_id tracker configured \u2014 poll leadbay_get_contacts per lead after ~60s; contact.enrichment.done flips to true.",
+              next_action: notificationId ? "Wait for the next `_meta.notifications` entry (typically <2 min for a small batch). If you want progress sooner, call leadbay_bulk_enrich_status({bulk_id})." : bulkRecord ? "Call leadbay_bulk_enrich_status({bulk_id}) after ~60s; pass include_contacts=true for the final read." : "Wait ~60s, then call leadbay_research_lead_by_id or leadbay_get_contacts on the leads you care about."
             };
           } finally {
             try {
@@ -17518,6 +18025,14 @@ var init_enrich_titles = __esm({
 });
 
 // ../core/dist/composite/bulk-enrich-status.js
+async function readNotification2(client, notificationId) {
+  try {
+    const page = await client.listNotifications({ archived: false, count: 50 });
+    return page.items.find((n) => n.id === notificationId) ?? null;
+  } catch {
+    return null;
+  }
+}
 async function pMap(items, fn, concurrency) {
   const out = new Array(items.length);
   let next = 0;
@@ -17689,6 +18204,53 @@ var init_bulk_enrich_status = __esm({
             launched_at: record.launched_at
           };
         }
+        const notifId = record.notification_id ?? null;
+        if (notifId) {
+          const n = await readNotification2(client, notifId);
+          if (n && n.bulk_progress) {
+            const bp = n.bulk_progress;
+            const inProgress = n.in_progress;
+            let leads2 = [];
+            if (!inProgress && includeContacts) {
+              leads2 = await pMap(record.lead_ids, async (leadId) => {
+                try {
+                  const out = await getContacts.execute(client, { leadId });
+                  const contacts = Array.isArray(out?.contacts) ? out.contacts : [];
+                  return { lead_id: leadId, contacts };
+                } catch {
+                  return { lead_id: leadId };
+                }
+              }, STATUS_FETCH_CONCURRENCY);
+            } else {
+              leads2 = record.lead_ids.map((id) => ({ lead_id: id }));
+            }
+            ctx?.logger?.info?.(`bulk.status_checked_via_notification bulk_id=${record.bulk_id} notification_id=${notifId} done=${bp.success_count}/${bp.total_count} in_progress=${inProgress} wall_ms=${Date.now() - startMs}`);
+            return {
+              bulk_id: record.bulk_id,
+              notification_id: notifId,
+              launched_at: record.launched_at,
+              status: record.status,
+              durability: record.durability,
+              titles: record.titles,
+              email: record.email,
+              phone: record.phone,
+              lens_id: record.lens_id,
+              leads: leads2,
+              overall_progress: {
+                done: bp.success_count + bp.failure_count + bp.quota_hit_count,
+                total: bp.total_count,
+                done_ratio: bp.total_count === 0 ? 0 : (bp.success_count + bp.failure_count + bp.quota_hit_count) / bp.total_count
+              },
+              bulk_progress: bp,
+              in_progress: inProgress,
+              all_done: !inProgress,
+              ...bp.quota_hit_count > 0 ? {
+                quota_hit_hint: "Some contacts could not be enriched because the AI-credits quota was hit. Top up via leadbay_create_topup_link or wait for the window reset."
+              } : {}
+            };
+          }
+          ctx?.logger?.info?.(`bulk_enrich_status: notification ${notifId} not yet visible; falling back to per-lead fan-out`);
+        }
         let doneSoFar = 0;
         const totalLeads = record.lead_ids.length;
         const results = await pMap(record.lead_ids, async (leadId) => {
@@ -19457,8 +20019,11 @@ __export(dist_exports, {
   InMemoryBulkStore: () => InMemoryBulkStore,
   LeadbayClient: () => LeadbayClient,
   LocalBulkStore: () => LocalBulkStore,
+  NotificationsInbox: () => NotificationsInbox,
+  NotificationsWsClient: () => NotificationsWsClient,
   REGIONS: () => REGIONS,
   accountStatus: () => accountStatus,
+  acknowledgeNotification: () => acknowledgeNotification,
   addLeadsToCampaign: () => addLeadsToCampaign,
   addNote: () => addNote,
   adjustAudience: () => adjustAudience,
@@ -19466,6 +20031,7 @@ __export(dist_exports, {
   agentMemoryRecall: () => agentMemoryRecall,
   agentMemoryReview: () => agentMemoryReview,
   agentMemoryTools: () => agentMemoryTools,
+  anchorIdFor: () => anchorIdFor,
   answerClarification: () => answerClarification,
   appendEntry: () => appendEntry,
   appendTombstone: () => appendTombstone,
@@ -19474,6 +20040,7 @@ __export(dist_exports, {
   bulkQualifyLeads: () => bulkQualifyLeads,
   campaignCallSheet: () => campaignCallSheet,
   campaignProgression: () => campaignProgression,
+  catchUpNotifications: () => catchUpNotifications,
   clearAgentMemoryCache: () => clearAgentMemoryCache,
   clearMockJournal: () => clearMockJournal,
   clearSelection: () => clearSelection,
@@ -19523,6 +20090,7 @@ __export(dist_exports, {
   importAndQualify: () => importAndQualify,
   importLeads: () => importLeads,
   importStatus: () => importStatus,
+  inferKind: () => inferKind,
   invalidateAgentMemoryCache: () => invalidateAgentMemoryCache,
   isAgentMemoryEnabled: () => isAgentMemoryEnabled,
   isValidBulkId: () => isValidBulkId,
@@ -19563,12 +20131,14 @@ __export(dist_exports, {
   resolveAgentMemorySummary: () => resolveAgentMemorySummary,
   resolveImportRows: () => resolveImportRows,
   resolveRegion: () => resolveRegion,
+  reviseHintFor: () => reviseHintFor,
   seedCandidates: () => seedCandidates,
   selectLeads: () => selectLeads,
   setActiveLens: () => setActiveLens,
   setEpilogueStatus: () => setEpilogueStatus,
   setPushback: () => setPushback,
   setUserPrompt: () => setUserPrompt,
+  toInboxEntry: () => toInboxEntry,
   tools: () => tools,
   tourPlan: () => tourPlan,
   updateLens: () => updateLens,
@@ -19583,6 +20153,7 @@ var init_dist = __esm({
     init_types();
     init_agent_memory();
     init_composite_file_names();
+    init_notifications();
     init_login();
     init_list_lenses();
     init_discover_leads();
@@ -19612,6 +20183,7 @@ var init_dist = __esm({
     init_agent_memory_recall();
     init_agent_memory_capture();
     init_agent_memory_review();
+    init_acknowledge_notification();
     init_select_leads();
     init_deselect_leads();
     init_clear_selection();
@@ -19771,7 +20343,13 @@ var init_dist = __esm({
       // didn't deliver"). Does not mutate Leadbay state; emits a PostHog
       // event only. Companion to leadbay_report_outreach (which DOES write
       // to the backend and stays gated behind LEADBAY_MCP_WRITE).
-      reportFriction
+      reportFriction,
+      // Notification ack — ALWAYS exposed even though it POSTs to /seen.
+      // _meta.notifications surfaces terminal bulk-progress notifications on
+      // every tool response regardless of write gating; without ack the agent
+      // sees the same entries on every call forever. Pairing the surfacing
+      // channel with the clearing tool is non-optional.
+      acknowledgeNotification
     ];
     compositeWriteTools = [
       bulkQualifyLeads,
@@ -22119,6 +22697,22 @@ function buildServer(client, opts = {}) {
       });
     }
   };
+  const maybeAttachNotifications = (result) => {
+    const inbox = opts.notificationsInbox;
+    if (!inbox) return;
+    if (result === null || typeof result !== "object" || Array.isArray(result)) {
+      return;
+    }
+    const entries = inbox.list();
+    if (entries.length === 0) return;
+    const envelope = result;
+    const target = envelope.__markdown_envelope === true && envelope.structured !== null && typeof envelope.structured === "object" && !Array.isArray(envelope.structured) ? envelope.structured : envelope;
+    const existingMeta = target._meta && typeof target._meta === "object" && !Array.isArray(target._meta) ? target._meta : {};
+    target._meta = {
+      ...existingMeta,
+      notifications: entries
+    };
+  };
   const isLeadbayBusinessError = (err) => err != null && typeof err === "object" && err.error === true && typeof err.code === "string";
   const buildBusinessCtx = (toolName, envelope, triggered_by) => {
     const meta = envelope._meta ?? {};
@@ -22238,11 +22832,13 @@ function buildServer(client, opts = {}) {
       const result = await tool.execute(client, args, {
         logger: opts.logger,
         bulkTracker: opts.bulkTracker,
+        notificationsInbox: opts.notificationsInbox,
         signal: extra.signal,
         progress,
         elicit
       });
       maybeAttachUpdate(name, result);
+      maybeAttachNotifications(result);
       if (result && typeof result === "object" && result.error === true) {
         const envText = formatErrorForLLM(result);
         const envDur = Date.now() - callStart;
@@ -23680,7 +24276,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.17.3";
+var VERSION = "0.18.0";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 
@@ -24777,21 +25373,41 @@ async function main() {
       logger.warn?.(`update_check.unexpected ${err?.message ?? err}`);
     });
   }
+  const notificationsInbox = new NotificationsInbox();
+  let notificationsWs = null;
+  const WS_DISABLED = process.env.LEADBAY_NOTIFICATIONS_WS_DISABLED === "1" || authState !== "ok";
+  if (!WS_DISABLED) {
+    notificationsWs = new NotificationsWsClient({
+      client,
+      inbox: notificationsInbox,
+      logger
+    });
+    void notificationsWs.start().catch((err) => {
+      logger.warn?.(
+        `notifications.ws start_failed: ${err?.message ?? err}`
+      );
+    });
+  }
   const server = buildServer(client, {
     includeAdvanced,
     includeWrite,
     logger,
     bulkTracker,
+    notificationsInbox,
     version: VERSION,
     telemetry,
     updateStateStore
   });
   const transport = new StdioServerTransport();
   logger.info?.(
-    `Starting MCP server v${VERSION} (advanced=${includeAdvanced}, write=${includeWrite}, baseUrl=${client.baseUrl}, bulk_store=${bulkTracker.durability}, auth_state=${authState})`
+    `Starting MCP server v${VERSION} (advanced=${includeAdvanced}, write=${includeWrite}, baseUrl=${client.baseUrl}, bulk_store=${bulkTracker.durability}, notifications_ws=${WS_DISABLED ? "disabled" : "enabled"}, auth_state=${authState})`
   );
   await server.connect(transport);
   const shutdown = async (code) => {
+    try {
+      notificationsWs?.stop();
+    } catch {
+    }
     try {
       await telemetry.shutdown();
     } finally {