@vincentt-xr/cli 0.20.0 → 0.21.0

package/dist/login/loginCommand.js

@@ -7,8 +7,10 @@
 // L1–L4 branch is unit-testable with no real browser, socket, or config file.
 import os from "node:os";
 import { isAuthRefused } from "../shared/authError.js";
+import { UpgradeRequiredError, upgradeRefusalLines } from "../shared/upgradeError.js";
 import { EXIT } from "../lib/exitCodes.js";
 import { dayMonth, sanitizeServerLabel } from "./machineLabel.js";
+import { SignedInThenRefusedError } from "./pkceLogin.js";
 /** Collapse the home dir to `~` for display. `~/.vincentt/config.json` in every transcript. */
 export function displayConfigPath(absPath, home) {
     if (home && absPath.startsWith(home))
@@ -58,8 +60,10 @@ export async function loginCommand(deps, opts = {}) {
         // The old token stays on disk until the new one is saved: a failed login must
         // never leave the machine with neither.
         const old = deps.storedToken ? await deps.storedToken() : undefined;
-        const code = await runLoginFlow(deps);
-        if (code === EXIT.OK && old && deps.revokeToken) {
+        const { code, saved } = await signIn(deps);
+        // Keyed on the new token being SAVED, not on success: a version refusal
+        // after the save still replaced the old token, which must not stay live.
+        if (saved && old && deps.revokeToken) {
             try {
                 await deps.revokeToken(old);
             }
@@ -78,6 +82,8 @@ export async function loginCommand(deps, opts = {}) {
                 who = await deps.whoAmI();
             }
             catch (err) {
+                if (err instanceof UpgradeRequiredError)
+                    return refusedVersion(deps, err);
                 if (!isTokenRejected(err)) {
                     // A down api or a dead network says nothing about the token, so it stays.
                     deps.print("✗ Could not check the account for the token on this machine.");
@@ -102,6 +108,10 @@ function isTokenRejected(err) {
         (err instanceof Error && err.status === 403));
 }
 async function runLoginFlow(deps) {
+    return (await signIn(deps)).code;
+}
+/** The flow's exit code, and whether a new token was written to this machine. */
+async function signIn(deps) {
     // L1 / L4 — run the loopback + PKCE flow.
     try {
         const { identity, configPath, label, evicted } = await deps.runLogin();
@@ -116,16 +126,33 @@ async function runLoginFlow(deps) {
         deps.print(`  Token saved to ${displayConfigPath(configPath, deps.home)}`);
         deps.print("");
         deps.print("Run `vincentt --help` to see what you can do.");
-        return 0;
+        return { code: EXIT.OK, saved: true };
     }
     catch (err) {
+        // Refused after the exchange: the token is on disk, so the screen says so
+        // and names any machine this sign-in signed out.
+        if (err instanceof SignedInThenRefusedError) {
+            const arm = { kind: "login_saved", evictionLines: err.evicted.map(evictionLine) };
+            for (const l of upgradeRefusalLines(err, arm))
+                deps.print(l);
+            return { code: EXIT.UPGRADE_REQUIRED, saved: true };
+        }
+        // The exchange is judged before anything is minted, so no token was written.
+        if (err instanceof UpgradeRequiredError) {
+            return { code: refusedVersion(deps, err), saved: false };
+        }
         // L4 — timeout / callback failure: ✗ line + the exact next command. No token written.
         const message = err instanceof Error ? err.message : "Sign-in failed.";
         deps.print(`✗ ${message}`);
         deps.print("  Run `vincentt login` to try again.");
-        return 1;
+        return { code: EXIT.FAILED, saved: false };
     }
 }
+function refusedVersion(deps, err) {
+    for (const l of upgradeRefusalLines(err, { kind: "login" }))
+        deps.print(l);
+    return EXIT.UPGRADE_REQUIRED;
+}
 /**
  * `vincentt logout` (Flow L7): the platform sign-out was already attempted; the
  * local token is ALWAYS deleted, and only an api that could not be reached adds

package/dist/login/pkceLogin.d.ts

@@ -1,4 +1,5 @@
 import { type AuthBackend, type EvictedMachine, type Identity } from "./authBackend.js";
+import { UpgradeRequiredError } from "../shared/upgradeError.js";
 export interface PkceLoginOptions {
     /** Console origin that serves /cli-auth (browser target). */
     consoleUrl: string;
@@ -31,6 +32,15 @@ export interface PkceLoginResult {
 export declare class LoginTimeoutError extends Error {
     constructor();
 }
+/**
+ * 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 declare class SignedInThenRefusedError extends UpgradeRequiredError {
+    readonly evicted: EvictedMachine[];
+    constructor(refused: UpgradeRequiredError, evicted?: EvictedMachine[]);
+}
 /** Thrown when the loopback callback fails state-verify or is cancelled (QA-F1-C3). */
 export declare class LoginCallbackError extends Error {
     constructor(message: string);

package/dist/login/pkceLogin.js

@@ -17,6 +17,7 @@ import { writeMachineConfig } from "../shared/config.js";
 import { makePkceMaterial, buildCliAuthUrl, parseCallback, } from "./pkce.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() {
@@ -24,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) {
@@ -170,6 +184,15 @@ export async function runPkceLogin(opts) {
     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);
+    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

@@ -455,12 +455,25 @@ export function endedAuthExpired() {
         "",
     ];
 }
-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.
  *