@vincentt-xr/cli 0.18.2 → 0.19.0

package/MIGRATION.md

@@ -3,6 +3,28 @@
 Per version, newest first. Read by the platform's own version surface and served to
 creators' agents. Accurate or absent, never speculative (B-F5-2).
 
+## 0.19.0
+
+required: false
+No action required for a project made from the Vincentt template. Behaviour that changed:
+- The platform caps how many previews one person runs at once (5 by default, across every workspace; a preview that is still connecting counts, viewers never do). Re-running `vincentt preview` in a folder that already has a preview is never refused by the cap.
+- `vincentt preview` past the preview cap exits 1, starts nothing and stops nothing, and says how many previews are running and how to stop one: Ctrl-C where it runs, `vincentt preview --stop` in its folder, or Stop on its project's Preview tab in the console.
+- A preview refusal the CLI does not recognise prints the platform's own message instead of "A preview is already running for this folder."
+- `vincentt preview` with no `vincentt.json`, `--port` or `--dev-command` starts the project's `dev` script on a free port, passed to it as `PORT`, instead of 5173, and never reuses a server it finds already listening. Two previews at once, or another server already on 5173, no longer share one app. The settings banner shows the chosen port. A port from `--port` or `vincentt.json` is kept, and a server already listening there is still reused.
+- A preview answers 404 for any path segment shaped like a Windows short name (one to six characters, then `~` and a digit, such as `GIT~1` or `ENVLOC~1`), on every platform. On Windows these names open the dotted files the preview already hides. Bundler chunk names such as `vendors~main` are unaffected.
+- The preview tunnel client is part of the CLI itself instead of being loaded from `@vincentt-xr/harness`. The preview behaves the same, and it works with any harness version a project has installed.
+- A preview answers 404 for files and folders named like credentials, with no opt-out: `credentials.json`, `service-account*.json`, `*firebase-adminsdk*.json`, `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.p8`, `*.ppk`, `id_rsa*`, `id_dsa*`, `id_ed25519*`, `id_ecdsa*`, `*.jks`, `*.keystore`, `*.env`, `*.tfstate`, `*.tfvars`, and their `~` or `.bak` backups, in any letter case. An app asset with one of these names (for example a `.key` file) needs a new name to load in a preview.
+- A preview also refuses a Windows stream name, a name with trailing dots or spaces, and a query or fragment carrying a parent-folder step, a backslash or an encoded slash. The 404 advisory names the path decoded, without control or bidirectional-override characters, and now ends `A preview never serves hidden or credential files from your project.`
+- `vincentt login` and the report consent prompt open a browser only for an `https:` address, or an `http:` address on `localhost`, `127.0.0.1` or `[::1]`; anything else is printed but not opened. On Windows the browser opens through `rundll32` instead of `cmd`.
+
+## 0.18.3
+
+required: false
+No action required when the preview and the commands reading it (`logs`, `feedback`, `preview --stop`) come from the same CLI version. Behaviour that changed:
+- The local preview relay refuses web pages other than the preview itself. It answers only requests whose Host is `127.0.0.1:<port>` or `localhost:<port>`, accepts the diagnostics socket and feedback posts only from the preview's own address (or from a client that sends no Origin), and refuses a POST whose content type is not JSON with 415.
+- The relay's diagnostics read and feedback long-poll now require a per-session token, which the preview writes to the project's relay record (now readable by the owner only). The CLI's own commands send it; a direct diagnostics or feedback request without the `x-vincentt-relay-token` header is refused with 401. A command from CLI 0.18.2 or older cannot read a preview started by this version, and the reverse still works.
+- `vincentt relay` prints the token it requires and accepts `--origin <url>` for a page it should accept; without it, only pages served from localhost or 127.0.0.1 can connect.
+
 ## 0.18.2
 
 required: false

package/dist/cli/index.js

@@ -37,13 +37,14 @@ import { USAGE_TEXT } from "./usage-text.js";
 import { PreviewUi } from "../preview/command.js";
 import { httpRelayClient } from "../lib/diagnostics.js";
 import { readLivePreview, relayInfoDir } from "../lib/relayInfo.js";
-import { attachedToRunning, mintRateLimited, noDiagnosticsStatic, notSignedIn, previewConflict, settingsBanner, startBlock, } from "../preview/copy.js";
+import { attachedToRunning, mintRateLimited, noDiagnosticsStatic, notSignedIn, previewConflict, previewUserLimitRefused, settingsBanner, startBlock, } from "../preview/copy.js";
+import { chooseDevPort } from "../preview/devPort.js";
 import { isPortListening } from "../preview/net.js";
 import { readSettings, resolveSettings, SettingsError, TEMPLATE_DEFAULTS, validateField, } from "../lib/settings.js";
 import { settingsRefusal, sourceWords } from "../lib/settingsCopy.js";
 import { listsHarness } from "../lib/template.js";
 import { renderTerminalQr, shouldRenderQr } from "../preview/qr.js";
-import { PreviewConflictError, PreviewLimitError, PreviewRateLimitedError, } from "../preview/api.js";
+import { PreviewConflictError, PreviewLimitError, PreviewRateLimitedError, PreviewUserLimitError, } from "../preview/api.js";
 import { previewLimitRefused, resolveCountLimit, } from "../shared/countLimit.js";
 import { fetchNext, readCursor, writeCursor } from "../lib/feedback.js";
 import * as feedbackCopy from "../lib/feedbackCopy.js";
@@ -531,14 +532,16 @@ async function preview() {
         return;
     }
     const devCommand = settings.devCommand.value;
-    const devPort = settings.devPort.value;
+    const { port: devPort, fresh: devPortFresh } = await chooseDevPort(settings);
+    // What the creator gets running the dev command by hand, without PORT.
+    const handRunUrl = `http://localhost:${settings.devPort.value}`;
     const localUrl = `http://localhost:${devPort}`;
     for (const l of settingsBanner({
         devCommand,
         devCommandSource: sourceWords(settings.devCommand),
         devPort,
         devPortSource: sourceWords(settings.devPort),
-        reused: await isPortListening(devPort),
+        reused: devPortFresh ? false : await isPortListening(devPort),
     })) {
         console.log(l);
     }
@@ -549,7 +552,7 @@ async function preview() {
     // The gate is LOCAL and NOTHING IS ATTEMPTED: no spinner, no partial mint, no
     // session left in `pending`. The command stops before it touches the network.
     if (!(await currentToken())) {
-        for (const l of notSignedIn(devCommand, localUrl))
+        for (const l of notSignedIn(devCommand, handRunUrl))
             console.log(l);
         process.exitCode = EXIT.NOT_AUTHENTICATED;
         return;
@@ -607,6 +610,7 @@ async function preview() {
     try {
         const started = await previewStart(cwd, (m) => console.error(`[preview] ${m}`), {
             appPort: devPort,
+            appPortFresh: devPortFresh,
             devCommand,
             onHiddenPath: (p) => ui.hiddenPath(p),
             appStdio: has("--verbose") ? "inherit" : "ignore",
@@ -727,7 +731,7 @@ async function followPreview(info, ui, filterTester, filterViewer) {
         console.log("✓ Following this preview");
     }
     console.log("");
-    const relay = httpRelayClient(`http://127.0.0.1:${info.relayPort}`);
+    const relay = httpRelayClient(`http://127.0.0.1:${info.relayPort}`, info.token);
     let since = -1;
     let warnedMissing = false;
     let stop = false;
@@ -842,6 +846,8 @@ function previewFailureLines(err, local) {
     if (err instanceof PreviewLimitError) {
         return previewLimitRefused(resolveCountLimit(err.detail, local));
     }
+    if (err instanceof PreviewUserLimitError)
+        return previewUserLimitRefused(err.detail);
     if (err instanceof PreviewConflictError)
         return previewConflict();
     if (err instanceof ProjectUnreachableError) {
@@ -1357,13 +1363,19 @@ async function domain() {
 // ---- servers ----------------------------------------------------------------
 async function relay() {
     const { startRelay } = await import("../relay/server.js");
+    const { mintRelayToken, RELAY_TOKEN_HEADER } = await import("../relay/guard.js");
     const port = numFlag("--port") ?? 7331;
     const dir = flag("--dir");
+    const origin = flag("--origin");
+    const token = mintRelayToken();
     startRelay({
         port,
         projectDir: dir ? path.resolve(dir) : undefined,
+        allowedOrigins: origin ? [origin] : undefined,
+        token,
         onLog: (m) => console.log(`[relay] ${m}`),
     });
+    console.log(`[relay] /query and feedback/next require ${RELAY_TOKEN_HEADER}: ${token}`);
 }
 // ---- dispatch ---------------------------------------------------------------
 export function usage() {

package/dist/cli/usage-text.js

@@ -58,7 +58,7 @@ export const USAGE_TEXT = `Vincentt CLI: the local-first AR dev loop\n\n` +
     `                       [--port <n>] [--dev-command <cmd>] [--tester <id>]\n` +
     `                       [--no-qr] [--stop]\n` +
     `                       Runs dev.command and forwards dev.port from vincentt.json,\n` +
-    `                       else npm run dev on 5173.\n` +
+    `                       else npm run dev on a free port (passed as PORT).\n` +
     `                       Re-running prints the live link; --restart mints a new one.\n\n` +
     // f16. HELP TEACHES THE CANONICAL VERBS ONLY: `add` and `remove` are accepted
     // as silent aliases and are deliberately ABSENT here, because help, docs and

package/dist/lib/diagnostics.d.ts

@@ -1,9 +1,10 @@
 import type { DiagEvent, LogEvent, NetworkEvent, RelayQuery, RelayResult, TraceEvent } from "@vincentt-xr/harness/events";
+export declare function relayAuthHeaders(token: string | undefined): Record<string, string>;
 export interface RelayClient {
     query(q: RelayQuery): Promise<RelayResult>;
 }
 /** A RelayClient backed by the relay's HTTP /query endpoint. */
-export declare function httpRelayClient(baseUrl: string): RelayClient;
+export declare function httpRelayClient(baseUrl: string, token?: string): RelayClient;
 export declare function formatLog(e: LogEvent, now: number): string;
 export declare function formatNetwork(e: NetworkEvent, now: number): string;
 export declare function formatTrace(e: TraceEvent, now: number): string;

package/dist/lib/diagnostics.js

@@ -2,13 +2,17 @@
 // the relay and format them into the compact text an agent reads. Kept separate
 // from the SDK wiring (server.ts) so the formatting is unit-testable and the SDK
 // version can churn without touching this.
+import { RELAY_TOKEN_HEADER } from "../relay/guard.js";
+export function relayAuthHeaders(token) {
+    return token === undefined ? {} : { [RELAY_TOKEN_HEADER]: token };
+}
 /** A RelayClient backed by the relay's HTTP /query endpoint. */
-export function httpRelayClient(baseUrl) {
+export function httpRelayClient(baseUrl, token) {
     return {
         async query(q) {
             const res = await fetch(`${baseUrl}/query`, {
                 method: "POST",
-                headers: { "content-type": "application/json" },
+                headers: { "content-type": "application/json", ...relayAuthHeaders(token) },
                 body: JSON.stringify(q),
             });
             if (!res.ok)

package/dist/lib/feedback.js

@@ -11,6 +11,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { isProcessAlive, isRelayResponding, readRelayInfo, relayInfoDir, } from "./relayInfo.js";
+import { relayAuthHeaders } from "./diagnostics.js";
 const CURSOR_FILE = ".vincentt/annotations/offset";
 /**
  * A cursor that reads too LOW re-delivers, which is the accepted cost of
@@ -96,13 +97,13 @@ export async function fetchNext(cwd, opts) {
     u.searchParams.set("timeout", String(opts.timeoutMs));
     let res;
     try {
-        res = await fetch(u);
+        res = await fetch(u, { headers: relayAuthHeaders(info.token) });
     }
     catch {
         // The socket died under us. The pid gate + relay-identity probe is what
         // separates "the preview ended" from "the request failed but a relay is
         // still there" — only the latter is a fault worth an exit 1.
-        if (await relayGone(info.pid, info.relayPort)) {
+        if (await relayGone(info.pid, info.relayPort, info.token)) {
             return { kind: "closed", reason: "unreachable" };
         }
         throw new Error(`Could not reach the preview relay on :${info.relayPort}. The relay is answering, so this is not a session end.`);
@@ -117,8 +118,8 @@ export async function fetchNext(cwd, opts) {
         throw new Error(`relay feedback/next returned ${res.status}`);
     return { kind: "annotation", annotation: (await res.json()) };
 }
-async function relayGone(pid, port) {
+async function relayGone(pid, port, token) {
     if (pid !== undefined && !isProcessAlive(pid))
         return true;
-    return !(await isRelayResponding(port));
+    return !(await isRelayResponding(port, undefined, undefined, token));
 }

package/dist/lib/lifecycle.js

@@ -175,6 +175,7 @@ export async function previewStart(projectCwd, onLog, extra = {}) {
         harnessPath: "/__harness",
         expiresAt: preview.expiresAt,
         pidStartTime: await readProcessStartTime(process.pid),
+        token: preview.relayToken,
     });
     return { preview, started: true };
 }
@@ -286,7 +287,7 @@ export async function previewStopSignal(projectCwd, deps = {}) {
         // relay's own teardown and print a number that was true of a preview which
         // no longer exists. A dead pid is never queried at all — the marker is stale
         // and there is nothing on that port to ask.
-        const relay = deps.relay ?? httpRelayClient(`http://127.0.0.1:${info.relayPort}`);
+        const relay = deps.relay ?? httpRelayClient(`http://127.0.0.1:${info.relayPort}`, info.token);
         const connected = await readLiveConnections(relay);
         try {
             (deps.kill ?? ((pid, sig) => process.kill(pid, sig)))(info.pid, "SIGTERM");
@@ -333,7 +334,7 @@ async function relayForProject(projectCwd, override) {
         throw new Error("No running preview for this project. Run `vincentt preview` first.");
     }
     // The relay listens on 127.0.0.1 only; `localhost` may resolve to ::1 first.
-    return httpRelayClient(`http://127.0.0.1:${info.relayPort}`);
+    return httpRelayClient(`http://127.0.0.1:${info.relayPort}`, info.token);
 }
 /** Raw diagnostics query against the running relay (used by CLI --json). */
 export async function diagQuery(projectCwd, kind, opts = {}, relay) {

package/dist/lib/relayInfo.d.ts

@@ -24,6 +24,12 @@ export interface RelayInfo {
      * written by an older CLI or on a platform with no reader.
      */
     pidStartTime?: string;
+    /**
+     * The relay's per-session secret for `/query` and `feedback/next`. The marker
+     * is written 0600 because of it. Absent from markers written by an older CLI,
+     * whose relay asks for none.
+     */
+    token?: string;
 }
 export declare function relayInfoPath(cwd: string): string;
 /**
@@ -64,7 +70,7 @@ export declare function isProcessAlive(pid: number): boolean;
  * runs fifty times a day, and the fallback (mint a preview) is what they asked
  * for anyway.
  */
-export declare function isRelayResponding(port: number, timeoutMs?: number, fetchImpl?: typeof fetch): Promise<boolean>;
+export declare function isRelayResponding(port: number, timeoutMs?: number, fetchImpl?: typeof fetch, token?: string): Promise<boolean>;
 /**
  * readLivePreview returns the marker ONLY when it still describes a preview that
  * is genuinely running, and CLEARS it otherwise.
@@ -81,5 +87,5 @@ export declare function isRelayResponding(port: number, timeoutMs?: number, fetc
  */
 export declare function readLivePreview(cwd: string, deps?: {
     processAlive?: (pid: number) => boolean;
-    relayResponding?: (port: number) => Promise<boolean>;
+    relayResponding?: (port: number, token?: string) => Promise<boolean>;
 }): Promise<RelayInfo | undefined>;

package/dist/lib/relayInfo.js

@@ -5,6 +5,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { locateProjectBinding } from "../shared/config.js";
+import { relayAuthHeaders } from "./diagnostics.js";
 const RELAY_INFO_FILE = "relay.json";
 const VINCENTT_DIR = ".vincentt";
 export function relayInfoPath(cwd) {
@@ -28,7 +29,15 @@ export async function relayInfoDir(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");
+    // Removed first so an older 0644 marker is not rewritten in place: `mode`
+    // only applies when the file is created, and the token must never be
+    // readable by another user.
+    await fs.rm(p, { force: true });
+    await fs.writeFile(p, JSON.stringify(info, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: 0o600,
+        flag: "wx",
+    });
     return p;
 }
 /** Reads the marker for the TREE containing cwd, not only the folder itself. */
@@ -83,7 +92,7 @@ export function isProcessAlive(pid) {
  * runs fifty times a day, and the fallback (mint a preview) is what they asked
  * for anyway.
  */
-export async function isRelayResponding(port, timeoutMs = 700, fetchImpl = fetch) {
+export async function isRelayResponding(port, timeoutMs = 700, fetchImpl = fetch, token) {
     if (!Number.isInteger(port) || port <= 0 || port > 65535)
         return false;
     const ac = new AbortController();
@@ -91,7 +100,7 @@ export async function isRelayResponding(port, timeoutMs = 700, fetchImpl = fetch
     try {
         const res = await fetchImpl(`http://127.0.0.1:${port}/query`, {
             method: "POST",
-            headers: { "content-type": "application/json" },
+            headers: { "content-type": "application/json", ...relayAuthHeaders(token) },
             body: JSON.stringify({ kind: "log", limit: 0 }),
             signal: ac.signal,
         });
@@ -132,14 +141,15 @@ export async function readLivePreview(cwd, deps = {}) {
     if (!info)
         return undefined;
     const processAlive = deps.processAlive ?? isProcessAlive;
-    const relayResponding = deps.relayResponding ?? ((p) => isRelayResponding(p));
+    const relayResponding = deps.relayResponding ??
+        ((p, t) => isRelayResponding(p, undefined, undefined, t));
     // The cheap gate first: a dead pid needs no network round trip.
     if (info.pid !== undefined && !processAlive(info.pid)) {
         await clearRelayInfo(cwd);
         return undefined;
     }
     // The identity gate: alive-but-not-ours (a recycled pid) fails here.
-    if (!(await relayResponding(info.relayPort))) {
+    if (!(await relayResponding(info.relayPort, info.token))) {
         await clearRelayInfo(cwd);
         return undefined;
     }

package/dist/lib/terminalText.d.ts

@@ -1,3 +1,5 @@
 export declare const CONTROL_CHARS: RegExp;
 /** Each C0/C1 control character as a visible `\uXXXX`, so nothing is hidden or redrawn. */
 export declare function escapeControl(text: string): string;
+/** Text with every C0/C1 control and bidi override or isolate removed. */
+export declare function terminalSafe(text: string): string;

package/dist/lib/terminalText.js

@@ -8,3 +8,10 @@ const CONTROL_CHARS_G = /[\u0000-\u001f\u007f-\u009f]/g;
 export function escapeControl(text) {
     return text.replace(CONTROL_CHARS_G, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
 }
+// U+202A..U+202E (embeddings, overrides) and U+2066..U+2069 (isolates) can
+// reorder a terminal line, so a crafted name could disguise what it says.
+const BIDI_CONTROLS_G = /[\u202a-\u202e\u2066-\u2069]/g;
+/** Text with every C0/C1 control and bidi override or isolate removed. */
+export function terminalSafe(text) {
+    return text.replace(CONTROL_CHARS_G, "").replace(BIDI_CONTROLS_G, "");
+}

package/dist/login/pkceLogin.d.ts

@@ -29,11 +29,17 @@ export declare class LoginTimeoutError extends Error {
 export declare class LoginCallbackError extends Error {
     constructor(message: string);
 }
-/** The platform command + args to open `url` in the default browser. */
+/**
+ * The platform command + args to open `url` in the default browser. On win32
+ * the URL goes to `rundll32` as one argument, so no command interpreter parses
+ * it and `&` cannot split the command.
+ */
 export declare function browserOpenCommand(url: string, platform?: string): {
     cmd: string;
     args: string[];
 };
+/** Only `https:`, or `http:` on a loopback host, is ever handed to the OS opener. */
+export declare function isLaunchableUrl(url: string): boolean;
 type SpawnLike = (cmd: string, args: string[], opts: {
     stdio: "ignore";
     detached: boolean;

package/dist/login/pkceLogin.js

@@ -30,14 +30,35 @@ export class LoginCallbackError extends Error {
         this.name = "LoginCallbackError";
     }
 }
-/** The platform command + args to open `url` in the default browser. */
+/**
+ * The platform command + args to open `url` in the default browser. On win32
+ * the URL goes to `rundll32` as one argument, so no command interpreter parses
+ * it and `&` cannot split the command.
+ */
 export function browserOpenCommand(url, platform = process.platform) {
-    const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
-    const args = platform === "win32" ? ["/c", "start", "", url] : [url];
-    return { cmd, args };
+    if (platform === "win32") {
+        return { cmd: "rundll32", args: ["url.dll,FileProtocolHandler", url] };
+    }
+    return { cmd: platform === "darwin" ? "open" : "xdg-open", args: [url] };
+}
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "[::1]", "localhost"]);
+/** Only `https:`, or `http:` on a loopback host, is ever handed to the OS opener. */
+export function isLaunchableUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol === "https:")
+        return true;
+    return parsed.protocol === "http:" && LOOPBACK_HOSTS.has(parsed.hostname);
 }
 /** Launch the browser via an injected spawn; a throw is swallowed (fallback = the printed URL). */
 export function launchBrowser(url, spawn, platform) {
+    if (!isLaunchableUrl(url))
+        return;
     const { cmd, args } = browserOpenCommand(url, platform);
     try {
         const child = spawn(cmd, args, { stdio: "ignore", detached: true });

package/dist/preview/api.d.ts

@@ -46,6 +46,21 @@ export declare class PreviewLimitError extends BackendError {
     readonly detail: CountLimitDetail;
     constructor(message: string, detail: CountLimitDetail);
 }
+/** The refusal body's detail on `preview_user_limit`. */
+export interface PreviewUserLimitDetail {
+    limit?: string;
+    count?: number;
+    ceiling?: number;
+}
+/**
+ * The caller already runs as many previews as one person may, across every
+ * workspace (`409 preview_user_limit`). A THIRD 409 on the mint route, told
+ * apart by its code. Nothing was ended; the remedy is stopping a preview.
+ */
+export declare class PreviewUserLimitError extends BackendError {
+    readonly detail: PreviewUserLimitDetail;
+    constructor(message: string, detail: PreviewUserLimitDetail);
+}
 /**
  * The session is gone — `preview_session_ended`, the CLI's terminal branch.
  *

package/dist/preview/api.js

@@ -47,6 +47,19 @@ export class PreviewLimitError extends BackendError {
         this.name = "PreviewLimitError";
     }
 }
+/**
+ * The caller already runs as many previews as one person may, across every
+ * workspace (`409 preview_user_limit`). A THIRD 409 on the mint route, told
+ * apart by its code. Nothing was ended; the remedy is stopping a preview.
+ */
+export class PreviewUserLimitError extends BackendError {
+    detail;
+    constructor(message, detail) {
+        super(message, 409);
+        this.detail = detail;
+        this.name = "PreviewUserLimitError";
+    }
+}
 /**
  * The session is gone — `preview_session_ended`, the CLI's terminal branch.
  *
@@ -130,7 +143,20 @@ export async function mintPreviewSession(cfg, projectId, key, fetchImpl = apiFet
             if (body.code === "preview_limit") {
                 throw new PreviewLimitError(body.message ?? "this organization is at its preview limit", body.detail ?? {});
             }
-            throw new PreviewConflictError(body.message ?? "a preview is already running for this folder");
+            if (body.code === "preview_user_limit") {
+                const d = body.detail ?? {};
+                throw new PreviewUserLimitError(body.message ?? "you already have the most previews one person can run at once", {
+                    limit: typeof d.limit === "string" ? d.limit : undefined,
+                    count: typeof d.count === "number" ? d.count : undefined,
+                    ceiling: typeof d.ceiling === "number" ? d.ceiling : undefined,
+                });
+            }
+            if (body.code === "preview_session_conflict" || body.code === undefined) {
+                throw new PreviewConflictError(body.message ?? "a preview is already running for this folder");
+            }
+            // An unrecognised refusal prints the server's own words rather than the
+            // folder-conflict screen, so a future 409 is never misread as a conflict.
+            throw new BackendError(body.message ?? `could not start a preview (409)`, 409);
         }
         throw new BackendError(body.message ?? `could not start a preview (${res.status})`, res.status);
     }

package/dist/preview/command.d.ts

@@ -1,5 +1,5 @@
 import type { DiagEvent } from "@vincentt-xr/harness/events";
-import type { TunnelState, UAClass } from "@vincentt-xr/harness/tunnel";
+import type { TunnelState, UAClass } from "../tunnel/index.js";
 import type { EventTags } from "../relay/server.js";
 import type { PreviewEndReason } from "./runner.js";
 export interface PreviewUiDeps {

package/dist/preview/copy.d.ts

@@ -51,7 +51,7 @@ export declare function deviceArrived(descriptor: string): string;
  * The window's length is deliberately not printed.
  */
 export declare function noDiagnosticsRuntime(descriptor: string): string[];
-/** Flow P1 — the proxy refused a hidden path. Once per preview, naming the first. */
+/** Flow P1 — the proxy refused a hidden or credential path. Once per preview, naming the first. */
 export declare function hiddenPathRefused(requestPath: string): string;
 /** Flow L16 — `--viewer`, a second terminal, not a second preview. */
 export declare function followingBlock(label: string, descriptor: string): string[];
@@ -267,3 +267,16 @@ export declare function mintRateLimited(retryAfterSec: number): string[];
 export declare function approxWait(seconds: number): string;
 /** The conflict a supersede lost (409). Rare: the mint supersedes first. */
 export declare function previewConflict(): string[];
+/**
+ * The per-person preview cap, refused at mint (`409 preview_user_limit`, B-F3-9).
+ *
+ * The count and the cap come only from the refusal body, never from a number
+ * compiled in: the cap is an operator setting. It names no workspace, plan or
+ * price, because no plan raises it. "Still running" comes first among the facts
+ * for the same reason as the org-ceiling screen: the command that refused is the
+ * one that starts previews, so a creator assumes it took something down.
+ */
+export declare function previewUserLimitRefused(d: {
+    count?: number;
+    ceiling?: number;
+}): string[];

package/dist/preview/copy.js

@@ -17,7 +17,7 @@
 // sharpest — it transits an agent's tool-output transcript by default in this
 // product, so f1's "a token is never printed" extends to it verbatim.
 /** Flow L13 — the start block. */
-import { escapeControl } from "../lib/terminalText.js";
+import { escapeControl, terminalSafe } from "../lib/terminalText.js";
 export function startBlock(i) {
     const out = [
         "",
@@ -128,9 +128,9 @@ export function noDiagnosticsRuntime(descriptor) {
         "  stopped before that line ran.",
     ];
 }
-/** Flow P1 — the proxy refused a hidden path. Once per preview, naming the first. */
+/** Flow P1 — the proxy refused a hidden or credential path. Once per preview, naming the first. */
 export function hiddenPathRefused(requestPath) {
-    return `! Answered 404 for ${requestPath}. A preview never serves hidden files from your project.`;
+    return `! Answered 404 for ${terminalSafe(requestPath)}. A preview never serves hidden or credential files from your project.`;
 }
 /** Flow L16 — `--viewer`, a second terminal, not a second preview. */
 export function followingBlock(label, descriptor) {
@@ -572,3 +572,37 @@ export function previewConflict() {
         "",
     ];
 }
+/**
+ * The per-person preview cap, refused at mint (`409 preview_user_limit`, B-F3-9).
+ *
+ * The count and the cap come only from the refusal body, never from a number
+ * compiled in: the cap is an operator setting. It names no workspace, plan or
+ * price, because no plan raises it. "Still running" comes first among the facts
+ * for the same reason as the org-ceiling screen: the command that refused is the
+ * one that starts previews, so a creator assumes it took something down.
+ */
+export function previewUserLimitRefused(d) {
+    const { count, ceiling } = d;
+    const known = typeof count === "number" && typeof ceiling === "number" && ceiling > 0;
+    let first = "✗ You already have the most previews one person can run at once.";
+    if (known && count > ceiling) {
+        first = `✗ You already have ${count} previews running. One person can run ${ceiling} at once.`;
+    }
+    else if (known && count === ceiling) {
+        first = `✗ You already have ${count} previews running, the most one person can run at once.`;
+    }
+    return [
+        "",
+        first,
+        "",
+        "  Every preview that was running is still running. This one did not start.",
+        "  A preview that is still connecting counts too. Viewers never count.",
+        "",
+        "  To start this one, stop a preview you no longer need:",
+        "    press Ctrl-C where it runs, or run  vincentt preview --stop  in its folder,",
+        "    or press Stop on its project's Preview tab in the console.",
+        "",
+        "  Nothing was started.",
+        "",
+    ];
+}

package/dist/preview/devPort.d.ts

@@ -0,0 +1,17 @@
+import type { ResolvedSettings } from "../lib/settings.js";
+export interface DevPortChoice {
+    port: number;
+    /**
+     * The port was picked for this preview. Nothing else may answer there, so a
+     * listener found on it is never reused as the app.
+     */
+    fresh: boolean;
+}
+/**
+ * The port the preview's dev server runs on. Only the template default is
+ * replaced with a free port (passed to the dev command as PORT), so two
+ * previews never share one. A port from `--port` or `vincentt.json`, or any
+ * port paired with a custom dev command, is kept: many outside dev servers
+ * ignore PORT and listen where they were told.
+ */
+export declare function chooseDevPort(settings: Pick<ResolvedSettings, "devCommand" | "devPort">, pickPort?: () => Promise<number>): Promise<DevPortChoice>;

package/dist/preview/devPort.js

@@ -0,0 +1,14 @@
+import { getFreePort } from "./net.js";
+/**
+ * The port the preview's dev server runs on. Only the template default is
+ * replaced with a free port (passed to the dev command as PORT), so two
+ * previews never share one. A port from `--port` or `vincentt.json`, or any
+ * port paired with a custom dev command, is kept: many outside dev servers
+ * ignore PORT and listen where they were told.
+ */
+export async function chooseDevPort(settings, pickPort = getFreePort) {
+    if (settings.devPort.source === "default" && settings.devCommand.source === "default") {
+        return { port: await pickPort(), fresh: true };
+    }
+    return { port: settings.devPort.value, fresh: false };
+}

package/dist/preview/proxy.d.ts

@@ -36,17 +36,24 @@ export declare function proxyWs(req: IncomingMessage, socket: Duplex, head: Buff
 export declare function relayRoute(url: string, harnessPath: string, kind: "http" | "upgrade"): "relay" | "refuse" | "app";
 /**
  * Whether the front proxy must answer 404 itself for this app-route URL, so a
- * file-server dev tool serving the repo root cannot hand `/.env`, `/.git/config`
- * or the binding to any holder of a preview link.
+ * file-server dev tool serving the repo root cannot hand `/.env`, `/.git/config`,
+ * the binding or a credential file to any holder of a preview link.
  *
  * The path is decoded once, and an encoded `/` or `\` is refused outright (a
- * separator the dev server would split on and this check would not). A segment
- * still carrying an encoded dot after that one decode is judged as the dev
- * server would read it after a second decode, so `%252eenv` cannot slip past.
- * `.` and `..` segments are always refused, which is what makes the `/@fs/`
- * text containment below real containment.
+ * separator the dev server would split on and this check would not). The query
+ * and fragment may not carry a traversal or a separator either, because some
+ * dev servers resolve a file from a query parameter. A segment still carrying
+ * an encoded character after that one decode is judged as the dev server would
+ * read it after a second decode, so `%252eenv` cannot slip past; a second decode
+ * that throws is done leniently, never treated as "not hidden". `.` and `..`
+ * segments are always refused, which is what makes the `/@fs/` text containment
+ * below real containment.
  *
- * `projectRoot` is the realpath of the binding directory, taken once at preview
- * start; inside-ness is a segment-aligned text prefix, with no disk call.
+ * Three rules read the checked segments: the dot rule (raw name), and the
+ * short-name and credential-name rules (normalized name, see `normalizedName`).
+ *
+ * `projectRoot` is the realpath of the binding directory with forward slashes,
+ * taken once at preview start; inside-ness is a segment-aligned text prefix,
+ * with no disk call.
  */
 export declare function isHiddenAppPath(url: string, projectRoot: string): boolean;