@cosmoops/connect-sdk 0.33.0 → 0.34.1

package/dist/esm/server/handler.js

@@ -55,6 +55,99 @@ function sameState(a, b) {
         diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
     return diff === 0;
 }
+/**
+ * How many sign-ins one browser may have in flight at once.
+ *
+ * The state cookie used to hold a *single* `state:next` pair, so a second
+ * `GET /signin` overwrote the first. Two tabs - or one abandoned attempt and
+ * one fresh one - and the older round trip came back to a cookie naming a
+ * state it had never heard of: `connect_error=state_mismatch`, which the host
+ * app's own session gate answers by silently firing another `/signin`, putting
+ * the visitor back on the sign-in screen with nothing on the page saying why.
+ *
+ * Five is far past what anyone opens by hand and still a cookie nobody
+ * notices - each entry is a 43-character state plus a short path. Entries are
+ * newest-first and the oldest fall off the end, so the tab a visitor is
+ * actually looking at is the last one to be forgotten.
+ *
+ * It does not weaken the CSRF check: a callback must still present one of
+ * these exact 256-bit values, and each still expires with the cookie.
+ */
+const MAX_PENDING_STATES = 5;
+/** `-` and `r` are the only flag fields this format writes - see `decodePendingState`. */
+const RETRIED_FLAG = "r";
+const NO_FLAGS = "-";
+/**
+ * The state cookie's wire format: one entry per in-flight sign-in, newest
+ * first, joined by `|`.
+ *
+ * An entry is `state:flags:next` with the destination **percent-encoded**
+ * rather than written raw, and that is what makes splitting on a delimiter
+ * safe: `state` is base64url so it can hold neither, and an encoded path
+ * cannot be read as a field boundary however many colons or pipes it
+ * contains. The raw single-pair format this replaces is exactly why `retried`
+ * and the silent marker had to live outside the cookie - the split was too
+ * fragile to carry a third field.
+ */
+function encodePendingStates(entries) {
+    return entries
+        .map((entry) => `${entry.state}:${entry.retried ? RETRIED_FLAG : NO_FLAGS}:${encodeURIComponent(entry.next)}`)
+        .join("|");
+}
+function decodePendingStates(raw) {
+    if (!raw)
+        return [];
+    const entries = [];
+    for (const part of raw.split("|")) {
+        const entry = decodePendingState(part);
+        if (entry)
+            entries.push(entry);
+    }
+    return entries;
+}
+/**
+ * One entry, tolerating the format this replaced.
+ *
+ * A cookie minted by the previous version is a single raw `state:next` pair,
+ * and sign-ins in flight across a deploy carry one. The flag field is a known
+ * one-character set, so anything else in that position means the remainder is
+ * a legacy destination - including one that itself contains a colon. Dropping
+ * those instead would answer every mid-deploy callback with
+ * `state_mismatch`.
+ */
+function decodePendingState(part) {
+    const firstColon = part.indexOf(":");
+    if (firstColon <= 0)
+        return null;
+    const state = part.slice(0, firstColon);
+    const remainder = part.slice(firstColon + 1);
+    const secondColon = remainder.indexOf(":");
+    const flags = secondColon === -1 ? "" : remainder.slice(0, secondColon);
+    const hasFlags = flags === NO_FLAGS || flags === RETRIED_FLAG;
+    return {
+        state,
+        next: decodeDestination(hasFlags ? remainder.slice(secondColon + 1) : remainder),
+        retried: flags === RETRIED_FLAG,
+    };
+}
+/**
+ * `decodeURIComponent` throws on a lone `%`, which a legacy raw destination
+ * may well hold. The undecoded string then goes through `safeRedirect` like
+ * any other candidate, so a malformed one costs the default destination
+ * rather than a 500.
+ */
+function decodeDestination(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+/** Appends `connect_error=<code>` to a destination that may already carry a query. */
+function withError(next, code) {
+    return `${next}${next.includes("?") ? "&" : "?"}connect_error=${encodeURIComponent(code)}`;
+}
 function readCookie(request, name) {
     const header = request.headers.get("cookie");
     if (!header)
@@ -127,6 +220,10 @@ export function createConnectHandler(options) {
      * the cross-site redirect back from Connect, which is the one request that
      * has to read it. Scoped to `basePath` so it is never attached to ordinary
      * page loads.
+     *
+     * Holds every in-flight round trip rather than the latest one - see
+     * `MAX_PENDING_STATES` and `encodePendingStates`. An empty value clears it,
+     * which is what an exchange that consumed the last pending entry wants.
      */
     function stateCookie(value, secure) {
         const cleared = value === "";
@@ -956,6 +1053,17 @@ export function createConnectHandler(options) {
          * alongside the post-login destination, and bounces the browser to
          * Connect.
          *
+         * The new entry is **prepended to whatever is already pending** rather
+         * than replacing it, so opening the app in a second tab no longer
+         * invalidates the first - see `MAX_PENDING_STATES`.
+         *
+         * `?connect_retry=1` is stamped onto the entry here, which is the only
+         * place that marker can be read: it is a query parameter on *this* URL,
+         * and the `redirect_uri` handed to Connect is a registered, exact-match
+         * value that cannot carry it. The callback used to look for it on its own
+         * URL, where it could never arrive - so both retry bounds below were
+         * unreachable and `login_required` could loop indefinitely.
+         *
          * Registered only when the session store can `write` - without that, the
          * callback would have nowhere to put the session it just earned.
          */
@@ -971,9 +1079,13 @@ export function createConnectHandler(options) {
                 state,
                 ...(prompt ? { prompt } : {}),
             });
-            // State and destination travel together in one cookie so the callback
+            // State and destination travel together in one entry so the callback
             // cannot end up with one and not the other.
-            const cookies = [stateCookie(`${state}:${next}`, secure)];
+            const pending = [
+                { state, next, retried: url.searchParams.get("connect_retry") === "1" },
+                ...decodePendingStates(readCookie(request, stateCookieName)),
+            ].slice(0, MAX_PENDING_STATES);
+            const cookies = [stateCookie(encodePendingStates(pending), secure)];
             if (prompt === "none")
                 cookies.push(silentCookie("1", secure));
             return redirect(authorizeUrl, cookies);
@@ -986,20 +1098,49 @@ export function createConnectHandler(options) {
         "GET /callback": async (request) => {
             const url = new URL(request.url);
             const secure = url.protocol === "https:";
-            const [cookieState, ...destinationParts] = (readCookie(request, stateCookieName) ?? "").split(":");
-            const next = safeRedirect(destinationParts.join(":") || null, defaultRedirect);
-            const clearState = stateCookie("", secure);
+            const pending = decodePendingStates(readCookie(request, stateCookieName));
             const returnedState = url.searchParams.get("state") ?? "";
-            if (!cookieState || !sameState(cookieState, returnedState)) {
-                // Either a forged callback or a genuinely stale tab. Neither should
-                // mint a session, and neither is worth an error page.
-                return redirect(`${next}${next.includes("?") ? "&" : "?"}connect_error=state_mismatch`, [
-                    clearState,
-                    silentCookie("", secure),
-                ]);
-            }
+            const matched = pending.find((entry) => sameState(entry.state, returnedState)) ?? null;
+            // Every *other* in-flight sign-in survives this one. Clearing the whole
+            // cookie is what made a second tab collateral damage: finishing in one
+            // tab left the other holding a state the server had just forgotten.
+            const settleState = stateCookie(encodePendingStates(pending.filter((entry) => entry !== matched)), secure);
+            // Only ever this flow's own destination. With no match there is no
+            // destination to trust - a `next` belonging to a different round trip is
+            // somebody else's business, so that case takes the default.
+            const next = safeRedirect(matched?.next ?? null, defaultRedirect);
+            // Read before the state check, not after. A `prompt=none` probe must
+            // never escalate into a visible sign-in - including the retry below -
+            // and the mismatch branch is reachable for a silent probe whose cookie
+            // has expired.
             const wasSilent = readCookie(request, silentCookieName) === "1";
             const clearSilent = silentCookie("", secure);
+            /** One more interactive attempt, marked so the next pass can tell. */
+            const retrySignIn = () => {
+                const retry = new URL(`${url.origin}${basePath}/signin`);
+                retry.searchParams.set("next", next);
+                retry.searchParams.set("connect_retry", "1");
+                return redirect(retry.toString(), [settleState, clearSilent]);
+            };
+            if (!matched) {
+                // A stale tab whose cookie has expired, more entries in flight than
+                // `MAX_PENDING_STATES` holds, or a forged callback. None of them mints
+                // a session and none is worth an error page.
+                //
+                // One retry, because the overwhelmingly common cause is a round trip
+                // whose own entry is simply gone and whose visitor Connect has already
+                // signed in - that completes in a single hop. The bound reads *any*
+                // pending entry's marker rather than the matched one, there being
+                // none: a browser that has already been bounced once gets the error
+                // instead of another lap. Without it this is the silent infinite loop,
+                // since the host app's session gate answers `/dashboard` with no
+                // session by firing `/signin` again.
+                if (wasSilent)
+                    return redirect(next, [settleState, clearSilent]);
+                if (!pending.some((entry) => entry.retried))
+                    return retrySignIn();
+                return redirect(withError(next, "state_mismatch"), [settleState, clearSilent]);
+            }
             const error = url.searchParams.get("error");
             if (error) {
                 // A silent (`prompt=none`) probe that came back empty-handed. All
@@ -1014,27 +1155,20 @@ export function createConnectHandler(options) {
                 // if they're already here" into "force everyone to log in", which is
                 // the precise opposite of the feature.
                 if (wasSilent) {
-                    return redirect(next, [clearState, clearSilent]);
+                    return redirect(next, [settleState, clearSilent]);
                 }
                 // `login_required` is normal traffic, not a fault: a new account gets
                 // pulled out to their inbox to verify, and the ~15 minute request
                 // expires before they return. Connect has already signed them in, so
-                // one silent retry completes in a single hop. `connect_retry` bounds
-                // it - a genuine loop must surface, not spin.
-                if (error === "login_required" && url.searchParams.get("connect_retry") !== "1") {
-                    const retry = new URL(`${url.origin}${basePath}/signin`);
-                    retry.searchParams.set("next", next);
-                    retry.searchParams.set("connect_retry", "1");
-                    return redirect(retry.toString(), [clearState, clearSilent]);
-                }
-                return redirect(`${next}${next.includes("?") ? "&" : "?"}connect_error=${encodeURIComponent(error)}`, [
-                    clearState,
-                    clearSilent,
-                ]);
+                // one silent retry completes in a single hop. The marker on this
+                // flow's own entry bounds it - a genuine loop must surface, not spin.
+                if (error === "login_required" && !matched.retried)
+                    return retrySignIn();
+                return redirect(withError(next, error), [settleState, clearSilent]);
             }
             const code = url.searchParams.get("code");
             if (!code) {
-                return redirect(`${next}${next.includes("?") ? "&" : "?"}connect_error=missing_code`, [clearState, clearSilent]);
+                return redirect(withError(next, "missing_code"), [settleState, clearSilent]);
             }
             const result = await client.identity.exchangeCode({
                 code,
@@ -1043,7 +1177,7 @@ export function createConnectHandler(options) {
             // Verified before the session is stored, not after - an unverifiable
             // token must never become a signed-in user.
             await client.identity.verifyIdToken(result.idToken);
-            const response = redirect(next, [clearState, clearSilent]);
+            const response = redirect(next, [settleState, clearSilent]);
             await session.write(request, response, result.sessionToken);
             return response;
         },

package/dist/esm/server/resources/billing.js

@@ -14,6 +14,10 @@ export class BillingResource {
      * independently of the instance it talks to. Without the coercion a partner
      * pointed at a Connect that has not upgraded yet renders a feature list of
      * blanks - which is exactly what happened. See `normalizePlanFeatures`.
+     *
+     * `limits` is defaulted for the same reason, one version later: an instance
+     * that predates limits sends no such field, and a pricing grid mapping over
+     * `plan.limits` would throw rather than simply show no limit rows.
      */
     async listPlans() {
         const response = await request(this.transport, { method: "GET", path: "/plans" });
@@ -21,6 +25,7 @@ export class BillingResource {
             plans: (response.plans ?? []).map((plan) => ({
                 ...plan,
                 features: normalizePlanFeatures(plan.features),
+                limits: plan.limits ?? [],
             })),
         };
     }

package/dist/esm/server/resources/entitlements.js

@@ -1,4 +1,5 @@
 import { pathSegment, request } from "../http.js";
+import { NO_PLAN_LIMIT, planLimitAllows, planLimitFor } from "../../helpers.js";
 /**
  * The two checks worth making on every request: may this workspace be here at
  * all, and what is it paying for.
@@ -42,6 +43,52 @@ export class EntitlementsResource {
         const result = await this.getSubscription(workspaceId);
         return result.hasActiveSubscription && (result.plan?.features.includes(feature) ?? false);
     }
+    /**
+     * How much of a metered resource this workspace may have - the numeric
+     * counterpart of `hasFeature`, for the resources your application counts
+     * itself (sites, projects, pipelines).
+     *
+     * **This is the effective ceiling, not the plan's own number.** Connect has
+     * already folded in whatever the add-ons on the subscription raise it by, so
+     * "Starter includes 1 site, they bought two 5-site packs" arrives here as
+     * `{ model: "limited", value: 11 }`. You never join the plan against the
+     * add-on list yourself, and a customer who buys another pack needs no change
+     * on your side.
+     *
+     * Returns `{ model: "none" }` rather than throwing when there is no active
+     * subscription, when the plan carries no answer for this key, and when the
+     * Connect instance predates limits entirely - the same reasoning
+     * `hasFeature` gives for answering `false`: "not entitled" is the same answer
+     * either way, and a limit check should not need a try/catch around it.
+     *
+     * Connect does not enforce this. It cannot see what you are counting, so it
+     * hands you the number and your code refuses the next row - `canAdd` is that
+     * comparison if you already have the count.
+     */
+    async getLimit(workspaceId, key) {
+        const result = await this.getSubscription(workspaceId);
+        if (!result.hasActiveSubscription)
+            return NO_PLAN_LIMIT;
+        return planLimitFor(result.plan?.limits, key);
+    }
+    /**
+     * Whether this workspace may add `additional` more of a limited resource,
+     * given how many it already has.
+     *
+     * You supply the count, because only your application can produce it. This
+     * is `getLimit` plus `planLimitAllows`, which exists so the comparison is
+     * not rewritten per call site - see that helper for the three ways of
+     * getting it wrong.
+     *
+     * ```ts
+     * if (!(await connect.entitlements.canAdd(workspaceId, "sites", sites.length))) {
+     *   return refuse("Your plan's site limit is reached.");
+     * }
+     * ```
+     */
+    async canAdd(workspaceId, key, currentCount, additional = 1) {
+        return planLimitAllows(await this.getLimit(workspaceId, key), currentCount, additional);
+    }
     /**
      * One page of the workspaces subscribed to your application, newest first.
      *

package/dist/types/client/components/access-gate.d.ts

@@ -23,6 +23,15 @@ export type ConnectAccessGateState = "loading"
  | "clear";
 export interface ConnectAccessGateResult {
     state: ConnectAccessGateState;
+    /**
+     * Re-reads entitlements, evicting the cached answer first.
+     *
+     * Exposed because a blocker is almost always resolved **somewhere this tab
+     * cannot see** - on Connect, in another tab or on a phone - and nothing
+     * about that reaches this one. The gate wires it to the tab regaining
+     * focus; call it yourself if your app learns of a change some other way.
+     */
+    refresh(): void;
     /** The blocker driving a hard-block state (`suspended`/`no_subscription`/`onboarding_pending`/`blocked`). `null` otherwise. */
     blocker: ReadinessBlocker | null;
     /** The `payment_retry_pending` blocker, only when `state === "payment_retry"`. Carries `graceEndsAt`. */

package/dist/types/client/components/subscription.d.ts

@@ -61,6 +61,12 @@ export declare function ConnectSubscriptionCard({ plansHref, className }: Connec
  * count against, so it renders nothing rather than a meter that is always
  * empty. Under `"per-seat"` going over is billable rather than blocked, so it
  * says what the extra costs instead of warning.
+ *
+ * `detail.seatCount` is a live count of the members holding a role for this
+ * application. It used to be the subscription's last-billed snapshot, which
+ * only ever moved on a `"per-seat"` plan - so a `"fixed"` single-seat plan
+ * read "0 of 1 seat used" permanently, including when its one seat was taken
+ * and Connect was already refusing the next assignment.
  */
 export declare function ConnectSeatUsage({ plan, detail, className, }: Readonly<{
     plan: SubscribedPlan;

package/dist/types/client/provider.d.ts

@@ -196,7 +196,21 @@ export interface ConnectProviderProps {
      * not a Connect URL - it is your backend that exchanges the code.
      */
     redirectUri?: string;
-    /** Override for non-production Connect instances. */
+    /**
+     * Override for non-production Connect instances. Defaults to
+     * `https://connect.cosmoops.com`.
+     *
+     * The twin of `CONNECT_APP_URL`, and *not* derived from it - that variable
+     * is read on your server and never reaches the browser. This value is where
+     * the user menu's Profile, Billing and Invoices destinations open, where
+     * `ConnectAppsGrid` sends an unsubscribed application, where checkout
+     * opens, and - if you pass `redirectUri` and so build the authorize URL
+     * here rather than in your own `/signin` route - where sign-in goes. Point
+     * the server somewhere else and leave this alone and the two halves
+     * disagree, so pass both or neither. Your root layout is a Server
+     * Component, so `appUrl={process.env.CONNECT_APP_URL}` is enough and needs
+     * no browser-visible variable.
+     */
     appUrl?: string;
     /**
      * Replace the `fetch` used to reach your bridge. The browser-side twin of
@@ -327,11 +341,20 @@ export declare function useConnectEntitlements(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -347,11 +370,20 @@ export declare function useConnectAddonUsage(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -361,11 +393,20 @@ export declare function useConnectPlans(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -384,11 +425,20 @@ export declare function useConnectCompanyProfile(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -400,11 +450,20 @@ export declare function useConnectApps(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -423,11 +482,20 @@ export declare function useConnectWorkspaces(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -442,11 +510,20 @@ export declare function useConnectWorkspaceMembers(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -456,11 +533,20 @@ export declare function useConnectIntegrations(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -476,11 +562,20 @@ export declare function useConnectSessions(): {
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };
@@ -512,11 +607,20 @@ export declare function useConnectResource<T>(path: string, options?: Readonly<U
     isLoading: boolean;
     error: string | null;
     /**
-     * Forces a fresh read - the provider's cache clears the mutated path's
-     * entry on a successful `mutateResource` call, but nothing re-triggers
-     * this hook's own effect on its own (none of its dependencies change from
-     * a cache write nobody here observes). Call this right after a
-     * `mutateResource` you made against the same `path` completes.
+     * Forces a fresh read - evicts this path's cache entry and re-runs the
+     * read.
+     *
+     * It used only to re-trigger the effect, on the assumption that the caller
+     * had just evicted the entry itself through `mutateResource`. That made it
+     * useless for the other reason to refetch: **something changed somewhere
+     * this tab cannot see.** The provider's cache is a `Map` of resolved
+     * promises with no expiry, so a `refetch()` without the eviction re-read
+     * the same settled promise and reported the same stale answer forever -
+     * which is what left `<ConnectAccessGate>` showing "Choose a plan" in a tab
+     * whose workspace had subscribed in a different one.
+     *
+     * Still safe after a `mutateResource` against the same path: evicting an
+     * entry that is already gone is a no-op.
      */
     refetch(): void;
 };