@vincentt-xr/cli 0.6.0 → 0.8.0

package/dist/dx/enablement.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The product-lifetime bound on an explicitly internal-beta capability. Past this
+ * date `enable` refuses AND an existing flag stops being honored, so FORGETTING
+ * THIS TURNS THE FEATURE OFF — the safe direction.
+ *
+ * This is deliberately a constant in shipped code rather than a CI test with a
+ * hard-coded date: such a test fires in an uninvolved engineer's lap at a moment
+ * with no context, and the cheapest green is bumping the constant. Reaching this
+ * date is a decision to make (extend, or remove the feature), not a number to
+ * raise.
+ */
+export declare const DX_UNATTENDED_SUNSET: number;
+export interface Enablement {
+    enabled: boolean;
+    /** The raw ISO8601 grant time. Present only when `enabled` is true. */
+    at?: string;
+}
+/**
+ * Decide enablement from an already-parsed config object. Pure, and STRICT:
+ * identity against `true`, never truthiness.
+ *
+ * Truthiness fails OPEN on `"false"`, `"0"`, `{}`, `[]`, `1`, and `"garbage"` —
+ * every one of those is truthy in JavaScript. The worst is `"false"`, which is
+ * what a person hand-editing this file writes when they are trying to turn the
+ * feature OFF; `{}` is what a refactor grouping the two fields produces. A gate
+ * that reads a creator's "off" as "on" is inverted, not merely loose.
+ */
+export declare function readEnablement(cfg: unknown, now: number): Enablement;
+/**
+ * Read enablement from the real machine config.
+ *
+ * Wrapped in its OWN try/catch, independent of the auth read, because
+ * `readJsonIfExists` rethrows everything that is not ENOENT: a truncated
+ * config.json must DISABLE the relaxation, not throw through it and take an
+ * unrelated verb down with it.
+ */
+export declare function loadEnablement(now: number): Promise<Enablement>;
+/** Whole days elapsed, floored, never negative — a clock skew must not print `(-2 days)`. */
+export declare function ageInDays(at: string, now: number): number;
+/** The calendar day of the grant, in UTC. The time of day is noise at this age scale. */
+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)
+ *
+ * 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,
+ * which would cost exactly the attention the enabled line needs.
+ */
+export declare function enablementLine(e: Enablement, now: number): string | undefined;

package/dist/dx/enablement.js

@@ -0,0 +1,97 @@
+/**
+ * Durable authorization for unattended `vincentt dx --send`.
+ *
+ * `--send` transmits only when the session is interactive OR this machine has
+ * been explicitly enabled by a person, at a terminal, via `vincentt dx enable`.
+ * The state is two fields in ~/.vincentt/config.json, set by `enable`, cleared by
+ * `disable` and by `logout`, and it has NO expiry — it stays on until the creator
+ * turns it off.
+ *
+ * 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
+ * `(145 days)` reads as drift and is the number that makes someone ask whether
+ * they still want it. That is why an unparseable timestamp fails CLOSED rather
+ * than printing `since Invalid Date (NaN days)` — a degraded mitigation is worse
+ * than a visible absence.
+ */
+import { loadMachineConfig } from "../shared/config.js";
+/**
+ * The product-lifetime bound on an explicitly internal-beta capability. Past this
+ * date `enable` refuses AND an existing flag stops being honored, so FORGETTING
+ * THIS TURNS THE FEATURE OFF — the safe direction.
+ *
+ * This is deliberately a constant in shipped code rather than a CI test with a
+ * hard-coded date: such a test fires in an uninvolved engineer's lap at a moment
+ * with no context, and the cheapest green is bumping the constant. Reaching this
+ * date is a decision to make (extend, or remove the feature), not a number to
+ * raise.
+ */
+export const DX_UNATTENDED_SUNSET = Date.parse("2027-02-24T00:00:00.000Z");
+const DISABLED = { enabled: false };
+/**
+ * Decide enablement from an already-parsed config object. Pure, and STRICT:
+ * identity against `true`, never truthiness.
+ *
+ * Truthiness fails OPEN on `"false"`, `"0"`, `{}`, `[]`, `1`, and `"garbage"` —
+ * every one of those is truthy in JavaScript. The worst is `"false"`, which is
+ * what a person hand-editing this file writes when they are trying to turn the
+ * feature OFF; `{}` is what a refactor grouping the two fields produces. A gate
+ * that reads a creator's "off" as "on" is inverted, not merely loose.
+ */
+export function readEnablement(cfg, now) {
+    if (typeof cfg !== "object" || cfg === null)
+        return DISABLED;
+    const { dxSendEnabled, dxSendEnabledAt } = cfg;
+    if (dxSendEnabled !== true)
+        return DISABLED;
+    if (typeof dxSendEnabledAt !== "string")
+        return DISABLED;
+    if (!Number.isFinite(Date.parse(dxSendEnabledAt)))
+        return DISABLED;
+    if (now >= DX_UNATTENDED_SUNSET)
+        return DISABLED;
+    return { enabled: true, at: dxSendEnabledAt };
+}
+/**
+ * Read enablement from the real machine config.
+ *
+ * Wrapped in its OWN try/catch, independent of the auth read, because
+ * `readJsonIfExists` rethrows everything that is not ENOENT: a truncated
+ * config.json must DISABLE the relaxation, not throw through it and take an
+ * unrelated verb down with it.
+ */
+export async function loadEnablement(now) {
+    try {
+        return readEnablement(await loadMachineConfig(), now);
+    }
+    catch {
+        return DISABLED;
+    }
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Whole days elapsed, floored, never negative — a clock skew must not print `(-2 days)`. */
+export function ageInDays(at, now) {
+    const t = Date.parse(at);
+    if (!Number.isFinite(t))
+        return 0;
+    return Math.max(0, Math.floor((now - t) / DAY_MS));
+}
+/** The calendar day of the grant, in UTC. The time of day is noise at this age scale. */
+export function grantedOn(at) {
+    return new Date(Date.parse(at)).toISOString().slice(0, 10);
+}
+/**
+ * The one visibility line, in the single pinned shape every human surface uses:
+ *
+ *   Unattended send: ENABLED since 2026-04-01 (145 days)
+ *
+ * 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,
+ * which would cost exactly the attention the enabled line needs.
+ */
+export function enablementLine(e, now) {
+    if (!e.enabled || e.at === undefined)
+        return undefined;
+    const days = ageInDays(e.at, now);
+    return `Unattended send: ENABLED since ${grantedOn(e.at)} (${days} ${days === 1 ? "day" : "days"})`;
+}

package/dist/dx/nudge.d.ts

@@ -0,0 +1,7 @@
+import type { JournalEntry } from "./journal.js";
+/**
+ * The nudge fires only on a cluster the CURRENT run just completed, so it
+ * appears at the moment of friction rather than as a standing complaint about
+ * something that happened this morning.
+ */
+export declare function nudgeFor(entries: JournalEntry[], now: number): string[];

package/dist/dx/nudge.js

@@ -0,0 +1,54 @@
+/**
+ * The nudge: a one-line hint, printed after a command that just completed a
+ * friction cluster, telling the creator the report exists.
+ *
+ * It is here because a command nobody remembers produces no data. A creator
+ * building an AR app is not going to think "I should audit my tooling" — they
+ * are going to swear at the fourth preview and keep going. The moment the
+ * friction happens is the only moment the report is cheap to ask for.
+ *
+ * It is a HINT and never an action. Nothing is sent, nothing is queued, and the
+ * creator still has to type the command — which is what keeps `--send` an
+ * explicit act rather than a dialog they clicked through while annoyed.
+ */
+import { findClusters } from "./clusters.js";
+/** How far back a nudge looks. A cluster older than this is not "right now". */
+const WINDOW_MS = 15 * 60 * 1000;
+/**
+ * The nudge fires only on a cluster the CURRENT run just completed, so it
+ * appears at the moment of friction rather than as a standing complaint about
+ * something that happened this morning.
+ */
+export function nudgeFor(entries, now) {
+    if (entries.length === 0)
+        return [];
+    const recent = entries.filter((e) => {
+        const t = Date.parse(e.ts);
+        return Number.isFinite(t) && now - t <= WINDOW_MS;
+    });
+    if (recent.length === 0)
+        return [];
+    const last = recent[recent.length - 1];
+    const clusters = findClusters(recent);
+    // Only a cluster the LAST entry belongs to. A cluster the caller already
+    // worked past is not friction they are feeling now, and nagging about it is
+    // how a hint becomes noise a reader learns to skip.
+    const live = clusters.find((c) => c.skeleton === last.skel && c.entries[c.entries.length - 1].ts === last.ts);
+    if (live === undefined)
+        return [];
+    const what = live.kind === "repetition"
+        ? `${live.entries.length} runs of \`${live.skeleton}\` in a few minutes.`
+        : `\`${live.skeleton}\` failed ${live.errors}× just now.`;
+    // STATES A FACT, NEVER AN INSTRUCTION.
+    //
+    // This line lands in an agent's transcript, because in the agent-driven loop
+    // the CLI's stdout IS the agent's input. "Run `vincentt dx --send` to report
+    // this" is a directive an autonomous caller will simply obey — and a report
+    // an agent decided to send is automation wearing consent's clothes, not the
+    // opt-in this feature is built around. Naming that a command exists is
+    // information; telling a caller to transmit is not.
+    //
+    // Note it names `vincentt dx` (which only READS, locally) and never the
+    // sending form.
+    return ["", `  ! ${what}`, "    `vincentt dx` shows friction from your recent runs."];
+}

package/dist/dx/qa.f7.fixtures.d.ts

@@ -0,0 +1,73 @@
+/**
+ * QA fixtures for the dx-agent-consent delta (f7).
+ *
+ * Declared in the change's qa.md `## Fixtures` section. All three are
+ * machine-config state, which f7 has never had a fixture for — its existing
+ * fixtures (F7_JOURNAL_FRICTION, F7_REPORT_EXPIRED, …) are journal-side or
+ * server-side.
+ *
+ * F7_CONFIG_SIGNED_IN is written by driving the REAL writeMachineConfig(), never
+ * by hand-writing JSON. A hand-written config asserts against a shape the CLI
+ * never produces — the f1 orgs/memberships failure at file scope, where a mock
+ * of state the API could actually produce drifted from the API and stayed green.
+ *
+ * These are QA-owned (qa.* prefix) and deliberately separate from dev's test
+ * files in the same package.
+ */
+import type { JournalEntry } from "./journal.js";
+/** The honest baseline config, as the CLI itself writes it. */
+export declare const F7_CONFIG_SIGNED_IN: {
+    readonly apiUrl: "https://api.test";
+    readonly consoleUrl: "https://console.test";
+    readonly pat: "vct_alice";
+    readonly activeOrg: "alice";
+};
+/**
+ * The instant every fixture is dated against. 145 days after the grant in
+ * F7_CONFIG_ENABLED, and before DX_UNATTENDED_SUNSET.
+ */
+export declare const F7_NOW: number;
+/** 145 days before F7_NOW. The AGE is the point — see qa.md on F7_CONFIG_ENABLED. */
+export declare const F7_ENABLED_AT = "2026-04-01T00:00:00.000Z";
+/**
+ * The single pinned human-facing shape. Every human surface must render this
+ * byte-for-byte; the age is the load-bearing half, so it is pinned as a literal
+ * rather than computed (a computed expectation would follow a broken
+ * implementation wherever it went).
+ */
+export declare const F7_PINNED_ENABLEMENT_LINE = "Unattended send: ENABLED since 2026-04-01 (145 days)";
+/** F7_CONFIG_SIGNED_IN + durable enablement, aged. */
+export declare const F7_CONFIG_ENABLED: {
+    readonly dxSendEnabled: true;
+    readonly dxSendEnabledAt: "2026-04-01T00:00:00.000Z";
+    readonly apiUrl: "https://api.test";
+    readonly consoleUrl: "https://console.test";
+    readonly pat: "vct_alice";
+    readonly activeOrg: "alice";
+};
+/**
+ * Every shape the enablement read must treat as DISABLED.
+ *
+ * Rows B, C, E, F, G are TRUTHY IN JAVASCRIPT — `if (cfg.dxSendEnabled)` passes
+ * every one of them. That is the entire reason this fixture exists, and why the
+ * read is specified as `=== true`. The worst is B ("false"): what a person
+ * hand-editing this file writes when trying to turn the feature OFF.
+ *
+ * `raw` rows (K, L) are written as bytes rather than as an object, because the
+ * property under test is that an UNPARSEABLE config fails closed instead of
+ * throwing through into an unrelated verb.
+ */
+export interface MalformedRow {
+    id: string;
+    why: string;
+    /** A config object to serialize, or undefined when `raw` carries the bytes. */
+    patch?: Record<string, unknown>;
+    /** Literal file bytes, for the rows that are not valid JSON at all. */
+    raw?: string;
+}
+export declare const F7_CONFIG_MALFORMED_ENABLEMENT: MalformedRow[];
+/**
+ * F7_JOURNAL_FRICTION, as the record declares it: three runs of the same verb in
+ * a few minutes, which is a repetition cluster.
+ */
+export declare function f7JournalFriction(now?: number): JournalEntry[];

package/dist/dx/qa.f7.fixtures.js

@@ -0,0 +1,58 @@
+/** The honest baseline config, as the CLI itself writes it. */
+export const F7_CONFIG_SIGNED_IN = {
+    apiUrl: "https://api.test",
+    consoleUrl: "https://console.test",
+    pat: "vct_alice",
+    activeOrg: "alice",
+};
+/**
+ * The instant every fixture is dated against. 145 days after the grant in
+ * F7_CONFIG_ENABLED, and before DX_UNATTENDED_SUNSET.
+ */
+export const F7_NOW = Date.parse("2026-08-24T12:00:00.000Z");
+/** 145 days before F7_NOW. The AGE is the point — see qa.md on F7_CONFIG_ENABLED. */
+export const F7_ENABLED_AT = "2026-04-01T00:00:00.000Z";
+/**
+ * The single pinned human-facing shape. Every human surface must render this
+ * byte-for-byte; the age is the load-bearing half, so it is pinned as a literal
+ * rather than computed (a computed expectation would follow a broken
+ * implementation wherever it went).
+ */
+export const F7_PINNED_ENABLEMENT_LINE = "Unattended send: ENABLED since 2026-04-01 (145 days)";
+/** F7_CONFIG_SIGNED_IN + durable enablement, aged. */
+export const F7_CONFIG_ENABLED = {
+    ...F7_CONFIG_SIGNED_IN,
+    dxSendEnabled: true,
+    dxSendEnabledAt: F7_ENABLED_AT,
+};
+export const F7_CONFIG_MALFORMED_ENABLEMENT = [
+    { id: "A", why: 'truthy STRING "true"', patch: { dxSendEnabled: "true", dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "B", why: 'truthy in JS, means false to a human', patch: { dxSendEnabled: "false", dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "C", why: 'truthy in JS ("0")', patch: { dxSendEnabled: "0", dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "D", why: "truthy, not the boolean (1)", patch: { dxSendEnabled: 1, dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "E", why: "truthy ({} — what a refactor grouping the fields produces)", patch: { dxSendEnabled: {}, dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "F", why: "truthy ([])", patch: { dxSendEnabled: [], dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "G", why: 'truthy ("garbage")', patch: { dxSendEnabled: "garbage", dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "H", why: "key absent entirely", patch: {} },
+    { id: "I", why: "enabled true, dxSendEnabledAt absent", patch: { dxSendEnabled: true } },
+    { id: "J", why: 'enabled true, dxSendEnabledAt "not-a-date"', patch: { dxSendEnabled: true, dxSendEnabledAt: "not-a-date" } },
+    { id: "K", why: "file truncated mid-JSON", raw: '{"pat":"vct_alice","dxSendEn' },
+    { id: "L", why: "file empty (0 bytes)", raw: "" },
+];
+/**
+ * F7_JOURNAL_FRICTION, as the record declares it: three runs of the same verb in
+ * a few minutes, which is a repetition cluster.
+ */
+export function f7JournalFriction(now = F7_NOW) {
+    const entry = (minutesAgo) => ({
+        ts: new Date(now - minutesAgo * 60_000).toISOString(),
+        v: "0.7.0",
+        verb: "preview",
+        skel: "preview",
+        exit: 0,
+        ms: 800,
+        err: null,
+        wt: "abc123",
+    });
+    return [entry(3), entry(2), entry(1)];
+}

package/dist/dx/send.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `vincentt dx --send` — the one place anything from the journal leaves the
+ * machine.
+ *
+ * The journal itself is local and unconditional. Sending is neither: it happens
+ * only when a creator types this flag, and only after they have been shown the
+ * exact payload. That ordering is the whole consent model — a report is an act,
+ * not a background transmission — so nothing in this file may be called from a
+ * path the creator did not ask for.
+ *
+ * What goes: the SHAPE of the friction (skeleton, counts, timing, error class
+ * names) plus the CLI version and platform. What never goes: the raw journal,
+ * flag values, paths, error messages, or anything about which project this was.
+ * The server re-validates all of it — a client that leaked a value cannot
+ * persist it by asking — but the boundary is drawn here first, because a payload
+ * that needs server-side scrubbing was built wrong.
+ */
+import type { Cluster } from "./clusters.js";
+/** A finding as it goes on the wire. Mirrors the API's dxFindingRequest. */
+export interface WireFinding {
+    kind: "error" | "repetition";
+    skeleton: string;
+    calls: number;
+    errors: number;
+    spanMs: number;
+    errorClasses?: string[];
+    note?: string;
+}
+export interface WireReport {
+    cliVersion: string;
+    platform: string;
+    findings: WireFinding[];
+}
+/**
+ * The server bounds a report at 50 findings and refuses the whole thing past
+ * that, so the worst clusters are sent rather than the request rejected. They
+ * arrive ranked, so this is a head, not a sample.
+ */
+export declare const MAX_SENT_FINDINGS = 50;
+export declare function platformTag(): string;
+/**
+ * Build the wire payload from ranked clusters.
+ *
+ * Every field here is derived from the journal's own skeletonized entries — this
+ * function reads counts and timings, never values. If a future journal field
+ * carries content, it must not be added to this mapping without the same
+ * scrutiny the skeleton got.
+ */
+export declare function buildReport(clusters: Cluster[], cliVersion: string, note?: string): WireReport;
+/**
+ * Render the payload for the creator to read BEFORE it is sent.
+ *
+ * This is not a summary of the payload — it is the payload, formatted. A preview
+ * that paraphrased what would be sent would be exactly the wrong thing to show
+ * someone deciding whether to send it.
+ */
+export declare function renderPayload(report: WireReport): string[];
+export interface SendResult {
+    ref: string;
+    findings: number;
+    expiresAt: string;
+}
+export declare class DXSendError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/**
+ * POST the report. The caller has already shown the payload and had it accepted.
+ */
+export declare function postReport(apiUrl: string, pat: string, report: WireReport, fetchImpl?: typeof fetch): Promise<SendResult>;

package/dist/dx/send.js

@@ -0,0 +1,108 @@
+/**
+ * The server bounds a report at 50 findings and refuses the whole thing past
+ * that, so the worst clusters are sent rather than the request rejected. They
+ * arrive ranked, so this is a head, not a sample.
+ */
+export const MAX_SENT_FINDINGS = 50;
+/** Error classes per finding, matching the server's bound. */
+const MAX_ERROR_CLASSES = 10;
+export function platformTag() {
+    return `${process.platform}-${process.arch}`;
+}
+/**
+ * Build the wire payload from ranked clusters.
+ *
+ * Every field here is derived from the journal's own skeletonized entries — this
+ * function reads counts and timings, never values. If a future journal field
+ * carries content, it must not be added to this mapping without the same
+ * scrutiny the skeleton got.
+ */
+export function buildReport(clusters, cliVersion, note) {
+    const findings = clusters.slice(0, MAX_SENT_FINDINGS).map((c) => {
+        const classes = [
+            ...new Set(c.entries.map((e) => e.err).filter((e) => e !== null)),
+        ].slice(0, MAX_ERROR_CLASSES);
+        const f = {
+            kind: c.kind,
+            skeleton: c.skeleton,
+            calls: c.entries.length,
+            errors: c.errors,
+            spanMs: Math.max(0, Math.round(c.spanMs)),
+        };
+        if (classes.length > 0)
+            f.errorClasses = classes;
+        return f;
+    });
+    // The note rides on the first finding: it is the creator's own words about the
+    // friction they are reporting, and the report is about one sitting.
+    if (note !== undefined && note.trim() !== "" && findings.length > 0) {
+        findings[0].note = note.trim();
+    }
+    return { cliVersion, platform: platformTag(), findings };
+}
+/**
+ * Render the payload for the creator to read BEFORE it is sent.
+ *
+ * This is not a summary of the payload — it is the payload, formatted. A preview
+ * that paraphrased what would be sent would be exactly the wrong thing to show
+ * someone deciding whether to send it.
+ */
+export function renderPayload(report) {
+    const hasNote = report.findings.some((f) => f.note !== undefined && f.note !== "");
+    const lines = [
+        "This is what would be sent:",
+        "",
+        ...JSON.stringify(report, null, 2)
+            .split("\n")
+            .map((l) => `  ${l}`),
+        "",
+    ];
+    // The generated fields carry shape only. The NOTE does not, and saying
+    // otherwise above a note that may hold a path or a token would be asking the
+    // creator to consent on a false claim — the one thing this screen exists to
+    // prevent. So the sentence changes when a note is present.
+    if (hasNote) {
+        lines.push("  The generated fields carry no paths, flag values, or error messages.", "  YOUR NOTE IS SENT EXACTLY AS WRITTEN — check it for paths, URLs,", "  tokens, or customer names before sending.");
+    }
+    else {
+        lines.push("  No paths, no flag values, no error messages, and nothing about which", "  project this was.");
+    }
+    lines.push("  Your journal stays on this machine.");
+    return lines;
+}
+export class DXSendError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "DXSendError";
+    }
+}
+/**
+ * POST the report. The caller has already shown the payload and had it accepted.
+ */
+export async function postReport(apiUrl, pat, report, fetchImpl = fetch) {
+    const res = await fetchImpl(`${apiUrl}/dx-reports`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${pat}` },
+        body: JSON.stringify(report),
+    });
+    if (!res.ok) {
+        let detail = "";
+        try {
+            const body = (await res.json());
+            detail = body.message ?? "";
+        }
+        catch {
+            // A non-JSON body is not more informative than the status.
+        }
+        if (res.status === 401) {
+            throw new DXSendError("Your access token is no longer valid — run `vincentt login`.", 401);
+        }
+        // A 400 here means the payload this CLI built failed the server's own
+        // grammar. Surfaced verbatim rather than softened: it is a bug in this CLI,
+        // and the creator is the one who can report it.
+        throw new DXSendError(detail !== "" ? detail : `The report was not accepted (${res.status}).`, res.status);
+    }
+    return (await res.json());
+}

package/dist/dx/skeleton.js

@@ -10,6 +10,83 @@
  */
 import { BOOLEAN_FLAGS } from "../cli/args.js";
 const ELIDED = "<v>";
+/**
+ * The verbs this CLI dispatches. A first bare token that is not one of these is
+ * not a verb — it is whatever the caller typed, and it must not be kept.
+ *
+ * Keeping it verbatim was a leak: an agent that mistypes
+ * `vincentt publish-acme-demo-to-prod`, fails, and retries builds a top-ranked
+ * friction cluster, so a customer's name ended up at the head of both the
+ * on-disk journal and any report built from it. Lowercase kebab-case is exactly
+ * what slugs and project names are made of, so no character-class check catches
+ * this — only a list of the verbs that actually exist.
+ */
+const KNOWN_VERBS = new Set([
+    "create",
+    "dx",
+    "feedback",
+    "init",
+    "link",
+    "login",
+    "logout",
+    "logs",
+    "network",
+    "preview",
+    "publish",
+    "relay",
+    "trace",
+    "unlink",
+    "version",
+    "whoami",
+    "help",
+]);
+/** Flags the CLI defines. An unknown `--flag` name is caller text, not signal. */
+const KNOWN_FLAGS = new Set([
+    "--allow-custom-api",
+    "--api",
+    "--console",
+    "--days",
+    "--dir",
+    "--dist",
+    "--editor",
+    "--errors",
+    "--force",
+    "--help",
+    "--json",
+    "--limit",
+    "--name",
+    "--no-install",
+    "--no-qr",
+    "--note",
+    "--org",
+    "--port",
+    "--preview",
+    "--restart",
+    "--send",
+    "--session",
+    "--since",
+    "--slug",
+    "--stop",
+    "--template",
+    "--tester",
+    "--timeout",
+    "--verbose",
+    "--version",
+    "--viewer",
+    "--wait",
+    "--watch",
+    "--yes",
+]);
+/**
+ * Placeholders for tokens the CLI does not recognize. Angle brackets cannot
+ * appear in a token the caller typed, so a caller cannot forge one.
+ *
+ * A mistyped verb still produces a finding — it clusters under `<verb>`, which
+ * is itself worth seeing (repeated unknown verbs mean an agent is guessing at a
+ * command that should exist).
+ */
+const UNKNOWN_VERB = "<verb>";
+const UNKNOWN_FLAG = "--<flag>";
 /**
  * Normalize an argv into `verb --flag=<v> <v>` form — the key a retry cluster
  * groups on. Two calls that differ only in their values share a skeleton, which
@@ -20,12 +97,18 @@ export function skeleton(args) {
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
         if (!a.startsWith("-")) {
-            // The verb is the first bare token and is kept verbatim; every later
-            // positional is a value (a slug, an id, a path) and is elided.
-            out.push(out.length === 0 ? a : ELIDED);
+            // The first bare token is the verb — kept only when it is one we actually
+            // dispatch. Every later positional is a value (a slug, an id, a path).
+            if (out.length === 0) {
+                out.push(KNOWN_VERBS.has(a) ? a : UNKNOWN_VERB);
+            }
+            else {
+                out.push(ELIDED);
+            }
             continue;
         }
-        const name = a.split("=")[0];
+        const rawName = a.split("=")[0];
+        const name = KNOWN_FLAGS.has(rawName) ? rawName : UNKNOWN_FLAG;
         if (BOOLEAN_FLAGS.has(a)) {
             out.push(name);
             continue;
@@ -47,7 +130,7 @@ export function verbOf(args) {
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
         if (!a.startsWith("-"))
-            return a;
+            return KNOWN_VERBS.has(a) ? a : UNKNOWN_VERB;
         if (!BOOLEAN_FLAGS.has(a) && !a.includes("="))
             i++;
     }