fullstackgtm 0.44.0 → 0.46.0

package/src/mcp.ts

@@ -38,6 +38,8 @@ const { StdioServerTransport } = await importPeer<typeof import("@modelcontextpr
 );
 const { z } = await importPeer<typeof import("zod/v4")>("zod/v4");
 import { auditSnapshot, defaultPolicy } from "./audit.ts";
+import { assertCanonicalSnapshot } from "./cli/shared.ts";
+import { nearest } from "./cli/suggest.ts";
 import { loadConfig, mergePolicy, resolveConfiguredRules } from "./config.ts";
 import { applyPatchPlan } from "./connector.ts";
 import { createHubspotConnector } from "./connectors/hubspot.ts";
@@ -51,6 +53,8 @@ import {
 import { generateDemoSnapshot } from "./demo.ts";
 import type { FieldMappings } from "./mappings.ts";
 import { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
+import { verifyApprovalDigests } from "./integrity.ts";
+import { createFilePlanStore, type StoredPlan } from "./planStore.ts";
 import { builtinAuditRules } from "./rules.ts";
 import { sampleSnapshot } from "./sampleData.ts";
 import { normalizeTranscript, parseCall } from "./calls.ts";
@@ -123,8 +127,10 @@ async function connectorFor(provider: string): Promise<GtmConnector> {
     }
     return createStripeConnector({ getApiKey: () => key });
   }
+  const providerSuggestion = nearest(provider.toLowerCase(), ["hubspot", "salesforce", "stripe"], 3);
   throw new Error(
-    `Unknown provider: ${provider}. Supported providers: hubspot, salesforce, stripe`,
+    `Unknown provider: ${provider}.${providerSuggestion ? ` Did you mean ${providerSuggestion}?` : ""} ` +
+      "Supported providers: hubspot, salesforce, stripe",
   );
 }
 
@@ -138,9 +144,10 @@ async function readSnapshot(
     return connector.fetchSnapshot();
   }
   if (!inputPath) return sampleSnapshot;
-  return JSON.parse(
-    readFileSync(resolve(process.cwd(), inputPath), "utf8"),
-  ) as CanonicalGtmSnapshot;
+  return assertCanonicalSnapshot(
+    JSON.parse(readFileSync(resolve(process.cwd(), inputPath), "utf8")),
+    inputPath,
+  );
 }
 
 function packageVersion() {
@@ -152,15 +159,29 @@ function packageVersion() {
   }
 }
 
-export async function startMcpServer() {
-  const server = new McpServer({
-    name: "fullstackgtm",
-    version: packageVersion(),
-  });
+type ToolDefinition = {
+  name: string;
+  // Whether the tool can write to a CRM. Everything else reads, or writes
+  // only local workspace state (market_observe appends to the local
+  // observation store).
+  writesCrm: boolean;
+  config: { title: string; description: string; inputSchema?: Record<string, unknown> };
+  // Args are validated by the SDK against config.inputSchema before the
+  // handler runs; the loose typing here is what lets one table drive a
+  // registration loop instead of per-call generics.
+  handler: (args: any) => Promise<ReturnType<typeof content>> | ReturnType<typeof content>;
+};
 
-  server.registerTool(
-    "fullstackgtm_audit",
-    {
+// Single registration table. startMcpServer() registers exactly this list,
+// and fullstackgtm_capabilities reports its names from the same array — the
+// advertised inventory cannot drift from what is actually registered.
+// (A hand-written parallel tool list was a core defect of the first pass at
+// a capabilities tool, which reported 4 of the 8 registered tools.)
+const toolDefinitions: ToolDefinition[] = [
+  {
+    name: "fullstackgtm_audit",
+    writesCrm: false,
+    config: {
       title: "GTM Ops Audit",
       description:
         "Run a dry-run GTM hygiene audit and return a reviewable patch plan. " +
@@ -176,23 +197,23 @@ export async function startMcpServer() {
         staleDealDays: z.number().int().positive().optional(),
       },
     },
-    async ({ provider, inputPath, configPath, rules, output, today, staleDealDays }) => {
+    handler: async ({ provider, inputPath, configPath, rules, output, today, staleDealDays }) => {
       const loaded = configPath ? loadConfig(configPath) : null;
       const policy = mergePolicy(defaultPolicy(today), loaded?.config);
       if (today) policy.today = today;
       if (staleDealDays !== undefined) policy.staleDealDays = staleDealDays;
       const ruleSet = await resolveConfiguredRules(loaded);
       const selected = rules?.length
-        ? ruleSet.filter((rule) => rules.includes(rule.id))
+        ? ruleSet.filter((rule: { id: string }) => rules.includes(rule.id))
         : ruleSet;
       const plan = auditSnapshot(await readSnapshot(provider, inputPath), policy, selected);
       return content(output === "markdown" ? patchPlanToMarkdown(plan) : plan);
     },
-  );
-
-  server.registerTool(
-    "fullstackgtm_suggest",
-    {
+  },
+  {
+    name: "fullstackgtm_suggest",
+    writesCrm: false,
+    config: {
       title: "Suggest Placeholder Values",
       description:
         "Derive values for a plan's requires_human_* placeholder operations from snapshot " +
@@ -204,16 +225,16 @@ export async function startMcpServer() {
         inputPath: z.string().optional(),
       },
     },
-    async ({ planPath, provider, inputPath }) => {
+    handler: async ({ planPath, provider, inputPath }) => {
       const plan = JSON.parse(readFileSync(resolve(process.cwd(), planPath), "utf8")) as PatchPlan;
       const snapshot = await readSnapshot(provider, inputPath);
       return content({ suggestions: suggestValues(plan, snapshot) });
     },
-  );
-
-  server.registerTool(
-    "fullstackgtm_call_parse",
-    {
+  },
+  {
+    name: "fullstackgtm_call_parse",
+    writesCrm: false,
+    config: {
       title: "Parse Call Transcript",
       description:
         "Parse a call transcript (Speaker:/[Speaker]: lines or Granola utterance JSON) into " +
@@ -230,7 +251,7 @@ export async function startMcpServer() {
         model: z.string().optional(),
       },
     },
-    async ({ transcript, transcriptPath, title, source, extractor, model }) => {
+    handler: async ({ transcript, transcriptPath, title, source, extractor, model }) => {
       const raw =
         transcript ??
         (transcriptPath ? readFileSync(resolve(process.cwd(), transcriptPath), "utf8") : null);
@@ -255,11 +276,11 @@ export async function startMcpServer() {
       }
       return content(parseCall(raw, { title, sourceSystem: source }));
     },
-  );
-
-  server.registerTool(
-    "fullstackgtm_resolve",
-    {
+  },
+  {
+    name: "fullstackgtm_resolve",
+    writesCrm: false,
+    config: {
       title: "Resolve Record (create gate)",
       description:
         "Before creating a CRM record, check whether it already exists. Returns a verdict " +
@@ -276,34 +297,38 @@ export async function startMcpServer() {
         inputPath: z.string().optional(),
       },
     },
-    async ({ objectType, name, domain, email, accountId, provider, inputPath }) => {
+    handler: async ({ objectType, name, domain, email, accountId, provider, inputPath }) => {
       const snapshot = await readSnapshot(provider, inputPath);
       return content(resolveRecord(snapshot, { objectType, name, domain, email, accountId }));
     },
-  );
-
-  server.registerTool(
-    "fullstackgtm_rules",
-    {
+  },
+  {
+    name: "fullstackgtm_rules",
+    writesCrm: false,
+    config: {
       title: "List Audit Rules",
       description: "List the built-in deterministic audit rules with ids and descriptions.",
       inputSchema: {},
     },
-    async () => {
+    handler: async () => {
       return content(
         builtinAuditRules.map(({ id, title, description }) => ({ id, title, description })),
       );
     },
-  );
-
-  server.registerTool(
-    "fullstackgtm_apply",
-    {
+  },
+  {
+    name: "fullstackgtm_apply",
+    writesCrm: true,
+    config: {
       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(),
@@ -312,21 +337,135 @@ export async function startMcpServer() {
         output: z.enum(["json", "markdown"]).optional(),
       },
     },
-    async ({ provider, planPath, approvedOperationIds, valueOverrides, output }) => {
-      const plan = JSON.parse(
-        readFileSync(resolve(process.cwd(), planPath), "utf8"),
-      ) as PatchPlan;
+    handler: async ({ provider, planPath, approvedOperationIds, valueOverrides, output }) => {
+      // 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")) as unknown;
+      const filePlan = isStoredPlanFile(parsed) ? parsed.plan : (parsed as PatchPlan);
+      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: PatchPlan;
+      let effectiveOverrides: Record<string, unknown>;
+      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: string) => !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: string) => !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);
-    },
-  );
 
-  server.registerTool(
-    "fullstackgtm_market_worksheet",
-    {
+      // 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" as const) : ("external" as const),
+        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 });
+    },
+  },
+  {
+    name: "fullstackgtm_market_worksheet",
+    writesCrm: false,
+    config: {
       title: "Market Map Classification Worksheet",
       description:
         "Get everything needed to classify ONE vendor's messaging intensity for a market map: " +
@@ -341,15 +480,15 @@ export async function startMcpServer() {
         captureRun: z.string().optional(),
       },
     },
-    async ({ vendorId, configPath, captureRun }) => {
+    handler: async ({ vendorId, configPath, captureRun }) => {
       const config = loadMarketConfigOrHint(resolve(process.cwd(), configPath ?? "market.config.json"));
       return content(buildWorksheet(config, vendorId, { captureRun }));
     },
-  );
-
-  server.registerTool(
-    "fullstackgtm_market_observe",
-    {
+  },
+  {
+    name: "fullstackgtm_market_observe",
+    writesCrm: false,
+    config: {
       title: "Submit Market Map Observations",
       description:
         "Submit a complete ObservationSet (every vendor × claim cell) for a market map run. " +
@@ -361,7 +500,7 @@ export async function startMcpServer() {
         configPath: z.string().optional().describe("Path to market.config.json (default ./market.config.json)"),
       },
     },
-    async ({ observationsPath, configPath }) => {
+    handler: async ({ observationsPath, configPath }) => {
       const config = loadMarketConfigOrHint(resolve(process.cwd(), configPath ?? "market.config.json"));
       const set = JSON.parse(readFileSync(resolve(process.cwd(), observationsPath), "utf8")) as ObservationSet;
       const problems = validateObservationSet(config, set);
@@ -377,12 +516,80 @@ export async function startMcpServer() {
       const fronts = computeFrontStates(config, set);
       return content({ accepted: true, runLabel: set.runLabel, observations: set.observations.length, fronts });
     },
-  );
+  },
+];
+
+// Registered first so agents that list tools see the contract entry up top.
+// Its payload closes over the registration table, so the reported inventory
+// is derived, not hand-maintained.
+toolDefinitions.unshift({
+  name: "fullstackgtm_capabilities",
+  writesCrm: false,
+  config: {
+    title: "FullStackGTM Capabilities",
+    description:
+      "Machine-readable contract for this MCP server: the tool inventory (derived from the " +
+      "server's own registration table, with per-tool CRM-write flags), safety defaults, and " +
+      "the CLI entrypoints for everything the tools don't cover.",
+  },
+  handler: async () =>
+    content({
+      ok: true,
+      tool: "fullstackgtm",
+      version: packageVersion(),
+      planFirst: true,
+      mcpTools: toolDefinitions.map(({ name, writesCrm, config }) => ({
+        name,
+        title: config.title,
+        writesCrm,
+      })),
+      safety:
+        "Only tools flagged writesCrm can reach a CRM; fullstackgtm_apply writes only operations " +
+        "listed in approvedOperationIds and never writes requires_human_* placeholders without a value override.",
+      server: { command: "npx -y fullstackgtm-mcp" },
+      cli: {
+        command: "npx fullstackgtm <command> [--json]",
+        capabilities: "npx fullstackgtm capabilities --json",
+        agentGuide: "npx fullstackgtm robot-docs",
+      },
+      examples: [
+        "npx -y fullstackgtm-mcp",
+        "npx fullstackgtm capabilities --json",
+        "npx fullstackgtm audit --demo --json",
+      ],
+    }),
+});
+
+export async function startMcpServer() {
+  const server = new McpServer({
+    name: "fullstackgtm",
+    version: packageVersion(),
+  });
+
+  for (const tool of toolDefinitions) {
+    // The table is loosely typed so it can drive one loop; the SDK still
+    // validates every call against the zod inputSchema at runtime.
+    server.registerTool(tool.name, tool.config as never, tool.handler as never);
+  }
 
   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: unknown): value is StoredPlan {
+  if (typeof value !== "object" || value === null || !("plan" in value)) return false;
+  const plan = (value as { plan?: unknown }).plan;
+  return (
+    typeof plan === "object" &&
+    plan !== null &&
+    Array.isArray((plan as { operations?: unknown }).operations)
+  );
+}
+
 function loadMarketConfigOrHint(path: string): ReturnType<typeof loadMarketConfig> {
   try {
     return loadMarketConfig(path);

package/src/progress.ts

@@ -0,0 +1,197 @@
+/**
+ * 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;
+};
+
+const DEFAULT_THROTTLE_MS = 2000;
+
+/**
+ * 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 function createProgressEmitter(
+  listener: ProgressListener,
+  options: { throttleMs?: number; now?: () => number } = {},
+): ProgressEmitter {
+  const throttleMs = options.throttleMs ?? DEFAULT_THROTTLE_MS;
+  const now = options.now ?? Date.now;
+  const state: ProgressSnapshot = {
+    opsApplied: 0,
+    opsSkipped: 0,
+    opsFailed: 0,
+    updatedAt: now(),
+  };
+  let lastItemsDelivery = 0;
+  let pendingItems = false;
+
+  function deliver(event: ProgressEvent) {
+    state.updatedAt = now();
+    try {
+      listener(event, { ...state });
+    } catch {
+      // Renderers are presentation-only; never fail the work.
+    }
+  }
+
+  return {
+    stage(stage, stageIndex, stageCount) {
+      state.stage = stage;
+      state.stageIndex = stageIndex;
+      state.stageCount = stageCount;
+      state.itemsDone = undefined;
+      state.itemsTotal = undefined;
+      state.note = undefined;
+      pendingItems = false;
+      deliver({ kind: "stage", stage, stageIndex, stageCount });
+    },
+    items(done, total) {
+      state.itemsDone = done;
+      state.itemsTotal = total;
+      const terminal = total !== undefined && done >= total;
+      const due = now() - lastItemsDelivery >= throttleMs;
+      if (terminal || due) {
+        lastItemsDelivery = now();
+        pendingItems = false;
+        deliver({ kind: "items", done, total });
+      } else {
+        pendingItems = true;
+      }
+    },
+    note(note) {
+      state.note = note;
+      deliver({ kind: "note", note });
+    },
+    opResult(opId, status, detail) {
+      if (status === "applied") state.opsApplied += 1;
+      else if (status === "skipped") state.opsSkipped += 1;
+      else state.opsFailed += 1;
+      deliver({ kind: "opResult", opId, status, detail });
+    },
+    meter(spent, budget, unit) {
+      deliver({ kind: "meter", spent, budget, unit });
+    },
+    snapshot() {
+      return { ...state, updatedAt: now() };
+    },
+    flush() {
+      if (pendingItems && state.itemsDone !== undefined) {
+        lastItemsDelivery = now();
+        pendingItems = false;
+        deliver({ kind: "items", done: state.itemsDone, total: state.itemsTotal });
+      }
+    },
+  };
+}
+
+/**
+ * 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 function composeListeners(
+  ...listeners: Array<ProgressListener | undefined | null>
+): ProgressListener {
+  const active = listeners.filter((listener): listener is ProgressListener => Boolean(listener));
+  return (event, snapshot) => {
+    for (const listener of active) {
+      try {
+        listener(event, snapshot);
+      } catch {
+        // Listeners are presentation/observability only; never fail the work.
+      }
+    }
+  };
+}
+
+// ── Shared stage registries ─────────────────────────────────────────────────
+// Package constants so the CLI checklist and the app StageTimeline render
+// LITERALLY the same stages in the same order — one mental model everywhere.
+
+export const CRM_SYNC_STAGES = [
+  "owners",
+  "accounts",
+  "contacts",
+  "deals",
+  "counters",
+  "health",
+] as const;
+
+/** A connector snapshot pull — the CRM-sync stages that happen CLI-side. */
+export const SNAPSHOT_PULL_STAGES = ["owners", "accounts", "contacts", "deals"] as const;
+
+/** The Stripe connector's snapshot pull (billing systems have no owners). */
+export const STRIPE_SNAPSHOT_STAGES = ["customers", "subscriptions"] as const;
+
+export const CALL_SYNC_STAGES = ["notes", "transcripts", "insights"] as const;
+
+export const BACKFILL_STRIPE_STAGES = ["invoices", "snapshot", "matching", "plan"] as const;
+
+/** `backfill runs` — replaying local plan runs + health history to the broker. */
+export const RUNS_REPLAY_STAGES = ["runs", "health"] as const;
+
+export const APPLY_STAGES = ["preflight", "operations", "results"] as const;
+
+/** `enrich acquire` — routing sourced candidate rows into a create plan. */
+export const ACQUIRE_STAGES = ["candidates"] as const;
+
+export const MARKET_CAPTURE_STAGES = ["sources", "capture", "classify", "persist"] as const;
+
+/** No-op emitter for callers that don't care (keeps signatures simple). */
+export function nullProgressEmitter(): ProgressEmitter {
+  return createProgressEmitter(() => {});
+}