@leadbay/mcp 0.17.2 → 0.18.0

package/dist/http-server.js

@@ -1756,6 +1756,23 @@ var LeadbayClient = class {
     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) {
@@ -6187,6 +6204,8 @@ var COMPOSITE_FILE_TOOL_NAMES = /* @__PURE__ */ new Set([
   "leadbay_import_leads",
   "leadbay_import_status",
   "leadbay_list_campaigns",
+  "leadbay_my_lenses",
+  "leadbay_new_lens",
   "leadbay_prepare_outreach",
   "leadbay_pull_followups",
   "leadbay_pull_leads",
@@ -6203,6 +6222,9 @@ var COMPOSITE_FILE_TOOL_NAMES = /* @__PURE__ */ new Set([
   "leadbay_tour_plan"
 ]);
 
+// ../core/dist/notifications/inbox.js
+var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
+
 // ../core/dist/tool-descriptions.generated.js
 var leadbay_account_status = `## WHEN TO USE
 
@@ -6239,10 +6261,53 @@ 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.
 `;
+var 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\`.
+`;
 var leadbay_add_leads_to_campaign = `## WHEN TO USE
 
 Trigger phrases: "add leads to <name> campaign", "attach these to <campaign>", "put these in Q2 Push", "add to existing campaign".
@@ -6297,7 +6362,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\`.
 `;
-var 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).
+var 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.).
 
@@ -7511,6 +7606,258 @@ WHEN NOT TO USE: if a token is already preconfigured \u2014 you'll just overwrit
 
 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\`.
 `;
+var 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.
+`;
+var 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.
+`;
 var 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.
 
 Sibling of \`leadbay_create_topup_link\`. Use cases differ:
@@ -8143,7 +8490,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.
 `;
-var 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).
+var 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.
 
@@ -10838,9 +11211,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);
@@ -10848,7 +11235,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();
@@ -10904,7 +11291,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) {
@@ -10969,6 +11356,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,
@@ -11156,6 +11544,7 @@ var importLeads = {
         leads: [],
         not_imported,
         importIds: [],
+        notification_ids: [],
         region: client.region,
         dry_run: dryRun || void 0,
         _meta: client.lastMeta ?? {
@@ -11210,6 +11599,10 @@ var importLeads = {
         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,
@@ -11230,6 +11623,7 @@ var importLeads = {
     }
     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;
@@ -11241,6 +11635,9 @@ var importLeads = {
       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);
         }
@@ -11261,7 +11658,7 @@ var importLeads = {
         throw err;
       }
     }
-    return buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled);
+    return buildImportLeadsResult(client, prep, importIds, matched, notImported, dryRun, cancelled, notificationIds);
   }
 };
 async function runImportInBackground(client, prep, uploadedChunks, opts, ctx, handleId) {
@@ -11278,17 +11675,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,
@@ -11956,50 +12357,107 @@ var agentMemoryReview = {
   }
 };
 
-// ../core/dist/tools/select-leads.js
-var selectLeads = {
-  name: "leadbay_select_leads",
+// ../core/dist/tools/acknowledge-notification.js
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var acknowledgeNotification = {
+  name: "leadbay_acknowledge_notification",
   annotations: {
-    title: "Select leads",
+    title: "Acknowledge a Leadbay notification",
     readOnlyHint: false,
-    destructiveHint: true,
+    destructiveHint: false,
     idempotentHint: true,
     openWorldHint: true
   },
-  description: leadbay_select_leads,
-  optional: true,
+  description: leadbay_acknowledge_notification,
   write: true,
   inputSchema: {
     type: "object",
     properties: {
-      leadIds: {
-        type: "array",
-        items: { type: "string" },
-        description: "Lead UUIDs to add to selection (1-1000)",
-        minItems: 1,
-        maxItems: 1e3
+      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: ["leadIds"],
+    required: ["notification_id"],
     additionalProperties: false
   },
   outputSchema: {
     type: "object",
     properties: {
-      selected: {
-        type: "number",
-        description: "How many leadIds the call added to the selection (echoes input length)."
-      }
+      acknowledged: { type: "boolean" },
+      notification_id: { type: "string" },
+      action: { type: "string", enum: ["seen", "archive"] }
     },
-    required: ["selected"]
+    required: ["acknowledged", "notification_id", "action"]
   },
-  execute: async (client, params) => {
-    const qs = params.leadIds.map((id) => `leadIds=${encodeURIComponent(id)}`).join("&");
-    await client.requestVoid("POST", `/leads/selection/select?${qs}`);
-    return { selected: params.leadIds.length };
-  }
-};
-
+  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 = {
+  name: "leadbay_select_leads",
+  annotations: {
+    title: "Select leads",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_select_leads,
+  optional: true,
+  write: true,
+  inputSchema: {
+    type: "object",
+    properties: {
+      leadIds: {
+        type: "array",
+        items: { type: "string" },
+        description: "Lead UUIDs to add to selection (1-1000)",
+        minItems: 1,
+        maxItems: 1e3
+      }
+    },
+    required: ["leadIds"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      selected: {
+        type: "number",
+        description: "How many leadIds the call added to the selection (echoes input length)."
+      }
+    },
+    required: ["selected"]
+  },
+  execute: async (client, params) => {
+    const qs = params.leadIds.map((id) => `leadIds=${encodeURIComponent(id)}`).join("&");
+    await client.requestVoid("POST", `/leads/selection/select?${qs}`);
+    return { selected: params.leadIds.length };
+  }
+};
+
 // ../core/dist/tools/deselect-leads.js
 var deselectLeads = {
   name: "leadbay_deselect_leads",
@@ -12118,7 +12576,7 @@ var createLens = {
   },
   execute: async (client, params) => {
     const lens = await client.request("POST", "/lenses", {
-      base: params.base,
+      base: String(params.base),
       name: params.name,
       description: params.description
     });
@@ -15028,6 +15486,11 @@ var accountStatus = {
         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: {
@@ -15087,6 +15550,13 @@ var accountStatus = {
       // 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
       }
@@ -15100,6 +15570,33 @@ var DEFAULT_COUNT = 10;
 var MAX_COUNT = 25;
 var DEFAULT_PER_LEAD_BUDGET_MS = 9e4;
 var DEFAULT_TOTAL_BUDGET_MS2 = 5 * 6e4;
+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 bulkQualifyLeads = {
   name: "leadbay_bulk_qualify_leads",
   annotations: {
@@ -15267,69 +15764,50 @@ var bulkQualifyLeads = {
         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) {
@@ -16042,6 +16520,7 @@ var importAndQualify = {
           ...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 } : {},
@@ -16066,6 +16545,7 @@ var importAndQualify = {
         ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
         qualify_id: null,
         import_ids: queued.importIds,
+        notification_ids: queued.notification_ids ?? [],
         imported: [],
         not_imported: [],
         qualified: [],
@@ -16103,6 +16583,7 @@ var importAndQualify = {
         ...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: [],
@@ -16140,6 +16621,7 @@ var importAndQualify = {
         ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
         qualify_id: null,
         import_ids: importResult.importIds,
+        notification_ids: importResult.notification_ids ?? [],
         imported,
         not_imported,
         qualified: [],
@@ -16250,6 +16732,7 @@ var importAndQualify = {
       ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
       qualify_id: reservation.record.bulk_id,
       import_ids: importResult.importIds,
+      notification_ids: importResult.notification_ids ?? [],
       imported,
       not_imported,
       qualified,
@@ -16591,6 +17074,14 @@ var importStatus = {
 };
 
 // ../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 = {
   name: "leadbay_qualify_status",
   annotations: {
@@ -16745,6 +17236,16 @@ var qualifyStatus = {
       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,
@@ -16756,6 +17257,9 @@ var qualifyStatus = {
       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,
@@ -16768,6 +17272,9 @@ var qualifyStatus = {
       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;
   }
 };
@@ -17038,6 +17545,7 @@ var enrichTitles = {
               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,
@@ -17053,8 +17561,9 @@ var enrichTitles = {
           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) {
@@ -17078,9 +17587,10 @@ var enrichTitles = {
           }
           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 {
@@ -17108,8 +17618,9 @@ var enrichTitles = {
           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 {
@@ -17125,6 +17636,14 @@ var enrichTitles = {
 };
 
 // ../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;
+  }
+}
 var STATUS_FETCH_CONCURRENCY = 5;
 async function pMap(items, fn, concurrency) {
   const out = new Array(items.length);
@@ -17289,6 +17808,53 @@ var bulkEnrichStatus = {
         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) => {
@@ -17373,6 +17939,8 @@ var bulkEnrichStatus = {
 
 // ../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) {
@@ -17386,11 +17954,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));
@@ -17399,6 +17967,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) {
@@ -17411,6 +17983,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: [] };
@@ -17444,11 +18032,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 {
@@ -17456,6 +18048,9 @@ function mergeFilter(current, toAddSectors, toExcludeSectors, sizes) {
     locations: current.locations ?? { results: [], parents: [] }
   };
 }
+function filterWriteBody(filter) {
+  return { items: filter.lens_filter.items };
+}
 var adjustAudience = {
   name: "leadbay_adjust_audience",
   annotations: {
@@ -17497,6 +18092,10 @@ var adjustAudience = {
         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)"
@@ -17510,21 +18109,35 @@ var adjustAudience = {
   },
   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",
@@ -17537,28 +18150,63 @@ var adjustAudience = {
   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;
@@ -17567,24 +18215,28 @@ var adjustAudience = {
     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;
         }
@@ -17596,7 +18248,7 @@ var adjustAudience = {
         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 {
@@ -17612,17 +18264,21 @@ var adjustAudience = {
           }
           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: {
@@ -17630,10 +18286,11 @@ var adjustAudience = {
         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 }
     };
   }
@@ -18005,6 +18662,384 @@ var extendLens = {
   }
 };
 
+// ../core/dist/composite/my-lenses.js
+var sid = (v) => v == null ? null : String(v);
+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 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 = {
+  lens_filter: { items: [{ criteria: [] }] },
+  locations: { results: [], parents: [] }
+};
+var 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 = {
   name: "leadbay_answer_clarification",
@@ -18524,7 +19559,6 @@ var granularReadTools = [
   getQuota,
   getLensFilter,
   getLensScoring,
-  listSectors,
   listLocations,
   getUserPrompt,
   getClarification,
@@ -18595,6 +19629,11 @@ var compositeReadTools = [
   // 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
@@ -18609,7 +19648,13 @@ var compositeReadTools = [
   // 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
 ];
 var compositeWriteTools = [
   bulkQualifyLeads,
@@ -18637,7 +19682,16 @@ var compositeWriteTools = [
   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
 ];
 var compositeTools = [
   ...compositeReadTools,
@@ -19419,6 +20473,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 ?? {};
@@ -19538,11 +20608,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;
@@ -19837,7 +20909,7 @@ function parseWriteEnv(env = process.env) {
 }
 
 // src/http-server.ts
-var VERSION = true ? "0.17.2" : "0.0.0-dev";
+var VERSION = true ? "0.18.0" : "0.0.0-dev";
 var PORT = Number(process.env.PORT ?? 8080);
 var HOST = process.env.HOST ?? "0.0.0.0";
 var sseSessions = /* @__PURE__ */ new Map();