feat(billing): add on-demand usage reconciliation check

[pandemicsyn]

Summary

• Add an admin-only Reconcile with Cloudflare action after an exact user or organization usage search over the applied, bounded [start, end) window.
• Query containersUsageAdaptiveGroups only for physical Cloudflare instance IDs already recorded by the meter, with account settings, retention, duration, page-size, request-count, timeout, and raw-response bounds enforced.
• Return Cloudflare billing inputs and memory/disk capacity-equivalent diagnostics while explicitly marking provider awake seconds and variance unavailable; live account validation showed that Cloudflare sums overlapping container and micro-VM resource records.
• Keep missing, partial, ambiguous, and unavailable provider results distinct from zero usage, and expose the parsed Cloudflare response through an inline disclosure without another provider request.
• Keep CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_ANALYTICS_API_TOKEN optional at application startup; missing configuration fails only when an admin invokes reconciliation.

Verification

• pnpm --filter web test -- --runInBand src/lib/cloudflare/container-usage-analytics.test.ts src/routers/admin/cloud-billing-skus-router.test.ts
• pnpm --filter web typecheck
• pnpm --filter web lint
• Validate the live GraphQL response shape, account settings, exact instance filter, half-open datetime filter, application identity, and resource sums against known Cloud Agent instances.

Visual Changes

• Add the reconciliation action, normalized meter totals, provider allocation-equivalent diagnostics, per-instance statuses, responsive overflow behavior, and raw JSON disclosure to Cloud Billing → Usage records.
• Validate the populated, empty, error, and raw-response states at desktop and 390px mobile widths.

Reviewer Notes

• Review the exact subject and segment-time [start, end) scoping, physical instance deduplication, and instanceId_in provider filter closely; these prevent unrelated usage from entering the report.
• Live validation found memory and disk allocation equivalents agree numerically, but event-level Cloudflare records overlap and their aggregate can exceed the selected wall-clock window. The report therefore does not label them provider awake seconds or calculate false variance.
• A single observed Cloudflare applicationId is reported without a hardcoded application-name assumption; multiple applications for one physical instance are surfaced as ambiguous.
• The procedure performs no database writes, charges, credit movement, SKU changes, scheduling, or persisted reconciliation reports. Raw responses contain parsed response bodies only, never request headers or token material.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

The incremental change since 8d86c31 adds the missing statusDetail assertion to the capacity-mismatch reconciliation test, which now distinguishes the CAPACITY_CROSS_CHECK_RELATIVE_TOLERANCE mismatch branch from the agreeing branch; no new issues found and all previously reported findings are resolved.

Resolved since previous review

• cloud-billing-skus-router.test.ts — the capacity-mismatch test now asserts statusDetail contains imply different active durations, verified against the mismatch branch in cloud-billing-skus-router.ts:403-405 (test inputs yield a 9% relative divergence, well above the 1e-6 tolerance).
• UsageRecordsContent.tsx — statusDetail rendering restored for all rows.
• cloud-billing-skus-router.ts — permanently-null reconciliation totals and their dead UI removed.

Files Reviewed (1 file, incremental since 8d86c31)

• apps/web/src/routers/admin/cloud-billing-skus-router.test.ts

Previous Review Summaries (5 snapshots, latest commit 8d86c31)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 8d86c31)

Status: 1 Issue Found | Recommendation: Address before merge

Executive Summary

Both previously reported issues are fixed in 8d86c31; the only remaining finding is that the capacity-mismatch reconciliation test lost the assertion that distinguished the tolerance branch.

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	1

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
apps/web/src/routers/admin/cloud-billing-skus-router.test.ts	782	Capacity-mismatch test asserts only status: 'comparison_unavailable', which the agreeing path also returns, so the CAPACITY_CROSS_CHECK_RELATIVE_TOLERANCE branch is unverified; assert statusDetail

Resolved since previous review

• UsageRecordsContent.tsx — statusDetail is now rendered for every row, so identity-mapping, unmapped-capacity, and capacity-mismatch outcomes are distinguishable again.
• cloud-billing-skus-router.ts — permanently-null providerComparisonSeconds, differenceSeconds, differencePercent, totals.providerCpuTimeSec, and counts.matched were removed along with their dead summary tiles and Difference column.

Files Reviewed (3 files, incremental since e42d58a)

• apps/web/src/app/admin/cloud-billing-skus/UsageRecordsContent.tsx - 0 issues
• apps/web/src/routers/admin/cloud-billing-skus-router.ts - 0 issues
• apps/web/src/routers/admin/cloud-billing-skus-router.test.ts - 1 issue

Fix these issues in Kilo Cloud

Previous review (commit e42d58a)

Status: 2 Issues Found | Recommendation: Address before merge

Executive Summary

Collapsing the former matched status into comparison_unavailable made the admin table hide statusDetail for identity-mapping failures, unmapped capacity, and capacity mismatches, leaving four different outcomes indistinguishable in the reconciliation UI.

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	1

Issue Details (click to expand)

WARNING

File	Line	Issue
apps/web/src/app/admin/cloud-billing-skus/UsageRecordsContent.tsx	943	row.status !== 'comparison_unavailable' suppresses statusDetail for identity-issue, unmapped-capacity, and capacity-mismatch rows, which now share one badge label

SUGGESTION

File	Line	Issue
apps/web/src/routers/admin/cloud-billing-skus-router.ts	531	totals.providerComparisonSeconds/differenceSeconds/differencePercent/providerCpuTimeSec and counts.matched are permanent constants, leaving summary tiles, the row Difference column, and 0 matched as dead UI

Files Reviewed (3 files, incremental since b2bc5fd)

• apps/web/src/app/admin/cloud-billing-skus/UsageRecordsContent.tsx - 1 issue
• apps/web/src/routers/admin/cloud-billing-skus-router.ts - 1 issue
• apps/web/src/routers/admin/cloud-billing-skus-router.test.ts - 0 issues

Fix these issues in Kilo Cloud

Previous review (commit b2bc5fd)

Status: No Issues Found | Recommendation: Merge

Executive Summary

Incremental update hardens reconciliation state handling (deduplicated sharedProvisionedCapacity, exhaustive status switches, stale-mutation guarding via sameSummaryRequest) and removes the always-true hasUsage field as dead code; no new issues found.

Files Reviewed (5 files)

• apps/web/src/app/admin/cloud-billing-skus/UsageRecordsContent.tsx
• apps/web/src/lib/cloudflare/container-usage-analytics.test.ts
• apps/web/src/lib/cloudflare/container-usage-analytics.ts
• apps/web/src/routers/admin/cloud-billing-skus-router.test.ts
• apps/web/src/routers/admin/cloud-billing-skus-router.ts

Previous review (commit 97131ec)

Status: No Issues Found | Recommendation: Merge

Executive Summary

Incremental update only removes the Playwright e2e spec (cloud-billing-reconciliation.spec.ts); no other source changes to review, and no issues found in the remaining reconciliation code.

Files Reviewed (7 files)

• ENVIRONMENT.md
• apps/web/src/app/admin/cloud-billing-skus/UsageRecordsContent.tsx
• apps/web/src/lib/cloudflare/container-usage-analytics.test.ts
• apps/web/src/lib/cloudflare/container-usage-analytics.ts
• apps/web/src/lib/config.server.ts
• apps/web/src/routers/admin/cloud-billing-skus-router.test.ts
• apps/web/src/routers/admin/cloud-billing-skus-router.ts

Previous review (commit 067a8d2)

Status: No Issues Found | Recommendation: Merge

Files Reviewed (8 files)

• ENVIRONMENT.md
• apps/web/src/app/admin/cloud-billing-skus/UsageRecordsContent.tsx
• apps/web/src/lib/cloudflare/container-usage-analytics.test.ts
• apps/web/src/lib/cloudflare/container-usage-analytics.ts
• apps/web/src/lib/config.server.ts
• apps/web/src/routers/admin/cloud-billing-skus-router.test.ts
• apps/web/src/routers/admin/cloud-billing-skus-router.ts
• apps/web/tests/e2e/cloud-billing-reconciliation.spec.ts

---

_{Reviewed by claude-opus-5 · Input: 30 · Output: 3.5K · Cached: 565.2K}

_{Review guidance: REVIEW.md from base branch main}