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.