@leadbay/mcp 0.17.3 → 0.18.1

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) {
@@ -5086,6 +5103,7 @@ var init_composite_file_names = __esm({
   "../core/dist/composite/_composite-file-names.js"() {
     "use strict";
     COMPOSITE_FILE_TOOL_NAMES = /* @__PURE__ */ new Set([
+      "leadbay_account_history",
       "leadbay_account_status",
       "leadbay_add_leads_to_campaign",
       "leadbay_adjust_audience",
@@ -5122,11 +5140,455 @@ 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_history, 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";
+    leadbay_account_history = `## WHEN TO USE
+
+Trigger phrases: "what's the history on this account", "why should I revisit this account", "summarize everything we've done with <Company>", "has this account gone cold", "give me the back-story on lead <UUID>".
+
+**Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
+
+Do NOT use for: "live signals only, no history" \u2192 \`leadbay_research_lead_by_id\`; "which accounts should I follow up with" \u2192 \`leadbay_pull_followups\`.
+
+Prefer when: user wants ONE account's full back-story \u2014 notes + past activity + current signals together; pass \`leadId\`
+
+Examples that SHOULD invoke this tool:
+- "What's the full history on this account \u2014 why did it resurface?"
+- "Summarize everything we've logged on that lead and whether it's worth another visit."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Tell me the current AI take on this lead."
+- "Which accounts should I follow up with this week?"
+
+## RENDER (quick)
+
+Single resurfaced-account card. Lead the card with the current signal/trigger
+line (from \`signals\`), then a "History" section: notes digest
+(chronological) + the activity timeline. Close with a one-line "why revisit
+now" synthesis and a suggested outreach angle tied to the freshest signal.
+
+---
+
+Give me one account's full back-story in a single call. This is the tool for
+the **reprioritize-a-neglected-account** workflow: the user has an account
+that was contacted or quoted long ago and wants to know, in one shot, whether
+a fresh signal makes it worth another visit.
+
+It bundles three reads on one \`leadId\`:
+
+1. **Current state** \u2014 passed through verbatim from \`leadbay_research_lead_by_id\`:
+   \`signals\` (web-research signals with hot flags + sources), \`firmographics\`,
+   \`qualification\` answers, \`contacts\`, and \`engagement\` counts. This is the
+   "why is this account hot NOW" layer.
+2. **\`notes\`** \u2014 the FULL list of notes logged on the record (note body +
+   \`created_at\`), chronological. \`leadbay_research_lead_by_id\` only returns a
+   \`notes_count\`; this tool returns the bodies so you can summarize the
+   historical context.
+3. **\`activities\`** \u2014 the interaction timeline (\`{type, date}\` entries, newest
+   first) plus the total count. Drives the "no contact in N months" judgement.
+
+\`notes\` and \`activities\` **degrade gracefully**: if either read fails the card
+still returns with that section empty (\`notes: []\` /
+\`activities.total: 0\`). The current-state block is load-bearing \u2014 if research
+itself errors the whole call fails, because there is nothing to narrate.
+
+Params: \`leadId\` (required UUID) and \`activityCount\` (optional, default 50,
+max 100).
+
+Companion tools: **leadbay_research_lead_by_id** when the user only wants the
+live AI take with no history; **leadbay_pull_followups** when the user wants a
+LIST of accounts to act on rather than one account's deep history.
+
+## RENDERING \u2014 single-record research card, mode-adaptive
+
+Present as a single-record card, not a table. This tool gets invoked in two distinct user contexts \u2014 detect which and adapt the body density accordingly.
+
+**MODE A \u2014 Discovery.** The user is evaluating whether to pursue this company as a target. Signals: "tell me about", "what do they do", "is this a fit", "research [company]", arrival via a click-through from \`leadbay_pull_leads\`, no prior outreach context in the conversation. Next step is usually qualify, deep-dive via \`leadbay_research_lead_by_id\`, or decide whether to start outreach.
+
+**MODE B \u2014 Contact preparation.** The user is about to call or email someone at this company and needs the talking points. Signals: "I'm calling them", "draft an email", "before my call", "outreach prep", "what should I say", or the conversation has already touched on a specific contact. Next step is usually \`leadbay_prepare_outreach\`.
+
+Default to MODE A when uncertain. Always offer the cross-mode pivot at the end so the user can redirect if you guessed wrong.
+
+### Common structure (both modes)
+
+- **Header** (H4 or H5): \`<10-segment score bar>\` \`[Company name](website)\`. Use the score-bar algorithm; the bar lives in a single inline-code span. Prefix \`https://\` to website if it's a bare hostname.
+- **Pill row** (immediately below the header): short location \xB7 compact size \xB7 social pill chips iterated over \`social_urls\` (each non-null platform becomes \`[<platform-label>](<url>)\`) \xB7 \`[website-domain](website)\` \xB7 \`\u260E phone\` when \`phone_numbers[]\` is non-empty (use the first number). All \` \xB7 \`-separated.
+- **Blurb**: render \`description\` (preferred) or \`short_description\` as a single blockquoted paragraph.
+- **Staleness line**: italic, \`"Researched <relative time>"\` from \`web_insights_fetched_at\`. Use \`"today"\` / \`"yesterday"\` / \`"N days ago"\` up to 30 days, then absolute date. Prefix with \`\u26A0\` if older than 30 days.
+- **Contacts table** (always at the bottom):
+  \`\`\`
+  |   | Name | Title | LinkedIn |
+  \`\`\`
+  Markers in column 1:
+  - \`\u2605\` \u2014 \`recommended_contact\` match.
+  - \`\u{1F48E}\` \u2014 name fuzzy-matches a \`hot: true\` entry in \`web_insights\` key_people. (Use \`\u{1F48E}\`, not \`\u{1F525}\`, to avoid glyph collision with the follow-up status badge.)
+  Sort \`\u2605\` first, then \`\u{1F48E}\`-only rows, then API order. Link the name via \`linkedin_page\` first; fall back to LinkedIn people-search with \`<First>+<Last>+<Company>\`. Append \`\xB0\` only when the fallback is in use AND \`social_presence.linkedin == false\`. Cap to 6 rows; if \`contacts_count > shown\`, end with \`"+N more \u2014 ask to see the full list"\`.
+
+### MODE A body (Discovery, fuller, scannable)
+
+Render each non-empty \`web_insights\` section as H5 with the emoji + label intact. Section order: \`\u{1F3E2} company profile\` \u2192 \`\u{1F4C8} business signals\` \u2192 \`\u{1F4A1} prospecting clues\` \u2192 \`\u{1F9E9} strategic positioning\` \u2192 \`\u{1F50E} technologies & innovation\`. Inside each, bullet 3\u20135 items. Sort \`hot: true\` items first. **Bold** the description text of hot items; leave cold items plain. Render \`source\` as \`[source](url)\` at the end; include \`date\` when present. Omit empty sections. Skip \`\u{1F517} social links\` (already in the pill row) and \`\u{1F464} key people\` (already in the contacts table).
+
+### MODE B body (Contact preparation, tighter)
+
+Render exactly two H5 sections:
+
+##### \u{1F3AF} Conversation hooks
+
+Distill the 3 most recent / most hot signals from \`\u{1F4C8} business signals\` and \`\u{1F4A1} prospecting clues\` into one-sentence talking points in salesperson voice. Strip the academic framing. Cite the source inline.
+
+##### \u{1F464} About the person *(only when recommended_contact is non-empty)*
+
+2-line summary: their title + any context from \`web_insights\` key_people. If they appear in a hot signal ("X appointed CEO"), surface that prominently.
+
+Skip \u{1F3E2} profile, \u{1F9E9} strategic positioning, \u{1F50E} technologies in MODE B \u2014 context the user doesn't need for the next 30 seconds.
+
+If \`qualification[]\` is non-empty, append one collapsed line: \`"Qualification: N questions answered, avg boost X"\` and offer to expand in NEXT STEPS.
+
+**Hide:** \`id\`, \`lead.id\`, \`contact.id\`, \`lead.location.pos\`, \`web_fetch_in_progress\`, \`enrichment_in_progress\`, \`recommended_contact_title\` (duplicates \`recommended_contact.job_title\`), empty arrays, fields whose value is the string \`"null"\`, \`contact.source\` (internal), insights whose \`source\` is empty.
+
+**Legend (print once below the card):** \`\` \`\u25B0\` firmographic \xB7 \`\u2756\` AI booster \xB7 \`\u25B1\` unfilled \xB7 \u2605 recommended \xB7 \u{1F48E} hot in web_insights \xB7 \xB0 = no company LinkedIn (fallback link only) \`\`
+
+## Linking a contact's name
+
+**MANDATORY: every contact name in your output \u2014 table cells, prose, headers, "Reach <Name>" callouts \u2014 MUST be wrapped in markdown link syntax \`[Name](URL)\`. Never render a contact name as bare text. A plain-text name is a broken contact card; the underlined name is the user's primary affordance for "take me to this person's profile". No "no URL available" exception \u2014 the search URL below is always constructable from name + company.**
+
+URL priority (first applicable wins):
+
+1. **Real profile** \u2014 \`contact.linkedin_page\` when it's a string starting with \`https://\` (the MCP coerces the legacy literal \`"null"\` string to real null before you see it).
+2. **Constructed people-search** \u2014 \`https://www.linkedin.com/search/results/people/?keywords=<First>+<Last>+<Company>\`. URL-encode params. Strip Inc / LLC / Corp / Ltd / GmbH / Co / S.A. / S.L. / PLC / AG / SAS / SARL suffixes from the company. Append a trailing \` \xB0\` to the rendered name ONLY when this fallback is in use AND \`social_presence.linkedin == false\`. Never append \`\xB0\` when a real \`linkedin_page\` was used.
+
+Never link a person's name to the company's LinkedIn page (and vice versa) \u2014 the two surfaces are different and conflating them quietly degrades the workflow.
+
+## Linking the company
+
+Use the lead's \`website\` as the company-name link target \u2014 prefix \`https://\` if the value is a bare hostname. (The MCP does NOT synthesize a Leadbay-app deep-link URL; the team has not standardized one. Linking to \`website\` is always real data.)
+
+When the response carries \`social_urls\` (the post-fix multi-platform URL block on rich-lead responses), render every non-null platform as a pill chip in the company-info row. Iterate over \`social_urls\`'s keys \u2014 never hardcode a fixed list \u2014 and emit each as \`[<platform-label>](<url>)\`. Skip platforms whose URL is null.
+
+\`social_presence\` carries booleans for the same 6 platforms (crunchbase, facebook, instagram, linkedin, tiktok, twitter) \u2014 useful when you only care that the company has a profile somewhere. Use it as the \xB0-flag signal in the contact people-search fallback (see linking/contact-linkedin).
+
+
+
+### RENDERING \u2014 the history layer (on top of the card above)
+
+After the research card, add a **History** section so the user sees why this
+account resurfaced:
+
+- **##### \u{1F5D2} Notes** \u2014 render \`notes\` chronologically (oldest \u2192 newest). Each
+  as a bullet: \`**<relative date from created_at>** \u2014 <note body>\`. Cap at 8;
+  if \`_meta.notes_count > shown\`, end with \`"+N more notes"\`. Omit the section
+  entirely when \`notes\` is empty.
+- **##### \u{1F553} Timeline** \u2014 render \`activities.activities\` newest-first as a
+  compact bullet list: \`<relative date> \xB7 <type>\`. Cap at 10; if
+  \`activities.total > shown\`, end with \`"+N earlier"\`. Omit when empty.
+- **##### \u21BB Why revisit now** \u2014 one or two sentences synthesizing the freshest
+  HOT signal from \`signals\` against the gap in \`activities\` (e.g. "Won a public
+  tender last month; no logged contact since the 2024 quote \u2014 strong re-open
+  angle"). Then one suggested outreach angle tied to that signal. This
+  synthesis is the payload of the whole tool \u2014 always include it when there is
+  at least one hot signal.
+`;
     leadbay_account_status = `## WHEN TO USE
 
 Trigger phrases: "what's my account status", "how much quota do I have", "what lens am I on", "I topped up / I bought credits / I added credits".
@@ -5147,10 +5609,13 @@ Examples that should NOT invoke this tool (sound similar, route elsewhere):
 
 ## RENDER (quick)
 
-Compact markdown: org name + admin badge on line 1; active lens on
-line 2; per-window quota usage as \`(used / cap)\` chips for
-llm_completion \xB7 ai_rescore \xB7 web_fetch. Surface regeneration flag
-prominently if mid-regen.
+If \`quota_error\` is set the call FAILED \u2014 quota unreadable; on 401/403 tell
+the user to reconnect. NEVER report zero usage or "no limits". Else render
+\`quota.org.resources\` (usage lives there, NOT at quota.resources) as a
+table, never prose: rows = resources (llm_completion \xB7 ai_rescore \xB7
+web_fetch + others), cols = Daily/Weekly/Monthly used \`count\` (= amount
+USED; no cap field, \`plan\` may be null \u2014 never invent a denominator).
+Empty = a 0 table, not "unlimited". Above: org + admin, lens.
 
 ---
 
@@ -5162,9 +5627,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
 
@@ -5294,6 +5802,10 @@ This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible
 WHEN TO USE: poll this after leadbay_enrich_titles returns a \`bulk_id\`. Default \`include_contacts=false\` for cheap status polls; set \`include_contacts=true\` once \`all_done\` flips for the final read.
 
 WHEN NOT TO USE: as a substitute for leadbay_research_lead_by_id \u2014 that already includes enriched contacts for a single lead.
+
+## CREDIT COST \u2014 show the balance, discreetly
+
+Once \`all_done\` is true the result carries \`credits_remaining\` (the post-spend AI-credit balance). Don't make a fuss \u2014 no sentence, no callout. Just append ONE small italic line in parentheses at the very END of your reply: \`_(N credits remaining)_\`. If \`credits_remaining\` is null (billing unavailable), omit the line \u2014 don't print 0. Do NOT report a "credits used" figure for this run: the per-contact cost can't be scoped to this specific enrichment (a lead's contact list mixes in earlier runs), so any "X used" number would be misleading.
 `;
     leadbay_bulk_qualify_leads = `Pick the next N unqualified leads in the active lens and qualify them (run AI rescore + web fetch). Pass \`wait_for_completion:false\` to return quickly with \`{status:'running', qualify_id}\`; poll leadbay_qualify_status with that id. With \`wait_for_completion\` omitted/true, the legacy behavior polls until the answers are populated or a budget is exhausted. Already-qualified leads (those with a non-null \`ai_agent_lead_score\`) are silently no-ops on the backend, so this composite paginates past them to find fresh candidates. On 429 mid-fanout, stops launching but keeps polling already-launched leads.
 
@@ -5758,6 +6270,10 @@ WHEN TO USE: when you have a specific \`contact_id\` (from leadbay_get_contacts)
 
 WHEN NOT TO USE: for bulk enrichment by job title across many leads \u2014 use leadbay_enrich_titles, which handles the selection lifecycle and returns a clean preview/launch flow.
 
+## CREDIT COST \u2014 discreet
+
+This is a paid call. The result returns \`credits_remaining\` (billing.ai_credits, read before the spend). Don't make a fuss about credits: only flag the balance if it's low (e.g. \u2264 a few credits) so the user can decide. Otherwise append it quietly as a small italic parenthetical at the END of your reply \u2014 \`_(N credits remaining)_\`. Don't quote an exact per-contact cost (the rate is backend-only). The actual per-contact cost (enrichment.credits_used) appears on the contact via leadbay_get_contacts after enrichment. If \`credits_remaining\` is null, omit the line \u2014 don't assume zero.
+
 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_enrich_titles = `Order contact enrichments by job title across many leads. Contacts are NOT returned by default with a lead (Leadbay keeps enrichment out-of-band to control cost); the agent requests them on demand via this tool when it's ready to actually reach out. Two modes: (A) NO \`titles\` param \u2014 returns the available titles + Leadbay's \`title_suggestions\` + \`auto_included_titles\` + a count of enrichable contacts, so the agent can ask the user which titles to enrich. (B) \`titles\` given \u2014 calls preview, then launches if there's anything enrichable. On 429 returns \`{status:'quota_exceeded'}\` cleanly. Selection lifecycle is wrapped in a try/finally so the user's selection is left clean even on error.
@@ -5766,6 +6282,35 @@ WHEN TO USE: as the agent's go-to enrichment entry point, immediately before pro
 
 WHEN NOT TO USE: to enrich a single contact \u2014 that's leadbay_enrich_contacts (granular). Speculatively, before the user has committed to outreaching \u2014 enrichment spends credits.
 
+## CREDIT COST \u2014 make spend visible
+
+Enrichment is the main PAID operation. Surface cost both before and after.
+
+**BEFORE (confirm before launching).** The discover / preview_only / dry_run modes return \`credits_remaining\` (the balance) and \`enrichable_contacts\` (the volume that would be enriched). Tell the user plainly: **"You have {credits_remaining} credits. This will enrich {enrichable_contacts} contacts."** then ask them to confirm before you launch the paid run. Route that confirmation through \`ask_user_input_v0\` ("Enrich {enrichable_contacts} contacts now?" \u2192 ["Yes, enrich", "No, cancel"]). Do NOT state an exact estimated cost \u2014 the per-contact credit rate lives backend-side and is not in the preview; show the balance and the count, never a fabricated "will cost N credits". If \`credits_remaining\` is null, billing is unavailable \u2014 say the balance is unknown, don't assume zero or unlimited.
+
+**AFTER (show the balance, discreetly).** Once the job finishes \u2014 poll \`leadbay_bulk_enrich_status\`, which returns \`credits_remaining\` (the post-spend balance). Don't make a fuss: append ONE small italic line in parentheses at the very END of your reply \u2014 \`_(N credits remaining)_\`. Omit it if \`credits_remaining\` is null. Do NOT report a "credits used" figure: per-run cost can't be scoped reliably (a lead's contacts mix earlier enrichments), so only the balance is shown.
+
+## GATE \u2014 PREFER BUILT-IN HOST WIDGETS
+
+Modern chat hosts (Claude, ChatGPT) expose first-party widgets the agent can route into. These ALWAYS produce a better UX than markdown tables / inline prose for the data shapes they support \u2014 they're tappable on mobile, persistent across turns, and integrate with the host's quick-actions.
+
+**The Big Three** \u2014 when a tool result fits, route there:
+
+| Host widget | Use when | Field map (from Leadbay payload) |
+|---|---|---|
+| \`places_map_display_v0\` (Claude) | Result has \u22652 leads with \`location.city\` set, and the user's intent is geographic / "in person" / travel | \`{name: lead.company_name, address: "<city>, <country>", place_id: lead.location.place_id ?? omit, notes: <one-sentence pitch>}\` per location |
+| \`message_compose_v1\` (Claude) | You're about to draft outreach (email / message / call opener) | \`{kind: "email", summary_title, variants: [{label, body, subject}]}\` \u2014 2\u20133 variants, labels describe STRATEGY ("Push for alignment", "Reference the M&A signal"), not tone ("Friendly", "Formal") |
+| \`ask_user_input_v0\` (Claude) | The tool's NEXT STEPS block has 2\u20134 mutually-exclusive next moves and the user hasn't already chosen | \`{questions: [{question: "What next?", type: "single_select", options: [<2-4 short button labels>]}]}\`; max 3 questions per call |
+
+ChatGPT exposes the same routing pattern via \`_meta.openai/outputTemplate\`. We don't ship any custom widgets ourselves \u2014 this gate is exclusively about routing into the host's first-party widgets when the data shape fits.
+
+**Rules:**
+- The widget IS the visual. Do NOT emit a markdown table or prose list of the same data alongside \u2014 that produces two competing UIs.
+- Pass identifiers (place_id, lead.id, contact_id) verbatim. Don't rewrite.
+- When the host doesn't expose the named widget, the agent falls back to the prose/table rendering the per-tool description already specifies. The directive is host-conditional; the fallback is automatic.
+- One short intro sentence in chat is enough \u2014 "Here are your 5 NYC follow-ups." Then route into the widget.
+
+
 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_extend_lens = `## WHEN TO USE
@@ -8576,10 +9121,36 @@ var init_get_quota = __esm({
       outputSchema: {
         type: "object",
         properties: {
-          plan: { type: ["string", "null"], description: "Org plan tier (e.g., FREE, PRO)." },
+          plan: {
+            type: ["string", "null"],
+            description: "Org plan tier (e.g., FREE, TIER1, TIER2). May be null."
+          },
+          org: {
+            type: "object",
+            description: "Org-level quota state.",
+            properties: {
+              spend: { type: "array", description: "Reserved; empty in practice.", items: { type: "object" } },
+              resources: {
+                type: "array",
+                description: "Per-resource per-window USAGE. Each: {resource_type, count, window_type, resets_at}. `count` is the amount USED in that window (not remaining, not a cap). No cap field is returned by the API.",
+                items: { type: "object" }
+              }
+            }
+          },
+          user: {
+            type: "object",
+            description: "User-level quota state, same shape as `org`. May be absent.",
+            properties: {
+              spend: { type: "array", items: { type: "object" } },
+              resources: { type: "array", items: { type: "object" } }
+            }
+          },
+          // Legacy/compat: the live API does NOT return a top-level `windows`
+          // array — usage lives in org/user.resources[]. Declared only so older
+          // recorded fixtures still conform; do not rely on it.
           windows: {
             type: "array",
-            description: "Per-resource per-window limits. Each: {resource, window, current_units, max_units, resets_at}.",
+            description: "Deprecated \u2014 not returned by the live API. Use org/user.resources[].",
             items: { type: "object" }
           }
         }
@@ -10199,9 +10770,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 +10794,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 +10850,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 +10915,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 +10941,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 +11188,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 +11243,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 +11267,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 +11279,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 +11302,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 +12010,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({
@@ -14578,6 +15241,86 @@ var init_research_lead_by_name_fuzzy = __esm({
   }
 });
 
+// ../core/dist/composite/account-history.js
+var accountHistory;
+var init_account_history = __esm({
+  "../core/dist/composite/account-history.js"() {
+    "use strict";
+    init_research_lead_by_id();
+    init_tool_descriptions_generated();
+    accountHistory = {
+      name: "leadbay_account_history",
+      annotations: {
+        title: "One account's full back-story",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      description: leadbay_account_history,
+      inputSchema: {
+        type: "object",
+        properties: {
+          leadId: { type: "string", description: "Lead UUID (required)" },
+          activityCount: {
+            type: "number",
+            description: "Number of activity-timeline entries to return, max 100 (default: 50)."
+          },
+          lensId: {
+            type: "number",
+            description: "Lens id the lead came from (escape hatch \u2014 normally omit; defaults to the active lens). Pass it when researching a lead from a lens other than the current default, so the underlying /lenses/{lensId}/leads/{leadId} fetch doesn't 404 after the active lens changed."
+          }
+        },
+        required: ["leadId"],
+        additionalProperties: false
+      },
+      execute: async (client, params, ctx) => {
+        const leadId = params.leadId;
+        const count = Math.max(1, Math.min(Math.floor(params.activityCount ?? 50), 100));
+        const [research, notes, activities] = await Promise.all([
+          researchLeadById.execute(client, { leadId, lensId: params.lensId, response_format: "json" }, ctx),
+          client.request("GET", `/leads/${leadId}/notes`).catch(() => []),
+          client.request("GET", `/leads/${leadId}/activities?count=${count}`).catch(() => ({ items: [], pagination: { total: 0 } }))
+        ]);
+        const r = research;
+        const noteList = Array.isArray(notes) ? notes : [];
+        const activityItems = Array.isArray(activities?.items) ? activities.items : [];
+        return {
+          lead: {
+            id: r.firmographics?.id ?? leadId,
+            name: r.firmographics?.name ?? null
+          },
+          // Current state — signals, firmographics, qualification, contacts,
+          // engagement: passed through verbatim from research_lead_by_id so the
+          // agent gets the live "why is this account hot NOW" picture.
+          signals: r.signals ?? null,
+          firmographics: r.firmographics ?? null,
+          qualification: r.qualification ?? [],
+          contacts: r.contacts ?? null,
+          engagement: r.engagement ?? null,
+          // Historical context — the part research only counts/summarizes.
+          notes: noteList,
+          activities: {
+            activities: activityItems.map((a) => ({ type: a.type, date: a.date })),
+            total: activities?.pagination?.total ?? 0
+          },
+          // Preserve research's pass-through metadata (agent_memory summary,
+          // lens_id, web_fetch_in_progress, has_reachable_contact, …) — the
+          // generated description advertises the memory protocol, so dropping
+          // _meta.agent_memory would make history narratives miss stored
+          // preferences. Spread research _meta first, then layer our counts.
+          _meta: {
+            ...r._meta ?? {},
+            region: client.region,
+            notes_count: noteList.length,
+            activities_returned: activityItems.length
+          }
+        };
+      }
+    };
+  }
+});
+
 // ../core/dist/composite/recall-ordered-titles.js
 var recallOrderedTitles;
 var init_recall_ordered_titles = __esm({
@@ -14758,7 +15501,21 @@ var init_account_status = __esm({
           },
           quota: {
             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."
+            description: "Per-resource quota state (llm_completion, ai_rescore, web_fetch, LENS_EXTRA_REFILL) across daily/weekly/monthly windows. Null if /quota_status failed (see quota_error) or genuinely returned nothing. Pre-check the LENS_EXTRA_REFILL entry before calling leadbay_extend_lens."
+          },
+          quota_error: {
+            type: ["object", "null"],
+            description: "Non-null ONLY when the quota_status call FAILED \u2014 {code, http_status, message}. A 401/403 means the token lacks quota scope: tell the user to reconnect / re-run OAuth. Treat as 'quota unreadable', NEVER as zero usage or 'no limits'.",
+            properties: {
+              code: { type: "string" },
+              http_status: { type: ["number", "null"] },
+              message: { type: "string" }
+            }
+          },
+          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",
@@ -14794,9 +15551,15 @@ var init_account_status = __esm({
       execute: async (client, _params, ctx) => {
         const me = await client.resolveMe();
         let quota = null;
+        let quota_error = null;
         try {
           quota = await client.request("GET", `/organizations/${me.organization.id}/quota_status`);
         } catch (err) {
+          quota_error = {
+            code: err?.code ?? "QUOTA_STATUS_FAILED",
+            http_status: err?._meta?.http_status ?? null,
+            message: err?.message ?? "quota_status request failed"
+          };
           ctx?.logger?.warn?.(`account_status: quota_status failed: ${err?.message ?? err?.code ?? err}`);
         }
         return withAgentMemoryMeta(client, {
@@ -14819,6 +15582,16 @@ 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() ?? [],
+          // Non-null ONLY when the quota_status call failed. The agent must treat
+          // this as "could not read quota" (reauth on 401/403) — NOT as zero usage.
+          quota_error,
           _meta: {
             region: client.region
           }
@@ -14829,13 +15602,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 +15656,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 +15747,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 +15806,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 +16685,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 +16710,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 +16748,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 +16786,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 +16897,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 +17493,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 +17758,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 +17927,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 +17948,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,17 +17963,36 @@ 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;
       }
     };
   }
 });
 
+// ../core/dist/composite/_credits-helpers.js
+async function readCreditsRemaining(client, force = false) {
+  try {
+    const me = await client.resolveMe(force);
+    return me.organization.billing?.ai_credits ?? null;
+  } catch {
+    return null;
+  }
+}
+var init_credits_helpers = __esm({
+  "../core/dist/composite/_credits-helpers.js"() {
+    "use strict";
+  }
+});
+
 // ../core/dist/composite/enrich-titles.js
 var DEFAULT_CANDIDATE_COUNT, enrichTitles;
 var init_enrich_titles = __esm({
   "../core/dist/composite/enrich-titles.js"() {
     "use strict";
+    init_credits_helpers();
     init_tool_descriptions_generated();
     DEFAULT_CANDIDATE_COUNT = 25;
     enrichTitles = {
@@ -17246,6 +18076,10 @@ var init_enrich_titles = __esm({
             type: "number",
             description: "Count of enrichable contacts at preview time."
           },
+          credits_remaining: {
+            type: ["number", "null"],
+            description: "AI-credit balance BEFORE launching (billing.ai_credits). Present in discover / preview_only / dry_run modes. Pair with enrichable_contacts to tell the user 'you have N credits, this will enrich M contacts' \u2014 do NOT estimate an exact cost (the per-contact rate is backend-only). Null = billing unavailable."
+          },
           selected_lead_count: {
             type: "number",
             description: "How many leads the selection covers."
@@ -17369,6 +18203,10 @@ var init_enrich_titles = __esm({
                 previously_enriched: previouslyEnriched,
                 enrichable_contacts: enrichableContacts,
                 selected_lead_count: leadIds.length,
+                // BEFORE: show balance + volume. We can't estimate exact cost
+                // (the per-contact rate is backend-only), so surface the balance
+                // and the count, not a fabricated "will cost N".
+                credits_remaining: await readCreditsRemaining(client),
                 next_action: "Pick titles to enrich and call leadbay_enrich_titles again with titles=[...]"
               };
             }
@@ -17391,7 +18229,8 @@ var init_enrich_titles = __esm({
                 preview,
                 launched: false,
                 message: "No enrichable contacts for the chosen titles. Try other titles from available_titles or recommendations.",
-                available_titles: availableTitles
+                available_titles: availableTitles,
+                credits_remaining: await readCreditsRemaining(client)
               };
             }
             if (params.dry_run) {
@@ -17399,7 +18238,12 @@ var init_enrich_titles = __esm({
                 mode: "dry_run",
                 preview,
                 launched: false,
-                would_launch: { titles: params.titles, email, phone }
+                would_launch: { titles: params.titles, email, phone },
+                // BEFORE confirmation gate: balance + how many contacts WOULD be
+                // enriched. enrichable_contacts is the volume; credits_remaining
+                // the balance. No estimated cost — that rate is backend-only.
+                enrichable_contacts: preview.enrichable_contacts,
+                credits_remaining: await readCreditsRemaining(client)
               };
             }
             const tracker = ctx?.bulkTracker;
@@ -17429,6 +18273,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 +18289,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 +18315,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 +18346,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 +18366,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;
@@ -17538,6 +18394,7 @@ var init_bulk_enrich_status = __esm({
     "use strict";
     init_get_contacts();
     init_bulk_store();
+    init_credits_helpers();
     init_tool_descriptions_generated();
     STATUS_FETCH_CONCURRENCY = 5;
     bulkEnrichStatus = {
@@ -17604,6 +18461,10 @@ var init_bulk_enrich_status = __esm({
             type: "boolean",
             description: "True when overall_progress.done === total AND no partial_failures."
           },
+          credits_remaining: {
+            type: ["number", "null"],
+            description: "AI-credit balance re-read after the spend (force-refreshed /users/me \u2192 billing.ai_credits). Present only when all_done. Null = billing unavailable (don't read as zero). NOTE: a per-run 'credits used' figure is intentionally NOT returned \u2014 getContacts can't scope cost to this bulk, so any sum would conflate historical enrichments."
+          },
           partial_failures: {
             type: "array",
             description: "Per-lead errors observed during contacts fan-out (omitted when no failures).",
@@ -17689,6 +18550,55 @@ 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}`);
+            const creditsRemaining2 = !inProgress ? await readCreditsRemaining(client, true) : null;
+            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,
+              ...!inProgress ? { credits_remaining: creditsRemaining2 } : {},
+              ...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) => {
@@ -17754,6 +18664,10 @@ var init_bulk_enrich_status = __esm({
         };
         const allDone = totalAll > 0 && totalDone === totalAll && partialFailures.length === 0;
         ctx?.logger?.info?.(`bulk.status_checked bulk_id=${record.bulk_id} done=${totalDone} total=${totalAll} wall_ms=${Date.now() - startMs}`);
+        let creditsRemaining = null;
+        if (allDone) {
+          creditsRemaining = await readCreditsRemaining(client, true);
+        }
         return {
           bulk_id: record.bulk_id,
           launched_at: record.launched_at,
@@ -17766,6 +18680,7 @@ var init_bulk_enrich_status = __esm({
           leads,
           overall_progress: overallProgress,
           all_done: allDone,
+          ...allDone ? { credits_remaining: creditsRemaining } : {},
           ...partialFailures.length > 0 ? { partial_failures: partialFailures } : {}
         };
       }
@@ -19457,8 +20372,12 @@ __export(dist_exports, {
   InMemoryBulkStore: () => InMemoryBulkStore,
   LeadbayClient: () => LeadbayClient,
   LocalBulkStore: () => LocalBulkStore,
+  NotificationsInbox: () => NotificationsInbox,
+  NotificationsWsClient: () => NotificationsWsClient,
   REGIONS: () => REGIONS,
+  accountHistory: () => accountHistory,
   accountStatus: () => accountStatus,
+  acknowledgeNotification: () => acknowledgeNotification,
   addLeadsToCampaign: () => addLeadsToCampaign,
   addNote: () => addNote,
   adjustAudience: () => adjustAudience,
@@ -19466,6 +20385,7 @@ __export(dist_exports, {
   agentMemoryRecall: () => agentMemoryRecall,
   agentMemoryReview: () => agentMemoryReview,
   agentMemoryTools: () => agentMemoryTools,
+  anchorIdFor: () => anchorIdFor,
   answerClarification: () => answerClarification,
   appendEntry: () => appendEntry,
   appendTombstone: () => appendTombstone,
@@ -19474,6 +20394,7 @@ __export(dist_exports, {
   bulkQualifyLeads: () => bulkQualifyLeads,
   campaignCallSheet: () => campaignCallSheet,
   campaignProgression: () => campaignProgression,
+  catchUpNotifications: () => catchUpNotifications,
   clearAgentMemoryCache: () => clearAgentMemoryCache,
   clearMockJournal: () => clearMockJournal,
   clearSelection: () => clearSelection,
@@ -19523,6 +20444,7 @@ __export(dist_exports, {
   importAndQualify: () => importAndQualify,
   importLeads: () => importLeads,
   importStatus: () => importStatus,
+  inferKind: () => inferKind,
   invalidateAgentMemoryCache: () => invalidateAgentMemoryCache,
   isAgentMemoryEnabled: () => isAgentMemoryEnabled,
   isValidBulkId: () => isValidBulkId,
@@ -19563,12 +20485,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 +20507,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 +20537,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();
@@ -19647,6 +20573,7 @@ var init_dist = __esm({
     init_campaign_call_sheet();
     init_research_lead_by_id();
     init_research_lead_by_name_fuzzy();
+    init_account_history();
     init_recall_ordered_titles();
     init_account_status();
     init_bulk_qualify_leads();
@@ -19739,6 +20666,13 @@ var init_dist = __esm({
       campaignCallSheet,
       researchLeadById,
       researchLeadByNameFuzzy,
+      // accountHistory layers FULL notes + activity timeline on top of research
+      // so the agent can write the US4 "why has this dormant account resurfaced"
+      // narrative in ONE call. ALWAYS exposed (compositeReadTools) — the underlying
+      // get_lead_notes / get_lead_activities are ADVANCED-gated, but the
+      // reprioritize-a-neglected-account workflow (#3630 GAP C) must work in a
+      // default deployment without LEADBAY_MCP_ADVANCED=1.
+      accountHistory,
       recallOrderedTitles,
       accountStatus,
       bulkEnrichStatus,
@@ -19771,7 +20705,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 +23059,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 +23194,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 +24638,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.17.3";
+var VERSION = "0.18.1";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 
@@ -24777,21 +25735,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 {