@vincentt-xr/cli 0.17.0 → 0.18.1

package/dist/cli/usage-text.js

@@ -1,13 +1,13 @@
 // The help text, in its own module so it can be rendered without importing the
 // CLI entrypoint — `cli/index.ts` calls `main()` at module scope, so importing it
 // runs the CLI, writes the dx journal and sets process.exitCode.
-export const USAGE_TEXT = `Vincentt CLI — local-first AR dev loop\n\n` +
+export const USAGE_TEXT = `Vincentt CLI: the local-first AR dev loop\n\n` +
     `Usage: vincentt <command> [options]\n\n` +
     `Getting started (building a new app with a coding agent)\n` +
     `  1. Confirm a project name with the developer first.\n` +
     `  2. Create:  vincentt create <name>     (scaffolds if the folder is empty)\n` +
     `  3. The scaffold writes the agent contract into the project root. Read it,\n` +
-    `     confirm the project is ready, and stop — do NOT invent an app.\n` +
+    `     confirm the project is ready, and stop. Do NOT invent an app.\n` +
     `     Wait for the developer to describe what to build.\n` +
     `  Full guide: npm view @vincentt-xr/cli readme\n\n` +
     `Auth\n` +
@@ -16,7 +16,7 @@ export const USAGE_TEXT = `Vincentt CLI — local-first AR dev loop\n\n` +
     `  logout             Remove the saved access token\n` +
     `  whoami             Show the signed-in account\n\n` +
     `Project\n` +
-    `  init [dir]         Scaffold a Vincentt XR app — no account needed, ever\n` +
+    `  init [dir]         Scaffold a Vincentt XR app; no account needed, ever\n` +
     `                       [--no-install] [--template <version>]\n` +
     `                       [--from <owner>/<repo>@<tag>] Clone a gallery template\n` +
     `                       and register it   [--name <s>] [--slug <s>]\n` +
@@ -28,7 +28,18 @@ export const USAGE_TEXT = `Vincentt CLI — local-first AR dev loop\n\n` +
     `                       Omit the name to use the current folder as-is.\n` +
     `                       [--name <s>] [--slug <s>]\n` +
     `                       [--org <s>] [--preview] [--force] [--no-install]\n` +
+    `                       In an app that already carries a @vincentt-xr package it\n` +
+    `                       only registers, then settles vincentt.json like link does.\n` +
     `  link <project-id>  Link this folder to an existing project\n` +
+    `                       For an app not made from the Vincentt template, link also\n` +
+    `                       reads how the app runs (it runs nothing) and writes\n` +
+    `                       vincentt.json: dev.command, dev.port, build.command and\n` +
+    `                       build.output. Commit it. A present vincentt.json is used\n` +
+    `                       as-is, with no defaults, and is never rewritten.\n` +
+    `                       [--json] [--dev-command <cmd>] [--dev-port <n>]\n` +
+    `                       [--build-command <cmd>] [--build-output <folder>]\n` +
+    `                       Diagnostics for such an app: npm i @vincentt-xr/harness,\n` +
+    `                       then import "@vincentt-xr/harness/auto"; (see the readme).\n` +
     `  unlink             Disconnect this folder from its project\n` +
     `  projects           List the workspace's projects, their ids, and where each\n` +
     `                       one lives on this machine  [--json]\n` +
@@ -37,9 +48,17 @@ export const USAGE_TEXT = `Vincentt CLI — local-first AR dev loop\n\n` +
     `                       [--org <s>] to list a workspace other than the active one\n\n` +
     `Dev loop\n` +
     `  publish            Upload the built dist; go live at <slug>.vincentt.app\n` +
-    `                       [--dist <path>] [--note <s>] [--yes]\n` +
+    `                       [--dist <path>] [--note <s>] [--yes] [--json]\n` +
+    `                       Says live once the address serves the new version\n` +
+    `                       (waits up to 90s; --json needs --yes).\n` +
+    `                       The folder is build.output from vincentt.json, else dist.\n` +
+    `                       --dist and build.output are relative to the project\n` +
+    `                       folder (the one holding the link), not the working dir.\n` +
     `  preview            Serve the app at an https link a phone can open\n` +
-    `                       [--port <n>] [--tester <id>] [--no-qr] [--stop]\n` +
+    `                       [--port <n>] [--dev-command <cmd>] [--tester <id>]\n` +
+    `                       [--no-qr] [--stop]\n` +
+    `                       Runs dev.command and forwards dev.port from vincentt.json,\n` +
+    `                       else npm run dev on 5173.\n` +
     `                       Re-running prints the live link; --restart mints a new one.\n\n` +
     // f16. HELP TEACHES THE CANONICAL VERBS ONLY: `add` and `remove` are accepted
     // as silent aliases and are deliberately ABSENT here, because help, docs and
@@ -97,7 +116,7 @@ export const USAGE_TEXT = `Vincentt CLI — local-first AR dev loop\n\n` +
     // DELIBERATELY ABSENT: any product name; any shell idiom; any mention of a
     // scheduled task EVEN TO FORBID ONE (naming a bad pattern is how a reader
     // learns it exists); any "recommended for AI" framing.
-    `Reverse channel — feedback sent from the phone\n` +
+    `Reverse channel: feedback sent from the phone\n` +
     `  feedback --wait     Block until feedback arrives, print every annotation\n` +
     `                        waiting as one JSON object per line, then exit.\n` +
     `                        [--timeout <seconds>, default 300]\n` +
@@ -119,8 +138,9 @@ export const USAGE_TEXT = `Vincentt CLI — local-first AR dev loop\n\n` +
     `                       Prints the installed and current version of each Vincentt\n` +
     `                       package, the string to place in package.json, and any\n` +
     `                       migration note the platform published. Writes nothing.\n` +
-    `  dx                 Where this dev loop fought you  [--days <n>] [--json]\n` +
+    `  dx                 Where this dev loop fought you  [--since <duration>] [--json]\n` +
     `                       Reads a local journal of your own runs. Local by default.\n` +
+    `                       Covers the last 24 hours; --since 30m, 2h or 7d changes it.\n` +
     `                       --send reports the findings to the Vincentt team; it\n` +
     `                       shows the exact payload and asks first. [--note <text>]\n` +
     `  dx enable          Allow reports to be sent from this machine without asking.\n` +
@@ -129,9 +149,11 @@ export const USAGE_TEXT = `Vincentt CLI — local-first AR dev loop\n\n` +
     `                       \`vincentt version\` while on.\n` +
     `  dx disable         Turn that off again.\n` +
     `  report "<text>"    Tell us something went wrong, in your own words.\n` +
-    `                       For when nothing failed but something looked wrong —\n` +
+    `                       For when nothing failed but something looked wrong,\n` +
     `                       the case \`dx --send\` cannot see. Shows the exact\n` +
     `                       payload and asks first. [--no-context] [--yes]\n\n` +
-    `Common options: --dir <path> (where to work, default cwd — for \`create\` this is\n` +
+    `Common options: --dir <path> (where to work, default cwd; for \`create\` this is\n` +
     `                              the PARENT of the new folder, not the folder itself)\n` +
-    `                --allow-custom-api  honor a binding's apiUrl override\n`;
+    `                --allow-custom-api  honor a binding's apiUrl override\n\n` +
+    `Exit 4 from any verb that needs an account: not signed in, or the stored token\n` +
+    `was refused. Run \`vincentt login\` at a terminal, then run the verb again.\n`;

package/dist/domain/api.d.ts

@@ -1,18 +1,20 @@
 import type { ResolvedConfig } from "../shared/config.js";
 import { type DomainListView, type DomainView } from "./wire.js";
-export interface DomainApiErrorDetail {
-    /** The plan's ceiling, on a ceiling refusal. */
-    limit?: number;
-    /** The plan in force, when the API names one. */
-    planName?: string;
-    planTier?: string;
+/**
+ * The ceiling refusal's figures. `domain_limit_reached` carries them at the TOP
+ * of the body, beside `code` and `message`, not under `detail`. `entitled` is 0
+ * for a plan that carries no custom domains at all.
+ */
+export interface DomainLimitFigures {
+    attached?: number;
+    entitled?: number;
 }
 export declare class DomainApiError extends Error {
     readonly status: number;
     readonly code: string;
-    readonly detail: DomainApiErrorDetail;
+    readonly figures: DomainLimitFigures;
     readonly retryAfterSec?: number | undefined;
-    constructor(status: number, code: string, message: string, detail?: DomainApiErrorDetail, retryAfterSec?: number | undefined);
+    constructor(status: number, code: string, message: string, figures?: DomainLimitFigures, retryAfterSec?: number | undefined);
 }
 /**
  * The record's role, when the API names one, parallel to `records`.

package/dist/domain/api.js

@@ -13,22 +13,26 @@
 // 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 { parseDomain, parseDomainList, } from "./wire.js";
 export class DomainApiError extends Error {
     status;
     code;
-    detail;
+    figures;
     retryAfterSec;
-    constructor(status, code, message, detail = {}, retryAfterSec) {
+    constructor(status, code, message, figures = {}, retryAfterSec) {
         super(message);
         this.status = status;
         this.code = code;
-        this.detail = detail;
+        this.figures = figures;
         this.retryAfterSec = retryAfterSec;
         this.name = "DomainApiError";
     }
 }
+/** Rejects with AuthExpiredError on a 401; every other status becomes a DomainApiError. */
 async function readError(res) {
+    rejectAuthExpired(res);
     let body = {};
     try {
         body = (await res.json());
@@ -36,8 +40,9 @@ async function readError(res) {
     catch {
         // A non-JSON error body is still an error; the status carries the meaning.
     }
+    const num = (v) => (typeof v === "number" ? v : undefined);
     const retryAfter = res.headers.get("retry-after");
-    return new DomainApiError(res.status, body.code ?? `http_${res.status}`, body.message ?? `request failed (${res.status})`, body.detail ?? {}, retryAfter ? Number(retryAfter) : undefined);
+    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}` };
@@ -51,7 +56,7 @@ function rolesOf(raw) {
     });
 }
 /** POST /projects/{id}/domains — returns the records to publish. Rate-limited. */
-export async function attachDomain(cfg, projectId, domain, fetchImpl = fetch) {
+export async function attachDomain(cfg, projectId, domain, fetchImpl = apiFetch) {
     const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/domains`, {
         method: "POST",
         headers: { ...authHeaders(cfg), "content-type": "application/json" },
@@ -76,7 +81,7 @@ export async function attachDomain(cfg, projectId, domain, fetchImpl = fetch) {
  * Rate-limited per `(org, domain)`, so a 429 here is expected traffic rather than
  * a defect, and its copy names no limit family.
  */
-export async function verifyDomain(cfg, projectId, domain, fetchImpl = fetch) {
+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) });
     if (!res.ok)
         throw await readError(res);
@@ -92,7 +97,7 @@ export async function verifyDomain(cfg, projectId, domain, fetchImpl = fetch) {
     };
 }
 /** GET /projects/{id}/domains — this project's domains with state + findings. */
-export async function listProjectDomains(cfg, projectId, fetchImpl = fetch) {
+export async function listProjectDomains(cfg, projectId, fetchImpl = apiFetch) {
     const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/domains`, { headers: authHeaders(cfg) });
     if (!res.ok)
         throw await readError(res);
@@ -106,14 +111,14 @@ export async function listProjectDomains(cfg, projectId, fetchImpl = fetch) {
  * collision copy is safe: a creator who genuinely holds a contested name finds it
  * here, and this route only ever returns their own.
  */
-export async function listOrgDomains(cfg, orgSlug, fetchImpl = fetch) {
+export async function listOrgDomains(cfg, orgSlug, fetchImpl = apiFetch) {
     const res = await fetchImpl(`${cfg.apiUrl}/orgs/${encodeURIComponent(orgSlug)}/domains`, { headers: authHeaders(cfg) });
     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 = fetch) {
+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) });
     // 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

package/dist/domain/command.js

@@ -21,6 +21,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 { localRefusal, normalizeArgument } from "./hostname.js";
 import * as copy from "./copy.js";
 /** The canonical subcommands. */
@@ -170,7 +171,15 @@ async function attachVerb(deps, cfg, opts) {
     }
     return 0;
 }
+/** The api refused the token: the sign-in remedy, and the not-signed-in exit code. */
+function authExpired(deps) {
+    for (const l of authExpiredLines())
+        deps.print(l);
+    return EXIT.NOT_AUTHENTICATED;
+}
 function printAttachError(deps, err, hostname) {
+    if (err instanceof AuthExpiredError)
+        return authExpired(deps);
     if (!(err instanceof DomainApiError)) {
         deps.print("");
         deps.print(`✗ Couldn't reach Vincentt to attach ${hostname}.`);
@@ -179,31 +188,25 @@ function printAttachError(deps, err, hostname) {
         deps.print("");
         return 1;
     }
-    // The refusals, each by the server's own code. The ceiling figure and the plan
-    // name come from the API — the CLI holds no plan ladder.
+    // The refusals, each by the server's own code. The ceiling figure comes from
+    // the API; the CLI holds no plan ladder. A platform hostname or a root domain
+    // the local check missed arrives as `domain_invalid` and takes the generic arm.
     switch (err.code) {
-        case "domain_limit_reached":
-            for (const l of copy.refusedAtCeiling(err.detail.limit ?? 0))
+        case "domain_limit_reached": {
+            // One code for both: a plan with no custom domains is refused at a
+            // ceiling of 0, and "using all 0" would read as a bug.
+            const entitled = err.figures.entitled;
+            const lines = entitled === 0 ? copy.refusedNoEntitlement() : copy.refusedAtCeiling(entitled);
+            for (const l of lines)
                 deps.print(l);
             return 1;
+        }
         case "domain_taken":
             // BYTE-IDENTICAL whether the holder is this workspace or a stranger. The
             // CLI passes no holder information because the API sends none.
             for (const l of copy.refusedAlreadyAttached(hostname))
                 deps.print(l);
             return 1;
-        case "platform_hostname":
-            for (const l of copy.refusedPlatformHost())
-                deps.print(l);
-            return 1;
-        case "root_domain_unsupported":
-            for (const l of copy.refusedRootDomain(hostname))
-                deps.print(l);
-            return 1;
-        case "no_entitlement":
-            for (const l of copy.refusedNoEntitlement(err.detail.planName))
-                deps.print(l);
-            return 1;
         default:
             break;
     }
@@ -236,6 +239,8 @@ async function listVerb(deps, cfg, opts) {
         view = await deps.listOrg(cfg, org.org.slug);
     }
     catch (err) {
+        if (err instanceof AuthExpiredError)
+            return authExpired(deps);
         deps.print("");
         deps.print(err instanceof DomainApiError
             ? `✗ ${err.message}`
@@ -288,6 +293,8 @@ async function verifyVerb(deps, cfg, opts) {
         result = await deps.verify(cfg, binding.projectId, hostname);
     }
     catch (err) {
+        if (err instanceof AuthExpiredError)
+            return authExpired(deps);
         if (err instanceof DomainApiError && err.status === 404) {
             for (const l of copy.notAttached(hostname))
                 deps.print(l);
@@ -452,6 +459,8 @@ async function detachVerb(deps, cfg, opts) {
         await deps.detach(cfg, binding.projectId, hostname);
     }
     catch (err) {
+        if (err instanceof AuthExpiredError)
+            return authExpired(deps);
         deps.print("");
         deps.print(err instanceof DomainApiError
             ? `✗ ${err.message}`

package/dist/domain/copy.d.ts

@@ -166,7 +166,7 @@ export declare const NOTHING_WAS_CLAIMED = "  Nothing was claimed.";
  * No price, no plan name other than the one they are on, no URL. Clause 4 reaches
  * the CLI too.
  */
-export declare function refusedAtCeiling(limit: number): string[];
+export declare function refusedAtCeiling(entitled: number | undefined): string[];
 /**
  * Already attached — THE ANTI-ORACLE ANSWER.
  *
@@ -192,8 +192,11 @@ export declare function refusedPlatformHost(): string[];
  * doesn't support it"* sounds like something we might fix on request.
  */
 export declare function refusedRootDomain(domain: string): string[];
-/** Not on a plan that carries custom domains. Names the plan they are on and nothing else. */
-export declare function refusedNoEntitlement(planName: string | undefined): string[];
+/**
+ * Not on a plan that carries custom domains: the ceiling refusal at
+ * `entitled: 0`. The body names no plan, so neither does this.
+ */
+export declare function refusedNoEntitlement(): string[];
 /**
  * A verify refused by the rate limit.
  *

package/dist/domain/copy.js

@@ -477,10 +477,12 @@ export const NOTHING_WAS_CLAIMED = "  Nothing was claimed.";
  * No price, no plan name other than the one they are on, no URL. Clause 4 reaches
  * the CLI too.
  */
-export function refusedAtCeiling(limit) {
+export function refusedAtCeiling(entitled) {
+    // A body without the figure states no number rather than inventing one.
+    const all = entitled === undefined ? "all" : `all ${entitled}`;
     return [
         "",
-        `✗ This workspace is using all ${limit} of the custom domains its plan carries.`,
+        `✗ This workspace is using ${all} of the custom domains its plan carries.`,
         "",
         "  Detach one to attach this:",
         "    vincentt domain list",
@@ -550,12 +552,14 @@ export function refusedRootDomain(domain) {
         "",
     ];
 }
-/** Not on a plan that carries custom domains. Names the plan they are on and nothing else. */
-export function refusedNoEntitlement(planName) {
-    const plan = planName ? ` This workspace is on ${planName}.` : "";
+/**
+ * Not on a plan that carries custom domains: the ceiling refusal at
+ * `entitled: 0`. The body names no plan, so neither does this.
+ */
+export function refusedNoEntitlement() {
     return [
         "",
-        `✗ Custom domains are part of the paid plans.${plan}`,
+        "✗ Custom domains are part of the paid plans.",
         "",
         "  An owner can change the workspace's plan in the console.",
         "",

package/dist/dx/command.d.ts

@@ -1,10 +1,11 @@
 import type { ConsentDecision } from "./consent.js";
 import type { Enablement } from "./enablement.js";
-import type { JournalEntry } from "./journal.js";
+import type { JournalEntry, JournalWindow } from "./journal.js";
 import type { WireReport } from "./send.js";
 import { type BuiltWith } from "../platform/resolve.js";
 export interface DxDeps {
-    entries: () => JournalEntry[];
+    /** Entries inside the window, or the whole journal when called without one. */
+    entries: (window?: JournalWindow) => JournalEntry[];
     print: (line: string) => void;
     now: () => number;
     enabled: () => boolean;
@@ -15,9 +16,17 @@ export interface DxDeps {
      */
     enablement?: () => Enablement;
 }
+/** How far back a report looks. */
+export interface DxWindow {
+    ms: number;
+    /** The compact form a caller types and `--json` carries: `30m`, `24h`, `7d`. */
+    label: string;
+}
 export interface DxOptions {
-    /** Only consider runs from the last N days. */
-    days: number;
+    /** Only consider runs inside this window. */
+    window: DxWindow;
+    /** The `--since` value that did not parse, when one was given. */
+    sinceInvalid?: string;
     json: boolean;
     /** Send the findings to the Vincentt team. Never implied by anything else. */
     send: boolean;
@@ -30,6 +39,17 @@ export interface DxOptions {
     /** `vincentt dx disable` — a positional subcommand, not a flag. */
     disable: boolean;
 }
+/**
+ * One sitting, not the whole file. A report is read as describing the session
+ * that prompted it, so the default must not reach back into earlier ones.
+ */
+export declare const DEFAULT_WINDOW: DxWindow;
+/** `30m`, `2h`, `7d`: a positive whole number and one unit. Anything else is undefined. */
+export declare function parseDuration(raw: string): DxWindow | undefined;
+/** `the last 24 hours`, `the last hour`, `the last 7 days`. */
+export declare function describeWindow(w: DxWindow): string;
+/** The usage refusal for a `--since` value that did not parse. */
+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. */

package/dist/dx/command.js

@@ -3,10 +3,64 @@ import { enablementLine } from "./enablement.js";
 import { journalEnabled, journalPath, readJournal } from "./journal.js";
 import { buildReport, renderPayload } from "./send.js";
 import { resolveBuiltWith } from "../platform/resolve.js";
-const DEFAULT_DAYS = 7;
+import { EXIT } from "../lib/exitCodes.js";
+const MINUTE_MS = 60 * 1000;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
+const UNIT_MS = { m: MINUTE_MS, h: HOUR_MS, d: DAY_MS };
+const UNIT_WORD = { m: "minute", h: "hour", d: "day" };
+/**
+ * One sitting, not the whole file. A report is read as describing the session
+ * that prompted it, so the default must not reach back into earlier ones.
+ */
+export const DEFAULT_WINDOW = { ms: DAY_MS, label: "24h" };
+/** `30m`, `2h`, `7d`: a positive whole number and one unit. Anything else is undefined. */
+export function parseDuration(raw) {
+    const m = /^([1-9]\d*)([mhd])$/.exec(raw.trim());
+    if (m === null)
+        return undefined;
+    const n = Number(m[1]);
+    const ms = n * UNIT_MS[m[2]];
+    if (!Number.isSafeInteger(ms))
+        return undefined;
+    return { ms, label: `${n}${m[2]}` };
+}
+/** `the last 24 hours`, `the last hour`, `the last 7 days`. */
+export function describeWindow(w) {
+    const m = /^(\d+(?:\.\d+)?)([mhd])$/.exec(w.label);
+    if (m === null)
+        return `the last ${w.label}`;
+    const word = UNIT_WORD[m[2]];
+    return m[1] === "1" ? `the last ${word}` : `the last ${m[1]} ${word}s`;
+}
+/** The usage refusal for a `--since` value that did not parse. */
+export function sinceUsageLines(raw) {
+    return [
+        raw === ""
+            ? "--since needs a duration."
+            : `Invalid --since value: ${JSON.stringify(raw)}.`,
+        "Use a whole number and a unit: 30m, 2h or 7d.",
+        "Usage: vincentt dx [--since <duration>] [--json]",
+    ];
+}
+function parseWindow(args) {
+    const s = args.indexOf("--since");
+    if (s !== -1) {
+        const raw = args[s + 1];
+        const parsed = raw === undefined || raw.startsWith("-") ? undefined : parseDuration(raw);
+        return parsed !== undefined
+            ? { window: parsed }
+            : { window: DEFAULT_WINDOW, sinceInvalid: raw ?? "" };
+    }
+    // `--days <n>` predates `--since` and stays accepted so scripts written
+    // against it keep their window.
+    const d = args.indexOf("--days");
+    const days = d !== -1 ? Number(args[d + 1]) : NaN;
+    return Number.isFinite(days) && days > 0
+        ? { window: { ms: days * DAY_MS, label: `${days}d` } }
+        : { window: DEFAULT_WINDOW };
+}
 export function parseDxOptions(args) {
-    const i = args.indexOf("--days");
-    const raw = i !== -1 ? Number(args[i + 1]) : NaN;
     const n = args.indexOf("--note");
     const note = n !== -1 ? args[n + 1] : undefined;
     // Positional, and read only from the slot right after the verb: `--note enable`
@@ -15,7 +69,7 @@ export function parseDxOptions(args) {
     // already running, which is the shape this whole gate exists to refuse.
     const sub = args[0] === "dx" ? args[1] : args[0];
     return {
-        days: Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_DAYS,
+        ...parseWindow(args),
         json: args.includes("--json"),
         send: args.includes("--send"),
         yes: args.includes("--yes"),
@@ -24,12 +78,8 @@ export function parseDxOptions(args) {
         disable: sub === "disable",
     };
 }
-function withinDays(entries, days, now) {
-    const cutoff = now - days * 24 * 60 * 60 * 1000;
-    return entries.filter((e) => {
-        const t = Date.parse(e.ts);
-        return Number.isFinite(t) && t >= cutoff;
-    });
+function cutoff(options, now) {
+    return { sinceMs: now - options.window.ms };
 }
 function seconds(ms) {
     if (ms < 1000)
@@ -41,8 +91,8 @@ function seconds(ms) {
 }
 function describe(c) {
     const head = c.kind === "error"
-        ? `${c.entries.length}× ${c.skeleton} — ${c.errors} failed${c.recovered ? ", then succeeded" : ", never recovered"}`
-        : `${c.entries.length}× ${c.skeleton} — all succeeded, within ${seconds(c.spanMs)}`;
+        ? `${c.entries.length}× ${c.skeleton}: ${c.errors} failed${c.recovered ? ", then succeeded" : ", never recovered"}`
+        : `${c.entries.length}× ${c.skeleton}: all succeeded, within ${seconds(c.spanMs)}`;
     const why = c.kind === "error"
         ? c.recovered
             ? "  The caller got there in the end. What did the first failure not tell them?"
@@ -61,13 +111,14 @@ export function dxCommand(deps, options) {
         deps.print("The DX journal is off (VINCENTT_DX_JOURNAL=0). Nothing is being recorded.");
         return 0;
     }
-    const all = deps.entries();
-    if (all.length === 0) {
-        deps.print("No journal yet — it fills as you use the CLI.");
+    const entries = deps.entries(cutoff(options, deps.now()));
+    // Only an empty window pays for the second, unwindowed read, and it is what
+    // tells "nothing recorded yet" apart from "nothing recent".
+    if (entries.length === 0 && deps.entries().length === 0) {
+        deps.print("No journal yet. It fills as you use the CLI.");
         deps.print(`  ${deps.path()}`);
         return 0;
     }
-    const entries = withinDays(all, options.days, deps.now());
     const clusters = rankClusters(findClusters(entries));
     const enablement = deps.enablement?.() ?? { enabled: false };
     if (options.json) {
@@ -75,7 +126,7 @@ export function dxCommand(deps, options) {
         // AGENT reads, and an agent that can send unattended should be able to see
         // that it can.
         deps.print(JSON.stringify({
-            window: `${options.days}d`,
+            window: options.window.label,
             runs: entries.length,
             clusters,
             dxSendEnabled: enablement.enabled,
@@ -85,7 +136,7 @@ export function dxCommand(deps, options) {
         }, null, 2));
         return 0;
     }
-    deps.print(`${entries.length} runs in the last ${options.days} days.`);
+    deps.print(`${entries.length} runs in ${describeWindow(options.window)}.`);
     deps.print("");
     if (clusters.length === 0) {
         // A clean window is a real result. Manufacturing a finding to fill the
@@ -100,7 +151,7 @@ export function dxCommand(deps, options) {
                 deps.print(l);
             deps.print("");
         }
-        deps.print("If an agent ran these, ask it what it was trying to do — the journal");
+        deps.print("If an agent ran these, ask it what it was trying to do; the journal");
         deps.print("records the shape of a run, not the intent behind it.");
     }
     // Printed on every report, findings or not: where the file is and that it
@@ -119,7 +170,7 @@ export function dxCommand(deps, options) {
 /** Wire the command to the real journal. */
 export function runDx(args, print, enablement = () => ({ enabled: false })) {
     return dxCommand({
-        entries: readJournal,
+        entries: (window) => readJournal(window),
         print,
         now: () => Date.now(),
         enabled: () => journalEnabled(),
@@ -178,7 +229,7 @@ export async function dxEnableCommand(deps, sunset) {
         deps.print("");
         deps.print("  Run `vincentt login` first.");
         deps.print("");
-        return 1;
+        return EXIT.NOT_AUTHENTICATED;
     }
     if (!deps.interactive()) {
         return enableViaBrowser(deps);
@@ -333,12 +384,12 @@ export async function dxSendCommand(deps, options) {
         deps.print("The DX journal is off (VINCENTT_DX_JOURNAL=0). There is nothing to send.");
         return 0;
     }
-    const entries = withinDays(deps.entries(), options.days, deps.now());
+    const entries = deps.entries(cutoff(options, deps.now()));
     const clusters = rankClusters(findClusters(entries));
     if (clusters.length === 0) {
         // Nothing to report is a result, not a failure. Sending an empty report
         // would cost the creator a round trip to tell us nothing.
-        deps.print(`No friction detected in the last ${options.days} days — nothing to send.`);
+        deps.print(`No friction detected in ${describeWindow(options.window)}. Nothing to send.`);
         return 0;
     }
     // SENDING requires either an interactive session or durable enablement — the
@@ -416,7 +467,7 @@ export async function dxSendCommand(deps, options) {
     }
     if (auth === undefined) {
         deps.print("Not signed in. Run `vincentt login` to send a report.");
-        return 1;
+        return EXIT.NOT_AUTHENTICATED;
     }
     // RESOLVED AFTER THE GATE AND IMMEDIATELY BEFORE THE BUILD.
     //
@@ -448,6 +499,10 @@ export async function dxSendCommand(deps, options) {
             deps.print(`${line}. Not asking.`);
         }
     }
+    // The window is stated beside the payload rather than in it: the api refuses
+    // fields it does not know, so carrying it would be a contract change.
+    deps.print("");
+    deps.print(`Findings from ${describeWindow(options.window)}.`);
     // renderPayload runs on EVERY path, including the unattended one. This is
     // DISCLOSURE, NOT CONSENT: on the attended path it is what the creator answers
     // to; unattended it is a forensic artifact that answers "what did we send"
@@ -465,7 +520,7 @@ export async function dxSendCommand(deps, options) {
     try {
         const res = await deps.post(auth.apiUrl, auth.pat, report);
         deps.print("");
-        deps.print(`✓ Reported — ${res.findings} ${res.findings === 1 ? "finding" : "findings"}, ref ${res.ref}`);
+        deps.print(`✓ Reported: ${res.findings} ${res.findings === 1 ? "finding" : "findings"}, ref ${res.ref}`);
         deps.print(`  Kept until ${res.expiresAt}, then deleted.`);
         deps.print("  Your journal stays on this machine.");
         return 0;