fullstackgtm 0.56.1 → 0.58.0

package/dist/hostedArtifacts.js

@@ -1,4 +1,4 @@
-/** Best-effort artifact mirroring for a human-paired CLI profile. */
+/** Version-aware hosted artifact transport for a human-paired CLI profile. */
 import { getCredential } from "./credentials.js";
 const ENDPOINT = "/api/cli/artifact";
 const DEFAULT_TIMEOUT_MS = 4000;
@@ -17,27 +17,52 @@ function broker() {
         return null;
     }
 }
+function requestOptions(accessToken, timeoutMs) {
+    return { headers: { Authorization: `Bearer ${accessToken}` }, signal: AbortSignal.timeout(timeoutMs) };
+}
+export async function readHostedArtifact(kind, key, options = {}) {
+    const paired = broker();
+    if (!paired)
+        return { status: "unpaired" };
+    try {
+        const url = new URL(`${paired.baseUrl}${ENDPOINT}`);
+        url.searchParams.set("kind", kind);
+        url.searchParams.set("key", key);
+        const response = await (options.fetchImpl ?? fetch)(url, requestOptions(paired.accessToken, options.timeoutMs ?? DEFAULT_TIMEOUT_MS));
+        if (response.status === 404)
+            return { status: "missing" };
+        if (!response.ok)
+            return { status: "unavailable", reason: `hosted artifact request failed (HTTP ${response.status})` };
+        const state = await response.json();
+        if (!state.artifactId || !Number.isSafeInteger(state.revision) || !state.document)
+            return { status: "unavailable", reason: "hosted artifact response was invalid" };
+        return { status: "found", state };
+    }
+    catch {
+        return { status: "unavailable", reason: "hosted artifact request was unavailable" };
+    }
+}
 export async function writeHostedArtifact(artifact, options = {}) {
-    if (!artifact.key || artifact.key.length > 256 || !artifact.label || artifact.label.length > 200) {
+    if (!artifact.key || artifact.key.length > 256 || !artifact.label || artifact.label.length > 200)
         throw new Error("Hosted artifact key/label is invalid.");
-    }
     const paired = broker();
     if (!paired)
         return { status: "unpaired" };
     try {
         const response = await (options.fetchImpl ?? fetch)(`${paired.baseUrl}${ENDPOINT}`, {
-            method: "POST",
-            headers: { Authorization: `Bearer ${paired.accessToken}`, "Content-Type": "application/json" },
-            body: JSON.stringify(artifact),
-            signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+            method: "POST", ...requestOptions(paired.accessToken, options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+            headers: { Authorization: `Bearer ${paired.accessToken}`, "Content-Type": "application/json" }, body: JSON.stringify(artifact),
         });
+        if (response.status === 409) {
+            const body = await response.json();
+            return { status: "conflict", reason: "hosted ICP changed since the last sync", currentRevision: body.currentRevision, documentSha256: body.documentSha256 };
+        }
         if (!response.ok)
             return { status: "unavailable", reason: `hosted artifact request failed (HTTP ${response.status})` };
         const body = await response.json();
-        if (typeof body.created !== "boolean" || typeof body.updatedAt !== "number") {
+        if (typeof body.artifactId !== "string" || typeof body.created !== "boolean" || typeof body.updatedAt !== "number" || typeof body.revision !== "number" || typeof body.documentSha256 !== "string")
             return { status: "unavailable", reason: "hosted artifact response was invalid" };
-        }
-        return { status: "saved", created: body.created, updatedAt: body.updatedAt };
+        return { status: "saved", artifactId: body.artifactId, created: body.created, updatedAt: body.updatedAt, revision: body.revision, documentSha256: body.documentSha256, unchanged: body.unchanged === true };
     }
     catch {
         return { status: "unavailable", reason: "hosted artifact request was unavailable" };

package/dist/icp.d.ts

@@ -71,6 +71,9 @@ export type Icp = {
     scoring?: {
         /** minimum fit (0..1) for a prospect to become a create_record op. Default 0.5. */
         threshold?: number;
+        /** Require a literal persona.titleKeywords phrase in title/headline. This
+         * disables the broader function fallback for high-precision sourcing. */
+        requireTitleKeyword?: boolean;
     };
 };
 export declare const DEFAULT_FIT_THRESHOLD = 0.5;

package/dist/icp.js

@@ -381,15 +381,18 @@ export function scoreProspectAgainstIcp(prospect, icp) {
     const keywords = (icp.persona.titleKeywords ?? []).map((k) => k.toLowerCase());
     const levels = (icp.persona.jobLevels ?? []).map((l) => l.toLowerCase());
     const depts = (icp.persona.departments ?? []).map((d) => d.toLowerCase());
+    const exactTitleKeyword = keywords.find((keyword) => title.includes(keyword));
+    if (icp.scoring?.requireTitleKeyword && keywords.length && !exactTitleKeyword) {
+        return { score: 0, reasons: ["title does not contain a required ICP keyword"] };
+    }
     let score = 0;
     let weightSum = 0;
     if (keywords.length) {
         weightSum += 0.6;
-        const exact = keywords.find((k) => title.includes(k));
-        const functional = exact ? undefined : roleKeywords(icp).find((keyword) => title.includes(keyword));
-        if (exact) {
+        const functional = exactTitleKeyword ? undefined : roleKeywords(icp).find((keyword) => title.includes(keyword));
+        if (exactTitleKeyword) {
             score += 0.6;
-            reasons.push(`title matches ICP keyword "${exact}"`);
+            reasons.push(`title matches ICP keyword "${exactTitleKeyword}"`);
         }
         else if (functional) {
             score += 0.45;

package/dist/icpSync.d.ts

@@ -0,0 +1,55 @@
+import { type Icp } from "./icp.ts";
+import { type HostedArtifactState } from "./hostedArtifacts.ts";
+export type IcpSyncState = {
+    version: 1;
+    artifactId: string;
+    key: string;
+    domain: string;
+    revision: number;
+    localIcpSha256: string;
+    hostedDocumentSha256?: string;
+    syncedAt: string;
+};
+export type IcpSyncStatus = {
+    state: "unpaired" | "missing_hosted" | "in_sync" | "local_changed" | "hosted_changed" | "conflict" | "untracked" | "unavailable";
+    localIcpSha256: string;
+    hostedRevision?: number;
+    trackedRevision?: number;
+    reason?: string;
+};
+export declare function classifyIcpSync(localHash: string, hostedRevision: number, hostedHash: string, tracked: IcpSyncState | null): IcpSyncStatus["state"];
+export declare function canonicalJson(value: unknown): string;
+export declare const icpSha256: (icp: Icp) => string;
+export declare function artifactKeyForDomain(domain: string): string;
+export declare const sidecarPathFor: (icpPath: string) => string;
+export declare function readLocalIcp(path: string): Icp;
+export declare function extractHostedIcp(state: HostedArtifactState): Icp;
+export declare function readIcpSyncState(icpPath: string): IcpSyncState | null;
+export declare function writeIcpSyncState(icpPath: string, state: IcpSyncState): void;
+export declare function getIcpSyncStatus(icpPath: string, domain: string): Promise<{
+    status: IcpSyncStatus;
+    hosted?: HostedArtifactState;
+    local: Icp;
+}>;
+export declare function markIcpSynced(icpPath: string, domain: string, hosted: HostedArtifactState | {
+    artifactId: string;
+    revision: number;
+    documentSha256?: string;
+}, icp: Icp): void;
+export declare function pushIcp(icpPath: string, domain: string, changeSummary?: string): Promise<{
+    status: "conflict";
+    checked: {
+        status: IcpSyncStatus;
+        hosted?: HostedArtifactState;
+        local: Icp;
+    };
+    result?: undefined;
+} | {
+    status: "conflict" | "unpaired" | "unavailable" | "saved";
+    result: import("./hostedArtifacts.ts").HostedArtifactResult;
+    checked: {
+        status: IcpSyncStatus;
+        hosted?: HostedArtifactState;
+        local: Icp;
+    };
+}>;

package/dist/icpSync.js

@@ -0,0 +1,93 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { parseIcp } from "./icp.js";
+import { readSecureRegularFile, writeSecureFileAtomic } from "./secureFile.js";
+import { readHostedArtifact, writeHostedArtifact } from "./hostedArtifacts.js";
+export function classifyIcpSync(localHash, hostedRevision, hostedHash, tracked) {
+    if (!tracked)
+        return localHash === hostedHash ? "in_sync" : "untracked";
+    const localChanged = localHash !== tracked.localIcpSha256;
+    const hostedChanged = hostedRevision !== tracked.revision;
+    return localChanged && hostedChanged ? "conflict" : localChanged ? "local_changed" : hostedChanged ? "hosted_changed" : "in_sync";
+}
+export function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const object = value;
+    return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`).join(",")}}`;
+}
+export const icpSha256 = (icp) => createHash("sha256").update(canonicalJson(icp)).digest("hex");
+export function artifactKeyForDomain(domain) {
+    const candidate = /^https?:\/\//i.test(domain.trim()) ? domain.trim() : `https://${domain.trim()}`;
+    let parsed;
+    try {
+        parsed = new URL(candidate);
+    }
+    catch {
+        throw new Error(`Invalid company domain: ${domain}`);
+    }
+    const hostname = parsed.hostname.toLowerCase().replace(/^www\./, "").replace(/\.$/, "");
+    if (!hostname.includes("."))
+        throw new Error(`Invalid public company domain: ${domain}`);
+    return `icp:${hostname}`;
+}
+export const sidecarPathFor = (icpPath) => resolve(dirname(resolve(icpPath)), ".fullstackgtm", `${resolve(icpPath).split(/[\\/]/).pop()}.sync.json`);
+export function readLocalIcp(path) { return parseIcp(readSecureRegularFile(resolve(path))); }
+export function extractHostedIcp(state) {
+    const root = state.document && typeof state.document === "object" && !Array.isArray(state.document) ? state.document : {};
+    return parseIcp(JSON.stringify(root.icp ?? state.document));
+}
+export function readIcpSyncState(icpPath) {
+    const path = sidecarPathFor(icpPath);
+    if (!existsSync(path))
+        return null;
+    try {
+        const value = JSON.parse(readSecureRegularFile(path));
+        return value?.version === 1 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeIcpSyncState(icpPath, state) {
+    const path = sidecarPathFor(icpPath);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeSecureFileAtomic(path, `${JSON.stringify(state, null, 2)}\n`);
+}
+export async function getIcpSyncStatus(icpPath, domain) {
+    const local = readLocalIcp(icpPath);
+    const localHash = icpSha256(local);
+    const tracked = readIcpSyncState(icpPath);
+    const read = await readHostedArtifact("icp", artifactKeyForDomain(domain));
+    if (read.status === "unpaired")
+        return { local, status: { state: "unpaired", localIcpSha256: localHash } };
+    if (read.status === "missing")
+        return { local, status: { state: "missing_hosted", localIcpSha256: localHash } };
+    if (read.status === "unavailable")
+        return { local, status: { state: "unavailable", localIcpSha256: localHash, reason: read.reason } };
+    const hostedHash = icpSha256(extractHostedIcp(read.state));
+    const state = classifyIcpSync(localHash, read.state.revision, hostedHash, tracked);
+    return { local, hosted: read.state, status: { state, localIcpSha256: localHash, hostedRevision: read.state.revision, trackedRevision: tracked?.revision } };
+}
+export function markIcpSynced(icpPath, domain, hosted, icp) {
+    const key = artifactKeyForDomain(domain);
+    const normalizedDomain = key.slice("icp:".length);
+    writeIcpSyncState(icpPath, { version: 1, artifactId: hosted.artifactId, key, domain: normalizedDomain, revision: hosted.revision, localIcpSha256: icpSha256(icp), hostedDocumentSha256: hosted.documentSha256, syncedAt: new Date().toISOString() });
+}
+export async function pushIcp(icpPath, domain, changeSummary) {
+    const checked = await getIcpSyncStatus(icpPath, domain);
+    if (checked.status.state === "conflict" || checked.status.state === "hosted_changed" || checked.status.state === "untracked")
+        return { status: "conflict", checked };
+    const current = checked.hosted;
+    const root = current?.document && typeof current.document === "object" && !Array.isArray(current.document) ? current.document : {};
+    const key = artifactKeyForDomain(domain);
+    const normalizedDomain = key.slice("icp:".length);
+    const document = Object.keys(root).length ? { ...root, icp: checked.local, humanReview: { reviewedAt: new Date().toISOString(), source: "cli" } } : { company: { domain: normalizedDomain }, icp: checked.local, evidence: [], humanReview: { reviewedAt: new Date().toISOString(), source: "cli" } };
+    const result = await writeHostedArtifact({ kind: "icp", key, label: checked.local.name, domain: normalizedDomain, document, expectedRevision: current?.revision ?? 0, changeSummary });
+    if (result.status === "saved")
+        markIcpSynced(icpPath, domain, { artifactId: result.artifactId, revision: result.revision, documentSha256: result.documentSha256 }, checked.local);
+    return { status: result.status, result, checked };
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { auditSnapshot, defaultPolicy } from "./audit.ts";
 export { DEFAULT_ICP_DERIVATION_MODEL, OPENROUTER_API_BASE, deriveWebsiteIcp, normalizeCompanyWebsite, websiteText, icpReviewSegments, type WebsiteIcpDerivation, type WebsiteIcpEvidence, type IcpReviewSegment, type IcpDerivationProgress, } from "./icpDerive.ts";
+export { artifactKeyForDomain, classifyIcpSync, extractHostedIcp, getIcpSyncStatus, icpSha256, markIcpSynced, pushIcp, readIcpSyncState, sidecarPathFor, type IcpSyncState, type IcpSyncStatus, } from "./icpSync.ts";
 export { acquireCheckpointId, acquireCheckpointsDir, createFileAcquireCheckpointStore, validateAcquireCheckpoint, validateAcquireCheckpointKey, type AcquireCheckpoint, type AcquireCheckpointKey, type AcquireCheckpointStore, type AcquireContinuation, } from "./acquireCheckpoint.ts";
 export { matchesTerritory, parseAssignmentPolicy, resolveAssignment, type AssignmentContext, type AssignmentPolicy, type AssignmentResult, type AssignmentStrategy, type TerritoryRule, } from "./assign.ts";
 export { buildBulkUpdatePlan, isFilterableField, parseWhere, type BulkUpdateOptions } from "./bulkUpdate.ts";
@@ -27,6 +28,7 @@ export { claimHostedPlanApply, hostedPlanDigest, hostedReviewDocument, readHoste
 export { scaffoldWorkspace, starterEnrichConfig, starterIcp, starterPlaybook, type InitProvider, type InitSource, type ScaffoldFile, type ScaffoldOptions, } from "./init.ts";
 export { appendCoverage, classifyAccount, classifyCoverage, computeCoverage, coverageCountsFromSnapshot, coveredAccounts, coverageToText, crmCheckableCriteria, deriveAcvFromClosedWon, deriveBuyersPerAccount, estimateTam, loadTamModel, projectEta, readCoverageTimeline, saveTamModel, tamDir, tamReportToMarkdown, type AccountTamClass, type AcvBasis, type DerivedAcv, type DerivedBuyers, type EstimateTamInput, type TamClassified, type TamCoverage, type TamCoverageCounts, type TamCrossCheck, type TamEta, type TamModel, type TamTargeting, type TamUniverse, } from "./tam.ts";
 export { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords, type ApolloClient, type ApolloClientOptions, type ApolloPullKey, type ApolloPullResult, } from "./enrichApollo.ts";
+export { createZoomInfoClient, pullZoomInfoRecords, type ZoomInfoClient, type ZoomInfoClientOptions, type ZoomInfoCommandResult, type ZoomInfoCommandRunner, type ZoomInfoPullKey, type ZoomInfoPullOptions, type ZoomInfoPullResult, } from "./enrichZoomInfo.ts";
 export { diffFindings, diffSnapshots, diffToMarkdown, type CollectionDiff, type FieldChange, type FindingsDrift, type RecordChange, type SnapshotDiff, } from "./diff.ts";
 export { mergeSnapshots, type MergeConflict, type MergeMatch, type MergeReport, type MergeSuggestion, } from "./merge.ts";
 export { createFilePlanStore, type PlanStore, type StoredPlan } from "./planStore.ts";

package/dist/index.js

@@ -1,5 +1,6 @@
 export { auditSnapshot, defaultPolicy } from "./audit.js";
 export { DEFAULT_ICP_DERIVATION_MODEL, OPENROUTER_API_BASE, deriveWebsiteIcp, normalizeCompanyWebsite, websiteText, icpReviewSegments, } from "./icpDerive.js";
+export { artifactKeyForDomain, classifyIcpSync, extractHostedIcp, getIcpSyncStatus, icpSha256, markIcpSynced, pushIcp, readIcpSyncState, sidecarPathFor, } from "./icpSync.js";
 export { acquireCheckpointId, acquireCheckpointsDir, createFileAcquireCheckpointStore, validateAcquireCheckpoint, validateAcquireCheckpointKey, } from "./acquireCheckpoint.js";
 export { matchesTerritory, parseAssignmentPolicy, resolveAssignment, } from "./assign.js";
 export { buildBulkUpdatePlan, isFilterableField, parseWhere } from "./bulkUpdate.js";
@@ -27,6 +28,7 @@ export { claimHostedPlanApply, hostedPlanDigest, hostedReviewDocument, readHoste
 export { scaffoldWorkspace, starterEnrichConfig, starterIcp, starterPlaybook, } from "./init.js";
 export { appendCoverage, classifyAccount, classifyCoverage, computeCoverage, coverageCountsFromSnapshot, coveredAccounts, coverageToText, crmCheckableCriteria, deriveAcvFromClosedWon, deriveBuyersPerAccount, estimateTam, loadTamModel, projectEta, readCoverageTimeline, saveTamModel, tamDir, tamReportToMarkdown, } from "./tam.js";
 export { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords, } from "./enrichApollo.js";
+export { createZoomInfoClient, pullZoomInfoRecords, } from "./enrichZoomInfo.js";
 export { diffFindings, diffSnapshots, diffToMarkdown, } from "./diff.js";
 export { mergeSnapshots, } from "./merge.js";
 export { createFilePlanStore } from "./planStore.js";

package/dist/runReport.js

@@ -85,6 +85,10 @@ let inflightHeartbeat = null;
  * commands simply never stream.
  */
 export function beginRunReport(args, startedAt) {
+    counts = undefined;
+    findings = undefined;
+    crm = undefined;
+    events.length = 0;
     lastHeartbeatAt = 0;
     heartbeatBroker = undefined;
     inflightHeartbeat = null;
@@ -186,6 +190,13 @@ export async function flushRunReport(args, status, startedAt, error) {
     const identity = runIdentity(args, startedAt);
     if (!identity)
         return;
+    // A successful command with no result, finding, event, or live progress is
+    // terminal telemetry rather than something a person can explore. Keep it
+    // out of Runs. Errors always report; heartbeating commands still send their
+    // terminal status so an in-progress row cannot be stranded.
+    const hasUsefulOutput = Boolean((counts && Object.keys(counts).length > 0) || findings?.length || events.length);
+    if (status === "success" && !hasUsefulOutput && lastHeartbeatAt === 0)
+        return;
     const broker = getCredential("broker");
     if (!broker?.baseUrl || !broker.accessToken)
         return; // opt-in: only when paired

package/docs/api.md

@@ -126,7 +126,7 @@ Four flags name "where data comes from / goes to"; they are not interchangeable:
 | Flag | Meaning | Values |
 |---|---|---|
 | `--provider` | The CRM the data lives in — the system a snapshot is read from and an approved plan is applied to. | `hubspot`, `salesforce` (plus `stripe`, read-only) |
-| `--source` | The external data source feeding a verb: an enrichment/discovery vendor on `enrich`/`tam` (`--source apollo`, `acquire --source pipe0`), a staged-ingest label on `enrich ingest`, on `signals fetch` which no-auth ATS board adapters to scan, or `exa` on `signals discover`. | `apollo`, `clay`, `pipe0`, `explorium`, `theirstack`, `linkedin` (HeyReach), `exa`; `greenhouse` / `lever` / `ashby` on `signals fetch` |
+| `--source` | The external data source feeding a verb: an enrichment/discovery vendor on `enrich`/`tam` (`--source zoominfo`, `--source apollo`, `acquire --source pipe0`), a staged-ingest label on `enrich ingest`, on `signals fetch` which no-auth ATS board adapters to scan, or `exa` on `signals discover`. | `zoominfo` (official `gtm` CLI), `apollo`, `clay`, `pipe0`, `explorium`, `theirstack`, `linkedin` (HeyReach), `exa`; `greenhouse` / `lever` / `ashby` on `signals fetch` |
 | `--connector` | A signal-intake source connector on `signals fetch`: pulls candidate signals from a connected platform or the local webhook spool into the signal ledger. | `file`, `serpapi-news`, `hubspot-forms` |
 | `--channel` | Where a plan's output is delivered. On `apply`, the delivery terminus — a plan applies to `--provider <crm>` *or* `--channel outbox` (render approved openers to a local outbox file; transmits nothing), never both. On `draft`, which outreach channel the opener is drafted for (shapes the emitted op). | `apply`: `outbox` · `draft`: `email`, `linkedin`, `task` |
 

package/docs/architecture.md

@@ -103,6 +103,11 @@ replays automatically: reconcile provider state, then `plans recover ...
   reconciliation. Review documents are immutable/hash-bound; hosted approval
   becomes executable only after the CLI verifies it and generates local HMAC
   signatures. Hosted never owns the apply lease for CLI-origin plans.
+- `hostedArtifacts.ts` + `icpSync.ts` — version-aware artifact transport and
+  conservative bidirectional ICP reconciliation. Published revisions use
+  compare-and-swap; a private sidecar binds a local ICP hash to its last hosted
+  revision. Divergent arrays are never auto-merged and hosted changes never
+  silently replace the execution-local ICP file.
 - `assign.ts` — `AssignmentPolicy` (fixed / round-robin / territory /
   account-owner): the pure owner-routing rule `buildAcquirePlan` stamps onto new
   leads (never born ownerless) and `reassign --assign-unowned` reuses to backfill.

package/llms.txt

@@ -149,8 +149,9 @@ approve → apply.
 
 ## Key invariants (enrich)
 
-`fullstackgtm enrich` is governed enrichment: `append` pulls (Apollo, BYO key
-via `login apollo`/APOLLO_API_KEY) or reads data staged by `ingest` (Clay CSV
+`fullstackgtm enrich` is governed enrichment: `append` pulls from Apollo (BYO key
+via `login apollo`/APOLLO_API_KEY) or ZoomInfo (official `gtm` CLI; `gtm auth login`),
+or reads data staged by `ingest` (Clay CSV
 exports / webhook payload JSON), matches source records to CRM records via
 ordered keys in `enrich.config.json` (unique hit wins; ambiguity skips or
 becomes `requires_human_record_selection` placeholders — never a coin flip),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fullstackgtm",
-  "version": "0.56.1",
-  "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
+  "version": "0.58.0",
+  "description": "Open-source CRM control plane and safety toolbox for AI agents: deterministic audits, reviewable patch plans, approval-gated write-back, conflict detection, and entity resolution for HubSpot and Salesforce.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM LLC <ryan@fullstackgtm.com> (https://fullstackgtm.com)",
   "homepage": "https://github.com/fullstackgtm/core#readme",

package/src/cli/enrich.ts

@@ -19,7 +19,8 @@ import { progressReporter, reportCounts, reportEvent } from "../runReport.ts";
 import { ACQUIRE_STAGES, composeListeners, createProgressEmitter } from "../progress.ts";
 import { createLinkedInProvider, discoverLinkedInProspects } from "../acquireLinkedIn.ts";
 import { clayPeopleFilterRoutes, fitThreshold, icpToClayInvestmentCompanyFilters, icpToClayPeopleFilters, icpToCrustdataFilters, icpToExploriumFilters, scoreProspectAgainstIcp, type Icp } from "../icp.ts";
-import { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords, type ApolloPullKey } from "../enrichApollo.ts";
+import { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords, type ApolloPullKey, type ApolloPullOptions } from "../enrichApollo.ts";
+import { createZoomInfoClient, pullZoomInfoRecords } from "../enrichZoomInfo.ts";
 import type { CanonicalGtmSnapshot, CreateRecordPayload } from "../types.ts";
 import { isSpoolPath, readSpoolPath } from "../spoolFiles.ts";
 import { isOptionValue, loadIcp, numericOption, option, readSnapshot, saveRequested } from "./shared.ts";
@@ -28,11 +29,13 @@ import { unknownSubcommandError } from "./suggest.ts";
 import { box, colorEnabled, createProgressRenderer, createStatusLine, formatBar, formatDuration, paint, scoreColor, truncateToWidth, type Paint } from "./ui.ts";
 import { compactPlan, verbosePlanRequested } from "./planOutput.ts";
 import type { AcquireBudget } from "../acquireMeter.ts";
+import { writeHostedArtifact } from "../hostedArtifacts.ts";
+import { readIcpSyncState } from "../icpSync.ts";
 
 
 /**
- * The enrich layer: governed append/refresh of third-party data (Apollo pull,
- * Clay ingest) into the CRM through the normal dry-run → approval → apply
+ * The enrich layer: governed append/refresh of third-party data (Apollo or
+ * ZoomInfo pull, Clay ingest) into the CRM through the normal dry-run → approval → apply
  * contract. State lives in the profile-scoped run store (checkpoint,
  * staleness ledger, observability in one); scheduling belongs to the
  * horizontal scheduler — enrich owns no cron logic.
@@ -75,8 +78,9 @@ 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,
-webhook payload JSON), matches source records to CRM records via the ordered
+APOLLO_API_KEY; ZoomInfo — official \`gtm\` CLI via \`gtm auth login\`) or reads
+data staged by \`enrich ingest\` (Clay CSV exports, webhook payload JSON),
+matches source records to CRM records via the ordered
 match keys in enrich.config.json (unique hit wins; zero hits falls through to
 the next key; multiple hits skip or flow into the suggest chain, per
 onAmbiguous), and emits a fill-blanks-only patch plan. Without --save it
@@ -259,6 +263,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
     // piped) and, via the composed reporter, heartbeat to a paired hosted app.
     // The meter reading (creates vs headroom + budget burn) rides the same
     // emitter, feeding the dashboard's gauge without printing anything new.
+    const acquireRunLabel = option(rest, "--run-label") ?? `acquire-${source}-${today}`;
     let result: ReturnType<typeof buildAcquirePlan>;
     try {
       acquireProgress.stage(ACQUIRE_STAGES[2], 2, ACQUIRE_STAGES.length);
@@ -275,7 +280,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         source,
         snapshot,
         records,
-        runLabel: option(rest, "--run-label") ?? `acquire-${source}-${today}`,
+        runLabel: acquireRunLabel,
         maxRecords: cap,
         progress: acquireProgress,
       });
@@ -293,7 +298,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
     // Observability: headline metrics for the web run timeline (paired users).
     reportCounts({
       sourced: result.counts.fetched,
-      created: result.counts.created,
+      proposed: result.counts.created,
       withheldByMeter: result.counts.withheldByMeter,
       skippedInCrm: apiSkippedCrm,
       skippedSeen: apiSkippedSeen,
@@ -302,6 +307,16 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
 
     const meterLine = formatAcquireMeter(headroom, costPerRecord);
     const gaugeLine = acquireGaugeLine(headroom, config.acquire.budget ?? {}, paint(colorEnabled(process.stdout)));
+    const icpPath = resolve(process.cwd(), option(rest, "--icp") ?? "icp.json");
+    const trackedIcp = existsSync(icpPath) ? readIcpSyncState(icpPath) : null;
+    const leadMirror = await writeHostedArtifact({
+      kind: "lead_run", key: `leads:${result.plan.id}`, label: acquireRunLabel,
+      domain: trackedIcp?.domain,
+      document: { runLabel: acquireRunLabel, createdAt: new Date().toISOString(), source, targetDomain: option(rest, "--company-domain"), counts: result.counts,
+        plan: result.plan, icpRef: trackedIcp ? { artifactId: trackedIcp.artifactId, domain: trackedIcp.domain, revision: trackedIcp.revision, localIcpSha256: trackedIcp.localIcpSha256 } : undefined },
+    });
+    if (leadMirror.status === "saved") console.error(`Recorded lead preview against${trackedIcp ? ` ICP revision ${trackedIcp.revision}` : " the local untracked ICP"}.`);
+    else if (leadMirror.status === "unavailable") console.error(`Warning: ${leadMirror.reason}. The local lead preview is unchanged.`);
     if (!save) {
       printAcquireOutput({
         args: rest,
@@ -424,10 +439,19 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
       );
       return;
     }
-    const client = createApolloClient({
-      getApiKey: () => apolloApiKey(),
-      apiBaseUrl: process.env.APOLLO_API_BASE_URL,
-    });
+    if (source !== "apollo" && source !== "zoominfo") {
+      throw new Error(
+        `enrich ${mode}: api source "${source}" supports acquire discovery, not snapshot enrichment. ` +
+          "Use apollo or zoominfo for append/refresh, or stage records with `enrich ingest`.",
+      );
+    }
+    const apolloClient = source === "apollo"
+      ? createApolloClient({
+          getApiKey: () => apolloApiKey(),
+          apiBaseUrl: process.env.APOLLO_API_BASE_URL,
+        })
+      : null;
+    const zoomInfoClient = source === "zoominfo" ? createZoomInfoClient() : null;
     if (save) {
       run = await openEnrichRun(store, source, mode, option(rest, "--run-label"), today);
       if (run.cursor) {
@@ -443,7 +467,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
     let pullProcessed = 0;
     let result: Awaited<ReturnType<typeof pullApolloRecords>>;
     try {
-      result = await pullApolloRecords(client, pullKeys, {
+      const pullOptions: ApolloPullOptions = {
         resumeAfter: run?.cursor ?? null,
         onProgress: async (progress) => {
           if (pullBar.active) {
@@ -461,7 +485,10 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
           if (progress.miss) run.missedKeys = [...(run.missedKeys ?? []), progress.miss.value];
           await store.update(run);
         },
-      });
+      };
+      result = source === "zoominfo"
+        ? await pullZoomInfoRecords(zoomInfoClient!, pullKeys, pullOptions)
+        : await pullApolloRecords(apolloClient!, pullKeys, pullOptions);
     } finally {
       pullBar.done();
     }

package/src/cli/help.ts

@@ -90,7 +90,7 @@ Usage:
   fullstackgtm enrich refresh [--source apollo] [--stale-days <n>] [--save] [--config <path>] [source options]
   fullstackgtm enrich ingest <file.csv|payload.json|spool.jsonl|spool-dir> --source clay [--run-label <label>]
   fullstackgtm enrich status [--runs] [--source <id>] [--json]
-                                               governed enrichment: pull (Apollo) or stage (Clay) third-party
+                                               governed enrichment: pull (Apollo/ZoomInfo) or stage (Clay) third-party
                                                data, match it to CRM records deterministically, and emit a
                                                fill-blanks-only patch plan through the normal dry-run →
                                                approve → apply gate. refresh re-checks stale stamped fields
@@ -524,7 +524,7 @@ export const HELP: Record<string, HelpEntry> = {
     seeAlso: ["enrich", "plans", "apply", "resolve"],
   },
   enrich: {
-    summary: "governed third-party enrichment (Apollo/Clay), fill-blanks-only",
+    summary: "governed third-party enrichment (Apollo/ZoomInfo/Clay), fill-blanks-only",
     phase: "Remediate",
     synopsis: ["fullstackgtm enrich append|refresh|ingest|status …  (run `enrich --help` for full options)"],
     detail:
@@ -701,14 +701,14 @@ export const COMMAND_FLAGS: Record<string, string[]> = {
   merge: ["--input", "--out", "--json"],
   market: ["--category", "--config", "--vendor", "--snapshot", "--task-account", "--task-deal", "--capture-run", "--run", "--prior-run", "--diff", "--from", "--calls", "--anchor", "--min-mentions", "--max-claims", "--promote-lift", "--model", "--format", "--auto", "--unverified", "--save", "--dry-run", "--verbose", "--json", "--out"],
   tam: [...SOURCE_FLAGS, "--source", "--name", "--icp", "--accounts", "--acv", "--acv-basis", "--acv-from-crm", "--deal-period", "--buyers-per-account", "--cross-checks", "--max", "--max-credits", "--usd-per-credit", "--dry-run", "--confirm", "--cron", "--label", "--save", "--verbose", "--json", "--out"],
-  icp: [...SOURCE_FLAGS, "--name", "--icp", "--domain", "--no-interactive", "--signals-from", "--with-history", "--prompt", "--min-score", "--from-judge", "--golden", "--against-outcomes", "--min-accuracy", "--model", "--label", "--save", "--verbose", "--json", "--out"],
+  icp: [...SOURCE_FLAGS, "--name", "--icp", "--domain", "--no-interactive", "--signals-from", "--with-history", "--prompt", "--min-score", "--from-judge", "--golden", "--against-outcomes", "--min-accuracy", "--model", "--label", "--change-summary", "--force", "--save", "--verbose", "--json", "--out"],
   signals: ["--bucket", "--source", "--connector", "--connector-opt", "--watchlist", "--keywords", "--from", "--label", "--since", "--icp", "--max-accounts", "--max-results", "--max-searches", "--max-usd", "--account", "--contact", "--unjudged", "--touch", "--result", "--save", "--verbose", "--json", "--explain"],
   draft: ["--from-judge", "--min-score", "--prompt", "--model", "--channel", "--save", "--dry-run", "--verbose", "--json", "--out"],
   schedule: ["--cron", "--label", "--provider", "--trigger", "--timer", "--runs", "--verbose", "--json"],
 };
 
 export const FLAGS_WITH_VALUES = new Set([
-  "--account", "--account-id", "--accounts", "--acv", "--acv-basis", "--after", "--anchor", "--api-key", "--approve", "--archive", "--assign-owner", "--attendees", "--before", "--bucket", "--buyers-per-account", "--call", "--call-type", "--calls", "--capture-run", "--category", "--channel", "--client", "--client-id", "--client-secret", "--company-domain", "--config", "--connector", "--connector-opt", "--contact", "--cron", "--cross-checks", "--deal", "--deal-period", "--diff", "--domain", "--email", "--except-deal-stage", "--format", "--from", "--from-judge", "--golden", "--guard", "--icp", "--in", "--input", "--instance-url", "--keep", "--key", "--keywords", "--label", "--list", "--login-url", "--match", "--match-property", "--max", "--max-accounts", "--max-claims", "--max-credits", "--max-examples", "--max-operations", "--max-results", "--max-searches", "--max-usd", "--min-accuracy", "--min-confidence", "--min-mentions", "--min-score", "--model", "--name", "--objects", "--operations", "--out", "--pipeline", "--plan", "--plan-id", "--policy", "--port", "--prepared-by", "--prior-run", "--profile", "--promote-lift", "--prompt", "--provider", "--reason", "--require", "--result", "--rubric", "--rule", "--rules", "--run", "--run-label", "--runs", "--scan-limit", "--scopes", "--seed", "--set", "--signals-from", "--since", "--snapshot", "--source", "--staged-run", "--stale-days", "--status", "--task-account", "--task-deal", "--timer", "--title", "--to", "--today", "--token", "--token-env", "--touch", "--transcript", "--trigger", "--usd-per-credit", "--value", "--values-from", "--vendor", "--via", "--watchlist", "--where",
+  "--account", "--account-id", "--accounts", "--acv", "--acv-basis", "--after", "--anchor", "--api-key", "--approve", "--archive", "--assign-owner", "--attendees", "--before", "--bucket", "--buyers-per-account", "--call", "--call-type", "--calls", "--capture-run", "--category", "--change-summary", "--channel", "--client", "--client-id", "--client-secret", "--company-domain", "--config", "--connector", "--connector-opt", "--contact", "--cron", "--cross-checks", "--deal", "--deal-period", "--diff", "--domain", "--email", "--except-deal-stage", "--format", "--from", "--from-judge", "--golden", "--guard", "--icp", "--in", "--input", "--instance-url", "--keep", "--key", "--keywords", "--label", "--list", "--login-url", "--match", "--match-property", "--max", "--max-accounts", "--max-claims", "--max-credits", "--max-examples", "--max-operations", "--max-results", "--max-searches", "--max-usd", "--min-accuracy", "--min-confidence", "--min-mentions", "--min-score", "--model", "--name", "--objects", "--operations", "--out", "--pipeline", "--plan", "--plan-id", "--policy", "--port", "--prepared-by", "--prior-run", "--profile", "--promote-lift", "--prompt", "--provider", "--reason", "--require", "--result", "--rubric", "--rule", "--rules", "--run", "--run-label", "--runs", "--scan-limit", "--scopes", "--seed", "--set", "--signals-from", "--since", "--snapshot", "--source", "--staged-run", "--stale-days", "--status", "--task-account", "--task-deal", "--timer", "--title", "--to", "--today", "--token", "--token-env", "--touch", "--transcript", "--trigger", "--usd-per-credit", "--value", "--values-from", "--vendor", "--via", "--watchlist", "--where",
 ]);
 
 // Lifecycle-grouped front door. One line per verb, organized by the