salesprompter-cli 0.1.82 → 0.1.84

package/README.md

@@ -44,29 +44,90 @@ For headless or automation use, generate a CLI token in the app and run `salespr
 
 `leads:at-companies` researches Director, Head-of, VP and C-level contacts across functions. It exports a shortlist for review without starting email enrichment or outreach.
 
-The checkpoint, shortlist and review exports refresh after every completed search, so long runs expose saved progress immediately. Company labels with punctuation, such as `(TKMS)`, are escaped safely in search queries.
+Start with company names; no LinkedIn IDs are needed in your brief:
+
+```json
+{ "companies": [{ "name": "Your target company", "maxContacts": 20 }] }
+```
+
+```bash
+salesprompter auth:login
+salesprompter browser:connect
+salesprompter leads:at-companies --brief companies.json --out-dir ./research --resolve-companies --all
+```
+
+After a successful connection, Chrome is remembered for company research. If names are ambiguous, an interactive terminal shows verified candidate locations, websites and evidence links. Choose a number, then confirm; nothing is preselected. The CLI saves the decision and resumes without editing your brief. Use `--review` to review a saved ambiguity later. Enter 0 or press Enter to leave it unresolved.
+
+JSON, quiet and non-interactive runs never prompt. Their `outcome` is `complete`, `incomplete` or `needs_review`; `nextCommand` gives the terminal command for pending collection or identity review. `collectionComplete` refers only to collection, so it can be true while role review remains. Add `--require-complete` for exit code 2 whenever collection or review is unfinished. Without it, exit 0 means the command ran, not that all research is complete. `--no-interactive` disables prompts in a terminal too.
+
+Guided review fetches native details for at most ten exact-name candidates. Non-exact, composite or larger identity choices still need independently checked `--review-file` decisions. Missing/mismatched details cannot be approved. Explicit connection flags override the remembered choice; failed Chrome authentication never falls back silently to another identity.
+
+The checkpoint, shortlist and review exports refresh after every collected page, so long runs expose saved progress immediately. Company labels with punctuation, such as `(TKMS)`, are escaped safely in search queries.
 
 Use `--report-only` to refresh saved reports without contacting LinkedIn. The workspace-bound checkpoint is still checked. `progress` separates unique shortlisted people, review rows, review people, review-only people, pending searches, partial/unknown coverage and unresolved companies. `collectionComplete` is false while any coverage gap remains; `nextActions` explains what is left. Unrestricted geography is labeled explicitly.
 
-For a manually verified legal-name alias, add `verifiedEmployerAliases: [{ "name": "Exact source employer name", "evidenceUrl": "https://official.example/legal" }]` to that company. The CLI records the evidence link but does not independently verify its contents. Aliases never bypass the numeric current-company ID check and are never inferred from similar names. Changing the brief requires a new output directory; no existing review rows are silently promoted.
+### Recover saved research without recollecting
+
+Version 0.1.83 separates collection evidence from review decisions. Keep the original brief and output directory:
+
+```bash
+# Recheck saved roles and write an actionable recovery.json; no LinkedIn requests.
+salesprompter leads:at-companies --brief companies.json --out-dir ./research --report-only
+# Verify canonical employer names against native company details for selected targets.
+salesprompter leads:at-companies --brief companies.json --out-dir ./research \
+  --browser chrome --verify-employers --company 'Example (CH)'
+# Continue partial searches until company shortlist ceilings are filled.
+salesprompter leads:at-companies --brief companies.json --out-dir ./research \
+  --browser chrome --continue-partial quota --all
+# Or request all accessible pages for one exact brief company name.
+salesprompter leads:at-companies --brief companies.json --out-dir ./research \
+  --browser chrome --continue-partial exhaustive --company 'Example (CH)'
+```
+
+`--company` is repeatable and limits network work, not the overall report. `--verify-employers` checks scoped employers with saved candidates and caches their canonical-name evidence. Only equivalent presentation/legal-suffix names (for example, `BioNTech` / `BioNTech SE`) qualify automatically; group, division and subsidiary differences still require review. The exact numeric current-employer ID check always applies.
+
+`recovery.json` contains alias proposals, identity-search attempts and candidate evidence, explicit unresolved reasons, and a fingerprint-bound review template. Proposals are **not** approvals. Copy its `reviewFileTemplate` into a private JSON file and add only independently verified decisions:
+
+```json
+{
+  "fingerprint": "COPY_THE_64_CHARACTER_FINGERPRINT_FROM_RECOVERY_JSON",
+  "employerAliases": [
+    { "companyId": "123", "name": "Exact source name", "evidenceUrl": "https://official.example/evidence" }
+  ],
+  "identities": [
+    { "targetName": "Exact name in brief", "companyId": "456", "canonicalName": "Verified source name", "evidenceUrl": "https://official.example/evidence" }
+  ]
+}
+```
+
+```bash
+salesprompter leads:at-companies --brief companies.json --out-dir ./research \
+  --review-file ./verified-decisions.json --report-only
+# Then collect any newly resolved identities through the same checkpoint.
+salesprompter leads:at-companies --brief companies.json --out-dir ./research --browser chrome --all
+```
+
+The CLI validates and persists the complete review file as `review-decisions.json`, checks its workspace/brief fingerprint, and rejects conflicting/shared identities. Supplied evidence URLs record human decisions; their contents are not independently verified by `--review-file`. Later runs reuse the decisions. An alias never approves an ambiguous role. For a new collection, `verifiedEmployerAliases` in the company brief remains supported; changing the original targeting brief still requires a new output directory.
+
+Partial continuation checkpoints the raw next offset and deduplicates people. Old checkpoints without an offset replay the first page once before advancing. `quota` stops at the shortlist ceiling; `exhaustive` means attempting the accessible 2,500-result window, **not** a promise of exhaustive coverage. Count changes, empty/repeated pages and larger result sets remain explicitly incomplete. Stopped searches require investigation; the CLI does not automatically clear `stoppedReason`. `--all` controls the number of jobs, not these safety limits. Make a private copy of the output directory before comparing old and new role-policy results.
 
-For standalone browser research, sign in once to the CLI-owned Chrome profile, then select Chrome:
+For standalone browser research, sign in once to the CLI-owned Chrome profile:
 
 ```bash
 salesprompter browser:connect
 salesprompter leads:at-companies --brief companies.json --out-dir ./research \
-  --resolve-companies --all --browser chrome
+  --resolve-companies --all
 ```
 
 `browser:connect` opens a separate Chrome window and waits up to ten minutes for your manual Sales Navigator sign-in (change with `--wait <seconds>`). It confirms a successful native authenticated request, then closes its own browser. Google Chrome must be installed. The private profile lives at `~/.config/salesprompter/chrome-research` (or under `SALESPROMPTER_CONFIG_DIR`). Your everyday Chrome profile stays untouched. The control connection uses a private OS pipe, not a debugging port. No cookies or browser storage are read/exported. The CLI keeps only allowlisted native request headers in memory.
 
 Research runs reuse that profile in background Chrome, execute the GET requests themselves, and close their own browser when finished. No Codex task, relay worker, extension, or manual request polling is needed. A first sign-in, expired login, or security challenge still requires you: rerun `browser:connect`, then repeat the research command with the same output directory. Rate limits stop immediately without switching accounts. `--browser chrome`, `--browser-relay-port`, and `--wait-for-session` are mutually exclusive. Chrome connects lazily, so completed checkpoints and report-only runs never launch it.
 
-The default `--browser session` keeps the extension-credential route. Credentials load only for pending requests; on an auth failure it tries changed credentials for the same identity once. Add `--wait-for-session 300` for a bounded refresh wait. The optional Codex `--browser-relay-port` route still needs its external worker. Salesprompter workspace authentication applies in every mode.
+`browser:connect` remembers Chrome only after confirming a successful authenticated request. `browser:connect --check` checks an existing sign-in in background and also remembers it; it does not open a sign-in window. The preference is private and scoped to the CLI configuration directory. Explicit `--browser session` selects extension credentials; without a remembered choice, session remains the fallback. Explicit relay/wait flags take precedence over the preference. Credentials load only for pending requests; on an auth failure the session route tries changed credentials for the same identity once. Add `--wait-for-session 300` for a bounded refresh wait. The optional Codex `--browser-relay-port` route still needs its external worker. Salesprompter workspace authentication applies in every mode.
 
 Ctrl+C, SIGTERM and terminal hangup stop Chrome research gracefully: completed searches stay saved, the owned browser closes, and the research lock is released before exit. Repeat the same command to resume only pending work. A forced kill or power loss cannot run cleanup; if a stale lock remains, confirm that its process stopped before removing only `.research-lock` as the CLI error explains.
 
-Create a JSON brief with verified numeric LinkedIn company IDs. Use each subsidiary's own ID; names alone are not an employer match. Missing IDs stay in the coverage report as unresolved.
+Create a JSON brief with company names or verified numeric LinkedIn company IDs. Use `--resolve-companies` for names. Each subsidiary must resolve to its own ID; unresolved identities stay in the coverage report and are never guessed.
 
 For a name-only list, the executable end-to-end research mode is:
 
@@ -74,7 +135,7 @@ For a name-only list, the executable end-to-end research mode is:
 salesprompter leads:at-companies --brief companies.json --out-dir ./research --resolve-companies --all
 ```
 
-The CLI first collects prepared IDs, then resolves missing IDs through paginated Account Search and immediately collects their contacts. It accepts only one exact-name identity from a fully read result set of at most 1,000 companies; fuzzy, shared-ID, oversized and ambiguous matches remain unresolved. Resolutions and misses are saved in the workspace-bound checkpoint and `company-resolutions.json`, without editing the input brief. Repeat the command to resume. Add `--retry-unresolved --resolve-companies` to intentionally retry saved identity misses in the same directory without repeating successful resolutions or completed searches. `--all` removes the invocation's job-count limit, not LinkedIn pacing or per-function candidate limits. A working LinkedIn session is required for new requests; use `--browser chrome` to eliminate the external browser-worker dependency.
+The CLI first collects prepared IDs, then resolves missing IDs through paginated Account Search and immediately collects their contacts. It tries up to three name queries, normalizing only presentation/legal-suffix differences. Automatic resolution requires a unique matching identity in a complete result set of at most 1,000 companies plus matching native company-detail evidence. Fuzzy, shared-ID, oversized, ambiguous and composite parent/subsidiary targets remain unresolved with diagnostics in `recovery.json`. Resolutions and misses are saved in the workspace-bound checkpoint and `company-resolutions.json`, without editing the input brief. Repeat the command to resume. Add `--retry-unresolved --resolve-companies` to intentionally retry saved identity misses without repeating successful work; add `--company` to narrow the retry. `--all` removes the invocation's job-count limit, not LinkedIn pacing or per-function candidate limits. A working LinkedIn session is required for new requests; use `--browser chrome` to eliminate the external browser-worker dependency.
 
 ```bash
 salesprompter leads:at-companies --brief companies.json --out-dir ./research \
@@ -102,13 +163,13 @@ The default six functions are Digital Marketing & CRM, Digital Product & UX, Sof
 
 Contacts must match the current company ID, a senior title and the requested function. Selection alternates between functions, deduplicates profile URLs and never pads a company to its ceiling. The default ceiling is 20; each company can override it. Head-of roles classified as experienced managers are searched, but generic manager titles do not pass the final seniority check.
 
-Default role matching includes talent acquisition, business intelligence, digital workplace and German department-head titles. Broad digital/transformation, communications and operational-technology matches go into `review.csv`, not the selected contacts. Mixed-role headlines cannot borrow seniority from an assistant or former role. Current-position evidence overrides a conflicting summary employer or headline.
+Default role matching includes talent acquisition, business intelligence, digital workplace and German department-head titles. Role policy 2 requires software-specific context for Software Development and digital/UX context for Digital Product & UX; generic engineering, physical-vehicle product roles and technical flight/hydraulic data do not automatically qualify. Broad digital/transformation, communications and operational-technology matches go into `review.csv`, not the selected contacts. Mixed-role headlines cannot borrow seniority from an assistant or former role. Current-position evidence overrides a conflicting summary employer or headline. Reports include `rolePolicyVersion`; review rows retain every applicable `reasons` entry as well as the primary `reason`.
 
-The export retains the source employer name. If LinkedIn returns the target ID with a different employer name, that candidate goes to review too: parent/subsidiary scope and legal-name aliases need an explicit human check.
+The export retains the source employer name and accepted alias evidence. Unverified employer-name differences go to review: verify equivalent canonical names with `--verify-employers`, or supply an evidence-backed review decision for non-equivalent names. Parent/subsidiary scope is never inferred.
 
 For custom functions, add `reviewTerms` (a subset of `terms`) for discovery terms that should require manual review: `{"name":"IT","terms":["it","digital"],"reviewTerms":["digital"]}`. A specific non-review term in the same senior-role clause can qualify a contact.
 
-Outputs are private local `contacts.csv`, `review.csv`, `coverage.json` (including review candidates, rejected/unresolved matches and per-function counts), and `checkpoint.json`. Review counts are candidate/function pairs, not additional unique leads. A completed search batch is not exhaustive coverage: each function collects at most `candidatesPerDepartment` candidates and the report records LinkedIn's reported total and any shortfall. Default `--max-searches 12` bounds each invocation. Increase it explicitly for larger batches. HTTP 429/999 stops the run and preserves completed searches; resume after cooldown. An interrupted individual search may be repeated.
+Outputs are private local `contacts.csv`, `review.csv`, `coverage.json` (including review candidates, rejected/unresolved matches and per-function counts), `recovery.json`, `company-resolutions.json`, and `checkpoint.json`. Review counts are candidate/function pairs, not additional unique leads. A completed search batch is not exhaustive coverage: ordinary collection stops at `candidatesPerDepartment`; use `--continue-partial` explicitly to advance. The report records LinkedIn's reported total and any shortfall. Default `--max-searches 12` bounds collection jobs and resolution attempts; employer-detail verification is scoped separately with `--company`. Increase job limits explicitly for larger batches. HTTP 429/999 stops the run and preserves saved pages; resume only after cooldown.
 
 Live research requires Salesprompter workspace login and a LinkedIn session. `--browser-relay-port` uses the existing signed-in browser relay. Checkpoints are bound to both the brief and workspace; changed criteria require a new output directory. A concurrent run is refused; after a crash, remove only `.research-lock` after confirming the process stopped. This command does not import the shortlist into the workspace, find emails, or create campaigns. Review company identity, role fit and coverage before downstream use.
 

package/dist/cli.js

@@ -16,6 +16,9 @@ import { Command } from "commander";
 import { z } from "zod";
 import { AffiliateCopyReviewSchema, renderAffiliateCopyReview } from "./affiliate-copy.js";
 import { CompanyBriefSchema, planCompanySearches, runCompanyResearch } from "./company-leads.js";
+import { CompanyReviewSchema, resolveCompanyIdentity } from "./company-recovery.js";
+import { chooseCompanyIdentity, companyResearchNextCommand, createCompanyReviewPrompt } from "./company-identity-review.js";
+import { rememberResearchBrowser, selectResearchBrowser } from "./research-browser-preference.js";
 import { createLazySessionRecovery, waitForFreshSession, isFreshSessionForIdentity } from "./session-recovery.js";
 import { createChromeResearchBrowser, ChromeResearchInterruptedError } from "./chrome-browser.js";
 import { clearAuthSession, loginWithBrowserConnect, loginWithDeviceFlow, loginWithToken, readAuthSession, requireAuthSession, shouldBypassAuth, verifySession, writeAuthSession } from "./auth.js";
@@ -15141,10 +15144,13 @@ program
     .command("browser:connect")
     .description("Sign in once to the CLI-owned research Chrome; no external browser worker required.")
     .option("--wait <seconds>", "Time allowed for manual LinkedIn sign-in", "600")
+    .option("--check", "Check the saved sign-in in background without opening a sign-in window", false)
     .action(async (options) => {
-    const browser = createChromeResearchBrowser({ visible: true, loginWaitMs: z.coerce.number().int().min(1).max(3600).parse(options.wait) * 1000, onProgress: message => process.stderr.write(`${message}\n`) });
+    const browser = createChromeResearchBrowser({ visible: !options.check, loginWaitMs: options.check ? 5000 : z.coerce.number().int().min(1).max(3600).parse(options.wait) * 1000, onProgress: message => process.stderr.write(`${message}\n`) });
     try {
-        printOutput({ status: "ok", ...await browser.connect() });
+        const connection = await browser.connect();
+        await rememberResearchBrowser(getSalesprompterConfigDir(), "chrome");
+        printOutput({ status: "ok", ...connection, defaultResearchBrowser: "chrome" });
     }
     finally {
         await browser.close();
@@ -15153,19 +15159,32 @@ program
 program
     .command("leads:at-companies")
     .description("Find senior contacts at named companies, balanced across functions; export a review shortlist.")
-    .requiredOption("--brief <path>", "JSON company list with verified company IDs and optional role criteria")
+    .requiredOption("--brief <path>", "JSON company names or verified IDs, with optional role criteria")
     .option("--out-dir <path>", "Private output directory and resume checkpoint", "./company-leads")
     .option("--max-searches <number>", "Maximum company/function searches this invocation", "12")
     .option("--report-only", "Refresh saved research reports without contacting LinkedIn", false)
     .option("--all", "Process all pending company/function searches in this invocation", false)
     .option("--resolve-companies", "Resolve unique exact company names and collect their contacts in the same run", false)
     .option("--retry-unresolved", "Retry cached identity misses without discarding completed searches (requires --resolve-companies)", false)
+    .option("--review-file <path>", "Apply fingerprint-bound, evidence-backed identity/alias decisions without changing the brief")
+    .option("--review", "Choose unresolved company identities in this terminal, then resume collection", false)
+    .option("--no-interactive", "Never prompt for company review; return needs_review for unresolved choices")
+    .option("--require-complete", "Exit 2 unless collection and review are complete; still write reports", false)
+    .option("--verify-employers", "Verify canonical employer names against LinkedIn company details and save safe aliases", false)
+    .option("--continue-partial <mode>", "Resume saved partial pages: quota or exhaustive (2500-result window)")
+    .option("--company <name>", "Limit recovery to an exact brief company name; repeat for multiple companies", (value, previous) => [...previous, value], [])
     .option("--wait-for-session <seconds>", "Wait for a refreshed extension session after an auth failure; never retry rate limits", "0")
     .option("--browser-relay-port <number>", "Use the signed-in Codex browser through a loopback relay")
-    .option("--browser <mode>", "Use chrome for CLI-owned browser research, or session for extension credentials", "session")
+    .option("--browser <mode>", "Override saved connection: chrome or session; browser:connect remembers chrome")
     .option("--dry-run", "Preview targeting and unresolved companies without network calls", false)
     .action(async (options) => {
-    const browserMode = z.enum(["chrome", "session"]).parse(options.browser);
+    const browserMode = await selectResearchBrowser(options, getSalesprompterConfigDir());
+    const canReview = Boolean(process.stdin.isTTY && process.stderr.isTTY && !runtimeOutputOptions.json && !runtimeOutputOptions.quiet && options.interactive);
+    if (options.review && !canReview)
+        throw new Error("--review requires an interactive terminal without --json, --quiet or --no-interactive. Run the displayed nextCommand in a terminal, or use --review-file for an evidence-backed scripted decision.");
+    if (options.review && (options.reportOnly || options.dryRun))
+        throw new Error("--review cannot be combined with --report-only or --dry-run; candidate verification requires live company details.");
+    const interactiveReview = canReview && !options.reportOnly && !options.dryRun && (options.review || options.resolveCompanies);
     if (options.retryUnresolved && !options.resolveCompanies)
         throw new Error("--retry-unresolved requires --resolve-companies.");
     const waitMs = z.coerce.number().int().min(0).max(3600).parse(options.waitForSession) * 1000;
@@ -15174,19 +15193,39 @@ program
     if (waitMs && options.browserRelayPort)
         throw new Error("--wait-for-session refreshes extension credentials, not a browser relay. Use one connection mode.");
     const brief = await readJsonFile(path.resolve(options.brief), CompanyBriefSchema);
+    const review = options.reviewFile ? await readJsonFile(path.resolve(options.reviewFile), CompanyReviewSchema) : undefined;
+    const continuePartial = options.continuePartial ? z.enum(["quota", "exhaustive"]).parse(options.continuePartial) : undefined;
+    for (const name of options.company)
+        if (!brief.companies.some(c => c.name === name))
+            throw new Error(`Unknown target company: ${name}`);
     const jobs = planCompanySearches(brief);
     const maxSearches = options.all ? Number.MAX_SAFE_INTEGER : z.coerce.number().int().min(1).max(10000).parse(options.maxSearches);
     if (options.dryRun) {
-        printOutput({ status: "ok", dryRun: true, searches: jobs, unresolvedCompanies: brief.companies.filter(c => !c.companyId), maxSearches, outreachStarted: false, emailEnrichmentStarted: false });
+        const inScope = (name) => !options.company.length || options.company.includes(name);
+        printOutput({ status: "ok", outcome: "preview", browser: browserMode, dryRun: true, searches: jobs.filter(job => inScope(job.company.name)), unresolvedCompanies: brief.companies.filter(c => !c.companyId && inScope(c.name)), maxSearches, recovery: { companies: options.company, verifyEmployers: options.verifyEmployers, continuePartial: continuePartial ?? null, reviewFile: options.reviewFile ? path.resolve(options.reviewFile) : null, savedCheckpointNotRead: true }, outreachStarted: false, emailEnrichmentStarted: false });
         return;
     }
     const session = await requireAuthSession();
     const orgId = session.user.orgId;
     if (!orgId)
         throw new Error("Choose a Salesprompter workspace before company research.");
+    const finish = (report, reportOnly = false) => {
+        const nextCommand = companyResearchNextCommand({ brief: path.resolve(options.brief), outDir: report.output, browser: browserMode, unresolved: report.progress.unresolvedCompanies, pending: report.progress.remainingSearches, companies: options.company });
+        writeProgress(`\n${report.outcome.replace(/_/g, " ").toUpperCase()}: ${report.selected.length} contacts; ${report.progress.completedSearches}/${report.progress.totalSearches} searches; ${report.progress.reviewOnlyPeople} additional people to review.`);
+        if (nextCommand)
+            writeProgress(`Next: ${nextCommand}`);
+        if (report.review.length)
+            writeProgress(`Role/employer review: ${path.join(report.output, "review.csv")}`);
+        if (process.stdout.isTTY && !runtimeOutputOptions.json)
+            writeProgress(`Contacts: ${path.join(report.output, "contacts.csv")}\nReport: ${path.join(report.output, "coverage.json")}`);
+        else
+            printOutput({ status: report.status, outcome: report.outcome, browser: browserMode, reportOnly, selected: report.selected.length, reviewRequired: report.review.length, progress: report.progress, nextActions: report.nextActions, nextCommand, completedSearches: report.completedSearches, totalSearches: report.totalSearches, coverage: report.coverage, output: report.output, resumable: true, outreachStarted: false, emailEnrichmentStarted: false });
+        if (options.requireComplete && report.outcome !== "complete")
+            process.exitCode = 2;
+    };
     if (options.reportOnly) {
-        const report = await runCompanyResearch({ brief, outDir: path.resolve(options.outDir), scope: `${session.apiBaseUrl}:${orgId}`, maxSearches: 0, search: async () => { throw new Error("Report-only cannot collect leads."); } });
-        printOutput({ status: "ok", reportOnly: true, progress: report.progress, nextActions: report.nextActions, output: report.output, outreachStarted: false, emailEnrichmentStarted: false });
+        const report = await runCompanyResearch({ brief, review, onlyCompanies: options.company, outDir: path.resolve(options.outDir), scope: `${session.apiBaseUrl}:${orgId}`, maxSearches: 0, search: async () => { throw new Error("Report-only cannot collect leads."); } });
+        finish(report, true);
         return;
     }
     const port = options.browserRelayPort == null ? null : z.coerce.number().int().min(1).max(65535).parse(options.browserRelayPort);
@@ -15228,41 +15267,54 @@ program
         },
     });
     let startedSearches = 0;
+    const paced = async () => { if (startedSearches++ > 0)
+        await delay(randomIntegerBetween(5000, 8000)); };
+    const detailsCache = new Map();
+    const details = async (id) => {
+        if (detailsCache.has(id))
+            return detailsCache.get(id);
+        await paced();
+        process.stderr.write(`Verifying employer ${id}\n`);
+        const response = await recoverSession(config => fetchCliImportSalesNavigatorJson({ url: buildCliImportCompanyDetailsUrl([id]), config, browserRelay: relay, timeoutMs: 30000, label: "Company identity evidence", companyId: id }));
+        const body = cliImportCompanyRecord(response.body?.results);
+        const record = cliImportCompanyRecord(body?.[id]);
+        const explicitId = record?.entityUrn ? extractLinkedInSalesCompanyIdFromUrn(record.entityUrn) : null;
+        const evidence = response.status === 200 && typeof record?.name === "string" && (!explicitId || explicitId === id)
+            ? { companyId: id, name: record.name, website: typeof record.website === "string" ? record.website : undefined, location: formatCliImportCompanyLocation(record.headquarters) ?? formatCliImportCompanyLocation(record.location) ?? undefined, evidenceUrl: `https://www.linkedin.com/sales/company/${id}` } : null;
+        detailsCache.set(id, evidence);
+        return evidence;
+    };
     try {
-        const report = await runCompanyResearch({ brief, outDir: path.resolve(options.outDir), scope: `${session.apiBaseUrl}:${orgId}`, maxSearches, retryUnresolved: options.retryUnresolved,
-            resolveCompany: !options.resolveCompanies ? undefined : async (company) => {
-                if (startedSearches++ > 0)
-                    await delay(randomIntegerBetween(5000, 8000));
-                writeProgress(`Resolving ${company.name}`);
-                const queryUrl = buildCliImportAccountSearchUrl(company.name);
-                const response = await recoverSession(activeConfig => fetchCliImportSalesNavigatorJson({ url: queryUrl, config: activeConfig, browserRelay: relay, timeoutMs: 30000, label: `Company identity for ${company.name}` }));
+        const report = await runCompanyResearch({ brief, review, onlyCompanies: options.company, continuePartial, outDir: path.resolve(options.outDir), scope: `${session.apiBaseUrl}:${orgId}`, maxSearches, retryUnresolved: options.retryUnresolved,
+            reviewIdentity: !interactiveReview ? undefined : async (company, diagnostic) => {
+                const prompt = createCompanyReviewPrompt();
+                try {
+                    return await chooseCompanyIdentity({ targetName: company.name, diagnostic, details, io: prompt.io });
+                }
+                finally {
+                    prompt.close();
+                }
+            },
+            verifyEmployer: options.verifyEmployers ? details : undefined,
+            diagnoseCompany: !options.resolveCompanies ? undefined : company => resolveCompanyIdentity(company.name, async (query, start) => {
+                await paced();
+                process.stderr.write(`Resolving ${company.name}: ${query}, offset ${start}\n`);
+                const url = buildCliImportAccountSearchUrl(query).replace(/([?&])start=\d+/, `$1start=${start}`);
+                const response = await recoverSession(config => fetchCliImportSalesNavigatorJson({ url, config, browserRelay: relay, timeoutMs: 30000, label: `Company identity for ${company.name}` }));
                 if (response.status !== 200 || !response.body)
                     throw new Error(`Company identity search failed (${response.status}).`);
                 const elements = extractLocalSalesNavigatorElements(response.body);
-                const total = extractLocalSalesNavigatorTotalResults(response.body);
-                // A truncated or unknown result set cannot establish a unique identity.
-                if (total == null || total > 1000)
-                    return null;
-                for (let start = 25; start < total; start += 25) {
-                    await delay(randomIntegerBetween(5000, 8000));
-                    const pageUrl = queryUrl.replace(/([?&])start=\d+/, `$1start=${start}`);
-                    const page = await recoverSession(activeConfig => fetchCliImportSalesNavigatorJson({ url: pageUrl, config: activeConfig, browserRelay: relay, timeoutMs: 30000, label: `Company identity for ${company.name}` }));
-                    if (page.status !== 200 || !page.body)
-                        throw new Error(`Company identity page failed (${page.status}).`);
-                    const rows = extractLocalSalesNavigatorElements(page.body);
-                    if (!rows.length)
-                        return null;
-                    elements.push(...rows);
-                }
-                if (elements.length < total)
-                    return null;
-                const accounts = elements.map(element => normalizeLocalSalesNavigatorAccount(element, queryUrl)).filter(Boolean);
-                const exact = accounts.filter(account => normalizeLooseMatchText(String(account.companyName ?? "")) === normalizeLooseMatchText(company.name));
-                const ids = new Set(exact.map(account => String(account.companyId ?? "")).filter(id => /^[1-9]\d*$/.test(id)));
-                if (ids.size !== 1)
-                    return null;
-                const companyId = [...ids][0];
-                return { companyId, companyName: company.name, evidenceUrl: `https://www.linkedin.com/sales/company/${companyId}` };
+                return { rawCount: elements.length, total: extractLocalSalesNavigatorTotalResults(response.body), candidates: elements.map(e => normalizeLocalSalesNavigatorAccount(e, url)).filter(a => a && /^[1-9]\d*$/.test(String(a.companyId)) && typeof a.companyName === "string").map(a => ({ companyId: String(a.companyId), name: String(a.companyName), evidenceUrl: `https://www.linkedin.com/sales/company/${a.companyId}` })) };
+            }, details),
+            searchPage: async (job, start, count) => {
+                await paced();
+                process.stderr.write(`Researching ${job.company.name} — ${job.department.name}, offset ${start}\n`);
+                return recoverSession(async (config) => {
+                    const request = relay ? { url: buildSalesNavigatorLeadApiUrlFromSearchUrl(job.queryUrl, count), headers: {} } : buildSalesNavigatorApiRequestFromSearchUrl(job.queryUrl, config, count);
+                    request.url = withSalesNavigatorPaging(request.url, start, count);
+                    const response = relay ? await relay.request(request) : await fetchLocalSalesNavigatorRequest(request, { maxRetries: 0, retryBaseDelayMs: 2000, retryMaxDelayMs: 10000 });
+                    return { people: normalizeLocalSalesNavigatorPeople(response.body, request.url), totalResults: extractLocalSalesNavigatorTotalResults(response.body), rawCount: extractLocalSalesNavigatorElements(response.body).length };
+                });
             },
             search: async (job) => {
                 if (startedSearches++ > 0)
@@ -15280,7 +15332,7 @@ program
                 });
             },
         });
-        printOutput({ status: report.status, selected: report.selected.length, reviewRequired: report.review.length, progress: report.progress, nextActions: report.nextActions, completedSearches: report.completedSearches, totalSearches: report.totalSearches, coverage: report.coverage, output: report.output, resumable: true, outreachStarted: false, emailEnrichmentStarted: false });
+        finish(report);
     }
     finally {
         await relay?.close();

package/dist/company-identity-review.js

@@ -0,0 +1,78 @@
+import { companyIdentityKey } from "./company-recovery.js";
+import { createInterface } from "node:readline/promises";
+/** Cancelling a terminal question must reject it so research can release its lock. */
+export function createCompanyReviewPrompt(input = process.stdin, output = process.stderr) {
+    const rl = createInterface({ input, output, terminal: true });
+    const cancellation = new AbortController();
+    const cancel = () => cancellation.abort();
+    const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+    rl.on("SIGINT", cancel);
+    rl.once("close", cancel);
+    for (const signal of signals)
+        process.on(signal, cancel);
+    return {
+        io: {
+            write: (text) => { output.write(text); },
+            ask: async (question) => {
+                try {
+                    return await rl.question(question, { signal: cancellation.signal });
+                }
+                catch (error) {
+                    if (cancellation.signal.aborted)
+                        throw new Error("Company review cancelled. Saved work is preserved; rerun with the same --out-dir to resume.");
+                    throw error;
+                }
+            },
+        },
+        close: () => {
+            for (const signal of signals)
+                process.off(signal, cancel);
+            rl.close();
+        },
+    };
+}
+export const terminalText = (text) => text.replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, " ").slice(0, 300);
+export async function chooseCompanyIdentity(input) {
+    const { targetName, diagnostic, details, io } = input;
+    const candidates = [...new Map(diagnostic.candidates.filter(c => /^[1-9]\d*$/.test(c.companyId) && companyIdentityKey(c.name) === companyIdentityKey(targetName)).map(c => [c.companyId, c])).values()];
+    io.write(`\nCompany review: ${terminalText(targetName)}\n`);
+    if (!candidates.length || candidates.length > 10) {
+        io.write("No bounded exact-name choice is available. Inspect recovery.json and use an evidence-backed --review-file; this company remains unresolved.\n");
+        return null;
+    }
+    const verified = [];
+    for (const candidate of candidates) {
+        const evidence = await details(candidate.companyId);
+        if (!evidence || evidence.companyId !== candidate.companyId || evidence.evidenceUrl !== `https://www.linkedin.com/sales/company/${candidate.companyId}` || companyIdentityKey(evidence.name) !== companyIdentityKey(candidate.name))
+            continue;
+        verified.push(evidence);
+        io.write(`\n${verified.length}. ${terminalText(evidence.name)}\n   Location: ${terminalText(evidence.location ?? "not provided")}\n   Website: ${terminalText(evidence.website ?? "not provided")}\n   Evidence: ${terminalText(evidence.evidenceUrl)}\n`);
+    }
+    if (!verified.length) {
+        io.write("No candidate could be verified. Nothing approved.\n");
+        return null;
+    }
+    io.write("\nMatch the location and website to your intended company. No choice is preselected.\n");
+    while (true) {
+        const answer = (await io.ask("Company number [0 = skip]: ")).trim();
+        if (!answer || answer === "0")
+            return null;
+        if (!/^[1-9]\d*$/.test(answer) || Number(answer) > verified.length) {
+            io.write("Enter a listed number, or 0 to skip.\n");
+            continue;
+        }
+        const chosen = verified[Number(answer) - 1];
+        const confirm = await io.ask(`Use ${terminalText(chosen.name)} (${terminalText(chosen.location ?? chosen.companyId)}) for ${terminalText(targetName)}? [y/N]: `);
+        return /^(y|yes)$/i.test(confirm.trim()) ? chosen : null;
+    }
+}
+export function companyResearchNextCommand(input) {
+    const quote = (text) => `'${text.replace(/'/g, "'\\''")}'`;
+    const scope = (input.companies ?? []).map(name => ` --company ${quote(name)}`).join("");
+    const base = `salesprompter leads:at-companies --brief ${quote(input.brief)} --out-dir ${quote(input.outDir)} --browser ${input.browser}${scope}`;
+    if (input.unresolved)
+        return `${base} --resolve-companies --review --all`;
+    if (input.pending)
+        return `${base} --all`;
+    return null;
+}

package/dist/company-leads.js

@@ -3,6 +3,7 @@ import { mkdir, readFile, rename, writeFile, chmod, rmdir } from "node:fs/promis
 import path from "node:path";
 import { z } from "zod";
 import { buildSalesNavigatorPeopleSearchUrl } from "./sales-navigator.js";
+import { CompanyReviewSchema, companyIdentityKey } from "./company-recovery.js";
 export const defaultDepartments = [
     { name: "Digital Marketing & CRM", terms: ["marketing", "crm", "growth", "communication"], reviewTerms: ["communication"] },
     { name: "Digital Product & UX", terms: ["product", "ux", "design"], reviewTerms: [] },
@@ -63,7 +64,17 @@ export function classifyCompanyRole(title, department) {
     if (!relevant.length)
         return "seniority_not_verified";
     const reviewTerms = new Set(department.reviewTerms.map(words));
-    if (relevant.some(clause => department.terms.some(term => !reviewTerms.has(words(term)) && hasTerm(clause, term))))
+    const contextMatches = (clause) => {
+        const t = words(clause);
+        if (department.name === "Software Development")
+            return /\b(software|cto|developer|developers|devops|frontend|backend|full stack)\b/.test(t);
+        if (department.name === "Digital Product & UX")
+            return /\b(ux|user experience|digital product|software product|product design|digital design|ui)\b/.test(t) && !/\b(vehicles|mechanical|industrial design|hardware design)\b/.test(t);
+        if (department.name === "Data & AI" && /\b(technical data|hydraulic|flight control)\b/.test(t))
+            return /\b(analytics|artificial intelligence|machine learning|data science|data engineering)\b/.test(t);
+        return true;
+    };
+    if (relevant.some(clause => contextMatches(clause) && department.terms.some(term => !reviewTerms.has(words(term)) && hasTerm(clause, term))))
         return "match";
     if (relevant.some(clause => department.terms.some(term => hasTerm(clause, term))))
         return "review";
@@ -123,7 +134,7 @@ export function shortlistCompanyLeads(brief, results) {
                     const key = `${company.companyId}:${job.department.name}:${profile}`;
                     if (!reviewSeen.has(key)) {
                         reviewSeen.add(key);
-                        review.push({ ...row, reason: employerNameDiffers ? "employer_name_differs" : "ambiguous_role" });
+                        review.push({ ...row, reason: employerNameDiffers ? "employer_name_differs" : "ambiguous_role", reasons: [...(employerNameDiffers ? ["employer_name_differs"] : []), ...(role === "review" ? ["ambiguous_role"] : [])] });
                     }
                     continue;
                 }
@@ -151,11 +162,11 @@ export function shortlistCompanyLeads(brief, results) {
         selected.push(...local);
         coverage.push({ companyName: company.name, companyId: company.companyId ?? null, selected: local.length, reviewRequired: review.filter(p => p.companyId === company.companyId).length, ceiling: company.maxContacts,
             status: !company.companyId ? "unresolved_company" : jobs.some(j => !results[j.key]) ? "pending" : local.length ? "review_ready" : "no_verified_matches",
-            departments: jobs.map(j => ({ name: j.department.name, selected: local.filter(p => p.department === j.department.name).length, collected: results[j.key]?.people.length ?? null, reported: results[j.key]?.totalResults ?? null, searchComplete: results[j.key]?.totalResults != null ? results[j.key].people.length >= results[j.key].totalResults : null })) });
+            departments: jobs.map(j => ({ name: j.department.name, selected: local.filter(p => p.department === j.department.name).length, collected: results[j.key]?.people.length ?? null, reported: results[j.key]?.totalResults ?? null, stoppedReason: results[j.key]?.stoppedReason ?? null, searchComplete: results[j.key]?.totalResults != null ? !results[j.key].stoppedReason && results[j.key].people.length >= results[j.key].totalResults : null })) });
     }
     const jobs = planCompanySearches(brief);
     const completed = jobs.filter(j => results[j.key]);
-    const incomplete = completed.filter(j => results[j.key].totalResults != null && results[j.key].people.length < results[j.key].totalResults);
+    const incomplete = completed.filter(j => results[j.key].stoppedReason || results[j.key].totalResults != null && results[j.key].people.length < results[j.key].totalResults);
     const unknown = completed.filter(j => results[j.key].totalResults == null);
     const selectedIds = new Set(selected.map(p => String(p.profileUrl)));
     const reviewIds = new Set(review.map(p => String(p.profileUrl)));
@@ -171,14 +182,15 @@ export function shortlistCompanyLeads(brief, results) {
     };
     const nextActions = [
         ...(progress.remainingSearches ? ["Resume the unchanged brief and output directory to collect pending searches."] : []),
-        ...(unresolved.length ? ["Verify unresolved company identities; use a new output directory after changing the brief."] : []),
-        ...(incomplete.length || unknown.length ? ["Review partial or unknown search coverage before claiming exhaustive collection."] : []),
-        ...(review.length ? ["Review roles and employer names separately. Add only evidence-backed verifiedEmployerAliases; exact company ID checks still apply."] : []),
+        ...(unresolved.length ? ["Use --review in a terminal to choose a verified exact-name identity. Inspect recovery.json for non-exact decisions or an intentional --retry-unresolved --resolve-companies retry."] : []),
+        ...(incomplete.length || unknown.length ? ["Use --continue-partial quota or exhaustive to resume eligible pages; inspect stoppedReason before claiming exhaustive coverage."] : []),
+        ...(review.length ? ["Use --verify-employers for canonical names, or evidence-backed --review-file aliases. Ambiguous roles remain review-only."] : []),
     ];
-    return { selected, review, rejected, coverage, progress, nextActions, outreachStarted: false, emailEnrichmentStarted: false };
+    const outcome = unresolved.length ? "needs_review" : !progress.collectionComplete ? "incomplete" : review.length ? "needs_review" : "complete";
+    return { outcome, selected, review, rejected, coverage, progress, nextActions, rolePolicyVersion: 2, outreachStarted: false, emailEnrichmentStarted: false };
 }
 export function companyLeadCsv(rows) {
-    const columns = ["companyName", "companyId", "fullName", "title", "department", "profileUrl", "location", "sourceQueryUrl", "observedAt", "sourceCompanyName", "reason", "employerAliasEvidence"];
+    const columns = ["companyName", "companyId", "fullName", "title", "department", "profileUrl", "location", "sourceQueryUrl", "observedAt", "sourceCompanyName", "reason", "reasons", "employerAliasEvidence"];
     const escape = (value) => { let s = String(value ?? ""); if (/^[=+@\-\t\r]/.test(s))
         s = "'" + s; return `"${s.replace(/"/g, '""')}"`; };
     return [columns.join(","), ...rows.map(r => columns.map(c => escape(r[c])).join(","))].join("\n") + "\n";
@@ -217,47 +229,189 @@ async function runCompanyResearchLocked(input) {
             throw e;
     }
     const save = async (file, value) => { await writeFile(file + ".tmp", value, { mode: 0o600 }); await chmod(file + ".tmp", 0o600); await rename(file + ".tmp", file); };
+    let review = input.review ? CompanyReviewSchema.parse(input.review) : undefined;
+    if (!review) {
+        try {
+            review = CompanyReviewSchema.parse(JSON.parse(await readFile(path.join(outDir, "review-decisions.json"), "utf8")));
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                throw e;
+        }
+    }
+    if (review && review.fingerprint !== fingerprint)
+        throw new Error("Review decisions belong to a different brief or workspace.");
+    for (const identity of review?.identities ?? []) {
+        const index = brief.companies.findIndex(c => c.name === identity.targetName);
+        if (index < 0 || brief.companies[index].companyId || state.resolutions?.[String(index)] && state.resolutions[String(index)].companyId !== identity.companyId)
+            throw new Error("Reviewed identity must target an unresolved company in this brief.");
+        const occupied = [...brief.companies.flatMap(c => c.companyId ? [c.companyId] : []), ...Object.entries(state.resolutions ?? {}).filter(([i]) => i !== String(index)).flatMap(([, r]) => r ? [r.companyId] : [])];
+        if (occupied.includes(identity.companyId))
+            throw new Error("Reviewed identity is already assigned to another target.");
+        state.resolutions ??= {};
+        state.resolutions[String(index)] = { companyId: identity.companyId, companyName: identity.targetName, canonicalName: identity.canonicalName, evidenceUrl: identity.evidenceUrl };
+    }
     const effectiveBrief = () => CompanyBriefSchema.parse({ ...brief, companies: brief.companies.map((company, index) => {
             const resolution = state.resolutions?.[String(index)];
-            return !company.companyId && resolution ? { ...company, companyId: resolution.companyId } : company;
+            const resolved = !company.companyId && resolution ? { ...company, companyId: resolution.companyId } : company;
+            const evidence = resolved.companyId ? state.employerEvidence?.[resolved.companyId] : undefined;
+            const aliases = [...(resolved.verifiedEmployerAliases ?? []), ...(review?.employerAliases.filter(a => a.companyId === resolved.companyId).map(({ name, evidenceUrl }) => ({ name, evidenceUrl })) ?? [])];
+            if (resolution?.canonicalName)
+                aliases.push({ name: resolution.canonicalName, evidenceUrl: resolution.evidenceUrl });
+            if (evidence && companyIdentityKey(evidence.name) === companyIdentityKey(resolved.name))
+                aliases.push({ name: evidence.name, evidenceUrl: evidence.evidenceUrl });
+            return { ...resolved, verifiedEmployerAliases: aliases };
         }) });
-    const publish = async () => { const report = shortlistCompanyLeads(effectiveBrief(), state.results); await save(path.join(outDir, "contacts.csv"), companyLeadCsv(report.selected)); await save(path.join(outDir, "review.csv"), companyLeadCsv(report.review)); await save(path.join(outDir, "coverage.json"), JSON.stringify(report, null, 2)); await save(path.join(outDir, "company-resolutions.json"), JSON.stringify(state.resolutions ?? {}, null, 2)); return report; };
+    const allowed = (name) => !input.onlyCompanies?.length || input.onlyCompanies.includes(name);
+    for (const name of input.onlyCompanies ?? [])
+        if (!brief.companies.some(c => c.name === name))
+            throw new Error(`Unknown target company: ${name}`);
+    for (const alias of review?.employerAliases ?? [])
+        if (!effectiveBrief().companies.some(c => c.companyId === alias.companyId))
+            throw new Error("Reviewed alias targets an unknown company ID.");
+    if (input.review) {
+        await save(path.join(outDir, "review-decisions.json"), JSON.stringify(review, null, 2));
+        await save(checkpoint, JSON.stringify(state));
+    }
+    const publish = async () => {
+        const report = shortlistCompanyLeads(effectiveBrief(), state.results);
+        const aliases = new Map();
+        for (const row of report.review.filter(r => r.reason === "employer_name_differs")) {
+            const id = String(row.companyId), name = String(row.sourceCompanyName);
+            aliases.set(`${id}:${name}`, { companyId: id, targetName: String(row.companyName), name, evidenceUrl: `https://www.linkedin.com/sales/company/${id}`, status: "needs_verification" });
+        }
+        await save(path.join(outDir, "contacts.csv"), companyLeadCsv(report.selected));
+        await save(path.join(outDir, "review.csv"), companyLeadCsv(report.review));
+        await save(path.join(outDir, "coverage.json"), JSON.stringify(report, null, 2));
+        await save(path.join(outDir, "company-resolutions.json"), JSON.stringify(state.resolutions ?? {}, null, 2));
+        await save(path.join(outDir, "recovery.json"), JSON.stringify({ fingerprint, aliases: [...aliases.values()], identities: brief.companies.flatMap((c, i) => !c.companyId && !state.resolutions?.[String(i)] ? [{ targetName: c.name, diagnostic: state.diagnostics?.[String(i)] ?? { reason: "legacy_unknown" } }] : []), reviewFileTemplate: { fingerprint, employerAliases: [], identities: [] } }, null, 2));
+        return report;
+    };
     let performed = 0;
     try {
+        if (input.verifyEmployer)
+            for (const company of effectiveBrief().companies) {
+                if (!company.companyId || !allowed(company.name) || state.employerEvidence?.[company.companyId])
+                    continue;
+                if (!Object.values(state.results).some(result => result.people.some(p => String(p.companyId) === company.companyId)))
+                    continue;
+                const evidence = await input.verifyEmployer(company.companyId);
+                if (evidence?.companyId === company.companyId) {
+                    state.employerEvidence ??= {};
+                    state.employerEvidence[company.companyId] = evidence;
+                    await save(checkpoint, JSON.stringify(state));
+                    await publish();
+                }
+            }
         // Known IDs run first; an unresolved identity cannot block already prepared work.
         const collect = async () => {
             for (const job of planCompanySearches(effectiveBrief())) {
-                if (state.results[job.key])
+                if (!allowed(job.company.name))
+                    continue;
+                const previous = state.results[job.key];
+                const defaultBudgetFinished = previous && (previous.nextOffset == null || previous.nextOffset >= brief.candidatesPerDepartment);
+                if (previous && (!input.continuePartial && defaultBudgetFinished || previous.totalResults != null && previous.people.length >= previous.totalResults || previous.stoppedReason))
+                    continue;
+                if (previous && input.continuePartial === "quota" && shortlistCompanyLeads(effectiveBrief(), state.results).coverage.find(c => c.companyId === job.company.companyId).selected >= job.company.maxContacts)
                     continue;
                 if (performed >= input.maxSearches)
                     break;
-                state.results[job.key] = await input.search(job);
                 performed++;
+                if (input.searchPage) {
+                    const result = previous ? { ...previous, people: [...previous.people] } : { people: [], totalResults: null, fetchedPages: 0, nextOffset: 0 };
+                    // Old checkpoints lack a reliable raw offset; replay the first page once and deduplicate.
+                    let start = result.nextOffset ?? 0;
+                    const seen = new Set(result.people.map(p => canonicalProfile(p.profileUrl)));
+                    const target = input.continuePartial ? 2500 : brief.candidatesPerDepartment;
+                    while (start < target) {
+                        const replayingLegacyFirstPage = previous != null && previous.nextOffset == null && start === 0;
+                        const count = Math.min(100, target - start);
+                        const page = await input.searchPage(job, start, count);
+                        result.fetchedPages++;
+                        if (result.totalResults != null && page.totalResults !== result.totalResults)
+                            result.stoppedReason = "reported_total_changed";
+                        result.totalResults ??= page.totalResults;
+                        let added = 0;
+                        for (const person of page.people) {
+                            const key = canonicalProfile(person.profileUrl);
+                            if (key && !seen.has(key)) {
+                                seen.add(key);
+                                result.people.push(person);
+                                added++;
+                            }
+                        }
+                        start += page.rawCount;
+                        result.nextOffset = start;
+                        if ((page.rawCount === 0 || !added && !replayingLegacyFirstPage) && (result.totalResults == null || result.people.length < result.totalResults))
+                            result.stoppedReason = "empty_or_duplicate_page";
+                        state.results[job.key] = result;
+                        await save(checkpoint, JSON.stringify(state));
+                        await publish();
+                        if (result.stoppedReason || result.totalResults != null && start >= result.totalResults)
+                            break;
+                        if (input.continuePartial === "quota" && shortlistCompanyLeads(effectiveBrief(), state.results).coverage.find(c => c.companyId === job.company.companyId).selected >= job.company.maxContacts)
+                            break;
+                    }
+                }
+                else
+                    state.results[job.key] = await input.search(job);
                 await save(checkpoint, JSON.stringify(state));
                 await publish();
             }
         };
         await collect();
-        if (input.resolveCompany) {
+        if (input.resolveCompany || input.diagnoseCompany) {
             let resolutionsPerformed = 0;
             for (const [index, company] of brief.companies.entries()) {
                 if (performed >= input.maxSearches || resolutionsPerformed >= input.maxSearches)
                     break;
                 const savedResolution = state.resolutions?.[String(index)];
-                if (company.companyId || (Object.hasOwn(state.resolutions ?? {}, String(index)) && !(input.retryUnresolved && savedResolution === null)))
+                if (!allowed(company.name) || company.companyId || (Object.hasOwn(state.resolutions ?? {}, String(index)) && !(input.retryUnresolved && savedResolution === null)))
                     continue;
-                const resolution = await input.resolveCompany(company);
+                const diagnosed = input.diagnoseCompany ? await input.diagnoseCompany(company) : undefined;
+                const resolution = diagnosed ? diagnosed.resolution : await input.resolveCompany(company);
+                if (diagnosed) {
+                    state.diagnostics ??= {};
+                    state.diagnostics[String(index)] = diagnosed.diagnostic;
+                }
                 resolutionsPerformed++;
                 if (resolution && (!/^[1-9]\d*$/.test(resolution.companyId) || words(resolution.companyName) !== words(company.name)))
                     throw new Error("Company resolver returned a non-exact identity.");
                 const occupied = new Set(effectiveBrief().companies.map(c => c.companyId).filter(Boolean));
                 state.resolutions ??= {};
                 state.resolutions[String(index)] = resolution && !occupied.has(resolution.companyId) ? resolution : null;
+                if (resolution && occupied.has(resolution.companyId) && state.diagnostics?.[String(index)])
+                    state.diagnostics[String(index)].reason = "shared_identity";
                 await save(checkpoint, JSON.stringify(state));
                 await publish();
                 await collect();
             }
         }
+        if (input.reviewIdentity)
+            for (const [index, company] of brief.companies.entries()) {
+                if (!allowed(company.name) || company.companyId || state.resolutions?.[String(index)])
+                    continue;
+                const diagnostic = state.diagnostics?.[String(index)];
+                if (!diagnostic)
+                    continue;
+                const choice = await input.reviewIdentity(company, diagnostic);
+                if (!choice)
+                    continue;
+                if (!diagnostic.candidates.some(c => c.companyId === choice.companyId && companyIdentityKey(c.name) === companyIdentityKey(choice.name)))
+                    throw new Error("Reviewed identity must match a verified candidate from this research.");
+                if (effectiveBrief().companies.some(c => c.companyId === choice.companyId))
+                    throw new Error("Reviewed identity is already assigned to another target.");
+                const identity = { targetName: company.name, companyId: choice.companyId, canonicalName: choice.name, evidenceUrl: choice.evidenceUrl };
+                review = CompanyReviewSchema.parse({ fingerprint, employerAliases: review?.employerAliases ?? [], identities: [...(review?.identities ?? []), identity] });
+                // The durable review overlay is written first. A crash before the checkpoint
+                // write is recovered by the normal review-file replay on the next invocation.
+                await save(path.join(outDir, "review-decisions.json"), JSON.stringify(review, null, 2));
+                state.resolutions ??= {};
+                state.resolutions[String(index)] = { companyId: choice.companyId, companyName: company.name, canonicalName: choice.name, evidenceUrl: choice.evidenceUrl };
+                await save(checkpoint, JSON.stringify(state));
+                await publish();
+                await collect();
+            }
     }
     catch (e) {
         await publish();

package/dist/company-recovery.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+// Only presentation annotations and legal suffixes are interchangeable. Group,
+// division, brand and subsidiary names remain different identities.
+export function companyIdentityKey(name) {
+    let key = name.replace(/\s*\((?:CH|DE|AT|UK|US|USA)\)\s*$/i, "")
+        .normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/ß/g, "ss").toLowerCase()
+        .replace(/&/g, " and ").replace(/[^a-z0-9]+/g, " ")
+        .replace(/\s+/g, " ").trim();
+    // Do not erase a brand token in names such as AG Insurance or SE Ranking.
+    while (/\s(?:gmbh|kgaa|ag|se|ltd|limited|inc|incorporated|llc)$/.test(key))
+        key = key.replace(/\s\S+$/, "");
+    return key;
+}
+export function companyQueryVariants(name) {
+    const plain = name.replace(/\s*\([^)]*\)\s*/g, " ").trim();
+    const primary = plain.split(/\s+\/\s+/)[0].trim();
+    return [...new Set([name, plain, primary, companyIdentityKey(primary)].filter(Boolean))].slice(0, 3);
+}
+export async function resolveCompanyIdentity(name, search, details) {
+    const diagnostic = { reason: "no_exact_match", attempts: [], candidates: [], observedAt: new Date().toISOString() };
+    const candidates = new Map();
+    const proven = new Map();
+    let incomplete = false, oversized = false;
+    for (const query of companyQueryVariants(name)) {
+        const first = await search(query, 0);
+        let count = first.rawCount;
+        const total = first.total;
+        const queryCandidates = new Map(first.candidates.map(c => [c.companyId, c]));
+        let complete = total != null && total <= 1000;
+        for (const c of first.candidates)
+            candidates.set(c.companyId, c);
+        if (complete)
+            for (let start = 25; start < total; start += 25) {
+                const page = await search(query, start);
+                if (page.total !== total || page.rawCount === 0) {
+                    complete = false;
+                    break;
+                }
+                count += page.rawCount;
+                for (const c of page.candidates) {
+                    candidates.set(c.companyId, c);
+                    queryCandidates.set(c.companyId, c);
+                }
+            }
+        complete = complete && count >= total && queryCandidates.size >= total;
+        diagnostic.attempts.push({ query, total, collected: count, complete });
+        incomplete ||= !complete;
+        oversized ||= total != null && total > 1000;
+        // A complete exact query is sufficient; avoid repeating equivalent searches.
+        if (complete)
+            for (const c of queryCandidates.values())
+                proven.set(c.companyId, c);
+        if (complete && [...queryCandidates.values()].some(c => companyIdentityKey(c.name) === companyIdentityKey(name))) {
+            incomplete = false;
+            oversized = false;
+            break;
+        }
+    }
+    diagnostic.candidates = [...candidates.values()].slice(0, 100);
+    const exact = [...proven.values()].filter(c => companyIdentityKey(c.name) === companyIdentityKey(name));
+    if (/\/|\([^)]*(?:\/|,)[^)]*\)/.test(name))
+        diagnostic.reason = "entity_decision_required";
+    else if (oversized)
+        diagnostic.reason = "oversized";
+    else if (incomplete)
+        diagnostic.reason = "incomplete";
+    else if (exact.length > 1)
+        diagnostic.reason = "ambiguous";
+    else if (exact.length === 1) {
+        const evidence = await details(exact[0].companyId);
+        if (evidence?.companyId === exact[0].companyId && companyIdentityKey(evidence.name) === companyIdentityKey(name)) {
+            diagnostic.reason = "resolved";
+            return { resolution: { companyId: evidence.companyId, companyName: name, canonicalName: evidence.name, evidenceUrl: evidence.evidenceUrl }, diagnostic };
+        }
+        diagnostic.reason = "detail_mismatch";
+    }
+    return { resolution: null, diagnostic };
+}
+const evidenceUrl = z.url().refine(value => /^https:\/\//i.test(value), "Evidence must use HTTPS");
+export const CompanyReviewSchema = z.object({
+    fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    employerAliases: z.array(z.object({ companyId: z.string().regex(/^[1-9]\d*$/), name: z.string().trim().min(1), evidenceUrl }).strict()).default([]),
+    identities: z.array(z.object({ targetName: z.string().trim().min(1), companyId: z.string().regex(/^[1-9]\d*$/), canonicalName: z.string().trim().min(1), evidenceUrl }).strict()).default([]),
+}).strict();

package/dist/research-browser-preference.js

@@ -0,0 +1,37 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+const Preference = z.object({ browser: z.enum(["chrome", "session"]) }).strict();
+export async function readResearchBrowserPreference(configDir) {
+    const file = path.join(configDir, "research-browser.json");
+    try {
+        return Preference.parse(JSON.parse(await readFile(file, "utf8"))).browser;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "session";
+        throw new Error(`Cannot read research browser preference at ${file}. Run browser:connect again, or choose --browser chrome or --browser session explicitly.`);
+    }
+}
+export async function rememberResearchBrowser(configDir, browser) {
+    const value = Preference.parse({ browser });
+    await mkdir(configDir, { recursive: true, mode: 0o700 });
+    const file = path.join(configDir, "research-browser.json");
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(value) + "\n", { mode: 0o600, flag: "wx" });
+        await rename(temporary, file);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+export async function selectResearchBrowser(options, configDir) {
+    if (options.browser !== undefined)
+        return Preference.shape.browser.parse(options.browser);
+    // An explicit connection route takes precedence over the saved preference.
+    if (options.browserRelayPort !== undefined || Number(options.waitForSession ?? 0) > 0)
+        return "session";
+    return readResearchBrowserPreference(configDir);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "salesprompter-cli",
-  "version": "0.1.82",
+  "version": "0.1.84",
   "description": "Sales workflow CLI for guided lead generation, enrichment, scoring, and sync.",
   "author": "Daniel Sinewe <hello@danielsinewe.com>",
   "type": "module",