@vincentt-xr/cli 0.9.0 → 0.11.0

package/dist/lib/feedbackCopy.js

@@ -0,0 +1,163 @@
+// Every line `vincentt feedback` writes to STDERR (Flows C1-C6). Pure functions
+// returning string arrays, so the transcripts are assertable without a terminal.
+//
+// The verb has two readers on two streams and they are different audiences:
+// stdout is a MACHINE (one JSON annotation per line, nothing else, ever) and
+// stderr is a HUMAN. Nothing in this file may ever be written to stdout.
+//
+// Two rules govern all of it:
+//   - UNBIDDEN OUTPUT STATES A FACT, NEVER A COMMAND. `--wait` prints on its own
+//     initiative into what is often an agent's input, so no line here names
+//     something to run. Every ending states what is true about the world
+//     ("The preview is still live", "The preview ended") where the CLI's older
+//     verbs would have ended with an instruction.
+//   - An exit code that means "retry is correct" carries NO GLYPH. 64 is neither
+//     a failure nor a success: `✗` would teach a polling host's reader that the
+//     normal case looks broken, and `✓` would claim something happened.
+//
+// The annotation's own content is never echoed here on the `--wait` path. It is
+// viewer-authored and hostile, and the reader is a parked consumer that is about
+// to receive the whole record on stdout anyway.
+/** Flow C1 — the two lines before the park. */
+export function waiting() {
+    return [
+        "  Waiting for feedback from the preview in this folder.",
+        // The verb is ambiguous on first contact — `feedback` could plausibly mean
+        // "send feedback to Vincentt", which is `vincentt dx`. This disambiguates by
+        // naming DIRECTION rather than by issuing an instruction.
+        "  Nothing is sent from here; this only reads what your phone sends.",
+    ];
+}
+/** Flow C6 — the opening line of a watch. */
+export function watching() {
+    return ["  Watching for feedback from the preview in this folder. Ctrl-C to stop."];
+}
+/**
+ * Flow C2 — the ending of a drain. A count and nothing else: a fact about what
+ * this process did, naming no next step.
+ *
+ * It exists because a human running this in their own terminal otherwise reads
+ * three dense JSON lines and cannot tell whether the command is finished. It is
+ * deliberately NOT one line per annotation, which would duplicate the preview
+ * stream's arrival line in a second place and triple the stderr noise of the
+ * exact case this feature exists for.
+ */
+export function handedOver(n) {
+    return ["", `  ${n} handed over.`, ""];
+}
+/**
+ * Flow C3 — the bounded window elapsed. One line, one integer, no glyph.
+ *
+ * `The preview is still live` is the load-bearing half: it is the fact that
+ * makes exit 64 actionable without an instruction. The window is named with its
+ * number because an unexplained stop is worse than the calibration.
+ */
+export function windowElapsed(timeoutMs) {
+    return [
+        "",
+        `  No feedback in the last ${windowLabel(timeoutMs)}. The preview is still live.`,
+        "",
+    ];
+}
+/** Whole minutes read as minutes; anything else reads as seconds. */
+function windowLabel(timeoutMs) {
+    const seconds = Math.max(Math.round(timeoutMs / 1000), 0);
+    if (seconds >= 60 && seconds % 60 === 0) {
+        const minutes = seconds / 60;
+        return `${minutes} ${minutes === 1 ? "minute" : "minutes"}`;
+    }
+    return `${seconds} ${seconds === 1 ? "second" : "seconds"}`;
+}
+/**
+ * Flow C4 — the session ended. `✗`, because this one stops: 65 is not a fault,
+ * but it is the end of a channel, and the glyph separates it from 64 at a glance
+ * in scrollback.
+ *
+ * The last line answers the creator's actual fear ("did my annotations die with
+ * the preview?") before they can ask it. It does NOT say to start a preview —
+ * that precondition is stated in `--help`, which is where a recipe reads it.
+ *
+ * `0 already handed over` reads slightly oddly and is the price of one sentence
+ * covering both counts; suppressing the line at zero would make the ending's
+ * shape depend on the count and give a reader two endings to learn.
+ */
+export function sessionEnded(handed) {
+    return [
+        "",
+        "✗ The preview ended. Nothing more can arrive on it.",
+        "",
+        `  Nothing was missed — the ${handed} already handed over stay handed over.`,
+        "",
+    ];
+}
+/**
+ * The triage detail behind a 65, one flag away.
+ *
+ * The two paths print IDENTICALLY by default: a polling host reaches 65 on every
+ * re-park once a preview has ended, and a creator cannot act on the difference
+ * between a graceful teardown and a killed process. The distinction belongs to
+ * whoever is diagnosing, not to the hot path.
+ */
+export function sessionEndedDetail(reason, tree, cursor) {
+    const which = reason === "signalled"
+        ? "The preview signalled it was ending"
+        : "The relay stopped answering (no teardown signal)";
+    return [`  ${which} · ${tree}`, `  Cursor unchanged at ${cursor}.`, ""];
+}
+/** Flow C6 — a human stopped a watch. The preview is not what ended. */
+export function stoppedWatching() {
+    return ["", "  Stopped watching. The preview is still live.", ""];
+}
+/** Flow C5 — the usage error. */
+export const USAGE = "Usage: vincentt feedback --wait | --watch [--timeout <seconds>]";
+/** Content indent + the time column + its gutter — where the tester starts. */
+const TESTER_COL = 9;
+export function watchEntry(e, columns) {
+    const time = clockLabel(e.createdAt);
+    const tester = e.tester ?? "";
+    const head = `  ${time}  ${tester}`;
+    const gutter = " ".repeat(TESTER_COL);
+    // The message is viewer-authored and hostile. A raw `\n` or an ANSI escape in
+    // it must not forge a second entry or repaint the screen, so control
+    // characters are STRIPPED (not escaped — this stream is for reading) before
+    // the text is wrapped. stdout's equivalent protection is JSON.stringify.
+    const width = wrapWidth(columns);
+    const indent = " ".repeat(head.length + 2);
+    const body = wrap(stripControl(e.message), Math.max(width - indent.length, 20));
+    const out = [`${head}  ${body[0] ?? ""}`];
+    for (const line of body.slice(1))
+        out.push(`${indent}${line}`);
+    out.push(`${gutter}${stripControl(e.screenshotPath)}`);
+    return out;
+}
+function clockLabel(createdAt) {
+    const d = new Date(createdAt);
+    if (Number.isNaN(d.getTime()))
+        return "--:--";
+    return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+}
+function wrapWidth(columns) {
+    return columns !== undefined && columns >= 40 ? columns : 80;
+}
+/**
+ * C0 and C1 controls out, including ESC, CR, LF, NUL and the DEL range. A
+ * replacement character would still occupy a cell for something the tester did
+ * not type, so they are removed rather than substituted.
+ */
+const CONTROL_RE = /[\u0000-\u001f\u007f-\u009f]/gu;
+export function stripControl(s) {
+    return s.replace(CONTROL_RE, "");
+}
+/** Hard wrap at `width`, breaking on spaces where one is available. */
+export function wrap(s, width) {
+    const out = [];
+    let rest = s;
+    while (rest.length > width) {
+        const cut = rest.lastIndexOf(" ", width);
+        const at = cut > 0 ? cut : width;
+        out.push(rest.slice(0, at));
+        rest = rest.slice(cut > 0 ? at + 1 : at);
+    }
+    out.push(rest);
+    return out;
+}

package/dist/lib/initFrom.d.ts

@@ -23,13 +23,31 @@ export interface RegisterDeps {
         message: string;
     }>;
     /**
-     * f2's shipped `createCommand`, injected. Returns the exit code; it owns the
+     * f2's shipped registration half, injected. Returns the exit code; it owns the
      * binding write, which happens ONLY after the 201.
      */
     create: (opts: {
         name: string;
         slug: string;
     }) => Promise<number>;
+    /**
+     * Whether a scaffold ran above this call. It changes exactly one word, and that
+     * word is the on-disk state: "Nothing else was written." (source exists) versus
+     * "Nothing was written." (it does not).
+     *
+     * `create` in an ALREADY-scaffolded folder (case 2) reaches this orchestrator
+     * without having written anything, so the shipped default — true, f6's combined
+     * path, where a clone always precedes it — would tell that creator their source
+     * was written by this command.
+     */
+    scaffolded?: boolean;
+    /**
+     * Whether the resume block carries a `cd <dir>`. `create` run in the cwd has
+     * nowhere to cd to, so the line would be `cd .`.
+     *
+     * Defaults to true: f6's path always scaffolds INTO a named directory.
+     */
+    resumeNeedsCd?: boolean;
 }
 export type OrgSource = "active" | "env" | "flag";
 export interface RegisterOptions {
@@ -39,9 +57,13 @@ export interface RegisterOptions {
     slug?: string;
 }
 /**
- * The registration half. Runs ONLY after the scaffold reported success, so the
- * source is already on disk in every branch below — which is why every failure
- * closes with "Nothing else was written." rather than "Nothing was written."
+ * The registration half — the below-the-seam orchestrator shared by `init --from`
+ * (f6) and by `vincentt create` (create-scaffolds). One implementation, because a
+ * second implementation of f2's rules is a second place for them to be wrong.
+ *
+ * `deps.scaffolded` says whether source was written above this call, and it decides
+ * one word in every failure's last line: that word IS the on-disk state, read at a
+ * glance in scrollback by someone who wants exactly one bit of information.
  */
 export declare function registerAfterScaffold(deps: RegisterDeps, opts?: RegisterOptions): Promise<number>;
 /** The `· from owner/repo@tag` bullet in the start block. */

package/dist/lib/initFrom.js

@@ -23,23 +23,47 @@ const ORG_SOURCE_LABEL = {
 function reassure(print, dirLabel) {
     print(`  Your source is fine — ${dirLabel} is on disk and it's yours.`);
 }
-/** The resume block: `cd <dir>` then the exact create command. */
-function resume(print, dirLabel, command) {
-    print(`  cd ${stripLeadingDotSlash(dirLabel)}`);
+/** The resume block: `cd <dir>` (when there is one) then the exact create command. */
+function resume(print, dirLabel, command, needsCd = true) {
+    if (needsCd)
+        print(`  cd ${stripLeadingDotSlash(dirLabel)}`);
     print(`  ${command}`);
 }
 function stripLeadingDotSlash(label) {
     return label.startsWith("./") ? label.slice(2) : label;
 }
 /**
- * The registration half. Runs ONLY after the scaffold reported success, so the
- * source is already on disk in every branch below — which is why every failure
- * closes with "Nothing else was written." rather than "Nothing was written."
+ * The registration half — the below-the-seam orchestrator shared by `init --from`
+ * (f6) and by `vincentt create` (create-scaffolds). One implementation, because a
+ * second implementation of f2's rules is a second place for them to be wrong.
+ *
+ * `deps.scaffolded` says whether source was written above this call, and it decides
+ * one word in every failure's last line: that word IS the on-disk state, read at a
+ * glance in scrollback by someone who wants exactly one bit of information.
  */
 export async function registerAfterScaffold(deps, opts = {}) {
     const defaultName = opts.name ?? path.basename(path.resolve(deps.targetDir));
     const defaultSlug = opts.slug ?? slugify(defaultName);
     const resumeCommand = `vincentt create --name "${defaultName}" --slug ${defaultSlug || "<address>"}`;
+    const scaffolded = deps.scaffolded ?? true;
+    const needsCd = deps.resumeNeedsCd ?? true;
+    const closing = scaffolded ? "  Nothing else was written." : "  Nothing was written.";
+    // Reached two ways — runLogin threw, and runLogin returned with still no token
+    // (the creator closed the tab). One creator-visible outcome, so one block: two
+    // copies of nine lines diverge on the first edit to either.
+    const printSignInAbandoned = () => {
+        deps.print("");
+        deps.print("✗ Sign-in was not completed.");
+        deps.print("");
+        if (scaffolded)
+            reassure(deps.print, deps.dirLabel);
+        deps.print("  The project was not registered, so no address is reserved yet.");
+        deps.print("");
+        deps.print("  Finish when you're ready:");
+        resume(deps.print, deps.dirLabel, "vincentt create", needsCd);
+        deps.print("");
+        deps.print(closing);
+    };
     // TRAP 2 inverted deliberately: the session is checked AFTER the scaffold, and
     // `ensureLoggedIn` is only reachable on a TTY because it opens a browser.
     const token = await deps.currentToken();
@@ -48,48 +72,45 @@ export async function registerAfterScaffold(deps, opts = {}) {
             deps.print("");
             deps.print("✗ Not signed in, and signing in needs a browser.");
             deps.print("");
-            reassure(deps.print, deps.dirLabel);
+            if (scaffolded)
+                reassure(deps.print, deps.dirLabel);
             deps.print("  No address is reserved yet.");
             deps.print("");
             deps.print("  On a machine with a browser:");
             deps.print("  vincentt login");
             deps.print("");
             deps.print("  Then finish:");
-            resume(deps.print, deps.dirLabel, resumeCommand);
+            resume(deps.print, deps.dirLabel, resumeCommand, needsCd);
             deps.print("");
-            deps.print("  Nothing else was written.");
+            deps.print(closing);
             return 1;
         }
         deps.print("");
         deps.print("→ Now registering the project so it gets an address.");
         deps.print("  You're not signed in yet — opening the browser to authorize this device…");
+        // The open path's load-bearing home, and the only new sentence in this flow.
+        // The reader is a human holding working source who is being asked for an
+        // account thirty seconds after watching an app appear on their disk — the one
+        // person for whom "you did not have to" is news, and nobody reads `--help` at
+        // the moment they are being asked to sign in. It is a statement of FACT, not
+        // an offer to abort: their source is already on disk, so the sentence has no
+        // action attached and costs the reader nothing.
+        //
+        // Only when a scaffold actually happened. In an already-scaffolded folder the
+        // creator has source `init` did not write, so the sentence would be advice to
+        // re-run a verb that has nothing left to do.
+        if (scaffolded) {
+            deps.print("  (`vincentt init` scaffolds with no account at all, if you'd rather not sign in.)");
+        }
         try {
             await deps.runLogin();
         }
         catch {
-            deps.print("");
-            deps.print("✗ Sign-in was not completed.");
-            deps.print("");
-            reassure(deps.print, deps.dirLabel);
-            deps.print("  The project was not registered, so no address is reserved yet.");
-            deps.print("");
-            deps.print("  Finish when you're ready:");
-            resume(deps.print, deps.dirLabel, "vincentt create");
-            deps.print("");
-            deps.print("  Nothing else was written.");
+            printSignInAbandoned();
             return 1;
         }
         if (!(await deps.currentToken())) {
-            deps.print("");
-            deps.print("✗ Sign-in was not completed.");
-            deps.print("");
-            reassure(deps.print, deps.dirLabel);
-            deps.print("  The project was not registered, so no address is reserved yet.");
-            deps.print("");
-            deps.print("  Finish when you're ready:");
-            resume(deps.print, deps.dirLabel, "vincentt create");
-            deps.print("");
-            deps.print("  Nothing else was written.");
+            printSignInAbandoned();
             return 1;
         }
     }
@@ -98,13 +119,14 @@ export async function registerAfterScaffold(deps, opts = {}) {
         deps.print("");
         deps.print("✗ Can't register the project without a name and an address, and I can't ask.");
         deps.print("");
-        reassure(deps.print, deps.dirLabel);
+        if (scaffolded)
+            reassure(deps.print, deps.dirLabel);
         deps.print("  No address is reserved yet.");
         deps.print("");
         deps.print("  Finish it:");
-        resume(deps.print, deps.dirLabel, resumeCommand);
+        resume(deps.print, deps.dirLabel, resumeCommand, needsCd);
         deps.print("");
-        deps.print("  Nothing else was written.");
+        deps.print(closing);
         return 1;
     }
     const org = await deps.resolveOrg();
@@ -112,15 +134,15 @@ export async function registerAfterScaffold(deps, opts = {}) {
         deps.print("");
         deps.print(org.message);
         deps.print("");
-        reassure(deps.print, deps.dirLabel);
+        if (scaffolded)
+            reassure(deps.print, deps.dirLabel);
         deps.print("  No address is reserved yet.");
         deps.print("");
         deps.print("  Check who you are:  vincentt whoami");
         deps.print("  Then finish:");
-        deps.print(`  cd ${stripLeadingDotSlash(deps.dirLabel)}`);
-        deps.print("  vincentt create --org <workspace>");
+        resume(deps.print, deps.dirLabel, "vincentt create --org <workspace>", needsCd);
         deps.print("");
-        deps.print("  Nothing else was written.");
+        deps.print(closing);
         return 1;
     }
     // AF-3: name the org AND where it came from, before the address prompt. The
@@ -157,7 +179,8 @@ export async function registerAfterScaffold(deps, opts = {}) {
                 deps.print("");
                 deps.print("✗ That address is taken.");
                 deps.print("");
-                reassure(deps.print, deps.dirLabel);
+                if (scaffolded)
+                    reassure(deps.print, deps.dirLabel);
                 deps.print("  No address is reserved yet.");
                 if (err.suggestions.length > 0) {
                     deps.print("");
@@ -169,17 +192,18 @@ export async function registerAfterScaffold(deps, opts = {}) {
                 deps.print(deps.ask
                     ? "  Finish with an address of your own:"
                     : "  Finish with one of those, or your own:");
-                deps.print(`  cd ${stripLeadingDotSlash(deps.dirLabel)}`);
-                deps.print(`  vincentt create --name "${name}" --slug <address>`);
+                resume(deps.print, deps.dirLabel, `vincentt create --name "${name}" --slug <address>`, needsCd);
                 deps.print("");
-                deps.print("  Nothing else was written.");
+                deps.print(closing);
                 return 1;
             }
             // A routine, expected collision mid-flow: `!` and a re-ask, not `✗` and an
             // exit. The command DOES proceed, so a `✗` would announce a stop that is
             // not happening.
             deps.print("");
-            deps.print("! That address is taken. Your source is fine — pick another.");
+            deps.print(scaffolded
+                ? "! That address is taken. Your source is fine — pick another."
+                : "! That address is taken. Pick another.");
             if (err.suggestions.length > 0) {
                 deps.print("");
                 deps.print("  Available alternatives:");

package/dist/lib/lifecycle.d.ts

@@ -1,3 +1,5 @@
+import type { OrgSource } from "./initFrom.js";
+import type { Ask } from "../publish/prompt.js";
 import { type ResolvedOrg } from "./org.js";
 import { type RelayClient } from "./diagnostics.js";
 import { type ResolvedConfig } from "../shared/config.js";
@@ -12,6 +14,18 @@ export interface CreateOptions {
     org?: string;
     /** Honor a binding's apiUrl override (--allow-custom-api). */
     allowCustomApi?: boolean;
+    /** The positional, already through `sanitizeAppName`. Resolves against the cwd. */
+    dir?: string;
+    /** `--no-install`, the same meaning it has on `init`. */
+    skipInstall?: boolean;
+    /** Free-text prompt. Absent → not a TTY, so nothing may be asked. */
+    ask?: Ask;
+    /** The PAT that would authenticate a call, if any. Never triggers a login. */
+    currentToken?: () => Promise<string | undefined>;
+    /** The interactive browser login. Only ever reached on a TTY. */
+    runLogin?: () => Promise<void>;
+    /** Where the resolved org came from, so a surprising value is diagnosable. */
+    orgSource?: () => OrgSource;
     /**
      * Stream the transcript as it happens. The CLI passes console.log so a slow
      * create shows progress and the apiUrl advisory lands before the request; MCP
@@ -30,8 +44,9 @@ export interface CreateResult {
  * `project_create` tool, so the two surfaces can never diverge in behavior OR in
  * what they tell the caller.
  *
- * It does NOT scaffold — that is `vincentt init`, which needs no account. See
- * `initCommand`.
+ * A two-half verb: it scaffolds an EMPTY folder from the standard starter, only
+ * registers a folder that is already a Vincentt app, and refuses anything else.
+ * See `createCommand`.
  */
 export declare function projectCreate(projectCwd: string, opts?: CreateOptions): Promise<CreateResult>;
 /**
@@ -95,6 +110,16 @@ export interface PreviewStopOutcome {
     stopped: boolean;
     message: string;
 }
+export interface PreviewStopDeps {
+    /**
+     * The relay to ask for presence. Injected for tests; in production it is built
+     * from the marker's port. A client that throws, hangs, or answers a body of
+     * the wrong shape yields NO count, which yields no line.
+     */
+    relay?: RelayClient;
+    /** Injected so the SIGTERM is observable without signalling a real process. */
+    kill?: (pid: number, signal: NodeJS.Signals) => void;
+}
 /**
  * Stop a preview started by a *different* process (the common case: `vincentt
  * preview` runs in the background and the agent later wants it down). Reads the
@@ -107,7 +132,7 @@ export interface PreviewStopOutcome {
  * closes, the edge sees the tunnel go, and the session drains on its own — so
  * SIGTERM plus clearing the stale relay info is the whole of the cleanup.
  */
-export declare function previewStopSignal(projectCwd: string): Promise<PreviewStopOutcome>;
+export declare function previewStopSignal(projectCwd: string, deps?: PreviewStopDeps): Promise<PreviewStopOutcome>;
 export interface DiagQueryOptions {
     since?: number;
     limit?: number;

package/dist/lib/lifecycle.js

@@ -3,6 +3,7 @@
 // lower-level pieces (backend calls, scaffold, preview, diagnostics); no CLI or
 // MCP SDK concerns leak in here. Both surfaces render the returned data their
 // own way.
+import path from "node:path";
 import { getMe } from "./backend.js";
 import { createCommand } from "./projects.js";
 import { publishCommand } from "../publish/command.js";
@@ -11,13 +12,18 @@ import { filterErrors, httpRelayClient, renderResult, } from "./diagnostics.js";
 import { clearRelayInfo, readLivePreview, readRelayInfo, writeRelayInfo, } from "./relayInfo.js";
 import { loadMachineConfig, locateProjectBinding, resolveConfig, } from "../shared/config.js";
 import { startPreview, } from "../preview/index.js";
+// The SHIPPED stopping line, reused rather than reworded: the interrupt path and
+// this path are one sentence about one event, and it says CONNECTIONS because one
+// tab opens several under HTTP/1.1 (preview/copy.ts).
+import * as previewCopy from "../preview/copy.js";
 /**
  * The shared `create` orchestration behind both `vincentt create` and the MCP
  * `project_create` tool, so the two surfaces can never diverge in behavior OR in
  * what they tell the caller.
  *
- * It does NOT scaffold — that is `vincentt init`, which needs no account. See
- * `initCommand`.
+ * A two-half verb: it scaffolds an EMPTY folder from the standard starter, only
+ * registers a folder that is already a Vincentt app, and refuses anything else.
+ * See `createCommand`.
  */
 export async function projectCreate(projectCwd, opts = {}) {
     const lines = [];
@@ -25,11 +31,16 @@ export async function projectCreate(projectCwd, opts = {}) {
         lines.push(line);
         opts.onLine?.(line);
     };
+    // ONE target: the positional names a child of `projectCwd`, and the config must
+    // be read from the folder the verb ACTS on, not from its parent — a parent's
+    // binding carrying an apiUrl override would otherwise decide where the child's
+    // project is registered.
+    const target = opts.dir ? path.resolve(projectCwd, opts.dir) : path.resolve(projectCwd);
     // Resolved once, lazily: a create refused by a local guard must not require a
     // PAT and must not reach the network at all.
     let cached;
     const config = async () => {
-        cached ??= await resolveConfig(projectCwd, {
+        cached ??= await resolveConfig(target, {
             allowCustomApi: opts.allowCustomApi,
             warn: print,
         });
@@ -40,7 +51,17 @@ export async function projectCreate(projectCwd, opts = {}) {
         cwd: projectCwd,
         config,
         org: async () => resolveOrgForCommand(await config(), { flag: opts.org }),
-    }, { name: opts.name, slug: opts.slug, force: opts.force });
+        ask: opts.ask,
+        currentToken: opts.currentToken,
+        runLogin: opts.runLogin,
+        orgSource: opts.orgSource,
+    }, {
+        name: opts.name,
+        slug: opts.slug,
+        force: opts.force,
+        dir: opts.dir,
+        skipInstall: opts.skipInstall,
+    });
     return { message: lines.join("\n"), exitCode };
 }
 /**
@@ -171,6 +192,51 @@ function isAlive(pid) {
         return false;
     }
 }
+/** The bound the caller is held to: one query, no retry, isRelayResponding's window. */
+const PRESENCE_TIMEOUT_MS = 700;
+/**
+ * How many connections are attached, or UNDEFINED when that cannot be
+ * established — and undefined is a first-class answer here, not an error.
+ *
+ * ⚠ THE WRONG SOURCE IS IN THE SAME RESPONSE OBJECT. A `RelayResult` carries
+ * `viewers[]` and `testers[]`, and when `liveConnections` is absent those arrays
+ * are frequently NON-EMPTY, because they are ever-seen sets the store never
+ * prunes (relay/store.ts:14-31). `result.viewers.length` therefore returns a
+ * plausible number at exactly the moment the real count is unknown, and printing
+ * it claims a phone that closed its tab twenty minutes ago is still watching.
+ * There is NO FALLBACK here on purpose: no `?? 0`, no `viewers.length`. Absent
+ * means unknown, and unknown prints nothing.
+ */
+async function readLiveConnections(relay) {
+    // BOUNDED, not rate-limited: one query, the same window isRelayResponding
+    // uses, no retry. The relay has no limiter and this branch reads two in-memory
+    // integers; the discipline belongs on the caller.
+    const timeout = new Promise((resolve) => setTimeout(() => resolve(undefined), PRESENCE_TIMEOUT_MS).unref?.());
+    let result;
+    try {
+        result = await Promise.race([relay.query({ presence: true, limit: 0 }), timeout]);
+    }
+    catch {
+        // Refused, non-JSON, a non-2xx — every one of them is "no count".
+        return undefined;
+    }
+    if (result === undefined)
+        return undefined;
+    // The SHAPE is the identity proof, the same one isRelayResponding applies: a
+    // stranger on a reused port does not answer a RelayResult. Only after the
+    // envelope is recognised is the count itself read, and it must be a real
+    // non-negative integer — a relay that predates the field sends none.
+    if (typeof result !== "object" ||
+        result === null ||
+        !Array.isArray(result.events) ||
+        typeof result.latestSeq !== "number") {
+        return undefined;
+    }
+    const n = result.liveConnections;
+    if (typeof n !== "number" || !Number.isInteger(n) || n < 0)
+        return undefined;
+    return n;
+}
 /**
  * Stop a preview started by a *different* process (the common case: `vincentt
  * preview` runs in the background and the agent later wants it down). Reads the
@@ -183,17 +249,43 @@ function isAlive(pid) {
  * closes, the edge sees the tunnel go, and the session drains on its own — so
  * SIGTERM plus clearing the stale relay info is the whole of the cleanup.
  */
-export async function previewStopSignal(projectCwd) {
+export async function previewStopSignal(projectCwd, deps = {}) {
     const info = await readRelayInfo(projectCwd);
     if (!info) {
         return { stopped: false, message: "No preview is running for this directory." };
     }
     const previewAlive = info.pid !== undefined && isAlive(info.pid);
     if (previewAlive) {
+        // PRESENCE IS READ BEFORE THE SIGNAL, and the order is the feature. The
+        // creator is about to blank someone's screen, so the count has to describe
+        // the moment before that happens; asking after the SIGTERM would race the
+        // 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 connected = await readLiveConnections(relay);
         try {
-            process.kill(info.pid, "SIGTERM");
+            (deps.kill ?? ((pid, sig) => process.kill(pid, sig)))(info.pid, "SIGTERM");
             await clearRelayInfo(projectCwd);
-            return { stopped: true, message: "✓ Preview stopped. The link no longer works." };
+            // A TRUE ZERO AND AN UNAVAILABLE COUNT PRODUCE THE IDENTICAL BYTES, and
+            // that is the decision rather than an accident. `stopping(0)` is the bare
+            // `→ Stopping…`, which carries no count — so emitting it on a confirmed
+            // zero while omitting it on an unknown would make the two distinguishable
+            // by a line that says nothing either way, and a creator could read the
+            // difference as meaning something. The line is emitted only when there is
+            // a count to state; both silent states collapse.
+            //
+            // "0 connections open" is the other tempting answer and it is refused for
+            // the same reason `stopping()` already refuses it: it would be a claim,
+            // and in the unavailable case a false one. Silence claims nothing.
+            const line = connected === undefined || connected === 0
+                ? undefined
+                : previewCopy.stopping(connected);
+            const lines = [
+                ...(line === undefined ? [] : [line]),
+                "✓ Preview stopped. The link no longer works.",
+            ];
+            return { stopped: true, message: lines.join("\n") };
         }
         catch {
             // Raced with its own exit; the socket is gone either way.