salesprompter-cli 0.1.82 → 0.1.83

package/README.md

@@ -44,11 +44,54 @@ 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.
+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:
 
@@ -74,7 +117,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 +145,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,7 @@ 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 { 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";
@@ -15160,6 +15161,10 @@ program
     .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("--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")
@@ -15174,10 +15179,16 @@ 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", 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();
@@ -15185,7 +15196,7 @@ program
     if (!orgId)
         throw new Error("Choose a Salesprompter workspace before company research.");
     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."); } });
+        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."); } });
         printOutput({ status: "ok", reportOnly: true, progress: report.progress, nextActions: report.nextActions, output: report.output, outreachStarted: false, emailEnrichmentStarted: false });
         return;
     }
@@ -15228,41 +15239,45 @@ 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, 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,
+            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)

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,14 @@ 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 ? ["Inspect recovery.json; retry selected identities with --resolve-companies --retry-unresolved --company, or apply evidence-backed --review-file decisions."] : []),
+        ...(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 };
+    return { 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,42 +228,159 @@ 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();

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/package.json

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