fullstackgtm 0.37.0 → 0.38.1

package/src/acquireLinkedIn.ts

@@ -0,0 +1,83 @@
+/**
+ * LinkedIn → acquire bridge (Phase 1, step 2).
+ *
+ * Connects the provider-agnostic LinkedIn discovery layer (connectors/linkedin.ts)
+ * to the `enrich acquire` spine: pull prospects from a LinkedIn source, map them
+ * to the canonical `Prospect`, and hand them to the existing ICP-score → dedup →
+ * create_record → meter → dry-run/apply pipeline unchanged.
+ *
+ * Kept out of cli.ts on purpose: the only remaining wiring is a ~3-line
+ * discovery branch in `acquireFromApi` (call `createLinkedInProvider` +
+ * `discoverLinkedInProspects`), a `builtinAcquirePreset('linkedin')` entry, the
+ * source allowlist/help, and a `login heyreach` credential. That lands once
+ * cli.ts is clean of other in-flight work — see docs/linkedin-connector-spec.md.
+ *
+ * HeyReach reads a pre-populated lead LIST (not an ICP-driven search), and the
+ * natural identity key is the LinkedIn profile URL — so acquire's matchKey is
+ * `linkedin`, which means the spine skips pipe0 email resolution automatically.
+ */
+
+import {
+  createHeyReachProvider,
+  type HeyReachProviderOptions,
+  type LinkedInProspect,
+  type LinkedInProvider,
+} from "./connectors/linkedin.ts";
+import type { Prospect } from "./connectors/prospectSources.ts";
+
+/** Map a normalized LinkedIn prospect into the canonical acquire `Prospect`. */
+export function linkedInProspectToProspect(lp: LinkedInProspect): Prospect {
+  return {
+    firstName: lp.firstName || undefined,
+    lastName: lp.lastName || undefined,
+    fullName: lp.fullName,
+    // Title drives ICP scoring; fall back to the headline when no title is set.
+    jobTitle: lp.jobTitle ?? lp.headline,
+    companyName: lp.company,
+    linkedin: lp.profileUrl || undefined,
+    email: lp.email,
+    // The profile URL is LinkedIn's stable native id — use it for traceability.
+    sourceId: lp.profileUrl || undefined,
+  };
+}
+
+export type DiscoverLinkedInOptions = {
+  /** Which source (HeyReach lead-list id) to read; provider may have a default. */
+  sourceId?: string;
+  /** Hard cap on prospects pulled. */
+  max?: number;
+};
+
+/**
+ * Discovery branch for `acquireFromApi`: read prospects from a LinkedIn source
+ * and return them as canonical `Prospect`s. Read-only — never sends. The
+ * provider is injected so this is fully testable against the fake (no key).
+ */
+export async function discoverLinkedInProspects(
+  provider: LinkedInProvider,
+  options: DiscoverLinkedInOptions = {},
+): Promise<Prospect[]> {
+  const raw = await provider.fetchProspects({ sourceId: options.sourceId, max: options.max });
+  return raw.map(linkedInProspectToProspect);
+}
+
+export type CreateLinkedInProviderOptions = Omit<HeyReachProviderOptions, "apiKey">;
+
+/**
+ * Build the execution provider for a LinkedIn acquire source. HeyReach is the
+ * default; `unipile` is the planned alternative (same interface). Called by the
+ * cli acquire branch with the stored/env API key.
+ */
+export function createLinkedInProvider(
+  source: string,
+  apiKey: string,
+  options: CreateLinkedInProviderOptions = {},
+): LinkedInProvider {
+  switch (source) {
+    case "linkedin":
+    case "heyreach":
+      return createHeyReachProvider({ apiKey, ...options });
+    default:
+      throw new Error(`Unknown LinkedIn execution provider "${source}" (supported: heyreach).`);
+  }
+}

package/src/assign.ts

@@ -0,0 +1,193 @@
+/**
+ * AssignmentPolicy — the shared rule that decides which owner a record belongs
+ * to. One policy, two consumers:
+ *   1. `enrich acquire` stamps the resolved owner into each `create_record`
+ *      payload, so a lead is never born ownerless, and
+ *   2. `reassign --assign-unowned` applies the SAME policy to backfill existing
+ *      ownerless records.
+ *
+ * Pure + zero-dep: `resolveAssignment` takes plain data (the record's routing
+ * attributes + the candidate owners + the within-run index) and returns an
+ * ownerId or null. Round-robin distributes by the within-run index, so it needs
+ * no persisted rotation cursor — the same plan always resolves the same way
+ * (deterministic apply). Every result is gated by the set of KNOWN active
+ * owners: a policy that points at an unknown or inactive owner yields null, and
+ * the caller leaves that record unassigned + surfaces it — never a bad write.
+ */
+
+export type AssignmentStrategy = "fixed" | "round-robin" | "territory" | "account-owner";
+
+/** The attributes a territory rule can route on, lifted from a record/prospect. */
+export type AssignmentContext = {
+  /** ISO country code, lowercased (e.g. "us"). */
+  geo?: string;
+  /** human industry label, lowercased (e.g. "software"). */
+  industry?: string;
+  /** provider-agnostic employee band (e.g. "11-50"). */
+  employeeBand?: string;
+  /** department, lowercased (e.g. "sales"). */
+  department?: string;
+  /** raw job title, lowercased — matched against rule titleKeywords as substrings. */
+  title?: string;
+  /** owner of the associated account, if any — enables "account-owner" inherit. */
+  accountOwnerId?: string;
+};
+
+/**
+ * One territory clause. Every present key must match (AND across keys); within a
+ * key the candidate value must be one of the listed values (OR). `titleKeywords`
+ * matches when the context title CONTAINS any keyword as a substring.
+ */
+export type TerritoryRule = {
+  when: Partial<{
+    geo: string[];
+    industry: string[];
+    employeeBand: string[];
+    department: string[];
+    titleKeywords: string[];
+  }>;
+  ownerId: string;
+};
+
+export type AssignmentPolicy =
+  | { strategy: "fixed"; ownerId: string }
+  | { strategy: "round-robin"; ownerIds: string[] }
+  | { strategy: "territory"; rules: TerritoryRule[]; fallbackOwnerId?: string }
+  | { strategy: "account-owner"; fallbackOwnerId?: string };
+
+export type AssignmentResult = {
+  /** the resolved owner, or null when the policy can't place this record. */
+  ownerId: string | null;
+  /** short human label for why (audit trail): "fixed", "round-robin", "territory:0", "account-owner", "fallback". */
+  rule?: string;
+};
+
+const STRATEGIES: AssignmentStrategy[] = ["fixed", "round-robin", "territory", "account-owner"];
+
+function asStringArray(value: unknown, label: string): string[] {
+  if (!Array.isArray(value) || value.length === 0 || value.some((v) => typeof v !== "string" || !v.trim())) {
+    throw new Error(`assign: ${label} must be a non-empty array of strings`);
+  }
+  return value.map((v) => (v as string).trim());
+}
+
+/**
+ * Validate + normalize a raw assignment policy (from enrich.config.json or a
+ * CLI flag). Throws on shape errors so a misconfigured policy fails loud at
+ * plan time, never silently mis-routes.
+ */
+export function parseAssignmentPolicy(raw: unknown): AssignmentPolicy {
+  if (!raw || typeof raw !== "object") throw new Error("assign: expected a policy object");
+  const p = raw as Record<string, unknown>;
+  const strategy = p.strategy;
+  if (typeof strategy !== "string" || !STRATEGIES.includes(strategy as AssignmentStrategy)) {
+    throw new Error(`assign: "strategy" must be one of ${STRATEGIES.join(" | ")}`);
+  }
+  switch (strategy) {
+    case "fixed": {
+      if (typeof p.ownerId !== "string" || !p.ownerId.trim()) {
+        throw new Error('assign: fixed strategy needs a non-empty "ownerId"');
+      }
+      return { strategy, ownerId: p.ownerId.trim() };
+    }
+    case "round-robin": {
+      const ownerIds = asStringArray(p.ownerIds, "round-robin ownerIds");
+      return { strategy, ownerIds };
+    }
+    case "territory": {
+      if (!Array.isArray(p.rules) || p.rules.length === 0) {
+        throw new Error('assign: territory strategy needs a non-empty "rules" array');
+      }
+      const rules: TerritoryRule[] = p.rules.map((r, i) => {
+        if (!r || typeof r !== "object") throw new Error(`assign: territory rule ${i} must be an object`);
+        const rule = r as Record<string, unknown>;
+        if (typeof rule.ownerId !== "string" || !rule.ownerId.trim()) {
+          throw new Error(`assign: territory rule ${i} needs a non-empty "ownerId"`);
+        }
+        const whenRaw = (rule.when ?? {}) as Record<string, unknown>;
+        const when: TerritoryRule["when"] = {};
+        for (const key of ["geo", "industry", "employeeBand", "department", "titleKeywords"] as const) {
+          if (whenRaw[key] !== undefined) when[key] = asStringArray(whenRaw[key], `territory rule ${i} when.${key}`);
+        }
+        if (Object.keys(when).length === 0) {
+          throw new Error(`assign: territory rule ${i} "when" needs at least one clause (else it matches everything — use a fallbackOwnerId instead)`);
+        }
+        return { when, ownerId: rule.ownerId.trim() };
+      });
+      const fallbackOwnerId = typeof p.fallbackOwnerId === "string" && p.fallbackOwnerId.trim() ? p.fallbackOwnerId.trim() : undefined;
+      return { strategy, rules, ...(fallbackOwnerId ? { fallbackOwnerId } : {}) };
+    }
+    case "account-owner": {
+      const fallbackOwnerId = typeof p.fallbackOwnerId === "string" && p.fallbackOwnerId.trim() ? p.fallbackOwnerId.trim() : undefined;
+      return { strategy, ...(fallbackOwnerId ? { fallbackOwnerId } : {}) };
+    }
+    default:
+      throw new Error(`assign: unsupported strategy "${strategy}"`);
+  }
+}
+
+function clauseMatches(values: string[], candidate: string | undefined): boolean {
+  if (candidate === undefined) return false;
+  return values.some((v) => v.toLowerCase() === candidate.toLowerCase());
+}
+
+function titleMatches(keywords: string[], title: string | undefined): boolean {
+  if (!title) return false;
+  const lower = title.toLowerCase();
+  return keywords.some((k) => lower.includes(k.toLowerCase()));
+}
+
+/** Does the context satisfy every present clause of a territory rule? */
+export function matchesTerritory(rule: TerritoryRule, ctx: AssignmentContext): boolean {
+  const { when } = rule;
+  if (when.geo && !clauseMatches(when.geo, ctx.geo)) return false;
+  if (when.industry && !clauseMatches(when.industry, ctx.industry)) return false;
+  if (when.employeeBand && !clauseMatches(when.employeeBand, ctx.employeeBand)) return false;
+  if (when.department && !clauseMatches(when.department, ctx.department)) return false;
+  if (when.titleKeywords && !titleMatches(when.titleKeywords, ctx.title)) return false;
+  return true;
+}
+
+/** Gate a candidate ownerId by the known-active set: returns it, or null. */
+function known(ownerId: string | undefined, knownOwnerIds: ReadonlySet<string>): string | null {
+  return ownerId && knownOwnerIds.has(ownerId) ? ownerId : null;
+}
+
+/**
+ * Resolve the owner for one record. `index` is the record's 0-based position
+ * within the run (used by round-robin for deterministic, even within-run
+ * distribution without persisted state). `knownOwnerIds` is the set of active
+ * owners from the snapshot; any result outside it collapses to null so callers
+ * never write an owner the CRM won't accept.
+ */
+export function resolveAssignment(
+  policy: AssignmentPolicy,
+  ctx: AssignmentContext,
+  index: number,
+  knownOwnerIds: ReadonlySet<string>,
+): AssignmentResult {
+  switch (policy.strategy) {
+    case "fixed":
+      return { ownerId: known(policy.ownerId, knownOwnerIds), rule: "fixed" };
+    case "round-robin": {
+      const pool = policy.ownerIds.filter((id) => knownOwnerIds.has(id));
+      if (pool.length === 0) return { ownerId: null, rule: "round-robin" };
+      const safeIndex = ((index % pool.length) + pool.length) % pool.length;
+      return { ownerId: pool[safeIndex], rule: "round-robin" };
+    }
+    case "territory": {
+      for (let i = 0; i < policy.rules.length; i++) {
+        if (matchesTerritory(policy.rules[i], ctx)) {
+          const hit = known(policy.rules[i].ownerId, knownOwnerIds);
+          if (hit) return { ownerId: hit, rule: `territory:${i}` };
+        }
+      }
+      return { ownerId: known(policy.fallbackOwnerId, knownOwnerIds), rule: "fallback" };
+    }
+    case "account-owner": {
+      const inherited = known(ctx.accountOwnerId, knownOwnerIds);
+      if (inherited) return { ownerId: inherited, rule: "account-owner" };
+      return { ownerId: known(policy.fallbackOwnerId, knownOwnerIds), rule: "fallback" };
+    }
+  }
+}

package/src/bin.ts

@@ -1,7 +1,20 @@
 #!/usr/bin/env node
 import { runCli } from "./cli.ts";
+import { flushRunReport } from "./runReport.ts";
 
-runCli(process.argv.slice(2)).catch((error) => {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exitCode = 1;
-});
+const args = process.argv.slice(2);
+const startedAt = Date.now();
+
+runCli(args)
+  .then(async () => {
+    // exitCode 2 (audit findings / create-gate) or 1 (no value) = "partial":
+    // the command ran but flagged something. No exitCode = clean success.
+    const status = process.exitCode && process.exitCode !== 0 ? "partial" : "success";
+    await flushRunReport(args, status, startedAt);
+  })
+  .catch(async (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    await flushRunReport(args, "error", startedAt, message);
+    console.error(message);
+    process.exitCode = 1;
+  });

package/src/cli.ts

@@ -135,6 +135,8 @@ import {
   type Prospect,
 } from "./connectors/prospectSources.ts";
 import { loadSeen, recordSeen } from "./acquireSeen.ts";
+import { reportCounts, reportEvent } from "./runReport.ts";
+import { createLinkedInProvider, discoverLinkedInProspects } from "./acquireLinkedIn.ts";
 import {
   fitThreshold,
   icpFromAnswers,
@@ -197,7 +199,7 @@ Usage:
   fullstackgtm login salesforce --instance-url <url> [--no-validate]
   fullstackgtm login stripe [--no-validate]
   fullstackgtm login anthropic | openai        store an LLM API key for call parse/score
-  fullstackgtm login apollo                    store an Apollo API key for enrich pulls\n  fullstackgtm login pipe0 | explorium         store a discovery-provider key for enrich acquire\n  fullstackgtm logout <hubspot|salesforce|stripe|anthropic|openai|apollo|pipe0|explorium|broker>
+  fullstackgtm login apollo                    store an Apollo API key for enrich pulls\n  fullstackgtm login pipe0 | explorium         store a discovery-provider key for enrich acquire\n  fullstackgtm login heyreach                  store a HeyReach key for enrich acquire --source linkedin\n  fullstackgtm logout <hubspot|salesforce|stripe|anthropic|openai|apollo|pipe0|explorium|heyreach|broker>
 
   Secrets (tokens, client secrets) are NEVER passed as flags — they leak via
   the process list and shell history. Pipe them on stdin or enter them at the
@@ -272,9 +274,10 @@ Usage:
                                                deterministic survivor (richest = most populated data
                                                fields, ties to lowest id; oldest = lowest id). Approve and
                                                apply like any plan; merges are IRREVERSIBLE on apply.
-  fullstackgtm reassign --from <ownerId> --to <ownerId> [--objects account,contact,deal] [--where <expr> …] [--except-deal-stage <stage>] [--include-closed-deals] [source options] [--save] [--json] [--out <path>]
+  fullstackgtm reassign (--from <ownerId> | --assign-unowned) --to <ownerId> [--objects account,contact,deal] [--where <expr> …] [--except-deal-stage <stage>] [--include-closed-deals] [source options] [--save] [--json] [--out <path>]
                                                ownership handoff playbook: one bulk-update-style plan per
-                                               object type (ownerId=<from> → <to>). Extra --where scoping
+                                               object type (ownerId=<from> → <to>). --assign-unowned instead
+                                               claims every ownerless record (ownerId:empty) for --to. Extra --where scoping
                                                is account-lifted for deals/contacts (domain~.de becomes
                                                account.domain~.de); --except-deal-stage <stage> excludes
                                                deals in that stage AND every record whose account has an
@@ -530,7 +533,7 @@ const HELP: Record<string, HelpEntry> = {
   reassign: {
     summary: "ownership handoff: one plan per object type",
     phase: "Remediate",
-    synopsis: ["fullstackgtm reassign --from <ownerId> --to <ownerId> [--objects account,contact,deal] [--where <expr> …] [--save] [--json]"],
+    synopsis: ["fullstackgtm reassign (--from <ownerId> | --assign-unowned) --to <ownerId> [--objects account,contact,deal] [--where <expr> …] [--save] [--json]"],
     detail:
       "Extra `--where` scoping is account-lifted for deals/contacts. `--except-deal-stage <stage>` excludes that stage and any record whose account has an open deal in it, re-verified per record at apply.",
     seeAlso: ["bulk-update", "plans", "apply"],
@@ -929,6 +932,11 @@ async function audit(args: string[]) {
   if (staleDealDays !== undefined) policy.staleDealDays = staleDealDays;
 
   const plan = auditSnapshot(snapshot, policy, rules);
+  reportCounts({
+    findings: plan.findings.length,
+    critical: plan.findings.filter((f) => f.severity === "critical").length,
+    warning: plan.findings.filter((f) => f.severity === "warning").length,
+  });
   const out = option(args, "--out");
   if (out) {
     writeFileSync(resolve(process.cwd(), out), `${JSON.stringify(plan, null, 2)}\n`);
@@ -1877,7 +1885,7 @@ enrich append  [--source apollo] [--objects companies,contacts] [--save] [--conf
 enrich refresh [--source apollo] [--stale-days <n>] [--save] [--config <path>]
                [source options] [--run-label <label>] [--json]
 enrich ingest  <file.csv|payload.json> --source clay [--run-label <label>] [--objects companies|contacts] [--config <path>]
-enrich acquire [--source <id>] [--max <n>] [--save] [--config <path>] [--json]
+enrich acquire [--source <id>] [--max <n>] [--list <id>] [--assign-owner <id>] [--save] [--config <path>] [--json]
 enrich status  [--runs] [--source <id>] [--config <path>] [--json]
 
 acquire creates NET-NEW leads from a staged prospect list (ingest first):
@@ -1887,6 +1895,16 @@ it dedupes each sourced row against the CRM, skips matches and ambiguities
 remaining budget (records + spend, per day and per month; whichever is hit
 first). Approval-gated like every write: \`--save\` → plans approve → apply.
 The meter is charged only when a create actually lands at apply.
+Discovery sources (zero-config presets): explorium | pipe0 (ICP-driven search),
+and linkedin (reads a HeyReach lead list — pass --list <id>, key on the LinkedIn
+URL, $0/record; \`login heyreach\` or HEYREACH_API_KEY).
+
+Leads are never born ownerless: set an \`acquire.assign\` policy (fixed /
+round-robin / territory / account-owner) to stamp an owner at create time, or
+pass \`--assign-owner <id>\`. With a single-owner portal and no policy, acquire
+defaults every lead to that owner; with several owners and no policy it warns
+and leaves them unassigned. Backfill existing ownerless records with
+\`reassign --assign-unowned --to <ownerId>\`.
 
 append pulls from an api source (Apollo — BYO key via \`login apollo\` or
 APOLLO_API_KEY) or reads data staged by \`enrich ingest\` (Clay CSV exports,
@@ -2021,6 +2039,34 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
     let cap = headroom.maxRecords;
     if (explicitMax !== undefined) cap = cap === null ? explicitMax : Math.min(cap, explicitMax);
 
+    // Assignment: never create an ownerless lead. An explicit `acquire.assign`
+    // policy wins; a `--assign-owner <id>` flag is a quick fixed override;
+    // otherwise, when the portal has exactly one active owner, default every
+    // lead to them. With multiple owners and no policy we refuse to guess —
+    // leads are left unassigned and the operator is told to configure a rule.
+    const assignOwnerFlag = option(rest, "--assign-owner");
+    if (!config.acquire.assign) {
+      if (assignOwnerFlag) {
+        config.acquire.assign = { strategy: "fixed", ownerId: assignOwnerFlag };
+      } else {
+        const activeOwners = (snapshot.users ?? []).filter((u) => u.active !== false);
+        if (activeOwners.length === 1) {
+          const sole = activeOwners[0].crmId ?? activeOwners[0].id;
+          config.acquire.assign = { strategy: "fixed", ownerId: sole };
+          console.error(
+            `Assignment: no policy set — defaulting every lead to the portal's sole owner ` +
+              `${activeOwners[0].name} (${sole}). Configure "acquire.assign" to route across reps.`,
+          );
+        } else if (activeOwners.length > 1) {
+          console.error(
+            `⚠ Assignment: ${activeOwners.length} active owners and no "acquire.assign" policy — ` +
+              `leads will be created OWNERLESS. Add an acquire.assign rule (fixed / round-robin / territory) ` +
+              `or pass --assign-owner <id> so every lead lands with an owner.`,
+          );
+        }
+      }
+    }
+
     const result = buildAcquirePlan({
       config,
       source,
@@ -2030,6 +2076,23 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
       maxRecords: cap,
     });
 
+    if (result.counts.unassigned > 0 && result.counts.created > 0) {
+      console.error(
+        `⚠ ${result.counts.unassigned}/${result.counts.created} proposed lead(s) have no owner ` +
+          `(policy could not place them). They will be created ownerless.`,
+      );
+    }
+
+    // Observability: headline metrics for the web run timeline (paired users).
+    reportCounts({
+      sourced: result.counts.fetched,
+      created: result.counts.created,
+      withheldByMeter: result.counts.withheldByMeter,
+      skippedInCrm: apiSkippedCrm,
+      skippedSeen: apiSkippedSeen,
+      estCostUsd: result.estCostUsd,
+    });
+
     const meterLine = formatAcquireMeter(headroom, costPerRecord);
     if (!save) {
       if (rest.includes("--json")) {
@@ -2053,6 +2116,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
     if (result.plan.operations.length > 0) {
       await createFilePlanStore().save(result.plan);
       planIds.push(result.plan.id);
+      reportEvent("plan_saved", result.plan.id);
     }
     await store.update({
       ...run,
@@ -2178,6 +2242,13 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
   result.counts.fetched += missCount;
   result.counts.unmatched += missCount;
 
+  reportCounts({
+    fetched: result.counts.fetched,
+    matched: result.counts.matched,
+    unmatched: result.counts.unmatched,
+    opsEmitted: result.counts.opsEmitted,
+  });
+
   if (!save) {
     if (rest.includes("--json")) {
       console.log(JSON.stringify(result.plan, null, 2));
@@ -2227,8 +2298,9 @@ function formatEnrichCounts(counts: EnrichCounts, ambiguities: number) {
 
 /** Best-effort enrich-config load for apply-time acquire-budget enforcement. */
 /** Provider API key: env override first, then the credential store (`login`). */
-function providerKey(provider: "explorium" | "pipe0"): string {
-  const envName = provider === "explorium" ? "EXPLORIUM_API_KEY" : "PIPE0_API_KEY";
+function providerKey(provider: "explorium" | "pipe0" | "heyreach"): string {
+  const envName =
+    provider === "explorium" ? "EXPLORIUM_API_KEY" : provider === "pipe0" ? "PIPE0_API_KEY" : "HEYREACH_API_KEY";
   if (process.env[envName]) return process.env[envName] as string;
   const stored = getCredential(provider);
   if (stored) return stored.accessToken;
@@ -2347,8 +2419,19 @@ async function acquireFromApi(
   } else if (disc.provider === "pipe0") {
     const filters = icp ? icpToCrustdataFilters(icp) : (disc.filters ?? {});
     prospects = await fetchPipe0CrustdataProspects({ apiKey: providerKey("pipe0"), filters, limit: size });
+  } else if (disc.provider === "linkedin" || disc.provider === "heyreach") {
+    // LinkedIn reads a pre-populated lead list (not an ICP-driven query); the ICP
+    // scores the pulled list below. List id: disc.listId or --list <id>.
+    const listId = disc.listId ?? option(rest, "--list") ?? undefined;
+    if (!listId) {
+      throw new Error(
+        "enrich acquire --source linkedin needs a HeyReach lead-list id: pass --list <id> or set acquire.discovery.linkedin.listId.",
+      );
+    }
+    const provider = createLinkedInProvider(disc.provider, providerKey("heyreach"));
+    prospects = await discoverLinkedInProspects(provider, { sourceId: listId, max: size });
   } else {
-    throw new Error(`enrich acquire: unknown discovery provider "${disc.provider}" (explorium | pipe0).`);
+    throw new Error(`enrich acquire: unknown discovery provider "${disc.provider}" (explorium | pipe0 | linkedin).`);
   }
 
   // 2. ICP fit scoring BEFORE paying for emails — only above-threshold prospects
@@ -3213,9 +3296,10 @@ async function dedupeCommand(args: string[]) {
 async function reassignCommand(args: string[]) {
   const from = option(args, "--from");
   const to = option(args, "--to");
-  if (!from || !to) {
+  const assignUnowned = args.includes("--assign-unowned");
+  if (!to || (!from && !assignUnowned)) {
     throw new Error(
-      "Usage: fullstackgtm reassign --from <ownerId> --to <ownerId> [--objects account,contact,deal] [--where <expr> …] [--except-deal-stage <stage>] [--include-closed-deals] [source options] [--reason <text>] [--max-operations <n>] [--save] [--out <path>] [--json]",
+      "Usage: fullstackgtm reassign (--from <ownerId> | --assign-unowned) --to <ownerId> [--objects account,contact,deal] [--where <expr> …] [--except-deal-stage <stage>] [--include-closed-deals] [source options] [--reason <text>] [--max-operations <n>] [--save] [--out <path>] [--json]\n\n--assign-unowned claims every OWNERLESS record (ownerId:empty) for --to — the backfill twin of `enrich acquire`'s create-time assignment.",
     );
   }
   const objects = option(args, "--objects")
@@ -3224,8 +3308,9 @@ async function reassignCommand(args: string[]) {
     .filter(Boolean) as ReassignObjectType[] | undefined;
   const snapshot = await readSnapshot(args);
   const plans = buildReassignPlans(snapshot, {
-    fromOwnerId: from,
+    fromOwnerId: from ?? undefined,
     toOwnerId: to,
+    assignUnowned,
     objects,
     where: repeatedOption(args, "--where"),
     exceptDealStage: option(args, "--except-deal-stage") ?? undefined,
@@ -3601,6 +3686,11 @@ async function apply(args: string[]) {
     }
   }
 
+  // Observability: apply-outcome tallies for the web run timeline.
+  const applyTally: Record<string, number> = { applied: 0, conflict: 0, skipped: 0, failed: 0 };
+  for (const result of run.results) applyTally[result.status] = (applyTally[result.status] ?? 0) + 1;
+  reportCounts(applyTally);
+
   if (args.includes("--json")) {
     console.log(JSON.stringify(run, null, 2));
   } else {
@@ -4097,7 +4187,7 @@ async function login(args: string[]) {
     console.log(`Stored Apollo API key in ${credentialsPath()}. \`fullstackgtm enrich append|refresh\` use it automatically.`);
     return;
   }
-  if (provider === "pipe0" || provider === "explorium") {
+  if (provider === "pipe0" || provider === "explorium" || provider === "heyreach") {
     rejectArgvSecret(args, "--token", "--key", "--api-key");
     const key = await readSecret(`${provider} API key`);
     if (!key) throw new Error(`No ${provider} key provided.`);

package/src/connectors/hubspot.ts

@@ -595,19 +595,28 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
       return { operationId: operation.id, status: "applied", detail: `Resolved/created company "${matchValue}" (${id}).`, providerData: { id } };
     }
 
-    // contact — resolve-first on the dedupe key (email by default)
+    // contact — resolve-first on the dedupe key (email by default). The match
+    // key is canonical (e.g. "linkedin"); translate it to the HubSpot property
+    // name ("hs_linkedin_url") before searching — HubSpot 400s on a filter
+    // against a property it doesn't have (there is no property named "linkedin").
     const matchKey = payload.matchKey || "email";
+    const searchProperty = HUBSPOT_DEFAULT_FIELD_MAPPINGS.contacts[matchKey] ?? matchKey;
     const matchKeyLower = `${matchKey}:${matchValue.toLowerCase()}`;
     if (createdContactsByMatch.has(matchKeyLower)) {
       return { operationId: operation.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already created earlier in this run; not duplicating.`, providerData: { id: createdContactsByMatch.get(matchKeyLower), existing: true } };
     }
-    const existing = await searchContactsBy(matchKey, matchValue);
+    const existing = await searchContactsBy(searchProperty, matchValue);
     if (existing.length > 0) {
       createdContactsByMatch.set(matchKeyLower, existing[0]);
       return { operationId: operation.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already exists (${existing.join(", ")}); resolve-first declined to create.`, providerData: { id: existing[0], existing: true } };
     }
 
     const properties: Record<string, string> = { ...payload.properties };
+    // Stamp ownership at create time so the lead is never born ownerless. The
+    // canonical ownerId maps to HubSpot's standard owner property.
+    if (payload.ownerId && !properties.hubspot_owner_id) {
+      properties.hubspot_owner_id = String(payload.ownerId);
+    }
     let created;
     try {
       created = await request(`/crm/v3/objects/${objectPath}`, {