@zackbart/connecta 0.36.2 → 0.37.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), [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), [Google hosted MCP](#google-service-account-tokens-and-hosted-mcp)      |
-| 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), [principal forwarding](#forwarding-the-admitted-principal), [Google hosted MCP](#google-service-account-tokens-and-hosted-mcp) |
+| 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.
@@ -1336,6 +1336,29 @@ healthy. Restart invalidates it even if the connection ends healthy. Continue
 trusts the stored registration's `redirect_uris`; after changing `publicUrl`,
 Restart registers for the current callback URL.
 
+For `remoteMcp()` OAuth, the owner's stored grant decides whether a connection
+is connected, not whether the downstream answers. Some servers answer
+`initialize` and `tools/list` without credentials and challenge only
+`tools/call`. The operator status, the UI's connected state, and a start agree
+with the gate a call passes:
+
+| Stored grant        | Status                                                      | Start (Connect, Continue, Restart, `authorize_connector`)                                                                                                                                                                                                                          |
+| ------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Disconnected        | `auth_required`; the downstream is not asked                | Replaces the epoch, then proceeds as for no tokens                                                                                                                                                                                                                                 |
+| No tokens           | Connects; `auth_required` even when the downstream answers  | Connects first, so a 401's `resource_metadata` starts consent as before. A downstream that answers without credentials still gets consent, discovered from RFC 9728 metadata at the configured URL's well-known locations. The start answers `auth_required` with the consent URL. |
+| Tokens (any expiry) | Connects; `ok`, or `auth_required` when a 401 needs consent | Connects; `ok` without starting a flow when healthy                                                                                                                                                                                                                                |
+
+A start without a challenge runs the same SDK flow as a 401 without
+`resource_metadata`. Issuer and resource checks, consent state, PKCE, and
+the CIMD, registration, and static-client order are unchanged, and nothing is
+sent to the MCP endpoint. A call never starts consent. A call's 401 that names
+per-tool metadata, such as `/.well-known/oauth-protected-resource/<tool>`,
+renews through it when the grant holds no discovery. That metadata must name
+the configured resource, as any other must. When renewal is refused, the grant
+loses its tokens and the next start hands out consent. Restart (`force: true`)
+removes the tokens first, so it starts consent unless the downstream or
+discovery fails.
+
 ### Consents and callbacks
 
 A start stores its flow record, then the grant's pointer to it. A reset that
@@ -2648,12 +2671,18 @@ For providers offering both, deployment config chooses; handlers check `ctx.oaut
 
 `remoteMcp("<id>", { auth: { type: "request", token: async (ctx) => … } })` resolves
 its token before connecting and before reusing a client. The callback receives
-the operation's cancellation context, never an agent-selected credential owner.
+the operation's cancellation context only. It never receives an agent-selected
+credential owner, and without the opt-in below it never receives the caller.
 Only shared ownership is accepted. Tokens remain inside the request's hardened
 transport, are not stored or described, and a changed token replaces the client.
 This mode refuses cleartext non-loopback origins. Optional `auth.headers` carry
 static protocol/catalog controls and cannot set Authorization.
 
+Return the same token for the same caller while it remains valid, and cache a
+minted token until shortly before it expires. A value that changes on every
+resolution replaces the client each time; a change that lands while a call
+connects fails that call with a retryable error.
+
 A resolver may expose `token.invalidate(rejectedToken, ctx): Promise<void>` to
 remove a cached token after a downstream HTTP 401. The hook receives the exact
 token sent by that transport, so it must leave a newer cached token intact.
@@ -2672,6 +2701,95 @@ is retained across requests, and rejected writes are never replayed. An omitted
 `describe()` includes neither the key nor the minted tokens. The maintained
 provider skill explains App permissions and installation prerequisites.
 
+### Forwarding the admitted principal
+
+Set `auth.principal` instead of `auth.token` to let the resolver act for the
+caller inbound auth admitted. Use it only for a downstream the deployment
+controls and that already trusts this deployment, so the downstream needs no
+per-person OAuth:
+
+```ts
+auth: {
+  type: "request",
+  principal: {
+    accept: "human",
+    token: async (ctx, { principal }) => await notesAssertion(principal),
+  },
+},
+```
+
+- `principal` is `{ kind: "human", namespace, id }`: the admitted person's
+  stable reference, the same `{ namespace, id }` a pool member resolves to.
+  Inbound auth admits no verified email or display name into it; map the id in
+  deployment code or in the downstream when one is needed.
+- `accept: "human"` admits only people. Agents, anonymous callers,
+  principal-less machine credentials and contexts no request admitted are
+  refused with `auth_required` before the resolver runs. Agents still see the
+  connector, and their calls fail. No identity is ever substituted.
+- `accept: "human-or-agent"` also admits declared agents as
+  `{ kind: "agent", name, pool }`, the pool being the one the agent arrived on.
+  An agent is never presented as a person, its pool's owner included.
+- The caller comes only from the authorization that admitted the request.
+  Tool arguments, program code and request headers cannot choose or change it.
+- The principal joins the client's identity. A different principal never
+  reuses a client, connection or connect in flight, even when the resolver
+  returns the same token. `token.invalidate(rejected, ctx, { principal })`
+  receives the principal the rejected token was minted for.
+- Catalog listing needs an admitted caller like any call, and its cache stays
+  partitioned per caller. Operator status and catalog checks carry no caller,
+  so they report `auth_required` without connecting.
+- The connector stays shared. Connecta keeps no per-principal credential state
+  and never stores, logs or describes the principal or the token. `describe()`
+  reports `mode: "request"` as for any request resolver.
+
+#### Over a Workers service binding
+
+Pair principal forwarding with the optional `fetch` to reach a sibling Worker
+through a service binding. Then neither Cloudflare Access, the public internet
+nor a service token lies between the two Workers:
+
+```ts
+const notes = remoteMcp("notes", {
+  url: "https://notes.example.com/mcp",
+  fetch: (input, init) => env.NOTES.fetch(input, init),
+  auth: {
+    type: "request",
+    principal: {
+      accept: "human",
+      token: async (_ctx, { principal }) => await notesAssertion(principal, env.NOTES_ASSERTION_KEY),
+    },
+  },
+});
+```
+
+`notesAssertion` is deployment code. It signs a short-lived assertion naming
+`principal.namespace` and `principal.id` with a key both Workers hold, and
+caches it per principal until shortly before it expires. Over a binding, the
+token may instead be an unsigned principal reference, provided the downstream
+reads it only where the trust rule below holds.
+
+The downstream must accept a forwarded identity only through its binding
+entry point or after verifying the signature. Bind to a named entrypoint, such
+as `{ "binding": "NOTES", "service": "notes", "entrypoint": "Connecta" }` in
+the deployment's Wrangler `services`, and read the identity only in that
+entrypoint. Never accept it on a public route: anyone who can reach that route
+could name any person. A signature verified with a deployment-held key is also
+safe on a public route.
+
+`fetch` carries every MCP request, including handshakes, catalog reads, calls,
+writes and session close. Global fetch is never used for that connector. The
+configured `url` stays the logical origin: its HTTPS rule, cleartext refusal,
+redirect policy and same-origin redirect checks apply unchanged. A request for
+any other origin is refused before it reaches `fetch`. Each request, writes
+included, is handed to `fetch` once with `redirect: "manual"`, and a dispatched
+write is never sent again, so `fetch` must not retry or follow redirects. On
+Node, such writes do not need the owned transport. `fetch` cannot be combined
+with OAuth auth, because discovery, registration and token requests go to
+authorization servers the downstream names.
+
+Contributor evidence: `test/remote-mcp-principal-forwarding.test.ts` runs on
+Node and, through a real service binding, on workerd.
+
 ### Google service-account tokens and hosted MCP
 
 Import `googleServiceAccountToken` from `@zackbart/connecta/google` to connect a

package/documentation/code-mode.md

@@ -65,9 +65,15 @@ createConnecta({ executor: workerExecutor({ loader: env.LOADER }), readOnly: fal
 ```
 
 The adapter uses only `loader` and an optional `timeout`. Its admission defaults
-are two active runs, eight queued runs, and a five-second queue deadline, settable
-through `admission`. Lease release disposes RPC and loader handles independently
-of guest settlement. `bindings`, `modules`, or `globalOutbound` violate `P2`.
+are two active runs, eight queued runs, a 60-second queue deadline (the default
+guest deadline) and a one-second `retryAfterMs` hint. `admission` replaces all
+four: `{ concurrency, maxQueueSize, queueTimeoutMs, retryAfterMs? }`, where an
+omitted `retryAfterMs` equals `queueTimeoutMs`. The pool belongs to the executor
+instance, so a Worker that builds one per isolate bounds each isolate, not the
+deployment or a caller: concurrent requests that land on one isolate share its
+slots, and requests on other isolates do not count. Lease release disposes RPC
+and loader handles independently of guest settlement. `bindings`, `modules`, or
+`globalOutbound` violate `P2`.
 The [Worker example](../examples/worker/README.md#code-mode) has the full setup.
 
 Keep the Worker's optional peer. Unbranded executors throw, including bundled upstream copies.
@@ -981,7 +987,21 @@ payload is refused before parsing and names no address.
 plus a bounded queue with a wait timeout. Overload is a retryable
 `executor_overloaded` carrying `retryAfterMs`; cancellation and shutdown are
 terminal. Admission happens _before_ any catalog or provider is built, so a
-queued request holds no state.
+queued request holds no state. A full queue refuses at once with
+`Executor queue is full.`; a queued run that outlives `queueTimeoutMs` is
+refused with `Executor admission timed out after <n>ms.`. Either arrives as an
+error result whose `structuredContent.error` is
+`{ code: "executor_overloaded", message, retryable: true, retryAfterMs }`, with
+`hostCalls` all zero; the program never started, so retrying it after
+`retryAfterMs` sends nothing twice. Whichever request releases a slot, the
+queued run resumes, builds its providers, makes its host calls and holds its
+sandbox handles in its own request; the releasing request's result is
+unaffected. A slot handed to a queued run is heard a turn after it is granted.
+When the executor closes in that gap, the slot is given back and the run is
+refused with `executor_closed`, so nothing granted before `close()` starts after
+it. A grant that beat the caller's abort stays the caller's, which releases it
+on arrival. A queued run also holds its MCP request permit
+([request admission](./architecture.md#admission-in-two-places)) while it waits.
 
 **L8.** Result, log, host-call, and emission budgets are deployment configuration.
 A call may request `timeoutMs` just as a direct call does; the guest deadline is
@@ -1287,7 +1307,7 @@ rejection, and branded adapter acceptance across module copies.
 | `L1`, `L2`             | `test/guest-api-contract.test.ts` (in-flight call fails `cancelled`), `test/execute.test.ts` (cancels outstanding host calls, discovery included, and refuses discovery after the run; a cancelled wedged executor, or one whose `acquire()` ignores the signal, returns promptly and releases its lease)                                                                                                                                                                                                                       |
 | `L3`, `X1`             | `test/guest-api-contract.test.ts` (short-deadline executors), `test/execute.test.ts` (the watchdog ends a never-settling executor, frees the default pool, spares a slow run, and falls back from an unusable value)                                                                                                                                                                                                                                                                                                            |
 | `L4`, `L8`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (shared discovery/call budgets and terminal catch-and-continue loops and queued-write cancellation on both executors), `test/worker-budget-response.node.test.ts` (native handle disposal and admission recovery across completed HTTP responses)                                                                                                                                                                                                                     |
-| `L5`, `L7`, `X2`       | `test/quickjs-executor.node.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue)                                                                                                                                                                                                                                                                                                                                                                                    |
+| `L5`, `L7`, `X2`       | `test/quickjs-executor.node.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue), `test/executor-requests.test.ts` (queued handoffs and refusal shape across separate workerd requests), `test/request-context.node.test.ts` (queued and QuickJS host-call request context)                                                                                                                                                                                         |
 | `L6`, `X10`            | `test/guest-api-contract-quickjs.node.test.ts` and `test/guest-api-contract.test.ts` (whole oversized reads and one-write pageable handles), `test/sqlite-storage.node.test.ts` and `test/kv-to-d1.test.ts` (SQL stash and native D1 fault probes), `test/quickjs-executor.node.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message), `test/quickjs-child-stderr.node.test.ts` (outer reply serialization failure settles the call)                                                 |
 | `V1`–`V4`              | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no event for the execution itself), `test/activity.test.ts` (the shared code → friction table, the identity clamp, the one-attempt floor), `test/browser/operator-ui.spec.ts` (identity changes), `test/sql-storage-contract.ts`, run by `test/sqlite-storage.node.test.ts` (historical activity rows still round-trip)                                                             |
 | `V5`, `W9`             | `test/program-writes.test.ts` (unawaited program drain, failed-program accounting), `test/identity-write-journey.node.test.ts` (committed ambiguity, reconciliation and physical writes), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                                                                                 |

package/documentation/integrating.md

@@ -163,15 +163,28 @@ also supports OAuth, static headers, and request-local token resolution. Use
 [client registration](./auth.md#downstream-oauth-client-registration), and
 [request-local tokens](./auth.md#request-local-downstream-bearer-tokens)
 for those cases. Secrets belong in deployment secret storage or the vault,
-not source literals.
+not source literals. For a first-party downstream that already trusts this
+deployment, request auth can
+[forward the admitted principal](./auth.md#forwarding-the-admitted-principal)
+instead of asking each person to authorize it.
+
+Optional `fetch` sends every MCP request for one connector through a
+deployment-supplied function instead of global fetch, such as a Workers
+service binding: `fetch: (input, init) => env.NOTES.fetch(input, init)`. `url`
+still names the logical origin, and its HTTPS, redirect and same-origin rules
+apply. `fetch` receives each request once with `redirect: "manual"` and must
+not retry. It cannot be combined with OAuth auth. See
+[over a Workers service binding](./auth.md#over-a-workers-service-binding).
 
 Use optional top-level `headers` for non-secret resource context:
 `remoteMcp("crm", { url: "https://crm.example/mcp", headers: {
 "X-MCP-Toolsets": "tickets,notes" }, readOnly: true })`. These headers apply to
 MCP handshake, catalog and call requests at the exact resource URL path, never OAuth
 metadata, token or registration requests. Values are included in cache and
-negotiation identities; values of at least eight characters are redacted if echoed. Configuration descriptions
-show only names. Never put credentials here. Use `auth` for secrets. Extra
+negotiation identities. They are never treated as sent secrets: program and
+direct-call arguments equal to a header value reach the downstream unchanged on
+every call, and results, catalogs and errors that echo a value return it as
+sent. Configuration descriptions show only names. Never put credentials here. Use `auth` for secrets. Extra
 headers cannot be combined with `auth.type: "headers"`, collide with an
 auth-owned name, or set HTTP transport/session headers
 (`Accept`, `Cookie`, `Host`, `Content-*`, hop-by-hop headers, `Last-Event-ID`,
@@ -205,7 +218,8 @@ optional and composes with endpoint policy.
 On Node, serve with `listen` from `@zackbart/connecta/node`: it installs the
 owned transport that prevents native fetch or a host-configured dispatcher
 from silently resending a remote MCP write. Without that transport, Node
-refuses remote writes before dispatch. Downstream OAuth token, registration and
+refuses remote writes before dispatch. A connector with its own `fetch` hands
+writes to that function instead, which owns their single attempt. Downstream OAuth token, registration and
 revocation POSTs also require the owned sender. Read calls and OAuth discovery
 GETs keep native fetch. Workers
 use their native fetch with manual redirects; transport failures after

package/documentation/operator-tests.md

@@ -43,6 +43,25 @@ clock, UTC, en-US, locally hosted fonts, disabled animations, hidden carets,
 and a 1280 × 900 viewport. Narrow fixtures use 390 × 844. Every test waits for
 its state and fonts before capturing.
 
+## Loading and recovery probes
+
+`test/operator-contract-server.test.ts` counts physical legacy MCP initialize,
+initialized, SSE GET and tools/list requests: cached admission and summary perform
+none, then one detail per connector performs one session and complete listing.
+The suite also checks default v2 compatibility, the unchanged member projection,
+blocked custom connectors and bounded essential token-slot failure.
+`test/ui.test.ts` checks complete detail schemas and independent sibling scope cleanup.
+
+`test/oauth-stored-observation.test.ts` covers absent, disconnected, tokenless,
+sealed/unreadable and issuer-mismatched grants, owner isolation, both built-in
+connector paths and custom connectors. Storage spies require zero auth mutations,
+including migration and resealing. `test/operator-store.test.ts` counts scoped
+refresh/focus/mutation/poll requests, coalescing and bounded retries, and verifies
+stale admission blocks privileged reads, connection writes and token actions while
+retaining the snapshot. Late reads, role/identity changes and concurrent polls
+exercise publication fences. Browser recovery and flow suites use real routes to
+check a usable shell with a stalled connector, OAuth return and scoped Refresh.
+
 ## Page and state matrix
 
 Each row runs empty, loading, error, populated, and restricted-viewer fixtures

package/documentation/operator-ui.md

@@ -391,6 +391,21 @@ activity and access-token routes answer 404, and owners are `null`. Every respon
 allowed. One shape serves both roles; a field a role does not receive is
 `null` or empty, never omitted.
 
+The browser uses `GET /ui/api/config?live=cached` for admission. For maintainers,
+this mode performs no downstream status or catalog probes. `live.connectors`
+contains only known observations, or `[]`; absence means unobserved, never healthy
+or failed. The default URL and published v2 type remain unchanged. Members receive
+their existing projection in either mode. Cached metadata reads have a 500 ms
+budget each and the entire metadata build has a five-second budget, below the
+browser's 15-second admission deadline. Essential token-slot failure still returns 503. Optional reads degrade conservatively. No downstream session spans requests.
+
+Cached matrix counts use credential vault metadata or a built-in OAuth stored-auth
+observation in each owner's partition. This boolean observation opens sealed grants
+and checks token presence, disconnect state and issuer binding, without refreshing,
+authorizing, migrating or writing auth. Unreadable grants and custom connectors
+without this capability contribute an unconfirmed count of zero. For example,
+`notes_alice` reporting zero connected people does not prove that nobody connected.
+
 The maintainer view carries:
 
 - `config`, the construction-time `describeConfig()` snapshot, including
@@ -507,6 +522,15 @@ exception: clearing a stored value that cannot be read is accepted although
 `manage` lists only `save` in that state. Public HTML shells and static assets carry no catalog data.
 Access-token management also requires an interactive session.
 
+`GET /ui/connectors/:id` returns the existing auth controls plus an optional typed
+`overlay`, all from the same status/catalog observation. The overlay contains
+complete classified tools with input/output schemas, registration path, catalog
+age, and activity-derived last-call facts under the reader's disclosure policy.
+A failed or timed-out connector releases its own scope; siblings finish independently.
+The browser publishes the detail and overlay atomically. Config observations never
+overwrite a completed detail row. Each connector opens at most one live observation
+per page load; the summary `/ui/data` performs no downstream probes.
+
 `GET /ui/api/config?connector=<id>` narrows the same contract to one connector
 before status and catalog probes. For a maintainer, config, provenance, live
 rows and matrix cells contain only that connector's facts; for a member,
@@ -545,52 +569,39 @@ no duplicate standalone server modules. The shared contract owns the unchanged
 `OperatorPage` union exported from `@zackbart/connecta/ui`. An Access-only shell selects
 Access even when the HTML request has no trusted context; only authenticated
 API responses establish the session. A gated Access session offers Retry.
-Focus, visibility, and timer-driven recovery share one admission-read schedule
-with at least two seconds between passive attempts. An admission read takes
-the contract first and, for a maintainer, then `/ui/data` and the connector
-details, which reuse that contract rather than read it again. An in-flight
-passive attempt coalesces returns until its admission read finishes, so slow
-successful reads can publish. Each admission read shares one 15-second
-deadline, including token acquisition, fetches and response bodies. This is an admission deadline, not a request
-lifetime limit: it releases the recovery guard and exposes Retry without aborting
-the pending read or invalidating its identity/revision fence. A late healthy
-response still publishes if that cycle is current. Passive timers and returns
-coalesce onto the pending cycle, including after its deadline; they never start
-duplicate summary, token, config, detail or body reads. The passive retry schedule
-stays bounded and does not reset its budget on a deadline. Retry remains available
-during recovery configuration loading and supersedes and aborts the old cycle;
-identity changes, navigation and connector-page unmount also cancel it. Navigation
-that cancels pending data schedules a bounded reread for the destination. A scoped OAuth poll publishes only its connector's detail and live row. It does
-not supersede a pending full admission or catalog/auth cycle, release its
-recovery guard, or clear its deadline. That full cycle still publishes other
-connectors as they settle and decides recovery, retaining the newer polled row
-even when its summary was pending or its deadline exposed Retry. Only a newer
-full cycle, mutation, identity change, or sign-out fences older work. Owed
-publication neither spends nor resets the failed-read retry budget and adds no
-timer. Failed reads retry after
-2, 2, 4, and 8 seconds. Refusals preserve the throttle and retry budget. After
-those four automatic retries, a focus return can request one more read after
-the eight-second backoff, without replenishing the automatic budget. Retry
-resets the budget with a 150 ms click debounce. Successful reads and explicit
-identity transitions also reset recovery. Identity changes
-cancel pending retries and fence out responses from the previous identity.
-Queued focus callbacks carry the same identity fence. Explicit sign-out
-suppresses passive reads until an intentional sign-in or a new Clerk session.
-
-Catalog and connector auth details share one revisioned refresh cycle. Each
-completed connector publishes its catalog facts and auth controls together,
-while a slow provider leaves other rows usable.
-Catalog refresh, connector refresh, and mutation follow-up reads update both
-consumers together. A later refresh or mutation invalidates an older cycle's publication fence
-without aborting its read, and a failed contract read clears its old snapshot;
-the next refresh then reads the contract before any connector detail. After an explicit OAuth
-start, visible tabs poll only that connector's read-only catalog and auth facts
-every two seconds for up to 30 seconds. The scoped result replaces only that
-connector's matching live row and auth controls. Success, a failed read or status,
-disconnect, navigation away from the connector, unmount, or identity reset ends
-polling and aborts its in-flight reads. The deadline also aborts a stalled read.
-A later focus return can request another status read. Recovery never starts OAuth
-or replays a mutation.
+Focus, visibility and timer-driven admission recovery share a schedule with at
+least two seconds between passive attempts. Admission reads the cached contract
+first, then `/ui/data` for maintainers. Token acquisition, fetches and response
+bodies share a 15-second deadline. Once admission succeeds, connector details
+have independent deadlines and cannot withdraw deployment-wide admission.
+
+A passive admission deadline retains the last maintainer snapshot with a stale
+notice. Admission validity is separate from snapshot presence: privileged reads,
+connection writes and token actions require valid admission. A scoped connector
+result cannot restore it. Queued reads withheld locally after admission expires
+are discarded without clearing the snapshot or showing sign-in. A late full
+admission may publish behind its original identity and revision fences. HTTP
+401/403 refusal, identity change and sign-out clear immediately;
+member failures still remove their actionable projection. Retry aborts the old
+admission cycle; navigation and identity transitions cancel its reads. Passive
+attempts coalesce even after the deadline. Automatic admission retries remain
+bounded at 2, 2, 4 and 8 seconds; a later focus return can try again after backoff.
+
+Connector Refresh, focus recovery and mutation follow-ups read only affected
+connectors. Focus probes unhealthy rows, never healthy siblings. All detail reads
+share a four-request limit and coalesce per connector. Failures retry only their
+connector with the same bounded backoff; recovery never replays a mutation.
+Mutations cancel affected reads and advance their publication fence both at
+dispatch and on settlement, including failure. Follow-ups require an observation
+started after settlement, so a Refresh or retry started during the write cannot
+supply its result. Newer publications also fence older results per connector,
+while identity and full refresh revisions fence the complete view. An explicit
+OAuth start polls only that connector every two seconds for up to 30 seconds.
+Concurrent authorizations retain independent cancellation and publication. Success,
+failed reads, disconnect, navigation, unmount and identity reset stop the matching
+poll. Recovery never starts authorization. A scoped result cannot confirm identity,
+role, token slots or any other deployment-wide admission fact.
+
 Unreadable credential metadata uses `configured: null`, including named fields,
 and renders as unavailable with a retry prompt. It does not claim that the slot
 is empty. Overview, Endpoints, Connectors, connector

package/examples/worker/README.md

@@ -547,7 +547,11 @@ LOADER: Cloudflare.WorkerLoader(),
 `@zackbart/connecta/worker`. The adapter constructs the upstream
 `DynamicWorkerExecutor` with only the loader and a deadline, and disposes each
 run's loader and RPC handles when its lease ends, even if the guest has not
-settled. It serves the six-tool surface. Do not add `bindings`, `modules`, or
+settled. It serves the six-tool surface. Its admission pool is per isolate:
+two runs, eight queued for up to 60 seconds, then a retryable
+`executor_overloaded`. Pass `admission` to `workerExecutor()` to change it; see
+[code mode](../../documentation/code-mode.md#deploy-time-capability). Do not
+add `bindings`, `modules`, or
 `globalOutbound`; they grant guest code ambient authority. A copied deployment
 owns the package install — see
 [copied into its own repository](#copied-into-its-own-repository).

package/guides/connecting-agents.md

@@ -146,6 +146,12 @@ owner whose account the agent will use. See
 [Workspace pool owners](../documentation/auth.md#pool-owners-for-google-workspace)
 before connecting an agent to someone's account.
 
+A connection to the organization's own service can instead act as whoever
+signed in, by forwarding that person's identity. Agents cannot use such a
+connection unless the operator also allows them, and then they appear to the
+service as themselves, never as a person. See
+[forwarding the admitted principal](../documentation/auth.md#forwarding-the-admitted-principal).
+
 An assistant serving several people must use a pool appropriate for everyone
 in the conversation. Its app chooses that pool; the model does not choose
 its own access level. Keep private results out of broader conversations.

package/guides/safety-and-trust.md

@@ -141,6 +141,7 @@ own availability, project/environment choices, and revocation details.
 | Enable the credential vault    | Encrypt stored credentials and OAuth tokens before connecting accounts.                              |
 | Pool membership and tools      | Each member can use every action that pool grants.                                                   |
 | Service permissions            | A shared credential uses the same account for every member.                                          |
+| Forwarded identity             | A service that trusts a forwarded person must accept it only from this deployment.                   |
 | Approval policy                | A writable pool can run unattended; the Eve helper defaults to that behavior.                        |
 | Tool classification            | Labels must match the service's actual behavior.                                                     |
 | Deployment and secret handling | Enable the credential vault; protect storage, encryption keys, backups, ingress, and the agent host. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.36.2",
+  "version": "0.37.0",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of six meta-tools.",

package/templates/node/package.json

@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@clerk/backend": "^3.12.0",
-    "@zackbart/connecta": "0.36.2",
+    "@zackbart/connecta": "0.37.0",
     "quickjs-emscripten": "0.32.0",
     "undici": "6.29.1"
   },