@vincentt-xr/cli 0.16.0 → 0.18.0

package/dist/login/ensure.js

@@ -1,13 +1,24 @@
-// First-run login guard. An auth-requiring verb (create / preview / publish) calls
-// this before doing any work: if there's no token yet, it runs the login flow inline
-// and continues, instead of failing with "not signed in". Login stays a human browser
-// approval — this only removes the separate `vincentt login` step a user had to know
-// to run first. Deps are injected so the branch is unit-testable without a real
-// browser round-trip or a real config file.
-/** No-op when a token is already present; otherwise log-and-login before returning. */
+// First-run login guard. An auth-requiring verb calls this before doing any work:
+// if there's no token yet, it runs the login flow inline and continues, instead of
+// failing with "not signed in". Login stays a human browser approval, so it is
+// offered only at a terminal. Without one the browser wait would outlast the
+// caller's shell timeout, so the verb refuses at once with the login remedy.
+import { NOT_SIGNED_IN_LINES } from "../shared/authError.js";
+/**
+ * True when a token is present, or a login at the terminal produced one. False
+ * after printing the not-signed-in lines: the caller exits EXIT.NOT_AUTHENTICATED.
+ * A login that throws (cancelled, timed out) propagates.
+ */
 export async function ensureLoggedIn(deps) {
     if (await deps.currentToken())
-        return;
-    deps.notify("You're not signed in yet — opening the browser to authorize this device…");
-    await deps.runLogin();
+        return true;
+    if (deps.interactive) {
+        deps.notify("You're not signed in yet. Opening the browser to authorize this device…");
+        await deps.runLogin();
+        if (await deps.currentToken())
+            return true;
+    }
+    for (const l of NOT_SIGNED_IN_LINES)
+        deps.notify(l);
+    return false;
 }

package/dist/login/guard.js

@@ -1,7 +1,8 @@
 // The not-signed-in voice (Flow L3). f1 defines this voice; any gated command (f2+) uses
 // it via `requireSignedIn`. When no token is present it prints the exact two-line message
-// and reports "not signed in" so the caller can abort with a non-zero exit — no stack trace,
-// no auto-browser-launch (that's `ensureLoggedIn`'s convenience path; the gate is explicit).
+// and reports "not signed in" so the caller can abort with EXIT.NOT_AUTHENTICATED: no stack
+// trace, no auto-browser-launch (that's `ensureLoggedIn`'s convenience path; the gate is explicit).
+import { NOT_SIGNED_IN_LINES } from "../shared/authError.js";
 /**
  * True when a token is present. When absent, prints the L3 not-signed-in message and returns
  * false. The exact copy is locked by the f1 design:
@@ -11,7 +12,7 @@
 export async function requireSignedIn(deps) {
     if (await deps.currentToken())
         return true;
-    deps.print("✗ You're not signed in.");
-    deps.print("  Run `vincentt login` to connect this machine to your Vincentt account.");
+    for (const l of NOT_SIGNED_IN_LINES)
+        deps.print(l);
     return false;
 }

package/dist/login/loginCommand.d.ts

@@ -14,8 +14,8 @@ export interface LoginCommandDeps {
     print: (line: string) => void;
     /** The token currently on this machine, if any (env override or config file). */
     currentToken: () => Promise<string | undefined>;
-    /** Confirm who a present token belongs to (GET /me). Undefined if it can't be resolved. */
-    whoAmI: () => Promise<Identity | undefined>;
+    /** Confirm who the present token belongs to (GET /me). Throws the client's error unchanged. */
+    whoAmI: () => Promise<Identity>;
     /** Run the loopback + PKCE flow; resolves identity + the saved config path. */
     runLogin: () => Promise<{
         identity: Identity;

package/dist/login/loginCommand.js

@@ -5,6 +5,8 @@
 //
 // The IO boundary (print, current identity, run the PKCE flow, clock) is injected so every
 // L1–L4 branch is unit-testable with no real browser, socket, or config file.
+import { isAuthRefused } from "../shared/authError.js";
+import { EXIT } from "../lib/exitCodes.js";
 /** Collapse the home dir to `~` for display. `~/.vincentt/config.json` in every transcript. */
 export function displayConfigPath(absPath, home) {
     if (home && absPath.startsWith(home))
@@ -42,16 +44,38 @@ export async function loginCommand(deps, opts = {}) {
         await deps.clearToken();
     }
     else {
-        // L2 — already signed in: no browser, no re-mint.
+        // L2: already signed in, but only once the api confirms the token.
         const existing = await deps.currentToken();
         if (existing) {
-            const who = await deps.whoAmI().catch(() => undefined);
-            const email = who?.email ?? "your account";
-            deps.print(`✓ Already signed in as ${email} (token in ${displayPath})`);
+            let who;
+            try {
+                who = await deps.whoAmI();
+            }
+            catch (err) {
+                if (!isTokenRejected(err)) {
+                    // A down api or a dead network says nothing about the token, so it stays.
+                    deps.print("✗ Could not check the account for the token on this machine.");
+                    deps.print(`  The token in ${displayPath} was kept.`);
+                    deps.print("  Check your connection, then run `vincentt login` again.");
+                    return EXIT.FAILED;
+                }
+                deps.print("→ The stored token is no longer valid. Signing in again…");
+                await deps.clearToken();
+                return runLoginFlow(deps);
+            }
+            deps.print(`✓ Already signed in as ${who.email} (token in ${displayPath})`);
             deps.print("  Re-run with `vincentt login --force` to sign in as someone else.");
-            return 0;
+            return EXIT.OK;
         }
     }
+    return runLoginFlow(deps);
+}
+/** 403 counts too: a token the api knows but will not honor is as unusable as an unknown one. */
+function isTokenRejected(err) {
+    return (isAuthRefused(err) ||
+        (err instanceof Error && err.status === 403));
+}
+async function runLoginFlow(deps) {
     // L1 / L4 — run the loopback + PKCE flow.
     try {
         const { identity, configPath } = await deps.runLogin();

package/dist/login/pkce.js

@@ -81,7 +81,7 @@ export function parseCallback(params, expectedState) {
         return {
             ok: false,
             reason: "state_mismatch",
-            message: "State mismatch — ignoring an unexpected callback.",
+            message: "State mismatch. Ignoring an unexpected callback.",
         };
     }
     const error = params.get("error");

package/dist/login/pkceLogin.js

@@ -130,7 +130,7 @@ export async function runPkceLogin(opts) {
                     value: result.code,
                     page: {
                         status: 200,
-                        html: browserPage(true, "You're all set", "Return to your terminal — you can close this tab."),
+                        html: browserPage(true, "You're all set", "Return to your terminal. You can close this tab."),
                     },
                 };
             }

package/dist/platform/outdated.js

@@ -106,7 +106,7 @@ export function renderOutdated(view) {
         // no install command — the creator's package manager is theirs and we do not
         // know which — and it does not print `vincentt update`, because no such verb
         // exists and must not appear to.
-        lines.push("", "  Editing package.json and installing is the whole dependency upgrade. Ask your", "  agent, or do it by hand — the strings to place are above.");
+        lines.push("", "  Editing package.json and installing is the whole dependency upgrade. Ask your", "  agent, or do it by hand; the strings to place are above.");
     }
     return lines;
 }
@@ -165,7 +165,7 @@ function templateBlock(view) {
     // a stronger statement than silence and costs two lines.
     lines.push(`    current                 ${current.version}`);
     if (from !== current.version) {
-        lines.push("    The template is source that was copied into this repository when the project", "    was created. Some of it is platform plumbing you never wrote — the app shell,", "    the helpers, the build config. `src/Scene.tsx` and everything you added is", "    yours, and nothing reports on it but this line.");
+        lines.push("    The template is source that was copied into this repository when the project", "    was created. Some of it is platform plumbing you never wrote: the app shell,", "    the helpers, the build config. `src/Scene.tsx` and everything you added is", "    yours, and nothing reports on it but this line.");
     }
     return lines;
 }

package/dist/platform/upgradeReport.js

@@ -48,7 +48,7 @@ export function renderUpgradeReport(r) {
         `  Compared against template ${r.comparedAgainst ?? "unknown"}, as recorded in this project.`,
     ];
     if (r.changed.length > 0) {
-        lines.push("", "  REPLACED — AND YOU HAD CHANGED THESE", "");
+        lines.push("", "  REPLACED, AND YOU HAD CHANGED THESE", "");
         // NEVER COMPRESSED, at any length: one file per line, always.
         const width = Math.max(...r.changed.map((f) => f.path.length));
         for (const f of r.changed) {
@@ -57,22 +57,22 @@ export function renderUpgradeReport(r) {
         lines.push(...unrecoverableBlock(r.changed));
     }
     if (r.unchanged.length > 0 || r.unchangedTestCount > 0) {
-        lines.push("", `  REPLACED — UNCHANGED BY YOU, compared against ${r.comparedAgainst ?? "the recorded baseline"}`, "", ...middotList(r.unchanged, r.unchangedTestCount));
+        lines.push("", `  REPLACED, UNCHANGED BY YOU, compared against ${r.comparedAgainst ?? "the recorded baseline"}`, "", ...middotList(r.unchanged, r.unchangedTestCount));
     }
-    lines.push("", "  LEFT ALONE — YOURS", "", 
+    lines.push("", "  LEFT ALONE: YOURS", "", 
     // Three claims, not one. Not-written is the weak claim; NOT-READ is the
     // strong one, and it is true — the procedure never has the creator's scene
     // content in its context.
     "    src/Scene.tsx, and every file you added. None of them was read, compared,", "    or written by this upgrade.");
     if (r.deletions.length > 0) {
-        lines.push("", `  NOT PART OF ${r.to} — STILL IN YOUR PROJECT`, "");
+        lines.push("", `  NOT PART OF ${r.to}: STILL IN YOUR PROJECT`, "");
         const width = Math.max(...r.deletions.map((p) => p.length));
         for (const p of r.deletions) {
             lines.push(`    ${p.padEnd(width)}    ${r.to} does not carry this file. It has not been`, `    ${" ".repeat(width)}    removed. Nothing in ${r.to} imports it.`);
         }
     }
     if (r.notPermitted.length > 0) {
-        lines.push("", "  NOT UPGRADED — NOT PERMITTED TO BE", "", `    ${r.notPermitted.join(" · ")}`, "    These run on your machine, so they are never replaced by this procedure.", `    ${r.to}'s versions differ from the ones in this project.`);
+        lines.push("", "  NOT UPGRADED: NOT PERMITTED TO BE", "", `    ${r.notPermitted.join(" · ")}`, "    These run on your machine, so they are never replaced by this procedure.", `    ${r.to}'s versions differ from the ones in this project.`);
     }
     lines.push("", ...NOT_VERIFIED);
     return lines;
@@ -86,7 +86,9 @@ export function renderUpgradeReport(r) {
  * operationalise.
  */
 function unrecoverableBlock(changed) {
-    const lost = changed.filter((f) => f.tracked === "untracked" || f.tracked === "ignored" || f.tracked === "no_repository");
+    const lost = changed.filter((f) => f.tracked === "untracked" ||
+        f.tracked === "ignored" ||
+        f.tracked === "no_repository");
     if (lost.length === 0) {
         return [
             "",
@@ -136,7 +138,7 @@ function trackedLabel(state) {
  */
 export function renderBlockedReport(r) {
     const lines = [...dependencyBlock(r.dependencies)];
-    lines.push("", "  TEMPLATE — NOT ATTEMPTED", "");
+    lines.push("", "  TEMPLATE: NOT ATTEMPTED", "");
     if (r.reason === "refused") {
         lines.push(`    Template ${r.to ?? r.firstManifestVersion} states which parts of the template are platform`, "    plumbing and which are yours, and that statement did not pass the checks this", "    procedure applies to it before reading anything. Nothing can say which files", "    would be safe to replace, so no template file was read or written.", "", "    This is not something this project can resolve. It is a fault in the template", "    version itself, and a later template version is what changes it.", "", "  NOT VERIFIED", "", "    The build has not been run. Whether this project still builds after the", "    dependency changes is not something this procedure established.");
         return lines;
@@ -167,15 +169,15 @@ export function renderBlockedReport(r) {
  */
 export function renderDegradedReport(r) {
     const lines = [...dependencyBlock(r.dependencies)];
-    lines.push("", "  TEMPLATE — NOT UPGRADED", "", "    This project has no recorded template version, so there is nothing to", "    compare your files against. No file was replaced.");
+    lines.push("", "  TEMPLATE: NOT UPGRADED", "", "    This project has no recorded template version, so there is nothing to", "    compare your files against. No file was replaced.");
     if (r.matching.length > 0 || r.matchingTestCount > 0) {
         lines.push("", `  ALREADY MATCHING ${r.to}, byte for byte`, "", ...middotList(r.matching, r.matchingTestCount));
     }
     if (r.differing.length > 0) {
-        lines.push("", `  DIFFERS FROM ${r.to} — LEFT ALONE`, "", ...middotList(r.differing, 0), "", "    Whether these differ because you changed them, or because this project came", "    from an older template, cannot be established without a recorded template", "    version. This procedure will not guess, and it did not replace them.");
+        lines.push("", `  DIFFERS FROM ${r.to}: LEFT ALONE`, "", ...middotList(r.differing, 0), "", "    Whether these differ because you changed them, or because this project came", "    from an older template, cannot be established without a recorded template", "    version. This procedure will not guess, and it did not replace them.");
     }
     if (r.deletions.length > 0) {
-        lines.push("", `  NOT PART OF ${r.to} — STILL IN YOUR PROJECT`, "");
+        lines.push("", `  NOT PART OF ${r.to}: STILL IN YOUR PROJECT`, "");
         for (const p of r.deletions) {
             lines.push(`    ${p}    ${r.to} does not carry this file.`);
         }
@@ -193,7 +195,9 @@ export function renderDegradedReport(r) {
         lines.push("", matched
             ? `  This project's template version is now recorded as ${r.to} for the files that`
             : `  This project's template version is now recorded as ${r.to}.`, ...(matched
-            ? ["  already match. A future upgrade from here can tell your changes apart from the"]
+            ? [
+                "  already match. A future upgrade from here can tell your changes apart from the",
+            ]
             : ["  A future upgrade from here can tell your changes apart from the"]), "  platform's, and will be able to report what it replaced.");
     }
     lines.push("", "  NOT VERIFIED", "", "    The build has not been run.");
@@ -214,7 +218,7 @@ export function renderDependencyIncompleteReport(r) {
         lines.push(...dependencyBlock(r.completed));
         lines.push("");
     }
-    lines.push("  TEMPLATE — NOT ATTEMPTED", "", "    The dependency changes are not all in place yet, and the template's platform", "    plumbing expects the versions this upgrade names. Replacing that plumbing over", "    a project still on the old versions would leave a project matching neither, so", "    no template file was read or written.", "", "    Still outstanding:", "", ...r.outstanding.map((name) => `      ${name}`), "", "    A later run of this procedure, once those are in place, performs the template", "    half.", "", "  NOT VERIFIED", "", "    The build has not been run.");
+    lines.push("  TEMPLATE: NOT ATTEMPTED", "", "    The dependency changes are not all in place yet, and the template's platform", "    plumbing expects the versions this upgrade names. Replacing that plumbing over", "    a project still on the old versions would leave a project matching neither, so", "    no template file was read or written.", "", "    Still outstanding:", "", ...r.outstanding.map((name) => `      ${name}`), "", "    A later run of this procedure, once those are in place, performs the template", "    half.", "", "  NOT VERIFIED", "", "    The build has not been run.");
     return lines;
 }
 function dependencyBlock(deps) {

package/dist/preview/api.d.ts

@@ -1,4 +1,5 @@
 import type { ResolvedConfig } from "../shared/config.js";
+import type { CountLimitDetail } from "../shared/countLimit.js";
 import { BackendError } from "../lib/backend.js";
 /** The mint response. Its key set is the cross-repo pin (contract table 2.11). */
 export interface MintedPreview {
@@ -28,19 +29,31 @@ export declare class PreviewConflictError extends BackendError {
     constructor(message: string);
 }
 /**
- * The session is gone — `preview_session_ended`, the CLI's terminal branch.
+ * The org is at its concurrent-live-preview ceiling.
+ *
+ * IT IS A SECOND 409 ON THE MINT ROUTE and it is told from the first by its
+ * CODE, never by its status. The two mean opposite things to a creator: a
+ * conflict says a preview for this folder is already running and to go watch it;
+ * the ceiling says no preview started and the organization is full. Collapsing
+ * them would tell a creator at their ceiling to watch a preview that does not
+ * exist.
  *
- * `endReason` is the DISCRIMINATOR the five ending screens need, and it is
- * `undefined` against the API as built: every terminal cause answers this route
- * with a byte-identical body (`{"code":"preview_session_ended","message":"this
- * preview has ended"}`), verified against the running stack with an `abandoned`
- * row and an `expired` row. QA-F3-09 names that exact condition — "if the wire
- * carried one undifferentiated 'ended', the designer's spec would be unbuildable
- * and that is a fork, not a test failure".
+ * It carries the whole detail because the refusal IS the notice: the figures and
+ * the org name are the only things that make it actionable, and the CLI cannot
+ * obtain either anywhere else.
+ */
+export declare class PreviewLimitError extends BackendError {
+    readonly detail: CountLimitDetail;
+    constructor(message: string, detail: CountLimitDetail);
+}
+/**
+ * The session is gone — `preview_session_ended`, the CLI's terminal branch.
  *
- * It is read here anyway so the client half is complete and the seam is one
- * field: the day the API adds `endReason` to the 410 body, the abandoned and
- * hard-max screens separate with no further client change.
+ * `endReason` is the DISCRIMINATOR the ending screens need. The API sends it
+ * inside the error's `detail` (`{"code":"preview_session_ended","message":...,
+ * "detail":{"endReason":"abandoned"}}`), never at the top of the body. It is
+ * `undefined` only for a 410 that carries no reason, which renders the
+ * cause-free ending rather than a guessed one.
  */
 export declare class PreviewEndedError extends BackendError {
     readonly endReason?: string | undefined;

package/dist/preview/api.js

@@ -7,6 +7,8 @@
 import { createHash } from "node:crypto";
 import { realpath } from "node:fs/promises";
 import { BackendError, ProjectUnreachableError } from "../lib/backend.js";
+import { rejectAuthExpired } from "../shared/authError.js";
+import { apiFetch } from "../shared/http.js";
 /** The mint rate limit (§2.16). `retryAfterSec` comes from the header, never the body. */
 export class PreviewRateLimitedError extends BackendError {
     retryAfterSec;
@@ -24,19 +26,35 @@ export class PreviewConflictError extends BackendError {
     }
 }
 /**
- * The session is gone — `preview_session_ended`, the CLI's terminal branch.
+ * The org is at its concurrent-live-preview ceiling.
+ *
+ * IT IS A SECOND 409 ON THE MINT ROUTE and it is told from the first by its
+ * CODE, never by its status. The two mean opposite things to a creator: a
+ * conflict says a preview for this folder is already running and to go watch it;
+ * the ceiling says no preview started and the organization is full. Collapsing
+ * them would tell a creator at their ceiling to watch a preview that does not
+ * exist.
  *
- * `endReason` is the DISCRIMINATOR the five ending screens need, and it is
- * `undefined` against the API as built: every terminal cause answers this route
- * with a byte-identical body (`{"code":"preview_session_ended","message":"this
- * preview has ended"}`), verified against the running stack with an `abandoned`
- * row and an `expired` row. QA-F3-09 names that exact condition — "if the wire
- * carried one undifferentiated 'ended', the designer's spec would be unbuildable
- * and that is a fork, not a test failure".
+ * It carries the whole detail because the refusal IS the notice: the figures and
+ * the org name are the only things that make it actionable, and the CLI cannot
+ * obtain either anywhere else.
+ */
+export class PreviewLimitError extends BackendError {
+    detail;
+    constructor(message, detail) {
+        super(message, 409);
+        this.detail = detail;
+        this.name = "PreviewLimitError";
+    }
+}
+/**
+ * The session is gone — `preview_session_ended`, the CLI's terminal branch.
  *
- * It is read here anyway so the client half is complete and the seam is one
- * field: the day the API adds `endReason` to the 410 body, the abandoned and
- * hard-max screens separate with no further client change.
+ * `endReason` is the DISCRIMINATOR the ending screens need. The API sends it
+ * inside the error's `detail` (`{"code":"preview_session_ended","message":...,
+ * "detail":{"endReason":"abandoned"}}`), never at the top of the body. It is
+ * `undefined` only for a 410 that carries no reason, which renders the
+ * cause-free ending rather than a guessed one.
  */
 export class PreviewEndedError extends BackendError {
     endReason;
@@ -89,7 +107,7 @@ export function parseRetryAfter(raw) {
     return Number.isFinite(n) && n > 0 ? Math.ceil(n) : 60;
 }
 /** POST /projects/{id}/preview-sessions — mint. */
-export async function mintPreviewSession(cfg, projectId, key, fetchImpl = fetch) {
+export async function mintPreviewSession(cfg, projectId, key, fetchImpl = apiFetch) {
     const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/preview-sessions`, {
         method: "POST",
         headers: authHeaders(cfg),
@@ -99,11 +117,19 @@ export async function mintPreviewSession(cfg, projectId, key, fetchImpl = fetch)
         throw new PreviewRateLimitedError(parseRetryAfter(res.headers.get("retry-after")));
     }
     if (!res.ok) {
+        rejectAuthExpired(res);
         const body = await errorBody(res);
         if (res.status === 404) {
             throw new ProjectUnreachableError(body.message ?? "This project is not available to you.");
         }
         if (res.status === 409) {
+            // TWO 409s NOW LAND HERE and the CODE is what separates them. Reading the
+            // status alone would render the ceiling refusal as "a preview is already
+            // running for this folder" — a sentence that is false, that names a
+            // preview the creator does not have, and that sends them to watch it.
+            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");
         }
         throw new BackendError(body.message ?? `could not start a preview (${res.status})`, res.status);
@@ -136,12 +162,13 @@ export function parseMint(raw) {
     return { sessionId, url, edgeUrl, grant, heartbeatSec, expiresAt };
 }
 /** POST /preview-sessions/{id}/heartbeat — keepalive AND re-authorization. */
-export async function heartbeatPreviewSession(cfg, sessionId, fetchImpl = fetch) {
+export async function heartbeatPreviewSession(cfg, sessionId, fetchImpl = apiFetch) {
     const res = await fetchImpl(`${cfg.apiUrl}/preview-sessions/${encodeURIComponent(sessionId)}/heartbeat`, { method: "POST", headers: authHeaders(cfg) });
     if (!res.ok) {
+        rejectAuthExpired(res);
         const body = await errorBody(res);
         if (res.status === 410) {
-            throw new PreviewEndedError(body.message ?? "this preview has ended", typeof body.endReason === "string" ? body.endReason : undefined);
+            throw new PreviewEndedError(body.message ?? "this preview has ended", typeof body.detail?.endReason === "string" ? body.detail.endReason : undefined);
         }
         if (res.status === 404 || res.status === 403) {
             throw new ProjectUnreachableError(body.message ?? "This project is not available to you.");
@@ -161,7 +188,7 @@ export async function heartbeatPreviewSession(cfg, sessionId, fetchImpl = fetch)
  * Surfacing a teardown failure would turn a successful stop into an error the
  * creator cannot act on.
  */
-export async function endPreviewSession(cfg, sessionId, fetchImpl = fetch) {
+export async function endPreviewSession(cfg, sessionId, fetchImpl = apiFetch) {
     try {
         await fetchImpl(`${cfg.apiUrl}/preview-sessions/${encodeURIComponent(sessionId)}`, {
             method: "DELETE",

package/dist/preview/command.d.ts

@@ -12,7 +12,21 @@ export interface PreviewUiDeps {
     filterTester?: string;
     /** Filter the stream to one connection (`--viewer`). */
     filterViewer?: string;
+    /** The resolved dev command, named by the origin-down advisory. */
+    devCommand?: string;
+    /** Where the forwarded port came from, named by the origin-down advisory. */
+    portSource?: "flag" | "vincentt.json" | "default";
+    /**
+     * Whether package.json lists the harness. `false` means the static
+     * no-diagnostics line was shown, so arrivals are printed per device class;
+     * `true` arms the runtime line. Undefined prints neither.
+     */
+    harnessListed?: boolean;
+    /** Injected for tests. Returns a cancel. */
+    schedule?: (fn: () => void, ms: number) => () => void;
 }
+/** How long a viewer may be present with no harness hello before the runtime line. */
+export declare const NO_DIAGNOSTICS_WINDOW_MS = 10000;
 /**
  * PreviewUi owns every line after the mint. It is a pure sink — it takes events
  * and prints strings — so the whole transcript is assertable without a terminal,
@@ -32,6 +46,13 @@ export declare class PreviewUi {
     private hardMaxWarned;
     private tunnelState;
     private ended;
+    /** Device classes already announced by the arrival line. */
+    private readonly arrivedClasses;
+    /** Any connection sent a harness hello in this preview. */
+    private helloSeen;
+    private runtimeArmed;
+    private cancelRuntime;
+    private hiddenAdvised;
     constructor(deps: PreviewUiDeps);
     get connectedCount(): number;
     get totalConnections(): number;
@@ -47,6 +68,14 @@ export declare class PreviewUi {
      * forty assets from announcing itself forty times.
      */
     viewerSeen(label: string, uaClass: UAClass): void;
+    /**
+     * The two no-diagnostics signals, never both in one preview. Keyed on the
+     * tunnel's own viewer signal, which exists with or without a harness; a hello
+     * is what names a tester, so neither line can name one.
+     */
+    private noDiagnosticsSignal;
+    /** The front proxy refused a hidden path. One advisory per preview, naming the first. */
+    hiddenPath(requestPath: string): void;
     viewerGone(label: string): void;
     /**
      * The harness introduced itself on a connection. This is what prints the

package/dist/preview/command.js

@@ -15,6 +15,13 @@ import * as copy from "./copy.js";
 import { PerfThrottle, palette, renderAnnotation, renderEvent, uaLabel, } from "./stream.js";
 import { ViewerRoster } from "./viewers.js";
 import { MAX_TESTERS } from "../relay/testers.js";
+/** How long a viewer may be present with no harness hello before the runtime line. */
+export const NO_DIAGNOSTICS_WINDOW_MS = 10_000;
+function defaultSchedule(fn, ms) {
+    const t = setTimeout(fn, ms);
+    t.unref?.();
+    return () => clearTimeout(t);
+}
 /**
  * PreviewUi owns every line after the mint. It is a pure sink — it takes events
  * and prints strings — so the whole transcript is assertable without a terminal,
@@ -34,6 +41,13 @@ export class PreviewUi {
     hardMaxWarned = false;
     tunnelState = "connecting";
     ended = false;
+    /** Device classes already announced by the arrival line. */
+    arrivedClasses = new Set();
+    /** Any connection sent a harness hello in this preview. */
+    helloSeen = false;
+    runtimeArmed = false;
+    cancelRuntime;
+    hiddenAdvised = false;
     constructor(deps) {
         this.deps = deps;
         this.p = palette(deps.color);
@@ -65,6 +79,7 @@ export class PreviewUi {
      */
     viewerSeen(label, uaClass) {
         const out = this.roster.connect(label, uaClass, this.deps.now());
+        this.noDiagnosticsSignal(uaClass);
         if (out.connect === undefined)
             return;
         this.line("");
@@ -73,6 +88,43 @@ export class PreviewUi {
             this.lines(out.advisory.map((l) => `  ${l}`));
         this.line("");
     }
+    /**
+     * The two no-diagnostics signals, never both in one preview. Keyed on the
+     * tunnel's own viewer signal, which exists with or without a harness; a hello
+     * is what names a tester, so neither line can name one.
+     */
+    noDiagnosticsSignal(uaClass) {
+        if (this.deps.harnessListed === false) {
+            if (this.arrivedClasses.has(uaClass))
+                return;
+            this.arrivedClasses.add(uaClass);
+            this.line("");
+            this.line(`  ${copy.deviceArrived(uaLabel(uaClass))}`);
+            this.line("");
+            return;
+        }
+        if (this.deps.harnessListed !== true || this.runtimeArmed || this.helloSeen)
+            return;
+        this.runtimeArmed = true;
+        const descriptor = uaLabel(uaClass);
+        const schedule = this.deps.schedule ?? defaultSchedule;
+        this.cancelRuntime = schedule(() => {
+            if (this.helloSeen || this.ended)
+                return;
+            this.line("");
+            this.lines(copy.noDiagnosticsRuntime(descriptor).map((l) => `  ${l}`));
+            this.line("");
+        }, NO_DIAGNOSTICS_WINDOW_MS);
+    }
+    /** The front proxy refused a hidden path. One advisory per preview, naming the first. */
+    hiddenPath(requestPath) {
+        if (this.hiddenAdvised)
+            return;
+        this.hiddenAdvised = true;
+        this.line("");
+        this.line(`  ${copy.hiddenPathRefused(requestPath)}`);
+        this.line("");
+    }
     viewerGone(label) {
         const out = this.roster.disconnect(label, this.deps.now());
         this.perf.forget(label);
@@ -89,6 +141,9 @@ export class PreviewUi {
      * fixes.
      */
     testerSeen(label, tester) {
+        this.helloSeen = true;
+        this.cancelRuntime?.();
+        this.cancelRuntime = undefined;
         const out = this.roster.attribute(label, tester);
         if (out.connect === undefined)
             return;
@@ -179,7 +234,10 @@ export class PreviewUi {
             return;
         this.originDown = true;
         this.line("");
-        this.lines(copy.originDown(this.deps.targetUrl).map((l) => `  ${l}`));
+        const settings = this.deps.devCommand !== undefined && this.deps.portSource !== undefined
+            ? { devCommand: this.deps.devCommand, portSource: this.deps.portSource }
+            : undefined;
+        this.lines(copy.originDown(this.deps.targetUrl, settings).map((l) => `  ${l}`));
     }
     originRecovered() {
         this.originDown = false;
@@ -275,6 +333,8 @@ export function endingLines(reason, orgName) {
             return copy.endedUnreachable(orgName);
         case "authz_unconfirmed":
             return copy.endedUnconfirmed();
+        case "auth_expired":
+            return copy.endedAuthExpired();
         case "egress_cap":
             return copy.egressHard();
         case "stopped":