fullstackgtm 0.49.0 → 0.50.0

package/CHANGELOG.md

@@ -7,6 +7,59 @@ The path to 1.0 is planned in [docs/roadmap-to-1.0.md](https://github.com/fullst
 
 ## [Unreleased]
 
+## [0.50.0] — 2026-07-10
+
+### Added
+
+- CLI and hosted now act as local-first replicas of one immutable patch plan.
+  Either surface may execute when it has a compatible CRM connection; online
+  execution uses a shared claim, while offline CLI work remains available and
+  reconciles later through stable provider idempotency and exact receipts.
+- `fullstackgtm plans sync` explicitly exchanges approval revisions, terminal
+  state, and per-operation execution receipts. Plan list, show, and apply also
+  perform best-effort ambient check-ins.
+- Hosted can execute fully synchronized CLI-origin plans through its connected
+  HubSpot or Salesforce connector. The CLI imports hosted runs without replaying
+  provider writes, and hosted imports exact CLI outcomes rather than inferring
+  success for every approved row.
+
+### Security
+
+- Shared execution claims are bound to the immutable plan, exact approved
+  subset, replica, and paired CLI token. Approval edits freeze during apply;
+  stranded claims require an explicit audited recovery, and preflight release
+  is permitted only before provider I/O by the owning replica.
+- Hosted ingestion recomputes the immutable document digest and verifies an
+  exact one-to-one operation set. Terminal transitions require complete,
+  duplicate-free receipts for the approved subset and cannot widen authority.
+
+### Fixed
+
+- Paired CLIs now mirror saved plans into the hosted Patch Plans queue and
+  print an exact review deep-link. Mirrors are org-scoped, immutable and
+  idempotent; hosted approvals are hash/operation-verified and locally
+  HMAC-signed before CLI execution. Security state and evidence/findings stay
+  local, while bounded provider receipts replicate between capable executors.
+- `enrich acquire` now reports discovery, resolution, and plan-building progress
+  across the previously silent provider/dedupe middle. Paired hosted runs render
+  the same live stage, counters, and generic progress notes on their detail page.
+- Interactive acquisition runs retain both the CRM snapshot and acquisition
+  checklists in terminal history, then print a compact plan summary, copyable
+  review/approve/apply commands, and the paired hosted Runs deep-link.
+- Persistent progress completion freezes the already-painted final frame rather
+  than repainting it, preventing duplicate live/final checklists in scrollback.
+- Acquisition now persists query-bound Pipe0 cursors and HeyReach/Explorium
+  offsets so scheduled runs traverse the full audience instead of repeatedly
+  exhausting the first 25 results. `--max` controls desired new leads and the
+  new `--scan-limit` bounds raw duplicate-heavy scanning. Run history records
+  the complete discovery funnel and provider-confirmed exhaustion state.
+- Checkpoints now live in a dedicated profile-scoped store keyed independently
+  by provider/source/list/query. Paired CLIs synchronize opaque continuation to
+  an organization-scoped hosted record using broker authentication and
+  compare-and-swap revisions; conflicts retain the newer hosted checkpoint.
+- The documented LinkedIn `--list <id>` flag is accepted by strict CLI parsing,
+  and NAICS-only software ICPs retain their industry constraint on Pipe0.
+
 ## [0.49.0] — 2026-07-10
 
 ### Security

package/DATA-FLOWS.md

@@ -26,6 +26,7 @@ is no fullstackgtm-operated server in the data path for the open package.**
 | `enrich append --source apollo`, `enrich refresh` | **Apollo** (api.apollo.io) | The company domain / contact email being enriched | Your `APOLLO_API_KEY` (BYO) |
 | `market capture`, `market refresh` | **Public vendor websites** you list in `market.config.json` | A bounded HTTP GET; DNS answers are validated and pinned, mixed/private/reserved answers are refused, and every redirect is revalidated | none |
 | `login --via <url>` (optional) | **Your hosted deployment's broker** | A pairing handshake; the broker mints short-lived CRM tokens | broker pairing token |
+| paired `enrich acquire` checkpoint sync (optional) | **Your hosted deployment** | Opaque query fingerprint plus provider cursor/list offset, exhaustion flag, and CAS revision. No prospect records, emails, names, or provider credentials. Scoped to the broker token's organization. | broker pairing token |
 
 Commands not listed (`plans`, `rules`, `doctor`, `schedule`, `audit-log`,
 `diff`, `merge`, report rendering) make **no network calls**.

package/README.md

@@ -192,6 +192,7 @@ echo "$PIPE0_API_KEY" | fullstackgtm login pipe0            # discovery + work-e
 
 fullstackgtm enrich acquire --provider hubspot              # zero-config: ICP → discover → score → dedup → dry-run diff
 fullstackgtm enrich acquire --provider hubspot --max 25 --save   # cap the batch, persist the needs_approval plan
+fullstackgtm enrich acquire --provider hubspot --max 25 --scan-limit 500 --save # scan through duplicate-heavy pages for 25 fresh leads
 fullstackgtm plans approve <id> --operations all
 fullstackgtm apply --plan-id <id> --provider hubspot        # the only step that creates contacts
 ```
@@ -206,6 +207,46 @@ The **ICP** (`icp.json`) is the single targeting artifact: it generates each pro
 
 Every run is **metered**: a per-profile budget caps both record count and provider spend (per-day + per-month, whichever binds first), charged only for creates that actually land. `enrich acquire` runs with just an `icp.json` and a `login` — sensible defaults for budget, provider, and create-mapping ship in the box.
 
+Discovery continuation is profile-scoped and independently keyed by the exact
+provider, source, list, and ICP query. Scheduled runs resume the saved Pipe0
+cursor or HeyReach offset instead of rereading page one, even when several
+lists alternate. When the CLI is paired, this non-PII checkpoint is mirrored
+to the hosted organization with compare-and-swap so another authenticated
+worker can resume without moving a newer cursor backwards. `--max` is the desired net-new plan size;
+`--scan-limit` independently bounds raw candidates scanned after ICP filtering
+and dedupe. `enrich status --runs` exposes the full funnel and whether the
+audience is continuing or provider-confirmed exhausted.
+
+When paired, every saved plan is also mirrored into the hosted Patch Plans
+review queue and the CLI prints its exact deep-link. The mirror is immutable
+and organization-scoped: replaying the same plan is idempotent, while the same
+id with different content is rejected. Hosted reviewers can approve or reject;
+the plan is executable from any synchronized surface with a compatible CRM
+connection. A CLI-created plan can be applied in hosted, and a hosted approval
+can be applied from the CLI—the plan's origin does not permanently own it.
+
+This is local-first replication, not remote control. The local plan store works
+offline, and plan commands perform a best-effort hosted check-in. Run
+`fullstackgtm plans sync` to explicitly exchange every plan's latest approval,
+execution claim, status, and receipts. If hosted applies while the CLI is
+offline, the next check-in imports the exact per-operation results and marks
+the local plan applied. If the CLI applies while hosted is unavailable, it
+keeps the result locally and uploads the receipt on a later check-in.
+
+Before either surface writes, it verifies the immutable plan hash, selected
+operation ids, current approval revision, connector capability, and provider
+state. Online replicas use a short-lived execution claim to coordinate; stable
+operation ids, resolve-before-create, compare-and-set guards, and provider
+readback protect offline retries. Receipts record each operation as `applied`,
+`skipped`, or `failed`, plus provider record ids when available, so another
+replica learns what happened rather than inferring it from plan status. A
+conflicting plan body or approval revision is surfaced for review and is never
+merged by expanding authority.
+
+Local signing keys and HMAC digests never upload. Operation before/after values
+do upload to the paired organization because they are required for informed
+review and hosted execution.
+
 **Discovery sources** are zero-config presets behind `--source`: `explorium` and `pipe0` run ICP-driven people search, while `linkedin` (Phase 1 — discovery + dry-run) reads a pre-built **HeyReach** lead list:
 
 ```bash

package/dist/acquireCheckpoint.d.ts

@@ -0,0 +1,33 @@
+/** The complete identity of one independently traversable provider audience. */
+export type AcquireCheckpointKey = {
+    provider: string;
+    source: string;
+    listId: string | null;
+    queryFingerprint: string;
+};
+export type AcquireContinuation = {
+    cursor?: string | null;
+    offset?: number | null;
+    exhausted: boolean;
+};
+/** Versioned wire format shared by local persistence and hosted sync. */
+export type AcquireCheckpoint = {
+    version: 1;
+    id: string;
+    key: AcquireCheckpointKey;
+    continuation: AcquireContinuation;
+    updatedAt: string;
+};
+export declare function validateAcquireCheckpointKey(value: unknown): AcquireCheckpointKey;
+/** Stable, non-secret filename/key suitable for both filesystem and hosted records. */
+export declare function acquireCheckpointId(key: AcquireCheckpointKey): string;
+export declare function validateAcquireCheckpoint(value: unknown): AcquireCheckpoint;
+export declare function acquireCheckpointsDir(baseDir?: string): string;
+export interface AcquireCheckpointStore {
+    get(key: AcquireCheckpointKey): Promise<AcquireCheckpoint | null>;
+    put(key: AcquireCheckpointKey, continuation: AcquireContinuation, updatedAt?: Date): Promise<AcquireCheckpoint>;
+    /** Import a validated local/hosted record without changing its timestamp. */
+    putRecord(record: AcquireCheckpoint): Promise<AcquireCheckpoint>;
+    list(): Promise<AcquireCheckpoint[]>;
+}
+export declare function createFileAcquireCheckpointStore(baseDir?: string): AcquireCheckpointStore;

package/dist/acquireCheckpoint.js

@@ -0,0 +1,149 @@
+import { createHash } from "node:crypto";
+import { chmodSync, mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { credentialsDir, ensureSecureHomeDir } from "./credentials.js";
+import { assertNoSymlinkComponents, readSecureRegularFile, writeSecureFileAtomic, } from "./secureFile.js";
+const COMPONENT_MAX = 512;
+function requireComponent(value, name) {
+    if (typeof value !== "string" || value.length === 0 || value.length > COMPONENT_MAX || /[\u0000-\u001f]/.test(value)) {
+        throw new Error(`Invalid acquisition checkpoint ${name}`);
+    }
+    return value;
+}
+export function validateAcquireCheckpointKey(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Invalid acquisition checkpoint key");
+    }
+    const candidate = value;
+    const listId = candidate.listId;
+    if (listId !== null && listId !== undefined)
+        requireComponent(listId, "listId");
+    return {
+        provider: requireComponent(candidate.provider, "provider"),
+        source: requireComponent(candidate.source, "source"),
+        listId: listId ?? null,
+        queryFingerprint: requireComponent(candidate.queryFingerprint, "queryFingerprint"),
+    };
+}
+/** Stable, non-secret filename/key suitable for both filesystem and hosted records. */
+export function acquireCheckpointId(key) {
+    const valid = validateAcquireCheckpointKey(key);
+    const canonical = JSON.stringify([valid.provider, valid.source, valid.listId, valid.queryFingerprint]);
+    return `acqcp_${createHash("sha256").update(canonical).digest("hex")}`;
+}
+function validateContinuation(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Invalid acquisition checkpoint continuation");
+    }
+    const candidate = value;
+    if (typeof candidate.exhausted !== "boolean")
+        throw new Error("Invalid acquisition checkpoint exhausted flag");
+    if (candidate.cursor !== undefined && candidate.cursor !== null)
+        requireComponent(candidate.cursor, "cursor");
+    if (candidate.offset !== undefined && candidate.offset !== null &&
+        (!Number.isSafeInteger(candidate.offset) || candidate.offset < 0)) {
+        throw new Error("Invalid acquisition checkpoint offset");
+    }
+    return {
+        ...(candidate.cursor !== undefined ? { cursor: candidate.cursor } : {}),
+        ...(candidate.offset !== undefined ? { offset: candidate.offset } : {}),
+        exhausted: candidate.exhausted,
+    };
+}
+export function validateAcquireCheckpoint(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Invalid acquisition checkpoint");
+    }
+    const candidate = value;
+    if (candidate.version !== 1)
+        throw new Error(`Unsupported acquisition checkpoint version: ${String(candidate.version)}`);
+    const key = validateAcquireCheckpointKey(candidate.key);
+    const id = acquireCheckpointId(key);
+    if (candidate.id !== id)
+        throw new Error("Acquisition checkpoint id does not match its key");
+    if (typeof candidate.updatedAt !== "string" || !Number.isFinite(Date.parse(candidate.updatedAt))) {
+        throw new Error("Invalid acquisition checkpoint updatedAt");
+    }
+    return {
+        version: 1,
+        id,
+        key,
+        continuation: validateContinuation(candidate.continuation),
+        updatedAt: candidate.updatedAt,
+    };
+}
+export function acquireCheckpointsDir(baseDir) {
+    return join(baseDir ?? credentialsDir(), "acquire", "checkpoints");
+}
+export function createFileAcquireCheckpointStore(baseDir) {
+    const directory = acquireCheckpointsDir(baseDir);
+    function fileForId(id) {
+        return join(directory, `${id}.json`);
+    }
+    function readId(id) {
+        try {
+            return validateAcquireCheckpoint(JSON.parse(readSecureRegularFile(fileForId(id), { tightenMode: 0o600 })));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
+        }
+    }
+    function ensureDirectory() {
+        if (baseDir === undefined)
+            ensureSecureHomeDir();
+        // Tighten both managed levels. mkdir's mode does not affect a directory
+        // restored or pre-created with broader permissions.
+        const levels = [join(baseDir ?? credentialsDir(), "acquire"), directory];
+        for (const level of levels) {
+            assertNoSymlinkComponents(level);
+            mkdirSync(level, { recursive: true, mode: 0o700 });
+            assertNoSymlinkComponents(level);
+            try {
+                chmodSync(level, 0o700);
+            }
+            catch { /* chmod is unavailable on some filesystems. */ }
+        }
+    }
+    function writeRecord(value) {
+        const record = validateAcquireCheckpoint(value);
+        ensureDirectory();
+        writeSecureFileAtomic(fileForId(record.id), `${JSON.stringify(record, null, 2)}\n`);
+        return record;
+    }
+    return {
+        async get(key) {
+            return readId(acquireCheckpointId(key));
+        },
+        async put(key, continuation, updatedAt = new Date()) {
+            const validKey = validateAcquireCheckpointKey(key);
+            return writeRecord({
+                version: 1,
+                id: acquireCheckpointId(validKey),
+                key: validKey,
+                continuation: validateContinuation(continuation),
+                updatedAt: updatedAt.toISOString(),
+            });
+        },
+        async putRecord(record) {
+            return writeRecord(record);
+        },
+        async list() {
+            let names;
+            try {
+                assertNoSymlinkComponents(directory);
+                names = readdirSync(directory).filter((name) => /^acqcp_[a-f0-9]{64}\.json$/.test(name));
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return [];
+                throw error;
+            }
+            return names
+                .map((name) => readId(name.slice(0, -5)))
+                .filter((record) => record !== null)
+                .sort((a, b) => a.updatedAt.localeCompare(b.updatedAt));
+        },
+    };
+}

package/dist/acquireLinkedIn.d.ts

@@ -25,6 +25,8 @@ export type DiscoverLinkedInOptions = {
     sourceId?: string;
     /** Hard cap on prospects pulled. */
     max?: number;
+    /** Opaque provider continuation cursor. */
+    cursor?: string;
 };
 /**
  * Discovery branch for `acquireFromApi`: read prospects from a LinkedIn source

package/dist/acquireLinkedIn.js

@@ -41,7 +41,7 @@ export function linkedInProspectToProspect(lp) {
  * provider is injected so this is fully testable against the fake (no key).
  */
 export async function discoverLinkedInProspects(provider, options = {}) {
-    const raw = await provider.fetchProspects({ sourceId: options.sourceId, max: options.max });
+    const raw = await provider.fetchProspects({ sourceId: options.sourceId, max: options.max, cursor: options.cursor });
     return raw.map(linkedInProspectToProspect);
 }
 /**