@agent-finops/core 0.8.1 → 0.9.1

package/dist/providerConnectors.d.ts

@@ -82,6 +82,64 @@ export type ProviderConnectorInput = {
     accountId?: string;
     fetcher?: Fetcher;
     tokenResolver?: TokenResolver;
+    /**
+     * Operator-declared reconciliation anchor for this sync. Today only the
+     * Cursor connector consumes it; when absent, the Cursor connector also
+     * accepts the AI_SPEND_CURSOR_RECONCILE_* environment variables so the
+     * shipped CLI can run a reconciliation without new flags.
+     */
+    reconciliation?: CursorReconciliationExpectation;
+};
+/**
+ * A human-read billing anchor for one Cursor reconciliation run: the
+ * on-demand ("usage based pricing") total the operator read off the Cursor
+ * team dashboard or invoice for the CURRENT subscription cycle. The connector
+ * compares its own summed spendCents against this figure; only an in-run
+ * match within tolerance can produce verified financial evidence.
+ */
+export type CursorReconciliationExpectation = {
+    /** Dashboard/invoice on-demand total for the current cycle, in USD. */
+    expectedOnDemandUsd: number;
+    /**
+     * The billing-cycle start date shown next to that figure (YYYY-MM-DD).
+     * Must land within one calendar day of the UTC date of the API's
+     * subscriptionCycleStart, proving both numbers describe the same window.
+     */
+    expectedCycleStartDate: string;
+    /**
+     * Optional absolute comparison tolerance in USD. Defaults to $0.01 (the
+     * dashboard rounds to cents). Clamped to at most 1% of the expected total
+     * so a huge tolerance can never rubber-stamp a mismatch.
+     */
+    toleranceUsd?: number;
+};
+export type CursorReconciliationOutcome = {
+    status: "verified" | "mismatch" | "not_provable";
+    /** Product-authored, terminal-safe explanation of the outcome. */
+    note: string;
+    connectorTotalUsd?: number;
+    expectedOnDemandUsd?: number;
+    differenceUsd?: number;
+    toleranceUsd?: number;
+    /** Provider-reported cycle start for the reconciled window, ISO-8601. */
+    cycleStartIso?: string;
+};
+/** Environment variables the Cursor connector reads for a reconciliation run. */
+export declare const cursorReconciliationEnvVars: {
+    readonly expectedUsd: "AI_SPEND_CURSOR_RECONCILE_EXPECTED_USD";
+    readonly cycleStart: "AI_SPEND_CURSOR_RECONCILE_CYCLE_START";
+    readonly toleranceUsd: "AI_SPEND_CURSOR_RECONCILE_TOLERANCE_USD";
+};
+/**
+ * Read an operator-declared Cursor reconciliation anchor from the local
+ * environment. Absent variables mean "no reconciliation requested"; present
+ * but invalid variables fail closed with a reason (records stay estimated)
+ * instead of throwing, so a typo can never abort or silently verify a sync.
+ * Raw variable values are never echoed into the reason.
+ */
+export declare function parseCursorReconciliationEnv(env?: Record<string, string | undefined>): {
+    expectation?: CursorReconciliationExpectation;
+    invalidReason?: string;
 };
 export type ProviderConnectorResult = {
     provider: string;
@@ -121,7 +179,7 @@ export declare function normalizeAnthropicClaudeCodeUsageResponse(response: unkn
 export declare function normalizeGitHubCopilotSeatResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
 export declare function normalizeAnthropicCostResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
 export declare function normalizeGitHubCopilotMetricsResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
-export declare function normalizeCursorSpendResponse(response: unknown, options: NormalizerOptions): UsageRecord[];
+export declare function normalizeCursorSpendResponse(response: unknown, options: NormalizerOptions, reconciliation?: CursorReconciliationOutcome): UsageRecord[];
 export declare function fetchProviderUsageRecords(input: ProviderConnectorInput): Promise<ProviderConnectorResult>;
 export declare function summarizeProviderFinancials(records: UsageRecord[]): ProviderFinancialSummary;
 export declare function providerFinancialCompleteness(records: UsageRecord[], coverage: ProviderCoverageStatus): ProviderConnectorResult["completeness"];
@@ -131,6 +189,108 @@ export declare function providerFinancialCompleteness(records: UsageRecord[], co
  * spend headlines; callers should retain the original records for attribution.
  */
 export declare function selectProviderFinancialHeadlineRecords(records: UsageRecord[]): UsageRecord[];
+/** Inputs that determine which provider account (org/team) one sync reads. */
+export type ProviderAccountKeyInput = {
+    provider: string;
+    authReference: string;
+    org?: string;
+    enterprise?: string;
+    accountId?: string;
+};
+/**
+ * Stable identity for one provider account (an OpenAI/Anthropic organization,
+ * a Cursor team, a GitHub org/enterprise). Admin credentials are account-
+ * scoped and multi-account setups are common, so records from different
+ * accounts of one provider must coexist instead of replacing each other.
+ *
+ * The key prefers the explicit account flag the connector already requires
+ * (--org/--enterprise/--account-id, which can share one credential); it
+ * otherwise falls back to the user-chosen credential REFERENCE NAME
+ * (e.g. "env:OPENAI_ADMIN_KEY_ORG2") — stable, printable, and never derived
+ * from secret material. A provider-reported organization id would be
+ * preferable, but the cost APIs aibill calls do not reliably return one
+ * (the OpenAI costs request groups by project/line-item/api-key only), and a
+ * sometimes-present key would split one account into two slices.
+ */
+export declare function providerAccountKey(input: ProviderAccountKeyInput): string;
+/** The deterministic record-id prefix for one account slice. */
+export declare function providerAccountRecordIdPrefix(accountKey: string): string;
+/**
+ * Stamp one sync's records with their account slice. The record id gains a
+ * deterministic account prefix (slug + raw-key digest) so identical usage
+ * buckets from two accounts of the same provider can never collide into one
+ * row id — even for slug-equivalent account spellings — and re-syncing the
+ * same account regenerates the same ids (idempotent replace).
+ *
+ * Migration note: slices tagged by the short-lived pre-digest format
+ * (slug-only prefix) are superseded on their next re-sync — same-account
+ * replacement keys on `source.account`, never on id shape — and any
+ * colliding pre-digest rows already persisted are excluded fail-closed by
+ * the id-conflict guard in {@link retainProviderRecordsForNewSync}.
+ */
+export declare function tagProviderAccountRecords(records: readonly UsageRecord[], accountKey: string): UsageRecord[];
+/**
+ * Records from a prior trusted snapshot that must survive a new sync of
+ * `provider` + `accountKey`: every other provider's records, plus this
+ * provider's records that belong to a DIFFERENT named account slice.
+ * Re-syncing the same account replaces its own slice. Records with no account
+ * label (synced before multi-account support) are replaced too — fail-closed:
+ * they cannot be proven to come from a different account, and keeping them
+ * could double-count the same organization.
+ *
+ * Id-conflict guard: a retained record may never share an id with a newly
+ * synced record, nor with another retained record. Colliding ids describe
+ * the same underlying row (possible only in state written by the pre-digest
+ * prefix format, where slug-equivalent account spellings collided) — keeping
+ * both would double-count, so the copy that is not part of the fresh sync is
+ * dropped fail-closed.
+ */
+export declare function retainProviderRecordsForNewSync(priorRecords: readonly UsageRecord[], provider: string, accountKey: string, syncedRecords: readonly UsageRecord[]): UsageRecord[];
+export type ProviderAccountSlice = {
+    /** Account key, or null for records synced before multi-account support. */
+    account: string | null;
+    recordCount: number;
+    /** Sum of this slice's verified provider-billed rows; null when none. */
+    billedUsd: number | null;
+};
+/** Group one provider's records into per-account slices for honest display. */
+export declare function providerAccountSlices(records: readonly UsageRecord[], provider: string): ProviderAccountSlice[];
+/**
+ * Detect the same organization synced under two different references: when
+ * two named slices of one provider hold IDENTICAL inner record ids (the ids
+ * modulo their account prefixes), the provider almost certainly returned the
+ * same data twice and the combined total double-counts. This is an honest
+ * diagnostic, not a silent fix — the user chose both identities, so the user
+ * removes one.
+ */
+export declare function duplicateProviderAccountSliceWarnings(records: readonly UsageRecord[], provider: string): string[];
+/**
+ * Honest notices for prior records a sync removed. Replacement is fail-closed
+ * by design (unlabeled legacy rows, same-slice re-sync, id-collision guard),
+ * but billed dollars must never disappear without a word: each dropped slice
+ * is named with its record count and billed sum. A routine same-slice re-sync
+ * that returns the same or more billed evidence stays quiet.
+ */
+export declare function providerSliceReplacementNotices(input: {
+    provider: string;
+    accountKey: string;
+    priorRecords: readonly UsageRecord[];
+    retainedRecords: readonly UsageRecord[];
+    syncedRecordCount: number;
+    syncedBilledUsd: number | null;
+}): string[];
+/**
+ * Intersection of two claimed coverage windows — the interval every account
+ * slice of a provider actually covers. Returns undefined when either window
+ * is absent/malformed or the windows do not overlap (fail-closed: no window
+ * is claimed rather than an overstated one).
+ */
+export declare function intersectProviderCoverageIntervals(left: ProviderCoverageInterval | undefined, right: ProviderCoverageInterval | undefined): ProviderCoverageInterval | undefined;
+/**
+ * Printable slice list, e.g.
+ * `env:OPENAI_ADMIN_KEY (6 records, billed $0.81) + env:OPENAI_ADMIN_KEY_ORG2 (18 records, billed $8.66)`.
+ */
+export declare function formatProviderAccountSlices(slices: readonly ProviderAccountSlice[]): string;
 export declare function createProviderConnection(input: CreateProviderConnectionInput): ApprovedSource;
 export declare function resolveTokenReference(reference: string, env?: Record<string, string | undefined>): string;
 export {};

package/dist/providerConnectors.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { createProviderConnectorStub, slugifySourceId } from "./sourceRegistry.js";
 import { redactSecrets } from "./discovery.js";
 /**
@@ -19,6 +20,55 @@ export function isProviderAuthenticationError(error) {
     return error instanceof ProviderConnectorError &&
         error.code === "authentication_error";
 }
+/** Environment variables the Cursor connector reads for a reconciliation run. */
+export const cursorReconciliationEnvVars = {
+    expectedUsd: "AI_SPEND_CURSOR_RECONCILE_EXPECTED_USD",
+    cycleStart: "AI_SPEND_CURSOR_RECONCILE_CYCLE_START",
+    toleranceUsd: "AI_SPEND_CURSOR_RECONCILE_TOLERANCE_USD"
+};
+/**
+ * Read an operator-declared Cursor reconciliation anchor from the local
+ * environment. Absent variables mean "no reconciliation requested"; present
+ * but invalid variables fail closed with a reason (records stay estimated)
+ * instead of throwing, so a typo can never abort or silently verify a sync.
+ * Raw variable values are never echoed into the reason.
+ */
+export function parseCursorReconciliationEnv(env = process.env) {
+    const rawExpected = env[cursorReconciliationEnvVars.expectedUsd];
+    const rawCycleStart = env[cursorReconciliationEnvVars.cycleStart];
+    const rawTolerance = env[cursorReconciliationEnvVars.toleranceUsd];
+    if (rawExpected === undefined && rawCycleStart === undefined && rawTolerance === undefined) {
+        return {};
+    }
+    if (rawExpected === undefined || rawCycleStart === undefined) {
+        return {
+            invalidReason: `both ${cursorReconciliationEnvVars.expectedUsd} and ${cursorReconciliationEnvVars.cycleStart} are required to request a reconciliation`
+        };
+    }
+    const expectedOnDemandUsd = Number(rawExpected.trim());
+    const toleranceUsd = rawTolerance === undefined ? undefined : Number(rawTolerance.trim());
+    const expectation = {
+        expectedOnDemandUsd,
+        expectedCycleStartDate: rawCycleStart.trim(),
+        ...(toleranceUsd === undefined ? {} : { toleranceUsd })
+    };
+    const invalidReason = invalidCursorReconciliationExpectationReason(expectation);
+    return invalidReason ? { invalidReason } : { expectation };
+}
+function invalidCursorReconciliationExpectationReason(expectation) {
+    if (!Number.isFinite(expectation.expectedOnDemandUsd) || expectation.expectedOnDemandUsd <= 0) {
+        return `${cursorReconciliationEnvVars.expectedUsd} must be a positive USD amount read off the Cursor dashboard or invoice`;
+    }
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(expectation.expectedCycleStartDate) ||
+        !Number.isFinite(Date.parse(`${expectation.expectedCycleStartDate}T00:00:00Z`))) {
+        return `${cursorReconciliationEnvVars.cycleStart} must be the cycle start date shown on the dashboard, formatted YYYY-MM-DD`;
+    }
+    if (expectation.toleranceUsd !== undefined &&
+        (!Number.isFinite(expectation.toleranceUsd) || expectation.toleranceUsd < 0)) {
+        return `${cursorReconciliationEnvVars.toleranceUsd} must be a non-negative USD amount when set`;
+    }
+    return undefined;
+}
 export function normalizeOpenAiCostResponse(response, options) {
     const data = isObject(response) && Array.isArray(response.data) ? response.data : [];
     const records = [];
@@ -399,10 +449,21 @@ export function normalizeGitHubCopilotMetricsResponse(response, options) {
     }
     return records;
 }
-export function normalizeCursorSpendResponse(response, options) {
+export function normalizeCursorSpendResponse(response, options, reconciliation) {
     const users = extractArray(response, "teamMemberSpend");
     const cycleStart = isRecord(response) ? numberValue(response.subscriptionCycleStart) : undefined;
     const timestamp = typeof cycleStart === "number" ? new Date(cycleStart).toISOString() : new Date().toISOString();
+    // The Cursor connector's dollars are labeled estimated until an in-run
+    // reconciliation proves the connector total against a human-read dashboard
+    // or invoice figure for the same cycle. Only that evidence — never a
+    // hardcoded flip — can stamp these records "verified", and a mismatched or
+    // unprovable reconciliation fails closed back to estimated.
+    const reconciled = reconciliation?.status === "verified";
+    const confidence = reconciled ? "verified" : "estimated";
+    // Documented semantics: spendCents is "On-demand spend in cents for the
+    // current billing cycle" — seat fees and included-pool usage are excluded.
+    const baseOperation = "Cursor on-demand team spend (current billing cycle; excludes seat fees and included-pool usage)";
+    const operation = reconciled ? `${baseOperation}; ${reconciliation.note}` : baseOperation;
     return users.flatMap((user) => {
         if (!isRecord(user))
             return [];
@@ -413,20 +474,17 @@ export function normalizeCursorSpendResponse(response, options) {
         return [{
                 id: slugifySourceId(["cursor-spend", options.accountId, userId].filter(Boolean).join("-")),
                 timestamp,
-                // The Cursor connector is spec-built and not yet live-verified (beta),
-                // so its dollars are labeled estimated until reconciled against a real
-                // team's invoice. Never stamp "verified" on data we haven't verified.
-                source: { id: options.sourceId, name: "Cursor Admin API", provider: "cursor", confidence: "estimated", observedFrom: options.observedFrom },
+                source: { id: options.sourceId, name: "Cursor Admin API", provider: "cursor", confidence, observedFrom: options.observedFrom },
                 model: "cursor-team-usage",
                 inputTokens: 0,
                 outputTokens: 0,
                 amountUsd: cents / 100,
-                costConfidence: "estimated",
+                costConfidence: confidence,
                 userId,
                 projectId: options.accountId,
                 providerCostType: "cursor_spend",
                 usageGranularity: "user_aggregate",
-                operation: "Cursor team spend"
+                operation
             }];
     });
 }
@@ -571,8 +629,102 @@ async function fetchGitHubCopilot(input, token, fetcher, sourceId) {
 async function fetchCursor(input, token, fetcher, sourceId) {
     const accountId = input.accountId ?? input.org ?? "cursor-team";
     const spendFetch = await fetchCursorSpendPages(fetcher, token);
-    const records = spendFetch.pages.flatMap((page) => normalizeCursorSpendResponse(page, { sourceId, observedFrom: "Cursor Admin API", accountId }));
-    return providerResult("cursor", sourceId, input.authReference, records, qaSummary("cursor", [spendFetch]));
+    const requested = input.reconciliation
+        ? { expectation: input.reconciliation, invalidReason: invalidCursorReconciliationExpectationReason(input.reconciliation) }
+        : parseCursorReconciliationEnv();
+    const reconciliation = assessCursorReconciliation(spendFetch, requested.expectation, requested.invalidReason);
+    const records = spendFetch.pages.flatMap((page) => normalizeCursorSpendResponse(page, { sourceId, observedFrom: "Cursor Admin API", accountId }, reconciliation));
+    const qa = qaSummary("cursor", [spendFetch]);
+    if (reconciliation) {
+        // The outcome must survive the persisted-QA round trip, so it rides in
+        // instructions (kept verbatim) and, on failure, in responseDrift.
+        qa.instructions = [...qa.instructions, `Reconciliation ${reconciliation.status}: ${reconciliation.note}`];
+        if (reconciliation.status !== "verified") {
+            qa.responseDrift.push({
+                label: "Cursor Admin API spend",
+                field: "teamMemberSpend[].spendCents (cycle total)",
+                issue: reconciliation.note
+            });
+        }
+    }
+    return providerResult("cursor", sourceId, input.authReference, records, qa);
+}
+/**
+ * Compare the connector's summed current-cycle on-demand total against the
+ * operator-read dashboard/invoice figure. Every exit that is not an exact
+ * window-proven match inside the clamped tolerance fails closed: the records
+ * stay estimated and the note says exactly why. Returns undefined when no
+ * reconciliation was requested.
+ */
+function assessCursorReconciliation(spendFetch, expectation, invalidReason) {
+    if (!expectation && !invalidReason)
+        return undefined;
+    if (invalidReason || !expectation) {
+        return {
+            status: "not_provable",
+            note: `Cursor reconciliation input was rejected (${invalidReason ?? "missing expectation"}); records remain estimated.`
+        };
+    }
+    if (spendFetch.pagination.stoppedBecause !== "complete" || spendFetch.coverageIncomplete === true) {
+        return {
+            status: "not_provable",
+            note: `Cursor reconciliation requires a complete spend window; pagination stopped because "${spendFetch.pagination.stoppedBecause}" so a partial window cannot verify billed dollars. Records remain estimated.`
+        };
+    }
+    const cycleStarts = spendFetch.pages.map((page) => isRecord(page) ? numberValue(page.subscriptionCycleStart) : undefined);
+    const cycleStart = cycleStarts[0];
+    if (typeof cycleStart !== "number" || cycleStarts.some((value) => value !== cycleStart)) {
+        return {
+            status: "not_provable",
+            note: "Cursor did not report one consistent subscriptionCycleStart across spend pages; the reconciliation window cannot be proven. Records remain estimated."
+        };
+    }
+    const cycleStartIso = new Date(cycleStart).toISOString();
+    const apiCycleDate = cycleStartIso.slice(0, 10);
+    const declaredDateMs = Date.parse(`${expectation.expectedCycleStartDate}T00:00:00Z`);
+    const dayMs = 24 * 60 * 60 * 1000;
+    if (!Number.isFinite(declaredDateMs) || Math.abs(Date.parse(`${apiCycleDate}T00:00:00Z`) - declaredDateMs) > dayMs) {
+        return {
+            status: "not_provable",
+            cycleStartIso,
+            note: `The declared cycle start ${expectation.expectedCycleStartDate} does not match the provider-reported cycle start ${apiCycleDate} (UTC); the dashboard figure and the connector read different windows. Records remain estimated.`
+        };
+    }
+    const connectorTotalCents = spendFetch.pages.reduce((sum, page) => sum + extractArray(page, "teamMemberSpend").reduce((pageSum, member) => pageSum + (isRecord(member) ? numberValue(member.spendCents) ?? 0 : 0), 0), 0);
+    const connectorTotalUsd = connectorTotalCents / 100;
+    if (!(connectorTotalUsd > 0)) {
+        return {
+            status: "not_provable",
+            cycleStartIso,
+            connectorTotalUsd,
+            expectedOnDemandUsd: expectation.expectedOnDemandUsd,
+            note: "Cursor reconciliation needs a non-zero connector total; matching $0.00 against a dashboard figure proves nothing. Records remain estimated."
+        };
+    }
+    // Default $0.01 (dashboards round to cents); clamp to at most 1% of the
+    // expected figure so an oversized tolerance cannot manufacture a match.
+    const requestedTolerance = Math.max(expectation.toleranceUsd ?? 0.01, 0.01);
+    const toleranceUsd = Math.min(requestedTolerance, Math.max(0.01, expectation.expectedOnDemandUsd * 0.01));
+    const differenceUsd = Math.abs(connectorTotalUsd - expectation.expectedOnDemandUsd);
+    const shared = {
+        connectorTotalUsd,
+        expectedOnDemandUsd: expectation.expectedOnDemandUsd,
+        differenceUsd,
+        toleranceUsd,
+        cycleStartIso
+    };
+    if (differenceUsd <= toleranceUsd + 1e-9) {
+        return {
+            status: "verified",
+            ...shared,
+            note: `reconciled to the operator-read dashboard/invoice on-demand total $${expectation.expectedOnDemandUsd.toFixed(2)} for the cycle starting ${apiCycleDate}: connector total $${connectorTotalUsd.toFixed(2)}, difference $${differenceUsd.toFixed(2)} within tolerance $${toleranceUsd.toFixed(2)}`
+        };
+    }
+    return {
+        status: "mismatch",
+        ...shared,
+        note: `Cursor reconciliation mismatch: connector on-demand total $${connectorTotalUsd.toFixed(2)} vs operator-read $${expectation.expectedOnDemandUsd.toFixed(2)} for the cycle starting ${apiCycleDate}; difference $${differenceUsd.toFixed(2)} exceeds tolerance $${toleranceUsd.toFixed(2)}. Records remain estimated until the totals agree.`
+    };
 }
 async function fetchCursorSpendPages(fetcher, token) {
     const label = "Cursor Admin API spend";
@@ -1392,7 +1544,18 @@ function knownProviderFields(provider, label) {
         return new Set([...common, "total_seats", "seats", "seats[]", "seats[].created_at", "seats[].updated_at", "seats[].pending_cancellation_date", "seats[].last_activity_at", "seats[].last_activity_editor", "seats[].last_authenticated_at", "seats[].plan_type", "seats[].login", "seats[].id", "seats[].assignee", "seats[].assignee.login", "seats[].assignee.email", "seats[].assignee.id", "seats[].assignee.node_id", "seats[].assignee.avatar_url", "seats[].assignee.html_url", "seats[].assignee.type", "seats[].assignee.site_admin", "seats[].assigning_team", "seats[].organization"]);
     }
     if (provider === "cursor") {
-        return new Set([...common, "teamMemberSpend", "teamMemberSpend[]", "teamMemberSpend[].userId", "teamMemberSpend[].email", "teamMemberSpend[].name", "teamMemberSpend[].role", "teamMemberSpend[].spendCents", "teamMemberSpend[].fastPremiumRequests", "teamMemberSpend[].hardLimitOverrideDollars", "subscriptionCycleStart", "totalMembers", "totalPages"]);
+        return new Set([
+            ...common,
+            "teamMemberSpend", "teamMemberSpend[]", "teamMemberSpend[].userId", "teamMemberSpend[].email", "teamMemberSpend[].name", "teamMemberSpend[].role", "teamMemberSpend[].spendCents", "teamMemberSpend[].fastPremiumRequests", "teamMemberSpend[].hardLimitOverrideDollars",
+            // Documented in the 2026 Admin API reference alongside spendCents.
+            "teamMemberSpend[].overallSpendCents", "teamMemberSpend[].monthlyLimitDollars", "teamMemberSpend[].effectivePerUserLimitDollars",
+            // Present in live responses and staff-acknowledged as a docs lag
+            // (forum.cursor.com thread 162742, "docs for Get Spending Data are
+            // behind the current API schema"). billingTier and the percent fields
+            // are tiered-team-only and may be undefined elsewhere.
+            "teamMemberSpend[].includedSpendCents", "teamMemberSpend[].profilePictureUrl", "teamMemberSpend[].billingTier", "teamMemberSpend[].autoPercentUsed", "teamMemberSpend[].apiPercentUsed", "teamMemberSpend[].totalPercentUsed",
+            "subscriptionCycleStart", "totalMembers", "totalPages"
+        ]);
     }
     return new Set([...common]);
 }
@@ -1429,7 +1592,9 @@ function providerInstructions(provider) {
     if (provider === "cursor") {
         return [
             "Use a Cursor team admin API key reference, or fall back to Browser Account UI/manual export when API access is unavailable.",
-            "Validate user-level spend against invoices before treating the source as finance-grade."
+            "Cursor's 2026 docs list the Admin API under Enterprise teams; individual Pro/Ultra plans expose no billing API. Standard Admin API endpoints are rate-limited to 20 requests/minute per team.",
+            "spendCents is on-demand spend for the current billing cycle; seat fees and included-pool usage are not in this total.",
+            "Validate user-level spend against invoices before treating the source as finance-grade; set AI_SPEND_CURSOR_RECONCILE_EXPECTED_USD and AI_SPEND_CURSOR_RECONCILE_CYCLE_START to run an in-sync reconciliation."
         ];
     }
     return ["Use a local token reference only; never paste raw provider secrets into commands or reports."];
@@ -1533,6 +1698,236 @@ export function selectProviderFinancialHeadlineRecords(records) {
             : providerRecords;
     });
 }
+/**
+ * Stable identity for one provider account (an OpenAI/Anthropic organization,
+ * a Cursor team, a GitHub org/enterprise). Admin credentials are account-
+ * scoped and multi-account setups are common, so records from different
+ * accounts of one provider must coexist instead of replacing each other.
+ *
+ * The key prefers the explicit account flag the connector already requires
+ * (--org/--enterprise/--account-id, which can share one credential); it
+ * otherwise falls back to the user-chosen credential REFERENCE NAME
+ * (e.g. "env:OPENAI_ADMIN_KEY_ORG2") — stable, printable, and never derived
+ * from secret material. A provider-reported organization id would be
+ * preferable, but the cost APIs aibill calls do not reliably return one
+ * (the OpenAI costs request groups by project/line-item/api-key only), and a
+ * sometimes-present key would split one account into two slices.
+ */
+export function providerAccountKey(input) {
+    if (input.org)
+        return `org:${input.org}`;
+    if (input.enterprise)
+        return `enterprise:${input.enterprise}`;
+    if (input.accountId)
+        return `account:${input.accountId}`;
+    return input.authReference;
+}
+/**
+ * Deterministic short digest of the RAW account key. The slug alone is not
+ * injective — cursor `--account-id "team a"` and `--account-id "team-a"`
+ * both slug to `team-a` — so the record-id prefix carries this digest of the
+ * raw identity: distinct account keys can never share a record-id namespace,
+ * while the same key always regenerates the same digest (idempotent
+ * re-sync). Never derived from secret material: account keys are reference
+ * names and explicit account flags by construction.
+ */
+function providerAccountKeyDigest(accountKey) {
+    return createHash("sha256").update(accountKey, "utf8").digest("hex").slice(0, 8);
+}
+/** The deterministic record-id prefix for one account slice. */
+export function providerAccountRecordIdPrefix(accountKey) {
+    return `${slugifySourceId(accountKey)}-${providerAccountKeyDigest(accountKey)}`;
+}
+/**
+ * Stamp one sync's records with their account slice. The record id gains a
+ * deterministic account prefix (slug + raw-key digest) so identical usage
+ * buckets from two accounts of the same provider can never collide into one
+ * row id — even for slug-equivalent account spellings — and re-syncing the
+ * same account regenerates the same ids (idempotent replace).
+ *
+ * Migration note: slices tagged by the short-lived pre-digest format
+ * (slug-only prefix) are superseded on their next re-sync — same-account
+ * replacement keys on `source.account`, never on id shape — and any
+ * colliding pre-digest rows already persisted are excluded fail-closed by
+ * the id-conflict guard in {@link retainProviderRecordsForNewSync}.
+ */
+export function tagProviderAccountRecords(records, accountKey) {
+    const prefix = providerAccountRecordIdPrefix(accountKey);
+    return records.map((record) => ({
+        ...record,
+        id: `${prefix}-${record.id}`,
+        source: { ...record.source, account: accountKey }
+    }));
+}
+/**
+ * Records from a prior trusted snapshot that must survive a new sync of
+ * `provider` + `accountKey`: every other provider's records, plus this
+ * provider's records that belong to a DIFFERENT named account slice.
+ * Re-syncing the same account replaces its own slice. Records with no account
+ * label (synced before multi-account support) are replaced too — fail-closed:
+ * they cannot be proven to come from a different account, and keeping them
+ * could double-count the same organization.
+ *
+ * Id-conflict guard: a retained record may never share an id with a newly
+ * synced record, nor with another retained record. Colliding ids describe
+ * the same underlying row (possible only in state written by the pre-digest
+ * prefix format, where slug-equivalent account spellings collided) — keeping
+ * both would double-count, so the copy that is not part of the fresh sync is
+ * dropped fail-closed.
+ */
+export function retainProviderRecordsForNewSync(priorRecords, provider, accountKey, syncedRecords) {
+    const syncedIds = new Set(syncedRecords.map((record) => record.id));
+    const seenIds = new Set();
+    return priorRecords.filter((record) => {
+        const replacedSlice = record.source.provider === provider &&
+            !(typeof record.source.account === "string" && record.source.account !== accountKey);
+        if (replacedSlice)
+            return false;
+        if (syncedIds.has(record.id) || seenIds.has(record.id))
+            return false;
+        seenIds.add(record.id);
+        return true;
+    });
+}
+/** Group one provider's records into per-account slices for honest display. */
+export function providerAccountSlices(records, provider) {
+    const slices = new Map();
+    for (const record of records) {
+        if (record.source.provider !== provider)
+            continue;
+        const key = record.source.account ?? null;
+        const slice = slices.get(key) ?? { recordCount: 0, billedUsd: null };
+        slice.recordCount += 1;
+        if (record.costConfidence === "verified" && typeof record.amountUsd === "number") {
+            slice.billedUsd = (slice.billedUsd ?? 0) + record.amountUsd;
+        }
+        slices.set(key, slice);
+    }
+    return [...slices.entries()]
+        .map(([account, slice]) => ({ account, ...slice }))
+        .sort((left, right) => (left.account ?? "").localeCompare(right.account ?? ""));
+}
+/**
+ * A slice's record ids with their account prefix stripped — the provider-side
+ * bucket identity. Understands the current slug+digest prefix and the
+ * short-lived pre-digest slug-only prefix; unprefixed ids pass through.
+ */
+function sliceInnerRecordId(id, accountKey) {
+    const digestPrefix = `${providerAccountRecordIdPrefix(accountKey)}-`;
+    if (id.startsWith(digestPrefix))
+        return id.slice(digestPrefix.length);
+    const slugPrefix = `${slugifySourceId(accountKey)}-`;
+    if (id.startsWith(slugPrefix))
+        return id.slice(slugPrefix.length);
+    return id;
+}
+/**
+ * Detect the same organization synced under two different references: when
+ * two named slices of one provider hold IDENTICAL inner record ids (the ids
+ * modulo their account prefixes), the provider almost certainly returned the
+ * same data twice and the combined total double-counts. This is an honest
+ * diagnostic, not a silent fix — the user chose both identities, so the user
+ * removes one.
+ */
+export function duplicateProviderAccountSliceWarnings(records, provider) {
+    const innerIdsByAccount = new Map();
+    for (const record of records) {
+        if (record.source.provider !== provider)
+            continue;
+        const account = record.source.account;
+        if (typeof account !== "string")
+            continue;
+        const inner = innerIdsByAccount.get(account) ?? new Set();
+        inner.add(sliceInnerRecordId(record.id, account));
+        innerIdsByAccount.set(account, inner);
+    }
+    const accounts = [...innerIdsByAccount.keys()].sort();
+    const warnings = [];
+    for (let leftIndex = 0; leftIndex < accounts.length; leftIndex += 1) {
+        for (let rightIndex = leftIndex + 1; rightIndex < accounts.length; rightIndex += 1) {
+            const left = innerIdsByAccount.get(accounts[leftIndex]);
+            const right = innerIdsByAccount.get(accounts[rightIndex]);
+            if (left.size === 0 || left.size !== right.size)
+                continue;
+            if (![...left].every((id) => right.has(id)))
+                continue;
+            warnings.push(`${provider} slices ${accounts[leftIndex]} and ${accounts[rightIndex]} contain identical records — ` +
+                "likely the same organization under two references; the combined total counts it twice. " +
+                `Remove one: npx aibill drop-slice --provider ${provider} --account "${accounts[rightIndex]}"`);
+        }
+    }
+    return warnings;
+}
+/**
+ * Honest notices for prior records a sync removed. Replacement is fail-closed
+ * by design (unlabeled legacy rows, same-slice re-sync, id-collision guard),
+ * but billed dollars must never disappear without a word: each dropped slice
+ * is named with its record count and billed sum. A routine same-slice re-sync
+ * that returns the same or more billed evidence stays quiet.
+ */
+export function providerSliceReplacementNotices(input) {
+    const retained = new Set(input.retainedRecords);
+    const dropped = input.priorRecords.filter((record) => !retained.has(record));
+    if (dropped.length === 0)
+        return [];
+    const notices = [];
+    for (const slice of providerAccountSlices(dropped, input.provider)) {
+        const billed = slice.billedUsd === null
+            ? "no billed evidence"
+            : `${formatProviderUsd(slice.billedUsd)} billed`;
+        const rows = `${slice.recordCount} record${slice.recordCount === 1 ? "" : "s"}`;
+        if (slice.account === null) {
+            notices.push(`replaced prior unlabeled slice: ${billed} from ${rows} superseded`);
+            continue;
+        }
+        if (slice.account === input.accountKey) {
+            const reducesBilledEvidence = slice.billedUsd !== null &&
+                (input.syncedBilledUsd === null || input.syncedBilledUsd + 0.005 < slice.billedUsd);
+            if (!reducesBilledEvidence)
+                continue;
+            const newBilled = input.syncedBilledUsd === null
+                ? "no billed evidence"
+                : `billed ${formatProviderUsd(input.syncedBilledUsd)}`;
+            notices.push(`replaced prior slice ${slice.account}: ${billed} from ${rows} superseded ` +
+                `(this sync returned ${input.syncedRecordCount} record${input.syncedRecordCount === 1 ? "" : "s"}, ${newBilled})`);
+            continue;
+        }
+        notices.push(`replaced prior slice ${slice.account}: ${billed} from ${rows} superseded (record ids collided with newer state)`);
+    }
+    return notices;
+}
+/**
+ * Intersection of two claimed coverage windows — the interval every account
+ * slice of a provider actually covers. Returns undefined when either window
+ * is absent/malformed or the windows do not overlap (fail-closed: no window
+ * is claimed rather than an overstated one).
+ */
+export function intersectProviderCoverageIntervals(left, right) {
+    if (!left || !right)
+        return undefined;
+    if (typeof left.coverageStart !== "string" || typeof left.coverageEnd !== "string" ||
+        typeof right.coverageStart !== "string" || typeof right.coverageEnd !== "string") {
+        return undefined;
+    }
+    const coverageStart = left.coverageStart > right.coverageStart
+        ? left.coverageStart
+        : right.coverageStart;
+    const coverageEnd = left.coverageEnd < right.coverageEnd
+        ? left.coverageEnd
+        : right.coverageEnd;
+    return coverageStart <= coverageEnd ? { coverageStart, coverageEnd } : undefined;
+}
+/**
+ * Printable slice list, e.g.
+ * `env:OPENAI_ADMIN_KEY (6 records, billed $0.81) + env:OPENAI_ADMIN_KEY_ORG2 (18 records, billed $8.66)`.
+ */
+export function formatProviderAccountSlices(slices) {
+    return slices.map((slice) => {
+        const label = slice.account ?? "earlier sync (unlabeled account)";
+        const billed = slice.billedUsd === null ? "" : `, billed ${formatProviderUsd(slice.billedUsd)}`;
+        return `${label} (${slice.recordCount} record${slice.recordCount === 1 ? "" : "s"}${billed})`;
+    }).join(" + ");
+}
 function sumAmounts(records) {
     const amounts = records
         .map((record) => record.amountUsd)