fullstackgtm 0.44.0 → 0.46.0

package/llms.txt

@@ -2,7 +2,7 @@
 
 > Plan/apply for your GTM stack: canonical CRM/GTM data model, deterministic
 > hygiene audits, reviewable dry-run patch plans, and approval-gated
-> write-back to HubSpot, Salesforce, and Stripe (read-only). Think
+> write-back to HubSpot and Salesforce; Stripe is read-only. Think
 > `terraform plan` for your CRM. Apache-2.0.
 
 CLI quick check: `fullstackgtm doctor --json`. Zero-credential demo:
@@ -15,7 +15,7 @@ at/above `--fail-on`.
 - [README](https://github.com/fullstackgtm/core/blob/main/README.md): install, five-minute loop, auth ladder, MCP setup, programmatic use
 - [INSTALL_FOR_AGENTS](https://github.com/fullstackgtm/core/blob/main/INSTALL_FOR_AGENTS.md): deterministic install-and-verify steps with expected outputs
 - [Agent skill](https://github.com/fullstackgtm/core/blob/main/skills/fullstackgtm/SKILL.md): compact operating guide, installable via `npx skills add fullstackgtm/core`
-- [Recipes](https://github.com/fullstackgtm/core/blob/main/packages/fullstackgtm/docs/recipes.md): five composable GTM plays over the primitives (cold-start lead-fill, the trigger→judge→draft outbound loop, scheduled-continuous, ABM-from-companies, hygiene-gated outbound) — the CLI ships primitives, your agent is the orchestrator, the package never sends
+- [Recipes](https://github.com/fullstackgtm/core/blob/main/docs/recipes.md): five composable GTM plays over the primitives (cold-start lead-fill, the trigger→judge→draft outbound loop, scheduled-continuous, ABM-from-companies, hygiene-gated outbound) — the CLI ships primitives, your agent is the orchestrator, the package never sends
 - [Architecture](https://github.com/fullstackgtm/core/blob/main/docs/architecture.md): module map + snapshot → audit → plan → apply data flow; "where do I add a rule/connector/operation"
 - [Contributing](https://github.com/fullstackgtm/core/blob/main/CONTRIBUTING.md): dev setup, the open-core mirror model, the release ritual
 - [API reference](https://github.com/fullstackgtm/core/blob/main/docs/api.md): semver-covered surfaces — canonical model, rule interface, plan/apply contract, connector contract, config, CLI, MCP tools
@@ -202,7 +202,7 @@ outbox is the send-side mirror of the spool; the always-on sender is hosted/opt-
 --contact <id> --result replied|...` credits the contact reached so weights
 re-learn. The contact↔account join (`contact.accountId` + `account.domain`) is
 surfaced at every hop, so the loop is contact-coherent end to end — see the
-[recipes](https://github.com/fullstackgtm/core/blob/main/packages/fullstackgtm/docs/recipes.md).
+[recipes](https://github.com/fullstackgtm/core/blob/main/docs/recipes.md).
 
 ## Key invariants (schedule)
 
@@ -211,17 +211,26 @@ owns cron logic. `add "<command>" --cron "<expr>"` validates the command
 against the read/plan-side allowlist (audit, snapshot, enrich append|refresh,
 enrich acquire --save, market capture|refresh, signals fetch, icp judge|eval,
 draft, suggest, report, doctor) and the 5-field cron
-expression, but touches no crontab; `install` materializes enabled entries
-into a sentinel-delimited managed block (`# >>> fullstackgtm <profile> >>>`)
-replaced wholesale on re-install, lines outside it untouched; `uninstall`
-removes only the block. Scheduling never auto-approves: `apply` is
+expression, but touches no system timer; `install` materializes enabled
+entries into the platform timer (`--timer` defaults launchd on macOS,
+crontab elsewhere). crontab: a sentinel-delimited managed block
+(`# >>> fullstackgtm <profile> >>>`) replaced wholesale on re-install, lines
+outside it untouched. launchd: one LaunchAgent plist per entry
+(`com.fullstackgtm.<profile>.<id>` in `~/Library/LaunchAgents`), the fleet
+replaced wholesale, foreign plists untouched — chosen because macOS gates
+`crontab` writes behind Full Disk Access (unpromptable TCC), while
+LaunchAgents need no permission and coalesce firings missed during sleep
+into one run on wake. `uninstall` removes only what install created.
+Scheduling never auto-approves: `apply` is
 schedulable ONLY as `apply --plan-id <id>` and every firing re-checks the
 plan is approved — unapproved plans record a `plan_not_approved` no-op run,
 no flag relaxes this. `schedule run <id>` is the single provider entry point
-(in-process dispatch, never shell); run records (exit code, output tail,
+(in-process dispatch, never shell; a second cron trigger in the same minute
+records a `duplicate_firing` no-op — launchd double-triggers the Vixie
+dom+dow OR corner); run records (exit code, output tail,
 artifacts: plan ids / enrich run labels, trigger cron|manual) land under
 `<home>/schedule/runs/<id>/`. `status` shows next firing and surfaces missed
-firings (visibility only — local cron has no catch-up). Providers beyond
+firings (visibility only — cron has no catch-up). Providers beyond
 `local` are not yet implemented (future: codegen scaffolds, same contract).
 
 ## Key invariants (engagement workspace / health)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM LLC <ryan@fullstackgtm.com> (https://fullstackgtm.com)",
@@ -25,7 +25,14 @@
   "files": [
     "dist",
     "src",
-    "docs",
+    "docs/api.md",
+    "docs/architecture.md",
+    "docs/crm-health-lifecycle.md",
+    "docs/linkedin-connector-spec.md",
+    "docs/outbox-format.md",
+    "docs/recipes.md",
+    "docs/signal-spool-format.md",
+    "docs/tam.md",
     "README.md",
     "CHANGELOG.md",
     "INSTALL_FOR_AGENTS.md",
@@ -41,7 +48,7 @@
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "pretest": "test -d tests || { echo 'No tests/ in this directory. In the published mirror, tests live here and `npm test` works. In the monorepo, run package tests from the repo ROOT: `node --experimental-strip-types --test tests/fullstackgtm*.test.ts` (the tests live at the monorepo root tests/).' >&2; exit 1; }",
     "test": "node --experimental-strip-types --test tests/*.test.ts",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && npm pack --dry-run && node dist/bin.js --help && node dist/mcp-bin.js --help"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/skills/fullstackgtm/SKILL.md

@@ -60,6 +60,7 @@ credentials AND stored plans per client org.
 | `bulk-update <object> --where … --set\|--archive\|--create-task` | Filtered dry-run plan; filter re-verified per record at apply time |
 | `reassign --from <owner> --to <owner>` | Ownership handoff plans per object type; `--assign-unowned --to <id>` backfills every ownerless record |
 | `fix --rule <id>` | audit one rule → suggest → approve at the confidence bar → apply only with `--yes` |
+| `backfill stripe\|runs [--since <iso>] [--pipeline <id\|label>]` | Paid Stripe invoices → proposed closed-won deals (amount = invoice total, close date = paid date, company matched by billing-email domain then name); deduped by a `stripe_invoice_id` deal property re-resolved at apply, so re-running never double-creates; a customer the CRM doesn't know gets a proposed account create in the same plan (freemail domains never used; `--skip-unmatched` = report-only); `--save` → approve → `apply`. `backfill runs` replays LOCAL run history + health timeline to the paired hosted app (idempotent; `--dry-run` to preview) |
 | `call parse\|score\|link\|plan` | Transcripts → evidence-quoted insights, rubric scorecards, deal linking, governed next-step writes |
 | `enrich append\|refresh\|ingest\|status` | Governed enrichment (Apollo pull / Clay ingest), fill-blanks-only plans |
 | `enrich acquire [--source explorium\|pipe0\|linkedin]` | Net-new ICP-targeted lead gen: resolve-first deduped `create_record` plans, capped by a per-profile windowed meter (records + spend); owner-stamped via `acquire.assign`/`--assign-owner` (never born ownerless); links each lead to a domain-stamped, signal-watchable account; `acquire.create.company` acquires accounts (ABM); `--source linkedin --list <id>` reads a HeyReach lead list (Phase 1 discovery, read-only — never sends); never auto-writes |
@@ -79,7 +80,7 @@ Add `--json` for machine-readable output on any command.
 ## MCP server (alternative surface, same gates)
 
 ```bash
-npx -y -p fullstackgtm -p @modelcontextprotocol/sdk -p zod fullstackgtm-mcp
+npx -y fullstackgtm-mcp
 ```
 
 Tools over stdio: `fullstackgtm_audit` (read-only), `fullstackgtm_rules`,

package/src/audit.ts

@@ -18,6 +18,19 @@ const DEFAULT_POLICY: Omit<GtmPolicy, "today"> = {
   requireAccountForDeal: true,
 };
 
+/**
+ * Wall clock for the plan's stdout-bound `createdAt`, honoring the
+ * SOURCE_DATE_EPOCH reproducible-build convention (seconds since the Unix
+ * epoch). When set, `audit --demo --json` is byte-deterministic across
+ * re-runs — golden tests and CI diffs can pin the payload. Unset (normal
+ * use) it is the real clock, exactly as before.
+ */
+function nowIso(): string {
+  const epoch = process.env.SOURCE_DATE_EPOCH;
+  if (epoch && /^\d+$/.test(epoch)) return new Date(Number(epoch) * 1000).toISOString();
+  return new Date().toISOString();
+}
+
 export function defaultPolicy(today = new Date().toISOString().slice(0, 10)): GtmPolicy {
   return {
     ...DEFAULT_POLICY,
@@ -28,20 +41,33 @@ export function defaultPolicy(today = new Date().toISOString().slice(0, 10)): Gt
 /**
  * Run every rule over the snapshot and collect the results into a single
  * dry-run patch plan. Pass custom rules to extend or replace the built-ins.
+ * `onRule` reports per-rule progress (presentation only — a throwing callback
+ * never fails the audit).
  */
 export function auditSnapshot(
   snapshot: CanonicalGtmSnapshot,
   policy: GtmPolicy = defaultPolicy(),
   rules: GtmAuditRule[] = builtinAuditRules,
+  onRule?: (ruleId: string, phase: "start" | "done", findings?: number) => void,
 ): PatchPlan {
   const context = { snapshot, policy, index: buildSnapshotIndex(snapshot) };
   const findings: AuditFinding[] = [];
   const operations: PatchOperation[] = [];
 
   for (const rule of rules) {
+    try {
+      onRule?.(rule.id, "start");
+    } catch {
+      // progress is presentation-only
+    }
     const result = rule.evaluate(context);
     findings.push(...result.findings);
     operations.push(...result.operations);
+    try {
+      onRule?.(rule.id, "done", result.findings.length);
+    } catch {
+      // progress is presentation-only
+    }
   }
 
 
@@ -52,7 +78,7 @@ export function auditSnapshot(
   return {
     id: `patch_plan_${stableHash(`${snapshot.provider}:${snapshot.generatedAt}:${findings.length}:${operations.length}`)}`,
     title: "GTM hygiene audit patch plan",
-    createdAt: new Date().toISOString(),
+    createdAt: nowIso(),
     status: operations.length > 0 ? "needs_approval" : "draft",
     dryRun: true,
     summary: `${findings.length} findings and ${operations.length} proposed dry-run operations.`,

package/src/backfill.ts

@@ -0,0 +1,340 @@
+/**
+ * Backfill: Stripe paid invoices → closed-won CRM deals, through the normal
+ * governed plan/apply flow.
+ *
+ * Product assumption this encodes: billing (Stripe) is the revenue source
+ * of truth; the CRM should retroactively carry ONE closed-won deal per paid
+ * invoice (amount = invoice total, close date = paid date, associated to the
+ * customer's company, deduped by invoice id). This module only BUILDS the
+ * dry-run plan — nothing here touches a CRM. Writes happen exclusively via
+ * `apply` on operations approved through `plans approve`, where the HubSpot
+ * connector re-resolves each invoice id (resolve-first) and creates only on
+ * a confirmed miss.
+ */
+
+import type {
+  CanonicalAccount,
+  CanonicalGtmSnapshot,
+  CreateRecordPayload,
+  GtmEvidence,
+  PatchOperation,
+  PatchPlan,
+} from "./types.ts";
+import type { StripePaidInvoice } from "./connectors/stripe.ts";
+import { normalizeDomain } from "./merge.ts";
+
+// Mirrors stableHash in rules.ts (FNV-1a); duplicated to keep backfill.ts
+// importable without pulling the audit engine (the enrich.ts precedent).
+function fnv1a(value: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < value.length; i += 1) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+export const DEFAULT_BACKFILL_MATCH_PROPERTY = "stripe_invoice_id";
+
+// Freemail domains never become a company domain: stamping "gmail.com" on an
+// account (or resolving a company BY gmail.com) would collapse unrelated
+// customers onto one record. Mirrors FREE_MAIL in connectors/signalSources.ts
+// (duplicated to keep backfill.ts importable without connector code, the
+// fnv1a precedent above).
+const FREE_MAIL = new Set([
+  "gmail.com",
+  "yahoo.com",
+  "hotmail.com",
+  "outlook.com",
+  "icloud.com",
+  "aol.com",
+  "proton.me",
+  "protonmail.com",
+]);
+
+export type StripeBackfillOptions = {
+  /** Pipeline id or case-insensitive label; absent = the portal's default pipeline. */
+  pipeline?: string;
+  /** Deal dedupe property stamped with the invoice id (default "stripe_invoice_id"). */
+  matchProperty?: string;
+  /** Source label recorded on payloads/evidence (default "stripe:invoices"). */
+  source?: string;
+  /**
+   * When a customer matches no CRM account, propose creating the account as
+   * part of this plan (default true). The account op is explicit and
+   * approval-gated like everything else; apply is resolve-first, so an
+   * account that appeared in the meantime is reused, not duplicated. False =
+   * the conservative original behavior: unmatched customers are reported
+   * only and their invoices produce no operations.
+   */
+  createMissingAccounts?: boolean;
+  /** Injectable clock for deterministic tests. */
+  now?: () => Date;
+};
+
+/** One invoice whose customer could not be matched to any CRM account. */
+export type StripeBackfillUnmatched = {
+  invoiceId: string;
+  invoiceNumber?: string;
+  customerName?: string;
+  customerDomain?: string;
+  amountPaid: number;
+  currency?: string;
+  paidAt?: string;
+};
+
+/** One account this plan proposes to create for an unmatched Stripe customer. */
+export type StripeBackfillProposedAccount = {
+  name: string;
+  domain?: string;
+  /** Paid invoices from this customer that the plan attaches to the account. */
+  invoiceCount: number;
+};
+
+export type StripeBackfillCounts = {
+  invoices: number;
+  /** create_record deal ops emitted. */
+  planned: number;
+  /** create_record account ops emitted for unmatched customers. */
+  accountsProposed: number;
+  /** Customers with no CRM match AND no usable name/domain — reported only. */
+  unmatched: number;
+  /** Plan-time prefilter: a deal with the same name already exists. */
+  alreadyInCrm: number;
+};
+
+export type StripeBackfillResult = {
+  plan: PatchPlan;
+  counts: StripeBackfillCounts;
+  unmatched: StripeBackfillUnmatched[];
+  proposedAccounts: StripeBackfillProposedAccount[];
+};
+
+/** `Invoice <number || id> — <customer name>` (the plan-time dedupe name). */
+function backfillDealName(invoice: StripePaidInvoice, companyName: string): string {
+  return `Invoice ${invoice.number ?? invoice.id} — ${invoice.customerName ?? companyName}`;
+}
+
+/**
+ * Match each paid invoice's customer to a snapshot account (normalized domain
+ * first — the accurate key — then exact case-insensitive name) and emit one
+ * create_record deal op per invoice that has no deal yet.
+ *
+ * Unmatched customers (default): the plan ALSO proposes creating the account —
+ * one explicit, approval-gated account create_record op per new customer,
+ * with the customer's invoices attached as deals. Freemail billing domains
+ * (gmail/outlook/…) are never used as a company domain. A customer with no
+ * usable name or domain stays report-only. `createMissingAccounts: false`
+ * restores the original conservative behavior (unmatched = reported, no ops).
+ *
+ * The by-deal-name prefilter here is best-effort plan hygiene; the
+ * AUTHORITATIVE duplicate gate is the connector's apply-time resolve-first
+ * search on the invoice-id property (and resolve-by-domain/name for accounts).
+ */
+export function buildStripeBackfillPlan(
+  invoices: StripePaidInvoice[],
+  snapshot: CanonicalGtmSnapshot,
+  opts: StripeBackfillOptions = {},
+): StripeBackfillResult {
+  const nowIso = (opts.now ?? (() => new Date()))().toISOString();
+  const matchProperty = opts.matchProperty ?? DEFAULT_BACKFILL_MATCH_PROPERTY;
+  const source = opts.source ?? "stripe:invoices";
+
+  // Snapshot lookups. First occurrence wins on a duplicate key — the
+  // connector's own resolve/associate step handles ambiguity at apply time.
+  const accountsByDomain = new Map<string, CanonicalAccount>();
+  const accountsByName = new Map<string, CanonicalAccount>();
+  for (const account of snapshot.accounts ?? []) {
+    const domain = normalizeDomain(account.domain);
+    if (domain && !accountsByDomain.has(domain)) accountsByDomain.set(domain, account);
+    const name = account.name?.trim().toLowerCase();
+    if (name && !accountsByName.has(name)) accountsByName.set(name, account);
+  }
+  const existingDealNames = new Set(
+    (snapshot.deals ?? [])
+      .map((deal) => deal.name?.trim().toLowerCase())
+      .filter((name): name is string => Boolean(name)),
+  );
+
+  const createMissingAccounts = opts.createMissingAccounts ?? true;
+  const operations: PatchOperation[] = [];
+  const evidence: GtmEvidence[] = [];
+  const unmatched: StripeBackfillUnmatched[] = [];
+  const proposedByKey = new Map<string, StripeBackfillProposedAccount>();
+  const counts: StripeBackfillCounts = {
+    invoices: invoices.length,
+    planned: 0,
+    accountsProposed: 0,
+    unmatched: 0,
+    alreadyInCrm: 0,
+  };
+
+  for (const invoice of invoices) {
+    // Match the customer to a CRM account: domain first, then exact name.
+    const domain = normalizeDomain(invoice.customerDomain);
+    let account = domain ? accountsByDomain.get(domain) : undefined;
+    if (!account && invoice.customerName) {
+      account = accountsByName.get(invoice.customerName.trim().toLowerCase());
+    }
+
+    // The company the deal will land on: the matched account, or (default) a
+    // new account this plan proposes for the unmatched customer.
+    let companyName: string | undefined = account?.name;
+    let companyDomain = normalizeDomain(account?.domain);
+    let accountIsNew = false;
+    if (!account && createMissingAccounts) {
+      const usableDomain = domain && !FREE_MAIL.has(domain) ? domain : undefined;
+      const name = invoice.customerName?.trim() || usableDomain;
+      if (name) {
+        companyName = name;
+        companyDomain = usableDomain;
+        accountIsNew = true;
+      }
+    }
+    if (!companyName) {
+      counts.unmatched += 1;
+      unmatched.push({
+        invoiceId: invoice.id,
+        invoiceNumber: invoice.number,
+        customerName: invoice.customerName,
+        customerDomain: invoice.customerDomain,
+        amountPaid: invoice.amountPaid,
+        currency: invoice.currency,
+        paidAt: invoice.paidAt,
+      });
+      continue;
+    }
+
+    // Plan-time dupe prefilter by deal name (best-effort; apply-time
+    // resolve-first on the invoice-id property is the authoritative gate).
+    const dealName = backfillDealName(invoice, companyName);
+    if (existingDealNames.has(dealName.trim().toLowerCase())) {
+      counts.alreadyInCrm += 1;
+      continue;
+    }
+
+    const invoiceLabel = invoice.number ?? invoice.id;
+    const amountLabel = `${invoice.amountPaid}${invoice.currency ? ` ${invoice.currency}` : ""}`;
+    const recordEvidence: GtmEvidence = {
+      id: `ev_bkf_${fnv1a(`${source}:${invoice.id}`)}`,
+      sourceSystem: "web",
+      sourceObjectType: "invoice",
+      sourceObjectId: invoice.id,
+      title: `Stripe paid invoice ${invoiceLabel}`,
+      text:
+        `Stripe invoice ${invoiceLabel} (${invoice.id}) for ${invoice.customerName ?? companyName}: ` +
+        `${amountLabel} paid${invoice.paidAt ? ` on ${invoice.paidAt}` : ""}.`,
+      capturedAt: nowIso,
+      metadata: {
+        source,
+        invoiceId: invoice.id,
+        amountPaid: invoice.amountPaid,
+        currency: invoice.currency ?? null,
+        paidAt: invoice.paidAt ?? null,
+        customerId: invoice.customerId ?? null,
+      },
+    };
+    evidence.push(recordEvidence);
+
+    // One explicit account op per NEW customer (not per invoice): the reviewer
+    // sees exactly which companies this plan will create. Apply resolves by
+    // domain-then-name first, so a concurrently-created account is reused.
+    if (accountIsNew) {
+      const accountKey = (companyDomain ?? companyName).toLowerCase();
+      const existing = proposedByKey.get(accountKey);
+      if (existing) {
+        existing.invoiceCount += 1;
+      } else {
+        proposedByKey.set(accountKey, {
+          name: companyName,
+          ...(companyDomain ? { domain: companyDomain } : {}),
+          invoiceCount: 1,
+        });
+        const accountPayload: CreateRecordPayload = {
+          properties: {
+            name: companyName,
+            ...(companyDomain ? { domain: companyDomain } : {}),
+          },
+          matchKey: "name",
+          matchValue: companyName,
+          source,
+        };
+        operations.push({
+          id: `op_bkf_${fnv1a(`${source}:account:${accountKey}`)}`,
+          objectType: "account",
+          objectId: `create:stripe:customer:${invoice.customerId ?? accountKey}`,
+          operation: "create_record",
+          beforeValue: null,
+          afterValue: accountPayload,
+          reason:
+            `Stripe customer "${companyName}"${companyDomain ? ` (${companyDomain})` : ""} has paid ` +
+            `invoice(s) but no CRM account — create it so the backfilled deals have a home. ` +
+            `Resolve-first by ${companyDomain ? "domain, then " : ""}name at apply.`,
+          sourceRuleOrPolicy: `backfill:${source}`,
+          riskLevel: "medium",
+          approvalRequired: true,
+          rollback: "Archive the created company (it was net-new).",
+          evidenceIds: [recordEvidence.id],
+        });
+        counts.accountsProposed += 1;
+      }
+    }
+
+    // Prefer the matched ACCOUNT's own name/domain for the association so the
+    // connector's resolve-first company step lands on the matched record; for
+    // a new customer these are the proposed account's name/domain.
+    const payload: CreateRecordPayload = {
+      properties: {
+        dealname: dealName,
+        amount: String(invoice.amountPaid),
+        ...(invoice.paidAt ? { closedate: invoice.paidAt } : {}),
+        ...(invoice.description ? { description: invoice.description } : {}),
+      },
+      matchKey: matchProperty,
+      matchValue: invoice.id,
+      source,
+      dealStage: "closed_won",
+      ...(opts.pipeline ? { dealPipeline: opts.pipeline } : {}),
+      associateCompanyName: companyName,
+      ...(companyDomain ? { associateCompanyDomain: companyDomain } : {}),
+    };
+    operations.push({
+      id: `op_bkf_${fnv1a(`${source}:deal:${invoice.id}`)}`,
+      objectType: "deal",
+      objectId: `create:stripe:invoice:${invoice.id}`,
+      operation: "create_record",
+      beforeValue: null,
+      afterValue: payload,
+      reason:
+        `Paid Stripe invoice ${invoiceLabel} (${amountLabel}, paid ${invoice.paidAt ?? "date unknown"}) ` +
+        `has no CRM deal — backfill as closed-won on ${accountIsNew ? "NEW account" : "account"} ` +
+        `"${companyName}"${accountIsNew ? " (created by this plan)" : ""} ` +
+        `(deduped by ${matchProperty}=${invoice.id}).`,
+      sourceRuleOrPolicy: `backfill:${source}`,
+      riskLevel: "medium",
+      approvalRequired: true,
+      rollback: "Archive the created deal (it was net-new).",
+      evidenceIds: [recordEvidence.id],
+    });
+    counts.planned += 1;
+  }
+
+  const plan: PatchPlan = {
+    id: `patch_plan_backfill_${fnv1a(`${source}:${nowIso}:${invoices.map((invoice) => invoice.id).join(",")}`)}`,
+    title: `Backfill closed-won deals — ${source}`,
+    createdAt: nowIso,
+    status: operations.length > 0 ? "needs_approval" : "draft",
+    dryRun: true,
+    summary:
+      `${counts.planned} closed-won deal(s) proposed from ${counts.invoices} paid Stripe invoice(s)` +
+      `${counts.accountsProposed > 0 ? `, plus ${counts.accountsProposed} new account(s) proposed for customers the CRM doesn't know` : ""} ` +
+      `(${counts.alreadyInCrm} already have a matching deal, ${counts.unmatched} ` +
+      `${createMissingAccounts ? "customer(s) with no usable name/domain" : "unmatched customer(s)"} reported only` +
+      `${createMissingAccounts ? "" : " — account creation disabled"}). ` +
+      `Deduped by ${matchProperty} = invoice id; apply re-checks resolve-first before creating.`,
+    findings: [],
+    evidence,
+    operations,
+  };
+  return { plan, counts, unmatched, proposedAccounts: [...proposedByKey.values()] };
+}

package/src/bin.ts

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 import { runCli } from "./cli.ts";
-import { flushRunReport } from "./runReport.ts";
+import { beginRunReport, flushRunReport } from "./runReport.ts";
 
 const args = process.argv.slice(2);
 const startedAt = Date.now();
 
+// Arm live progress heartbeats (paired CLIs stream long runs to the hosted
+// app under the same clientRunId the final flush below will upsert).
+beginRunReport(args, startedAt);
+
 runCli(args)
   .then(async () => {
     // exitCode 2 (audit findings / create-gate) or 1 (no value) = "partial":