fullstackgtm 0.49.0 → 0.50.1

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)
@@ -261,8 +262,12 @@ export function createChecklist(items, stream = process.stderr, env = process.en
             const label = entry.state === "pending" ? p.dim(item.label.padEnd(labelWidth)) : item.label.padEnd(labelWidth);
             return `  ${glyph} ${label}${note}`;
         });
-        const up = painted > 0 ? `\u001b[${painted}A` : "";
-        stream.write(`${up}${lines.map((line) => `\u001b[2K${line}`).join("\n")}\n`);
+        // Keep the cursor on the board's last row while it is live. A trailing
+        // newline on every repaint can scroll the old top row into permanent
+        // history when the board sits at the bottom of the terminal, producing
+        // apparent duplicate/errored frames in terminal captures.
+        const up = painted > 1 ? `\u001b[${painted - 1}A` : "";
+        stream.write(`${up}${lines.map((line) => `\u001b[2K${line}`).join("\n")}`);
         painted = lines.length;
     };
     const start = () => {
@@ -280,17 +285,29 @@ 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.
+                // Advance exactly once so subsequent output begins below it.
+                if (painted > 0)
+                    stream.write("\n");
+                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`);
+                // Erase in place without linefeeds, which could themselves scroll.
+                const up = painted > 1 ? `\u001b[${painted - 1}A` : "";
+                const clear = Array.from({ length: painted }, (_, index) => `\u001b[2K${index < painted - 1 ? "\u001b[1B" : ""}`).join("");
+                const restore = painted > 1 ? `\u001b[${painted - 1}A` : "";
+                stream.write(`${up}${clear}${restore}`);
                 painted = 0;
             }
         },
@@ -344,8 +361,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/hubspot.d.ts

@@ -18,6 +18,10 @@ export type HubspotConnectorOptions = {
      * alongside the legacy `onProgress` callback; both are presentation-only.
      */
     progress?: ProgressEmitter;
+    /** Maximum retries for HubSpot 429/5xx responses (default 5). */
+    maxRetries?: number;
+    /** Injectable delay for deterministic retry tests. */
+    sleep?: (milliseconds: number) => Promise<void>;
 };
 /**
  * Reference connector for HubSpot.

package/dist/connectors/hubspot.js

@@ -30,6 +30,8 @@ const PULL_STAGE_BY_TYPE = {
 export function createHubspotConnector(options) {
     const baseUrl = (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
     const fetchImpl = options.fetchImpl ?? fetch;
+    const maxRetries = options.maxRetries ?? 5;
+    const sleep = options.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
     const mappings = options.fieldMappings;
     // create:<Name> dedup within one connector lifetime (one apply run): the
     // search API is eventually consistent, so a just-created company is
@@ -66,28 +68,44 @@ export function createHubspotConnector(options) {
         emitter.items(fetched);
     };
     async function request(path, init = {}) {
-        const token = await options.getAccessToken();
         let response;
-        try {
-            response = await fetchImpl(`${baseUrl}${path}`, {
-                ...init,
-                headers: {
-                    Authorization: `Bearer ${token}`,
-                    "Content-Type": "application/json",
-                    ...(init.headers ?? {}),
-                },
-            });
-        }
-        catch (error) {
-            const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
-            throw new Error(`Cannot reach HubSpot at ${baseUrl}${cause}. Check network access.`);
-        }
-        if (!response.ok) {
+        for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+            const token = await options.getAccessToken();
+            try {
+                response = await fetchImpl(`${baseUrl}${path}`, {
+                    ...init,
+                    headers: {
+                        Authorization: `Bearer ${token}`,
+                        "Content-Type": "application/json",
+                        ...(init.headers ?? {}),
+                    },
+                });
+            }
+            catch (error) {
+                const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+                throw new Error(`Cannot reach HubSpot at ${baseUrl}${cause}. Check network access.`);
+            }
+            const retryable = response.status === 429 || response.status >= 500;
+            if (!retryable || attempt === maxRetries)
+                break;
+            await response.text().catch(() => undefined);
+            const retryAfter = response.headers.get("Retry-After");
+            const seconds = retryAfter === null ? NaN : Number(retryAfter);
+            const dateDelay = retryAfter && !Number.isFinite(seconds) ? Date.parse(retryAfter) - Date.now() : NaN;
+            const delayMs = Math.min(30_000, Math.max(0, Number.isFinite(seconds) ? seconds * 1_000 : Number.isFinite(dateDelay) ? dateDelay : 1_000 * 2 ** attempt));
+            const reason = response.status === 429 ? "rate limited" : `temporarily unavailable (${response.status})`;
+            options.progress?.note(`HubSpot ${reason}; retrying in ${Math.ceil(delayMs / 1_000)}s (${attempt + 1}/${maxRetries})`);
+            await sleep(delayMs);
+        }
+        if (!response || !response.ok) {
             // Status line only — HubSpot 4xx bodies echo submitted property values
             // (contact emails, company domains) and the request payload, and these
             // errors are persisted into scheduled-run records. Never interpolate it.
-            await response.text().catch(() => undefined);
-            throw new Error(`HubSpot API error ${response.status}. Check the token scopes and request.`);
+            await response?.text().catch(() => undefined);
+            if (response?.status === 429) {
+                throw new Error(`HubSpot rate limit (429) persisted after ${maxRetries} retries. Wait for the portal limit to reset, then retry; no CRM writes were made.`);
+            }
+            throw new Error(`HubSpot API error ${response?.status ?? "unknown"}. Check the token scopes and request.`);
         }
         // DELETE and some association writes return 204 with an empty body.
         const text = await response.text();

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

package/dist/hostedPatchPlan.d.ts

@@ -0,0 +1,87 @@
+import type { PlanStore, StoredPlan } from "./planStore.ts";
+import type { PatchOperation, PatchPlan, PatchPlanRun } from "./types.ts";
+type Options = {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+};
+export type HostedPlanState = {
+    patchPlanId: string;
+    externalPlanId: string;
+    documentSha256: string;
+    status: string;
+    approvedOperationIds: string[];
+    valueOverrides: Record<string, unknown>;
+    updatedAt: number;
+    runRecord?: PatchPlanRun;
+    url: string;
+};
+export type HostedPlanResult = {
+    status: "unpaired";
+} | {
+    status: "missing";
+} | {
+    status: "found" | "saved";
+    state: HostedPlanState;
+} | {
+    status: "conflict";
+    reason: string;
+} | {
+    status: "unavailable";
+    reason: string;
+};
+/** Review document intentionally omits evidence/findings and all mutable store security state. */
+export declare function hostedReviewDocument(plan: PatchPlan): {
+    guards?: import("./types.ts").PlanGuard[] | undefined;
+    filter?: {
+        objectType: "account" | "contact" | "deal";
+        where: string[];
+        today?: string;
+    } | undefined;
+    id: string;
+    title: string;
+    createdAt: string;
+    status: string;
+    dryRun: boolean;
+    summary: string;
+    operations: PatchOperation[];
+};
+export declare function hostedPlanDigest(plan: PatchPlan): string;
+export declare function uploadHostedPatchPlan(stored: StoredPlan, options?: Options): Promise<HostedPlanResult>;
+export declare function readHostedPatchPlan(planId: string, options?: Options): Promise<HostedPlanResult>;
+export type HostedReconcileResult = {
+    status: "unchanged" | "unpaired" | "missing";
+} | {
+    status: "updated";
+    stored: StoredPlan;
+    remoteStatus: string;
+} | {
+    status: "conflict" | "unavailable";
+    reason: string;
+};
+/** Pull a peer's newer lifecycle into the local replica without weakening local integrity gates. */
+export declare function reconcileHostedPatchPlan(store: PlanStore, stored: StoredPlan, options?: Options): Promise<HostedReconcileResult>;
+export declare function reportHostedPlanLifecycle(stored: StoredPlan, options?: Options & {
+    claimId?: string;
+}): Promise<HostedPlanResult>;
+export type HostedApplyClaimResult = {
+    status: "unpaired";
+} | {
+    status: "claimed";
+    claimId: string;
+    expiresAt?: number;
+} | {
+    status: "applied";
+} | {
+    status: "conflict" | "unavailable";
+    reason: string;
+};
+/** Coordinate online replicas before provider I/O; provider idempotency remains the offline fallback. */
+export declare function claimHostedPlanApply(stored: StoredPlan, options?: Options): Promise<HostedApplyClaimResult>;
+/** Release a shared CLI claim only when preflight aborts before provider I/O. */
+export declare function releaseHostedPlanApply(stored: StoredPlan, claimId: string, reason: string, options?: Options): Promise<{
+    status: "released" | "unpaired";
+} | {
+    status: "conflict" | "unavailable";
+    reason: string;
+}>;
+export {};