@leadbay/mcp 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog — @leadbay/mcp
 
+## 0.2.2 — 2026-04-21
+
+Bug fix + contract correction + mental-model docs release.
+
+- **Fix [product#3504](https://github.com/leadbay/product/issues/3504)**: `npx -y @leadbay/mcp` no longer exits silently on Node 25. The `isEntrypoint` check now resolves both sides through `realpathSync`, so the npx shim symlink path matches the real `dist/bin.js`. Previously `main()` never ran under npx and the MCP host saw a dead connection with no diagnostic.
+- Replaced stale `app.leadbay.ai` URLs in error strings (NOT_AUTHENTICATED, AUTH_INVALID, BILLING_SUSPENDED, PERMISSION_DENIED) and CLI help text with runnable commands (`leadbay-mcp install`, `leadbay-mcp login`) or "contact support". Recovery hints include `--region <us|fr>` because the CLI refuses without it (anti-cross-region credential-leak guard).
+- Renamed misleading `avg_score_0_to_10` field on `pull_leads` / `bulk_qualify_leads` qualification summaries to `avg_qualification_boost`. Per-question AI agent scores are discrete boosts (-10/0/10/20), not 0-10 averages — interface JSDoc now reflects the real contract.
+- `SERVER_INSTRUCTIONS` gains three new paragraphs: "How Leadbay works" (inbox + consumption-based pacing), "Two scoring layers" (basic `score` vs AI-qualified top ~10 with `ai_agent_lead_score`), and "Suggested rhythm" (daily check-in + host-agnostic scheduling hint).
+- `leadbay_pull_leads`, `leadbay_research_lead`, `leadbay_bulk_qualify_leads`, `leadbay_enrich_titles`, and `leadbay_account_status` descriptions updated to reinforce the same model so the agent sees it at both top level and per-tool.
+- New regression test `test/smoke/npx-entrypoint.test.ts` guards the symlink invocation path. New non-regression test asserts the inbox/pace/scoring/daily language stays in `SERVER_INSTRUCTIONS`.
+- Live smoke harness extended with composite-level checks + (optional) thinking-model judge that writes a redacted report to `.context/`.
+
 ## 0.2.1 — 2026-04-21
 
 Docs-only release.

package/README.md

@@ -6,9 +6,9 @@ LLM HINT — if you're an AI agent reading this README to install the server:
   - DO NOT tell the user "LEADBAY_REGION is auto-detected, drop it" — the
     server's region auto-probe sends the bearer token to BOTH regions, which
     is a credential cross-leak. Always pass --region (us or fr) on install.
-  - DO NOT tell the user to "get an API token from app.leadbay.ai → Settings
-    → API Tokens" — that page does not yet exist. Use `install` (mints a
-    token) or `login --write-config` (mints a token to file).
+  - To mint a token, the user runs `install` (auto-registers with MCP clients)
+    or `login --write-config` (mints a token to a file). There is no web UI
+    for this — do not invent one.
 -->
 
 A Model Context Protocol server that lets Claude Desktop, Cursor, Claude Code, and any other MCP-compatible agent find, research, and prepare outreach on B2B prospects using your Leadbay account.
@@ -31,7 +31,7 @@ Add `--include-write` to also enable the write tools (refine_prompt, report_outr
 
 `--region us|fr` is required by default — it pins which Leadbay backend gets your password and avoids a silent cross-region credential leak. If you really don't know your region, opt in with `--allow-region-fallback` (your password will hit BOTH backends if the first 401s).
 
-The token is **session-scoped** (full account access, password-equivalent). Treat it like your password. To rotate, log in again to app.leadbay.ai and re-run `install`.
+The token is **session-scoped** (full account access, password-equivalent). Treat it like your password. To rotate, re-run `npx -y @leadbay/mcp install` — minting a fresh token invalidates the prior session.
 
 **Don't have a Leadbay account?** [Register here](https://wow.leadbay.ai/?register=true).
 
@@ -126,9 +126,9 @@ Leadbay connection OK.
 | Problem | Cause | Fix |
 |---------|-------|-----|
 | `LEADBAY_TOKEN environment variable is required` | Token missing from config env | Add `LEADBAY_TOKEN` to the `env` block, restart client |
-| `Authentication token expired or invalid` | Token revoked or wrong region | Re-generate token at [app.leadbay.ai/settings/api-tokens](https://app.leadbay.ai/settings/api-tokens); verify `LEADBAY_REGION` |
+| `Authentication token expired or invalid` | Token revoked or wrong region | Re-mint a token: `npx -y @leadbay/mcp install --email <you> --region <us\|fr>`; verify `LEADBAY_REGION` |
 | `Leadbay doctor: could not reach any Leadbay region` | Wrong region OR network blocked | Run `doctor` with `LEADBAY_REGION=fr` to auto-probe. Check `https://api-us.leadbay.app` reachable. |
-| `No enrichment credits remaining` | Out of quota | Buy credits at [app.leadbay.ai](https://app.leadbay.ai) |
+| `No enrichment credits remaining` | Out of quota | Contact Leadbay support to extend quota |
 | Claude Desktop "loading forever" on first use | `npx` cold-start fetching the package | First run takes ~10s. Prefer `npm install -g @leadbay/mcp` for faster startup. |
 | Claude Desktop doesn't show Leadbay tools | Server crashed at startup | Check `~/Library/Logs/Claude/mcp*.log` (macOS) or `%APPDATA%\Claude\logs\mcp*.log` (Windows). |
 

package/dist/bin.js

@@ -3,12 +3,15 @@ import {
   compositeReadTools,
   compositeWriteTools,
   createClient,
+  createDefaultBulkStore,
   granularReadTools,
   granularWriteTools,
   resolveRegion
-} from "./chunk-BGJ6JWIO.js";
+} from "./chunk-FJBO2MY2.js";
 
 // src/bin.ts
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/server.ts
@@ -17,7 +20,7 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
-var SERVER_INSTRUCTIONS = "After every email, call, message, or meeting with a lead's contact, you MUST call leadbay_report_outreach with verification={source, ref} (gmail_message_id from the Gmail send, calendar_event_id from a booking, or user_confirmed='<the user's literal confirmation>'). Skipping or fabricating verification poisons the human team's pipeline.\n\nStart with leadbay_account_status to see the user's state, then leadbay_pull_leads to surface fresh leads. Use leadbay_research_lead to dig into one lead deeply (qualification answers, signals, contacts). When the user wants more leads, narrower audience, refined criteria, or contact enrichment, use the matching composite tool (bulk_qualify_leads / adjust_audience / refine_prompt / enrich_titles) \u2014 they hide lens permissions, region routing, polling, and selection state from you.";
+var SERVER_INSTRUCTIONS = "After every email, call, message, or meeting with a lead's contact, you MUST call leadbay_report_outreach with verification={source, ref} (gmail_message_id from the Gmail send, calendar_event_id from a booking, or user_confirmed='<the user's literal confirmation>'). Skipping or fabricating verification poisons the human team's pipeline.\n\nHow Leadbay works (mental model): Leadbay is a sales inbox, not a queryable database. Each day the user logs back in, a fresh batch of leads is delivered. Batch size is paced by how many leads the user has actually acted on recently \u2014 some workflows produce a big stream of smaller prospects, others a narrow stream of bigger ones. Pulling more won't produce more; the user acting on leads (outreach, skips, saves) does.\n\nTwo scoring layers: every lead has a basic `score` (firmographic \u2014 already decent, usually correlates with AI). Roughly the top 10 of each batch are also AI-qualified (targeted web research + qualification questions \u2192 `ai_agent_lead_score`, surfaced as `qualification_summary` on leadbay_pull_leads). Leads past the top ~10 are not worse \u2014 the system is saving resources. Call leadbay_bulk_qualify_leads for deeper qualification or leadbay_enrich_titles for contacts on any lead that looks worth it.\n\nStart with leadbay_account_status to see the user's state, then leadbay_pull_leads to surface fresh leads. Use leadbay_research_lead to dig into one lead deeply (qualification answers, signals, contacts). When the user wants more leads, narrower audience, refined criteria, or contact enrichment, use the matching composite tool (bulk_qualify_leads / adjust_audience / refine_prompt / enrich_titles) \u2014 they hide lens permissions, region routing, polling, and selection state from you.\n\nSuggested rhythm: a healthy agent pattern is a daily check-in \u2014 pull fresh leads, skim the auto-qualified top, deepen 1-3 promising ones, propose outreach to the user, then leadbay_report_outreach on what actually got sent. If your host supports scheduling, offer to set up a daily run.";
 function formatErrorForLLM(err) {
   if (err && typeof err === "object" && err.error === true) {
     const parts = [`${err.message}.`, err.hint];
@@ -85,7 +88,10 @@ function buildServer(client, opts = {}) {
     }
     const args = req.params.arguments ?? {};
     try {
-      const result = await tool.execute(client, args, { logger: opts.logger });
+      const result = await tool.execute(client, args, {
+        logger: opts.logger,
+        bulkTracker: opts.bulkTracker
+      });
       if (result && typeof result === "object" && result.error === true) {
         return {
           content: [
@@ -113,7 +119,7 @@ function buildServer(client, opts = {}) {
 
 // src/bin.ts
 import { createRequire } from "module";
-var VERSION = "0.2.1";
+var VERSION = "0.2.2";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 
@@ -132,7 +138,7 @@ USAGE
   leadbay-mcp --help     Print this help
 
 ENV VARS
-  LEADBAY_TOKEN          (required) Bearer token from https://app.leadbay.ai/settings/api-tokens
+  LEADBAY_TOKEN          (required) Bearer token (run \`leadbay-mcp install\` to mint one).
   LEADBAY_REGION         (optional) "us" or "fr". Auto-detected from /users/me if unset.
   LEADBAY_BASE_URL       (optional) Override API base URL (for staging/dev).
   LEADBAY_MCP_ADVANCED   (optional) Set to "1" to expose granular API tools alongside
@@ -189,7 +195,7 @@ function parseLogLevel(raw) {
 }
 function exitWithTokenError() {
   process.stderr.write(
-    "leadbay-mcp: LEADBAY_TOKEN environment variable is required.\n  1. Create a token at https://app.leadbay.ai/settings/api-tokens\n  2. Set it in your MCP client config (e.g. claude_desktop_config.json).\n\nRun `leadbay-mcp --help` for the full config template.\n"
+    "leadbay-mcp: LEADBAY_TOKEN environment variable is required.\n  1. Run: npx -y @leadbay/mcp install --email <you> --region <us|fr>\n  2. Set it in your MCP client config (e.g. claude_desktop_config.json).\n\nRun `leadbay-mcp --help` for the full config template.\n"
   );
   process.exit(1);
 }
@@ -326,7 +332,7 @@ async function runLogin(args) {
   let result;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-PIXZN6N4.js");
+      const { REGIONS } = await import("./dist-FENQ2I7R.js");
       const baseUrl = REGIONS[pinnedRegion];
       const c = createClient({ region: pinnedRegion });
       const token = await loginAt(baseUrl, email, password);
@@ -669,7 +675,7 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
   let region;
   try {
     if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-PIXZN6N4.js");
+      const { REGIONS } = await import("./dist-FENQ2I7R.js");
       const baseUrl = REGIONS[pinnedRegion];
       token = await loginAt(baseUrl, email, password);
       region = pinnedRegion;
@@ -721,7 +727,7 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
 The token was written into client config files but never printed to your terminal.
 Verify with: LEADBAY_TOKEN=$(...) npx -y @leadbay/mcp@0.2 doctor
 Restart your MCP client(s) to pick up the new server.
-If you ever leak the token, log in to app.leadbay.ai again to invalidate the prior session.
+If you ever leak the token, run \`leadbay-mcp login --email <you> --region <us|fr>\` to mint a fresh one (which invalidates the prior session).
 `
   );
   return anyOk ? 0 : 1;
@@ -795,10 +801,16 @@ async function main() {
   const client = await resolveClientFromEnv(logger);
   const includeAdvanced = process.env.LEADBAY_MCP_ADVANCED === "1";
   const includeWrite = process.env.LEADBAY_MCP_WRITE === "1";
-  const server = buildServer(client, { includeAdvanced, includeWrite, logger });
+  const bulkTracker = await createDefaultBulkStore({ logger });
+  const server = buildServer(client, {
+    includeAdvanced,
+    includeWrite,
+    logger,
+    bulkTracker
+  });
   const transport = new StdioServerTransport();
   logger.info?.(
-    `Starting MCP server v${VERSION} (advanced=${includeAdvanced}, write=${includeWrite}, baseUrl=${client.baseUrl})`
+    `Starting MCP server v${VERSION} (advanced=${includeAdvanced}, write=${includeWrite}, baseUrl=${client.baseUrl}, bulk_store=${bulkTracker.durability})`
   );
   await server.connect(transport);
 }
@@ -806,8 +818,8 @@ var isEntrypoint = (() => {
   try {
     const entry = process.argv[1];
     if (!entry) return false;
-    const url = new URL(import.meta.url);
-    return url.pathname === entry || url.pathname.endsWith(entry);
+    const self = fileURLToPath(import.meta.url);
+    return realpathSync(self) === realpathSync(entry);
   } catch {
     return false;
   }

package/dist/{chunk-BGJ6JWIO.js → chunk-FJBO2MY2.js}

@@ -240,7 +240,7 @@ var LeadbayClient = class {
       return this.mockRequest(method, path, body);
     }
     if (!this.token) {
-      throw this.makeError("NOT_AUTHENTICATED", "Not logged in to Leadbay", "Set LEADBAY_TOKEN env var (obtain token at https://app.leadbay.ai/settings/api-tokens), or use the OpenClaw leadbay_login tool", path);
+      throw this.makeError("NOT_AUTHENTICATED", "Not logged in to Leadbay", "Set LEADBAY_TOKEN in your MCP client config, or run: npx -y @leadbay/mcp install --email <you> --region <us|fr>", path);
     }
     await this.acquireSemaphore();
     try {
@@ -275,7 +275,7 @@ var LeadbayClient = class {
       return;
     }
     if (!this.token) {
-      throw this.makeError("NOT_AUTHENTICATED", "Not logged in to Leadbay", "Set LEADBAY_TOKEN env var (obtain token at https://app.leadbay.ai/settings/api-tokens), or use the OpenClaw leadbay_login tool", path);
+      throw this.makeError("NOT_AUTHENTICATED", "Not logged in to Leadbay", "Set LEADBAY_TOKEN in your MCP client config, or run: npx -y @leadbay/mcp install --email <you> --region <us|fr>", path);
     }
     await this.acquireSemaphore();
     try {
@@ -332,7 +332,7 @@ var LeadbayClient = class {
     }
     const retryAfter = parseRetryAfter(headers["retry-after"]);
     if (status === 401) {
-      return this.makeError("AUTH_EXPIRED", "Authentication token expired or invalid", "Your LEADBAY_TOKEN is no longer valid. Regenerate at https://app.leadbay.ai/settings/api-tokens and restart.", endpoint);
+      return this.makeError("AUTH_EXPIRED", "Authentication token expired or invalid", "Your LEADBAY_TOKEN is no longer valid. Regenerate it: npx -y @leadbay/mcp login --email <you> --region <us|fr>, then restart your MCP client.", endpoint);
     }
     if (status === 429 || status === 402 || parsed?.error === "quota_exceeded" || parsed?.error?.code === "quota_exceeded") {
       return this.makeError("QUOTA_EXCEEDED", retryAfter ? `Quota exceeded \u2014 retry in ${retryAfter}s` : "Quota exceeded", retryAfter ? `Wait ${retryAfter}s before retrying. Check leadbay_get_quota to see which resource window was hit.` : "Wait, then retry. Check leadbay_get_quota to see which resource window (daily/weekly/monthly) was hit.", endpoint, retryAfter);
@@ -340,9 +340,9 @@ var LeadbayClient = class {
     if (status === 403) {
       const msg = parsed?.message || parsed?.error || parsed?.error?.message || "";
       if (typeof msg === "string" && (msg.includes("suspend") || msg.includes("billing"))) {
-        return this.makeError("BILLING_SUSPENDED", "Account billing is suspended", "Your Leadbay account billing is suspended. Update at https://app.leadbay.ai", endpoint);
+        return this.makeError("BILLING_SUSPENDED", "Account billing is suspended", "Your Leadbay account billing is suspended. Contact Leadbay support.", endpoint);
       }
-      return this.makeError("FORBIDDEN", "Insufficient permissions", "Your token does not have access to this resource. Check account permissions at https://app.leadbay.ai", endpoint);
+      return this.makeError("FORBIDDEN", "Insufficient permissions", "Your token does not have access to this resource. Contact Leadbay support to verify account permissions.", endpoint);
     }
     if (status === 404) {
       return this.makeError("NOT_FOUND", parsed?.message || parsed?.error?.message || "Resource not found", "Verify the ID is correct", endpoint);
@@ -754,7 +754,7 @@ var getTasteProfile = {
         question: q.question
       })),
       ...isEmpty ? {
-        hint: "No taste profile configured yet. Set it up at app.leadbay.ai for better lead matching."
+        hint: "No taste profile configured yet. Use leadbay_refine_prompt or contact Leadbay support to set one up for better lead matching."
       } : {}
     };
   }
@@ -827,7 +827,7 @@ var enrichContacts = {
       const me = await client.request("GET", "/users/me");
       creditsRemaining = me.organization.billing?.ai_credits ?? null;
       if (creditsRemaining !== null && creditsRemaining <= 0) {
-        throw client.makeError("QUOTA_EXCEEDED", "No enrichment credits remaining", "Purchase more credits at app.leadbay.ai");
+        throw client.makeError("QUOTA_EXCEEDED", "No enrichment credits remaining", "Contact Leadbay support to extend your credit quota");
       }
     } catch (e) {
       if (e?.code === "QUOTA_EXCEEDED")
@@ -1664,11 +1664,11 @@ function summarise(responses) {
   if (excerpt && excerpt.length > 200) {
     excerpt = excerpt.slice(0, 197) + "...";
   }
-  return { answered, total, avg_score_0_to_10: avg, best_response_excerpt: excerpt };
+  return { answered, total, avg_qualification_boost: avg, best_response_excerpt: excerpt };
 }
 var pullLeads = {
   name: "leadbay_pull_leads",
-  description: "Pull up new leads from the user's last-active lens (the canonical 'show me prospects to work on' tool). Each returned lead carries a one-line qualification_summary built from leadbay_ai_agent_responses, plus the rich tags / scores / recommended_contact_title / engagement counters / in-flight flags from the lead summary. When to use: as the agent's default opening move when the user wants to see leads. When NOT to use: when the user has named a specific lens \u2014 pass lensId to override the auto-resolution. Replaces the older leadbay_find_prospects (which is removed in v0.2.0).",
+  description: "Pull up new leads from the user's last-active lens \u2014 the canonical 'show me today's prospects' tool. Leadbay works like an inbox: each time the user logs back in, a fresh batch is delivered, paced by how many leads they've actually acted on recently. Pulling more won't produce more; user outreach/skips/saves does. Each returned lead carries a one-line qualification_summary built from leadbay_ai_agent_responses, plus the rich tags / scores / recommended_contact_title / engagement counters / in-flight flags from the lead summary. Roughly the top 10 of the batch come pre-qualified (populated qualification_summary + ai_agent_lead_score); leads below the top ~10 carry only the basic firmographic `score` \u2014 not worse, just resource-saved by the system. Call leadbay_bulk_qualify_leads to deepen any of them on demand. When to use: as the agent's default opening move when the user wants to see leads, or as a daily check-in for what's new today. When NOT to use: when the user has named a specific lens \u2014 pass lensId to override the auto-resolution. Replaces the older leadbay_find_prospects (which is removed in v0.2.0).",
   inputSchema: {
     type: "object",
     properties: {
@@ -1701,7 +1701,7 @@ var pullLeads = {
           summary: {
             answered: 0,
             total: 0,
-            avg_score_0_to_10: null,
+            avg_qualification_boost: null,
             best_response_excerpt: null
           }
         };
@@ -1783,7 +1783,7 @@ function reshapeWebFetchContent(content) {
 }
 var researchLead = {
   name: "leadbay_research_lead",
-  description: "Tell me everything decision-relevant about a single lead. Bundles the lens-scoped lead profile, the AI qualification answers (the agent's knowledge-base food), the structured web-research signals (with hot flags + sources), the enriched contacts, and the recent notes/epilogue/prospecting activity in one call. Order is deliberate: qualification first, then signals, then firmographics, then contacts, then engagement. When to use: when picking up a single lead from leadbay_pull_leads to decide whether to act on it. When NOT to use: across many leads at once \u2014 that's leadbay_pull_leads' job. (This composite supersedes the lower-level leadbay_get_lead_profile in agent flow; the granular tool stays available for fine-grained access.)",
+  description: "Tell me everything decision-relevant about a single lead. Bundles the lens-scoped lead profile, the AI qualification answers (the agent's knowledge-base food), the structured web-research signals (with hot flags + sources), the enriched contacts, and the recent notes/epilogue/prospecting activity in one call. Order is deliberate: qualification first, then signals, then firmographics, then contacts, then engagement. Scoring has two layers: the basic `score` (firmographic, always present, already decent) and the AI qualification layer (`ai_agent_lead_score` + per-question answers + web_fetch signals). The AI layer is pre-populated for roughly the top 10 of each daily batch, and on-demand (via leadbay_bulk_qualify_leads) for anything below that. Combine both layers when judging a lead. When to use: when picking up a single lead from leadbay_pull_leads to decide whether to act on it. When NOT to use: across many leads at once \u2014 that's leadbay_pull_leads' job. (This composite supersedes the lower-level leadbay_get_lead_profile in agent flow; the granular tool stays available for fine-grained access.)",
   inputSchema: {
     type: "object",
     properties: {
@@ -1997,7 +1997,7 @@ var recallOrderedTitles = {
 // ../core/dist/composite/account-status.js
 var accountStatus = {
   name: "leadbay_account_status",
-  description: "Show the user's account state \u2014 admin rights, language, last-active lens, current quota usage across daily/weekly/monthly windows for llm_completion / ai_rescore / web_fetch resources, and whether the org's intelligence is mid-regeneration. When to use: at the start of a session to know what the agent can/can't do, or after a 429 to explain to the user which resource window was exhausted and when it resets. When NOT to use: as a pre-flight gate before bulk ops \u2014 operations themselves return 429; this tool is for context, not gating.",
+  description: "Show the user's account state \u2014 admin rights, language, last-active lens, current quota usage across daily/weekly/monthly windows for llm_completion / ai_rescore / web_fetch resources, and whether the org's intelligence is mid-regeneration. Quota windows also hint at the user's consumption pace: heavy recent activity (ai_rescore / web_fetch near their window limits) is a signal that Leadbay will deliver a larger fresh batch next time the user logs back in, since batch size is paced by real consumption. When to use: at the start of a session to know what the agent can/can't do, or after a 429 to explain to the user which resource window was exhausted and when it resets. When NOT to use: as a pre-flight gate before bulk ops \u2014 operations themselves return 429; this tool is for context, not gating.",
   inputSchema: { type: "object", properties: {} },
   execute: async (client, _params, ctx) => {
     const me = await client.resolveMe();
@@ -2042,7 +2042,7 @@ var DEFAULT_PER_LEAD_BUDGET_MS = 9e4;
 var DEFAULT_TOTAL_BUDGET_MS = 5 * 6e4;
 var bulkQualifyLeads = {
   name: "leadbay_bulk_qualify_leads",
-  description: "Pick the next N unqualified leads in the active lens and qualify them (run AI rescore + web fetch), polling 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. When to use: when the user wants more qualified leads than what's currently shown. When NOT to use: to qualify a single specific lead \u2014 that's leadbay_qualify_lead (granular, advanced).",
+  description: "Pick the next N unqualified leads in the active lens and qualify them (run AI rescore + web fetch), polling 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. Context: Leadbay auto-qualifies roughly the top 10 of each daily batch. Leads below the top ~10 are NOT worse \u2014 the system is saving resources. This tool is how the agent spends more resources to go deeper on promising-looking leads the user hasn't had time to surface yet. When to use: when the user wants more qualified leads than what's currently shown, or when a lead looks promising in leadbay_pull_leads but has an empty qualification_summary. When NOT to use: to qualify a single specific lead \u2014 that's leadbay_qualify_lead (granular, advanced).",
   inputSchema: {
     type: "object",
     properties: {
@@ -2169,7 +2169,7 @@ var bulkQualifyLeads = {
         qualification_summary: responses.length > 0 ? {
           answered: responses.filter((r) => r.score != null).length,
           total: responses.length,
-          avg_score_0_to_10: avg
+          avg_qualification_boost: avg
         } : null,
         signals_count: lastWf?.content ? Object.values(lastWf.content).reduce((acc, arr) => acc + (Array.isArray(arr) ? arr.length : 0), 0) : null,
         _stillRunning: stillRunning
@@ -2194,7 +2194,7 @@ var bulkQualifyLeads = {
 var DEFAULT_CANDIDATE_COUNT = 25;
 var enrichTitles = {
   name: "leadbay_enrich_titles",
-  description: "Order contact enrichments by job title across many leads. 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. When to use: as the agent's go-to enrichment entry point. When NOT to use: to enrich a single contact \u2014 that's leadbay_enrich_contacts (granular).",
+  description: "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. When to use: as the agent's go-to enrichment entry point, immediately before proposing outreach. 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.",
   inputSchema: {
     type: "object",
     properties: {
@@ -2235,9 +2235,11 @@ var enrichTitles = {
         hint: "Set email:true (most common) or phone:true"
       };
     }
+    const explicitLeadIds = params.leadIds && params.leadIds.length > 0;
+    const selectionSource = explicitLeadIds ? "explicit" : "wishlist";
+    const lensId = params.lensId ?? await client.resolveDefaultLens();
     let leadIds = params.leadIds;
     if (!leadIds || leadIds.length === 0) {
-      const lensId = params.lensId ?? await client.resolveDefaultLens();
       const cnt = params.candidateCount ?? DEFAULT_CANDIDATE_COUNT;
       const wish = await client.request("GET", `/lenses/${lensId}/leads/wishlist?count=${Math.min(cnt, 50)}&page=0`);
       leadIds = wish.items.map((l) => l.id);
@@ -2311,9 +2313,53 @@ var enrichTitles = {
             would_launch: { titles: params.titles, email, phone }
           };
         }
+        const tracker = ctx?.bulkTracker;
+        let bulkRecord;
+        let bulkReused = false;
+        let bulkSecondsSinceOriginal;
+        if (tracker) {
+          const res = await tracker.findOrCreatePending({
+            lead_ids: leadIds,
+            titles: params.titles,
+            email,
+            phone,
+            lens_id: lensId,
+            selection_source: selectionSource
+          });
+          bulkRecord = {
+            bulk_id: res.record.bulk_id,
+            launched_at: res.record.launched_at,
+            durability: res.record.durability
+          };
+          bulkReused = res.reused;
+          bulkSecondsSinceOriginal = res.seconds_since_original;
+          if (bulkReused && res.record.status !== "failed") {
+            return {
+              mode: "already_launched",
+              re_used: true,
+              bulk_id: res.record.bulk_id,
+              launched_at: res.record.launched_at,
+              durability: res.record.durability,
+              seconds_since_original_launch: bulkSecondsSinceOriginal ?? 0,
+              titles: params.titles,
+              email,
+              phone,
+              preview,
+              message: `No new enrichment was ordered; quota not spent. An identical bulk was launched ${bulkSecondsSinceOriginal ?? 0}s ago. Poll leadbay_bulk_enrich_status with this bulk_id for results.`,
+              next_action: "Call leadbay_bulk_enrich_status({bulk_id}) to check progress; include_contacts=true for the final read."
+            };
+          }
+        }
         try {
           await client.requestVoid("POST", "/leads/selection/enrichment/launch", { titles: params.titles, email, phone });
         } catch (err) {
+          if (bulkRecord && tracker) {
+            try {
+              await tracker.markFailed(bulkRecord.bulk_id);
+            } catch (e) {
+              ctx?.logger?.warn?.(`enrich_titles: tracker.markFailed failed: ${e?.message ?? e}`);
+            }
+          }
           if (err?.code === "QUOTA_EXCEEDED") {
             return {
               status: "quota_exceeded",
@@ -2324,6 +2370,26 @@ var enrichTitles = {
           }
           throw err;
         }
+        if (bulkRecord && tracker) {
+          try {
+            await tracker.markLaunched(bulkRecord.bulk_id);
+          } catch (e) {
+            ctx?.logger?.warn?.(`enrich_titles: tracker.markLaunched failed: ${e?.message ?? e}`);
+            return {
+              mode: "launched_tracker_pending",
+              launched: true,
+              preview,
+              bulk_id: bulkRecord.bulk_id,
+              launched_at: bulkRecord.launched_at,
+              durability: bulkRecord.durability,
+              titles: params.titles,
+              email,
+              phone,
+              message: "Enrichment job launched on the backend, but the local tracker record could not be flipped to 'launched'. The bulk_id is still valid \u2014 leadbay_bulk_enrich_status will return status:'pending' until the tracker heals.",
+              next_action: "Wait ~60s, then call leadbay_bulk_enrich_status({bulk_id}). If it persists, restart the MCP."
+            };
+          }
+        }
         return {
           mode: "launched",
           preview,
@@ -2331,8 +2397,11 @@ var enrichTitles = {
           titles: params.titles,
           email,
           phone,
-          message: "Enrichment job launched. The Leadbay backend does not return a bulk_id (probed 2026-04-20) \u2014 track results by polling individual leads via leadbay_get_contacts after ~60s; contact.enrichment.done flips to true.",
-          next_action: "Wait ~60s, then call leadbay_research_lead or leadbay_get_contacts on the leads you care about."
+          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 or leadbay_get_contacts on the leads you care about."
         };
       } finally {
         try {
@@ -2347,6 +2416,523 @@ var enrichTitles = {
   }
 };
 
+// ../core/dist/jobs/bulk-store.js
+import { mkdir as mkdirAsync, lstat, open as fsOpen, readFile, rename, stat, unlink } from "fs/promises";
+import { constants as fsConstants } from "fs";
+import { dirname, resolve as resolvePath } from "path";
+import { homedir, platform } from "os";
+import { createHash, randomUUID } from "crypto";
+var DEFAULT_IDEMPOTENCY_WINDOW_MS = 5 * 60 * 1e3;
+var TTL_MS = 30 * 24 * 60 * 60 * 1e3;
+var UUIDV4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function isValidBulkId(v) {
+  return typeof v === "string" && UUIDV4_RE.test(v);
+}
+function computeIdempotencyKey(args) {
+  const parts = [
+    [...args.lead_ids].sort().join(","),
+    [...args.titles].sort().join(","),
+    args.email ? "e1" : "e0",
+    args.phone ? "p1" : "p0",
+    `l${args.lens_id}`
+  ];
+  return createHash("sha256").update(parts.join("|")).digest("hex");
+}
+function normalizeLaunchInputs(args) {
+  return {
+    lead_ids: [...new Set(args.lead_ids)].sort(),
+    titles: [...new Set(args.titles)].sort()
+  };
+}
+var AsyncMutex = class {
+  locked = false;
+  queue = [];
+  async lock() {
+    if (!this.locked) {
+      this.locked = true;
+      return;
+    }
+    return new Promise((resolve) => {
+      this.queue.push(() => {
+        this.locked = true;
+        resolve();
+      });
+    });
+  }
+  unlock() {
+    this.locked = false;
+    const next = this.queue.shift();
+    if (next)
+      next();
+  }
+  async run(fn) {
+    await this.lock();
+    try {
+      return await fn();
+    } finally {
+      this.unlock();
+    }
+  }
+};
+var LocalBulkStore = class {
+  backend;
+  path;
+  logger;
+  allowUnsafePath;
+  now;
+  mutex = new AsyncMutex();
+  memory = [];
+  // Cached file resolution — computed lazily on first access.
+  initialized = false;
+  constructor(opts) {
+    this.backend = opts.backend;
+    this.logger = opts.logger;
+    this.allowUnsafePath = !!opts.allowUnsafePath;
+    this.now = opts.now ?? Date.now;
+    if (this.backend === "file") {
+      if (!opts.path) {
+        throw new Error("LocalBulkStore: path is required when backend=file");
+      }
+      this.path = resolvePath(opts.path);
+      this.validatePath(this.path);
+    }
+  }
+  get durability() {
+    return this.backend;
+  }
+  // Exposed for tests and ops tooling.
+  get resolvedPath() {
+    return this.path;
+  }
+  validatePath(p) {
+    if (this.allowUnsafePath)
+      return;
+    const home = resolvePath(homedir());
+    if (p !== home && !p.startsWith(home + "/") && !p.startsWith(home + "\\")) {
+      throw new Error(`LocalBulkStore: path ${p} is outside $HOME (${home}). Set LEADBAY_BULK_STORE_PATH_UNSAFE=1 to override.`);
+    }
+  }
+  async ensureInitialized() {
+    if (this.initialized || this.backend !== "file") {
+      this.initialized = true;
+      return;
+    }
+    const dir = dirname(this.path);
+    await mkdirAsync(dir, { recursive: true, mode: 448 });
+    try {
+      const st = await lstat(this.path);
+      if (st.isSymbolicLink()) {
+        throw new Error(`LocalBulkStore: refusing to use ${this.path} \u2014 path is a symlink. Set LEADBAY_BULK_STORE_PATH_UNSAFE=1 to override.`);
+      }
+    } catch (err) {
+      if (err?.code !== "ENOENT")
+        throw err;
+    }
+    this.initialized = true;
+  }
+  // ─── Storage layer (file or memory) ──────────────────────────────────────
+  async readAll() {
+    if (this.backend === "memory")
+      return [...this.memory];
+    await this.ensureInitialized();
+    let raw;
+    try {
+      raw = await readFile(this.path, "utf8");
+    } catch (err) {
+      if (err?.code === "ENOENT")
+        return [];
+      throw err;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      this.logger?.warn?.(`bulk.record_dropped file_parse_failed ${err?.message ?? err}`);
+      return [];
+    }
+    if (!Array.isArray(parsed)) {
+      this.logger?.warn?.("bulk.record_dropped file_not_array");
+      return [];
+    }
+    const out = [];
+    for (const entry of parsed) {
+      try {
+        out.push(this.validateRecord(entry));
+      } catch (err) {
+        this.logger?.warn?.(`bulk.record_dropped invalid_record ${err?.message ?? err}`);
+      }
+    }
+    return out;
+  }
+  validateRecord(raw) {
+    if (!raw || typeof raw !== "object")
+      throw new Error("not an object");
+    const r = raw;
+    if (!isValidBulkId(r.bulk_id))
+      throw new Error("invalid bulk_id");
+    if (typeof r.launched_at !== "string")
+      throw new Error("missing launched_at");
+    if (!Array.isArray(r.lead_ids) || !r.lead_ids.every((x) => typeof x === "string"))
+      throw new Error("invalid lead_ids");
+    if (!Array.isArray(r.titles) || !r.titles.every((x) => typeof x === "string"))
+      throw new Error("invalid titles");
+    if (typeof r.email !== "boolean")
+      throw new Error("invalid email");
+    if (typeof r.phone !== "boolean")
+      throw new Error("invalid phone");
+    if (typeof r.lens_id !== "number")
+      throw new Error("invalid lens_id");
+    if (r.selection_source !== "explicit" && r.selection_source !== "wishlist")
+      throw new Error("invalid selection_source");
+    if (r.status !== "pending" && r.status !== "launched" && r.status !== "failed")
+      throw new Error("invalid status");
+    if (typeof r.idempotency_key !== "string")
+      throw new Error("invalid idempotency_key");
+    return {
+      bulk_id: r.bulk_id,
+      launched_at: r.launched_at,
+      lead_ids: r.lead_ids,
+      titles: r.titles,
+      email: r.email,
+      phone: r.phone,
+      lens_id: r.lens_id,
+      selection_source: r.selection_source,
+      status: r.status,
+      idempotency_key: r.idempotency_key,
+      durability: this.backend
+    };
+  }
+  async writeAll(records) {
+    if (this.backend === "memory") {
+      this.memory = records.map((r) => ({ ...r, durability: "memory" }));
+      return;
+    }
+    await this.ensureInitialized();
+    const payload = records.map((r) => ({ ...r, durability: "file" }));
+    const json = JSON.stringify(payload, null, 2);
+    const tmp = this.path + ".tmp";
+    let fh = await openTmpFileExclusive(tmp);
+    try {
+      await fh.writeFile(json, { encoding: "utf8" });
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    if (platform() === "win32") {
+      try {
+        await unlink(this.path);
+      } catch (err) {
+        if (err?.code !== "ENOENT")
+          throw err;
+      }
+    }
+    await rename(tmp, this.path);
+    try {
+      const dirFh = await fsOpen(dirname(this.path), "r");
+      try {
+        await dirFh.sync();
+      } finally {
+        await dirFh.close();
+      }
+    } catch {
+    }
+  }
+  // ─── TTL cleanup ─────────────────────────────────────────────────────────
+  prune(records) {
+    const cutoff = this.now() - TTL_MS;
+    const kept = [];
+    for (const r of records) {
+      const launched = Date.parse(r.launched_at);
+      if (Number.isFinite(launched) && launched >= cutoff) {
+        kept.push(r);
+      } else {
+        this.logger?.info?.(`bulk.ttl_dropped bulk_id=${r.bulk_id} launched_at=${r.launched_at}`);
+      }
+    }
+    return kept;
+  }
+  // ─── BulkTracker API ────────────────────────────────────────────────────
+  async findOrCreatePending(args) {
+    const { lead_ids, titles } = normalizeLaunchInputs(args);
+    const idempotency_key = computeIdempotencyKey({
+      lead_ids,
+      titles,
+      email: args.email,
+      phone: args.phone,
+      lens_id: args.lens_id
+    });
+    const window = args.idempotency_window_ms ?? DEFAULT_IDEMPOTENCY_WINDOW_MS;
+    return this.mutex.run(async () => {
+      const all = this.prune(await this.readAll());
+      const nowMs = this.now();
+      const existing = all.find((r) => r.idempotency_key === idempotency_key && r.status !== "failed" && nowMs - Date.parse(r.launched_at) < window);
+      if (existing) {
+        this.logger?.info?.(`bulk.reused bulk_id=${existing.bulk_id} seconds_since_original=${Math.round((nowMs - Date.parse(existing.launched_at)) / 1e3)}`);
+        return {
+          record: existing,
+          reused: true,
+          seconds_since_original: Math.round((nowMs - Date.parse(existing.launched_at)) / 1e3)
+        };
+      }
+      const record = {
+        bulk_id: randomUUID(),
+        launched_at: new Date(nowMs).toISOString(),
+        lead_ids,
+        titles,
+        email: args.email,
+        phone: args.phone,
+        lens_id: args.lens_id,
+        selection_source: args.selection_source,
+        status: "pending",
+        idempotency_key,
+        durability: this.backend
+      };
+      all.push(record);
+      await this.writeAll(all);
+      this.logger?.info?.(`bulk.registered bulk_id=${record.bulk_id} lens_id=${record.lens_id} lead_count=${record.lead_ids.length} titles_count=${record.titles.length} durability=${record.durability}`);
+      return { record, reused: false };
+    });
+  }
+  async markLaunched(bulk_id) {
+    return this.mutex.run(async () => {
+      const all = this.prune(await this.readAll());
+      const idx = all.findIndex((r) => r.bulk_id === bulk_id);
+      if (idx < 0) {
+        throw new Error(`bulk_id not found: ${bulk_id}`);
+      }
+      all[idx] = { ...all[idx], status: "launched" };
+      await this.writeAll(all);
+      this.logger?.info?.(`bulk.launched bulk_id=${bulk_id}`);
+      return all[idx];
+    });
+  }
+  async markFailed(bulk_id) {
+    return this.mutex.run(async () => {
+      const all = this.prune(await this.readAll());
+      const idx = all.findIndex((r) => r.bulk_id === bulk_id);
+      if (idx < 0) {
+        return;
+      }
+      all[idx] = { ...all[idx], status: "failed" };
+      await this.writeAll(all);
+      this.logger?.info?.(`bulk.launch_failed bulk_id=${bulk_id}`);
+    });
+  }
+  async get(bulk_id) {
+    return this.mutex.run(async () => {
+      const all = this.prune(await this.readAll());
+      return all.find((r) => r.bulk_id === bulk_id);
+    });
+  }
+  async list() {
+    return this.mutex.run(async () => {
+      const all = this.prune(await this.readAll());
+      return [...all].sort((a, b) => Date.parse(b.launched_at) - Date.parse(a.launched_at));
+    });
+  }
+};
+async function openTmpFileExclusive(path) {
+  try {
+    return await fsOpen(path, fsConstants.O_CREAT | fsConstants.O_WRONLY | fsConstants.O_EXCL, 384);
+  } catch (err) {
+    if (err?.code === "EEXIST") {
+      await unlink(path).catch(() => {
+      });
+      return fsOpen(path, fsConstants.O_CREAT | fsConstants.O_WRONLY | fsConstants.O_EXCL, 384);
+    }
+    throw err;
+  }
+}
+var InMemoryBulkStore = class extends LocalBulkStore {
+  constructor(opts = {}) {
+    super({ backend: "memory", logger: opts.logger, now: opts.now });
+  }
+};
+async function createDefaultBulkStore(opts = {}) {
+  const env = opts.env ?? process.env;
+  const allowMemory = env.LEADBAY_BULK_STORE_ALLOW_MEMORY === "1";
+  const allowUnsafePath = env.LEADBAY_BULK_STORE_PATH_UNSAFE === "1";
+  const path = env.LEADBAY_BULK_STORE_PATH ?? resolvePath(homedir(), ".leadbay", "bulks.json");
+  try {
+    const store = new LocalBulkStore({
+      backend: "file",
+      path,
+      logger: opts.logger,
+      allowUnsafePath
+    });
+    await store.ensureInitialized();
+    await stat(dirname(path));
+    return store;
+  } catch (err) {
+    if (!allowMemory) {
+      const msg = `bulk store init failed at ${path}: ${err?.message ?? err}. Set LEADBAY_BULK_STORE_ALLOW_MEMORY=1 to fall back to in-memory (handles won't survive MCP restart), or set LEADBAY_BULK_STORE_PATH to a writable path.`;
+      opts.logger?.error?.(msg);
+      throw new Error(msg);
+    }
+    opts.logger?.warn?.(`bulk.fallback_memory path=${path} reason=${err?.message ?? err}`);
+    return new LocalBulkStore({ backend: "memory", logger: opts.logger });
+  }
+}
+
+// ../core/dist/composite/bulk-enrich-status.js
+var STATUS_FETCH_CONCURRENCY = 5;
+async function pMap(items, fn, concurrency) {
+  const out = new Array(items.length);
+  let next = 0;
+  async function worker() {
+    while (true) {
+      const i = next++;
+      if (i >= items.length)
+        return;
+      out[i] = await fn(items[i], i);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
+  return out;
+}
+var bulkEnrichStatus = {
+  name: "leadbay_bulk_enrich_status",
+  description: "Check status + per-lead contacts for a bulk enrichment you previously launched via leadbay_enrich_titles. Returns the bulk_id, progress per lead (done/total enrichable contacts), and overall progress. When include_contacts=true (opt-in), includes each contact's email/phone/job_title/enrichment.done. 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 \u2014 that already includes enriched contacts for a single lead.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      bulk_id: {
+        type: "string",
+        description: "UUIDv4 returned by leadbay_enrich_titles at launch time. Required."
+      },
+      include_contacts: {
+        type: "boolean",
+        description: "If true, return the full contact list per lead (email, phone, enrichment.done). Default false \u2014 cheap status polls."
+      }
+    },
+    required: ["bulk_id"]
+  },
+  execute: async (client, params, ctx) => {
+    if (!isValidBulkId(params.bulk_id)) {
+      return {
+        error: true,
+        code: "BULK_INVALID_ID",
+        message: "bulk_id is not a valid UUIDv4",
+        hint: "Pass the bulk_id returned by leadbay_enrich_titles verbatim."
+      };
+    }
+    if (!ctx?.bulkTracker) {
+      return {
+        error: true,
+        code: "BULK_TRACKER_UNAVAILABLE",
+        message: "No BulkTracker configured on this MCP instance",
+        hint: "This composite requires a BulkTracker in ToolContext. Upgrade to @leadbay/mcp \u22650.3.0 or run with LEADBAY_BULK_STORE_ALLOW_MEMORY=1."
+      };
+    }
+    const includeContacts = params.include_contacts ?? false;
+    const startMs = Date.now();
+    let record;
+    try {
+      record = await ctx.bulkTracker.get(params.bulk_id);
+    } catch (err) {
+      return {
+        error: true,
+        code: "BULK_STORE_UNAVAILABLE",
+        message: `Bulk store read failed: ${err?.message ?? err}`,
+        hint: "Check the file at $LEADBAY_BULK_STORE_PATH (default ~/.leadbay/bulks.json). Set LEADBAY_BULK_STORE_ALLOW_MEMORY=1 to fall back to in-memory storage on startup (handles won't survive restart)."
+      };
+    }
+    if (!record) {
+      return {
+        error: true,
+        code: "BULK_NOT_FOUND",
+        message: "No bulk record for that bulk_id",
+        hint: "The record may have aged out (30-day TTL) or the MCP process was restarted without persistence. Launch a new enrichment via leadbay_enrich_titles."
+      };
+    }
+    if (record.status === "pending") {
+      return {
+        error: true,
+        code: "BULK_PENDING",
+        message: "Bulk is in 'pending' state \u2014 the launch is in flight or the MCP crashed between launch and ack.",
+        hint: "Retry leadbay_bulk_enrich_status in a few seconds. If it persists >60s, relaunch via leadbay_enrich_titles.",
+        bulk_id: record.bulk_id,
+        launched_at: record.launched_at
+      };
+    }
+    if (record.status === "failed") {
+      return {
+        error: true,
+        code: "BULK_LAUNCH_FAILED",
+        message: "The original /enrichment/launch POST failed; no backend enrichment was ordered.",
+        hint: "Call leadbay_enrich_titles again \u2014 the failed record won't block a fresh launch.",
+        bulk_id: record.bulk_id,
+        launched_at: record.launched_at
+      };
+    }
+    const results = await pMap(record.lead_ids, async (leadId) => {
+      try {
+        const out = await getContacts.execute(client, { leadId });
+        const contacts = Array.isArray(out?.contacts) ? out.contacts : [];
+        const enrichable = contacts.filter((c) => c && c.enrichment);
+        const done = enrichable.filter((c) => c.enrichment?.done === true).length;
+        const total = enrichable.length;
+        return {
+          kind: "ok",
+          lead_id: leadId,
+          done,
+          total,
+          contacts: includeContacts ? contacts : void 0
+        };
+      } catch (err) {
+        return {
+          kind: "fail",
+          lead_id: leadId,
+          code: err?.code ?? "UNKNOWN",
+          retry_after: err?._meta?.retry_after
+        };
+      }
+    }, STATUS_FETCH_CONCURRENCY);
+    const leads = [];
+    const partialFailures = [];
+    let totalDone = 0;
+    let totalAll = 0;
+    for (const r of results) {
+      if (r.kind === "fail") {
+        partialFailures.push({
+          lead_id: r.lead_id,
+          code: r.code,
+          ...r.retry_after !== void 0 ? { retry_after: r.retry_after } : {}
+        });
+        continue;
+      }
+      leads.push({
+        lead_id: r.lead_id,
+        ...r.contacts ? { contacts: r.contacts } : {},
+        enrichment_progress: { done: r.done, total: r.total }
+      });
+      totalDone += r.done;
+      totalAll += r.total;
+    }
+    const overallProgress = {
+      done: totalDone,
+      total: totalAll,
+      done_ratio: totalAll === 0 ? 0 : totalDone / totalAll
+    };
+    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}`);
+    return {
+      bulk_id: record.bulk_id,
+      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,
+      overall_progress: overallProgress,
+      all_done: allDone,
+      ...partialFailures.length > 0 ? { partial_failures: partialFailures } : {}
+    };
+  }
+};
+
 // ../core/dist/composite/adjust-audience.js
 function tokens(s) {
   return s.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
@@ -2924,6 +3510,7 @@ var compositeReadTools = [
   researchLead,
   recallOrderedTitles,
   accountStatus,
+  bulkEnrichStatus,
   // Keep the existing composites available too.
   researchCompany,
   prepareOutreach
@@ -2996,6 +3583,11 @@ export {
   accountStatus,
   bulkQualifyLeads,
   enrichTitles,
+  isValidBulkId,
+  LocalBulkStore,
+  InMemoryBulkStore,
+  createDefaultBulkStore,
+  bulkEnrichStatus,
   adjustAudience,
   refinePrompt,
   answerClarification,

package/dist/{dist-PIXZN6N4.js → dist-FENQ2I7R.js}

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 import {
+  InMemoryBulkStore,
   LeadbayClient,
+  LocalBulkStore,
   REGIONS,
   accountStatus,
   addNote,
   adjustAudience,
   answerClarification,
+  bulkEnrichStatus,
   bulkQualifyLeads,
   clearMockJournal,
   clearSelection,
@@ -14,6 +17,7 @@ import {
   compositeTools,
   compositeWriteTools,
   createClient,
+  createDefaultBulkStore,
   createLens,
   createLensDraft,
   deselectLeads,
@@ -40,6 +44,7 @@ import {
   granularReadTools,
   granularTools,
   granularWriteTools,
+  isValidBulkId,
   launchBulkEnrichment,
   listLenses,
   listSectors,
@@ -64,14 +69,17 @@ import {
   tools,
   updateLens,
   updateLensFilter
-} from "./chunk-BGJ6JWIO.js";
+} from "./chunk-FJBO2MY2.js";
 export {
+  InMemoryBulkStore,
   LeadbayClient,
+  LocalBulkStore,
   REGIONS,
   accountStatus,
   addNote,
   adjustAudience,
   answerClarification,
+  bulkEnrichStatus,
   bulkQualifyLeads,
   clearMockJournal,
   clearSelection,
@@ -80,6 +88,7 @@ export {
   compositeTools,
   compositeWriteTools,
   createClient,
+  createDefaultBulkStore,
   createLens,
   createLensDraft,
   deselectLeads,
@@ -106,6 +115,7 @@ export {
   granularReadTools,
   granularTools,
   granularWriteTools,
+  isValidBulkId,
   launchBulkEnrichment,
   listLenses,
   listSectors,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leadbay/mcp",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Model Context Protocol (MCP) server for Leadbay — AI lead discovery, qualification, and enrichment for Claude Desktop, Cursor, and Claude Code.",
   "type": "module",
   "bin": {
@@ -27,6 +27,7 @@
     "@modelcontextprotocol/sdk": "1.29.0"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.40.0",
     "@leadbay/core": "workspace:*"
   },
   "engines": {