fullstackgtm 0.49.0 → 0.50.0

package/dist/cli/plans.js

@@ -14,6 +14,7 @@ import { createFilePlanStore } from "../planStore.js";
 import { ENRICH_CONFIG_FILE_NAME, loadEnrichConfig } from "../enrich.js";
 import { loadMeter, recordConsumption, remaining } from "../acquireMeter.js";
 import { progressReporter, reportCounts } from "../runReport.js";
+import { claimHostedPlanApply, reconcileHostedPatchPlan, releaseHostedPlanApply, reportHostedPlanLifecycle, uploadHostedPatchPlan } from "../hostedPatchPlan.js";
 import { APPLY_STAGES, composeListeners, createProgressEmitter } from "../progress.js";
 import { connectorFor, isOptionValue, numericOption, option, repeatedOption, selectedRules } from "./shared.js";
 import { colorEnabled, createProgressRenderer, paint, planStatusWord, stylizePlanMarkdown, table, truncateToWidth } from "./ui.js";
@@ -132,9 +133,20 @@ export async function apply(args) {
     let valueOverrides;
     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>\`.`);
         }
@@ -211,11 +223,38 @@ export async function apply(args) {
     // transmits nothing; a CRM provider writes records. Same governed apply path.
     const connector = channel ? createChannelConnector(channel) : await connectorFor(provider, args);
     let applyClaimId;
+    let hostedApplyClaimId;
     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, claimed.stored.valueOverrides, 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, "Approval integrity verification failed after the claim and before provider I/O.");
             throw new Error(`Refusing to apply plan ${planId}: approval changed while acquiring the apply claim.`);
         }
@@ -248,7 +287,12 @@ export async function apply(args) {
         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.
     if (createOps.length > 0) {
@@ -353,7 +397,14 @@ export async function plansCommand(args) {
     const [subcommand, ...rest] = args;
     if (subcommand === "list" || subcommand === undefined) {
         const status = option(rest, "--status");
-        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(plans.map((stored) => ({
                 id: stored.plan.id,
@@ -407,9 +458,17 @@ export async function plansCommand(args) {
         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;
@@ -418,6 +477,11 @@ export async function plansCommand(args) {
         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) {
@@ -470,6 +534,10 @@ export async function plansCommand(args) {
             ...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>\`.`);
         return;
     }
@@ -477,7 +545,11 @@ export async function plansCommand(args) {
         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;
     }
@@ -503,5 +575,27 @@ export async function plansCommand(args) {
             `No writes were replayed. Re-audit provider state, review the plan, then approve operations again before any apply.`);
         return;
     }
-    throw unknownSubcommandError("plans", subcommand, ["list", "show", "approve", "reject", "recover"]);
+    if (subcommand === "sync") {
+        const plans = await store.list();
+        let updated = 0;
+        const warnings = [];
+        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/dist/cli/shared.d.ts

@@ -23,7 +23,9 @@ export declare function saveRequested(args: string[]): boolean;
 export declare function confirmRequested(args: string[], ...legacyAliases: string[]): boolean;
 export declare function numericOption(args: string[], name: string): number | undefined;
 export declare function connectorFor(provider: string, args: string[], progress?: ProgressEmitter): Promise<GtmConnector>;
-export declare function readSnapshot(args: string[], progress?: ProgressEmitter): Promise<CanonicalGtmSnapshot>;
+export declare function readSnapshot(args: string[], progress?: ProgressEmitter, options?: {
+    persistProgress?: boolean;
+}): Promise<CanonicalGtmSnapshot>;
 /**
  * Validate that an --input file actually has the canonical snapshot shape
  * (the JSON `snapshot --out` writes) instead of blindly casting — a plan or

package/dist/cli/shared.js

@@ -131,7 +131,7 @@ export async function connectorFor(provider, args, progress) {
     throw new Error(`Unknown provider: ${provider}.${providerSuggestion ? ` Did you mean ${providerSuggestion}?` : ""} ` +
         "Supported providers: hubspot, salesforce, stripe");
 }
-export async function readSnapshot(args, progress) {
+export async function readSnapshot(args, progress, options = {}) {
     const provider = option(args, "--provider");
     if (provider) {
         // A verb driving its own progress board (e.g. `backfill stripe`) passes
@@ -153,7 +153,7 @@ export async function readSnapshot(args, progress) {
             return await connector.fetchSnapshot();
         }
         finally {
-            renderer.done();
+            renderer.done({ persist: options.persistProgress });
         }
     }
     if (args.includes("--demo")) {

package/dist/cli/ui.d.ts

@@ -88,14 +88,17 @@ export declare function startElapsedStatus(label: (elapsed: string) => string, s
 };
 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;
 };
 /**
  * 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 declare function createChecklist(items: Array<{
     id: string;
@@ -107,8 +110,10 @@ 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;
 };
 /**

package/dist/cli/ui.js

@@ -241,7 +241,8 @@ const NOOP_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, stream = process.stderr, env = process.env) {
     if (!animationEnabled(stream, env) || items.length === 0)
@@ -280,14 +281,22 @@ export function createChecklist(items, stream = process.stderr, env = process.en
             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`);
@@ -344,8 +353,10 @@ export function createProgressRenderer(stages, stream = process.stderr, env = pr
             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/dist/connectors/linkedin.d.ts

@@ -38,6 +38,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;

package/dist/connectors/linkedin.js

@@ -85,6 +85,11 @@ export function createHeyReachProvider(options) {
             const max = opts.max ?? Number.POSITIVE_INFINITY;
             const out = [];
             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/dist/connectors/prospectSources.d.ts

@@ -46,6 +46,8 @@ export declare function fetchExploriumProspects(opts: {
     apiKey: string;
     filters: ExploriumFilters;
     size?: number;
+    /** One-based result page. */
+    page?: number;
     apiBaseUrl?: string;
     fetchImpl?: FetchImpl;
 }): Promise<Prospect[]>;
@@ -53,9 +55,30 @@ export declare 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[]>;
+/** 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 declare 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>;
 export declare const EXPLORIUM_BUSINESS_COUNT_CAP = 60000;
 export type BusinessCountProbe = {
     /** matching companies (the account universe); == cap when saturated. */

package/dist/connectors/prospectSources.js

@@ -24,7 +24,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);
@@ -48,14 +48,24 @@ export async function fetchExploriumProspects(opts) {
 // (no separate connection needed). Returns profiles; pair with
 // pipe0ResolveWorkEmails to get real emails.
 export async function fetchPipe0CrustdataProspects(opts) {
+    return (await fetchPipe0CrustdataProspectPage(opts)).prospects;
+}
+/**
+ * Fetch one page and expose its continuation cursor. The array-returning
+ * `fetchPipe0CrustdataProspects` remains available for existing consumers.
+ */
+export async function fetchPipe0CrustdataProspectPage(opts) {
     const fetchImpl = opts.fetchImpl ?? fetch;
     const base = (opts.apiBaseUrl ?? "https://api.pipe0.com").replace(/\/$/, "");
     const limit = Math.min(opts.limit ?? 25, 100);
+    const config = { 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) {
@@ -68,7 +78,7 @@ export async function fetchPipe0CrustdataProspects(opts) {
     if (upstreamErrors.length > 0 && !(body.results ?? []).length) {
         throw new Error(`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 {
@@ -81,6 +91,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) {
     const v = field?.value;

package/dist/enrich.d.ts

@@ -86,6 +86,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;
@@ -286,7 +288,46 @@ export declare function selectStaleWork(config: EnrichConfig, runs: EnrichRun[],
     now?: () => Date;
     staleDaysOverride?: number;
 }): EnrichWorkItem[];
-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;
     runLabel: string;
@@ -298,6 +339,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. */

package/dist/hostedAcquireCheckpoint.d.ts

@@ -0,0 +1,43 @@
+import type { AcquireDiscoveryCheckpoint } from "./enrich.ts";
+export type HostedAcquireCheckpoint = {
+    checkpoint: AcquireDiscoveryCheckpoint;
+    /** Opaque server revision used only for compare-and-swap. */
+    version: number;
+    updatedAt: number;
+};
+export type HostedCheckpointReadResult = {
+    status: "unpaired";
+} | {
+    status: "missing";
+} | {
+    status: "found";
+    record: HostedAcquireCheckpoint;
+} | {
+    status: "unavailable";
+    reason: string;
+};
+export type HostedCheckpointWriteResult = {
+    status: "unpaired";
+} | {
+    status: "saved";
+    record: HostedAcquireCheckpoint;
+} | {
+    status: "conflict";
+    current: HostedAcquireCheckpoint | null;
+} | {
+    status: "unavailable";
+    reason: string;
+};
+type Options = {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+};
+/** Read a query/list checkpoint. Inert unless this profile is paired. */
+export declare function readHostedAcquireCheckpoint(key: string, options?: Options): Promise<HostedCheckpointReadResult>;
+/**
+ * Mirror a local checkpoint using compare-and-swap. Pass null only when the
+ * caller observed no hosted record (sent as version zero); pass the exact
+ * positive version returned by read for an update.
+ */
+export declare function writeHostedAcquireCheckpoint(key: string, checkpoint: AcquireDiscoveryCheckpoint, expectedVersion: number | null, options?: Options): Promise<HostedCheckpointWriteResult>;
+export {};

package/dist/hostedAcquireCheckpoint.js

@@ -0,0 +1,129 @@
+/**
+ * Authenticated acquisition-checkpoint transport for paired CLI installs.
+ *
+ * The local checkpoint remains authoritative for running a job. This module
+ * only mirrors/query-scoped continuation state to the paired hosted app so a
+ * different authenticated worker can resume it. Writes use compare-and-swap:
+ * a stale client receives a conflict and must explicitly reconcile instead of
+ * silently moving a provider cursor backwards or overwriting another worker.
+ */
+import { getCredential } from "./credentials.js";
+const ENDPOINT = "/api/cli/acquisition-checkpoint";
+const DEFAULT_TIMEOUT_MS = 4000;
+const CHECKPOINT_KEY = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
+function validKey(key) {
+    if (!CHECKPOINT_KEY.test(key)) {
+        throw new Error("Acquisition checkpoint key must be 1-256 URL-safe characters.");
+    }
+    return key;
+}
+function broker() {
+    const credential = getCredential("broker");
+    if (!credential?.baseUrl || !credential.accessToken)
+        return null;
+    let url;
+    try {
+        url = new URL(credential.baseUrl);
+    }
+    catch {
+        return null;
+    }
+    const local = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && local))
+        return null;
+    return { baseUrl: url.href.replace(/\/+$/, ""), accessToken: credential.accessToken };
+}
+function isCheckpoint(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const item = value;
+    return (typeof item.queryFingerprint === "string" &&
+        item.queryFingerprint.length > 0 &&
+        typeof item.exhausted === "boolean" &&
+        (item.cursor === undefined || item.cursor === null || typeof item.cursor === "string") &&
+        (item.offset === undefined || item.offset === null ||
+            (typeof item.offset === "number" && Number.isSafeInteger(item.offset) && item.offset >= 0)));
+}
+function parseRecord(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const body = value;
+    if (!isCheckpoint(body.checkpoint) || !Number.isSafeInteger(body.version) || body.version < 1)
+        return null;
+    if (!Number.isSafeInteger(body.updatedAt) || body.updatedAt < 0)
+        return null;
+    return {
+        checkpoint: body.checkpoint,
+        version: body.version,
+        updatedAt: body.updatedAt,
+    };
+}
+function reasonFor(status) {
+    if (status === 401 || status === 403)
+        return "hosted authentication was rejected; pair the CLI again";
+    return `hosted checkpoint request failed (HTTP ${status})`;
+}
+/** Read a query/list checkpoint. Inert unless this profile is paired. */
+export async function readHostedAcquireCheckpoint(key, options = {}) {
+    validKey(key);
+    const paired = broker();
+    if (!paired)
+        return { status: "unpaired" };
+    try {
+        const response = await (options.fetchImpl ?? fetch)(`${paired.baseUrl}${ENDPOINT}?key=${encodeURIComponent(key)}`, {
+            headers: { Authorization: `Bearer ${paired.accessToken}`, Accept: "application/json" },
+            signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        });
+        if (response.status === 404)
+            return { status: "missing" };
+        if (!response.ok)
+            return { status: "unavailable", reason: reasonFor(response.status) };
+        const record = parseRecord(await response.json());
+        return record
+            ? { status: "found", record }
+            : { status: "unavailable", reason: "hosted checkpoint response was invalid" };
+    }
+    catch {
+        return { status: "unavailable", reason: "hosted checkpoint request was unavailable" };
+    }
+}
+/**
+ * Mirror a local checkpoint using compare-and-swap. Pass null only when the
+ * caller observed no hosted record (sent as version zero); pass the exact
+ * positive version returned by read for an update.
+ */
+export async function writeHostedAcquireCheckpoint(key, checkpoint, expectedVersion, options = {}) {
+    validKey(key);
+    if (!isCheckpoint(checkpoint))
+        throw new Error("Refusing to sync an invalid acquisition checkpoint.");
+    if (expectedVersion !== null && (!Number.isSafeInteger(expectedVersion) || expectedVersion < 1)) {
+        throw new Error("expectedVersion must be null or a positive integer.");
+    }
+    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({ key, checkpoint, expectedVersion: expectedVersion ?? 0 }),
+            signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        });
+        if (response.status === 409) {
+            const body = await response.json().catch(() => null);
+            const current = body && typeof body === "object"
+                ? parseRecord(body.current)
+                : null;
+            return { status: "conflict", current };
+        }
+        if (!response.ok)
+            return { status: "unavailable", reason: reasonFor(response.status) };
+        const record = parseRecord(await response.json());
+        return record
+            ? { status: "saved", record }
+            : { status: "unavailable", reason: "hosted checkpoint response was invalid" };
+    }
+    catch {
+        return { status: "unavailable", reason: "hosted checkpoint request was unavailable" };
+    }
+}