@vincentt-xr/cli 0.20.0 → 0.22.0

package/MIGRATION.md

@@ -3,6 +3,36 @@
 Per version, newest first. Read by the platform's own version surface and served to
 creators' agents. Accurate or absent, never speculative (B-F5-2).
 
+## 0.22.0
+
+required: false
+No action required. Behaviour that changed:
+- `vincentt dx enable` at a terminal now asks `Allow unattended reports on your account? [y/N]` and, on `y`, records the grant on your Vincentt account first, then sets this machine. Success reads `Enabled for your account. Reports may now be sent without a prompt from any machine signed in to it.`
+- If the account does not record the grant, `vincentt dx enable` changes nothing and exits 1 with `✗ Vincentt did not record your consent.`, `✗ Too many consent changes. Wait a minute and try again.`, or `✗ Could not reach Vincentt to record your consent.` A refused sign-in exits 4 and a too-old CLI exits 5, as on other verbs.
+- Unattended `vincentt dx --send` and `vincentt report` now check the account first. An account grant sends; an account that is not granted refuses (exit 1) and clears this machine's setting, so turning reports off in the console or on another machine reaches this one. This machine's setting is used on its own only when the account cannot be reached. An interactive session still asks and makes no account check.
+- The `Unattended send: ENABLED since <day> (<n> days)` line now ends with where the answer came from: `· granted from the CLI`, `· granted in the console`, `· on your account`, or `· this machine (account not checked)`. `vincentt dx` and `vincentt version` check the account for up to 3 seconds first; `vincentt version` never fails because of that check.
+- `vincentt dx --json` adds `dxConsent`: `{"state": "on" | "off" | "unknown", "checked": "account" | "machine", "at"?, "via"?}`. `dxSendEnabled` and `dxSendEnabledAt` still describe this machine's setting.
+- `vincentt preview` has a new ending: when the preview server answers the tunnel with a reply this CLI cannot accept, the preview ends once with `✗ Preview stopped: the preview server sent an invalid reply. Update the CLI or try again later.` (exit 1) instead of reconnecting every few seconds indefinitely. The screen names the upgrade command and `vincentt preview`.
+- `vincentt publish` refuses the whole publish, listing the files, when a folder in the build output turns into a link to somewhere outside it while publish reads it. Let the build finish, then publish again.
+- `vincentt publish` refuses to upload when the platform's upload link does not carry the checksum publish computed for that file; nothing is sent, and the screen names the file.
+- A folder or file in the build output that publish cannot read now ends the publish with the "changed while publish was reading it" screen naming the path inside the build output, instead of a raw error message holding the full path.
+- File names printed on publish refusal screens show bidirectional and direction-mark characters as visible `\uXXXX` escapes.
+
+## 0.21.0
+
+required: false
+No action required unless a build output holds a credential file. Behaviour that changed:
+- `vincentt publish` refuses a build output that holds a file or folder named like a credential (`credentials.json`, `service-account*.json`, `*firebase-adminsdk*.json`, `*.key`, `*.p12`, `*.pfx`, `*.p8`, `*.ppk`, `id_rsa*`, `id_dsa*`, `id_ed25519*`, `id_ecdsa*`, `*.jks`, `*.keystore`, `*.env`, `*.tfstate`, `*.tfvars`, and their `~`, `.bak`, `.gz`, `.br` or `.zst` copies, in any letter case).
+- `vincentt publish` also refuses a build output holding a file with a private key (including one a bundler inlined into JavaScript from an environment variable), or a Google service-account or user credential JSON.
+- A file that changes or becomes a link while publish reads it is also refused.
+- A publish that worked before can now be refused, with no override: move the file out of the build output (or rename an asset such as a Keynote `.key`) and rebuild. Public `.pem` certificates are still published.
+- `vincentt publish` can print a new "Heavy files" warning section in the checklist (a model over 10 MB, or an image over 2048 px on its long side); exit codes and prompts are unchanged.
+- Every request the CLI makes to the platform, including a preview's start, check-in and stop, and every preview tunnel connection, now says which CLI version is calling (`X-Vincentt-Client: cli/<version>`).
+- A new exit code, 5: the platform refused this CLI's version and nothing was changed on the platform. `create` may already have written the project, and its screen says where. No minimum version is set by this release, so nothing is refused yet.
+- On exit 5 the screen names this CLI's version, the minimum it needs and how to upgrade; `publish --json` prints `{"state":"failed","exitCode":5}`; the newer-version notice is not printed after it. When the platform received no version at all, the screen asks for a report instead of an upgrade.
+- `vincentt preview` has two new endings: the CLI is too old (exit 5), and "Vincentt stopped confirming it" when the platform stops confirming a running preview (exit 1, and no new preview is started on its own). The "Couldn't confirm your access to this project." ending is gone.
+- A request body sent to a preview with no declared length (chunked, or HTTP/2 without Content-Length) now reaches the dev server whole, sent with `Transfer-Encoding: chunked`, and a request with no body completes at once. Against a platform edge that predates this release the previous behaviour stays. Each forwarded request uses its own connection to the dev server, and a request whose Content-Length disagrees with its body is reset on its own without ending the preview.
+
 ## 0.20.0
 
 required: false

package/dist/cli/index.js

@@ -24,11 +24,12 @@ import { fileLocationStore } from "../shared/locationStore.js";
 import { getMe, listProjects, ProjectUnreachableError } from "../lib/backend.js";
 import { EXIT } from "../lib/exitCodes.js";
 import { AuthExpiredError, authExpiredLines, isAuthRefused, NOT_SIGNED_IN_LINES, NotSignedInError, } from "../shared/authError.js";
+import { UpgradeRequiredError, upgradeRefusalLines, } from "../shared/upgradeError.js";
 import { listProjectsCommand } from "../lib/listProjects.js";
 import { initCommand } from "../lib/initCommand.js";
 import { linkCommand, printUnreachable, unlinkCommand } from "../lib/projects.js";
 import { whoamiCommand } from "../lib/whoami.js";
-import { renderVersion, versionReport } from "../lib/version.js";
+import { renderVersion, VERSION_ACCOUNT_TIMEOUT_MS, versionReport, } from "../lib/version.js";
 import { diagQuery, diagRead, previewStart, previewStop, previewStopSignal, projectCreate, } from "../lib/lifecycle.js";
 import { publishCommand } from "../publish/command.js";
 import { stdinAsk, stdinConfirm } from "../publish/prompt.js";
@@ -52,7 +53,7 @@ import * as feedbackCopy from "../lib/feedbackCopy.js";
 import { record as recordInvocation } from "../dx/journal.js";
 import { dxDisableCommand, dxEnableCommand, dxSendCommand, parseDxOptions, runDx, sinceUsageLines, } from "../dx/command.js";
 import { httpConsentBackend, runConsentInBrowser } from "../dx/consent.js";
-import { DX_UNATTENDED_SUNSET, loadEnablement } from "../dx/enablement.js";
+import { DX_UNATTENDED_SUNSET, loadEnablement, resolveConsentView, } from "../dx/enablement.js";
 import { journalEnabled, journalPath, readJournal } from "../dx/journal.js";
 import { postReport } from "../dx/send.js";
 import { nudgeFor } from "../dx/nudge.js";
@@ -340,6 +341,7 @@ async function create() {
         dir = safe;
     }
     const interactive = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+    const consoleUrl = (await resolveAuthUrls()).consoleUrl;
     const result = await projectCreate(projectDir(), {
         name: flag("--name"),
         slug: flag("--slug"),
@@ -354,8 +356,18 @@ async function create() {
             await login();
         },
         orgSource,
-        consoleUrl: (await resolveAuthUrls()).consoleUrl,
+        consoleUrl,
         onLine: (l) => console.log(l),
+    }).catch((err) => {
+        // Registration is refused after the source is already on disk, so the
+        // screen says where it is.
+        if (!(err instanceof UpgradeRequiredError))
+            throw err;
+        const where = dir === undefined ? undefined : `./${dir}`;
+        for (const l of upgradeRefusalLines(err, { kind: "create", dir: where })) {
+            console.log(l);
+        }
+        return { message: "", exitCode: EXIT.UPGRADE_REQUIRED };
     });
     if (result.exitCode !== 0) {
         process.exitCode = result.exitCode;
@@ -627,7 +639,18 @@ async function preview() {
         }
     }
     let ending = null;
+    let endingRefusal;
     let resolveDone;
+    const refusedAtStart = (facts) => {
+        for (const l of upgradeRefusalLines(facts, {
+            kind: "preview_start",
+            devCommand,
+            localUrl: handRunUrl,
+        })) {
+            console.log(l);
+        }
+        process.exitCode = EXIT.UPGRADE_REQUIRED;
+    };
     const done = new Promise((r) => {
         resolveDone = r;
     });
@@ -656,8 +679,9 @@ async function preview() {
             onOriginError: () => ui.originError(),
             onOriginRecovered: () => ui.originRecovered(),
             onExpiring: () => ui.checkHardMax(running?.expiresAt ?? ""),
-            onEnded: (reason) => {
+            onEnded: (reason, refusal) => {
                 ending = reason;
+                endingRefusal = refusal;
                 resolveDone?.();
             },
         });
@@ -669,6 +693,11 @@ async function preview() {
         }
     }
     catch (err) {
+        // Refused by the mint, before the dev server was spawned: nothing to stop.
+        if (err instanceof UpgradeRequiredError) {
+            refusedAtStart(err);
+            return;
+        }
         // The local org is the FALLBACK only. A count refusal names the org that
         // owns this project, and the wire's name wins over this one wherever both
         // exist — see resolveCountLimit.
@@ -678,6 +707,13 @@ async function preview() {
         process.exitCode = err instanceof AuthExpiredError ? EXIT.NOT_AUTHENTICATED : 1;
         return;
     }
+    // A first dial refused before the start block printed: the creator never saw
+    // a link, so this is the start-time screen, not the running preview's ending.
+    if (ending === "upgrade_required") {
+        await previewStop();
+        refusedAtStart(endingRefusal ?? {});
+        return;
+    }
     const qr = shouldRenderQr({
         isTTY: Boolean(process.stdout.isTTY),
         noQr: has("--no-qr"),
@@ -714,11 +750,19 @@ async function preview() {
     await done;
     clearInterval(ceiling);
     if (ending !== null) {
-        ui.endedBy(ending, (await activeOrgName()) || "your workspace");
+        ui.endedBy(ending, (await activeOrgName()) || "your workspace", endingRefusal);
         await previewStop();
-        process.exitCode = ending === "auth_expired" ? EXIT.NOT_AUTHENTICATED : 1;
+        process.exitCode = previewExitCode(ending);
     }
 }
+/** A preview's ending → its exit: 5 for a version refusal, 4 for a refused token, else 1. */
+function previewExitCode(ending) {
+    if (ending === "upgrade_required")
+        return EXIT.UPGRADE_REQUIRED;
+    if (ending === "auth_expired")
+        return EXIT.NOT_AUTHENTICATED;
+    return EXIT.FAILED;
+}
 /** A `--port` or `--dev-command` value the schema refuses, before anything runs. */
 function previewFlagRefusal(port, devCommand) {
     const portMessage = port === undefined
@@ -1095,14 +1139,22 @@ function cliVersion() {
     }
 }
 async function version() {
+    const now = Date.now();
     const report = await versionReport(projectDir(), {
         cliVersion: cliVersion(),
         allowCustomApi: has("--allow-custom-api"),
+        consent: {
+            auth: dxAuth,
+            readAccount: (auth) => httpConsentBackend().read(auth.apiUrl, auth.pat, now, VERSION_ACCOUNT_TIMEOUT_MS),
+            clearLocal: () => writeDxEnablement(undefined),
+        },
     });
     for (const line of renderVersion(report))
         console.log(line);
 }
 // ---- dx ---------------------------------------------------------------------
+/** The account bound on `vincentt dx` (f7 Scenario 3c); the send gate uses the default. */
+const DX_ACCOUNT_TIMEOUT_MS = 3_000;
 /**
  * The API host + PAT for a dx call, or undefined when signed out.
  *
@@ -1153,6 +1205,7 @@ async function dx() {
                     onProgress: (l) => console.log(l),
                 });
             },
+            grantAccountConsent: (auth) => consent.grant(auth.apiUrl, auth.pat, now),
             revokeAccountConsent: (auth) => consent.revoke(auth.apiUrl, auth.pat),
         };
         process.exitCode = options.enable
@@ -1170,7 +1223,15 @@ async function dx() {
     // relaxation, not throw through it.
     const enablement = await loadEnablement(now);
     if (!options.send) {
-        process.exitCode = runDx(argv, (l) => console.log(l), () => enablement);
+        // The report tail and `dxConsent` read the account first, bounded at 3 s.
+        const view = await resolveConsentView({
+            auth: await dxAuth(),
+            readAccount: (auth) => httpConsentBackend().read(auth.apiUrl, auth.pat, now, DX_ACCOUNT_TIMEOUT_MS),
+            local: () => enablement,
+            clearLocal: () => writeDxEnablement(undefined),
+            timeoutMs: DX_ACCOUNT_TIMEOUT_MS,
+        });
+        process.exitCode = runDx(argv, (l) => console.log(l), () => view.local, () => view);
         return;
     }
     // `--send` is the one path out of this machine, so it resolves auth the way
@@ -1187,10 +1248,9 @@ async function dx() {
         confirm: (q) => stdinConfirm()(`${q} [y/N] `, false),
         interactive,
         enablement: () => enablement,
-        // The third arm: the account-wide grant, read from /me. Consulted only when the
-        // first two have not already allowed the send, and allowed to throw — a /me that
-        // is unreachable falls back to the other two arms rather than blocking.
+        // The account decides when it answers; never read on an interactive session.
         accountConsent: (auth) => httpConsentBackend().read(auth.apiUrl, auth.pat, now),
+        clearEnablement: () => writeDxEnablement(undefined),
         // `--dir`-or-cwd, the same resolution every other verb uses, so `--dir`
         // works on a send as it does everywhere else.
         cwd: projectDir(),
@@ -1232,6 +1292,7 @@ async function report() {
         interactive,
         enablement: () => enablement,
         accountConsent: (auth) => httpConsentBackend().read(auth.apiUrl, auth.pat, now),
+        clearEnablement: () => writeDxEnablement(undefined),
         // `--dir`-or-cwd, the same resolution every other verb uses, so `--dir`
         // works on a report as it does everywhere else.
         cwd: projectDir(),
@@ -1530,8 +1591,12 @@ function journal(exitCode, error) {
     // a notice is worth nothing if it costs a second on every publish.
     try {
         const cached = loadCache();
-        for (const l of updateNotice(cliVersion(), cached?.latest))
-            console.error(l);
+        // Suppressed on a version refusal: the ending already names the number that
+        // matters, and a stale cache could name a `latest` below the floor.
+        if (exitCode !== EXIT.UPGRADE_REQUIRED) {
+            for (const l of updateNotice(cliVersion(), cached?.latest))
+                console.error(l);
+        }
         if (!isFresh(cached, Date.now()))
             refreshUpdateCache();
     }
@@ -1623,6 +1688,15 @@ main()
         journal(EXIT.NOT_AUTHENTICATED, err);
         process.exit(EXIT.NOT_AUTHENTICATED);
     }
+    // L22's generic screen, for every verb without its own arm. Prose on the
+    // verb's usual channel, or stderr under --json so stdout stays a document.
+    if (err instanceof UpgradeRequiredError) {
+        const say = has("--json") ? console.error : console.log;
+        for (const l of upgradeRefusalLines(err))
+            say(l);
+        journal(EXIT.UPGRADE_REQUIRED, err);
+        process.exit(EXIT.UPGRADE_REQUIRED);
+    }
     if (isAuthRefused(err)) {
         for (const l of authExpiredLines())
             console.error(l);

package/dist/domain/api.js

@@ -12,9 +12,9 @@
 // ordinary indistinguishable 404 before the hostname is read at all. The CLI
 // therefore cannot distinguish "no such project" from "not your project" — and
 // must not try.
-import { clientHeaders } from "../shared/clientHeader.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";
 import { parseDomain, parseDomainList, } from "./wire.js";
 export class DomainApiError extends Error {
     status;
@@ -30,8 +30,12 @@ export class DomainApiError extends Error {
         this.name = "DomainApiError";
     }
 }
-/** Rejects with AuthExpiredError on a 401; every other status becomes a DomainApiError. */
+/**
+ * Rejects with UpgradeRequiredError on a 426 and AuthExpiredError on a 401;
+ * every other status becomes a DomainApiError.
+ */
 async function readError(res) {
+    await rejectUpgradeRequired(res);
     rejectAuthExpired(res);
     let body = {};
     try {
@@ -44,8 +48,8 @@ async function readError(res) {
     const retryAfter = res.headers.get("retry-after");
     return new DomainApiError(res.status, body.code ?? `http_${res.status}`, body.message ?? `request failed (${res.status})`, { attached: num(body.attached), entitled: num(body.entitled) }, retryAfter ? Number(retryAfter) : undefined);
 }
-function authHeaders(cfg) {
-    return { ...clientHeaders(), authorization: `Bearer ${cfg.pat}` };
+function call(cfg, path, init, fetchImpl) {
+    return apiRequest(cfg, path, init, { authenticated: true }, fetchImpl);
 }
 function rolesOf(raw) {
     const o = typeof raw === "object" && raw !== null ? raw : {};
@@ -57,11 +61,11 @@ function rolesOf(raw) {
 }
 /** POST /projects/{id}/domains — returns the records to publish. Rate-limited. */
 export async function attachDomain(cfg, projectId, domain, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/domains`, {
+    const res = await call(cfg, `/projects/${encodeURIComponent(projectId)}/domains`, {
         method: "POST",
-        headers: { ...authHeaders(cfg), "content-type": "application/json" },
+        headers: { "content-type": "application/json" },
         body: JSON.stringify({ domain }),
-    });
+    }, fetchImpl);
     if (!res.ok)
         throw await readError(res);
     const raw = await res.json();
@@ -82,7 +86,7 @@ export async function attachDomain(cfg, projectId, domain, fetchImpl = apiFetch)
  * a defect, and its copy names no limit family.
  */
 export async function verifyDomain(cfg, projectId, domain, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/domains/${encodeURIComponent(domain)}/verify`, { method: "POST", headers: authHeaders(cfg) });
+    const res = await call(cfg, `/projects/${encodeURIComponent(projectId)}/domains/${encodeURIComponent(domain)}/verify`, { method: "POST" }, fetchImpl);
     if (!res.ok)
         throw await readError(res);
     const raw = await res.json();
@@ -98,7 +102,7 @@ export async function verifyDomain(cfg, projectId, domain, fetchImpl = apiFetch)
 }
 /** GET /projects/{id}/domains — this project's domains with state + findings. */
 export async function listProjectDomains(cfg, projectId, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/domains`, { headers: authHeaders(cfg) });
+    const res = await call(cfg, `/projects/${encodeURIComponent(projectId)}/domains`, {}, fetchImpl);
     if (!res.ok)
         throw await readError(res);
     return parseDomainList(await res.json());
@@ -112,14 +116,14 @@ export async function listProjectDomains(cfg, projectId, fetchImpl = apiFetch) {
  * here, and this route only ever returns their own.
  */
 export async function listOrgDomains(cfg, orgSlug, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${cfg.apiUrl}/orgs/${encodeURIComponent(orgSlug)}/domains`, { headers: authHeaders(cfg) });
+    const res = await call(cfg, `/orgs/${encodeURIComponent(orgSlug)}/domains`, {}, fetchImpl);
     if (!res.ok)
         throw await readError(res);
     return parseDomainList(await res.json());
 }
 /** DELETE /projects/{id}/domains/{domain} — detach. The row is never deleted server-side. */
 export async function detachDomain(cfg, projectId, domain, fetchImpl = apiFetch) {
-    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/domains/${encodeURIComponent(domain)}`, { method: "DELETE", headers: authHeaders(cfg) });
+    const res = await call(cfg, `/projects/${encodeURIComponent(projectId)}/domains/${encodeURIComponent(domain)}`, { method: "DELETE" }, fetchImpl);
     // 404 is a SILENT RESOLVE on detach: the creator asked for a state the world is
     // already in. It is not distinguishable from "not your project", and it does
     // not need to be — either way this project is not serving that name.

package/dist/domain/command.js

@@ -22,6 +22,7 @@ import { EXIT } from "../lib/exitCodes.js";
 import { VALIDATION_RECORD_GONE } from "./wire.js";
 import { DomainApiError } from "./api.js";
 import { AuthExpiredError, authExpiredLines } from "../shared/authError.js";
+import { UpgradeRequiredError } from "../shared/upgradeError.js";
 import { localRefusal, normalizeArgument } from "./hostname.js";
 import * as copy from "./copy.js";
 /** The canonical subcommands. */
@@ -178,6 +179,8 @@ function authExpired(deps) {
     return EXIT.NOT_AUTHENTICATED;
 }
 function printAttachError(deps, err, hostname) {
+    if (err instanceof UpgradeRequiredError)
+        throw err;
     if (err instanceof AuthExpiredError)
         return authExpired(deps);
     if (!(err instanceof DomainApiError)) {
@@ -239,6 +242,8 @@ async function listVerb(deps, cfg, opts) {
         view = await deps.listOrg(cfg, org.org.slug);
     }
     catch (err) {
+        if (err instanceof UpgradeRequiredError)
+            throw err;
         if (err instanceof AuthExpiredError)
             return authExpired(deps);
         deps.print("");
@@ -293,6 +298,8 @@ async function verifyVerb(deps, cfg, opts) {
         result = await deps.verify(cfg, binding.projectId, hostname);
     }
     catch (err) {
+        if (err instanceof UpgradeRequiredError)
+            throw err;
         if (err instanceof AuthExpiredError)
             return authExpired(deps);
         if (err instanceof DomainApiError && err.status === 404) {
@@ -459,6 +466,8 @@ async function detachVerb(deps, cfg, opts) {
         await deps.detach(cfg, binding.projectId, hostname);
     }
     catch (err) {
+        if (err instanceof UpgradeRequiredError)
+            throw err;
         if (err instanceof AuthExpiredError)
             return authExpired(deps);
         deps.print("");

package/dist/dx/command.d.ts

@@ -1,5 +1,5 @@
-import type { ConsentDecision } from "./consent.js";
-import type { Enablement } from "./enablement.js";
+import type { ConsentDecision, GrantResult } from "./consent.js";
+import type { AccountRead, ConsentView, Enablement } from "./enablement.js";
 import type { JournalEntry, JournalWindow } from "./journal.js";
 import type { WireReport } from "./send.js";
 import { type BuiltWith } from "../platform/resolve.js";
@@ -11,10 +11,15 @@ export interface DxDeps {
     enabled: () => boolean;
     path: () => string;
     /**
-     * Durable unattended-send state. Optional so the many callers that only read
-     * the journal need not resolve it; absent reads as not enabled.
+     * This machine's copy of the grant (the local flag). Optional so the many callers that
+     * only read the journal need not resolve it; absent reads as not enabled.
      */
     enablement?: () => Enablement;
+    /**
+     * The account-first answer the report tail and `dxConsent` show. Absent falls back to
+     * the local flag, reported as checked on this machine only.
+     */
+    consentView?: () => ConsentView;
 }
 /** How far back a report looks. */
 export interface DxWindow {
@@ -53,7 +58,7 @@ export declare function sinceUsageLines(raw: string): string[];
 export declare function parseDxOptions(args: string[]): DxOptions;
 export declare function dxCommand(deps: DxDeps, options: DxOptions): number;
 /** Wire the command to the real journal. */
-export declare function runDx(args: string[], print: (line: string) => void, enablement?: () => Enablement): number;
+export declare function runDx(args: string[], print: (line: string) => void, enablement?: () => Enablement, consentView?: () => ConsentView): number;
 export interface DxEnableDeps {
     print: (line: string) => void;
     now: () => number;
@@ -89,6 +94,14 @@ export interface DxEnableDeps {
      * no socket, no browser, and no clock to test.
      */
     consentInBrowser?: () => Promise<ConsentDecision>;
+    /**
+     * POST /me/dx-consent with the PAT, on the terminal path. Rejects only with the version
+     * refusal or the sign-in error; every other outcome is a GrantResult.
+     */
+    grantAccountConsent?: (auth: {
+        apiUrl: string;
+        pat: string;
+    }) => Promise<GrantResult>;
     /**
      * DELETE /me/dx-consent. Used only by `disable`, and allowed to throw — the caller
      * treats a network failure as "local revoke still stands", never as a reason to leave
@@ -103,11 +116,13 @@ export interface DxEnableDeps {
  * `vincentt dx enable` — grant durable permission to send DX reports without asking
  * first.
  *
- * TWO PATHS, and which one runs is decided by whether there is a terminal to ask in:
+ * TWO PATHS to ONE account grant, and which one runs is decided by whether there is a
+ * terminal to ask in:
  *
- *   - At a TTY: the original terminal prompt, unchanged. A person is already here and
- *     can read the disclosure where they stand; sending them to a browser would be
- *     ceremony.
+ *   - At a TTY: the terminal prompt. A person is already here and can read the
+ *     disclosure where they stand; sending them to a browser would be ceremony. On `y`
+ *     the CLI POSTs /me/dx-consent with the PAT, and writes the local flag only after
+ *     the account recorded the grant.
  *   - With no TTY: the BROWSER path. This is the case the feature exists for — a
  *     creator driving the CLI through a coding agent has no terminal, so the old code
  *     refused and the flow dead-ended. It now opens the console, where a human can
@@ -130,8 +145,8 @@ export declare function dxEnableCommand(deps: DxEnableDeps, sunset: number): Pro
  * Clears BOTH local keys AND revokes the account grant when there is a PAT to do it
  * with. Both halves are needed: a creator who runs `disable` means "stop sending", and
  * clearing only the local flag would leave the account grant standing, so the very next
- * `--send` would be authorized by arm (c) and the command would appear not to have
- * worked.
+ * `--send` would be authorized by the account and the command would appear not to
+ * have worked.
  *
  * ORDER IS DELIBERATE: local first, network second. The local clear is the one that
  * cannot fail and the one that stops THIS machine, which is the machine the creator is
@@ -168,18 +183,19 @@ export interface DxSendDeps extends DxDeps {
      * convenience, not authorization.
      */
     interactive: () => boolean;
-    /** Durable unattended-send state, read strictly. Absent reads as not enabled. */
+    /** This machine's flag, read strictly. Absent reads as not enabled. */
     enablement?: () => Enablement;
     /**
-     * The ACCOUNT's consent, read from GET /me. The third arm of the gate.
-     *
-     * Allowed to throw, and its throw is not fatal — see the gate below. Absent (the dep
-     * not wired at all) reads as not consented, never as "unknown, so allow".
+     * The ACCOUNT's consent, read from GET /me. Allowed to throw; a throw reads as
+     * unreadable. Absent reads as unreadable too: it can only let a valid local flag stand,
+     * never authorize on its own.
      */
     accountConsent?: (auth: {
         apiUrl: string;
         pat: string;
-    }) => Promise<Enablement>;
+    }) => Promise<AccountRead>;
+    /** Clears this machine's flag when the account answers "not granted". */
+    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
@@ -188,6 +204,46 @@ export interface DxSendDeps extends DxDeps {
     builtWith?: () => Promise<BuiltWith | undefined>;
     cwd?: string;
 }
+/** What the send gate needs. `dx --send` and `report` both satisfy it. */
+export interface SendGateDeps {
+    interactive: () => boolean;
+    enablement?: () => Enablement;
+    accountConsent?: (auth: {
+        apiUrl: string;
+        pat: string;
+    }) => Promise<AccountRead>;
+    clearEnablement?: () => Promise<unknown>;
+}
+export type SendGate = {
+    arm: "interactive";
+} | {
+    arm: "unattended";
+    enablement: Enablement;
+} | {
+    arm: "refused";
+};
+/**
+ * The one consent gate both send paths call (f7 Scenario 3), checked in order:
+ *
+ *   1. an interactive session → ask, then send. No /me read at all, so a creator at their
+ *      own terminal is never blocked by an API being slow or down.
+ *   2. signed in and GET /me answers: a strict grant sends (source: account); any other
+ *      200 clears this machine's flag and refuses.
+ *   3. /me cannot be read and this machine's flag is valid → send (source: machine).
+ *
+ * An unreadable /me never authorizes by itself; it only lets an existing local flag stand.
+ */
+export declare function gateSend(deps: SendGateDeps, auth: {
+    apiUrl: string;
+    pat: string;
+} | undefined): Promise<SendGate>;
+/**
+ * The gate's refusal. It NAMES the enabling command: a refusal is an answer to a
+ * command the caller typed, which makes it SOLICITED output — the prohibition is on
+ * UNBIDDEN output instructing a caller. A refusal naming nothing leaves a human at
+ * exit 1 with no path forward, for no security gain.
+ */
+export declare const SEND_REFUSAL_LINES: readonly string[];
 /**
  * `vincentt dx --send`.
  *
@@ -195,6 +251,6 @@ export interface DxSendDeps extends DxDeps {
  * who cannot see what leaves their machine before it leaves has not agreed to
  * anything:
  *
- *     friction → GATE (three arms) → auth → RESOLVE → build → SHOW → ask → post
+ *     friction → auth → GATE → RESOLVE → build → SHOW → ask → post
  */
 export declare function dxSendCommand(deps: DxSendDeps, options: DxOptions): Promise<number>;