@shipfox/client-shell 25.0.0 → 27.0.0

package/dist/core/session.d.ts

@@ -9,6 +9,12 @@ export interface UserIdentity {
 export interface AuthenticatedSession {
     accessToken: string;
     user: UserIdentity;
+    /**
+     * Present only for externally minted sessions (for example an adopted
+     * session whose token carries the claim); ordinary cookie sessions never
+     * set it.
+     */
+    impersonatorId?: string;
 }
 export interface WorkspaceMembership {
     id: string;

package/dist/core/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,aAAa,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;CAC7C"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,aAAa,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;IACnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;CAC7C"}

package/dist/core/session.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/core/session.ts"],"sourcesContent":["export type AdminRole = 'admin-observer' | 'admin-operator' | 'admin-owner';\n\nexport interface UserIdentity {\n  id: string;\n  email: string;\n  name?: string;\n  emailVerifiedAt?: string;\n  adminRole?: AdminRole;\n}\n\nexport interface AuthenticatedSession {\n  accessToken: string;\n  user: UserIdentity;\n}\n\nexport interface WorkspaceMembership {\n  id: string;\n  workspaceId: string;\n}\n\nexport interface WorkspaceSummary {\n  id: string;\n  name: string;\n  slug: string;\n  membershipId: string;\n  status?: 'active' | 'suspended' | 'deleted';\n}\n"],"names":[],"mappings":"AAoBA,WAMC"}
+{"version":3,"sources":["../../src/core/session.ts"],"sourcesContent":["export type AdminRole = 'admin-observer' | 'admin-operator' | 'admin-owner';\n\nexport interface UserIdentity {\n  id: string;\n  email: string;\n  name?: string;\n  emailVerifiedAt?: string;\n  adminRole?: AdminRole;\n}\n\nexport interface AuthenticatedSession {\n  accessToken: string;\n  user: UserIdentity;\n  /**\n   * Present only for externally minted sessions (for example an adopted\n   * session whose token carries the claim); ordinary cookie sessions never\n   * set it.\n   */\n  impersonatorId?: string;\n}\n\nexport interface WorkspaceMembership {\n  id: string;\n  workspaceId: string;\n}\n\nexport interface WorkspaceSummary {\n  id: string;\n  name: string;\n  slug: string;\n  membershipId: string;\n  status?: 'active' | 'suspended' | 'deleted';\n}\n"],"names":[],"mappings":"AA0BA,WAMC"}

package/dist/hooks/api/session-mapper.d.ts

@@ -1,5 +1,6 @@
-import type { LoginResponseDto, UserDto } from '@shipfox/api-auth-dto';
+import type { SessionResponseDto, UserDto } from '@shipfox/api-auth-dto';
 import type { AuthenticatedSession, UserIdentity } from '#core/session.js';
+export type { SessionResponseDto };
 export declare function toUserIdentity(dto: UserDto): UserIdentity;
-export declare function toAuthenticatedSession(dto: LoginResponseDto): AuthenticatedSession;
+export declare function toAuthenticatedSession(dto: SessionResponseDto): AuthenticatedSession;
 //# sourceMappingURL=session-mapper.d.ts.map

package/dist/hooks/api/session-mapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-mapper.d.ts","sourceRoot":"","sources":["../../../src/hooks/api/session-mapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,gBAAgB,EAAE,OAAO,EAAC,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAC,oBAAoB,EAAE,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAEzE,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAOzD;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,gBAAgB,GAAG,oBAAoB,CAQlF"}
+{"version":3,"file":"session-mapper.d.ts","sourceRoot":"","sources":["../../../src/hooks/api/session-mapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,kBAAkB,EAAE,OAAO,EAAC,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAC,oBAAoB,EAAE,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAEzE,YAAY,EAAC,kBAAkB,EAAC,CAAC;AAEjC,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAOzD;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,kBAAkB,GAAG,oBAAoB,CASpF"}

package/dist/hooks/api/session-mapper.js

@@ -18,7 +18,10 @@ export function toAuthenticatedSession(dto) {
             ...dto.admin_role ? {
                 adminRole: dto.admin_role
             } : {}
-        }
+        },
+        ...dto.impersonator_id ? {
+            impersonatorId: dto.impersonator_id
+        } : {}
     };
 }
 

package/dist/hooks/api/session-mapper.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/hooks/api/session-mapper.ts"],"sourcesContent":["import type {LoginResponseDto, UserDto} from '@shipfox/api-auth-dto';\nimport type {AuthenticatedSession, UserIdentity} from '#core/session.js';\n\nexport function toUserIdentity(dto: UserDto): UserIdentity {\n  return {\n    id: dto.id,\n    email: dto.email,\n    ...(dto.name ? {name: dto.name} : {}),\n    ...(dto.email_verified_at ? {emailVerifiedAt: dto.email_verified_at} : {}),\n  };\n}\n\nexport function toAuthenticatedSession(dto: LoginResponseDto): AuthenticatedSession {\n  return {\n    accessToken: dto.token,\n    user: {\n      ...toUserIdentity(dto.user),\n      ...(dto.admin_role ? {adminRole: dto.admin_role} : {}),\n    },\n  };\n}\n"],"names":["toUserIdentity","dto","id","email","name","email_verified_at","emailVerifiedAt","toAuthenticatedSession","accessToken","token","user","admin_role","adminRole"],"mappings":"AAGA,OAAO,SAASA,eAAeC,GAAY;IACzC,OAAO;QACLC,IAAID,IAAIC,EAAE;QACVC,OAAOF,IAAIE,KAAK;QAChB,GAAIF,IAAIG,IAAI,GAAG;YAACA,MAAMH,IAAIG,IAAI;QAAA,IAAI,CAAC,CAAC;QACpC,GAAIH,IAAII,iBAAiB,GAAG;YAACC,iBAAiBL,IAAII,iBAAiB;QAAA,IAAI,CAAC,CAAC;IAC3E;AACF;AAEA,OAAO,SAASE,uBAAuBN,GAAqB;IAC1D,OAAO;QACLO,aAAaP,IAAIQ,KAAK;QACtBC,MAAM;YACJ,GAAGV,eAAeC,IAAIS,IAAI,CAAC;YAC3B,GAAIT,IAAIU,UAAU,GAAG;gBAACC,WAAWX,IAAIU,UAAU;YAAA,IAAI,CAAC,CAAC;QACvD;IACF;AACF"}
+{"version":3,"sources":["../../../src/hooks/api/session-mapper.ts"],"sourcesContent":["import type {SessionResponseDto, UserDto} from '@shipfox/api-auth-dto';\nimport type {AuthenticatedSession, UserIdentity} from '#core/session.js';\n\nexport type {SessionResponseDto};\n\nexport function toUserIdentity(dto: UserDto): UserIdentity {\n  return {\n    id: dto.id,\n    email: dto.email,\n    ...(dto.name ? {name: dto.name} : {}),\n    ...(dto.email_verified_at ? {emailVerifiedAt: dto.email_verified_at} : {}),\n  };\n}\n\nexport function toAuthenticatedSession(dto: SessionResponseDto): AuthenticatedSession {\n  return {\n    accessToken: dto.token,\n    user: {\n      ...toUserIdentity(dto.user),\n      ...(dto.admin_role ? {adminRole: dto.admin_role} : {}),\n    },\n    ...(dto.impersonator_id ? {impersonatorId: dto.impersonator_id} : {}),\n  };\n}\n"],"names":["toUserIdentity","dto","id","email","name","email_verified_at","emailVerifiedAt","toAuthenticatedSession","accessToken","token","user","admin_role","adminRole","impersonator_id","impersonatorId"],"mappings":"AAKA,OAAO,SAASA,eAAeC,GAAY;IACzC,OAAO;QACLC,IAAID,IAAIC,EAAE;QACVC,OAAOF,IAAIE,KAAK;QAChB,GAAIF,IAAIG,IAAI,GAAG;YAACA,MAAMH,IAAIG,IAAI;QAAA,IAAI,CAAC,CAAC;QACpC,GAAIH,IAAII,iBAAiB,GAAG;YAACC,iBAAiBL,IAAII,iBAAiB;QAAA,IAAI,CAAC,CAAC;IAC3E;AACF;AAEA,OAAO,SAASE,uBAAuBN,GAAuB;IAC5D,OAAO;QACLO,aAAaP,IAAIQ,KAAK;QACtBC,MAAM;YACJ,GAAGV,eAAeC,IAAIS,IAAI,CAAC;YAC3B,GAAIT,IAAIU,UAAU,GAAG;gBAACC,WAAWX,IAAIU,UAAU;YAAA,IAAI,CAAC,CAAC;QACvD;QACA,GAAIV,IAAIY,eAAe,GAAG;YAACC,gBAAgBb,IAAIY,eAAe;QAAA,IAAI,CAAC,CAAC;IACtE;AACF"}

package/dist/runtime/auth.d.ts

@@ -1,5 +1,43 @@
 import type { PropsWithChildren } from 'react';
 import type { AuthenticatedSession, UserIdentity, WorkspaceSummary } from '#core/session.js';
+/**
+ * A renewal response for an adopted session. `expiresAt` and `serverTime` are
+ * both issuer timestamps; their difference is the server-side remaining
+ * lifetime, which is the renewal scheduling anchor.
+ */
+export interface AdoptedSessionRenewal {
+    session: AuthenticatedSession;
+    expiresAt: string;
+    serverTime: string;
+}
+export type AdoptedSessionRenewalSupplier = () => Promise<AdoptedSessionRenewal | null>;
+/**
+ * Options for the adopted-session renewal. A `null` renewal result ends the
+ * adoption and falls back to the ordinary cookie refresh.
+ */
+export interface AdoptSessionOptions {
+    expiresAt: string;
+    serverTime: string;
+    renew: AdoptedSessionRenewalSupplier;
+}
+/** The adopted session as exposed to composing consumers. */
+export interface AdoptedSessionState {
+    session: AuthenticatedSession;
+    expiresAt: string;
+    serverTime: string;
+}
+interface AdoptedSessionRuntimeState extends AdoptedSessionState {
+    generation: number;
+    receivedAtMs: number;
+    renew: AdoptedSessionRenewalSupplier;
+    /**
+     * Consecutive malformed or non-advancing renewal responses (responses that
+     * merely lost a race to a longer expiry excluded). Capped at
+     * {@link ADOPTED_RENEWAL_STALL_LIMIT} before the adoption falls back to the
+     * ordinary cookie refresh.
+     */
+    stalledRenewals: number;
+}
 export type AuthStatus = 'loading' | 'authenticated' | 'guest';
 export type Workspace = WorkspaceSummary;
 export interface AuthState {
@@ -22,12 +60,41 @@ export declare function toAuthenticatedState(session: AuthenticatedSession, work
 export declare function useAuthState(): AuthStateValue;
 export { authRefreshQueryKey, authRefreshQueryOptions, listUserWorkspaces, userWorkspacesQueryKey, userWorkspacesQueryOptions, } from '#hooks/api/session-auth.js';
 export declare function getAuthRefreshDelayMs(token: string, nowMs?: number): number | undefined;
+/**
+ * Delay until the adopted session's renewal point, derived from the issuer
+ * timestamps only. Both values come from the server, so a skewed browser
+ * clock cannot shorten or lengthen the window. Negative when the renewal
+ * point already passed; callers clamp.
+ */
+export declare function getAdoptedSessionRenewDelayMs(expiresAt: string, serverTime: string): number;
 export declare function useAuthTransition(): {
     beginAuthTransition: () => number;
     enterAuthenticated: (session: AuthenticatedSession, transitionEpoch?: number) => Promise<boolean>;
     enterGuest: (transitionEpoch?: number) => Promise<boolean>;
 };
 export declare function useRefreshAuth(): () => Promise<AuthenticatedSession>;
+/**
+ * The adopted-session runtime seam. An adopted session is an externally minted
+ * access-token-only session entered through the ordinary authenticated path;
+ * it suspends the cookie-based proactive refresh and runs until its issuer
+ * expiry, then asks the renewal supplier or falls back to the cookie.
+ *
+ * Release is terminal for the tab: it increments an adoption generation before
+ * ending the adoption, and a mint or renewal response is adopted only when its
+ * generation still matches the current one. Tabs share no adopted token and no
+ * release state.
+ *
+ * The renew timer asks the supplier near the issuer expiry without operator
+ * action. ADR 0014 renewal is a deliberate administrator action, so callers
+ * gate the supplier on the operator's Extend signal (returning `null`
+ * otherwise) to keep every extension deliberate and audited.
+ */
+export declare function useAdoptedSession(): {
+    adoptSession: (session: AuthenticatedSession, options: AdoptSessionOptions) => Promise<boolean>;
+    renewAdoptedSession: () => Promise<AdoptedSessionRenewal | null>;
+    releaseAdoptedSession: () => Promise<void>;
+    adoptedSession: AdoptedSessionRuntimeState | null;
+};
 export interface AuthRuntimeProps extends PropsWithChildren {
     effects?: boolean;
 }

package/dist/runtime/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/runtime/auth.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,OAAO,CAAC;AAE7C,OAAO,KAAK,EAAC,oBAAoB,EAAE,YAAY,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAiB3F,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,eAAe,GAAG,OAAO,CAAC;AAE/D,MAAM,MAAM,SAAS,GAAG,gBAAgB,CAAC;AAEzC,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,eAAO,MAAM,gBAAgB,EAAE,SAA+B,CAAC;AAC/D,eAAO,MAAM,aAAa;;CAAoC,CAAC;AAG/D,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,oBAAoB,EAC7B,UAAU,GAAE,gBAAgB,EAAO,GAClC,SAAS,CAOX;AAED,wBAAgB,YAAY,IAAI,cAAc,CAY7C;AAED,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,4BAA4B,CAAC;AAoBpC,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAa,GAAG,MAAM,GAAG,SAAS,CAG3F;AAED,wBAAgB,iBAAiB;;kCAkCb,oBAAoB,oBAAoB,MAAM;mCAhBrC,MAAM;EAiDlC;AAED,wBAAgB,cAAc,wCAuC7B;AAED,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,WAAW,CAAC,EAAC,QAAQ,EAAE,OAAc,EAAC,EAAE,gBAAgB,6BAyEvE"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/runtime/auth.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,OAAO,CAAC;AAE7C,OAAO,KAAK,EAAC,oBAAoB,EAAE,YAAY,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAkB3F;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,6BAA6B,GAAG,MAAM,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;AAExF;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,6BAA6B,CAAC;CACtC;AAED,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,0BAA2B,SAAQ,mBAAmB;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,6BAA6B,CAAC;IACrC;;;;;OAKG;IACH,eAAe,EAAE,MAAM,CAAC;CACzB;AAqBD,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,eAAe,GAAG,OAAO,CAAC;AAE/D,MAAM,MAAM,SAAS,GAAG,gBAAgB,CAAC;AAEzC,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,eAAO,MAAM,gBAAgB,EAAE,SAA+B,CAAC;AAC/D,eAAO,MAAM,aAAa;;CAAoC,CAAC;AAG/D,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,oBAAoB,EAC7B,UAAU,GAAE,gBAAgB,EAAO,GAClC,SAAS,CAOX;AAED,wBAAgB,YAAY,IAAI,cAAc,CAY7C;AAED,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,4BAA4B,CAAC;AAoBpC,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAa,GAAG,MAAM,GAAG,SAAS,CAG3F;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE3F;AAED,wBAAgB,iBAAiB;;kCAyCb,oBAAoB,oBAAoB,MAAM;mCAfrC,MAAM;EAiDlC;AAED,wBAAgB,cAAc,wCAsD7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB;4BA6Bb,oBAAoB,WAAW,mBAAmB,KAAG,OAAO,CAAC,OAAO,CAAC;+BAmCrC,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;;;EAqGxF;AAED,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,WAAW,CAAC,EAAC,QAAQ,EAAE,OAAc,EAAC,EAAE,gBAAgB,6BAyJvE"}

package/dist/runtime/auth.js

@@ -6,11 +6,29 @@ import { authRefreshQueryKey, authRefreshQueryOptions, userWorkspacesQueryOption
 import { lastWorkspaceIdAtom } from './last-workspace.js';
 const REFRESH_EARLY_MS = 5 * 60 * 1000;
 const REFRESH_RETRY_DELAY_MS = 60_000;
+// Consecutive renewal responses that do not advance the adopted window (a
+// malformed response, or an expiry no later than the one already held) end
+// the adoption instead of driving an unbounded zero-delay renew loop. A
+// valid response that merely lost a race to a longer expiry is not one.
+const ADOPTED_RENEWAL_STALL_LIMIT = 3;
 const BASE64_URL_REPLACEMENTS = {
     dash: /-/g,
     underscore: /_/g
 };
 const refreshPromises = new WeakMap();
+const adoptedSessionAtom = atom(null);
+const adoptionGenerationAtom = atom(0);
+/**
+ * Expiry reserved by a renewal whose adoption transition is still running.
+ * Overlapping renewals compare against it so a shorter response cannot slip
+ * past the later-`expires_at` check while the longer one is entering.
+ *
+ * It lives in its own atom instead of inside {@link adoptedSessionAtom} so a
+ * reservation write does not re-run `AuthRuntime`'s renewal effect: an effect
+ * re-run while the first transition is still pending would reset the
+ * in-flight guard and schedule another renewal from the old expiry, letting
+ * an already-due adoption invoke the supplier a second time.
+ */ const adoptedRenewalReservationAtom = atom(0);
 function invalidateRefresh(queryClient) {
     refreshPromises.delete(queryClient);
 }
@@ -58,6 +76,14 @@ export function getAuthRefreshDelayMs(token, nowMs = Date.now()) {
     const exp = readJwtExp(token);
     return exp === undefined ? undefined : exp * 1000 - nowMs - REFRESH_EARLY_MS;
 }
+/**
+ * Delay until the adopted session's renewal point, derived from the issuer
+ * timestamps only. Both values come from the server, so a skewed browser
+ * clock cannot shorten or lengthen the window. Negative when the renewal
+ * point already passed; callers clamp.
+ */ export function getAdoptedSessionRenewDelayMs(expiresAt, serverTime) {
+    return Date.parse(expiresAt) - Date.parse(serverTime) - REFRESH_EARLY_MS;
+}
 export function useAuthTransition() {
     const queryClient = useQueryClient();
     const store = useStore();
@@ -70,19 +96,24 @@ export function useAuthTransition() {
     }, [
         store
     ]);
-    const clearPrivateState = useCallback(async ()=>{
+    const clearPrivateState = useCallback(async (epoch)=>{
         await queryClient.cancelQueries();
+        // A superseded transition must not clear the cache: the clear would
+        // destroy an in-flight query owned by the transition that superseded it
+        // (for example the cookie fallback started by a release during a mint).
+        if (store.get(authTransitionEpochAtom) !== epoch) return false;
         queryClient.clear();
+        return true;
     }, [
-        queryClient
+        queryClient,
+        store
     ]);
     const enterGuest = useCallback(async (transitionEpoch)=>{
         const isExternalTransition = transitionEpoch === undefined;
         const epoch = transitionEpoch ?? beginAuthTransition();
         if (isExternalTransition) invalidateRefresh(queryClient);
         if (store.get(authTransitionEpochAtom) !== epoch) return false;
-        await clearPrivateState();
-        if (store.get(authTransitionEpochAtom) !== epoch) return false;
+        if (!await clearPrivateState(epoch)) return false;
         setLastWorkspaceId(undefined);
         setState({
             status: 'guest'
@@ -103,9 +134,10 @@ export function useAuthTransition() {
         if (store.get(authTransitionEpochAtom) !== epoch) return false;
         const previousState = store.get(authStateAtom);
         const principalChanged = previousState.status !== 'authenticated' || previousState.user?.id !== session.user.id;
-        if (principalChanged) await clearPrivateState();
-        if (store.get(authTransitionEpochAtom) !== epoch) return false;
-        if (principalChanged) setLastWorkspaceId(undefined);
+        if (principalChanged) {
+            if (!await clearPrivateState(epoch)) return false;
+            setLastWorkspaceId(undefined);
+        }
         queryClient.setQueryData(authRefreshQueryKey, session);
         let workspaces = [];
         try {
@@ -133,10 +165,22 @@ export function useAuthTransition() {
 }
 export function useRefreshAuth() {
     const queryClient = useQueryClient();
+    const store = useStore();
     const { beginAuthTransition, enterAuthenticated, enterGuest } = useAuthTransition();
     return useCallback(()=>{
         const existingRefresh = refreshPromises.get(queryClient);
         if (existingRefresh) return existingRefresh;
+        if (store.get(adoptedSessionAtom) !== null) {
+            // The ordinary refresh restores the cookie principal; running it while
+            // an adoption is live would desync the adopted token from its metadata
+            // and make product requests carry the administrator credential. ADR
+            // 0014: the adopted bearer token is the only request credential.
+            return Promise.reject(new ApiError({
+                message: 'The adopted session must end before the ordinary cookie refresh.',
+                code: 'unauthorized',
+                status: 401
+            }));
+        }
         const transitionEpoch = beginAuthTransition();
         const refresh = (async ()=>{
             try {
@@ -168,22 +212,223 @@ export function useRefreshAuth() {
         beginAuthTransition,
         enterAuthenticated,
         enterGuest,
-        queryClient
+        queryClient,
+        store
     ]);
 }
+/**
+ * The adopted-session runtime seam. An adopted session is an externally minted
+ * access-token-only session entered through the ordinary authenticated path;
+ * it suspends the cookie-based proactive refresh and runs until its issuer
+ * expiry, then asks the renewal supplier or falls back to the cookie.
+ *
+ * Release is terminal for the tab: it increments an adoption generation before
+ * ending the adoption, and a mint or renewal response is adopted only when its
+ * generation still matches the current one. Tabs share no adopted token and no
+ * release state.
+ *
+ * The renew timer asks the supplier near the issuer expiry without operator
+ * action. ADR 0014 renewal is a deliberate administrator action, so callers
+ * gate the supplier on the operator's Extend signal (returning `null`
+ * otherwise) to keep every extension deliberate and audited.
+ */ export function useAdoptedSession() {
+    const store = useStore();
+    const queryClient = useQueryClient();
+    const { beginAuthTransition, enterAuthenticated, enterGuest } = useAuthTransition();
+    const refreshAuth = useRefreshAuth();
+    const adoptedSession = useAtomValue(adoptedSessionAtom);
+    const endAdoption = useCallback(async ()=>{
+        store.set(adoptionGenerationAtom, store.get(adoptionGenerationAtom) + 1);
+        store.set(adoptedRenewalReservationAtom, 0);
+        store.set(adoptedSessionAtom, null);
+        try {
+            await refreshAuth();
+        } catch (error) {
+            // A superseded restore is not a failure: a newer transition (for
+            // example a fresh adoption) already owns the session, and forcing
+            // guest would log out that newer session.
+            if (error instanceof ApiError && error.message === 'Authentication refresh was superseded.') {
+                return;
+            }
+            // The cookie restore failed (transient network error, or a cookie that
+            // died while the adoption suspended the refresh). The adopted token must
+            // never remain the ambient request credential after Stop, so fall back
+            // to guest instead of leaving the tab under the adopted principal.
+            if (store.get(authStateAtom).status !== 'guest') await enterGuest();
+        }
+    }, [
+        enterGuest,
+        refreshAuth,
+        store
+    ]);
+    const adoptSession = useCallback(async (session, options)=>{
+        // Each adoption starts a new generation: a renewal still in flight from
+        // a previous adoption, or a release racing the mint, must not land over
+        // the new adoption.
+        const generation = store.get(adoptionGenerationAtom) + 1;
+        store.set(adoptionGenerationAtom, generation);
+        // A fresh adoption must not inherit an expiry reserved by a renewal of
+        // the previous adoption whose transition is still in flight.
+        store.set(adoptedRenewalReservationAtom, 0);
+        const transitionEpoch = beginAuthTransition();
+        // The transition supersedes any cookie refresh still in flight; leaving
+        // it in the map would make the release fallback reuse a promise that
+        // rejects as superseded instead of restoring the cookie session.
+        invalidateRefresh(queryClient);
+        // The token's server-side lifetime started when it was received; a slow
+        // workspace hydration must not push the renewal point past expiresAt.
+        // The monotonic clock keeps the elapsed measurement immune to wall-clock
+        // steps (NTP correction, VM suspend/resume).
+        const receivedAtMs = performance.now();
+        const accepted = await enterAuthenticated(session, transitionEpoch);
+        if (!accepted || store.get(adoptionGenerationAtom) !== generation) return false;
+        store.set(adoptedSessionAtom, {
+            generation,
+            receivedAtMs,
+            session,
+            expiresAt: options.expiresAt,
+            serverTime: options.serverTime,
+            renew: options.renew,
+            stalledRenewals: 0
+        });
+        return true;
+    }, [
+        beginAuthTransition,
+        enterAuthenticated,
+        queryClient,
+        store
+    ]);
+    const renewAdoptedSession = useCallback(async ()=>{
+        const adopted = store.get(adoptedSessionAtom);
+        if (adopted === null) return null;
+        const generation = store.get(adoptionGenerationAtom);
+        let result;
+        try {
+            result = await adopted.renew();
+        } catch  {
+            // A failed renewal degrades like a refused one: back to the cookie.
+            result = null;
+        }
+        // The generation is captured when the request started; a response that
+        // resolves after a release is discarded.
+        if (store.get(adoptionGenerationAtom) !== generation) return null;
+        if (result === null) {
+            await endAdoption();
+            return null;
+        }
+        const candidateExpiryMs = Date.parse(result.expiresAt);
+        const candidateServerTimeMs = Date.parse(result.serverTime);
+        const candidateValid = Number.isFinite(candidateExpiryMs) && Number.isFinite(candidateServerTimeMs) && candidateExpiryMs > candidateServerTimeMs;
+        const current = store.get(adoptedSessionAtom);
+        if (current === null) return null;
+        const currentExpiryMs = Date.parse(current.expiresAt);
+        const bestReservedExpiryMs = Math.max(currentExpiryMs, store.get(adoptedRenewalReservationAtom));
+        // A candidate that is malformed, stuck on the expiry the adoption already
+        // holds, or shorter than the best expiry adopted or reserved by another
+        // renewal did not advance the window and is never adopted.
+        const windowDidNotAdvance = !candidateValid || candidateExpiryMs <= bestReservedExpiryMs;
+        if (windowDidNotAdvance) {
+            // Count a stall only when the window really did not move: a malformed
+            // response, or one stuck on an expiry the adoption already holds. A
+            // valid response that merely lost a race to a longer expiry adopted or
+            // reserved while this renewal was in flight is a healthy concurrent
+            // renewal; counting it would burn the stall budget and fire extra
+            // supplier requests. The cap ends the adoption instead of driving an
+            // unbounded zero-delay renew loop and falls back to the cookie refresh.
+            const lostRace = candidateValid && (candidateExpiryMs > currentExpiryMs || currentExpiryMs > Date.parse(adopted.expiresAt));
+            if (!candidateValid || !lostRace) {
+                const stalled = {
+                    ...current,
+                    stalledRenewals: current.stalledRenewals + 1
+                };
+                store.set(adoptedSessionAtom, stalled);
+                if (stalled.stalledRenewals >= ADOPTED_RENEWAL_STALL_LIMIT) {
+                    await endAdoption();
+                }
+            }
+            return null;
+        }
+        if (candidateExpiryMs > store.get(adoptedRenewalReservationAtom)) {
+            // Reserve the candidate expiry before the asynchronous transition so an
+            // overlapping shorter response cannot overwrite the longer token. The
+            // reservation lives outside adoptedSessionAtom so this write does not
+            // re-run the renew effect while the transition is still pending.
+            store.set(adoptedRenewalReservationAtom, candidateExpiryMs);
+        }
+        const receivedAtMs = performance.now();
+        const transitionEpoch = beginAuthTransition();
+        // The renewal transition supersedes any cookie refresh still in flight;
+        // release must not reuse a promise that will reject as superseded.
+        invalidateRefresh(queryClient);
+        const accepted = await enterAuthenticated(result.session, transitionEpoch);
+        if (!accepted || store.get(adoptionGenerationAtom) !== generation) {
+            // Drop our reservation only while it is still the current one; another
+            // renewal may have reserved a later expiry meanwhile.
+            if (store.get(adoptedRenewalReservationAtom) === candidateExpiryMs) {
+                store.set(adoptedRenewalReservationAtom, 0);
+            }
+            return null;
+        }
+        store.set(adoptedRenewalReservationAtom, 0);
+        store.set(adoptedSessionAtom, {
+            generation,
+            receivedAtMs,
+            session: result.session,
+            expiresAt: result.expiresAt,
+            serverTime: result.serverTime,
+            renew: adopted.renew,
+            stalledRenewals: 0
+        });
+        return result;
+    }, [
+        beginAuthTransition,
+        endAdoption,
+        enterAuthenticated,
+        queryClient,
+        store
+    ]);
+    const releaseAdoptedSession = useCallback(async ()=>{
+        // Always advance the generation and fall back to the cookie: a release
+        // while a mint is still entering must still invalidate that mint, or the
+        // mint would re-enter the session after Stop.
+        await endAdoption();
+    }, [
+        endAdoption
+    ]);
+    return {
+        adoptSession,
+        renewAdoptedSession,
+        releaseAdoptedSession,
+        adoptedSession
+    };
+}
 export function AuthRuntime({ children, effects = true }) {
     const store = useStore();
     const authState = useAtomValue(authStateAtom);
     const refreshAuth = useRefreshAuth();
+    const { adoptedSession, renewAdoptedSession, releaseAdoptedSession } = useAdoptedSession();
     useEffect(()=>{
         if (!effects) return;
         configureApiClient({
             getAccessToken: ()=>store.get(authStateAtom).token,
-            refreshAccessToken: async ()=>(await refreshAuth()).accessToken
+            refreshAccessToken: async ()=>{
+                if (store.get(adoptedSessionAtom) !== null) {
+                    // A 401 under an adopted token ends the adoption: the cookie
+                    // refresh restores the cookie's principal, and the renew timer must
+                    // not resurrect the adopted session afterwards. The falsy result
+                    // stops the failed request from being re-sent under the restored
+                    // administrator's principal (ADR 0014: the adopted bearer token is
+                    // the only request credential).
+                    await releaseAdoptedSession();
+                    return undefined;
+                }
+                return (await refreshAuth()).accessToken;
+            }
         });
     }, [
         effects,
         refreshAuth,
+        releaseAdoptedSession,
         store
     ]);
     useEffect(()=>{
@@ -194,7 +439,9 @@ export function AuthRuntime({ children, effects = true }) {
         refreshAuth
     ]);
     useEffect(()=>{
-        if (!effects || authState.status !== 'authenticated' || !authState.token) return;
+        if (!effects || authState.status !== 'authenticated' || !authState.token || adoptedSession !== null) {
+            return;
+        }
         let timeout;
         let disposed = false;
         let refreshing = false;
@@ -209,11 +456,12 @@ export function AuthRuntime({ children, effects = true }) {
         const retryIfStillDue = ()=>{
             const current = store.get(authStateAtom);
             if (current.status !== 'authenticated' || !current.token) return;
+            if (store.get(adoptedSessionAtom) !== null) return;
             const delay = getAuthRefreshDelayMs(current.token);
             if (delay !== undefined && delay <= 0) scheduleRefresh(REFRESH_RETRY_DELAY_MS);
         };
         function runRefresh() {
-            if (disposed || refreshing) return;
+            if (disposed || refreshing || store.get(adoptedSessionAtom) !== null) return;
             refreshing = true;
             clearRefreshTimer();
             refreshAuth().catch(()=>undefined).finally(()=>{
@@ -224,6 +472,7 @@ export function AuthRuntime({ children, effects = true }) {
         const refreshIfDue = ()=>{
             const current = store.get(authStateAtom);
             if (current.status !== 'authenticated' || !current.token) return;
+            if (store.get(adoptedSessionAtom) !== null) return;
             const delay = getAuthRefreshDelayMs(current.token);
             if (delay !== undefined && delay <= 0) runRefresh();
         };
@@ -243,12 +492,71 @@ export function AuthRuntime({ children, effects = true }) {
             document.removeEventListener('visibilitychange', refreshIfVisible);
         };
     }, [
+        adoptedSession,
         authState.status,
         authState.token,
         effects,
         refreshAuth,
         store
     ]);
+    useEffect(()=>{
+        if (!effects || adoptedSession === null) return;
+        let timeout;
+        let disposed = false;
+        let renewing = false;
+        let nextFireAtMs = 0;
+        const clearRenewTimer = ()=>{
+            if (timeout !== undefined) clearTimeout(timeout);
+            timeout = undefined;
+        };
+        const scheduleRenew = ()=>{
+            clearRenewTimer();
+            const current = store.get(adoptedSessionAtom);
+            if (current === null) return;
+            // The fire point comes from the issuer timestamps; elapsed time is
+            // measured on the monotonic clock so a wall-clock step (NTP correction,
+            // VM suspend/resume) cannot shift the renewal point.
+            const earlyFireAtMs = current.receivedAtMs + getAdoptedSessionRenewDelayMs(current.expiresAt, current.serverTime);
+            // A missed early point (tab suspended, timer throttled) must renew now
+            // instead of waiting for the hard expiry.
+            nextFireAtMs = Math.max(earlyFireAtMs, performance.now());
+            timeout = setTimeout(runRenew, Math.max(0, nextFireAtMs - performance.now()));
+        };
+        const runRenew = ()=>{
+            if (disposed || renewing) return;
+            renewing = true;
+            clearRenewTimer();
+            renewAdoptedSession().catch(()=>undefined).finally(()=>{
+                renewing = false;
+                // Re-arm when the adoption survived (for example a racing response
+                // with an earlier expiry was discarded); the effect re-runs and
+                // re-arms when a renewal is adopted instead.
+                if (!disposed) scheduleRenew();
+            });
+        };
+        const renewIfDue = ()=>{
+            if (performance.now() >= nextFireAtMs) runRenew();
+        };
+        const renewIfVisible = ()=>{
+            if (document.visibilityState === 'visible') renewIfDue();
+        };
+        scheduleRenew();
+        window.addEventListener('focus', renewIfDue);
+        window.addEventListener('online', renewIfDue);
+        document.addEventListener('visibilitychange', renewIfVisible);
+        return ()=>{
+            disposed = true;
+            clearRenewTimer();
+            window.removeEventListener('focus', renewIfDue);
+            window.removeEventListener('online', renewIfDue);
+            document.removeEventListener('visibilitychange', renewIfVisible);
+        };
+    }, [
+        adoptedSession,
+        effects,
+        renewAdoptedSession,
+        store
+    ]);
     return children;
 }