@leadbay/mcp 0.17.2 → 0.18.0

package/dist/bin.js

@@ -553,6 +553,23 @@ var init_client = __esm({
         await this.resolveOrgId();
         await this.resolveTasteProfile();
       }
+      // ─── Notifications helpers ────────────────────────────────────────────
+      // Backend exposes `GET /notifications`, `POST /notifications/{id}/seen`,
+      // `POST /notifications/{id}/archive`, plus `GET /ws/ticket?v=1.0` to mint
+      // a one-shot WS URL. See backend/docs/adr/notifications.md for shape.
+      async listNotifications(args = {}) {
+        const params = new URLSearchParams();
+        params.set("archived", String(args.archived ?? false));
+        params.set("page", String(args.page ?? 0));
+        params.set("count", String(args.count ?? 50));
+        return this.request("GET", `/notifications?${params.toString()}`);
+      }
+      async acknowledgeNotification(notificationId, action = "seen") {
+        await this.requestVoid("POST", `/notifications/${notificationId}/${action}`);
+      }
+      async getWsTicket() {
+        return this.request("GET", "/auth/ws?v=1.0");
+      }
       makeError(code, message, hint, endpoint, retry_after, http_status) {
         const out = { error: true, code, message, hint };
         if (endpoint || this._region) {
@@ -5102,6 +5119,8 @@ var init_composite_file_names = __esm({
       "leadbay_import_leads",
       "leadbay_import_status",
       "leadbay_list_campaigns",
+      "leadbay_my_lenses",
+      "leadbay_new_lens",
       "leadbay_prepare_outreach",
       "leadbay_pull_followups",
       "leadbay_pull_leads",
@@ -5120,8 +5139,306 @@ var init_composite_file_names = __esm({
   }
 });
 
+// ../core/dist/notifications/revise-hint.js
+function reviseHintFor(kind) {
+  switch (kind) {
+    case "bulk_enrich":
+      return HINT_BULK_ENRICH;
+    case "bulk_qualify":
+      return HINT_BULK_QUALIFY;
+    case "import":
+      return HINT_IMPORT;
+    default:
+      return HINT_OTHER;
+  }
+}
+function inferKind(n) {
+  if (n.links.some((l) => l.type === "bulk_enrichment"))
+    return "bulk_enrich";
+  if (n.file_import_id)
+    return "import";
+  if (n.bulk_progress)
+    return "bulk_qualify";
+  return "other";
+}
+function anchorIdFor(n, kind) {
+  if (kind === "bulk_enrich") {
+    const link = n.links.find((l) => l.type === "bulk_enrichment");
+    return link ? String(link.id) : null;
+  }
+  if (kind === "import")
+    return n.file_import_id;
+  return null;
+}
+function toInboxEntry(n) {
+  const kind = inferKind(n);
+  return {
+    notification_id: n.id,
+    kind,
+    anchor_id: anchorIdFor(n, kind),
+    title: n.title,
+    bulk_progress: n.bulk_progress,
+    completed_at: n.updated_at,
+    revise_hint: reviseHintFor(kind)
+  };
+}
+var HINT_BULK_ENRICH, HINT_BULK_QUALIFY, HINT_IMPORT, HINT_OTHER;
+var init_revise_hint = __esm({
+  "../core/dist/notifications/revise-hint.js"() {
+    "use strict";
+    HINT_BULK_ENRICH = "Contact enrichment just finished. Revise any prior output that named these leads' contacts (outreach drafts, contact lists, recommended-lead lists with contact_count, NEXT STEPS asking the user to wait for emails / phones). Re-fetch contacts via leadbay_get_contacts for the affected leads.";
+    HINT_BULK_QUALIFY = "Lead qualification just finished. Revise any prior lead list / ranking / outreach shortlist that depended on ai_agent_lead_score for these leads \u2014 today's leads, top-of-inbox, followups maps, prepare-outreach shortlists. Re-pull qualification answers via leadbay_research_lead_by_id or re-rank via leadbay_pull_leads.";
+    HINT_IMPORT = "CSV / CRM import just finished. Revise any prior output that referenced 'leads available' before the import landed \u2014 lead lists pulled from the affected lens, 'what's new today', followup planning. Re-pull the affected lens via leadbay_pull_leads / leadbay_pull_followups.";
+    HINT_OTHER = "Background work just completed. If you referenced its subject in prior output, re-fetch the affected data and revise.";
+  }
+});
+
+// ../core/dist/notifications/inbox.js
+var DEFAULT_TTL_MS, NotificationsInbox;
+var init_inbox = __esm({
+  "../core/dist/notifications/inbox.js"() {
+    "use strict";
+    init_revise_hint();
+    DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
+    NotificationsInbox = class {
+      entries = /* @__PURE__ */ new Map();
+      ttl_ms;
+      now;
+      constructor(opts = {}) {
+        this.ttl_ms = opts.ttl_ms ?? DEFAULT_TTL_MS;
+        this.now = opts.now ?? Date.now;
+      }
+      // Upsert by notification id. Latest write wins so duplicate arrivals
+      // (WS event + REST catch-up landing the same row) collapse cleanly.
+      record(n) {
+        if (!n.bulk_progress)
+          return;
+        if (n.in_progress)
+          return;
+        const entry = toInboxEntry(n);
+        this.entries.set(entry.notification_id, {
+          entry,
+          recordedAt: this.now()
+        });
+      }
+      list() {
+        this.expireStale();
+        return [...this.entries.values()].map((e) => e.entry);
+      }
+      markSeen(notification_id) {
+        this.entries.delete(notification_id);
+      }
+      size() {
+        this.expireStale();
+        return this.entries.size;
+      }
+      expireStale() {
+        const cutoff = this.now() - this.ttl_ms;
+        for (const [id, e] of this.entries) {
+          if (e.recordedAt < cutoff)
+            this.entries.delete(id);
+        }
+      }
+    };
+  }
+});
+
+// ../core/dist/notifications/catch-up.js
+async function catchUpNotifications(client, inbox, opts = {}) {
+  const count = opts.count ?? DEFAULT_COUNT;
+  let added = 0;
+  try {
+    const page = await client.listNotifications({
+      archived: false,
+      page: 0,
+      count
+    });
+    for (const n of page.items) {
+      if (!n.bulk_progress)
+        continue;
+      if (n.in_progress)
+        continue;
+      if (n.first_seen_at)
+        continue;
+      const sizeBefore = inbox.size();
+      inbox.record(n);
+      if (inbox.size() > sizeBefore)
+        added += 1;
+    }
+    opts.logger?.info?.(`notifications.catch_up scanned=${page.items.length} seeded=${added}`);
+  } catch (err) {
+    opts.logger?.warn?.(`notifications.catch_up failed: ${err?.message ?? err?.code ?? err}`);
+  }
+  return added;
+}
+var DEFAULT_COUNT;
+var init_catch_up = __esm({
+  "../core/dist/notifications/catch-up.js"() {
+    "use strict";
+    DEFAULT_COUNT = 50;
+  }
+});
+
+// ../core/dist/notifications/ws-client.js
+var PING_INTERVAL_MS, RECONNECT_INITIAL_MS, RECONNECT_MAX_MS, NotificationsWsClient;
+var init_ws_client = __esm({
+  "../core/dist/notifications/ws-client.js"() {
+    "use strict";
+    init_catch_up();
+    PING_INTERVAL_MS = 3e4;
+    RECONNECT_INITIAL_MS = 1e3;
+    RECONNECT_MAX_MS = 3e4;
+    NotificationsWsClient = class {
+      client;
+      inbox;
+      logger;
+      ws = null;
+      pingTimer = null;
+      reconnectTimer = null;
+      reconnectDelay = RECONNECT_INITIAL_MS;
+      stopped = false;
+      constructor(opts) {
+        this.client = opts.client;
+        this.inbox = opts.inbox;
+        this.logger = opts.logger;
+      }
+      async start() {
+        this.stopped = false;
+        await catchUpNotifications(this.client, this.inbox, { logger: this.logger });
+        void this.connect();
+      }
+      stop() {
+        this.stopped = true;
+        if (this.pingTimer)
+          clearInterval(this.pingTimer);
+        if (this.reconnectTimer)
+          clearTimeout(this.reconnectTimer);
+        this.pingTimer = null;
+        this.reconnectTimer = null;
+        if (this.ws) {
+          try {
+            this.ws.close(1e3, "shutdown");
+          } catch {
+          }
+          this.ws = null;
+        }
+      }
+      async connect() {
+        if (this.stopped)
+          return;
+        let url;
+        try {
+          const ticket = await this.client.getWsTicket();
+          url = ticket.url;
+        } catch (err) {
+          this.logger?.warn?.(`notifications.ws ticket_fetch_failed: ${err?.message ?? err?.code ?? err}`);
+          this.scheduleReconnect();
+          return;
+        }
+        let ws;
+        try {
+          ws = new WebSocket(url);
+        } catch (err) {
+          this.logger?.warn?.(`notifications.ws construct_failed: ${err?.message ?? err}`);
+          this.scheduleReconnect();
+          return;
+        }
+        this.ws = ws;
+        ws.addEventListener("open", () => {
+          this.logger?.info?.("notifications.ws connected");
+          this.reconnectDelay = RECONNECT_INITIAL_MS;
+          void catchUpNotifications(this.client, this.inbox, {
+            logger: this.logger
+          });
+          this.pingTimer = setInterval(() => this.sendPing(), PING_INTERVAL_MS);
+        });
+        ws.addEventListener("message", (ev) => {
+          const text = typeof ev.data === "string" ? ev.data : String(ev.data ?? "");
+          if (!text)
+            return;
+          let msg;
+          try {
+            msg = JSON.parse(text);
+          } catch {
+            this.logger?.warn?.("notifications.ws non_json_frame");
+            return;
+          }
+          this.handleMessage(msg);
+        });
+        ws.addEventListener("error", (ev) => {
+          this.logger?.warn?.(`notifications.ws error: ${ev?.message ?? "(no detail)"}`);
+        });
+        ws.addEventListener("close", (ev) => {
+          this.logger?.info?.(`notifications.ws closed code=${ev.code} reason=${ev.reason || "(none)"}`);
+          if (this.pingTimer)
+            clearInterval(this.pingTimer);
+          this.pingTimer = null;
+          this.ws = null;
+          this.scheduleReconnect();
+        });
+      }
+      handleMessage(msg) {
+        if (msg.type === "pong")
+          return;
+        if (msg.type === "ping") {
+          this.sendRaw({ type: "pong" });
+          return;
+        }
+        if (msg.type !== "notification")
+          return;
+        const { type: _t, ...rest } = msg;
+        void _t;
+        const n = rest;
+        if (n.bulk_progress == null || n.in_progress) {
+          return;
+        }
+        this.inbox.record(n);
+        this.logger?.info?.(`notifications.ws terminal id=${n.id} kind=${n.file_import_id ? "import" : n.links.some((l) => l.type === "bulk_enrichment") ? "bulk_enrich" : "bulk_qualify"}`);
+      }
+      sendPing() {
+        this.sendRaw({ type: "ping" });
+      }
+      sendRaw(obj) {
+        if (!this.ws)
+          return;
+        if (this.ws.readyState !== WebSocket.OPEN)
+          return;
+        try {
+          this.ws.send(JSON.stringify(obj));
+        } catch (err) {
+          this.logger?.warn?.(`notifications.ws send_failed: ${err?.message ?? err}`);
+        }
+      }
+      scheduleReconnect() {
+        if (this.stopped)
+          return;
+        if (this.reconnectTimer)
+          return;
+        const delay = this.reconnectDelay;
+        this.reconnectDelay = Math.min(this.reconnectDelay * 2, RECONNECT_MAX_MS);
+        this.reconnectTimer = setTimeout(() => {
+          this.reconnectTimer = null;
+          void this.connect();
+        }, delay);
+        this.logger?.info?.(`notifications.ws reconnect_in_${delay}ms`);
+      }
+    };
+  }
+});
+
+// ../core/dist/notifications/index.js
+var init_notifications = __esm({
+  "../core/dist/notifications/index.js"() {
+    "use strict";
+    init_inbox();
+    init_ws_client();
+    init_catch_up();
+    init_revise_hint();
+  }
+});
+
 // ../core/dist/tool-descriptions.generated.js
-var leadbay_account_status, leadbay_add_leads_to_campaign, leadbay_add_note, leadbay_adjust_audience, leadbay_agent_memory_capture, leadbay_agent_memory_recall, leadbay_agent_memory_review, leadbay_answer_clarification, leadbay_bulk_enrich_status, leadbay_bulk_qualify_leads, leadbay_campaign_call_sheet, leadbay_campaign_progression, leadbay_clear_selection, leadbay_clear_user_prompt, leadbay_create_campaign, leadbay_create_custom_field, leadbay_create_lens, leadbay_create_lens_draft, leadbay_create_topup_link, leadbay_deselect_leads, leadbay_discover_leads, leadbay_dislike_lead, leadbay_dismiss_clarification, leadbay_enrich_contacts, leadbay_enrich_titles, leadbay_extend_lens, leadbay_followups_map, leadbay_get_clarification, leadbay_get_contacts, leadbay_get_enrichment_job_titles, leadbay_get_epilogue_responses, leadbay_get_lead_activities, leadbay_get_lead_notes, leadbay_get_lead_profile, leadbay_get_lens_filter, leadbay_get_lens_scoring, leadbay_get_prospecting_actions, leadbay_get_quota, leadbay_get_selection_ids, leadbay_get_taste_profile, leadbay_get_user_prompt, leadbay_get_web_fetch, leadbay_import_and_qualify, leadbay_import_leads, leadbay_import_status, leadbay_launch_bulk_enrichment, leadbay_like_lead, leadbay_list_campaigns, leadbay_list_lenses, leadbay_list_locations, leadbay_list_mappable_fields, leadbay_list_sectors, leadbay_login, leadbay_open_billing_portal, leadbay_pick_clarification, leadbay_prepare_outreach, leadbay_preview_bulk_enrichment, leadbay_promote_lens, leadbay_pull_followups, leadbay_pull_leads, leadbay_qualify_lead, leadbay_qualify_status, leadbay_recall_ordered_titles, leadbay_refine_prompt, leadbay_remove_epilogue, leadbay_remove_leads_from_campaign, leadbay_remove_pushback, leadbay_report_friction, leadbay_report_outreach, leadbay_research_lead_by_id, leadbay_research_lead_by_name_fuzzy, leadbay_resolve_import_rows, leadbay_seed_candidates, leadbay_select_leads, leadbay_set_active_lens, leadbay_set_epilogue_status, leadbay_set_pushback, leadbay_set_user_prompt, leadbay_tour_plan, leadbay_update_lens, leadbay_update_lens_filter;
+var leadbay_account_status, leadbay_acknowledge_notification, leadbay_add_leads_to_campaign, leadbay_add_note, leadbay_adjust_audience, leadbay_agent_memory_capture, leadbay_agent_memory_recall, leadbay_agent_memory_review, leadbay_answer_clarification, leadbay_bulk_enrich_status, leadbay_bulk_qualify_leads, leadbay_campaign_call_sheet, leadbay_campaign_progression, leadbay_clear_selection, leadbay_clear_user_prompt, leadbay_create_campaign, leadbay_create_custom_field, leadbay_create_lens, leadbay_create_lens_draft, leadbay_create_topup_link, leadbay_deselect_leads, leadbay_discover_leads, leadbay_dislike_lead, leadbay_dismiss_clarification, leadbay_enrich_contacts, leadbay_enrich_titles, leadbay_extend_lens, leadbay_followups_map, leadbay_get_clarification, leadbay_get_contacts, leadbay_get_enrichment_job_titles, leadbay_get_epilogue_responses, leadbay_get_lead_activities, leadbay_get_lead_notes, leadbay_get_lead_profile, leadbay_get_lens_filter, leadbay_get_lens_scoring, leadbay_get_prospecting_actions, leadbay_get_quota, leadbay_get_selection_ids, leadbay_get_taste_profile, leadbay_get_user_prompt, leadbay_get_web_fetch, leadbay_import_and_qualify, leadbay_import_leads, leadbay_import_status, leadbay_launch_bulk_enrichment, leadbay_like_lead, leadbay_list_campaigns, leadbay_list_lenses, leadbay_list_locations, leadbay_list_mappable_fields, leadbay_list_sectors, leadbay_login, leadbay_my_lenses, leadbay_new_lens, leadbay_open_billing_portal, leadbay_pick_clarification, leadbay_prepare_outreach, leadbay_preview_bulk_enrichment, leadbay_promote_lens, leadbay_pull_followups, leadbay_pull_leads, leadbay_qualify_lead, leadbay_qualify_status, leadbay_recall_ordered_titles, leadbay_refine_prompt, leadbay_remove_epilogue, leadbay_remove_leads_from_campaign, leadbay_remove_pushback, leadbay_report_friction, leadbay_report_outreach, leadbay_research_lead_by_id, leadbay_research_lead_by_name_fuzzy, leadbay_resolve_import_rows, leadbay_seed_candidates, leadbay_select_leads, leadbay_set_active_lens, leadbay_set_epilogue_status, leadbay_set_pushback, leadbay_set_user_prompt, leadbay_tour_plan, leadbay_update_lens, leadbay_update_lens_filter;
 var init_tool_descriptions_generated = __esm({
   "../core/dist/tool-descriptions.generated.js"() {
     "use strict";
@@ -5160,9 +5477,52 @@ Show the user's account state \u2014 admin rights, language, last-active lens, c
 
 **After a user tops up, do NOT keep refusing \u2014 RETRY.** If the user signals they topped up / bought credits / added credits, the previous QUOTA_EXCEEDED is invalidated the moment the Stripe webhook lands. RE-CALL \`leadbay_account_status\` to pick up the new state AND retry the originally failed call. The retry itself does not require a successful account_status check first \u2014 a topped-up user has cleared the throttle whether or not your cached snapshot reflects it yet. If the retry hits the wall again, only then re-offer top-up / wait. **A stale quota snapshot is never a reason to gate-keep a topped-up user.**
 
+**\`notifications\` block.** The response now includes a top-level \`notifications\` array listing background work the user (or agent) initiated that has since completed (\`bulk_enrich\`, \`bulk_qualify\`, \`import\`). These are signals to revise prior agent outputs the just-finished work might have made stale \u2014 they're NOT a pending-task list for the user. After revising (or confirming nothing is affected), call \`leadbay_acknowledge_notification(notification_id)\`. Full handling protocol below.
+
+## GATE \u2014 INSPECT \`_meta.notifications\` ON EVERY RESPONSE
+
+Some Leadbay tool responses include a \`_meta.notifications\` array listing **background work the user (or you) initiated that has since completed**. The three relevant kinds:
+
+| Kind | What just finished |
+|---|---|
+| \`bulk_enrich\` | A bulk contact-enrichment job (emails / phone numbers attached to leads' contacts). |
+| \`bulk_qualify\` | A bulk lead-qualification job (web-fetch + AI rescore, producing \`ai_agent_lead_score\` and qualification answers). |
+| \`import\` | A CSV / CRM file import (rows resolved to leads in the user's pipeline). |
+
+**Your job when you see an entry: revise prior outputs the just-finished work might have made stale.** This is NOT a pending-task list. It's a "your earlier answer used data that has now changed" signal.
+
+| Kind | Outputs you've produced that may now be stale \u2014 refresh them |
+|---|---|
+| \`bulk_enrich\` | Outreach drafts mentioning these leads' contacts; contact lists; recommended-lead lists citing \`contact_count\`; NEXT STEPS that asked the user to wait for emails / phones. Re-fetch via \`leadbay_get_contacts(leadId)\` for the affected leads. |
+| \`bulk_qualify\` | Lead rankings / shortlists you produced without \`ai_agent_lead_score\`; "today's leads"; followup maps; prepare-outreach picks. Re-pull via \`leadbay_pull_leads\` / \`leadbay_research_lead_by_id\`. |
+| \`import\` | "Available leads" claims; pulls from the affected lens that ran before the import landed; followup planning that needed the imported set. Re-pull via \`leadbay_pull_leads\` / \`leadbay_pull_followups\`. |
+
+**After revising (or after confirming no prior output is affected):** call \`leadbay_acknowledge_notification(notification_id)\` so the entry stops resurfacing on every tool response. Ack-and-move-on is correct even when nothing was stale \u2014 that's how the inbox stays focused on what's actually pending.
+
+**Do NOT** interpret these entries as "things waiting for the user." The user expects you to handle them silently. They are signals to YOU \u2014 agent \u2014 that prior outputs need a refresh.
+
+**Don't poll.** When you launch a long operation (enrichment / qualification / import), simply continue the conversation \u2014 the next time you call any tool, the completed-work entry will appear in \`_meta.notifications\`. Status tools (\`leadbay_bulk_enrich_status\`, \`leadbay_qualify_status\`, \`leadbay_import_status\`) exist for the case where you want the answer NOW (mid-conversation), not for ambient polling.
+
+Also surfaced as a top-level \`notifications\` array on \`leadbay_account_status\` \u2014 same shape, same handling.
+
+
 WHEN TO USE: at the start of a session to know what the agent can/can't do, after a 429 to explain to the user which resource window was exhausted and when it resets (and to offer the top-up alternative), and after the user signals a top-up so the agent can resume the interrupted workflow.
 
 WHEN NOT TO USE: as a pre-flight gate before bulk ops \u2014 operations themselves return 429; this tool is for context, not gating. And: a recent quota snapshot showing "exhausted" is NOT a reason to refuse a write call when the user has just topped up \u2014 re-call this tool first, then proceed.
+`;
+    leadbay_acknowledge_notification = `Acknowledge a Leadbay notification \u2014 i.e. tell the MCP and the backend "I've seen this and acted on it." Wraps \`POST /1.5/notifications/{id}/seen\` (default) or \`/archive\` (when \`archive:true\`) and drops the entry from the local inbox so subsequent \`_meta.notifications\` payloads stop carrying it.
+
+**When to call.** After you read an entry from \`_meta.notifications\` or \`account_status.notifications\` and have revised whatever prior output the just-finished background work might have made stale (outreach drafts, lead lists, "available leads" claims, followup plans). Mark-seen tells the human team's pipeline you handled this and prevents the notification from re-surfacing on every subsequent tool response.
+
+If nothing you produced for the user is affected, ack anyway with \`archive:false\` \u2014 the entry should still clear so the inbox stays focused on what's actually pending.
+
+Use \`archive:true\` only when you want the row gone from the FE notification dropdown too (e.g. a non-actionable system notification that's already handled). Default behaviour is \`seen\` \u2014 same as the FE dropdown's "click to read" semantics.
+
+WHEN TO USE: immediately after you finish reviewing / revising in response to a \`_meta.notifications[]\` entry. Idempotent \u2014 calling twice with the same id is safe.
+
+WHEN NOT TO USE: before doing the revision work; for general "mark all read" sweeps (call once per notification id you've actually consumed).
+
+This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 `;
     leadbay_add_leads_to_campaign = `## WHEN TO USE
 
@@ -5218,7 +5578,37 @@ WHEN NOT TO USE: to log an outreach action \u2014 use leadbay_report_outreach, w
 
 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_adjust_audience = `Restrict (or expand) the lens audience by sector / size. Free-text sectors are auto-resolved against the sector taxonomy; ambiguous matches are surfaced to the agent rather than guessed silently. Permission routing is hidden: the default lens auto-clones to a new user lens; an org-level lens defaults to a per-user draft (admins can override with \`save_for_org:true\`). Filter MERGES with existing criteria (unrelated criteria are not dropped).
+    leadbay_adjust_audience = `## WHEN TO USE
+
+Trigger phrases: "narrow the audience to <sector>", "add <sector> to my <name> lens", "remove <sector> from this lens", "only show me companies of <size>", "stop including <sector>", "broaden this lens to also include <sector>".
+
+**Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
+
+Do NOT use for: "create a new lens called X" \u2192 \`leadbay_new_lens\`; "make a new audience for Y" \u2192 \`leadbay_new_lens\`; "show me / list / switch my lenses" \u2192 \`leadbay_my_lenses\`; "focus on a kind of company beyond sector/size (e.g. 'hospitals running their own IT')" \u2192 \`leadbay_refine_prompt\`.
+
+Prefer when: user wants to change an EXISTING lens's sectors/sizes. If the user NAMES a lens ('my Joinery lens'), you MUST pass lensName with that name \u2014 do NOT edit the active lens. To create a brand-new lens use leadbay_new_lens instead.
+
+Examples that SHOULD invoke this tool:
+- "Add fintech to my Joinery lens."
+- "Narrow my audience to manufacturing companies, 50\u2013500 people."
+- "Stop including retail in this lens."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Create a lens called Joinery for fintech."
+- "Show me my lenses."
+- "Focus on hospitals that run their own IT."
+
+## RENDER (quick)
+
+On \`applied\`: confirm the lens edited (name) + the sectors/sizes added as
+chips. On \`ambiguous_sectors\` / \`ambiguous_lens\` / \`lens_not_found\`: surface
+the candidates and ask the user to pick, then re-call with the id/exact name.
+
+---
+
+Restrict (or expand) the lens audience by sector / size. Free-text sectors are auto-resolved against the sector taxonomy; ambiguous matches are surfaced to the agent rather than guessed silently. Permission routing is hidden: the default lens auto-clones to a new user lens; an org-level lens defaults to a per-user draft (admins can override with \`save_for_org:true\`). Filter MERGES with existing criteria (unrelated criteria are not dropped).
+
+**Targeting a lens \u2014 READ THIS.** By default this edits the user's ACTIVE lens. **If the user names a lens** ("add fintech to my **Joinery** lens", "in my Nordics lens, exclude retail"), you MUST pass \`lensName\` with that name (\`lensName:"Joinery"\`). Do NOT silently edit the active lens when a different one was named \u2014 that corrupts the wrong audience and is a top friction source. The name resolves against the user's lenses (case-insensitive, exact then unique-substring); it is edit-only and does NOT change which lens is active. An unmatched name returns \`status:"lens_not_found"\` with the lens list, and a name matching several returns \`status:"ambiguous_lens"\` with the candidates \u2014 surface them and re-call with the exact \`lensName\` or a \`lensId\`. Use \`leadbay_my_lenses\` if the user first wants to SEE or SWITCH lenses. To CREATE a brand-new lens, use \`leadbay_new_lens\` \u2014 not this tool.
 
 WHEN TO USE: when the user wants to see different kinds of leads (sector / size / etc.).
 
@@ -6431,6 +6821,258 @@ WHEN TO USE: at the start of a session if no token is preconfigured (cfg.token /
 WHEN NOT TO USE: if a token is already preconfigured \u2014 you'll just overwrite it. The user needs a Leadbay account first; they can register at https://wow.leadbay.ai/?register=true.
 
 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_my_lenses = `## WHEN TO USE
+
+Trigger phrases: "show me my lenses", "list my lenses", "which audiences do I have", "switch to my <name> lens", "change lens", "rename my <name> lens to <X>", "set the description of my <name> lens", "delete my <name> lens", "remove this lens".
+
+**Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
+
+Do NOT use for: "narrow the audience" \u2192 \`leadbay_adjust_audience\`; "stop showing me <sector>" \u2192 \`leadbay_refine_prompt\`; "more leads on this lens" \u2192 \`leadbay_extend_lens\`; "show me today's leads" \u2192 \`leadbay_pull_leads\`.
+
+Prefer when: user wants to SEE lenses, CHANGE which is active, RENAME one, or DELETE one \u2014 not edit a lens's sector/size criteria
+
+Examples that SHOULD invoke this tool:
+- "Show me my lenses."
+- "Rename my Auto lens to Automotive and add a description."
+- "Delete my old Auto lens."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Narrow the audience to fintech only."
+- "I want more leads on this lens."
+- "Show me today's leads."
+
+## RENDER (quick)
+
+Small markdown table, active lens first: col 1 = \u2B50 prefix when active +
+lens name; col 2 = description (or \`\u2014\`). After a switch lead with
+"Now showing **<name>**."; after a rename lead with the rename confirmation.
+Full algorithm below.
+
+---
+
+List the user's lenses (saved audiences) and, when asked, switch which one is active. A lens shapes the kind of leads delivered each day; this tool is how the user sees their audiences and moves between them \u2014 it does NOT edit a lens's criteria (that's \`leadbay_adjust_audience\`).
+
+**Three modes, one tool:**
+
+- **List (no args)** \u2014 pure read. Returns \`{status:"listed", lenses:[{id, name, description, is_active}], active_lens_id}\`. The active lens is resolved from the user's last-requested lens, so \`is_active\` is authoritative even if a row's flag is stale.
+- **Switch (\`switchToLensId\`)** \u2014 changes the active lens to that id and returns the REFRESHED list. The id MUST be one of the user's lenses; an unknown id returns \`{status:"not_found"}\` with the current list \u2014 surface it and ask the user to pick, do NOT invent an id. Switching to the already-active lens is a harmless no-op.
+- **Edit (\`editLensId\` + \`newName\` and/or \`newDescription\`)** \u2014 rename and/or set the description of a lens in one call, returns the REFRESHED list. Provide either or both; pass \`newDescription:""\` to clear a description. Same not_found handling. Use the \`id\` from the list for the lens the user named.
+- **Delete (\`deleteLensId\`)** \u2014 DESTRUCTIVE and confirm-gated. Without \`confirm:true\` it returns \`status:"delete_preview"\` with \`will_delete\` and removes NOTHING \u2014 show it, get the user's explicit yes, then re-call with \`confirm:true\`. The DEFAULT lens cannot be deleted (\`status:"cannot_delete_default"\`). Deleting the active lens leaves no active lens until the next switch/pull resolves one.
+
+**Lens ids are strings** (e.g. \`"40005"\`) \u2014 pass the \`id\` value straight from the list when switching/renaming/deleting; it is fine to pass it as the string it came as.
+
+**When the user is vague** ("switch lens" with no target), list first, then offer the lenses as a quick choice via \`ask_user_input_v0\` rather than guessing.
+
+WHEN TO USE: when the user wants to see their lenses or switch the active one. Canonical phrasings: "show me my lenses", "which audiences do I have", "switch to my <name> lens".
+
+WHEN NOT TO USE: to change a lens's audience criteria \u2014 that's \`leadbay_adjust_audience\`. Not for refining beyond firmographics (\`leadbay_refine_prompt\`), not for topping up the same lens (\`leadbay_extend_lens\`), not for the daily pull (\`leadbay_pull_leads\`).
+
+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\`.
+
+
+## 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.
+
+
+---
+
+## RENDERING \u2014 lenses table, active-first
+
+Markdown table with TWO columns. Sort **active lens first**, then by \`name\`
+ascending. **No score bar** \u2014 the \`\u25B0\u2756\u25B1\` glyph identity belongs to lead
+discovery, not lenses.
+
+**Column 1 \u2014 Lens**
+- Prefix \`\u2B50 \` when \`is_active\` is true; otherwise no prefix.
+- The lens name in **bold**. (Lenses have no public URL \u2014 do not fabricate a link.)
+
+**Column 2 \u2014 Description**
+- \`description\` verbatim, clipped to \u2264 18 words.
+- When null/empty: render \`\u2014\`.
+
+**After a \`switched: true\` response**, open with a single confirmation line
+ABOVE the table: \`Now showing **<name>**.\` For \`status: "not_found"\`, lead with
+the \`message\` (the bad id) and render the list so the user can pick a real one.
+
+**Empty list** (\`lenses: []\`): render \`*You don't have any lenses yet.*\` \u2014 do not
+render an empty table.
+
+**Legend:** \u2B50 active lens.
+
+
+## NEXT STEPS \u2014 after \`leadbay_my_lenses\`
+
+**RENDER NEXT STEPS via \`ask_user_input_v0\` when the host exposes it.**
+
+The (Observation, Suggest, Calls) table below is the source of truth for which moves are valid. Pick the 2\u20134 most relevant rows based on what the response actually contains, then surface them as a \`single_select\` quick-select widget:
+
+\`\`\`
+ask_user_input_v0({
+  questions: [{
+    question: "What next?",
+    type: "single_select",
+    options: [
+      "<Suggest column from row 1>",
+      "<Suggest column from row 2>",
+      "<Suggest column from row 3>"
+    ]
+  }]
+})
+\`\`\`
+
+When the user picks an option, you call the matching tool from the \`Calls\` column. Constraints carried over from the widget contract: 2\u20134 mutually-exclusive options per question, button-sized labels (\u22646 words), max 3 questions per call.
+
+**Fallback prose mode** \u2014 when the host doesn't expose \`ask_user_input_v0\` (or it returned an error): surface the same 2\u20133 picks as a short bulleted list of "Suggest" phrasings. The table itself stays internal; never recite the whole table to the user.
+
+---
+
+
+
+Pick the 2\u20133 rows that fit what the user is likely to want next. When the user
+named no target but wants to switch, offer the lenses themselves as the
+quick-select options (each option = a lens name \u2192 \`leadbay_my_lenses(switchToLensId=<id>)\`).
+
+| Observation                          | Suggest                                  | Calls                                                |
+|--------------------------------------|------------------------------------------|------------------------------------------------------|
+| User wants a different lens          | "Switch to <lens name>"                  | \`leadbay_my_lenses(switchToLensId=<id>)\`             |
+| User wants to rename / describe a lens| "Rename or describe <lens>"             | \`leadbay_my_lenses(editLensId=<id>, newName?=<X>, newDescription?=<Y>)\` |
+| User wants to delete a lens          | "Delete <lens>"                          | \`leadbay_my_lenses(deleteLensId=<id>)\` \u2192 confirm \u2192 \`confirm=true\` |
+| \`delete_preview\` (not yet deleted)   | "Yes, delete it"                         | \`leadbay_my_lenses(deleteLensId=<id>, confirm=true)\` |
+| User wants leads on the active lens  | "Pull today's leads"                     | \`leadbay_pull_leads()\`                               |
+| User wants to change the audience    | "Adjust this lens's audience"            | \`leadbay_adjust_audience(...)\`                       |
+| User wants more of the same          | "Get a bigger batch on this lens"        | \`leadbay_extend_lens(...)\`                           |
+
+If nothing fits, default to "pull today's leads on the active lens" \u2014 never
+invent a tool that doesn't exist.
+`;
+    leadbay_new_lens = `## WHEN TO USE
+
+Trigger phrases: "create a lens", "create a new lens called <name>", "create a lens specialized in/into <X>", "make me a new audience for <X>", "set up a lens for <sector>", "new lens named <name>", "I want a lens just for <X>".
+
+**Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
+
+Do NOT use for: "narrow the audience / add or remove a sector on an EXISTING lens" \u2192 \`leadbay_adjust_audience\`; "add <sector> to my <name> lens" \u2192 \`leadbay_adjust_audience\`; "focus on a qualitative trait beyond sector/size" \u2192 \`leadbay_refine_prompt\`; "show me / list / switch my lenses" \u2192 \`leadbay_my_lenses\`; "more leads on this lens" \u2192 \`leadbay_extend_lens\`.
+
+Prefer when: user wants a brand-new lens (create/make/set up, often 'specialized in <X>'). Editing an existing lens \u2192 leadbay_adjust_audience (use lensName). Qualitative refinement \u2192 refine_prompt (admin-only).
+
+Examples that SHOULD invoke this tool:
+- "Create a lens called Joinery for the fintech sector."
+- "Make me a new audience for healthcare companies, 30\u2013300 people."
+- "Set up a new lens named Nordics SaaS."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Add fintech to my Joinery lens."
+- "Show me my lenses."
+- "I want more leads on this lens."
+
+## RENDER (quick)
+
+On \`preview\` (default \u2014 NOTHING created yet): show the lens that WILL be
+created (name + resolved sectors/sizes as chips) and ASK the user to confirm
+via ask_user_input_v0 ("Create this lens?" / "Change something"). Only on
+"yes" re-call with confirm:true. On \`created\`: confirm "Created **<name>**."
+On \`ambiguous_sectors\`: surface the candidate sectors to pick from.
+
+---
+
+Create a brand-new lens (saved audience) and apply its sector/size criteria. Clones a base lens (the user's active/default lens unless \`base\` is given), names it, and applies the filter.
+
+**Confirm before creating \u2014 two-step by default.** A call WITHOUT \`confirm:true\` is a dry run: it resolves the sectors/sizes and returns \`status:"preview"\` with \`will_create\` (what it WOULD build) \u2014 **nothing is created**. Show that to the user, get an explicit yes (ask via \`ask_user_input_v0\`), then re-call the SAME args with \`confirm:true\` to actually create. Never pass \`confirm:true\` on the first call \u2014 the user must see the preview first. (Sector ambiguity is still surfaced in the preview step, so they pick before confirming.)
+
+**Sectors resolve first.** Free-text \`sectors\`/\`exclude_sectors\` are auto-resolved against the taxonomy. If any don't resolve, the tool returns \`status:"ambiguous_sectors"\` with the candidates and **does NOT create the lens** \u2014 so re-calling after picking the right sector won't leave orphan half-built lenses. To discover valid sector labels up front, use \`leadbay_list_sectors\`.
+
+**Does not switch the active lens.** The new lens is created but the user stays on their current one. Offer \`leadbay_my_lenses(switchToLensId=<new id>)\` as a next step if they want to start pulling from it.
+
+WHEN TO USE: when the user wants a NEW lens. Canonical phrasings: "create a lens called X", "make a new audience for Y", "set up a lens for <sector>".
+
+WHEN NOT TO USE: to EDIT an existing lens \u2014 use \`leadbay_adjust_audience\` (pass \`lensName\` to target one by name). Not for listing/switching (\`leadbay_my_lenses\`) or topping up (\`leadbay_extend_lens\`).
+
+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\`.
+
+
+## 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.
+
+
+---
+
+## NEXT STEPS \u2014 after \`leadbay_new_lens\`
+
+**RENDER NEXT STEPS via \`ask_user_input_v0\` when the host exposes it.**
+
+The (Observation, Suggest, Calls) table below is the source of truth for which moves are valid. Pick the 2\u20134 most relevant rows based on what the response actually contains, then surface them as a \`single_select\` quick-select widget:
+
+\`\`\`
+ask_user_input_v0({
+  questions: [{
+    question: "What next?",
+    type: "single_select",
+    options: [
+      "<Suggest column from row 1>",
+      "<Suggest column from row 2>",
+      "<Suggest column from row 3>"
+    ]
+  }]
+})
+\`\`\`
+
+When the user picks an option, you call the matching tool from the \`Calls\` column. Constraints carried over from the widget contract: 2\u20134 mutually-exclusive options per question, button-sized labels (\u22646 words), max 3 questions per call.
+
+**Fallback prose mode** \u2014 when the host doesn't expose \`ask_user_input_v0\` (or it returned an error): surface the same 2\u20133 picks as a short bulleted list of "Suggest" phrasings. The table itself stays internal; never recite the whole table to the user.
+
+---
+
+
+
+Pick the rows that fit. On \`created\`, the switch + pull rows are the natural
+follow-ups. On \`ambiguous_sectors\`, the only move is to pick a sector and re-call.
+
+| Observation                       | Suggest                                  | Calls                                                  |
+|-----------------------------------|------------------------------------------|--------------------------------------------------------|
+| \`preview\` (not yet created)       | "Yes, create this lens"                  | \`leadbay_new_lens(...same args..., confirm=true)\`      |
+| \`preview\` (not yet created)       | "Change the sectors/size first"          | (re-ask the user, then \`leadbay_new_lens\` with new args) |
+| Lens created                      | "Switch to it and pull leads"            | \`leadbay_my_lenses(switchToLensId=<new id>)\` then \`leadbay_pull_leads()\` |
+| Lens created                      | "Refine the audience further"            | \`leadbay_adjust_audience(lensName=<new name>, ...)\`    |
+| Lens created                      | "Leave it; keep my current lens active"  | (no call)                                              |
+| \`ambiguous_sectors\`               | "Pick the right sector and create"       | \`leadbay_new_lens(name=..., sectors=[<chosen id>])\`    |
+
+If nothing fits, default to "switch to the new lens and pull leads" \u2014 never
+invent a tool that doesn't exist.
 `;
     leadbay_open_billing_portal = `Generate a one-shot Stripe customer-portal URL. Wraps \`GET /1.5/stripe/portal\` \u2192 \`{url}\`. Returns a fresh Stripe-hosted URL the user can open to manage their existing Leadbay subscription: change plan tier, swap payment method, view invoices. The agent does NOT make subscription changes itself \u2014 it surfaces the URL and lets the user act.
 
@@ -7064,7 +7706,33 @@ WHEN TO USE: before leadbay_enrich_titles, to plan which titles to order.
 
 WHEN NOT TO USE: when you already know the exact titles you want to enrich.
 `;
-    leadbay_refine_prompt = `Refine the kind of leads Leadbay surfaces, beyond firmographics. Free-text instruction (e.g. "focus on hospitals running their own IT"). Sets the org's \`user_prompt\`; if the new prompt produces ambiguous criteria, Leadbay raises a clarification question, which this composite polls for and surfaces. Admin-only on the backend (will return 403 for non-admins).
+    leadbay_refine_prompt = `## WHEN TO USE
+
+Trigger phrases: "focus on companies that <qualitative trait>", "I prefer leads that <behavior/characteristic>", "prioritize companies running their own IT", "deprioritize companies that just raised".
+
+**Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
+
+Do NOT use for: "create a new lens / a lens specialized into <X>" \u2192 \`leadbay_new_lens\`; "add/remove <sector> to/from my <name> lens" \u2192 \`leadbay_adjust_audience\`; "narrow the audience to <sector> / <size>" \u2192 \`leadbay_adjust_audience\`; "show me / list / switch my lenses" \u2192 \`leadbay_my_lenses\`.
+
+Prefer when: ADMIN-ONLY. Qualitative refinement of the active lens that sector/size can't express. Creating/naming/listing/switching/sector-editing a lens routes elsewhere. Non-admin user \u2192 do NOT pick this.
+
+Examples that SHOULD invoke this tool:
+- "Focus on hospitals that run their own IT in-house."
+- "Prioritize companies that have recently expanded headcount."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Create a lens specialized in automobile."
+- "Add fintech to my Joinery lens."
+- "Show me my lenses."
+
+## RENDER (quick)
+
+On success: confirm the refinement applied to the active lens. If a
+clarification was raised, surface its question (route via ask_user_input_v0).
+
+---
+
+Refine the kind of leads Leadbay surfaces, beyond firmographics. Free-text instruction (e.g. "focus on hospitals running their own IT"). Sets the org's \`user_prompt\`; if the new prompt produces ambiguous criteria, Leadbay raises a clarification question, which this composite polls for and surfaces. Admin-only on the backend (will return 403 for non-admins).
 
 WHEN TO USE: when audience filters (leadbay_adjust_audience) aren't enough.
 
@@ -9889,9 +10557,23 @@ async function completeUploadedChunk(client, upload, mappings, dryRun, perPhaseB
   await pollPreprocess(client, importId, phaseBudget, ctx, signal);
   ctx?.logger?.info?.(`import-leads: preprocess done for importId=${importId}`);
   if (dryRun) {
-    return { importId, records: [] };
+    return { importId, records: [], notification_id: null };
+  }
+  let updateMappingsResp = null;
+  try {
+    updateMappingsResp = await client.request("POST", `/imports/${importId}/update_mappings`, mappings);
+  } catch (err) {
+    if (err?.code === "API_ERROR" || err?.code === "NOT_FOUND") {
+      ctx?.logger?.warn?.(`import-leads: update_mappings raw error (${err?.code}); retrying void`);
+      await client.requestVoid("POST", `/imports/${importId}/update_mappings`, mappings);
+    } else {
+      throw err;
+    }
+  }
+  const importNotificationId = updateMappingsResp?.notification_id ?? null;
+  if (importNotificationId) {
+    ctx?.logger?.info?.(`import-leads: notification_id=${importNotificationId} importId=${importId}`);
   }
-  await client.requestVoid("POST", `/imports/${importId}/update_mappings`, mappings);
   ctx?.logger?.info?.(`import-leads: mappings committed for importId=${importId}`);
   const phaseBudget2 = Math.min(perPhaseBudgetMs, Math.max(1, totalDeadline - Date.now()));
   await pollProcess(client, importId, phaseBudget2, ctx, signal);
@@ -9899,7 +10581,7 @@ async function completeUploadedChunk(client, upload, mappings, dryRun, perPhaseB
   const phaseBudget3 = Math.min(perPhaseBudgetMs, Math.max(1, totalDeadline - Date.now()));
   const records = await pollRecordsToTerminal(client, importId, phaseBudget3, chunk.length, ctx, signal);
   ctx?.logger?.info?.(`import-leads: ${records.length} records terminal for importId=${importId}`);
-  return { importId, records };
+  return { importId, records, notification_id: importNotificationId };
 }
 function reconcileOneChunk(prep, chunk, matched, notImported) {
   const seenInputIndex = /* @__PURE__ */ new Set();
@@ -9955,7 +10637,7 @@ function reconcileOneChunk(prep, chunk, matched, notImported) {
     }
   }
 }
-function buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled) {
+function buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled, notificationIds) {
   const leads = [];
   const not_imported = [];
   if (dryRun) {
@@ -10020,6 +10702,7 @@ function buildImportLeadsResult(client, prep, importIds, matched, notImported, d
     leads,
     not_imported,
     importIds,
+    notification_ids: notificationIds,
     region: client.region,
     cancelled: cancelled || void 0,
     dry_run: dryRun || void 0,
@@ -10045,17 +10728,21 @@ async function runImportInBackground(client, prep, uploadedChunks, opts, ctx, ha
     void (async () => {
       const bgCtx = { logger: ctx.logger, bulkTracker: tracker };
       const importIds = uploadedChunks.map((chunk) => chunk.importId);
+      const notificationIds = [];
       const matched = /* @__PURE__ */ new Map();
       const notImported = /* @__PURE__ */ new Map();
       try {
         const totalDeadline = Date.now() + opts.totalBudget;
         for (const upload of uploadedChunks) {
           const out = await completeUploadedChunk(client, upload, prep.mappings, opts.dryRun, opts.perPhaseBudget, totalDeadline, bgCtx, void 0);
+          if (out.notification_id && !notificationIds.includes(out.notification_id)) {
+            notificationIds.push(out.notification_id);
+          }
           if (!opts.dryRun) {
             reconcileOneChunk(prep, out, matched, notImported);
           }
         }
-        const result = buildImportLeadsResult(client, prep, importIds, matched, notImported, opts.dryRun, false);
+        const result = buildImportLeadsResult(client, prep, importIds, matched, notImported, opts.dryRun, false, notificationIds);
         await tracker.markImportComplete(handleId, {
           leads: result.leads,
           not_imported: result.not_imported,
@@ -10288,6 +10975,7 @@ var init_import_leads = __esm({
             leads: [],
             not_imported,
             importIds: [],
+            notification_ids: [],
             region: client.region,
             dry_run: dryRun || void 0,
             _meta: client.lastMeta ?? {
@@ -10342,6 +11030,10 @@ var init_import_leads = __esm({
             status: "running",
             handle_id: reservation.record.bulk_id,
             importIds: importIds2,
+            // Notifications fire from update_mappings, which the background
+            // task hasn't called yet at this point. They surface via the WS
+            // listener / catch-up REST on subsequent agent turns.
+            notification_ids: [],
             progress: {
               phase: reservation.record.status === "complete" ? "complete" : importIds2.length > 0 ? "preprocess" : "queued",
               records_processed: reservation.record.status === "complete" ? reservation.record.records_total : 0,
@@ -10362,6 +11054,7 @@ var init_import_leads = __esm({
         }
         ctx?.logger?.info?.(`import-leads(${prep.mode}): ${prep.validInputs.length} rows \u2192 ${chunks.length} chunk(s); dry_run=${dryRun}, totalBudgetMs=${totalBudget}`);
         const importIds = [];
+        const notificationIds = [];
         const matched = /* @__PURE__ */ new Map();
         const notImported = /* @__PURE__ */ new Map();
         let cancelled = false;
@@ -10373,6 +11066,9 @@ var init_import_leads = __esm({
           for (let i = 0; i < chunks.length; i++) {
             const chunk = chunks[i];
             const out = await runOneChunk(client, chunk, i, chunks.length, prep.header, prep.mappings, dryRun, perPhaseBudget, totalDeadline, ctx, signal, recordImportId);
+            if (out.notification_id && !notificationIds.includes(out.notification_id)) {
+              notificationIds.push(out.notification_id);
+            }
             if (!dryRun) {
               reconcileOneChunk(prep, out, matched, notImported);
             }
@@ -10393,7 +11089,7 @@ var init_import_leads = __esm({
             throw err;
           }
         }
-        return buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled);
+        return buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled, notificationIds);
       }
     };
   }
@@ -11101,6 +11797,70 @@ var init_agent_memory_review = __esm({
   }
 });
 
+// ../core/dist/tools/acknowledge-notification.js
+var UUID_RE, acknowledgeNotification;
+var init_acknowledge_notification = __esm({
+  "../core/dist/tools/acknowledge-notification.js"() {
+    "use strict";
+    init_tool_descriptions_generated();
+    UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    acknowledgeNotification = {
+      name: "leadbay_acknowledge_notification",
+      annotations: {
+        title: "Acknowledge a Leadbay notification",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      description: leadbay_acknowledge_notification,
+      write: true,
+      inputSchema: {
+        type: "object",
+        properties: {
+          notification_id: {
+            type: "string",
+            description: "UUID of the notification to acknowledge. Use the notification_id from `_meta.notifications[]` or `account_status.notifications[]`."
+          },
+          archive: {
+            type: "boolean",
+            description: "If true, archive the notification (won't appear in `archived=false` listings). If false / omitted, mark seen (resets firstSeenAt)."
+          }
+        },
+        required: ["notification_id"],
+        additionalProperties: false
+      },
+      outputSchema: {
+        type: "object",
+        properties: {
+          acknowledged: { type: "boolean" },
+          notification_id: { type: "string" },
+          action: { type: "string", enum: ["seen", "archive"] }
+        },
+        required: ["acknowledged", "notification_id", "action"]
+      },
+      execute: async (client, params, ctx) => {
+        if (!UUID_RE.test(params.notification_id)) {
+          return {
+            error: true,
+            code: "BAD_INPUT",
+            message: "notification_id must be a UUID",
+            hint: "Pass the notification_id verbatim from _meta.notifications[].notification_id or account_status.notifications[].notification_id."
+          };
+        }
+        const action = params.archive ? "archive" : "seen";
+        await client.acknowledgeNotification(params.notification_id, action);
+        ctx?.notificationsInbox?.markSeen(params.notification_id);
+        return {
+          acknowledged: true,
+          notification_id: params.notification_id,
+          action
+        };
+      }
+    };
+  }
+});
+
 // ../core/dist/tools/select-leads.js
 var selectLeads;
 var init_select_leads = __esm({
@@ -11296,7 +12056,7 @@ var init_create_lens = __esm({
       },
       execute: async (client, params) => {
         const lens = await client.request("POST", "/lenses", {
-          base: params.base,
+          base: String(params.base),
           name: params.name,
           description: params.description
         });
@@ -14450,6 +15210,11 @@ var init_account_status = __esm({
             type: ["object", "null"],
             description: "Per-resource quota state (llm_completion, ai_rescore, web_fetch, LENS_EXTRA_REFILL) across daily/weekly/monthly windows. Null if /quota_status failed (logged in stderr). Pre-check the LENS_EXTRA_REFILL entry before calling leadbay_extend_lens."
           },
+          notifications: {
+            type: "array",
+            description: "Terminal bulk-progress notifications the MCP knows about (background work the user or agent started that has since completed). Each entry carries notification_id, kind (bulk_enrich | bulk_qualify | import | other), bulk_progress counters, and a revise_hint pointing at prior agent outputs the just-finished work might have made stale. After revising affected outputs, call leadbay_acknowledge_notification(notification_id) to clear the entry. Empty array when nothing has completed.",
+            items: { type: "object" }
+          },
           _meta: {
             type: "object",
             properties: {
@@ -14509,6 +15274,13 @@ var init_account_status = __esm({
           // on /me are intentionally NOT surfaced — they're defunct (see
           // SHAPE-DRIFT.md probe round 4).
           quota,
+          // Inbox of terminal bulk-progress notifications. Same shape the MCP
+          // server attaches to `_meta.notifications` on every tool response —
+          // duplicated here as a top-level field so the agent's daily-rhythm
+          // check-in (this composite) sees them without having to read _meta.
+          // Empty array when the WS listener isn't wired (OpenClaw, tests) OR
+          // when nothing has completed since the last ack.
+          notifications: ctx?.notificationsInbox?.list() ?? [],
           _meta: {
             region: client.region
           }
@@ -14516,16 +15288,43 @@ 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;
+});
+
+// ../core/dist/composite/bulk-qualify-leads.js
+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;
@@ -14546,7 +15345,7 @@ var init_bulk_qualify_leads = __esm({
         properties: {
           count: {
             type: "number",
-            description: `How many fresh leads to qualify (default ${DEFAULT_COUNT}, max ${MAX_COUNT})`
+            description: `How many fresh leads to qualify (default ${DEFAULT_COUNT2}, max ${MAX_COUNT})`
           },
           leadIds: {
             type: "array",
@@ -14637,7 +15436,7 @@ var init_bulk_qualify_leads = __esm({
         ]
       },
       execute: async (client, params, ctx) => {
-        const wantCount = Math.min(params.count ?? DEFAULT_COUNT, MAX_COUNT);
+        const wantCount = Math.min(params.count ?? DEFAULT_COUNT2, MAX_COUNT);
         const perLeadBudget = params.per_lead_budget_ms ?? DEFAULT_PER_LEAD_BUDGET_MS;
         const totalBudget = params.total_budget_ms ?? DEFAULT_TOTAL_BUDGET_MS2;
         const totalDeadline = Date.now() + totalBudget;
@@ -14696,69 +15495,50 @@ var init_bulk_qualify_leads = __esm({
             per_lead_budget_ms: perLeadBudget,
             total_budget_ms: totalBudget
           });
-          const launched2 = [];
-          const failed2 = [];
+          let launchedCount = 0;
+          let notificationId = null;
           let quotaExceeded2 = false;
+          let failed2 = [];
           if (!reservation.reused) {
-            for (const leadId of candidates) {
-              if (quotaExceeded2)
-                break;
-              try {
-                await client.requestVoid("POST", `/leads/${leadId}/web_fetch?force_fetch=false`);
-                launched2.push(leadId);
-              } catch (err) {
-                if (err?.code === "QUOTA_EXCEEDED") {
-                  quotaExceeded2 = true;
-                } else if (err?.code === "NOT_FOUND") {
-                  failed2.push({ lead_id: leadId, error: "lead not found" });
-                } else {
-                  failed2.push({
-                    lead_id: leadId,
-                    error: err?.message ?? err?.code ?? "unknown"
-                  });
-                }
-              }
-            }
-            if (failed2.length === candidates.length || launched2.length > 0 || quotaExceeded2) {
-              await ctx.bulkTracker.markLaunched(reservation.record.bulk_id);
+            const launch = await launchBulkQualify(client, candidates, ctx);
+            quotaExceeded2 = launch.quotaExceeded;
+            notificationId = launch.resp?.notification_id ?? null;
+            const queuedIds = launch.resp?.queued_ids ?? [];
+            const skippedIds = launch.resp?.skipped_ids ?? [];
+            launchedCount = queuedIds.length;
+            const seen = /* @__PURE__ */ new Set([...queuedIds, ...skippedIds]);
+            failed2 = candidates.filter((id) => !seen.has(id)).map((id) => ({ lead_id: id, error: "not_queued" }));
+            if (queuedIds.length > 0 || quotaExceeded2 || skippedIds.length > 0 || failed2.length === candidates.length) {
+              await ctx.bulkTracker.markLaunched(reservation.record.bulk_id, notificationId);
             }
+          } else {
+            notificationId = reservation.record.notification_id ?? null;
+            launchedCount = reservation.record.lead_ids.length;
           }
           const out = {
             status: "running",
             handle_id: reservation.record.bulk_id,
             qualify_id: reservation.record.bulk_id,
             lead_ids: candidates,
-            launched_count: reservation.reused ? reservation.record.lead_ids.length : launched2.length,
+            launched_count: launchedCount,
             failed: failed2,
             quota_exceeded: quotaExceeded2,
             lens_id: lensId,
+            notification_id: notificationId,
             _meta: { region: client.region }
           };
           return out;
         }
-        const launched = [];
-        const failed = [];
-        let quotaExceeded = false;
-        for (const leadId of candidates) {
-          if (quotaExceeded)
-            break;
-          try {
-            await client.requestVoid("POST", `/leads/${leadId}/web_fetch?force_fetch=false`);
-            launched.push(leadId);
-          } catch (err) {
-            if (err?.code === "QUOTA_EXCEEDED") {
-              quotaExceeded = true;
-              ctx?.logger?.warn?.(`bulk_qualify_leads: 429 mid-fanout after launching ${launched.length}/${candidates.length} \u2014 stopping further launches but polling those already in flight`);
-            } else if (err?.code === "NOT_FOUND") {
-              failed.push({ lead_id: leadId, error: "lead not found" });
-            } else {
-              failed.push({
-                lead_id: leadId,
-                error: err?.message ?? err?.code ?? "unknown"
-              });
-            }
-          }
+        const inlineLaunch = await launchBulkQualify(client, candidates, ctx);
+        const quotaExceeded = inlineLaunch.quotaExceeded;
+        const launched = inlineLaunch.resp?.queued_ids ?? [];
+        const inlineSkipped = inlineLaunch.resp?.skipped_ids ?? [];
+        const inlineNotificationId = inlineLaunch.resp?.notification_id ?? null;
+        if (inlineNotificationId) {
+          ctx?.logger?.info?.(`bulk_qualify_leads: launched bulk progress_notification_id=${inlineNotificationId} queued=${launched.length} skipped=${inlineSkipped.length}`);
         }
+        const inlineFailedSeen = /* @__PURE__ */ new Set([...launched, ...inlineSkipped]);
+        const failed = candidates.filter((id) => !inlineFailedSeen.has(id)).map((id) => ({ lead_id: id, error: "not_queued" }));
         let progressDone = 0;
         const progressTotal = launched.length;
         if (progressTotal > 0) {
@@ -15594,6 +16374,7 @@ var init_import_and_qualify = __esm({
               ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
               qualify_id: null,
               import_ids: queued.importIds,
+              notification_ids: queued.notification_ids ?? [],
               imported: queued.leads.map((l) => ({
                 leadId: l.leadId,
                 ...l.domain ? { domain: l.domain } : {},
@@ -15618,6 +16399,7 @@ var init_import_and_qualify = __esm({
             ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
             qualify_id: null,
             import_ids: queued.importIds,
+            notification_ids: queued.notification_ids ?? [],
             imported: [],
             not_imported: [],
             qualified: [],
@@ -15655,6 +16437,7 @@ var init_import_and_qualify = __esm({
             ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
             qualify_id: null,
             import_ids: importResult.importIds,
+            notification_ids: importResult.notification_ids ?? [],
             imported: [],
             not_imported: importResult.not_imported.map(toNotImportedEntry),
             qualified: [],
@@ -15692,6 +16475,7 @@ var init_import_and_qualify = __esm({
             ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
             qualify_id: null,
             import_ids: importResult.importIds,
+            notification_ids: importResult.notification_ids ?? [],
             imported,
             not_imported,
             qualified: [],
@@ -15802,6 +16586,7 @@ var init_import_and_qualify = __esm({
           ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
           qualify_id: reservation.record.bulk_id,
           import_ids: importResult.importIds,
+          notification_ids: importResult.notification_ids ?? [],
           imported,
           not_imported,
           qualified,
@@ -16397,16 +17182,20 @@ var init_bulk_store = __esm({
           this.logger?.info?.(`bulk.import_failed bulk_id=${bulk_id}`);
         });
       }
-      async markLaunched(bulk_id) {
+      async markLaunched(bulk_id, notification_id) {
         return this.mutex.run(async () => {
           const all = this.prune(await this.readAll());
           const idx = all.findIndex((r) => r.bulk_id === bulk_id);
           if (idx < 0) {
             throw new Error(`bulk_id not found: ${bulk_id}`);
           }
-          all[idx] = { ...all[idx], status: "launched" };
+          all[idx] = {
+            ...all[idx],
+            status: "launched",
+            ...notification_id ? { notification_id } : {}
+          };
           await this.writeAll(all);
-          this.logger?.info?.(`bulk.launched bulk_id=${bulk_id}`);
+          this.logger?.info?.(`bulk.launched bulk_id=${bulk_id}${notification_id ? ` notification_id=${notification_id}` : ""}`);
           return all[idx];
         });
       }
@@ -16658,6 +17447,14 @@ var init_import_status = __esm({
 });
 
 // ../core/dist/composite/qualify-status.js
+async function readNotification(client, notificationId) {
+  try {
+    const page = await client.listNotifications({ archived: false, count: 50 });
+    return page.items.find((n) => n.id === notificationId) ?? null;
+  } catch {
+    return null;
+  }
+}
 var qualifyStatus;
 var init_qualify_status = __esm({
   "../core/dist/composite/qualify-status.js"() {
@@ -16819,6 +17616,16 @@ var init_qualify_status = __esm({
           const { _stillRunning, _failedCode, ...rest } = r;
           qualified.push(rest);
         }
+        let bulkProgress = null;
+        let inProgressFlag = null;
+        const notifId = record.notification_id ?? null;
+        if (notifId) {
+          const n = await readNotification(client, notifId);
+          if (n) {
+            bulkProgress = n.bulk_progress;
+            inProgressFlag = n.in_progress;
+          }
+        }
         const out = {
           qualify_id: record.bulk_id,
           launched_at: record.launched_at,
@@ -16830,6 +17637,9 @@ var init_qualify_status = __esm({
           still_running,
           failed,
           not_in_lens: [...notInLensSet],
+          notification_id: notifId,
+          bulk_progress: bulkProgress,
+          in_progress: inProgressFlag,
           region: client.region,
           _meta: client.lastMeta ?? {
             region: client.region,
@@ -16842,6 +17652,9 @@ var init_qualify_status = __esm({
           out.per_lead_budget_ms = record.per_lead_budget_ms;
         if (record.total_budget_ms !== void 0)
           out.total_budget_ms = record.total_budget_ms;
+        if (bulkProgress && bulkProgress.quota_hit_count > 0) {
+          out.quota_hit_hint = "Some leads hit the AI-credits quota during qualification. Top up via leadbay_create_topup_link to clear the throttle immediately, or wait until the daily/weekly window resets.";
+        }
         return out;
       }
     };
@@ -17119,6 +17932,7 @@ var init_enrich_titles = __esm({
                   bulk_id: res.record.bulk_id,
                   launched_at: res.record.launched_at,
                   durability: res.record.durability,
+                  notification_id: res.record.notification_id ?? null,
                   seconds_since_original_launch: bulkSecondsSinceOriginal ?? 0,
                   titles: params.titles,
                   email,
@@ -17134,8 +17948,9 @@ var init_enrich_titles = __esm({
               total: 3,
               message: `Launching enrichment for ${params.titles.length} title${params.titles.length === 1 ? "" : "s"}\u2026`
             });
+            let launchResp = null;
             try {
-              await client.requestVoid("POST", "/leads/selection/enrichment/launch", { titles: params.titles, email, phone });
+              launchResp = await client.request("POST", "/leads/selection/enrichment/launch", { titles: params.titles, email, phone });
             } catch (err) {
               const aborted = err?.name === "AbortError" || ctx?.signal?.aborted === true;
               if (bulkRecord && tracker) {
@@ -17159,9 +17974,10 @@ var init_enrich_titles = __esm({
               }
               throw err;
             }
+            const notificationId = launchResp?.notification_id ?? null;
             if (bulkRecord && tracker) {
               try {
-                await tracker.markLaunched(bulkRecord.bulk_id);
+                await tracker.markLaunched(bulkRecord.bulk_id, notificationId);
               } catch (e) {
                 ctx?.logger?.warn?.(`enrich_titles: tracker.markLaunched failed: ${e?.message ?? e}`);
                 return {
@@ -17189,8 +18005,9 @@ var init_enrich_titles = __esm({
               bulk_id: bulkRecord?.bulk_id,
               launched_at: bulkRecord?.launched_at,
               durability: bulkRecord?.durability,
-              message: bulkRecord ? "Enrichment job launched. Backend has no server-side bulk_id yet; MCP minted a client-side bulk_id (persisted to disk by default) so you can poll via leadbay_bulk_enrich_status." : "Enrichment job launched. No bulk_id tracker configured \u2014 poll leadbay_get_contacts per lead after ~60s; contact.enrichment.done flips to true.",
-              next_action: bulkRecord ? "Call leadbay_bulk_enrich_status({bulk_id}) after ~60s; pass include_contacts=true for the final read." : "Wait ~60s, then call leadbay_research_lead_by_id or leadbay_get_contacts on the leads you care about."
+              notification_id: notificationId,
+              message: notificationId ? "Enrichment job launched. The MCP is now listening for the backend notification \u2014 when enrichment finishes, a `_meta.notifications` entry will surface on your next tool response (also visible in `leadbay_account_status.notifications`)." : bulkRecord ? "Enrichment job launched. Backend did not return a notification id this time; poll via leadbay_bulk_enrich_status with the bulk_id." : "Enrichment job launched. No bulk_id tracker configured \u2014 poll leadbay_get_contacts per lead after ~60s; contact.enrichment.done flips to true.",
+              next_action: notificationId ? "Wait for the next `_meta.notifications` entry (typically <2 min for a small batch). If you want progress sooner, call leadbay_bulk_enrich_status({bulk_id})." : bulkRecord ? "Call leadbay_bulk_enrich_status({bulk_id}) after ~60s; pass include_contacts=true for the final read." : "Wait ~60s, then call leadbay_research_lead_by_id or leadbay_get_contacts on the leads you care about."
             };
           } finally {
             try {
@@ -17208,6 +18025,14 @@ var init_enrich_titles = __esm({
 });
 
 // ../core/dist/composite/bulk-enrich-status.js
+async function readNotification2(client, notificationId) {
+  try {
+    const page = await client.listNotifications({ archived: false, count: 50 });
+    return page.items.find((n) => n.id === notificationId) ?? null;
+  } catch {
+    return null;
+  }
+}
 async function pMap(items, fn, concurrency) {
   const out = new Array(items.length);
   let next = 0;
@@ -17379,6 +18204,53 @@ var init_bulk_enrich_status = __esm({
             launched_at: record.launched_at
           };
         }
+        const notifId = record.notification_id ?? null;
+        if (notifId) {
+          const n = await readNotification2(client, notifId);
+          if (n && n.bulk_progress) {
+            const bp = n.bulk_progress;
+            const inProgress = n.in_progress;
+            let leads2 = [];
+            if (!inProgress && includeContacts) {
+              leads2 = await pMap(record.lead_ids, async (leadId) => {
+                try {
+                  const out = await getContacts.execute(client, { leadId });
+                  const contacts = Array.isArray(out?.contacts) ? out.contacts : [];
+                  return { lead_id: leadId, contacts };
+                } catch {
+                  return { lead_id: leadId };
+                }
+              }, STATUS_FETCH_CONCURRENCY);
+            } else {
+              leads2 = record.lead_ids.map((id) => ({ lead_id: id }));
+            }
+            ctx?.logger?.info?.(`bulk.status_checked_via_notification bulk_id=${record.bulk_id} notification_id=${notifId} done=${bp.success_count}/${bp.total_count} in_progress=${inProgress} wall_ms=${Date.now() - startMs}`);
+            return {
+              bulk_id: record.bulk_id,
+              notification_id: notifId,
+              launched_at: record.launched_at,
+              status: record.status,
+              durability: record.durability,
+              titles: record.titles,
+              email: record.email,
+              phone: record.phone,
+              lens_id: record.lens_id,
+              leads: leads2,
+              overall_progress: {
+                done: bp.success_count + bp.failure_count + bp.quota_hit_count,
+                total: bp.total_count,
+                done_ratio: bp.total_count === 0 ? 0 : (bp.success_count + bp.failure_count + bp.quota_hit_count) / bp.total_count
+              },
+              bulk_progress: bp,
+              in_progress: inProgress,
+              all_done: !inProgress,
+              ...bp.quota_hit_count > 0 ? {
+                quota_hit_hint: "Some contacts could not be enriched because the AI-credits quota was hit. Top up via leadbay_create_topup_link or wait for the window reset."
+              } : {}
+            };
+          }
+          ctx?.logger?.info?.(`bulk_enrich_status: notification ${notifId} not yet visible; falling back to per-lead fan-out`);
+        }
         let doneSoFar = 0;
         const totalLeads = record.lead_ids.length;
         const results = await pMap(record.lead_ids, async (leadId) => {
@@ -17465,6 +18337,8 @@ var init_bulk_enrich_status = __esm({
 
 // ../core/dist/composite/adjust-audience.js
 function tokens(s) {
+  if (!s)
+    return [];
   return s.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
 }
 function bestMatches(text, taxonomy) {
@@ -17478,11 +18352,11 @@ function bestMatches(text, taxonomy) {
       if (have.has(t))
         overlap += 1;
     const score = overlap / Math.max(want.size, 1);
-    return { id: s.id, name: s.name, score };
+    return { id: s.id, name: s.name ?? "", score };
   }).filter((m) => m.score > 0).sort((a, b) => b.score - a.score);
   return ranked.slice(0, 5);
 }
-async function resolveSectors(client, texts) {
+async function resolveSectors(client, texts, ctx) {
   const looksLikeId2 = (s) => /^\d+$/.test(s);
   const direct = texts.filter(looksLikeId2);
   const free = texts.filter((s) => !looksLikeId2(s));
@@ -17491,6 +18365,10 @@ async function resolveSectors(client, texts) {
   const me = await client.resolveMe().catch(() => null);
   const lang = me?.language ?? "en";
   const taxonomy = await client.request("GET", `/sectors/all?lang=${encodeURIComponent(lang)}&includeInvisible=false`);
+  const nullNames = taxonomy.filter((s) => !s.name).length;
+  if (nullNames > 0) {
+    ctx?.logger?.warn?.(`adjust_audience: /sectors/all returned ${nullNames}/${taxonomy.length} sector(s) with a null/missing name`);
+  }
   const resolved = [...direct];
   const ambiguities = [];
   for (const text of free) {
@@ -17503,6 +18381,22 @@ async function resolveSectors(client, texts) {
   }
   return { resolved, ambiguities };
 }
+async function resolveLensByName(client, name) {
+  const lenses = await client.request("GET", "/lenses");
+  const all = lenses.map((l) => ({ id: l.id, name: l.name }));
+  const needle = name.trim().toLowerCase();
+  const exact = all.filter((l) => (l.name ?? "").trim().toLowerCase() === needle);
+  if (exact.length === 1)
+    return { ok: true, id: exact[0].id };
+  if (exact.length > 1)
+    return { ok: false, reason: "ambiguous", matches: exact };
+  const partial = all.filter((l) => (l.name ?? "").toLowerCase().includes(needle));
+  if (partial.length === 1)
+    return { ok: true, id: partial[0].id };
+  if (partial.length > 1)
+    return { ok: false, reason: "ambiguous", matches: partial };
+  return { ok: false, reason: "not_found", lenses: all };
+}
 function mergeFilter(current, toAddSectors, toExcludeSectors, sizes) {
   const items = current?.lens_filter?.items ?? [];
   const item = items[0] ?? { criteria: [] };
@@ -17536,11 +18430,15 @@ function mergeFilter(current, toAddSectors, toExcludeSectors, sizes) {
     }
   }
   if (sizes && sizes.length > 0) {
+    const normalizedSizes = sizes.map((s) => ({
+      min: s.min ?? 0,
+      max: s.max ?? 1e6
+    }));
     const idx = criteria.findIndex((c) => c.type === "size");
     if (idx >= 0) {
-      criteria[idx] = { type: "size", is_excluded: false, sizes };
+      criteria[idx] = { type: "size", is_excluded: false, sizes: normalizedSizes };
     } else {
-      criteria.push({ type: "size", is_excluded: false, sizes });
+      criteria.push({ type: "size", is_excluded: false, sizes: normalizedSizes });
     }
   }
   return {
@@ -17548,6 +18446,9 @@ function mergeFilter(current, toAddSectors, toExcludeSectors, sizes) {
     locations: current.locations ?? { results: [], parents: [] }
   };
 }
+function filterWriteBody(filter) {
+  return { items: filter.lens_filter.items };
+}
 var adjustAudience;
 var init_adjust_audience = __esm({
   "../core/dist/composite/adjust-audience.js"() {
@@ -17594,6 +18495,10 @@ var init_adjust_audience = __esm({
             description: "Company size buckets, e.g. [{min:30,max:300}]"
           },
           lensId: { type: "number", description: "Lens id (escape hatch)" },
+          lensName: {
+            type: "string",
+            description: "Target a lens BY NAME (e.g. 'Joinery') instead of the active one. Resolved against your lenses \u2014 edit-only, does NOT switch your active lens. Unknown/ambiguous names are surfaced to pick from. Takes effect only when lensId is not given."
+          },
           save_for_org: {
             type: "boolean",
             description: "Admin only \u2014 propagate the change to the org-level lens for everyone (default false: per-user draft)"
@@ -17607,21 +18512,35 @@ var init_adjust_audience = __esm({
       },
       outputSchema: {
         type: "object",
-        description: "Two return shapes: 'ambiguous_sectors' when free-text sectors matched multiple candidates (agent re-calls with sector_ids), 'applied' on success.",
+        description: "Return shapes: 'applied' on success; 'ambiguous_sectors' when free-text sectors matched multiple candidates (re-call with sector_ids); 'lens_not_found' / 'ambiguous_lens' when a lensName didn't resolve to exactly one lens (re-call with lensId or an exact lensName).",
         properties: {
           status: {
             type: "string",
-            description: "'ambiguous_sectors' or 'applied'."
+            description: "'applied', 'ambiguous_sectors', 'lens_not_found', or 'ambiguous_lens'."
           },
           sector_ambiguities: {
             type: "array",
             description: "Per ambiguous text: {sector_text, matches:[{id, name, score}]}. Agent picks an id and re-calls.",
             items: { type: "object" }
           },
+          lenses: {
+            type: "array",
+            description: "On 'lens_not_found': the user's lenses [{id, name}] to pick from.",
+            items: { type: "object" }
+          },
+          matches: {
+            type: "array",
+            description: "On 'ambiguous_lens': the lenses [{id, name}] the name matched.",
+            items: { type: "object" }
+          },
+          lens_query: {
+            type: "string",
+            description: "On 'lens_not_found' / 'ambiguous_lens': the lensName the user asked for."
+          },
           message: { type: "string" },
           lens_used: {
             type: "object",
-            description: "Resolved lens metadata: {id, name, was_draft, was_new, save_for_org}."
+            description: "Resolved lens metadata: {id, name, was_draft, was_new, active_lens_changed, save_for_org}."
           },
           filter_applied: {
             type: "object",
@@ -17634,28 +18553,63 @@ var init_adjust_audience = __esm({
       execute: async (client, params, ctx) => {
         const me = await client.resolveMe();
         const isAdmin = me.admin === true;
-        const startingLensId = params.lensId ?? me.last_requested_lens ?? await client.resolveDefaultLens();
+        let namedLensId;
+        if (params.lensId == null && params.lensName != null && params.lensName.trim() !== "") {
+          const res = await resolveLensByName(client, params.lensName);
+          if (!res.ok && res.reason === "not_found") {
+            return {
+              status: "lens_not_found",
+              lens_query: params.lensName,
+              lenses: res.lenses,
+              message: `No lens named "${params.lensName}". Pick one of the listed lenses (pass lensId or an exact lensName), or create it first.`
+            };
+          }
+          if (!res.ok && res.reason === "ambiguous") {
+            return {
+              status: "ambiguous_lens",
+              lens_query: params.lensName,
+              matches: res.matches,
+              message: `"${params.lensName}" matched multiple lenses. Re-call with the exact lensName or the lensId of the one you mean.`
+            };
+          }
+          if (res.ok)
+            namedLensId = res.id;
+        }
+        const startingLensId = params.lensId ?? namedLensId ?? me.last_requested_lens ?? await client.resolveDefaultLens();
+        const isNamedEdit = namedLensId != null && params.lensId == null;
         const includeTexts = [
           ...params.sectors ?? [],
           ...params.sector_ids ?? []
         ];
         const excludeTexts = params.exclude_sectors ?? [];
-        const includeRes = await resolveSectors(client, includeTexts);
-        const excludeRes = await resolveSectors(client, excludeTexts);
+        const includeRes = await resolveSectors(client, includeTexts, ctx);
+        const excludeRes = await resolveSectors(client, excludeTexts, ctx);
         const ambiguities = [
           ...includeRes.ambiguities,
           ...excludeRes.ambiguities
         ];
         if (ambiguities.length > 0) {
+          const noMatch = ambiguities.filter((a) => a.matches.length === 0);
+          const multi = ambiguities.filter((a) => a.matches.length > 0);
+          const parts = [];
+          if (noMatch.length > 0) {
+            const names = noMatch.map((a) => `"${a.sector_text}"`).join(", ");
+            parts.push(`Couldn't find a sector matching ${names}. Ask the user to rephrase or pick a known sector, then re-call with sector_ids=...`);
+          }
+          if (multi.length > 0) {
+            const names = multi.map((a) => `"${a.sector_text}"`).join(", ");
+            parts.push(`${names} matched multiple sectors. Pick from the matches and re-call with sector_ids=...`);
+          }
           return {
             status: "ambiguous_sectors",
             sector_ambiguities: ambiguities,
-            message: "One or more sector names matched multiple sectors. Pick from the matches and re-call with sector_ids=..."
+            message: parts.join(" ")
           };
         }
         const lens = await client.request("GET", `/lenses/${startingLensId}`);
         const currentFilter = await client.request("GET", `/lenses/${startingLensId}/filter`);
         const merged = mergeFilter(currentFilter, includeRes.resolved, excludeRes.resolved, params.sizes);
+        const mergedBody = filterWriteBody(merged);
         const isDefault = lens.is_default || lens.default;
         const isUserLevel = lens.user_id != null;
         const isOrgLevel = !isUserLevel && !isDefault;
@@ -17664,24 +18618,28 @@ var init_adjust_audience = __esm({
         let wasNew = false;
         if (isDefault) {
           const name = params.newLensName ?? `Custom audience \u2014 ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}`;
-          const newLens = await client.request("POST", "/lenses", {
-            base: startingLensId,
+          const newLens2 = await client.request("POST", "/lenses", {
+            base: String(startingLensId),
             name
           });
-          targetLensId = newLens.id;
+          targetLensId = newLens2.id;
           wasNew = true;
-          await client.requestVoid("POST", `/lenses/${targetLensId}/filter`, merged);
-          await client.requestVoid("POST", `/lenses/${targetLensId}/update_last_requested`);
+          await client.requestVoid("POST", `/lenses/${targetLensId}/filter`, mergedBody);
+          if (!isNamedEdit) {
+            await client.requestVoid("POST", `/lenses/${targetLensId}/update_last_requested`);
+          }
         } else if (isUserLevel) {
           try {
-            await client.requestVoid("POST", `/lenses/${startingLensId}/filter`, merged);
+            await client.requestVoid("POST", `/lenses/${startingLensId}/filter`, mergedBody);
           } catch (err) {
             if (err?.code === "FORBIDDEN") {
               wasDraft = true;
               const draft = await client.request("POST", `/lenses/${startingLensId}/draft`);
               targetLensId = draft.id;
-              await client.requestVoid("POST", `/lenses/${targetLensId}/filter`, merged);
-              await client.requestVoid("POST", `/lenses/${targetLensId}/update_last_requested`);
+              await client.requestVoid("POST", `/lenses/${targetLensId}/filter`, mergedBody);
+              if (!isNamedEdit) {
+                await client.requestVoid("POST", `/lenses/${targetLensId}/update_last_requested`);
+              }
             } else {
               throw err;
             }
@@ -17693,7 +18651,7 @@ var init_adjust_audience = __esm({
             const draft = await client.request("POST", `/lenses/${startingLensId}/draft`);
             targetLensId = draft.id;
             try {
-              await client.requestVoid("POST", `/lenses/${targetLensId}/filter`, merged);
+              await client.requestVoid("POST", `/lenses/${targetLensId}/filter`, mergedBody);
             } catch (err) {
               ctx?.logger?.warn?.(`adjust_audience: filter on draft ${targetLensId} failed: ${err?.message}`);
               try {
@@ -17709,17 +18667,21 @@ var init_adjust_audience = __esm({
               }
               throw err;
             }
-            await client.requestVoid("POST", `/lenses/${targetLensId}/update_last_requested`);
+            if (!isNamedEdit) {
+              await client.requestVoid("POST", `/lenses/${targetLensId}/update_last_requested`);
+            }
           } else {
             try {
-              await client.requestVoid("POST", `/lenses/${startingLensId}/filter`, merged);
+              await client.requestVoid("POST", `/lenses/${startingLensId}/filter`, mergedBody);
             } catch (err) {
               throw err;
             }
           }
         }
-        client.invalidateMe();
+        if (!isNamedEdit)
+          client.invalidateMe();
         client.invalidateDefaultLens();
+        const namedEditForkedMessage = isNamedEdit && (wasNew || wasDraft) ? ` Note: "${lens.name}" can't be edited in place, so the change was applied to a ${wasDraft ? "personal draft" : "new copy"} (id ${targetLensId}); your active lens is unchanged.` : "";
         return {
           status: "applied",
           lens_used: {
@@ -17727,10 +18689,11 @@ var init_adjust_audience = __esm({
             name: lens.name,
             was_draft: wasDraft,
             was_new: wasNew,
+            active_lens_changed: !isNamedEdit && (wasNew || wasDraft),
             save_for_org: params.save_for_org === true && isAdmin && isOrgLevel
           },
           filter_applied: merged,
-          message: wasDraft ? "Applied to your personal draft of the org lens (your view only)." : wasNew ? `Created a new user-level lens "${lens.name}" with the filter (you can rename via leadbay_update_lens).` : "Applied directly to the lens.",
+          message: (wasDraft ? "Applied to your personal draft of the org lens (your view only)." : wasNew ? `Created a new user-level lens "${lens.name}" with the filter (you can rename via leadbay_update_lens).` : "Applied directly to the lens.") + namedEditForkedMessage,
           _meta: { region: client.region }
         };
       }
@@ -18125,6 +19088,399 @@ var init_extend_lens = __esm({
   }
 });
 
+// ../core/dist/composite/my-lenses.js
+async function listWithActive(client) {
+  const lenses = await client.request("GET", "/lenses");
+  const me = await client.resolveMe().catch(() => null);
+  const activeFromMe = sid(me?.last_requested_lens);
+  const active_lens_id = activeFromMe ?? sid(lenses.find((l) => l.is_last_active)?.id) ?? null;
+  return {
+    active_lens_id,
+    lenses: lenses.map((l) => ({
+      id: sid(l.id),
+      name: l.name,
+      description: l.description ?? null,
+      is_active: sid(l.id) === active_lens_id,
+      is_default: l.is_default === true || l.default === true
+    }))
+  };
+}
+var sid, myLenses;
+var init_my_lenses = __esm({
+  "../core/dist/composite/my-lenses.js"() {
+    "use strict";
+    init_tool_descriptions_generated();
+    sid = (v) => v == null ? null : String(v);
+    myLenses = {
+      name: "leadbay_my_lenses",
+      annotations: {
+        title: "List, switch, edit, or delete your lenses",
+        // No args → pure read. The delete mode issues DELETE /lenses/:id (an
+        // irreversible side effect), so the tool is destructive — clients must
+        // treat it as approval-required, not auto-run. The delete path is itself
+        // confirm-gated (preview unless confirm:true). switch/edit are not
+        // idempotent across modes either, so don't claim idempotency.
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true
+      },
+      description: leadbay_my_lenses,
+      inputSchema: {
+        type: "object",
+        properties: {
+          switchToLensId: {
+            type: ["string", "number"],
+            description: "When set, switch the active lens to this id (must be one of the user's lenses), then return the refreshed list."
+          },
+          editLensId: {
+            type: ["string", "number"],
+            description: "When set, edit this lens's metadata \u2014 provide newName and/or newDescription. Must be one of the user's lenses."
+          },
+          newName: {
+            type: "string",
+            description: "New lens name (used with editLensId)."
+          },
+          newDescription: {
+            type: "string",
+            description: "New lens description (used with editLensId). Pass an empty string to clear it."
+          },
+          deleteLensId: {
+            type: ["string", "number"],
+            description: "When set, delete this lens. DESTRUCTIVE \u2014 returns a delete_preview unless confirm:true. Cannot delete the default lens."
+          },
+          confirm: {
+            type: "boolean",
+            description: "Required (=true) to actually delete. Without it, deleteLensId returns a preview to confirm with the user first."
+          }
+        },
+        additionalProperties: false
+      },
+      outputSchema: {
+        type: "object",
+        properties: {
+          status: {
+            type: "string",
+            description: "'listed', 'switched', 'already_active', 'edited', 'deleted', 'delete_preview' (confirm to proceed), 'cannot_delete_default', or 'not_found'."
+          },
+          switched: { type: "boolean", description: "True when this call changed the active lens." },
+          edited: { type: "boolean", description: "True when this call renamed/re-described a lens." },
+          deleted: { type: "boolean", description: "True when this call deleted a lens." },
+          will_delete: {
+            type: "object",
+            description: "On 'delete_preview': the lens that WILL be deleted {id, name}. Nothing removed yet."
+          },
+          active_lens_id: { type: ["string", "null"] },
+          lenses: {
+            type: "array",
+            description: "The user's lenses. Each: {id, name, description, is_active}.",
+            items: { type: "object" }
+          },
+          message: { type: "string" }
+        },
+        required: ["status", "lenses", "active_lens_id"]
+      },
+      execute: async (client, params) => {
+        if (params.deleteLensId != null) {
+          const targetId = sid(params.deleteLensId);
+          const before = await listWithActive(client);
+          const target = before.lenses.find((l) => l.id === targetId);
+          if (!target) {
+            return {
+              status: "not_found",
+              switched: false,
+              edited: false,
+              deleted: false,
+              active_lens_id: before.active_lens_id,
+              lenses: before.lenses,
+              message: `No lens with id ${targetId}. Pick one from the list.`
+            };
+          }
+          if (target.is_default) {
+            return {
+              status: "cannot_delete_default",
+              switched: false,
+              edited: false,
+              deleted: false,
+              active_lens_id: before.active_lens_id,
+              lenses: before.lenses,
+              message: `"${target.name}" is the default lens and can't be deleted.`
+            };
+          }
+          if (params.confirm !== true) {
+            return {
+              status: "delete_preview",
+              switched: false,
+              edited: false,
+              deleted: false,
+              active_lens_id: before.active_lens_id,
+              lenses: before.lenses,
+              will_delete: { id: target.id, name: target.name },
+              message: `About to delete "${target.name}". This can't be undone. Confirm with the user, then re-call with confirm:true.`
+            };
+          }
+          await client.requestVoid("DELETE", `/lenses/${targetId}`);
+          client.invalidateMe();
+          client.invalidateDefaultLens();
+          const after = await listWithActive(client);
+          return {
+            status: "deleted",
+            switched: false,
+            edited: false,
+            deleted: true,
+            active_lens_id: after.active_lens_id,
+            lenses: after.lenses,
+            message: `Deleted "${target.name}".`
+          };
+        }
+        if (params.editLensId != null) {
+          const targetId = sid(params.editLensId);
+          const before = await listWithActive(client);
+          const target = before.lenses.find((l) => l.id === targetId);
+          if (!target) {
+            return {
+              status: "not_found",
+              switched: false,
+              edited: false,
+              active_lens_id: before.active_lens_id,
+              lenses: before.lenses,
+              message: `No lens with id ${targetId}. Pick one from the list.`
+            };
+          }
+          const body = {};
+          const newName = params.newName?.trim();
+          if (newName)
+            body.name = newName;
+          if (params.newDescription !== void 0)
+            body.description = params.newDescription;
+          if (Object.keys(body).length === 0) {
+            return {
+              status: "not_found",
+              switched: false,
+              edited: false,
+              active_lens_id: before.active_lens_id,
+              lenses: before.lenses,
+              message: `Nothing to change on "${target.name}" \u2014 provide newName and/or newDescription.`
+            };
+          }
+          await client.requestVoid("POST", `/lenses/${targetId}`, body);
+          client.invalidateDefaultLens();
+          const changed = [
+            body.name != null ? `renamed to "${body.name}"` : null,
+            body.description !== void 0 ? "description updated" : null
+          ].filter(Boolean).join(", ");
+          const after = await listWithActive(client);
+          return {
+            status: "edited",
+            switched: false,
+            edited: true,
+            active_lens_id: after.active_lens_id,
+            lenses: after.lenses,
+            message: `"${target.name}" \u2014 ${changed}.`
+          };
+        }
+        if (params.switchToLensId != null) {
+          const targetId = sid(params.switchToLensId);
+          const before = await listWithActive(client);
+          const target = before.lenses.find((l) => l.id === targetId);
+          if (!target) {
+            return {
+              status: "not_found",
+              switched: false,
+              edited: false,
+              active_lens_id: before.active_lens_id,
+              lenses: before.lenses,
+              message: `No lens with id ${targetId}. Pick an id from the list.`
+            };
+          }
+          if (target.is_active) {
+            return {
+              status: "already_active",
+              switched: false,
+              edited: false,
+              active_lens_id: before.active_lens_id,
+              lenses: before.lenses,
+              message: `"${target.name}" is already your active lens.`
+            };
+          }
+          await client.requestVoid("POST", `/lenses/${targetId}/update_last_requested`);
+          client.invalidateMe();
+          client.invalidateDefaultLens();
+          const after = await listWithActive(client);
+          return {
+            status: "switched",
+            switched: true,
+            edited: false,
+            active_lens_id: after.active_lens_id,
+            lenses: after.lenses,
+            message: `Now showing "${target.name}".`
+          };
+        }
+        const { lenses, active_lens_id } = await listWithActive(client);
+        return { status: "listed", switched: false, edited: false, active_lens_id, lenses };
+      }
+    };
+  }
+});
+
+// ../core/dist/composite/new-lens.js
+var EMPTY_FILTER, newLens;
+var init_new_lens = __esm({
+  "../core/dist/composite/new-lens.js"() {
+    "use strict";
+    init_adjust_audience();
+    init_tool_descriptions_generated();
+    EMPTY_FILTER = {
+      lens_filter: { items: [{ criteria: [] }] },
+      locations: { results: [], parents: [] }
+    };
+    newLens = {
+      name: "leadbay_new_lens",
+      annotations: {
+        title: "Create a new named lens",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        // each call creates a distinct lens
+        openWorldHint: true
+      },
+      description: leadbay_new_lens,
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Display name for the new lens (required)." },
+          sectors: {
+            type: "array",
+            items: { type: "string" },
+            description: "Sectors to include \u2014 free text (auto-resolved) or ids."
+          },
+          exclude_sectors: {
+            type: "array",
+            items: { type: "string" },
+            description: "Sectors to exclude \u2014 free text or ids."
+          },
+          sizes: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: { min: { type: "number" }, max: { type: "number" } }
+            },
+            description: "Company size buckets, e.g. [{min:30,max:300}]."
+          },
+          base: {
+            type: "number",
+            description: "Lens id to clone from. Defaults to the active/default lens."
+          },
+          description: { type: "string", description: "Optional lens description." },
+          confirm: {
+            type: "boolean",
+            description: "Safety gate. Defaults to false \u2192 the tool returns a PREVIEW and creates nothing. Show the preview to the user, get their explicit go-ahead, then re-call the SAME args with confirm:true to actually create the lens."
+          }
+        },
+        required: ["name"],
+        additionalProperties: false
+      },
+      outputSchema: {
+        type: "object",
+        description: "'preview' (default, NOTHING created \u2014 confirm with the user then re-call with confirm:true); 'created' on success; 'ambiguous_sectors' when free-text sectors didn't resolve (re-call with sector ids \u2014 the lens was NOT created).",
+        properties: {
+          status: { type: "string", description: "'preview', 'created', 'ambiguous_sectors', or 'orphan_created' (filter write failed + cleanup failed)." },
+          will_create: {
+            type: "object",
+            description: "On 'preview': what WILL be created \u2014 {name, description, sectors, exclude_sectors, sizes}. Nothing has been written yet."
+          },
+          filter_preview: { type: "object", description: "On 'preview': the FilterPayload that would be applied." },
+          lens: {
+            type: "object",
+            description: "On 'created': the created lens {id, name}."
+          },
+          sector_ambiguities: {
+            type: "array",
+            description: "On 'ambiguous_sectors': per text {sector_text, matches:[{id,name,score}]}.",
+            items: { type: "object" }
+          },
+          filter_applied: { type: "object", description: "On 'created': the FilterPayload POSTed to the new lens." },
+          message: { type: "string" },
+          _meta: { type: "object" }
+        },
+        required: ["status"]
+      },
+      execute: async (client, params, ctx) => {
+        const includeRes = await resolveSectors(client, params.sectors ?? [], ctx);
+        const excludeRes = await resolveSectors(client, params.exclude_sectors ?? [], ctx);
+        const ambiguities = [...includeRes.ambiguities, ...excludeRes.ambiguities];
+        if (ambiguities.length > 0) {
+          const noMatch = ambiguities.filter((a) => a.matches.length === 0);
+          const multi = ambiguities.filter((a) => a.matches.length > 0);
+          const parts = [];
+          if (noMatch.length > 0) {
+            parts.push(`Couldn't find a sector matching ${noMatch.map((a) => `"${a.sector_text}"`).join(", ")}. Pick a known sector and re-call (lens not yet created).`);
+          }
+          if (multi.length > 0) {
+            parts.push(`${multi.map((a) => `"${a.sector_text}"`).join(", ")} matched multiple sectors. Pick from the matches and re-call with the sector id.`);
+          }
+          return {
+            status: "ambiguous_sectors",
+            sector_ambiguities: ambiguities,
+            message: parts.join(" ")
+          };
+        }
+        const merged = mergeFilter(EMPTY_FILTER, includeRes.resolved, excludeRes.resolved, params.sizes);
+        if (params.confirm !== true) {
+          return {
+            status: "preview",
+            will_create: {
+              name: params.name,
+              description: params.description ?? null,
+              sectors: includeRes.resolved,
+              exclude_sectors: excludeRes.resolved,
+              sizes: merged.lens_filter.items[0].criteria.find((c) => c.type === "size") ?? null
+            },
+            filter_preview: merged,
+            message: `About to create "${params.name}". Confirm with the user, then re-call with confirm:true.`,
+            _meta: { region: client.region }
+          };
+        }
+        const base = params.base ?? await client.resolveDefaultLens();
+        const created = await client.request("POST", "/lenses", {
+          base: String(base),
+          name: params.name,
+          description: params.description
+        });
+        const hasCriteria = merged.lens_filter.items[0].criteria.length > 0;
+        if (hasCriteria) {
+          try {
+            await client.requestVoid("POST", `/lenses/${created.id}/filter`, filterWriteBody(merged));
+          } catch (err) {
+            ctx?.logger?.warn?.(`new_lens: filter write on new lens ${created.id} failed: ${err?.message} \u2014 rolling back`);
+            try {
+              await client.requestVoid("DELETE", `/lenses/${created.id}`);
+            } catch {
+              client.invalidateDefaultLens();
+              return {
+                status: "orphan_created",
+                lens: { id: created.id, name: created.name },
+                message: `Created "${created.name}" but applying its filter failed, and cleanup also failed. The lens exists with no criteria \u2014 delete it via leadbay_my_lenses(deleteLensId:"${created.id}", confirm:true) or set its audience with leadbay_adjust_audience.`,
+                _meta: { region: client.region }
+              };
+            }
+            client.invalidateDefaultLens();
+            throw err;
+          }
+        }
+        client.invalidateDefaultLens();
+        return {
+          status: "created",
+          lens: { id: created.id, name: created.name },
+          filter_applied: merged,
+          message: `Created "${created.name}".`,
+          _meta: { region: client.region }
+        };
+      }
+    };
+  }
+});
+
 // ../core/dist/composite/answer-clarification.js
 var answerClarification;
 var init_answer_clarification = __esm({
@@ -18663,8 +20019,11 @@ __export(dist_exports, {
   InMemoryBulkStore: () => InMemoryBulkStore,
   LeadbayClient: () => LeadbayClient,
   LocalBulkStore: () => LocalBulkStore,
+  NotificationsInbox: () => NotificationsInbox,
+  NotificationsWsClient: () => NotificationsWsClient,
   REGIONS: () => REGIONS,
   accountStatus: () => accountStatus,
+  acknowledgeNotification: () => acknowledgeNotification,
   addLeadsToCampaign: () => addLeadsToCampaign,
   addNote: () => addNote,
   adjustAudience: () => adjustAudience,
@@ -18672,6 +20031,7 @@ __export(dist_exports, {
   agentMemoryRecall: () => agentMemoryRecall,
   agentMemoryReview: () => agentMemoryReview,
   agentMemoryTools: () => agentMemoryTools,
+  anchorIdFor: () => anchorIdFor,
   answerClarification: () => answerClarification,
   appendEntry: () => appendEntry,
   appendTombstone: () => appendTombstone,
@@ -18680,6 +20040,7 @@ __export(dist_exports, {
   bulkQualifyLeads: () => bulkQualifyLeads,
   campaignCallSheet: () => campaignCallSheet,
   campaignProgression: () => campaignProgression,
+  catchUpNotifications: () => catchUpNotifications,
   clearAgentMemoryCache: () => clearAgentMemoryCache,
   clearMockJournal: () => clearMockJournal,
   clearSelection: () => clearSelection,
@@ -18729,6 +20090,7 @@ __export(dist_exports, {
   importAndQualify: () => importAndQualify,
   importLeads: () => importLeads,
   importStatus: () => importStatus,
+  inferKind: () => inferKind,
   invalidateAgentMemoryCache: () => invalidateAgentMemoryCache,
   isAgentMemoryEnabled: () => isAgentMemoryEnabled,
   isValidBulkId: () => isValidBulkId,
@@ -18769,12 +20131,14 @@ __export(dist_exports, {
   resolveAgentMemorySummary: () => resolveAgentMemorySummary,
   resolveImportRows: () => resolveImportRows,
   resolveRegion: () => resolveRegion,
+  reviseHintFor: () => reviseHintFor,
   seedCandidates: () => seedCandidates,
   selectLeads: () => selectLeads,
   setActiveLens: () => setActiveLens,
   setEpilogueStatus: () => setEpilogueStatus,
   setPushback: () => setPushback,
   setUserPrompt: () => setUserPrompt,
+  toInboxEntry: () => toInboxEntry,
   tools: () => tools,
   tourPlan: () => tourPlan,
   updateLens: () => updateLens,
@@ -18789,6 +20153,7 @@ var init_dist = __esm({
     init_types();
     init_agent_memory();
     init_composite_file_names();
+    init_notifications();
     init_login();
     init_list_lenses();
     init_discover_leads();
@@ -18818,6 +20183,7 @@ var init_dist = __esm({
     init_agent_memory_recall();
     init_agent_memory_capture();
     init_agent_memory_review();
+    init_acknowledge_notification();
     init_select_leads();
     init_deselect_leads();
     init_clear_selection();
@@ -18867,6 +20233,8 @@ var init_dist = __esm({
     init_refine_prompt();
     init_seed_candidates();
     init_extend_lens();
+    init_my_lenses();
+    init_new_lens();
     init_answer_clarification();
     init_report_outreach();
     init_report_friction();
@@ -18886,7 +20254,6 @@ var init_dist = __esm({
       getQuota,
       getLensFilter,
       getLensScoring,
-      listSectors,
       listLocations,
       getUserPrompt,
       getClarification,
@@ -18957,6 +20324,11 @@ var init_dist = __esm({
       // it for discoverability; expose it always-on so agents can find custom fields
       // without needing LEADBAY_MCP_ADVANCED=1.
       listMappableFields,
+      // listSectors is granular-shaped but ALWAYS exposed: it's the sector taxonomy
+      // lookup the agent needs to STOP guessing sector names (and to feed
+      // leadbay_new_lens / leadbay_adjust_audience). Without it the agent can only
+      // probe sectors by trial-and-error or ask the user to read the web UI.
+      listSectors,
       // Billing / top-up tools — granular-shaped but ALWAYS exposed because
       // they're the canonical recovery path from a QUOTA_EXCEEDED wall. If
       // they were gated behind LEADBAY_MCP_ADVANCED=1 the agent would
@@ -18971,7 +20343,13 @@ var init_dist = __esm({
       // didn't deliver"). Does not mutate Leadbay state; emits a PostHog
       // event only. Companion to leadbay_report_outreach (which DOES write
       // to the backend and stays gated behind LEADBAY_MCP_WRITE).
-      reportFriction
+      reportFriction,
+      // Notification ack — ALWAYS exposed even though it POSTs to /seen.
+      // _meta.notifications surfaces terminal bulk-progress notifications on
+      // every tool response regardless of write gating; without ack the agent
+      // sees the same entries on every call forever. Pairing the surfacing
+      // channel with the clearing tool is non-optional.
+      acknowledgeNotification
     ];
     compositeWriteTools = [
       bulkQualifyLeads,
@@ -18999,7 +20377,16 @@ var init_dist = __esm({
       removeLeadsFromCampaign,
       // Lens extend — agent-driven on-demand fill (additive). Gated behind
       // LEADBAY_MCP_WRITE=1. Subject to per-org daily LENS_EXTRA_REFILL quota.
-      extendLens
+      extendLens,
+      // Lens list/switch — read-first (no args = pure list); a switchToLensId
+      // changes the active lens. In compositeWriteTools because the switch path
+      // mutates last_requested_lens, but it stays on the default surface
+      // (write is on by default since 0.3.0).
+      myLenses,
+      // Lens creation — make a brand-new named lens with sectors/sizes in one
+      // call. Default-surface so "create a lens called X for Y" works without
+      // the advanced gate.
+      newLens
     ];
     compositeTools = [
       ...compositeReadTools,
@@ -21310,6 +22697,22 @@ function buildServer(client, opts = {}) {
       });
     }
   };
+  const maybeAttachNotifications = (result) => {
+    const inbox = opts.notificationsInbox;
+    if (!inbox) return;
+    if (result === null || typeof result !== "object" || Array.isArray(result)) {
+      return;
+    }
+    const entries = inbox.list();
+    if (entries.length === 0) return;
+    const envelope = result;
+    const target = envelope.__markdown_envelope === true && envelope.structured !== null && typeof envelope.structured === "object" && !Array.isArray(envelope.structured) ? envelope.structured : envelope;
+    const existingMeta = target._meta && typeof target._meta === "object" && !Array.isArray(target._meta) ? target._meta : {};
+    target._meta = {
+      ...existingMeta,
+      notifications: entries
+    };
+  };
   const isLeadbayBusinessError = (err) => err != null && typeof err === "object" && err.error === true && typeof err.code === "string";
   const buildBusinessCtx = (toolName, envelope, triggered_by) => {
     const meta = envelope._meta ?? {};
@@ -21429,11 +22832,13 @@ function buildServer(client, opts = {}) {
       const result = await tool.execute(client, args, {
         logger: opts.logger,
         bulkTracker: opts.bulkTracker,
+        notificationsInbox: opts.notificationsInbox,
         signal: extra.signal,
         progress,
         elicit
       });
       maybeAttachUpdate(name, result);
+      maybeAttachNotifications(result);
       if (result && typeof result === "object" && result.error === true) {
         const envText = formatErrorForLLM(result);
         const envDur = Date.now() - callStart;
@@ -22871,7 +24276,7 @@ var OAUTH_BASE_URLS = {
     fr: "https://staging.api.leadbay.app"
   }
 };
-var VERSION = "0.17.2";
+var VERSION = "0.18.0";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 
@@ -23968,21 +25373,41 @@ async function main() {
       logger.warn?.(`update_check.unexpected ${err?.message ?? err}`);
     });
   }
+  const notificationsInbox = new NotificationsInbox();
+  let notificationsWs = null;
+  const WS_DISABLED = process.env.LEADBAY_NOTIFICATIONS_WS_DISABLED === "1" || authState !== "ok";
+  if (!WS_DISABLED) {
+    notificationsWs = new NotificationsWsClient({
+      client,
+      inbox: notificationsInbox,
+      logger
+    });
+    void notificationsWs.start().catch((err) => {
+      logger.warn?.(
+        `notifications.ws start_failed: ${err?.message ?? err}`
+      );
+    });
+  }
   const server = buildServer(client, {
     includeAdvanced,
     includeWrite,
     logger,
     bulkTracker,
+    notificationsInbox,
     version: VERSION,
     telemetry,
     updateStateStore
   });
   const transport = new StdioServerTransport();
   logger.info?.(
-    `Starting MCP server v${VERSION} (advanced=${includeAdvanced}, write=${includeWrite}, baseUrl=${client.baseUrl}, bulk_store=${bulkTracker.durability}, auth_state=${authState})`
+    `Starting MCP server v${VERSION} (advanced=${includeAdvanced}, write=${includeWrite}, baseUrl=${client.baseUrl}, bulk_store=${bulkTracker.durability}, notifications_ws=${WS_DISABLED ? "disabled" : "enabled"}, auth_state=${authState})`
   );
   await server.connect(transport);
   const shutdown = async (code) => {
+    try {
+      notificationsWs?.stop();
+    } catch {
+    }
     try {
       await telemetry.shutdown();
     } finally {