feat(cost-insights): Introduce Cost Insights feature

[jeanduplessis]

Summary

Adds owner-scoped Cost Insights for personal users and organizations so authorized users can inspect Credit spend, configure Spend Alerts, review alert episodes, and act on Cost Suggestions.

• Adds Cost Insights dashboard, activity, Ask Kilo, and settings routes with responsive personal and organization UI.
• Adds normalized hourly spend rollups, coverage tracking, repair/backfill jobs, and atomic updates across Credit-spend paths.
• Adds anomaly and rolling 24-hour threshold evaluation, active episode state, notification delivery, retention cleanup, and cron entry points.
• Adds Coding Plan and Kilo Pass Cost Suggestions based on observed spend, with dismissal history and independent enablement.
• Adds owner-scoped authorization, current-recipient revalidation, server-side activity pagination, captured contributor evidence, and numeric sidebar review badges.
• Adds generated database migrations, seed data, Storybook coverage, and regression tests for rollups, evaluation, presentation, routing, and billing integrations.

Verification

• Not manually verified in browser in this session.

Visual Changes

N/A - screenshots were not captured as part of this update.

Reviewer Notes

• Review spend-writer transaction boundaries carefully: Credit spend and its hourly rollup must commit atomically.
• Review anomaly coverage and repair behavior around incomplete historical windows and current partial hours.
• Review organization authorization and notification recipient revalidation for owners and billing managers.
• Cost Suggestions remain advisory and independent from Spend Alert enablement; they do not alter billing or spend behavior.
• Activity history uses server-side filtering and pagination, while alert events resolve current actor labels from captured driver IDs.

Run this branch locally

Prerequisites: Docker Desktop must be running, tmux must be installed, and .env.local must contain a local POSTGRES_URL. Use Node from .nvmrc and pnpm from package.json.

1. Fetch and check out the branch. For a first checkout, use the tracking command; if the branch already exists locally, use git switch jdp/cost-insights && git pull --ff-only instead.

git fetch origin jdp/cost-insights
git switch --track origin/jdp/cost-insights
nvm install
nvm use
corepack enable
pnpm install

2. Configure local environment variables if this clone is not already configured. Team members with Vercel access can use the first path; otherwise use the interactive local setup.

# Team-member/Vercel path
vercel link --project kilocode-app
vercel env pull

# Or local-only setup
pnpm dev:setup-env

# Generate service-specific local env files after either path
pnpm dev:env

3. Start PostgreSQL and apply this branch's migrations. Re-run migration after every pull that adds migration files.

docker compose -f dev/docker-compose.yml up -d --wait postgres
pnpm drizzle migrate

4. Seed the Cost Insights fixture before opening the UI.

pnpm dev:seed cost-insights:spend-evidence

5. Start the app.

pnpm dev:start

Default web URL is http://localhost:3000. If another Kilo dev stack is running, generate env and start this worktree with a stable automatic offset, then read the actual Next.js port from status output:

KILO_PORT_OFFSET=auto pnpm dev:env
KILO_PORT_OFFSET=auto pnpm dev:start
KILO_PORT_OFFSET=auto pnpm dev:status --json

What the seed creates

pnpm dev:seed cost-insights:spend-evidence creates a deterministic, owner-scoped fixture containing:

• 90 days of personal and organization Variable Credit spend.
• Monthly KiloClaw Scheduled Credit spend.
• Current-hour anomaly spikes and rolling 24-hour threshold crossings.
• Active Spend Alert banners, Coding Plan and Kilo Pass Cost Suggestions, notification rows, and activity history.
• An organization named [seed:cost-insights] Northstar Labs with owner, billing manager, and member-attributed spend drivers.
• Matching hourly rollups and complete coverage metadata, so all 24h, 7d, 30d, and 90d views are populated.

The command prints personalLoginPath, organizationLoginPath, owner IDs, organization ID, record counts, and the database target. Prefix a printed login path with http://localhost:<nextjs-port>.

Seed identities:

Purpose	Email
Personal Spend owner and organization owner	cost-insights-owner@example.com
Organization billing manager	cost-insights-billing-manager@example.com
Organization spend contributor fixture	cost-insights-member@example.com

Organization ID: 4f2fc143-4b30-4c8a-878b-df89c89c6790.

With the default port, use these direct fake-login URLs:

Personal dashboard:
http://localhost:3000/users/sign_in?fakeUser=cost-insights-owner%40example.com&callbackPath=%2Fcost-insights

Organization dashboard as owner:
http://localhost:3000/users/sign_in?fakeUser=cost-insights-owner%40example.com&callbackPath=%2Forganizations%2F4f2fc143-4b30-4c8a-878b-df89c89c6790%2Fcost-insights

Organization dashboard as billing manager:
http://localhost:3000/users/sign_in?fakeUser=cost-insights-billing-manager%40example.com&callbackPath=%2Forganizations%2F4f2fc143-4b30-4c8a-878b-df89c89c6790%2Fcost-insights

Organization dashboard as read-only Kilo admin:
http://localhost:3000/users/sign_in?fakeUser=cost-insights-reviewer%40admin.example.com&callbackPath=%2Forganizations%2F4f2fc143-4b30-4c8a-878b-df89c89c6790%2Fcost-insights

Wait for fake-login account creation to finish before evaluating the page. The owner and billing manager can change settings and review items. The Kilo admin can inspect the organization but must not receive mutation or checkout controls. The regular member exists to exercise contributor attribution and is not authorized to open organization Cost Insights.

Suggested local checks

• Confirm personal and organization dashboards show anomaly and threshold banners, suggestions, spend metrics, and top drivers.
• Switch spend evidence among 24h, 7d, 30d, and 90d; zero-spend buckets should have zero-height bars.
• Open Activity, switch each filter, and paginate through retained events.
• Disable the threshold from its alert action; confirm the banner clears, settings update, and activity records the change.
• Dismiss a suggestion and acknowledge alerts; confirm sidebar review count decreases.
• Open organization settings as owner and billing manager, then repeat as the fake Kilo admin to confirm read-only behavior.

Seed safety and reset behavior

• The seed refuses USE_PRODUCTION_DB=true and rejects any POSTGRES_URL whose host is not loopback (localhost, 127.0.0.1, or ::1).
• Rerunning the seed is the normal reset path. It replaces only this fixture's stable users, organization, spend evidence, rollups, events, suggestions, and notification rows.
• Seeded users use placeholder Stripe customer IDs. Use fake login for Cost Insights pages; do not open Stripe-backed billing pages with these users.
• To restore mutated Cost Insights state after testing, rerun pnpm dev:seed cost-insights:spend-evidence.
• For a completely fresh local database, stop the app and run the destructive reset below. This removes all local app data, not only Cost Insights fixtures.

pnpm dev:stop
pnpm dev:db:reset
pnpm drizzle migrate
pnpm dev:seed cost-insights:spend-evidence
pnpm dev:start

[pandemicsyn]

Found additional correctness issues and non-blocking performance warnings after excluding feedback already present on the PR. Database performance warnings are advisory and do not individually block merging.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

This incremental review covers the 17 files changed since the last review; all 4 previously flagged findings (non-concurrent index creation on credit_transactions/exa_usage_log in the migration, the anomaly-dedup timestamp comparison bug, and the hardcoded placeholder org slug) are fixed in this update, and no new issues were introduced.

Files Reviewed (17 files)

• apps/storybook/stories/cost-insights/CostInsightsAlertBar.stories.tsx
• apps/web/src/components/cost-insights/CostInsightsOverviewClient.tsx
• apps/web/src/components/cost-insights/overview/CostInsightsDashboardView.tsx
• apps/web/src/components/cost-insights/overview/DashboardNotices.tsx
• apps/web/src/components/cost-insights/overview/SpendEvidenceCard.tsx
• apps/web/src/components/cost-insights/settings/CostInsightsSettingsView.tsx
• apps/web/src/components/cost-insights/shell/CostInsightsAlertBar.tsx
• apps/web/src/components/cost-insights/useCostInsightsTracking.ts
• apps/web/src/lib/cost-insights/evaluation.ts
• apps/web/src/lib/cost-insights/presenter.test.ts
• apps/web/src/lib/cost-insights/presenter.ts
• apps/web/src/lib/credit-transaction-indexes-script.test.ts
• apps/web/src/scripts/db/credit-transaction-indexes.ts
• packages/db/src/migrations/0176_cynical_norrin_radd.sql
• packages/db/src/migrations/meta/0176_snapshot.json
• packages/db/src/migrations/meta/_journal.json
• packages/db/src/schema.ts

Previous Review Summary (commit 5f4ddc4)

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

Previous review (commit 5f4ddc4)

Status: 4 Issues Found | Recommendation: Address before merge

Executive Summary

The generated migration applies non-concurrent CREATE INDEX statements to the populated, actively-written credit_transactions and partitioned exa_usage_log tables, risking write locks on core billing paths during deploy.

Overview

Severity	Count
CRITICAL	0
WARNING	4
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
packages/db/src/migrations/0176_opposite_tiger_shark.sql	313	Non-concurrent CREATE INDEX on populated credit_transactions table blocks writes during build
packages/db/src/migrations/0176_opposite_tiger_shark.sql	315	Non-concurrent CREATE INDEX on partitioned exa_usage_log recurses into every partition with locking builds, bypassing this PR's own safe per-partition CONCURRENTLY script
apps/web/src/lib/cost-insights/evaluation.ts	184	Anomaly-episode dedup short-circuit compares canonical ISO hourStart to raw, unnormalized Postgres timestamp text, so it never matches and the intended re-evaluation short-circuit never fires
apps/web/src/components/cost-insights/shell/CostInsightsAlertBar.tsx	14	Hardcoded placeholder org slug (acme-cost-insights) in the organization review link; currently unreachable from any route but broken by construction if ever wired up

Verification of prior review feedback

This PR previously received 66 inline review comments from human and bot reviewers. All findings with a currently-resolvable line mapping were re-verified against the current HEAD (5f4ddc459e) and confirmed fixed, including: independent active-alert snapshots surviving event retention, transactional event/state writes, stale-episode acknowledgment guarding via episode-ID match, added indexes for previously-flagged missing-index performance issues, hourly-rollup-based rolling-window evidence queries, roving-focus chart accessibility, sidebar badge accessibility, settings mutation invalidation awaiting, and upstream Exa response runtime validation. No duplicates of those findings are included above.

Files Reviewed (125 files)

Full PR diff (base 0e8b4d1e → head 5f4ddc459) across Cost Insights dashboard/activity/settings/Ask Kilo UI, presenter/formatting/tracking, evaluation/jobs/notifications, repository/spend-repository/canonical-sources, routers and API routes (cron, Exa), database schema/migrations/rollups, seed fixtures, and Storybook stories.

Fix these issues in Kilo Cloud

---

_{Reviewed by claude-sonnet-5-20260630 · Input: 94 · Output: 21.8K · Cached: 3.7M}

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