fullstackgtm 0.45.0 → 0.46.0

package/CHANGELOG.md

@@ -3,7 +3,115 @@
 All notable changes to the `fullstackgtm` package are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
-The path to 1.0 is planned in [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md).
+The path to 1.0 is planned in the roadmap doc in the repository.
+
+## [Unreleased]
+
+## [0.46.0] — 2026-07-06
+
+### Fixed — launch hardening
+
+- **`fullstackgtm-mcp --help`/`--version` now work without optional peers.**
+  The MCP entrypoint parsed argv before importing `@modelcontextprotocol/sdk`
+  and `zod`, so on a clean install `fullstackgtm-mcp --help` exited 1. It now
+  prints usage (and the `npx -y -p fullstackgtm -p @modelcontextprotocol/sdk
+  -p zod fullstackgtm-mcp` invocation) and exits 0.
+- **Packaging hygiene.** Narrowed `files` so internal planning docs
+  (`dx-punch-list`, `perf-notes`, `roadmap-to-1.0`) no longer ship in the npm
+  tarball; strengthened `prepublishOnly` to also run `npm pack --dry-run` and
+  smoke both bin `--help` paths.
+- **Doc accuracy.** README Stripe restricted-key guidance now includes
+  Invoices:Read (required by `backfill stripe`); schedule allowlist lists
+  `enrich acquire --save`; benchmark headline points to the leaderboard
+  caveats; `llms.txt` clarifies Stripe is read-only and fixes broken public
+  mirror links; CHANGELOG clarifies unmatched Stripe customers get a proposed,
+  approval-gated account-create (not silent auto-create).
+- **Public-surface scrub.** Replaced realistic fake LinkedIn prospect fixtures
+  with clearly-synthetic example identities and removed private-context
+  wording from shipped source/docs.
+
+### Added
+
+- **Hosted first-party CRM OAuth for the CLI.** `fullstackgtm login hubspot` and
+  `fullstackgtm login salesforce` now default to hosted browser OAuth (explicit
+  `--hosted`, `--via`/`FULLSTACKGTM_HOSTED_URL` override), storing the same local
+  broker credential used by team pairing while provider tokens are minted
+  server-side. BYO app/token paths remain as advanced fallbacks, secrets still
+  never travel via argv, and first-party app secrets never ship in the npm
+  package. Non-TTY missing-BYO-flag errors print a deterministic hosted-login
+  next command.
+
+- **Chunked LLM insight extraction (`extractInsightsChunked`) — the TamTone
+  "langextract" method.** Transcripts are never sent whole: they are chopped
+  into ~1,500-char speaker-turn-respecting chunks (the tested quality lever —
+  small chunks yielded ~95% more grounded signals than large ones) and each
+  chunk gets its own focused few-shot extraction call. Per-chunk results pass
+  the SAME verbatim-evidence and next-step-grounding gates as before (checked
+  against the chunk they came from — a quote from another chunk is treated as
+  a hallucination), then a quality gate
+  (0.25·length + 0.40·specificity + 0.35·confidence, reject < 0.15) filters
+  filler before per-call dedupe (richer statement wins) and ranking.
+  `call parse --llm` now uses this pipeline; single-shot remains for
+  one-chunk transcripts. Bounded: ≤80 chunks/call, 4 concurrent, a failed
+  chunk is skipped (all-failed throws).
+
+- **`backfill runs` — replay local execution history to the paired hosted
+  app.** An engagement that started CLI-only gets its full trail on pairing:
+  every stored plan's apply runs (with per-op result counts and ORIGINAL
+  timestamps) and the `health.jsonl` hygiene timeline (seeding the hosted
+  health trend). Idempotent by construction — deterministic per-run
+  `clientRunId`s and server-side timestamp dedupe make re-running safe.
+  `--dry-run` counts without sending. Privacy unchanged: only what live
+  reporting sends leaves the machine (statuses, counts, timestamps,
+  scores — never CRM field values). Live run reports also carry a stable
+  `clientRunId` now, so retried reports never duplicate.
+
+- **`backfill stripe` — paid Stripe invoices become closed-won CRM deals,
+  through the normal governed flow.** For a business whose revenue source of
+  truth is Stripe, the CRM can now be retroactively made honest: one
+  closed-won deal per paid invoice (amount = invoice total, close date = paid
+  date, associated to the customer's company), matched to CRM accounts by
+  billing-email domain first, then exact name. Unmatched customers are either
+  report-only (when they lack a usable name/domain, or with `--skip-unmatched`)
+  or an explicit proposed ACCOUNT create in the same `needs_approval` plan. The
+  command only ever proposes: `--save` persists the plan and writes happen
+  through `plans approve` → `apply`, where the connector re-resolves each
+  invoice id and creates only on a confirmed miss — re-running never
+  double-creates. Proposed account creates are one op per customer, use the
+  billing-email domain unless freemail, and stay approval-gated like every
+  other write.
+- **HubSpot deal creation in `create_record`.** `CreateRecordPayload` gains
+  `dealStage: "closed_won"` (a provider-neutral sentinel resolved to the
+  target pipeline's real closed-won stage id from pipeline metadata — never
+  substring guessing) and `dealPipeline` (id or label; default pipeline when
+  absent). The dedupe key is a custom deal property (default
+  `stripe_invoice_id`), ensured on demand; if it can't be ensured the create
+  is skipped rather than performed without its dedupe key. Salesforce deal
+  creation stays explicitly skipped for now.
+- **`fetchStripePaidInvoices`** on the Stripe connector: paginated
+  `status=paid` invoice reads with `created[gte]` incremental support,
+  cents→major conversion, and paid-date extraction.
+- **Node-free health scoring (`src/healthScore.ts`).** `computeHealth` /
+  `summarizeHealth` / `healthToMarkdown` split out of `health.ts` (which keeps
+  the fs-backed profile timeline and re-exports everything) so V8 runtimes —
+  the hosted app's Convex functions — can score CRM hygiene with the exact
+  same deterministic curve the CLI uses.
+
+### Changed
+
+- **CLI startup is ~20–30% faster (p50), with zero output changes.** The
+  dispatcher now loads verb modules lazily instead of compiling the full
+  78-module graph on every invocation, `node:http` (which transitively
+  compiles node's bundled undici on Node 22) is deferred to the OAuth
+  loopback login that actually starts a server, and the CRM connector /
+  demo-data modules load only when that data source is selected. Measured
+  p50 over interleaved A/B runs: `--version` −31%, `capabilities --json`
+  −30%, `audit --demo --json` −23%. Every output is byte-identical to the
+  previous build (verified against 57 golden outputs across help, audit,
+  doctor, rules, dedupe, resolve, snapshot, and error paths) and the public
+  import surface of `cli.ts` is unchanged. Profiling method, opportunity
+  matrix, and honest non-wins are documented in
+  [docs/perf-notes.md](./docs/perf-notes.md).
 
 ## [0.45.0] — 2026-07-02
 

package/INSTALL_FOR_AGENTS.md

@@ -45,13 +45,15 @@ Credential resolution ladder, first match wins:
 
 1. `--token-env <NAME>` — explicit env var for one invocation
 2. Ambient env: `HUBSPOT_ACCESS_TOKEN`, or `SALESFORCE_ACCESS_TOKEN` + `SALESFORCE_INSTANCE_URL`, or `STRIPE_SECRET_KEY`
-3. Stored login: `fullstackgtm login <provider>` (interactive; a human runs this once)
-4. Broker pairing: `fullstackgtm login --via <hosted url>` (a human approves the pairing code)
+3. BYO direct login: advanced token/OAuth paths stored locally; these override hosted
+4. Hosted OAuth / broker: `fullstackgtm login hubspot` or `fullstackgtm login salesforce` (default browser OAuth; stores a broker credential and mints provider tokens server-side) or `login --via <hosted url>`
 
-In an agent sandbox, prefer rung 1 or 2. Never echo tokens into argv —
-`login` reads secrets from stdin only. Set `FSGTM_NO_BROWSER=1` in headless
+In an agent sandbox, prefer rung 1 or 2. If a human is at a browser, the next
+command is usually `fullstackgtm login hubspot --hosted` or
+`fullstackgtm login salesforce --hosted`. Never echo tokens into argv — BYO
+secret paths read from stdin only. Set `FSGTM_NO_BROWSER=1` in headless
 environments — login flows then print verification URLs instead of opening
-the OS browser.
+the OS browser. First-party app secrets never ship in the npm package.
 
 LLM calls (`call parse`, `call score`, `market classify`): set
 `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in the environment, or have the human
@@ -77,11 +79,11 @@ count and provider spend per day and per month. It still flows through
 dry-run → approve → apply and never auto-writes — expect it to refuse rather
 than silently exceed the meter.
 
-Provider prerequisites (what the human must create, and which scopes) are in
-the README's **"Connect your CRM"** section: HubSpot needs a private app with
-four `crm.objects.*.read` scopes (plus write scopes only for `apply`);
-Salesforce needs an admin-created Connected App with device flow enabled;
-Stripe works with a restricted key (Customers + Subscriptions read).
+Provider prerequisites for BYO fallback (what the human must create, and which
+scopes) are in the README's **"Connect your CRM"** section: HubSpot private app
+or BYO OAuth app scopes, Salesforce admin-created Connected App for device
+flow, and Stripe restricted key (Customers + Subscriptions read). Hosted
+HubSpot/Salesforce OAuth is the default when available.
 
 ```bash
 HUBSPOT_ACCESS_TOKEN=$TOKEN fullstackgtm audit --provider hubspot --json --out plan.json
@@ -140,6 +142,6 @@ stored captures before anything is appended).
 | Symptom | Fix |
 | --- | --- |
 | `fullstackgtm: command not found` | Re-run with `npx fullstackgtm`, or check global npm bin is on PATH |
-| `No HubSpot credentials` (exit 1) | Set `HUBSPOT_ACCESS_TOKEN` or have a human run `fullstackgtm login hubspot` |
+| `No HubSpot credentials` (exit 1) | Set `HUBSPOT_ACCESS_TOKEN` or have a human run `fullstackgtm login hubspot --hosted` |
 | MCP server prints peer-dependency help | Install `@modelcontextprotocol/sdk` and `zod` (see step 6) |
 | Need machine state for orchestration | `fullstackgtm doctor --json` |

package/README.md

@@ -8,7 +8,7 @@ Think `terraform plan` for your CRM: agents and scripts may *read* everything, b
 
 Licensed under [Apache-2.0](./LICENSE). The boundary is deliberate and stable: the framework, CLI, and MCP server are open source; the hosted Full Stack GTM application (dashboard, sync backend, broker service, team workflows) is a separate, proprietary product built on top of this package. Features never move from open to closed. See [CONTRIBUTING.md](./CONTRIBUTING.md) for how development and mirroring work.
 
-**Status: beta (0.x).** The surfaces in [docs/api.md](./docs/api.md) — the canonical model, rule interface, plan/apply contract, connector contract, merge/diff, config, CLI, and MCP tools — are settling but may still break in minor releases until 1.0; the path there is [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md). The safety invariants (read-only audits, approval-gated writes, placeholder refusal) are not beta and do not change. Connectors: HubSpot (read/write), Salesforce (read/write), Stripe (read-only billing).
+**Status: beta (0.x).** The surfaces in [docs/api.md](./docs/api.md) — the canonical model, rule interface, plan/apply contract, connector contract, merge/diff, config, CLI, and MCP tools — are settling but may still break in minor releases until 1.0. The safety invariants (read-only audits, approval-gated writes, placeholder refusal) are not beta and do not change. Connectors: HubSpot (read/write), Salesforce (read/write), Stripe (read-only billing).
 
 ## Install
 
@@ -136,8 +136,11 @@ fullstackgtm dedupe account --key domain --keep richest --save   # one merge_rec
 fullstackgtm reassign --from 411 --to 902 --except-deal-stage closing --save   # ownership handoff playbook
 fullstackgtm reassign --assign-unowned --to 902 --save          # claim every ownerless record for an owner
 fullstackgtm fix --rule missing-deal-owner --provider hubspot --yes  # audit one rule → suggest → approve → apply, one command
+fullstackgtm backfill stripe --save     # paid Stripe invoices → proposed closed-won deals, deduped by invoice id
 ```
 
+`backfill stripe` makes the CRM honest when Stripe is the revenue source of truth: one closed-won deal per paid invoice (amount = invoice total, close date = paid date, company association by billing-email domain). A customer the CRM doesn't know gets a proposed account create in the same approval-gated plan (freemail billing domains are never used as a company domain; `--skip-unmatched` keeps them report-only), and apply re-resolves each invoice id so re-running never double-creates.
+
 `bulk-update` filters the snapshot (`=`, `!=`, `~` substring, `!~` not-substring, `:empty`/`:notempty`, type-aware comparisons `<` `>` `<=` `>=` where `today` resolves to the policy date — e.g. `closeDate<today` — and date/numeric fields coerce by value form, `|` any-of, relational pseudo-fields like `account.domain` or `openDealStages`) into a dry-run patch plan — and **the full filter is re-verified per record at apply time**, with mid-apply rechecks, so a record that stopped matching between audit and apply is skipped, not clobbered. For date/count hygiene (past close dates, stale deals, missing accounts, duplicates), prefer the rule-backed `fix --rule <id>` — the rule encodes the open-deal + date logic deterministically; use `bulk-update` only when no rule covers the task. Equality filters double as preconditions; `--require` adds explicit ones; `--guard` asserts cross-record conditions; `--max-operations` caps blast radius. `--set field=from:<sourceField>` derives values per record; `--create-task <text>` is the third change mode, emitting approval-gated `create_task` operations instead of field writes; `--archive` refuses records whose identity key (account domain, contact email) is shared with another record — that's a duplicate, and duplicates are merged with `dedupe`, not archived around (`--force-archive-duplicates` overrides that refusal explicitly).
 
 `dedupe` finds duplicate groups by normalized identity key and emits one `merge_records` operation per group with a deterministic survivor (`richest` = most populated fields, ties to lowest id; `oldest`). Merges stay irreversible-and-therefore-low-confidence-capped on approval, exactly like merge suggestions from the audit. `reassign` is the ownership-handoff playbook: one plan per object type, extra scoping account-lifted to deals and contacts, and `--except-deal-stage` excludes both deals in that stage and every record whose account has an open deal in it. `fix` is the one-shot composite for a single rule: audit → save → suggest → approve suggestion-backed operations at the confidence bar → with `--yes`, apply and print the stage-by-stage summary; without it, stop after approval and print the apply command.
@@ -260,7 +263,7 @@ fullstackgtm schedule status --runs 5            # last runs, exit codes, artifa
 fullstackgtm schedule uninstall                  # remove the managed block, touch nothing else
 ```
 
-**Scheduling never auto-approves.** Schedulable commands are read/plan-side only — `audit`, `snapshot`, `enrich append|refresh`, `market capture|refresh`, `signals fetch`, `icp judge`, `icp eval`, `draft`, `suggest`, `report`, `doctor` — so unattended runs accumulate *proposals* (plans in the queue, run records, reports), never CRM writes. `apply` is schedulable only as `apply --plan-id <id>`, and every firing re-checks the plan's status is approved: an unapproved plan records a `plan_not_approved` no-op run instead of executing, and no flag relaxes this. Arbitrary shell is not schedulable — an entry's argv must resolve to a known fullstackgtm command (validated at `add` time and re-checked at run time), and the timer line you audit — crontab entry or LaunchAgent `ProgramArguments` — is always `fullstackgtm schedule run <id>` and nothing else.
+**Scheduling never auto-approves.** Schedulable commands are read/plan-side only — `audit`, `snapshot`, `enrich append|refresh`, `enrich acquire --save`, `market capture|refresh`, `signals fetch`, `icp judge`, `icp eval`, `draft`, `suggest`, `report`, `doctor` — so unattended runs accumulate *proposals* (plans in the queue, run records, reports), never CRM writes. `apply` is schedulable only as `apply --plan-id <id>`, and every firing re-checks the plan's status is approved: an unapproved plan records a `plan_not_approved` no-op run instead of executing, and no flag relaxes this. Arbitrary shell is not schedulable — an entry's argv must resolve to a known fullstackgtm command (validated at `add` time and re-checked at run time), and the timer line you audit — crontab entry or LaunchAgent `ProgramArguments` — is always `fullstackgtm schedule run <id>` and nothing else.
 
 `install` materializes enabled entries into the system timer; `--timer` defaults by platform. On macOS it writes one LaunchAgent plist per entry (`com.fullstackgtm.<profile>.<id>` in `~/Library/LaunchAgents`, loaded via `launchctl bootstrap`) — macOS gates `crontab` writes behind Full Disk Access, a permission no program can request, while LaunchAgents need none; launchd also coalesces firings missed during sleep into one run on wake. Re-install replaces the profile's plist fleet wholesale and never touches foreign plists. Elsewhere (or with `--timer crontab`) it renders a sentinel-delimited block (`# >>> fullstackgtm <profile> >>>` … `# <<< fullstackgtm <profile> <<<`) in your user crontab; re-install replaces the block wholesale and never touches lines outside it. Honest limitation: cron has no catch-up — a laptop asleep at firing time means a missed run. `schedule status` surfaces missed firings by comparing expected-vs-actual run history, so the gap is at least visible. Entries are provider-agnostic; cloud providers (Modal, AWS) arrive as scaffold generators that call the same `schedule run <id>` contract, and are refused as "not yet implemented" until then.
 
@@ -312,7 +315,9 @@ fullstackgtm diff --before old.json --after new.json --fail-on-new-findings
 - `--demo` (with `--seed`) generates a realistic mid-market CRM with injected real-world failure modes — departed owners, unlinked deals, orphan accounts, stale pipeline — so agents and CI can exercise the full snapshot → audit → apply pipeline with zero credentials.
 - Exit codes: `0` success, `1` error, `2` findings at/above `--fail-on`.
 
-"Built for agents" is measured, not asserted: a 1,892-run benchmark (20 scenarios = 17 synthetic + 3 seeded from an anonymized real portal, × 3 tool-surface arms × up to 4 trials, across nine models from six vendors, deterministic graders over final CRM state, τ-bench-style pass^k) shows the gated CLI surface beating raw CRM-API access on completion-under-policy for every model tested — and the tool-surface effect is monotonic and vendor-independent. Full matrix and methodology: [the leaderboard](./evals/crm/leaderboard/RESULTS.md).
+"Built for agents" is measured, not asserted: a 1,904-run benchmark (17 CRM-operations scenarios × 3 tool-surface arms × up to 4 trials, across ten models from six vendors, deterministic graders over final CRM state, τ-bench-style pass^k) shows the gated CLI surface matching or beating raw CRM-API access on completion-under-policy for every model tested — strictly better in nine of ten — and the effect is vendor-independent. Full matrix and methodology: [the leaderboard](./evals/crm/leaderboard/RESULTS.md).
+
+Caveat: the leaderboard documents the Opus reduced protocol and mixed-version Informed arms; treat the headline as a pointer to those exact RESULTS.md conditions.
 
 The design is **deterministic apply, governed suggest**: the parts that touch your CRM — the audit rules, the plan/apply contract, compare-and-set, the survivor/merge logic — are deterministic and replayable; the parts that read free text (`call parse`/`score`, `market classify`) are LLM-powered but bounded, with every quoted span mechanically verified against the source before it can drive a writeback. Nondeterministic suggestion, deterministic governance.
 
@@ -321,9 +326,9 @@ The design is **deterministic apply, governed suggest**: the parts that touch yo
 Credential resolution is a ladder — the first rung that yields a token wins:
 
 1. **`--token-env <NAME>`** — explicit env var for one invocation (agent sandboxes, scripts)
-2. **`HUBSPOT_ACCESS_TOKEN`** — ambient env (CI)
-3. **Stored login** — `fullstackgtm login hubspot`, kept in `~/.fullstackgtm/credentials.json` (0600; override location with `FSGTM_HOME`)
-4. **Broker pairing** — `fullstackgtm login --via <hosted url>`: the team's deployment holds the CRM credentials; the CLI holds only a revocable pairing token
+2. **`HUBSPOT_ACCESS_TOKEN` / Salesforce env** — ambient env (CI)
+3. **BYO direct login** — advanced token/OAuth paths stored in `~/.fullstackgtm/credentials.json` (0600; override location with `FSGTM_HOME`); these override hosted
+4. **Hosted OAuth / broker** — `fullstackgtm login hubspot` or `fullstackgtm login salesforce` opens hosted browser OAuth by default, stores only a broker credential locally, and mints provider tokens server-side
 
 ### Teams: auth once, point every CLI at the stored sync credentials
 
@@ -337,22 +342,26 @@ An admin connects HubSpot **once** in the hosted dashboard (the org's OAuth toke
 
 **Run observability (paired CLIs).** Once paired, each command best-effort reports a run record — command, status (`success`/`partial`/`error`), duration, headline counts (e.g. ops emitted, leads created, est. cost), and structured events (plan saved, meter charged) — to the deployment's **run timeline** in the dashboard. It's opt-in by pairing (an unpaired CLI sends nothing), a 4-second-capped POST that swallows every error, and never changes the command's exit code. Setup/inspection verbs (`login`, `doctor`, `help`, `--version`) are skipped.
 
-### Individuals: no deployment needed
+### Individuals: hosted OAuth by default, BYO still available
 
 ```bash
-# HubSpot, zero web flow: paste a private app token once (validated, then stored)
+# Default: hosted first-party OAuth. No provider app or provider secret in the npm package.
 fullstackgtm login hubspot
+fullstackgtm login salesforce
+# optional: point at a self-hosted/team deployment
+fullstackgtm login hubspot --hosted --via https://gtm.yourco.com
+
+# Advanced HubSpot private app token (validated, then stored; token on stdin).
+# Note: hosted HubSpot OAuth covers reads and object writes but cannot create
+# tasks (HubSpot exposes no tasks scope to public apps) — use a private-app
+# token if your workflow relies on `create_task` proposals.
+echo "$HUBSPOT_TOKEN" | fullstackgtm login hubspot --private-token
 
-# HubSpot, bring-your-own-app OAuth. The browser is used exactly once — the
-# consent grant — captured on a 127.0.0.1 loopback (RFC 8252); the CLI
-# exchanges the code itself and refreshes silently from then on. The client
-# secret is read from stdin or an interactive prompt — never as a flag.
+# Advanced HubSpot BYO-app OAuth. Client secret is read from stdin/prompt — never a flag.
 echo "$CLIENT_SECRET" | fullstackgtm login hubspot --oauth --client-id <id>
 #   (register http://localhost:8763/callback as a redirect URL on your app)
 
-# Salesforce: native device flow — confirm a code on any device, no localhost
-# server, no client secret, silent refresh. Needs a Connected App consumer key
-# with device flow enabled (see "Connect your CRM" below).
+# Advanced Salesforce BYO Connected App device flow.
 fullstackgtm login salesforce --device --client-id <consumer key>
 # ...or a session token directly (token on stdin, never as a flag):
 echo "$SF_SESSION_TOKEN" | fullstackgtm login salesforce --instance-url https://yourorg.my.salesforce.com
@@ -360,7 +369,7 @@ echo "$SF_SESSION_TOKEN" | fullstackgtm login salesforce --instance-url https://
 fullstackgtm logout hubspot   # or: salesforce | broker
 ```
 
-A direct `login hubspot` always wins over a broker pairing, so an operator can override the team default. HubSpot does not support the device-authorization grant or secretless public clients, which is why the bring-your-own-app OAuth path requires client credentials; they are stored locally for silent refresh, the same model as `gcloud` and `aws` CLI profiles.
+BYO direct credentials always win over a hosted broker pairing, so an operator can override the team default. First-party app secrets never ship in the npm package; hosted login stores a local broker token and mints provider tokens server-side. HubSpot does not support the device-authorization grant or secretless public clients, which is why the bring-your-own-app OAuth path requires client credentials; they are stored locally for silent refresh, the same model as `gcloud` and `aws` CLI profiles.
 
 ## Connect your CRM
 
@@ -389,7 +398,7 @@ Connectors differ in what the provider's API allows — stated up front so nothi
    - `crm.objects.contacts.read`
    - `crm.objects.deals.read`
 3. If you plan to **apply** approved operations (not just audit), also grant write scopes for the objects you'll let it touch: `crm.objects.deals.write` (covers `deal.next_step` and other deal fields), plus `crm.objects.contacts.write` / `crm.objects.companies.write` for contact/company patches, and the **Tasks** write scope for `create_task` operations (search "tasks" in the scope picker; naming varies by portal).
-4. Create the app, copy the token (`pat-...`), then: `echo "$TOKEN" | fullstackgtm login hubspot`.
+4. Create the app, copy the token (`pat-...`), then: `echo "$TOKEN" | fullstackgtm login hubspot --private-token`.
 
 If a scope is missing you'll see a `403` mid-run whose body names the exact missing scope (`requiredGranularScopes`) — add it to the private app and re-run. Note that `login` only validates the token itself; it can't tell whether every scope you'll need is granted.
 
@@ -418,7 +427,7 @@ This is a **short-lived session token with no refresh** — ideal for a one-off
 
 ### Stripe: a restricted key is enough (read-only connector)
 
-The Stripe connector only reads customers and subscriptions, and `apply` is read-only by construction. Create a **restricted key** with just **Customers: Read** and **Subscriptions: Read** (Developers → API keys → Create restricted key) instead of pasting a full-access secret key: `echo "$KEY" | fullstackgtm login stripe`.
+The Stripe connector reads customers, subscriptions, and paid invoices (`backfill stripe` calls `/v1/invoices`), and `apply` is read-only by construction. Create a **restricted key** with just **Customers: Read**, **Subscriptions: Read**, and **Invoices: Read** (Developers → API keys → Create restricted key) instead of pasting a full-access secret key: `echo "$KEY" | fullstackgtm login stripe`.
 
 ## Concepts
 

package/dist/backfill.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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 { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
+import type { StripePaidInvoice } from "./connectors/stripe.ts";
+export declare const DEFAULT_BACKFILL_MATCH_PROPERTY = "stripe_invoice_id";
+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[];
+};
+/**
+ * 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 declare function buildStripeBackfillPlan(invoices: StripePaidInvoice[], snapshot: CanonicalGtmSnapshot, opts?: StripeBackfillOptions): StripeBackfillResult;

package/dist/backfill.js

@@ -0,0 +1,251 @@
+/**
+ * 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 { normalizeDomain } from "./merge.js";
+// 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) {
+    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",
+]);
+/** `Invoice <number || id> — <customer name>` (the plan-time dedupe name). */
+function backfillDealName(invoice, companyName) {
+    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, snapshot, opts = {}) {
+    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();
+    const accountsByName = new Map();
+    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) => Boolean(name)));
+    const createMissingAccounts = opts.createMissingAccounts ?? true;
+    const operations = [];
+    const evidence = [];
+    const unmatched = [];
+    const proposedByKey = new Map();
+    const counts = {
+        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 = 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 = {
+            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 = {
+                    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 = {
+            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 = {
+        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/dist/bin.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 import { runCli } from "./cli.js";
-import { flushRunReport } from "./runReport.js";
+import { beginRunReport, flushRunReport } from "./runReport.js";
 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":