feat(cloud-agent-next): add Vercel billing identity and settlement producer scaffolding

[eshurakov]

Summary

First chunk of a two-PR stack that lets Vercel sandbox sessions be billed the same way as the
Cloudflare containers runtime: wall-clock seconds metered through the shared
@kilocode/container-usage meter while the sandbox is alive.

This PR is inert infrastructure plus the producer module. Nothing in the Durable Object calls or
constructs the new pieces, so it is safe to merge on its own and cannot change live behaviour.

What's included

• container-usage-context.ts — SandboxVercelSmall / SandboxVercelLarge, their SKUs,
  VERCEL_BILLING_CAPACITIES (2 vCPU/4096 MiB, 4 vCPU/8192 MiB, no disk), vercelBillingIdentity,
  capacity lookup, the isolated-small arm of assertSandboxBillingAllocation, and exclusion of the
  Vercel classes from LegacySandboxClassName. SANDBOX_CAPACITIES and
  CONTAINERS_BILLING_CAPACITIES are unchanged.
• control-alarm.ts — billingDueAt composed into the single control alarm. null preserves the
  existing composition exactly; this file remains the only setAlarm/deleteAlarm caller.
• billing-schedule.ts (new) — durable per-callback schedule table with load-before-snapshot,
  "not loaded" distinct from "empty", retryNotBefore, and a dirty-bit compose callback. No alarm
  calls.
• metered-billing-lifecycle.ts — omit disk_mb when a capacity has no disk; add pinAssumeHeld,
  public pinMeasurementCursor, and openIntervalBeforeCreate. Containers do not call these and
  their first-schedule stamp is unchanged.
• vercel-billing.ts (new) — prepareSettlement / deliverSettlement; pin, zero segment, settlement
  end from stored createdAt/terminal time (never Date.now()); settlement delivery routes through
  billingHeartbeatTick so stop retry and the 60-minute abandon apply.
• SandboxControl.ts — pass billingDueAt: null so the new argument compiles.

Verification

• vitest run on the chunk files: 6 files, 130 passed.
• pnpm lint: 0 warnings, 0 errors.
• pnpm typecheck: exit 0.

Notes

• Part of a stack. The wiring chunk stacks on this branch and turns the path on.
• Operator prerequisite for recording: cloud_billing_sku rows cloud-agent-vercel-small-2026-09
  and cloud-agent-vercel-large-2026-09 (unit second, positive rate, accepts_new_usage = true).

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

The branch was rebased (the previously reviewed SHA is not an ancestor), so I re-reviewed the full 11-file PR diff against current HEAD: the Vercel billing identity/capacity wiring, the disk_mb omission path, the billingDueAt alarm composition, the durable BillingScheduleTable, and the settlement producer. No security, correctness, or memory-growth defects were found in the changed lines.

Files Reviewed (11 files)

• services/cloud-agent-next/src/container-usage-context.ts
• services/cloud-agent-next/src/container-usage-context.test.ts
• services/cloud-agent-next/src/metered-billing-lifecycle.ts
• services/cloud-agent-next/src/persistence/SandboxControl.ts
• services/cloud-agent-next/src/sandbox-containers/containers-billing.test.ts
• services/cloud-agent-next/src/sandbox-control/billing-schedule.ts
• services/cloud-agent-next/src/sandbox-control/billing-schedule.test.ts
• services/cloud-agent-next/src/sandbox-control/control-alarm.ts
• services/cloud-agent-next/src/sandbox-control/control-alarm.test.ts
• services/cloud-agent-next/src/sandbox-control/vercel-billing.ts
• services/cloud-agent-next/src/sandbox-control/vercel-billing.test.ts

Previous Review Summary (commit 624045b)

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

Previous review (commit 624045b)

Status: No Issues Found | Recommendation: Merge

Files Reviewed (11 files)

• services/cloud-agent-next/src/container-usage-context.ts
• services/cloud-agent-next/src/container-usage-context.test.ts
• services/cloud-agent-next/src/metered-billing-lifecycle.ts
• services/cloud-agent-next/src/persistence/SandboxControl.ts
• services/cloud-agent-next/src/sandbox-containers/containers-billing.test.ts
• services/cloud-agent-next/src/sandbox-control/billing-schedule.ts
• services/cloud-agent-next/src/sandbox-control/billing-schedule.test.ts
• services/cloud-agent-next/src/sandbox-control/control-alarm.ts
• services/cloud-agent-next/src/sandbox-control/control-alarm.test.ts
• services/cloud-agent-next/src/sandbox-control/vercel-billing.ts
• services/cloud-agent-next/src/sandbox-control/vercel-billing.test.ts

Verified the Vercel billing identity/capacity wiring, the disk_mb-omission path, the billingDueAt: null alarm composition, the durable BillingScheduleTable (load dedupe, dirty-bit compose loop, retry backoff, payload/due fencing), and the prepareSettlement/deliverSettlement producer. No security, correctness, or memory-growth defects were found in the changed lines; the new modules are not yet constructed by the Durable Object, so the PR is inert as described.

---

_{Reviewed by deepseek-v4.1-flash · Input: 0 · Output: 0 · Cached: 0}

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