fullstackgtm 0.49.0 → 0.50.0

package/dist/cli/enrich.js

@@ -1,13 +1,17 @@
 // Extracted verbatim from src/cli.ts (mechanical split, no behavior change).
 import { existsSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { resolve } from "node:path";
 import { getCredential } from "../credentials.js";
 import { patchPlanToMarkdown } from "../format.js";
 import { createFilePlanStore } from "../planStore.js";
 import { buildAcquirePlan, buildEnrichPlan, createFileEnrichRunStore, DEFAULT_STALE_DAYS, ENRICH_CONFIG_FILE_NAME, builtinAcquirePreset, builtinEnrichPreset, enrichRunId, inferIngestObjectType, latestStamps, loadEnrichConfig, parseCsv, resolveCrmField, selectStaleWork, stagedSourceRecords, staleDaysFor } from "../enrich.js";
 import { loadMeter, remaining } from "../acquireMeter.js";
-import { crmContactKeys, fetchExploriumProspects, fetchPipe0CrustdataProspects, partitionFreshProspects, pipe0ResolveCompanyDomains, pipe0ResolveWorkEmails, prospectIdentityKeys } from "../connectors/prospectSources.js";
+import { crmContactKeys, fetchExploriumProspects, fetchPipe0CrustdataProspectPage, partitionFreshProspects, pipe0ResolveCompanyDomains, pipe0ResolveWorkEmails, prospectIdentityKeys } from "../connectors/prospectSources.js";
 import { loadSeen, recordSeen } from "../acquireSeen.js";
+import { acquireCheckpointId, createFileAcquireCheckpointStore } from "../acquireCheckpoint.js";
+import { readHostedAcquireCheckpoint, writeHostedAcquireCheckpoint } from "../hostedAcquireCheckpoint.js";
+import { uploadHostedPatchPlan } from "../hostedPatchPlan.js";
 import { progressReporter, reportCounts, reportEvent } from "../runReport.js";
 import { ACQUIRE_STAGES, composeListeners, createProgressEmitter } from "../progress.js";
 import { createLinkedInProvider, discoverLinkedInProspects } from "../acquireLinkedIn.js";
@@ -37,7 +41,7 @@ enrich append  [--source apollo] [--objects companies,contacts] [--save] [--conf
 enrich refresh [--source apollo] [--stale-days <n>] [--save] [--config <path>]
                [source options] [--run-label <label>] [--json]
 enrich ingest  <file.csv|payload.json|spool.jsonl|spool-dir> --source clay [--run-label <label>] [--objects companies|contacts] [--config <path>]
-enrich acquire [--source <id>] [--max <n>] [--list <id>] [--assign-owner <id>] [--save] [--config <path>] [--json]
+enrich acquire [--source <id>] [--max <new-leads>] [--scan-limit <candidates>] [--list <id>] [--assign-owner <id>] [--save] [--config <path>] [--json]
 enrich status  [--runs] [--source <id>] [--config <path>] [--json]
 
 acquire creates NET-NEW leads from a staged prospect list (ingest first):
@@ -47,6 +51,9 @@ it dedupes each sourced row against the CRM, skips matches and ambiguities
 remaining budget (records + spend, per day and per month; whichever is hit
 first). Approval-gated like every write: \`--save\` → plans approve → apply.
 The meter is charged only when a create actually lands at apply.
+\`--max\` controls the desired net-new plan size; \`--scan-limit\` separately
+bounds raw candidates scanned after ICP and dedupe filtering. Continuation is
+persisted per query so scheduled runs advance instead of rereading page one.
 Discovery sources (zero-config presets): explorium | pipe0 (ICP-driven search),
 and linkedin (reads a HeyReach lead list — pass --list <id>, key on the LinkedIn
 URL, $0/record; \`login heyreach\` or HEYREACH_API_KEY).
@@ -125,7 +132,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         const today = new Date().toISOString().slice(0, 10);
         // Prospects come from an API source (net-new discovery, e.g. Explorium +
         // pipe0 work-email) or a staged ingest list (Clay/CSV/webhook).
-        const snapshot = await readSnapshot(rest);
+        const snapshot = await readSnapshot(rest, undefined, { persistProgress: true });
         const icp = loadIcp(rest);
         if (sourceConfig.kind === "api" && !icp) {
             console.error("⚠ No ICP loaded — discovery will use the raw discovery.filters and skip fit scoring. " +
@@ -139,16 +146,38 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
                 "acquire writes it on every new contact it creates, so coverage grows automatically.");
         }
         const seen = loadSeen();
+        const now = new Date();
+        const costPerRecord = config.acquire.costPerRecord?.[source] ?? 0;
+        const headroom = remaining(loadMeter(now), config.acquire.budget, costPerRecord, now);
+        const explicitMax = numericOption(rest, "--max");
+        const desiredCreates = explicitMax ?? config.acquire.discovery?.[source]?.size ?? 25;
+        const cap = headroom.maxRecords === null ? desiredCreates : Math.min(headroom.maxRecords, desiredCreates);
         let records;
         let apiSkippedCrm = 0;
         let apiSkippedSeen = 0;
         let apiProcessedKeys = [];
+        let acquireTelemetry;
+        let acquireCheckpointSync;
+        const renderer = createProgressRenderer(ACQUIRE_STAGES);
+        const acquireProgress = createProgressEmitter(composeListeners(renderer.listener, progressReporter()));
         if (sourceConfig.kind === "api") {
-            const api = await acquireFromApi(config, source, rest, icp, snapshot, seen);
+            const priorRun = await store.latest({ source, mode: "acquire" });
+            acquireProgress.stage(ACQUIRE_STAGES[0], 0, ACQUIRE_STAGES.length);
+            acquireProgress.note("loading saved audience position");
+            let api;
+            try {
+                api = await acquireFromApi(config, source, rest, icp, snapshot, seen, priorRun, cap, save, acquireProgress);
+            }
+            catch (error) {
+                renderer.done({ persist: true });
+                throw error;
+            }
             records = api.records;
             apiSkippedCrm = api.skippedCrm;
             apiSkippedSeen = api.skippedSeen;
             apiProcessedKeys = api.processedKeys;
+            acquireTelemetry = api.telemetry;
+            acquireCheckpointSync = { key: api.checkpointKey, hostedVersion: api.hostedVersion };
         }
         else {
             const stagedLabel = option(rest, "--staged-run");
@@ -162,17 +191,13 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         }
         // Meter: how many MORE leads may we create right now? --max is an
         // additional per-run ceiling, never a way to exceed the budget.
-        const now = new Date();
-        const costPerRecord = config.acquire.costPerRecord?.[source] ?? 0;
         if (apiSkippedCrm || apiSkippedSeen) {
             console.error(`Pre-email dedup: skipped ${apiSkippedCrm} already-in-CRM + ${apiSkippedSeen} seen before paying for emails ` +
                 `(≈$${((apiSkippedCrm + apiSkippedSeen) * costPerRecord).toFixed(2)} enrichment saved).`);
         }
-        const headroom = remaining(loadMeter(now), config.acquire.budget, costPerRecord, now);
-        const explicitMax = numericOption(rest, "--max");
-        let cap = headroom.maxRecords;
-        if (explicitMax !== undefined)
-            cap = cap === null ? explicitMax : Math.min(cap, explicitMax);
+        // `cap` is the desired create count bounded by the persistent meter. Raw
+        // discovery scanning has its own --scan-limit and may cross many duplicate-
+        // heavy pages to fill this target.
         // Assignment: never create an ownerless lead. An explicit `acquire.assign`
         // policy wins; a `--assign-owner <id>` flag is a quick fixed override;
         // otherwise, when the portal has exactly one active owner, default every
@@ -202,11 +227,10 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
         // piped) and, via the composed reporter, heartbeat to a paired hosted app.
         // The meter reading (creates vs headroom + budget burn) rides the same
         // emitter, feeding the dashboard's gauge without printing anything new.
-        const renderer = createProgressRenderer(ACQUIRE_STAGES);
-        const acquireProgress = createProgressEmitter(composeListeners(renderer.listener, progressReporter()));
         let result;
         try {
-            acquireProgress.stage(ACQUIRE_STAGES[0], 0, ACQUIRE_STAGES.length);
+            acquireProgress.stage(ACQUIRE_STAGES[2], 2, ACQUIRE_STAGES.length);
+            acquireProgress.note("building governed create plan");
             if (config.acquire.budget?.records?.perDay && headroom.records.day !== null) {
                 acquireProgress.meter(config.acquire.budget.records.perDay - headroom.records.day, config.acquire.budget.records.perDay, "records/day");
             }
@@ -221,7 +245,7 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
             });
         }
         finally {
-            renderer.done();
+            renderer.done({ persist: true });
         }
         if (result.counts.unassigned > 0 && result.counts.created > 0) {
             console.error(`⚠ ${result.counts.unassigned}/${result.counts.created} proposed lead(s) have no owner ` +
@@ -251,32 +275,69 @@ are phase 2. Recurring execution is the scheduler's job; enrich has no cron.`);
             }
             return;
         }
-        const run = await openEnrichRun(store, source, "append", option(rest, "--run-label"), today);
+        const run = await openEnrichRun(store, source, "acquire", option(rest, "--run-label"), today);
         const planIds = [];
+        let hostedPlanUrl = null;
         if (result.plan.operations.length > 0) {
-            await createFilePlanStore().save(result.plan);
+            const storedPlan = await createFilePlanStore().save(result.plan);
             planIds.push(result.plan.id);
             reportEvent("plan_saved", result.plan.id);
+            const mirror = await uploadHostedPatchPlan(storedPlan);
+            if (mirror.status === "saved") {
+                hostedPlanUrl = mirror.state.url;
+                reportEvent("plan_mirrored", mirror.state.patchPlanId);
+            }
+            else if (mirror.status === "unavailable" || mirror.status === "conflict") {
+                console.error(`Hosted plan sync pending: ${mirror.reason}. The local signed plan remains authoritative.`);
+            }
+        }
+        if (acquireTelemetry) {
+            acquireTelemetry.funnel.proposed = result.counts.created;
+            acquireTelemetry.funnel.withheldByMeter = result.counts.withheldByMeter;
         }
         await store.update({
             ...run,
             completedAt: new Date().toISOString(),
-            cursor: null,
+            cursor: acquireTelemetry?.discovery.cursor ?? null,
+            counts: acquireTelemetry
+                ? {
+                    fetched: acquireTelemetry.funnel.discovered,
+                    matched: acquireTelemetry.funnel.skippedCrm + acquireTelemetry.funnel.skippedSeen,
+                    unmatched: acquireTelemetry.funnel.resolved,
+                    ambiguous: result.counts.ambiguous,
+                    opsEmitted: acquireTelemetry.funnel.proposed,
+                }
+                : run.counts,
+            acquireTelemetry,
             planIds: [...(run.planIds ?? []), ...planIds],
         });
         // Remember everyone we email-resolved this run so the next run skips them
         // pre-email (cross-run credit saver). Committed (--save) runs only.
         if (apiProcessedKeys.length > 0)
             recordSeen(apiProcessedKeys, now);
-        console.log(meterLine);
-        if (gaugeLine)
-            console.log(gaugeLine);
+        if (acquireTelemetry && acquireCheckpointSync) {
+            await persistAcquireCheckpoint(acquireCheckpointSync.key, acquireTelemetry.discovery, acquireCheckpointSync.hostedVersion);
+        }
         if (planIds.length > 0) {
-            console.log(`Saved plan ${result.plan.id} — ${result.counts.created} net-new lead(s), est. $${result.estCostUsd.toFixed(2)}. ` +
-                `Review \`fullstackgtm plans show ${result.plan.id}\`, approve \`fullstackgtm plans approve ${result.plan.id} --operations all\`, ` +
-                `then \`fullstackgtm apply --plan-id ${result.plan.id} --provider hubspot\`. The meter is charged only when a create lands at apply.`);
+            const hostedRuns = hostedRunsUrl();
+            console.log(`\nSaved plan ${result.plan.id}`);
+            console.log(`  Leads      ${result.counts.created} net-new`);
+            console.log(`  Est. cost  $${result.estCostUsd.toFixed(2)}`);
+            console.log(`  Budget     ${gaugeLine ?? meterLine}`);
+            if (hostedPlanUrl)
+                console.log(`  Plan       ${hostedPlanUrl}`);
+            if (hostedRuns)
+                console.log(`  Observe    ${hostedRuns}`);
+            console.log("\nNext steps");
+            console.log(`  Review     fullstackgtm plans show ${result.plan.id}`);
+            console.log(`  Approve    fullstackgtm plans approve ${result.plan.id} --operations all`);
+            console.log(`  Apply      fullstackgtm apply --plan-id ${result.plan.id} --provider hubspot`);
+            console.log("\nThe meter is charged only when a create lands at apply.");
         }
         else {
+            console.log(meterLine);
+            if (gaugeLine)
+                console.log(gaugeLine);
             console.log("No net-new leads to create (everything sourced already matched, or was withheld by the meter).");
         }
         return;
@@ -442,69 +503,152 @@ function formatEnrichCounts(counts, ambiguities) {
  * pipe0 (when resolveEmailsWith=pipe0) fills real work emails. Only rows that
  * carry the dedupe key (email) survive — you cannot resolve-first without it.
  */
-async function acquireFromApi(config, source, rest, icp, snapshot, seen) {
+async function acquireFromApi(config, source, rest, icp, snapshot, seen, priorRun, targetFresh, persistCheckpoint, progress) {
     const acquire = config.acquire;
     const disc = acquire.discovery?.[source];
     if (!disc) {
         throw new Error(`enrich acquire: api source "${source}" needs an "acquire.discovery.${source}" config (provider + size).`);
     }
     const matchKey = acquire.create.contact?.matchKey ?? "email";
-    const maxOverride = numericOption(rest, "--max");
-    const size = maxOverride !== undefined ? Math.min(maxOverride, disc.size ?? 25) : disc.size ?? 25;
-    // 1. Discover. Filters come from the ICP when one is loaded (the whole point —
-    //    targeted, not random); otherwise from the hand-written disc.filters.
-    let prospects;
-    if (disc.provider === "explorium") {
-        const filters = icp
-            ? icpToExploriumFilters(icp)
-            : (disc.filters ?? {});
-        prospects = await fetchExploriumProspects({ apiKey: providerKey("explorium"), filters, size });
-    }
-    else if (disc.provider === "pipe0") {
-        const filters = icp ? icpToCrustdataFilters(icp) : (disc.filters ?? {});
-        prospects = await fetchPipe0CrustdataProspects({ apiKey: providerKey("pipe0"), filters, limit: size });
-    }
-    else if (disc.provider === "linkedin" || disc.provider === "heyreach") {
-        // LinkedIn reads a pre-populated lead list (not an ICP-driven query); the ICP
-        // scores the pulled list below. List id: disc.listId or --list <id>.
-        const listId = disc.listId ?? option(rest, "--list") ?? undefined;
-        if (!listId) {
-            throw new Error("enrich acquire --source linkedin needs a HeyReach lead-list id: pass --list <id> or set acquire.discovery.linkedin.listId.");
-        }
-        const provider = createLinkedInProvider(disc.provider, providerKey("heyreach"));
-        prospects = await discoverLinkedInProspects(provider, { sourceId: listId, max: size });
-    }
-    else {
-        throw new Error(`enrich acquire: unknown discovery provider "${disc.provider}" (explorium | pipe0 | linkedin).`);
-    }
-    // Surface a zero-discovery result LOUDLY rather than emit a silent empty plan.
-    // A provider that returns 0 with no error usually means an over-narrow ICP
-    // filter (most often the industry/seniority vocab) — not "no market exists".
-    const discoveredCount = prospects.length;
-    if (discoveredCount === 0) {
+    const explicitScanLimit = numericOption(rest, "--scan-limit");
+    const scanLimit = Math.max(targetFresh, Math.min(explicitScanLimit ?? disc.scanLimit ?? Math.max(100, targetFresh * 10), 5_000));
+    const listId = disc.listId ?? option(rest, "--list") ?? undefined;
+    if ((disc.provider === "linkedin" || disc.provider === "heyreach") && !listId) {
+        throw new Error("enrich acquire --source linkedin needs a HeyReach lead-list id: pass --list <id> or set acquire.discovery.linkedin.listId.");
+    }
+    const filters = disc.provider === "explorium"
+        ? (icp ? icpToExploriumFilters(icp) : (disc.filters ?? {}))
+        : disc.provider === "pipe0"
+            ? (icp ? icpToCrustdataFilters(icp) : (disc.filters ?? {}))
+            : {};
+    const queryFingerprint = createHash("sha256")
+        .update(JSON.stringify({ source, provider: disc.provider, listId, filters, icp: icp ?? null }))
+        .digest("hex");
+    const checkpointKey = {
+        provider: disc.provider,
+        source,
+        listId: listId ?? null,
+        queryFingerprint,
+    };
+    const checkpointStore = createFileAcquireCheckpointStore();
+    const localCheckpoint = await checkpointStore.get(checkpointKey);
+    const hostedRead = await readHostedAcquireCheckpoint(acquireCheckpointId(checkpointKey));
+    const hostedRecord = hostedRead.status === "found" ? hostedRead.record : null;
+    const hostedVersion = hostedRecord?.version ?? null;
+    // Once paired, hosted state lets another authenticated worker resume this
+    // audience. A newer offline local checkpoint is still preserved and pushed
+    // with CAS; otherwise hosted wins. Legacy run telemetry is a one-time
+    // migration source only when neither dedicated store has this exact key.
+    let persisted = localCheckpoint?.continuation;
+    if (hostedRecord &&
+        (!localCheckpoint || hostedRecord.updatedAt >= Date.parse(localCheckpoint.updatedAt))) {
+        persisted = hostedRecord.checkpoint;
+        if (persistCheckpoint) {
+            await checkpointStore.put(checkpointKey, {
+                cursor: hostedRecord.checkpoint.cursor,
+                offset: hostedRecord.checkpoint.offset,
+                exhausted: hostedRecord.checkpoint.exhausted,
+            }, new Date(hostedRecord.updatedAt));
+        }
+    }
+    const prior = priorRun?.acquireTelemetry?.discovery;
+    const resume = persisted ?? (prior?.queryFingerprint === queryFingerprint
+        ? { cursor: prior.cursor, offset: prior.offset, exhausted: prior.exhausted }
+        : undefined);
+    let cursor = resume?.cursor ?? null;
+    let offset = resume?.offset ?? 0;
+    let exhausted = resume?.exhausted ?? false;
+    let discovered = 0;
+    let qualified = 0;
+    let skippedCrm = 0;
+    let skippedSeen = 0;
+    const prospects = [];
+    const crmKeys = crmContactKeys(snapshot);
+    const runSeen = new Set(seen);
+    // Pull successive pages until we have enough fresh candidates or hit the
+    // bounded scan ceiling. Page size follows the remaining target, so advancing
+    // a cursor never silently discards unused candidates from the final page.
+    while (prospects.length < targetFresh && discovered < scanLimit && !exhausted) {
+        // Cursor/offset providers can shrink the final request exactly. Explorium
+        // uses page numbers, so keep page_size stable or page boundaries would
+        // overlap/skip as the number of fresh candidates changes.
+        const requestSize = Math.max(1, Math.min(100, disc.provider === "explorium" ? targetFresh : targetFresh - prospects.length, scanLimit - discovered));
+        let page;
+        let exploriumPage = null;
+        if (disc.provider === "pipe0") {
+            const result = await fetchPipe0CrustdataProspectPage({
+                apiKey: providerKey("pipe0"), filters, limit: requestSize, cursor: cursor ?? undefined,
+            });
+            page = result.prospects;
+            cursor = result.nextCursor;
+            exhausted = result.nextCursor === null;
+        }
+        else if (disc.provider === "explorium") {
+            const pageNumber = offset + 1;
+            exploriumPage = pageNumber;
+            page = await fetchExploriumProspects({
+                apiKey: providerKey("explorium"),
+                filters: filters,
+                size: requestSize,
+                page: pageNumber,
+            });
+            exhausted = page.length < requestSize;
+        }
+        else if (disc.provider === "linkedin" || disc.provider === "heyreach") {
+            const provider = createLinkedInProvider(disc.provider, providerKey("heyreach"));
+            page = await discoverLinkedInProspects(provider, {
+                sourceId: listId, max: requestSize, cursor: String(offset),
+            });
+            offset += page.length;
+            exhausted = page.length < requestSize;
+        }
+        else {
+            throw new Error(`enrich acquire: unknown discovery provider "${disc.provider}" (explorium | pipe0 | linkedin).`);
+        }
+        discovered += page.length;
+        progress.items(discovered, scanLimit);
+        if (page.length === 0) {
+            exhausted = true;
+            break;
+        }
+        let fitted = page;
+        if (icp) {
+            const threshold = fitThreshold(icp);
+            fitted = page
+                .map((p) => ({ ...p, fitScore: scoreProspectAgainstIcp(p, icp).score }))
+                .filter((p) => (p.fitScore ?? 0) >= threshold);
+        }
+        qualified += fitted.length;
+        const partition = partitionFreshProspects(fitted, crmKeys, runSeen);
+        skippedCrm += partition.skippedCrm;
+        skippedSeen += partition.skippedSeen;
+        const remainingTarget = targetFresh - prospects.length;
+        for (const prospect of partition.fresh) {
+            if (prospects.length >= targetFresh)
+                break;
+            prospects.push(prospect);
+            for (const key of prospectIdentityKeys(prospect))
+                runSeen.add(key);
+        }
+        progress.note(`${discovered} scanned · ${qualified} qualified · ${prospects.length}/${targetFresh} fresh`);
+        // Explorium is page-number based. Only advance after consuming every fresh
+        // candidate on that page; otherwise the next run safely re-reads the page
+        // and CRM/seen dedupe exposes the remainder instead of losing it.
+        if (exploriumPage !== null && partition.fresh.length <= remainingTarget)
+            offset = exploriumPage;
+    }
+    if (discovered === 0 && !resume) {
         console.error(`enrich acquire: ${disc.provider} discovered 0 prospects for this ICP — the plan will be empty. ` +
             "This is usually an over-narrow filter, not an empty market: check the ICP's industry and seniority " +
             "(provider vocab is finicky), widen one constraint, or run `fullstackgtm icp show` to inspect the " +
             "generated discovery filters. (Distinct from dedup: nothing was returned to filter.)");
     }
-    // 2. ICP fit scoring BEFORE paying for emails — only above-threshold prospects
-    //    proceed to (credit-spending) email resolution.
-    if (icp) {
-        const threshold = fitThreshold(icp);
-        prospects = prospects
-            .map((p) => ({ ...p, fitScore: scoreProspectAgainstIcp(p, icp).score }))
-            .filter((p) => (p.fitScore ?? 0) >= threshold);
-        if (discoveredCount > 0 && prospects.length === 0) {
-            console.error(`enrich acquire: all ${discoveredCount} discovered prospect(s) scored below the ICP fit threshold ` +
-                `(${fitThreshold(icp)}) — none qualified. Loosen the ICP persona or lower scoring.threshold.`);
-        }
-    }
-    // 2.5 Pre-email dedup — drop prospects already in the CRM (name+domain match
-    //     vs the snapshot) or already processed in a prior run (the seen cache),
-    //     BEFORE paying pipe0 for emails. The email-level dedup (buildAcquirePlan)
-    //     and apply-time resolve-first remain the precise backstop.
-    const { fresh, skippedCrm, skippedSeen } = partitionFreshProspects(prospects, crmContactKeys(snapshot), seen);
-    prospects = fresh;
+    if (icp && discovered > 0 && qualified === 0) {
+        console.error(`enrich acquire: all ${discovered} discovered prospect(s) scored below the ICP fit threshold ` +
+            `(${fitThreshold(icp)}) — none qualified. Loosen the ICP persona or lower scoring.threshold.`);
+    }
+    progress.stage(ACQUIRE_STAGES[1], 1, ACQUIRE_STAGES.length);
+    progress.note("checking work-email requirements");
     // 3. Resolve real work emails. Triggered either when email IS the dedupe key
     //    (Explorium's email is hashed, Crustdata returns none) or when a source
     //    that keys on something else opts in via `resolveEmailsWith: "pipe0"`
@@ -515,10 +659,16 @@ async function acquireFromApi(config, source, rest, icp, snapshot, seen) {
         // names. Resolve domains first (pipe0 company:identity) so resolution can
         // actually land — without it, name-only resolution fails for every lead.
         if (prospects.some((p) => !p.companyDomain && p.companyName)) {
-            prospects = await pipe0ResolveCompanyDomains({ apiKey: providerKey("pipe0"), prospects });
+            progress.note(`resolving company domains for ${prospects.length} candidate(s)`);
+            const resolved = await pipe0ResolveCompanyDomains({ apiKey: providerKey("pipe0"), prospects });
+            prospects.splice(0, prospects.length, ...resolved);
         }
-        prospects = await pipe0ResolveWorkEmails({ apiKey: providerKey("pipe0"), prospects });
+        progress.note(`resolving work emails for ${prospects.length} candidate(s)`);
+        const resolved = await pipe0ResolveWorkEmails({ apiKey: providerKey("pipe0"), prospects });
+        prospects.splice(0, prospects.length, ...resolved);
     }
+    progress.items(prospects.length, prospects.length);
+    progress.note(`${prospects.length} candidate(s) ready for planning`);
     const processedKeys = prospects.flatMap(prospectIdentityKeys);
     const records = prospects
         .map((p) => {
@@ -531,7 +681,46 @@ async function acquireFromApi(config, source, rest, icp, snapshot, seen) {
         };
     })
         .filter((record) => Boolean(record.keys[matchKey]));
-    return { records, skippedCrm, skippedSeen, processedKeys };
+    const discovery = { queryFingerprint, cursor, offset, exhausted };
+    return {
+        records,
+        skippedCrm,
+        skippedSeen,
+        processedKeys,
+        telemetry: {
+            funnel: {
+                discovered,
+                qualified,
+                skippedCrm,
+                skippedSeen,
+                resolved: records.length,
+                proposed: 0,
+                withheldByMeter: 0,
+            },
+            discovery,
+        },
+        checkpointKey,
+        hostedVersion,
+    };
+}
+/** Commit continuation only after the saved plan/run is durable. */
+async function persistAcquireCheckpoint(key, discovery, hostedVersion) {
+    const store = createFileAcquireCheckpointStore();
+    await store.put(key, {
+        cursor: discovery.cursor,
+        offset: discovery.offset,
+        exhausted: discovery.exhausted,
+    });
+    const hostedWrite = await writeHostedAcquireCheckpoint(acquireCheckpointId(key), discovery, hostedVersion);
+    if (hostedWrite.status === "conflict" && hostedWrite.current) {
+        const current = hostedWrite.current.checkpoint;
+        await store.put(key, { cursor: current.cursor, offset: current.offset, exhausted: current.exhausted }, new Date(hostedWrite.current.updatedAt));
+        console.error("Acquisition checkpoint advanced concurrently in the hosted workspace; " +
+            "the newer hosted continuation was kept locally for the next run.");
+    }
+    else if (hostedWrite.status === "unavailable") {
+        console.error(`Hosted checkpoint sync unavailable; local continuation retained (${hostedWrite.reason}).`);
+    }
 }
 /**
  * Rich-only fuel gauge under the acquire meter line: one bar per configured
@@ -566,6 +755,10 @@ function formatAcquireMeter(headroom, costPerRecord) {
         `Spend left: ${money(headroom.spendUsd.day)}/day, ${money(headroom.spendUsd.month)}/month ` +
         `(≈$${costPerRecord.toFixed(2)}/lead).`);
 }
+function hostedRunsUrl() {
+    const baseUrl = getCredential("broker")?.baseUrl?.replace(/\/+$/, "");
+    return baseUrl ? `${baseUrl}/dashboard/runs` : null;
+}
 function resolveEnrichSource(config, rest) {
     const requested = option(rest, "--source");
     const declared = Object.keys(config.sources);
@@ -767,6 +960,7 @@ async function enrichStatus(store, rest, configFile) {
                 startedAt: last.startedAt,
                 completedAt: last.completedAt,
                 counts: last.counts,
+                acquireTelemetry: last.acquireTelemetry,
                 planIds: last.planIds,
             },
             interrupted: interrupted.map((run) => ({ runLabel: run.runLabel, cursor: run.cursor })),
@@ -790,6 +984,16 @@ async function enrichStatus(store, rest, configFile) {
             ` · ${last.counts.fetched} fetched, ${last.counts.matched} matched, ${last.counts.unmatched} unmatched,` +
             ` ${last.counts.ambiguous} ambiguous, ${last.counts.opsEmitted} ops` +
             (last.planIds.length ? ` · plans: ${last.planIds.join(", ")}` : ""));
+        if (last.acquireTelemetry) {
+            const f = last.acquireTelemetry.funnel;
+            const d = last.acquireTelemetry.discovery;
+            console.log(`  funnel: ${f.discovered} discovered → ${f.qualified} qualified → ` +
+                `${f.resolved} resolved → ${f.proposed} proposed` +
+                ` · skipped ${f.skippedCrm} CRM + ${f.skippedSeen} seen` +
+                (f.withheldByMeter ? ` · ${f.withheldByMeter} meter-withheld` : ""));
+            console.log(`  audience: ${d.exhausted ? "exhausted" : "continuing"}` +
+                `${d.cursor ? " · cursor saved" : d.offset ? ` · offset ${d.offset}` : ""}`);
+        }
         for (const run of entry.interrupted) {
             console.log(`  interrupted: ${run.runLabel} at cursor ${run.cursor ?? "(start)"} — re-run with --save to resume`);
         }

package/dist/cli/help.js

@@ -176,7 +176,7 @@ Usage:
   fullstackgtm suggest --plan-id <id> | --plan <path>  [source options] [--json] [--out <path>]
                                                derive values for requires_human_* placeholders
                                                from snapshot evidence, with confidence + reasons
-  fullstackgtm plans list [--status <s>] | show <id> | reject <id>
+  fullstackgtm plans list [--status <s>] | show <id> | sync | reject <id>
   fullstackgtm plans approve <id> --operations <ids|all> [--value <opId>=<v>]
   fullstackgtm plans approve <id> --values-from <suggestions.json> [--min-confidence high|low] [--include-creates]
   fullstackgtm plans recover <id> --acknowledge-uncertain-writes
@@ -200,7 +200,11 @@ Profiles (multi-organization use):
 Plan lifecycle:
   audit --save persists the dry-run plan to ~/.fullstackgtm/plans. Approve
   specific operations (optionally with --value <opId>=<v> for placeholders),
-  then apply by id — the store enforces approval and records every run.
+  then apply by id — the store enforces approval and records every run. When
+  paired, local and hosted are replicas of the same immutable plan: either
+  capable surface may approve or apply, and each CLI check-in imports missing
+  approvals and exact operation receipts. Use \`plans sync\` for an explicit
+  check-in; offline changes reconcile later without blocking local work.
 
 Authentication (checked in order):
   1. --token-env <name>        explicit env var for this invocation (hubspot)
@@ -495,15 +499,15 @@ export const HELP = {
         seeAlso: ["audit", "plans", "apply"],
     },
     plans: {
-        summary: "plan lifecycle: list / show / approve / reject saved plans",
+        summary: "replicated plan lifecycle: list / show / sync / approve / reject",
         phase: "Govern",
         synopsis: [
-            "fullstackgtm plans list [--status <s>] | show <id> | reject <id>",
+            "fullstackgtm plans list [--status <s>] | show <id> | sync | reject <id>",
             "fullstackgtm plans approve <id> --operations <ids|all> [--value <opId>=<v>]",
             "fullstackgtm plans approve <id> --values-from <suggestions.json> [--min-confidence high|low]",
             "fullstackgtm plans recover <id> --acknowledge-uncertain-writes",
         ],
-        detail: "Approval is explicit and per-operation; placeholders need a concrete --value or a suggestion to be approvable.",
+        detail: "Approval is explicit and per-operation; placeholders need a concrete --value or a suggestion to be approvable. When paired, hosted and CLI are eventually consistent replicas of one immutable plan. `plans sync` explicitly exchanges approval revisions, execution state, and exact per-operation receipts; ordinary plan commands also check in best-effort. Either surface may apply when its CRM connector supports the selected operations.",
         seeAlso: ["audit", "suggest", "apply"],
     },
     apply: {
@@ -514,7 +518,7 @@ export const HELP = {
             "fullstackgtm apply --plan-id <id> --channel outbox   (render approved drafted openers to the outbox; transmits nothing)",
             "fullstackgtm apply --plan <path> --provider <name> --approve <ids|all> [--value <opId>=<v>]",
         ],
-        detail: "The only verb that mutates a CRM. Writes only operations approved via `plans approve` or `--approve`, with compare-and-set and readback. Never writes requires_human_* placeholders without a --value override.",
+        detail: "The CLI CRM-write verb. Writes only operations approved locally or imported from the shared hosted replica, with an online execution claim when available, stable operation ids, compare-and-set, resolve-before-create, and readback. Hosted may execute the same synchronized plan when it has a compatible CRM connection; its exact operation receipts are imported on the next CLI check-in. Never writes requires_human_* placeholders without a --value override.",
         seeAlso: ["plans", "suggest", "audit-log"],
     },
     "audit-log": {
@@ -620,7 +624,7 @@ export const COMMAND_FLAGS = {
     dedupe: [...SOURCE_FLAGS, "--key", "--keep", "--reason", "--max-operations", "--save", "--dry-run", "--json", "--out"],
     reassign: [...SOURCE_FLAGS, "--from", "--assign-unowned", "--to", "--objects", "--where", "--except-deal-stage", "--include-closed-deals", "--reason", "--max-operations", "--save", "--dry-run", "--json", "--out"],
     backfill: [...SOURCE_FLAGS, "--since", "--pipeline", "--match-property", "--skip-unmatched", "--save", "--dry-run", "--json"],
-    enrich: [...SOURCE_FLAGS, "--config", "--source", "--icp", "--input", "--provider", "--stale-days", "--assign-owner", "--objects", "--max", "--staged-run", "--run-label", "--label", "--runs", "--save", "--dry-run", "--json", "--out"],
+    enrich: [...SOURCE_FLAGS, "--config", "--source", "--icp", "--input", "--provider", "--list", "--stale-days", "--assign-owner", "--objects", "--max", "--scan-limit", "--staged-run", "--run-label", "--label", "--runs", "--save", "--dry-run", "--json", "--out"],
     call: [...SOURCE_FLAGS, "--transcript", "--title", "--source", "--model", "--deterministic", "--heuristics", "--llm", "--json", "--ndjson", "--out", "--call", "--call-type", "--rubric", "--list", "--list-rubrics", "--attendees", "--domain", "--deal", "--save", "--dry-run"],
     suggest: [...SOURCE_FLAGS, "--plan-id", "--plan", "--json", "--out"],
     plans: ["--status", "--operations", "--value", "--values-from", "--min-confidence", "--include-creates", "--acknowledge-uncertain-writes", "--json"],
@@ -632,10 +636,10 @@ export const COMMAND_FLAGS = {
     icp: [...SOURCE_FLAGS, "--name", "--signals-from", "--with-history", "--prompt", "--min-score", "--from-judge", "--golden", "--against-outcomes", "--min-accuracy", "--model", "--label", "--save", "--json", "--out"],
     signals: ["--bucket", "--source", "--connector", "--connector-opt", "--watchlist", "--keywords", "--from", "--label", "--since", "--account", "--contact", "--unjudged", "--touch", "--result", "--save", "--json", "--explain"],
     draft: ["--from-judge", "--min-score", "--prompt", "--model", "--channel", "--save", "--dry-run", "--json", "--out"],
-    schedule: ["--cron", "--label", "--provider", "--trigger", "--runs", "--json"],
+    schedule: ["--cron", "--label", "--provider", "--trigger", "--timer", "--runs", "--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", "--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", "--login-url", "--match", "--match-property", "--max", "--max-claims", "--max-credits", "--max-examples", "--max-operations", "--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", "--scopes", "--seed", "--set", "--signals-from", "--since", "--snapshot", "--source", "--staged-run", "--stale-days", "--status", "--task-account", "--task-deal", "--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", "--channel", "--client", "--client-id", "--client-secret", "--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-claims", "--max-credits", "--max-examples", "--max-operations", "--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.