@leadbay/mcp 0.17.3 → 0.18.1

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) {
@@ -6171,6 +6188,7 @@ function makeAgentMemoryTombstone(input) {
 
 // ../core/dist/composite/_composite-file-names.js
 var COMPOSITE_FILE_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "leadbay_account_history",
   "leadbay_account_status",
   "leadbay_add_leads_to_campaign",
   "leadbay_adjust_audience",
@@ -6205,7 +6223,156 @@ 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_history = `## WHEN TO USE
+
+Trigger phrases: "what's the history on this account", "why should I revisit this account", "summarize everything we've done with <Company>", "has this account gone cold", "give me the back-story on lead <UUID>".
+
+**Memory:** recall + capture via \`leadbay_agent_memory_*\` tools.
+
+Do NOT use for: "live signals only, no history" \u2192 \`leadbay_research_lead_by_id\`; "which accounts should I follow up with" \u2192 \`leadbay_pull_followups\`.
+
+Prefer when: user wants ONE account's full back-story \u2014 notes + past activity + current signals together; pass \`leadId\`
+
+Examples that SHOULD invoke this tool:
+- "What's the full history on this account \u2014 why did it resurface?"
+- "Summarize everything we've logged on that lead and whether it's worth another visit."
+
+Examples that should NOT invoke this tool (sound similar, route elsewhere):
+- "Tell me the current AI take on this lead."
+- "Which accounts should I follow up with this week?"
+
+## RENDER (quick)
+
+Single resurfaced-account card. Lead the card with the current signal/trigger
+line (from \`signals\`), then a "History" section: notes digest
+(chronological) + the activity timeline. Close with a one-line "why revisit
+now" synthesis and a suggested outreach angle tied to the freshest signal.
+
+---
+
+Give me one account's full back-story in a single call. This is the tool for
+the **reprioritize-a-neglected-account** workflow: the user has an account
+that was contacted or quoted long ago and wants to know, in one shot, whether
+a fresh signal makes it worth another visit.
+
+It bundles three reads on one \`leadId\`:
+
+1. **Current state** \u2014 passed through verbatim from \`leadbay_research_lead_by_id\`:
+   \`signals\` (web-research signals with hot flags + sources), \`firmographics\`,
+   \`qualification\` answers, \`contacts\`, and \`engagement\` counts. This is the
+   "why is this account hot NOW" layer.
+2. **\`notes\`** \u2014 the FULL list of notes logged on the record (note body +
+   \`created_at\`), chronological. \`leadbay_research_lead_by_id\` only returns a
+   \`notes_count\`; this tool returns the bodies so you can summarize the
+   historical context.
+3. **\`activities\`** \u2014 the interaction timeline (\`{type, date}\` entries, newest
+   first) plus the total count. Drives the "no contact in N months" judgement.
+
+\`notes\` and \`activities\` **degrade gracefully**: if either read fails the card
+still returns with that section empty (\`notes: []\` /
+\`activities.total: 0\`). The current-state block is load-bearing \u2014 if research
+itself errors the whole call fails, because there is nothing to narrate.
+
+Params: \`leadId\` (required UUID) and \`activityCount\` (optional, default 50,
+max 100).
+
+Companion tools: **leadbay_research_lead_by_id** when the user only wants the
+live AI take with no history; **leadbay_pull_followups** when the user wants a
+LIST of accounts to act on rather than one account's deep history.
+
+## RENDERING \u2014 single-record research card, mode-adaptive
+
+Present as a single-record card, not a table. This tool gets invoked in two distinct user contexts \u2014 detect which and adapt the body density accordingly.
+
+**MODE A \u2014 Discovery.** The user is evaluating whether to pursue this company as a target. Signals: "tell me about", "what do they do", "is this a fit", "research [company]", arrival via a click-through from \`leadbay_pull_leads\`, no prior outreach context in the conversation. Next step is usually qualify, deep-dive via \`leadbay_research_lead_by_id\`, or decide whether to start outreach.
+
+**MODE B \u2014 Contact preparation.** The user is about to call or email someone at this company and needs the talking points. Signals: "I'm calling them", "draft an email", "before my call", "outreach prep", "what should I say", or the conversation has already touched on a specific contact. Next step is usually \`leadbay_prepare_outreach\`.
+
+Default to MODE A when uncertain. Always offer the cross-mode pivot at the end so the user can redirect if you guessed wrong.
+
+### Common structure (both modes)
+
+- **Header** (H4 or H5): \`<10-segment score bar>\` \`[Company name](website)\`. Use the score-bar algorithm; the bar lives in a single inline-code span. Prefix \`https://\` to website if it's a bare hostname.
+- **Pill row** (immediately below the header): short location \xB7 compact size \xB7 social pill chips iterated over \`social_urls\` (each non-null platform becomes \`[<platform-label>](<url>)\`) \xB7 \`[website-domain](website)\` \xB7 \`\u260E phone\` when \`phone_numbers[]\` is non-empty (use the first number). All \` \xB7 \`-separated.
+- **Blurb**: render \`description\` (preferred) or \`short_description\` as a single blockquoted paragraph.
+- **Staleness line**: italic, \`"Researched <relative time>"\` from \`web_insights_fetched_at\`. Use \`"today"\` / \`"yesterday"\` / \`"N days ago"\` up to 30 days, then absolute date. Prefix with \`\u26A0\` if older than 30 days.
+- **Contacts table** (always at the bottom):
+  \`\`\`
+  |   | Name | Title | LinkedIn |
+  \`\`\`
+  Markers in column 1:
+  - \`\u2605\` \u2014 \`recommended_contact\` match.
+  - \`\u{1F48E}\` \u2014 name fuzzy-matches a \`hot: true\` entry in \`web_insights\` key_people. (Use \`\u{1F48E}\`, not \`\u{1F525}\`, to avoid glyph collision with the follow-up status badge.)
+  Sort \`\u2605\` first, then \`\u{1F48E}\`-only rows, then API order. Link the name via \`linkedin_page\` first; fall back to LinkedIn people-search with \`<First>+<Last>+<Company>\`. Append \`\xB0\` only when the fallback is in use AND \`social_presence.linkedin == false\`. Cap to 6 rows; if \`contacts_count > shown\`, end with \`"+N more \u2014 ask to see the full list"\`.
+
+### MODE A body (Discovery, fuller, scannable)
+
+Render each non-empty \`web_insights\` section as H5 with the emoji + label intact. Section order: \`\u{1F3E2} company profile\` \u2192 \`\u{1F4C8} business signals\` \u2192 \`\u{1F4A1} prospecting clues\` \u2192 \`\u{1F9E9} strategic positioning\` \u2192 \`\u{1F50E} technologies & innovation\`. Inside each, bullet 3\u20135 items. Sort \`hot: true\` items first. **Bold** the description text of hot items; leave cold items plain. Render \`source\` as \`[source](url)\` at the end; include \`date\` when present. Omit empty sections. Skip \`\u{1F517} social links\` (already in the pill row) and \`\u{1F464} key people\` (already in the contacts table).
+
+### MODE B body (Contact preparation, tighter)
+
+Render exactly two H5 sections:
+
+##### \u{1F3AF} Conversation hooks
+
+Distill the 3 most recent / most hot signals from \`\u{1F4C8} business signals\` and \`\u{1F4A1} prospecting clues\` into one-sentence talking points in salesperson voice. Strip the academic framing. Cite the source inline.
+
+##### \u{1F464} About the person *(only when recommended_contact is non-empty)*
+
+2-line summary: their title + any context from \`web_insights\` key_people. If they appear in a hot signal ("X appointed CEO"), surface that prominently.
+
+Skip \u{1F3E2} profile, \u{1F9E9} strategic positioning, \u{1F50E} technologies in MODE B \u2014 context the user doesn't need for the next 30 seconds.
+
+If \`qualification[]\` is non-empty, append one collapsed line: \`"Qualification: N questions answered, avg boost X"\` and offer to expand in NEXT STEPS.
+
+**Hide:** \`id\`, \`lead.id\`, \`contact.id\`, \`lead.location.pos\`, \`web_fetch_in_progress\`, \`enrichment_in_progress\`, \`recommended_contact_title\` (duplicates \`recommended_contact.job_title\`), empty arrays, fields whose value is the string \`"null"\`, \`contact.source\` (internal), insights whose \`source\` is empty.
+
+**Legend (print once below the card):** \`\` \`\u25B0\` firmographic \xB7 \`\u2756\` AI booster \xB7 \`\u25B1\` unfilled \xB7 \u2605 recommended \xB7 \u{1F48E} hot in web_insights \xB7 \xB0 = no company LinkedIn (fallback link only) \`\`
+
+## Linking a contact's name
+
+**MANDATORY: every contact name in your output \u2014 table cells, prose, headers, "Reach <Name>" callouts \u2014 MUST be wrapped in markdown link syntax \`[Name](URL)\`. Never render a contact name as bare text. A plain-text name is a broken contact card; the underlined name is the user's primary affordance for "take me to this person's profile". No "no URL available" exception \u2014 the search URL below is always constructable from name + company.**
+
+URL priority (first applicable wins):
+
+1. **Real profile** \u2014 \`contact.linkedin_page\` when it's a string starting with \`https://\` (the MCP coerces the legacy literal \`"null"\` string to real null before you see it).
+2. **Constructed people-search** \u2014 \`https://www.linkedin.com/search/results/people/?keywords=<First>+<Last>+<Company>\`. URL-encode params. Strip Inc / LLC / Corp / Ltd / GmbH / Co / S.A. / S.L. / PLC / AG / SAS / SARL suffixes from the company. Append a trailing \` \xB0\` to the rendered name ONLY when this fallback is in use AND \`social_presence.linkedin == false\`. Never append \`\xB0\` when a real \`linkedin_page\` was used.
+
+Never link a person's name to the company's LinkedIn page (and vice versa) \u2014 the two surfaces are different and conflating them quietly degrades the workflow.
+
+## Linking the company
+
+Use the lead's \`website\` as the company-name link target \u2014 prefix \`https://\` if the value is a bare hostname. (The MCP does NOT synthesize a Leadbay-app deep-link URL; the team has not standardized one. Linking to \`website\` is always real data.)
+
+When the response carries \`social_urls\` (the post-fix multi-platform URL block on rich-lead responses), render every non-null platform as a pill chip in the company-info row. Iterate over \`social_urls\`'s keys \u2014 never hardcode a fixed list \u2014 and emit each as \`[<platform-label>](<url>)\`. Skip platforms whose URL is null.
+
+\`social_presence\` carries booleans for the same 6 platforms (crunchbase, facebook, instagram, linkedin, tiktok, twitter) \u2014 useful when you only care that the company has a profile somewhere. Use it as the \xB0-flag signal in the contact people-search fallback (see linking/contact-linkedin).
+
+
+
+### RENDERING \u2014 the history layer (on top of the card above)
+
+After the research card, add a **History** section so the user sees why this
+account resurfaced:
+
+- **##### \u{1F5D2} Notes** \u2014 render \`notes\` chronologically (oldest \u2192 newest). Each
+  as a bullet: \`**<relative date from created_at>** \u2014 <note body>\`. Cap at 8;
+  if \`_meta.notes_count > shown\`, end with \`"+N more notes"\`. Omit the section
+  entirely when \`notes\` is empty.
+- **##### \u{1F553} Timeline** \u2014 render \`activities.activities\` newest-first as a
+  compact bullet list: \`<relative date> \xB7 <type>\`. Cap at 10; if
+  \`activities.total > shown\`, end with \`"+N earlier"\`. Omit when empty.
+- **##### \u21BB Why revisit now** \u2014 one or two sentences synthesizing the freshest
+  HOT signal from \`signals\` against the gap in \`activities\` (e.g. "Won a public
+  tender last month; no logged contact since the 2024 quote \u2014 strong re-open
+  angle"). Then one suggested outreach angle tied to that signal. This
+  synthesis is the payload of the whole tool \u2014 always include it when there is
+  at least one hot signal.
+`;
 var leadbay_account_status = `## WHEN TO USE
 
 Trigger phrases: "what's my account status", "how much quota do I have", "what lens am I on", "I topped up / I bought credits / I added credits".
@@ -6226,10 +6393,13 @@ Examples that should NOT invoke this tool (sound similar, route elsewhere):
 
 ## RENDER (quick)
 
-Compact markdown: org name + admin badge on line 1; active lens on
-line 2; per-window quota usage as \`(used / cap)\` chips for
-llm_completion \xB7 ai_rescore \xB7 web_fetch. Surface regeneration flag
-prominently if mid-regen.
+If \`quota_error\` is set the call FAILED \u2014 quota unreadable; on 401/403 tell
+the user to reconnect. NEVER report zero usage or "no limits". Else render
+\`quota.org.resources\` (usage lives there, NOT at quota.resources) as a
+table, never prose: rows = resources (llm_completion \xB7 ai_rescore \xB7
+web_fetch + others), cols = Daily/Weekly/Monthly used \`count\` (= amount
+USED; no cap field, \`plan\` may be null \u2014 never invent a denominator).
+Empty = a 0 table, not "unlimited". Above: org + admin, lens.
 
 ---
 
@@ -6241,10 +6411,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".
@@ -6373,6 +6586,10 @@ var leadbay_bulk_enrich_status = `Check status + per-lead contacts for a bulk en
 WHEN TO USE: poll this after leadbay_enrich_titles returns a \`bulk_id\`. Default \`include_contacts=false\` for cheap status polls; set \`include_contacts=true\` once \`all_done\` flips for the final read.
 
 WHEN NOT TO USE: as a substitute for leadbay_research_lead_by_id \u2014 that already includes enriched contacts for a single lead.
+
+## CREDIT COST \u2014 show the balance, discreetly
+
+Once \`all_done\` is true the result carries \`credits_remaining\` (the post-spend AI-credit balance). Don't make a fuss \u2014 no sentence, no callout. Just append ONE small italic line in parentheses at the very END of your reply: \`_(N credits remaining)_\`. If \`credits_remaining\` is null (billing unavailable), omit the line \u2014 don't print 0. Do NOT report a "credits used" figure for this run: the per-contact cost can't be scoped to this specific enrichment (a lead's contact list mixes in earlier runs), so any "X used" number would be misleading.
 `;
 var leadbay_bulk_qualify_leads = `Pick the next N unqualified leads in the active lens and qualify them (run AI rescore + web fetch). Pass \`wait_for_completion:false\` to return quickly with \`{status:'running', qualify_id}\`; poll leadbay_qualify_status with that id. With \`wait_for_completion\` omitted/true, the legacy behavior polls until the answers are populated or a budget is exhausted. Already-qualified leads (those with a non-null \`ai_agent_lead_score\`) are silently no-ops on the backend, so this composite paginates past them to find fresh candidates. On 429 mid-fanout, stops launching but keeps polling already-launched leads.
 
@@ -6837,6 +7054,10 @@ WHEN TO USE: when you have a specific \`contact_id\` (from leadbay_get_contacts)
 
 WHEN NOT TO USE: for bulk enrichment by job title across many leads \u2014 use leadbay_enrich_titles, which handles the selection lifecycle and returns a clean preview/launch flow.
 
+## CREDIT COST \u2014 discreet
+
+This is a paid call. The result returns \`credits_remaining\` (billing.ai_credits, read before the spend). Don't make a fuss about credits: only flag the balance if it's low (e.g. \u2264 a few credits) so the user can decide. Otherwise append it quietly as a small italic parenthetical at the END of your reply \u2014 \`_(N credits remaining)_\`. Don't quote an exact per-contact cost (the rate is backend-only). The actual per-contact cost (enrichment.credits_used) appears on the contact via leadbay_get_contacts after enrichment. If \`credits_remaining\` is null, omit the line \u2014 don't assume zero.
+
 This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 `;
 var leadbay_enrich_titles = `Order contact enrichments by job title across many leads. Contacts are NOT returned by default with a lead (Leadbay keeps enrichment out-of-band to control cost); the agent requests them on demand via this tool when it's ready to actually reach out. Two modes: (A) NO \`titles\` param \u2014 returns the available titles + Leadbay's \`title_suggestions\` + \`auto_included_titles\` + a count of enrichable contacts, so the agent can ask the user which titles to enrich. (B) \`titles\` given \u2014 calls preview, then launches if there's anything enrichable. On 429 returns \`{status:'quota_exceeded'}\` cleanly. Selection lifecycle is wrapped in a try/finally so the user's selection is left clean even on error.
@@ -6845,6 +7066,35 @@ WHEN TO USE: as the agent's go-to enrichment entry point, immediately before pro
 
 WHEN NOT TO USE: to enrich a single contact \u2014 that's leadbay_enrich_contacts (granular). Speculatively, before the user has committed to outreaching \u2014 enrichment spends credits.
 
+## CREDIT COST \u2014 make spend visible
+
+Enrichment is the main PAID operation. Surface cost both before and after.
+
+**BEFORE (confirm before launching).** The discover / preview_only / dry_run modes return \`credits_remaining\` (the balance) and \`enrichable_contacts\` (the volume that would be enriched). Tell the user plainly: **"You have {credits_remaining} credits. This will enrich {enrichable_contacts} contacts."** then ask them to confirm before you launch the paid run. Route that confirmation through \`ask_user_input_v0\` ("Enrich {enrichable_contacts} contacts now?" \u2192 ["Yes, enrich", "No, cancel"]). Do NOT state an exact estimated cost \u2014 the per-contact credit rate lives backend-side and is not in the preview; show the balance and the count, never a fabricated "will cost N credits". If \`credits_remaining\` is null, billing is unavailable \u2014 say the balance is unknown, don't assume zero or unlimited.
+
+**AFTER (show the balance, discreetly).** Once the job finishes \u2014 poll \`leadbay_bulk_enrich_status\`, which returns \`credits_remaining\` (the post-spend balance). Don't make a fuss: append ONE small italic line in parentheses at the very END of your reply \u2014 \`_(N credits remaining)_\`. Omit it if \`credits_remaining\` is null. Do NOT report a "credits used" figure: per-run cost can't be scoped reliably (a lead's contacts mix earlier enrichments), so only the balance is shown.
+
+## GATE \u2014 PREFER BUILT-IN HOST WIDGETS
+
+Modern chat hosts (Claude, ChatGPT) expose first-party widgets the agent can route into. These ALWAYS produce a better UX than markdown tables / inline prose for the data shapes they support \u2014 they're tappable on mobile, persistent across turns, and integrate with the host's quick-actions.
+
+**The Big Three** \u2014 when a tool result fits, route there:
+
+| Host widget | Use when | Field map (from Leadbay payload) |
+|---|---|---|
+| \`places_map_display_v0\` (Claude) | Result has \u22652 leads with \`location.city\` set, and the user's intent is geographic / "in person" / travel | \`{name: lead.company_name, address: "<city>, <country>", place_id: lead.location.place_id ?? omit, notes: <one-sentence pitch>}\` per location |
+| \`message_compose_v1\` (Claude) | You're about to draft outreach (email / message / call opener) | \`{kind: "email", summary_title, variants: [{label, body, subject}]}\` \u2014 2\u20133 variants, labels describe STRATEGY ("Push for alignment", "Reference the M&A signal"), not tone ("Friendly", "Formal") |
+| \`ask_user_input_v0\` (Claude) | The tool's NEXT STEPS block has 2\u20134 mutually-exclusive next moves and the user hasn't already chosen | \`{questions: [{question: "What next?", type: "single_select", options: [<2-4 short button labels>]}]}\`; max 3 questions per call |
+
+ChatGPT exposes the same routing pattern via \`_meta.openai/outputTemplate\`. We don't ship any custom widgets ourselves \u2014 this gate is exclusively about routing into the host's first-party widgets when the data shape fits.
+
+**Rules:**
+- The widget IS the visual. Do NOT emit a markdown table or prose list of the same data alongside \u2014 that produces two competing UIs.
+- Pass identifiers (place_id, lead.id, contact_id) verbatim. Don't rewrite.
+- When the host doesn't expose the named widget, the agent falls back to the prose/table rendering the per-tool description already specifies. The directive is host-conditional; the fallback is automatic.
+- One short intro sentence in chat is enough \u2014 "Here are your 5 NYC follow-ups." Then route into the widget.
+
+
 This tool MUTATES state. The caller (agent or human-in-the-loop) is responsible for confirming intent before invocation; the MCP server does not soft-prompt for confirmation. See \`annotations.destructiveHint\`.
 `;
 var leadbay_extend_lens = `## WHEN TO USE
@@ -9612,10 +9862,36 @@ var getQuota = {
   outputSchema: {
     type: "object",
     properties: {
-      plan: { type: ["string", "null"], description: "Org plan tier (e.g., FREE, PRO)." },
+      plan: {
+        type: ["string", "null"],
+        description: "Org plan tier (e.g., FREE, TIER1, TIER2). May be null."
+      },
+      org: {
+        type: "object",
+        description: "Org-level quota state.",
+        properties: {
+          spend: { type: "array", description: "Reserved; empty in practice.", items: { type: "object" } },
+          resources: {
+            type: "array",
+            description: "Per-resource per-window USAGE. Each: {resource_type, count, window_type, resets_at}. `count` is the amount USED in that window (not remaining, not a cap). No cap field is returned by the API.",
+            items: { type: "object" }
+          }
+        }
+      },
+      user: {
+        type: "object",
+        description: "User-level quota state, same shape as `org`. May be absent.",
+        properties: {
+          spend: { type: "array", items: { type: "object" } },
+          resources: { type: "array", items: { type: "object" } }
+        }
+      },
+      // Legacy/compat: the live API does NOT return a top-level `windows`
+      // array — usage lives in org/user.resources[]. Declared only so older
+      // recorded fixtures still conform; do not rely on it.
       windows: {
         type: "array",
-        description: "Per-resource per-window limits. Each: {resource, window, current_units, max_units, resets_at}.",
+        description: "Deprecated \u2014 not returned by the live API. Use org/user.resources[].",
         items: { type: "object" }
       }
     }
@@ -11148,9 +11424,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);
@@ -11158,7 +11448,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();
@@ -11214,7 +11504,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) {
@@ -11279,6 +11569,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,
@@ -11466,6 +11757,7 @@ var importLeads = {
         leads: [],
         not_imported,
         importIds: [],
+        notification_ids: [],
         region: client.region,
         dry_run: dryRun || void 0,
         _meta: client.lastMeta ?? {
@@ -11520,6 +11812,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,
@@ -11540,6 +11836,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;
@@ -11551,6 +11848,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);
         }
@@ -11571,7 +11871,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) {
@@ -11588,17 +11888,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,
@@ -12266,6 +12570,63 @@ var agentMemoryReview = {
   }
 };
 
+// ../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: "Acknowledge a Leadbay notification",
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_acknowledge_notification,
+  write: true,
+  inputSchema: {
+    type: "object",
+    properties: {
+      notification_id: {
+        type: "string",
+        description: "UUID of the notification to acknowledge. Use the notification_id from `_meta.notifications[]` or `account_status.notifications[]`."
+      },
+      archive: {
+        type: "boolean",
+        description: "If true, archive the notification (won't appear in `archived=false` listings). If false / omitted, mark seen (resets firstSeenAt)."
+      }
+    },
+    required: ["notification_id"],
+    additionalProperties: false
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      acknowledged: { type: "boolean" },
+      notification_id: { type: "string" },
+      action: { type: "string", enum: ["seen", "archive"] }
+    },
+    required: ["acknowledged", "notification_id", "action"]
+  },
+  execute: async (client, params, ctx) => {
+    if (!UUID_RE.test(params.notification_id)) {
+      return {
+        error: true,
+        code: "BAD_INPUT",
+        message: "notification_id must be a UUID",
+        hint: "Pass the notification_id verbatim from _meta.notifications[].notification_id or account_status.notifications[].notification_id."
+      };
+    }
+    const action = params.archive ? "archive" : "seen";
+    await client.acknowledgeNotification(params.notification_id, action);
+    ctx?.notificationsInbox?.markSeen(params.notification_id);
+    return {
+      acknowledged: true,
+      notification_id: params.notification_id,
+      action
+    };
+  }
+};
+
 // ../core/dist/tools/select-leads.js
 var selectLeads = {
   name: "leadbay_select_leads",
@@ -15169,6 +15530,78 @@ var researchLeadByNameFuzzy = {
   }
 };
 
+// ../core/dist/composite/account-history.js
+var accountHistory = {
+  name: "leadbay_account_history",
+  annotations: {
+    title: "One account's full back-story",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  description: leadbay_account_history,
+  inputSchema: {
+    type: "object",
+    properties: {
+      leadId: { type: "string", description: "Lead UUID (required)" },
+      activityCount: {
+        type: "number",
+        description: "Number of activity-timeline entries to return, max 100 (default: 50)."
+      },
+      lensId: {
+        type: "number",
+        description: "Lens id the lead came from (escape hatch \u2014 normally omit; defaults to the active lens). Pass it when researching a lead from a lens other than the current default, so the underlying /lenses/{lensId}/leads/{leadId} fetch doesn't 404 after the active lens changed."
+      }
+    },
+    required: ["leadId"],
+    additionalProperties: false
+  },
+  execute: async (client, params, ctx) => {
+    const leadId = params.leadId;
+    const count = Math.max(1, Math.min(Math.floor(params.activityCount ?? 50), 100));
+    const [research, notes, activities] = await Promise.all([
+      researchLeadById.execute(client, { leadId, lensId: params.lensId, response_format: "json" }, ctx),
+      client.request("GET", `/leads/${leadId}/notes`).catch(() => []),
+      client.request("GET", `/leads/${leadId}/activities?count=${count}`).catch(() => ({ items: [], pagination: { total: 0 } }))
+    ]);
+    const r = research;
+    const noteList = Array.isArray(notes) ? notes : [];
+    const activityItems = Array.isArray(activities?.items) ? activities.items : [];
+    return {
+      lead: {
+        id: r.firmographics?.id ?? leadId,
+        name: r.firmographics?.name ?? null
+      },
+      // Current state — signals, firmographics, qualification, contacts,
+      // engagement: passed through verbatim from research_lead_by_id so the
+      // agent gets the live "why is this account hot NOW" picture.
+      signals: r.signals ?? null,
+      firmographics: r.firmographics ?? null,
+      qualification: r.qualification ?? [],
+      contacts: r.contacts ?? null,
+      engagement: r.engagement ?? null,
+      // Historical context — the part research only counts/summarizes.
+      notes: noteList,
+      activities: {
+        activities: activityItems.map((a) => ({ type: a.type, date: a.date })),
+        total: activities?.pagination?.total ?? 0
+      },
+      // Preserve research's pass-through metadata (agent_memory summary,
+      // lens_id, web_fetch_in_progress, has_reachable_contact, …) — the
+      // generated description advertises the memory protocol, so dropping
+      // _meta.agent_memory would make history narratives miss stored
+      // preferences. Spread research _meta first, then layer our counts.
+      _meta: {
+        ...r._meta ?? {},
+        region: client.region,
+        notes_count: noteList.length,
+        activities_returned: activityItems.length
+      }
+    };
+  }
+};
+
 // ../core/dist/composite/recall-ordered-titles.js
 var recallOrderedTitles = {
   name: "leadbay_recall_ordered_titles",
@@ -15336,7 +15769,21 @@ var accountStatus = {
       },
       quota: {
         type: ["object", "null"],
-        description: "Per-resource quota state (llm_completion, ai_rescore, web_fetch, LENS_EXTRA_REFILL) across daily/weekly/monthly windows. Null if /quota_status failed (logged in stderr). Pre-check the LENS_EXTRA_REFILL entry before calling leadbay_extend_lens."
+        description: "Per-resource quota state (llm_completion, ai_rescore, web_fetch, LENS_EXTRA_REFILL) across daily/weekly/monthly windows. Null if /quota_status failed (see quota_error) or genuinely returned nothing. Pre-check the LENS_EXTRA_REFILL entry before calling leadbay_extend_lens."
+      },
+      quota_error: {
+        type: ["object", "null"],
+        description: "Non-null ONLY when the quota_status call FAILED \u2014 {code, http_status, message}. A 401/403 means the token lacks quota scope: tell the user to reconnect / re-run OAuth. Treat as 'quota unreadable', NEVER as zero usage or 'no limits'.",
+        properties: {
+          code: { type: "string" },
+          http_status: { type: ["number", "null"] },
+          message: { type: "string" }
+        }
+      },
+      notifications: {
+        type: "array",
+        description: "Terminal bulk-progress notifications the MCP knows about (background work the user or agent started that has since completed). Each entry carries notification_id, kind (bulk_enrich | bulk_qualify | import | other), bulk_progress counters, and a revise_hint pointing at prior agent outputs the just-finished work might have made stale. After revising affected outputs, call leadbay_acknowledge_notification(notification_id) to clear the entry. Empty array when nothing has completed.",
+        items: { type: "object" }
       },
       _meta: {
         type: "object",
@@ -15372,9 +15819,15 @@ var accountStatus = {
   execute: async (client, _params, ctx) => {
     const me = await client.resolveMe();
     let quota = null;
+    let quota_error = null;
     try {
       quota = await client.request("GET", `/organizations/${me.organization.id}/quota_status`);
     } catch (err) {
+      quota_error = {
+        code: err?.code ?? "QUOTA_STATUS_FAILED",
+        http_status: err?._meta?.http_status ?? null,
+        message: err?.message ?? "quota_status request failed"
+      };
       ctx?.logger?.warn?.(`account_status: quota_status failed: ${err?.message ?? err?.code ?? err}`);
     }
     return withAgentMemoryMeta(client, {
@@ -15397,6 +15850,16 @@ 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() ?? [],
+      // Non-null ONLY when the quota_status call failed. The agent must treat
+      // this as "could not read quota" (reauth on 401/403) — NOT as zero usage.
+      quota_error,
       _meta: {
         region: client.region
       }
@@ -15410,6 +15873,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: {
@@ -15577,69 +16067,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) {
@@ -16352,6 +16823,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 } : {},
@@ -16376,6 +16848,7 @@ var importAndQualify = {
         ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
         qualify_id: null,
         import_ids: queued.importIds,
+        notification_ids: queued.notification_ids ?? [],
         imported: [],
         not_imported: [],
         qualified: [],
@@ -16413,6 +16886,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: [],
@@ -16450,6 +16924,7 @@ var importAndQualify = {
         ...chosenBudgets ? { chosen_budgets: chosenBudgets } : {},
         qualify_id: null,
         import_ids: importResult.importIds,
+        notification_ids: importResult.notification_ids ?? [],
         imported,
         not_imported,
         qualified: [],
@@ -16560,6 +17035,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,
@@ -16901,6 +17377,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: {
@@ -17055,6 +17539,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,
@@ -17066,6 +17560,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,
@@ -17078,10 +17575,23 @@ 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;
   }
 };
 
+// ../core/dist/composite/_credits-helpers.js
+async function readCreditsRemaining(client, force = false) {
+  try {
+    const me = await client.resolveMe(force);
+    return me.organization.billing?.ai_credits ?? null;
+  } catch {
+    return null;
+  }
+}
+
 // ../core/dist/composite/enrich-titles.js
 var DEFAULT_CANDIDATE_COUNT = 25;
 var enrichTitles = {
@@ -17165,6 +17675,10 @@ var enrichTitles = {
         type: "number",
         description: "Count of enrichable contacts at preview time."
       },
+      credits_remaining: {
+        type: ["number", "null"],
+        description: "AI-credit balance BEFORE launching (billing.ai_credits). Present in discover / preview_only / dry_run modes. Pair with enrichable_contacts to tell the user 'you have N credits, this will enrich M contacts' \u2014 do NOT estimate an exact cost (the per-contact rate is backend-only). Null = billing unavailable."
+      },
       selected_lead_count: {
         type: "number",
         description: "How many leads the selection covers."
@@ -17288,6 +17802,10 @@ var enrichTitles = {
             previously_enriched: previouslyEnriched,
             enrichable_contacts: enrichableContacts,
             selected_lead_count: leadIds.length,
+            // BEFORE: show balance + volume. We can't estimate exact cost
+            // (the per-contact rate is backend-only), so surface the balance
+            // and the count, not a fabricated "will cost N".
+            credits_remaining: await readCreditsRemaining(client),
             next_action: "Pick titles to enrich and call leadbay_enrich_titles again with titles=[...]"
           };
         }
@@ -17310,7 +17828,8 @@ var enrichTitles = {
             preview,
             launched: false,
             message: "No enrichable contacts for the chosen titles. Try other titles from available_titles or recommendations.",
-            available_titles: availableTitles
+            available_titles: availableTitles,
+            credits_remaining: await readCreditsRemaining(client)
           };
         }
         if (params.dry_run) {
@@ -17318,7 +17837,12 @@ var enrichTitles = {
             mode: "dry_run",
             preview,
             launched: false,
-            would_launch: { titles: params.titles, email, phone }
+            would_launch: { titles: params.titles, email, phone },
+            // BEFORE confirmation gate: balance + how many contacts WOULD be
+            // enriched. enrichable_contacts is the volume; credits_remaining
+            // the balance. No estimated cost — that rate is backend-only.
+            enrichable_contacts: preview.enrichable_contacts,
+            credits_remaining: await readCreditsRemaining(client)
           };
         }
         const tracker = ctx?.bulkTracker;
@@ -17348,6 +17872,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,
@@ -17363,8 +17888,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) {
@@ -17388,9 +17914,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 {
@@ -17418,8 +17945,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 {
@@ -17435,6 +17963,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);
@@ -17514,6 +18050,10 @@ var bulkEnrichStatus = {
         type: "boolean",
         description: "True when overall_progress.done === total AND no partial_failures."
       },
+      credits_remaining: {
+        type: ["number", "null"],
+        description: "AI-credit balance re-read after the spend (force-refreshed /users/me \u2192 billing.ai_credits). Present only when all_done. Null = billing unavailable (don't read as zero). NOTE: a per-run 'credits used' figure is intentionally NOT returned \u2014 getContacts can't scope cost to this bulk, so any sum would conflate historical enrichments."
+      },
       partial_failures: {
         type: "array",
         description: "Per-lead errors observed during contacts fan-out (omitted when no failures).",
@@ -17599,6 +18139,55 @@ 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}`);
+        const creditsRemaining2 = !inProgress ? await readCreditsRemaining(client, true) : null;
+        return {
+          bulk_id: record.bulk_id,
+          notification_id: notifId,
+          launched_at: record.launched_at,
+          status: record.status,
+          durability: record.durability,
+          titles: record.titles,
+          email: record.email,
+          phone: record.phone,
+          lens_id: record.lens_id,
+          leads: leads2,
+          overall_progress: {
+            done: bp.success_count + bp.failure_count + bp.quota_hit_count,
+            total: bp.total_count,
+            done_ratio: bp.total_count === 0 ? 0 : (bp.success_count + bp.failure_count + bp.quota_hit_count) / bp.total_count
+          },
+          bulk_progress: bp,
+          in_progress: inProgress,
+          all_done: !inProgress,
+          ...!inProgress ? { credits_remaining: creditsRemaining2 } : {},
+          ...bp.quota_hit_count > 0 ? {
+            quota_hit_hint: "Some contacts could not be enriched because the AI-credits quota was hit. Top up via leadbay_create_topup_link or wait for the window reset."
+          } : {}
+        };
+      }
+      ctx?.logger?.info?.(`bulk_enrich_status: notification ${notifId} not yet visible; falling back to per-lead fan-out`);
+    }
     let doneSoFar = 0;
     const totalLeads = record.lead_ids.length;
     const results = await pMap(record.lead_ids, async (leadId) => {
@@ -17664,6 +18253,10 @@ var bulkEnrichStatus = {
     };
     const allDone = totalAll > 0 && totalDone === totalAll && partialFailures.length === 0;
     ctx?.logger?.info?.(`bulk.status_checked bulk_id=${record.bulk_id} done=${totalDone} total=${totalAll} wall_ms=${Date.now() - startMs}`);
+    let creditsRemaining = null;
+    if (allDone) {
+      creditsRemaining = await readCreditsRemaining(client, true);
+    }
     return {
       bulk_id: record.bulk_id,
       launched_at: record.launched_at,
@@ -17676,6 +18269,7 @@ var bulkEnrichStatus = {
       leads,
       overall_progress: overallProgress,
       all_done: allDone,
+      ...allDone ? { credits_remaining: creditsRemaining } : {},
       ...partialFailures.length > 0 ? { partial_failures: partialFailures } : {}
     };
   }
@@ -19360,6 +19954,13 @@ var compositeReadTools = [
   campaignCallSheet,
   researchLeadById,
   researchLeadByNameFuzzy,
+  // accountHistory layers FULL notes + activity timeline on top of research
+  // so the agent can write the US4 "why has this dormant account resurfaced"
+  // narrative in ONE call. ALWAYS exposed (compositeReadTools) — the underlying
+  // get_lead_notes / get_lead_activities are ADVANCED-gated, but the
+  // reprioritize-a-neglected-account workflow (#3630 GAP C) must work in a
+  // default deployment without LEADBAY_MCP_ADVANCED=1.
+  accountHistory,
   recallOrderedTitles,
   accountStatus,
   bulkEnrichStatus,
@@ -19392,7 +19993,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,
@@ -20211,6 +20818,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 ?? {};
@@ -20330,11 +20953,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;
@@ -20629,7 +21254,7 @@ function parseWriteEnv(env = process.env) {
 }
 
 // src/http-server.ts
-var VERSION = true ? "0.17.3" : "0.0.0-dev";
+var VERSION = true ? "0.18.1" : "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();