@zackbart/connecta 0.24.2 → 0.24.4

package/AGENTS.md

@@ -32,8 +32,8 @@ Cloudflare Workers.
 `check:operator-ui` → `check:lint` → `check:unused` → `typecheck` → `test`
 (both vitest projects) → `build` → `check:examples`. It is also the `prepack`
 hook. `npm run release:check` adds `check:security` and `check:package` and is
-what CI runs on publish; use it when touching packaging, dependencies, or
-exports.
+what CI runs on every pull request, on `main`, and again on publish; use it
+when touching packaging, dependencies, or exports.
 
 ## The map
 
@@ -41,13 +41,13 @@ exports.
   decisions table, and the invariants every change must preserve. Check it
   before building something new; "we already decided not to" is a real answer
   there, and its removed/provisional verdicts override anything staler.
-- [`documentation/`](./documentation/) — per-subsystem guides for agents
-  working on the repo. All of them are written now
-  ([#348](https://github.com/zackbart/connecta/issues/348)); the retired manual
-  (`docs/<name>.md`) survives only in git history, which is worth mining for
-  rationale a rewrite dropped and worth nothing where it disagrees with
-  `ethos.md`. Start with `architecture.md`, then the guide for the subsystem
-  you are changing.
+- [`documentation/`](./documentation/) — four guides for agents working on the
+  repo: `architecture.md`, `meta-tools.md`, `code-mode.md`, and `auth.md`.
+  Everything else — connectors, providers, admission, storage, the operator
+  UI, operations — is documented where it lives, in the source and its tests.
+  The guides that once covered those survive only in git history, which is
+  worth mining for rationale and worth nothing where it disagrees with
+  `ethos.md` or the code. Start with `architecture.md`.
 - [`README.md`](./README.md) — the human-facing overview.
 - [`templates/node/`](./templates/node/) — the one standalone Node deployment
   shape copied by `connecta init`, Docker-ready rather than Docker-only. Keep
@@ -56,13 +56,14 @@ exports.
   diff away from one of them is the shape
   [#344](https://github.com/zackbart/connecta/issues/344) deleted.
 
-**Read `ethos.md` and the subsystem's guide before changing a subsystem.**
+**Read `ethos.md` before changing a subsystem, and its guide when it has one.**
 
 ## Deployment setup
 
 `connecta init [directory]` is the golden path. It copies `templates/node/`,
 pins the generated deployment to the CLI package's exact version, restores the
-template `.gitignore`, and refuses to merge into an existing path.
+template `.gitignore` and the `CLAUDE.md` symlink, and refuses to merge into an
+existing path.
 `connecta doctor` verifies a running deployment's health, executor, and exact
 seven-tool surface. The template carries its own `Dockerfile` and
 `docker-compose.yml`, so the generated project is the container: setup changes
@@ -96,8 +97,9 @@ Two boundaries CI enforces that are not obvious from reading a file:
   forbidden is a platform-bound adapter becoming importable from the package,
   not a file appearing in the artifact. `@clerk/backend` and
   `quickjs-emscripten` are optional peers behind the `./auth/clerk` and
-  `./quickjs` subpaths and must never become dependencies or install with
-  core. Enforced by `test/package-surface.test.ts` and
+  `./quickjs` subpaths, and `@cloudflare/codemode` is the third, peered
+  without a subpath because a Worker deployment imports it directly. None may
+  become a dependency or install with core. Enforced by `test/package-surface.test.ts` and
   `scripts/check-package.mjs`. Anything heavyweight or platform-bound gets a
   subpath and an optional peer.
 
@@ -108,10 +110,7 @@ Every `*.test.ts` belongs to exactly one explicit list: runtime-portable suites
 in `WORKERS_SUITES`, Node-bound suites in `NODE_ONLY_SUITES` with a reason. The
 `node` project runs both lists; the `workers` project re-runs the portable list
 inside workerd. `test/suite-partition.test.ts` walks the directory and fails on
-an unclassified, double-classified, stale, or reasonless entry. New behavior
-also gets a row in the test map in `documentation/operations.md`, which
-classifies every suite — one missing from it is either new and undocumented or
-dead, and neither is a state to leave the repository in.
+an unclassified, double-classified, stale, or reasonless entry.
 
 ## Conventions
 
@@ -132,9 +131,8 @@ dead, and neither is a state to leave the repository in.
   documentation and OpenAPI contracts and never reads a provider credential.
   Remote MCP schemas remain owned by the live `tools/list` response rather than
   a vendored copy. Findings are read by a human and become GitHub issues;
-  nothing files itself.
-  See
-  [`documentation/provider-conventions.md`](./documentation/provider-conventions.md#the-maintainer-run-drift-check).
+  nothing files itself. `scripts/drift-check.mjs` is the reference for what
+  each flag covers.
 - **Releases.** `npm run release:check`, tag `v<version>` matching
   `package.json` exactly (the publish workflow verifies this and fails
   otherwise), and publishing fires on GitHub **Release publication**, not on the

package/CHANGELOG.md

@@ -2,6 +2,205 @@
 
 All notable changes to this package are documented here.
 
+## 0.24.4 — 2026-09-17
+
+The operator UI is the release. Its connections page is now a summary line and
+one row per connector instead of a wall of expanded cards, and the stylesheet
+behind it resolves through design tokens a deployment can set with the new
+`branding.theme`. Nothing a deployment configures today changes meaning, no
+storage format moved, and the page shows exactly what it showed before under
+the same gates — an operator who has the page bookmarked will find it reads
+differently, and that is the whole of the upgrade. The documentation cut to
+four guides lands here too, along with one execution-path fix.
+
+### Added
+
+- **`branding.theme`.** Five tokens — `accent`, `radius`, `fontFamily`,
+  `monoFamily`, and `colorScheme` — set on `operatorUi({ branding })`. Every
+  other color on the operator page is mixed from those, so setting one accent
+  themes the page rather than leaving half of it on the defaults. Light and
+  dark are the same tokens and follow the operator's OS setting unless
+  `colorScheme` pins one. Each token is gated the way the branding URLs already
+  were: a hex color, a CSS length, a plain font-family list, one of
+  `system`/`light`/`dark`. A rejected value takes the default and gets named in
+  a startup warning. The gates are narrow because these values land in a
+  `:root` block on the page, where anything unvalidated would be CSS injection.
+
+### Changed
+
+- **The operator UI reads as a dashboard.** The connections page opens with one
+  summary line — connected, anything needing authorization, anything
+  unavailable, tools available — and then one row per connector: status dot,
+  name, auth scope, tool count, state. What used to be stacked in every card at
+  once (the description, the permission line, OAuth actions, the credential
+  panel, diagnostics, drift, and the tool list) is now behind a row an operator
+  expands, so a deployment with twenty connectors is a screen instead of a
+  scroll. Nothing about what the page may show or do changed: same payload,
+  same gates, and the drift panel still refuses to render a tool name or a
+  schema (#554).
+- **The documentation is four guides.** `documentation/` now ships
+  `architecture.md`, `meta-tools.md`, `code-mode.md`, and `auth.md`. The
+  operations, upgrading, connector, provider, admission, storage, and operator
+  UI guides are removed; the rationale source comments used to defer to them
+  for now lives in those comments, and the provider conventions H1–H14 and
+  P1–P13 are defined in `test/provider-conventions.test.ts`. Each release's
+  opening paragraph here is the upgrade guidance. `records/` and `eval/` are
+  removed with the `load:admission` script and the CI job that served them. The
+  template and Worker example keep their `AGENTS.md`, which now points at this
+  changelog for upgrades (#552, #553).
+
+### Fixed
+
+- **`get_result` paging cost.** A stashed result is stored as base64 chunks
+  under one key each — 48 KiB of text per chunk, wider for a result over
+  roughly 1.5 MB so the key and write count stays bounded — and a page reads
+  and decodes only the chunks it covers. Paging a large result no longer reads
+  the whole stash — let alone re-encodes it — once per page, so cost tracks the
+  page rather than the total. Offsets, `nextOffset`, `totalBytes`, and
+  character-boundary alignment are unchanged, and entries stashed in the
+  previous formats stay readable for the rest of their 15-minute TTL (#540).
+
+## 0.24.3 — 2026-09-16
+
+A bug-fix release from a full audit of the execution path, invocation, catalog
+rendering, downstream OAuth, and the route table, plus the one MCP 2026-07-28
+requirement the previous inventory had missed. Two changes can be felt by a
+deployment: `/mcp` now validates the browser `Origin` header, so a browser MCP
+client hosted on an origin other than `publicUrl` or loopback needs
+`allowedOrigins`; and the overload and shutdown JSON-RPC error codes moved
+from `-32001`/`-32002` to `-31001`/`-31002`. Everything else is a fix a
+deployment can take without action. No storage format changed, but
+`fileStorage` now refuses a second process on the same state file, which a
+deployment sharing one file between two processes was never safe doing.
+
+### Added
+
+- **`allowedOrigins`.** `/mcp` and every `/mcp/<pool>` path refuse a
+  disallowed `Origin` with a fixed 403 before redirects, admission, auth, or
+  preflight, as the Streamable HTTP transport requires against DNS rebinding.
+  The default admits the `publicUrl` origin and HTTP(S) loopback at any port;
+  a list replaces the default; `"*"` keeps unrestricted CORS. Clients that
+  send no `Origin` are unaffected. Allowed preflight now returns 204 without
+  admission or auth and echoes valid requested `mcp-param-*` header names.
+- **Host-owned refresh recovery.** A valid token response is a consumed
+  refresh token. When the request that owned a refresh is cancelled,
+  redirected to authorization, or invalidated before the SDK saves the
+  response, the coordinator persists the rotation itself, holds contenders
+  behind the pending-mutation marker until that write lands, and hands them
+  the saved rotation. A retired refresh token is never redeemed twice, and two
+  deterministic waves of eight overlapping scopes pin one grant per wave
+  (#526).
+- Downstream JSON-RPC `-32602` refusals map to `invalid_args`, and 4xx
+  responses with a JSON message keep that message, bounded, without inferring
+  retryability from prose. 429 stays `rate_limited` and 408 becomes `timeout`.
+- `Retry-After` accepts the HTTP-date form as well as delta-seconds.
+- Personal connectors admit calls through their principal registry's own
+  budget instead of sharing one root budget; shutdown closes both, and
+  eviction never discards a live budget.
+- `records/mcp-2026-07-28.md` gains rows for Origin validation, deterministic
+  `tools/list` order, the bearer challenge, SEP-2243 parameter headers, and
+  trace propagation, and corrects the stale extensions row.
+- **Bounded `get_result` stash.** `results.maxStashBytes` (default 8 MiB)
+  and `results.maxStashEntries` (default 64) bound the paging stash per
+  runtime, with accounting that reserves capacity before concurrent writes
+  finish and reclaims expired entries before reuse. A refused stash keeps the
+  call successful with its preview and the paging-unavailable notice.
+- **Byte-range paging.** Stashed results are stored as a byte-addressable
+  envelope, so `get_result` decodes only the requested page instead of
+  re-encoding the whole result on every call. Entries stashed before the
+  upgrade still page until their TTL expires.
+- **Identity-partitioned results.** The stash partition derives from any
+  authenticated subject or principal, no longer only from providers that
+  declare `activityActorNamespace`. Open deployments share one partition.
+- **Sanitized `unavailable` detail.** Unreachable downstreams may carry
+  `details.host` (origin only) and `details.code` (a closed allowlist of
+  network errnos, or `timeout`) so an outage is distinguishable from a typo
+  without leaking a path, query, or credential. Activity stays payload-free.
+- **`fileStorage` writer lock.** A second instance or process opening the
+  same state file fails at construction naming the holder. The lock is
+  heartbeat-based, so a container restart that reuses a pid cannot wedge a
+  deployment, and each write uses a unique temp file. The returned store now
+  has `close()`.
+- **Logs survive every executor failure.** QuickJS streams console entries
+  to the parent, so a program that is cancelled, killed at the deadline,
+  crashed, or lost to an IPC failure still returns what it printed.
+
+### Changed
+
+- `/health` no longer names connectors: drift reports are keyed by a truncated
+  SHA-256 of the connector id and downstream admission is summed without ids.
+  `connecta doctor` keeps its stale-allowlist signal.
+- Overload and shutdown JSON-RPC codes are `-31001` and `-31002`, outside the
+  reserved range, per the specification's allocation policy.
+- `connecta.search` and `connecta.describe` spend the same host-call budget as
+  `connecta.call`; only `connecta.emit` is exempt (L4, M7).
+- One per-call deadline now covers catalog resolution, admission, and the
+  connector call, so a hung connector fails with a catchable `timeout` instead
+  of consuming the whole execution wall clock.
+- Compact describe caps each shape at 8,192 UTF-8 bytes and sets
+  `inputSchemaTruncated` / `outputSchemaTruncated`; use `format: "json"` for
+  the exact schema.
+- Top-level discovery measures the complete tool result, both copies and JSON
+  escaping, against the 256,000-byte ceiling.
+- Downstream `isError` text is bounded at 512 UTF-8 bytes, and error framing
+  fits the call's result cap in both result modes.
+- Open deployments warn whenever any connector is configured, since `api()`
+  headers can carry secrets without declaring credential hooks.
+
+### Fixed
+
+- **A long downstream error could leak the sandbox's per-run secret to guest
+  code and let a program forge a typed failure.** The QuickJS bridge sliced a
+  rejected host call at 4,000 characters, which clipped the authenticated
+  failure frame mid-JSON. Details are bounded before framing, the bridge
+  refuses an oversized frame whole, the prelude hides a malformed frame, and
+  the raw transport lives in a private closure so guest code cannot swap
+  `Error` or reach the bridge.
+- **A completed destructive call was reported as a retryable failure when the
+  `get_result` stash write failed.** The truncated preview is returned with a
+  paging-unavailable notice, activity records success, and
+  `result_processing_failed` is never retryable.
+- **The OAuth refresh gate wedged permanently** when a token fetch succeeded
+  but the SDK's save never ran, answering 503 to every later refresh in the
+  isolate until a forced reauthorization.
+- **Compact schema rendering went quartic on `allOf`-of-`$ref` schemas.** A
+  3.5 KB downstream schema took over four seconds of synchronous CPU, and the
+  describe path produced a 1.9 MB string from 1.8 KB. Rendering now spends a
+  shared 2,000-visit budget with memoized `$ref` expansion.
+- `call_tool` in MCP result mode returned `{"content":[]}` for a downstream
+  result carrying only `structuredContent`; a text block is now synthesized,
+  and a `null` structured value survives unwrapping.
+- In-program `connecta.search` returned `offset: null` and an empty page for a
+  non-numeric offset, and threw a raw `TypeError` for a non-string query; both
+  are `invalid_args`.
+- Caller-authored text in `get_result`, `authorize_connector`, `skills`, and
+  `search_tools` refusals is bounded; a `connector` over 512 bytes is
+  `invalid_args`. A failed stash read is a typed `unavailable`.
+- Legacy `mcp-session-id` DELETE now runs on credential rotation, generation
+  change, disconnect, and abandoned connects, not only on scope close.
+- Pool names outside `[a-z0-9_-]` fell through to a generic 404 without CORS
+  or authentication; every `/mcp/` suffix now reaches the identical pool 404
+  after auth.
+- The absent-grant warning set was unbounded and keyed by caller-derivable
+  text; it is capped at 1,024 entries.
+- `requiredInputKeys` could name keys the schema did not declare.
+- Validation error detail embedded whole enums; drift digests recursed without
+  a depth bound; refresh token responses were read without a byte ceiling;
+  credential revision races could loop without bound.
+- Containment matching for escaped failures ignores messages under eight
+  characters, and a QuickJS host-result reply that cannot be serialized settles
+  the call instead of hanging until the wall deadline.
+- Every `connecta.call` attempt spends one host call on entry, so unknown
+  addresses cannot loop for free; the escaped-failure list keeps the most
+  recent 64; an empty terminal error string is a failure, not a success.
+- The compact renderer renders `prefixItems` as a tuple, marks
+  `dependentSchemas` and `if`/`then`/`else` shapes conditional with the
+  truncation flag, and resolves `$dynamicRef` like `$ref`.
+- The guarded transport's no-body-stream path enforces the byte ceiling on
+  `text()` and `json()`.
+- The pool-name timing oracle is accepted and documented; `authorize_connector`
+  honoring tool-level grants is documented and pinned.
+
 ## 0.24.2 — 2026-09-16
 
 `connectorAccess` can now grant individual tools, and a deployment can declare
@@ -22,7 +221,7 @@ returns `"all"` or connector ids and declares no pools.
 - **Tool-level grants in `identity.connectorAccess`.** Entries may be a
   connector id (every tool) or an exact `connector.tool` address (that tool
   only); grants are additive. The scoped registry view filters below the
-  catalog service, so `search_tools`, `describe_tools`, `call_tool`,
+  catalog service, so `search_tools`, `call_tool`,
   `call_destructive_tool`, a program's `connecta.search` and `connecta.call`,
   and the connection UI all see the same list, and an ungranted tool fails as
   `unknown_tool` exactly like an absent one. There is no wildcard: a remote
@@ -32,6 +231,11 @@ returns `"all"` or connector ids and declares no pools.
 
 ## 0.24.1 — 2026-09-08
 
+A small additive release for deployments whose providers run long: two
+optional `execute.*` settings and a log line for failed calls. Nothing breaks
+and nothing needs migrating; a deployment that sets neither option behaves as
+it did on 0.24.0.
+
 ### Added
 
 - `execute.maxHostCalls` and `execute.hostCallTimeoutMs` configure the

package/README.md

@@ -95,9 +95,7 @@ Cloudflare Access supplies Worker identity; Node can use Clerk or the optional
 configured bearer adapter. Connecta owns no accounts or groups and issues no
 client access tokens. Shared-credential administration and personal connection
 setup require separate explicit permissions, both denied by default. See
-[inbound auth](./documentation/auth.md#principals-visibility-and-operators),
-[shared and personal auth](./documentation/storage-and-credentials.md#shared-and-personal-auth),
-and the [module migration guide](./documentation/upgrading.md#0240-optional-modules).
+[inbound auth](./documentation/auth.md#principals-visibility-and-operators).
 
 Connecta is not a platform, a marketplace, a policy engine, or a multi-tenant
 service. Those are decisions, and the [ethos](./ethos.md) records each one
@@ -107,9 +105,10 @@ and why.
 
 Setup is written for an agent. Point yours at [`AGENTS.md`](./AGENTS.md) and
 ask it to set up a Connecta deployment; the
-[documentation](./documentation/) covers every subsystem if you want to go
-deeper, and [upgrading](./documentation/upgrading.md) an existing deployment
-is its own runbook.
+[documentation](./documentation/) covers the architecture, the seven tools,
+code mode, and inbound auth if you want to go deeper. When upgrading an
+existing deployment, each [changelog](./CHANGELOG.md) release opens with what
+breaks and what a deployment can ignore.
 
 ## Status
 

package/dist/auth/bearer.js

@@ -39,6 +39,8 @@ export function bearerToken(secret, options = {}) {
                     status: 401,
                     headers: {
                         "Content-Type": "application/json",
+                        // A configured secret has no OAuth metadata or issuer to
+                        // advertise; interactive adapters own resource discovery.
                         "WWW-Authenticate": "Bearer",
                     },
                 }),

package/dist/auth/downstream-oauth.d.ts

@@ -13,6 +13,16 @@ interface OAuthRefreshFlight {
     release: (outcome: OAuthRefreshFlightOutcome) => void;
     stopObservingOwnerAbort: () => void;
     mutationId: object;
+    writing: boolean;
+    /**
+     * Set once the token endpoint answered with valid tokens: the authorization
+     * server has consumed the rotating refresh token, so if the SDK's own
+     * saveTokens never arrives (owner cancelled, redirected, or invalidated),
+     * `fail` persists this copy itself rather than stranding the marker or
+     * letting a contender redeem the retired token.
+     */
+    acceptedTokens?: OAuthTokens;
+    persist?: (tokens: OAuthTokens) => Promise<void>;
 }
 /**
  * Share one rotating-token redemption within one connector runtime and OAuth
@@ -41,6 +51,8 @@ export declare class OAuthRefreshCoordinator {
     /** @internal Opaque basis for issuer-aware provider token reads. */
     successfulRefreshIdentity(generation: string): object | undefined;
     coordinatedFetch(provider: KvOAuthProvider, baseFetch: FetchLike, requestSignal?: AbortSignal): FetchLike;
+    /** Start storage only while this owner still holds its exact flight. */
+    beginMutation(generation: string, flight: OAuthRefreshFlight): boolean;
     /** Publish one exact owner's successful save without disturbing a newer try. */
     succeedMutation(generation: string, flight: OAuthRefreshFlight): void;
     /** Give joined callers a fetch/flow failure, without rejecting the gate. */
@@ -92,7 +104,6 @@ export declare class KvOAuthProvider implements OAuthClientProvider {
     flowGeneration(): Promise<string>;
     /** @internal Record the refresh attempt this provider owns. */
     captureRefreshFlight(generation: string, flight: OAuthRefreshFlight): void;
-    private succeedRefreshFlight;
     private failRefreshFlight;
     /** True when another request saved a refresh result after this flow's read. */
     refreshBasisChanged(current: OAuthTokens, generation: string): boolean;

package/dist/auth/downstream-oauth.js

@@ -63,18 +63,66 @@ function sdkAcceptsOAuthTokens(value) {
     }
     return true;
 }
-async function refreshResponseFailure(response) {
+const MAX_REFRESH_RESPONSE_BYTES = 65_536;
+class OversizedRefreshResponse extends Error {
+    constructor() {
+        super(`OAuth refresh response exceeded ${MAX_REFRESH_RESPONSE_BYTES} bytes.`);
+    }
+}
+async function readRefreshResponse(response) {
+    if (Number(response.headers.get("content-length")) > MAX_REFRESH_RESPONSE_BYTES) {
+        void response.body?.cancel().catch(() => { });
+        throw new OversizedRefreshResponse();
+    }
+    const reader = response.clone().body?.getReader();
+    if (!reader)
+        return undefined;
+    const decoder = new TextDecoder();
+    let size = 0;
+    let text = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_REFRESH_RESPONSE_BYTES) {
+                // A cloned body's cancellation can await its sibling. Cancel both,
+                // without making the refusal wait for the provider to finish sending.
+                void reader.cancel().catch(() => { });
+                void response.body?.cancel().catch(() => { });
+                throw new OversizedRefreshResponse();
+            }
+            text += decoder.decode(value, { stream: true });
+        }
+        return JSON.parse(text + decoder.decode());
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * Classify the token endpoint's answer once, on a clone, and keep the parsed
+ * tokens: a valid response has already consumed the rotating refresh token, so
+ * the host persists it (`coordinatedFetch`) rather than trusting the SDK's
+ * later `saveTokens` to arrive on a request that may already be cancelled.
+ */
+async function refreshResponseOutcome(response) {
     if (!response.ok) {
-        return new Error(`OAuth refresh failed with HTTP ${response.status}.`);
+        return { failure: new Error(`OAuth refresh failed with HTTP ${response.status}.`) };
     }
+    let parsed;
     try {
-        return sdkAcceptsOAuthTokens(await response.clone().json())
-            ? undefined
-            : new Error("OAuth refresh response did not match the token schema.");
+        parsed = await readRefreshResponse(response);
     }
-    catch {
-        return new Error("OAuth refresh response did not contain JSON tokens.");
+    catch (error) {
+        if (error instanceof OversizedRefreshResponse)
+            throw error;
+        return { failure: new Error("OAuth refresh response did not contain JSON tokens.") };
     }
+    return sdkAcceptsOAuthTokens(parsed)
+        ? { tokens: parsed }
+        : { failure: new Error("OAuth refresh response did not match the token schema.") };
 }
 function refreshMutationPendingResponse() {
     return Response.json({
@@ -189,7 +237,9 @@ export class OAuthRefreshCoordinator {
             const requestedRefreshToken = init?.body instanceof URLSearchParams
                 ? init.body.get("refresh_token")
                 : new URLSearchParams(String(init?.body ?? "")).get("refresh_token");
-            while (true) {
+            for (let attempt = 0; attempt < 64; attempt++) {
+                if (requestSignal?.aborted)
+                    throw aborted(requestSignal);
                 const revisionBeforeReads = this.stateRevision;
                 const activeGeneration = await provider.generation();
                 this.observeAuthoritativeGeneration(activeGeneration);
@@ -258,6 +308,8 @@ export class OAuthRefreshCoordinator {
                     release: (outcome) => release(outcome),
                     stopObservingOwnerAbort: () => { },
                     mutationId: {},
+                    writing: false,
+                    persist: (tokens) => provider.saveTokens(tokens),
                 };
                 this.flights.set(generation, flight);
                 this.advanceStateRevision();
@@ -280,18 +332,35 @@ export class OAuthRefreshCoordinator {
                 }
                 try {
                     const response = await baseFetch(input, requestSignal ? { ...init, signal: requestSignal } : init);
-                    // These responses never reach a successful saveTokens callback. Give
+                    // Failed responses never reach a successful saveTokens callback. Give
                     // current waiters a bounded failure now while leaving the owner's
                     // response untouched for the SDK to parse and classify itself.
-                    const failure = await refreshResponseFailure(response);
-                    if (failure) {
-                        this.fail(generation, flight, failure);
+                    const outcome = await refreshResponseOutcome(response);
+                    if (outcome.failure) {
+                        this.fail(generation, flight, outcome.failure);
+                        return response;
                     }
-                    else if (requestSignal?.aborted ||
-                        !this.markMutationPending(generation, flight)) {
-                        throw requestSignal?.aborted
-                            ? aborted(requestSignal)
-                            : new Error("OAuth refresh ended before tokens could be saved.");
+                    // A valid response means the authorization server has consumed the
+                    // rotating refresh token. The SDK's saveTokens normally persists it;
+                    // keep this copy so `fail` can persist it instead if that callback
+                    // never comes (the SDK merges the old refresh token the same way).
+                    const rotatedRefreshToken = outcome.tokens.refresh_token ?? currentTokens?.refresh_token;
+                    flight.acceptedTokens = {
+                        ...outcome.tokens,
+                        ...(rotatedRefreshToken !== undefined
+                            ? { refresh_token: rotatedRefreshToken }
+                            : {}),
+                    };
+                    if (!this.markMutationPending(generation, flight)) {
+                        // Already settled (the owner was cancelled first). Still write the
+                        // rotation: losing it would leave a dead credential.
+                        void flight.persist?.(flight.acceptedTokens).catch(() => { });
+                        throw new Error("OAuth refresh ended before tokens could be saved.");
+                    }
+                    if (requestSignal?.aborted) {
+                        // Same recovery as an abort landing later: `fail` persists.
+                        this.fail(generation, flight, aborted(requestSignal));
+                        throw aborted(requestSignal);
                     }
                     return response;
                 }
@@ -300,8 +369,16 @@ export class OAuthRefreshCoordinator {
                     throw error;
                 }
             }
+            return refreshMutationPendingResponse();
         };
     }
+    /** Start storage only while this owner still holds its exact flight. */
+    beginMutation(generation, flight) {
+        if (this.flights.get(generation) !== flight)
+            return false;
+        flight.writing = true;
+        return true;
+    }
     /** Publish one exact owner's successful save without disturbing a newer try. */
     succeedMutation(generation, flight) {
         if (this.finishMutation(generation, flight)) {
@@ -312,6 +389,37 @@ export class OAuthRefreshCoordinator {
     }
     /** Give joined callers a fetch/flow failure, without rejecting the gate. */
     fail(generation, flight, error) {
+        // Only saveTokens owns a live credential write. If it has started, its
+        // success/failure callback clears the marker even after owner cancellation.
+        if (flight.writing) {
+            this.settle(generation, flight, { status: "failed", error });
+            return;
+        }
+        // The token endpoint already answered with valid tokens but the SDK will
+        // not save them (the owner was cancelled, redirected, or invalidated).
+        // The old refresh token is spent, so the host persists the rotation
+        // itself and keeps contenders behind the marker until it lands. Joined
+        // callers then receive the saved rotation, never a retired token to
+        // redeem again. saveTokens' own bookkeeping settles the flight when the
+        // provider still holds it; otherwise settle here once the write ends.
+        const tokens = flight.acceptedTokens;
+        if (tokens !== undefined &&
+            flight.persist !== undefined &&
+            this.pendingMutations.get(generation) === flight.mutationId) {
+            flight.writing = true;
+            void flight.persist(tokens).then(() => {
+                if (this.finishMutation(generation, flight)) {
+                    this.settle(generation, flight, { status: "refreshed" });
+                }
+            }, (writeError) => {
+                if (this.finishMutation(generation, flight)) {
+                    this.settle(generation, flight, { status: "failed", error: writeError });
+                }
+            });
+            return;
+        }
+        // A response alone is not a write and must never strand the generation.
+        this.finishMutation(generation, flight);
         this.settle(generation, flight, { status: "failed", error });
     }
     /** Finish an exact failed credential write, then publish its failure. */
@@ -417,23 +525,11 @@ export class KvOAuthProvider {
     captureRefreshFlight(generation, flight) {
         this.refreshFlight = { generation, flight };
     }
-    succeedRefreshFlight() {
-        const owned = this.refreshFlight;
-        this.refreshFlight = undefined;
-        if (owned) {
-            this.refreshCoordinator?.succeedMutation(owned.generation, owned.flight);
-        }
-    }
-    failRefreshFlight(error, mutationFinished = false) {
+    failRefreshFlight(error) {
         const owned = this.refreshFlight;
         this.refreshFlight = undefined;
         if (owned) {
-            if (mutationFinished) {
-                this.refreshCoordinator?.failMutation(owned.generation, owned.flight, error);
-            }
-            else {
-                this.refreshCoordinator?.fail(owned.generation, owned.flight, error);
-            }
+            this.refreshCoordinator?.fail(owned.generation, owned.flight, error);
         }
     }
     /** True when another request saved a refresh result after this flow's read. */
@@ -650,14 +746,30 @@ export class KvOAuthProvider {
         return tokens;
     }
     async saveTokens(tokens, ctx) {
+        // A retired flight (the owner was cancelled or superseded after the
+        // token response) still writes: the authorization server has already
+        // consumed the old refresh token, so dropping the rotated one would leave a
+        // dead credential. writeValue itself refuses when the generation moved.
+        // Only the coordinator bookkeeping belongs to the exact live flight.
+        const owned = this.refreshFlight;
+        const coordinated = owned !== undefined &&
+            this.refreshCoordinator?.beginMutation(owned.generation, owned.flight) === true;
         try {
             await this.writeValue("oauth:tokens", tokens, (value) => JSON.stringify(value), ctx?.issuer);
-            this.succeedRefreshFlight();
+            if (coordinated)
+                this.refreshCoordinator?.succeedMutation(owned.generation, owned.flight);
         }
         catch (error) {
-            this.failRefreshFlight(error, true);
+            if (coordinated)
+                this.refreshCoordinator?.failMutation(owned.generation, owned.flight, error);
             throw error;
         }
+        finally {
+            // The write owns this identity even if an SDK failure callback has
+            // already detached the provider's flight while storage was pending.
+            if (this.refreshFlight === owned)
+                this.refreshFlight = undefined;
+        }
     }
     /**
      * OAuth `state`. The SDK calls this (when present) and appends the value to
@@ -701,9 +813,9 @@ export class KvOAuthProvider {
         return stored.value;
     }
     async redirectToAuthorization(authorizationUrl) {
-        if (!this.allowAuthorization)
-            throw new UnauthorizedError("Authorization required. Use authorize_connector or Connect to start consent.");
         try {
+            if (!this.allowAuthorization)
+                throw new UnauthorizedError("Authorization required. Use authorize_connector or Connect to start consent.");
             await this.writeValue("oauth:pending", authorizationUrl.toString(), (raw) => raw);
             this.failRefreshFlight(new Error("OAuth refresh required reauthorization before tokens were saved."));
         }