fullstackgtm 0.56.0 → 0.57.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ The path to 1.0 is planned in [docs/roadmap-to-1.0.md](https://github.com/fullst
 
 ## [Unreleased]
 
+## [0.57.0] — 2026-07-13
+
+### Added
+
+- Paired CLIs can inspect and safely reconcile hosted ICPs with `icp status`,
+  `icp pull`, `icp push`, and `icp sync`. A private adjacent sidecar records
+  the last synchronized revision and content hash without changing `icp.json`.
+- Hosted ICP edits publish immutable numbered revisions with author, timestamp,
+  origin, content hash, change summary, comparison, and restore-as-new-revision
+  history.
+- Signal evidence and ICP-scored lead previews record the exact ICP revision
+  and hash used to produce them.
+
+### Changed
+
+- Hosted changes never silently replace a local ICP. Concurrent local and
+  hosted edits are reported as conflicts, and `icp sync` writes the hosted
+  revision to a separate review file.
+- Older CLIs may continue updating CLI-origin artifacts, but blind writes can
+  no longer overwrite an artifact whose latest revision was published in the
+  hosted editor.
+
+## [0.56.1] — 2026-07-13
+
+### Fixed
+
+- Portable Clay normalization retains provider `work_email` and fallback
+  `personal_email` fields, preserving the homepage demo's pre-existing contact
+  disclosure behavior while still returning only the canonical prospect shape.
+
 ## [0.56.0] — 2026-07-13
 
 ### Added

package/README.md

@@ -199,6 +199,23 @@ fullstackgtm apply --plan-id <id> --provider hubspot        # the only step that
 
 The **ICP** (`icp.json`) is the single targeting artifact: it generates each provider's discovery filters (Explorium, pipe0/Crustdata) *and* fit-scores every discovered prospect — only above-threshold leads are proposed. Develop one by interview; the CLI can't run `AskUserQuestion` itself, so `icp interview` emits the spec and an agent (Claude Code / Codex) drives it.
 
+When the CLI is paired, the hosted workspace and local ICP can be edited
+without last-write-wins data loss:
+
+```bash
+fullstackgtm icp status --domain acme.com --icp ./icp.json
+fullstackgtm icp push --domain acme.com --icp ./icp.json --change-summary "Narrowed buyer titles"
+fullstackgtm icp sync --domain acme.com --icp ./icp.json
+fullstackgtm icp pull --domain acme.com --out ./icp.json --force
+```
+
+Published hosted edits are immutable numbered revisions. The CLI stores only
+sync metadata in `./.fullstackgtm/icp.json.sync.json`; the portable `icp.json`
+schema is unchanged. `sync` never silently replaces the local file: if hosted
+changed, it writes `icp.json.hosted-rN.json` for review. If both sides changed,
+it reports a conflict rather than unioning ordered targeting arrays. Signal and
+lead-preview records retain the exact ICP revision used for later analysis.
+
 **You don't pay to re-discover dupes.** Before the (credit-spending) email step, acquire drops prospects already in your CRM and any seen in a prior run:
 
 - **Pre-email CRM dedup** matches the live snapshot. The LinkedIn URL (`hs_linkedin_url`, read into the snapshot by default — safe everywhere, HubSpot ignores unknown properties) is the strong key; name+domain is the fallback. Created contacts get their LinkedIn URL written back, so coverage — and dedup precision — grows over time. If your CRM has no LinkedIn URLs, acquire says so and recommends populating it.

package/dist/cli/enrich.js

@@ -25,6 +25,8 @@ 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
@@ -265,6 +267,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: result.plan.title ?? result.plan.id,
+            domain: trackedIcp?.domain,
+            document: { runLabel: result.plan.id, createdAt: new Date().toISOString(), source, 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,

package/dist/cli/help.js

@@ -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,7 @@ 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);
         }
         else {
             console.error("(not saved — re-run with --save to persist this evidence to the signal ledger)");
@@ -299,7 +300,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 +389,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) {
+    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,
+            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/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;

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";

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";

package/dist/portable/clay.js

@@ -26,7 +26,7 @@ export function normalizeClayPerson(value) {
         companyName: stringValue(row.latest_experience_company),
         companyDomain: bareDomain(stringValue(row.domain)),
         linkedin: normalizeLinkedin(stringValue(row.url)),
-        email: stringValue(row.email),
+        email: stringValue(row.work_email) ?? stringValue(row.email) ?? stringValue(row.personal_email),
         sourceId: normalizeLinkedin(stringValue(row.url)) ?? fullName,
         location: {
             city: stringValue(location.city),

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

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "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.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM LLC <ryan@fullstackgtm.com> (https://fullstackgtm.com)",

package/src/cli/enrich.ts

@@ -28,6 +28,8 @@ 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";
 
 
 /**
@@ -302,6 +304,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: result.plan.title ?? result.plan.id,
+      domain: trackedIcp?.domain,
+      document: { runLabel: result.plan.id, createdAt: new Date().toISOString(), source, 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,

package/src/cli/help.ts

@@ -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

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,7 @@ 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);
     } else {
       console.error("(not saved — re-run with --save to persist this evidence to the signal ledger)");
     }
@@ -317,7 +318,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 +413,14 @@ async function mirrorSignalRun(
   buckets: SignalBucket[],
   counts: { fetched: number; new: number; deduped: number },
   signals: Signal[],
+  args: string[],
 ) {
+  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,
+      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/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,

package/src/portable/clay.ts

@@ -40,7 +40,7 @@ export function normalizeClayPerson(value: unknown): Prospect {
     companyName: stringValue(row.latest_experience_company),
     companyDomain: bareDomain(stringValue(row.domain)),
     linkedin: normalizeLinkedin(stringValue(row.url)),
-    email: stringValue(row.email),
+    email: stringValue(row.work_email) ?? stringValue(row.email) ?? stringValue(row.personal_email),
     sourceId: normalizeLinkedin(stringValue(row.url)) ?? fullName,
     location: {
       city: stringValue(location.city),