fullstackgtm 0.45.0 → 0.47.0

package/dist/market.d.ts

@@ -1,3 +1,4 @@
+import { type ProgressEmitter } from "./progress.ts";
 import type { GtmEvidence } from "./types.ts";
 /**
  * The Market Map: a live model of the competitive category a company sells
@@ -163,12 +164,24 @@ export type FetchPage = (url: string) => Promise<{
 }>;
 export declare function assertPublicUrl(rawUrl: string): Promise<URL>;
 export type CaptureOptions = {
-    /** Directory for captures; defaults to <marketHome>/captures. */
+    /** Directory for captures; defaults to <marketHome>/captures. Ignored when `store` is given. */
     dir?: string;
     runLabel?: string;
     /** Injectable for tests; defaults to global fetch. */
     fetchPage?: FetchPage;
     now?: () => Date;
+    /**
+     * Storage seam (see MarketStore below). Defaults to the profile-home file
+     * store; the hosted app passes a Convex-backed store. Same engine, same
+     * evidence chain, different persistence.
+     */
+    store?: MarketStore;
+    /**
+     * Progress emission over MARKET_CAPTURE_STAGES ("sources" → "capture" →
+     * "persist" here; "classify" belongs to classifyMarket). Presentation-only:
+     * a throwing listener never fails the capture.
+     */
+    progress?: ProgressEmitter;
 };
 export type CaptureResult = {
     entries: CaptureEntry[];
@@ -197,6 +210,31 @@ export declare function loadCaptureTexts(category: string, directory?: string):
     entries: CaptureEntry[];
     textByHash: Map<string, string>;
 };
+export interface MarketStore {
+    /** Operator-facing location of the capture manifest (file path or logical label). */
+    captureLocation(): string;
+    /** Persist one page's extracted text under its content hash (idempotent). */
+    saveCaptureText(captureHash: string, text: string): Promise<void>;
+    /** Append one capture pass's manifest entries (append-only; never rewrites history). */
+    appendCaptureEntries(entries: CaptureEntry[]): Promise<void>;
+    /** Full manifest + resolvable texts — the evidence-verification input. */
+    loadCaptureTexts(): Promise<{
+        entries: CaptureEntry[];
+        textByHash: Map<string, string>;
+    }>;
+    /** Append-only observation runs (the same ObservationStore contract as before). */
+    observations: ObservationStore;
+}
+/** The CLI's store: captures + observations under the profile market home. */
+export declare function createFileMarketStore(category: string, options?: {
+    capturesDir?: string;
+    observationsDir?: string;
+}): MarketStore;
+/**
+ * In-memory store: seam tests, and throwaway grounding captures (e.g. the
+ * taxonomy proposer's bootstrap pass) that should never persist anywhere.
+ */
+export declare function createMemoryMarketStore(category: string): MarketStore;
 /**
  * Whitespace-only normalization for span matching, plus one extraction
  * artifact: the HTML-to-text step can emit a line break before punctuation

package/dist/market.js

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from
 import { isIP } from "node:net";
 import { join } from "node:path";
 import { credentialsDir } from "./credentials.js";
+import { MARKET_CAPTURE_STAGES, nullProgressEmitter } from "./progress.js";
 const INTENSITY_RANK = {
     loud: 3,
     quiet: 2,
@@ -283,58 +284,57 @@ const defaultFetchPage = async (url) => {
     throw new Error(`market capture: too many redirects (>${MAX_REDIRECTS}) for ${url}`);
 };
 export async function captureMarket(config, options = {}) {
-    const dir = options.dir ?? join(marketHome(config.category), "captures");
+    const store = options.store ?? createFileMarketStore(config.category, { capturesDir: options.dir });
+    const progress = options.progress ?? nullProgressEmitter();
     const runLabel = options.runLabel ?? "run-1";
     const fetchPage = options.fetchPage ?? defaultFetchPage;
     const fetchedAt = (options.now ?? (() => new Date()))().toISOString();
-    mkdirSync(dir, { recursive: true });
-    const manifestPath = join(dir, "manifest.json");
-    const manifest = existsSync(manifestPath)
-        ? JSON.parse(readFileSync(manifestPath, "utf8"))
-        : [];
-    const entries = [];
+    progress.stage(MARKET_CAPTURE_STAGES[0], 0, MARKET_CAPTURE_STAGES.length);
+    const targets = [];
     for (const vendor of config.vendors) {
-        const targets = [
-            { kind: "home", url: vendor.urls.home },
-        ];
+        targets.push({ vendorId: vendor.id, kind: "home", url: vendor.urls.home });
         if (vendor.urls.pricing)
-            targets.push({ kind: "pricing", url: vendor.urls.pricing });
+            targets.push({ vendorId: vendor.id, kind: "pricing", url: vendor.urls.pricing });
         for (const url of vendor.urls.product)
-            targets.push({ kind: "product", url });
-        for (const target of targets) {
-            let status = null;
-            let text = "";
-            try {
-                const page = await fetchPage(target.url);
-                status = page.status;
-                if (page.status === 200)
-                    text = extractReadableText(page.body);
-            }
-            catch {
-                status = null;
-            }
-            let captureHash = null;
-            if (text) {
-                captureHash = createHash("sha256").update(text).digest("hex");
-                // Content-addressed: an unchanged page dedupes to the same file.
-                writeFileSync(join(dir, `${captureHash}.txt`), text);
-            }
-            const entry = {
-                runLabel,
-                vendorId: vendor.id,
-                kind: target.kind,
-                url: target.url,
-                fetchedAt,
-                httpStatus: status,
-                captureHash,
-                textChars: text.length,
-            };
-            manifest.push(entry);
-            entries.push(entry);
+            targets.push({ vendorId: vendor.id, kind: "product", url });
+    }
+    progress.note(`${config.vendors.length} vendor(s), ${targets.length} page(s)`);
+    progress.stage(MARKET_CAPTURE_STAGES[1], 1, MARKET_CAPTURE_STAGES.length);
+    const entries = [];
+    for (const target of targets) {
+        let status = null;
+        let text = "";
+        try {
+            const page = await fetchPage(target.url);
+            status = page.status;
+            if (page.status === 200)
+                text = extractReadableText(page.body);
+        }
+        catch {
+            status = null;
         }
+        let captureHash = null;
+        if (text) {
+            captureHash = createHash("sha256").update(text).digest("hex");
+            // Content-addressed: an unchanged page dedupes to the same key.
+            await store.saveCaptureText(captureHash, text);
+        }
+        entries.push({
+            runLabel,
+            vendorId: target.vendorId,
+            kind: target.kind,
+            url: target.url,
+            fetchedAt,
+            httpStatus: status,
+            captureHash,
+            textChars: text.length,
+        });
+        progress.items(entries.length, targets.length);
     }
-    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
-    return { entries, manifestPath };
+    progress.stage(MARKET_CAPTURE_STAGES[3], 3, MARKET_CAPTURE_STAGES.length);
+    await store.appendCaptureEntries(entries);
+    progress.flush();
+    return { entries, manifestPath: store.captureLocation() };
 }
 export function createFileObservationStore(category, directory) {
     const dir = directory ?? join(marketHome(category), "observations");
@@ -459,6 +459,78 @@ export function loadCaptureTexts(category, directory) {
     }
     return { entries, textByHash };
 }
+/** The CLI's store: captures + observations under the profile market home. */
+export function createFileMarketStore(category, options = {}) {
+    const dir = options.capturesDir ?? join(marketHome(category), "captures");
+    const manifestPath = join(dir, "manifest.json");
+    return {
+        captureLocation: () => manifestPath,
+        async saveCaptureText(captureHash, text) {
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(join(dir, `${captureHash}.txt`), text);
+        },
+        async appendCaptureEntries(entries) {
+            mkdirSync(dir, { recursive: true });
+            const manifest = existsSync(manifestPath)
+                ? JSON.parse(readFileSync(manifestPath, "utf8"))
+                : [];
+            manifest.push(...entries);
+            writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+        },
+        async loadCaptureTexts() {
+            return loadCaptureTexts(category, dir);
+        },
+        observations: createFileObservationStore(category, options.observationsDir),
+    };
+}
+/**
+ * In-memory store: seam tests, and throwaway grounding captures (e.g. the
+ * taxonomy proposer's bootstrap pass) that should never persist anywhere.
+ */
+export function createMemoryMarketStore(category) {
+    const entries = [];
+    const textByHash = new Map();
+    const sets = new Map();
+    const sorted = () => [...sets.values()].sort((a, b) => a.runAt.localeCompare(b.runAt));
+    return {
+        captureLocation: () => `memory://${category}/captures`,
+        async saveCaptureText(captureHash, text) {
+            textByHash.set(captureHash, text);
+        },
+        async appendCaptureEntries(newEntries) {
+            entries.push(...newEntries);
+        },
+        async loadCaptureTexts() {
+            return { entries: [...entries], textByHash: new Map(textByHash) };
+        },
+        observations: {
+            async append(set) {
+                if (set.category !== category) {
+                    throw new Error(`Observation set category "${set.category}" does not match store "${category}"`);
+                }
+                if (sets.has(set.runLabel)) {
+                    throw new Error(`Run "${set.runLabel}" already exists — observations are append-only; use a new run label`);
+                }
+                sets.set(set.runLabel, set);
+                return set;
+            },
+            async get(runLabel) {
+                return sets.get(runLabel) ?? null;
+            },
+            async list() {
+                return sorted().map((set) => ({
+                    runLabel: set.runLabel,
+                    runAt: set.runAt,
+                    observations: set.observations.length,
+                }));
+            },
+            async latest() {
+                const all = sorted();
+                return all.length ? all[all.length - 1] : null;
+            },
+        },
+    };
+}
 /**
  * Whitespace-only normalization for span matching, plus one extraction
  * artifact: the HTML-to-text step can emit a line break before punctuation

package/dist/marketClassify.d.ts

@@ -1,5 +1,6 @@
 import { type LlmCallOptions } from "./llm.ts";
-import { type CaptureEntry, type MarketClaim, type MarketConfig, type ObservationSet } from "./market.ts";
+import { type CaptureEntry, type MarketClaim, type MarketConfig, type MarketStore, type ObservationSet } from "./market.ts";
+import { type ProgressEmitter } from "./progress.ts";
 export type ClassifyMarketOptions = {
     llm: LlmCallOptions;
     /** Observation run label to produce; must be new (the store is append-only). */
@@ -10,9 +11,16 @@ export type ClassifyMarketOptions = {
     vendors?: string[];
     /** Captures directory override (tests); defaults to the profile market home. */
     capturesDir?: string;
+    /** Storage seam: when given, captures are read through it instead of the file layout. */
+    store?: MarketStore;
     now?: () => Date;
     /** Per-vendor progress (presentation only — a throwing callback never fails the run). */
     onVendor?: (done: number, total: number, vendorId: string) => void;
+    /**
+     * Progress emission over MARKET_CAPTURE_STAGES (the "classify" stage, items
+     * per vendor). Presentation-only: a throwing listener never fails the run.
+     */
+    progress?: ProgressEmitter;
 };
 export type ClassifyMarketResult = {
     set: ObservationSet;

package/dist/marketClassify.js

@@ -1,5 +1,6 @@
 import { DEFAULT_MODELS, forcedToolCall } from "./llm.js";
 import { loadCaptureTexts, observationId, verifyEvidenceSpans, } from "./market.js";
+import { MARKET_CAPTURE_STAGES, nullProgressEmitter } from "./progress.js";
 /**
  * LLM intensity classification for the market map — the same
  * semi-deterministic posture as call extraction, with one upgrade calls
@@ -78,7 +79,10 @@ function claimsBlock(claims) {
 }
 export async function classifyMarket(config, options) {
     const model = options.llm.model ?? DEFAULT_MODELS[options.llm.provider];
-    const { entries, textByHash } = loadCaptureTexts(config.category, options.capturesDir);
+    const progress = options.progress ?? nullProgressEmitter();
+    const { entries, textByHash } = options.store
+        ? await options.store.loadCaptureTexts()
+        : loadCaptureTexts(config.category, options.capturesDir);
     if (entries.length === 0) {
         throw new Error(`No captures for ${config.category} — run \`market capture\` first`);
     }
@@ -92,6 +96,7 @@ export async function classifyMarket(config, options) {
     const claimIds = config.claims.map((claim) => claim.id);
     const observations = [];
     const retriedVendorIds = [];
+    progress.stage(MARKET_CAPTURE_STAGES[2], 2, MARKET_CAPTURE_STAGES.length);
     for (const [vendorIndex, vendorId] of vendorIds.entries()) {
         try {
             options.onVendor?.(vendorIndex, vendorIds.length, vendorId);
@@ -99,6 +104,7 @@ export async function classifyMarket(config, options) {
         catch {
             // progress is presentation-only
         }
+        progress.note(vendorId);
         const vendor = config.vendors.find((candidate) => candidate.id === vendorId);
         if (!vendor)
             throw new Error(`Unknown vendor "${vendorId}"`);
@@ -120,6 +126,7 @@ export async function classifyMarket(config, options) {
                     evidence: [],
                 });
             }
+            progress.items(vendorIndex + 1, vendorIds.length);
             continue;
         }
         const prompt = (feedback) => `${CLASSIFY_INSTRUCTIONS}\n\nSurface rule for this category:\n${config.surfaceRule ?? "(default rule above)"}\n\nClaims to classify (all of them):\n${claimsBlock(config.claims)}\n${feedback}\nVendor: ${vendor.name}\nCaptured pages:\n${dossier}`;
@@ -165,7 +172,9 @@ export async function classifyMarket(config, options) {
         }
         for (const reading of outcome.readings)
             observations.push(toObservation(reading, vendorId));
+        progress.items(vendorIndex + 1, vendorIds.length);
     }
+    progress.flush();
     return {
         set: {
             id: `set_${config.category}_${options.runLabel}`,

package/dist/marketTaxonomy.d.ts

@@ -1,5 +1,5 @@
 import { type LlmCallOptions } from "./llm.ts";
-import { type FetchPage, type MarketConfig } from "./market.ts";
+import { type FetchPage, type MarketConfig, type MarketStore } from "./market.ts";
 /**
  * Cold-start taxonomy bootstrap. `market init` writes a stub for a human
  * analyst to fill in; the self-serve hosted map has no analyst in the loop, so
@@ -30,6 +30,11 @@ export type SuggestTaxonomyOptions = {
     /** Test injectables. */
     fetchPage?: FetchPage;
     capturesDir?: string;
+    /**
+     * Storage seam for the bootstrap captures; defaults to the file layout.
+     * Pass createMemoryMarketStore for throwaway grounding (hosted flow).
+     */
+    store?: MarketStore;
     now?: () => Date;
 };
 export type SuggestTaxonomyResult = {

package/dist/marketTaxonomy.js

@@ -147,8 +147,10 @@ export async function suggestMarketConfig(options) {
     const anchorId = anchorSeed ? vendors[options.vendors.indexOf(anchorSeed)]?.id : undefined;
     // Capture the seed homepages so the proposer only sees text we actually
     // fetched (the SSRF guard in captureMarket applies to these user-supplied URLs).
-    await captureMarket({ category, vendors, claims: [] }, { dir: options.capturesDir, runLabel: "bootstrap", fetchPage: options.fetchPage, now: options.now });
-    const capture = loadCaptureTexts(category, options.capturesDir);
+    await captureMarket({ category, vendors, claims: [] }, { dir: options.capturesDir, store: options.store, runLabel: "bootstrap", fetchPage: options.fetchPage, now: options.now });
+    const capture = options.store
+        ? await options.store.loadCaptureTexts()
+        : loadCaptureTexts(category, options.capturesDir);
     const { dossier, unreadable } = buildDossier(vendors, capture, perVendorChars);
     if (!dossier.trim()) {
         throw new Error(`market init --auto: none of the ${vendors.length} seed pages returned readable text — check the URLs are public homepages.`);

package/dist/mcp-bin.js

@@ -1,4 +1,33 @@
 #!/usr/bin/env node
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+    console.log(`Usage: fullstackgtm-mcp [--help] [--version]
+
+Starts the fullstackgtm MCP stdio server.
+
+The MCP server requires optional peer dependencies:
+  @modelcontextprotocol/sdk
+  zod
+
+Zero-install with peers:
+  npx -y -p fullstackgtm -p @modelcontextprotocol/sdk -p zod fullstackgtm-mcp`);
+    process.exit(0);
+}
+if (args.includes("--version") || args.includes("-v")) {
+    console.log(await readPackageVersion());
+    process.exit(0);
+}
+async function readPackageVersion() {
+    try {
+        const { readFileSync } = await import("node:fs");
+        const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
 // The MCP server needs the optional peer dependencies. Import dynamically so
 // a missing peer produces install guidance instead of a module-load stack
 // trace — `npx fullstackgtm-mcp` alone never installs optional peers.

package/dist/mcp.js

@@ -52,6 +52,8 @@ import { createStripeConnector } from "./connectors/stripe.js";
 import { getCredential, resolveHubspotAccessToken, resolveSalesforceConnection, } from "./credentials.js";
 import { generateDemoSnapshot } from "./demo.js";
 import { formatPatchPlanRun, patchPlanToMarkdown } from "./format.js";
+import { verifyApprovalDigests } from "./integrity.js";
+import { createFilePlanStore } from "./planStore.js";
 import { builtinAuditRules } from "./rules.js";
 import { sampleSnapshot } from "./sampleData.js";
 import { normalizeTranscript, parseCall } from "./calls.js";
@@ -270,7 +272,11 @@ const toolDefinitions = [
             title: "Apply Approved Patch Operations",
             description: "Apply explicitly approved operations from a patch plan through a provider " +
                 "connector. Operations not listed in approvedOperationIds are never written, " +
-                "and requires_human_* placeholders need a value override.",
+                "and requires_human_* placeholders need a value override. When the plan is in " +
+                "the local plan store (saved via `audit --save`), approvals are verified against " +
+                "the store's HMAC approval digests — ids not approved with `plans approve` are " +
+                "refused — and the run is recorded onto the stored plan so `plans show` and " +
+                "`audit-log export` include it.",
             inputSchema: {
                 provider: z.enum(["hubspot", "salesforce"]),
                 planPath: z.string(),
@@ -280,12 +286,107 @@ const toolDefinitions = [
             },
         },
         handler: async ({ provider, planPath, approvedOperationIds, valueOverrides, output }) => {
-            const plan = JSON.parse(readFileSync(resolve(process.cwd(), planPath), "utf8"));
+            // The file may be a raw PatchPlan (audit --out) or a StoredPlan envelope
+            // (a file straight out of the plan-store directory).
+            const parsed = JSON.parse(readFileSync(resolve(process.cwd(), planPath), "utf8"));
+            const filePlan = isStoredPlanFile(parsed) ? parsed.plan : parsed;
+            if (!filePlan || !Array.isArray(filePlan.operations)) {
+                throw new Error(`${planPath} is not a patch plan (expected { id, operations: [...] }).`);
+            }
+            // Governance parity with CLI apply: when this plan id exists in the local
+            // plan store, the STORE is the source of truth — the approved-id set must
+            // come from `plans approve` (which HMAC-signed each approved op), the
+            // signatures are re-verified here, and the run is recorded back onto the
+            // plan so audit-log export sees MCP applies exactly like CLI applies.
+            const store = createFilePlanStore();
+            const stored = typeof filePlan.id === "string" && /^[\w.-]+$/.test(filePlan.id)
+                ? await store.get(filePlan.id)
+                : null;
+            let plan;
+            let effectiveOverrides;
+            if (stored) {
+                if (stored.status !== "approved") {
+                    throw new Error(`Plan ${filePlan.id} is ${stored.status}; approve operations first with ` +
+                        `\`fullstackgtm plans approve ${filePlan.id} --operations <ids|all>\`.`);
+                }
+                // Downgrade guard (same as CLI apply): an approved plan with no
+                // signatures either predates 0.26 or had approvalDigests stripped to
+                // skip the integrity check. Refuse rather than trust the file.
+                if (stored.approvedOperationIds.length > 0 && !stored.approvalDigests) {
+                    throw new Error(`Refusing to apply plan ${filePlan.id}: it was approved without integrity signatures ` +
+                        "(approved before 0.26.0, or its signatures were removed). Re-approve it with " +
+                        `\`fullstackgtm plans approve ${filePlan.id} --operations <ids|all>\`.`);
+                }
+                // Never widen: every id the tool wants applied must already be
+                // store-approved. (A subset is fine — narrowing never writes more.)
+                const storeApproved = new Set(stored.approvedOperationIds);
+                const unapproved = approvedOperationIds.filter((id) => !storeApproved.has(id));
+                if (unapproved.length > 0) {
+                    throw new Error(`Refusing to apply plan ${filePlan.id}: operation(s) ${unapproved.join(", ")} were never ` +
+                        "approved in the plan store. Approve them first with " +
+                        `\`fullstackgtm plans approve ${filePlan.id} --operations <ids>\`.`);
+                }
+                // Integrity gate: verify against the EFFECTIVE overrides (stored ∪ tool
+                // args), so a tool-supplied value that changes what the human approved
+                // is treated as tamper, not a live override — what gets written must
+                // equal what was signed.
+                effectiveOverrides = { ...stored.valueOverrides, ...(valueOverrides ?? {}) };
+                const verification = verifyApprovalDigests(stored.plan.operations, stored.approvedOperationIds, effectiveOverrides, stored.approvalDigests);
+                if (!verification.ok) {
+                    const detail = verification.reason === "no_key"
+                        ? "the plan-signing key is missing (was this plan approved on another machine?). Re-approve it here with `fullstackgtm plans approve`."
+                        : `these operations differ from what was approved: ${verification.tampered.join(", ")}. ` +
+                            "If you want a different value, set it at approval (`plans approve --value <op>=<v>`) and re-approve; " +
+                            "otherwise the plan was edited after approval — review and re-approve.";
+                    throw new Error(`Refusing to apply plan ${filePlan.id}: ${detail}`);
+                }
+                plan = stored.plan; // apply what was signed, not what the file says now
+            }
+            else {
+                // External plan file, not in the store: no digests exist to verify, but
+                // approvals must still reference real operations in the plan content.
+                plan = filePlan;
+                const known = new Set(plan.operations.map((operation) => operation.id));
+                const unknown = approvedOperationIds.filter((id) => !known.has(id));
+                if (unknown.length > 0) {
+                    throw new Error(`Plan ${planPath} has no operation(s) ${unknown.join(", ")} — approvedOperationIds ` +
+                        "must reference operations in the plan.");
+                }
+                effectiveOverrides = valueOverrides ?? {};
+            }
             const run = await applyPatchPlan(await connectorFor(provider), plan, {
                 approvedOperationIds,
-                valueOverrides,
+                valueOverrides: effectiveOverrides,
             });
-            return content(output === "markdown" ? formatPatchPlanRun(run) : run);
+            // Persist the run (same data the CLI records) so runs[] and plan status
+            // update and audit-log export includes MCP applies. External plan files
+            // have no store entry to update — say so instead of silently dropping it.
+            let runRecorded = false;
+            if (stored) {
+                await store.recordRun(plan.id, run);
+                runRecorded = true;
+            }
+            const governance = {
+                planSource: stored ? "store" : "external",
+                approvalDigestsVerified: stored !== null,
+                runRecorded,
+                ...(stored
+                    ? {}
+                    : {
+                        note: "Plan file is not in the local plan store: approvals came from tool arguments " +
+                            "(verified against the plan content only — no approval-digest check) and the run " +
+                            "was not recorded. Use `fullstackgtm audit --save` + `plans approve` for " +
+                            "store-backed governance.",
+                    }),
+            };
+            if (output === "markdown") {
+                return content(`${formatPatchPlanRun(run)}\n\nGovernance: plan source ${governance.planSource}; ` +
+                    (runRecorded
+                        ? "approval digests verified; run recorded on the stored plan (audit-log export includes it)."
+                        : governance.note));
+            }
+            // Backward compatible: the run's own fields stay top-level; governance is additive.
+            return content({ ...run, governance });
         },
     },
     {
@@ -392,6 +493,18 @@ export async function startMcpServer() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
+/**
+ * A plan-store file is a StoredPlan envelope ({ plan, status, runs, ... });
+ * `audit --out` writes a bare PatchPlan. fullstackgtm_apply accepts either.
+ */
+function isStoredPlanFile(value) {
+    if (typeof value !== "object" || value === null || !("plan" in value))
+        return false;
+    const plan = value.plan;
+    return (typeof plan === "object" &&
+        plan !== null &&
+        Array.isArray(plan.operations));
+}
 function loadMarketConfigOrHint(path) {
     try {
         return loadMarketConfig(path);

package/dist/progress.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The shared progress-event vocabulary — ONE set of semantics for every
+ * long-running process, rendered natively by each surface:
+ *
+ *   CLI  → ui.ts (spinner / checklist / apply-ticker; TTY-only styling)
+ *   app  → Convex heartbeat patches → reactive ProgressChip / StageTimeline
+ *   both → optional broker streaming (a paired CLI POSTs heartbeats to the
+ *          hosted app under its clientRunId, so long local runs tick live in
+ *          the org's activity feed)
+ *
+ * Renderer-agnostic by contract: no event assumes persistence (the CLI drops
+ * them after painting) or ANSI (the app can't use it). Listeners are
+ * best-effort — a throwing renderer must never fail the work — and the
+ * throttle policy lives HERE so both surfaces feel identical.
+ *
+ * Standing convention: if a verb loops, it emits. New long-running verbs wire
+ * an emitter at the package layer; surfaces get feedback for free.
+ */
+export type ProgressEvent = {
+    kind: "stage";
+    stage: string;
+    stageIndex: number;
+    stageCount: number;
+} | {
+    kind: "items";
+    done: number;
+    total?: number;
+} | {
+    kind: "note";
+    note: string;
+} | {
+    kind: "opResult";
+    opId: string;
+    status: "applied" | "skipped" | "failed" | "conflict";
+    detail?: string;
+} | {
+    kind: "meter";
+    spent: number;
+    budget: number;
+    unit: string;
+};
+/** Accumulated state — what a heartbeat persists / a chip renders. */
+export type ProgressSnapshot = {
+    stage?: string;
+    stageIndex?: number;
+    stageCount?: number;
+    itemsDone?: number;
+    itemsTotal?: number;
+    note?: string;
+    opsApplied: number;
+    opsSkipped: number;
+    opsFailed: number;
+    updatedAt: number;
+};
+export type ProgressListener = (event: ProgressEvent, snapshot: ProgressSnapshot) => void;
+export type ProgressEmitter = {
+    stage(stage: string, stageIndex: number, stageCount: number): void;
+    items(done: number, total?: number): void;
+    note(note: string): void;
+    opResult(opId: string, status: "applied" | "skipped" | "failed" | "conflict", detail?: string): void;
+    meter(spent: number, budget: number, unit: string): void;
+    /** Current accumulated state (always fresh, ignoring the throttle). */
+    snapshot(): ProgressSnapshot;
+    /** Force-deliver the latest state (call at stage ends / completion). */
+    flush(): void;
+};
+/**
+ * Throttled emitter: `items` heartbeats coalesce to at most one delivery per
+ * throttle window (terminal `done === total` always delivers); `stage`,
+ * `opResult`, `note`, and `meter` are structural and always deliver.
+ */
+export declare function createProgressEmitter(listener: ProgressListener, options?: {
+    throttleMs?: number;
+    now?: () => number;
+}): ProgressEmitter;
+/**
+ * Fan one event stream out to several listeners (e.g. the CLI's local renderer
+ * plus the broker heartbeat streamer). Each listener is isolated: one throwing
+ * never starves the others, matching the emitter's own best-effort contract.
+ */
+export declare function composeListeners(...listeners: Array<ProgressListener | undefined | null>): ProgressListener;
+export declare const CRM_SYNC_STAGES: readonly ["owners", "accounts", "contacts", "deals", "counters", "health"];
+/** A connector snapshot pull — the CRM-sync stages that happen CLI-side. */
+export declare const SNAPSHOT_PULL_STAGES: readonly ["owners", "accounts", "contacts", "deals"];
+/** The Stripe connector's snapshot pull (billing systems have no owners). */
+export declare const STRIPE_SNAPSHOT_STAGES: readonly ["customers", "subscriptions"];
+export declare const CALL_SYNC_STAGES: readonly ["notes", "transcripts", "insights"];
+export declare const BACKFILL_STRIPE_STAGES: readonly ["invoices", "snapshot", "matching", "plan"];
+/** `backfill runs` — replaying local plan runs + health history to the broker. */
+export declare const RUNS_REPLAY_STAGES: readonly ["runs", "health"];
+export declare const APPLY_STAGES: readonly ["preflight", "operations", "results"];
+/** `enrich acquire` — routing sourced candidate rows into a create plan. */
+export declare const ACQUIRE_STAGES: readonly ["candidates"];
+export declare const MARKET_CAPTURE_STAGES: readonly ["sources", "capture", "classify", "persist"];
+/** No-op emitter for callers that don't care (keeps signatures simple). */
+export declare function nullProgressEmitter(): ProgressEmitter;