fix: quota-exceeded users can still start sessions (stopped after 3min)

[nikolanovoselec]

Bug

When a user reaches 100% of their monthly compute quota, they can still click "+ New Session" and start a container. The session runs for ~3 minutes (startup guard period) until the Timekeeper KV updates and the quota check kicks in, at which point the session is stopped and the user is kicked back to the dashboard.

The user can repeat this indefinitely — each cycle wastes container resources and gives ~3 minutes of free compute.

Expected Behavior

Users who have exceeded their quota should be blocked from starting new sessions entirely, similar to how trial users cannot start more than 1 concurrent session. The "+ New Session" button should be disabled and show a message like "Monthly quota exceeded — upgrade to continue."

Current Flow (broken)

1. User reaches 100% quota
2. User clicks "+ New Session" — container starts
3. Container runs for ~3 min (startup guard protects new sessions from immediate quota kill)
4. Timekeeper ping returns quotaExceeded: true — container stopped via SIGTERM
5. User lands on dashboard — can repeat from step 2

Expected Flow

1. User reaches 100% quota
2. batch-status returns quota state — frontend disables "+ New Session"
3. POST /api/container/start rejects with 402 QUOTA_EXCEEDED (server-side guard)
4. User sees upgrade CTA

Where to Fix

• Frontend: isAtUsageQuota() already exists in session-usage.ts and disables the button — verify it's wired correctly to the "New Session" button state
• Backend: validateSessionAndCheckLimits() in container lifecycle should check quota BEFORE starting the container, not rely on Timekeeper ping after startup
• REQ-SUB-007 (quota enforcement) and REQ-SUB-008 (mid-session quota stop) — the gap is between these two: pre-start enforcement needs to be airtight

References

• web-ui/src/stores/session-usage.ts — isAtUsageQuota()
• src/routes/container/lifecycle.ts — validateSessionAndCheckLimits()
• src/timekeeper/index.ts — quota ping handler
• sdd/subscription.md — REQ-SUB-007, REQ-SUB-008

[nikolanovoselec]

Investigation notes (not yet fixed)

Looked into this. Have a leading theory but it doesn't fully explain the symptom — flagging here so future-me (or someone else) doesn't redo the same dead end.

Leading theory: stale KV in validateSessionAndCheckLimits

The /api/container/start endpoint already calls validateSessionAndCheckLimits (src/routes/container/lifecycle.ts:147-166) which DOES check usage quota. But the check reads getTimekeeperKey(bucketName) from KV, which the Timekeeper Durable Object only flushes every 5 minutes (src/timekeeper/index.ts:22 FLUSH_INTERVAL_MS = 300_000).

Between flushes, KV is stale by up to 5 min. The Timekeeper DO has the live state in lastFlushedMonthlyTotal + pendingSeconds.

Pattern to copy: src/routes/usage.ts:24-42 already queries the Timekeeper DO directly via tk.fetch('http://timekeeper/usage') for live state with KV fallback. The same pattern should be applied to validateSessionAndCheckLimits and to src/routes/session/lifecycle.ts:139 (batch-status endpoint, which feeds the frontend's `isAtUsageQuota()` check that disables the New Session button).

Why the theory is incomplete

If the bug were purely stale-KV, it would only manifest within the 5-minute window between hitting quota and the next Timekeeper flush. After that flush, KV would be fresh and subsequent starts would correctly reject.

For the bug to persist beyond 5 minutes, there must be some other mechanism:

• A literal startup-grace window in the start path that I haven't found yet (couldn't locate via grep on STARTUP_GRACE, 180_000, 3 \* 60, etc.)
• OR the Timekeeper flush isn't happening as expected after a kill (e.g., container DO destroy clears state before alarm fires)
• OR a different start path bypasses `validateSessionAndCheckLimits` entirely (terminal WebSocket upgrade in `src/routes/terminal.ts:110` doesn't call it — but the frontend does call `POST /container/start` first per `web-ui/src/api/client.ts:143`, so this should be covered)

Proposed next steps

1. Reproduce the bug deliberately: hit 100% quota, observe the kill, immediately try to start a new session, capture timestamps. Check whether the bug persists past the 5-minute KV flush window.
2. If bug persists past 5 min: there's a real guard somewhere I missed. Add logging in `validateSessionAndCheckLimits` to print the `monthlySeconds` it's reading vs the tier limit, then push and reproduce.
3. If bug only happens within 5 min: stale-KV theory is correct, fix is the Timekeeper-DO query pattern (10 lines in `lifecycle.ts` + same in `session/lifecycle.ts` for `batch-status`).

Reverted my exploratory fix on branch `fix/quota-bypass-and-cf-access-skip` so develop stays clean.