feat(cost): add org and team monthly budgets with alerting

[ayushtr-aws]

Adds recurring monthly USD guardrails for Cognito users and groups, with admission enforcement, threshold alerts, operator controls, and read-only personal visibility.

Area

• cdk — infrastructure, handlers, constructs
• agent — Python runtime / Docker image
• cli — bgagent client
• docs — guides or design sources (docs/guides/, docs/design/)
• tooling — root mise.toml, scripts, CI workflows

Related

Closes #471

Changes

• Add recurring user and Cognito-group monthly budget configuration and UTC-month spend rollups.
• Check personal and applicable team hard-stop budgets at the shared task-admission boundary, returning 429 BUDGET_EXCEEDED without interrupting running work.
• Roll terminal task cost_usd into user/team scopes idempotently through the existing TaskTable stream reconciler.
• Emit one-shot 80% and 100% CloudWatch threshold metrics and notify the shared operational SNS topic.
• Add operator bgagent budget status|set commands and authenticated, read-only bgagent budget status --me personal visibility.
• Document organization-group setup, onboarding overhead, enforcement behavior, estimated AWS operating cost, and the distinction from authoritative AWS billing.
• Keep the change scoped to CDK, CLI, and documentation; no agent runtime or agent-registry changes are included.

Validation

• CDK lint and TypeScript compilation
• CDK: 203 suites, 4,117 tests passed
• CLI lint and TypeScript compilation
• CLI: 58 suites, 769 tests passed
• Documentation Astro check, link check, and 78-page static build
• Drift-prevention and whitespace checks
• Deployed smoke test: personal status started at $0.00; a $0.0573 task stopped by its per-task limit and a $0.0270 completed task both rolled up, producing $0.08 monthly spend

mise was unavailable in the implementation shell, so the package-native equivalents were used.

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

[ayushtr-aws]

Addressed the self-review in a41a06f.

• B1 fixed: orchestration reconciliation and budget rollup are now attempted independently for every TaskTable stream record. A failure in either still requests an isolated retry, but cannot prevent the other subsystem from progressing.
• N1 fixed: added coverage for a single rollup crossing both 80% and 100%.
• N2 fixed: threshold metrics now emit before the conditional claim. This removes the permanent alert-loss window; rare concurrent/crash retries may emit a harmless duplicate, which is documented.
• N3 fixed: operator status now rejects corrupt non-positive configured limits consistently with admission and personal status.
• N4 retained intentionally: duplicate deliveries still reload state and retry alert work. Returning early after the task dedupe marker would permanently lose an alert when spend committed but alert delivery failed. A code comment and recovery test now make this explicit.
• N5 deferred: reliably recording the modifying AWS principal would require a new STS dependency/request and is better handled as a dedicated auditability enhancement.
• N6 addressed: native Cognito array claims preserve exact names; docs recommend avoiding whitespace/commas because API Gateway's string fallback treats them as delimiters.
• N7 fixed: added admission and rollup coverage for the 99-scope transaction boundary.

The failed build (agentcore) check was unrelated to agent registry. AgentCore built successfully; the mutation guard caught a stale root yarn.lock after the new Cognito SDK dependency. This commit includes the regenerated lockfile, verified with yarn install --frozen-lockfile.

Validation on the final source changes:

• CDK: 203 suites, 4,124 tests
• CLI: 58 suites, 770 tests
• CDK/CLI lint and TypeScript compilation
• Docs check/build: 78 pages
• Docs link check and all drift-prevention checks