fullstackgtm 0.56.1 → 0.58.0

package/src/cli/icp.ts

@@ -1,6 +1,6 @@
 // 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";
@@ -9,14 +9,16 @@ import { fitThreshold, icpFromAnswers, icpToCrustdataFilters, icpToExploriumFilt
 import { createFileSignalStore, DEFAULT_SIGNALS_CONFIG, type SignalsConfig } from "../signals.ts";
 import { createFileJudgeStore, DEFAULT_JUDGE_PROMPT, judgeRunId, judgeSignals } from "../judge.ts";
 import { DEFAULT_GOLDEN_NOW_ISO, DEFAULT_GOLDEN_SET, DEFAULT_MIN_ACCURACY, defaultJudgeFn, gradeAgainstOutcomes, gradeJudge, parseGoldenSet } from "../judgeEval.ts";
-import { loadIcp, numericOption, option, readSecret, readSnapshot, resolveLlmBaseUrls, saveRequested } from "./shared.ts";
+import { loadIcp, numericOption, option, readPackageInfo, readSecret, readSnapshot, resolveLlmBaseUrls, saveRequested } from "./shared.ts";
 import { createStatusLine } from "./ui.ts";
 import { box, colorEnabled, paint, truncateToWidth } from "./ui.ts";
 import { getCredential, storeCredential } from "../credentials.ts";
 import { deriveWebsiteIcp, icpReviewSegments, OPENROUTER_API_BASE, type WebsiteIcpDerivation } from "../icpDerive.ts";
 import type { Icp } from "../icp.ts";
 import { unknownSubcommandError } from "./suggest.ts";
-import { writeHostedArtifact } from "../hostedArtifacts.ts";
+import { readHostedArtifact, writeHostedArtifact } from "../hostedArtifacts.ts";
+import { artifactKeyForDomain, extractHostedIcp, getIcpSyncStatus, markIcpSynced, pushIcp, readIcpSyncState } from "../icpSync.ts";
+import { writeSecureFileAtomic } from "../secureFile.ts";
 
 function renderJudgeDecisions(decisions: Awaited<ReturnType<typeof judgeSignals>>): string {
   if (decisions.length === 0) return "No accounts cleared the score threshold.";
@@ -178,6 +180,14 @@ export async function icpCommand(args: string[]) {
   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)
@@ -235,14 +245,79 @@ 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")) console.log(JSON.stringify(derived, null, 2));
     else if (!reviewedInteractively) 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) throw new Error("Usage: fullstackgtm icp set <answers.json> [--name <n>] [--out <path>]");

package/src/cli/signals.ts

@@ -12,6 +12,7 @@ import { loadIcp, option, readSnapshot, repeatedOption, saveRequested } from "./
 import { createStatusLine } from "./ui.ts";
 import { unknownSubcommandError } from "./suggest.ts";
 import { writeHostedArtifact } from "../hostedArtifacts.ts";
+import { readIcpSyncState } from "../icpSync.ts";
 
 
 /**
@@ -178,7 +179,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)");
     }
@@ -317,7 +329,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)");
     }
@@ -412,10 +424,15 @@ async function mirrorSignalRun(
   buckets: SignalBucket[],
   counts: { fetched: number; new: number; deduped: number },
   signals: Signal[],
+  args: string[],
+  discovery?: Record<string, unknown>,
 ) {
+  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.");
   else if (mirrored.status === "unavailable") console.error(`Warning: ${mirrored.reason}. The local signal ledger is still authoritative.`);

package/src/enrich.ts

@@ -20,7 +20,7 @@ import type {
  *
  * 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
@@ -154,7 +154,7 @@ const MATCH_KEYS: Record<EnrichObjectType, string[]> = {
 };
 
 /** 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

package/src/enrichZoomInfo.ts

@@ -0,0 +1,197 @@
+import { execFile } from "node:child_process";
+import type { EnrichObjectType, EnrichSourceRecord } 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>;
+};
+
+const DEFAULT_MAX_BUFFER = 16 * 1024 * 1024;
+
+const runCommand: ZoomInfoCommandRunner = (executable, args) =>
+  new Promise((resolve, reject) => {
+    execFile(executable, args, { encoding: "utf8", maxBuffer: DEFAULT_MAX_BUFFER }, (error, stdout, stderr) => {
+      if (error) {
+        const code = (error as NodeJS.ErrnoException).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: string): unknown {
+  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: ZoomInfoClientOptions = {}): ZoomInfoClient {
+  const executable = options.executable ?? process.env.ZOOMINFO_GTM_BIN ?? "gtm";
+  const run = options.run ?? runCommand;
+
+  async function invoke(args: string[]): Promise<unknown> {
+    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: unknown): Record<string, unknown>[] {
+  if (Array.isArray(value)) {
+    return value.filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object" && !Array.isArray(item));
+  }
+  if (!value || typeof value !== "object") return [];
+  const object = value as Record<string, unknown>;
+  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: Record<string, unknown>, paths: string[]): string | undefined {
+  for (const path of paths) {
+    let current: unknown = record;
+    for (const segment of path.split(".")) {
+      if (!current || typeof current !== "object") {
+        current = undefined;
+        break;
+      }
+      current = (current as Record<string, unknown>)[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: unknown, key: EnrichPullKey): EnrichSourceRecord | undefined {
+  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: ZoomInfoClient,
+  keys: EnrichPullKey[],
+  options: EnrichPullOptions = {},
+): Promise<EnrichPullResult> {
+  const records: EnrichSourceRecord[] = [];
+  const misses: EnrichPullKey[] = [];
+  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 };
+}
+
+export type ZoomInfoPullKey = EnrichPullKey;
+export type ZoomInfoPullOptions = EnrichPullOptions;
+export type ZoomInfoPullResult = EnrichPullResult;
+export type ZoomInfoObjectType = EnrichObjectType;

package/src/hostedArtifacts.ts

@@ -1,21 +1,38 @@
-/** 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.ts";
 
 const ENDPOINT = "/api/cli/artifact";
 const DEFAULT_TIMEOUT_MS = 4000;
 
+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"; created: boolean; updatedAt: number }
+  | { 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 };
 
 function broker(): { baseUrl: string; accessToken: string } | null {
@@ -29,29 +46,41 @@ function broker(): { baseUrl: string; accessToken: string } | null {
   } catch { return null; }
 }
 
-export async function writeHostedArtifact(
-  artifact: HostedArtifact,
-  options: { fetchImpl?: typeof fetch; timeoutMs?: number } = {},
-): Promise<HostedArtifactResult> {
-  if (!artifact.key || artifact.key.length > 256 || !artifact.label || artifact.label.length > 200) {
-    throw new Error("Hosted artifact key/label is invalid.");
-  }
+function requestOptions(accessToken: string, timeoutMs: number): Pick<RequestInit, "headers" | "signal"> {
+  return { headers: { Authorization: `Bearer ${accessToken}` }, signal: AbortSignal.timeout(timeoutMs) };
+}
+
+export async function readHostedArtifact(kind: HostedArtifactKind, key: string, options: { fetchImpl?: typeof fetch; timeoutMs?: number } = {}): Promise<HostedArtifactReadResult> {
+  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() as HostedArtifactState;
+    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: HostedArtifact, options: { fetchImpl?: typeof fetch; timeoutMs?: number } = {}): Promise<HostedArtifactResult> {
+  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.ok) return { status: "unavailable", reason: `hosted artifact request failed (HTTP ${response.status})` };
-    const body = await response.json() as { created?: unknown; updatedAt?: unknown };
-    if (typeof body.created !== "boolean" || typeof body.updatedAt !== "number") {
-      return { status: "unavailable", reason: "hosted artifact response was invalid" };
+    if (response.status === 409) {
+      const body = await response.json() as { currentRevision?: number; documentSha256?: string };
+      return { status: "conflict", reason: "hosted ICP changed since the last sync", currentRevision: body.currentRevision, documentSha256: body.documentSha256 };
     }
-    return { status: "saved", created: body.created, updatedAt: body.updatedAt };
-  } catch {
-    return { status: "unavailable", reason: "hosted artifact request was unavailable" };
-  }
+    if (!response.ok) return { status: "unavailable", reason: `hosted artifact request failed (HTTP ${response.status})` };
+    const body = await response.json() as { artifactId?: unknown; created?: unknown; updatedAt?: unknown; revision?: unknown; documentSha256?: unknown; unchanged?: unknown };
+    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", 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/src/icp.ts

@@ -73,6 +73,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;
   };
 };
 
@@ -456,17 +459,20 @@ export function scoreProspectAgainstIcp(
   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;
       reasons.push(`title matches ICP function "${functional}"`);

package/src/icpSync.ts

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { parseIcp, type Icp } from "./icp.ts";
+import { readSecureRegularFile, writeSecureFileAtomic } from "./secureFile.ts";
+import { readHostedArtifact, writeHostedArtifact, 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 function classifyIcpSync(localHash: string, hostedRevision: number, hostedHash: string, tracked: IcpSyncState | null): IcpSyncStatus["state"] {
+  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: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const object = value as Record<string, unknown>;
+  return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`).join(",")}}`;
+}
+export const icpSha256 = (icp: Icp) => createHash("sha256").update(canonicalJson(icp)).digest("hex");
+export function artifactKeyForDomain(domain: string): string {
+  const candidate = /^https?:\/\//i.test(domain.trim()) ? domain.trim() : `https://${domain.trim()}`;
+  let parsed: URL; 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: string) => resolve(dirname(resolve(icpPath)), ".fullstackgtm", `${resolve(icpPath).split(/[\\/]/).pop()}.sync.json`);
+
+export function readLocalIcp(path: string): Icp { return parseIcp(readSecureRegularFile(resolve(path))); }
+export function extractHostedIcp(state: HostedArtifactState): Icp {
+  const root = state.document && typeof state.document === "object" && !Array.isArray(state.document) ? state.document as Record<string, unknown> : {};
+  return parseIcp(JSON.stringify(root.icp ?? state.document));
+}
+export function readIcpSyncState(icpPath: string): IcpSyncState | null {
+  const path = sidecarPathFor(icpPath); if (!existsSync(path)) return null;
+  try { const value = JSON.parse(readSecureRegularFile(path)) as IcpSyncState; return value?.version === 1 ? value : null; } catch { return null; }
+}
+export function writeIcpSyncState(icpPath: string, state: IcpSyncState): void {
+  const path = sidecarPathFor(icpPath); mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeSecureFileAtomic(path, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+export async function getIcpSyncStatus(icpPath: string, domain: string): Promise<{ status: IcpSyncStatus; hosted?: HostedArtifactState; local: Icp }> {
+  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: string, domain: string, hosted: HostedArtifactState | { artifactId: string; revision: number; documentSha256?: string }, icp: Icp): void {
+  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: string, domain: string, changeSummary?: string) {
+  const checked = await getIcpSyncStatus(icpPath, domain);
+  if (checked.status.state === "conflict" || checked.status.state === "hosted_changed" || checked.status.state === "untracked") return { status: "conflict" as const, checked };
+  const current = checked.hosted;
+  const root = current?.document && typeof current.document === "object" && !Array.isArray(current.document) ? current.document as Record<string, unknown> : {};
+  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/src/index.ts

@@ -11,6 +11,19 @@ export {
   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,
@@ -263,6 +276,17 @@ export {
   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,