salesprompter-cli 0.1.20 → 0.1.22

package/README.md

@@ -1,338 +1,58 @@
 # salesprompter-cli
 
-`salesprompter-cli` is a JSON-first command line interface for running a practical sales workflow:
+Salesprompter CLI helps you go from company or product input to qualified leads with a guided terminal flow.
 
-- Authenticate via Salesprompter app backend
-- Crawl LinkedIn product categories
-- Derive intended-role job titles
-- Split broad Sales Navigator searches into exportable slices
-- Export those slices through Phantombuster
-- Store product and people data in Salesprompter
-- Enrich leads
-- Score leads
-- Sync leads into CRM and outreach systems
-- Analyze upstream lead-list and domain-enrichment bottlenecks
-- Replace opaque Pipedream logic with deterministic CLI workflows
-
-It is built for two users at the same time:
-
-- humans working in a terminal
-- coding agents such as Codex, Claude Code, and other LLM-driven shell workflows
-
-The app, CLI, and Chrome extension all write into one shared Salesprompter backend and database. Access is scoped to
-the active workspace you choose at login.
-
-## Start Here
-
-If someone discovers Salesprompter from a vague prompt, give them the shortest working path for their context.
-
-```bash
-## Human-friendly guided path
-npx -y salesprompter-cli@latest
-
-## Explicit guided path
-npx -y salesprompter-cli@latest wizard
-
-## Primary raw command for agents and scripts
-npx -y salesprompter-cli@latest salesnav:from-product-category --input deel.com --dry-run
-```
-
-Or install it globally:
-
-```bash
-npm install -g salesprompter-cli
-salesprompter
-salesprompter wizard
-salesprompter --help
-```
-
-Bare `salesprompter` now opens a guided wizard in an interactive terminal. Keep using explicit subcommands for agents, CI, and copy-paste docs.
-If your Salesprompter user belongs to multiple workspaces, browser login asks which workspace the CLI session should use.
-
-## Prompt To Command
-
-The primary live path is:
-
-1. crawl a LinkedIn product category
-2. derive the intended job titles
-3. turn those into Sales Navigator queries
-4. split broad searches into exportable chunks
-5. export them through Phantombuster
-6. store everything in Salesprompter
-
-### "I sell for Deel and want the right people at similar companies"
-
-Start from the company, product, or category input:
+## Install
 
 ```bash
-salesprompter salesnav:from-product-category --input deel.com
+npm i -g salesprompter-cli
 ```
 
-The CLI now stays attached while durable title crawls are still running remotely, writes JSONL trace logs, and exits non-zero if any title crawl finishes with failures. Use `--allow-partial-success` only when you explicitly want a best-effort run.
-
-Preview the generated titles and first split queries before creating crawl jobs:
+or run directly:
 
 ```bash
-salesprompter --json salesnav:from-product-category --input deel.com --dry-run
-```
-
-### "Find people at deel.com"
-
-That is still a direct target-company lookup:
-
-```bash
-salesprompter account:resolve --domain deel.com --company-name Deel --out ./data/deel-account.json
-salesprompter leads:generate --icp ./data/icp.json --count 5 --domain deel.com --company-name Deel --out ./data/deel-leads.json
-```
-
-### Historical warehouse fallback
-
-`salesnav:ensure-count` remains a historical backfill path, not the primary workflow:
-
-```bash
-salesprompter salesnav:ensure-count --target-count 200000 --org-id "$SALESPROMPTER_ORG_ID"
-```
-
-## Documentation
-
-This repository now includes the public Salesprompter docs site for the wider Salesprompter universe, including the app contract, CLI surface, Chrome extension contract, and the main warehouse-backed workflows.
-
-- Live docs: `https://salesprompter-cli.vercel.app`
-
-- Docs home: `./index.mdx`
-- Quickstart: `./quickstart.mdx`
-- Architecture: `./architecture.mdx`
-- App: `./platform/app.mdx`
-- CLI: `./platform/cli.mdx`
-- Chrome extension: `./platform/chrome-extension.mdx`
-- Domain finder: `./workflows/domain-finder.mdx`
-- Command reference: `./reference/cli.mdx`
-- Environment variables: `./reference/environment-variables.mdx`
-- Troubleshooting: `./operations/troubleshooting.mdx`
-
-Run the docs locally with:
-
-```bash
-npm run docs:dev
+npx -y salesprompter-cli@latest
 ```
 
-Build the deployable static docs site with:
+## Quickstart
 
 ```bash
-npm run build:docs:site
-```
-
-## Integration Contract
-
-This CLI is not a standalone toy. It is a production integration surface for the Salesprompter app.
-
-- The Domain Finder flow in this repository is a real end-to-end test case for Salesprompter app integration.
-- CLI behavior should be treated as an app contract: auth, BigQuery execution, artifacts, and writeback semantics must remain stable.
-- Changes to domain selection, writeback, or audit logic should always be validated with:
-  - CLI tests (`npm test`)
-  - BigQuery-backed runs (`domainfinder:run:bq`, `domainfinder:audit-existing:bq`)
-  - before/after delta checks (`domainfinder:audit-delta`)
-
-The current live path is product-first. It resolves a LinkedIn product category, derives intended-role Sales Navigator searches, and lets the app run durable exports through Phantombuster. Account-first lead generation still exists for direct target-company lookups.
-
-When the output `mode` is `fallback`, the leads are modeled contacts for workflow testing, not verified real contacts. A real provider path should return `mode: "real"` using the same JSON shape.
-
-All non-auth commands require a logged-in CLI session. This gives you one identity model across Salesprompter app, CLI, and Chrome extension.
-
-Global output flags:
-
-- `--json`: compact machine-readable JSON (optimized for agent/LLM parsers)
-- `--quiet`: suppress successful stdout payloads (errors still surface)
-
-## Auth and Session
-
-The CLI stores a local session file at `~/.config/salesprompter/auth-session.json` (or `SALESPROMPTER_CONFIG_DIR`).
+# Start the interactive wizard
+salesprompter
 
-```bash
-# Preferred path: browser/device login
+# Login explicitly
 salesprompter auth:login
 
-# Fallback path: generate a short-lived CLI token in the Salesprompter app
-salesprompter auth:login --token "$SALESPROMPTER_TOKEN" --api-url "https://salesprompter.ai"
-
-# Verify active identity with backend
-salesprompter auth:whoami --verify
-
-# Clear local session
-salesprompter auth:logout
-```
-
-If your user belongs to multiple workspaces, the browser flow asks you to choose the workspace for that CLI session before returning to the terminal.
-
-Environment variables:
-
-- `SALESPROMPTER_API_BASE_URL`: override backend URL (default `https://salesprompter.ai`)
-- `SALESPROMPTER_CONFIG_DIR`: override local config dir
-- `SALESPROMPTER_ORG_ID`: optional org override for privileged Sales Navigator backfills
-- `SALESPROMPTER_SKIP_AUTH=1`: bypass auth guard (tests/dev only)
-- `INSTANTLY_API_KEY`: required for real `sync:outreach --target instantly`
-- `INSTANTLY_CAMPAIGN_ID`: default campaign id for Instantly sync
-- `SALESPROMPTER_INSTANTLY_BASE_URL`: override Instantly API base URL (tests/local proxies)
-- `NEXT_PUBLIC_SUPABASE_URL` or `SALESPROMPTER_SUPABASE_URL`: required for `salesnav:ensure-count` and for CLI-managed Sales Navigator exports
-- `SUPABASE_SERVICE_ROLE_KEY`: required for `salesnav:ensure-count` and for CLI-managed Sales Navigator exports
-- `LINKEDIN_SESSION_COOKIE_ENCRYPTION_KEY` or `EXTENSION_AUTH_SECRET` or `CLERK_SECRET_KEY`: required for Sales Navigator export and crawl commands that launch exports
-- `SALESPROMPTER_LINKEDIN_SESSION_EXCLUDED_EMAILS`: optional comma-separated emails to keep out of CLI-managed Sales Navigator rotation
-- `SALESPROMPTER_LINKEDIN_SESSION_EXCLUDED_HANDLES`: optional comma-separated LinkedIn handles to keep out of CLI-managed Sales Navigator rotation
-- `SALESPROMPTER_CLI_MANAGE_LINKEDIN_SESSIONS=0`: optional test or legacy fallback override; when omitted, the CLI claims, rotates, and preflights Sales Navigator session cookies before export launch
-- `GOOGLE_SERVICE_ACCOUNT_KEY`: required for `salesnav:ensure-count`
-- `BIGQUERY_PROJECT_ID`: optional when the Google service-account JSON already includes `project_id`
-
-App compatibility:
-
-- Salesprompter app should expose `/api/cli/auth/device/start`, `/api/cli/auth/device/poll`, and `/api/cli/auth/me`.
-- `salesprompter auth:login` uses browser/device login and prints the verification URL plus code before polling.
-- `POST /api/cli/auth/token` remains the fallback path when browser/device login is disabled or unavailable.
-
-Fallback command:
-
-```bash
-salesprompter auth:login --token "<token-from-app>" --api-url "https://salesprompter.ai"
+# Verify your session
+salesprompter auth:whoami
 ```
 
-## Why this shape works for humans and LLMs
-
-- Every command reads and writes plain JSON.
-- Output is machine-readable and composable (`--json` for compact transport).
-- The top-level use cases map ambiguous prompts like "determine the ICP of deel.com" into explicit command paths.
-- Domain contracts are explicit and validated with `zod`.
-- External integrations are behind narrow provider interfaces.
-- Lead generation reports which provider and mode produced the result.
-- Workflow bottlenecks become inspectable artifacts instead of hidden Pipedream state.
-- Real prospect lookup can be normalized straight into the CLI lead schema with `--lead-out`.
-
-## Commands
+## Common commands
 
 ```bash
-salesprompter icp:define --name "EU SaaS RevOps" \
-  --description "RevOps and sales leaders in European growth-stage software companies" \
-  --industries "Software,Financial Services" \
-  --company-sizes "50-199,200-499" \
-  --regions "Europe" \
-  --countries "DE,NL,GB" \
-  --titles "Head of Revenue Operations,VP Sales" \
-  --required-signals "recent funding,growing outbound team" \
-  --keywords "revenue operations,outbound,sales tooling" \
-  --out ./data/icp.json
+# Product/category to leads workflow
+salesprompter salesnav:from-product-category --input "https://www.linkedin.com/company/example/"
 
-salesprompter auth:login
-salesprompter auth:whoami --verify
-salesprompter --json salesnav:from-product-category --input deel.com --dry-run
-salesprompter salesnav:from-product-category --input deel.com
-# Historical fallback only. Resumes from prior CLI historical backfill runs unless you pass --start-offset.
-salesprompter salesnav:ensure-count --target-count 200000 --org-id "$SALESPROMPTER_ORG_ID"
+# Run a Sales Navigator crawl from a query URL
 salesprompter salesnav:crawl --query-url "https://www.linkedin.com/sales/search/people?query=..."
-salesprompter icp:vendor --vendor deel --market dach --out ./data/deel-icp.json
-salesprompter leads:lookup:bq --icp ./data/deel-icp.json --limit 100 --execute --out ./data/deel-leads-raw.json --lead-out ./data/deel-leads.json
-salesprompter leads:enrich --in ./data/deel-leads.json --out ./data/deel-enriched.json
-salesprompter leads:score --icp ./data/deel-icp.json --in ./data/deel-enriched.json --out ./data/deel-scored.json
-salesprompter sync:outreach --target instantly --in ./data/deel-scored.json --campaign-id "$INSTANTLY_CAMPAIGN_ID"
-salesprompter sync:outreach --target instantly --in ./data/deel-scored.json --campaign-id "$INSTANTLY_CAMPAIGN_ID" --apply
-salesprompter icp:from-historical-queries:bq --vendor deel --market dach --out ./data/deel-icp-historical.json --report-out ./data/deel-historical-report.json
-salesprompter leadlists:funnel:bq --vendor deel --market dach --out ./data/deel-leadlists-funnel.json
-salesprompter leadlists:direct-export:bq --vendor deel --market dach --limit 20000 --out-dir ./data/direct-path --sql-out ./data/direct-path/deel-direct-dach.sql
-salesprompter domainfinder:backlog:bq --market dach --out ./data/deel-domainfinder-backlog.json
-salesprompter domainfinder:candidates:bq --market dach --limit 500 --out ./data/domain-candidates.json --sql-out ./data/domain-candidates.sql
-salesprompter domainfinder:input-sql --market dach --out ./data/domainFinder_input_v2.sql
-salesprompter domainfinder:select --in ./data/domain-candidates.json --out ./data/domain-decisions.json
-salesprompter domainfinder:audit --in ./data/domain-decisions.json --out ./data/domain-audit.json
-salesprompter domainfinder:compare-pipedream --in ./data/domain-candidates.json --out ./data/domain-comparison.json
-salesprompter domainfinder:audit-existing:bq --market dach --out ./data/domain-existing-audit.json
-salesprompter domainfinder:audit-delta --before ./data/domain-existing-audit-before.json --after ./data/domain-existing-audit-after.json --out ./data/domain-existing-audit-delta.json
-salesprompter domainfinder:repair-existing:bq --market dach --mode conservative --limit 5000 --out ./data/domain-repair.sql --trace-id salesprompter-cli-repair-dach
-salesprompter domainfinder:writeback-sql --in ./data/domain-decisions.json --out ./data/domain-writeback.sql --trace-id salesprompter-cli-dach-20260308
-salesprompter domainfinder:writeback:bq --in ./data/domain-decisions.json --out ./data/domain-writeback.sql --trace-id salesprompter-cli-dach-20260308
-salesprompter domainfinder:run:bq --market dach --limit 500 --out-dir ./data/domainfinder-run --trace-id salesprompter-cli-dach-20260308
-salesprompter account:resolve --domain deel.com --company-name Deel --out ./data/deel-account.json
-salesprompter leads:generate --icp ./data/icp.json --count 5 --out ./data/leads.json
-salesprompter leads:generate --icp ./data/icp.json --count 5 --domain deel.com --company-name Deel --out ./data/deel-leads.json
-salesprompter leads:enrich --in ./data/leads.json --out ./data/enriched.json
-salesprompter leads:score --icp ./data/icp.json --in ./data/enriched.json --out ./data/scored.json
-salesprompter leads:lookup:bq --icp ./data/deel-icp.json --limit 100
-salesprompter queries:analyze:bq --search-kind sales-people --include-function "Human Resources" --out ./data/hr-query-report.json
-salesprompter sync:crm --target hubspot --in ./data/scored.json
-salesprompter sync:outreach --target instantly --in ./data/scored.json
-```
-
-## Domain Finder Migration
-
-The original Pipedream `domainFinder` workflow was doing three things:
-
-1. fetch a small input set from BigQuery
-2. ask OpenAI / Hunter for candidate domains
-3. pick a domain and write it back
-
-The CLI now models that logic directly and improves it:
 
-- `domainfinder:backlog:bq` measures whether the backlog is being starved before enrichment
-- `domainfinder:candidates:bq` fetches real candidate rows from BigQuery for backlog companies
-- `domainfinder:input-sql` generates a replacement input view driven by `linkedin_companies`, not `leadPool_new`
-- `domainfinder:select` applies deterministic domain selection rules
-- `domainfinder:audit` turns decisions into a review queue and writeback summary
-- `domainfinder:compare-pipedream` quantifies how often the old selector would disagree with the improved selector
-- `domainfinder:audit-existing:bq` measures current warehouse-visible mismatches and bad chosen domains
-- `domainfinder:audit-delta` compares two audit snapshots and reports metric deltas
-- `domainfinder:repair-existing:bq` generates (and optionally executes) targeted repair writes with selectable mode:
-  - `conservative`: only missing/blacklisted chosen domains
-  - `aggressive`: missing/blacklisted plus all mismatches
-  - `mismatch-only`: only mismatched chosen domains
-- `domainfinder:writeback-sql` emits conservative SQL for `domainFinder_output`
-- `domainfinder:writeback:bq` can execute that writeback in BigQuery when explicitly asked
-- `domainfinder:run:bq` runs the full candidate -> decision -> audit -> writeback pipeline and stores all artifacts
-
-Improved selection policy:
-
-1. prefer `domain_linkedin` when present and not blacklisted
-2. otherwise prefer `website_linkedin` root domain when present and not blacklisted
-3. otherwise choose the non-blacklisted candidate with the highest Hunter email count
-4. otherwise fall back to the first non-null candidate
-
-This removes the earlier failure mode where OpenAI or Hunter could override a good LinkedIn domain purely because of a higher Hunter count.
-
-Writeback policy:
-
-- write to `SalesPrompter.domainFinder_output`, which is the source feeding `linkedin_companies.domain`
-- exclude `no-domain` decisions
-- exclude blacklisted domains from generated writeback SQL
-- preserve batch provenance through `trace_id`
-
-## Development
-
-```bash
-npm install
-npm run build
-node ./dist/cli.js --help
-npm test
+# Check crawl status
+salesprompter salesnav:crawl:status --job-id "<job-id>"
 ```
 
-BigQuery project selection:
-
-- The CLI runs `bq query` with `--project_id` from `BQ_PROJECT_ID`.
-- Fallback order: `BQ_PROJECT_ID` -> `GOOGLE_CLOUD_PROJECT` -> `GCLOUD_PROJECT` -> `icpidentifier`.
-
-## Real Deel Flow
+## Output modes
 
-For Deel as the vendor you sell for, do not use `--domain deel.com`. That path targets contacts at Deel itself.
+- `--json` for machine-readable output
+- `--quiet` to suppress successful payload output
 
-Use this path instead:
+## Notes
 
-1. `salesprompter icp:vendor --vendor deel --market dach --out ./data/deel-icp.json`
-2. `salesprompter leads:lookup:bq --icp ./data/deel-icp.json --limit 100 --execute --out ./data/deel-leads-raw.json --lead-out ./data/deel-leads.json`
-3. `salesprompter leads:enrich --in ./data/deel-leads.json --out ./data/deel-enriched.json`
-4. `salesprompter leads:score --icp ./data/deel-icp.json --in ./data/deel-enriched.json --out ./data/deel-scored.json`
-5. `salesprompter sync:outreach --target instantly --in ./data/deel-scored.json --campaign-id "$INSTANTLY_CAMPAIGN_ID"`
-6. Add `--apply` only when the dry-run output looks correct.
+- Use your own authorized LinkedIn / Sales Navigator access.
+- Respect LinkedIn and provider terms.
+- The CLI is designed for interactive users and agent-assisted workflows.
 
-## Next integrations
+## Links
 
-- Replace `HeuristicCompanyProvider` with a real account lookup provider.
-- Replace `HeuristicPeopleSearchProvider` with Apollo, Clay, LinkedIn, or custom people-data providers.
-- Replace `HeuristicEnrichmentProvider` with enrichment APIs such as Clearbit, FullEnrich, or custom LLM workflows.
-- Replace `DryRunSyncProvider` with real HubSpot, Salesforce, Pipedrive, Instantly, Apollo, or Outreach clients.
-- Add provider selection and credentials for a first real `--domain deel.com` workflow.
-- Replace configurable `bq` field mapping with a typed adapter per warehouse schema.
-- Add a real candidate-fetch command that reads domain candidates from BigQuery and feeds them into `domainfinder:select`.
+- Docs: https://salesprompter-cli.vercel.app
+- App: https://salesprompter.ai
+- Repository: https://github.com/danielsinewe/salesprompter-cli

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { access, appendFile, mkdir } from "node:fs/promises";
+import { access, appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
+import os from "node:os";
 import path from "node:path";
 import { emitKeypressEvents } from "node:readline";
 import { createInterface } from "node:readline/promises";
@@ -19,6 +20,7 @@ import { analyzeHistoricalQueries } from "./historical-queries.js";
 import { buildHistoricalVendorIcp, buildVendorIcp } from "./icp-templates.js";
 import { InstantlySyncProvider } from "./instantly.js";
 import { crawlLinkedInProductCategory } from "./linkedin-products.js";
+import { claimValidatedSalesNavigatorSessionCookieForCli } from "./linkedin-session.js";
 import { buildLeadlistsFunnelQueries } from "./leadlists-funnel.js";
 import { readJsonFile, splitCsv, writeJsonFile, writeTextFile } from "./io.js";
 import { buildSalesNavigatorCrawlPreview, createSalesNavigatorCrawlSeed, DEFAULT_SALES_NAVIGATOR_CRAWL_DIMENSIONS, buildSalesNavigatorPeopleSlice, deriveSalesNavigatorTitleQuerySeeds, expandSalesNavigatorCrawlAttempt, SalesNavigatorSliceTooBroadError } from "./sales-navigator.js";
@@ -783,29 +785,10 @@ function summarizeSalesNavigatorQuery(url, appliedFilters) {
         appliedFilters
     };
 }
-function extractSalesNavigatorFilterTypes(url, appliedFilters) {
-    const filterTypes = new Set(appliedFilters.map((filter) => filter.type));
-    const decodedQuery = decodeSalesNavigatorQueryParam(url) ?? "";
-    for (const match of decodedQuery.matchAll(/type:([A-Z_]+)/g)) {
-        const value = match[1]?.trim();
-        if (value) {
-            filterTypes.add(value);
-        }
-    }
-    return [...filterTypes];
-}
 function shouldPreSplitSalesNavigatorRootSlice(slice, maxSplitDepth) {
-    if (slice.depth !== 0 || slice.splitTrail.length > 0) {
-        return false;
-    }
-    if (!nextSalesNavigatorSplitDimension(slice, maxSplitDepth)) {
-        return false;
-    }
-    const filterTypes = new Set(extractSalesNavigatorFilterTypes(slice.slicedQueryUrl, slice.appliedFilters));
-    if (!filterTypes.has("CURRENT_TITLE")) {
-        return false;
-    }
-    return !DEFAULT_SALES_NAVIGATOR_CRAWL_DIMENSIONS.some((dimension) => filterTypes.has(dimension.filterType));
+    void slice;
+    void maxSplitDepth;
+    return false;
 }
 function buildTraceHeaders(traceId) {
     return traceId ? { "X-Salesprompter-Trace-Id": traceId } : {};
@@ -1632,6 +1615,10 @@ async function runSalesNavigatorCrawlAttempt(session, attempt, options, context)
     if (totalResults === null || totalResults > attempt.maxResultsPerSearch) {
         return probeResult;
     }
+    const splitTriggerResults = Math.min(attempt.maxResultsPerSearch, SALES_NAVIGATOR_SPLIT_TRIGGER_RESULTS);
+    if (totalResults > splitTriggerResults) {
+        throw new SalesNavigatorSliceTooBroadError(`Sales Navigator slice produced ${totalResults} results, exceeding the split trigger of ${splitTriggerResults}.`, { totalResults });
+    }
     return await runSalesNavigatorExportWithAgentWait(session, {
         sourceQueryUrl: attempt.sourceQueryUrl,
         slicedQueryUrl: attempt.slicedQueryUrl,
@@ -1731,10 +1718,112 @@ function nextSalesNavigatorSplitDimension(slice, maxSplitDepth) {
     if (slice.depth >= maxSplitDepth) {
         return null;
     }
-    return DEFAULT_SALES_NAVIGATOR_CRAWL_DIMENSIONS[slice.depth] ?? null;
+    const usedDimensionKeys = new Set(slice.splitTrail.map((entry) => entry.key));
+    const orderedDimensions = getLearnedSalesNavigatorDimensionOrder();
+    return orderedDimensions.find((dimension) => !usedDimensionKeys.has(dimension.key)) ?? null;
 }
 const SALES_NAVIGATOR_COOKIE_RETRY_LIMIT = 8;
 const SALES_NAVIGATOR_RESULT_RETRY_LIMIT = 3;
+const SALES_NAVIGATOR_SPLIT_TRIGGER_RESULTS = 1500;
+const SALES_NAVIGATOR_FILTER_IMPACT_MIN_OBSERVATIONS = 3;
+let salesNavigatorFilterImpactModel = null;
+let salesNavigatorFilterImpactLoaded = false;
+function getSalesprompterConfigDir() {
+    const override = process.env.SALESPROMPTER_CONFIG_DIR?.trim();
+    if (override !== undefined && override.length > 0) {
+        return override;
+    }
+    return path.join(os.homedir(), ".config", "salesprompter");
+}
+function getSalesNavigatorFilterImpactPath() {
+    return path.join(getSalesprompterConfigDir(), "salesnav-filter-impact.json");
+}
+async function loadSalesNavigatorFilterImpactModel() {
+    if (salesNavigatorFilterImpactLoaded) {
+        return salesNavigatorFilterImpactModel;
+    }
+    salesNavigatorFilterImpactLoaded = true;
+    const filePath = getSalesNavigatorFilterImpactPath();
+    try {
+        const content = await readFile(filePath, "utf8");
+        const parsed = JSON.parse(content);
+        if (parsed && parsed.version === 1 && parsed.dimensions && typeof parsed.dimensions === "object") {
+            salesNavigatorFilterImpactModel = parsed;
+        }
+    }
+    catch {
+        salesNavigatorFilterImpactModel = null;
+    }
+    return salesNavigatorFilterImpactModel;
+}
+async function persistSalesNavigatorFilterImpactModel() {
+    if (!salesNavigatorFilterImpactModel) {
+        return;
+    }
+    const filePath = getSalesNavigatorFilterImpactPath();
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(salesNavigatorFilterImpactModel, null, 2)}\n`, "utf8");
+}
+function getLearnedSalesNavigatorDimensionOrder() {
+    const model = salesNavigatorFilterImpactModel;
+    if (!model) {
+        return DEFAULT_SALES_NAVIGATOR_CRAWL_DIMENSIONS;
+    }
+    const defaultIndex = new Map(DEFAULT_SALES_NAVIGATOR_CRAWL_DIMENSIONS.map((dimension, index) => [dimension.key, index]));
+    return [...DEFAULT_SALES_NAVIGATOR_CRAWL_DIMENSIONS].sort((left, right) => {
+        const leftStats = model.dimensions[left.key];
+        const rightStats = model.dimensions[right.key];
+        const leftReliable = (leftStats?.observations ?? 0) >= SALES_NAVIGATOR_FILTER_IMPACT_MIN_OBSERVATIONS;
+        const rightReliable = (rightStats?.observations ?? 0) >= SALES_NAVIGATOR_FILTER_IMPACT_MIN_OBSERVATIONS;
+        if (leftReliable && rightReliable) {
+            const delta = (leftStats?.avgResults ?? Number.POSITIVE_INFINITY) -
+                (rightStats?.avgResults ?? Number.POSITIVE_INFINITY);
+            if (delta !== 0) {
+                return delta;
+            }
+        }
+        else if (leftReliable !== rightReliable) {
+            return leftReliable ? -1 : 1;
+        }
+        return (defaultIndex.get(left.key) ?? 0) - (defaultIndex.get(right.key) ?? 0);
+    });
+}
+async function recordSalesNavigatorFilterImpactObservation(slice, totalResults, options) {
+    if (totalResults === null || totalResults === undefined || !Number.isFinite(totalResults)) {
+        return;
+    }
+    const learnedDimension = slice.splitTrail.at(-1)?.key ?? null;
+    if (!learnedDimension) {
+        return;
+    }
+    await loadSalesNavigatorFilterImpactModel();
+    if (!salesNavigatorFilterImpactModel) {
+        salesNavigatorFilterImpactModel = {
+            version: 1,
+            updatedAt: new Date().toISOString(),
+            dimensions: {}
+        };
+    }
+    const previous = salesNavigatorFilterImpactModel.dimensions[learnedDimension];
+    const observations = (previous?.observations ?? 0) + 1;
+    const sumResults = (previous?.sumResults ?? 0) + totalResults;
+    const avgResults = sumResults / observations;
+    salesNavigatorFilterImpactModel.dimensions[learnedDimension] = {
+        observations,
+        sumResults,
+        avgResults,
+        lastObservedAt: new Date().toISOString()
+    };
+    salesNavigatorFilterImpactModel.updatedAt = new Date().toISOString();
+    await persistSalesNavigatorFilterImpactModel();
+    await options?.logger?.log("salesnav.filter_impact.updated", {
+        dimensionKey: learnedDimension,
+        observations,
+        avgResults,
+        totalResults,
+        outcome: options?.outcome ?? null
+    });
+}
 function buildSalesNavigatorSplitChildren(slice, dimension) {
     const attempt = buildSalesNavigatorCrawlAttemptFromClaimedSlice(slice);
     return expandSalesNavigatorCrawlAttempt(attempt, dimension).map((child) => ({
@@ -1812,6 +1901,42 @@ function buildSalesNavigatorSliceFailureReport(slice, error, options) {
 function formatSalesNavigatorSplitTrail(splitTrail) {
     return splitTrail.map((entry) => `${entry.key}:${entry.value.text}`);
 }
+async function ensureSalesNavigatorSessionPoolReady(queryUrl, options) {
+    try {
+        await options.logger?.log("salesnav.session_pool.preflight.started", {
+            source: options.source,
+            queryUrl
+        });
+        const claimed = await claimValidatedSalesNavigatorSessionCookieForCli({
+            queryUrl,
+            source: options.source,
+            env: process.env
+        });
+        await options.logger?.log("salesnav.session_pool.preflight.completed", {
+            source: options.source,
+            queryUrl,
+            status: claimed ? "ok" : "skipped",
+            selectedSessionUserEmail: claimed?.userEmail ?? null,
+            selectedSessionUserHandle: claimed?.userHandle ?? null,
+            selectedSessionCookieSha256: claimed?.sessionCookieSha256 ?? null
+        });
+        return {
+            ready: true
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        await options.logger?.log("salesnav.session_pool.preflight.failed", {
+            source: options.source,
+            queryUrl,
+            error: message
+        });
+        return {
+            ready: false,
+            error: message
+        };
+    }
+}
 async function processSalesNavigatorClaimedCrawlSlice(session, jobId, slice, options) {
     let currentSession = session;
     await options.logger?.log("salesnav.crawl.slice.claimed", {
@@ -1869,7 +1994,8 @@ async function processSalesNavigatorClaimedCrawlSlice(session, jobId, slice, opt
                     error: `Pre-split by ${nextDimension.key}`,
                     errorCode: "presplit_root_title_query",
                     totalResults: null
-                }
+                },
+                forceSessionPoolRecheck: false
             };
         }
     }
@@ -1909,6 +2035,10 @@ async function processSalesNavigatorClaimedCrawlSlice(session, jobId, slice, opt
             })
         }, options.traceId);
         currentSession = reported.session;
+        await recordSalesNavigatorFilterImpactObservation(slice, result.totalResults ?? null, {
+            logger: options.logger,
+            outcome: "exported"
+        });
         await options.logger?.log("salesnav.crawl.slice.exported", {
             jobId,
             sliceId: slice.id,
@@ -1927,7 +2057,8 @@ async function processSalesNavigatorClaimedCrawlSlice(session, jobId, slice, opt
                 outcome: "exported",
                 runId: result.runId,
                 totalResults: result.totalResults ?? null
-            }
+            },
+            forceSessionPoolRecheck: false
         };
     }
     catch (error) {
@@ -1956,6 +2087,10 @@ async function processSalesNavigatorClaimedCrawlSlice(session, jobId, slice, opt
         });
         const reported = await reportSalesNavigatorCrawlSlice(currentSession, jobId, payload, options.traceId);
         currentSession = reported.session;
+        await recordSalesNavigatorFilterImpactObservation(slice, payload.totalResults ?? null, {
+            logger: options.logger,
+            outcome: payload.outcome
+        });
         await options.logger?.log("salesnav.crawl.slice.reported", {
             jobId,
             sliceId: slice.id,
@@ -1976,11 +2111,13 @@ async function processSalesNavigatorClaimedCrawlSlice(session, jobId, slice, opt
                 error: payload.error,
                 errorCode: payload.errorCode,
                 totalResults: payload.totalResults
-            }
+            },
+            forceSessionPoolRecheck: payload.errorCode === "invalid_session"
         };
     }
 }
 async function executeSalesNavigatorCrawlJob(session, jobId, options) {
+    await loadSalesNavigatorFilterImpactModel();
     let currentSession = session;
     let claimedSlices = 0;
     const seenSliceIds = new Set();
@@ -1992,11 +2129,56 @@ async function executeSalesNavigatorCrawlJob(session, jobId, options) {
     const inFlight = new Map();
     let nextSlot = 0;
     let noMoreClaimableWork = false;
+    let sessionPoolFailures = 0;
+    let nextSessionPoolRetryAt = 0;
+    let lastSessionPoolReadyAt = 0;
+    const sessionPoolReadinessCooldownMs = 120_000;
     while (true) {
         while (!noMoreClaimableWork && inFlight.size < parallelExports) {
             if (claimedSlices >= options.maxSlices) {
                 break;
             }
+            if (inFlight.size === 0) {
+                const now = Date.now();
+                if (now < nextSessionPoolRetryAt) {
+                    await delay(Math.max(0, nextSessionPoolRetryAt - now));
+                    continue;
+                }
+                if (now - lastSessionPoolReadyAt >= sessionPoolReadinessCooldownMs) {
+                    const readiness = await ensureSalesNavigatorSessionPoolReady(job?.sourceQueryUrl ?? "https://www.linkedin.com/sales/search/people", {
+                        logger: options.logger,
+                        source: "cli_salesnav_crawl_preflight"
+                    });
+                    if (!readiness.ready) {
+                        sessionPoolFailures += 1;
+                        idlePollCount += 1;
+                        const waitSeconds = Math.min(120, 10 * Math.max(1, sessionPoolFailures));
+                        nextSessionPoolRetryAt = Date.now() + waitSeconds * 1000;
+                        await options.logger?.log("salesnav.crawl.session_pool.waiting", {
+                            jobId,
+                            idlePollCount,
+                            idleMaxPolls: options.idleMaxPolls,
+                            sessionPoolFailures,
+                            waitSeconds,
+                            error: readiness.error
+                        });
+                        if (idlePollCount >= options.idleMaxPolls) {
+                            lastOutcome = {
+                                outcome: "terminal_failed",
+                                error: readiness.error ??
+                                    `Sales Navigator session pool stayed unavailable for ${options.idleMaxPolls} checks.`,
+                                errorCode: "blocked_no_valid_salesnav_session"
+                            };
+                            noMoreClaimableWork = true;
+                            break;
+                        }
+                        continue;
+                    }
+                    sessionPoolFailures = 0;
+                    nextSessionPoolRetryAt = 0;
+                    lastSessionPoolReadyAt = Date.now();
+                }
+            }
             const claimed = await claimNextSalesNavigatorCrawlSlice(currentSession, jobId, options.traceId);
             currentSession = claimed.session;
             job = claimed.value.job;
@@ -2089,6 +2271,10 @@ async function executeSalesNavigatorCrawlJob(session, jobId, options) {
         job = completed.value.job;
         activeSlice = completed.value.activeSlice;
         lastOutcome = completed.value.lastOutcome;
+        if (completed.value.forceSessionPoolRecheck) {
+            lastSessionPoolReadyAt = 0;
+            nextSessionPoolRetryAt = 0;
+        }
     }
     if (!job) {
         const status = await getSalesNavigatorCrawlStatus(currentSession, jobId, options.traceId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "salesprompter-cli",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "JSON-first sales prospecting CLI for ICP definition, lead generation, enrichment, scoring, and CRM/outreach sync.",
   "type": "module",
   "bin": {
@@ -22,6 +22,12 @@
     "verify:all": "npm run check && npm test && npm run build:docs:site && npm run docs:broken-links && npm run docs:a11y",
     "vercel-build": "npm run build:docs:site"
   },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "sales",
     "salesprompter",
@@ -57,6 +63,9 @@
     "commander": "^14.0.1",
     "zod": "^4.1.5"
   },
+  "overrides": {
+    "undici": "^7.24.0"
+  },
   "devDependencies": {
     "@types/node": "^24.3.0",
     "gray-matter": "^4.0.3",