@vincentt-xr/cli 0.5.0 → 0.6.0

package/dist/cli/args.d.ts

@@ -13,6 +13,8 @@ export declare function isHelpInvocation(args: string[]): boolean;
  * skip a publish the creator asked for. Anywhere else it stays an unknown flag.
  */
 export declare function isVersionInvocation(args: string[]): boolean;
+/** Flags that stand alone; every other `--flag` consumes the next argument. */
+export declare const BOOLEAN_FLAGS: Set<string>;
 export declare function refusedFlag(args: string[]): string | undefined;
 /**
  * The bare arguments, with flag VALUES removed. Without this, `vincentt link --dir

package/dist/cli/args.js

@@ -18,7 +18,7 @@ export function isVersionInvocation(args) {
     return args[0] === "--version" || args[0] === "-v";
 }
 /** Flags that stand alone; every other `--flag` consumes the next argument. */
-const BOOLEAN_FLAGS = new Set([
+export const BOOLEAN_FLAGS = new Set([
     "--force",
     "--preview",
     "--json",
@@ -26,6 +26,9 @@ const BOOLEAN_FLAGS = new Set([
     "--wait",
     "--watch",
     "--stop",
+    "--restart",
+    "--no-qr",
+    "--verbose",
     "--no-install",
     "--allow-custom-api",
     "--yes",

package/dist/cli/index.js

@@ -31,14 +31,18 @@ import { consoleVerbCommand, isConsoleOnlyVerb } from "../publish/consoleVerbs.j
 import { PreviewUi } from "../preview/command.js";
 import { httpRelayClient } from "../lib/diagnostics.js";
 import { readLivePreview } from "../lib/relayInfo.js";
-import { mintRateLimited, notSignedIn, previewConflict, startBlock, } from "../preview/copy.js";
+import { attachedToRunning, mintRateLimited, notSignedIn, previewConflict, startBlock, } from "../preview/copy.js";
 import { renderTerminalQr, shouldRenderQr } from "../preview/qr.js";
 import { PreviewConflictError, PreviewRateLimitedError } from "../preview/api.js";
 import { fetchNext, readCursor, writeCursor } from "../lib/feedback.js";
+import { record as recordInvocation } from "../dx/journal.js";
+import { runDx } from "../dx/command.js";
 import { isHelpInvocation, isVersionInvocation, positionalArgs, refusedFlag, } from "./args.js";
 // The console origin serves /cli-auth (the browser target for `vincentt login`). VINCENTT_
 // CONSOLE_URL overrides for dev/dogfood; VINCENTT_EDITOR_URL is honored as a legacy alias.
-const DEFAULT_CONSOLE_URL = "https://vincentt.app";
+// This is the prod console; vincentt.app is the published-PROJECT apex, not the console, so a
+// first-run `vincentt login` (no machine config yet) must default here or it opens a dead page.
+const DEFAULT_CONSOLE_URL = "https://console.vincentt.studio";
 const DEFAULT_API_URL = "https://api.vincentt.studio";
 // ---- arg helpers ------------------------------------------------------------
 const argv = process.argv.slice(2);
@@ -303,8 +307,23 @@ async function preview() {
     // treated as absent, which lands on the mint the creator actually asked for.
     const existing = await readLivePreview(cwd);
     if (existing !== undefined) {
-        await followPreview(existing, ui, filterTester, filterViewer);
-        return;
+        if (has("--restart")) {
+            // Asked for explicitly, so the old session is ended before the mint —
+            // otherwise the server's supersede rule would race the new one.
+            await previewStopSignal(cwd);
+        }
+        else if (filterTester === undefined && filterViewer === undefined) {
+            // No filter means the caller wanted the preview, not a diagnostics stream:
+            // hand them the link and exit rather than blocking in the follow loop.
+            // Following a live preview is what `vincentt logs`/`network`/`trace` are.
+            for (const l of attachedToRunning(existing.url, existing.expiresAt))
+                console.log(l);
+            return;
+        }
+        else {
+            await followPreview(existing, ui, filterTester, filterViewer);
+            return;
+        }
     }
     let ending = null;
     let resolveDone;
@@ -400,6 +419,10 @@ async function preview() {
  */
 async function followPreview(info, ui, filterTester, filterViewer) {
     console.log("→ Attaching to the preview running in this folder");
+    // The link, on its own line: a caller who is following a tester still needs to
+    // know which preview they landed on, and re-running to find out is the loop
+    // this printing exists to break.
+    console.log(info.url);
     const following = filterTester ?? filterViewer;
     if (following !== undefined) {
         console.log(`✓ Following ${following}`);
@@ -591,7 +614,8 @@ function usage() {
         `  publish            Upload the built dist; go live at <slug>.vincentt.app\n` +
         `                       [--dist <path>] [--note <s>] [--yes]\n` +
         `  preview            Serve the app at an https link a phone can open\n` +
-        `                       [--port <n>] [--tester <id>] [--no-qr] [--stop]\n\n` +
+        `                       [--port <n>] [--tester <id>] [--no-qr] [--stop]\n` +
+        `                       Re-running prints the live link; --restart mints a new one.\n\n` +
         `Diagnostics (need a running preview)\n` +
         `  logs [--errors]    Console logs from the device    [--json] [--tester <id>]\n` +
         `  network            fetch/XHR requests              [--json] [--tester <id>]\n` +
@@ -605,7 +629,9 @@ function usage() {
         `Servers\n` +
         `  relay              Run the diagnostics/annotation relay\n\n` +
         `Meta\n` +
-        `  version            CLI version, and the API this machine resolves to\n\n` +
+        `  version            CLI version, and the API this machine resolves to\n` +
+        `  dx                 Where this dev loop fought you  [--days <n>] [--json]\n` +
+        `                       Reads a local journal of your own runs. Never sent.\n\n` +
         `Common options: --dir <path> (project dir, default cwd)\n` +
         `                --allow-custom-api  honor a binding's apiUrl override\n`);
 }
@@ -653,6 +679,9 @@ async function main() {
             return feedback();
         case "relay":
             return relay();
+        case "dx":
+            process.exitCode = runDx(argv, (l) => console.log(l));
+            return;
         default:
             // Flow L30: rolling back and taking an address offline are console
             // actions, and a bare "unknown command" here would be the product failing
@@ -664,7 +693,30 @@ async function main() {
             process.exitCode = 1;
     }
 }
-main().catch((err) => {
+// Every invocation is journaled here, at the one site that sees all of them —
+// the verbs, both pre-switch gates, the console-only fallback and the unknown
+// command. Recording is best-effort and local-only (see dx/journal.ts); it never
+// changes what the CLI does or what it exits with.
+const startedAt = Date.now();
+function journal(exitCode, error) {
+    recordInvocation({
+        argv,
+        cliVersion: cliVersion(),
+        cwd: process.cwd(),
+        startedAt,
+        endedAt: Date.now(),
+        exitCode,
+        error,
+    });
+}
+main()
+    .then(() => {
+    // Verbs report failure by assigning process.exitCode and returning, so the
+    // resolved path is not necessarily the successful one.
+    journal(Number(process.exitCode ?? 0));
+})
+    .catch((err) => {
     console.error(`\n✗ ${err instanceof Error ? err.message : String(err)}`);
+    journal(1, err);
     process.exit(1);
 });

package/dist/dx/clusters.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Friction detection over journal entries.
+ *
+ * Two cluster types, because the two halves of "DX" fail differently:
+ *
+ *  - `error` — the caller fought the tool and it pushed back. This is the
+ *    classic retry loop (guessed a flag, got an error, tried again).
+ *  - `repetition` — the caller ran the same thing repeatedly and it WORKED
+ *    every time. No error is ever raised, so an error-keyed detector is blind
+ *    to it, yet it is friction: the caller didn't know the first run had
+ *    already given them what they needed. The reported case that motivated
+ *    this file was exactly that shape — repeated `preview` runs, each one
+ *    succeeding, each one minting a fresh link.
+ *
+ * Detection is deliberately loose. A false positive costs a line in a report a
+ * human is already reading; a miss costs a DX gap nobody ever hears about.
+ */
+import type { JournalEntry } from "./journal.js";
+export type ClusterKind = "error" | "repetition";
+export interface Cluster {
+    kind: ClusterKind;
+    skeleton: string;
+    entries: JournalEntry[];
+    /** Wall time from the first to the last call in the run, in ms. */
+    spanMs: number;
+    errors: number;
+    /** True when the run ended on a success — the caller got there eventually. */
+    recovered: boolean;
+}
+/**
+ * Group consecutive same-skeleton entries and keep the runs that look like
+ * friction. Entries are expected in chronological order.
+ */
+export declare function findClusters(entries: JournalEntry[]): Cluster[];
+/**
+ * Rank by cost × recurrence: a cluster's cost is the calls it wasted, and a
+ * skeleton seen across several clusters is a recurring gap rather than a bad
+ * afternoon. Error clusters outrank repetition ones at equal weight — the
+ * caller was actively blocked rather than merely inefficient.
+ */
+export declare function rankClusters(clusters: Cluster[]): Cluster[];

package/dist/dx/clusters.js

@@ -0,0 +1,71 @@
+/** A repetition run must be at least this long to count as friction. */
+const REPETITION_MIN = 3;
+/**
+ * How close together repeated calls must sit to read as one struggle. Three
+ * `preview` runs across a working day are three sessions; three inside ten
+ * minutes are one caller not getting what they needed.
+ */
+const REPETITION_WINDOW_MS = 10 * 60 * 1000;
+function span(run) {
+    const first = Date.parse(run[0].ts);
+    const last = Date.parse(run[run.length - 1].ts);
+    return Number.isFinite(first) && Number.isFinite(last) ? last - first : 0;
+}
+/**
+ * Group consecutive same-skeleton entries and keep the runs that look like
+ * friction. Entries are expected in chronological order.
+ */
+export function findClusters(entries) {
+    const clusters = [];
+    for (let i = 0; i < entries.length;) {
+        const skel = entries[i].skel;
+        const run = [];
+        let j = i;
+        while (j < entries.length && entries[j].skel === skel)
+            run.push(entries[j++]);
+        const errors = run.filter((e) => e.exit !== 0).length;
+        const spanMs = span(run);
+        // A cluster needs at least two calls. A lone failure is usually the tool
+        // working — a signed-out `whoami`, a typo'd verb — and reporting each one
+        // buries the real findings under noise, which is the failure mode that
+        // trains a reader to skim past the report entirely.
+        if (errors > 0 && run.length >= 2) {
+            clusters.push({
+                kind: "error",
+                skeleton: skel,
+                entries: run,
+                spanMs,
+                errors,
+                recovered: run[run.length - 1].exit === 0,
+            });
+        }
+        else if (errors === 0 &&
+            run.length >= REPETITION_MIN &&
+            spanMs <= REPETITION_WINDOW_MS) {
+            clusters.push({
+                kind: "repetition",
+                skeleton: skel,
+                entries: run,
+                spanMs,
+                errors: 0,
+                recovered: true,
+            });
+        }
+        i = j;
+    }
+    return clusters;
+}
+/**
+ * Rank by cost × recurrence: a cluster's cost is the calls it wasted, and a
+ * skeleton seen across several clusters is a recurring gap rather than a bad
+ * afternoon. Error clusters outrank repetition ones at equal weight — the
+ * caller was actively blocked rather than merely inefficient.
+ */
+export function rankClusters(clusters) {
+    const recurrence = new Map();
+    for (const c of clusters) {
+        recurrence.set(c.skeleton, (recurrence.get(c.skeleton) ?? 0) + 1);
+    }
+    const weight = (c) => c.entries.length * (recurrence.get(c.skeleton) ?? 1) * (c.kind === "error" ? 2 : 1);
+    return [...clusters].sort((a, b) => weight(b) - weight(a));
+}

package/dist/dx/command.d.ts

@@ -0,0 +1,17 @@
+import type { JournalEntry } from "./journal.js";
+export interface DxDeps {
+    entries: () => JournalEntry[];
+    print: (line: string) => void;
+    now: () => number;
+    enabled: () => boolean;
+    path: () => string;
+}
+export interface DxOptions {
+    /** Only consider runs from the last N days. */
+    days: number;
+    json: boolean;
+}
+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): number;

package/dist/dx/command.js

@@ -0,0 +1,95 @@
+import { findClusters, rankClusters } from "./clusters.js";
+import { journalEnabled, journalPath, readJournal } from "./journal.js";
+const DEFAULT_DAYS = 7;
+export function parseDxOptions(args) {
+    const i = args.indexOf("--days");
+    const raw = i !== -1 ? Number(args[i + 1]) : NaN;
+    return {
+        days: Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_DAYS,
+        json: args.includes("--json"),
+    };
+}
+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 seconds(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    return `${Math.round(s / 60)}m`;
+}
+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)}`;
+    const why = c.kind === "error"
+        ? c.recovered
+            ? "  The caller got there in the end. What did the first failure not tell them?"
+            : "  The caller retried, then gave up. This one blocked real work."
+        : "  Repeated with no error: the caller did not get what they needed the first time.";
+    const errs = [
+        ...new Set(c.entries.map((e) => e.err).filter((e) => e !== null)),
+    ];
+    const lines = [`• ${head}`, why];
+    if (errs.length > 0)
+        lines.push(`  Errors: ${errs.join(", ")}`);
+    return lines;
+}
+export function dxCommand(deps, options) {
+    if (!deps.enabled()) {
+        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.");
+        deps.print(`  ${deps.path()}`);
+        return 0;
+    }
+    const entries = withinDays(all, options.days, deps.now());
+    const clusters = rankClusters(findClusters(entries));
+    if (options.json) {
+        deps.print(JSON.stringify({ window: `${options.days}d`, runs: entries.length, clusters }, null, 2));
+        return 0;
+    }
+    deps.print(`${entries.length} runs in the last ${options.days} days.`);
+    deps.print("");
+    if (clusters.length === 0) {
+        // A clean window is a real result. Manufacturing a finding to fill the
+        // report is how a signal becomes noise.
+        deps.print("No friction detected.");
+    }
+    else {
+        deps.print(`${clusters.length} friction ${clusters.length === 1 ? "point" : "points"}, worst first:`);
+        deps.print("");
+        for (const c of clusters) {
+            for (const l of describe(c))
+                deps.print(l);
+            deps.print("");
+        }
+        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
+    // stays put is the claim that lets this run without asking permission first,
+    // and a claim only made on some runs is one a reader cannot rely on.
+    deps.print("");
+    deps.print(`Journal: ${deps.path()} (local only, never sent)`);
+    return 0;
+}
+/** Wire the command to the real journal. */
+export function runDx(args, print) {
+    return dxCommand({
+        entries: readJournal,
+        print,
+        now: () => Date.now(),
+        enabled: () => journalEnabled(),
+        path: journalPath,
+    }, parseDxOptions(args));
+}

package/dist/dx/journal.d.ts

@@ -0,0 +1,51 @@
+export interface JournalEntry {
+    /** ISO8601 UTC, invocation start. */
+    ts: string;
+    /** CLI version, so a finding can be dropped once the fix ships. */
+    v: string;
+    verb: string;
+    /** Flag names with values elided — the retry-cluster key. */
+    skel: string;
+    exit: number;
+    ms: number;
+    /** Error CLASS (`err.name`), never a message — messages carry user data. */
+    err: string | null;
+    /** Hash of the working tree, so runs group by project without recording where it is. */
+    wt: string;
+}
+/**
+ * Beside the machine config, so the journal shares the home the PAT already
+ * lives in — and so a run made outside any project (`login`, `version`) is still
+ * recorded, which a per-project file could not do.
+ *
+ * Resolved per call rather than captured at module load: the home directory is
+ * the seam tests move, and a frozen path would silently write to the real one.
+ */
+export declare function journalPath(): string;
+/** `VINCENTT_DX_JOURNAL=0` turns recording off. A local file still needs an off switch. */
+export declare function journalEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * A stable, non-reversible handle for "the folder this run happened in". Enough
+ * to group runs by project — which is what makes the one-session-per-tree
+ * friction visible — without recording anyone's directory layout.
+ */
+export declare function workingTreeId(cwd: string): string;
+export interface RecordInput {
+    argv: string[];
+    cliVersion: string;
+    cwd: string;
+    startedAt: number;
+    endedAt: number;
+    exitCode: number;
+    error?: unknown;
+}
+export declare function buildEntry(input: RecordInput): JournalEntry;
+/**
+ * Append one entry. Never throws: a journal that can break a publish is a
+ * liability, and every failure mode here (read-only home, full disk, a
+ * concurrent writer) is one the creator would rather have silently ignored than
+ * turned into a failed command.
+ */
+export declare function record(input: RecordInput): void;
+/** Read the journal oldest-first. Malformed lines are skipped, not fatal. */
+export declare function readJournal(): JournalEntry[];

package/dist/dx/journal.js

@@ -0,0 +1,129 @@
+/**
+ * The DX journal — one line per `vincentt` invocation, on the creator's own
+ * machine, never transmitted.
+ *
+ * This is instrumentation without transmission. The file is the creator's, the
+ * way a shell history is: they can read it, delete it, or turn it off. Nothing
+ * here contacts the network, and nothing outside this module may make it. That
+ * property is what keeps the journal clear of the diagnostics-retention rule
+ * (B19) — there is no platform side to it.
+ *
+ * What it records is deliberately narrow: the SHAPE of a run (verb, flag names,
+ * exit code, duration), never its CONTENT (no flag values, no paths, no error
+ * messages, no output). A slug, a project id, or a token typed on a command
+ * line must never reach this file — see `skeleton()`.
+ *
+ * Writes are best-effort and synchronous. Best-effort because instrumentation
+ * that breaks the tool it measures is worse than no instrumentation; synchronous
+ * because the CLI's top-level handler calls `process.exit(1)`, which abandons a
+ * pending async write.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { skeleton, verbOf } from "./skeleton.js";
+const JOURNAL_FILE = "dx.ndjson";
+/** Keep the journal bounded: a rolling window, trimmed on write. */
+const MAX_ENTRIES = 2000;
+/**
+ * Beside the machine config, so the journal shares the home the PAT already
+ * lives in — and so a run made outside any project (`login`, `version`) is still
+ * recorded, which a per-project file could not do.
+ *
+ * Resolved per call rather than captured at module load: the home directory is
+ * the seam tests move, and a frozen path would silently write to the real one.
+ */
+export function journalPath() {
+    return path.join(os.homedir(), ".vincentt", JOURNAL_FILE);
+}
+/** `VINCENTT_DX_JOURNAL=0` turns recording off. A local file still needs an off switch. */
+export function journalEnabled(env = process.env) {
+    return env.VINCENTT_DX_JOURNAL !== "0";
+}
+/**
+ * A stable, non-reversible handle for "the folder this run happened in". Enough
+ * to group runs by project — which is what makes the one-session-per-tree
+ * friction visible — without recording anyone's directory layout.
+ */
+export function workingTreeId(cwd) {
+    return createHash("sha256").update(path.resolve(cwd)).digest("hex").slice(0, 12);
+}
+function classify(err) {
+    if (err === undefined || err === null)
+        return null;
+    return err instanceof Error ? err.name : "unknown";
+}
+/**
+ * Trim to the newest MAX_ENTRIES. Reads the whole file, which is fine at this
+ * bound (a few hundred KB at worst) and keeps the writer a single atomic
+ * rewrite rather than a partial in-place edit.
+ */
+function trim(file) {
+    const lines = fs
+        .readFileSync(file, "utf8")
+        .split("\n")
+        .filter((l) => l.trim() !== "");
+    if (lines.length <= MAX_ENTRIES)
+        return;
+    fs.writeFileSync(file, lines.slice(-MAX_ENTRIES).join("\n") + "\n", "utf8");
+}
+export function buildEntry(input) {
+    return {
+        ts: new Date(input.startedAt).toISOString(),
+        v: input.cliVersion,
+        verb: verbOf(input.argv),
+        skel: skeleton(input.argv),
+        exit: input.exitCode,
+        ms: Math.max(0, input.endedAt - input.startedAt),
+        err: classify(input.error),
+        wt: workingTreeId(input.cwd),
+    };
+}
+/**
+ * Append one entry. Never throws: a journal that can break a publish is a
+ * liability, and every failure mode here (read-only home, full disk, a
+ * concurrent writer) is one the creator would rather have silently ignored than
+ * turned into a failed command.
+ */
+export function record(input) {
+    if (!journalEnabled())
+        return;
+    try {
+        const file = journalPath();
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        fs.appendFileSync(file, JSON.stringify(buildEntry(input)) + "\n", {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        // `mode` on appendFile only applies when it CREATES the file, so a journal
+        // that predates this (or a looser umask) would keep its old perms.
+        fs.chmodSync(file, 0o600);
+        trim(file);
+    }
+    catch {
+        // Instrumentation must not break the tool it measures.
+    }
+}
+/** Read the journal oldest-first. Malformed lines are skipped, not fatal. */
+export function readJournal() {
+    let raw;
+    try {
+        raw = fs.readFileSync(journalPath(), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // A torn line from a killed process is not a reason to lose the rest.
+        }
+    }
+    return out;
+}

package/dist/dx/skeleton.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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
+ * is what makes "the caller ran the same thing four times" detectable.
+ */
+export declare function skeleton(args: string[]): string;
+/**
+ * The dispatched verb — the first bare token, skipping flags AND the values they
+ * consume. `vincentt --dir /tmp publish` runs publish, not `/tmp`; recording the
+ * path as the verb would both mis-bucket the run and leak the directory.
+ */
+export declare function verbOf(args: string[]): string;

package/dist/dx/skeleton.js

@@ -0,0 +1,55 @@
+/**
+ * The journal's privacy boundary lives here: a skeleton keeps flag NAMES (which
+ * carry the DX signal — a caller guessing `--name` when the flag is `--slug` is
+ * exactly the friction worth finding) and discards every VALUE (which carries
+ * the risk — slugs, paths, ids, anything typed on a command line).
+ *
+ * Value elision is not cosmetic. It is what lets `vincentt dx --send` ship a
+ * finding without a scrubbing pass, and what keeps the on-disk journal a
+ * shell-history-class artifact rather than a record of the creator's work.
+ */
+import { BOOLEAN_FLAGS } from "../cli/args.js";
+const ELIDED = "<v>";
+/**
+ * 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
+ * is what makes "the caller ran the same thing four times" detectable.
+ */
+export function skeleton(args) {
+    const out = [];
+    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);
+            continue;
+        }
+        const name = a.split("=")[0];
+        if (BOOLEAN_FLAGS.has(a)) {
+            out.push(name);
+            continue;
+        }
+        // `--flag=value` carries its value inline; `--flag value` consumes the next
+        // argv entry. Both collapse to the same skeleton so they cluster together.
+        out.push(`${name}=${ELIDED}`);
+        if (!a.includes("="))
+            i++;
+    }
+    return out.join(" ");
+}
+/**
+ * The dispatched verb — the first bare token, skipping flags AND the values they
+ * consume. `vincentt --dir /tmp publish` runs publish, not `/tmp`; recording the
+ * path as the verb would both mis-bucket the run and leak the directory.
+ */
+export function verbOf(args) {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!a.startsWith("-"))
+            return a;
+        if (!BOOLEAN_FLAGS.has(a) && !a.includes("="))
+            i++;
+    }
+    return "";
+}

package/dist/lib/feedback.js

@@ -5,15 +5,24 @@
 // before that re-delivers on the next call.
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { readRelayInfo } from "./relayInfo.js";
+import { readRelayInfo, relayInfoDir } from "./relayInfo.js";
 const CURSOR_FILE = ".vincentt/annotations/offset";
 export function cursorPath(cwd) {
     return path.join(cwd, CURSOR_FILE);
 }
+/**
+ * The cursor belongs to the tree, beside the annotations the relay writes. A
+ * cursor anchored on the raw cwd would restart at 0 when `vincentt feedback` is
+ * run from a different folder of the same project, re-delivering every
+ * annotation already handed off.
+ */
+async function treeCursorPath(cwd) {
+    return cursorPath(await relayInfoDir(cwd));
+}
 /** Last-consumed annotation seq for this project (0 if none consumed yet). */
 export async function readCursor(cwd) {
     try {
-        const raw = await fs.readFile(cursorPath(cwd), "utf8");
+        const raw = await fs.readFile(await treeCursorPath(cwd), "utf8");
         return Number(raw.trim()) || 0;
     }
     catch (err) {
@@ -24,7 +33,7 @@ export async function readCursor(cwd) {
 }
 /** Advance the cursor. Called ONLY after the annotation was handed off. */
 export async function writeCursor(cwd, seq) {
-    const p = cursorPath(cwd);
+    const p = await treeCursorPath(cwd);
     await fs.mkdir(path.dirname(p), { recursive: true });
     await fs.writeFile(p, `${seq}\n`, "utf8");
 }

package/dist/lib/lifecycle.js

@@ -129,19 +129,24 @@ export async function previewStart(projectCwd, onLog, extra = {}) {
     const preview = await startPreview({
         ...extra,
         projectCwd,
+        projectRoot: located.dir,
         config,
         projectId: located.binding.projectId,
         onLog,
     });
     activePreview = preview;
-    activeProjectCwd = projectCwd;
+    // The marker is the tree's, not the folder's: `readLivePreview` resolves the
+    // binding the same way, so a preview started in a subdirectory is still found
+    // from the repo root instead of minting a second live session for one tree.
+    activeProjectCwd = located.dir;
     // Record the OS-assigned relay port so a separate `vincentt logs`/`feedback`
     // invocation can find this preview's relay.
-    await writeRelayInfo(projectCwd, {
+    await writeRelayInfo(located.dir, {
         relayPort: preview.relayPort,
         url: preview.url,
         pid: process.pid,
         harnessPath: "/__harness",
+        expiresAt: preview.expiresAt,
     });
     return { preview, started: true };
 }

package/dist/lib/relayInfo.d.ts

@@ -7,9 +7,32 @@ export interface RelayInfo {
     pid: number;
     /** WS/HTTP path prefix routed to the relay (default /__harness). */
     harnessPath: string;
+    /**
+     * When the session's hard maximum lifetime expires, ISO8601.
+     *
+     * A live marker proves the LOCAL relay is up; it does not prove the tunnel
+     * URL still resolves — a session can be superseded from another machine or
+     * hit its hard max while this process sits idle. Carrying the expiry lets a
+     * re-run say "this link is still good until X" instead of printing a URL it
+     * only assumes is live. Optional: markers written by an older CLI lack it.
+     */
+    expiresAt?: string;
 }
 export declare function relayInfoPath(cwd: string): string;
+/**
+ * The directory a marker for this tree lives in: the binding's directory when
+ * there is one, else the cwd unchanged.
+ *
+ * A preview is one per WORKING TREE, and a binding is found by walking up from
+ * the cwd — so `apps/web/` and the repo root are the same tree and must find the
+ * same marker. Anchoring on the raw cwd instead made them two, and a second
+ * `vincentt preview` from the repo root minted a second live session for a
+ * project that already had one (the server could not supersede it either: its
+ * tree key is derived from the same path).
+ */
+export declare function relayInfoDir(cwd: string): Promise<string>;
 export declare function writeRelayInfo(cwd: string, info: RelayInfo): Promise<string>;
+/** Reads the marker for the TREE containing cwd, not only the folder itself. */
 export declare function readRelayInfo(cwd: string): Promise<RelayInfo | undefined>;
 export declare function clearRelayInfo(cwd: string): Promise<void>;
 /**

package/dist/lib/relayInfo.js

@@ -4,20 +4,38 @@
 // the gitignored .vincentt/ dir, so it never rides a commit.
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { locateProjectBinding } from "../shared/config.js";
 const RELAY_INFO_FILE = "relay.json";
 const VINCENTT_DIR = ".vincentt";
 export function relayInfoPath(cwd) {
     return path.join(cwd, VINCENTT_DIR, RELAY_INFO_FILE);
 }
+/**
+ * The directory a marker for this tree lives in: the binding's directory when
+ * there is one, else the cwd unchanged.
+ *
+ * A preview is one per WORKING TREE, and a binding is found by walking up from
+ * the cwd — so `apps/web/` and the repo root are the same tree and must find the
+ * same marker. Anchoring on the raw cwd instead made them two, and a second
+ * `vincentt preview` from the repo root minted a second live session for a
+ * project that already had one (the server could not supersede it either: its
+ * tree key is derived from the same path).
+ */
+export async function relayInfoDir(cwd) {
+    const located = await locateProjectBinding(cwd);
+    return located?.dir ?? cwd;
+}
 export async function writeRelayInfo(cwd, info) {
     const p = relayInfoPath(cwd);
     await fs.mkdir(path.dirname(p), { recursive: true });
     await fs.writeFile(p, JSON.stringify(info, null, 2) + "\n", "utf8");
     return p;
 }
+/** Reads the marker for the TREE containing cwd, not only the folder itself. */
 export async function readRelayInfo(cwd) {
     try {
-        return JSON.parse(await fs.readFile(relayInfoPath(cwd), "utf8"));
+        const dir = await relayInfoDir(cwd);
+        return JSON.parse(await fs.readFile(relayInfoPath(dir), "utf8"));
     }
     catch (err) {
         if (err.code === "ENOENT")
@@ -27,7 +45,7 @@ export async function readRelayInfo(cwd) {
 }
 export async function clearRelayInfo(cwd) {
     try {
-        await fs.unlink(relayInfoPath(cwd));
+        await fs.unlink(relayInfoPath(await relayInfoDir(cwd)));
     }
     catch {
         // Already gone — clearing a non-existent info file is a no-op.

package/dist/login/pkceLogin.js

@@ -95,7 +95,11 @@ export async function runPkceLogin(opts) {
     const backend = opts.backend ?? httpAuthBackend(opts.apiUrl);
     const pickPort = opts.pickPort ?? getFreePort;
     const openBrowser = opts.openBrowser ?? defaultOpenBrowser;
-    const saveToken = opts.saveToken ?? ((apiUrl, pat) => writeMachineConfig({ apiUrl, pat }));
+    // Persist consoleUrl alongside apiUrl + pat so a later `vincentt login` resolves the
+    // console origin from config instead of falling back to the DEFAULT_CONSOLE_URL — the
+    // resolution the very first login could not use because nothing was stored yet.
+    const saveToken = opts.saveToken ??
+        ((apiUrl, pat) => writeMachineConfig({ apiUrl, pat, consoleUrl: opts.consoleUrl }));
     const progress = opts.onProgress ?? (() => { });
     const material = makePkceMaterial();
     const port = await pickPort();

package/dist/preview/copy.d.ts

@@ -139,6 +139,18 @@ export declare function hardMaxWarning(clockTime: string, minutesLeft: number):
 export declare function hardMaxReached(): string[];
 /** c. Superseded — the terminal that LOST. */
 export declare function supersededLoser(): string[];
+/**
+ * Re-running `vincentt preview` on a folder that already has one attaches to it
+ * rather than minting a second — but a caller who is not SHOWN the link cannot
+ * tell the difference between "attached" and "failed to give me a URL". The
+ * reported behavior was an agent re-running preview until it saw a link, and
+ * each of those re-runs superseded the previous session: the link really did
+ * keep changing, because the attach never printed one.
+ *
+ * The URL renders bare on its own line, matching the start block, so anything
+ * scraping for a link finds it in the same shape either way.
+ */
+export declare function attachedToRunning(url: string, expiresAt?: string): string[];
 /**
  * c. Superseded — the terminal that WON. This sits ABOVE the `✓ Preview is live`
  * block so the consequence is read before the URL is copied.

package/dist/preview/copy.js

@@ -299,6 +299,28 @@ export function supersededLoser() {
         "",
     ];
 }
+/**
+ * Re-running `vincentt preview` on a folder that already has one attaches to it
+ * rather than minting a second — but a caller who is not SHOWN the link cannot
+ * tell the difference between "attached" and "failed to give me a URL". The
+ * reported behavior was an agent re-running preview until it saw a link, and
+ * each of those re-runs superseded the previous session: the link really did
+ * keep changing, because the attach never printed one.
+ *
+ * The URL renders bare on its own line, matching the start block, so anything
+ * scraping for a link finds it in the same shape either way.
+ */
+export function attachedToRunning(url, expiresAt) {
+    const lines = ["", "→ A preview is already running for this folder.", "", url, ""];
+    // Stated only when known: a marker written by an older CLI has no expiry, and
+    // inventing one would be the over-claim this copy exists to avoid.
+    if (expiresAt !== undefined) {
+        lines.push(`  This link is good until ${expiresAt}.`);
+    }
+    lines.push("  Start a fresh one:  vincentt preview --restart");
+    lines.push("");
+    return lines;
+}
 /**
  * c. Superseded — the terminal that WON. This sits ABOVE the `✓ Preview is live`
  * block so the consequence is read before the URL is copied.

package/dist/preview/runner.d.ts

@@ -33,6 +33,19 @@ export type PreviewEndReason = "stopped"
 export interface StartPreviewOptions {
     /** Project directory — its .vincentt binding + dev script drive the preview. */
     projectCwd: string;
+    /**
+     * The directory holding the binding — the tree's IDENTITY, as distinct from
+     * the directory the dev server runs in.
+     *
+     * These differ whenever a creator runs `vincentt preview` from a subdirectory
+     * of a bound repo: `locateProjectBinding` walks up to find the binding, so the
+     * same project resolves from `apps/web/` and from the repo root. Keying the
+     * one-session-per-tree rule off the raw cwd made those two spellings two
+     * trees, which is precisely what `workingTreeKey` normalizes symlinks and
+     * relative paths to prevent. Defaults to projectCwd when the caller has not
+     * located a binding.
+     */
+    projectRoot?: string;
     /** The API host + PAT. Resolved by the caller so the runner makes no policy. */
     config: ResolvedConfig;
     projectId: string;

package/dist/preview/runner.js

@@ -22,7 +22,7 @@ import { getFreePort, isPortListening, waitForApp } from "./net.js";
 import { endPreviewSession, heartbeatPreviewSession, mintPreviewSession, workingTreeKey, PreviewEndedError, } from "./api.js";
 import { ProjectUnreachableError } from "../lib/backend.js";
 export async function startPreview(opts) {
-    const { projectCwd, config, projectId, harnessPath = "/__harness", devCommand = ["npm", "run", "dev"], appStdio = "ignore", appReadyTimeoutMs = 8_000, onLog = () => undefined, fetchImpl = fetch, } = opts;
+    const { projectCwd, projectRoot = projectCwd, config, projectId, harnessPath = "/__harness", devCommand = ["npm", "run", "dev"], appStdio = "ignore", appReadyTimeoutMs = 8_000, onLog = () => undefined, fetchImpl = fetch, } = opts;
     const appPort = opts.appPort ?? 5173;
     const relayPort = opts.relayPort ?? (await getFreePort());
     const frontPort = opts.frontPort ?? (await getFreePort());
@@ -56,7 +56,9 @@ export async function startPreview(opts) {
         // The MINT comes first. Everything below it costs the creator a dev-server
         // start and a port; if the mint is going to fail — rate limit, revoked
         // membership, no binding — it should fail before any of that happens.
-        const key = await workingTreeKey(projectCwd);
+        // Keyed on the tree's identity, not the folder the command was typed in:
+        // the supersede rule must see one tree however the creator addressed it.
+        const key = await workingTreeKey(projectRoot);
         minted = await mintPreviewSession(config, projectId, key, fetchImpl);
         if (reuseApp) {
             onLog(`reusing the dev server already on :${appPort}`);
@@ -73,7 +75,10 @@ export async function startPreview(opts) {
         relay = startRelay({
             port: relayPort,
             path: harnessPath,
-            projectDir: projectCwd,
+            // Annotations land beside the binding, so `vincentt feedback` finds them
+            // from anywhere in the tree rather than only from the folder that started
+            // the preview.
+            projectDir: projectRoot,
             onLog: (m) => onLog(`[relay] ${m}`),
             onEvents: opts.onEvents,
             onAttribute: opts.onAttribute,

package/dist/publish/consoleVerbs.js

@@ -3,7 +3,7 @@
 //
 // This is ARGUMENT PARSING. Exit 1, no network call, nothing looked up.
 import { CONSOLE_ONLY_VERBS, consoleVerb } from "./copy.js";
-const DEFAULT_CONSOLE_URL = "https://console.vincentt.app";
+const DEFAULT_CONSOLE_URL = "https://console.vincentt.studio";
 export function isConsoleOnlyVerb(verb) {
     return CONSOLE_ONLY_VERBS.includes(verb);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",