fullstackgtm 0.56.1 → 0.58.0

package/dist/cli/enrich.d.ts

@@ -1,6 +1,6 @@
 /**
- * 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.

package/dist/cli/enrich.js

@@ -19,15 +19,18 @@ import { ACQUIRE_STAGES, composeListeners, createProgressEmitter } from "../prog
 import { createLinkedInProvider, discoverLinkedInProspects } from "../acquireLinkedIn.js";
 import { clayPeopleFilterRoutes, fitThreshold, icpToClayInvestmentCompanyFilters, icpToClayPeopleFilters, icpToCrustdataFilters, icpToExploriumFilters, scoreProspectAgainstIcp } from "../icp.js";
 import { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords } from "../enrichApollo.js";
+import { createZoomInfoClient, pullZoomInfoRecords } from "../enrichZoomInfo.js";
 import { isSpoolPath, readSpoolPath } from "../spoolFiles.js";
 import { isOptionValue, loadIcp, numericOption, option, readSnapshot, saveRequested } from "./shared.js";
 import { providerKey } from "./tam.js";
 import { unknownSubcommandError } from "./suggest.js";
 import { box, colorEnabled, createProgressRenderer, createStatusLine, formatBar, formatDuration, paint, scoreColor, truncateToWidth } from "./ui.js";
 import { compactPlan, verbosePlanRequested } from "./planOutput.js";
+import { writeHostedArtifact } from "../hostedArtifacts.js";
+import { readIcpSyncState } from "../icpSync.js";
 /**
- * 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.
@@ -69,8 +72,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
@@ -230,6 +234,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;
         try {
             acquireProgress.stage(ACQUIRE_STAGES[2], 2, ACQUIRE_STAGES.length);
@@ -242,7 +247,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,
             });
@@ -257,7 +262,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,
@@ -265,6 +270,18 @@ 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,
@@ -372,10 +389,17 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
                 : "Nothing to refresh: no stale records carry a pull key (companies need a domain, contacts an email).");
             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) {
@@ -389,7 +413,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         let pullProcessed = 0;
         let result;
         try {
-            result = await pullApolloRecords(client, pullKeys, {
+            const pullOptions = {
                 resumeAfter: run?.cursor ?? null,
                 onProgress: async (progress) => {
                     if (pullBar.active) {
@@ -408,7 +432,10 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
                         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/dist/cli/help.js

@@ -86,7 +86,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
@@ -481,7 +481,7 @@ export const HELP = {
         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: "Pull (Apollo) or stage (Clay) 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.",
@@ -639,13 +639,13 @@ export const COMMAND_FLAGS = {
     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
 // Prevent→Detect→Remediate→Verify loop so a new user sees ~6 jobs, not 22 verbs.

package/dist/cli/icp.js

@@ -1,5 +1,5 @@
 // Extracted verbatim from src/cli.ts (mechanical split, no behavior change).
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { emitKeypressEvents } from "node:readline";
 import { createInterface } from "node:readline/promises";
 import { resolve } from "node:path";
@@ -8,13 +8,15 @@ import { fitThreshold, icpFromAnswers, icpToCrustdataFilters, icpToExploriumFilt
 import { createFileSignalStore, DEFAULT_SIGNALS_CONFIG } from "../signals.js";
 import { createFileJudgeStore, DEFAULT_JUDGE_PROMPT, judgeRunId, judgeSignals } from "../judge.js";
 import { DEFAULT_GOLDEN_NOW_ISO, DEFAULT_GOLDEN_SET, DEFAULT_MIN_ACCURACY, defaultJudgeFn, gradeAgainstOutcomes, gradeJudge, parseGoldenSet } from "../judgeEval.js";
-import { loadIcp, numericOption, option, readSecret, readSnapshot, resolveLlmBaseUrls, saveRequested } from "./shared.js";
+import { loadIcp, numericOption, option, readPackageInfo, readSecret, readSnapshot, resolveLlmBaseUrls, saveRequested } from "./shared.js";
 import { createStatusLine } from "./ui.js";
 import { box, colorEnabled, paint, truncateToWidth } from "./ui.js";
 import { getCredential, storeCredential } from "../credentials.js";
 import { deriveWebsiteIcp, icpReviewSegments, OPENROUTER_API_BASE } from "../icpDerive.js";
 import { unknownSubcommandError } from "./suggest.js";
-import { writeHostedArtifact } from "../hostedArtifacts.js";
+import { readHostedArtifact, writeHostedArtifact } from "../hostedArtifacts.js";
+import { artifactKeyForDomain, extractHostedIcp, getIcpSyncStatus, markIcpSynced, pushIcp, readIcpSyncState } from "../icpSync.js";
+import { writeSecureFileAtomic } from "../secureFile.js";
 function renderJudgeDecisions(decisions) {
     if (decisions.length === 0)
         return "No accounts cleared the score threshold.";
@@ -192,6 +194,14 @@ export async function icpCommand(args) {
   fullstackgtm icp interview                      emit the interview spec (an agent drives it with AskUserQuestion)
   fullstackgtm icp derive --domain <site> [--model <id>] [--out icp.json] [--json]
                                                 derive an evidence-backed ICP from a public website (OpenRouter/OpenAI/Anthropic)
+  fullstackgtm icp status --domain <site> [--icp icp.json] [--json]
+                                                compare local and hosted revisions without changing either
+  fullstackgtm icp pull --domain <site> [--out icp.json] [--force] [--json]
+                                                explicitly download hosted canonical ICP; refuses to replace an existing file without --force
+  fullstackgtm icp push --domain <site> [--icp icp.json] [--change-summary <text>] [--json]
+                                                publish the local ICP with revision conflict protection
+  fullstackgtm icp sync --domain <site> [--icp icp.json] [--json]
+                                                reconcile safe one-sided changes; hosted changes become a sibling review file
   fullstackgtm icp set <answers.json> [--name <n>] [--out <path>]   write icp.json from interview answers
   fullstackgtm icp show [--icp <path>]            render the ICP + the discovery filters it produces
   fullstackgtm icp judge [--signals-from latest|<label>] [--with-history] [--prompt <path>] [--min-score 0] [--save]   rank unjudged signals into send/nurture/skip decisions (timing x fit x memory)
@@ -245,10 +255,15 @@ ops. Develop one by interview, then \`enrich acquire\` picks up ./icp.json.
         }
         const mirrored = await writeHostedArtifact({
             kind: "icp", key: `icp:${derived.company.domain}`, label: derived.icp.name,
-            domain: derived.company.domain, document: derived,
+            domain: derived.company.domain, document: derived, sourceVersion: readPackageInfo().version,
         });
-        if (mirrored.status === "saved")
-            console.error("Mirrored the reviewed ICP to the paired hosted workspace.");
+        if (mirrored.status === "saved") {
+            if (out)
+                markIcpSynced(resolve(process.cwd(), out), derived.company.domain, mirrored, derived.icp);
+            console.error(`Mirrored the reviewed ICP to the paired hosted workspace at revision ${mirrored.revision}.`);
+        }
+        else if (mirrored.status === "conflict")
+            console.error(`Warning: ${mirrored.reason}. Run \`fullstackgtm icp sync --domain ${derived.company.domain}${out ? ` --icp ${out}` : ""}\` to reconcile.`);
         else if (mirrored.status === "unavailable")
             console.error(`Warning: ${mirrored.reason}. The local ICP is still authoritative.`);
         if (rest.includes("--json"))
@@ -257,6 +272,84 @@ ops. Develop one by interview, then \`enrich acquire\` picks up ./icp.json.
             console.log(renderDerivedIcp(derived));
         return;
     }
+    if (["status", "pull", "push", "sync"].includes(sub)) {
+        const domain = option(rest, "--domain");
+        if (!domain)
+            throw new Error(`icp ${sub}: --domain <company.com> is required.`);
+        const asJson = rest.includes("--json");
+        const icpPath = resolve(process.cwd(), option(rest, "--icp") ?? option(rest, "--out") ?? "icp.json");
+        if (sub === "status") {
+            if (!existsSync(icpPath))
+                throw new Error(`icp status: local ICP not found at ${icpPath}.`);
+            const checked = await getIcpSyncStatus(icpPath, domain);
+            if (asJson)
+                console.log(JSON.stringify({ path: icpPath, domain, ...checked.status }, null, 2));
+            else
+                console.log(`ICP ${checked.status.state.replaceAll("_", " ")} · local ${checked.status.localIcpSha256.slice(0, 12)}${checked.status.hostedRevision ? ` · hosted r${checked.status.hostedRevision}` : ""}${checked.status.trackedRevision ? ` · last synced r${checked.status.trackedRevision}` : ""}`);
+            return;
+        }
+        if (sub === "pull") {
+            const out = resolve(process.cwd(), option(rest, "--out") ?? "icp.json");
+            const hosted = await readHostedArtifact("icp", artifactKeyForDomain(domain));
+            if (hosted.status !== "found")
+                throw new Error(hosted.status === "missing" ? `No hosted ICP exists for ${domain}.` : hosted.status === "unpaired" ? "This CLI is not paired with a hosted workspace." : hosted.reason);
+            const icp = extractHostedIcp(hosted.state);
+            if (existsSync(out) && !rest.includes("--force"))
+                throw new Error(`Refusing to replace ${out}. Re-run with --force after reviewing hosted revision ${hosted.state.revision}.`);
+            writeSecureFileAtomic(out, `${JSON.stringify(icp, null, 2)}\n`);
+            markIcpSynced(out, domain, hosted.state, icp);
+            if (asJson)
+                console.log(JSON.stringify({ status: "pulled", path: out, revision: hosted.state.revision, documentSha256: hosted.state.documentSha256 }, null, 2));
+            else
+                console.log(`Pulled hosted ICP revision ${hosted.state.revision} to ${out}.`);
+            return;
+        }
+        if (!existsSync(icpPath))
+            throw new Error(`icp ${sub}: local ICP not found at ${icpPath}.`);
+        if (sub === "push") {
+            const pushed = await pushIcp(icpPath, domain, option(rest, "--change-summary") ?? undefined);
+            if (pushed.status === "conflict")
+                throw new Error(`ICP conflict: hosted revision ${pushed.checked.status.hostedRevision ?? "?"} changed since local revision ${pushed.checked.status.trackedRevision ?? "untracked"}. Run \`icp sync\` to write a review copy.`);
+            if (pushed.result.status !== "saved")
+                throw new Error(pushed.result.status === "unpaired" ? "This CLI is not paired with a hosted workspace." : pushed.result.status === "conflict" ? pushed.result.reason : pushed.result.reason);
+            if (asJson)
+                console.log(JSON.stringify({ status: "pushed", revision: pushed.result.revision, documentSha256: pushed.result.documentSha256, unchanged: pushed.result.unchanged }, null, 2));
+            else
+                console.log(`${pushed.result.unchanged ? "Already at" : "Published"} hosted ICP revision ${pushed.result.revision}.`);
+            return;
+        }
+        const checked = await getIcpSyncStatus(icpPath, domain);
+        if (checked.status.state === "local_changed" || checked.status.state === "missing_hosted") {
+            const pushed = await pushIcp(icpPath, domain, "Synchronized local ICP");
+            if (pushed.result?.status !== "saved")
+                throw new Error("ICP sync could not publish the local change.");
+            if (asJson)
+                console.log(JSON.stringify({ status: "pushed", revision: pushed.result.revision }, null, 2));
+            else
+                console.log(`Published local ICP as hosted revision ${pushed.result.revision}.`);
+            return;
+        }
+        if ((checked.status.state === "hosted_changed" || checked.status.state === "conflict" || checked.status.state === "untracked") && checked.hosted) {
+            const reviewPath = `${icpPath}.hosted-r${checked.hosted.revision}.json`;
+            writeSecureFileAtomic(reviewPath, `${JSON.stringify(extractHostedIcp(checked.hosted), null, 2)}\n`);
+            const result = { status: checked.status.state, reviewPath, hostedRevision: checked.hosted.revision, trackedRevision: readIcpSyncState(icpPath)?.revision };
+            if (asJson)
+                console.log(JSON.stringify(result, null, 2));
+            else
+                console.log(`Hosted changes need review. Wrote revision ${checked.hosted.revision} to ${reviewPath}; your local ICP was not replaced.`);
+            return;
+        }
+        if (checked.status.state === "in_sync") {
+            if (!readIcpSyncState(icpPath) && checked.hosted)
+                markIcpSynced(icpPath, domain, checked.hosted, checked.local);
+            if (asJson)
+                console.log(JSON.stringify({ status: "in_sync", revision: checked.status.hostedRevision }, null, 2));
+            else
+                console.log(`ICP is in sync${checked.status.hostedRevision ? ` at revision ${checked.status.hostedRevision}` : ""}.`);
+            return;
+        }
+        throw new Error(checked.status.reason ?? `ICP sync unavailable (${checked.status.state}).`);
+    }
     if (sub === "set") {
         const file = rest.find((a) => !a.startsWith("--"));
         if (!file)

package/dist/cli/signals.js

@@ -11,6 +11,7 @@ import { loadIcp, option, readSnapshot, repeatedOption, saveRequested } from "./
 import { createStatusLine } from "./ui.js";
 import { unknownSubcommandError } from "./suggest.js";
 import { writeHostedArtifact } from "../hostedArtifacts.js";
+import { readIcpSyncState } from "../icpSync.js";
 /**
  * Resolve a signals config: explicit --config, else signals.config.json in cwd,
  * else the zero-config DEFAULT_SIGNALS_CONFIG (preset-first, like enrich).
@@ -170,7 +171,18 @@ from the credential ladder, never argv; --connector-opt carries non-secret knobs
             await store.appendRun({ id: signalRunId(runLabel), runLabel, startedAt: now.toISOString(), completedAt: new Date().toISOString(),
                 buckets: ["job"], counts: { fetched: discovered.summary.rawResults, new: ranked.length, deduped: deduped.length }, signals: ranked });
             console.error(`Saved signal run "${runLabel}". Next: \`fullstackgtm icp judge --signals-from ${runLabel} --save\`.`);
-            await mirrorSignalRun(runLabel, now, ["job"], { fetched: discovered.summary.rawResults, new: ranked.length, deduped: deduped.length }, ranked);
+            await mirrorSignalRun(runLabel, now, ["job"], { fetched: discovered.summary.rawResults, new: ranked.length, deduped: deduped.length }, ranked, rest, {
+                provider: discovered.summary.provider,
+                searchesUsed: discovered.summary.searchesUsed,
+                searchLimit: maxSearches,
+                rawResults: discovered.summary.rawResults,
+                matchedEvidence: discovered.summary.matchedEvidence,
+                resolvedAccounts: discovered.summary.resolvedAccounts,
+                unresolvedAccounts: discovered.summary.unresolvedAccounts,
+                costUsd: discovered.summary.costUsd,
+                costLimitUsd: maxUsd,
+                warnings: discovered.summary.warnings,
+            });
         }
         else {
             console.error("(not saved — re-run with --save to persist this evidence to the signal ledger)");
@@ -299,7 +311,7 @@ from the credential ladder, never argv; --connector-opt carries non-secret knobs
                 signals: ranked,
             });
             console.error(`Saved signal run "${runLabel}" (${fresh.length} fresh). Next: \`fullstackgtm icp judge --save\`.`);
-            await mirrorSignalRun(runLabel, now, buckets, { fetched, new: fresh.length, deduped: deduped.length }, ranked);
+            await mirrorSignalRun(runLabel, now, buckets, { fetched, new: fresh.length, deduped: deduped.length }, ranked, rest);
         }
         else {
             console.error("(not saved — re-run with --save to persist this run to the signal ledger)");
@@ -388,10 +400,13 @@ from the credential ladder, never argv; --connector-opt carries non-secret knobs
     }
     throw unknownSubcommandError("signals", sub, ["fetch", "discover", "list", "outcome", "weights"]);
 }
-async function mirrorSignalRun(runLabel, startedAt, buckets, counts, signals) {
+async function mirrorSignalRun(runLabel, startedAt, buckets, counts, signals, args, discovery) {
+    const icpPath = resolve(process.cwd(), option(args, "--icp") ?? "icp.json");
+    const tracked = existsSync(icpPath) ? readIcpSyncState(icpPath) : null;
     const mirrored = await writeHostedArtifact({
         kind: "signal_run", key: `signals:${signalRunId(runLabel)}`, label: runLabel,
-        document: { runLabel, startedAt: startedAt.toISOString(), completedAt: new Date().toISOString(), buckets, counts, signals },
+        document: { runLabel, startedAt: startedAt.toISOString(), completedAt: new Date().toISOString(), buckets, counts, signals, ...discovery,
+            icpRef: tracked ? { artifactId: tracked.artifactId, domain: tracked.domain, revision: tracked.revision, localIcpSha256: tracked.localIcpSha256 } : undefined },
     });
     if (mirrored.status === "saved")
         console.error("Mirrored the signal run to the paired hosted workspace.");

package/dist/enrich.d.ts

@@ -8,7 +8,7 @@ import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
  *
  * Every enrichment vendor ships fire-and-forget writeback — data lands without
  * a diff, without approval, over whatever a human typed. This layer inverts
- * that: a source (Apollo pull, Clay ingest) feeds a deterministic matcher,
+ * that: a source (Apollo/ZoomInfo pull, Clay ingest) feeds a deterministic matcher,
  * the matcher feeds a fill-blanks-only patch plan, and the plan goes through
  * the existing dry-run → approval → apply contract. Every proposed value is
  * traceable to the source payload that produced it (`GtmEvidence` on the

package/dist/enrich.js

@@ -13,7 +13,7 @@ const MATCH_KEYS = {
     contact: ["email", "name", "linkedin"],
 };
 /** API source ids the MVP can pull from. */
-export const SUPPORTED_API_SOURCES = ["apollo", "explorium", "pipe0", "clay", "linkedin"];
+export const SUPPORTED_API_SOURCES = ["apollo", "zoominfo", "explorium", "pipe0", "clay", "linkedin"];
 /**
  * Canonical fields enrich may target, plus the HubSpot property spellings the
  * config may use for them (so `"crm": "numberofemployees"` and

package/dist/enrichZoomInfo.d.ts

@@ -0,0 +1,33 @@
+import type { EnrichObjectType } from "./enrich.ts";
+import type { ApolloPullKey as EnrichPullKey, ApolloPullOptions as EnrichPullOptions, ApolloPullResult as EnrichPullResult } from "./enrichApollo.ts";
+/**
+ * ZoomInfo source adapter for governed enrichment.
+ *
+ * ZoomInfo owns authentication and credit accounting in its official `gtm`
+ * CLI. fullstackgtm invokes that CLI as a read-only source, normalizes the
+ * JSON response, then sends proposed CRM changes through the normal
+ * diff → patch plan → approval → apply lifecycle. No ZoomInfo credential is
+ * copied into fullstackgtm and this adapter never writes to the CRM directly.
+ */
+export type ZoomInfoCommandResult = {
+    stdout: string;
+    stderr: string;
+};
+export type ZoomInfoCommandRunner = (executable: string, args: string[]) => Promise<ZoomInfoCommandResult>;
+export type ZoomInfoClientOptions = {
+    /** Official ZoomInfo CLI executable. Defaults to `gtm`. */
+    executable?: string;
+    /** Injectable command runner for tests. */
+    run?: ZoomInfoCommandRunner;
+};
+export type ZoomInfoClient = {
+    enrichCompany(domain: string): Promise<unknown>;
+    enrichContact(email: string): Promise<unknown>;
+};
+export declare function createZoomInfoClient(options?: ZoomInfoClientOptions): ZoomInfoClient;
+/** Pull snapshot-driven enrichment keys through ZoomInfo's official CLI. */
+export declare function pullZoomInfoRecords(client: ZoomInfoClient, keys: EnrichPullKey[], options?: EnrichPullOptions): Promise<EnrichPullResult>;
+export type ZoomInfoPullKey = EnrichPullKey;
+export type ZoomInfoPullOptions = EnrichPullOptions;
+export type ZoomInfoPullResult = EnrichPullResult;
+export type ZoomInfoObjectType = EnrichObjectType;

package/dist/enrichZoomInfo.js

@@ -0,0 +1,144 @@
+import { execFile } from "node:child_process";
+const DEFAULT_MAX_BUFFER = 16 * 1024 * 1024;
+const runCommand = (executable, args) => new Promise((resolve, reject) => {
+    execFile(executable, args, { encoding: "utf8", maxBuffer: DEFAULT_MAX_BUFFER }, (error, stdout, stderr) => {
+        if (error) {
+            const code = error.code;
+            if (code === "ENOENT") {
+                reject(new Error("ZoomInfo CLI not found. Install it with `brew install zoominfo/gtm-ai/gtm-ai-cli` " +
+                    "or `npm install -g @zoominfo/gtm-ai-cli`, then run `gtm auth login`."));
+                return;
+            }
+            // Do not echo stdout/stderr: provider errors can contain submitted
+            // company domains, contact emails, or tenant-specific data and this
+            // message may be persisted in a scheduled-run record.
+            reject(new Error(`ZoomInfo CLI failed${typeof code === "string" || typeof code === "number" ? ` (${code})` : ""}. ` +
+                "Run `gtm auth whoami`, then retry the same `gtm ... enrich` command directly if needed."));
+            return;
+        }
+        resolve({ stdout, stderr });
+    });
+});
+function parseOutput(stdout) {
+    const text = stdout.trim();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error("ZoomInfo CLI returned non-JSON output. Upgrade `gtm` and verify that `gtm ... enrich -f json` works directly.");
+    }
+}
+export function createZoomInfoClient(options = {}) {
+    const executable = options.executable ?? process.env.ZOOMINFO_GTM_BIN ?? "gtm";
+    const run = options.run ?? runCommand;
+    async function invoke(args) {
+        const result = await run(executable, [...args, "-f", "json"]);
+        return parseOutput(result.stdout);
+    }
+    return {
+        enrichCompany(domain) {
+            return invoke(["companies", "enrich", "--domain", domain]);
+        },
+        enrichContact(email) {
+            return invoke(["contacts", "enrich", "--email", email]);
+        },
+    };
+}
+function recordCandidates(value) {
+    if (Array.isArray(value)) {
+        return value.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item));
+    }
+    if (!value || typeof value !== "object")
+        return [];
+    const object = value;
+    if (Array.isArray(object.data))
+        return recordCandidates(object.data);
+    if (object.data && typeof object.data === "object")
+        return recordCandidates(object.data);
+    if (Array.isArray(object.companies))
+        return recordCandidates(object.companies);
+    if (Array.isArray(object.contacts))
+        return recordCandidates(object.contacts);
+    return [object];
+}
+function valueAt(record, paths) {
+    for (const path of paths) {
+        let current = record;
+        for (const segment of path.split(".")) {
+            if (!current || typeof current !== "object") {
+                current = undefined;
+                break;
+            }
+            current = current[segment];
+        }
+        if (typeof current === "string" && current.trim())
+            return current.trim();
+        if (typeof current === "number" && Number.isFinite(current))
+            return String(current);
+    }
+    return undefined;
+}
+function normalizeRecord(payload, key) {
+    const record = recordCandidates(payload)[0];
+    if (!record)
+        return undefined;
+    const id = valueAt(record, ["id", "attributes.id", "companyId", "personId", "attributes.companyId", "attributes.personId"]);
+    if (key.objectType === "company") {
+        return {
+            id: `zoominfo:company_${id ?? key.value}`,
+            objectType: "company",
+            keys: {
+                domain: valueAt(record, [
+                    "attributes.domain",
+                    "attributes.website",
+                    "attributes.companyWebsite",
+                    "domain",
+                    "website",
+                    "companyWebsite",
+                ]) ?? key.value,
+                name: valueAt(record, ["attributes.name", "attributes.companyName", "name", "companyName"]),
+            },
+            payload: record,
+        };
+    }
+    return {
+        id: `zoominfo:contact_${id ?? key.value}`,
+        objectType: "contact",
+        keys: {
+            email: valueAt(record, [
+                "attributes.email",
+                "attributes.emailAddress",
+                "attributes.contactEmail",
+                "email",
+                "emailAddress",
+                "contactEmail",
+            ]) ?? key.value,
+            name: valueAt(record, ["attributes.fullName", "attributes.name", "fullName", "name"]),
+        },
+        payload: record,
+    };
+}
+/** Pull snapshot-driven enrichment keys through ZoomInfo's official CLI. */
+export async function pullZoomInfoRecords(client, keys, options = {}) {
+    const records = [];
+    const misses = [];
+    const resumeIndex = options.resumeAfter ? keys.findIndex((key) => key.value === options.resumeAfter) : -1;
+    for (const key of keys.slice(resumeIndex + 1)) {
+        const payload = key.objectType === "company"
+            ? await client.enrichCompany(key.value)
+            : await client.enrichContact(key.value);
+        const record = normalizeRecord(payload, key);
+        if (record)
+            records.push(record);
+        else
+            misses.push(key);
+        await options.onProgress?.({
+            lastKeyValue: key.value,
+            record,
+            miss: record ? undefined : key,
+        });
+    }
+    return { records, misses };
+}

package/dist/hostedArtifacts.d.ts

@@ -1,21 +1,55 @@
+export type HostedArtifactKind = "icp" | "signal_run" | "lead_run";
 export type HostedArtifact = {
-    kind: "icp" | "signal_run";
+    kind: HostedArtifactKind;
     key: string;
     label: string;
     domain?: string;
     document: unknown;
     sourceVersion?: string;
+    expectedRevision?: number;
+    changeSummary?: string;
+};
+export type HostedArtifactState = HostedArtifact & {
+    artifactId: string;
+    revision: number;
+    documentSha256?: string;
+    origin: "cli" | "hosted";
+    updatedAt: number;
 };
 export type HostedArtifactResult = {
     status: "unpaired";
 } | {
     status: "saved";
+    artifactId: string;
     created: boolean;
     updatedAt: number;
+    revision: number;
+    documentSha256: string;
+    unchanged: boolean;
+} | {
+    status: "conflict";
+    reason: string;
+    currentRevision?: number;
+    documentSha256?: string;
 } | {
     status: "unavailable";
     reason: string;
 };
+export type HostedArtifactReadResult = {
+    status: "unpaired";
+} | {
+    status: "found";
+    state: HostedArtifactState;
+} | {
+    status: "missing";
+} | {
+    status: "unavailable";
+    reason: string;
+};
+export declare function readHostedArtifact(kind: HostedArtifactKind, key: string, options?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<HostedArtifactReadResult>;
 export declare function writeHostedArtifact(artifact: HostedArtifact, options?: {
     fetchImpl?: typeof fetch;
     timeoutMs?: number;