@zackbart/connecta 0.34.1 → 0.35.0

package/documentation/auth.md

@@ -6,16 +6,16 @@
 and package maintenance. This guide owns identity, membership, and downstream
 credential contracts; use [deployment setup](./deploying.md) for runnable steps.
 
-| Task                                                                | Sections                                                                                                                                                                      |
-| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Connect a machine or migrate an old client                          | [Agent tokens](#agent-tokens-and-upgrading-from-earlier-tokens), [agent endpoints](#agent-endpoints), [static bearer migration](#migrating-static-bearer-clients)             |
-| Configure caller visibility, read-only endpoints, or auth ownership | [Principals and operators](#principals-visibility-and-operators), [pools](#pools), [shared and personal auth](#shared-and-personal-auth)                                      |
-| Lay out an agent's pools                                            | [Organizing an agent's pools](#organizing-an-agents-pools)                                                                                                                    |
-| Set up human sign-in                                                | [Access on Workers](#cloudflare-access-on-workers), [Clerk tokens and sessions](#clerk-oauth-tokens-and-operator-sessions), [management](#human-authentication-management)    |
-| Enable credential or connection controls                            | [Management permissions](#management-permissions), [start/restart/disconnect](#starting-restarting-and-disconnecting)                                                         |
-| Diagnose consent or token refresh                                   | [State at rest](#downstream-oauth-state-at-rest), [callbacks](#consents-and-callbacks), [refresh failures](#refresh-failures), [safe errors](#what-a-servers-errors-may-say)  |
-| Configure a downstream OAuth client or HTTP handler                 | [Client registration](#downstream-oauth-client-registration), [api() OAuth](#downstream-oauth-on-api), [request-local bearer tokens](#request-local-downstream-bearer-tokens) |
-| Review browser or downstream URL boundaries                         | [Origins](#origins), [advertised URLs](#urls-a-downstream-advertises), [one server per grant](#one-server-per-grant)                                                          |
+| Task                                                                | Sections                                                                                                                                                                                                                                               |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Connect a machine or migrate an old client                          | [Agent tokens](#agent-tokens-and-upgrading-from-earlier-tokens), [agent endpoints](#agent-endpoints), [static bearer migration](#migrating-static-bearer-clients)                                                                                      |
+| Configure caller visibility, read-only endpoints, or auth ownership | [Principals and operators](#principals-visibility-and-operators), [pools](#pools), [shared and personal auth](#shared-and-personal-auth)                                                                                                               |
+| Lay out an agent's pools                                            | [Organizing an agent's pools](#organizing-an-agents-pools)                                                                                                                                                                                             |
+| Set up human sign-in                                                | [Access on Workers](#cloudflare-access-on-workers), [Clerk tokens and sessions](#clerk-oauth-tokens-and-operator-sessions), [Clerk Organizations](#one-clerk-instance-one-organization-per-deployment), [management](#human-authentication-management) |
+| Enable credential or connection controls                            | [Management permissions](#management-permissions), [start/restart/disconnect](#starting-restarting-and-disconnecting)                                                                                                                                  |
+| Diagnose consent or token refresh                                   | [State at rest](#downstream-oauth-state-at-rest), [callbacks](#consents-and-callbacks), [refresh failures](#refresh-failures), [safe errors](#what-a-servers-errors-may-say)                                                                           |
+| Configure a downstream OAuth client or HTTP handler                 | [Client registration](#downstream-oauth-client-registration), [api() OAuth](#downstream-oauth-on-api), [request-local bearer tokens](#request-local-downstream-bearer-tokens)                                                                          |
+| Review browser or downstream URL boundaries                         | [Origins](#origins), [advertised URLs](#urls-a-downstream-advertises), [one server per grant](#one-server-per-grant)                                                                                                                                   |
 
 [Credential recognition and admission](#credential-recognition-and-admission)
 defines refusal precedence.
@@ -30,7 +30,8 @@ Finish [Clerk setup](#clerk-oauth-tokens-and-operator-sessions) or
 provider yet. A machine-only deployment cannot admit people or manage shared
 auth through the operator UI.
 
-1. Admit the person in the identity provider's sign-in policy. Obtain their
+1. Admit the person in the identity provider's sign-in policy. With Clerk's
+   `organizationId`, add them to the deployment's Clerk Organization. Obtain their
    stable principal id there: Clerk's user id, or Access's `user_uuid` (email
    only when no `user_uuid` is supplied). A display name or an email for a
    Clerk user is not their principal id.
@@ -223,15 +224,262 @@ Clerk, a `cta_` token refused at `/mcp` or `/mcp/<pool>` still receives Clerk's
 resource metadata challenge.
 An open deployment with connectors warns at construction.
 
+### Authentication capacity and ingress limiting
+
+Connecta admits at most **16 active inbound adapter authorizations** per
+loaded core in a process or Worker isolate. Human MCP endpoints, agent endpoints,
+operator APIs, connection starts (`/connect/<connector>`), and OAuth callbacks
+share this fixed bound, including network calls made inside an adapter's SDK.
+It has no queue and no configuration option. When full, a request receives HTTP
+503 with `Retry-After: 1`, `Cache-Control: no-store`, and
+`error: { code: "authentication_busy", message: "Authentication capacity reached.", retryable: true }`.
+The operator log records only the checked `authentication_busy` reason, never
+credentials or identity-provider diagnostics. Retry after the indicated delay;
+Connecta does not automatically retry the authentication.
+
+Underlying work stays charged until it settles, including cancellation cleanup.
+A caller leaving alone never releases capacity. After an authorization's hard
+deadline plus **one second of settlement grace**, unfinished work moves from the
+active pool to a separate **abandoned allowance of 16 operations**. The native
+Access lookup and agent-token verification have five-second deadlines; Clerk's
+deadline is ten seconds, and custom adapters share that ten-second threshold.
+The allowance equals the active limit, so normal authentication continues
+while a partial wave of stalled operations is abandoned, and at most **32
+authorizations** are ever outstanding per loaded core. A full wave of 16
+stalled operations fills the allowance. While the allowance is full, no
+authorization starts, even when active slots are free. Overdue work that finds
+the allowance full keeps its active slot until an abandoned operation ends and
+makes room. A binding that never settles therefore fills the allowance and
+fails closed instead of accumulating I/O.
+
+Each charge ends exactly once, in one of two ways:
+
+- **Settlement.** The adapter's promise and every native operation it
+  registered have settled. This applies on every runtime and through every
+  entry.
+- **Unreachable work.** Nothing can ever settle the charge: the garbage
+  collector has freed every promise and callback that could have. On Workers
+  this follows invocation cancellation. Cloudflare ends a fetch invocation at
+  most 30 seconds after its response is sent or its client disconnects
+  ([`waitUntil` limit](https://developers.cloudflare.com/workers/runtime-apis/context/)),
+  and drops each I/O operation it still owns without running its callbacks.
+  Once the collector frees that work, Connecta releases the charge, and the
+  next admission logs the checked reason `authentication_unreachable`.
+
+Release through unreachable work is **eventual, never timed**. It waits for a
+garbage collection, which runs as the process or isolate allocates. On
+workerd, a collection triggered by allocation can keep a recently freed object
+for several later collections, so one charge may linger after the rest are
+released. While anything can still settle the work, the charge counts: a
+connected caller, middleware that reads Connecta's response and then awaits
+other work, and a scheduled handler that is still running all keep their
+charges. A late settlement after such a release changes nothing, so no count
+is released twice.
+
+Release through unreachable work needs `FinalizationRegistry`. Node always
+provides it. On Workers, set the `enable_weak_ref` compatibility flag, or use
+a compatibility date of 2025-05-05 or later, and keep `enable_request_signal`;
+the installed Worker example sets both flags. Without `FinalizationRegistry`,
+only settlement releases a charge. A native authentication operation that
+hangs past invocation cancellation then consumes one abandoned slot until the
+isolate is recycled, and 16 such operations in one isolate make every later
+authentication return `authentication_busy`, visible on `/health`.
+
+A request refused because the allowance is full receives the same 503
+`authentication_busy` response and headers. The operator log records the
+checked reason `authentication_abandoned_saturated` instead. `GET /health`
+reports `admission.authentication` with `active`, `limit`, `abandoned`,
+`abandonedLimit`, `abandonedSaturated`, and `unreachableRelease`, for example:
+
+```json
+{
+  "active": 0,
+  "limit": 16,
+  "abandoned": 16,
+  "abandonedLimit": 16,
+  "abandonedSaturated": true,
+  "unreachableRelease": true
+}
+```
+
+`unreachableRelease` is `true` when the runtime provides
+`FinalizationRegistry`. On Workers, `false` means neither `enable_weak_ref` nor
+a compatibility date of 2025-05-05 or later is in effect. A saturated allowance
+refuses all new authentication until an underlying operation settles or its
+unreachable work is collected. Investigate the identity binding or token
+storage; restarting the process or isolate clears its local accounting.
+
+Clerk creates a client per authorization: SDK verification (opaque
+access tokens, JWT/JWKS, browser handshakes and session refresh), domain checks,
+and gate-client lookups all use that request's signal and a ten-second
+authentication deadline. Its transport reads at most 1 MiB per SDK response,
+cancels the upstream body on every exit, and gives the SDK only buffered bytes.
+JWKS fetches make one attempt; cancellation starts no retry timer. Additional
+Backend API admission reads retain their 64 KiB response bound.
+
+On Workers, the event's `ctx` reaches Connecta through the `ctx` argument of
+`connecta.fetch`. Its `waitUntil` keeps only that request's
+already-running authorization and cleanup runnable after disconnect, so an
+aborted upstream settles before its slot is released. No other request shares
+its promise or I/O. Custom adapters must honor `request.signal` and return a promise that settles
+only after their work ends; ignoring cancellation consumes the bounded
+abandoned allowance, and work the promise does not await is not counted.
+The current adapters cannot cheaply establish a fully authenticated cache hit
+before verification, so every adapter invocation counts, including one that
+later uses a cached membership or policy verdict. Cache hits finish their slots
+quickly; a cached policy verdict never bypasses credential verification.
+Domain/gate and organization caches store only completed verdicts, never a
+lookup failure, cancellation, or timeout. A `gate` that returns `false` after
+its request was cancelled is not cached either. The JWKS cache stores only
+signing keys from a completed fetch.
+An adapter returning a synchronous local verdict releases before yielding;
+it consumes no pending slot between requests.
+
+This bound is independent of MCP request/program admission and downstream call
+limits. `Mcp-Method: subscriptions/listen` still defers its MCP request permit:
+after authentication and endpoint admission, a body-confirmed modern listen is
+refused promptly even when execution capacity is full. It always passes the
+authentication bound, and no request body is read before authentication.
+
+Routes that do not invoke an inbound verifier consume no authentication slot:
+health, public OAuth discovery and client metadata, UI shells and static assets,
+preflight, redirects, unknown paths, and local header/origin/path refusals.
+An invalid `/connect` handoff or unknown OAuth callback target also refuses
+before a verifier. Downstream OAuth exchanges and display-label reads are
+separate operations, with their existing limits; this bound covers the inbound
+authentication that admits their caller. Cloudflare Access edge authentication
+runs before the Worker; its in-Worker identity lookup is covered. Access uses
+only the trusted runtime binding, with no JWT/JWKS fetch. That native binding
+and token storage expose no cancellation API. Both answer promptly on caller
+cancellation or their five-second deadline and keep the unfinished operation
+in active or abandoned accounting until it settles. The five-second agent
+deadline covers hashing and every verification read together, and returns the
+machine `401` challenge; no further storage read starts after cancellation or
+timeout. A late native result never admits its original caller.
+
+This is a concurrency bound, **not a rate limit or a shared provider quota**.
+Require ingress rate limiting for public deployments across all authenticated
+paths, including `/agent/*`, `/ui/*`, `/connect/*`, and `/oauth/callback/*`.
+For example, a deployment at `https://assistant.example.com` using Clerk must
+budget all isolates and deployments sharing its Clerk secret key together.
+Fast invalid tokens and repeated cache misses can exhaust a provider's request
+budget without ever exceeding 16 active authentications. Set ingress limits
+to that provider's quota and expected traffic; increasing MCP concurrency does
+not increase authentication capacity.
+
 Clerk denial logs carry checked fixed reason codes. Provider user IDs, email
 addresses, and email domains stay out of denial logs, activity, and status,
 including email lookup failures and admission policy refusals.
 
+## Vercel workload credentials
+
+Available from 0.35.0; earlier releases do not support workload admission.
+
+An agent running on Vercel can present its project's signed OIDC token instead
+of provisioning a Connecta token. Declare the binding beside its name:
+
+```ts
+agents: [{
+  name: "assistant",
+  vercel: {
+    team: "team_example",       // immutable owner_id, required; team slugs are refused
+    project: "prj_example",     // immutable project_id (preferred), or exact project name
+    // environments: ["production"], // default; preview/development require explicit entries
+  },
+}],
+pools: {
+  assistant: { tools: ["crm", "tickets"], members: ["agent:assistant"] },
+},
+```
+
+Enable OIDC federation in the calling Vercel project's security settings.
+Use exact values from that project's settings; wildcards and empty environment
+lists are refused. The team must be its immutable `team_...` ID, matched against
+`owner_id`; a team slug is not accepted. Prefer an immutable `prj_...` project ID,
+matched against `project_id`. A project name instead matches `project` and follows
+that name, including reuse within the team. Project names may contain dots, such
+as `assistant.example.com`; colons are refused. A workload that could match two
+agents is refused at construction; use project IDs consistently across agents
+to avoid ambiguous bindings.
+
+The default admits production only. List `preview` or `development` explicitly
+when those environments should have the same pool access. Every deployment of
+the bound project in an allowed environment can act as the agent. This is
+project workload identity, with no end-user identity or forwarding. Enabling
+`development` lets project members who can obtain development tokens act as the
+agent. Enabling `preview` lets code on any pushed preview branch act as the agent.
+
+Treat the project's OIDC token as a bearer credential for all of this agent's
+pools. Its default audience, `https://vercel.com/<team-slug>`, is shared by every
+service accepting Vercel's default OIDC tokens; it is not specific to Connecta.
+Anything holding the project's token can act as the agent:
+project code, builds (including build steps and dependency install scripts with
+access to `VERCEL_OIDC_TOKEN`), and services the project sends the token to,
+including other agents and third-party APIs. A holder may be able to obtain
+fresh Vercel tokens through `@vercel/oidc`'s exchange, so access may outlast the
+original token's expiry. Binding a project means trusting everything that can
+obtain that project's tokens. Send them only to services trusted with the same
+agent access. Signature verification establishes the project identity; it does
+not isolate Connecta from these other token holders.
+
+Both team (`https://oidc.vercel.com/<team-slug>`) and global
+(`https://oidc.vercel.com`) issuer modes work. Connecta verifies RS256 signatures
+against Vercel's fixed public JWKS, exact issuer/audience/subject consistency,
+the configured team/project/environment, required expiration and issued-at,
+and not-before when present, with 30 seconds of clock skew. External-user
+tokens carrying `external_sub` are refused. Public keys cache for five minutes;
+an unknown key can trigger one additional refresh per 30 seconds. Failed fetches
+back off for 30 seconds and never admit with expired cached keys. Fetches have
+the same five-second authentication deadline as agent tokens. Neither token
+contents nor upstream errors enter activity; activity names the declared agent.
+If the two concurrent key-fetch slots are occupied on a cold or expired cache,
+the endpoint returns 503 with `Retry-After: 1`, rather than rejecting the credential
+with 401.
+
+Send the token as `Authorization: Bearer <OIDC token>` to
+`https://connecta.example.com/agent/assistant`. The inbound
+`x-vercel-oidc-token` header alone is not a Connecta credential. In Eve:
+
+```ts
+import { getVercelOidcToken } from "@vercel/oidc";
+import { defineMcpClientConnection } from "eve/connections";
+
+export default defineMcpClientConnection({
+  url: "https://connecta.example.com/agent/assistant",
+  description: "Use the assistant's shared CRM and ticket tools.",
+  auth: {
+    credentialOwner: "app",
+    getToken: async () => ({ token: await getVercelOidcToken() }),
+  },
+});
+```
+
+Resolve the token inside the request through `getToken`; never obtain it at
+module initialization or cache it. Vercel supplies request tokens through
+`x-vercel-oidc-token`; the helper can also read `VERCEL_OIDC_TOKEN` in builds
+or development. Eve's inbound `vercelOidc()` and `vercelSubject()` configure
+who may call Eve, separately from this outbound connection.
+
+OIDC-only agents need no `accessTokens` module. To accept either credential
+for the same agent, also configure `accessTokens(storage)`; its token slot,
+rotation and revocation keep their existing behavior. Revoking a `cta_` token
+does not revoke the workload binding: remove the binding or agent in code to
+stop OIDC admission. Both credentials reach exactly the pools listing the
+agent. Human endpoints refuse Vercel workload credentials without consulting
+human adapters. Removing the agent stops both credential paths.
+
+The [operator agent view](./operator-ui.md#operator-data-contract) lists each
+declared agent's supported credential kinds and latest sampled successful pool
+admission. Last seen is payload-free admission evidence sampled within a minute,
+independent of completed-call history; a refused credential or pool does not
+update it. Recording is best effort within 500 ms or the shorter configured probe
+deadline; failure loses a sample and a later eligible admission can try again.
+
 ## Agent tokens and upgrading from earlier tokens
 
-Machine clients are **agents**, declared by name in code. `agents: string[]`
-lists them: each name matches `^[a-z0-9_-]+$`, at most 64 characters, and is
-unique; anything else, or agents without `accessTokens`, throws at
+Machine clients are **agents**, declared by name in code. String entries in `agents`
+list them: each name matches `^[a-z0-9_-]+$`, at most 64 characters, and is
+unique; anything else, or token-only agents without `accessTokens`, throws at
 construction. `describeConfig()` lists the names and never token state.
 `accessTokens` from `@zackbart/connecta/auth/access-tokens` installs the `cta_`
 inbound adapter and, beside `ui`, the Tokens page and `/ui/access-tokens`
@@ -322,7 +570,7 @@ request without any storage write. An admitted agent's identity is:
 }
 ```
 
-`identity.agent` is set only by the built-in adapter; a result from any other
+`identity.agent` is set only by built-in agent credential adapters; a result from any other
 inbound provider that carries `agent` is refused like an unknown token. An
 agent has no principal, so personal connectors are absent for it and it never
 reads activity. Its subject partitions result handles per
@@ -491,7 +739,7 @@ A member reference is one of:
 - `"agent:<name>"`, naming an agent declared in `agents` (pool `members` only).
 
 A person matches when the admitted principal equals the reference exactly; an
-agent matches by `identity.agent`, which only the built-in token adapter sets.
+agent matches by `identity.agent`, which only built-in agent credential adapters set.
 Construction throws on a bare id without exactly one interactive
 provider, a bare id containing `:`, an undeclared agent, a repeated reference,
 an empty or missing pool `members`, an agent in `maintainers`, `maintainers`
@@ -607,8 +855,8 @@ and reports.
 ## Pools
 
 A pool is a named slice of the deployment served to its members: people at
-`/mcp/<pool>` and agents at `/agent/<pool>`. A support team sees three Notion
-tools and Linear, a calendar bot sees one tool, both over the same credentials. Private remote catalog
+`/mcp/<pool>` and agents at `/agent/<pool>`. A support team sees two notes
+tools and tickets, a calendar bot sees one tool, both over the same credentials. Private remote catalog
 cache entries remain partitioned by the admitted pool.
 
 ```ts
@@ -621,12 +869,12 @@ createConnecta({
   agents: ["calendar-bot"],
   pools: {
     support: {
-      tools: ["linear", "notion.search_pages", "notion.fetch_page"],
+      tools: ["tickets", "notes.search_pages", "notes.fetch_page"],
       members: supportTeam,
-      description: "Support tools: Linear and three Notion reads. Ask a maintainer for anything else.",
+      description: "Support tools: tickets and two notes reads. Ask a maintainer for anything else.",
     },
     calendar_bot: { tools: ["calendar.create_event"], members: ["agent:calendar-bot"] },
-    reporting: { tools: ["linear", "notion"], readOnly: true, members: analysts },
+    reporting: { tools: ["tickets", "notes"], readOnly: true, members: analysts },
   },
   connectors, executor,
 });
@@ -643,6 +891,7 @@ admitted.
 | Scope        | `/mcp/<pool>` and `/agent/<pool>` serve exactly the pool's `tools` (connector ids or exact `connector.tool` addresses), with the pool's `readOnly`, to its member people and member agents respectively. Plain `/mcp` serves the whole catalog to maintainers. Neither intersects with or widens anything.                                                                                                               |
 | Refusal      | A non-maintainer at `/mcp`, a non-member, and an undeclared pool get an identical 404 status, body, and headers, after auth. The operator log records `not_maintainer`, `not_pool_member`, or `pool_not_declared`. Names are not anonymously enumerable; valid credentials cannot distinguish these cases by content.                                                                                                    |
 | Agents       | An agent member reaches its pools only at `/agent/<pool>`, with its `cta_` token. Human endpoints refuse `cta_`; see [agent endpoints](#agent-endpoints).                                                                                                                                                                                                                                                                |
+| Surface      | From 0.35.0, optional `surface`: `"meta"` (default) serves the six meta-tools; `"native"` lists each of the pool's downstream tools directly, for clients with their own tool search, with optional `executeCode: false` to replace `execute_code` with `read_result` (invalid on meta pools). Calls take the same paths either way. See the [native tool surface](./meta-tools.md#native-tool-surface).                 |
 | Description  | Optional `description`: plain text telling the model what this endpoint is for. `/mcp/<pool>` and `/agent/<pool>` append it to the MCP `initialize` instructions after `This endpoint: `; plain `/mcp` and a pool without one serve the shared instructions unchanged. It grants, hides, and refuses nothing, and changes no tool or tool description.                                                                   |
 | Construction | Malformed names, unknown options or connectors, empty pools, empty or missing `members`, unresolvable member references, a non-boolean `readOnly`, an `owner` that is not a Workspace email address, a `description` that is not 1 to 500 characters of one-line text after trimming, a retired `trust` or `grant`, and addresses absent from an `api()` static catalog throw. Remote catalogs are checked at lazy load. |
 | Discovery    | Clerk's pool 401 names `/.well-known/oauth-protected-resource/mcp/<pool>` with the pool URL as `resource`, matching RFC 9728. Cloudflare Managed OAuth is application-level and needs no pool setup.                                                                                                                                                                                                                     |
@@ -667,11 +916,11 @@ at the edge so an agent sends one credential, and it behaves the same on Node.
   `/%61gent/x`, `//agent/x`, `/agent/%2f..`, `/agentx`) answers the pool 404
   before any admission or auth, so a path Access bypasses never reaches a
   human route. The query string is not part of the match.
-- **Auth.** Only the built-in `cta_` adapter is consulted. Clerk and Access
+- **Auth.** Only built-in `cta_` and configured Vercel workload adapters are consulted. Clerk and Access
   adapters never run; `ctx.access`, which Access attaches even to a bypassed
   path, is never read or passed on; cookies, Clerk handshake parameters,
   `Cf-Access-Jwt-Assertion`, and Access service headers are ignored. A
-  missing, malformed, unknown, revoked, or non-`cta_` credential gets 401 with
+  missing, malformed, unknown, revoked, or unaccepted credential gets 401 with
   `WWW-Authenticate: Bearer` and no `resource_metadata`.
 - **Membership.** An admitted agent must be listed in that pool's `members`.
   A non-member agent, a pool that lists no agents, and an undeclared but
@@ -995,7 +1244,7 @@ intake-redacted successes, keyed by connector configuration. Set
 `authScope: "personal"` when every human needs a separate downstream account:
 
 ```ts
-remoteMcp("linear", { url: "https://mcp.linear.app/mcp", authScope: "personal",
+remoteMcp("crm", { url: "https://crm.example.com/mcp", authScope: "personal",
   auth: { type: "oauth" } });
 ```
 
@@ -1211,6 +1460,38 @@ a dispatched record. The refresh HTTP request and response body have a
 backoff. A waiter deadline returns retryable `unavailable`, keeps the grant,
 and starts no consent. It never permits resending a spent token.
 
+A `remoteMcp()` write the downstream answered with HTTP 401 is never sent
+again (INV-9). The SDK still refreshes the grant, and connecta stops its
+resend before it leaves, so any fresh call after the target is reconciled uses
+the fresh token. The call
+fails with a non-retryable `connector_call_failed` whose outcome is unknown.
+If the refresh fails instead, whatever it met (a dead grant, a waiter
+deadline, the caller leaving), or hands back the token the API just
+rejected, the 401's verdict stays:
+`downstream_oauth_required`, never retryable, with `reconciliationRequired`
+and `writeOutcome: "unknown"`, and an `authorize_connector` handoff that says
+to re-read the target before any fresh call. A read is refreshed and sent
+once more. MCP sends a tool only once when either its effective classification
+or its original server hints say write. A deployment write-to-read override
+cannot make a server-declared write replayable. Its failure after possible
+dispatch is also an unknown outcome, non-retryable and without wait advice;
+a proven unsent failure retains its own recovery advice. A direct call outside an
+invocation uses the dispatched definition, a reviewed write verdict, or the
+tool's hints, and fails closed as a write.
+
+A remote MCP tool call that loses its internal dispatch record is refused
+before sending unless active calls for that tool prove it is a read. A
+write or an unproven call fails non-retryable with `writeOutcome: "unknown"`:
+tracking loss cannot establish whether an earlier message already sent it.
+
+Google Workspace also uses the invocation's served classification
+before considering the HTTP method. A write-classified GET is never replayed
+after a 401; a read-classified POST may replay once. Without a served verdict,
+this transport uses GET as read and other methods as write. Google drops the
+rejected token for the next deliberate call and retains `auth_required` with
+`writeOutcome: "unknown"` and the operator handoff. A renewed credential does not establish the write outcome. Recovery
+that hands back the same token renewed nothing.
+
 One preparation deadline covers initial epoch and grant reads, claim acquisition,
 dispatch preparation, and local joiners waiting for a grant commit. Cancellation
 before sending settles the local flight without awaiting cleanup storage. An
@@ -1287,7 +1568,29 @@ contain `key`, `token`, `secret`, `auth`, `signature`, or `session`. Custom
 `api()` handlers use `ctx.fetch` for this tracking; `ctx.oauth.fetch` and
 maintained-provider transports track the final request too. Credential-slot
 reads cover values sent in headers, queries, or bodies. Echoed sensitive
-header lines are also withheld.
+header lines are also withheld, read before any echoed value in them is
+replaced: a private value that changes part of a header's name or takes a
+credential prefix (such as `Authorization: Bearer`) still leaves the whole
+header value withheld, every cookie pair included. A line that is not a
+sensitive header keeps its text.
+
+Redaction removes every registered form whole and every run of eight
+consecutive code units (K) of a registered form of a value at least eight units
+long, wherever it starts, in the raw text and in each JSON-decoded layer. A cut,
+trim, or page can therefore leave at most seven units of a form outside the
+cases below. Text Connecta or a maintained provider shortens before returning
+it, such as a long error message, a capped field, or one page of a long text, is
+redacted whole before any trimming, whitespace normalization, number parsing,
+extraction, or cut, so derived titles, previews, summaries, sizes, and raw
+branches share the same protection. An extraction whose source changed under
+redaction returns `[redacted]`. Text read only up to a bound also loses a tail
+that begins a sent value the read stopped inside, at every JSON decoding layer.
+Complete matches and unfinished tails are found against the original text and
+replaced together; even a one-unit prefix is withheld. This can conservatively
+suppress a legitimate tail that shares a secret's prefix. Text paging that
+counts redacted units binds its cursor to that representation and refuses
+continuation if a changed request secret set changes it, even when the vendor
+revision is unchanged.
 
 Submitted values under JSON Schema `writeOnly: true` join this memory-only
 request set, including nested objects, arrays, and local references. Strings
@@ -1304,69 +1607,200 @@ submitted data and cached catalogs never depend on one request's arguments.
 
 Payload rules apply where downstream or guest data enters: downstream results
 and errors, resource reads, connector usage guides and downstream skill files,
-program returns, logs, and emits, and relayed input prompts. JSON objects,
-arrays, and string literals are parsed and walked, whether they are wire text
-or a string inside a result, so nested JSON strings are decoded too. Every
-decoded string leaf and property name is scanned, and a number, boolean, or
-null whose canonical text matches becomes the string `[redacted]`, so the JSON
-stays valid. Text is reserialized
-only when something changed; otherwise its original bytes remain. The
-serialized bytes are then scanned raw, and a literal the walk cannot see, such
-as one spanning tokens, withholds the whole text. Other text is scanned raw and
-through one more layer of JSON string escapes at a time while the last layer
-could still hold an escape. A string is decoded through at most eight layers in
-total, counting the nested JSON strings it was parsed from; text that would
-need more is withheld. Every match is mapped back to the original text,
-overlapping and adjacent spans merge, and each merged span is replaced once, so
-one match can never split another. A span wholly inside an existing
+program returns, logs, and emits, and relayed input prompts. Each redaction
+projects the whole value: string and number leaves in serialization order,
+JSON objects, arrays, and string literals parsed into their own leaves whether
+they are wire text or a string inside a result, and errors' own fields. The
+joined projection is matched once, so a value split across adjacent leaves,
+such as text blocks or array items, is found; each match is replaced only in
+the leaves it touches, and the containers around them keep their shape. A
+number that a match touches becomes the string `[redacted]`, so the JSON stays
+valid. Text is reserialized only when something changed; otherwise its original
+bytes remain. Serialized JSON whose keys, syntax, and leaves together hold a run
+that no single leaf holds, as a value spanning tokens does, is withheld whole.
+Matching runs on the raw text and through one more layer of JSON string escapes
+at a time while the last layer still decodes an escape, at most eight layers;
+text still holding escapes past that is withheld. Each decoded layer is scanned
+around the escapes it decoded, since every other match was found a layer up. Every match is mapped back to
+the original text, overlapping spans merge, and each merged span is replaced
+once, so one match can never split another. A span wholly inside an existing
 `[redacted]` placeholder is that placeholder; a private value that contains the
-placeholder text is still redacted. Connecta and MCP envelope field names, tag
-values such as a content `type` or result `format`, and typed facts such as
-`isError` and `retryable` are copied unchanged. The agent boundary around
-Connecta's own envelopes repeats credential and literal private-value
-replacement without the short-value rules, so envelope identifiers, counts, and
-JSON-RPC ids are never rewritten.
+placeholder text is still redacted.
+
+A maintained provider's parsed vendor JSON has every value redacted on arrival
+and keeps its object keys until the connector returns, so the provider's value
+safety finds each field by the name the vendor gave it. The connector boundary
+then applies payload rules to the whole result or failure, keys included.
+Response header names are kept; their values are redacted. When a redacted
+value is one value safety decides on, such as an object's type, a record's
+label, a link's parameter name or the response's Content-Type, value safety
+takes its most protective choice, so more of that response may be withheld.
+
+Every string that can reach an agent, an executor, a page or storage goes
+through one checker that applies all of the checks in this section: text and
+number leaves, object keys, declared binary fields, the bytes of typed binary,
+cursor claims, error fields, provider text lanes, bounded reads, and structural
+fields that are refused instead of rewritten. Object keys are checked on their
+own, and a key holding a match is renamed. Image, audio, resource-blob, or
+`format: "base64"` content, or a REST body's `base64` beside its `contentType`,
+is checked as text and also decoded whole and checked as bytes and as UTF-8,
+then withheld whole as the base64 of `[redacted]` on a match; content that is
+not valid base64 as it stands is still checked through every text view. Base64
+or base64url in any string is decoded and checked in each of the string's text
+views: the text itself, the text with one layer of JSON escapes decoded
+(`\uXXXX` and the standard escapes), the text with its percent escapes
+decoded, and its form decoding, which reads a `+` as a space and decodes any
+percent escapes, whether or not the text holds one. So `x+bm90ZXM=` is read
+both as one run and as `x` followed by `bm90ZXM=`, the base64 of `notes`.
+A view that is wholly base64 is decoded from six characters. A run inside a
+view is decoded from six characters when a private value of four to seven
+characters is registered, and from eleven otherwise: each length is the
+shortest run that can carry the smallest value the pass matches, four bytes or
+eight, at any alignment, padded or not. Decoded bytes are checked as bytes, as
+UTF-8, and through base64 they carry, up to three encodings deep, and the field
+is withheld whole as `[redacted]` when only its decoding holds a match. Every
+decode is paid for from the call's work budget; a field the budget cannot
+check is withheld.
+
+Only fixed words are copied unchanged whatever was sent: Connecta, MCP, and
+JSON-RPC envelope member names, tag values such as a content `type` or result
+`format`, booleans under outcome names (`isError`, `ok`, `retryable`,
+`truncated`, `hasMore`), and, on an error, its classification code and a fixed
+name: one a built-in error, `DOMException` (`DOMException`, `AbortError`,
+`TimeoutError`), Connecta's own classes, or the pinned MCP SDK's classes give
+their instances. Any other error `name`, own or inherited, a data field or an
+accessor's answer, including one a custom class gives itself, is a leaf of the
+projection like any other field: it is matched joined with the fields beside it
+and through any JSON it holds, and replaced whole by `[redacted]` when anything
+changes any part of it. The copy keeps its class, so classification and
+identity facts still see it. An error's fields are joined in its copy's order:
+its own fields, then what its class answers for `stack`, `message`, `cause`,
+`code` and `name`, then the other accessors its class defines. A number or a string under any name,
+such as `retryAfterMs` or a plain object's `code`, is matched like any other
+value; a matching typed number on an error is dropped. Relay states and connect
+links Connecta minted are kept whole. The agent boundary around Connecta's own
+envelopes repeats every check except short private values, so envelope
+identifiers, counts, and JSON-RPC ids are never rewritten.
+
+Every base64 or base64url encoding Connecta itself returns, such as a Drive or
+Gmail download, a REST body's `base64`, or a page cursor, is produced by one
+helper that checks the content first and encodes `[redacted]` instead when it
+holds a match. A cursor holds Connecta's own names, counts and fingerprints
+beside vendor values redacted when they were placed: a vendor page token or
+page id is redacted, so one that echoes a sent value fails on the next page
+instead of carrying it; a vendor revision or id the cursor only compares is
+replaced by its digest when it holds a sent value. Before a cursor is encoded,
+every string in it is checked under payload rules, and its whole text and
+encoding under the agent boundary's, which leave Connecta's own keys and counts
+to short private values. A cursor that holds a match encodes `[redacted]`,
+which the next page refuses.
+
+What redaction returns is what it checked, and only JSON data: strings,
+numbers, booleans, `null`, plain objects and arrays, a fresh built-in
+`Uint8Array`, and copies of errors. A caller's object or array is
+returned as it stands only as verified plain data: its prototype is
+`Object.prototype`, `Array.prototype`, or `null`; no `toJSON` is on its chain;
+it has no symbol-keyed field; every field is a data property the pass read, an
+array's holes read through its prototypes; and nothing in it changed. Anything
+else is returned as a copy of writable, configurable data properties, so a
+frozen or read-only input never makes redaction throw, and the caller's value is
+never mutated:
+
+- An error is always copied, as its own class. Its stack, and every accessor its
+  class defines, such as DOMException's `name` and `message` or an SDK error's
+  `status`, is read once into a checked field, under its name checked as any key
+  is. Its `toJSON`, a data field or an
+  accessor, is never read and is shadowed by an `undefined` field on the copy,
+  and a field holding a function is withheld, so the copy carries no
+  serializer. Methods its class defines stay on its prototype; JSON calls none
+  of them.
+- An object's own accessor is never invoked and is left out of the copy; an
+  array index read through an accessor holds `[redacted]`.
+
+Every other value becomes the data JSON shows for it, checked, or is withheld:
+
+| Value                                                                                      | Returned as                                                                                                          |
+| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| Function                                                                                   | `[redacted]`; a `toJSON` it holds is never called                                                                    |
+| Symbol                                                                                     | `[redacted]`                                                                                                         |
+| `bigint`                                                                                   | itself, checked as its digits like a number; JSON exits refuse it, as before                                         |
+| `undefined`                                                                                | itself; JSON omits it                                                                                                |
+| Object or array with a callable `toJSON`, such as a `Date`                                 | the result of calling it once, checked: a `Date` becomes its ISO string, or `null`                                   |
+| `String`, `Number`, or `Boolean` wrapper                                                   | its primitive, checked                                                                                               |
+| `Map`, `Set`, `WeakMap`, `WeakSet`, `Promise`, `RegExp`, or an instance of any other class | a plain object of its own data fields, checked: `{}` for the built-ins, as JSON shows them; accessors are never read |
+| Array of another class                                                                     | a plain array of its indices, checked                                                                                |
+| Typed array, `DataView`, or `ArrayBuffer`, including a subclass                            | a fresh built-in `Uint8Array` of the bytes it held, or `[redacted]`                                                  |
+
+Typed binary is withheld as `[redacted]` when its bytes hold a match, checked as
+decoded binary content is, or when one of the numbers JSON shows for it does:
+its elements and, for the `Uint8Array` returned, its bytes, each checked as a
+JSON number and joined with its neighbours. A one-to-three-character numeric
+private value, such as `7`, therefore withholds a typed array holding that
+element, as it withholds an equal JSON number. Each of those numbers is an entry
+of the walk's 1,048,576-entry budget, so binary past it is withheld whole.
+Connecta returns downstream binary as base64 text, which none of this limits;
+only in-process code can return a typed array. With nothing registered for a
+request, redaction has nothing to match and returns its input as it stands.
+
+A change copies only the containers on its path. An array's fields other than
+its indices are not read: JSON, which the MCP wire, the result stash, and every
+executor marshal values with, never serializes them.
 
 Empty private strings are exempt because they contain nothing to leak. A
-non-empty private value shorter than eight characters redacts a structured
-string leaf, property name, or scalar only when it equals the value or a
-supported encoded form, including after JSON unescaping. A longer structured
-field that merely contains it, such as `prod-db` for `prod`, is kept: this
-documented tradeoff keeps identifiers and approval state usable. Prose that
-contains a short value or encoded form anywhere is withheld as `[redacted]`:
-plain-text results, `message`, `error`, `text`, `logs`, and `stack` strings,
-string program results, and relayed prompts. Typed error classification,
-retryability, retry delay, and write-outcome accounting remain. Private values
-of at least eight characters are replaced wherever they occur.
-
-Matching runs one Aho-Corasick automaton over every registered form, so each
-scanned code unit costs amortized constant work however many values are
-registered. The automaton indexes the first 256 code units of each form,
-credentials first, and at most 512 Ki indexed units for every registration
-together, so a long credential or private value costs no more automaton memory
-than its prefix. Where a longer form's prefix matches, the scanned view's
-rolling hash confirms the rest once its last unit arrives; equal text always
-confirms, so a hash collision could only redact more. Forms that share a prefix
-and a length share each confirmation, and overlapping prefix occurrences in
-self-similar text share one run of confirmations, so periodic text stays exact.
-Each confirmation is charged to the call's work budget before it is queued, and
-one scanned view holds at most 16 Ki runs; a view that needs more is withheld.
-Submitted values register at most 512 KiB of encoded forms and 4,096
-argument nodes. A form that does not fit either limit withholds every string
-at least as long as that form; an argument tree that cannot be walked withholds
-all downstream text.
+private value of one to three characters is matched only as a whole field
+value: a string, property name, number, boolean, or decoded binary view equal
+to it or a supported encoded form is withheld, and text around it stays, so a
+private `1` leaves `row 10` alone. A value of four to seven characters is also
+replaced wherever it occurs in payload text, numbers, property names, and
+decoded views, so `prod-db` becomes `[redacted]-db` for `prod`. Pieces of either
+are not matched. Private values of at least eight characters and credentials
+are matched whole and by every eight-unit run. At a cut, an unfinished prefix of
+any registered form is still withheld, however short.
+
+Identifiers sent beside a credential are matched whole only, because consent
+URLs and vendor metadata carry their parts by design: a confidential OAuth
+client's ID, a Basic username beside a password of at least eight characters,
+and credential-slot fields named as identifiers (ending in `id`, `user`,
+`username`, `login`, or `email`, or starting with `public`). A Basic username
+beside a shorter or empty password is the credential itself and is fully
+matched. Query parameters named as continuation cursors (`pageToken`,
+`nextPageToken`, `next_token`, `continuationToken`, `syncToken`) are public
+result state and are not registered. Header values a connector adds to token
+requests are registered under any name, except values equal to Connecta's own
+public ones (`Accept: application/json`, and the media types maintained
+providers send): registering a media type would redact a vendor's name wherever
+its fragments recur.
+
+The eight-unit runs are indexed as two independent 32-bit hashes per run, at
+most 512 Ki distinct runs, so a false match is vanishingly rare and only redacts
+more; repeated runs, as in a self-similar credential, are stored once. Indexing
+and scanning are linear in the registered forms and the scanned text, whatever
+the number of values. The `Bearer ` and `token ` framings are public, so no run
+starting inside them is indexed; an echo carrying a framing is replaced with it.
+Short private values and identifiers are matched whole by one Aho-Corasick
+automaton each, which also finds the unfinished tails of bounded reads. High-
+entropy credentials and private values do not match ordinary text. A value that
+embeds ordinary text, such as a password holding a word, a token holding a
+vendor's name, or a credential that is a URL, also redacts that text where it
+recurs within the same request. Submitted values register at most 512 KiB of
+encoded forms and 4,096 argument nodes. A value that does not fit either limit,
+or a set past the index's capacity, withholds every string of eight units or
+more and every run of adjacent shorter leaves reaching eight units; an argument
+tree that cannot be walked withholds all downstream text.
 
 One redaction call has one work budget across parsing and every scanned view:
 64 Mi units with private values, and 1 Gi for credentials alone, which keeps
-multi-MiB document and skill-file reads. Work that does not fit the remaining
-budget withholds its field, so smaller identifiers can still be checked. The
-same call walks structured values iteratively, at most 512 containers deep and
-1 Mi entries in total, and copies only containers on a path that changed. A
-container's entries are counted before it is walked. One that does not fit the
-remaining entries is scanned as serialized text instead: kept unchanged when
-nothing registered appears, otherwise withheld. A cycle or a container past the
-depth limit is withheld. No limit throws or exposes a matcher diagnostic, and
-typed success outcomes remain.
+multi-MiB document and skill-file reads. When the joined projection does not
+fit, leaves are matched alone, in order, and one that does not fit is withheld
+without spending what a smaller one needs; runs crossing two kept leaves are
+then matched 512 units deep on each side of their seam. The same call visits at
+most 512 containers deep and 1 Mi entries in total. A container's entries are
+counted before it is walked.
+One that does not fit the remaining entries is withheld whole: it is never
+serialized and checked as text, so nothing past the budget reaches a result, a
+page, or the result stash. A cycle or a container past the depth limit is
+withheld. No limit throws or
+exposes a matcher diagnostic, and typed success outcomes remain.
 
 Only credentials of at least eight characters enter the redaction and structural
 matchers. Credentials shorter than 8 characters are not redacted from echoes;
@@ -1376,9 +1810,9 @@ this floor produces one operator warning per connector with the typed code
 `short_secret_not_redacted` and no credential value. Remote connectors warn at
 construction; static `api()` OAuth warns on its first provider operation.
 Connecta's own messages never quote credential values, regardless of length.
-One automaton is cached until the secret set changes, and an empty set skips matching. Redaction runs after
-JSON unwrapping or joining text blocks and on final serialized text and every
-structured string, before result paging, emits, and program outputs/errors/logs. See
+The index and automata are cached until the secret set changes, and an empty set skips matching. Redaction
+runs before JSON unwrapping or joining text blocks, on final serialized text and every
+structured value, and before result paging, emits, and program outputs/errors/logs. See
 [the agent boundary](./architecture.md#errors-and-records).
 
 ## URLs a downstream advertises
@@ -1498,8 +1932,8 @@ createConnecta({
   auth: cloudflareAccessAuth(),
   // Administers shared credentials, agent tokens, and activity.
   maintainers: ["owner-id"],
-  // Each member connects their own account on personal_linear.
-  pools: { team: { tools: ["shared_docs", "personal_linear", "notion.search_pages"], members: team } },
+  // Each member connects their own account on personal_crm.
+  pools: { team: { tools: ["shared_docs", "personal_crm", "notes.search_pages"], members: team } },
   connectors, executor,
   readOnly: false, // required: true refuses every write call
 });
@@ -1539,7 +1973,8 @@ Connecta configuration still decides connector access and management: `maintaine
 Protect the Worker with a Worker-level Access application whose destination is
 `{ "type": "worker", "worker_id": "<the Worker script tag>" }`. A traditional
 hostname-level application blocks the URL but does not attach `ctx.access` to
-the Worker. Enable [**Managed OAuth**](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/managed-oauth/)
+the Worker. The Worker example's `alchemy.run.ts` declares this application and
+attaches it through the Worker's `access` property. Enable [**Managed OAuth**](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/managed-oauth/)
 on that Worker-level application for interactive MCP clients. Cloudflare then
 owns the unauthenticated challenge and `/.well-known/` metadata, issues opaque
 RFC 8707 tokens, and resolves them into the same trusted Worker identity.
@@ -1627,7 +2062,10 @@ claims. SDK 3.12.0 drops opaque `aud`, so connecta makes one additional Backend
 API verification request and reads the raw response. Its subject and client
 must agree with the SDK, and it must report an unrevoked, unexpired token.
 The extra call follows request cancellation, times out after ten seconds,
-caches no token or audience, and denies admission on failure.
+reads at most 64 KiB, follows no redirect, caches no token or audience, and
+denies admission on failure, including a redirect. It ends its request and
+response body on every outcome, including an error status and a body that
+stops arriving.
 
 ### Explicit fallback for unbound tokens
 
@@ -1644,6 +2082,140 @@ for this fallback. Hosts may cache registrations, but the list is impractical
 for standard onboarding. A CIMD client identifies the host, not the deployment
 resource. Prefer resource audiences with `allowedOAuthClientIds` omitted or `[]`.
 
+### One Clerk instance, one Organization per deployment
+
+`organizationId` lets one Clerk instance serve several deployments. Give each
+deployment its own Clerk Organization and pass that Organization's id. In the
+Node template, set `CLERK_ORGANIZATION_ID` instead of editing source.
+
+```ts
+clerkAuth({ publishableKey, secretKey,
+  publicUrl: "https://crm.example.com",
+  organizationId: "org_..." });
+```
+
+Admission in organization mode:
+
+- Membership is the only organization rule. Every admitted Clerk user is a
+  member of that Organization. Connecta asks Clerk's Backend API,
+  `GET /v1/organizations/{organization_id}/memberships?user_id={user_id}`,
+  for MCP OAuth tokens (JWT and opaque) and for operator sessions. It caches
+  each answer per Organization and user, counted from when the lookup
+  started: a member for 60 seconds, a non-member for 30. Each request that
+  misses the cache runs its own lookup, subject to the bounds below. An answer
+  is cached only if no lookup that started later has already cached one, so an
+  older answer never replaces a newer one. If eviction suppresses a newer
+  answer, any older answer for that user is invalidated. Assuming the clock
+  does not step back unseen within the TTL window described below, every
+  request reaching the check 60 seconds or more after a member's removal in
+  Clerk is refused, even while their day-long access token remains valid.
+  Under the same clock assumption, a non-member answer expires within 30
+  seconds of an addition; admission then requires a successful lookup.
+- The cache reads the deployment's clock. An answer is used only while the
+  clock reads from its lookup's start to that start plus 60 or 30 seconds.
+  A step forward only ends it early. A step back to before the start ends it
+  too, and once an answer has been found expired no later step revives it. A
+  step back that lands within that window before any request has seen the
+  answer expire cannot be detected, and keeps the answer until the clock
+  again reads its start plus the TTL. That unseen rollback can extend cached
+  admission beyond 60 seconds of elapsed time after removal.
+- Organization claims are never read. A token's `org_id` and a session's
+  active Organization neither admit nor refuse. A member's token is bound to
+  this deployment's URL whichever Organization they chose in Clerk, and a
+  non-member gets `403` from the lookup.
+- A lookup that fails, answers with a redirect, an error status other than
+  `429` (handled below), or an unreadable or oversized body, or times out ten seconds after it started
+  refuses its request with `403`. Redirects are never followed. A caller that
+  leaves cancels its own lookup and is refused; other requests' lookups go
+  on. Connecta ends the Backend API request and its body on every outcome and
+  caches neither a failure nor a cancelled lookup, so the next request asks
+  Clerk again, subject to the bounds and 429 backoff below.
+- Connecta checks the token's audience, issuer, and subject before the lookup.
+  The issuer must be the Frontend API origin encoded in `publishableKey`, and
+  the subject must be the user the lookup names. An opaque token's
+  verification response comes from the instance's Backend API and is matched by
+  subject instead. A mismatch gets `401`.
+- Organization roles and permissions grant nothing. `maintainers` and pool
+  `members` still list Clerk user ids in code. A member of the Organization in
+  neither list gets `404` at `/mcp` and at every `/mcp/<pool>`.
+- `allowedDomains` and `gate` still apply after membership. Every configured
+  check must pass, and an outsider never reaches `gate`.
+- Resource-bound tokens are required. A nonempty `allowedOAuthClientIds`
+  throws at construction; omit it or pass `[]`. Every deployment on a shared
+  instance gets tokens from one issuer, so the resource audience is what keeps
+  one deployment's token out of another.
+- Advertised scopes are unchanged. Organization mode needs no Clerk
+  organization scope, operator page, or sign-in page setting.
+
+Protect the shared Backend API quota:
+
+- Put ingress rate limiting in front of every deployment. Budget the combined
+  traffic of all deployments and other applications using the instance,
+  including authenticated non-members and opaque-token authentication. For
+  example, rate limit both `crm.example.com` and `tickets.example.com` within
+  one shared quota budget when they use the same Clerk instance; independent
+  limits that each consume the whole quota do not protect the other deployment.
+  [Clerk's system limits](https://clerk.com/docs/guides/how-clerk-works/system-limits)
+  apply per instance identified by the secret key: 1,000 Backend API requests
+  per ten seconds in production, 100 in development. Membership reads use that
+  general limit. A deployment's MCP concurrency setting does not bound all
+  authentication paths, including `subscriptions/listen` and operator routes.
+  The independent [authentication capacity bound](#authentication-capacity-and-ingress-limiting)
+  covers those paths and the SDK's authentication calls before this adapter's
+  organization-specific bounds; it still does not impose a rate budget.
+- Organization mode permits at most 16 concurrent membership/extra opaque
+  verification calls per `clerkAuth` instance (per isolate on Workers), with at
+  most two per user. Each call owns its signal, deadline, and response body;
+  there is no shared promise or waiting queue. Excess calls immediately get
+  HTTP `503`, fixed code `organization_lookup_busy`, `retryable: true`, and
+  `Retry-After: 1`. These fixed caps limit bursts relative to the documented
+  quotas; they do not limit sustained request rates or coordinate isolates,
+  deployments, or the SDK's own authentication calls. Do not treat them as a
+  substitute for ingress rate limiting.
+- A `429` from a membership read or extra opaque verification starts backoff
+  shared by those calls in that isolate. Connecta honors `Retry-After` seconds
+  (or an HTTP date), clamped to 1–60 seconds; missing or malformed values use
+  ten seconds. Concurrent 429s can extend, never shorten, the current backoff.
+  The triggering request and new misses during backoff receive the same
+  retryable `503` and a `Retry-After` for the remaining whole seconds, rounded
+  up. Backoff is timed on the wall clock, so a clock step back while it runs
+  lengthens the window by the size of the step. No membership verdict is
+  cached for these refusals. Valid cached
+  membership answers remain usable; opaque tokens still need verification.
+  After backoff expires the next miss asks Clerk again, with no automatic
+  retry of the original request. Monitor the payload-free
+  `organization_lookup_busy` log reason and adjust the ingress budget when it
+  recurs. A quota exhausted by another deployment can still refuse uncached
+  admission here.
+
+Set up a shared instance:
+
+1. Enable Organizations on the Clerk instance. Create one Organization per
+   deployment. Add each person who signs in to that deployment as a member;
+   any role works.
+2. Enable resource audiences as described in
+   [Enable resource audiences in Clerk](#enable-resource-audiences-in-clerk).
+   Each deployment has its own public URL, so its tokens name only it.
+3. Set `organizationId` to the deployment's Organization id. List
+   `maintainers` and pool `members` by Clerk user id as usual.
+4. Restart or redeploy. Verify that a member is admitted at `/mcp` and on the
+   operator pages, a signed-in non-member gets `403`, and a token issued for
+   another deployment's URL gets `401`.
+
+Isolation tradeoff: the secret key is instance-wide. It reaches every
+Organization, user, and OAuth application on the instance, so whoever reads it
+from one deployment's environment can read and change every other
+deployment's membership. Organization mode separates admission, not
+administration. When a deployment needs its own keys, users, or instance
+settings, give it its own Clerk instance and omit `organizationId`; that shape
+remains fully supported.
+
+Organization denials log the fixed codes `organization_membership_denied`,
+`organization_lookup_failed`, and `token_identity_mismatch`. They carry no user
+ids, Organization ids, or Backend API response text.
+
+### Session and diagnostic boundaries
+
 Clerk session tokens authenticate operator routes and browser OAuth callbacks
 only, with the deployment-origin `azp` check. MCP rejections retain the `401`
 Bearer challenge and endpoint `resource_metadata` URL required by
@@ -1679,7 +2251,9 @@ that is not `pk_test_`/`pk_live_` and a base64-encoded domain throws when
 `clerkAuth` is called, as `allowedDomains` does, naming the option without
 quoting the value — usually the _secret_ key pasted into the publishable slot.
 A per-request deployment, as on Workers, sees that error on its first request
-instead of a base64 stack on every route.
+instead of a base64 stack on every route. `organizationId` must be `org_`
+followed by 27 letters or digits, and it cannot be combined with a nonempty
+`allowedOAuthClientIds`; either mistake throws at construction.
 
 ## Human authentication management
 
@@ -1739,6 +2313,25 @@ and Origin checks. Vaults without sealing keep ordinary handoffs and cannot
 serve URL elicitation. See [authorization recovery](./meta-tools.md#authorization-recovery)
 for capability gating, retry termination, and dispatch restrictions.
 
+Downstream OAuth credential POSTs (code exchange, refresh, dynamic client
+registration and revocation) use a transport that sends each request at most
+once and never follows redirects. On Node, serve with `listen` from
+`@zackbart/connecta/node` and retain the `undici` peer; custom root-only Node
+hosts refuse these POSTs before dispatch. Node's explicit `listen({ proxy })`
+option applies to them. Discovery GETs keep native fetch and its host proxy
+policy. Workers use their native fetch transport. See [Node transport setup](./deploying.md#start-on-node).
+
+A refresh without a confirmed usable answer may have rotated the refresh token.
+Connecta blocks its fingerprint and requires a fresh authorization flow, without
+replaying that token or claiming the server did not receive it. Authorization
+can still be restarted; an unresolved fingerprint cannot become redeemable again
+by writing the same token into an old grant. Registration failure can leave a
+client at the provider; check the provider's client administration before
+starting another registration if its reply was lost. Disconnect removes the
+local grant before attempting revocation, and an unconfirmed revocation asks the
+operator to revoke it at the provider. No token forms or provider error prose
+are included in diagnostics.
+
 A verified `/connect` visit gives downstream OAuth work and its state handoff 30 seconds. The request signal
 and deadline reach discovery, registration, and other downstream fetches; expiry returns `504 OAuth
 authorization start timed out`. A restart's grant write, catalog invalidation, and scope close drain before
@@ -1759,9 +2352,15 @@ its URL.
 
 Credential and OAuth mutation require interactive identity, connector visibility, management permission, and
 an exact same-origin `Origin` for browser mutations. A static credential `authorize_connector` call needs
-visibility only: with `ui: operatorUi()` and a vault it returns a secret-free `operator_config` handoff;
-without either it returns `unavailable`. The OAuth branch also checks management permission and returns
-`unavailable` when refused.
+visibility only. With `ui: operatorUi()` and a vault, a missing credential returns a secret-free
+`operator_config` handoff; without either it returns `unavailable`. When all declared credential
+fields are configured, the explicit result returns `ready` with conditional guidance and retains
+the operator handoff fields (or the deployment configuration message when recovery is unavailable).
+If a call just failed with an authentication or operator-configuration error, give that handoff
+to the operator; otherwise proceed with the call. Presence does not validate a key, and this
+stateless result cannot remember failures from earlier requests. Authentication errors retain
+`oauth`, `operator_config` or `unavailable` recovery, never `ready`. The OAuth branch also checks
+management permission and returns `unavailable` when refused.
 
 Core owns `/connect/<connector>` and the callback without the optional UI. Both require Clerk sessions or
 Cloudflare Access users; MCP OAuth tokens, `cta_` tokens, and Access service identities
@@ -1844,9 +2443,9 @@ path, without credentials or a fragment. Its `client_id` must equal its URL,
 and its metadata must include the deployment's exact callback and public-client
 authentication. Changing from an external document to the self-hosted URL needs
 one Disconnect and reconnect because tokens belong to the old client ID.
-`basecamp()` now defaults to the self-hosted document and accepts an external
-URL override. Basecamp restricts DCR for HTTPS callbacks, so it needs a public
-HTTPS deployment or an external document.
+Basecamp restricts DCR for HTTPS callbacks, so its generic `remoteMcp()` entry
+needs a public HTTPS deployment or an external document. Preserve its client
+identity when following the [hosted MCP migration guide](./hosted-mcp-migration.md).
 
 For a pre-registered client, use:
 
@@ -1924,10 +2523,28 @@ owner's access token as `Authorization: Bearer` with these rules:
   untrusted response URLs. Return redirects unfollowed; handlers cannot set `Authorization`.
 - On 401, recover exactly once using an already rotated token or one coalesced
   refresh through `remoteMcp()`'s coordinator. Persist rotation even when its
-  owner is cancelled after the answer. Replay once; stream bodies are refused.
+  owner is cancelled after the answer. Only a positively read-classified
+  GET/HEAD without method-override headers replays once;
+  stream bodies are refused.
+- A request the core classifies as a write never replays (INV-9). Positive read
+  classification comes from deployment `classification` first and otherwise the rule the
+  registry applies to the tool's hints (a contradictory `readOnlyHint: true`
+  with `destructiveHint: true` is a write). The actual method must also be GET
+  or HEAD; an override header, missing read evidence, or a POST remains a
+  one-attempt write, even when the tool calls it a read. After the recovery,
+  the call fails with a non-retryable `connector_call_failed` whose outcome is
+  unknown, and the renewed grant serves any fresh call the agent makes after
+  reconciling the target.
+- Whatever that recovery meets, a write's failure is never retryable and its
+  outcome is unknown. Until a refresh succeeds the 401's verdict stands:
+  `downstream_oauth_required`, which the invocation marks
+  `reconciliationRequired`, with the `authorize_connector` handoff, whether
+  the refresh was [dead](#refresh-failures), lost after it was sent, raced
+  by a disconnect or reset, failed in storage or contention, or handed back
+  the token the API just rejected, which renews nothing.
 - No grant, a second 401, or a [dead refresh](#refresh-failures) means
   `downstream_oauth_required`, directing `authorize_connector`. Refresh waiter deadlines
-  return retryable `unavailable`. Latch second 401s for the request scope,
+  return retryable `unavailable` for a read. Latch second 401s for the request scope,
   preventing repeated refreshes by later program calls.
 - Handlers can name no storage, sealing, or owner partition; the registry owns them.
 - The answer's `.text()` and `.json()`, clones' too, decode its bytes as UTF-8, so
@@ -1963,6 +2580,90 @@ provider skill explains App permissions and installation prerequisites.
 
 ## Contributor reference
 
+### INV-5 output redaction limits
+
+The output boundary's guarantee is K = 8 units, and these are its exact limits:
+
+- A run of eight consecutive UTF-16 units of a registered form is matched
+  wherever it appears, raw, under JSON escapes, or in a decoded base64 view.
+- Pieces shorter than eight units are matched only where they are adjacent:
+  the projection joins neighbouring leaves (array items, text blocks), and
+  provider lanes join one source's runs (one Slides shape's text runs, one Docs document's text). Pieces shorter than eight
+  units that are not adjacent, such as the two seven-unit halves of a fourteen-
+  unit value in two Slides shapes with other leaves between them, survive: they
+  are indistinguishable from ordinary text without redacting ordinary words.
+- Object keys are checked on their own and never join the value projection, so
+  a key never separates two adjacent values. A value split between a key and
+  its value with each piece shorter than eight units, such as a seven-unit key
+  holding a seven-unit value, survives like any other non-adjacent pieces; a
+  piece of eight or more units is still matched in either place.
+- Private values of one to three units match whole field values only; four to
+  seven also as substrings; eight and more also by every eight-unit run.
+- One checker (`checked()` in `src/sent-secrets.ts`) applies everything below
+  to every output-bound string: leaves, keys, scalars, declared binary, typed
+  binary, cursor claims and Connecta's own encodings, provider lanes, bounded
+  reads and structural refusals. Its matching steps run only inside it; a
+  serialized container's cross-token scan, which can only withhold it whole, is
+  the one other reader of the fragment index. The test "there is one string
+  checker" spies on every step and fails when one runs outside it.
+- A Proxy, which only in-process code can construct, can answer a later read
+  differently from the one redaction made; the guarantee covers what redaction
+  read. So can code on an error class's prototype, which its copy keeps so that
+  classification still sees its class; JSON calls none of it once `toJSON` is
+  shadowed. Only verified plain data is returned as it stands; everything else
+  is a copy of checked data properties, and every value is JSON data, a fresh
+  `Uint8Array`, or an error copy.
+- An array's fields other than its indices are never read, because JSON never
+  serializes them.
+
+The encoding lattice is exactly this, and anything outside it is out of scope:
+
+- Text views of every string, whether a leaf, a key, a declared binary field or
+  a cursor claim: the raw text; one layer of JSON escapes decoded
+  (`\uXXXX` and `\" \\ \/ \b \f \n \r \t`); percent escapes decoded; and
+  the form decoding, a `+` read as a space with any percent escapes decoded,
+  generated whenever a `+` appears. Text matching itself also reads
+  through up to eight JSON escape layers and matches registered percent forms.
+- In every text view, base64 and base64url runs are decoded. A run is a maximal
+  span of `A-Z a-z 0-9 + / - _`, decoded from its first unit; up to two `=`
+  after it are padding and are never counted. A whole view is decoded from six
+  units; a run inside one from `SHORT_RUN_UNITS` = 6 under payload rules with a
+  four-to-seven-unit private value registered, otherwise `FRAGMENT_RUN_UNITS` = 11.
+- Derivation: a run of L units decodes to floor(3L/4) bytes, so p bytes that start
+  a bytes into the encoding (alignment a = 0, 1 or 2) need L >= ceil(4(a + p)/3),
+  least at a = 0. The smallest piece a payload pass matches is a short value,
+  four units and so at least four bytes: ceil(16/3) = 6. Otherwise it is K = 8
+  units, at least eight bytes: ceil(32/3) = 11. Padding follows the run, so a
+  padded and an unpadded encoding decode alike. The tests cover four-, seven-
+  and eight-unit values at every alignment, padded and unpadded, in both
+  alphabets.
+- Decoded bytes are matched as bytes, as UTF-8 when a form is not ASCII, and
+  through their own JSON escapes within the eight-layer limit. Every decode is
+  charged to the call's work budget, and content the budget cannot check is
+  withheld.
+- Bytes, decoded or held by a typed array, are checked as bytes, through their
+  JSON escapes, as UTF-8, and through the base64 they carry. Text views are
+  views of strings: bytes that need a percent or form decoding before their
+  base64 shows are two decodes chained, outside the lattice.
+- Out of scope: two or more text-layer decodes chained (percent escapes inside
+  JSON escapes, or two JSON layers before base64); base64 of base64 (decoded
+  content is searched for base64 up to three levels deep, but the guarantee does
+  not depend on it); a base64 encoding glued to preceding alphabet units with no
+  separator, such as a path segment after `/`, which decodes misaligned; HTML
+  entities; compression; custom alphabets; encryption; bytes written as a
+  JSON array of numbers; and one encoding split across separate leaves, such as
+  the base64 of a value cut into array items. Raw text and JSON escapes are
+  matched across adjacent leaves, but base64 and base64url decoding operates
+  within each string.
+- The boundary removes echoes of values Connecta sent. A downstream already
+  holds what it was sent and can always return it in a form outside this
+  lattice, so redaction is not a defense against a downstream that reshapes a
+  value on purpose.
+
+`test/sent-secret-output-boundary.test.ts` holds the evidence, including its
+`review round 3`, `review round 4` and `review round 5` blocks for these limits;
+`test/writeonly-wire-redaction.node.test.ts` runs the QuickJS guest cases.
+
 ### Source and tests
 
 [Decision 0007](https://github.com/zackbart/connecta/blob/main/decisions/0007-agent-pool-layout.md)
@@ -1973,6 +2674,8 @@ boundaries, and `src/storage/keys.ts` owns credential key families.
 Inbound adapters live in [src/auth](https://github.com/zackbart/connecta/tree/main/src/auth);
 [auth routes](https://github.com/zackbart/connecta/blob/main/src/routes/oauth.ts)
 own connection handoffs and callbacks. Check [inbound auth tests](https://github.com/zackbart/connecta/blob/main/test/inbound-auth.test.ts),
+[Clerk organization tests](https://github.com/zackbart/connecta/blob/main/test/clerk-organization.test.ts)
+and their [workerd counterpart](https://github.com/zackbart/connecta/blob/main/test/clerk-organization-workerd.test.ts),
 [Access tests](https://github.com/zackbart/connecta/blob/main/test/cloudflare-access-auth.test.ts),
 and [identity-scope tests](https://github.com/zackbart/connecta/blob/main/test/identity-scope.test.ts)
 for credential precedence and disclosure boundaries.
@@ -1985,3 +2688,23 @@ Downstream OAuth implementation and evidence are in
 [refresh leases](https://github.com/zackbart/connecta/blob/main/test/oauth-refresh-lease.test.ts),
 and [API OAuth tests](https://github.com/zackbart/connecta/blob/main/test/api-oauth.test.ts).
 Use the test pointers within each section for narrower failure cases.
+
+### Authentication execution (contributor)
+
+Built-in authentication and downstream OAuth use private native programs behind
+the same Promise adapter and SDK contracts. Recognition still selects one
+verifier, and a refusal never falls back to another identity provider. Native
+operations use the existing request owner; cancellation cannot make a closed
+caller consume a refresh result or send another resource request. Once the
+claim CAS is submitted, the bounded refresh coordinator completes independently
+and commits a successful rotation under the existing epoch and spent-token
+rules. Code exchange does not acquire that coordinator ownership.
+
+Authentication capacity remains charged until the underlying uncancellable work
+settles or collection proves that work unreachable. Abandonment alone never
+releases capacity. A native
+refactor does not change membership cache TTLs, audience/resource bindings,
+agent namespaces, credential partitions, OAuth transport policy or the rule of
+one physical attempt per credential-bearing POST. See the
+[native auth implementation](./architecture.md#native-auth-programs-contributor)
+for contributor boundaries and retained Promise leaves.