@vincentt-xr/cli 0.21.0 → 0.22.0

package/dist/dx/consent.d.ts

@@ -1,16 +1,35 @@
-import { type Enablement } from "./enablement.js";
+import { type AccountRead, type Enablement } from "./enablement.js";
+/** POST /me/dx-consent, sorted into the outcomes `dx enable` answers differently. */
+export type GrantResult = {
+    kind: "granted";
+    enablement: Enablement;
+} | {
+    kind: "not_granted";
+} | {
+    kind: "rate_limited";
+} | {
+    kind: "unreachable";
+};
 /**
  * The account-consent seam.
  *
- * `read` returns the parsed Enablement rather than the raw envelope so the strict
+ * Both reads return parsed results rather than the raw envelope so the strict
  * `=== true` interpretation happens in exactly one place and cannot be re-derived
  * loosely by a second caller.
  */
 export interface ConsentBackend {
-    /** GET /me → the account's dxReportsConsent fields, read strictly. */
-    read(apiUrl: string, pat: string, now: number): Promise<Enablement>;
-    /** POST /me/dx-consent — grant. Idempotent; a re-grant refreshes the timestamp. */
-    grant(apiUrl: string, pat: string, now: number): Promise<Enablement>;
+    /**
+     * GET /me → the account's consent, read strictly. A 426, a 5xx, a network error or a
+     * timeout is `unreadable`: the CLI floor refuses /me while reports stay floor-exempt,
+     * so a below-floor CLI must fall back to its local flag rather than stop. A 401 still
+     * rejects with the shared sign-in error.
+     */
+    read(apiUrl: string, pat: string, now: number, timeoutMs?: number): Promise<AccountRead>;
+    /**
+     * POST /me/dx-consent — grant. A re-grant refreshes the timestamp. Rejects only with
+     * the version refusal (426) or the sign-in error (401); every other outcome is a result.
+     */
+    grant(apiUrl: string, pat: string, now: number): Promise<GrantResult>;
     /** DELETE /me/dx-consent — revoke. Never fails on already-revoked. */
     revoke(apiUrl: string, pat: string): Promise<void>;
 }

package/dist/dx/consent.js

@@ -1,17 +1,11 @@
 /**
- * The ACCOUNT half of unattended-send authorization.
+ * The ACCOUNT grant for unattended sends: the authority, which the local flag caches.
  *
- * `vincentt dx enable` used to require a TTY, which dead-ends the flow this feature is
- * actually for: a creator drives the CLI through a coding agent, the agent has no
- * terminal, and the command refuses. Consent therefore moves to the console, where a
- * human can actually read the disclosure and click — the CLI opens a browser and waits.
- *
- * The grant is PER-ACCOUNT, not per-machine: one decision covers every machine the
- * creator signs in on. That is a wider blast radius than the local flag, which is why
- * the console page carries the full disclosure (including that an agent may compose a
- * note the user has not read) and why the visibility line names the console as the
- * source — a creator who wants it off needs to know that clearing a local flag is not
- * enough.
+ * A person grants it at a terminal (`dx enable` POSTs /me/dx-consent with the PAT) or,
+ * with no terminal, on the console page the CLI opens. Either way the grant is
+ * PER-ACCOUNT: one decision covers every machine the creator signs in on, which is why
+ * both surfaces carry the full disclosure (including that an agent may compose a note
+ * the user has not read) and why the visibility line names where it was granted.
  *
  * Every call is isolated behind ConsentBackend so the command layer is unit-testable
  * with no network.
@@ -21,10 +15,10 @@ import { waitForLoopbackCallback } from "../login/loopback.js";
 import { browserPage } from "../login/pkceLogin.js";
 import { stateMatches } from "../login/pkce.js";
 import { getFreePort } from "../preview/net.js";
-import { authFailureMessage } from "../shared/authError.js";
-import { apiRequest } from "../shared/http.js";
-import { rejectUpgradeRequired } from "../shared/upgradeError.js";
-import { readAccountConsent } from "./enablement.js";
+import { AuthExpiredError, authFailureMessage, rejectAuthExpired, } from "../shared/authError.js";
+import { apiFetch, apiRequest, withDeadline } from "../shared/http.js";
+import { rejectUpgradeRequired, UpgradeRequiredError } from "../shared/upgradeError.js";
+import { readAccountEnablement, } from "./enablement.js";
 async function safeText(res) {
     try {
         return (await res.text()).slice(0, 300);
@@ -54,19 +48,58 @@ export function httpConsentBackend() {
         return res;
     };
     return {
-        async read(apiUrl, pat, now) {
-            const res = await call(apiUrl, pat, "/me", {});
-            if (!res.ok) {
-                throw new Error(authFailureMessage("Could not read your account", res.status, await safeText(res)));
+        async read(apiUrl, pat, now, timeoutMs) {
+            const fetchImpl = timeoutMs === undefined
+                ? apiFetch
+                : withDeadline((input, init) => globalThis.fetch(input, init), timeoutMs);
+            let res;
+            let body;
+            try {
+                res = await apiRequest({ apiUrl, pat }, "/me", {}, { authenticated: true }, fetchImpl);
+                if (res.status === 401)
+                    rejectAuthExpired(res);
+                if (!res.ok)
+                    return { kind: "unreadable" };
+                body = await res.json();
             }
-            return readAccountConsent(unwrapMe(await res.json()), now);
+            catch (err) {
+                if (err instanceof AuthExpiredError)
+                    throw err;
+                // A 200 whose body does not parse (a captive portal, a proxy page) is not an
+                // account answer, so it must not clear this machine's flag.
+                return { kind: "unreadable" };
+            }
+            const enablement = readAccountEnablement(unwrapMe(body), now);
+            return enablement.enabled
+                ? { kind: "granted", enablement }
+                : { kind: "not_granted" };
         },
         async grant(apiUrl, pat, now) {
-            const res = await call(apiUrl, pat, "/me/dx-consent", { method: "POST" });
-            if (!res.ok) {
-                throw new Error(authFailureMessage("Could not record consent", res.status, await safeText(res)));
+            let res;
+            try {
+                res = await call(apiUrl, pat, "/me/dx-consent", { method: "POST" });
+            }
+            catch (err) {
+                if (err instanceof UpgradeRequiredError)
+                    throw err;
+                return { kind: "unreachable" };
+            }
+            rejectAuthExpired(res);
+            if (res.status === 429)
+                return { kind: "rate_limited" };
+            if (!res.ok)
+                return { kind: "unreachable" };
+            let body;
+            try {
+                body = await res.json();
+            }
+            catch {
+                return { kind: "not_granted" };
             }
-            return readAccountConsent(unwrapMe(await res.json()), now);
+            const enablement = readAccountEnablement(unwrapMe(body), now);
+            return enablement.enabled
+                ? { kind: "granted", enablement }
+                : { kind: "not_granted" };
         },
         async revoke(apiUrl, pat) {
             const res = await call(apiUrl, pat, "/me/dx-consent", { method: "DELETE" });

package/dist/dx/enablement.d.ts

@@ -11,21 +11,21 @@
  */
 export declare const DX_UNATTENDED_SUNSET: number;
 /**
- * WHERE the grant was made. Consent can now be given in the console (per-ACCOUNT, so it
- * covers every machine the creator signs in on) or at this terminal (per-MACHINE).
- *
- * The source is carried rather than inferred because the two have different blast radii
- * and different places to revoke. A creator reading `ENABLED` on a machine they never
- * ran `dx enable` on has no way to act on it without being told the grant lives in their
- * account — they would go looking for a local flag that is not there.
+ * WHERE the answer came from. The account is the authority whenever GET /me answers;
+ * `machine` means this machine's cached copy was used because the account could not be
+ * read. The two are reported differently because only one of them was checked just now.
  */
-export type EnablementSource = "console" | "machine";
+export type EnablementSource = "account" | "machine";
+/** Where the person answered the account grant, as the api recorded it. */
+export type EnablementVia = "cli" | "console";
 export interface Enablement {
     enabled: boolean;
     /** The raw ISO8601 grant time. Present only when `enabled` is true. */
     at?: string;
-    /** Where the grant came from. Present only when `enabled` is true. */
+    /** Where the answer came from. Present only when `enabled` is true. */
     source?: EnablementSource;
+    /** Account grants only, and only when the api recorded it. */
+    via?: EnablementVia;
 }
 /**
  * Decide enablement from an already-parsed config object. Pure, and STRICT:
@@ -49,7 +49,57 @@ export declare function readEnablement(cfg: unknown, now: number): Enablement;
  * stops being honored too, or "forgetting the sunset turns the feature off" would only be
  * true of the local half.
  */
-export declare function readAccountConsent(raw: unknown, now: number): Enablement;
+export declare function readAccountEnablement(raw: unknown, now: number): Enablement;
+/** GET /me, as the consent gate and the visibility surfaces need it. */
+export type AccountRead = {
+    kind: "granted";
+    enablement: Enablement;
+} | {
+    kind: "not_granted";
+} | {
+    kind: "unreadable";
+};
+/**
+ * What the consent surfaces show: the answer that decides (`shown`), this machine's copy
+ * (`local`, after any clear), and where the answer was checked.
+ */
+export interface ConsentView {
+    shown: Enablement;
+    local: Enablement;
+    checked: "account" | "machine";
+    signedIn: boolean;
+}
+export interface ConsentViewDeps {
+    auth: {
+        apiUrl: string;
+        pat: string;
+    } | undefined;
+    /** Allowed to throw; a throw reads as unreadable. */
+    readAccount?: (auth: {
+        apiUrl: string;
+        pat: string;
+    }) => Promise<AccountRead>;
+    local: () => Promise<Enablement> | Enablement;
+    /** Clears this machine's copy. Allowed to throw; see below. */
+    clearLocal: () => Promise<unknown>;
+    /** Bounds the account read from outside, so a backend that hangs cannot hang the caller. */
+    timeoutMs?: number;
+}
+/**
+ * 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 declare function resolveConsentView(deps: ConsentViewDeps): Promise<ConsentView>;
+/** `dxConsent` in `vincentt dx --json` (f7 Scenario 3c). */
+export interface DxConsentJson {
+    state: "on" | "off" | "unknown";
+    checked: "account" | "machine";
+    at?: string;
+    via?: EnablementVia;
+}
+export declare function dxConsentJson(view: ConsentView): DxConsentJson;
 /**
  * Read enablement from the real machine config.
  *
@@ -66,8 +116,10 @@ export declare function grantedOn(at: string): string;
 /**
  * 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,

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/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 }));
+    }
+}