fullstackgtm 0.49.0 → 0.50.0

package/src/cli/help.ts

@@ -180,7 +180,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
@@ -204,7 +204,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)
@@ -543,15 +547,16 @@ export const HELP: Record<string, HelpEntry> = {
     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: {
@@ -563,7 +568,7 @@ export const HELP: Record<string, HelpEntry> = {
       "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.",
+      "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": {
@@ -681,7 +686,7 @@ export const COMMAND_FLAGS: Record<string, string[]> = {
   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"],
@@ -693,11 +698,11 @@ export const COMMAND_FLAGS: Record<string, string[]> = {
   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

package/src/cli/plans.ts

@@ -15,6 +15,7 @@ import { createFilePlanStore } from "../planStore.ts";
 import { ENRICH_CONFIG_FILE_NAME, loadEnrichConfig, type EnrichConfig } from "../enrich.ts";
 import { loadMeter, recordConsumption, remaining } from "../acquireMeter.ts";
 import { progressReporter, reportCounts } from "../runReport.ts";
+import { claimHostedPlanApply, reconcileHostedPatchPlan, releaseHostedPlanApply, reportHostedPlanLifecycle, uploadHostedPatchPlan } from "../hostedPatchPlan.ts";
 import { APPLY_STAGES, composeListeners, createProgressEmitter } from "../progress.ts";
 import type { ValueSuggestion } from "../suggest.ts";
 import type { CanonicalGtmSnapshot, CreateRecordPayload, PatchOperation, PatchPlan, PatchPlanRun } from "../types.ts";
@@ -141,8 +142,18 @@ export async function apply(args: string[]) {
   const store = planId ? createFilePlanStore() : null;
 
   if (planId && store) {
-    const stored = await store.get(planId);
+    let stored = await store.get(planId);
     if (!stored) throw new Error(`No stored plan with id ${planId}.`);
+    const reconciliation = await reconcileHostedPatchPlan(store, stored);
+    if (reconciliation.status === "conflict") throw new Error(`Refusing to apply plan ${planId}: ${reconciliation.reason}.`);
+    if (reconciliation.status === "updated") {
+      stored = reconciliation.stored;
+      console.error(`Synced hosted ${reconciliation.remoteStatus} state for ${planId}.`);
+    }
+    if (stored.status === "applied") {
+      console.log(`Plan ${planId} was already applied by another replica; imported its execution receipt. No provider writes were attempted.`);
+      return;
+    }
     if (stored.status !== "approved") {
       throw new Error(
         `Plan ${planId} is ${stored.status}; approve operations first with \`fullstackgtm plans approve ${planId} --operations <ids|all>\`.`,
@@ -235,9 +246,29 @@ export async function apply(args: string[]) {
   // transmits nothing; a CRM provider writes records. Same governed apply path.
   const connector = channel ? createChannelConnector(channel) : await connectorFor(provider!, args);
   let applyClaimId: string | undefined;
+  let hostedApplyClaimId: string | undefined;
   if (planId && store) {
     const claimed = await store.claimApply(planId, { provider: provider ?? `channel:${channel}`, source: "cli" });
     applyClaimId = claimed.claimId;
+    const hostedClaim = await claimHostedPlanApply(claimed.stored);
+    if (hostedClaim.status === "applied") {
+      await store.abortApplyPreflight(planId, claimed.claimId, "Another replica completed apply before provider I/O.");
+      const refreshed = await store.get(planId);
+      if (refreshed) await reconcileHostedPatchPlan(store, refreshed);
+      console.log(`Plan ${planId} was already applied by another replica. No provider writes were attempted.`);
+      return;
+    }
+    if (hostedClaim.status === "conflict") {
+      await store.abortApplyPreflight(planId, claimed.claimId, `Hosted execution claim failed: ${hostedClaim.reason}`);
+      throw new Error(`Refusing to apply plan ${planId}: could not coordinate with its hosted replica (${hostedClaim.reason}).`);
+    }
+    if (hostedClaim.status === "unavailable") {
+      console.error(`Hosted replica is unavailable (${hostedClaim.reason}); continuing local-first. Resolve-before-create and provider conflict guards remain active, and the execution receipt will sync on a later check-in.`);
+    }
+    if (hostedClaim.status === "claimed") {
+      hostedApplyClaimId = hostedClaim.claimId;
+      await store.recordHostedClaim(planId, claimed.claimId, hostedClaim.claimId);
+    }
     const claimedVerification = verifyApprovalDigests(
       claimed.stored.plan.operations,
       claimed.stored.approvedOperationIds,
@@ -245,6 +276,16 @@ export async function apply(args: string[]) {
       claimed.stored.approvalDigests,
     );
     if (!claimedVerification.ok) {
+      if (hostedApplyClaimId) {
+        const released = await releaseHostedPlanApply(
+          claimed.stored,
+          hostedApplyClaimId,
+          "Approval integrity verification failed after claim and before provider I/O.",
+        );
+        if (released.status === "conflict" || released.status === "unavailable") {
+          console.error(`Hosted apply claim may require recovery: ${released.reason}.`);
+        }
+      }
       await store.abortApplyPreflight(
         planId,
         claimed.claimId,
@@ -280,7 +321,12 @@ export async function apply(args: string[]) {
     renderer.done();
   }
   if (planId && store) {
-    await store.recordRun(planId, run, applyClaimId!);
+    const recorded = await store.recordRun(planId, run, applyClaimId!);
+    const durableHostedClaimId = recorded.applyAttempts?.find((attempt) => attempt.id === applyClaimId)?.hostedClaimId;
+    const mirrored = await reportHostedPlanLifecycle(recorded, { claimId: durableHostedClaimId ?? hostedApplyClaimId });
+    if (mirrored.status === "unavailable" || mirrored.status === "conflict") {
+      console.error(`Hosted plan status is stale: ${mirrored.reason}. Local apply history remains authoritative.`);
+    }
   }
 
   // Charge the acquire meter for the creates that actually landed.
@@ -408,7 +454,13 @@ export async function plansCommand(args: string[]) {
     const status = option(rest, "--status") as
       | "draft" | "needs_approval" | "approved" | "rejected" | "applied"
       | null;
-    const plans = await store.list(status ?? undefined);
+    let plans = await store.list(status ?? undefined);
+    const synced = await Promise.all(plans.map(async (stored) => {
+      const result = await reconcileHostedPatchPlan(store, stored);
+      if (result.status === "updated") return result.stored;
+      return stored;
+    }));
+    plans = status ? synced.filter((stored) => stored.status === status) : synced;
     if (rest.includes("--json") || args.includes("--json")) {
       console.log(
         JSON.stringify(
@@ -473,8 +525,15 @@ export async function plansCommand(args: string[]) {
   if (subcommand === "show") {
     const planId = rest.find((arg) => !arg.startsWith("--"));
     if (!planId) throw new Error("Usage: fullstackgtm plans show <planId>");
-    const stored = await store.get(planId);
+    let stored = await store.get(planId);
     if (!stored) throw new Error(`No stored plan with id ${planId}.`);
+    const reconciliation = await reconcileHostedPatchPlan(store, stored);
+    if (reconciliation.status === "updated") {
+      stored = reconciliation.stored;
+      console.error(`Synced hosted ${reconciliation.remoteStatus} state for ${planId}.`);
+    } else if (reconciliation.status === "conflict") {
+      console.error(`Hosted sync conflict: ${reconciliation.reason}.`);
+    }
     if (rest.includes("--json")) {
       console.log(JSON.stringify(stored, null, 2));
       return;
@@ -483,6 +542,9 @@ export async function plansCommand(args: string[]) {
     console.log(`Status: ${planStatusWord(stored.status, showPaint)}`);
     console.log(`Approved operations: ${stored.approvedOperationIds.join(", ") || "none"}`);
     console.log(`Runs: ${stored.runs.length}`);
+    const mirror = await uploadHostedPatchPlan(stored);
+    if (mirror.status === "saved") console.log(`Hosted review: ${mirror.state.url}`);
+    else if (mirror.status === "unavailable" || mirror.status === "conflict") console.log(`Hosted review: sync pending (${mirror.reason})`);
     if (stored.applyAttempts?.length) {
       console.log("Apply attempts:");
       for (const attempt of stored.applyAttempts) {
@@ -541,6 +603,10 @@ export async function plansCommand(args: string[]) {
       ...fileOverrides,
       ...explicitOverrides,
     });
+    const mirror = await reportHostedPlanLifecycle(updated);
+    if (mirror.status === "unavailable" || mirror.status === "conflict") {
+      console.error(`Hosted plan status is stale: ${mirror.reason}. Local approval remains authoritative.`);
+    }
     console.log(
       `Approved ${updated.approvedOperationIds.length} operation(s) on ${planId}. Apply with \`fullstackgtm apply --plan-id ${planId} --provider <name>\`.`,
     );
@@ -550,7 +616,11 @@ export async function plansCommand(args: string[]) {
   if (subcommand === "reject") {
     const planId = rest.find((arg) => !arg.startsWith("--"));
     if (!planId) throw new Error("Usage: fullstackgtm plans reject <planId>");
-    await store.reject(planId);
+    const rejected = await store.reject(planId);
+    const mirror = await reportHostedPlanLifecycle(rejected);
+    if (mirror.status === "unavailable" || mirror.status === "conflict") {
+      console.error(`Hosted plan status is stale: ${mirror.reason}. Local rejection remains authoritative.`);
+    }
     console.log(`Rejected ${planId}.`);
     return;
   }
@@ -581,5 +651,24 @@ export async function plansCommand(args: string[]) {
     return;
   }
 
-  throw unknownSubcommandError("plans", subcommand, ["list", "show", "approve", "reject", "recover"]);
+  if (subcommand === "sync") {
+    const plans = await store.list();
+    let updated = 0;
+    const warnings: string[] = [];
+    for (const stored of plans) {
+      const result = await reconcileHostedPatchPlan(store, stored);
+      if (result.status === "updated") updated += 1;
+      else if (result.status === "conflict" || result.status === "unavailable") warnings.push(`${stored.plan.id}: ${result.reason}`);
+      if (stored.status === "applied") {
+        const hostedClaimId = [...(stored.applyAttempts ?? [])].reverse().find((attempt) => attempt.hostedClaimId)?.hostedClaimId;
+        const pushed = await reportHostedPlanLifecycle(stored, { claimId: hostedClaimId });
+        if (pushed.status === "conflict" || pushed.status === "unavailable") warnings.push(`${stored.plan.id} receipt: ${pushed.reason}`);
+      }
+    }
+    console.log(`Plan replicas synchronized: ${updated} updated, ${plans.length - updated} unchanged.`);
+    for (const warning of warnings) console.error(`  ${warning}`);
+    return;
+  }
+
+  throw unknownSubcommandError("plans", subcommand, ["list", "show", "sync", "approve", "reject", "recover"]);
 }

package/src/cli/shared.ts

@@ -164,6 +164,7 @@ export async function connectorFor(
 export async function readSnapshot(
   args: string[],
   progress?: ProgressEmitter,
+  options: { persistProgress?: boolean } = {},
 ): Promise<CanonicalGtmSnapshot> {
   const provider = option(args, "--provider");
   if (provider) {
@@ -189,7 +190,7 @@ export async function readSnapshot(
     try {
       return await connector.fetchSnapshot();
     } finally {
-      renderer.done();
+      renderer.done({ persist: options.persistProgress });
     }
   }
   if (args.includes("--demo")) {

package/src/cli/ui.ts

@@ -286,8 +286,8 @@ export function startElapsedStatus(
 
 export type Checklist = {
   update(id: string, state: "pending" | "running" | "ok" | "warn" | "fail", note?: string): void;
-  /** Stop animating and erase the board (callers print their own summary). */
-  done(): void;
+  /** Stop animating; optionally leave the final board in the terminal history. */
+  done(options?: { persist?: boolean }): void;
   readonly active: boolean;
 };
 
@@ -296,7 +296,8 @@ const NOOP_CHECKLIST: Checklist = { update() {}, done() {}, active: false };
 /**
  * A multi-line live board — one line per item, each flipping ○ → ⠹ → ✓ as work
  * progresses (the audit rule registry renders through this). Repaints with
- * cursor-up; erases itself on done() so the verb's real output owns stdout.
+ * cursor-up; done() normally erases it, while done({ persist: true }) leaves a
+ * final static history for multi-phase human workflows.
  */
 export function createChecklist(
   items: Array<{ id: string; label: string }>,
@@ -343,13 +344,20 @@ export function createChecklist(
       const entry = states.get(id);
       if (!entry) return;
       entry.state = state;
-      entry.note = note;
+      if (note !== undefined) entry.note = note;
       start();
       render();
     },
-    done() {
+    done(options = {}) {
       if (timer) clearInterval(timer);
       timer = null;
+      if (options.persist) {
+        // The caller's final state update already painted the completed board.
+        // Freeze that frame in scrollback; repainting here can leave both the
+        // last live frame and the final frame visible in some terminals.
+        painted = 0;
+        return;
+      }
       if (painted > 0) {
         // Erase the board: cursor up over every painted line, clear each.
         stream.write(`\u001b[${painted}A${"\u001b[2K\n".repeat(painted)}\u001b[${painted}A`);
@@ -366,8 +374,8 @@ export type ProgressRenderer = {
    * listener via `composeListeners` when the run should also heartbeat).
    */
   listener: ProgressListener;
-  /** Stop animating and erase the board (callers print their own summary). */
-  done(): void;
+  /** Stop animating; optionally leave the completed board in terminal history. */
+  done(options?: { persist?: boolean }): void;
   readonly active: boolean;
 };
 
@@ -423,8 +431,9 @@ export function createProgressRenderer(
       // larger flow) are ignored by createChecklist's unknown-id no-op.
       if (current) board.update(current, "running", noteFor(event, snapshot));
     },
-    done() {
-      board.done();
+    done(options) {
+      if (current) board.update(current, "ok");
+      board.done(options);
     },
     active: true,
   };

package/src/connectors/linkedin.ts

@@ -41,6 +41,8 @@ export type FetchProspectsOptions = {
   sourceId?: string;
   /** Hard cap on prospects returned; also bounds pagination. */
   max?: number;
+  /** Opaque continuation cursor. HeyReach uses the decimal list offset. */
+  cursor?: string;
 };
 
 export type ConnectionStatus = { ok: boolean; detail: string };
@@ -152,6 +154,10 @@ export function createHeyReachProvider(options: HeyReachProviderOptions): Linked
       const max = opts.max ?? Number.POSITIVE_INFINITY;
       const out: LinkedInProspect[] = [];
       let offset = 0;
+      if (opts.cursor !== undefined) {
+        if (!/^\d+$/.test(opts.cursor)) throw new Error(`Invalid HeyReach cursor: ${opts.cursor}`);
+        offset = Number(opts.cursor);
+      }
       while (out.length < max) {
         const data = await call("/list/GetLeadsFromList", "POST", { listId, offset, limit: pageSize });
         const items = toArray(data);

package/src/connectors/prospectSources.ts

@@ -68,6 +68,8 @@ export async function fetchExploriumProspects(opts: {
   apiKey: string;
   filters: ExploriumFilters;
   size?: number;
+  /** One-based result page. */
+  page?: number;
   apiBaseUrl?: string;
   fetchImpl?: FetchImpl;
 }): Promise<Prospect[]> {
@@ -77,7 +79,7 @@ export async function fetchExploriumProspects(opts: {
   const response = await fetchImpl(`${base}/v1/prospects`, {
     method: "POST",
     headers: { "api_key": opts.apiKey, "Content-Type": "application/json" },
-    body: JSON.stringify({ mode: "full", size, page_size: size, page: 1, filters: opts.filters }),
+    body: JSON.stringify({ mode: "full", size, page_size: size, page: opts.page ?? 1, filters: opts.filters }),
   });
   if (!response.ok) {
     throw new ProviderHttpError("Explorium", "prospect search", response.status);
@@ -119,17 +121,44 @@ export async function fetchPipe0CrustdataProspects(opts: {
   apiKey: string;
   filters: Record<string, unknown>;
   limit?: number;
+  /** Opaque cursor returned by a previous page. */
+  cursor?: string;
   apiBaseUrl?: string;
   fetchImpl?: FetchImpl;
 }): Promise<Prospect[]> {
+  return (await fetchPipe0CrustdataProspectPage(opts)).prospects;
+}
+
+/** A page from pipe0/Crustdata's cursor-based people search. */
+export type Pipe0CrustdataProspectPage = {
+  prospects: Prospect[];
+  /** Opaque cursor for the next page, or null when the search is exhausted. */
+  nextCursor: string | null;
+};
+
+/**
+ * Fetch one page and expose its continuation cursor. The array-returning
+ * `fetchPipe0CrustdataProspects` remains available for existing consumers.
+ */
+export async function fetchPipe0CrustdataProspectPage(opts: {
+  apiKey: string;
+  filters: Record<string, unknown>;
+  limit?: number;
+  /** Opaque cursor returned by a previous page. */
+  cursor?: string;
+  apiBaseUrl?: string;
+  fetchImpl?: FetchImpl;
+}): Promise<Pipe0CrustdataProspectPage> {
   const fetchImpl = opts.fetchImpl ?? fetch;
   const base = (opts.apiBaseUrl ?? "https://api.pipe0.com").replace(/\/$/, "");
   const limit = Math.min(opts.limit ?? 25, 100);
+  const config: Record<string, unknown> = { limit, filters: opts.filters };
+  if (opts.cursor !== undefined) config.cursor = opts.cursor;
   const response = await fetchImpl(`${base}/v1/searches/run/sync`, {
     method: "POST",
     headers: { Authorization: `Bearer ${opts.apiKey}`, "Content-Type": "application/json" },
     body: JSON.stringify({
-      searches: [{ search_id: "people:profiles:crustdata@1", config: { limit, filters: opts.filters } }],
+      searches: [{ search_id: "people:profiles:crustdata@1", config }],
     }),
   });
   if (!response.ok) {
@@ -137,7 +166,12 @@ export async function fetchPipe0CrustdataProspects(opts: {
   }
   const body = (await response.json()) as {
     results?: Array<Record<string, { value?: unknown }>>;
-    search_statuses?: Array<{ errors?: Array<{ code?: string; message?: string }> }>;
+    next_cursor?: unknown;
+    search_statuses?: Array<{
+      errors?: Array<{ code?: string; message?: string }>;
+      next_cursor?: unknown;
+      cursor?: unknown;
+    }>;
   };
   // Surface upstream provider errors (e.g. CreditBalanceInsufficient) instead of
   // silently returning [] — a throttle/credit failure must not look like "no ICP matches".
@@ -147,7 +181,7 @@ export async function fetchPipe0CrustdataProspects(opts: {
       `pipe0/Crustdata search error: ${upstreamErrors.map((e) => `${e.code ?? "error"}: ${e.message ?? ""}`).join("; ")}`,
     );
   }
-  return (body.results ?? []).map((row) => {
+  const prospects = (body.results ?? []).map((row) => {
     const fullName = strField(row.name);
     const { firstName, lastName } = splitName(fullName);
     return {
@@ -160,6 +194,14 @@ export async function fetchPipe0CrustdataProspects(opts: {
       sourceId: strField(row.profile_url) ?? fullName,
     };
   });
+  // Current pipe0 responses expose `next_cursor` at the top level. Accept the
+  // status-envelope variants too so older deployments remain usable.
+  const status = body.search_statuses?.[0];
+  const rawCursor = body.next_cursor ?? status?.next_cursor ?? status?.cursor;
+  return {
+    prospects,
+    nextCursor: typeof rawCursor === "string" && rawCursor.length > 0 ? rawCursor : null,
+  };
 }
 
 function strField(field: { value?: unknown } | undefined): string | undefined {

package/src/enrich.ts

@@ -111,6 +111,8 @@ export type AcquireDiscoveryConfig = {
   provider: "explorium" | "pipe0" | "linkedin" | "heyreach";
   filters?: Record<string, unknown>;
   size?: number;
+  /** Maximum raw provider candidates scanned per run while seeking fresh leads. */
+  scanLimit?: number;
   resolveEmailsWith?: "pipe0";
   /** LinkedIn sources only: the provider-native list id to read (HeyReach lead-list id). */
   listId?: string;
@@ -1326,7 +1328,49 @@ export function selectStaleWork(
 // Checkpoint (cursor), staleness ledger (stamps), and observability surface
 // (enrich status) in one structure — mirrors the market observations store.
 
-export type EnrichRunMode = EnrichMode | "ingest";
+export type EnrichRunMode = EnrichMode | "ingest" | "acquire";
+
+/**
+ * Provider continuation state for an acquisition query. The fingerprint binds
+ * a cursor/offset to the ICP + provider filters that produced it, preventing a
+ * changed query from accidentally resuming in the middle of the old audience.
+ */
+export type AcquireDiscoveryCheckpoint = {
+  queryFingerprint: string;
+  /** Opaque provider cursor (Pipe0 and other cursor-based sources). */
+  cursor?: string | null;
+  /** Zero-based provider offset (LinkedIn/HeyReach and other offset sources). */
+  offset?: number | null;
+  /** True only when the provider has positively reported no next page. */
+  exhausted: boolean;
+};
+
+/**
+ * Truthful acquisition funnel for one run. Each field counts candidates, not
+ * provider requests, making duplicate saturation and resolution loss visible
+ * instead of reporting every run as zero.
+ */
+export type AcquireRunFunnel = {
+  /** Raw candidates returned across all discovery pages scanned this run. */
+  discovered: number;
+  /** Candidates that met the configured ICP threshold. */
+  qualified: number;
+  /** Qualified candidates removed by the CRM pre-email dedupe. */
+  skippedCrm: number;
+  /** Qualified candidates removed by the cross-run seen ledger. */
+  skippedSeen: number;
+  /** Fresh candidates carrying the configured resolve-first key. */
+  resolved: number;
+  /** Governed create operations emitted into the saved/dry-run plan. */
+  proposed: number;
+  /** Otherwise-proposable candidates held back by the acquire meter. */
+  withheldByMeter: number;
+};
+
+export type AcquireRunTelemetry = {
+  funnel: AcquireRunFunnel;
+  discovery: AcquireDiscoveryCheckpoint;
+};
 
 export type EnrichRun = {
   id: string;
@@ -1339,6 +1383,8 @@ export type EnrichRun = {
   /** Resume point for an interrupted pull (last processed pull key). */
   cursor: string | null;
   counts: EnrichCounts;
+  /** Acquisition-only funnel + provider continuation state (absent on legacy runs). */
+  acquireTelemetry?: AcquireRunTelemetry;
   planIds: string[];
   stamps: EnrichStamp[];
   /** Staged source rows (ingest mode only), consumed by append/refresh. */