@zackbart/connecta 0.32.0 → 0.34.0

package/documentation/architecture.md

@@ -1,5 +1,11 @@
 # Architecture
 
+## Contributor reference
+
+This guide describes Connecta implementation and repository verification.
+It is optional for deployment operators. Start with the
+[operator task index](./README.md#operator-tasks) for package-local procedures.
+
 One Web-standard `fetch(request) => Promise<Response>` handler, a long-lived
 registry behind it, and a strict rule about what may be imported. Everything
 else in this repository is a detail of those three things.
@@ -85,20 +91,21 @@ table, security headers. Route _order_ is the contract — several routes would
 behave differently if they were reachable in another order — so read the table
 top to bottom.
 
-| Order | Route                                                     | Notes                                                                                                                                                                                                                                                                                |
-| ----- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 0     | MCP Origin check                                          | A disallowed `Origin` on `/mcp*` is a fixed 403 before redirects, admission, auth, or preflight — costing no permit and no auth lookup. Originless requests are admitted.                                                                                                            |
-| 0     | HTTPS upgrade                                             | 308 to an HTTPS `publicUrl`, with path and query _assigned_ onto it rather than resolved against it, so a `//host` pathname cannot replace the origin. `/health` is exempt: a loopback probe must not need public DNS.                                                               |
-| 0     | Cloudflare Access (Worker, when enabled)                  | Edge admission ahead of this table; an admitted invocation carries trusted identity in `ctx.access`.                                                                                                                                                                                 |
-| 1     | `/oauth/client-metadata/<connectorId>`                    | Public GET-only CIMD for configured self-hosted OAuth connectors; fixed `publicUrl`, no auth or storage.                                                                                                                                                                             |
-| 1     | Mounted UI routes                                         | Before wildcard OPTIONS, so mutation routes refuse preflight rather than inheriting MCP CORS. No UI module, no routes.                                                                                                                                                               |
-| 1     | `/connect/<connectorId>`, `/oauth/callback/<connectorId>` | GET-only browser OAuth routes, before wildcard OPTIONS. Both verify the initiating user and management permission, independent of the UI.                                                                                                                                            |
-| 2     | MCP preflight                                             | Allowed `OPTIONS` on `/mcp*`: 204 without admission or auth.                                                                                                                                                                                                                         |
-| 2     | Other `OPTIONS`                                           | Auth metadata first, otherwise compatibility CORS preflight.                                                                                                                                                                                                                         |
-| 3     | `/.well-known/*`                                          | Public auth metadata, or 404. Protected-resource discovery does not authenticate callers or evaluate endpoint grants.                                                                                                                                                                |
-| 4     | `/health`                                                 | Open and payload-free: health, executor, admission, and deployment metadata.                                                                                                                                                                                                         |
-| 6     | `/mcp`, `/mcp/<pool>`                                     | Admission, then auth, then a request-local MCP server. Body-confirmed modern listens skip admission and are refused after auth and SDK validation. An undeclared pool, a refusing endpoint grant, and a throwing endpoint grant are one identical 404; see [pools](./auth.md#pools). |
-| 7     | Other paths                                               | 404. Custom HTTP routes belong to the deployment.                                                                                                                                                                                                                                    |
+| Order | Route                                                     | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ----- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 0     | MCP Origin check                                          | A disallowed `Origin` on `/mcp*` is a fixed 403 before redirects, admission, auth, or preflight — costing no permit and no auth lookup. Originless requests are admitted.                                                                                                                                                                                                                                                            |
+| 0     | HTTPS upgrade                                             | 308 to an HTTPS `publicUrl`, with path and query _assigned_ onto it rather than resolved against it, so a `//host` pathname cannot replace the origin. `/health` is exempt: a loopback probe must not need public DNS.                                                                                                                                                                                                               |
+| 0     | Cloudflare Access (Worker, when enabled)                  | Edge admission ahead of this table; an admitted invocation carries trusted identity in `ctx.access`.                                                                                                                                                                                                                                                                                                                                 |
+| 1     | Agent namespace, any path starting `/agent` once decoded  | First, so no path Access bypasses reaches a human route. Exactly `/agent/<pool>`: admission, then the `cta_` adapter alone, then pool membership; every other spelling is the pool 404 before admission or auth. See [agent endpoints](./auth.md#agent-endpoints).                                                                                                                                                                   |
+| 1     | `/oauth/client-metadata/<connectorId>`                    | Public GET-only CIMD for configured self-hosted OAuth connectors; fixed `publicUrl`, no auth or storage.                                                                                                                                                                                                                                                                                                                             |
+| 1     | Mounted UI routes                                         | Before wildcard OPTIONS, so mutation routes refuse preflight rather than inheriting MCP CORS. No UI module, no routes.                                                                                                                                                                                                                                                                                                               |
+| 1     | `/connect/<connectorId>`, `/oauth/callback/<connectorId>` | GET-only browser OAuth routes, before wildcard OPTIONS. Both verify the initiating user and management permission, independent of the UI.                                                                                                                                                                                                                                                                                            |
+| 2     | MCP preflight                                             | Allowed `OPTIONS` on `/mcp*`: 204 without admission or auth.                                                                                                                                                                                                                                                                                                                                                                         |
+| 2     | Other `OPTIONS`                                           | Auth metadata first, otherwise compatibility CORS preflight.                                                                                                                                                                                                                                                                                                                                                                         |
+| 3     | `/.well-known/*`                                          | Public auth metadata, or 404. Protected-resource discovery does not authenticate callers or evaluate endpoint grants.                                                                                                                                                                                                                                                                                                                |
+| 4     | `/health`                                                 | Open and payload-free: health, executor, admission, and deployment metadata.                                                                                                                                                                                                                                                                                                                                                         |
+| 6     | `/mcp`, `/mcp/<pool>`                                     | Admission, then auth, then a request-local MCP server. No body is read before auth and endpoint admission. A request naming `subscriptions/listen` takes its permit only after a bounded classification read (413 past 64 KiB); a body-confirmed modern listen takes none and is refused after SDK validation. A non-maintainer at `/mcp`, a non-member, and an undeclared pool get one identical 404; see [pools](./auth.md#pools). |
+| 7     | Other paths                                               | 404. Custom HTTP routes belong to the deployment.                                                                                                                                                                                                                                                                                                                                                                                    |
 
 Every response leaves through `withSecurityHeaders`. HTML uses one common
 security-header helper, including status and error pages. Operator shells
@@ -112,36 +119,46 @@ reordering reads like a harmless refactor.
 An admitted non-preflight `/mcp` request then takes five steps in
 `src/routes/mcp.ts`:
 
-1. **Admit.** Modern `subscriptions/listen` requests take no permit: their
-   mirrored method and parsed body must both name the unsupported method.
-   They still pass auth, pool grants, and SDK validation, then receive HTTP
-   404 with JSON-RPC `-32601`. Their body classification and auth share the
-   configured request lifetime, starting before classification. Other requests
-   take one permit from the deployment-wide pool, taken before auth so an
-   unauthenticated flood costs a permit rather than a Clerk lookup, and held
-   until the response _body_ completes, the caller leaves, or its configured
-   lifetime ends, not until the handler returns.
-2. **Authorize.** Machine tokens precede interactive providers. A provider's
+1. **Admit.** No request body is read before auth on any endpoint. A request
+   whose `Mcp-Method` header names `subscriptions/listen` takes no permit
+   before auth. After auth and endpoint admission connecta reads at most
+   64 KiB (`MAX_LISTEN_CLASSIFICATION_BYTES`) of it: past that it answers
+   413 `-33006` and stops reading. A body that confirms a modern listen stays
+   permit-free, passes SDK validation, and receives HTTP 404 with JSON-RPC
+   `-32601`; anything else takes a permit then, so the header alone bypasses
+   nothing. Auth and classification share the configured request lifetime.
+   Other requests take one permit from the deployment-wide pool, taken before
+   auth so an unauthenticated flood costs a permit rather than a Clerk lookup,
+   and held until the response _body_ completes, the caller leaves, or its
+   configured lifetime ends, not until the handler returns.
+2. **Authorize.** `/agent/<pool>` consults only the built-in `cta_` adapter
+   (`authorizeAgent`), never with the runtime context that carries
+   `ctx.access`. Human endpoints refuse a `cta_` token before recognition or
+   storage, and never ask the `cta_` adapter. A provider's
    synchronous credential recognition selects the sole verifier for an explicit
-   credential; a refusal never falls back to another identity. Human routes
-   reject machine credentials without verification. With no recognized
+   credential; a refusal never falls back to another identity. With no recognized
    credential, configured providers are tried in order. A 401 takes its
    challenge from the actual protected-resource metadata owner. No providers
    means open development and warns at construction.
-3. **Narrow to the pool.** On `/mcp/<pool>`, look the name up, run its grant
-   against the identity, then `intersectAccess` the pool with the identity's own
-   access. A pool can never widen a view; anything else is a 404 naming no pool.
+3. **Admit to the endpoint.** Plain `/mcp` admits a principal listed in
+   `maintainers` (or, with no inbound auth, the anonymous caller) and serves the
+   whole catalog. `/mcp/<pool>` admits the pool's human `members`, matched by
+   principal, and `/agent/<pool>` its agent members, matched by
+   `identity.agent`; both serve exactly the pool's tools
+   (`src/membership.ts`, `admitsMaintainer`, `memberPool`, and `agentPool` in
+   `src/routes/shared.ts`). Nothing intersects or widens either view; every
+   refusal is one 404 naming no pool.
    The endpoint's `readOnly` is the pool's own value, else the deployment's;
    plain `/mcp` uses the deployment's. It travels to the meta-tools and the
    program as one boolean that drops writes from `CatalogService` search and
    describe and makes `writeRefusal` (`src/tool-safety.ts`) refuse every write
    call. Guides and skills are not filtered.
 4. **Derive the registry view.** One `registry.scoped(...)` call with those
-   connector ids, exact `connector.tool` addresses when the identity declares a
+   connector ids, exact `connector.tool` addresses when the pool declares a
    narrower slice, and the subject and principal keys. Personal connectors use
    the principal partition and result paging the subject partition with principal,
-   endpoint/pool, origin, connector, and tool bindings. Paging rechecks current
-   grants, pool membership, and the endpoint's `readOnly`; no caller parameter selects a partition (`test/identity-scope.test.ts`).
+   endpoint/pool, origin, connector, and tool bindings. Paging re-admits the
+   caller at its endpoint and rechecks the endpoint's `readOnly`; no caller parameter selects a partition (`test/identity-scope.test.ts`).
 5. **Serve.** Refuse `?toolkit=` with a 404 — the toolkits are gone
    ([#178](https://github.com/zackbart/connecta/issues/178)) but their URLs were
    handed out, and retiring a scoping boundary into fail-open is worse than any
@@ -157,7 +174,7 @@ never select an identity, grant, connector view, or pool. Direct and program
 activity records retain only the self-declared `clientName` and `clientVersion`,
 validated by one ASCII grammar at the record builder, SQL write/read boundaries,
 and authenticated activity read route. Names match
-`[A-Za-z0-9][A-Za-z0-9 ._@/+-]{0,63}`; versions match
+`[A-Za-z0-9@][A-Za-z0-9 ._@/+-]{0,63}`; versions match
 `[A-Za-z0-9][A-Za-z0-9._+-]{0,31}`, each as a whole string. Names allow up to
 64 characters, versions up to 32. `__proto__`, `constructor`, and `prototype`
 are reserved. Invalid values are absent, never truncated or escaped. Capabilities and other client metadata never enter activity.
@@ -191,13 +208,14 @@ request-scoped sent-credential set and pass through `redactAgentOutput` before
 serialization. The SDK's `server/discover` response and registered meta-tool
 results use that same set; connector contexts retain only an opaque scope.
 
-| Refusal                             | HTTP status | Application code | Previous code |
-| ----------------------------------- | ----------- | ---------------- | ------------- |
-| Request capacity exhausted          | 503         | `-33001`         | `-31001`      |
-| Server shutting down                | 503         | `-33002`         | `-31002`      |
-| Request lifetime exceeded           | 504         | `-33003`         | none          |
-| Pool missing or refused             | 404         | `-33004`         | none          |
-| Origin or admitted access forbidden | 403         | `-33005`         | none          |
+| Refusal                              | HTTP status | Application code | Previous code |
+| ------------------------------------ | ----------- | ---------------- | ------------- |
+| Request capacity exhausted           | 503         | `-33001`         | `-31001`      |
+| Server shutting down                 | 503         | `-33002`         | `-31002`      |
+| Request lifetime exceeded            | 504         | `-33003`         | none          |
+| Pool missing or refused              | 404         | `-33004`         | none          |
+| Origin or admitted access forbidden  | 403         | `-33005`         | none          |
+| Listen classification body too large | 413         | `-33006`         | none          |
 
 These allocations are outside JSON-RPC's reserved `-32768..-32000` range and
 MCP's `-32020..-32099` range. The prior admission codes were also outside those
@@ -273,6 +291,40 @@ cannot be faked as sequential leases: consuming a rolling token before a later
 rule refuses would charge a call that never reached the provider, the exact
 accounting error a budget exists to prevent. Both layers are pinned by
 `test/request-admission.test.ts` and `test/call-admission.test.ts`.
+Every defined budget must be an object with `kind: "rolling-window"` and positive
+whole `maxCalls` and `windowMs` values. Malformed budgets, including `false`,
+`null`, `0`, and `""`, throw during construction, even when the rule also sets
+`maxConcurrency`.
+
+An admitted tool call can charge sequential auxiliary downstream requests with the internal
+`chargeConnectorCall(ctx)` hook in `src/call-admission-context.ts`. Invocation
+binds the context to its existing permit; the hook returns a Promise over an
+internal Effect program. The charge uses the enclosing call's partition
+and concurrency slot, so a connector with `maxConcurrency: 1` can perform a
+lookup without queuing behind itself. Exhaustion returns the same
+`CallAdmissionError` and retry delay as ordinary call admission, before the
+auxiliary request is sent. Charges against a configured policy also refuse
+after cancellation, permit release, or controller shutdown. The hook adds no
+public connector option or context member. Contexts outside registry invocation
+have no bound permit, so the hook does nothing there. Providers await the hook
+before sending and propagate its refusal; it does not acquire concurrency for
+parallel auxiliary requests.
+
+Cloudflare's REST connector charges each uncached zone-ownership lookup used
+to enforce an account pin, in addition to the enclosing tool-call attempt.
+Explicitly pinned zones and cached ownership need no extra request or charge.
+Its limits of three ownership lookups per call and 60 per five minutes per
+connector remain: they bound pin checks separately from the connector's larger
+shared call budget. The Cloudflare provider tests cover these checks through
+registry invocation as well as the existing pin refusals.
+
+Only an omitted or `undefined` `callAdmission` selects a connector's default.
+The shared schema rejects malformed defined policies at factory construction,
+and the registry validates custom connector policies before registration.
+Falsy values such as `false`, `null`, `0`, and `""` are construction errors
+(INV-11), never a way to disable admission. The generated provider fixtures
+exercise these refusals and unchanged defaults in
+`test/call-admission-options.test.ts`.
 
 ### Production Worker disconnects
 
@@ -335,6 +387,173 @@ and deletes the Worker in `finally`. It uses no `waitUntil`, which would change
 the lifetime being measured. The production runtime build number was not
 exposed by the deployment; these findings are tied to the date and flags above.
 
+### Production Access bypass for agent endpoints
+
+P0 of [#837](https://github.com/zackbart/connecta/issues/837) asked whether
+`/agent/*` can skip a Worker-level Cloudflare Access application, so an agent
+sends only its `cta_` token, while every other path keeps Access and
+`ctx.access`. It can. The probe ran on 2026-10-15 against a disposable Worker on
+its `workers.dev` hostname, with compatibility date `2026-09-01`, `cf`
+1.0.0-beta.14, Wrangler 4.114.0, and curl 8.7.1 with `--path-as-is`, so raw
+paths reached the edge unnormalized. The Worker-level application allowed only
+a probe service token. Its unauthenticated refusal was therefore Access's 403
+page rather than a login redirect. The [observations](https://github.com/zackbart/connecta/blob/main/scripts/probes/access-agent-bypass-2026-10-15.json)
+record three identical rounds after each configuration change had produced
+three consecutive matching responses.
+
+- **Precedence.** A self-hosted application whose destination is
+  `{ "type": "public", "uri": "<host>/agent/*" }`, with one `bypass` policy
+  including `everyone`, overrides the Worker-level application on matching
+  paths only. Unauthenticated requests reach the Worker there. `/mcp`, `/`,
+  and every unmatched path still get the Access refusal. A service token is
+  still admitted on them with `ctx.access` from the Worker-level application.
+  This confirms Cloudflare's documented hierarchy, and that Worker-level
+  protection still covers the `workers.dev` hostname.
+- **`ctx.access` on a bypassed request is present, not absent.** Its `aud` is
+  nonempty and is the _path_ application's AUD, not the Worker-level one.
+  `getIdentity()` resolved to `undefined` for every credential tested: none, a
+  valid service token, a `cta_`-style bearer token, and a forged
+  `Cf-Access-Jwt-Assertion`. A service token on a protected path also gave
+  `undefined` identity, carrying the Worker-level AUD. A human
+  `CF_Authorization` cookie on a bypassed path was not tested, so what
+  `getIdentity()` returns there is unknown. That is one more reason the agent
+  route ignores Access context rather than relying on its contents.
+- **API shape.** A Worker destination is exclusive to one application. A
+  second application with `{ "type": "worker", "worker_id" }` plus `uri` or
+  `path` was refused with 409 `destination belongs to another application`. The
+  bypass must be hostname-and-path, stored with domain `<host>/agent/*`, and it
+  covers only that exact hostname.
+- **Propagation.** Creating or deleting each application took 15–19 seconds to
+  settle across runs. While a deployment or application change was propagating,
+  the edge returned transient 500 (`error code: 1104`) and 404 (`error code:
+  1042` or `1043`) responses. The recorded run has one such 404, on the
+  Worker-level-only service-token control for `/agent/x`. Deleting the path
+  application restored the 403 on `/agent/x`.
+
+| Raw request path           | Access outcome | Worker pathname (+ search) |
+| -------------------------- | -------------- | -------------------------- |
+| `/agent/x`                 | bypassed       | `/agent/x`                 |
+| `/agent/assistant-alice`   | bypassed       | `/agent/assistant-alice`   |
+| `/agent/`                  | bypassed       | `/agent/`                  |
+| `/agent/x/`                | bypassed       | `/agent/x/`                |
+| `/agent/x?y`               | bypassed       | `/agent/x?y`               |
+| `/AGENT/x`                 | bypassed       | `/AGENT/x`                 |
+| `/%61gent/x`               | bypassed       | `/%61gent/x`               |
+| `//agent/x`                | bypassed       | `//agent/x`                |
+| `/agent/%2f/mcp`           | bypassed       | `/agent/%2f/mcp`           |
+| `/agent/x%2f..%2f..%2fmcp` | bypassed       | `/agent/x%2f..%2f..%2fmcp` |
+| `/mcp/../agent/x`          | bypassed       | `/agent/x`                 |
+| `/mcp`                     | protected      | not reached                |
+| `/`                        | protected      | not reached                |
+| `/agent`                   | protected      | not reached                |
+| `/agentx`                  | protected      | not reached                |
+| `/mcp/agent/x`             | protected      | not reached                |
+| `/agent/../mcp`            | protected      | not reached                |
+| `/agent/x/../../mcp`       | protected      | not reached                |
+| `/agent/%2e%2e/mcp`        | protected      | not reached                |
+| `/agent/%2E%2E/mcp`        | protected      | not reached                |
+| `/agent%2f..%2fmcp`        | protected      | not reached                |
+
+Access matches after resolving dot segments, including `%2e` forms. It matches
+case-insensitively, decodes unreserved escapes such as `%61`, collapses a
+leading `//`, and treats `%2f` as data, not a separator. The effective Worker
+pathname, `new URL(request.url).pathname`, is the raw request path with case,
+escapes, and slashes untouched, except that dot segments arrive resolved:
+`/mcp/../agent/x` arrives as `/agent/x`. Every path that
+resolves outside `/agent/*`, including every `/mcp` form, stayed protected. The
+inverse is the risk: Access bypasses paths
+that connecta must not treat as an agent pool. Connecta's router compares raw
+pathnames without decoding, case folding, or slash collapsing, so an `/agent/`
+route must keep that property. It should accept exactly
+`/agent/<pool>`, with `<pool>` byte-equal to a declared pool name. It should
+refuse an empty segment, a trailing slash, any extra segment, `%`, uppercase
+variants, and a leading `//`, all with the same 404. It must ignore
+`ctx.access` entirely, since a bypassed request still carries an AUD.
+[Agent endpoints](./auth.md#agent-endpoints) implement exactly this in
+`src/routes/agent-path.ts`, and `test/agent-endpoints.test.ts` replays every
+row of the table above. The hyphenated row stands for any two-part pool name
+such as `<agent>-<user>`. The pool names in the recorded paths were replaced
+with placeholders after the run; the edge behavior for that path shape was
+unaffected.
+
+To configure the bypass, keep the Worker-level application described in
+[Cloudflare Access on Workers](./auth.md#cloudflare-access-on-workers). Then,
+for each hostname agents use (the `workers.dev` hostname, each Custom Domain,
+or route host), add a self-hosted Access application. In the dashboard, set
+domain to that hostname and path to `agent/*`, with one policy whose action is
+**Bypass** and whose include rule is **Everyone**. Through the API, that is:
+
+```json
+{
+  "type": "self_hosted",
+  "name": "connecta agents",
+  "destinations": [{ "type": "public", "uri": "connecta.example.com/agent/*" }],
+  "policies": [{ "name": "agents bypass", "decision": "bypass", "include": [{ "everyone": {} }] }]
+}
+```
+
+Only the `workers.dev` hostname was probed. A Custom Domain application is the
+same documented hostname-and-path form, but it was not observed here. Do not
+rely on a fixed wait after a change. Changes settled in 15–19 seconds, yet one
+earlier round still saw a 403 on a bypassed path more than 30 seconds after
+the change. Test only after the positive and negative controls agree together
+for several consecutive rounds. The positive controls are bypassed paths
+reaching the Worker with the path AUD and a service token reaching a protected
+path with the Worker-level AUD; the negative controls are `/mcp` and `/`
+returning the Access refusal. The current script requires five such rounds
+after creating the bypass and three after other changes. The recorded run
+predates this: after the bypass it converged only the positive `/agent/x`
+control, then waited a fixed 90 seconds, and its negative controls were checked
+in the recorded rounds rather than before them.
+
+To repeat from a repository checkout, run
+`node scripts/probes/access-agent-bypass.mjs --profile <name> [output.json]`.
+`--profile` is required and has no default; every `cf` call passes it
+explicitly. Name the profile for the account that should host the probe; it
+needs
+Access application, policy, and service-token writes, plus Workers script
+writes. The script deploys and deletes the Worker with `cf`. `cf deploy` builds
+through Wrangler 4.136.0 or newer, so the probe installs Wrangler 4.145.0 into
+its temporary project. Wrangler needs no login. The script records only the
+count of existing Access applications, then names everything it creates
+`connecta-probe-<run>`. It force-deletes and verifies each resource in
+`finally`, then checks that the non-probe application ids are unchanged.
+Observations record statuses, outcome classes, pathnames, and which
+application's AUD matched, compared by digest inside the Worker. They contain no
+hostnames, account ids, tokens, cookies, or JWTs. `cf` delete commands prompt
+for confirmation and exit 0 without deleting when stdin is not a terminal, so
+the script passes `--force`. `cf deploy` printed `Deploy complete` and then
+kept running, so the script stops it after that line. The recorded run deployed
+with Wrangler 4.114.0 and used `cf` for Access. A standalone deploy and delete
+verified the `cf` deploy and delete path. The full probe has not been rerun on
+that path.
+
+Every subprocess (`cf`, `curl`, `npm`) runs through one runner. It enforces a
+deadline by killing the process group, keeps stdout and stderr in memory, and
+returns only facts: success, exit code, timeout, HTTP status, numeric API
+code, and an error slug from a fixed set (anything else is `unknown`). Commands
+that return data are parsed inside the runner against schemas that copy only
+whitelisted fields: ids, names, counts, booleans, and the Worker's `ctx.access`
+summary. Credentials stay in a holder that prints as `[secret]`. An unexpected
+shape, including `null` where a list belongs, is a failure, never an empty
+result. Errors are fixed diagnostics plus those facts. Teardown deletes every
+tracked id on its own. Then Access applications, service tokens, and Workers
+each get their own bounded discovery-and-delete pass by name, for resources
+whose create response was lost, so a failure in one family never skips
+another. Each discovered resource is deleted independently. Access policies are
+inline on their applications and go with them. A resource counts as gone only
+when a successful lookup omits it, and the final inventory verifies each family
+separately. Run
+`node scripts/probes/access-agent-bypass.mjs --self-test` to check the runner
+offline. It feeds canary secrets, suffixed slugs, malformed JSON, and a stalled
+process tree through it. It also runs teardown against a fake `cf` whose
+application listing always fails, after a lost token-create response, and
+checks that the token is still found and deleted. It also checks that a Worker
+that refuses deletion does not block another Worker's deletion. It runs no real
+`cf`, `curl`, or network command. This
+hardening and the joint convergence are verified offline only and have not run
+against Cloudflare.
+
 ## Storage, credentials, and connectors
 
 A deployment has one store. On Workers it is one D1 database
@@ -374,8 +593,8 @@ storage clock. Supply at most one option. Custom adapters must implement both;
 a delayed absolute-expiry write must not restart a relative TTL at commit time. Each SQL claim
 is one statement, which SQLite executes atomically and D1 serializes on its
 primary. Everything that must claim a key exactly once relies on it with no
-read-then-write fallback: access-token issuance and
-capacity, OAuth handoff ownership, single-use connect links, every downstream
+read-then-write fallback: agent-token slot swaps and
+adoption, OAuth handoff ownership, single-use connect links, every downstream
 OAuth grant write and consent claim, and the result stash.
 
 Every key is built in `src/storage/keys.ts`, which lists each family with its
@@ -544,9 +763,9 @@ configuration, never runtime registration. `authScope: "shared" | "personal"`
 partitions connecta-owned context — state, credentials, OAuth, catalogs, observed
 shapes — by principal, and _only_ connecta-owned context: a secret a custom
 handler closes over is shared JavaScript state, and `remoteMcp()` refuses the
-literal-headers-plus-personal version of that mistake. Visibility
-(`identity.connectorAccess`) is a separate rule; hiding a connector does not
-change who owns its auth.
+literal-headers-plus-personal version of that mistake. Visibility (maintainers
+and pool `tools`) is a separate rule; hiding a connector does not change who
+owns its auth.
 
 ### Errors and records
 
@@ -751,7 +970,7 @@ manual review evidence instead of claiming a machine-checkable JSON pin.
 
 The generic REST connector (`src/providers/_shared/rest/`) serves
 `<vendor>_api_search`, `_api_details`, `_api_read`, and `_api_write` over an
-`OperationIndex` that `npm run providers:spec` compiles offline from the
+`OperationIndex` that `pnpm run providers:spec` compiles offline from the
 provider's pinned `openapi.source.json` into `openapi.generated.ts`.
 Each call is matched to an operation and checked against its parameters before
 transport; `_api_read` admits GET and the vendor's reviewed read-only POSTs in
@@ -827,8 +1046,90 @@ every vendor ships one reviewed table through one mechanism
    labelled or typed secret records lose their value, environment containers
    lose their values, header, cookie, and query rules lose theirs, external
    destinations keep their origin, and every URL loses userinfo and
-   credential-named query parameters or fragments. Exemptions are never
-   shared; each vendor states its own.
+   credential-named query parameters or fragments under its URL policy.
+   Exemptions are never shared; each vendor states its own. Every REST vendor
+   reviews the pinned spec's free-text fields for embedded vendor-minted links
+   and records its verdict and source limitations beside its value-safety table.
+   Stripe, Vercel, and Cloudflare use **reviewed paths plus global signing
+   parameters**. Literal AWS SigV4/Google V4 `X-Amz-`/`X-Goog-` Signature,
+   Credential and Security-Token values are withheld across all decoded string
+   values. Generic credential names (`code`, `key`, `token`, `signature`, `sig`,
+   etc.) and credential-looking fragments apply only to reviewed diagnostic
+   paths and vendor error text. Matching destinations lose their entire query
+   and fragment. The tables list exact operations/resource paths with evidence:
+   Stripe charge failure/outcome messages, Vercel deployment failures and
+   build/runtime log text, Cloudflare Workers/Pages build logs and telemetry
+   message/error and raw string/object source payloads in both events and
+   invocation maps. The shared review harness rejects embedded-URL operation
+   keys absent from each vendor's pinned index and invalid path syntax.
+   Vercel's unavailable full pin remains a review limitation.
+   Generic parameters in descriptions, metadata, nicknames, billing footers,
+   notes, DNS TXT, KV values and operator HTML retain their original bytes,
+   including whole URL strings. Ordinary code/key URLs can be false positives
+   in reviewed diagnostics. Existing structured-field/resource rules, reviewed
+   `url:` per-parameter rules, and payer-facing exceptions still apply.
+   Scans read the original escaped text before URL parsing or serialization;
+   adjacent HTML or Markdown is text even without whitespace. Relative Markdown
+   destinations are checked at their own query/fragment, without re-anchoring
+   a nested proxy URL. Ordinary proxy parameters retain their bytes.
+   Scans precede success/select/named projections and error mapping. Named
+   Vercel streams use the same paths before clamping. Binary responses encoded
+   as base64, including Cloudflare Worker JavaScript served as
+   `application/javascript`, are returned unchanged, without decoding/scanning.
+   Cloudflare omits an envelope cursor that URL sanitizing would change;
+   ordinary cursors retain their bytes. No vendor-wide host/bucket policy is
+   inferred. Each string is scanned with bounded linear passes over disjoint
+   destinations, including large inputs.
+   These three vendors enforce write admission with the shared
+   `carriesWithheldLink(value)` scanner and `refuseWithheldLinks`/
+   `refuseWithheldUpload` helpers, plus `refuseWithheldBase64` for documented
+   base64 JSON fields. Every supported write transport (JSON,
+   form-encoded, raw/base64 bytes, multipart parts and named writes) refuses
+   with `invalid_args` and zero dispatch when a URL destination's own query
+   or fragment contains the exact `[redacted]` placeholder, plain or up to four
+   layers encoded. Upload admission reads decoded bytes and each multipart
+   string/blob. Vercel deployment `files[].data` with `encoding: "base64"`
+   and Cloudflare KV bulk `value` with `base64: true` pass through the same
+   byte inspection with one decode, bounded by the field's own encoded length
+   (decoded bytes are at most three quarters of encoded characters). Cloudflare
+   KV additionally enforces its documented 25 MiB decoded value limit;
+   malformed base64 and values beyond that limit refuse with `invalid_args`.
+   The host's inbound request cap still applies (Node `maxBodyBytes`, or the
+   Workers platform); response and raw-upload limits do not bound JSON fields.
+   JSON admission iteratively checks every key and value, with no separate
+   depth or node-count ceiling below the accepted request's size. Cyclic
+   direct arguments refuse with `invalid_args`; repeated non-cyclic references
+   are inspected. The scans remain linear in the supplied and decoded bytes.
+   Withheld values must not be written back; obtain the original
+   link or omit the field. A placeholder outside a destination is ordinary
+   text. Notion keeps its stricter reviewed-host admission and proxy policy.
+   Vendors whose responses embed the file links they mint can
+   use `withholdSignedLinks(text, hosts)` or
+   `withholdSignedLinksIn(value, hosts)` with a reviewed `FileHosts` policy
+   (`domains` and S3 `buckets`). Notion applies the latter in its `result`
+   hook and before mapping errors, so Markdown, async task results, paging,
+   named-tool results, and `select` all pass through it. The linear scan
+   matches only the current URL/destination's actual authority: a reviewed
+   domain or subdomain, or a reviewed S3 bucket, virtual-hosted or exactly
+   the first path segment on an S3 endpoint. A secondary scheme or `//` in
+   another URL's path or query cannot re-anchor it; those proxy links keep
+   their bytes. Schemes and slashes may be escaped. File links lose their
+   whole query and fragment from a literal, percent-, entity-, or
+   `\u`-encoded opener through the next whitespace, quote, or angle bracket;
+   trailing closing punctuation comes back. AWS SigV4 and Google V4
+   `Signature`, `Credential`, and `Security-Token` parameter values are
+   withheld wherever their literal signing names occur, at any host, with
+   plain or encoded equals signs. `carriesWithheldLink(value, hosts)` is
+   the shared write-admission helper: Notion refuses a write before dispatch
+   when a file link's own query/fragment carries the exact `[redacted]`
+   placeholder, plain or up to four layers encoded. Admission resumes at
+   each actual Markdown destination's close, including adjacent links and
+   images and balanced/escaped parentheses; leading spaces, tabs, and one
+   line ending before the destination are recognized. A marker after the close is
+   ordinary text. This boundary is independent of redaction's fail-closed
+   span. Each string is scanned alone; split rich-text runs, encoded hosts
+   or signing names, bare hosts without `//`, and userinfo before a reviewed
+   host are outside this scan's threat model.
 4. **Errors.** A reviewed operation, or an unreviewed one whose request
    accepts a credential-named field, answers failures with the vendor's codes
    and status but not its text, unless its verdict is wrapped in
@@ -908,7 +1209,7 @@ regardless of wrapping.
 
 `createConnecta` takes closed typed `ui`, `vault`, and `activity`
 slots, with factories at `/ui`, `/credentials`, and `/activity`
-and machine tokens at `/auth/access-tokens`. Root exports the contracts, never the implementations, and there
+and agent tokens at `/auth/access-tokens`. Root exports the contracts, never the implementations, and there
 is no module array, runtime registration, or plugin lifecycle. Core keeps
 discovery, the executor contract, invocation, permissions, and OAuth callback
 verification; an omitted module contributes no runtime work at all.
@@ -935,10 +1236,13 @@ connecta shows a person — the operator shell, the OAuth callback, a browser's
 404 — reads it. `src/operator-ui/tokens.css`
 resolves every color, radius, and font through a custom property and mixes the
 rest from those with `color-mix`; `page.css` holds the base typography and the
-primitives (shell, masthead, buttons, badges, messages, the one-message status
-page). The UI's `browser.css` imports both, and the build writes the same CSS,
-minified, into `src/page-styles.ts`, a module of two strings that core imports
+pieces server-rendered pages share (top bar, buttons, badges, messages, the
+one-message status page). The UI's `browser.css` imports both, then one file
+per area under `src/operator-ui/styles/` (fonts, shared components, shell, and
+each page). The build writes the shared CSS, minified, into
+`src/page-styles.ts`, with the hashed font paths, a module that core imports
 without the UI bundle, so an OAuth callback still renders with the UI omitted.
+Those pages link the fonts only when the UI module serves them.
 `renderPage` in `src/branding.ts` is the one layout: head, favicon (the default
 is linked only when the UI serves it), `data-scheme`, the tokens with the theme
 after them, and the masthead. So `branding.theme` only has to append a `:root`
@@ -952,13 +1256,18 @@ Maintained providers act as the caller downstream. `src/connector-caller.ts`
 attaches the admitted identity beside the request-scoped context, readable only
 by in-repo code and set from authorization, never arguments. Google Workspace
 domain-wide delegation
-(`src/providers/google/`, first consumed by `./providers/gmail`) hands the
+(`src/providers/_shared/google/`, first consumed by `./providers/gmail`) hands the
 admitted identity to a deployment-config `subject` function and mints a
 service-account token as whatever Workspace address it returns. The caller
 carries whether an inbound provider _authenticated_ it: an open deployment
 admits everyone as the anonymous actor, and the function is never asked about
-them. No caller, an unauthenticated one, or no address fails `auth_required`
-before any request leaves. The provider never chooses the account and a
+them. It also carries the admitted pool's `owner`, which core copies from
+config: an agent acts as it, before and instead of the function. In a pool
+without one, the scoped registry view omits a mapping-subject connector for an
+agent (`src/registry.ts`, keyed on the tag in `src/workspace-subject.ts`), as it
+omits a personal connector, and the provider still fails closed if reached. A fixed `subject` address is every
+caller's. No caller, an unauthenticated one, or no address fails
+`auth_required` before any request leaves. The provider never chooses the account and a
 deployment's own connector still cannot read the caller (PRINCIPLES.md, INV-3; `test/google-workspace-delegation.test.ts`). Its tokens live in a
 bounded module-level map, in memory only, keyed by the key's own digest as well
 as the account, subject, and scopes. A mint in flight is shared across requests
@@ -1017,7 +1326,7 @@ Effect callers skip the Promise and take the program: `admit` and
 and `acquireCallScoped` for call admission, `closeScope` and `closeScopeOnExit`
 for a connector scope, `withDeadlineEffect` where Promise code has
 `withDeadline`. The build prunes every declaration no `exports` target reaches,
-and `npm run check:declarations` fails if what remains names an Effect type.
+and `pnpm run check:declarations` fails if what remains names an Effect type.
 
 ### One runner
 
@@ -1152,7 +1461,7 @@ resolve a single copy. Adopting an unstable subpath is its own pull request.
 
 The stable `4.0.0` release was re-evaluated on 2026-10-01 with
 [`scripts/probes/effect-v4-evaluation.mjs`](https://github.com/zackbart/connecta/blob/main/scripts/probes/effect-v4-evaluation.mjs).
-Run `npm run build`, then `node scripts/probes/effect-v4-evaluation.mjs output.json`.
+Run `pnpm run build`, then `node scripts/probes/effect-v4-evaluation.mjs output.json`.
 The [raw observations](https://github.com/zackbart/connecta/blob/main/scripts/probes/effect-v4-evaluation-2026-10-01.json)
 are synthetic Node requests and neutral esbuild bundles, not live-client or
 workerd lifetime verification. Bundle figures add representative prototypes
@@ -1190,7 +1499,7 @@ replacement's benefit or compatibility.
 The core's cost is recorded rather than guessed. Against 0.24.4 the root entry
 grew from 235,346 to 279,526 bytes gzip, the Worker example from 263,949 to
 314,336, and each provider by about 36 KB, since each reaches Effect through
-`remoteMcp()`; `npm run check:bundle` caps every entry against
+`remoteMcp()`; `pnpm run check:bundle` caps every entry against
 `scripts/bundle-budget.json`. An install carries about 53 MB of `effect`, with
 no dependencies of its own.
 
@@ -1206,7 +1515,7 @@ src/
   catalog-drift.ts    reviewed classifications and the drift counts a refresh produces
   provider.ts         defineProvider(): the one maintained-provider shape
   activity.ts         optional history factory and best-effort recorder
-  auth/               bearer, Cloudflare Access, clerk (optional peer), downstream OAuth (remote and static)
+  auth/               Cloudflare Access, clerk (optional peer), downstream OAuth (remote and static)
   executors/          the QuickJS pool and child (Node only)
   node.ts             listen() (Node only)
   d1.ts, sqlite.ts    the two storage drivers; storage/ holds the SQL core and key families
@@ -1214,7 +1523,7 @@ src/
 
 There are exactly two deployment shapes — `templates/node/`, which
 `connecta init` copies with its container files, and `examples/worker/` — and
-`test/deployment-shapes.node.test.ts` with `npm run check:examples` keeps both
+`test/deployment-shapes.node.test.ts` with `pnpm run check:examples` keeps both
 compiling and configuring the real thing.
 
 ## Sharp edges
@@ -1232,7 +1541,8 @@ compiling and configuring the real thing.
   SIGTERM/SIGINT.
 - **Structural mistakes throw at construction.** A duplicate connector id, an
   invalid admission rule or limit, an unknown option at any depth, the old
-  boolean `accessTokens` option, a missing executor, or an executor without a
+  boolean `accessTokens` option, malformed or repeated `agents` or agents
+  without `accessTokens`, a missing executor, or an executor without a
   lifecycle brand:
   all refuse to boot (`test/config.test.ts`, `test/registry.test.ts`). Starting
   in the wrong shape is worse than not starting.