diff --git a/extensions/levelcode-ai/agent.js b/extensions/levelcode-ai/agent.js
index a763cd1..1bc308e 100644
--- a/extensions/levelcode-ai/agent.js
+++ b/extensions/levelcode-ai/agent.js
@@ -1048,6 +1048,12 @@ async function runAgent(ctx) {
 			ctx.post({ type: 'agentError', message: 'You’ve hit the model’s context window (the conversation got too long). Start a New chat to reset it, switch to a larger-context model, or pin fewer files — then continue.', kind: 'context' });
 			reason = 'error';
 		}
+		else if (typeof ctx.isSessionExpired === 'function' && ctx.isSessionExpired(e)) {
+			// The gateway 401 that refreshAuth could not recover: the session is over. A sign-in card,
+			// not the adapter's raw message — the user needs a button, not a status code.
+			ctx.post({ type: 'agentError', message: ctx.sessionExpiredMessage || msg, code: 'session_expired' });
+			reason = 'error';
+		}
 		else { ctx.post({ type: 'agentError', message: msg, code }); reason = 'error'; }
 	} finally {
 		dbg('agent.done', { reason, steps: step - 1, edits: ctx.editCount || 0, costMicros: runCostMicros, creditsLeftMicros: ctx.credits != null ? ctx.credits : null });
diff --git a/extensions/levelcode-ai/extension.js b/extensions/levelcode-ai/extension.js
index 91ddd15..abe1442 100644
--- a/extensions/levelcode-ai/extension.js
+++ b/extensions/levelcode-ai/extension.js
@@ -17,6 +17,7 @@ const crypto = require('crypto');
 const providers = require('./providers/index');
 const catalog = require('./providers/catalog');
 const { resolveGateway } = require('./providers/gateway');
+const session = require('./providers/session');
 const { registerAiEdit } = require('./aiEdit');
 const { registerLmProvider } = require('./lmProvider');
 const { registerInlineComplete } = require('./inlineComplete');
@@ -202,6 +203,7 @@ function providerErrorMessage(req) {
 	if (req.reason === 'baseURL') { return 'Set a base URL for the custom OpenAI-compatible provider first (levelcode.ai.baseURL).'; }
 	if (req.reason === 'insecureBaseURL') { return 'Refusing to send your API key over plain http to a non-local host. Use an https base URL (or a localhost endpoint) for the custom provider.'; }
 	if (req.reason === 'insecureGateway') { return 'Refusing to send your LevelCode Cloud token over plain http. Set "levelcode.cloud.endpoint" to an https URL to use gateway mode.'; }
+	if (req.reason === 'signedOut') { return session.SESSION_EXPIRED_MESSAGE; }
 	return 'No API key set for ' + req.label + '. Use the key button or “LevelCode: AI: Set API Key”.';
 }
 
@@ -347,26 +349,302 @@ function isAuthError(e) { return /\bAPI 401\b|\b401\b.*unauthor/i.test(String((e
  * {apiUrl}/api/levelcode/v1/auth/refresh (the Rails backend), store the new access token, return true.
  * No-op (returns false) when not applicable (byok, signed out, no refresh token, or non-https apiUrl).
  */
+/**
+ * Renew the access token from the refresh token. Returns true on success.
+ *
+ * Two things this now does that it did not before, both for the same incident — a user back from a
+ * week away was shown "LevelCode Cloud API 401: Signature has expired" in the transcript while the
+ * account popover still said they were signed in:
+ *
+ *   1. It STORES the rotated refresh token the server now returns. Before, the editor kept the
+ *      refresh token from sign-in for its whole life, so the 30 days ran from the last sign-in rather
+ *      than the last use, and an active user was logged out on a schedule they could not see.
+ *   2. It knows the difference between "this attempt failed" and "the session is over". Only an
+ *      explicit 401 from the refresh endpoint is the latter; that ends the session (sessionExpired).
+ *      Offline, a 5xx, a malformed reply: nothing is known yet, so the tokens stay.
+ *
+ * And two things the wait in the middle demands. The request is out for as long as the network
+ * takes, and the rest of the editor does not stand still for it:
+ *
+ *   3. Its answer is about the session it STARTED against, and is applied to that one only.
+ *      Meanwhile the user can sign in again, or sign out. A late 401 must not delete the pair a
+ *      sign-in just stored; a late 200 must not sign someone back in, or file one account's tokens
+ *      under another's name. See sameSession().
+ *   4. It has a deadline, body included. `ready` waits on this before it restores the chat, so a
+ *      host that accepts the connection and then goes quiet would otherwise hold the transcript, the
+ *      config and the review controls behind it. Running out of time is (2)'s "this attempt failed".
+ *
+ * So "true" means: a usable access token is in place now — this refresh's, or a newer session's.
+ */
 async function refreshCloudToken() {
 	if (!ctx) { return false; }
 	const endpoint = cloudApiUrl();
 	if (!/^https:\/\//i.test(endpoint) && !/^http:\/\/(localhost|127\.0\.0\.1)([:/]|$)/i.test(endpoint)) { return false; }
-	const refresh = await ctx.secrets.get(ACCOUNT_REFRESH_KEY);
-	if (!refresh) { return false; }
+	// Never rejects. The stores can throw as well as the network (a locked keychain, say), and the
+	// callers are a webview's `ready`, a timer on window focus, and the 401 path of a request that is
+	// already in trouble — none of which can do anything with that except fail worse. It is one more
+	// way for this attempt to fail.
+	try { return await renewSession(endpoint); }
+	catch (e) { dbg('cloud.refresh', { error: String((e && e.message) || e) }); return false; }
+}
+
+/** refreshCloudToken's work, free to throw. */
+async function renewSession(endpoint) {
+	// Which session this request is about. Read under the lock, so never halfway through a sign-in.
+	const was = await withSessionLock(async () => ({ generation: sessionGeneration, refresh: await ctx.secrets.get(ACCOUNT_REFRESH_KEY) }));
+	if (!was.refresh) { return false; }
+	let outcome = 'retry';
+	/** @type {any} */
+	let data = null;
+	const ac = new AbortController();
+	const deadline = setTimeout(() => ac.abort(), session.REFRESH_TIMEOUT_MS);
 	try {
 		const res = await fetch(endpoint + '/api/levelcode/v1/auth/refresh', {
 			method: 'POST',
 			headers: { 'content-type': 'application/json' },
-			body: JSON.stringify({ refresh })
+			body: JSON.stringify({ refresh: was.refresh }),
+			signal: ac.signal
 		});
-		if (!res.ok) { dbg('cloud.refresh', { ok: false, status: res.status }); return false; }
-		const data = await res.json().catch(() => null);
-		const access = data && (data.access || data.token);
-		if (!access) { return false; }
-		await ctx.secrets.store(ACCOUNT_TOKEN_KEY, access);
-		dbg('cloud.refresh', { ok: true });
+		data = await res.json().catch(() => null);
+		outcome = session.classifyRefresh({ status: res.status, body: data });
+		dbg('cloud.refresh', { outcome, status: res.status, code: data && data.error && data.error.code });
+	} catch (e) { dbg('cloud.refresh', { error: String((e && e.message) || e) }); }
+	finally { clearTimeout(deadline); }   // only now: the deadline covers reading the body too
+	if (outcome === 'retry') { return false; }
+	if (outcome === 'expired') {
+		if (await sessionExpired(was)) { return false; }
+	} else {
+		const renewed = await withSessionLock(async () => {
+			if (!await sameSession(was)) { return false; }
+			await ctx.secrets.store(ACCOUNT_TOKEN_KEY, data.access || data.token);
+			if (data.refresh) { await ctx.secrets.store(ACCOUNT_REFRESH_KEY, data.refresh); }
+			return true;
+		});
+		if (renewed) { return true; }
+	}
+	// Not applied: the stored session is no longer the one this request was about — a sign-in, a
+	// sign-out, another refresh that finished first, or another window. What the caller needs is
+	// whether a token is in place to retry with.
+	const token = await storedToken();
+	dbg('cloud.refresh', { superseded: true, outcome, token: !!token });
+	if (!!token !== cloudSignedIn) { await catchUpWithStoredSession(token); }
+	return !!token;
+}
+
+/**
+ * The stored access token, read between session changes rather than in the middle of one. Every
+ * change this window makes moves the token and `cloudSignedIn` together inside the lock, so a token
+ * read this way that disagrees with the flag was changed by ANOTHER window.
+ */
+function storedToken() {
+	return withSessionLock(() => ctx.secrets.get(ACCOUNT_TOKEN_KEY));
+}
+
+/**
+ * The stored session belongs to every window, and a window only hears about the changes it makes
+ * itself. When what is stored stops matching what this window is showing, another window has signed
+ * out, signed in, or found the expiry — and a chat that is already open sends no second `ready` to
+ * notice. Bring this window level: the flag, the popover and footer, and the card. An expiry that
+ * is now waiting gets its card; if none is (the other window signed in), the account message takes
+ * a card that is still up back down.
+ * @param {string|undefined} token what SecretStorage holds now
+ */
+async function catchUpWithStoredSession(token) {
+	cloudSignedIn = !!token;
+	if (!token && sessionExpiredPending()) { postSessionExpired(); }
+	await postAccount(false);
+	sendConfigToWebview();
+}
+
+/**
+ * Every change to the stored session — a sign-in, a sign-out, a refresh's new tokens, an expiry —
+ * runs through here, one at a time.
+ *
+ * Each of them is several awaits long (two secrets and some globalState), and they are started by
+ * things that do not know about each other: the auth callback, a button, a timer on window focus.
+ * Without this, a sign-in could land between an expiry deciding "this is still the dead session" and
+ * its deletes, and lose the pair it had just stored. Nothing slow may run inside — above all not the
+ * network — and nothing inside may call this again.
+ */
+let sessionQueue = Promise.resolve();
+/** @template T @param {() => Promise<T>} fn @returns {Promise<T>} */
+function withSessionLock(fn) {
+	const run = sessionQueue.then(fn);
+	sessionQueue = run.then(() => { }, () => { });   // a failed change must not wedge the ones behind it
+	return run;
+}
+
+/** How many sessions this window has been through: a sign-in, a sign-out and an expiry each bump it. */
+let sessionGeneration = 0;
+
+/**
+ * Is the stored session still the one `was` describes? Call it INSIDE withSessionLock, immediately
+ * before acting on the answer.
+ *
+ * Two tests, because there are two ways for it to have changed. The generation counts what THIS
+ * window did, and under the lock it is exact. The refresh token itself catches what ANOTHER window
+ * did, which no counter in this process can see. That half is best-effort — another process can
+ * still write between this read and what follows — but it turns "any late answer" into
+ * "a few milliseconds".
+ */
+async function sameSession(was) {
+	return was.generation === sessionGeneration && await ctx.secrets.get(ACCOUNT_REFRESH_KEY) === was.refresh;
+}
+
+/**
+ * The cloud session `was` is over and cannot be renewed: forget its dead credentials, tell the
+ * webview, and resync the account popover so it stops claiming the user is signed in. Returns
+ * whether it ended anything — false when the stored session is no longer that one (see
+ * sameSession), in which case it touches nothing.
+ *
+ * The cached profile is deliberately KEPT — the sign-in card can say who it is talking to, and the
+ * next sign-in overwrites it anyway. What must go is anything the editor would otherwise keep
+ * presenting as a live session: the tokens, and the `cloudSignedIn` flag the footer and model gate
+ * read. A session ends once: a second caller holding the same dead session finds it already gone.
+ *
+ * It also leaves ACCOUNT_EXPIRED_KEY behind, because "the tokens are gone" says nothing afterwards:
+ * that is just as true of someone who signed out, or who never signed in. The marker is what
+ * records that a session ENDED here and the user has not answered it yet — sessionExpiredPending()
+ * has the two things that hang off it.
+ */
+async function sessionExpired(was) {
+	if (!ctx) { return false; }
+	const ended = await withSessionLock(async () => {
+		if (!await sameSession(was)) { return false; }
+		sessionGeneration++;
+		cloudSignedIn = false;
+		// Marker FIRST: if the editor dies between these writes, tokens-without-marker would read as an
+		// ordinary sign-out and the card would be lost; marker-with-tokens just finds the expiry again.
+		await ctx.globalState.update(ACCOUNT_EXPIRED_KEY, true);
+		await ctx.secrets.delete(ACCOUNT_TOKEN_KEY);
+		await ctx.secrets.delete(ACCOUNT_REFRESH_KEY);
 		return true;
-	} catch (e) { dbg('cloud.refresh', { error: String((e && e.message) || e) }); return false; }
+	});
+	if (!ended) { return false; }
+	const p = ctx.globalState.get(ACCOUNT_PROFILE_KEY) || {};
+	dbg('cloud.sessionExpired', { name: p.name || p.email || '' });
+	// In BYOK mode nothing the user is doing has stopped working, so there is no card to show — the
+	// popover going back to "signed out" is the whole of it. (The account message that follows would
+	// take the card straight down again anyway.) The marker is kept for if they return to gateway mode.
+	if (sessionExpiredPending()) { postSessionExpired(); }
+	await postAccount(false);
+	sendConfigToWebview();
+	return true;
+}
+
+/** Show the sign-in card. The profile outlives the session so the card can say who it is talking to. */
+function postSessionExpired() {
+	const p = (ctx && ctx.globalState.get(ACCOUNT_PROFILE_KEY)) || {};
+	post({ type: 'sessionExpired', name: p.name || '', message: session.SESSION_EXPIRED_MESSAGE });
+}
+
+/**
+ * True while an ended session is still waiting on the user: sessionExpired() left its marker, and
+ * nothing has answered it — a sign-in, a sign-out, or "use my own key" (clearSessionExpired).
+ *
+ * Everything about the sign-in card hangs off it, and each use needs more than "there is no token":
+ *
+ *   1. Showing it — replaySessionExpired. The session can end with no chat open to hear about it
+ *      (the focus check does not need one), and post() has nowhere to send the card.
+ *   2. Stopping a request to ask for a sign-in — prepProviderRequest. Gateway is the DEFAULT mode,
+ *      so "gateway mode, no token" describes everyone who uses LevelCode on their own key with no
+ *      account. Only a session that ended may stop a request; the rest fall back to BYOK, as the
+ *      setting promises.
+ *   3. Calling a failed request an expiry — isEndedSessionError. A 401 that lands after a
+ *      deliberate sign-out finds no session either, and is not one.
+ *   4. Taking it away — currentAccount reports it as `expired`, and the webview drops the card as
+ *      soon as that is false.
+ *
+ * Scoped to where the card can be acted on: gateway mode, with a host to sign in to. Leaving either
+ * (BYOK chosen in Settings, a cleared host) puts the expiry out of play WITHOUT answering it: the
+ * marker stays, and coming back brings the card back.
+ */
+function sessionExpiredPending() {
+	return !!(ctx && ctx.globalState.get(ACCOUNT_EXPIRED_KEY)) && providerMode() === 'gateway' && !!cloudEndpoint();
+}
+
+/**
+ * Is this failure the session having ENDED — the one failure that gets the sign-in card instead of
+ * its own message? Chat and the agent both ask it about a gateway 401 their refresh could not
+ * recover, and every clause is there for a case that looks the same without it:
+ *
+ *   - a gateway request: a BYOK provider's 401 is that provider's business;
+ *   - this window no longer signed in: a refresh that merely failed leaves the session alive;
+ *   - an expiry still waiting on the user: a 401 that lands after they signed OUT, mid-request,
+ *     finds the session gone as well — and "your session has expired" is the wrong thing to tell
+ *     someone who has just pressed Sign out;
+ *   - and the error being that 401 at all.
+ */
+function isEndedSessionError(req, e) {
+	return !!(req && req.gateway) && !cloudSignedIn && sessionExpiredPending() && session.isSessionExpiredError(e);
+}
+
+/** The user has answered the expiry, so stop asking: the marker goes. Unconditional — another window
+ *  may have set it, and this window's view of globalState can lag behind the write. */
+async function clearSessionExpired() {
+	if (ctx) { await ctx.globalState.update(ACCOUNT_EXPIRED_KEY, undefined); }
+}
+
+/**
+ * Put the card (back) in the transcript while the expiry is unanswered. Two kinds of caller:
+ *
+ *   - `ready`: a document that was not there to see the session end — the chat was closed, or it
+ *     has just moved to an editor tab. Called LAST there, so the card lands under a replayed
+ *     transcript instead of above it. When the check earlier in the same `ready` is what found the
+ *     expiry, this posts the card a second time; the webview keeps one, at the bottom.
+ *   - anything that rewrites the transcript IN PLACE, with no new `ready` to follow: New Chat and a
+ *     resumed session (both post `reset`, which empties the log) and a checkpoint restore (which
+ *     drops every node after the restored turn). Each takes the card with it, and the next message
+ *     would be stopped by an expiry nothing on screen mentions any more.
+ *
+ * Never rejects. It runs at the end of things that have already done their work — a resume, a
+ * restore — and a store that will not read is no reason to cut those short.
+ */
+async function replaySessionExpired() {
+	if (!sessionExpiredPending()) { return; }
+	try {
+		const token = await ctx.secrets.get(ACCOUNT_TOKEN_KEY);
+		// Asked AGAIN, because the answer can change while that read is out: "Use my own key instead"
+		// clears the marker, a Settings change takes the session out of play. Posting on the earlier
+		// answer would put back a card the user has just dismissed.
+		if (token || !sessionExpiredPending()) { return; }
+		dbg('cloud.sessionExpired.replay', {});
+		postSessionExpired();
+	} catch (e) { dbg('cloud.sessionExpired.replay', { error: String((e && e.message) || e) }); }
+}
+
+/**
+ * Check the session BEFORE the user types anything, so an expiry found on launch shows up as a
+ * sign-in card at the top of the chat rather than as the reply to their first message.
+ *
+ * Cheap by design: the access token's own `exp` is read locally and the network is only touched
+ * when it is expired or about to be. A session with hours left costs nothing here. Called on the
+ * webview's `ready` and again every time the window regains focus.
+ *
+ * Two halves. Catching up with the other windows is one local read, so it happens on every call.
+ * The half that can cost a request is rationed on focus. Never rejects: `ready` awaits this before
+ * it restores the chat.
+ */
+const SESSION_CHECK_EVERY_MS = 10 * 60 * 1000;
+let lastSessionCheck = 0;
+async function checkCloudSession(reason) {
+	if (!ctx || providerMode() !== 'gateway') { return; }
+	try {
+		const token = await storedToken();
+		// First, whether this window is still showing the session that is actually stored. On `ready`
+		// there is nothing to catch up on — the handler has just read the same token — and an expiry
+		// found while no chat was open is replayed LAST there, by replaySessionExpired(). On focus this
+		// is what tells an open chat that another window has ended, left or renewed the session.
+		if (!!token !== cloudSignedIn) { await catchUpWithStoredSession(token); }
+		if (!token) { return; }
+		// From here on it can cost a request, so focus gets a ration: a window clicked in and out of
+		// while offline must not retry the refresh on every click.
+		if (reason === 'focus' && Date.now() - lastSessionCheck <= SESSION_CHECK_EVERY_MS) { return; }
+		lastSessionCheck = Date.now();
+		if (!session.accessNeedsRefresh(token)) { return; }
+		dbg('cloud.sessionCheck', { reason, expiresAt: session.jwtExpiresAt(token) });
+		await refreshCloudToken();   // an expired refresh token lands in sessionExpired() from inside
+	} catch (e) { dbg('cloud.sessionCheck', { reason, error: String((e && e.message) || e) }); }
 }
 
 /** Gateway-mode token refresh (the streaming 401 retry path). Delegates to refreshCloudToken. */
@@ -379,7 +657,7 @@ async function refreshGatewayToken() {
  * Resolve everything needed to call the active provider: id, key, model, baseURL, maxTokens.
  * Returns { ok:false, reason } when a required key/baseURL is missing (after optional prompting) or
  * a custom endpoint would leak the key over plaintext — the caller renders providerErrorMessage().
- * @returns {Promise<{ok:boolean, providerId?:string, apiKey?:string, model?:string, baseURL?:string, maxTokens?:number, label?:string, reason?:string}>}
+ * @returns {Promise<{ok:boolean, providerId?:string, apiKey?:string, model?:string, baseURL?:string, maxTokens?:number, label?:string, reason?:string, gateway?:boolean}>}
  */
 async function prepProviderRequest(opts) {
 	const cfg = aiConfig();
@@ -387,6 +665,15 @@ async function prepProviderRequest(opts) {
 	// LevelCode Cloud metered gateway (an openai-kind endpoint) instead of the user's own provider/key. Falls
 	// back to the BYOK path below when signed out or in byok mode — the default is untouched.
 	const token = ctx ? await ctx.secrets.get(ACCOUNT_TOKEN_KEY) : null;
+	// No token in gateway mode is NOT, on its own, a reason to stop. Gateway is the default mode, so
+	// that describes everyone who uses LevelCode on their own key with no account, and they take the
+	// BYOK path below — "falls back to BYOK when you're signed out" is the setting's own promise.
+	// The exception is a session that ENDED and has not been answered: that user was on their plan a
+	// moment ago, and "No API key set for OpenAI" would send them hunting for a key they never needed.
+	// They get the sign-in card, until they sign in again or choose their own key.
+	if (!token && sessionExpiredPending()) {
+		return { ok: false, providerId: 'openai', label: 'LevelCode Cloud', reason: 'signedOut', gateway: true };
+	}
 	const gw = resolveGateway({ mode: providerMode(), endpoint: cloudApiUrl(), token: token || '' });
 	if (gw.use) {
 		if (!gw.ok) { return { ok: false, providerId: 'openai', label: 'LevelCode Cloud', reason: gw.reason }; }
@@ -1100,6 +1387,7 @@ async function resumeSession(id) {
 	if (lastUser) { lastAgentGoal = lastUser.text; }                        // keep Continue/Retry meaningful
 	post({ type: 'reset' });
 	post({ type: 'sessionResumed', id, title: (r.entry && r.entry.title) || 'Session', note: r.note || '', tier: r.plan && r.plan.tier, turns });
+	await replaySessionExpired();               // `reset` took the card; it goes back under the restored transcript
 	postContextFiles();
 	refreshSessions();                          // the resumed session bumps to the top — keep both surfaces current
 	focusChatView('resumeSession');
@@ -1184,6 +1472,7 @@ function newChat() {
 	post({ type: 'reset' });
 	postContextFiles();
 	postMemoryDigest();                    // the fresh empty state shows the welcome-back strip
+	replaySessionExpired();                // `reset` emptied the log, and an unanswered expiry's card with it
 }
 
 /** The currently open file as a context block (capped), or null. */
@@ -1299,6 +1588,7 @@ async function restoreCheckpoint(turnId) {
 	checkpoints.length = idx;                                              // drop restored + all later checkpoints (no redo)
 	dbg('checkpoint.restore', { turnId: turnId, files: restored, truncatedAt: cutIdx });
 	post({ type: 'checkpointRestored', turnId: turnId, filesRestored: restored });
+	await replaySessionExpired();   // the restore drops every node after this turn — the sign-in card among them
 }
 
 /** Pending in-chat approval requests, keyed by id, resolved by the webview. */
@@ -1633,7 +1923,7 @@ async function agentFlow(text, imageBlocks) {
 		return;
 	}
 	const req = await prepProviderRequest({ prompt: true });
-	if (!req.ok) { post({ type: 'agentError', message: providerErrorMessage(req) }); post({ type: 'agentDone', reason: 'error' }); return; }
+	if (!req.ok) { post({ type: 'agentError', message: providerErrorMessage(req), code: req.reason === 'signedOut' ? 'session_expired' : undefined }); post({ type: 'agentDone', reason: 'error' }); return; }
 
 	post({ type: 'agentStart' });
 	const epoch = conversationEpoch;   // this turn belongs to the conversation as it is RIGHT NOW
@@ -1702,6 +1992,12 @@ async function agentFlow(text, imageBlocks) {
 				if (!req.gateway) { return null; }
 				return (await refreshGatewayToken()) ? await ctx.secrets.get(ACCOUNT_TOKEN_KEY) : null;
 			},
+			// After refreshAuth has failed on a gateway 401, agent.js asks whether that was the session
+			// ending (→ it posts a sign-in card) or just an error. The refresh itself already ran
+			// sessionExpired() when the server said the refresh token was dead. The same question, asked
+			// the same way, as the chat path's — see isEndedSessionError.
+			isSessionExpired: (e) => isEndedSessionError(req, e),
+			sessionExpiredMessage: session.SESSION_EXPIRED_MESSAGE,
 			skills: skillsObj,                  // M6.5: implicit skills (name+desc menu in SYSTEM + use_skill resolver)
 			projectMemory: projectMemoryMarkdown(), // cross-session memory: a verify-first digest of past sessions, injected like project rules
 			// The recall_sessions tool: search past-session outcomes on demand. Off → the tool isn't offered at all.
@@ -1980,11 +2276,15 @@ async function handleSend(text, images) {
 	let assistant = '';
 	const onDelta = (d) => { assistant += d; post({ type: 'assistantDelta', text: d }); };
 
+	// Declared out here, not inside the try: the catch below reads it, and must be able to even when
+	// preparing the request is the thing that threw.
+	/** @type {Awaited<ReturnType<typeof prepProviderRequest>>} */
+	let req = { ok: false, gateway: false };
 	try {
-		const req = await prepProviderRequest({ prompt: true });
+		req = await prepProviderRequest({ prompt: true });
 		if (!req.ok) {
 			conversation.pop();
-			post({ type: 'assistantError', message: providerErrorMessage(req) });
+			post({ type: 'assistantError', message: providerErrorMessage(req), code: req.reason === 'signedOut' ? 'session_expired' : undefined });
 			return;
 		}
 		const doStream = (r) => providers.streamChat({
@@ -2014,7 +2314,18 @@ async function handleSend(text, images) {
 			post({ type: 'assistantDone' });
 		} else {
 			conversation.pop();
-			post({ type: 'assistantError', message: String((e && e.message) || e), code: e && e.code });
+			// A gateway 401 is a dead session only once the session has actually ENDED, and one place
+			// decides that: the refresh endpoint answering 401 (refreshCloudToken → sessionExpired, which
+			// is what clears cloudSignedIn). A 401 whose refresh merely failed — offline, a 5xx, a
+			// malformed reply — is this request failing, not the session: the tokens stay, the error is
+			// shown as the error it is, and the next message tries the refresh again. Ending the session
+			// from here would delete credentials classifyRefresh deliberately kept. The agent's
+			// isSessionExpired hook asks the same question: isEndedSessionError.
+			if (isEndedSessionError(req, e)) {
+				post({ type: 'assistantError', message: session.SESSION_EXPIRED_MESSAGE, code: 'session_expired' });
+			} else {
+				post({ type: 'assistantError', message: String((e && e.message) || e), code: e && e.code });
+			}
 		}
 	} finally {
 		// Only if this turn still owns it. A new turn may already have installed its own controller, and
@@ -2496,8 +2807,9 @@ class ChatViewProvider {
 		webview.onDidReceiveMessage(async (msg) => {
 			switch (msg.type) {
 				// `ready` is the earliest a freshly-loaded webview can hear anything, so it is also where a
-				// surface that just took over replays the conversation it inherited (openChatInEditor).
-				case 'ready': cloudSignedIn = !!(ctx && await ctx.secrets.get(ACCOUNT_TOKEN_KEY)); autopilot = aiConfig().get('agent.autopilot', false); sendConfigToWebview(); postActiveFile(); postContextFiles(); post({ type: 'mode', agent: agentMode }); post({ type: 'autopilot', on: autopilot }); postAccount(); buildFileIndex(); post({ type: 'contextUsage', input: 0, limit: currentContextLimit() }); if (review) { review.resync(); } postMemoryDigest(); if (pendingTranscriptReplay) { const t = pendingTranscriptReplay; pendingTranscriptReplay = ''; replayLiveTranscript(t); } break;
+				// surface that just took over replays the conversation it inherited (openChatInEditor) — and,
+				// after that, a session expiry this document was not there to see (replaySessionExpired).
+				case 'ready': cloudSignedIn = !!(ctx && await ctx.secrets.get(ACCOUNT_TOKEN_KEY)); await checkCloudSession('ready'); autopilot = aiConfig().get('agent.autopilot', false); sendConfigToWebview(); postActiveFile(); postContextFiles(); post({ type: 'mode', agent: agentMode }); post({ type: 'autopilot', on: autopilot }); postAccount(); buildFileIndex(); post({ type: 'contextUsage', input: 0, limit: currentContextLimit() }); if (review) { review.resync(); } postMemoryDigest(); if (pendingTranscriptReplay) { const t = pendingTranscriptReplay; pendingTranscriptReplay = ''; replayLiveTranscript(t); } await replaySessionExpired(); break;
 				case 'setMode': agentMode = !!msg.agent; post({ type: 'mode', agent: agentMode }); break;
 				case 'setAutopilot': autopilot = !!msg.on; aiConfig().update('agent.autopilot', autopilot, vscode.ConfigurationTarget.Global); dbg('autopilot.set', { on: autopilot }); post({ type: 'autopilot', on: autopilot }); break;
 				case 'send': await handleSend(msg.text, msg.images); break;
@@ -2528,6 +2840,10 @@ class ChatViewProvider {
 				case 'accountSignOut': await accountSignOut(); break;
 				case 'accountManage': await accountManage(); break;
 				case 'accountUpgrade': await openUpgrade(); break;
+				// The sign-in card's second button: the same setting the model picker's BYOK row opens.
+				// Choosing your own key ANSWERS the expiry, so the marker goes first — from the next message
+				// on this is an ordinary signed-out user, and gateway mode falls back to BYOK by itself.
+				case 'byokSettings': await clearSessionExpired(); vscode.commands.executeCommand('workbench.action.openSettings', 'levelcode.ai.providerMode'); break;
 				case 'openExternal': await openLegal(msg.target); break;
 				case 'copy': try { await vscode.env.clipboard.writeText(String(msg.text || '')); } catch (e) { /* clipboard unavailable */ } break;
 				case 'retry': if (lastAgentGoal && !abort) { dbg('retry', { goalChars: lastAgentGoal.length }); await agentFlow(lastAgentGoal); } break;
@@ -2764,6 +3080,7 @@ const ACCOUNT_TOKEN_KEY = 'levelcode.cloud.token';       // access token → Sec
 const ACCOUNT_REFRESH_KEY = 'levelcode.cloud.refresh';   // refresh token → SecretStorage (gateway silent renewal)
 const ACCOUNT_VERIFIER_KEY = 'levelcode.cloud.verifier'; // PKCE code_verifier → SecretStorage (per sign-in)
 const ACCOUNT_PROFILE_KEY = 'levelcode.cloud.profile';   // {name,email,plan} → globalState
+const ACCOUNT_EXPIRED_KEY = 'levelcode.cloud.sessionExpired';   // true while an ENDED session is unanswered → globalState
 
 /** base64url without padding — the encoding PKCE (RFC 7636) uses for both verifier and challenge. */
 function b64url(buf) { return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); }
@@ -2789,9 +3106,12 @@ async function currentAccount() {
 	cloudSignedIn = !!token;   // keep the footer/model gate in sync with the real session
 	if (token) {
 		const p = (ctx && ctx.globalState.get(ACCOUNT_PROFILE_KEY)) || {};
-		return { signedIn: true, mode, name: p.name || p.email || 'LevelCode user', email: p.email || '', plan: p.plan || '' };
+		return { signedIn: true, mode, expired: false, name: p.name || p.email || 'LevelCode user', email: p.email || '', plan: p.plan || '' };
 	}
-	return { signedIn: false, mode, status: cloudEndpoint() ? 'signedout' : 'unconfigured' };
+	// `expired`: an ended session is still waiting on the user. The webview keeps its sign-in card only
+	// while this says so — which is how the card leaves when the expiry is answered somewhere other
+	// than the card itself: switching to BYOK in Settings, or clearing the cloud host.
+	return { signedIn: false, mode, expired: sessionExpiredPending(), status: cloudEndpoint() ? 'signedout' : 'unconfigured' };
 }
 /**
  * Best-effort refresh of the cached profile (esp. `plan`) from the backend, so the free-tier lock /
@@ -2863,12 +3183,16 @@ async function accountSignIn(provider, create) {
 	await vscode.env.openExternal(vscode.Uri.parse(url));
 }
 async function accountSignOut() {
-	cloudSignedIn = false;
-	if (ctx) {
-		await ctx.secrets.delete(ACCOUNT_TOKEN_KEY);
-		await ctx.secrets.delete(ACCOUNT_REFRESH_KEY);
-		await ctx.globalState.update(ACCOUNT_PROFILE_KEY, undefined);
-	}
+	await withSessionLock(async () => {
+		sessionGeneration++;   // a refresh still out when this ran must not sign the user back in
+		cloudSignedIn = false;
+		if (ctx) {
+			await ctx.secrets.delete(ACCOUNT_TOKEN_KEY);
+			await ctx.secrets.delete(ACCOUNT_REFRESH_KEY);
+			await ctx.globalState.update(ACCOUNT_PROFILE_KEY, undefined);
+			await clearSessionExpired();   // signing out on purpose answers an expiry: no card, BYOK from here
+		}
+	});
 	dbg('account.signout');
 	await postAccount();
 }
@@ -2912,11 +3236,15 @@ async function webHandoffUrl() {
 /** Persist an editor session: access token (required), optional refresh token, and display profile. */
 async function storeSession(access, refresh, profile) {
 	if (!ctx || !access) { return; }
-	cloudSignedIn = true;
-	await ctx.secrets.store(ACCOUNT_TOKEN_KEY, access);
-	if (refresh) { await ctx.secrets.store(ACCOUNT_REFRESH_KEY, refresh); }
-	await ctx.globalState.update(ACCOUNT_PROFILE_KEY, {
-		name: (profile && profile.name) || '', email: (profile && profile.email) || '', plan: (profile && profile.plan) || ''
+	await withSessionLock(async () => {
+		sessionGeneration++;   // a refresh still out for the session this replaces must not touch the new one
+		await ctx.secrets.store(ACCOUNT_TOKEN_KEY, access);
+		if (refresh) { await ctx.secrets.store(ACCOUNT_REFRESH_KEY, refresh); }
+		cloudSignedIn = true;
+		await ctx.globalState.update(ACCOUNT_PROFILE_KEY, {
+			name: (profile && profile.name) || '', email: (profile && profile.email) || '', plan: (profile && profile.plan) || ''
+		});
+		await clearSessionExpired();   // signed in again: the expiry is answered
 	});
 }
 
@@ -2993,7 +3321,30 @@ async function openWorkspaceFile(rel) {
 	} catch (e) { dbg('openFile.error', { msg: String((e && e.message) || e) }); }
 }
 
+/**
+ * Settings changed. The routing mode and the cloud host decide whether a session is in play at all,
+ * so they resync the account popover — and with it the sign-in card, in BOTH directions. Leaving
+ * gateway mode (or clearing the host) answers an unanswered expiry as far as the screen goes: the
+ * account message says nothing is pending and the webview drops the card. Coming back puts the
+ * expiry back in force, and the card has to come back with it — otherwise the next message is
+ * stopped by something nothing on screen mentions.
+ */
+function onConfigChanged(e) {
+	if (e.affectsConfiguration('levelcode.ai')) { sendConfigToWebview(); }
+	if (e.affectsConfiguration('levelcode.ai.providerMode') || e.affectsConfiguration('levelcode.cloud')) {
+		postAccount();
+		replaySessionExpired();
+	}
+}
+
 function activate(context) {
+	// A window that comes back after a while away may have outlived its access token (8 h) — or
+	// another window may have ended, left or renewed the session they share. Re-check on every focus,
+	// so either is found before the next message rather than by it. The look is one local read;
+	// checkCloudSession rations the part that can cost a request.
+	context.subscriptions.push(vscode.window.onDidChangeWindowState((st) => {
+		if (st.focused) { checkCloudSession('focus'); }
+	}));
 	ctx = context;
 	// Constructed directly rather than by registerWebviewViewProvider: the chat is no longer a
 	// contributed view, but the panel still needs the one object that owns wire()/makeLive().
@@ -3063,10 +3414,7 @@ function activate(context) {
 		vscode.workspace.onDidDeleteFiles(scheduleFileIndex),
 		vscode.workspace.onDidRenameFiles(scheduleFileIndex),
 		vscode.workspace.onDidChangeWorkspaceFolders(scheduleFileIndex),
-		vscode.workspace.onDidChangeConfiguration((e) => {
-			if (e.affectsConfiguration('levelcode.ai')) { sendConfigToWebview(); }
-			if (e.affectsConfiguration('levelcode.ai.providerMode') || e.affectsConfiguration('levelcode.cloud')) { postAccount(); }
-		})
+		vscode.workspace.onDidChangeConfiguration(onConfigChanged)
 	);
 
 	// AI edit-with-diff (select code → instruct → review diff → apply) — provider-agnostic.
diff --git a/extensions/levelcode-ai/media/chat.html b/extensions/levelcode-ai/media/chat.html
index 06884cc..2f78a81 100644
--- a/extensions/levelcode-ai/media/chat.html
+++ b/extensions/levelcode-ai/media/chat.html
@@ -362,6 +362,8 @@
   .upgradecard .ucbtn.primary:hover { filter: brightness(1.1); }
   .upgradecard .ucbtn.ghost { background: transparent; border: 1px solid var(--border); color: var(--vscode-foreground); }
   .upgradecard .ucbtn.ghost:hover { background: var(--vscode-toolbar-hoverBackground, rgba(127,127,127,.14)); }
+  /* session expired — the upgrade card's shape, because it too ends in one button the user wants to press */
+  .sessioncard .uchead .ci { color: var(--accent); }
   /* our-side outage notice — neutral, NO accent, NO CTA (it is not the user's account/usage) */
   .noticecard { border: 1px solid var(--border); border-radius: 12px; margin: 8px 2px; padding: 13px 15px 14px; background: var(--field-bg); }
   .noticecard .uchead { display: flex; align-items: center; gap: 8px; font-size: 13px; font-weight: 600; margin-bottom: 6px; }
@@ -2733,6 +2735,32 @@
     log.appendChild(card); scrollIfStuck();
     card.querySelectorAll('[data-act]').forEach((b) => { b.onclick = () => vscode.postMessage({ type: 'accountUpgrade' }); });
   }
+  // The cloud session is over (the refresh token expired — 30 days without use, or a sign-out
+  // elsewhere). This is the ONE failure the user can fix in a click, so it gets a button, not red
+  // text: the raw "API 401: Signature has expired" this replaces told them nothing about what to do,
+  // while the account popover beside it still said they were signed in.
+  function isSessionExpired(m){ return !!(m && m.code === 'session_expired'); }
+  let sessionCard = null;
+  function addSignInCard(m){
+    clearStatus(); finishAgentBubble(); closeGroup();
+    if (sessionCard && sessionCard.isConnected){ sessionCard.remove(); }   // one card, however many paths find the expiry
+    const who = m && m.name ? 'Welcome back, ' + esc(m.name) + '.' : '';
+    const card = document.createElement('div'); card.className = 'upgradecard sessioncard';
+    card.innerHTML =
+      '<div class="uchead">' + codicon('shield') + '<span>Your session has expired</span></div>'
+      + '<div class="ucbody">' + (who ? who + ' ' : '') + 'Sign in again to keep using LevelCode Cloud — your chat and files here are untouched.</div>'
+      + '<div class="ucbtns"><button class="ucbtn primary" data-act="signin">Sign in</button>'
+      + '<button class="ucbtn ghost" data-act="byok">Use my own key instead</button></div>';
+    log.appendChild(card); scrollIfStuck();
+    card.querySelector('[data-act="signin"]').onclick = () => vscode.postMessage({ type: 'accountSignIn' });
+    // Choosing your own key answers the expiry — the host stops asking — so the card goes too,
+    // rather than sitting in the transcript offering a sign-in nobody is waiting on.
+    card.querySelector('[data-act="byok"]').onclick = () => {
+      vscode.postMessage({ type: 'byokSettings' });
+      card.remove(); if (sessionCard === card){ sessionCard = null; }
+    };
+    sessionCard = card;
+  }
   // Our-side outage / transient issue → a neutral "service" notice, NOT the red error and NOT the
   // upgrade card (the gateway already sanitized the message; this just picks a calmer presentation).
   function isServiceIssue(m){
@@ -4121,7 +4149,8 @@
     else if (m.type === 'assistantError'){
       pending = ''; flushAll = false; doneSignaled = false;
       const cap = capReachedInfo(m.message);
-      if (cap){ current = null; addUpgradeCard(cap); }
+      if (isSessionExpired(m)){ current = null; addSignInCard(m); }
+      else if (cap){ current = null; addUpgradeCard(cap); }
       else if (isServiceIssue(m)){ current = null; addServiceCard(m); }
       else {
         const html = '<span class="err">' + esc(m.message) + '</span>';
@@ -4130,6 +4159,7 @@
       }
       setStreaming(false);
     }
+    else if (m.type === 'sessionExpired'){ addSignInCard(m); }
     else if (m.type === 'activeFile'){ activeFileLabel = m.label; renderChips(); }
     else if (m.type === 'contextFiles'){ ctxFiles = m.files || []; renderChips(); }
     else if (m.type === 'autoContext'){ addAutoCtx(m.names); }
@@ -4167,9 +4197,14 @@
     else if (m.type === 'compactStart'){ ctxCompact = 'busy'; renderCtxCard(); }
     else if (m.type === 'compactResult'){ onCompactResult(m); }
     else if (m.type === 'debug'){ addDebug(m); }
-    else if (m.type === 'account'){ renderAccount(m); if (m.open) openAccount(); }
+    else if (m.type === 'account'){
+      // The sign-in card stays only while the host says an expiry is still waiting (m.expired).
+      // Signing in answers it; so does anything that takes the session out of play — BYOK mode
+      // chosen in Settings, or no cloud host to sign in to. Requests run on the user's own key by
+      // then, so a card still asking them to sign in would be wrong.
+      if (!m.expired && sessionCard && sessionCard.isConnected){ sessionCard.remove(); sessionCard = null; } renderAccount(m); if (m.open) openAccount(); }
     else if (m.type === 'fileIndex'){ setFileIndex(m.files || []); }
-    else if (m.type === 'agentError'){ clearStatus(); finishAgentBubble(); closeGroup(); const cap = capReachedInfo(m.message); if (cap){ addUpgradeCard(cap); } else if (isServiceIssue(m)){ addServiceCard(m); } else { add('assistant', '<span class="err">' + esc(m.message) + '</span>'); } }
+    else if (m.type === 'agentError'){ clearStatus(); finishAgentBubble(); closeGroup(); const cap = capReachedInfo(m.message); if (isSessionExpired(m)){ addSignInCard(m); } else if (cap){ addUpgradeCard(cap); } else if (isServiceIssue(m)){ addServiceCard(m); } else { add('assistant', '<span class="err">' + esc(m.message) + '</span>'); } }
     else if (m.type === 'agentDone'){ clearStatus(); finishAgentBubble(); addAgentDone(m.reason, m.edits, m.credits, m.maxSteps, m.costMicros); setStreaming(false); }
     else if (m.type === 'context'){ selLabel = m.label; renderChips(); }
     else if (m.type === 'clearContext'){ selLabel = null; renderChips(); }
diff --git a/extensions/levelcode-ai/providers/session.js b/extensions/levelcode-ai/providers/session.js
new file mode 100644
index 0000000..94f04c7
--- /dev/null
+++ b/extensions/levelcode-ai/providers/session.js
@@ -0,0 +1,100 @@
+/*---------------------------------------------------------------------------------------------
+ *  LevelCode — AI · LevelCode Cloud session state (pure)
+ *
+ *  The editor keeps two credentials for the cloud: a short-lived access token (8 h) and a refresh
+ *  token (30 days, rotated on use). Everything here is the arithmetic and classification around
+ *  them — no VS Code, no IO — so it can be unit-tested (test/session.test.js) and so the host can
+ *  answer "is this session still alive?" WITHOUT a network round-trip, by reading the access
+ *  token's own `exp` claim. A JWT's payload is plain base64url JSON; reading it is not verifying it
+ *  (the server does that), it is only asking the token when it says it dies.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+/** Refresh this far ahead of expiry, so a request issued right now cannot land after the deadline. */
+const EXPIRY_MARGIN_MS = 5 * 60 * 1000;
+
+/**
+ * How long the whole refresh exchange may take — connecting, the headers AND the body. The webview's
+ * `ready` waits on a refresh before it restores the chat, so this is how long a host that accepts the
+ * connection and then says nothing can hold that up. Running out of it is "this attempt failed",
+ * never "the session is over".
+ */
+const REFRESH_TIMEOUT_MS = 10 * 1000;
+
+/** The sentence shown when the session is gone. Mirrors the server's own wording. */
+const SESSION_EXPIRED_MESSAGE = 'Your LevelCode Cloud session has expired. Sign in again to continue.';
+
+/**
+ * The `exp` claim of a JWT as epoch milliseconds, or null when the token is not a JWT, carries no
+ * `exp`, or is unreadable. Never throws: a malformed token is a reason to re-check with the server,
+ * not a reason to crash the editor.
+ * @param {string|null|undefined} token
+ * @returns {number|null}
+ */
+function jwtExpiresAt(token) {
+	try {
+		const parts = String(token || '').split('.');
+		if (parts.length !== 3) { return null; }
+		const b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+		const payload = JSON.parse(Buffer.from(b64 + '='.repeat((4 - b64.length % 4) % 4), 'base64').toString('utf8'));
+		const exp = Number(payload && payload.exp);
+		return Number.isFinite(exp) && exp > 0 ? exp * 1000 : null;
+	} catch { return null; }
+}
+
+/**
+ * Whether an access token should be refreshed before use: it expires within the margin, has
+ * already expired, or cannot be read at all (an unreadable token is treated as expired — the
+ * server would reject it anyway, and asking first is cheaper than a failed request).
+ * @param {string|null|undefined} token
+ * @param {number} [nowMs]
+ */
+function accessNeedsRefresh(token, nowMs = Date.now()) {
+	const exp = jwtExpiresAt(token);
+	return exp === null || exp - nowMs <= EXPIRY_MARGIN_MS;
+}
+
+/**
+ * Classify the outcome of POST /auth/refresh so the caller knows whether the SESSION is over, or
+ * only this attempt failed.
+ *
+ *   'ok'      — a new access token was issued
+ *   'expired' — the server rejected the refresh token itself (401): the session is over, sign in again
+ *   'retry'   — anything else: offline, 5xx, a malformed reply. Keep the tokens; nothing is known yet.
+ *
+ * Only an explicit 401 ends the session. Clearing credentials on a network blip would log a user
+ * out for closing their laptop on the train.
+ *
+ * And 'ok' means the reply can be STORED as it stands, not merely that it was a 2xx with something
+ * in the right field. The tokens go into SecretStorage, which takes strings: `{ access: {} }` would
+ * throw on the way in, and `{ access: 'a', refresh: {} }` would throw after the access token had
+ * already been replaced. Either is a malformed reply — "nothing is known yet" — and the credentials
+ * in hand are still the best ones available. The refresh token is optional (a server that does not
+ * rotate sends none); when one is present it has to be usable too.
+ * @param {{status?:number, body?:any}|null|undefined} res
+ * @returns {'ok'|'expired'|'retry'}
+ */
+function classifyRefresh(res) {
+	if (!res) { return 'retry'; }
+	if (res.status === 401) { return 'expired'; }
+	if (!(res.status >= 200 && res.status < 300) || !res.body) { return 'retry'; }
+	const isToken = (v) => typeof v === 'string' && v.length > 0;
+	if (!isToken(res.body.access || res.body.token)) { return 'retry'; }   // the one the host will store
+	if (res.body.refresh && !isToken(res.body.refresh)) { return 'retry'; }
+	return 'ok';
+}
+
+/**
+ * True when a provider error means the cloud session is dead — a gateway 401 that a refresh could
+ * not recover. The adapter formats failures as `<label> API <status>: <detail>`; the server's own
+ * codes (`token_expired`, `refresh_expired`) are matched too so a structured body is not needed.
+ * @param {any} e
+ */
+function isSessionExpiredError(e) {
+	const status = e && e.status;
+	const msg = String((e && e.message) || e || '');
+	return status === 401 || /\bAPI 401\b|token_expired|refresh_expired|signature has expired/i.test(msg);
+}
+
+module.exports = { EXPIRY_MARGIN_MS, REFRESH_TIMEOUT_MS, SESSION_EXPIRED_MESSAGE, jwtExpiresAt, accessNeedsRefresh, classifyRefresh, isSessionExpiredError };
diff --git a/extensions/levelcode-ai/test/session.test.js b/extensions/levelcode-ai/test/session.test.js
new file mode 100644
index 0000000..770b89c
--- /dev/null
+++ b/extensions/levelcode-ai/test/session.test.js
@@ -0,0 +1,115 @@
+/*---------------------------------------------------------------------------------------------
+ *  Unit tests for providers/session.js (pure) — run: node test/session.test.js
+ *    - jwtExpiresAt: reads `exp` off a JWT payload without verifying; never throws
+ *    - accessNeedsRefresh: the 5-minute margin, expired, unreadable
+ *    - classifyRefresh: ONLY a 401 ends the session; offline/5xx keep the tokens; a 2xx is a
+ *      renewal only when what it carries can be stored
+ *    - isSessionExpiredError: the shapes a dead session arrives in
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const S = require('../providers/session');
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+/** An unsigned JWT with the given payload — the shape is all jwtExpiresAt reads. */
+function jwt(payload) {
+	const b64 = (o) => Buffer.from(JSON.stringify(o)).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+	return b64({ alg: 'HS256', typ: 'JWT' }) + '.' + b64(payload) + '.sig';
+}
+
+const NOW = 1_800_000_000_000;   // fixed "now" so the margin arithmetic is exact
+
+test('jwtExpiresAt: reads exp (seconds) as epoch milliseconds', () => {
+	assert.strictEqual(S.jwtExpiresAt(jwt({ sub: 1, exp: 1_800_000_123 })), 1_800_000_123_000);
+});
+test('jwtExpiresAt: survives base64url padding edge cases (payload lengths mod 4)', () => {
+	for (const pad of ['', 'x', 'xy', 'xyz']) {
+		assert.strictEqual(S.jwtExpiresAt(jwt({ p: pad, exp: 7 })), 7000, 'pad=' + JSON.stringify(pad));
+	}
+});
+test('jwtExpiresAt: null for a non-JWT, a JWT without exp, garbage, and nothing — never throws', () => {
+	assert.strictEqual(S.jwtExpiresAt('opaque-token'), null);
+	assert.strictEqual(S.jwtExpiresAt(jwt({ sub: 1 })), null);
+	assert.strictEqual(S.jwtExpiresAt('a.!!!.c'), null);
+	assert.strictEqual(S.jwtExpiresAt(''), null);
+	assert.strictEqual(S.jwtExpiresAt(null), null);
+	assert.strictEqual(S.jwtExpiresAt(undefined), null);
+});
+
+test('accessNeedsRefresh: a token with hours left does not', () => {
+	assert.strictEqual(S.accessNeedsRefresh(jwt({ exp: NOW / 1000 + 3600 }), NOW), false);
+});
+test('accessNeedsRefresh: inside the 5-minute margin, at the margin, and already expired all do', () => {
+	assert.strictEqual(S.accessNeedsRefresh(jwt({ exp: NOW / 1000 + 299 }), NOW), true);
+	assert.strictEqual(S.accessNeedsRefresh(jwt({ exp: NOW / 1000 + 300 }), NOW), true);
+	assert.strictEqual(S.accessNeedsRefresh(jwt({ exp: NOW / 1000 - 1 }), NOW), true);
+	assert.strictEqual(S.accessNeedsRefresh(jwt({ exp: NOW / 1000 + 301 }), NOW), false);
+});
+test('accessNeedsRefresh: an unreadable token is treated as expired (ask the server, do not guess)', () => {
+	assert.strictEqual(S.accessNeedsRefresh('opaque', NOW), true);
+	assert.strictEqual(S.accessNeedsRefresh('', NOW), true);
+});
+
+test('classifyRefresh: 200 with an access token → ok', () => {
+	assert.strictEqual(S.classifyRefresh({ status: 200, body: { access: 'a' } }), 'ok');
+	assert.strictEqual(S.classifyRefresh({ status: 200, body: { token: 'a' } }), 'ok');   // legacy field name
+});
+test('classifyRefresh: ONLY an explicit 401 ends the session', () => {
+	assert.strictEqual(S.classifyRefresh({ status: 401, body: { error: { code: 'refresh_expired' } } }), 'expired');
+	assert.strictEqual(S.classifyRefresh({ status: 401, body: null }), 'expired');
+});
+test('classifyRefresh: offline, 5xx, 403, a 200 with no token, nothing at all → retry (tokens kept)', () => {
+	assert.strictEqual(S.classifyRefresh(null), 'retry');
+	assert.strictEqual(S.classifyRefresh({ status: 503, body: null }), 'retry');
+	assert.strictEqual(S.classifyRefresh({ status: 500, body: {} }), 'retry');
+	assert.strictEqual(S.classifyRefresh({ status: 403, body: {} }), 'retry');
+	assert.strictEqual(S.classifyRefresh({ status: 200, body: {} }), 'retry');
+	assert.strictEqual(S.classifyRefresh({ status: 200, body: null }), 'retry');
+});
+
+test('classifyRefresh: a 2xx whose access token is not a usable string is NOT a renewal', () => {
+	for (const access of [{}, [], ['a'], 123, true]) {
+		assert.strictEqual(S.classifyRefresh({ status: 200, body: { access } }), 'retry', 'access=' + JSON.stringify(access));
+	}
+	assert.strictEqual(S.classifyRefresh({ status: 200, body: { token: {} } }), 'retry', 'the legacy field too');
+	// The host stores `access || token`, so that is the one judged: a broken `access` is not rescued by a
+	// good `token` beside it, and an EMPTY `access` falls through to `token` exactly as the store would.
+	assert.strictEqual(S.classifyRefresh({ status: 200, body: { access: {}, token: 'legacy' } }), 'retry');
+	assert.strictEqual(S.classifyRefresh({ status: 200, body: { access: '', token: 'legacy' } }), 'ok');
+});
+test('classifyRefresh: a refresh token, when one is sent, has to be a usable string too', () => {
+	for (const refresh of [{}, [], ['r'], 123, true]) {
+		assert.strictEqual(S.classifyRefresh({ status: 200, body: { access: 'a', refresh } }), 'retry', 'refresh=' + JSON.stringify(refresh));
+	}
+});
+test('classifyRefresh: no refresh token is still ok — a server that does not rotate sends none', () => {
+	for (const body of [{ access: 'a' }, { access: 'a', refresh: null }, { access: 'a', refresh: '' }, { access: 'a', refresh: 'r' }, { token: 'a', refresh: 'r' }]) {
+		assert.strictEqual(S.classifyRefresh({ status: 200, body }), 'ok', JSON.stringify(body));
+	}
+});
+
+test('isSessionExpiredError: the adapter\'s "<label> API 401: …" shape, with and without e.status', () => {
+	const e = new Error('LevelCode Cloud API 401: Your LevelCode Cloud session has expired. Sign in again to continue.');
+	assert.strictEqual(S.isSessionExpiredError(e), true);
+	// @ts-ignore
+	e.status = 401; assert.strictEqual(S.isSessionExpiredError(e), true);
+	assert.strictEqual(S.isSessionExpiredError({ status: 401 }), true);
+});
+test('isSessionExpiredError: the server codes and the old raw JWT text, as bare strings', () => {
+	assert.strictEqual(S.isSessionExpiredError('token_expired'), true);
+	assert.strictEqual(S.isSessionExpiredError('refresh_expired'), true);
+	assert.strictEqual(S.isSessionExpiredError('Signature has expired'), true);
+});
+test('isSessionExpiredError: a 402 cap hit, a 500, a 4010-byte message, nothing → not a dead session', () => {
+	assert.strictEqual(S.isSessionExpiredError(new Error('LevelCode Cloud API 402: {"error":{"code":"cap_reached"}}')), false);
+	assert.strictEqual(S.isSessionExpiredError(new Error('LevelCode Cloud API 500: upstream')), false);
+	assert.strictEqual(S.isSessionExpiredError(new Error('read 4010 bytes')), false);
+	assert.strictEqual(S.isSessionExpiredError(null), false);
+	assert.strictEqual(S.isSessionExpiredError(undefined), false);
+});
+
+console.log('\nsession: ' + n + ' tests passed.');
diff --git a/extensions/levelcode-ai/test/sessionExpiredHost.test.js b/extensions/levelcode-ai/test/sessionExpiredHost.test.js
new file mode 100644
index 0000000..8952a0f
--- /dev/null
+++ b/extensions/levelcode-ai/test/sessionExpiredHost.test.js
@@ -0,0 +1,1035 @@
+/*---------------------------------------------------------------------------------------------
+ *  Behaviour of the cloud-session code in extension.js — run: node test/sessionExpiredHost.test.js
+ *
+ *  sessionExpiredUi.test.js pins strings; this RUNS the code. The difference is why it exists: the
+ *  first version of this change read `req` in a catch that could not see it, so every failed chat
+ *  request threw a ReferenceError instead of showing an error — and every string guard passed,
+ *  because the strings were all there. What is pinned here is what the user gets:
+ *
+ *    - a failed chat request is an error in the transcript, never an exception
+ *    - a refresh that merely FAILED (offline, 5xx, a malformed reply) keeps the session; only the
+ *      refresh endpoint answering 401 ends it
+ *    - an expiry found while no chat was open is shown by the next webview to load, and keeps
+ *      being shown until the user answers it: signs in, signs out, or picks their own key
+ *    - gateway is the DEFAULT mode, so "no token" still means BYOK for everyone who never had a
+ *      session — only an ENDED session may stop a request and ask for a sign-in
+ *    - a refresh's answer belongs to the session it started against: one that arrives after a
+ *      sign-in or a sign-out changes nothing, and the request itself cannot outlast its deadline
+ *    - New Chat, a resumed session and a checkpoint restore rewrite the transcript in place; the
+ *      card they take with them is put back
+ *    - a sign-out is not an expiry, even with a 401 still in the air — in chat, and through the
+ *      real agent loop
+ *    - the account message tells the webview whether an expiry is still waiting, so the card leaves
+ *      when BYOK is chosen in Settings and comes back if gateway mode is
+ *    - a 2xx refresh reply that cannot be stored changes nothing, and nothing escapes into `ready`
+ *    - the replay asks whether an expiry is waiting AFTER its read, not only before it
+ *    - a window catches up with a session another window ended, left or renewed — on every focus
+ *
+ *  The functions are sliced out of the shipped extension.js and run against stand-ins for what they
+ *  touch (SecretStorage, globalState, fetch, the provider adapter), the way mcpManage.test.js does
+ *  it: extension.js requires `vscode` at load, and a copy here would be a test of the copy.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const session = require('../providers/session');
+const { resolveGateway, GATEWAY_PATH } = require('../providers/gateway');
+
+// The agent loop is NOT sliced: agent.js loads whole once `vscode` resolves to something, the way
+// workspacePaths.test.js loads it, so the agent cases below run the shipped loop end to end. No
+// folder is open, which is a state it supports.
+const Module = require('module');
+const loadModule = Module._load;
+// @ts-ignore — test-only loader shim
+Module._load = function (request, parent, isMain) {
+	if (request === 'vscode') { return { workspace: { workspaceFolders: undefined }, env: { appRoot: '' }, Uri: { file: (p) => ({ fsPath: p }) } }; }
+	return loadModule.call(this, request, parent, isMain);
+};
+const agentProviders = require('../providers/index');
+const { runAgent } = require('../agent');
+
+// Nothing here may reach the network. The host functions are handed a stand-in fetch, and the agent
+// loop's provider call is replaced before every run — but if a refactor ever routed around either,
+// the suite would send a made-up token to a real gateway and call the 401 it got back a pass. So
+// the real fetch is taken away: a stray request fails here, by name.
+global.fetch = async (url) => { throw new Error('sessionExpiredHost.test.js must not touch the network: ' + String((url && url.url) || url)); };
+
+const src = fs.readFileSync(path.join(__dirname, '..', 'extension.js'), 'utf8');
+
+// Slice a top-level `[async] function <name>(...) {…}` out of the source by matching its braces,
+// skipping the ones inside strings and comments (see mcpManage.test.js for why not "first `\n}`").
+function extract(name) {
+	let start = src.indexOf('function ' + name + '(');
+	assert.ok(start >= 0, 'extension.js no longer defines ' + name + '()');
+	const open = src.indexOf('{', start);
+	if (src.slice(start - 6, start) === 'async ') { start -= 6; }
+	let depth = 0, str = '', comment = '';
+	for (let i = open; i < src.length; i++) {
+		const ch = src[i], next = src[i + 1];
+		if (comment === 'line') { if (ch === '\n') { comment = ''; } continue; }
+		if (comment === 'block') { if (ch === '*' && next === '/') { comment = ''; i++; } continue; }
+		if (str) {
+			if (ch === '\\') { i++; }
+			else if (ch === str) { str = ''; }
+			continue;
+		}
+		if (ch === '/' && next === '/') { comment = 'line'; i++; continue; }
+		if (ch === '/' && next === '*') { comment = 'block'; i++; continue; }
+		if (ch === '"' || ch === "'" || ch === '`') { str = ch; continue; }
+		if (ch === '{') { depth++; }
+		else if (ch === '}' && --depth === 0) { return src.slice(start, i + 1); }
+	}
+	assert.fail('no matching closing brace found for ' + name + '()');
+}
+
+/** A one-line top-level declaration, taken from the source so the keys here cannot drift from the real ones. */
+function decl(name) {
+	const m = new RegExp('^(?:const|let) ' + name + ' = [^;\\n]*;', 'm').exec(src);
+	assert.ok(m, 'extension.js no longer declares ' + name);
+	return m[0];
+}
+
+const FUNCTIONS = [
+	'post', 'providerMode', 'providerErrorMessage', 'isAuthError', 'cloudEndpoint', 'cloudApiUrl',
+	'refreshCloudToken', 'renewSession', 'storedToken', 'catchUpWithStoredSession', 'withSessionLock', 'sameSession', 'sessionExpired', 'postSessionExpired',
+	'sessionExpiredPending', 'isEndedSessionError', 'clearSessionExpired', 'replaySessionExpired', 'checkCloudSession',
+	'refreshGatewayToken', 'prepProviderRequest', 'handleSend', 'currentAccount', 'postAccount', 'accountSignOut',
+	'storeSession', 'newChat', 'resumeSession', 'restoreCheckpoint', 'onConfigChanged'
+];
+// eslint-disable-next-line no-new-func
+const makeHost = new Function('env', [
+	"'use strict';",
+	'const { vscode, session, providers, resolveGateway, fetch, ctx, dbg, aiConfig, refreshCloudProfile, fetchCloudRoster, sendConfigToWebview,',
+	'  gatewayModel, maxOutputTokens, currentProviderId, baseUrlFor, getProviderKey, activeModel, storeImages, agentFlow,',
+	'  listWorkspaceFiles, workspaceMapBlock, activeFileBlock, contextFileBlocks, gatherAutoContext, labelImages, withImages,',
+	'  sealLiveSession, resetConversationState, postContextFiles, postMemoryDigest, sessionsManager, currentContextLimit,',
+	'  refreshSessions, focusChatView, review, checkpoints } = env;',
+	"const SYSTEM_PROMPT = 'system';",
+	'let activeWebview = env.webview, cloudSignedIn = env.signedIn, agentMode = false, conversation = [], pendingContext = null, conversationEpoch = 0, abort = null;',
+	'let agentMessages = [], currentCheckpoint = null, lastAgentGoal = null;',
+	decl('ACCOUNT_TOKEN_KEY'), decl('ACCOUNT_REFRESH_KEY'), decl('ACCOUNT_PROFILE_KEY'), decl('ACCOUNT_EXPIRED_KEY'),
+	decl('sessionQueue'), decl('sessionGeneration'), decl('SESSION_CHECK_EVERY_MS'), decl('lastSessionCheck'),
+	...FUNCTIONS.map(extract),
+	'return { ' + FUNCTIONS.join(', ') + ',',
+	'  KEY: { token: ACCOUNT_TOKEN_KEY, refresh: ACCOUNT_REFRESH_KEY, profile: ACCOUNT_PROFILE_KEY, expired: ACCOUNT_EXPIRED_KEY },',
+	'  signedIn: () => cloudSignedIn, conversation: () => conversation, abort: () => abort,',
+	'  openWebview: (w) => { activeWebview = w; }, setAgentMessages: (m) => { agentMessages = m; } };'
+].join('\n'));
+
+// The defaults a fresh install runs with come from package.json, not from this file: the whole
+// point of the BYOK cases below is what happens to someone who has changed nothing.
+const pkg = require('../package.json');
+const settingDefaults = Object.assign({}, ...[].concat(pkg.contributes.configuration).map((c) => c.properties || {}));
+function shippedDefault(key) { return settingDefaults[key] ? settingDefaults[key].default : undefined; }
+
+/** An unsigned JWT with the given payload — its `exp` is all the host reads. */
+function jwt(payload) {
+	const b64 = (o) => Buffer.from(JSON.stringify(o)).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+	return b64({ alg: 'HS256', typ: 'JWT' }) + '.' + b64(payload) + '.sig';
+}
+const HOUR = 3600;
+const now = () => Math.floor(Date.now() / 1000);
+const liveAccess = () => jwt({ sub: 1, exp: now() + 8 * HOUR });
+const deadAccess = () => jwt({ sub: 1, exp: now() - HOUR });
+
+/** The gateway's answer to an expired access token, as the openai adapter throws it. */
+const gateway401 = () => new Error('LevelCode Cloud API 401: {"error":{"code":"token_expired","message":"Your LevelCode Cloud session has expired. Sign in again to continue."}}');
+
+/** One turn of the event loop — what every SecretStorage / globalState call costs in the editor. */
+const tick = () => new Promise((resolve) => setImmediate(resolve));
+/** Let everything already in motion finish. */
+async function settle() { for (let i = 0; i < 25; i++) { await tick(); } }
+/** Wait for something the host is doing in the background; fail rather than spin if it never happens. */
+async function until(cond, what) {
+	for (let i = 0; i < 200; i++) { if (cond()) { return; } await tick(); }
+	assert.fail('never happened: ' + what);
+}
+/** A reply that arrives when the test says so. */
+function deferred() { let resolve; const promise = new Promise((r) => { resolve = r; }); return { promise, resolve }; }
+/** Fail loudly, instead of hanging the suite, when something that must finish does not. */
+function within(promise, ms, what) {
+	let timer;
+	const late = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(what + ' did not finish within ' + ms + ' ms')), ms); });
+	return Promise.race([promise, late]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * One editor window: the sliced host functions wired to in-memory stand-ins.
+ *   settings      — overrides on top of the shipped defaults (`null` unsets one)
+ *   access/refresh/profile/expired — what SecretStorage and globalState hold at the start
+ *   byokKey       — the user's own provider key ('' = none saved); t.keyError makes the lookup throw
+ *   webview       — false to start with the chat closed
+ *   refreshTimeoutMs — the refresh deadline, so a test of it need not take ten seconds
+ *
+ * The stores answer a turn of the event loop LATER, as the real ones do: every call to them is a
+ * round trip to another process. That gap is where two session changes can interleave, so a
+ * stand-in that answered at once would hide exactly what the lock is for. And SecretStorage takes
+ * strings only, as the real one does — handing it anything else is a rejection, not a quiet write.
+ */
+function boot(over) {
+	const o = Object.assign({ settings: {}, access: null, refresh: null, profile: null, expired: false, byokKey: '', webview: true, refreshTimeoutMs: 0 }, over);
+	const settings = {
+		'levelcode.ai.providerMode': shippedDefault('levelcode.ai.providerMode'),
+		'levelcode.cloud.endpoint': shippedDefault('levelcode.cloud.endpoint'),
+		'levelcode.ai.chat.autoContext': false, 'levelcode.ai.chat.workspaceMap': false
+	};
+	for (const k of Object.keys(o.settings)) { if (o.settings[k] === null) { delete settings[k]; } else { settings[k] = o.settings[k]; } }
+
+	const secrets = new Map(), state = new Map(), posted = [], ops = [];
+	const calls = { refresh: [], stream: [], keyPrompts: 0 };
+	const vscode = { workspace: { getConfiguration: (section) => ({ get: (k, d) => (settings[section + '.' + k] === undefined ? d : settings[section + '.' + k]) }) } };
+	const webview = { postMessage: (m) => { posted.push(m); } };
+	const t = {
+		posted, calls, ops, secrets, state, webview, settings,
+		/**
+		 * What POST /auth/refresh answers: 'offline'; 'stall' (accepts, never answers); { status, body },
+		 * where a body of 'garbage' is unparseable and 'stall' never arrives; or a function returning any
+		 * of those, or a promise of one — which is how a reply is made to arrive late.
+		 */
+		refreshReply: 'offline',
+		/** Called with every write the host makes to the stores, as it starts — the hook for landing something mid-change. */
+		onOp: (_op) => { },
+		checkpoints: [],
+		/** The provider adapter: called with the request, and the attempt number. */
+		stream: async (_req, _attempt) => { },
+		byokKey: o.byokKey,
+		/** @type {Error|null} */ keyError: null,
+		/** Makes SecretStorage refuse every write — a locked keychain. */
+		/** @type {Error|null} */ storeError: null,
+		/** …and every read. */
+		/** @type {Error|null} */ readError: null,
+		/** While set, every SecretStorage read waits on it — a read that is slow to come back. */
+		/** @type {Promise<any>|null} */ readGate: null,
+		/** The account messages the popover (and the sign-in card) were sent. */
+		accounts: () => posted.filter((m) => m.type === 'account'),
+		types: () => posted.map((m) => m.type),
+		last: (type) => posted.filter((m) => m.type === type).pop()
+	};
+	const env = {
+		vscode, resolveGateway, webview: o.webview ? webview : undefined, signedIn: !!o.access,
+		session: o.refreshTimeoutMs ? Object.assign({}, session, { REFRESH_TIMEOUT_MS: o.refreshTimeoutMs }) : session,
+		ctx: {
+			secrets: {
+				get: async (k) => {
+					await tick();
+					if (t.readGate) { await t.readGate; }
+					if (t.readError) { throw t.readError; }
+					return secrets.get(k);
+				},
+				store: async (k, v) => {
+					const op = 'store ' + k; ops.push(op); t.onOp(op); await tick();
+					if (t.storeError) { throw t.storeError; }
+					if (typeof v !== 'string') { throw new TypeError('SecretStorage: the value must be a string'); }
+					secrets.set(k, v);
+				},
+				delete: async (k) => { const op = 'forget ' + k; ops.push(op); t.onOp(op); await tick(); secrets.delete(k); }
+			},
+			globalState: {
+				get: (k) => state.get(k),
+				update: async (k, v) => {
+					const op = (v === undefined ? 'clear ' : 'set ') + k; ops.push(op); t.onOp(op); await tick();
+					if (v === undefined) { state.delete(k); } else { state.set(k, v); }
+				}
+			}
+		},
+		fetch: async (url, init) => {
+			const call = { url, body: JSON.parse(init.body), signal: init.signal };
+			calls.refresh.push(call);
+			// Silence until the caller's own deadline aborts the request. With no signal there is nothing
+			// to end it, and it hangs — which is the bug, and what within() then reports.
+			const silence = () => new Promise((_, reject) => {
+				if (init.signal) { init.signal.addEventListener('abort', () => reject(Object.assign(new Error('This operation was aborted'), { name: 'AbortError' }))); }
+			});
+			const r = typeof t.refreshReply === 'function' ? await t.refreshReply(call) : t.refreshReply;
+			if (r === 'offline') { throw new TypeError('fetch failed'); }
+			if (r === 'stall') { return silence(); }
+			return {
+				status: r.status,
+				json: async () => {
+					if (r.body === 'garbage') { throw new SyntaxError('Unexpected token <'); }
+					if (r.body === 'stall') { return silence(); }
+					return r.body;
+				}
+			};
+		},
+		providers: {
+			getProvider: (id) => ({ id, label: 'Claude' }),
+			isInsecureCustomUrl: () => false,
+			streamChat: async (req) => { calls.stream.push(req); return t.stream(req, calls.stream.length); }
+		},
+		getProviderKey: async (_id, opts) => {
+			if (t.keyError) { throw t.keyError; }
+			if (!t.byokKey && opts && opts.prompt) { calls.keyPrompts++; }
+			return t.byokKey || undefined;
+		},
+		aiConfig: () => vscode.workspace.getConfiguration('levelcode.ai'),
+		dbg: () => { }, refreshCloudProfile: async () => { }, fetchCloudRoster: () => { }, sendConfigToWebview: () => { },
+		gatewayModel: () => 'cloud-model', maxOutputTokens: () => 4096, currentProviderId: () => 'claude',
+		baseUrlFor: () => '', activeModel: () => 'claude-model', storeImages: () => [], agentFlow: async () => { },
+		listWorkspaceFiles: async () => [], workspaceMapBlock: () => '', activeFileBlock: () => '',
+		contextFileBlocks: async () => [], gatherAutoContext: async () => ({ blocks: [], names: [] }),
+		labelImages: (b) => b, withImages: (m) => m,
+		// What New Chat, a resumed session and a checkpoint restore touch besides the transcript.
+		sealLiveSession: () => { }, resetConversationState: () => { },
+		postContextFiles: () => { posted.push({ type: 'contextFiles' }); }, postMemoryDigest: () => { posted.push({ type: 'memoryDigest' }); },
+		sessionsManager: () => ({
+			resume: () => ({
+				messages: [{ role: 'user', content: 'an earlier goal' }], entry: { title: 'An earlier session' }, note: '', plan: { tier: 1 },
+				turns: [{ role: 'user', text: 'an earlier goal' }, { role: 'assistant', text: 'done' }]
+			})
+		}),
+		currentContextLimit: () => 200000, refreshSessions: () => { }, focusChatView: () => { },
+		review: { restoreOne: async () => true, finalizeAll: () => { } }, checkpoints: t.checkpoints
+	};
+	t.host = makeHost(env);
+	const K = t.host.KEY;
+	if (o.access) { secrets.set(K.token, o.access); }
+	if (o.refresh) { secrets.set(K.refresh, o.refresh); }
+	if (o.profile) { state.set(K.profile, o.profile); }
+	if (o.expired) { state.set(K.expired, true); }
+	t.K = K;
+	return t;
+}
+
+let n = 0;
+async function test(name, fn) { await fn(); n++; console.log('  ok - ' + name); }
+
+(async () => {
+	await test('premise: a fresh install is in gateway mode with a cloud host configured', () => {
+		assert.strictEqual(shippedDefault('levelcode.ai.providerMode'), 'gateway');
+		assert.ok(/^https:\/\//.test(shippedDefault('levelcode.cloud.endpoint')), 'a default endpoint is set');
+	});
+
+	// ── a failed chat request is an error in the transcript, never an exception ──────────────────
+	await test('chat: a BYOK provider error is posted as assistantError (the catch can read req)', async () => {
+		const t = boot({ byokKey: 'sk-own' });
+		t.stream = async () => { throw new Error('Claude API 529: overloaded'); };
+		await t.host.handleSend('hello');   // the regression: this REJECTED with "req is not defined"
+		const err = t.last('assistantError');
+		assert.ok(err, 'an assistantError was posted — the webview is not left streaming');
+		assert.strictEqual(err.message, 'Claude API 529: overloaded');
+		assert.notStrictEqual(err.code, 'session_expired');
+		assert.strictEqual(t.host.conversation().length, 0, 'the failed turn was taken back out');
+		assert.strictEqual(t.host.abort(), null, 'the turn released its abort controller');
+	});
+
+	await test('chat: an error while PREPARING the request is posted too, not thrown', async () => {
+		const t = boot({ byokKey: 'sk-own' });
+		t.keyError = new Error('keychain is locked');
+		await t.host.handleSend('hello');
+		assert.strictEqual(t.last('assistantError').message, 'keychain is locked');
+		assert.strictEqual(t.calls.stream.length, 0, 'nothing was sent');
+		assert.strictEqual(t.host.conversation().length, 0, 'the failed turn was taken back out');
+	});
+
+	await test('chat: a gateway error that is not a 401 is shown as itself', async () => {
+		const t = boot({ access: liveAccess(), refresh: 'r1' });
+		t.stream = async () => { const e = new Error('LevelCode Cloud API 402: {"error":{"code":"cap_reached"}}'); e.code = 'cap_reached'; throw e; };
+		await t.host.handleSend('hello');
+		const err = t.last('assistantError');
+		assert.strictEqual(err.code, 'cap_reached');
+		assert.strictEqual(t.calls.refresh.length, 0, 'not an auth failure — no refresh attempted');
+		assert.ok(t.secrets.get(t.K.token) && t.secrets.get(t.K.refresh), 'session untouched');
+	});
+
+	// ── only the refresh endpoint's 401 ends the session ─────────────────────────────────────────
+	for (const [label, reply] of [
+		['offline', 'offline'],
+		['a 503', { status: 503, body: null }],
+		['an unparseable reply', { status: 200, body: 'garbage' }],
+		['a 200 with no token in it', { status: 200, body: {} }]
+	]) {
+		await test('chat: a 401 whose refresh fails (' + label + ') keeps the session and shows the error', async () => {
+			const access = liveAccess();
+			const t = boot({ access, refresh: 'r1', profile: { name: 'Ada' } });
+			t.refreshReply = reply;
+			t.stream = async () => { throw gateway401(); };
+			await t.host.handleSend('hello');
+			assert.strictEqual(t.calls.refresh.length, 1, 'one refresh attempt');
+			assert.strictEqual(t.secrets.get(t.K.token), access, 'access token kept');
+			assert.strictEqual(t.secrets.get(t.K.refresh), 'r1', 'refresh token kept');
+			assert.strictEqual(t.host.signedIn(), true, 'still signed in');
+			assert.strictEqual(t.state.get(t.K.expired), undefined, 'no expiry recorded');
+			assert.ok(!t.types().includes('sessionExpired'), 'no sign-in card');
+			const err = t.last('assistantError');
+			assert.ok(err && /API 401/.test(err.message), 'the request error is shown');
+			assert.notStrictEqual(err.code, 'session_expired');
+			assert.strictEqual(t.calls.stream.length, 1, 'no retry without a fresh token');
+		});
+	}
+
+	await test('chat: a 401 whose refresh is REFUSED (401) ends the session — one card, credentials gone', async () => {
+		const t = boot({ access: liveAccess(), refresh: 'r1', profile: { name: 'Ada' } });
+		t.refreshReply = { status: 401, body: { error: { code: 'refresh_expired' } } };
+		t.stream = async () => { throw gateway401(); };
+		await t.host.handleSend('hello');
+		assert.strictEqual(t.secrets.get(t.K.token), undefined);
+		assert.strictEqual(t.secrets.get(t.K.refresh), undefined);
+		assert.strictEqual(t.host.signedIn(), false);
+		assert.strictEqual(t.state.get(t.K.expired), true, 'the expiry is recorded');
+		assert.deepStrictEqual(t.last('sessionExpired'), { type: 'sessionExpired', name: 'Ada', message: session.SESSION_EXPIRED_MESSAGE });
+		const err = t.last('assistantError');
+		assert.strictEqual(err.code, 'session_expired');
+		assert.strictEqual(err.message, session.SESSION_EXPIRED_MESSAGE);
+		assert.deepStrictEqual(t.state.get(t.K.profile), { name: 'Ada' }, 'profile kept so the card can greet by name');
+		const account = t.accounts().pop();
+		assert.ok(account, 'the account popover was resynced, so it stops saying "signed in"');
+		assert.deepStrictEqual({ signedIn: account.signedIn, expired: account.expired }, { signedIn: false, expired: true }, 'and it says an expiry is waiting');
+	});
+
+	await test('chat: a 401 whose refresh succeeds retries once on the new token and stores the rotated pair', async () => {
+		const t = boot({ access: liveAccess(), refresh: 'r1' });
+		const fresh = liveAccess() + 'x';
+		t.refreshReply = { status: 200, body: { access: fresh, refresh: 'r2' } };
+		t.stream = async (req, attempt) => { if (attempt === 1) { throw gateway401(); } };
+		await t.host.handleSend('hello');
+		assert.deepStrictEqual(t.calls.refresh[0].body, { refresh: 'r1' });
+		assert.strictEqual(t.secrets.get(t.K.token), fresh);
+		assert.strictEqual(t.secrets.get(t.K.refresh), 'r2', 'rotated refresh token stored');
+		assert.strictEqual(t.calls.stream.length, 2);
+		assert.strictEqual(t.calls.stream[1].apiKey, fresh, 'the retry carries the new token');
+		assert.ok(t.types().includes('assistantDone') && !t.types().includes('assistantError'));
+	});
+
+	await test('sessionExpired: the marker is written BEFORE the credentials are forgotten', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1' });
+		t.refreshReply = { status: 401, body: { error: { code: 'refresh_expired' } } };
+		await t.host.checkCloudSession('focus');
+		const marker = t.ops.indexOf('set ' + t.K.expired), forget = t.ops.indexOf('forget ' + t.K.token);
+		assert.ok(marker >= 0 && forget >= 0 && marker < forget, 'order was: ' + t.ops.join(', '));
+	});
+
+	// ── an expiry nobody was there to see is replayed, until it is answered ──────────────────────
+	await test('focus check with the chat CLOSED: the session ends, and the next webview to load shows the card', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1', profile: { name: 'Ada' }, webview: false });
+		t.refreshReply = { status: 401, body: { error: { code: 'refresh_expired' } } };
+		await t.host.checkCloudSession('focus');
+		assert.strictEqual(t.secrets.get(t.K.token), undefined, 'credentials are gone');
+		assert.deepStrictEqual(t.posted, [], 'nobody was listening');
+
+		t.host.openWebview(t.webview);            // the user opens the chat
+		await t.host.checkCloudSession('ready');  // …which finds no token and says nothing
+		assert.deepStrictEqual(t.posted, []);
+		await t.host.replaySessionExpired();      // …and `ready` ends with the replay
+		assert.deepStrictEqual(t.posted, [{ type: 'sessionExpired', name: 'Ada', message: session.SESSION_EXPIRED_MESSAGE }]);
+	});
+
+	await test('replay: every fresh document gets the card while the expiry is unanswered', async () => {
+		const t = boot({ expired: true, profile: { name: 'Ada' } });
+		await t.host.replaySessionExpired();   // a new chat
+		await t.host.replaySessionExpired();   // the chat moved to an editor tab
+		assert.strictEqual(t.posted.filter((m) => m.type === 'sessionExpired').length, 2);
+	});
+
+	await test('replay: answered by signing in again', async () => {
+		const t = boot({ expired: true });
+		await t.host.storeSession(liveAccess(), 'r2', { name: 'Ada' });
+		assert.strictEqual(t.state.get(t.K.expired), undefined);
+		await t.host.replaySessionExpired();
+		assert.deepStrictEqual(t.posted, []);
+	});
+
+	await test('replay: answered by signing out on purpose', async () => {
+		const t = boot({ expired: true, profile: { name: 'Ada' } });
+		await t.host.accountSignOut();
+		assert.strictEqual(t.state.get(t.K.expired), undefined);
+		await t.host.replaySessionExpired();
+		assert.ok(!t.types().includes('sessionExpired'));
+	});
+
+	await test('replay: answered by choosing your own key', async () => {
+		const t = boot({ expired: true });
+		await t.host.clearSessionExpired();
+		await t.host.replaySessionExpired();
+		assert.deepStrictEqual(t.posted, []);
+	});
+
+	await test('replay: silent for someone who never had a session, in BYOK mode, with no host, or with a live token', async () => {
+		const never = boot({}); await never.host.replaySessionExpired();
+		assert.deepStrictEqual(never.posted, [], 'never signed in');
+		const byok = boot({ expired: true, settings: { 'levelcode.ai.providerMode': 'byok' } }); await byok.host.replaySessionExpired();
+		assert.deepStrictEqual(byok.posted, [], 'BYOK mode');
+		const inert = boot({ expired: true, settings: { 'levelcode.cloud.endpoint': '' } }); await inert.host.replaySessionExpired();
+		assert.deepStrictEqual(inert.posted, [], 'no cloud host to sign in to');
+		const live = boot({ expired: true, access: liveAccess() }); await live.host.replaySessionExpired();
+		assert.deepStrictEqual(live.posted, [], 'another window signed in again');
+	});
+
+	await test('session check: a token with hours left costs no request; one near expiry is renewed', async () => {
+		const fine = boot({ access: liveAccess(), refresh: 'r1' });
+		await fine.host.checkCloudSession('ready');
+		assert.strictEqual(fine.calls.refresh.length, 0);
+		const stale = boot({ access: deadAccess(), refresh: 'r1' });
+		const fresh = liveAccess();
+		stale.refreshReply = { status: 200, body: { access: fresh, refresh: 'r2' } };
+		await stale.host.checkCloudSession('ready');
+		assert.strictEqual(stale.secrets.get(stale.K.token), fresh);
+		assert.deepStrictEqual(stale.posted, [], 'renewed silently');
+	});
+
+	// ── gateway is the default mode: "no token" is BYOK unless a session ENDED ───────────────────
+	await test('BYOK: a fresh install with its own key and no account goes straight to the provider', async () => {
+		const t = boot({ byokKey: 'sk-own' });
+		const req = await t.host.prepProviderRequest({ prompt: true });
+		assert.strictEqual(req.ok, true);
+		assert.strictEqual(req.providerId, 'claude');
+		assert.strictEqual(req.apiKey, 'sk-own');
+		assert.ok(!req.gateway, 'not the gateway');
+		await t.host.handleSend('hello');
+		assert.strictEqual(t.calls.stream.length, 1, 'the message was sent');
+		assert.strictEqual(t.calls.stream[0].apiKey, 'sk-own');
+		assert.ok(t.types().includes('assistantDone'));
+		assert.ok(!t.posted.some((m) => m.code === 'session_expired' || m.type === 'sessionExpired'), 'no sign-in card');
+	});
+
+	await test('BYOK: no account and no key is "No API key set for <provider>", not a session card', async () => {
+		const t = boot({});
+		const req = await t.host.prepProviderRequest({ prompt: true });
+		assert.deepStrictEqual({ ok: req.ok, reason: req.reason, providerId: req.providerId }, { ok: false, reason: 'key', providerId: 'claude' });
+		assert.ok(/^No API key set for Claude/.test(t.host.providerErrorMessage(req)));
+		assert.strictEqual(t.calls.keyPrompts, 1, 'and the key prompt is offered, as before');
+	});
+
+	await test('BYOK: signing out on purpose falls back to your own key', async () => {
+		const t = boot({ access: liveAccess(), refresh: 'r1', profile: { name: 'Ada' }, byokKey: 'sk-own' });
+		assert.strictEqual((await t.host.prepProviderRequest({ prompt: true })).gateway, true, 'on the plan while signed in');
+		await t.host.accountSignOut();
+		const req = await t.host.prepProviderRequest({ prompt: true });
+		assert.deepStrictEqual({ ok: req.ok, providerId: req.providerId, apiKey: req.apiKey }, { ok: true, providerId: 'claude', apiKey: 'sk-own' });
+	});
+
+	await test('signed in: the request routes through the gateway on the session token', async () => {
+		const access = liveAccess();
+		const t = boot({ access, refresh: 'r1', byokKey: 'sk-own' });
+		const req = await t.host.prepProviderRequest({ prompt: true });
+		assert.strictEqual(req.gateway, true);
+		assert.strictEqual(req.apiKey, access);
+		assert.strictEqual(req.baseURL, shippedDefault('levelcode.cloud.endpoint') + GATEWAY_PATH);
+	});
+
+	await test('an ENDED session stops the request with a sign-in card — own key or not, and never a key prompt', async () => {
+		for (const byokKey of ['', 'sk-own']) {
+			const t = boot({ expired: true, byokKey });
+			const req = await t.host.prepProviderRequest({ prompt: true });
+			assert.deepStrictEqual({ ok: req.ok, reason: req.reason, gateway: req.gateway }, { ok: false, reason: 'signedOut', gateway: true });
+			assert.strictEqual(t.host.providerErrorMessage(req), session.SESSION_EXPIRED_MESSAGE);
+			assert.strictEqual(t.calls.keyPrompts, 0, 'nobody is asked for a key they never needed');
+			await t.host.handleSend('hello');
+			assert.strictEqual(t.last('assistantError').code, 'session_expired');
+			assert.strictEqual(t.calls.stream.length, 0, 'nothing was sent');
+		}
+	});
+
+	await test('an ended session answered with "use my own key" is BYOK from the next message', async () => {
+		const t = boot({ expired: true, byokKey: 'sk-own' });
+		await t.host.clearSessionExpired();
+		const req = await t.host.prepProviderRequest({ prompt: true });
+		assert.deepStrictEqual({ ok: req.ok, providerId: req.providerId, apiKey: req.apiKey }, { ok: true, providerId: 'claude', apiKey: 'sk-own' });
+	});
+
+	await test('an ended session answered by switching to BYOK mode is BYOK too', async () => {
+		const t = boot({ expired: true, byokKey: 'sk-own', settings: { 'levelcode.ai.providerMode': 'byok' } });
+		assert.strictEqual((await t.host.prepProviderRequest({ prompt: true })).ok, true);
+	});
+
+	// ── a refresh's answer belongs to the session it started against ─────────────────────────────
+	const refused = { status: 401, body: { error: { code: 'refresh_expired' } } };
+
+	await test('late 401: a sign-in that lands while the refresh is out keeps its new session', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1', profile: { name: 'Ada' } });
+		const reply = deferred();
+		t.refreshReply = () => reply.promise;
+		const check = t.host.checkCloudSession('focus');          // the old session's refresh goes out…
+		await until(() => t.calls.refresh.length === 1, 'the refresh request');
+		const fresh = liveAccess();
+		await t.host.storeSession(fresh, 'r2', { name: 'Ada' });  // …the user signs in again…
+		reply.resolve(refused);                                   // …and only now does the 401 for r1 arrive
+		await check;
+		assert.strictEqual(t.secrets.get(t.K.token), fresh, 'the new access token survived');
+		assert.strictEqual(t.secrets.get(t.K.refresh), 'r2', 'the new refresh token survived');
+		assert.strictEqual(t.state.get(t.K.expired), undefined, 'no expiry recorded against the new session');
+		assert.strictEqual(t.host.signedIn(), true);
+		assert.ok(!t.types().includes('sessionExpired'), 'no sign-in card');
+	});
+
+	await test('late 401: a sign-in that brought no refresh token of its own is a new session all the same', async () => {
+		// The stored refresh token is unchanged here, so comparing tokens would call this "the same
+		// session" and delete an access token minted seconds ago. Counting sign-ins does not.
+		const t = boot({ access: deadAccess(), refresh: 'r1' });
+		const reply = deferred();
+		t.refreshReply = () => reply.promise;
+		const check = t.host.checkCloudSession('focus');
+		await until(() => t.calls.refresh.length === 1, 'the refresh request');
+		const fresh = liveAccess();
+		await t.host.storeSession(fresh, null, { name: 'Ada' });
+		reply.resolve(refused);
+		await check;
+		assert.strictEqual(t.secrets.get(t.K.token), fresh);
+		assert.strictEqual(t.state.get(t.K.expired), undefined);
+		assert.ok(!t.types().includes('sessionExpired'));
+	});
+
+	await test('late 401: a sign-out while the refresh is out is not turned into an expiry', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1', profile: { name: 'Ada' } });
+		const reply = deferred();
+		t.refreshReply = () => reply.promise;
+		const check = t.host.checkCloudSession('focus');
+		await until(() => t.calls.refresh.length === 1, 'the refresh request');
+		await t.host.accountSignOut();
+		reply.resolve(refused);
+		await check;
+		assert.strictEqual(t.state.get(t.K.expired), undefined, 'signed out on purpose: nothing to answer');
+		assert.ok(!t.types().includes('sessionExpired'), 'no sign-in card');
+		assert.strictEqual(t.accounts().length, 1, 'only the sign-out resynced the popover');
+	});
+
+	await test('late 200: a sign-out while the refresh is out stays signed out', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1' });
+		const reply = deferred();
+		t.refreshReply = () => reply.promise;
+		const renewal = t.host.refreshCloudToken();
+		await until(() => t.calls.refresh.length === 1, 'the refresh request');
+		await t.host.accountSignOut();
+		reply.resolve({ status: 200, body: { access: liveAccess(), refresh: 'r2' } });
+		assert.strictEqual(await renewal, false, 'nothing to retry with');
+		assert.strictEqual(t.secrets.get(t.K.token), undefined, 'not signed back in');
+		assert.strictEqual(t.secrets.get(t.K.refresh), undefined);
+		assert.strictEqual(t.host.signedIn(), false);
+	});
+
+	await test('late 200: tokens for the old session are not filed under a newer sign-in', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1', profile: { name: 'Ada' } });
+		const reply = deferred();
+		t.refreshReply = () => reply.promise;
+		const renewal = t.host.refreshCloudToken();
+		await until(() => t.calls.refresh.length === 1, 'the refresh request');
+		const other = liveAccess() + '.bo';
+		await t.host.storeSession(other, 'rB', { name: 'Bo' });   // someone else signs in on this machine
+		reply.resolve({ status: 200, body: { access: liveAccess() + '.ada', refresh: 'r1b' } });
+		assert.strictEqual(await renewal, true, 'a token is in place — the newer session\'s');
+		assert.strictEqual(t.secrets.get(t.K.token), other);
+		assert.strictEqual(t.secrets.get(t.K.refresh), 'rB');
+		assert.deepStrictEqual(t.state.get(t.K.profile), { name: 'Bo', email: '', plan: '' });
+	});
+
+	await test('the lock: a sign-in that starts in the MIDDLE of an expiry\'s deletes is not lost', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1' });
+		t.refreshReply = refused;
+		const fresh = liveAccess();
+		let signIn = null;
+		// The expiry has decided this is still the dead session and begun its writes. A sign-in arriving
+		// now must wait its turn; interleaved, its tokens would be stored and then deleted.
+		t.onOp = (op) => { if (!signIn && op === 'set ' + t.K.expired) { signIn = t.host.storeSession(fresh, 'r2', { name: 'Ada' }); } };
+		await t.host.checkCloudSession('focus');
+		assert.ok(signIn, 'the sign-in was started mid-expiry');
+		await signIn;
+		assert.strictEqual(t.secrets.get(t.K.token), fresh, 'ops were: ' + t.ops.join(', '));
+		assert.strictEqual(t.secrets.get(t.K.refresh), 'r2');
+		assert.strictEqual(t.state.get(t.K.expired), undefined, 'the sign-in answered the expiry');
+		assert.strictEqual(t.host.signedIn(), true);
+	});
+
+	await test('two refreshes at once, both renewed: one matching pair is stored and both report a token', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1' });
+		const pairs = [{ access: liveAccess() + '.a', refresh: 'r2a' }, { access: liveAccess() + '.b', refresh: 'r2b' }];
+		let i = 0;
+		t.refreshReply = () => ({ status: 200, body: pairs[i++] });
+		assert.deepStrictEqual(await Promise.all([t.host.refreshCloudToken(), t.host.refreshCloudToken()]), [true, true]);
+		const stored = { access: t.secrets.get(t.K.token), refresh: t.secrets.get(t.K.refresh) };
+		assert.ok(pairs.some((p) => p.access === stored.access && p.refresh === stored.refresh), 'an access token from one reply and a refresh token from the other: ' + JSON.stringify(stored));
+	});
+
+	await test('two refreshes at once, both refused: the session ends once — one card, one resync', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1', profile: { name: 'Ada' } });
+		t.refreshReply = refused;
+		assert.deepStrictEqual(await Promise.all([t.host.refreshCloudToken(), t.host.refreshCloudToken()]), [false, false]);
+		assert.strictEqual(t.posted.filter((m) => m.type === 'sessionExpired').length, 1);
+		assert.strictEqual(t.accounts().length, 1);
+		assert.strictEqual(t.state.get(t.K.expired), true);
+	});
+
+	await test('another window signed in while this refresh was out: its session is left alone', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1' });
+		const reply = deferred();
+		t.refreshReply = () => reply.promise;
+		const check = t.host.checkCloudSession('focus');
+		await until(() => t.calls.refresh.length === 1, 'the refresh request');
+		const theirs = liveAccess() + '.other-window';
+		t.secrets.set(t.K.token, theirs); t.secrets.set(t.K.refresh, 'rW');   // written by another process: no counter here saw it
+		reply.resolve(refused);
+		await check;
+		assert.strictEqual(t.secrets.get(t.K.token), theirs);
+		assert.strictEqual(t.secrets.get(t.K.refresh), 'rW');
+		assert.strictEqual(t.state.get(t.K.expired), undefined);
+		assert.ok(!t.types().includes('sessionExpired'));
+	});
+
+	await test('another window ENDED the session while this refresh was out: this window catches up', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1', profile: { name: 'Ada' } });
+		const reply = deferred();
+		t.refreshReply = () => reply.promise;
+		const check = t.host.checkCloudSession('focus');
+		await until(() => t.calls.refresh.length === 1, 'the refresh request');
+		t.secrets.delete(t.K.token); t.secrets.delete(t.K.refresh); t.state.set(t.K.expired, true);   // the other window's sessionExpired()
+		reply.resolve(refused);
+		await check;
+		assert.strictEqual(t.host.signedIn(), false, 'stops presenting a live session');
+		assert.strictEqual(t.posted.filter((m) => m.type === 'sessionExpired').length, 1, 'shows the card');
+		assert.strictEqual(t.accounts().length, 1, 'resyncs the popover');
+		assert.deepStrictEqual(t.ops, [], 'and writes nothing — there was nothing left to end');
+	});
+
+	// ── the refresh has a deadline, body included ────────────────────────────────────────────────
+	await test('a host that accepts the request and never answers: the check gives up, credentials kept', async () => {
+		const access = deadAccess();
+		const t = boot({ access, refresh: 'r1', refreshTimeoutMs: 40 });
+		t.refreshReply = 'stall';
+		await within(t.host.checkCloudSession('ready'), 2000, 'the session check `ready` waits on');
+		assert.strictEqual(t.calls.refresh[0].signal.aborted, true, 'the request was aborted at the deadline');
+		assert.strictEqual(t.secrets.get(t.K.token), access);
+		assert.strictEqual(t.secrets.get(t.K.refresh), 'r1');
+		assert.strictEqual(t.host.signedIn(), true);
+		assert.strictEqual(t.state.get(t.K.expired), undefined);
+		assert.deepStrictEqual(t.posted, []);
+	});
+
+	await test('headers arrive but the body never does: still bounded, still "this attempt failed"', async () => {
+		const access = deadAccess();
+		const t = boot({ access, refresh: 'r1', refreshTimeoutMs: 40 });
+		t.refreshReply = { status: 200, body: 'stall' };
+		assert.strictEqual(await within(t.host.refreshCloudToken(), 2000, 'the refresh'), false);
+		assert.strictEqual(t.secrets.get(t.K.token), access);
+		assert.strictEqual(t.secrets.get(t.K.refresh), 'r1');
+		assert.strictEqual(t.state.get(t.K.expired), undefined);
+	});
+
+	await test('a 401 whose body never arrives is still the server saying no: the session ends', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1', refreshTimeoutMs: 40 });
+		t.refreshReply = { status: 401, body: 'stall' };
+		assert.strictEqual(await within(t.host.refreshCloudToken(), 2000, 'the refresh'), false);
+		assert.strictEqual(t.secrets.get(t.K.token), undefined);
+		assert.strictEqual(t.state.get(t.K.expired), true);
+	});
+
+	await test('a refresh that answers in time is not aborted afterwards — its timer is cleared', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1', refreshTimeoutMs: 40 });
+		t.refreshReply = { status: 200, body: { access: liveAccess(), refresh: 'r2' } };
+		assert.strictEqual(await t.host.refreshCloudToken(), true);
+		await new Promise((resolve) => setTimeout(resolve, 90));   // well past the deadline
+		assert.strictEqual(t.calls.refresh[0].signal.aborted, false);
+	});
+
+	await test('the shipped deadline is ten seconds', () => {
+		assert.strictEqual(session.REFRESH_TIMEOUT_MS, 10000);
+	});
+
+	// ── what rewrites the transcript in place takes the card with it; it is put back ─────────────
+	const order = (t, ...of) => t.types().filter((x) => of.includes(x));
+
+	await test('New Chat: the card is replayed into the emptied transcript', async () => {
+		const t = boot({ expired: true, profile: { name: 'Ada' } });
+		t.host.newChat();
+		await until(() => t.types().includes('sessionExpired'), 'the replay after New Chat');
+		assert.deepStrictEqual(order(t, 'reset', 'memoryDigest', 'sessionExpired'), ['reset', 'memoryDigest', 'sessionExpired']);
+		assert.strictEqual(t.last('sessionExpired').name, 'Ada');
+	});
+
+	await test('a session resumed from History: the card goes back UNDER the restored transcript', async () => {
+		const t = boot({ expired: true });
+		await t.host.resumeSession('s1');
+		assert.deepStrictEqual(order(t, 'reset', 'sessionResumed', 'sessionExpired'), ['reset', 'sessionResumed', 'sessionExpired']);
+	});
+
+	await test('a checkpoint restore: the card dropped with the later turns is replayed', async () => {
+		const t = boot({ expired: true });
+		const goal = { role: 'user', content: 'a goal' };
+		t.checkpoints.push({ turnId: 7, goalMsg: goal, files: new Map() });
+		t.host.setAgentMessages([goal, { role: 'assistant', content: 'done' }]);
+		await t.host.restoreCheckpoint(7);
+		assert.deepStrictEqual(t.types(), ['checkpointRestored', 'sessionExpired']);
+	});
+
+	await test('none of the three says anything when no expiry is waiting', async () => {
+		const t = boot({});
+		const goal = { role: 'user', content: 'a goal' };
+		t.checkpoints.push({ turnId: 7, goalMsg: goal, files: new Map() });
+		t.host.setAgentMessages([goal]);
+		await t.host.restoreCheckpoint(7);
+		await t.host.resumeSession('s1');
+		t.host.newChat();
+		await settle();
+		assert.ok(t.types().includes('reset') && t.types().includes('checkpointRestored'), 'all three ran');
+		assert.ok(!t.types().includes('sessionExpired'));
+	});
+
+	// ── a sign-out is not an expiry, even with a 401 still in the air ─────────────────────────────
+	const renewed = () => ({ status: 200, body: { access: liveAccess(), refresh: 'r2' } });
+
+	for (const [label, late] of [['is refused', () => refused], ['succeeds', renewed]]) {
+		await test('chat: signing out while the 401\'s refresh is out — which then ' + label + ' — shows the error, not an expiry card', async () => {
+			const t = boot({ access: liveAccess(), refresh: 'r1', profile: { name: 'Ada' } });
+			const reply = deferred();
+			t.refreshReply = () => reply.promise;
+			t.stream = async () => { throw gateway401(); };
+			const sending = t.host.handleSend('hello');
+			await until(() => t.calls.refresh.length === 1, 'the refresh request');
+			await t.host.accountSignOut();
+			reply.resolve(late());
+			await sending;
+			const err = t.last('assistantError');
+			assert.ok(err && /API 401/.test(err.message), 'the request\'s own error is shown');
+			assert.notStrictEqual(err.code, 'session_expired', 'not an expiry');
+			assert.ok(!t.types().includes('sessionExpired'), 'no sign-in card');
+			assert.strictEqual(t.state.get(t.K.expired), undefined);
+			assert.strictEqual(t.secrets.get(t.K.token), undefined, 'and still signed out');
+		});
+	}
+
+	/**
+	 * One agent run against a gateway that answers 401 — the REAL loop from agent.js, given the two
+	 * hooks the way agentFlow hands them over (sessionExpiredUi.test.js pins that wiring).
+	 */
+	async function agentRunRefused(t, req) {
+		const real = agentProviders.streamAgentTurn;
+		let turns = 0;
+		agentProviders.streamAgentTurn = async () => { turns++; throw gateway401(); };
+		try {
+			await runAgent({
+				messages: [{ role: 'user', content: 'hello' }], providerId: req.providerId, baseURL: req.baseURL, label: req.label,
+				apiKey: req.apiKey, model: req.model, maxSteps: 3, maxTokens: 1024, signal: new AbortController().signal,
+				post: (m) => t.webview.postMessage(m), dbg: () => { }, autopilot: false, approve: async () => false, ask: async () => null,
+				mcp: { servers: {}, toolPolicy: {}, launchTrust: {} }, rememberMcpTrust: () => { },
+				verify: { enabled: false, command: '', maxRounds: 0, includeWarnings: false }, touched: new Set(),
+				refreshAuth: async () => ((await t.host.refreshGatewayToken()) ? t.secrets.get(t.K.token) : null),
+				isSessionExpired: (e) => t.host.isEndedSessionError(req, e),
+				sessionExpiredMessage: session.SESSION_EXPIRED_MESSAGE
+			});
+		} finally { agentProviders.streamAgentTurn = real; }
+		assert.strictEqual(turns, 1, 'the loop asked the stand-in provider, once: no retry without a fresh token');
+	}
+
+	await test('agent: a session that really ended, through the real loop — the sign-in card', async () => {
+		const t = boot({ access: liveAccess(), refresh: 'r1', profile: { name: 'Ada' } });
+		t.refreshReply = refused;
+		const req = await t.host.prepProviderRequest({ prompt: true });
+		assert.strictEqual(req.gateway, true);
+		await agentRunRefused(t, req);
+		assert.deepStrictEqual(t.last('agentError'), { type: 'agentError', message: session.SESSION_EXPIRED_MESSAGE, code: 'session_expired' });
+		assert.strictEqual(t.last('agentDone').reason, 'error');
+	});
+
+	await test('agent: signing out while the 401\'s refresh is out, through the real loop — the error, not an expiry card', async () => {
+		const t = boot({ access: liveAccess(), refresh: 'r1', profile: { name: 'Ada' } });
+		const reply = deferred();
+		t.refreshReply = () => reply.promise;
+		const req = await t.host.prepProviderRequest({ prompt: true });
+		const run = agentRunRefused(t, req);
+		await until(() => t.calls.refresh.length === 1, 'the refresh request');
+		await t.host.accountSignOut();
+		reply.resolve(refused);
+		await run;
+		const err = t.last('agentError');
+		assert.ok(err && /API 401/.test(err.message), 'the request\'s own error is shown');
+		assert.notStrictEqual(err.code, 'session_expired', 'not an expiry');
+		assert.ok(!t.types().includes('sessionExpired'), 'no sign-in card');
+	});
+
+	await test('the rule itself: all four clauses, one at a time', async () => {
+		const ended = boot({ expired: true });
+		assert.strictEqual(ended.host.isEndedSessionError({ gateway: true }, gateway401()), true, 'an ended session, a gateway 401');
+		assert.strictEqual(ended.host.isEndedSessionError({ gateway: false }, gateway401()), false, 'not a gateway request');
+		assert.strictEqual(ended.host.isEndedSessionError({ gateway: true }, new Error('LevelCode Cloud API 500: upstream')), false, 'not a 401');
+		assert.strictEqual(boot({}).host.isEndedSessionError({ gateway: true }, gateway401()), false, 'no expiry waiting — signed out, or never signed in');
+		assert.strictEqual(boot({ expired: true, access: liveAccess() }).host.isEndedSessionError({ gateway: true }, gateway401()), false, 'still signed in');
+	});
+
+	// ── the card follows the host's answer to "is an expiry still waiting?" ──────────────────────
+	const settingChanged = (...keys) => ({ affectsConfiguration: (k) => keys.includes(k) });
+	const brief = (a) => ({ signedIn: a.signedIn, mode: a.mode, expired: a.expired, status: a.status });
+
+	await test('account message: `expired` is true only while an ended session is waiting on the user', async () => {
+		const say = async (over) => brief(await boot(over).host.currentAccount());
+		assert.deepStrictEqual(await say({ expired: true }), { signedIn: false, mode: 'gateway', expired: true, status: 'signedout' });
+		assert.deepStrictEqual(await say({ expired: true, settings: { 'levelcode.ai.providerMode': 'byok' } }), { signedIn: false, mode: 'byok', expired: false, status: 'signedout' });
+		assert.deepStrictEqual(await say({ expired: true, settings: { 'levelcode.cloud.endpoint': '' } }), { signedIn: false, mode: 'gateway', expired: false, status: 'unconfigured' });
+		assert.deepStrictEqual(await say({}), { signedIn: false, mode: 'gateway', expired: false, status: 'signedout' });
+		assert.deepStrictEqual(await say({ expired: true, access: liveAccess() }), { signedIn: true, mode: 'gateway', expired: false, status: undefined });
+	});
+
+	await test('switching to BYOK in Settings: the account message says nothing is waiting — the card\'s cue to go', async () => {
+		const t = boot({ expired: true, profile: { name: 'Ada' } });
+		t.settings['levelcode.ai.providerMode'] = 'byok';
+		t.host.onConfigChanged(settingChanged('levelcode.ai', 'levelcode.ai.providerMode'));
+		await settle();
+		assert.deepStrictEqual(t.accounts().map(brief), [{ signedIn: false, mode: 'byok', expired: false, status: 'signedout' }]);
+		assert.ok(!t.types().includes('sessionExpired'), 'and no card is replayed while the session is out of play');
+	});
+
+	await test('switching BACK to gateway: the expiry is in force again, and the card comes back with it', async () => {
+		const t = boot({ expired: true, profile: { name: 'Ada' }, settings: { 'levelcode.ai.providerMode': 'byok' } });
+		t.settings['levelcode.ai.providerMode'] = 'gateway';
+		t.host.onConfigChanged(settingChanged('levelcode.ai', 'levelcode.ai.providerMode'));
+		await settle();
+		assert.deepStrictEqual(t.accounts().map(brief), [{ signedIn: false, mode: 'gateway', expired: true, status: 'signedout' }]);
+		assert.strictEqual(t.posted.filter((m) => m.type === 'sessionExpired').length, 1);
+		assert.strictEqual((await t.host.prepProviderRequest({ prompt: false })).reason, 'signedOut', 'the request it is there to explain');
+	});
+
+	await test('a session that ends while in BYOK mode: no card — nothing stopped working — until gateway mode is chosen', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1', profile: { name: 'Ada' }, settings: { 'levelcode.ai.providerMode': 'byok' } });
+		t.refreshReply = refused;
+		assert.strictEqual(await t.host.refreshCloudToken(), false);   // "Manage account" finding the session dead, say
+		assert.strictEqual(t.secrets.get(t.K.token), undefined, 'the session did end');
+		assert.ok(!t.types().includes('sessionExpired'), 'no card in BYOK mode');
+		assert.deepStrictEqual(t.accounts().map(brief), [{ signedIn: false, mode: 'byok', expired: false, status: 'signedout' }], 'the popover says signed out');
+		t.settings['levelcode.ai.providerMode'] = 'gateway';
+		t.host.onConfigChanged(settingChanged('levelcode.ai', 'levelcode.ai.providerMode'));
+		await settle();
+		assert.strictEqual(t.posted.filter((m) => m.type === 'sessionExpired').length, 1, 'now it matters, and now it shows');
+	});
+
+	await test('a settings change that touches neither the mode nor the cloud host resyncs neither', async () => {
+		const t = boot({ expired: true });
+		t.host.onConfigChanged(settingChanged('levelcode.ai'));
+		await settle();
+		assert.deepStrictEqual(t.posted, []);
+	});
+
+	// ── a 2xx is a renewal only if what it carries can be stored ─────────────────────────────────
+	for (const [label, body] of [
+		['an access token that is not a string', { access: {} }],
+		['a refresh token that is not a string', { access: 'new-access', refresh: {} }]
+	]) {
+		await test('malformed 200 (' + label + '): the check `ready` waits on completes, and the credentials are untouched', async () => {
+			const access = deadAccess();
+			const t = boot({ access, refresh: 'r1' });
+			t.refreshReply = { status: 200, body };
+			await t.host.checkCloudSession('ready');   // this REJECTED before, and took the rest of `ready` with it
+			assert.deepStrictEqual(t.ops, [], 'nothing was written');
+			assert.strictEqual(t.secrets.get(t.K.token), access, 'the access token was not replaced');
+			assert.strictEqual(t.secrets.get(t.K.refresh), 'r1');
+			assert.strictEqual(t.host.signedIn(), true);
+			assert.strictEqual(t.state.get(t.K.expired), undefined);
+		});
+	}
+
+	await test('a store that will not take a GOOD reply is one more failed attempt: false, and nothing escapes', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1' });
+		t.refreshReply = renewed();
+		t.storeError = new Error('the keychain is locked');
+		assert.strictEqual(await t.host.refreshCloudToken(), false);
+		await t.host.checkCloudSession('ready');
+		assert.strictEqual(t.secrets.get(t.K.refresh), 'r1', 'still the session it was');
+		assert.strictEqual(t.state.get(t.K.expired), undefined);
+	});
+
+	// ── the replay asks again after its read ─────────────────────────────────────────────────────
+	for (const [how, answer] of [
+		['"Use my own key instead"', (t) => t.host.clearSessionExpired()],
+		['BYOK chosen in Settings', async (t) => { t.settings['levelcode.ai.providerMode'] = 'byok'; }]
+	]) {
+		await test('replay: an expiry answered by ' + how + ' WHILE the token read is out is not shown again', async () => {
+			const t = boot({ expired: true, profile: { name: 'Ada' } });
+			const read = deferred();
+			t.readGate = read.promise;                     // SecretStorage is slow to answer…
+			const replay = t.host.replaySessionExpired();
+			await settle();                                // …so the replay is parked on that read…
+			await answer(t);                               // …and the user answers the card meanwhile.
+			read.resolve();
+			await replay;
+			assert.deepStrictEqual(t.posted, [], 'no card for an expiry that is no longer waiting');
+		});
+	}
+
+	await test('replay: the same slow read with nothing answered still ends in the card', async () => {
+		const t = boot({ expired: true, profile: { name: 'Ada' } });
+		const read = deferred();
+		t.readGate = read.promise;
+		const replay = t.host.replaySessionExpired();
+		await settle();
+		read.resolve();
+		await replay;
+		assert.deepStrictEqual(t.types(), ['sessionExpired']);
+	});
+
+	await test('a store that will not READ: the check and the replay finish quietly — neither can break what awaits them', async () => {
+		const t = boot({ expired: true, access: deadAccess(), refresh: 'r1' });
+		t.readError = new Error('the keychain is locked');
+		await t.host.checkCloudSession('ready');
+		await t.host.replaySessionExpired();
+		assert.deepStrictEqual(t.posted, []);
+	});
+
+	// ── a window catches up with what another window did to the session they share ───────────────
+	await test('another window ENDED the session before this window\'s focus check: flag, popover and card catch up', async () => {
+		const t = boot({ access: liveAccess(), refresh: 'r1', profile: { name: 'Ada' } });
+		assert.strictEqual(t.host.signedIn(), true, 'this window is showing a live session');
+		t.secrets.delete(t.K.token); t.secrets.delete(t.K.refresh); t.state.set(t.K.expired, true);   // the other window's sessionExpired()
+		await t.host.checkCloudSession('focus');
+		assert.strictEqual(t.host.signedIn(), false);
+		assert.deepStrictEqual(t.posted.filter((m) => m.type === 'sessionExpired'), [{ type: 'sessionExpired', name: 'Ada', message: session.SESSION_EXPIRED_MESSAGE }]);
+		assert.deepStrictEqual(t.accounts().map(brief), [{ signedIn: false, mode: 'gateway', expired: true, status: 'signedout' }]);
+		assert.strictEqual(t.calls.refresh.length, 0, 'nothing to renew, nothing requested');
+		assert.deepStrictEqual(t.ops, [], 'and nothing written');
+		const before = t.posted.length;
+		await t.host.checkCloudSession('focus');   // clicking back in again
+		assert.strictEqual(t.posted.length, before, 'said once, not on every focus');
+	});
+
+	await test('another window SIGNED OUT: the popover catches up, and there is no card — nothing expired', async () => {
+		const t = boot({ access: liveAccess(), refresh: 'r1', profile: { name: 'Ada' } });
+		t.secrets.delete(t.K.token); t.secrets.delete(t.K.refresh); t.state.delete(t.K.profile);       // the other window's accountSignOut()
+		await t.host.checkCloudSession('focus');
+		assert.strictEqual(t.host.signedIn(), false);
+		assert.deepStrictEqual(t.accounts().map(brief), [{ signedIn: false, mode: 'gateway', expired: false, status: 'signedout' }]);
+		assert.ok(!t.types().includes('sessionExpired'));
+	});
+
+	await test('another window SIGNED IN while this one showed the card: the account message is its cue to go', async () => {
+		const t = boot({ expired: true, profile: { name: 'Ada' } });
+		assert.strictEqual(t.host.signedIn(), false);
+		t.secrets.set(t.K.token, liveAccess()); t.secrets.set(t.K.refresh, 'r2'); t.state.delete(t.K.expired);   // the other window's storeSession()
+		await t.host.checkCloudSession('focus');
+		assert.strictEqual(t.host.signedIn(), true);
+		assert.deepStrictEqual(t.accounts().map(brief), [{ signedIn: true, mode: 'gateway', expired: false, status: undefined }]);
+		assert.ok(!t.types().includes('sessionExpired'));
+	});
+
+	await test('a focus check that lands in the MIDDLE of this window\'s own sign-out does not take it for another window\'s', async () => {
+		// Mid-sign-out the flag already says "signed out" while the token is still stored. Read then,
+		// the two disagree, and the catch-up would announce a session this window is busy ending.
+		const t = boot({ access: liveAccess(), refresh: 'r1', profile: { name: 'Ada' } });
+		let check = null;
+		t.onOp = (op) => { if (!check && op === 'forget ' + t.K.token) { check = t.host.checkCloudSession('focus'); } };
+		await t.host.accountSignOut();
+		assert.ok(check, 'the focus check was started mid-sign-out');
+		await check;
+		assert.deepStrictEqual(t.accounts().map(brief), [{ signedIn: false, mode: 'gateway', expired: false, status: 'signedout' }], 'one resync: the sign-out\'s own');
+		assert.strictEqual(t.host.signedIn(), false);
+	});
+
+	await test('the ration is on the refresh, not on the look: a second focus skips the request but still catches up', async () => {
+		const t = boot({ access: deadAccess(), refresh: 'r1', profile: { name: 'Ada' } });
+		t.refreshReply = 'offline';
+		await t.host.checkCloudSession('focus');
+		await t.host.checkCloudSession('focus');
+		assert.strictEqual(t.calls.refresh.length, 1, 'offline: one attempt, not one per click');
+		t.secrets.delete(t.K.token); t.secrets.delete(t.K.refresh); t.state.set(t.K.expired, true);   // meanwhile, in another window
+		await t.host.checkCloudSession('focus');
+		assert.strictEqual(t.posted.filter((m) => m.type === 'sessionExpired').length, 1, 'found inside the ten minutes');
+		assert.strictEqual(t.calls.refresh.length, 1);
+	});
+
+	await test('`ready` does not say it twice: the handler has just read the same token, and the card is replayed last', async () => {
+		const t = boot({ expired: true, profile: { name: 'Ada' } });
+		await t.host.checkCloudSession('ready');
+		assert.deepStrictEqual(t.posted, [], 'the check is quiet');
+		await t.host.replaySessionExpired();
+		assert.deepStrictEqual(t.types(), ['sessionExpired'], 'the last step speaks');
+	});
+
+	console.log('\nsessionExpiredHost: ' + n + ' tests passed.');
+})().catch((e) => { console.error(e); process.exit(1); });
diff --git a/extensions/levelcode-ai/test/sessionExpiredUi.test.js b/extensions/levelcode-ai/test/sessionExpiredUi.test.js
new file mode 100644
index 0000000..c702c65
--- /dev/null
+++ b/extensions/levelcode-ai/test/sessionExpiredUi.test.js
@@ -0,0 +1,198 @@
+/*---------------------------------------------------------------------------------------------
+ *  Static guards for the session-expired path in media/chat.html — run: node test/sessionExpiredUi.test.js
+ *
+ *  The incident this covers: a gateway 401 that a token refresh could not recover reached the
+ *  transcript as red text — "LevelCode Cloud API 401: Signature has expired" — while the account
+ *  popover still said "signed in". The fix routes `code: 'session_expired'` to a sign-in card in
+ *  BOTH error handlers and on a host-pushed startup check. A DOM test cannot see the routing
+ *  order inside the message switch; these read the source and pin it.
+ *
+ *  The host's BEHAVIOUR — what ends a session, what replays the card, who falls back to BYOK — is
+ *  run, not read, in sessionExpiredHost.test.js. What stays here is what can only be read: the order of
+ *  the `ready` handler and the wiring between the two files.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const html = fs.readFileSync(path.join(__dirname, '..', 'media', 'chat.html'), 'utf8');
+const ext = fs.readFileSync(path.join(__dirname, '..', 'extension.js'), 'utf8');
+const agent = fs.readFileSync(path.join(__dirname, '..', 'agent.js'), 'utf8');
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+/** The body of the `else if (m.type === '<type>'){ … }` branch — up to the next top-level `else if`. */
+function branch(type) {
+	const start = html.indexOf("m.type === '" + type + "'");
+	assert.ok(start > 0, 'no handler for ' + type);
+	const next = html.indexOf('\n    else if (m.type ===', start + 1);
+	return html.slice(start, next > 0 ? next : start + 2000);
+}
+
+test('a sign-in card exists and is a button, not text', () => {
+	assert.ok(/function addSignInCard\(/.test(html));
+	assert.ok(/data-act="signin"/.test(html.slice(html.indexOf('function addSignInCard('), html.indexOf('function addSignInCard(') + 2500)));
+	assert.ok(/type: 'accountSignIn'/.test(html.slice(html.indexOf('function addSignInCard('), html.indexOf('function addSignInCard(') + 2500)));
+});
+
+test('assistantError: session_expired is checked BEFORE the cap card and the red-text fallback', () => {
+	const b = branch('assistantError');
+	const i = b.indexOf('isSessionExpired(m)'), cap = b.indexOf('addUpgradeCard('), red = b.indexOf("class=\"err\"");
+	assert.ok(i > 0 && cap > 0 && red > 0, 'all three paths present');
+	assert.ok(i < cap && i < red, 'session check is not first');
+});
+
+test('agentError: the same ordering', () => {
+	const b = branch('agentError');
+	const i = b.indexOf('isSessionExpired(m)'), cap = b.indexOf('addUpgradeCard('), red = b.indexOf("class=\"err\"");
+	assert.ok(i > 0 && cap > 0 && red > 0, 'all three paths present');
+	assert.ok(i < cap && i < red, 'session check is not first');
+});
+
+test('a host-pushed sessionExpired (startup / focus check) shows the card before anything is typed', () => {
+	assert.ok(/m\.type === 'sessionExpired'\)\{ addSignInCard\(m\); \}/.test(html));
+});
+
+test('the card is dismissed when an account message says no expiry is waiting', () => {
+	// Signing in is one way to get there; BYOK chosen in Settings and a cleared cloud host are others.
+	// The host decides (currentAccount → `expired`); the webview does not keep its own list of reasons.
+	const b = branch('account');
+	assert.ok(/if \(!m\.expired && sessionCard && sessionCard\.isConnected\)\{ sessionCard\.remove\(\); sessionCard = null; \}/.test(b));
+	assert.ok(!/m\.signedIn && sessionCard/.test(b), 'not on sign-in alone');
+	assert.ok(/signedIn: true, mode, expired: false,/.test(ext) && /signedIn: false, mode, expired: sessionExpiredPending\(\),/.test(ext), 'both account shapes carry it');
+});
+
+test('the card uses an icon the inline codicon set actually defines', () => {
+	const m = /function addSignInCard\([\s\S]*?codicon\('([a-z-]+)'\)/.exec(html);
+	assert.ok(m, 'card has an icon');
+	assert.ok(new RegExp("'" + m[1] + "': \\{ vb:").test(html), 'icon "' + m[1] + '" is not in the set');
+});
+
+test('host: both send paths and the agent run name a dead session as session_expired', () => {
+	// Two shapes: the chat catch names it outright; the two prep-failure sites name it via a ternary on
+	// req.reason, so count the string wherever it appears as a code value.
+	assert.ok((ext.match(/'session_expired'/g) || []).length >= 3, 'chat catch + two prep sites');
+	assert.ok(/code: 'session_expired'/.test(agent), 'agent.js run-level catch');
+	assert.ok(/isSessionExpired: \(e\) =>/.test(ext), 'ctx hook handed to agent.js');
+});
+
+test('host: the webview ready handler checks the session before the first message', () => {
+	assert.ok(/case 'ready':[^\n]*await checkCloudSession\('ready'\)/.test(ext));
+	assert.ok(/onDidChangeWindowState/.test(ext), 'focus re-check');
+});
+
+test('host: every focus runs the check — the ten-minute ration is on the refresh, inside it', () => {
+	// With the ration in the hook, a window that had checked a minute ago did not look again, and so
+	// did not notice another window ending the session they share until the next message failed.
+	assert.ok(/onDidChangeWindowState\(\(st\) => \{\s*if \(st\.focused\) \{ checkCloudSession\('focus'\); \}/.test(ext), 'no time condition in the hook');
+	const fn = ext.slice(ext.indexOf('async function checkCloudSession('), ext.indexOf('async function refreshGatewayToken('));
+	const catchUp = fn.indexOf('await catchUpWithStoredSession(token)');
+	const ration = fn.indexOf("reason === 'focus' && Date.now() - lastSessionCheck <= SESSION_CHECK_EVERY_MS");
+	assert.ok(catchUp > 0 && ration > 0, 'both halves present');
+	assert.ok(catchUp < ration, 'catching up comes before the ration');
+});
+
+test('host: ready replays an unanswered expiry LAST — after the check, and under a replayed transcript', () => {
+	// The focus check can end the session with no chat open; post() then has nowhere to send the card,
+	// and the next `ready` finds no token to check. The replay is what shows it — and it has to come
+	// after the transcript replay, or a chat moved to an editor tab gets the card above its history.
+	const ready = /case 'ready':[^\n]*/.exec(ext)[0];
+	const check = ready.indexOf("await checkCloudSession('ready')");
+	const transcript = ready.indexOf('replayLiveTranscript(');
+	const replay = ready.indexOf('await replaySessionExpired()');
+	assert.ok(check >= 0 && transcript >= 0 && replay >= 0, 'all three steps present');
+	assert.ok(check < transcript && transcript < replay, 'order: check, transcript, expiry replay');
+	assert.ok(/await replaySessionExpired\(\); break;$/.test(ready.trimEnd()), 'the replay is the last thing ready does');
+});
+
+test('host: the card\'s "use my own key" button answers the expiry before it opens the setting', () => {
+	const byok = /case 'byokSettings':[^\n]*/.exec(ext)[0];
+	assert.ok(byok.indexOf('await clearSessionExpired()') >= 0, 'marker cleared');
+	assert.ok(byok.indexOf('await clearSessionExpired()') < byok.indexOf('workbench.action.openSettings'), 'before the settings open');
+});
+
+test('host: refresh stores the rotated refresh token and only a 401 ends the session', () => {
+	const fn = ext.slice(ext.indexOf('async function refreshCloudToken('), ext.indexOf('async function sessionExpired('));
+	assert.ok(/data\.refresh\)\s*\{\s*await ctx\.secrets\.store\(ACCOUNT_REFRESH_KEY, data\.refresh\)/.test(fn), 'rotation stored');
+	assert.ok(/session\.classifyRefresh\(/.test(fn), 'classified, not res.ok');
+	assert.ok(/outcome === 'expired'\)\s*\{\s*if \(await sessionExpired\(was\)\)/.test(fn), 'expired → sessionExpired, for the session the request was about');
+});
+
+test('host: only an ENDED session is signedOut — "no token" alone still falls back to BYOK', () => {
+	// Gateway is the default mode, so gating this on "no token" turned every BYOK user with no
+	// account into an expired session. It hangs off the marker sessionExpired() leaves instead.
+	const fn = ext.slice(ext.indexOf('async function prepProviderRequest('), ext.indexOf('function captureSelection('));
+	assert.ok(/if \(!token && sessionExpiredPending\(\)\) \{\s*return \{[^}]*reason: 'signedOut', gateway: true \};/.test(fn));
+	assert.ok(!/providerMode\(\) === 'gateway' && !token/.test(fn), 'the token-only condition is gone');
+	assert.ok(/req\.reason === 'signedOut'\)\s*\{ return session\.SESSION_EXPIRED_MESSAGE; \}/.test(ext));
+});
+
+test('host: the chat catch shows the card only once the session has ended, and never ends it itself', () => {
+	const fn = ext.slice(ext.indexOf('async function handleSend('), ext.indexOf('async function setModelSetting('));
+	// Chat and the agent ask ONE question, in one place — so a clause added for one (a sign-out is
+	// not an expiry) cannot be missing from the other.
+	assert.ok(/if \(isEndedSessionError\(req, e\)\) \{/.test(fn), 'the chat catch asks isEndedSessionError');
+	assert.ok(/isSessionExpired: \(e\) => isEndedSessionError\(req, e\),/.test(ext), 'and so does the hook handed to agent.js');
+	assert.ok(/refreshAuth: async \(\) => \{\s*if \(!req\.gateway\) \{ return null; \}\s*return \(await refreshGatewayToken\(\)\) \? await ctx\.secrets\.get\(ACCOUNT_TOKEN_KEY\) : null;/.test(ext), 'refreshAuth renews through the same refresh');
+	const rule = ext.slice(ext.indexOf('function isEndedSessionError('), ext.indexOf('async function clearSessionExpired('));
+	assert.ok(/!!\(req && req\.gateway\) && !cloudSignedIn && sessionExpiredPending\(\) && session\.isSessionExpiredError\(e\)/.test(rule), 'gateway, signed out, an expiry waiting, a 401');
+	assert.ok(!/\bsessionExpired\(/.test(fn.replace(/\/\/[^\n]*/g, '')), 'handleSend does not call sessionExpired()');
+	const only = (ext.replace(/\/\/[^\n]*/g, '').match(/await sessionExpired\(/g) || []).length;
+	assert.strictEqual(only, 1, 'one caller ends a session: the refresh endpoint answering 401');
+});
+
+// ── the card itself, run against a stand-in DOM ─────────────────────────────────────────────────
+function signInCard() {
+	const posted = [];
+	const log = { children: [], appendChild(c) { this.children.push(c); c.parent = this; c.isConnected = true; return c; } };
+	const createElement = () => {
+		const buttons = {};
+		return {
+			className: '', parent: null, isConnected: false, _html: '',
+			set innerHTML(v) { this._html = String(v); for (const m of this._html.matchAll(/data-act="([\w-]+)"/g)) { buttons[m[1]] = { onclick: null }; } },
+			get innerHTML() { return this._html; },
+			querySelector(sel) { const m = /^\[data-act="([\w-]+)"\]$/.exec(sel); assert.ok(m, 'stand-in DOM cannot parse ' + sel); return buttons[m[1]] || null; },
+			remove() { if (this.parent) { this.parent.children.splice(this.parent.children.indexOf(this), 1); } this.parent = null; this.isConnected = false; }
+		};
+	};
+	const start = html.indexOf('function addSignInCard(');
+	const fnSrc = html.slice(start, html.indexOf('\n  }', start) + 4);
+	// eslint-disable-next-line no-new-func
+	const api = new Function('document', 'log', 'vscode',
+		'const clearStatus = () => {}, finishAgentBubble = () => {}, closeGroup = () => {}, scrollIfStuck = () => {};\n'
+		+ 'const esc = (s) => String(s), codicon = (n) => "<i:" + n + ">";\nlet sessionCard = null;\n' + fnSrc
+		+ '\nreturn { addSignInCard, current: () => sessionCard };')({ createElement }, log, { postMessage: (m) => posted.push(m) });
+	return { api, log, posted };
+}
+
+test('card: a second expiry notice replaces the first — one card, however many paths find it', () => {
+	const { api, log } = signInCard();
+	api.addSignInCard({ name: 'Ada' });
+	api.addSignInCard({});   // e.g. the assistantError that follows the host-pushed notice
+	assert.strictEqual(log.children.length, 1);
+	assert.strictEqual(api.current(), log.children[0]);
+});
+
+test('card: "Sign in" starts the sign-in and leaves the card up until an account message says it worked', () => {
+	const { api, log, posted } = signInCard();
+	api.addSignInCard({ name: 'Ada' });
+	assert.ok(/Welcome back, Ada\./.test(log.children[0].innerHTML));
+	log.children[0].querySelector('[data-act="signin"]').onclick();
+	assert.deepStrictEqual(posted, [{ type: 'accountSignIn' }]);
+	assert.strictEqual(log.children.length, 1);
+});
+
+test('card: "Use my own key instead" tells the host and takes the card away', () => {
+	const { api, log, posted } = signInCard();
+	api.addSignInCard({});
+	log.children[0].querySelector('[data-act="byok"]').onclick();
+	assert.deepStrictEqual(posted, [{ type: 'byokSettings' }]);
+	assert.strictEqual(log.children.length, 0, 'the card is gone');
+	assert.strictEqual(api.current(), null);
+});
+
+console.log('\nsessionExpiredUi: ' + n + ' tests passed.');