fullstackgtm 0.37.0 → 0.38.0

package/CHANGELOG.md

@@ -5,6 +5,56 @@ 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).
 
+## [Unreleased]
+
+## [0.38.0] — 2026-06-23
+
+### Added
+
+- **CLI run observability — paired CLIs report each run to the hosted dashboard.**
+  When the CLI is paired (`login --via <hosted url>`), a best-effort run record —
+  command, status (`success`/`partial`/`error`), duration, headline counts, and
+  structured events (plan saved, meter charged) — is POSTed to the deployment's
+  run timeline after each command (`runReport.ts`: `reportCounts` / `reportEvent`
+  / `flushRunReport`). Opt-in by pairing (an unpaired CLI sends nothing), 4s-capped,
+  swallows every error, and never affects the command's exit code; setup/inspection
+  verbs (`login`, `doctor`, `help`, `--version`) are skipped. The hosted dashboard
+  re-maps onto these runs (`/dashboard/runs`).
+
+- **Lead assignment — acquired leads are never born ownerless.** A shared
+  `AssignmentPolicy` (`assign.ts`: `fixed` / `round-robin` / `territory` /
+  `account-owner`) routes an owner onto every record, consumed in two places:
+  - **`enrich acquire`** stamps the resolved owner into each `create_record`
+    payload (`EnrichConfig.acquire.assign`); the HubSpot connector maps it to
+    `hubspot_owner_id` at create time. Round-robin distributes by the within-run
+    index (deterministic, no persisted cursor); every result is gated by the
+    snapshot's active owners, so an unknown/inactive owner collapses to
+    unassigned rather than writing a bad owner. The CLI defaults to the portal's
+    sole active owner when no policy is set (or `--assign-owner <id>`), and warns
+    + leaves leads unassigned when several owners exist and no policy says how to
+    route. `AcquireCounts` now reports `assigned` / `unassigned`.
+  - **`reassign --assign-unowned --to <ownerId>`** claims every existing
+    ownerless record (`ownerId:empty`) for an owner — the backfill twin of
+    acquire's create-time assignment.
+
+- **`enrich acquire --source linkedin` — governed LinkedIn lead acquisition
+  (Phase 1, discovery + dry-run).** LinkedIn is a new discovery source on the
+  existing acquire spine: it reads a pre-built **HeyReach** lead list
+  (`--list <id>` or `acquire.discovery.linkedin.listId`), normalizes leads to
+  the canonical `Prospect` type, then reuses ICP scoring, pre-email dedup, the
+  acquire meter, and the dry-run → approve → apply gate unchanged. The LinkedIn
+  profile URL is the match key; cost is `$0`/record (the list is already built).
+  - **`LinkedInProvider`** interface (`connectors/linkedin.ts`) with a default
+    **HeyReach** adapter (`HEYREACH_BASE`, `X-API-KEY`) and a
+    `FakeLinkedInProvider` so the whole pipeline runs with no key and no network.
+    `createLinkedInProvider` rejects unknown providers (`heyreach` only for now;
+    `unipile` is the planned alternative behind the same interface).
+  - Auth: `login heyreach` or `HEYREACH_API_KEY`.
+  - **Read-only / no sending.** Phase 1 is discovery only — no
+    `linkedin_connect` / `linkedin_message` operations, no webhook ingestion
+    (Phase 2). Without `--save` nothing is written and there is zero send/ToS
+    exposure.
+
 ## [0.37.0] — 2026-06-19
 
 ### Added

package/INSTALL_FOR_AGENTS.md

@@ -69,6 +69,14 @@ the environment, or have the human run `echo "$KEY" | fullstackgtm login apollo`
 once. Without it, `enrich ingest <file> --source clay` still stages push-style
 data keyless.
 
+`enrich acquire` differs from `append`/`refresh`: instead of filling blanks on
+existing records it creates net-new, ICP-targeted leads via governed
+`create_record` plans (resolve-first dedupe re-checks the key at apply, never
+double-creates) and is capped by a per-profile windowed meter bounding record
+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`);

package/README.md

@@ -128,6 +128,7 @@ fullstackgtm bulk-update deal --where "stage=closedwon" --where "amount:empty" \
   --set amount=from:account.annualrevenue --save     # per-record derived values; empty sources skipped, never guessed
 fullstackgtm dedupe account --key domain --keep richest --save   # one merge_records op per duplicate group
 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
 ```
 
@@ -194,6 +195,17 @@ The **ICP** (`icp.json`) is the single targeting artifact: it generates each pro
 
 Every run is **metered**: a per-profile budget caps both record count and provider spend (per-day + per-month, whichever binds first), charged only for creates that actually land. `enrich acquire` runs with just an `icp.json` and a `login` — sensible defaults for budget, provider, and create-mapping ship in the box.
 
+**Discovery sources** are zero-config presets behind `--source`: `explorium` and `pipe0` run ICP-driven people search, while `linkedin` (Phase 1 — discovery + dry-run) reads a pre-built **HeyReach** lead list:
+
+```bash
+echo "$HEYREACH_API_KEY" | fullstackgtm login heyreach        # or set HEYREACH_API_KEY
+fullstackgtm enrich acquire --source linkedin --list <listId> --provider hubspot   # score → dedup → dry-run diff
+```
+
+LinkedIn is just another discovery source on the same scored → deduped → metered → dry-run→approve→apply spine; the LinkedIn profile URL is the match key and the list costs `$0`/record. **It never sends** — connect/message operations are out of scope for Phase 1, so without `--save` there is zero send/ToS exposure.
+
+**Leads are never born ownerless.** An `acquire.assign` policy stamps an owner onto every created lead at create time (mapped to HubSpot `hubspot_owner_id`), routed by one of four strategies — `fixed`, `round-robin` (distributed deterministically, no rotation state to drift), `territory` (by geo / industry / size / department / title), or `account-owner` (inherit the matched company's owner). With no policy and a single-owner portal, acquire defaults every lead to that owner (or pass `--assign-owner <id>`); with multiple owners and no policy it warns and leaves them unassigned rather than guess. To clear *existing* ownerless records, `reassign --assign-unowned --to <ownerId>` applies the same intent as a backfill.
+
 ## Schedules: declare a cadence once, keep the governance contract under automation
 
 Everything the CLI produces is accurate the moment it runs and silently stale afterward. The **schedule layer** is the horizontal fix — any read/plan-side command on a cron cadence, one component, every verb (no feature owns its own cron logic):
@@ -271,6 +283,8 @@ fullstackgtm login --via https://gtm.yourco.com
 
 An admin connects HubSpot **once** in the hosted dashboard (the org's OAuth tokens live encrypted in the deployment). Pairing a CLI is a device-flow handshake: the CLI prints a code, an admin or manager approves it in the dashboard, and the CLI receives a long-lived broker token (stored hashed server-side, revocable per CLI). From then on, every provider command silently exchanges the broker token for a short-lived CRM access token minted from the org's stored sync credentials — and inherits the org's field mappings. No one pastes CRM tokens; revoking a laptop is one row.
 
+**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
 
 ```bash

package/dist/acquireLinkedIn.d.ts

@@ -0,0 +1,41 @@
+/**
+ * LinkedIn → acquire bridge (Phase 1, step 2).
+ *
+ * Connects the provider-agnostic LinkedIn discovery layer (connectors/linkedin.ts)
+ * to the `enrich acquire` spine: pull prospects from a LinkedIn source, map them
+ * to the canonical `Prospect`, and hand them to the existing ICP-score → dedup →
+ * create_record → meter → dry-run/apply pipeline unchanged.
+ *
+ * Kept out of cli.ts on purpose: the only remaining wiring is a ~3-line
+ * discovery branch in `acquireFromApi` (call `createLinkedInProvider` +
+ * `discoverLinkedInProspects`), a `builtinAcquirePreset('linkedin')` entry, the
+ * source allowlist/help, and a `login heyreach` credential. That lands once
+ * cli.ts is clean of other in-flight work — see docs/linkedin-connector-spec.md.
+ *
+ * HeyReach reads a pre-populated lead LIST (not an ICP-driven search), and the
+ * natural identity key is the LinkedIn profile URL — so acquire's matchKey is
+ * `linkedin`, which means the spine skips pipe0 email resolution automatically.
+ */
+import { type HeyReachProviderOptions, type LinkedInProspect, type LinkedInProvider } from "./connectors/linkedin.ts";
+import type { Prospect } from "./connectors/prospectSources.ts";
+/** Map a normalized LinkedIn prospect into the canonical acquire `Prospect`. */
+export declare function linkedInProspectToProspect(lp: LinkedInProspect): Prospect;
+export type DiscoverLinkedInOptions = {
+    /** Which source (HeyReach lead-list id) to read; provider may have a default. */
+    sourceId?: string;
+    /** Hard cap on prospects pulled. */
+    max?: number;
+};
+/**
+ * Discovery branch for `acquireFromApi`: read prospects from a LinkedIn source
+ * and return them as canonical `Prospect`s. Read-only — never sends. The
+ * provider is injected so this is fully testable against the fake (no key).
+ */
+export declare function discoverLinkedInProspects(provider: LinkedInProvider, options?: DiscoverLinkedInOptions): Promise<Prospect[]>;
+export type CreateLinkedInProviderOptions = Omit<HeyReachProviderOptions, "apiKey">;
+/**
+ * Build the execution provider for a LinkedIn acquire source. HeyReach is the
+ * default; `unipile` is the planned alternative (same interface). Called by the
+ * cli acquire branch with the stored/env API key.
+ */
+export declare function createLinkedInProvider(source: string, apiKey: string, options?: CreateLinkedInProviderOptions): LinkedInProvider;

package/dist/acquireLinkedIn.js

@@ -0,0 +1,57 @@
+/**
+ * LinkedIn → acquire bridge (Phase 1, step 2).
+ *
+ * Connects the provider-agnostic LinkedIn discovery layer (connectors/linkedin.ts)
+ * to the `enrich acquire` spine: pull prospects from a LinkedIn source, map them
+ * to the canonical `Prospect`, and hand them to the existing ICP-score → dedup →
+ * create_record → meter → dry-run/apply pipeline unchanged.
+ *
+ * Kept out of cli.ts on purpose: the only remaining wiring is a ~3-line
+ * discovery branch in `acquireFromApi` (call `createLinkedInProvider` +
+ * `discoverLinkedInProspects`), a `builtinAcquirePreset('linkedin')` entry, the
+ * source allowlist/help, and a `login heyreach` credential. That lands once
+ * cli.ts is clean of other in-flight work — see docs/linkedin-connector-spec.md.
+ *
+ * HeyReach reads a pre-populated lead LIST (not an ICP-driven search), and the
+ * natural identity key is the LinkedIn profile URL — so acquire's matchKey is
+ * `linkedin`, which means the spine skips pipe0 email resolution automatically.
+ */
+import { createHeyReachProvider, } from "./connectors/linkedin.js";
+/** Map a normalized LinkedIn prospect into the canonical acquire `Prospect`. */
+export function linkedInProspectToProspect(lp) {
+    return {
+        firstName: lp.firstName || undefined,
+        lastName: lp.lastName || undefined,
+        fullName: lp.fullName,
+        // Title drives ICP scoring; fall back to the headline when no title is set.
+        jobTitle: lp.jobTitle ?? lp.headline,
+        companyName: lp.company,
+        linkedin: lp.profileUrl || undefined,
+        email: lp.email,
+        // The profile URL is LinkedIn's stable native id — use it for traceability.
+        sourceId: lp.profileUrl || undefined,
+    };
+}
+/**
+ * Discovery branch for `acquireFromApi`: read prospects from a LinkedIn source
+ * and return them as canonical `Prospect`s. Read-only — never sends. The
+ * provider is injected so this is fully testable against the fake (no key).
+ */
+export async function discoverLinkedInProspects(provider, options = {}) {
+    const raw = await provider.fetchProspects({ sourceId: options.sourceId, max: options.max });
+    return raw.map(linkedInProspectToProspect);
+}
+/**
+ * Build the execution provider for a LinkedIn acquire source. HeyReach is the
+ * default; `unipile` is the planned alternative (same interface). Called by the
+ * cli acquire branch with the stored/env API key.
+ */
+export function createLinkedInProvider(source, apiKey, options = {}) {
+    switch (source) {
+        case "linkedin":
+        case "heyreach":
+            return createHeyReachProvider({ apiKey, ...options });
+        default:
+            throw new Error(`Unknown LinkedIn execution provider "${source}" (supported: heyreach).`);
+    }
+}

package/dist/assign.d.ts

@@ -0,0 +1,83 @@
+/**
+ * AssignmentPolicy — the shared rule that decides which owner a record belongs
+ * to. One policy, two consumers:
+ *   1. `enrich acquire` stamps the resolved owner into each `create_record`
+ *      payload, so a lead is never born ownerless, and
+ *   2. `reassign --assign-unowned` applies the SAME policy to backfill existing
+ *      ownerless records.
+ *
+ * Pure + zero-dep: `resolveAssignment` takes plain data (the record's routing
+ * attributes + the candidate owners + the within-run index) and returns an
+ * ownerId or null. Round-robin distributes by the within-run index, so it needs
+ * no persisted rotation cursor — the same plan always resolves the same way
+ * (deterministic apply). Every result is gated by the set of KNOWN active
+ * owners: a policy that points at an unknown or inactive owner yields null, and
+ * the caller leaves that record unassigned + surfaces it — never a bad write.
+ */
+export type AssignmentStrategy = "fixed" | "round-robin" | "territory" | "account-owner";
+/** The attributes a territory rule can route on, lifted from a record/prospect. */
+export type AssignmentContext = {
+    /** ISO country code, lowercased (e.g. "us"). */
+    geo?: string;
+    /** human industry label, lowercased (e.g. "software"). */
+    industry?: string;
+    /** provider-agnostic employee band (e.g. "11-50"). */
+    employeeBand?: string;
+    /** department, lowercased (e.g. "sales"). */
+    department?: string;
+    /** raw job title, lowercased — matched against rule titleKeywords as substrings. */
+    title?: string;
+    /** owner of the associated account, if any — enables "account-owner" inherit. */
+    accountOwnerId?: string;
+};
+/**
+ * One territory clause. Every present key must match (AND across keys); within a
+ * key the candidate value must be one of the listed values (OR). `titleKeywords`
+ * matches when the context title CONTAINS any keyword as a substring.
+ */
+export type TerritoryRule = {
+    when: Partial<{
+        geo: string[];
+        industry: string[];
+        employeeBand: string[];
+        department: string[];
+        titleKeywords: string[];
+    }>;
+    ownerId: string;
+};
+export type AssignmentPolicy = {
+    strategy: "fixed";
+    ownerId: string;
+} | {
+    strategy: "round-robin";
+    ownerIds: string[];
+} | {
+    strategy: "territory";
+    rules: TerritoryRule[];
+    fallbackOwnerId?: string;
+} | {
+    strategy: "account-owner";
+    fallbackOwnerId?: string;
+};
+export type AssignmentResult = {
+    /** the resolved owner, or null when the policy can't place this record. */
+    ownerId: string | null;
+    /** short human label for why (audit trail): "fixed", "round-robin", "territory:0", "account-owner", "fallback". */
+    rule?: string;
+};
+/**
+ * Validate + normalize a raw assignment policy (from enrich.config.json or a
+ * CLI flag). Throws on shape errors so a misconfigured policy fails loud at
+ * plan time, never silently mis-routes.
+ */
+export declare function parseAssignmentPolicy(raw: unknown): AssignmentPolicy;
+/** Does the context satisfy every present clause of a territory rule? */
+export declare function matchesTerritory(rule: TerritoryRule, ctx: AssignmentContext): boolean;
+/**
+ * Resolve the owner for one record. `index` is the record's 0-based position
+ * within the run (used by round-robin for deterministic, even within-run
+ * distribution without persisted state). `knownOwnerIds` is the set of active
+ * owners from the snapshot; any result outside it collapses to null so callers
+ * never write an owner the CRM won't accept.
+ */
+export declare function resolveAssignment(policy: AssignmentPolicy, ctx: AssignmentContext, index: number, knownOwnerIds: ReadonlySet<string>): AssignmentResult;

package/dist/assign.js

@@ -0,0 +1,146 @@
+/**
+ * AssignmentPolicy — the shared rule that decides which owner a record belongs
+ * to. One policy, two consumers:
+ *   1. `enrich acquire` stamps the resolved owner into each `create_record`
+ *      payload, so a lead is never born ownerless, and
+ *   2. `reassign --assign-unowned` applies the SAME policy to backfill existing
+ *      ownerless records.
+ *
+ * Pure + zero-dep: `resolveAssignment` takes plain data (the record's routing
+ * attributes + the candidate owners + the within-run index) and returns an
+ * ownerId or null. Round-robin distributes by the within-run index, so it needs
+ * no persisted rotation cursor — the same plan always resolves the same way
+ * (deterministic apply). Every result is gated by the set of KNOWN active
+ * owners: a policy that points at an unknown or inactive owner yields null, and
+ * the caller leaves that record unassigned + surfaces it — never a bad write.
+ */
+const STRATEGIES = ["fixed", "round-robin", "territory", "account-owner"];
+function asStringArray(value, label) {
+    if (!Array.isArray(value) || value.length === 0 || value.some((v) => typeof v !== "string" || !v.trim())) {
+        throw new Error(`assign: ${label} must be a non-empty array of strings`);
+    }
+    return value.map((v) => v.trim());
+}
+/**
+ * Validate + normalize a raw assignment policy (from enrich.config.json or a
+ * CLI flag). Throws on shape errors so a misconfigured policy fails loud at
+ * plan time, never silently mis-routes.
+ */
+export function parseAssignmentPolicy(raw) {
+    if (!raw || typeof raw !== "object")
+        throw new Error("assign: expected a policy object");
+    const p = raw;
+    const strategy = p.strategy;
+    if (typeof strategy !== "string" || !STRATEGIES.includes(strategy)) {
+        throw new Error(`assign: "strategy" must be one of ${STRATEGIES.join(" | ")}`);
+    }
+    switch (strategy) {
+        case "fixed": {
+            if (typeof p.ownerId !== "string" || !p.ownerId.trim()) {
+                throw new Error('assign: fixed strategy needs a non-empty "ownerId"');
+            }
+            return { strategy, ownerId: p.ownerId.trim() };
+        }
+        case "round-robin": {
+            const ownerIds = asStringArray(p.ownerIds, "round-robin ownerIds");
+            return { strategy, ownerIds };
+        }
+        case "territory": {
+            if (!Array.isArray(p.rules) || p.rules.length === 0) {
+                throw new Error('assign: territory strategy needs a non-empty "rules" array');
+            }
+            const rules = p.rules.map((r, i) => {
+                if (!r || typeof r !== "object")
+                    throw new Error(`assign: territory rule ${i} must be an object`);
+                const rule = r;
+                if (typeof rule.ownerId !== "string" || !rule.ownerId.trim()) {
+                    throw new Error(`assign: territory rule ${i} needs a non-empty "ownerId"`);
+                }
+                const whenRaw = (rule.when ?? {});
+                const when = {};
+                for (const key of ["geo", "industry", "employeeBand", "department", "titleKeywords"]) {
+                    if (whenRaw[key] !== undefined)
+                        when[key] = asStringArray(whenRaw[key], `territory rule ${i} when.${key}`);
+                }
+                if (Object.keys(when).length === 0) {
+                    throw new Error(`assign: territory rule ${i} "when" needs at least one clause (else it matches everything — use a fallbackOwnerId instead)`);
+                }
+                return { when, ownerId: rule.ownerId.trim() };
+            });
+            const fallbackOwnerId = typeof p.fallbackOwnerId === "string" && p.fallbackOwnerId.trim() ? p.fallbackOwnerId.trim() : undefined;
+            return { strategy, rules, ...(fallbackOwnerId ? { fallbackOwnerId } : {}) };
+        }
+        case "account-owner": {
+            const fallbackOwnerId = typeof p.fallbackOwnerId === "string" && p.fallbackOwnerId.trim() ? p.fallbackOwnerId.trim() : undefined;
+            return { strategy, ...(fallbackOwnerId ? { fallbackOwnerId } : {}) };
+        }
+        default:
+            throw new Error(`assign: unsupported strategy "${strategy}"`);
+    }
+}
+function clauseMatches(values, candidate) {
+    if (candidate === undefined)
+        return false;
+    return values.some((v) => v.toLowerCase() === candidate.toLowerCase());
+}
+function titleMatches(keywords, title) {
+    if (!title)
+        return false;
+    const lower = title.toLowerCase();
+    return keywords.some((k) => lower.includes(k.toLowerCase()));
+}
+/** Does the context satisfy every present clause of a territory rule? */
+export function matchesTerritory(rule, ctx) {
+    const { when } = rule;
+    if (when.geo && !clauseMatches(when.geo, ctx.geo))
+        return false;
+    if (when.industry && !clauseMatches(when.industry, ctx.industry))
+        return false;
+    if (when.employeeBand && !clauseMatches(when.employeeBand, ctx.employeeBand))
+        return false;
+    if (when.department && !clauseMatches(when.department, ctx.department))
+        return false;
+    if (when.titleKeywords && !titleMatches(when.titleKeywords, ctx.title))
+        return false;
+    return true;
+}
+/** Gate a candidate ownerId by the known-active set: returns it, or null. */
+function known(ownerId, knownOwnerIds) {
+    return ownerId && knownOwnerIds.has(ownerId) ? ownerId : null;
+}
+/**
+ * Resolve the owner for one record. `index` is the record's 0-based position
+ * within the run (used by round-robin for deterministic, even within-run
+ * distribution without persisted state). `knownOwnerIds` is the set of active
+ * owners from the snapshot; any result outside it collapses to null so callers
+ * never write an owner the CRM won't accept.
+ */
+export function resolveAssignment(policy, ctx, index, knownOwnerIds) {
+    switch (policy.strategy) {
+        case "fixed":
+            return { ownerId: known(policy.ownerId, knownOwnerIds), rule: "fixed" };
+        case "round-robin": {
+            const pool = policy.ownerIds.filter((id) => knownOwnerIds.has(id));
+            if (pool.length === 0)
+                return { ownerId: null, rule: "round-robin" };
+            const safeIndex = ((index % pool.length) + pool.length) % pool.length;
+            return { ownerId: pool[safeIndex], rule: "round-robin" };
+        }
+        case "territory": {
+            for (let i = 0; i < policy.rules.length; i++) {
+                if (matchesTerritory(policy.rules[i], ctx)) {
+                    const hit = known(policy.rules[i].ownerId, knownOwnerIds);
+                    if (hit)
+                        return { ownerId: hit, rule: `territory:${i}` };
+                }
+            }
+            return { ownerId: known(policy.fallbackOwnerId, knownOwnerIds), rule: "fallback" };
+        }
+        case "account-owner": {
+            const inherited = known(ctx.accountOwnerId, knownOwnerIds);
+            if (inherited)
+                return { ownerId: inherited, rule: "account-owner" };
+            return { ownerId: known(policy.fallbackOwnerId, knownOwnerIds), rule: "fallback" };
+        }
+    }
+}

package/dist/bin.js

@@ -1,6 +1,18 @@
 #!/usr/bin/env node
 import { runCli } from "./cli.js";
-runCli(process.argv.slice(2)).catch((error) => {
-    console.error(error instanceof Error ? error.message : String(error));
+import { flushRunReport } from "./runReport.js";
+const args = process.argv.slice(2);
+const startedAt = Date.now();
+runCli(args)
+    .then(async () => {
+    // exitCode 2 (audit findings / create-gate) or 1 (no value) = "partial":
+    // the command ran but flagged something. No exitCode = clean success.
+    const status = process.exitCode && process.exitCode !== 0 ? "partial" : "success";
+    await flushRunReport(args, status, startedAt);
+})
+    .catch(async (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    await flushRunReport(args, "error", startedAt, message);
+    console.error(message);
     process.exitCode = 1;
 });