@vincentt-xr/cli 0.19.0 → 0.21.0

package/dist/login/pkceLogin.js

@@ -5,7 +5,8 @@
 //   2. Mint state + PKCE code_verifier/code_challenge (S256).
 //   3. Open the browser to /cli-auth?redirect_uri=<loopback>&state=…&code_challenge=….
 //   4. On the loopback callback: verify state constant-time (reject mismatch → no exchange).
-//   5. POST /access-tokens/exchange {code, code_verifier} → raw PAT (in body, once).
+//   5. POST /access-tokens/exchange {code, code_verifier, label} → raw PAT (in body, once),
+//      the stored label, and any machines the 10-machine cap signed out.
 //   6. Write ~/.vincentt/config.json, then GET /me Bearer <PAT> to confirm identity + orgs.
 //
 // Every external boundary is injected (getFreePort, listen, openBrowser, backend, clock/
@@ -14,8 +15,9 @@
 import { getFreePort } from "../preview/net.js";
 import { writeMachineConfig } from "../shared/config.js";
 import { makePkceMaterial, buildCliAuthUrl, parseCallback, } from "./pkce.js";
-import { httpAuthBackend } from "./authBackend.js";
+import { httpAuthBackend, } from "./authBackend.js";
 import { waitForLoopbackCallback } from "./loopback.js";
+import { UpgradeRequiredError } from "../shared/upgradeError.js";
 /** Thrown when the wait elapses with no approval; drives the L4 timeout transcript. */
 export class LoginTimeoutError extends Error {
     constructor() {
@@ -23,6 +25,19 @@ export class LoginTimeoutError extends Error {
         this.name = "LoginTimeoutError";
     }
 }
+/**
+ * The exchange was admitted and the token SAVED, then the identity check was
+ * refused for this CLI's version. Distinct from a refused exchange: a sign-in
+ * now exists on this machine, and machines may have been signed out for it.
+ */
+export class SignedInThenRefusedError extends UpgradeRequiredError {
+    evicted;
+    constructor(refused, evicted = []) {
+        super(refused.minimum, refused.declared);
+        this.evicted = evicted;
+        this.name = "SignedInThenRefusedError";
+    }
+}
 /** Thrown when the loopback callback fails state-verify or is cancelled (QA-F1-C3). */
 export class LoginCallbackError extends Error {
     constructor(message) {
@@ -166,8 +181,18 @@ export async function runPkceLogin(opts) {
         },
     });
     // (5) redeem the code for the raw PAT; (6) persist then confirm identity.
-    const pat = await backend.exchange(code, material.codeVerifier);
+    const exchanged = await backend.exchange(code, material.codeVerifier, opts.label);
+    const pat = exchanged.token;
     const configPath = await saveToken(opts.apiUrl.replace(/\/$/, ""), pat);
-    const identity = await backend.me(pat);
-    return { identity, configPath };
+    let identity;
+    try {
+        identity = await backend.me(pat);
+    }
+    catch (err) {
+        if (err instanceof UpgradeRequiredError) {
+            throw new SignedInThenRefusedError(err, exchanged.evicted);
+        }
+        throw err;
+    }
+    return { identity, configPath, label: exchanged.label, evicted: exchanged.evicted };
 }

package/dist/platform/releaseFetch.js

@@ -11,9 +11,7 @@
  * The 2s budget is f7's `FETCH_TIMEOUT_MS`, reused rather than re-chosen. A
  * second timeout constant is a second thing to tune and the one nobody finds.
  */
-import http from "node:http";
-import https from "node:https";
-import { CLIENT_HEADER, clientHeaderValue } from "../shared/clientHeader.js";
+import { apiRequest, apiRequestDetached } from "../shared/http.js";
 import { FETCH_TIMEOUT_MS } from "../dx/updateCheck.js";
 import { readPlatformRelease } from "./releaseCache.js";
 import { platformCheckEnabled } from "./offSwitch.js";
@@ -35,18 +33,14 @@ export async function fetchRelease(opts) {
     const onAbort = () => controller.abort();
     opts.signal?.addEventListener("abort", onAbort, { once: true });
     try {
-        const res = await fetchImpl(`${opts.apiUrl.replace(/\/$/, "")}${VERSIONS_PATH}`, {
+        // The client tag rides along (apiRequest stamps it) because the middleware
+        // LOGS it, and logging is not branching: the handler reads no header but
+        // `If-None-Match`, so this cannot change the answer. No credential: the
+        // route is public and never judged by the CLI floor.
+        const res = await apiRequest({ apiUrl: opts.apiUrl }, VERSIONS_PATH, {
             signal: controller.signal,
-            headers: {
-                // The client tag rides along because the existing middleware LOGS it,
-                // and logging is not branching: the handler reads no header but
-                // `If-None-Match`, so this cannot change the answer. Omitting it would
-                // make this one route's requests distinguishable from every other
-                // request the CLI makes, which is the opposite of what is wanted.
-                [CLIENT_HEADER]: clientHeaderValue(),
-                ...(opts.etag ? { "if-none-match": opts.etag } : {}),
-            },
-        });
+            headers: opts.etag ? { "if-none-match": opts.etag } : {},
+        }, { authenticated: false }, fetchImpl);
         if (!res.ok)
             return undefined;
         const release = readPlatformRelease(await res.json());
@@ -90,61 +84,34 @@ export async function fetchRelease(opts) {
 export function fetchReleaseDetached(opts, onResult) {
     if (!platformCheckEnabled())
         return;
-    let url;
-    try {
-        url = new URL(`${opts.apiUrl.replace(/\/$/, "")}${VERSIONS_PATH}`);
-    }
-    catch {
-        return;
-    }
-    const transport = url.protocol === "https:" ? https : http;
-    try {
-        const req = transport.request({
-            protocol: url.protocol,
-            hostname: url.hostname,
-            port: url.port,
-            path: `${url.pathname}${url.search}`,
-            method: "GET",
-            headers: {
-                [CLIENT_HEADER]: clientHeaderValue(),
-                ...(opts.etag ? { "if-none-match": opts.etag } : {}),
-            },
-        }, (res) => {
-            if (res.statusCode !== 200) {
-                res.resume();
-                return;
+    // The socket is unref'd inside apiRequestDetached: without that a pending
+    // request is an active handle and the process waits on it.
+    apiRequestDetached({ apiUrl: opts.apiUrl }, VERSIONS_PATH, opts.etag ? { "if-none-match": opts.etag } : {}, FETCH_TIMEOUT_MS, (res, abort) => {
+        if (res.statusCode !== 200) {
+            res.resume();
+            return;
+        }
+        let body = "";
+        res.setEncoding("utf8");
+        res.on("data", (chunk) => {
+            body += chunk;
+            // Bounded: this is parsed on a creator's machine off a public route,
+            // and an endless body must not grow without limit.
+            if (body.length > 256_000)
+                abort();
+        });
+        res.on("end", () => {
+            try {
+                const release = readPlatformRelease(JSON.parse(body));
+                if (release === undefined)
+                    return;
+                const etag = res.headers.etag;
+                onResult(typeof etag === "string" ? { release, etag } : { release });
+            }
+            catch {
+                // A malformed body is nothing to say.
             }
-            let body = "";
-            res.setEncoding("utf8");
-            res.on("data", (chunk) => {
-                body += chunk;
-                // Bounded: this is parsed on a creator's machine off a public route,
-                // and an endless body must not grow without limit.
-                if (body.length > 256_000)
-                    req.destroy();
-            });
-            res.on("end", () => {
-                try {
-                    const release = readPlatformRelease(JSON.parse(body));
-                    if (release === undefined)
-                        return;
-                    const etag = res.headers.etag;
-                    onResult(typeof etag === "string" ? { release, etag } : { release });
-                }
-                catch {
-                    // A malformed body is nothing to say.
-                }
-            });
-            res.on("error", () => { });
         });
-        // THE LOAD-BEARING CALL. Without it a pending request is an active handle
-        // and the process waits on it.
-        req.on("socket", (socket) => socket.unref());
-        req.on("error", () => { });
-        req.setTimeout(FETCH_TIMEOUT_MS, () => req.destroy());
-        req.end();
-    }
-    catch {
-        // A refresh that cannot even be started is nothing to say.
-    }
+        res.on("error", () => { });
+    });
 }

package/dist/preview/api.js

@@ -8,7 +8,8 @@ import { createHash } from "node:crypto";
 import { realpath } from "node:fs/promises";
 import { BackendError, ProjectUnreachableError } from "../lib/backend.js";
 import { rejectAuthExpired } from "../shared/authError.js";
-import { apiFetch } from "../shared/http.js";
+import { apiFetch, apiRequest } from "../shared/http.js";
+import { rejectUpgradeRequired } from "../shared/upgradeError.js";
 /** The mint rate limit (§2.16). `retryAfterSec` comes from the header, never the body. */
 export class PreviewRateLimitedError extends BackendError {
     retryAfterSec;
@@ -106,9 +107,6 @@ async function errorBody(res) {
         return {};
     }
 }
-function authHeaders(cfg) {
-    return { authorization: `Bearer ${cfg.pat}`, "content-type": "application/json" };
-}
 /**
  * parseRetryAfter reads the 429's header. The BODY carries no discriminator for
  * which of the two mint limits fired — the header answers "how long", never
@@ -121,11 +119,12 @@ export function parseRetryAfter(raw) {
 }
 /** POST /projects/{id}/preview-sessions — mint. */
 export async function mintPreviewSession(cfg, projectId, key, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/preview-sessions`, {
+    const res = await apiRequest(cfg, `/projects/${encodeURIComponent(projectId)}/preview-sessions`, {
         method: "POST",
-        headers: authHeaders(cfg),
+        headers: { "content-type": "application/json" },
         body: JSON.stringify({ workingTreeKey: key }),
-    });
+    }, { authenticated: true }, fetchImpl);
+    await rejectUpgradeRequired(res);
     if (res.status === 429) {
         throw new PreviewRateLimitedError(parseRetryAfter(res.headers.get("retry-after")));
     }
@@ -189,8 +188,9 @@ export function parseMint(raw) {
 }
 /** POST /preview-sessions/{id}/heartbeat — keepalive AND re-authorization. */
 export async function heartbeatPreviewSession(cfg, sessionId, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${cfg.apiUrl}/preview-sessions/${encodeURIComponent(sessionId)}/heartbeat`, { method: "POST", headers: authHeaders(cfg) });
+    const res = await apiRequest(cfg, `/preview-sessions/${encodeURIComponent(sessionId)}/heartbeat`, { method: "POST", headers: { "content-type": "application/json" } }, { authenticated: true }, fetchImpl);
     if (!res.ok) {
+        await rejectUpgradeRequired(res);
         rejectAuthExpired(res);
         const body = await errorBody(res);
         if (res.status === 410) {
@@ -216,10 +216,7 @@ export async function heartbeatPreviewSession(cfg, sessionId, fetchImpl = apiFet
  */
 export async function endPreviewSession(cfg, sessionId, fetchImpl = apiFetch) {
     try {
-        await fetchImpl(`${cfg.apiUrl}/preview-sessions/${encodeURIComponent(sessionId)}`, {
-            method: "DELETE",
-            headers: { authorization: `Bearer ${cfg.pat}` },
-        });
+        await apiRequest(cfg, `/preview-sessions/${encodeURIComponent(sessionId)}`, { method: "DELETE" }, { authenticated: true }, fetchImpl);
     }
     catch {
         // See above.

package/dist/preview/command.d.ts

@@ -2,6 +2,7 @@ import type { DiagEvent } from "@vincentt-xr/harness/events";
 import type { TunnelState, UAClass } from "../tunnel/index.js";
 import type { EventTags } from "../relay/server.js";
 import type { PreviewEndReason } from "./runner.js";
+import { type UpgradeFacts } from "../shared/upgradeError.js";
 export interface PreviewUiDeps {
     print: (line: string) => void;
     now: () => number;
@@ -124,13 +125,13 @@ export declare class PreviewUi {
     stopping(): void;
     stopped(): void;
     /** Every ending the creator did NOT cause. One first line per cause. */
-    endedBy(reason: PreviewEndReason, orgName: string): void;
+    endedBy(reason: PreviewEndReason, orgName: string, refusal?: UpgradeFacts): void;
     following(label: string): void;
     notFollowing(label: string): void;
     notFollowingTester(tester: string): void;
     /** Live testers — what `stopping`/`stopped` should be counting. */
     get testerCount(): number;
 }
-export declare function endingLines(reason: PreviewEndReason, orgName: string): string[];
+export declare function endingLines(reason: PreviewEndReason, orgName: string, refusal?: UpgradeFacts): string[];
 /** `21:04` — what a creator plans a demo around, in their own local time. */
 export declare function clockTime(d: Date): string;

package/dist/preview/command.js

@@ -15,6 +15,7 @@ import * as copy from "./copy.js";
 import { PerfThrottle, palette, renderAnnotation, renderEvent, uaLabel, } from "./stream.js";
 import { ViewerRoster } from "./viewers.js";
 import { MAX_TESTERS } from "../relay/testers.js";
+import { previewTooOldLines } from "../shared/upgradeError.js";
 /** How long a viewer may be present with no harness hello before the runtime line. */
 export const NO_DIAGNOSTICS_WINDOW_MS = 10_000;
 function defaultSchedule(fn, ms) {
@@ -295,11 +296,11 @@ export class PreviewUi {
         this.line("");
     }
     /** Every ending the creator did NOT cause. One first line per cause. */
-    endedBy(reason, orgName) {
+    endedBy(reason, orgName, refusal) {
         if (this.ended)
             return;
         this.ended = true;
-        this.lines(endingLines(reason, orgName));
+        this.lines(endingLines(reason, orgName, refusal));
     }
     // ---- --viewer -------------------------------------------------------------
     following(label) {
@@ -317,7 +318,7 @@ export class PreviewUi {
         return this.roster.testerCount;
     }
 }
-export function endingLines(reason, orgName) {
+export function endingLines(reason, orgName, refusal = {}) {
     switch (reason) {
         case "hard_max":
             return copy.hardMaxReached();
@@ -331,8 +332,10 @@ export function endingLines(reason, orgName) {
             return copy.endedAbandoned();
         case "authz_revoked":
             return copy.endedUnreachable(orgName);
-        case "authz_unconfirmed":
-            return copy.endedUnconfirmed();
+        case "authz_lapsed":
+            return copy.endedAuthzLapsed();
+        case "upgrade_required":
+            return previewTooOldLines(refusal);
         case "auth_expired":
             return copy.endedAuthExpired();
         case "egress_cap":

package/dist/preview/copy.d.ts

@@ -211,7 +211,14 @@ export declare function endedUnreachable(orgName: string): string[];
  * project and the access are fine, and the one thing to do is sign in again.
  */
 export declare function endedAuthExpired(): string[];
-export declare function endedUnconfirmed(): string[];
+/**
+ * The `authzUntil` drain: the edge ended the session because the platform
+ * stopped confirming it, and told this CLI so. It names no access, permission or
+ * outage, because the wire carries none of those and the cause may be on either
+ * side. "so one isn't started for you" is load-bearing: a new preview is a new
+ * link, and a silent re-mint would break every link already shared.
+ */
+export declare function endedAuthzLapsed(): string[];
 /**
  * e. Abandoned — this machine stopped checking in (the 30-minute heartbeat-
  * silence flip, `D-Abandoned-sessions-are-judged-on-heartbeat-silence-alone`).

package/dist/preview/copy.js

@@ -448,19 +448,32 @@ export function endedUnreachable(orgName) {
 export function endedAuthExpired() {
     return [
         "",
-        "✗ Preview ended. Your Vincentt access token is no longer valid.",
+        "✗ Preview ended. This machine is no longer signed in to Vincentt.",
         "",
         "  Sign in again:  vincentt login",
         "  Then start a new preview:  vincentt preview",
         "",
     ];
 }
-export function endedUnconfirmed() {
+/**
+ * The `authzUntil` drain: the edge ended the session because the platform
+ * stopped confirming it, and told this CLI so. It names no access, permission or
+ * outage, because the wire carries none of those and the cause may be on either
+ * side. "so one isn't started for you" is load-bearing: a new preview is a new
+ * link, and a silent re-mint would break every link already shared.
+ */
+export function endedAuthzLapsed() {
     return [
         "",
-        "✗ Preview ended. Couldn't confirm your access to this project.",
+        "✗ Preview ended. Vincentt stopped confirming it, and the link no longer works.",
+        "",
+        "  This window can't tell whether this machine lost touch with Vincentt or",
+        "  the cause was on our side. Nothing is wrong with your project.",
         "",
-        "  Try again:  vincentt preview",
+        "  A new preview gets a new link, so one isn't started for you. Any phone on",
+        "  the old link will need the new one.",
+        "",
+        "  Start a new one:  vincentt preview",
         "",
     ];
 }

package/dist/preview/proxy.js

@@ -4,6 +4,7 @@
 import { connect } from "node:net";
 import { request, } from "node:http";
 import { createGzip } from "node:zlib";
+import { CREDENTIAL_NAMES, PREVIEW_STRIP, foldName, isCredentialName, } from "../shared/credentialNames.js";
 // Rewrite Host to the loopback target. cloudflared forwards the public Host, and
 // esbuild's `serve` 403s any Host it doesn't recognize — so the phone would get a
 // 403. The origin only needs a Host it accepts; the browser never sees this value.
@@ -187,8 +188,10 @@ export function isHiddenAppPath(url, projectRoot) {
             const name = normalizedName(s);
             if (name === REFUSE)
                 return true;
-            if (SHORT_NAME.test(name) || isCredentialName(name))
+            if (SHORT_NAME.test(name) ||
+                isCredentialName(name, CREDENTIAL_NAMES, PREVIEW_STRIP)) {
                 return true;
+            }
         }
     }
     return false;
@@ -222,8 +225,7 @@ const REFUSE = Symbol("refuse");
 function normalizedName(segment) {
     if (segment.includes(":$"))
         return REFUSE;
-    const beforeColon = segment.split(":")[0] ?? "";
-    return beforeColon.replace(/[. ]+$/, "").normalize("NFKC").toUpperCase().toLowerCase();
+    return foldName(segment.split(":")[0] ?? "");
 }
 /**
  * A Windows 8.3 short name (`GIT~1`, `CREDEN~1.JSO`) opens the long-named file
@@ -232,42 +234,6 @@ function normalizedName(segment) {
  * proxy can front a Windows file system from any client.
  */
 const SHORT_NAME = /^[^~]{1,6}~[0-9]/;
-/** D-Preview-hides-credential-files: hard-coded, no opt-out. `*` is any run of characters. */
-const CREDENTIAL_NAMES = Object.freeze([
-    "credentials.json",
-    "service-account*.json",
-    "*firebase-adminsdk*.json",
-    "*.pem",
-    "*.key",
-    "*.p12",
-    "*.pfx",
-    "*.p8",
-    "*.ppk",
-    "id_rsa*",
-    "id_dsa*",
-    "id_ed25519*",
-    "id_ecdsa*",
-    "*.jks",
-    "*.keystore",
-    "*.env",
-    "*.tfstate",
-    "*.tfvars",
-].map((glob) => new RegExp(`^${glob
-    .split("*")
-    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
-    .join(".*")}$`, "s")));
-/** A listed name, or one with backup endings (`~`, `.bak`) added, any number of times. */
-function isCredentialName(name) {
-    let candidate = name;
-    for (;;) {
-        if (CREDENTIAL_NAMES.some((re) => re.test(candidate)))
-            return true;
-        const stripped = candidate.replace(/(?:~|\.bak)$/, "");
-        if (stripped === candidate)
-            return false;
-        candidate = stripped;
-    }
-}
 function checkedSegmentIndexes(segments, projectRoot) {
     const all = segments.map((_, i) => i);
     if (segments[0] !== "@fs")

package/dist/preview/runner.d.ts

@@ -2,6 +2,7 @@ import { type ControlKind, type TunnelState, type UAClass } from "../tunnel/inde
 import type { DiagEvent } from "@vincentt-xr/harness/events";
 import { type EventTags } from "../relay/server.js";
 import { type ResolvedConfig } from "../shared/config.js";
+import { type UpgradeFacts } from "../shared/upgradeError.js";
 /** The path a 404 advisory names: the request's own path, without its query. */
 export declare function requestPathOf(url: string | undefined): string;
 /**
@@ -31,7 +32,19 @@ export type PreviewEndReason = "stopped"
  * elapsed without the client getting back): same remedy, different diagnosis,
  * and the copy explains the bound only at the moment it bites.
  */
- | "grace_cap" | "authz_revoked" | "authz_unconfirmed"
+ | "grace_cap" | "authz_revoked"
+/**
+ * The edge drained the session because the platform stopped confirming it,
+ * and said so (CONTROL `authz_expired`). Final: a new preview is a new link,
+ * so nothing is re-minted and nothing redials.
+ */
+ | "authz_lapsed"
+/**
+ * The platform refused this CLI's version, on the heartbeat (426) or on a
+ * dial (410 + `X-Vincentt-Refusal: cli_upgrade_required`). One screen for
+ * both. No further platform call is made, the DELETE included.
+ */
+ | "upgrade_required"
 /**
  * The 30-minute heartbeat-silence flip. NEVER reported as `hard_max`: a
  * session ended at minute 30 has not reached its 12-hour ceiling, and saying
@@ -130,8 +143,11 @@ export interface StartPreviewOptions {
     onOriginError?: (label: string, code: string) => void;
     /** Their dev server answered again. Re-arms the advisory; prints NOTHING. */
     onOriginRecovered?: () => void;
-    /** The session ended for a reason the creator did not cause. */
-    onEnded?: (reason: PreviewEndReason) => void;
+    /**
+     * The session ended for a reason the creator did not cause. `refusal` carries
+     * the validated floor facts on `upgrade_required` only.
+     */
+    onEnded?: (reason: PreviewEndReason, refusal?: UpgradeFacts) => void;
     /** The hard max is approaching. A WARNING, never an ending (L20b). */
     onExpiring?: () => void;
     /** Injected for tests. */
@@ -154,11 +170,11 @@ export interface RunningPreview {
 }
 export declare function startPreview(opts: StartPreviewOptions): Promise<RunningPreview>;
 /**
- * Two of the three CONTROL kinds are endings. `expiring` is NOT: it is the
- * hard-max warning, and it arrives on the same channel. Mapping it to an ending
- * would take away a link that has half an hour left, at exactly the moment the
- * creator is being warned to plan around it — so it returns null and the caller
- * renders the warning instead.
+ * Three of the four kinds that reach onControl are endings. `expiring` is NOT:
+ * it is the hard-max warning, and it arrives on the same channel. Mapping it to
+ * an ending would take away a link that has half an hour left, at exactly the
+ * moment the creator is being warned to plan around it, so it returns null and
+ * the caller renders the warning instead. (`viewer_gone` never reaches here.)
  */
 export declare function controlToReason(kind: ControlKind): PreviewEndReason | null;
 /**
@@ -199,7 +215,7 @@ export declare function refusalToReason(status: number): PreviewEndReason | null
  * reason maps to its own screen. A 410 with no reason gets the cause-free
  * ending. See the note on PreviewEndedError.
  */
-export declare function runHeartbeat(config: ResolvedConfig, sessionId: string, fetchImpl: typeof fetch, onEnded?: (reason: PreviewEndReason) => void): Promise<void>;
+export declare function runHeartbeat(config: ResolvedConfig, sessionId: string, fetchImpl: typeof fetch, onEnded?: (reason: PreviewEndReason, refusal?: UpgradeFacts) => void): Promise<void>;
 /**
  * The API's `endReason` → the CLI's ending screen.
  *

package/dist/preview/runner.js

@@ -26,6 +26,7 @@ import { withoutCliCredentials } from "../shared/config.js";
 import { ProjectUnreachableError } from "../lib/backend.js";
 import { AuthExpiredError } from "../shared/authError.js";
 import { apiFetch } from "../shared/http.js";
+import { UpgradeRequiredError, parseDeclared, parseMinimum, } from "../shared/upgradeError.js";
 import { terminalSafe } from "../lib/terminalText.js";
 /** The path a 404 advisory names: the request's own path, without its query. */
 export function requestPathOf(url) {
@@ -63,6 +64,17 @@ export async function startPreview(opts) {
     let heartbeat;
     let minted;
     let stopped = false;
+    // Set once the platform refuses this CLI's version: every later platform
+    // call would be refused too, so none is made.
+    let versionRefused = false;
+    const ended = (reason, refusal) => {
+        if (reason === "upgrade_required") {
+            versionRefused = true;
+            if (heartbeat !== undefined)
+                clearInterval(heartbeat);
+        }
+        opts.onEnded?.(reason, refusal);
+    };
     const stop = async () => {
         if (stopped)
             return;
@@ -84,8 +96,9 @@ export async function startPreview(opts) {
         // best-effort in intent even though it is in effect: the 12-hour ceiling
         // and the edge's 60-second fail-closed deadline both reap a session whose
         // DELETE never landed.
-        if (minted)
+        if (minted && !versionRefused) {
             await endPreviewSession(config, minted.sessionId, fetchImpl);
+        }
     };
     try {
         // The MINT comes first. Everything below it costs the creator a dev-server
@@ -231,7 +244,7 @@ export async function startPreview(opts) {
                     opts.onExpiring?.();
                     return;
                 }
-                opts.onEnded?.(reason);
+                ended(reason);
             },
             onOriginError: opts.onOriginError,
             onStateChange: opts.onTunnelState,
@@ -241,8 +254,12 @@ export async function startPreview(opts) {
             onReconnectRefused: (status) => {
                 const reason = refusalToReason(status);
                 if (reason !== null)
-                    opts.onEnded?.(reason);
+                    ended(reason);
             },
+            onRefused: (_reason, minimum, declared) => ended("upgrade_required", {
+                minimum: parseMinimum(minimum),
+                declared: parseDeclared(declared),
+            }),
         });
         tunnel.start();
         // The heartbeat is keepalive AND re-authorization: every beat re-runs
@@ -252,10 +269,10 @@ export async function startPreview(opts) {
         // One beat in flight at a time: a slow api must not stack up requests.
         let beating = false;
         heartbeat = setInterval(() => {
-            if (beating)
+            if (beating || versionRefused)
                 return;
             beating = true;
-            void runHeartbeat(config, minted.sessionId, fetchImpl, opts.onEnded).finally(() => {
+            void runHeartbeat(config, minted.sessionId, fetchImpl, ended).finally(() => {
                 beating = false;
             });
         }, minted.heartbeatSec * 1000);
@@ -284,18 +301,24 @@ export async function startPreview(opts) {
     }
 }
 /**
- * Two of the three CONTROL kinds are endings. `expiring` is NOT: it is the
- * hard-max warning, and it arrives on the same channel. Mapping it to an ending
- * would take away a link that has half an hour left, at exactly the moment the
- * creator is being warned to plan around it — so it returns null and the caller
- * renders the warning instead.
+ * Three of the four kinds that reach onControl are endings. `expiring` is NOT:
+ * it is the hard-max warning, and it arrives on the same channel. Mapping it to
+ * an ending would take away a link that has half an hour left, at exactly the
+ * moment the creator is being warned to plan around it, so it returns null and
+ * the caller renders the warning instead. (`viewer_gone` never reaches here.)
  */
 export function controlToReason(kind) {
-    if (kind === "superseded")
-        return "superseded";
-    if (kind === "revoke")
-        return "authz_revoked";
-    return null;
+    switch (kind) {
+        case "superseded":
+            return "superseded";
+        case "revoke":
+            return "authz_revoked";
+        case "authz_expired":
+            return "authz_lapsed";
+        case "expiring":
+        case "viewer_gone":
+            return null;
+    }
 }
 /**
  * A refused RECONNECT dial → the ending screen it means.
@@ -346,6 +369,10 @@ export async function runHeartbeat(config, sessionId, fetchImpl, onEnded) {
         await heartbeatPreviewSession(config, sessionId, fetchImpl);
     }
     catch (err) {
+        if (err instanceof UpgradeRequiredError) {
+            onEnded?.("upgrade_required", { minimum: err.minimum, declared: err.declared });
+            return;
+        }
         if (err instanceof AuthExpiredError) {
             onEnded?.("auth_expired");
             return;