@vincentt-xr/cli 0.20.0 → 0.22.0

package/dist/dx/enablement.js

@@ -1,16 +1,16 @@
 /**
  * Durable authorization for unattended `vincentt dx --send`.
  *
- * `--send` transmits only when the session is interactive, OR this MACHINE has been
- * enabled via `vincentt dx enable`, OR the creator's ACCOUNT carries the grant they
- * gave in the console. `enable` collects that consent in the browser by default and
- * at the terminal when there is one; either way a person answers, never the caller.
+ * `--send` transmits only when the session is interactive, OR the creator's ACCOUNT
+ * carries the grant, OR — only when the account cannot be read — this machine's cached
+ * copy of that grant is valid. `enable` records the account grant at the terminal or in
+ * the browser; either way a person answers, never the caller.
  *
- * The machine half is two fields in ~/.vincentt/config.json, set by `enable`, cleared
- * by `disable` and by `logout`. The account half is read from `/me` and cleared by
- * `disable` or in the console — NOT by `logout`, since signing out of one machine is
- * not a decision about the account. Neither has an expiry: both stay on until the
- * creator turns them off.
+ * The account grant is read from `/me` and cleared by `disable` or in the console, NOT by
+ * `logout`, since signing out of one machine is not a decision about the account. The
+ * machine copy is two fields in ~/.vincentt/config.json, written by `enable` only after
+ * the account grant succeeded, and cleared by `disable`, by `logout`, and by any `/me`
+ * answer that is not a grant. Neither has an expiry.
  *
  * Because there is no expiry, VISIBILITY is the entire mitigation, and the AGE is
  * the load-bearing half of it: `ENABLED` alone reads as configuration, while
@@ -55,9 +55,6 @@ export function readEnablement(cfg, now) {
         return DISABLED;
     if (now >= DX_UNATTENDED_SUNSET)
         return DISABLED;
-    // The local flag is by definition a grant made on THIS machine — `dx enable` is the
-    // only writer, whether it took the browser path or the terminal one. An account grant
-    // never lands in this file; it is read from /me and reported separately.
     return { enabled: true, at: dxSendEnabledAt, source: "machine" };
 }
 /**
@@ -71,10 +68,10 @@ export function readEnablement(cfg, now) {
  * stops being honored too, or "forgetting the sunset turns the feature off" would only be
  * true of the local half.
  */
-export function readAccountConsent(raw, now) {
+export function readAccountEnablement(raw, now) {
     if (typeof raw !== "object" || raw === null)
         return DISABLED;
-    const { dxReportsConsent, dxReportsConsentAt } = raw;
+    const { dxReportsConsent, dxReportsConsentAt, dxReportsConsentVia } = raw;
     if (dxReportsConsent !== true)
         return DISABLED;
     if (typeof dxReportsConsentAt !== "string")
@@ -83,7 +80,73 @@ export function readAccountConsent(raw, now) {
         return DISABLED;
     if (now >= DX_UNATTENDED_SUNSET)
         return DISABLED;
-    return { enabled: true, at: dxReportsConsentAt, source: "console" };
+    // An unknown via is dropped, not rejected: it only decides the suffix, never the grant.
+    return dxReportsConsentVia === "cli" || dxReportsConsentVia === "console"
+        ? {
+            enabled: true,
+            at: dxReportsConsentAt,
+            source: "account",
+            via: dxReportsConsentVia,
+        }
+        : { enabled: true, at: dxReportsConsentAt, source: "account" };
+}
+/**
+ * The account-first read shared by the send gate, `vincentt dx` and `vincentt version`
+ * (f7 Scenario 3, 3c). The account decides when it answers; a "not granted" answer clears
+ * this machine's copy so a revoke made elsewhere reaches it. Only when the account cannot
+ * be read does the local flag stand on its own.
+ */
+export async function resolveConsentView(deps) {
+    const signedIn = deps.auth !== undefined;
+    if (deps.auth !== undefined && deps.readAccount !== undefined) {
+        const { auth, readAccount } = deps;
+        const read = await boundedRead(Promise.resolve().then(() => readAccount(auth)), deps.timeoutMs);
+        if (read.kind === "granted") {
+            return {
+                shown: read.enablement,
+                local: await deps.local(),
+                checked: "account",
+                signedIn,
+            };
+        }
+        if (read.kind === "not_granted") {
+            // A failed clear still reports off: the account said no, so nothing may send, and
+            // the next account read clears again.
+            await deps.clearLocal().catch(() => undefined);
+            return { shown: DISABLED, local: DISABLED, checked: "account", signedIn };
+        }
+    }
+    const local = await deps.local();
+    return { shown: local, local, checked: "machine", signedIn };
+}
+async function boundedRead(read, timeoutMs) {
+    const unreadable = { kind: "unreadable" };
+    const guarded = read.catch(() => unreadable);
+    if (timeoutMs === undefined)
+        return guarded;
+    let timer;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(unreadable), timeoutMs);
+        timer.unref?.();
+    });
+    try {
+        return await Promise.race([guarded, expired]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function dxConsentJson(view) {
+    const { shown } = view;
+    if (shown.enabled && shown.at !== undefined) {
+        return {
+            state: "on",
+            checked: view.checked,
+            at: shown.at,
+            ...(shown.via !== undefined ? { via: shown.via } : {}),
+        };
+    }
+    return { state: view.signedIn ? "off" : "unknown", checked: view.checked };
 }
 /**
  * Read enablement from the real machine config.
@@ -116,8 +179,10 @@ export function grantedOn(at) {
 /**
  * The one visibility line, in the single pinned shape every human surface uses:
  *
+ *   Unattended send: ENABLED since 2026-04-01 (145 days) · granted from the CLI
  *   Unattended send: ENABLED since 2026-04-01 (145 days) · granted in the console
- *   Unattended send: ENABLED since 2026-04-01 (145 days) · granted on this machine
+ *   Unattended send: ENABLED since 2026-04-01 (145 days) · on your account
+ *   Unattended send: ENABLED since 2026-04-01 (145 days) · this machine (account not checked)
  *
  * Returns undefined when not enabled. Nothing is printed in that case, on
  * purpose: a line that prints unconditionally is a line readers learn to skip,
@@ -136,10 +201,17 @@ export function enablementLine(e, now) {
     if (!e.enabled || e.at === undefined)
         return undefined;
     const days = ageInDays(e.at, now);
-    const where = e.source === "console"
-        ? " · granted in the console"
-        : e.source === "machine"
-            ? " · granted on this machine"
-            : "";
+    const where = sourceSuffix(e);
     return `Unattended send: ENABLED since ${grantedOn(e.at)} (${days} ${days === 1 ? "day" : "days"})${where}`;
 }
+function sourceSuffix(e) {
+    if (e.source === "machine")
+        return " · this machine (account not checked)";
+    if (e.source !== "account")
+        return "";
+    if (e.via === "cli")
+        return " · granted from the CLI";
+    if (e.via === "console")
+        return " · granted in the console";
+    return " · on your account";
+}

package/dist/dx/report.d.ts

@@ -1,25 +1,4 @@
-/**
- * `vincentt report "<what went wrong>"` — the creator's own words, sent.
- *
- * This exists because of a gap `dx --send` could not close. That command reports
- * DETECTED friction: it reads the journal, finds clusters of retries and errors,
- * and refuses when it finds none. But the friction a creator most wants to report
- * is routinely the kind the journal cannot see — a command that exits 0 and puts
- * the wrong thing on screen produces no error, no retry and no cluster. Asked to
- * carry a note about one, `--send` had nothing to attach it to and said "no
- * friction detected — nothing to send", which is the tool contradicting the
- * person using it.
- *
- * So the note stops being a rider on a finding and becomes the payload. An
- * observation carries no counts because there is nothing to count.
- *
- * The consent model is INHERITED, not relaxed. Sending is still gated on the
- * same three arms as `--send` (a terminal, a local `dx enable`, or an account
- * grant), the payload is still shown in full before it goes, and a note is still
- * shown under a warning that it is transmitted exactly as written. This verb
- * removes a refusal; it does not open a new door.
- */
-import type { Enablement } from "./enablement.js";
+import type { AccountRead, Enablement } from "./enablement.js";
 import type { JournalEntry } from "./journal.js";
 import { type BuiltWith } from "../platform/resolve.js";
 /** An observation as it goes on the wire. Mirrors the API's dxObservationRequest. */
@@ -114,7 +93,8 @@ export interface ReportDeps {
     accountConsent?: (auth: {
         apiUrl: string;
         pat: string;
-    }) => Promise<Enablement>;
+    }) => Promise<AccountRead>;
+    clearEnablement?: () => Promise<unknown>;
     /**
      * The version set. Injectable so a fixed set — or a REJECTING promise, the arm
      * proving a fault omits — can be driven with no filesystem. Defaults to the one
@@ -129,6 +109,6 @@ export interface ReportDeps {
  * Same order as `dx --send`, for the same reason — a creator who cannot see what
  * leaves their machine before it leaves has not agreed to anything:
  *
- *     bound-check → GATE (three arms) → auth → RESOLVE → build → SHOW → ask → post
+ *     bound-check → auth → GATE → RESOLVE → build → SHOW → ask → post
  */
 export declare function reportCommand(deps: ReportDeps, options: ReportOptions): Promise<number>;

package/dist/dx/report.js

@@ -1,3 +1,25 @@
+/**
+ * `vincentt report "<what went wrong>"` — the creator's own words, sent.
+ *
+ * This exists because of a gap `dx --send` could not close. That command reports
+ * DETECTED friction: it reads the journal, finds clusters of retries and errors,
+ * and refuses when it finds none. But the friction a creator most wants to report
+ * is routinely the kind the journal cannot see — a command that exits 0 and puts
+ * the wrong thing on screen produces no error, no retry and no cluster. Asked to
+ * carry a note about one, `--send` had nothing to attach it to and said "no
+ * friction detected — nothing to send", which is the tool contradicting the
+ * person using it.
+ *
+ * So the note stops being a rider on a finding and becomes the payload. An
+ * observation carries no counts because there is nothing to count.
+ *
+ * The consent model is INHERITED, not relaxed. Sending is gated by the same
+ * `gateSend` as `--send` (a terminal, the account grant, or, only when the
+ * account cannot be read, this machine's copy of it), the payload is still shown in full before it goes, and a note is still
+ * shown under a warning that it is transmitted exactly as written. This verb
+ * removes a refusal; it does not open a new door.
+ */
+import { gateSend, SEND_REFUSAL_LINES } from "./command.js";
 import { enablementLine } from "./enablement.js";
 import { DXSendError, platformTag } from "./send.js";
 import { resolveBuiltWith } from "../platform/resolve.js";
@@ -110,7 +132,7 @@ export function renderObservation(report) {
  * Same order as `dx --send`, for the same reason — a creator who cannot see what
  * leaves their machine before it leaves has not agreed to anything:
  *
- *     bound-check → GATE (three arms) → auth → RESOLVE → build → SHOW → ask → post
+ *     bound-check → auth → GATE → RESOLVE → build → SHOW → ask → post
  */
 export async function reportCommand(deps, options) {
     const note = options.note.trim();
@@ -128,28 +150,13 @@ export async function reportCommand(deps, options) {
         deps.print(`That note is longer than ${MAX_NOTE} characters. Please shorten it.`);
         return 1;
     }
-    // The gate, inherited from `dx --send` verbatim. An agent composing a note and
-    // confirming it with --yes on a machine nobody granted is the case this stops.
-    const localEnablement = deps.enablement?.() ?? { enabled: false };
-    const interactive = deps.interactive();
+    // The gate, shared with `dx --send`. An agent composing a note and confirming it
+    // with --yes on an account nobody granted is the case this stops.
     const auth = await deps.auth();
-    let accountEnablement = { enabled: false };
-    if (!interactive && !localEnablement.enabled && auth !== undefined) {
-        try {
-            accountEnablement = (await deps.accountConsent?.(auth)) ?? { enabled: false };
-        }
-        catch {
-            // Fail closed. An unreachable API never authorizes a send.
-            accountEnablement = { enabled: false };
-        }
-    }
-    const enablement = localEnablement.enabled
-        ? localEnablement
-        : accountEnablement;
-    if (!interactive && !enablement.enabled) {
-        deps.print("Sending a report needs consent that has not been given on this account.");
-        deps.print("`vincentt dx enable` opens the Vincentt console so you can allow it.");
-        deps.print("It takes one click, and it works from here.");
+    const gate = await gateSend(deps, auth);
+    if (gate.arm === "refused") {
+        for (const l of SEND_REFUSAL_LINES)
+            deps.print(l);
         return 1;
     }
     if (auth === undefined) {
@@ -179,9 +186,9 @@ export async function reportCommand(deps, options) {
     // omission an empty project yields, and neither can fail a report.
     const builtWith = await (deps.builtWith ?? (() => resolveBuiltWith(deps.cwd ?? process.cwd())))().catch(() => undefined);
     const report = buildObservationReport(note, deps.cliVersion(), context, builtWith);
-    const unattended = !interactive && enablement.enabled;
-    if (unattended) {
-        const line = enablementLine(enablement, deps.now());
+    const unattended = gate.arm === "unattended";
+    if (gate.arm === "unattended") {
+        const line = enablementLine(gate.enablement, deps.now());
         if (line !== undefined) {
             deps.print("");
             deps.print(`${line}. Not asking.`);

package/dist/dx/reportIo.js

@@ -1,13 +1,15 @@
 import { DXSendError } from "./send.js";
 import { AUTH_EXPIRED_MESSAGE } from "../shared/authError.js";
-import { apiFetch } from "../shared/http.js";
+import { apiFetch, apiRequest } from "../shared/http.js";
+import { rejectUpgradeRequired } from "../shared/upgradeError.js";
 export async function postObservationReport(apiUrl, pat, report, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${apiUrl}/dx-reports`, {
+    const res = await apiRequest({ apiUrl, pat }, "/dx-reports", {
         method: "POST",
-        headers: { "content-type": "application/json", authorization: `Bearer ${pat}` },
+        headers: { "content-type": "application/json" },
         body: JSON.stringify(report),
-    });
+    }, { authenticated: true }, fetchImpl);
     if (!res.ok) {
+        await rejectUpgradeRequired(res);
         let detail = "";
         try {
             const body = (await res.json());

package/dist/dx/send.js

@@ -1,5 +1,6 @@
 import { AUTH_EXPIRED_MESSAGE } from "../shared/authError.js";
-import { apiFetch } from "../shared/http.js";
+import { apiFetch, apiRequest } from "../shared/http.js";
+import { rejectUpgradeRequired } from "../shared/upgradeError.js";
 import { renderPayloadWithVersionSummary, summarizeBuiltWith, versionDisclosureLines, } from "../platform/versionSummary.js";
 /**
  * The server bounds a report at 50 findings and refuses the whole thing past
@@ -105,12 +106,13 @@ export class DXSendError extends Error {
  * POST the report. The caller has already shown the payload and had it accepted.
  */
 export async function postReport(apiUrl, pat, report, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${apiUrl}/dx-reports`, {
+    const res = await apiRequest({ apiUrl, pat }, "/dx-reports", {
         method: "POST",
-        headers: { "content-type": "application/json", authorization: `Bearer ${pat}` },
+        headers: { "content-type": "application/json" },
         body: JSON.stringify(report),
-    });
+    }, { authenticated: true }, fetchImpl);
     if (!res.ok) {
+        await rejectUpgradeRequired(res);
         let detail = "";
         try {
             const body = (await res.json());

package/dist/lib/backend.js

@@ -6,9 +6,9 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { clientHeaders } from "../shared/clientHeader.js";
 import { authFailureMessage } from "../shared/authError.js";
-import { apiFetch } from "../shared/http.js";
+import { apiRequest } from "../shared/http.js";
+import { rejectUpgradeRequired } from "../shared/upgradeError.js";
 const execFileAsync = promisify(execFile);
 export class BackendError extends Error {
     status;
@@ -19,14 +19,9 @@ export class BackendError extends Error {
     }
 }
 async function authFetch(cfg, pathname, init = {}) {
-    return apiFetch(`${cfg.apiUrl}${pathname}`, {
-        ...init,
-        headers: {
-            ...(init.headers ?? {}),
-            ...clientHeaders(),
-            authorization: `Bearer ${cfg.pat}`,
-        },
-    });
+    const res = await apiRequest(cfg, pathname, init, { authenticated: true });
+    await rejectUpgradeRequired(res);
+    return res;
 }
 async function safeText(res) {
     try {

package/dist/lib/exitCodes.d.ts

@@ -17,6 +17,12 @@ export declare const EXIT: {
     readonly DELIVERED_NOT_REGISTERED: 3;
     /** A platform call needed an account and the command did not answer for it. */
     readonly NOT_AUTHENTICATED: 4;
+    /**
+     * The platform refused this CLI's version, and nothing was changed on the
+     * platform. A verb such as `create` may have written local source; its screen
+     * says where.
+     */
+    readonly UPGRADE_REQUIRED: 5;
     /** A bounded wait elapsed with nothing handed over. */
     readonly WINDOW_ELAPSED: 64;
     /** The channel ended before anything was handed over. */

package/dist/lib/exitCodes.js

@@ -17,6 +17,12 @@ export const EXIT = {
     DELIVERED_NOT_REGISTERED: 3,
     /** A platform call needed an account and the command did not answer for it. */
     NOT_AUTHENTICATED: 4,
+    /**
+     * The platform refused this CLI's version, and nothing was changed on the
+     * platform. A verb such as `create` may have written local source; its screen
+     * says where.
+     */
+    UPGRADE_REQUIRED: 5,
     /** A bounded wait elapsed with nothing handed over. */
     WINDOW_ELAPSED: 64,
     /** The channel ended before anything was handed over. */

package/dist/lib/terminalText.d.ts

@@ -1,5 +1,11 @@
 export declare const CONTROL_CHARS: RegExp;
 /** Each C0/C1 control character as a visible `\uXXXX`, so nothing is hidden or redrawn. */
 export declare function escapeControl(text: string): string;
+/**
+ * Each C0/C1 control, bidi embedding, override or isolate, and direction mark
+ * as a visible `\uXXXX`: a file name cannot reorder the line, and the creator
+ * can still find the file.
+ */
+export declare function escapeTerminal(text: string): string;
 /** Text with every C0/C1 control and bidi override or isolate removed. */
 export declare function terminalSafe(text: string): string;

package/dist/lib/terminalText.js

@@ -11,6 +11,16 @@ export function escapeControl(text) {
 // U+202A..U+202E (embeddings, overrides) and U+2066..U+2069 (isolates) can
 // reorder a terminal line, so a crafted name could disguise what it says.
 const BIDI_CONTROLS_G = /[\u202a-\u202e\u2066-\u2069]/g;
+// The above, plus the direction marks U+200E, U+200F and U+061C.
+const TERMINAL_UNSAFE_G = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+/**
+ * Each C0/C1 control, bidi embedding, override or isolate, and direction mark
+ * as a visible `\uXXXX`: a file name cannot reorder the line, and the creator
+ * can still find the file.
+ */
+export function escapeTerminal(text) {
+    return text.replace(TERMINAL_UNSAFE_G, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
 /** Text with every C0/C1 control and bidi override or isolate removed. */
 export function terminalSafe(text) {
     return text.replace(CONTROL_CHARS_G, "").replace(BIDI_CONTROLS_G, "");

package/dist/lib/version.d.ts

@@ -1,4 +1,4 @@
-import type { Enablement } from "../dx/enablement.js";
+import type { AccountRead, Enablement, EnablementSource, EnablementVia } from "../dx/enablement.js";
 export interface VersionReport {
     cliVersion: string;
     nodeVersion: string;
@@ -9,10 +9,13 @@ export interface VersionReport {
     ignoredBindingApiUrl?: string;
     /** True when the resolved host is the built-in fallback (nothing configured). */
     isDefault: boolean;
-    /** True when this machine may send DX reports unattended. */
+    /** True when DX reports may be sent unattended, from the account-first answer. */
     dxSendEnabled: boolean;
     /** ISO8601 UTC of the grant. Present only when enabled. */
     dxSendEnabledAt?: string;
+    /** Where that answer came from, and where the account grant was made. */
+    dxSource?: EnablementSource;
+    dxVia?: EnablementVia;
     /** The instant the age is computed against, so renderVersion stays pure. */
     dxAgeAsOf: number;
 }
@@ -50,4 +53,27 @@ export declare function renderVersion(r: VersionReport): string[];
 export declare function versionReport(cwd: string, opts: {
     cliVersion: string;
     allowCustomApi?: boolean;
+    /** The account read; absent reports this machine's flag only. */
+    consent?: VersionConsentDeps;
 }): Promise<VersionReport>;
+/** The account bound on `version` (f7 Scenario 3c). */
+export declare const VERSION_ACCOUNT_TIMEOUT_MS = 3000;
+export interface VersionConsentDeps {
+    auth: () => Promise<{
+        apiUrl: string;
+        pat: string;
+    } | undefined>;
+    readAccount: (auth: {
+        apiUrl: string;
+        pat: string;
+    }) => Promise<AccountRead>;
+    clearLocal: () => Promise<unknown>;
+    local?: () => Promise<Enablement>;
+    timeoutMs?: number;
+}
+/**
+ * The enablement `version` shows: the account's answer when it can be read within the
+ * bound, else this machine's flag. Never throws and never waits past the bound, because
+ * `version` is the command people run when something is already broken.
+ */
+export declare function versionEnablement(now: number, consent: VersionConsentDeps | undefined): Promise<Enablement>;

package/dist/lib/version.js

@@ -7,7 +7,7 @@
 // misconfiguration. So this reports the resolved host AND its provenance, using
 // the same decideApiUrl the real verbs use; a version command that re-derived
 // the URL could disagree with them.
-import { enablementLine, loadEnablement } from "../dx/enablement.js";
+import { enablementLine, loadEnablement, resolveConsentView } from "../dx/enablement.js";
 import { decideApiUrl, loadMachineConfig, locateProjectBinding, } from "../shared/config.js";
 /**
  * Decide what to report. Pure, so the transcript is testable without a home
@@ -45,6 +45,8 @@ export function buildVersionReport(env) {
         isDefault,
         dxSendEnabled: enablement.enabled,
         dxSendEnabledAt: enablement.enabled ? enablement.at : undefined,
+        dxSource: enablement.enabled ? enablement.source : undefined,
+        dxVia: enablement.enabled ? enablement.via : undefined,
         dxAgeAsOf: env.now ?? Date.now(),
     };
 }
@@ -68,7 +70,7 @@ export function renderVersion(r) {
     // exactly when a forgotten enablement is most likely to be discovered. Printed
     // only when enabled — see the note in dx/enablement.ts on why there is no `off`
     // counterpart.
-    const dx = enablementLine({ enabled: r.dxSendEnabled, at: r.dxSendEnabledAt }, r.dxAgeAsOf);
+    const dx = enablementLine({ enabled: r.dxSendEnabled, at: r.dxSendEnabledAt, source: r.dxSource, via: r.dxVia }, r.dxAgeAsOf);
     if (dx !== undefined)
         out.push("", `  ${dx}`);
     out.push("");
@@ -106,7 +108,32 @@ export async function versionReport(cwd, opts) {
         allowCustomApi: opts.allowCustomApi,
         nodeVersion: process.version,
         cliVersion: opts.cliVersion,
-        enablement: await loadEnablement(now),
+        enablement: await versionEnablement(now, opts.consent),
         now,
     });
 }
+/** The account bound on `version` (f7 Scenario 3c). */
+export const VERSION_ACCOUNT_TIMEOUT_MS = 3_000;
+/**
+ * The enablement `version` shows: the account's answer when it can be read within the
+ * bound, else this machine's flag. Never throws and never waits past the bound, because
+ * `version` is the command people run when something is already broken.
+ */
+export async function versionEnablement(now, consent) {
+    const local = consent?.local ?? (() => loadEnablement(now));
+    if (consent === undefined)
+        return local();
+    try {
+        const view = await resolveConsentView({
+            auth: await consent.auth().catch(() => undefined),
+            readAccount: consent.readAccount,
+            local,
+            clearLocal: consent.clearLocal,
+            timeoutMs: consent.timeoutMs ?? VERSION_ACCOUNT_TIMEOUT_MS,
+        });
+        return view.shown;
+    }
+    catch {
+        return local().catch(() => ({ enabled: false }));
+    }
+}

package/dist/lib/whoami.js

@@ -7,6 +7,7 @@
 // f2's hardest copy rather than cosmetic.
 import { resolveActiveOrg } from "./org.js";
 import { authExpiredLines, isAuthRefused } from "../shared/authError.js";
+import { UpgradeRequiredError } from "../shared/upgradeError.js";
 import { EXIT } from "./exitCodes.js";
 export async function whoamiCommand(deps) {
     const cfg = await deps.config();
@@ -19,6 +20,8 @@ export async function whoamiCommand(deps) {
         me = await deps.getMe(cfg);
     }
     catch (err) {
+        if (err instanceof UpgradeRequiredError)
+            throw err;
         if (isAuthRefused(err)) {
             for (const l of authExpiredLines())
                 deps.print(l);

package/dist/library/assetsCommand.js

@@ -18,6 +18,7 @@ import { DOWNLOAD_DIR, downloadPath, exists, overwriteRefusalLines, writeAsset,
 import { dedupeForDisplay, parseIdArgs, parseSearchFlags } from "./parse.js";
 import { addLines, humanBytes, searchLines, showLines, unknownBlockLines, unreachableLines, } from "./render.js";
 import { isLibraryId } from "./wire.js";
+import { UpgradeRequiredError } from "../shared/upgradeError.js";
 /**
  * Map a thrown client error onto the exit-4 screen it deserves.
  *
@@ -28,6 +29,9 @@ import { isLibraryId } from "./wire.js";
  * corpus failed to load.
  */
 function failureScreen(err, retry) {
+    // Rethrown so main() renders the one refusal screen and exits 5.
+    if (err instanceof UpgradeRequiredError)
+        throw err;
     if (err instanceof LibraryUnreachableError) {
         return { lines: unreachableLines("transport", retry), code: 4 };
     }

package/dist/library/client.js

@@ -12,9 +12,9 @@
 // CLI-supplied URL reaches a fetch. That is a security control, not a style choice
 // (D-add-prints-urls degraded the no-invented-URLs rule from prevention to
 // detection, and this is the one arm that stayed prevention).
-import { clientHeaders } from "../shared/clientHeader.js";
 import { authFailureMessage } from "../shared/authError.js";
-import { apiFetch, withDeadline } from "../shared/http.js";
+import { apiRequest, withDeadline } from "../shared/http.js";
+import { rejectUpgradeRequired } from "../shared/upgradeError.js";
 import { parseBatchResponse, parseFetchResponse, parseSearchResponse, } from "./wire.js";
 // An asset file can be tens of megabytes, so its download gets longer than an api call.
 const downloadFetch = withDeadline((input, init) => globalThis.fetch(input, init), 5 * 60_000);
@@ -65,18 +65,16 @@ async function readJson(res) {
  * correct recovery differs between them (retry later vs re-search).
  */
 export function httpLibraryClient(cfg) {
-    const base = cfg.apiUrl.replace(/\/$/, "");
-    const auth = { ...clientHeaders(), authorization: `Bearer ${cfg.pat}` };
     const call = async (pathname, init) => {
+        let res;
         try {
-            return await apiFetch(`${base}${pathname}`, {
-                ...init,
-                headers: { ...(init?.headers ?? {}), ...auth },
-            });
+            res = await apiRequest(cfg, pathname, init, { authenticated: true });
         }
         catch (err) {
             throw new LibraryUnreachableError(err);
         }
+        await rejectUpgradeRequired(res);
+        return res;
     };
     const fail = async (res, what) => {
         // A 401 keeps its status: assetsCommand maps it to the sign-in screen and exit 4.