@vincentt-xr/cli 0.5.1 → 0.7.0

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/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/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.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,138 @@
+/**
+ * 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>";
+/**
+ * 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
+ * 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 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 rawName = a.split("=")[0];
+        const name = KNOWN_FLAGS.has(rawName) ? rawName : UNKNOWN_FLAG;
+        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 KNOWN_VERBS.has(a) ? a : UNKNOWN_VERB;
+        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.