@terreno/mcp 57.18.0 → 57.19.2

package/src/docs/versioned/next/implementationPlans/circleci-pr-speed-loop.md

@@ -0,0 +1,293 @@
+# Implementation Plan: CircleCI PR Speed Loop
+
+**Status:** In progress — iteration 0 (instrumentation) in review; iteration 1 picks the first lever
+**Owner:** Josh
+**Goal:** cut CircleCI wall-clock time for an **average PR** by **40% (≤ 5.7 min)**
+or to **under 4 min**, whichever comes first, without weakening any gate.
+**Driver:** run as a long-lived loop. `/terreno-scan:loop` with this document as
+the charter fits. Each iteration ships one PR-sized change through Pick → Roast →
+Brew → Taste.
+
+## Metric
+
+**PR CI wall clock:** from the first `ci/circleci:` status on a PR's head commit
+to the last terminal status of a test or build job. Excluded from the end time:
+`approve`, `architectural-pr-review`, `dco`, `deploy-*` previews, and
+`serial-*` deploy-group statuses. Those are review bots and previews, not tests.
+
+**Average PR:** a merged PR that touches **≤ 3 top-level directories**, not
+counting `docs/`, `website/`, or dot-directories (so `changelog/` counts).
+44 of the last 60 merged PRs qualify, and the median PR touches 2. PRs touching more than 3
+directories are tracked but do not count toward the goal.
+
+**Reported value:** the median over the last 20 qualifying merged PRs, plus the
+median of the benchmark set (below) for each experiment.
+
+### Baseline (last 60 merged PRs, measured 2026-10-25)
+
+| | Median | p25 | p75 |
+|---|---|---|---|
+| Average PRs (≤ 3 directories, n = 44) | **9.5 min** | — | — |
+| All PRs (n = 60) | 10.3 min | 5.9 min | 12.1 min |
+
+**Target:** median ≤ **5.7 min** (40% faster). If it gets there, keep going
+toward **≤ 4.0 min** only while iterations still pay off (see stop rules).
+
+Job that finished last on average PRs:
+
+| Job | PRs where it was last | Median duration | Median start after pipeline start |
+|---|---|---|---|
+| `e2e-app` | 13 / 44 | 4.0 min | 6.3 min (waits on `e2e-prepare`, 5.4 min) |
+| `api-ci` | 10 / 44 | 10.8 min | 1.0 min |
+| `repo-policies` | 5 / 44 | — | — |
+| `mcp-server-docker` | 4 / 44 | — | — |
+| `maestro-e2e` | 3 / 44 | 8.9 min | 0.9 min |
+| `new-file-coverage` | 3 / 44 | 3.5 min | 0.5 min |
+
+Other long jobs that can become last once these shrink:
+
+| Job | Median duration |
+|---|---|
+| `example-backend-docker` | 7.6 min |
+| `admin-spa-integration` | 6.0 min |
+| `ai-ci` | 5.9 min |
+| `admin-spa-ci` | 4.9 min |
+| `example-backend-ci` | 4.3 min |
+
+The setup workflow (path filtering plus continuation) costs about 0.6–1.0 min
+before any job starts. The 4-minute target needs that cut too.
+
+## Guardrails
+
+The loop may change anything in CI: config, resource classes, caching,
+parallelism, job graph, test runners, and test code. It may **not**:
+
+1. Delete, skip, or `.skip` a test. The one exception is a selection mechanism
+   (TIA, path filtering, the e2e affected gate) whose shadow run proves zero
+   misses over at least 2 weeks.
+2. Lower a coverage threshold, or move a blocking gate to post-merge. That
+   covers the 95% package gate, the 90% new-file gate, Knip zero findings, the
+   dependency-cruiser baseline, lint, and typecheck.
+3. Mark a flaky test as allowed-to-fail. Fix it or quarantine it with a
+   tracking issue, and count the quarantine as a regression for this goal.
+4. Make `master` or release pipelines less safe. `master` still runs
+   everything.
+5. Raise CircleCI spend more than **25%** per average PR without Josh's
+   approval. Report credits per average PR in every iteration.
+
+## The loop
+
+Each iteration is one PR. Keep going until a stop rule fires.
+
+1. **Measure.** Run `bun run ci:wall-clock --limit 20` for the rolling median
+   and the last-job histogram. Pull per-job step timings from
+   the CircleCI API (`CIRCLECI_TOKEN`; slug in `docs/how-to/circleci.md`) for
+   the top 2 critical-path jobs.
+2. **Pick the lever.** Take the job that is most often last. Choose the
+   highest-expected-gain lever for it from the backlog, or a new one found in
+   step 1. Write the hypothesis in the ledger, e.g. "caching the `bun install`
+   store cuts `api-ci` by 50 s".
+3. **Build it** on `ci-speed/<n>-<slug>` with Pick → Roast. Config changes
+   need `scripts/check-circleci-parity` and `circleci config validate` to pass.
+4. **Benchmark.** Run the [benchmark set](#benchmark-set) against the branch
+   and against `master` in the same hour, 2 runs each. The result is the
+   median of each case's median.
+5. **Decide.**
+   - **Keep:** benchmark median improves by **≥ 5%** (≈ 30 s) with every
+     guardrail intact. Brew → Taste → merge.
+   - **Drop:** under 5%, or any guardrail broken. Record why in the ledger and
+     close the PR.
+6. **Re-measure** after merge on the next 20 qualifying real PRs. Update the
+   ledger and the baseline table.
+7. **Loop.**
+
+### Stop rules
+
+- **Done:** the rolling real-PR median is ≤ 5.7 min (or ≤ 4.0 min) for 20
+  qualifying PRs in a row. Post a final report.
+- **Stalled:** 3 iterations in a row each gain under 5%. Escalate to Josh with
+  the current critical path, the levers tried, and the next options with their
+  cost (e.g. bigger resource classes, a paid feature, dropping a job from PRs
+  with proof).
+- **Blocked:** a lever needs a guardrail exception or a spend increase over
+  25%. Ask Josh.
+
+### Benchmark set
+
+Five recent average PRs whose code still reverts cleanly on `master`. They
+cover the jobs that most often finish last (`api-ci` and the e2e chain). Refresh
+them with `bun run ci:bench --suggest-cases` every 10 iterations, or sooner when
+a case replays as `invalid`.
+
+| Case | Shape | PR |
+|---|---|---|
+| `api-only` | `api` feature (plus changelog and docs) | #1491 |
+| `api-syncdb` | `api` plus `syncdb` | #1555 |
+| `ui-only` | `ui` component fix | #1567 |
+| `admin-example` | `admin-frontend` plus `example-frontend` | #1540 |
+| `small-package` | `create-terreno-app` | #1599 |
+
+Mechanics: `bun run ci:bench --branch <branch> --label <iteration>` (see
+[benchmark a CI change](../how-to/circleci.md#benchmark-a-ci-change)). For each
+case it opens two draft PRs labelled `ci-bench`, waits for CircleCI to settle,
+records the metric, and closes both PRs:
+
+- **Control:** `master` with the case's code hunks reverted.
+- **Treatment:** the branch under test with the case's code hunks reverted.
+
+The case list lives in `scripts/ci/bench/cases.ts`.
+
+### Ledger
+
+Append one row per iteration. Never edit past rows.
+
+| # | Date | Lever | Target job | Bench before → after | Real-PR median after | Credits/avg PR | Kept? | PR |
+|---|---|---|---|---|---|---|---|---|
+| 0 | 2026-10-25 | Baseline | — | — | 9.5 min | TBD | — | — |
+| 0 | 2026-10-26 | Instrumentation (`ci:wall-clock`, `ci:bench`) | — | `api-only` on master: 11.6 min (1 run, last job `api-ci`) | 9.5 min | TBD (needs CircleCI token) | Yes | this PR |
+
+## Lever backlog
+
+The order is a starting point. Re-rank every iteration from fresh step
+timings.
+
+### Iteration 0 — Instrumentation (½ day, required first)
+
+- Add `bun run ci:wall-clock` (`scripts/ci/ciWallClock/`), with tests, from
+  the measurement used for the baseline above.
+- Add `bun run ci:bench` (`scripts/ci/bench/`).
+- Pull step-level timings for `api-ci`, `e2e-prepare`, `e2e-app`,
+  `maestro-e2e`, and `example-backend-docker`. Record how much of each is
+  checkout, `bun install`, dependency compile, lint, typecheck, and tests.
+
+### e2e chain (`e2e-prepare` 5.4 min → `e2e-app` 4.0 min)
+
+- **Cache the Expo web export**, keyed on a hash of the inputs it reads
+  (`example-frontend`, the workspace packages it bundles, `bun.lock`). On a
+  hit, `e2e-prepare` skips `bun expo export`. The e2e affected gate already
+  computes the reachable input set (`scripts/ci/e2eAffected`), so reuse it for
+  the cache key.
+- Build `e2e-prepare` in parallel with lint and compile, not after them, and
+  start shards as soon as their artifact exists.
+- Rebalance or split `e2e-app`, the slowest shard, using Playwright timing
+  data. Static splitting is free with `circleci testsuite`.
+
+### `api-ci` (10.8 min)
+
+- Split lint, typecheck, and tests into parallel jobs. The test step alone is
+  about 4 min locally.
+- Static test splitting across `parallelism: 2–3` nodes. This needs the
+  coverage-splice work below, so each node's LCOV can combine into one exact
+  report.
+- Make every test file pass alone. 10 `api` files fail today, mostly 5 s
+  `beforeAll` timeouts. Splitting and TIA both need this.
+- **Test impact analysis**, piloted as described in
+  [Appendix A](#appendix-a--smarter-testing-findings). The simulation selects
+  about 46% of `api` test time on a typical PR.
+
+### Every job
+
+- Cache the `bun install` store. All jobs install without a cache today.
+- Cache workspace `dist/` output from `compile_packages`, keyed by each
+  package's source hash.
+- Right-size resource classes for jobs on the critical path. `large` costs
+  2× `medium` credits per minute but can halve CPU-bound steps. Check against
+  guardrail 5.
+- Shorten the setup workflow: path filtering plus continuation takes about
+  0.6–1.0 min.
+
+### `maestro-e2e` (8.9 min), `example-backend-docker` (7.6 min), `admin-spa-integration` (6.0 min)
+
+- Reuse the Expo export cache from the e2e chain in `maestro-e2e` and
+  `admin-spa-integration`.
+- Tighten path filters. Check these run only when their inputs change.
+- `example-backend-docker`: make better use of layer cache through BuildKit
+  `--cache-from` on a registry image. Docker Layer Caching costs 200 credits
+  per job, so compare costs first.
+
+## Appendix A — Smarter Testing findings
+
+Source docs:
+[get started](https://circleci.com/docs/guides/test/getting-started-with-smarter-testing/),
+[test impact analysis](https://circleci.com/docs/guides/test/set-up-test-impact-analysis/),
+[`test-suites.yml` reference](https://circleci.com/docs/reference/testsuite-configuration-reference/),
+[overview and credit charge](https://circleci.com/docs/guides/test/smarter-testing-overview/).
+
+**How it works.** `.circleci/test-suites.yml` defines suites with `discover`
+(lists test atoms, here files) and `run` (gets `<< test.atoms >>` and writes
+`<< outputs.junit >>`). An optional `analysis` command is the run command with
+coverage, writing `<< outputs.lcov >>` one atom at a time. The job step becomes
+`circleci testsuite run "<suite>"`, run from the package root.
+
+- **Analysis** runs on `master` and records which files each atom covers.
+- **Selection** runs on PRs. It runs new atoms, atoms that failed last time,
+  and atoms whose covered files changed. `full-test-run-paths` and
+  `test-selection-rules` cover what coverage cannot see.
+- **Free:** `testsuite run`, static splitting, rerun-only-failed, and test
+  uploads.
+- **Charged:** TIA, dynamic splitting, dynamic parallelism, and auto-rerun, at
+  3,000 credits per 100k atoms above the plan allowance. Estimated $1–3 a month
+  for us.
+
+**Bun compatibility (verified locally).**
+`bun test --reporter=junit --reporter-outfile=…` writes JUnit, and
+`bun test --coverage --coverage-reporter=lcov --coverage-dir=<dir> <atom>`
+writes a usable LCOV. Bun writes to a directory, so `analysis` needs a wrapper
+that moves `lcov.info` to `<< outputs.lcov >>`.
+
+**Selection simulation.** I ran each `api` and `ui` test file alone with
+coverage, then replayed the last 60 PR merges per package (version bumps
+excluded):
+
+| | `api` | `ui` |
+|---|---|---|
+| Atoms | 149 | 201 |
+| Full suite, local | 3 m 49 s | 1 m 14 s |
+| Analysis, one atom at a time | 17 min serial | 55 s at 4-way |
+| Atoms failing when run alone | 10 | 1 |
+| PRs forced to a full run | 19 / 60 | 14 / 60 |
+| Mean / median share of test time selected | 46% / 39% | 43% / 43% |
+
+Hub files limit the savings. In `api`, `logger.ts` and `requestContext.ts`
+are covered by 149/149 atoms and `errors.ts` by 131. Coverage also cannot see
+across packages: every `bunfig.toml` ignores `../**` and dependencies resolve
+to `dist/`. Each downstream suite therefore needs `full-test-run-paths` for
+its upstream packages. Whether paths outside the CLI's working directory are
+allowed must be checked with `circleci testsuite doctor`.
+
+**Coverage splicing (keeps gates blocking and exact).** The PR job builds a
+whole-package LCOV, then runs the unchanged 95% gate, the 90% new-file gate,
+and the Codecov upload on it.
+
+- **Changed files** (vs merge base) come from the PR's selected run. All atoms
+  covering them run in one `bun test` process, so those files are exact.
+- **Unchanged files** come from `master`'s full-run LCOV at the merge base,
+  using the per-file maximum with the PR run.
+- **Wiring:** `master` saves `coverage/lcov.info` via `save_cache`, keyed
+  `cov-base-<pkg>-{{ checksum "base-sha.txt" }}`. The PR job writes the merge
+  base to `base-sha.txt` and restores that key.
+- **Fallback:** if there is no baseline, or a full-run path changed, run the
+  full coverage suite as today.
+
+Why per-file and not per-atom: Bun reports a different set of instrumented
+lines per process, and writes only `FNF`/`FNH` totals, not which functions
+ran. Merging the 149 per-atom `api` reports gave 95.24% functions vs 98.95%
+real.
+
+Validated on `ui`: baseline at `7fc9843c^`, PR at HEAD, 9 changed files,
+16/201 atoms selected (7.9 s vs 74 s). The spliced report matched the full run
+exactly: 211/211 files, lines 99.25% = 99.25%, functions 98.61% = 98.61%.
+
+Known gap: an unchanged file can lose coverage when a changed file stops
+calling it. The `master` full run catches this right after merge and must
+comment on the PR.
+
+**TIA pilot steps (when the loop picks this lever).**
+1. Add the suite with `test-impact-analysis: true`,
+   `test-analysis-duration: 20`, and `full-test-run-paths`. Run analysis as a
+   non-blocking `master` job.
+2. Shadow it on PRs for 2 weeks. `list-tests` records what would be selected,
+   while the full suite still runs. Compare spliced LCOV against full LCOV,
+   file by file.
+3. Make it blocking only with zero selection misses, zero splice mismatches,
+   and a median test-step saving of at least 40%.

package/src/docs/versioned/next/implementationPlans/infra-mcp.md

@@ -29,9 +29,11 @@ A deployable, self-contained MCP server that puts privileged infrastructure tool
 | Write safety | **Write tools require per-call confirmation (MCP elicitation).** A config option can disable confirmation per integration or globally, but it only takes effect for users holding `infra:writeUnconfirmed` — everyone else is still prompted |
 | Phase 1 scope | **Read-only:** GCP observability (logs/metrics/errors), Sentry, MongoDB |
 | GCP credentials | **Cloud Run default runtime service account only (ADC).** No injected SA key env vars anywhere; the `GCP_SA_*` pattern for cloud agents is retired. IAM on the runtime SA is the outer bound; the MCP's RBAC is the per-user gate |
-| Other credentials | Static tokens (Sentry auth token, Mongo connection strings, later `EXPO_TOKEN`/Vercel token) from Secret Manager/env |
+| Other credentials | Static tokens (Sentry auth token, Mongo connection strings, later `EXPO_TOKEN`) from Secret Manager/env |
+| Vercel credentials | **One team-scoped token per Vercel team**, keyed by team slug; each project resolves to its team by asking which token can see it (cached). Project-scoped tokens are not enough: they list deployments and read build logs but get 403 on runtime logs (`POST /v1/observability/events`, measured 2026-10-25; the CLI says "You don't have access to runtime logs for this project"), and Vercel has no scope between project and team |
+| Resource scoping | An integration's reads can be narrowed per caller to named vendor resources (e.g. a machine user may read only its own Vercel projects) with an RBAC `scopes` entry (`vercel.read`). The tool resolves the resource first, then calls `access.can({permissions: {vercel: ["read"]}, context: {projectId}})`. Unknown and forbidden resources get the same refusal, so a caller can't probe names |
 | User store & login | Mongo users via `@terreno/api` (`baseUserPlugin` + `rbacUserPlugin`); MCP clients authenticate via OAuth 2.1 using **`@better-auth/oauth-provider` + `@better-auth/mcp`** (already aligned with the 2026-07-28 authorization spec: CIMD, RFC 9728, `requireMcpAuth`) |
-| Non-human callers | Service tokens (Better Auth `apiKey` plugin if compatible, else a `ServiceToken` model) mapped to machine users with RBAC roles — this is how cloud agents call the server |
+| Non-human callers | Service tokens (Better Auth `apiKey` plugin if compatible, else a `ServiceToken` model) mapped to machine users with RBAC roles — this is how cloud agents call the server. An orchestrator that starts agent sandboxes mints **one machine user and one token per sandbox** at create (role scoped to that sandbox's repo/resources) and revokes them at teardown. It's per sandbox, not per repo, because `@terreno/api` caps a user at ten live service tokens |
 | Packaging | New workspace package `infra-mcp/` publishing `@terreno/infra-mcp`; config-driven integration registry; deployed via a clone of the existing `mcp_service` terraform module |
 
 ## Architecture
@@ -44,7 +46,9 @@ POST /mcp  — SDK v2 createMcpHandler (2026-07-28 + legacy stateless)
   |
   1. Auth: Better Auth verifies token -> User (+ roles via rbacUserPlugin)
   2. Authz: access.can({[integration]: [tier]}) using Mcp-Name header ->
-     integration/tool lookup; tools/list is filtered to the caller's grants
+     integration/tool lookup; tools/list is filtered to the caller's grants;
+     a tool then re-checks with the resource it resolved ({context: {projectId}})
+     against the integration's RBAC scope
   3. Write tools: elicitation confirmation (unless override + infra:writeUnconfirmed)
   4. Dispatch: IntegrationAdapter (native handler | proxied MCP client)
   5. Audit: InfraAuditLog record for every tools/call
@@ -101,6 +105,19 @@ export const infraStatements = {
 - `read`/`write` are in the RBAC module's `READ_ACTIONS` semantics, so the shipped `auditor` role (read-only everywhere) works unmodified — that is the "log digging" role for free.
 - Default roles seeded on top of the RBAC defaults: `infra-readonly` (every integration `read`), `infra-operator` (`read` + `write`, still confirmed per call), `superadmin` from RBAC covers everything including `infra:writeUnconfirmed`.
 - Per-integration grants ("Sentry read only, no GCP") are just roles with narrower permission sets — no extra machinery.
+- Per-resource grants ("this agent's Vercel projects only") are RBAC `scopes`, passed to `createAccess`:
+
+  ```typescript
+  scopes: {
+    "vercel.read": {
+      check: async ({user, context}) =>
+        context?.projectId === undefined || isOperator(user) ||
+        (await projectsFor(user)).includes(context.projectId as string),
+    },
+  },
+  ```
+
+  `projectsFor` reads the machine user's allow-list (in our deployment, the project ids in the agent repo's environment). With no `projectId` in the context the call is a tier check only.
 
 ### Write confirmation flow
 
@@ -120,6 +137,8 @@ export default defineInfraMcp({
     gcp: {enabled: true, projectId: env("GCP_PROJECT")},           // ADC — no key
     sentry: {enabled: true, authToken: secret("SENTRY_MCP_TOKEN"), org: "flourish"},
     mongo: {enabled: true, readUri: secret("MONGO_READ_URI"), writeUri: secret("MONGO_WRITE_URI")},
+    // Phase 3. One team token per team, keyed by slug; projects map to teams by lookup.
+    vercel: {enabled: true, teams: {nangio: secret("VERCEL_TEAM_NANGIO"), terrenolabs: secret("VERCEL_TEAM_TERRENOLABS")}},
   },
   confirmWrites: true, // global default; per-integration override allowed
 });
@@ -216,7 +235,12 @@ No new frontend package. Admin surfaces reuse `@terreno/admin-backend` + `@terre
 
 - `ProxiedAdapter` (MCP client, stdio + HTTP transports, allow-list with mandatory tier annotations, name prefixing).
 - First proxied integration: `@sentry/mcp-server` (stdio, static token) or `observability-mcp` — pick one as the reference implementation and keep the native tools as fallback.
-- Native Expo/EAS tools (`EXPO_TOKEN`: builds, updates, submissions status) and Vercel tools (API token: deployments, logs).
+- Native Expo/EAS tools (`EXPO_TOKEN`: builds, updates, submissions status).
+- Native Vercel tools (team tokens, see Decisions): `vercel_list_projects`, `vercel_list_deployments`, `vercel_runtime_logs`.
+  - Runtime logs use `POST /v1/observability/events?teamId=<team>` with `event: "vercel.log"`, `scope: {ownerId, projectIds: [<project>]}`, a `timeRange`, `order: "desc"`, `limit` and an optional `cursor` (from `pagination.nextCursor`). This is the query `vercel logs` makes as of CLI 65.
+  - Optional filters (deployment, level, a free-form Vercel filter on `level`/`source`/`requestPath`/…) are ANDed into `filter`. The project goes in `scope`, never in the filter, so a filter can't widen the query (measured: a filter naming another project returns nothing).
+  - The older `GET /v1/projects/<p>/deployments/<d>/runtime-logs` stream isn't usable: it sent no headers within 60 s even with an account token.
+- Dogfooded first in our agent-session manager (hive) on `@terreno/api`'s MCP server, using the adapter interface above, with per-sandbox machine users and the `vercel.read` scope. It moves into this package when the package exists.
 - **Deliverable:** adding a vendor MCP is config + annotations, not code.
 
 ### Phase 4 — OSS packaging

package/src/docs/versioned/next/reference/test.md

@@ -8,7 +8,8 @@ Shared Bun test helpers for Terreno backend packages: in-memory MongoDB lifecycl
 bun add -d @terreno/test mongoose
 ```
 
-`mongoose` is a peer dependency (>= 8.0.0).
+`mongoose` is a peer dependency (>= 8.0.0). The Expo/React Native setup under
+`@terreno/test/expo/*` adds optional peers; see [Expo / React Native](#expo--react-native).
 
 ## Commands
 
@@ -105,6 +106,181 @@ If `registerBackendPreload` cannot start Mongo, every later test fails at once w
 | `ensureTestMongooseConnected` | Connect mongoose to test URI with retries. |
 | `waitForDocument` / `waitForDocuments` | Poll until documents match a query. |
 | `startTestTransaction` / `abortTestTransaction` | Per-test mongoose transactions when enabled. |
+| `TestTransactionOperationCancelledError` / `isTestTransactionOperationCancelled` | Error a queued DB operation rejects with when a test ends before it runs; the check follows `cause` chains. |
+| `waitUntil` / `waitForCalls` | Poll a predicate or a mock's call count instead of sleeping. |
+| `freezeTime` | Freeze `Date.now()`, `new Date()`, and Luxon at one instant for the current test. |
+| `authWithToken` | Supertest agent with a pre-minted bearer token (skips `POST /auth/login`). |
+| `expectAPIError` | Assert a response is the JSONAPI error body `APIError` produces. |
+| `assertStrictResponseProperties` | Fail when a response exposes a field outside an allowlist. |
+| `register*Mock` / `createMockLanguageModel` | Opt-in mocks for Cloud Tasks, SendGrid, Twilio, Expo push, GCS, Google auth, the AI SDK, and `@terreno/api` notifiers. |
+
+## Per-test transactions
+
+With `registerBackendPreload({useTransactions: true})`, each test runs inside a Mongo
+transaction that is aborted afterwards, and DB operations are serialized through one session.
+`abortTestTransaction({drainTimeoutMs = 3000})` first waits for in-flight operations, including
+fire-and-forget writes the test did not await, so they cannot run against the aborted
+transaction or commit for real. If they do not settle in time, the session is quarantined, the
+operations still queued reject with `TestTransactionOperationCancelledError`, and the test fails
+with `Timed out waiting for N serialized operation(s) to drain`.
+
+`bun test` reports an unawaited rejection itself and does not call
+`process.on("unhandledRejection")` listeners, so a fire-and-forget write that hits the
+cancellation fails the test. Await such writes in tests, or catch and check
+`isTestTransactionOperationCancelled(error)`.
+
+## Async and time helpers
+
+Poll the condition a test is waiting for instead of sleeping a fixed time:
+
+```typescript
+import {freezeTime, waitForCalls, waitUntil} from "@terreno/test";
+
+await waitUntil(() => socket.connected, {label: "socket connect", timeoutMs: 2000});
+await waitForCalls(sendMock, 2);
+```
+
+`waitUntil(predicate, {timeoutMs = 1000, intervalMs = 10, label})` throws
+`waitUntil timed out after <n>ms waiting for: <label>`. It measures elapsed time with
+`performance.now()`, so it keeps working while the clock is frozen. For rendered output in
+React Native tests, use `waitFor` from `@testing-library/react-native` instead.
+
+`freezeTime(isoOrDateTime, {restoreAfterEach = true})` freezes `Date.now()`, `new Date()`, and
+Luxon's `DateTime.now()` (Bun `setSystemTime` plus a `Date.now` override, so it still wins over
+a preload that replaced `Date.now`). Call it in `beforeEach` or inside a test; it restores the
+previous clock after that test. Nested freezes unwind to the outer instant. The returned
+function un-freezes early. Do not mix it with direct `setSystemTime` calls in the same test.
+
+## HTTP and assertion helpers
+
+`authAsUser` logs in through `POST /auth/login`, which pays the password-hash cost on every
+call. When the test is not about login, mint the token and use `authWithToken`:
+
+```typescript
+import {generateTokens} from "@terreno/api";
+import {authWithToken, expectAPIError, assertStrictResponseProperties} from "@terreno/test";
+
+const {token} = await generateTokens(user, authOptions);
+const agent = await authWithToken(app, {headers: {"app-version": "1.10.0"}, token});
+
+const res = await agent.post("/todos").send({});
+expectAPIError(res, {fields: {title: "Required"}, status: 400, title: "Validation failed"});
+
+const list = await agent.get("/users").expect(200);
+assertStrictResponseProperties(list.body, ["data._id", "data.name", "limit", "more", "page", "total"]);
+```
+
+- `expectAPIError(res, {status, title?, detail?, code?, fields?})` checks the HTTP status and
+  `body.status`, plus only the keys you pass. `title` and `detail` accept a string or `RegExp`;
+  `fields` is a partial match on `body.meta.fields`.
+- `assertStrictResponseProperties(body, allowedPaths)` lists every dot path in the body (array
+  items add no segment, so `data.email` covers each list item) and throws naming every path that
+  is not listed, an ancestor of a listed path, or under one. Use it on permission-scoped
+  endpoints so a new model field or populate cannot leak PHI or secrets unnoticed.
+
+## Service mocks
+
+Each registrar calls `mock.module` for one SDK, returns the mock functions, and has `reset()`
+to clear calls and restore defaults. The SDK does not need to be installed. Call the registrar
+in the package preload (or at the top of a test file before importing code that loads the SDK);
+`mock.module` lasts for the whole process.
+
+| Registrar | Module | Highlights |
+|-----------|--------|------------|
+| `registerCloudTasksMock()` | `@google-cloud/tasks` | `getEnqueuedTasks()` decodes base64 bodies; `drainTasks({app, path?, headers?, filter?, expectStatus?, maxRounds?})` POSTs each task to the app with supertest. |
+| `registerSendGridMock()` | `@sendgrid/mail` | `send`, `setApiKey`, `getSentMessages()`. |
+| `registerTwilioMock()` | `twilio` | `messagesCreate`, Verify `verificationsCreate` / `verificationChecksCreate` (approves any code). |
+| `registerExpoPushMock()` | `expo-server-sdk` | `sendPushNotificationsAsync`, receipts, `isExpoPushToken`, `getSentMessages()`. |
+| `registerGcsMock()` | `@google-cloud/storage` | In-memory buckets; missing files fail with `code: 404`; `putObject` / `getObject` / `listObjects` for setup and assertions. |
+| `registerGoogleAuthMock(options?)` | `google-auth-library` | `GoogleAuth` clients and `OAuth2Client.verifyIdToken`. |
+| `registerTerrenoNotifierMocks()` | `@terreno/api` | Replaces `sendToSlack`, `sendToZoom`, `sendToGoogleChat`; keeps every other export. Calls made inside `@terreno/api` itself still use the real notifiers. |
+| `createMockLanguageModel(options?)` | — | Scripted AI SDK language model (text, tool calls, errors, one response per call) for `AIService` and `generateText` / `streamText`. |
+
+```typescript
+import {registerCloudTasksMock} from "@terreno/test";
+
+const tasks = registerCloudTasksMock();
+
+it("runs the reminder task", async () => {
+  await agent.post("/reminders").send({}).expect(201);
+  await tasks.drainTasks({app, path: "/tasks/process"});
+});
+```
+
+## Expo / React Native
+
+`@terreno/test/expo/*` is a Bun test setup for Expo apps. It runs from TypeScript source, so it
+needs Bun. It needs the optional peers `react`, `react-native`,
+`@testing-library/react-native`, and `@terreno/ui` (plus `react-redux` when you pass a store);
+the backend entry point never loads them.
+
+```toml
+# bunfig.toml
+[test]
+preload = ["./tests/testPreload.ts"]
+```
+
+```typescript
+// tests/testPreload.ts
+import {registerExpoTestEnvironment} from "@terreno/test/expo/registerExpoTestEnvironment";
+
+registerExpoTestEnvironment({expoConfig: {extra: {}, scheme: "myapp"}});
+```
+
+`registerExpoTestEnvironment` mocks `react-native`, the common `expo-*` modules, `expo-router`,
+`@expo/vector-icons`, and common RN libraries (reanimated, gesture handler, SVG, AsyncStorage,
+NetInfo, SecureStore), serves image and font imports as asset stubs, and sets `__DEV__`, `TZ`,
+and `EXPO_OS`. After each test it restores spies, empties stored tokens, and resets `__DEV__`.
+Options: `skip`, `overrides`, `platform`, `timeZone`, `locale`, `expoConfig`, `scheme`,
+`fixedNow`, `cleanup`, `resolveFrom`, `nestedPackagePrefixes`. It returns
+`{mockedModules, restoreModuleMock(specifier)}`.
+
+| Subpath | Exports |
+|---------|---------|
+| `expo/registerExpoTestEnvironment` | `registerExpoTestEnvironment`, `createDefaultExpoModuleMocks`, `ASSET_FILE_PATTERN` |
+| `expo/renderWithTerreno` | `renderWithTerreno(ui, {store?, theme?, wrapper?, ...renderOptions})`, `createTerrenoWrapper` (for `renderHook`) |
+| `expo/authTokenStorage` | In-memory SecureStore / AsyncStorage: `setAuthTokens`, `clearAuthTokenStorage`, `TERRENO_AUTH_TOKEN_KEYS` (JWT `AUTH_TOKEN` / `REFRESH_TOKEN` and Better Auth keys) |
+| `expo/mockModuleAliases` | `createModuleAliasMocker({aliases, rootDir?})`: mock a module under every cache key Bun may use (alias and resolved path), starting from its real exports |
+| `expo/reactNativeMock`, `expo/expoModuleMocks`, `expo/libraryModuleMocks`, `expo/mockHelpers` | The individual mock factories, for apps that build their own set |
+
+`example-frontend/tests/testPreload.ts` is a working example.
+
+## CLIs
+
+Both CLIs need Bun.
+
+`terreno-test-shard` splits test files into balanced shards for parallel CI. Each file weighs
+`lines + 50 * testCount`; files are assigned heaviest first.
+
+```bash
+terreno-test-shard --shard 2/4 --list            # print this shard's files
+terreno-test-shard --shard 2/4 -- --timeout 30000 # run them; args after -- go to bun test
+```
+
+Flags: `--pattern`, `--exclude`, `--exclude-dir`, `--lines-per-test`, `--fail-fast`, `--cwd`,
+`--isolate <glob>` / `--isolate-file <list>` (run matching files in their own process), and
+`--process-per shard|dir|file` with `--dir-depth`. A run that matches no files exits 1.
+
+`terreno-test-hygiene` lints test files for patterns that make Bun suites flaky or leaky:
+
+| Rule | Flags |
+|------|-------|
+| `no-module-scope-mock-module` | `mock.module` at module scope (it leaks into every later file in the process). |
+| `no-direct-barrel-mock` | Mocking a barrel module directly (configure `--barrel-alias` / `--barrel-path`). |
+| `no-sleep` | Fixed sleeps (`setTimeout` promises, `Bun.sleep`, `--sleep-callee`); use `waitUntil`. |
+| `no-cache-busted-import` | `import("./x?t=...")` cache-busting. |
+| `no-late-real-capture` | Capturing a barrel's real exports inside a mock factory, after mocks may already be registered; capture them at module scope first. |
+| `no-component-snapshot` | `expect(Component).toMatchSnapshot()` on an imported reference instead of rendered output. |
+
+```bash
+terreno-test-hygiene --root src --baseline test-hygiene-baseline.json
+terreno-test-hygiene --update-baseline   # record current counts
+```
+
+Settings come from `--config` or `./test-hygiene.config.json` plus flags. A baseline holds
+per-file, per-rule counts so CI fails only on new violations. Suppress one line with a
+`test-hygiene-disable-next-line <rule>[, <rule>]` comment. Exit codes: 0 clean, 1 new
+violations, 2 usage error.
 
 ## Conventions
 

package/src/docs/versioned/next/reference/ui.md

@@ -9,6 +9,7 @@ React Native UI component library (a large component library). Layout (Box, Page
 - Display: `Text`, `Heading`, `Badge`, `DataTable`, `Scorecard`, `SparklineChart`, `LineChart`, `BarChart`, `AreaChart`, `DonutChart`
 - Actions: `Button`, `IconButton`, `Link`
 - Feedback: `Spinner`, `Modal`, `Toast`
+- Loading: `Skeleton`, `SkeletonText`, `SkeletonCircle`, `SkeletonCard`, `SkeletonList`, `SkeletonGroup`, `withLoading`, `LoadingProps`
 - Notifications: `NotificationBell`, `NotificationInbox`, `NotificationPreferences`
 - AI chat: `GPTChat`, `AskCard` (agent asks in the transcript), `SimpleAskCard` (an ask's simple card for narrow layouts), `BlocksView` (a whole-reply YAML document)
 - Authentication: `SocialLoginButton`, `LoginScreen`, `SignUpScreen`
@@ -280,6 +281,80 @@ and do not expose dismiss or read-state actions.
 | `preferences` | `{inapp, mail, push, sms}` | Current toggles |
 | `onChange` | `(channel, value) => void` | Per-channel updates |
 
+## Loading states and skeletons
+
+Containers share one loading contract, `LoadingProps`:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `loading` | `boolean` | `false` | Renders `loadingComponent` in place of the children |
+| `loadingComponent` | `ReactNode` | per component, below | The placeholder, usually built from skeletons |
+| `loadingAnimation` | `"pulse" \| "shimmer" \| "none"` | `"pulse"` | Animation for skeletons inside `loadingComponent` that do not set their own |
+| `loadingLabel` | `string` | `"Loading"` | What screen readers announce while loading |
+
+| Component | While `loading`, renders | Default `loadingComponent` |
+| --- | --- | --- |
+| `Box` | `loadingComponent` instead of children | `<SkeletonText />` (three lines) |
+| `Card` (container), `EditableCard` | `loadingComponent` instead of children | `<SkeletonText />` |
+| `Card` (display) | `loadingComponent` instead of image, title, and body | `<SkeletonCard>` with media when `imageUri` is set |
+| `ChartCard` | Title row, then `loadingComponent` instead of the body | 160px `Skeleton` |
+| `Scorecard` | Title row, then `loadingComponent` instead of the value | Value-sized `Skeleton`, plus a sparkline `Skeleton` when `sparklineData` is set |
+| `LineChart`, `BarChart`, `AreaChart`, `DonutChart` | `loadingComponent` instead of the plot | `Spinner` |
+| `Page` | `loadingComponent` instead of children | `Spinner` and `loadingText` |
+| `SplitPage` | `loadingComponent` instead of the list and detail | `Spinner` beside the content |
+
+`Page`, `SplitPage`, and the charts keep their spinner unless you pass `loadingComponent`. The
+spinner is busy and labeled the same way. `SplitPage` takes no `testID`, so its loading region is
+always `split-page-loading`.
+
+While loading, the container sets `accessibilityState.busy` (`aria-busy` on web) and the
+`loadingLabel` as its accessibility label. Skeleton blocks are hidden from screen readers. A
+clickable `Box` ignores presses while loading.
+
+```tsx
+import {Box, SkeletonList} from "@terreno/ui";
+
+<Box loading={isLoading} loadingAnimation="shimmer" loadingComponent={<SkeletonList rows={3} />}>
+  {rows}
+</Box>
+```
+
+### Skeleton primitives
+
+| Component | Props (defaults) | Shape |
+| --- | --- | --- |
+| `Skeleton` | `width` (`"100%"`), `height` (16), `rounding` (`"sm"`, or `"circle"`), `color` (`"neutralExtraLight"`) | One block |
+| `SkeletonText` | `lines` (3), `size` (`"md"`), `lastLineWidth` (`"60%"`) | Lines sized to `Text` at `size` |
+| `SkeletonCircle` | `size` (40) | Avatar or icon |
+| `SkeletonCard` | `showAvatar` (true), `showMedia` (false), `mediaHeight` (160), `lines` (2) | Media, avatar, title, and text |
+| `SkeletonList` | `rows` (3), `showAvatar` (true), `lines` (2) | Repeated list rows |
+
+Every primitive takes `animation` and `testID`. Child test ids are dot-suffixed, such as
+`{testID}.line.0`, `{testID}.row.1.avatar`, and `{testID}.shimmer`. Skeletons are hidden from
+assistive tech, so React Native Testing Library queries need `{includeHiddenElements: true}`.
+
+`SkeletonGroup` sets `animation` for every skeleton inside it and runs them from one timeline, so
+they pulse together. Loading containers wrap `loadingComponent` in one. A skeleton's own
+`animation` overrides the group. Animations stop while the OS reduce-motion setting is on. On
+native, skeletons hold still until that setting has been read, so they never animate first.
+
+### Custom components
+
+`withLoading(Component, {loadingComponent?, loadingAnimation?})` returns a component that takes
+`LoadingProps`. While `loading`, it renders `loadingComponent` in a busy `Box` with test id
+`{testID}-loading`; otherwise it renders `Component`. The wrapper consumes `loading`, so use it
+only for components without a `loading` prop of their own.
+
+```tsx
+const UserRowWithLoading = withLoading(UserRow, {loadingComponent: <SkeletonList rows={1} />});
+
+<UserRowWithLoading loading={isLoading} user={user} />
+```
+
+To give your own container the same contract, extend `LoadingProps` and pass the props to a
+`Box`, or call `resolveLoadingContent({children, loading, loadingAnimation, loadingComponent,
+defaultLoadingComponent})` where the placeholder goes.
+
 ## WhatsNewBanner
 
 Non-blocking release notes banner. It shows `What's new in <version>` (plus a count of earlier

package/src/docs/versioned/next/tasks/infra-mcp.md

@@ -34,7 +34,8 @@ Status: Blocked — Phase 1 RBAC wiring depends on the RBAC module PR ([rbac-per
 - [ ] `ProxiedAdapter`: `@modelcontextprotocol/client` (stdio + HTTP), deny-by-default `allowedTools` with mandatory tier annotations, tool name prefixing, upstream lifecycle management
 - [ ] Reference proxied integration (`@sentry/mcp-server` stdio or `@google-cloud/observability-mcp`) with parity tests against native tools
 - [ ] Expo/EAS native adapter (`EXPO_TOKEN`): build status, update status, submission status (read); trigger tools deferred to write expansion
-- [ ] Vercel native adapter (API token): deployments, logs, project info (read)
+- [ ] Vercel native adapter (one team token per team, project→team by lookup): `vercel_list_projects`, `vercel_list_deployments`, `vercel_runtime_logs` via `POST /v1/observability/events` (read); `vercel.read` RBAC scope limiting machine users to their own projects. Port from the hive dogfood implementation
+- [ ] Per-sandbox machine users for orchestrated agents: mint user + service token at sandbox create, revoke at teardown; per-resource allow-list consumed by integration scopes
 
 ## Phase 4 — OSS packaging