@vincentt-xr/cli 0.18.3 → 0.20.0

package/dist/login/machineLabel.js

@@ -0,0 +1,119 @@
+// The machine label `vincentt login` sends with the exchange: a name for this
+// machine's sign-in that the console lists and the eviction line prints.
+//
+// It is built from the OS, the architecture and today's date, NEVER the hostname:
+// a hostname often carries a person's name or an employer's asset tag, and the
+// label is shown back to the person. `--label` overrides it.
+//
+// validateMachineLabel applies the api's exact rules, counting CODE POINTS after
+// NFC (not UTF-16 units), so `--label` is refused here, before any browser or
+// network, for exactly what the api would refuse. The shared corpus
+// (__fixtures__/machine_label_corpus.json, copied from the api) pins agreement.
+export const MACHINE_LABEL_MAX_CODE_POINTS = 64;
+export const MACHINE_LABEL_MAX_MARK_RUN = 4;
+export const LEGACY_MACHINE_LABEL = "Signed in before machine names";
+export const DEFAULT_MACHINE_LABEL_PREFIX = "Unnamed machine,";
+const MONTHS = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+];
+export const MACHINE_LABEL_REFUSED_LINES = [
+    "✗ A machine label must be 1 to 64 letters, numbers, spaces, punctuation or symbols.",
+    '  Run `vincentt login --label "<name>"` with a shorter name, or leave out --label.',
+];
+/** "d Mon" in the given date's own calendar fields (local time unless the caller says otherwise). */
+export function dayMonth(d, utc = false) {
+    const day = utc ? d.getUTCDate() : d.getDate();
+    const month = utc ? d.getUTCMonth() : d.getMonth();
+    return `${day} ${MONTHS[month]}`;
+}
+function osName(platform) {
+    if (platform === "darwin")
+        return "macOS";
+    if (platform === "win32")
+        return "Windows";
+    if (platform === "linux")
+        return "Linux";
+    return platform;
+}
+/** The default label, "<OS> <arch>, <d Mon>", from injected platform, arch and clock. */
+export function defaultMachineLabel(platform = process.platform, arch = process.arch, now = new Date()) {
+    return `${osName(platform)} ${arch}, ${dayMonth(now)}`;
+}
+const ALLOWED = /^[\p{L}\p{M}\p{N}\p{P}\p{S} ]$/u;
+const MARK = /^\p{M}$/u;
+function trimSpaces(s) {
+    return s.replace(/^ +| +$/g, "");
+}
+function fold(s) {
+    return s.normalize("NFKC").toLowerCase();
+}
+const FOLDED_LEGACY = fold(LEGACY_MACHINE_LABEL);
+const FOLDED_DEFAULT_PREFIX = fold(DEFAULT_MACHINE_LABEL_PREFIX);
+/**
+ * The api's label rules, for a label the person typed: NFC, trim U+0020 only,
+ * then 1 to 64 code points, each a letter, mark, number, punctuation, symbol or
+ * plain space, no run of more than 4 marks, and not a platform-only string. An
+ * empty label is refused here (the api would store its default, but `--label ""`
+ * is a mistake, not a request for the default).
+ */
+export function validateMachineLabel(raw) {
+    const label = trimSpaces(raw.normalize("NFC"));
+    const points = [...label];
+    if (points.length < 1 || points.length > MACHINE_LABEL_MAX_CODE_POINTS)
+        return { ok: false };
+    let markRun = 0;
+    for (const cp of points) {
+        if (!ALLOWED.test(cp))
+            return { ok: false };
+        if (MARK.test(cp)) {
+            markRun++;
+            if (markRun > MACHINE_LABEL_MAX_MARK_RUN)
+                return { ok: false };
+        }
+        else {
+            markRun = 0;
+        }
+    }
+    // Case folding approximated by NFKC + toLowerCase; the shared corpus pins
+    // agreement with the api's NFKC + Unicode case fold.
+    const folded = trimSpaces(fold(label));
+    if (folded === FOLDED_LEGACY || folded.startsWith(FOLDED_DEFAULT_PREFIX))
+        return { ok: false };
+    return { ok: true, label };
+}
+/**
+ * Drop every code point outside the label allowlist before a server-sent label
+ * is printed. The api already refuses such labels; this keeps a later
+ * validation bug from writing escape sequences or bidi controls to a terminal.
+ */
+export function sanitizeServerLabel(label) {
+    if (typeof label !== "string")
+        return "";
+    return [...label].filter((cp) => ALLOWED.test(cp)).join("");
+}
+/**
+ * The label a `vincentt login` sends. Without --label it is the default; with it,
+ * the typed value must pass the api's rules, or the refusal lines are returned
+ * and the login must stop before any browser or network.
+ */
+export function resolveLoginLabel(given, raw, defaults = {}) {
+    if (!given) {
+        return {
+            ok: true,
+            label: defaultMachineLabel(defaults.platform, defaults.arch, defaults.now),
+        };
+    }
+    const check = validateMachineLabel(raw ?? "");
+    return check.ok ? check : { ok: false, lines: MACHINE_LABEL_REFUSED_LINES };
+}

package/dist/login/pkceLogin.d.ts

@@ -1,4 +1,4 @@
-import { type AuthBackend, type Identity } from "./authBackend.js";
+import { type AuthBackend, type EvictedMachine, type Identity } from "./authBackend.js";
 export interface PkceLoginOptions {
     /** Console origin that serves /cli-auth (browser target). */
     consoleUrl: string;
@@ -6,6 +6,8 @@ export interface PkceLoginOptions {
     apiUrl: string;
     /** Abort if the browser round-trip doesn't complete in time. Default 5 min. */
     timeoutMs?: number;
+    /** The machine label sent with the exchange (already validated). */
+    label?: string;
     /** Backend calls (exchange + me). Default: real HTTP against apiUrl. */
     backend?: AuthBackend;
     /** Pick a free loopback port. Default: the OS ephemeral picker. */
@@ -20,6 +22,10 @@ export interface PkceLoginOptions {
 export interface PkceLoginResult {
     identity: Identity;
     configPath: string;
+    /** The label the api stored, echoed back; absent from an older api. */
+    label?: string;
+    /** Machines this login signed out at the 10-machine cap. */
+    evicted?: EvictedMachine[];
 }
 /** Thrown when the wait elapses with no approval; drives the L4 timeout transcript. */
 export declare class LoginTimeoutError extends Error {
@@ -29,11 +35,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

@@ -5,7 +5,8 @@
 //   2. Mint state + PKCE code_verifier/code_challenge (S256).
 //   3. Open the browser to /cli-auth?redirect_uri=<loopback>&state=…&code_challenge=….
 //   4. On the loopback callback: verify state constant-time (reject mismatch → no exchange).
-//   5. POST /access-tokens/exchange {code, code_verifier} → raw PAT (in body, once).
+//   5. POST /access-tokens/exchange {code, code_verifier, label} → raw PAT (in body, once),
+//      the stored label, and any machines the 10-machine cap signed out.
 //   6. Write ~/.vincentt/config.json, then GET /me Bearer <PAT> to confirm identity + orgs.
 //
 // Every external boundary is injected (getFreePort, listen, openBrowser, backend, clock/
@@ -14,7 +15,7 @@
 import { getFreePort } from "../preview/net.js";
 import { writeMachineConfig } from "../shared/config.js";
 import { makePkceMaterial, buildCliAuthUrl, parseCallback, } from "./pkce.js";
-import { httpAuthBackend } from "./authBackend.js";
+import { httpAuthBackend, } from "./authBackend.js";
 import { waitForLoopbackCallback } from "./loopback.js";
 /** Thrown when the wait elapses with no approval; drives the L4 timeout transcript. */
 export class LoginTimeoutError extends Error {
@@ -30,14 +31,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 });
@@ -145,8 +167,9 @@ export async function runPkceLogin(opts) {
         },
     });
     // (5) redeem the code for the raw PAT; (6) persist then confirm identity.
-    const pat = await backend.exchange(code, material.codeVerifier);
+    const exchanged = await backend.exchange(code, material.codeVerifier, opts.label);
+    const pat = exchanged.token;
     const configPath = await saveToken(opts.apiUrl.replace(/\/$/, ""), pat);
     const identity = await backend.me(pat);
-    return { identity, configPath };
+    return { identity, configPath, label: exchanged.label, evicted: exchanged.evicted };
 }

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) {
@@ -448,7 +448,7 @@ export function endedUnreachable(orgName) {
 export function endedAuthExpired() {
     return [
         "",
-        "✗ Preview ended. Your Vincentt access token is no longer valid.",
+        "✗ Preview ended. This machine is no longer signed in to Vincentt.",
         "",
         "  Sign in again:  vincentt login",
         "  Then start a new preview:  vincentt preview",
@@ -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;

package/dist/preview/proxy.js

@@ -138,23 +138,34 @@ export function relayRoute(url, harnessPath, kind) {
 }
 /**
  * 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 function isHiddenAppPath(url, projectRoot) {
-    const raw = (url.split("#")[0] ?? "").split("?")[0] ?? "";
+    const [beforeHash = "", ...hash] = url.split("#");
+    const [raw = "", ...query] = beforeHash.split("?");
     if (/%(2f|5c)/i.test(raw) || raw.includes("\\"))
         return true;
+    const tail = [...query, ...hash].join("?");
+    if (/%(2f|5c)/i.test(tail) || tail.includes("\\") || tail.includes("/.."))
+        return true;
     let decoded;
     try {
         decoded = decodeURIComponent(raw);
@@ -168,22 +179,93 @@ export function isHiddenAppPath(url, projectRoot) {
     const checked = checkedSegmentIndexes(segments, projectRoot);
     for (const i of checked) {
         const seg = segments[i];
-        if (!startsWithDot(seg))
-            continue;
-        if (isAllowedDotSegment(segments, i))
-            continue;
-        return true;
+        const spellings = [seg, secondDecode(seg)];
+        if (spellings.some((s) => s.startsWith(".")) && !isAllowedDotSegment(segments, i)) {
+            return true;
+        }
+        for (const s of spellings) {
+            const name = normalizedName(s);
+            if (name === REFUSE)
+                return true;
+            if (SHORT_NAME.test(name) || isCredentialName(name))
+                return true;
+        }
     }
     return false;
 }
-function startsWithDot(segment) {
-    if (segment.startsWith("."))
-        return true;
+/** The segment as a second decode would read it; lenient when that decode throws. */
+function secondDecode(segment) {
+    if (!/%[0-9a-f]{2}/i.test(segment))
+        return segment;
     try {
-        return decodeURIComponent(segment).startsWith(".");
+        return decodeURIComponent(segment);
     }
     catch {
-        return false;
+        return segment.replace(/(?:%[0-9a-f]{2})+/gi, (run) => {
+            try {
+                return decodeURIComponent(run);
+            }
+            catch {
+                return run.replace(/%([0-9a-f]{2})/gi, (_, h) => String.fromCharCode(parseInt(h, 16)));
+            }
+        });
+    }
+}
+const REFUSE = Symbol("refuse");
+/**
+ * The name a Windows or case-insensitive file system would open for this
+ * segment: a stream suffix (`:$`) is refused outright, the rest is cut at the
+ * first colon (so `/@fs/C:/...` and `virtual:` modules still work), trailing
+ * dots and spaces are dropped (Windows resolves `server.pem. .` to `server.pem`),
+ * and compatibility and case forms are folded.
+ */
+function normalizedName(segment) {
+    if (segment.includes(":$"))
+        return REFUSE;
+    const beforeColon = segment.split(":")[0] ?? "";
+    return beforeColon.replace(/[. ]+$/, "").normalize("NFKC").toUpperCase().toLowerCase();
+}
+/**
+ * A Windows 8.3 short name (`GIT~1`, `CREDEN~1.JSO`) opens the long-named file
+ * it stands for, and its short form carries no leading dot, so `/GIT~1/config`
+ * would read `.git/config` past the dot rule. Refused on every platform: the
+ * proxy can front a Windows file system from any client.
+ */
+const SHORT_NAME = /^[^~]{1,6}~[0-9]/;
+/** D-Preview-hides-credential-files: hard-coded, no opt-out. `*` is any run of characters. */
+const CREDENTIAL_NAMES = Object.freeze([
+    "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",
+].map((glob) => new RegExp(`^${glob
+    .split("*")
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join(".*")}$`, "s")));
+/** A listed name, or one with backup endings (`~`, `.bak`) added, any number of times. */
+function isCredentialName(name) {
+    let candidate = name;
+    for (;;) {
+        if (CREDENTIAL_NAMES.some((re) => re.test(candidate)))
+            return true;
+        const stripped = candidate.replace(/(?:~|\.bak)$/, "");
+        if (stripped === candidate)
+            return false;
+        candidate = stripped;
     }
 }
 function checkedSegmentIndexes(segments, projectRoot) {

package/dist/preview/runner.d.ts

@@ -1,9 +1,15 @@
-import { type ControlKind, type TunnelState, type UAClass } from "@vincentt-xr/harness/tunnel";
+import { type ControlKind, type TunnelState, type UAClass } from "../tunnel/index.js";
 import type { DiagEvent } from "@vincentt-xr/harness/events";
 import { type EventTags } from "../relay/server.js";
 import { type ResolvedConfig } from "../shared/config.js";
 /** The path a 404 advisory names: the request's own path, without its query. */
 export declare function requestPathOf(url: string | undefined): string;
+/**
+ * The project root as the `/@fs/` check compares it: Vite writes `/@fs/C:/...`
+ * with forward slashes, so a Windows root holding backslashes would never match
+ * as inside, and a project under a dotted parent folder would get false 404s.
+ */
+export declare function hiddenPathRoot(realRoot: string): string;
 /** Why a preview ended. Each maps to exactly one screen (Flow L20/L21). */
 export type PreviewEndReason = "stopped"
 /**
@@ -57,8 +63,10 @@ export interface StartPreviewOptions {
     /** The API host + PAT. Resolved by the caller so the runner makes no policy. */
     config: ResolvedConfig;
     projectId: string;
-    /** App dev-serve port (default 5173). A server already here is REUSED. */
+    /** App dev-serve port (default 5173). A server already here is REUSED unless `appPortFresh`. */
     appPort?: number;
+    /** appPort was picked for this preview, so the dev command always starts there. */
+    appPortFresh?: boolean;
     relayPort?: number;
     frontPort?: number;
     /** Path routed to the relay instead of the app (default /__harness). */