@vincentt-xr/cli 0.9.0 → 0.11.0

package/dist/cli/verb-surface.js

@@ -0,0 +1,49 @@
+// The accepted-verb surface, pinned. B-F3-8: a verb may be added or aliased,
+// never renamed or removed — grounding naming these verbs ships into creators'
+// repositories and is never read back, so a rename is unseeable, unwarnable and
+// unfixable. Append only; never edit or delete a line.
+// prettier-ignore
+export const PINNED_VERBS = [
+    "version", "login", "logout", "whoami",
+    "init", "create", "link", "unlink",
+    "publish", "preview",
+    "logs", "network", "trace",
+    "feedback", "relay", "assets", "dx",
+    // Appended: a read-only listing. Nothing above was renamed or removed, which
+    // is the whole of what B-F3-8 pins — an addition is always permitted.
+    "projects",
+];
+// The dispatch's verb set, as data. `main()` switches over this, so the two can
+// never disagree: a verb added to the CLI is a key added here, and QA-AHG-01
+// reads it as the converse arm of the pin.
+export const VERB_HANDLERS = {
+    version: true,
+    login: true,
+    logout: true,
+    whoami: true,
+    init: true,
+    create: true,
+    link: true,
+    unlink: true,
+    publish: true,
+    preview: true,
+    logs: true,
+    network: true,
+    trace: true,
+    feedback: true,
+    relay: true,
+    assets: true,
+    dx: true,
+    projects: true,
+};
+// Answers "is this a verb this CLI accepts" without running it. The
+// console-redirect strings are NOT accepted here: they reach their explanation
+// through the dispatch's default branch, and treating them as verbs would put
+// the console's vocabulary inside B-F3-8.
+export function resolveVerb(cmd) {
+    if (cmd === undefined)
+        return undefined;
+    return Object.prototype.hasOwnProperty.call(VERB_HANDLERS, cmd)
+        ? cmd
+        : undefined;
+}

package/dist/dx/clusters.d.ts

@@ -1,20 +1,3 @@
-/**
- * Friction detection over journal entries.
- *
- * Two cluster types, because the two halves of "DX" fail differently:
- *
- *  - `error` — the caller fought the tool and it pushed back. This is the
- *    classic retry loop (guessed a flag, got an error, tried again).
- *  - `repetition` — the caller ran the same thing repeatedly and it WORKED
- *    every time. No error is ever raised, so an error-keyed detector is blind
- *    to it, yet it is friction: the caller didn't know the first run had
- *    already given them what they needed. The reported case that motivated
- *    this file was exactly that shape — repeated `preview` runs, each one
- *    succeeding, each one minting a fresh link.
- *
- * Detection is deliberately loose. A false positive costs a line in a report a
- * human is already reading; a miss costs a DX gap nobody ever hears about.
- */
 import type { JournalEntry } from "./journal.js";
 export type ClusterKind = "error" | "repetition";
 export interface Cluster {

package/dist/dx/clusters.js

@@ -1,3 +1,47 @@
+/**
+ * Friction detection over journal entries.
+ *
+ * Two cluster types, because the two halves of "DX" fail differently:
+ *
+ *  - `error` — the caller fought the tool and it pushed back. This is the
+ *    classic retry loop (guessed a flag, got an error, tried again).
+ *  - `repetition` — the caller ran the same thing repeatedly and it WORKED
+ *    every time. No error is ever raised, so an error-keyed detector is blind
+ *    to it, yet it is friction: the caller didn't know the first run had
+ *    already given them what they needed. The reported case that motivated
+ *    this file was exactly that shape — repeated `preview` runs, each one
+ *    succeeding, each one minting a fresh link.
+ *
+ * Detection is deliberately loose. A false positive costs a line in a report a
+ * human is already reading; a miss costs a DX gap nobody ever hears about.
+ */
+import { verbOf } from "./skeleton.js";
+/**
+ * Non-zero exits a verb DEFINES as ordinary outcomes, not failures.
+ *
+ * `feedback --wait` exits 64 when its window elapsed with nothing waiting and 65
+ * when the preview ended. Both are facts about the channel, and the whole point
+ * of the verb is that it is re-run in a tight loop: a caller re-parks after every
+ * 64, hundreds of times a day. Counted as errors, those runs read as a
+ * fight-with-the-tool that never happened, and the nudge narrates the intended
+ * loop as friction — on stderr, which in this loop is a caller's own input.
+ *
+ * A verb's neutral exits are ITS OWN. Nothing here generalizes 64/65 across the
+ * CLI; another verb adding a non-zero-but-fine exit adds a row.
+ */
+const NEUTRAL_EXITS = {
+    feedback: new Set([64, 65]),
+};
+/**
+ * Verbs whose contract is "run it again". Repeating them is not a caller failing
+ * to get what they needed on the first try; it is the documented way to use them.
+ */
+const LOOPING_VERBS = new Set(["feedback"]);
+function isFailure(e) {
+    if (e.exit === 0)
+        return false;
+    return !NEUTRAL_EXITS[verbOf(e.skel.split(" "))]?.has(e.exit);
+}
 /** A repetition run must be at least this long to count as friction. */
 const REPETITION_MIN = 3;
 /**
@@ -23,8 +67,12 @@ export function findClusters(entries) {
         let j = i;
         while (j < entries.length && entries[j].skel === skel)
             run.push(entries[j++]);
-        const errors = run.filter((e) => e.exit !== 0).length;
+        const errors = run.filter(isFailure).length;
         const spanMs = span(run);
+        // A verb whose whole contract is "run it again" cannot be detected as
+        // friction by repetition — the repetition IS the design. Its error arm still
+        // applies: an exit 1 from it is a real fault and clusters normally.
+        const loops = LOOPING_VERBS.has(verbOf(skel.split(" ")));
         // A cluster needs at least two calls. A lone failure is usually the tool
         // working — a signed-out `whoami`, a typo'd verb — and reporting each one
         // buries the real findings under noise, which is the failure mode that
@@ -40,6 +88,7 @@ export function findClusters(entries) {
             });
         }
         else if (errors === 0 &&
+            !loops &&
             run.length >= REPETITION_MIN &&
             spanMs <= REPETITION_WINDOW_MS) {
             clusters.push({

package/dist/lib/backend.d.ts

@@ -43,6 +43,17 @@ export declare class ProjectUnreachableError extends BackendError {
  * a creator's address is always a name they chose.
  */
 export declare function createProject(cfg: ResolvedConfig, orgSlug: string, name: string, slug?: string): Promise<CreatedProject>;
+/**
+ * List an org's projects. A READ, and the only new call `vincentt projects`
+ * makes — the same path `createProject` POSTs to, which is why the org is a slug
+ * here and not a bare id.
+ *
+ * The wire shape is `{projects: [...]}`, each member the same `projectView`
+ * `GET /projects/{id}` returns, so it goes through `parseProjectView` rather
+ * than a second reader: two parsers for one shape is how a contract break
+ * survives a green suite on one of them.
+ */
+export declare function listProjects(cfg: ResolvedConfig, orgSlug: string): Promise<ProjectView[]>;
 /** Read a project by id. Backs `link`; the org is derived server-side from the row. */
 export declare function getProject(cfg: ResolvedConfig, projectId: string): Promise<ProjectView>;
 export interface MintedTunnel {

package/dist/lib/backend.js

@@ -95,6 +95,29 @@ export async function createProject(cfg, orgSlug, name, slug) {
         liveUrl: p.liveUrl,
     };
 }
+/**
+ * List an org's projects. A READ, and the only new call `vincentt projects`
+ * makes — the same path `createProject` POSTs to, which is why the org is a slug
+ * here and not a bare id.
+ *
+ * The wire shape is `{projects: [...]}`, each member the same `projectView`
+ * `GET /projects/{id}` returns, so it goes through `parseProjectView` rather
+ * than a second reader: two parsers for one shape is how a contract break
+ * survives a green suite on one of them.
+ */
+export async function listProjects(cfg, orgSlug) {
+    const res = await authFetch(cfg, `/orgs/${encodeURIComponent(orgSlug)}/projects`);
+    if (!res.ok) {
+        const body = await errorBody(res);
+        throw new BackendError(res.status === 401
+            ? authFailureMessage("list projects failed", res.status, await safeText(res))
+            : (body.message ??
+                `list projects failed (${res.status}): ${await safeText(res)}`), res.status);
+    }
+    const raw = (await res.json());
+    const rows = Array.isArray(raw.projects) ? raw.projects : [];
+    return rows.map((p) => parseProjectView(p, "list projects"));
+}
 /** Read a project by id. Backs `link`; the org is derived server-side from the row. */
 export async function getProject(cfg, projectId) {
     const res = await authFetch(cfg, `/projects/${encodeURIComponent(projectId)}`);

package/dist/lib/classifyTarget.d.ts

@@ -0,0 +1,42 @@
+export type FolderCase = "vincentt-app" | "empty" | "occupied";
+/** Only the two fields the classifier reads, so a probe is trivial to fake. */
+export interface TargetStat {
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+}
+export interface ClassifyProbes {
+    looksLikeApp?: (dir: string) => Promise<boolean>;
+    /** lstat, NEVER stat — see rule 2. */
+    lstat?: (dir: string) => Promise<TargetStat>;
+    readdir?: (dir: string) => Promise<string[]>;
+}
+/**
+ * Which of the three cases the target directory is in.
+ *
+ * Four rules, each of which a caller depends on:
+ *
+ *  1. `ENOENT` is the ONLY error that means empty. `EACCES`, `EPERM`, `ENOTDIR`,
+ *     `ELOOP`, `ENAMETOOLONG` and anything unforeseen all return `occupied` —
+ *     "I could not establish that this is safe to write into" is a refusal.
+ *  2. `lstat`, never `stat`. A symlink is `occupied` whatever it points at;
+ *     `stat` follows it, which is how a scaffold writes outside the directory
+ *     the creator named.
+ *  3. A non-directory is `occupied`. A regular file at the path is not an empty
+ *     folder.
+ *  4. A `readdir` that throws after a successful `lstat` (a TOCTOU window, or a
+ *     permission change) is `occupied`. The unknown answer is never the writing
+ *     answer.
+ *
+ * `looksLikeApp` runs FIRST and unconditionally: order is the contract, because
+ * case 2 is defined by BEING a Vincentt app, not by what else is in the folder.
+ *
+ * Both IO probes are injected so every arm — including the error arms — is
+ * testable with no real filesystem. That matters for more than convenience: a
+ * mode-000 directory is a no-op as root, so a test staged on a real filesystem
+ * would pass for the wrong reason in CI.
+ *
+ * NOTE: the classifier answers a question at a MOMENT. The window between this
+ * answer and the write is closed by the writer's own guards (a non-recursive
+ * mkdir, and a realpath re-check), not here.
+ */
+export declare function classifyTarget(dir: string, probes?: ClassifyProbes): Promise<FolderCase>;

package/dist/lib/classifyTarget.js

@@ -0,0 +1,83 @@
+// The three-way folder classification `vincentt create` acts on, and it FAILS
+// CLOSED.
+//
+// `create` used to be a pure registration verb, so "is this a Vincentt app" was a
+// HINT: a wrong answer cost one advisory line. It now decides whether ~30 template
+// files get written, so a wrong answer is a silent write into a directory the
+// creator cares about. That is the hint-becomes-a-gate transition, and it is why
+// this is a security control with its own file rather than another export from
+// projects.ts.
+//
+// This deliberately does NOT call `isNonEmptyDir` (scaffold/index.ts). That
+// predicate catches EVERY error and returns false, which this design would read as
+// "empty". Four measured mis-answers it gives: a mode-000 directory holding files,
+// a symlink to an empty directory (the scaffold writes THROUGH the link, outside
+// the parent the creator named), a dangling symlink, and a regular file at the
+// path. Under `init` a false-empty reaches a confirm prompt a human sees; here it
+// reaches a silent write. `isNonEmptyDir` is left exactly as it is and keeps
+// serving `init`, where its error contract is correct: two predicates, two
+// contracts, each stated in terms of what its caller does with the answer.
+//
+// `needsScaffold` is not used either: it answers only "has a package.json", so a
+// stranger's non-Vincentt Node app lands in its scaffoldable arm.
+import { promises as fs } from "node:fs";
+import { looksLikeVincenttApp } from "./projects.js";
+/**
+ * Which of the three cases the target directory is in.
+ *
+ * Four rules, each of which a caller depends on:
+ *
+ *  1. `ENOENT` is the ONLY error that means empty. `EACCES`, `EPERM`, `ENOTDIR`,
+ *     `ELOOP`, `ENAMETOOLONG` and anything unforeseen all return `occupied` —
+ *     "I could not establish that this is safe to write into" is a refusal.
+ *  2. `lstat`, never `stat`. A symlink is `occupied` whatever it points at;
+ *     `stat` follows it, which is how a scaffold writes outside the directory
+ *     the creator named.
+ *  3. A non-directory is `occupied`. A regular file at the path is not an empty
+ *     folder.
+ *  4. A `readdir` that throws after a successful `lstat` (a TOCTOU window, or a
+ *     permission change) is `occupied`. The unknown answer is never the writing
+ *     answer.
+ *
+ * `looksLikeApp` runs FIRST and unconditionally: order is the contract, because
+ * case 2 is defined by BEING a Vincentt app, not by what else is in the folder.
+ *
+ * Both IO probes are injected so every arm — including the error arms — is
+ * testable with no real filesystem. That matters for more than convenience: a
+ * mode-000 directory is a no-op as root, so a test staged on a real filesystem
+ * would pass for the wrong reason in CI.
+ *
+ * NOTE: the classifier answers a question at a MOMENT. The window between this
+ * answer and the write is closed by the writer's own guards (a non-recursive
+ * mkdir, and a realpath re-check), not here.
+ */
+export async function classifyTarget(dir, probes = {}) {
+    const looksLikeApp = probes.looksLikeApp ?? looksLikeVincenttApp;
+    const lstat = probes.lstat ?? ((d) => fs.lstat(d));
+    const readdir = probes.readdir ?? ((d) => fs.readdir(d));
+    if (await looksLikeApp(dir))
+        return "vincentt-app";
+    try {
+        const st = await lstat(dir);
+        if (st.isSymbolicLink())
+            return "occupied";
+        if (!st.isDirectory())
+            return "occupied";
+    }
+    catch (err) {
+        // Read defensively rather than through a helper. `err.code` on a thrown
+        // string or null THROWS, and this catch sits inside a security control: an
+        // exception escaping here would propagate as an unhandled failure of the
+        // whole verb rather than as the refusal the contract promises.
+        const code = err?.code;
+        if (code === "ENOENT")
+            return "empty"; // `create <name>` creates it
+        return "occupied";
+    }
+    try {
+        return (await readdir(dir)).length === 0 ? "empty" : "occupied";
+    }
+    catch {
+        return "occupied";
+    }
+}

package/dist/lib/feedback.d.ts

@@ -2,14 +2,55 @@ import type { Annotation } from "@vincentt-xr/harness/events";
 export declare function cursorPath(cwd: string): string;
 /** Last-consumed annotation seq for this project (0 if none consumed yet). */
 export declare function readCursor(cwd: string): Promise<number>;
-/** Advance the cursor. Called ONLY after the annotation was handed off. */
+/**
+ * Advance the cursor. Called ONLY after the annotation was handed off.
+ *
+ * Temp file + same-directory rename, because `fs.writeFile` is not atomic and a
+ * kill mid-write is reachable on exactly the kill-mid-drain path this channel is
+ * designed around. A torn file reads as 0 under the strict parser, so the
+ * failure degrades to re-delivering the whole run — safe, but noisy and
+ * avoidable. Same directory keeps the rename on one filesystem, which is what
+ * makes it atomic.
+ */
 export declare function writeCursor(cwd: string, seq: number): Promise<void>;
 /**
- * Long-poll the relay for the next annotation after `after`. Resolves the
- * annotation, or null when the poll window elapsed with nothing new. Throws a
- * clear hint when no preview relay is running for this project.
+ * The three outcomes of a poll. `Annotation | null` could only express two, and
+ * a channel that has ENDED is not a channel that is merely quiet: a caller
+ * re-parks on `empty` and must not on `closed`.
+ */
+export type NextResult = {
+    kind: "annotation";
+    annotation: Annotation;
+}
+/** The window elapsed with nothing pending — re-parking is correct and free. */
+ | {
+    kind: "empty";
+}
+/** The preview session has ended; nothing more can arrive on this channel. */
+ | {
+    kind: "closed";
+    reason: ClosedReason;
+};
+/**
+ * Which of the two session-end routes fired. They are indistinguishable to the
+ * creator and print identically by default; the difference is triage detail
+ * surfaced under `--verbose`.
+ */
+export type ClosedReason = 
+/** The relay answered a parked long-poll 410 as it tore down. */
+"signalled"
+/** No relay is answering for this tree — a kill, a reboot, a stale marker. */
+ | "unreachable";
+/**
+ * Long-poll the relay for the next annotation after `after`.
+ *
+ * A missing marker and an unreachable relay both resolve `closed` rather than
+ * throwing: "no preview is running for this tree" is the same fact the graceful
+ * 410 carries, and the caller's correct response to both is identical. Throwing
+ * would reach the top-level catch and exit 1 — a fault code for an ordinary,
+ * expected end.
  */
 export declare function fetchNext(cwd: string, opts: {
     after: number;
     timeoutMs: number;
-}): Promise<Annotation | null>;
+}): Promise<NextResult>;

package/dist/lib/feedback.js

@@ -1,12 +1,29 @@
-// The agent-agnostic reverse-channel consumer behind `vincentt feedback --wait`.
-// Long-polls the running preview's relay for the next annotation after a locally
-// persisted cursor. Delivery is at-least-once: the caller advances the cursor only
-// after it has successfully handed the annotation off (printed it), so a crash
-// before that re-delivers on the next call.
+// The host-neutral reverse-channel consumer behind `vincentt feedback`. Long-polls
+// the running preview's relay for the next annotation after a locally persisted
+// cursor.
+//
+// Delivery is at-least-once, and every rule in this file exists to keep the error
+// on that side: the caller advances the cursor only after the annotation's write
+// has COMPLETED (see the drain in cli/index.ts), the cursor parser can only ever
+// read LOW, and the cursor write is atomic. A cursor that lags re-delivers; a
+// cursor that runs ahead skips silently, which is the one failure the channel
+// forbids.
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { readRelayInfo, relayInfoDir } from "./relayInfo.js";
+import { isProcessAlive, isRelayResponding, readRelayInfo, relayInfoDir, } from "./relayInfo.js";
 const CURSOR_FILE = ".vincentt/annotations/offset";
+/**
+ * A cursor that reads too LOW re-delivers, which is the accepted cost of
+ * at-least-once. A cursor that reads too HIGH silently SKIPS, which is the
+ * failure this channel forbids. So the parser is allowed to err only in one
+ * direction: anything that is not a bare non-negative integer is 0.
+ *
+ * `Number(raw.trim()) || 0` erred the forbidden way — `1e3` is 1000 (a thousand
+ * annotations skipped with no error anywhere), `-5` is -5, `0x10` is 16. And §9
+ * invites the creator to inspect and repair this file by hand, so a hand-edited
+ * value is foreseeable input rather than a hypothetical one.
+ */
+const CURSOR_RE = /^\d+$/;
 export function cursorPath(cwd) {
     return path.join(cwd, CURSOR_FILE);
 }
@@ -23,7 +40,12 @@ async function treeCursorPath(cwd) {
 export async function readCursor(cwd) {
     try {
         const raw = await fs.readFile(await treeCursorPath(cwd), "utf8");
-        return Number(raw.trim()) || 0;
+        const trimmed = raw.trim();
+        if (!CURSOR_RE.test(trimmed))
+            return 0;
+        const n = Number(trimmed);
+        // Beyond MAX_SAFE_INTEGER, Number() rounds — and rounding UP would skip.
+        return Number.isSafeInteger(n) ? n : 0;
     }
     catch (err) {
         if (err.code === "ENOENT")
@@ -31,22 +53,42 @@ export async function readCursor(cwd) {
         throw err;
     }
 }
-/** Advance the cursor. Called ONLY after the annotation was handed off. */
+/**
+ * Advance the cursor. Called ONLY after the annotation was handed off.
+ *
+ * Temp file + same-directory rename, because `fs.writeFile` is not atomic and a
+ * kill mid-write is reachable on exactly the kill-mid-drain path this channel is
+ * designed around. A torn file reads as 0 under the strict parser, so the
+ * failure degrades to re-delivering the whole run — safe, but noisy and
+ * avoidable. Same directory keeps the rename on one filesystem, which is what
+ * makes it atomic.
+ */
 export async function writeCursor(cwd, seq) {
     const p = await treeCursorPath(cwd);
     await fs.mkdir(path.dirname(p), { recursive: true });
-    await fs.writeFile(p, `${seq}\n`, "utf8");
+    const tmp = `${p}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, `${seq}\n`, "utf8");
+    try {
+        await fs.rename(tmp, p);
+    }
+    catch (err) {
+        await fs.rm(tmp, { force: true });
+        throw err;
+    }
 }
 /**
- * Long-poll the relay for the next annotation after `after`. Resolves the
- * annotation, or null when the poll window elapsed with nothing new. Throws a
- * clear hint when no preview relay is running for this project.
+ * Long-poll the relay for the next annotation after `after`.
+ *
+ * A missing marker and an unreachable relay both resolve `closed` rather than
+ * throwing: "no preview is running for this tree" is the same fact the graceful
+ * 410 carries, and the caller's correct response to both is identical. Throwing
+ * would reach the top-level catch and exit 1 — a fault code for an ordinary,
+ * expected end.
  */
 export async function fetchNext(cwd, opts) {
     const info = await readRelayInfo(cwd);
-    if (!info) {
-        throw new Error("No running preview for this project — run `vincentt preview` first.");
-    }
+    if (!info)
+        return { kind: "closed", reason: "unreachable" };
     const base = `http://localhost:${info.relayPort}`;
     const u = new URL(`${info.harnessPath}/feedback/next`, base);
     u.searchParams.set("project", cwd);
@@ -56,12 +98,27 @@ export async function fetchNext(cwd, opts) {
     try {
         res = await fetch(u);
     }
-    catch (err) {
-        throw new Error(`Could not reach the preview relay on :${info.relayPort} (${err.message}). Is the preview still running?`);
+    catch {
+        // The socket died under us. The pid gate + relay-identity probe is what
+        // separates "the preview ended" from "the request failed but a relay is
+        // still there" — only the latter is a fault worth an exit 1.
+        if (await relayGone(info.pid, info.relayPort)) {
+            return { kind: "closed", reason: "unreachable" };
+        }
+        throw new Error(`Could not reach the preview relay on :${info.relayPort}. The relay is answering, so this is not a session end.`);
     }
     if (res.status === 204)
-        return null;
+        return { kind: "empty" };
+    // BEFORE the not-ok throw: 410 is not ok, and a graceful session end must not
+    // become a fault.
+    if (res.status === 410)
+        return { kind: "closed", reason: "signalled" };
     if (!res.ok)
         throw new Error(`relay feedback/next returned ${res.status}`);
-    return (await res.json());
+    return { kind: "annotation", annotation: (await res.json()) };
+}
+async function relayGone(pid, port) {
+    if (pid !== undefined && !isProcessAlive(pid))
+        return true;
+    return !(await isRelayResponding(port));
 }

package/dist/lib/feedbackCopy.d.ts

@@ -0,0 +1,70 @@
+/** Flow C1 — the two lines before the park. */
+export declare function waiting(): string[];
+/** Flow C6 — the opening line of a watch. */
+export declare function watching(): string[];
+/**
+ * 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 declare function handedOver(n: number): string[];
+/**
+ * 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 declare function windowElapsed(timeoutMs: number): string[];
+/**
+ * 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 declare function sessionEnded(handed: number): string[];
+/**
+ * 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 declare function sessionEndedDetail(reason: "signalled" | "unreachable", tree: string, cursor: number): string[];
+/** Flow C6 — a human stopped a watch. The preview is not what ended. */
+export declare function stoppedWatching(): string[];
+/** Flow C5 — the usage error. */
+export declare const USAGE = "Usage: vincentt feedback --wait | --watch [--timeout <seconds>]";
+/**
+ * Flow C6's human render, on stderr, while stdout keeps the exact NDJSON. One
+ * observation, two fidelities — the rule that already governs the perf stream.
+ *
+ * Columns are the preview stream's columns (time, then the tester, then the
+ * content), so a creator who has read a preview stream reads this with nothing
+ * new to learn. The screenshot path is its own line, unadorned, so it is
+ * copy-clean. NOT rendered: id, seq, projectDir — a human can act on none of
+ * them.
+ */
+export interface WatchEntry {
+    createdAt: number;
+    tester?: string;
+    message: string;
+    screenshotPath: string;
+}
+export declare function watchEntry(e: WatchEntry, columns: number | undefined): string[];
+export declare function stripControl(s: string): string;
+/** Hard wrap at `width`, breaking on spaces where one is available. */
+export declare function wrap(s: string, width: number): string[];