@agent-finops/core 0.9.0 → 0.9.2

package/dist/providerConnectors.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { createProviderConnectorStub, slugifySourceId } from "./sourceRegistry.js";
 import { redactSecrets } from "./discovery.js";
 /**
@@ -68,6 +69,80 @@ function invalidCursorReconciliationExpectationReason(expectation) {
     }
     return undefined;
 }
+/** Environment variables the GitHub Copilot connector reads for a reconciliation run. */
+export const gitHubCopilotReconciliationEnvVars = {
+    expectedUsd: "AI_SPEND_COPILOT_RECONCILE_EXPECTED_USD",
+    billingMonth: "AI_SPEND_COPILOT_RECONCILE_MONTH",
+    toleranceUsd: "AI_SPEND_COPILOT_RECONCILE_TOLERANCE_USD",
+    /**
+     * Optional binding of the anchor to ONE account (post-hoc QA C3): a bare
+     * slug or `org:<slug>` / `enterprise:<slug>`. When set, a sync of any
+     * other account fails the reconciliation closed instead of stamping a
+     * coincidence-equal total verified with leftover shell env.
+     */
+    account: "AI_SPEND_COPILOT_RECONCILE_ACCOUNT"
+};
+/**
+ * Read an operator-declared GitHub Copilot 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 parseGitHubCopilotReconciliationEnv(env = process.env) {
+    const rawExpected = env[gitHubCopilotReconciliationEnvVars.expectedUsd];
+    const rawMonth = env[gitHubCopilotReconciliationEnvVars.billingMonth];
+    const rawTolerance = env[gitHubCopilotReconciliationEnvVars.toleranceUsd];
+    const rawAccount = env[gitHubCopilotReconciliationEnvVars.account];
+    // A dangling ACCOUNT binding alone requests nothing — it only constrains a
+    // reconciliation that the expected/month pair actually requested.
+    if (rawExpected === undefined && rawMonth === undefined && rawTolerance === undefined) {
+        return {};
+    }
+    if (rawExpected === undefined || rawMonth === undefined) {
+        return {
+            invalidReason: `both ${gitHubCopilotReconciliationEnvVars.expectedUsd} and ${gitHubCopilotReconciliationEnvVars.billingMonth} are required to request a reconciliation`
+        };
+    }
+    const expectedNetUsd = Number(rawExpected.trim());
+    const toleranceUsd = rawTolerance === undefined ? undefined : Number(rawTolerance.trim());
+    const account = rawAccount?.trim();
+    const expectation = {
+        expectedNetUsd,
+        expectedBillingMonth: rawMonth.trim(),
+        ...(toleranceUsd === undefined ? {} : { toleranceUsd }),
+        ...(account ? { account } : {})
+    };
+    const invalidReason = invalidGitHubCopilotReconciliationExpectationReason(expectation);
+    return invalidReason ? { invalidReason } : { expectation };
+}
+function invalidGitHubCopilotReconciliationExpectationReason(expectation) {
+    if (!Number.isFinite(expectation.expectedNetUsd) || expectation.expectedNetUsd <= 0) {
+        return `${gitHubCopilotReconciliationEnvVars.expectedUsd} must be a positive USD amount read off the GitHub billing usage page`;
+    }
+    if (!/^\d{4}-(0[1-9]|1[0-2])$/.test(expectation.expectedBillingMonth)) {
+        return `${gitHubCopilotReconciliationEnvVars.billingMonth} must be the billing month shown on the usage page, formatted YYYY-MM`;
+    }
+    if (expectation.toleranceUsd !== undefined &&
+        (!Number.isFinite(expectation.toleranceUsd) || expectation.toleranceUsd < 0)) {
+        return `${gitHubCopilotReconciliationEnvVars.toleranceUsd} must be a non-negative USD amount when set`;
+    }
+    if (expectation.account !== undefined &&
+        !/^(?:(?:org|enterprise):)?[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(expectation.account)) {
+        // Never echo the raw value — env parse reasons are printed verbatim.
+        return `${gitHubCopilotReconciliationEnvVars.account} must be an org/enterprise slug, optionally prefixed org: or enterprise:`;
+    }
+    return undefined;
+}
+/**
+ * Shared reconciliation tolerance rule: default $0.01 (billing pages round to
+ * cents) and clamp to at most 1% of the expected figure so an oversized
+ * tolerance can never manufacture a match.
+ */
+function clampReconciliationToleranceUsd(expectedUsd, requestedToleranceUsd) {
+    const requested = Math.max(requestedToleranceUsd ?? 0.01, 0.01);
+    return Math.min(requested, Math.max(0.01, expectedUsd * 0.01));
+}
 export function normalizeOpenAiCostResponse(response, options) {
     const data = isObject(response) && Array.isArray(response.data) ? response.data : [];
     const records = [];
@@ -448,6 +523,71 @@ export function normalizeGitHubCopilotMetricsResponse(response, options) {
     }
     return records;
 }
+/**
+ * Normalize one GitHub AI-credit usage report (the 2026 usage-based billing
+ * model: GET /organizations/{org}/settings/billing/ai_credit/usage) into
+ * billed-dollar evidence records. Rows are NET provider-reported dollars, but
+ * this connector is fixture-verified, so — exactly like the Cursor connector —
+ * the records stay "estimated" until an in-run reconciliation proves the
+ * connector total against the operator-read billing page figure for the same
+ * billing month. Legacy premium-request units are deliberately not fetched or
+ * blended here (provider-contract exclusion).
+ */
+export function normalizeGitHubCopilotAiCreditUsageResponse(response, options, reconciliation) {
+    const items = extractArray(response, "usageItems");
+    const timePeriod = isRecord(response) && isRecord(response.timePeriod) ? response.timePeriod : undefined;
+    const year = nonNegativeIntegerValue(timePeriod?.year);
+    const month = nonNegativeIntegerValue(timePeriod?.month);
+    const day = nonNegativeIntegerValue(timePeriod?.day);
+    const monthKey = typeof year === "number" && typeof month === "number" && month >= 1 && month <= 12
+        ? `${String(year).padStart(4, "0")}-${String(month).padStart(2, "0")}`
+        : undefined;
+    const timestampDate = monthKey && typeof day === "number" && day >= 1 && day <= 31
+        ? `${monthKey}-${String(day).padStart(2, "0")}`
+        : monthKey
+            ? `${monthKey}-01`
+            : undefined;
+    const timestamp = timestampDate && Number.isFinite(Date.parse(`${timestampDate}T00:00:00Z`))
+        ? new Date(`${timestampDate}T00:00:00Z`).toISOString()
+        : new Date().toISOString();
+    // Fail-closed stamping mirror of the Cursor connector: only an in-run
+    // reconciliation match may flip these records to "verified"; a mismatched or
+    // unprovable reconciliation keeps them estimated.
+    const reconciled = reconciliation?.status === "verified";
+    const confidence = reconciled ? "verified" : "estimated";
+    return items.flatMap((item, index) => {
+        if (!isRecord(item))
+            return [];
+        const product = stringValue(item.product);
+        const sku = stringValue(item.sku);
+        const netAmountUsd = parseDollarUsd(item.netAmount);
+        if (!product || !sku || typeof netAmountUsd !== "number")
+            return [];
+        const model = stringValue(item.model);
+        const grossAmountUsd = parseDollarUsd(item.grossAmount);
+        const discountAmountUsd = parseDollarUsd(item.discountAmount);
+        const netQuantity = nonNegativeNumberValue(item.netQuantity);
+        const amounts = typeof grossAmountUsd === "number" && typeof discountAmountUsd === "number"
+            ? `gross $${grossAmountUsd.toFixed(2)} - discounts $${discountAmountUsd.toFixed(2)} = net $${netAmountUsd.toFixed(2)}`
+            : `net $${netAmountUsd.toFixed(2)}`;
+        const baseOperation = `GitHub AI-credit billed usage${monthKey ? ` for ${monthKey}` : ""} (${sku}; ${amounts}; metered spend, excludes seat license fees)`;
+        return [{
+                id: slugifySourceId(["github-copilot-ai-credit", monthKey ?? "unknown-month", options.accountId, product, sku, model, String(index)].filter(Boolean).join("-")),
+                timestamp,
+                source: { id: options.sourceId, name: "GitHub AI-credit usage report", provider: "github-copilot", confidence, observedFrom: options.observedFrom },
+                model: model ?? sku,
+                inputTokens: 0,
+                outputTokens: 0,
+                amountUsd: netAmountUsd,
+                costConfidence: confidence,
+                projectId: options.accountId,
+                providerCostType: "copilot_ai_credit_billing",
+                usageGranularity: "billing_bucket",
+                ...(netQuantity === undefined ? {} : { quantity: netQuantity }),
+                operation: reconciled ? `${baseOperation}; ${reconciliation.note}` : baseOperation
+            }];
+    });
+}
 export function normalizeCursorSpendResponse(response, options, reconciliation) {
     const users = extractArray(response, "teamMemberSpend");
     const cycleStart = isRecord(response) ? numberValue(response.subscriptionCycleStart) : undefined;
@@ -621,9 +761,247 @@ async function fetchGitHubCopilot(input, token, fetcher, sourceId) {
     const seatFetch = input.org ? await fetchPaginatedJson(fetcher, buildGitHubCopilotSeatsUrl(input.org), request, "github-copilot", "GitHub Copilot seats") : undefined;
     if (seatFetch)
         assessGitHubCopilotSeatCompleteness(seatFetch);
-    const metricsRecords = metricsFetch.pages.flatMap((page) => normalizeGitHubCopilotMetricsResponse(page, { sourceId, observedFrom: "GitHub Copilot metrics API", accountId }));
-    const seatRecords = seatFetch ? seatFetch.pages.flatMap((page) => normalizeGitHubCopilotSeatResponse(page, { sourceId, observedFrom: "GitHub Copilot billing seats API", accountId })) : [];
-    return providerResult("github-copilot", sourceId, input.authReference, [...metricsRecords, ...seatRecords], qaSummary("github-copilot", [metricsFetch, ...(seatFetch ? [seatFetch] : [])]));
+    const requested = input.copilotReconciliation
+        ? { expectation: input.copilotReconciliation, invalidReason: invalidGitHubCopilotReconciliationExpectationReason(input.copilotReconciliation) }
+        : parseGitHubCopilotReconciliationEnv();
+    const aiCredit = await fetchGitHubCopilotAiCreditUsage(fetcher, input, request, requested.expectation);
+    const syncedAccount = input.org
+        ? { scope: "org", slug: input.org }
+        : { scope: "enterprise", slug: input.enterprise };
+    const reconciliation = assessGitHubCopilotReconciliation(aiCredit, requested.expectation, requested.invalidReason, syncedAccount);
+    // Dedupe every record family by stable id BEFORE the QA summary so a
+    // GitHub page-shift during churn (the same seat or day row returned on
+    // two pages) can never double-count estimated dollars or usage (QA M2).
+    const metricsRecords = dedupeGitHubCopilotRecordsById(metricsFetch.pages.flatMap((page) => normalizeGitHubCopilotMetricsResponse(page, { sourceId, observedFrom: "GitHub Copilot metrics API", accountId })), metricsFetch);
+    const seatRecords = seatFetch
+        ? dedupeGitHubCopilotRecordsById(seatFetch.pages.flatMap((page) => normalizeGitHubCopilotSeatResponse(page, { sourceId, observedFrom: "GitHub Copilot billing seats API", accountId })), seatFetch)
+        : [];
+    const aiCreditRecords = aiCredit.fetch
+        ? dedupeGitHubCopilotRecordsById(aiCredit.fetch.pages.flatMap((page) => normalizeGitHubCopilotAiCreditUsageResponse(page, { sourceId, observedFrom: "GitHub AI-credit usage report", accountId }, reconciliation)), aiCredit.fetch)
+        : [];
+    const qa = qaSummary("github-copilot", [metricsFetch, ...(seatFetch ? [seatFetch] : []), ...(aiCredit.fetch ? [aiCredit.fetch] : [])]);
+    if (aiCredit.unavailableReason) {
+        // A token scoped to Copilot metrics/seats alone still yields honest usage
+        // evidence, so a missing billing permission degrades to estimated records
+        // with an explicit diagnostic instead of failing the whole sync.
+        qa.instructions = [...qa.instructions, aiCredit.unavailableReason];
+        qa.responseDrift.push({
+            label: "GitHub Copilot AI-credit usage report",
+            field: "usageItems",
+            issue: aiCredit.unavailableReason
+        });
+    }
+    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: "GitHub Copilot AI-credit usage report",
+                field: "usageItems[].netAmount (billing month total)",
+                issue: reconciliation.note
+            });
+        }
+    }
+    return providerResult("github-copilot", sourceId, input.authReference, [...metricsRecords, ...seatRecords, ...aiCreditRecords], qa);
+}
+function resolveGitHubCopilotBillingMonth(expectation) {
+    if (expectation && /^\d{4}-(0[1-9]|1[0-2])$/.test(expectation.expectedBillingMonth)) {
+        const [year, month] = expectation.expectedBillingMonth.split("-").map(Number);
+        return { year: year, month: month };
+    }
+    const now = new Date();
+    return { year: now.getUTCFullYear(), month: now.getUTCMonth() + 1 };
+}
+/**
+ * Read the org/enterprise AI-credit usage report for one billing month (the
+ * declared reconciliation month, else the current UTC month). The endpoint
+ * needs the fine-grained "Administration: read" organization permission
+ * (enterprise reads: billing read); a 401/403/404 therefore degrades with an
+ * honest note instead of failing metrics/seat evidence, while transport and
+ * schema failures still fail closed.
+ */
+async function fetchGitHubCopilotAiCreditUsage(fetcher, input, request, expectation) {
+    const label = "GitHub Copilot AI-credit usage report";
+    const billingMonth = resolveGitHubCopilotBillingMonth(expectation);
+    try {
+        const response = await fetchJsonOrThrow(fetcher, buildGitHubCopilotAiCreditUsageUrl(input, billingMonth), request, "github-copilot", label);
+        const fetchResult = {
+            pages: [response.payload],
+            pagination: { label, pagesFetched: 1, stoppedBecause: "complete", maxPages: 1 },
+            rateLimits: response.rateLimit ? [response.rateLimit] : [],
+            responseDrift: detectResponseDrift(response.payload, "github-copilot", label)
+        };
+        markMalformedGitHubCopilotAiCreditRows(fetchResult, label);
+        return { fetch: fetchResult, billingMonth };
+    }
+    catch (error) {
+        const status = error instanceof ProviderConnectorError ? error.status : undefined;
+        if (error instanceof ProviderConnectorError && (error.code === "authentication_error" || status === 404)) {
+            return {
+                billingMonth,
+                unavailableReason: `GitHub AI-credit usage report was unavailable (HTTP ${status ?? "error"}); billed dollars were skipped. Grant the fine-grained "Administration: read" organization permission (enterprise: billing read) to include them.`
+            };
+        }
+        throw error;
+    }
+}
+function buildGitHubCopilotAiCreditUsageUrl(input, billingMonth) {
+    const base = input.enterprise
+        ? `https://api.github.com/enterprises/${encodeURIComponent(input.enterprise)}/settings/billing/ai_credit/usage`
+        : input.org
+            ? `https://api.github.com/organizations/${encodeURIComponent(input.org)}/settings/billing/ai_credit/usage`
+            : undefined;
+    if (!base)
+        throw new Error("GitHub Copilot connector requires --org or --enterprise.");
+    const url = new URL(base);
+    url.searchParams.set("year", String(billingMonth.year));
+    url.searchParams.set("month", String(billingMonth.month));
+    return url.toString();
+}
+function markMalformedGitHubCopilotAiCreditRows(fetchResult, label) {
+    const issues = [];
+    const report = (field, issue) => issues.push({ label, field, issue });
+    for (const page of fetchResult.pages) {
+        if (!isRecord(page) || !Array.isArray(page.usageItems)) {
+            report("usageItems", "AI-credit usage response omitted the canonical usageItems array; completeness cannot be proven");
+            continue;
+        }
+        if (!isRecord(page.timePeriod) || typeof nonNegativeIntegerValue(page.timePeriod.year) !== "number") {
+            report("timePeriod", "AI-credit usage response omitted the documented timePeriod object; the billing month cannot be proven");
+        }
+        for (const [index, item] of page.usageItems.entries()) {
+            const itemPath = `usageItems[${index}]`;
+            if (!isRecord(item)) {
+                report(itemPath, "AI-credit usage response contained a non-object usage row; the row was excluded");
+                continue;
+            }
+            if (!stringValue(item.product) || !stringValue(item.sku)) {
+                report(`${itemPath}.product/sku`, "AI-credit usage row is missing its product or sku label; the row was excluded");
+            }
+            if (typeof parseDollarUsd(item.netAmount) !== "number") {
+                report(`${itemPath}.netAmount`, "AI-credit usage row requires a non-negative USD netAmount; the row was excluded");
+            }
+            for (const field of ["grossAmount", "discountAmount", "pricePerUnit", "grossQuantity", "discountQuantity", "netQuantity"]) {
+                if (item[field] !== undefined && typeof nonNegativeNumberValue(item[field]) !== "number") {
+                    report(`${itemPath}.${field}`, "AI-credit usage amounts and quantities must be non-negative numbers; the invalid value was excluded");
+                }
+            }
+        }
+    }
+    if (issues.length === 0)
+        return;
+    fetchResult.coverageIncomplete = true;
+    fetchResult.responseDrift.push(...issues);
+}
+/** Case-insensitive account-binding match; a bare slug matches either scope. */
+function gitHubCopilotAccountBindingMatches(declared, synced) {
+    if (!synced)
+        return false;
+    const normalized = declared.trim().toLowerCase();
+    const scoped = normalized.match(/^(org|enterprise):(.+)$/);
+    if (scoped) {
+        return scoped[1] === synced.scope && scoped[2] === synced.slug.toLowerCase();
+    }
+    return normalized === synced.slug.toLowerCase();
+}
+/**
+ * Compare the connector's summed AI-credit net total for one billing month
+ * against the operator-read billing page figure. Every exit that is not a
+ * 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 assessGitHubCopilotReconciliation(aiCredit, expectation, invalidReason, syncedAccount) {
+    if (!expectation && !invalidReason)
+        return undefined;
+    if (invalidReason || !expectation) {
+        return {
+            status: "not_provable",
+            note: `GitHub Copilot reconciliation input was rejected (${invalidReason ?? "missing expectation"}); records remain estimated.`
+        };
+    }
+    const billingMonth = expectation.expectedBillingMonth;
+    if (expectation.account !== undefined &&
+        !gitHubCopilotAccountBindingMatches(expectation.account, syncedAccount)) {
+        // QA C3: leftover shell env from one account's runbook pass must never
+        // stamp a different account verified on a coincidence-equal total.
+        return {
+            status: "not_provable",
+            billingMonth,
+            note: `${gitHubCopilotReconciliationEnvVars.account} is bound to a different org/enterprise than this sync; the billing figure was not applied. Reconcile one account per shell, or update the binding. Records remain estimated.`
+        };
+    }
+    if (!aiCredit.fetch) {
+        return {
+            status: "not_provable",
+            billingMonth,
+            note: `GitHub Copilot reconciliation requires the AI-credit usage report; ${aiCredit.unavailableReason ?? "the report could not be read."} Records remain estimated.`
+        };
+    }
+    if (aiCredit.fetch.pagination.stoppedBecause !== "complete" || aiCredit.fetch.coverageIncomplete === true) {
+        return {
+            status: "not_provable",
+            billingMonth,
+            note: "GitHub Copilot reconciliation requires a complete AI-credit report; the response was incomplete or partially malformed, so billed dollars cannot be verified. Records remain estimated."
+        };
+    }
+    for (const page of aiCredit.fetch.pages) {
+        const timePeriod = isRecord(page) && isRecord(page.timePeriod) ? page.timePeriod : undefined;
+        const year = nonNegativeIntegerValue(timePeriod?.year);
+        const month = nonNegativeIntegerValue(timePeriod?.month);
+        const monthKey = typeof year === "number" && typeof month === "number"
+            ? `${String(year).padStart(4, "0")}-${String(month).padStart(2, "0")}`
+            : undefined;
+        if (monthKey !== billingMonth) {
+            return {
+                status: "not_provable",
+                billingMonth,
+                note: `The declared billing month ${billingMonth} does not match the provider-reported time period${monthKey ? ` ${monthKey}` : ""}; the billing page figure and the connector read different windows. Records remain estimated.`
+            };
+        }
+        if (timePeriod?.day !== undefined) {
+            // Fail closed on any day field (null included), and say WHY without
+            // the self-contradictory month-vs-same-month wording (QA A4): a
+            // day-scoped report cannot anchor a whole-month billing figure.
+            return {
+                status: "not_provable",
+                billingMonth,
+                note: `GitHub Copilot reconciliation requires a whole-month AI-credit report; the provider-reported time period carries a day field, so the monthly billing page figure cannot be compared against it. Records remain estimated.`
+            };
+        }
+    }
+    const connectorTotalUsd = aiCredit.fetch.pages.reduce((sum, page) => sum + extractArray(page, "usageItems").reduce((pageSum, item) => pageSum + (isRecord(item) ? parseDollarUsd(item.netAmount) ?? 0 : 0), 0), 0);
+    if (!(connectorTotalUsd > 0)) {
+        return {
+            status: "not_provable",
+            billingMonth,
+            connectorTotalUsd,
+            expectedNetUsd: expectation.expectedNetUsd,
+            note: "GitHub Copilot reconciliation needs a non-zero connector total; matching $0.00 against a billing page figure proves nothing (a fully promo-discounted month cannot verify). Records remain estimated."
+        };
+    }
+    const toleranceUsd = clampReconciliationToleranceUsd(expectation.expectedNetUsd, expectation.toleranceUsd);
+    const differenceUsd = Math.abs(connectorTotalUsd - expectation.expectedNetUsd);
+    const shared = {
+        connectorTotalUsd,
+        expectedNetUsd: expectation.expectedNetUsd,
+        differenceUsd,
+        toleranceUsd,
+        billingMonth
+    };
+    if (differenceUsd <= toleranceUsd + 1e-9) {
+        return {
+            status: "verified",
+            ...shared,
+            note: `reconciled to the operator-read GitHub billing usage AI-credit net total $${expectation.expectedNetUsd.toFixed(2)} for the billing month ${billingMonth}: connector total $${connectorTotalUsd.toFixed(2)}, difference $${differenceUsd.toFixed(2)} within tolerance $${toleranceUsd.toFixed(2)}`
+        };
+    }
+    return {
+        status: "mismatch",
+        ...shared,
+        note: `GitHub Copilot reconciliation mismatch: connector AI-credit net total $${connectorTotalUsd.toFixed(2)} vs operator-read $${expectation.expectedNetUsd.toFixed(2)} for the billing month ${billingMonth}; difference $${differenceUsd.toFixed(2)} exceeds tolerance $${toleranceUsd.toFixed(2)}. Records remain estimated until the totals agree.`
+    };
 }
 async function fetchCursor(input, token, fetcher, sourceId) {
     const accountId = input.accountId ?? input.org ?? "cursor-team";
@@ -700,10 +1078,7 @@ function assessCursorReconciliation(spendFetch, expectation, invalidReason) {
             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 toleranceUsd = clampReconciliationToleranceUsd(expectation.expectedOnDemandUsd, expectation.toleranceUsd);
     const differenceUsd = Math.abs(connectorTotalUsd - expectation.expectedOnDemandUsd);
     const shared = {
         connectorTotalUsd,
@@ -917,7 +1292,27 @@ function assessGitHubCopilotSeatCompleteness(fetchResult) {
     const expected = fetchResult.pages
         .map((page) => isRecord(page) ? numberValue(page.total_seats) : undefined)
         .find((value) => typeof value === "number");
-    const actual = fetchResult.pages.reduce((sum, page) => sum + extractArray(page, "seats").length, 0);
+    // Count UNIQUE seat identities (same derivation as the normalizer), not raw
+    // rows: a GitHub page-shift during churn can return the same assignee on
+    // two pages, which would otherwise satisfy total_seats while a real seat
+    // went unfetched (QA M2). Rows without any identity still count singly.
+    const identities = new Set();
+    let unidentifiedRows = 0;
+    for (const page of fetchResult.pages) {
+        for (const seat of extractArray(page, "seats")) {
+            if (!isRecord(seat)) {
+                unidentifiedRows += 1;
+                continue;
+            }
+            const assignee = isRecord(seat.assignee) ? seat.assignee : {};
+            const identity = stringValue(assignee.login) ?? stringValue(assignee.email) ?? stringValue(seat.login) ?? stringValue(seat.id);
+            if (identity)
+                identities.add(identity);
+            else
+                unidentifiedRows += 1;
+        }
+    }
+    const actual = identities.size + unidentifiedRows;
     if (typeof expected !== "number") {
         if (fetchResult.pagination.stoppedBecause === "complete")
             fetchResult.pagination.stoppedBecause = "missing_cursor";
@@ -926,10 +1321,42 @@ function assessGitHubCopilotSeatCompleteness(fetchResult) {
     }
     else if (fetchResult.pagination.stoppedBecause === "complete" && actual !== expected) {
         fetchResult.pagination.stoppedBecause = "missing_cursor";
-        fetchResult.pagination.note = `GitHub reported ${expected} seats but returned ${actual}; completeness cannot be proven.`;
+        fetchResult.pagination.note = `GitHub reported ${expected} seats but returned ${actual} unique seat identit${actual === 1 ? "y" : "ies"}; completeness cannot be proven.`;
         fetchResult.responseDrift.push({ label: "GitHub Copilot seats", field: "total_seats", issue: fetchResult.pagination.note });
     }
 }
+/**
+ * Dedupe one normalized GitHub Copilot record family by stable id, mirroring
+ * the OpenAI dedupe semantics: an identical duplicate is excluded with a
+ * drift note; conflicting rows sharing one id are ALL excluded (evidence
+ * that cannot be told apart must not be counted). Any duplicate marks the
+ * fetch's coverage incomplete so the sync reports partial instead of
+ * silently inflating estimated dollars (QA M2).
+ */
+function dedupeGitHubCopilotRecordsById(records, fetchResult) {
+    const byId = new Map();
+    const conflicted = new Set();
+    for (const record of records) {
+        const existing = byId.get(record.id);
+        if (!existing && !conflicted.has(record.id)) {
+            byId.set(record.id, record);
+            continue;
+        }
+        fetchResult.coverageIncomplete = true;
+        fetchResult.responseDrift.push({
+            label: fetchResult.pagination.label,
+            field: "normalized records[].id",
+            issue: existing && JSON.stringify(existing) === JSON.stringify(record)
+                ? "duplicate provider record was excluded"
+                : "conflicting provider records shared one stable identity; all conflicting rows were excluded"
+        });
+        if (existing && JSON.stringify(existing) !== JSON.stringify(record)) {
+            byId.delete(record.id);
+            conflicted.add(record.id);
+        }
+    }
+    return Array.from(byId.values());
+}
 async function fetchPaginatedJson(fetcher, initialUrl, request, provider, label) {
     const pages = [];
     const rateLimits = [];
@@ -1539,6 +1966,11 @@ function knownProviderFields(provider, label) {
     if (provider === "github-copilot" && label.toLowerCase().includes("metrics")) {
         return new Set([...common, "download_links", "download_links[]", "day_totals", "day_totals[]", "day_totals[].day", "day_totals[].daily_active_users", "day_totals[].totals_by_model_feature", "day_totals[].totals_by_model_feature[]", "day_totals[].totals_by_model_feature[].model", "day_totals[].totals_by_model_feature[].feature", "day_totals[].totals_by_model_feature[].engaged_users", "day_totals[].totals_by_model_feature[].total_requests", "day_totals[].totals_by_model_feature[].user_initiated_interaction_count", "day_totals[].totals_by_cli", "day_totals[].totals_by_cli.request_count", "day_totals[].totals_by_cli.prompt_count", "day_totals[].totals_by_cli.session_count", "day_totals[].totals_by_cli.token_usage", "day_totals[].totals_by_cli.token_usage.prompt_tokens_sum", "day_totals[].totals_by_cli.token_usage.output_tokens_sum", "day_totals[].totals_by_cli.token_usage.avg_tokens_per_request", "day_totals[].totals_by_cli.engaged_users", "day_totals[].totals_by_cli.total_requests", "report_start_day", "report_end_day", "created_at", "generated_at", "etl_id", "day_partition", "entity_id_partition", "enterprise_id", "organization_id"]);
     }
+    if (provider === "github-copilot" && label.toLowerCase().includes("ai-credit")) {
+        // Documented 2026 enhanced-billing usage report shape: a timePeriod echo
+        // plus usageItems rows (product/sku/model with gross/discount/net money).
+        return new Set([...common, "timePeriod", "timePeriod.year", "timePeriod.month", "timePeriod.day", "usageItems", "usageItems[]", "usageItems[].date", "usageItems[].product", "usageItems[].sku", "usageItems[].model", "usageItems[].unitType", "usageItems[].pricePerUnit", "usageItems[].grossQuantity", "usageItems[].grossAmount", "usageItems[].discountQuantity", "usageItems[].discountAmount", "usageItems[].netQuantity", "usageItems[].netAmount", "usageItems[].organizationName", "usageItems[].repositoryName"]);
+    }
     if (provider === "github-copilot" && label.toLowerCase().includes("seats")) {
         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"]);
     }
@@ -1584,8 +2016,11 @@ function providerInstructions(provider) {
     }
     if (provider === "github-copilot") {
         return [
-            "Use a GitHub token reference with org or enterprise Copilot metrics and billing seats read access.",
-            "Seat records estimate monthly commitment; metrics records are usage evidence without direct spend allocation."
+            "Use a GitHub token reference with org or enterprise Copilot metrics, billing seats, and billing usage read access.",
+            "Fine-grained token permissions (2026): 'Organization Copilot metrics: read' for usage metrics, 'GitHub Copilot Business: read' for seats, and 'Administration: read' for the AI-credit usage report (classic PATs: read:org and/or manage_billing:copilot; enterprise reads accept read:enterprise). The org's Copilot 'usage metrics' policy must be enabled.",
+            "Seat records estimate monthly plan commitment at list price ($19 Business / $39 Enterprise); metrics records are usage evidence without direct spend allocation.",
+            "AI-credit records carry GitHub-billed net dollars (usage-based billing for every Copilot Business/Enterprise account since 2026-06-01; 1 AI credit bills as $0.01) and stay estimated until an in-sync reconciliation matches the billing page figure; set AI_SPEND_COPILOT_RECONCILE_EXPECTED_USD and AI_SPEND_COPILOT_RECONCILE_MONTH to run one, and optionally AI_SPEND_COPILOT_RECONCILE_ACCOUNT (org:<slug> or enterprise:<slug>) to bind the anchor to one account when several are synced from one shell. Legacy premium-request billing is not fetched or blended.",
+            "Individual Copilot (Free/Pro/Pro+) exposes no org billing or metrics API; the personal-plan endpoints under /users/{username}/settings/billing need that user's own token with 'Plan: read' and are not implemented."
         ];
     }
     if (provider === "cursor") {
@@ -1609,7 +2044,7 @@ function providerPermissionPrompt(provider, label, response, payload) {
             return `Missing Anthropic Admin read scopes for ${label} (${status}). Reconnect with organization cost report and Claude Code usage report read access. ${rawMessage}`;
         }
         if (provider === "github-copilot") {
-            return `Missing GitHub Copilot org or enterprise read scopes for ${label} (${status}). Reconnect with Copilot metrics and billing seats read access. ${rawMessage}`;
+            return `Missing GitHub Copilot org or enterprise read scopes for ${label} (${status}). Reconnect with Copilot metrics, billing seats, and billing usage (Administration: read) access. ${rawMessage}`;
         }
         if (provider === "cursor") {
             return `Missing Cursor team admin read scopes for ${label} (${status}). Use Cursor Admin API access or fall back to Browser Account UI/manual export. ${rawMessage}`;
@@ -1697,6 +2132,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)