@vincentt-xr/cli 0.1.5 → 0.3.0

package/dist/relay/server.js

@@ -8,8 +8,10 @@ import { randomBytes } from "node:crypto";
 import path from "node:path";
 import { WebSocketServer } from "ws";
 import { EventStore } from "./store.js";
+import { TesterRegistry, isTesterId } from "./testers.js";
 import { AnnotationStore, annotationsDir } from "./annotations.js";
 import { claudeCodeInjector, createDispatcher, pasteInjector, } from "./injectors.js";
+import { VIEWER_LABEL_RE, VIEWER_STAMP_HEADER } from "@vincentt-xr/harness/tunnel";
 /** Cap an annotation POST body so a bad/huge upload can't exhaust memory. */
 const MAX_ANNOTATION_BYTES = 25 * 1024 * 1024;
 /** Clamp the long-poll hold so a request can't park forever. */
@@ -18,6 +20,7 @@ export function startRelay(opts = {}) {
     const port = opts.port ?? 7331;
     const wsPath = opts.path ?? "/__harness";
     const store = new EventStore(opts.capacity);
+    const testers = opts.testerRegistry ?? new TesterRegistry();
     const log = opts.onLog ?? (() => undefined);
     const makeId = opts.makeId ?? (() => randomBytes(3).toString("hex"));
     // Reverse channel is enabled when we know which project to bind annotations to.
@@ -34,15 +37,44 @@ export function startRelay(opts = {}) {
                     pasteInjector((p) => log(`annotation ready to paste:\n${p}`)),
                 ], log);
     }
-    const http = createServer((req, res) => handleHttp(req, res, { store, annotations, dispatcher, wsPath, makeId, log }));
+    const http = createServer((req, res) => handleHttp(req, res, {
+        store,
+        annotations,
+        dispatcher,
+        testers,
+        wsPath,
+        makeId,
+        log,
+        onCapReached: opts.onCapReached,
+    }));
     const wss = new WebSocketServer({ server: http, path: wsPath });
-    wss.on("connection", (ws) => {
-        log("client connected");
+    wss.on("connection", (ws, req) => {
+        // The label comes from the CONNECTION, stamped by the tunnel client on this
+        // machine after it re-validated the edge's value. It is re-validated ONCE
+        // MORE here — this is the last hop before a string reaches the terminal and
+        // MCP tool output, which for this product is adjacent to prompt injection,
+        // and a check that runs only upstream is a check a direct localhost client
+        // skips.
+        const viewer = readViewerLabel(req.headers[VIEWER_STAMP_HEADER]);
+        log(viewer ? `client connected · ${viewer}` : "client connected");
+        // The tester is resolved ONCE per connection, from the first batch's key.
+        // Re-resolving per batch would let one socket's events land under two ids if
+        // a client changed its key mid-stream.
+        let tester;
+        let resolved = false;
         ws.on("message", (data) => {
             try {
                 const msg = JSON.parse(String(data));
                 if (msg.type === "events" && Array.isArray(msg.events)) {
-                    store.ingest(msg.sessionId, msg.events);
+                    if (!resolved) {
+                        resolved = true;
+                        const attribution = testers.attribute(msg.sessionId);
+                        tester = attribution.tester;
+                        if (attribution.warnCapReached)
+                            opts.onCapReached?.();
+                    }
+                    store.ingest(msg.events, { viewer, tester });
+                    opts.onEvents?.(msg.events, { viewer, tester });
                 }
             }
             catch {
@@ -55,6 +87,7 @@ export function startRelay(opts = {}) {
     return {
         store,
         annotations,
+        testers,
         close: () => new Promise((resolve) => {
             annotations?.close();
             wss.close();
@@ -62,6 +95,17 @@ export function startRelay(opts = {}) {
         }),
     };
 }
+/**
+ * readViewerLabel accepts ONLY `^viewer-[0-9]{1,4}$` and returns undefined for
+ * everything else — an array-valued header (a duplicate), a forged class, an
+ * ANSI escape, a newline. There is no "sanitize and keep" branch: a label that
+ * does not match is not a label, and the events simply carry no viewer.
+ */
+export function readViewerLabel(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    return VIEWER_LABEL_RE.test(raw) ? raw : undefined;
+}
 function handleHttp(req, res, ctx) {
     const url = new URL(req.url ?? "/", "http://localhost");
     const p = url.pathname;
@@ -105,10 +149,16 @@ function handleAnnotationPost(req, res, ctx) {
             res.writeHead(400).end("annotation requires message + screenshot");
             return;
         }
-        const annotation = await ctx.annotations.add(input, {
-            now: Date.now(),
-            id: ctx.makeId(),
-        });
+        // The annotation's session key is RESOLVED, never assigned — `resolve`,
+        // not `attribute`. This route is unauthenticated and reachable by anyone
+        // holding the capability URL, so a door that minted here would let 64 bare
+        // POSTs exhaust the registry before the creator's phone connected, and the
+        // terminal only prints attributed events.
+        //
+        // The key is still hostile input either way: the annotation is appended to
+        // a queue a running Claude Code /loop drains, so the raw string must never
+        // survive onto the record.
+        const annotation = await ctx.annotations.add({ ...input, sessionId: ctx.testers.resolve(input.sessionId) }, { now: Date.now(), id: ctx.makeId() });
         // Fire the injector chain best-effort — a failed dispatch must not fail the
         // POST; the long-poll consumer still sees the persisted annotation.
         if (ctx.dispatcher) {
@@ -150,22 +200,40 @@ function handleFeedbackNext(res, url, ctx) {
             res.writeHead(400).end();
     });
 }
+/**
+ * A `tester` filter that is not a well-formed id becomes a sentinel that matches
+ * no stored tag, so it filters to an EMPTY list rather than erroring or being
+ * dropped (which would silently widen the query to everyone). The sentinel
+ * cannot collide with a real id: the registry only ever mints `t<n>`.
+ */
+const NO_SUCH_TESTER = "none";
+function normalizeTester(q) {
+    if (q.tester === undefined)
+        return q;
+    return isTesterId(q.tester) ? q : { ...q, tester: NO_SUCH_TESTER };
+}
 async function readQuery(req, url) {
     if (req.method === "POST") {
         const body = await readBody(req);
-        return body ? JSON.parse(body) : {};
+        return normalizeTester(body ? JSON.parse(body) : {});
     }
     const q = {};
     const p = url.searchParams;
-    if (p.get("sessionId"))
-        q.sessionId = p.get("sessionId");
     if (p.get("kind"))
         q.kind = p.get("kind");
     if (p.get("since"))
         q.since = Number(p.get("since"));
     if (p.get("limit"))
         q.limit = Number(p.get("limit"));
-    return q;
+    // `tester` and `viewer` both filter to NOTHING when malformed rather than
+    // being ignored: silently widening a filter would show the creator several
+    // testers' events under a heading naming one. There is no `sessionId` param —
+    // it was the only surface that would teach a creator the raw key exists.
+    if (p.get("tester"))
+        q.tester = p.get("tester");
+    if (p.get("viewer"))
+        q.viewer = p.get("viewer");
+    return normalizeTester(q);
 }
 function readBody(req, maxBytes = Infinity) {
     return new Promise((resolve, reject) => {

package/dist/relay/store.d.ts

@@ -2,12 +2,41 @@ import type { DiagEvent, RelayQuery, RelayResult } from "@vincentt-xr/harness/ev
 export declare class EventStore {
     private readonly capacity;
     private readonly buf;
-    private readonly sessionsSeen;
+    /**
+     * Insertion-ordered, so the roster reads in arrival order rather than in
+     * whatever order a hash lands. Labels are never removed: a viewer that
+     * disconnected 20 seconds ago still has events in this buffer, and dropping
+     * its label would make them unfilterable.
+     */
+    private readonly viewersSeen;
+    /**
+     * Same rule, same reason, for testers — and it matters MORE here, because
+     * `--tester t1` is what a creator runs at the moment the tester who hit the
+     * bug has already closed their tab.
+     *
+     * Note what is NOT here: a set of raw client session keys. The store used to
+     * hold one and return it in `RelayResult.sessions`, which put a
+     * viewer-controlled string on the terminal and in MCP tool output. The raw key
+     * never enters this file; the relay maps it to a tester id first.
+     */
+    private readonly testersSeen;
     private latest;
     constructor(capacity?: number);
-    /** Ingest a batch from a client. Tracks the session and advances latestSeq. */
-    ingest(sessionId: string, events: DiagEvent[]): void;
+    /**
+     * Ingest a batch from a client. Both the VIEWER and the TESTER come from the
+     * connection's own resolution, never from the payload — the device never
+     * proposes its own label (B22), and an identifier taken from the body would be
+     * a viewer-supplied string flowing to the terminal and to MCP tool output.
+     */
+    ingest(events: DiagEvent[], tags?: {
+        viewer?: string;
+        tester?: string;
+    }): void;
     /** Answer an MCP query against the buffer. Newest-biased when limited. */
     query(q?: RelayQuery): RelayResult;
+    /** The label an event carries, for the live terminal stream. */
+    viewerFor(e: DiagEvent): string | undefined;
+    /** The tester an event carries, for the live terminal stream. */
+    testerFor(e: DiagEvent): string | undefined;
     size(): number;
 }

package/dist/relay/store.js

@@ -1,22 +1,52 @@
 // The relay's memory: a bounded ring buffer of recent diagnostics events,
 // queryable the way the MCP server asks ("network events since seq 40", "last
-// 20 errors"). Pure and dependency-free so it is fully unit-testable; the WS
-// server in server.ts is a thin wrapper that feeds this and answers queries
-// from it.
+// 20 errors", "just tester t2"). Pure and dependency-free so it is fully
+// unit-testable; the WS server in server.ts is a thin wrapper that feeds this
+// and answers queries from it.
+//
+// This buffer is where diagnostics content lives, and the ONLY place besides
+// the phone's memory (B19). It is on the CREATOR'S OWN MACHINE.
 export class EventStore {
     capacity;
     buf = [];
-    sessionsSeen = new Set();
+    /**
+     * Insertion-ordered, so the roster reads in arrival order rather than in
+     * whatever order a hash lands. Labels are never removed: a viewer that
+     * disconnected 20 seconds ago still has events in this buffer, and dropping
+     * its label would make them unfilterable.
+     */
+    viewersSeen = new Set();
+    /**
+     * Same rule, same reason, for testers — and it matters MORE here, because
+     * `--tester t1` is what a creator runs at the moment the tester who hit the
+     * bug has already closed their tab.
+     *
+     * Note what is NOT here: a set of raw client session keys. The store used to
+     * hold one and return it in `RelayResult.sessions`, which put a
+     * viewer-controlled string on the terminal and in MCP tool output. The raw key
+     * never enters this file; the relay maps it to a tester id first.
+     */
+    testersSeen = new Set();
     latest = -1;
     constructor(capacity = 5000) {
         this.capacity = capacity;
     }
-    /** Ingest a batch from a client. Tracks the session and advances latestSeq. */
-    ingest(sessionId, events) {
-        this.sessionsSeen.add(sessionId);
+    /**
+     * Ingest a batch from a client. Both the VIEWER and the TESTER come from the
+     * connection's own resolution, never from the payload — the device never
+     * proposes its own label (B22), and an identifier taken from the body would be
+     * a viewer-supplied string flowing to the terminal and to MCP tool output.
+     */
+    ingest(events, tags = {}) {
+        const { viewer, tester } = tags;
+        if (viewer !== undefined)
+            this.viewersSeen.add(viewer);
+        if (tester !== undefined)
+            this.testersSeen.add(tester);
         for (const e of events) {
-            // Tag ownership on the stored copy so cross-session queries can filter.
-            this.buf.push(withSession(e, sessionId));
+            // Tag ownership on the stored copy so per-tester and per-viewer queries
+            // can filter.
+            this.buf.push(withTags(e, viewer, tester));
             if (e.seq > this.latest)
                 this.latest = e.seq;
         }
@@ -28,7 +58,12 @@ export class EventStore {
     /** Answer an MCP query against the buffer. Newest-biased when limited. */
     query(q = {}) {
         let out = this.buf.filter((e) => {
-            if (q.sessionId && sessionOf(e) !== q.sessionId)
+            // Filters INTERSECT. A caller passing both wants the events matching both;
+            // ORing them would answer a question nobody asked with more data than they
+            // requested, under a heading naming one.
+            if (q.tester && testerOf(e) !== q.tester)
+                return false;
+            if (q.viewer && viewerOf(e) !== q.viewer)
                 return false;
             if (q.kind && e.kind !== q.kind)
                 return false;
@@ -40,29 +75,48 @@ export class EventStore {
             out = out.slice(out.length - q.limit); // keep the newest `limit`
         }
         return {
-            events: out.map(stripSession),
+            events: out.map(stripTags),
+            // Parallel to `events`, so a follower can print the label in column one
+            // without inventing a placeholder for an unattributed event.
+            eventViewers: out.map(viewerOf),
+            eventTesters: out.map(testerOf),
             latestSeq: this.latest,
-            sessions: [...this.sessionsSeen],
+            testers: [...this.testersSeen],
+            viewers: [...this.viewersSeen],
         };
     }
+    /** The label an event carries, for the live terminal stream. */
+    viewerFor(e) {
+        return viewerOf(e);
+    }
+    /** The tester an event carries, for the live terminal stream. */
+    testerFor(e) {
+        return testerOf(e);
+    }
     size() {
         return this.buf.length;
     }
 }
-// The store tags each event with its owning session out-of-band (a symbol key)
-// so it survives in the buffer without polluting the wire type. Queries strip
-// it before returning.
-const SESSION = Symbol("session");
-function withSession(e, sessionId) {
+// The store tags each event with its owning viewer and tester out-of-band
+// (symbol keys) so they survive in the buffer without polluting the wire type.
+// Queries strip them before returning.
+const VIEWER = Symbol("viewer");
+const TESTER = Symbol("tester");
+function withTags(e, viewer, tester) {
     return Object.assign(Object.create(Object.getPrototypeOf(e)), e, {
-        [SESSION]: sessionId,
+        ...(viewer === undefined ? {} : { [VIEWER]: viewer }),
+        ...(tester === undefined ? {} : { [TESTER]: tester }),
     });
 }
-function sessionOf(e) {
-    return e[SESSION];
+function viewerOf(e) {
+    return e[VIEWER];
+}
+function testerOf(e) {
+    return e[TESTER];
 }
-function stripSession(e) {
+function stripTags(e) {
     const copy = { ...e };
-    delete copy[SESSION];
+    delete copy[VIEWER];
+    delete copy[TESTER];
     return copy;
 }

package/dist/relay/testers.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Attributed testers per run. Justified against D-Many-viewers-are-normal's
+ * 40-person demo, NOT against the platform's MaxConcurrentStreams = 256 — those
+ * count different things. 256 is per-session CONCURRENT CONNECTIONS, and one tab
+ * opens 2-6 under HTTP/1.1, so 64 tabs already exceeds what the platform admits
+ * and the platform's cap binds first. Memory does not choose this number: 64
+ * entries is about 4 KB.
+ *
+ * That argument holds ONLY because minting requires a WebSocket the harness
+ * opened — see `resolve` versus `attribute`. A door that could mint without a
+ * stream would not be bounded by the platform's stream cap at all, and filling
+ * this registry is a denial of the creator's live terminal, not merely of an id.
+ */
+export declare const MAX_TESTERS = 64;
+/**
+ * Refused keys remembered, so the cap warning prints ONCE per refused session
+ * rather than once per batch.
+ *
+ * This set is what makes print-once bounded. The key is client-supplied, so
+ * without a cap here its size is a number a client chooses by cycling
+ * sessionStorage. Past this many, further sessions are still refused but no
+ * longer remembered — so a pathological client can re-trigger its own warning
+ * line. That is the correct failure: noisy, local and self-inflicted, versus
+ * unbounded memory on the creator's machine.
+ */
+export declare const MAX_REFUSED_TOMBSTONES = 256;
+/** What the relay learned from one batch's key. */
+export interface Attribution {
+    /** The tester id, or undefined when this key is not attributed. */
+    readonly tester?: string;
+    /**
+     * True exactly once per refused session — the batch that should print the cap
+     * warning. Every later batch from the same refused key reports false.
+     */
+    readonly warnCapReached: boolean;
+}
+export declare class TesterRegistry {
+    private readonly maxTesters;
+    private readonly maxRefused;
+    /** Insertion-ordered, so ids read in arrival order. */
+    private readonly byKey;
+    /** Refused keys, for print-once. Holds no id — these were never assigned one. */
+    private readonly refused;
+    private next;
+    constructor(maxTesters?: number, maxRefused?: number);
+    /**
+     * Resolve a client-supplied key to a tester id, assigning one on first sight.
+     *
+     * The key is validated against the SAME grammar the client mints, with no
+     * sanitize-and-keep branch — the readViewerLabel discipline, applied to the
+     * field beside the label that never had it. A key that misses the grammar is
+     * un-attributed: its events are still ingested, only the tester tag is absent.
+     *
+     * Entries are NEVER removed for the life of the process. That mirrors
+     * viewersSeen in the event store and for its stated reason: the ring buffer
+     * holds events that outlive their producer, and dropping a tester's id would
+     * make its already-stored events unfilterable — worse than never having
+     * labelled them. `--tester t1` must keep answering for the tester who just hit
+     * the bug, because that is the moment the creator runs it.
+     */
+    attribute(key: unknown): Attribution;
+    /**
+     * Resolve a key WITHOUT ever assigning one — the read-only door.
+     *
+     * The annotation POST uses this, and the distinction is load-bearing. That
+     * route is UNAUTHENTICATED and reachable by anyone holding the preview's
+     * capability URL, so if it could mint, 64 bare `fetch` calls would exhaust the
+     * registry before the creator's own phone ever connected. Entries are never
+     * evicted, so that state would be permanent for the run — and because the
+     * terminal only prints attributed events, the creator's live stream would go
+     * blank for every real tester.
+     *
+     * Minting requires a WebSocket the harness actually opened. An annotation can
+     * therefore be attributed to a tester that already exists, and is otherwise
+     * un-attributed, which is the correct failure: the creator still gets their
+     * bug report, it just carries no id.
+     */
+    resolve(key: unknown): string | undefined;
+    /** Ids assigned so far, in arrival order. Never includes a refused session. */
+    testers(): string[];
+    /** How many keys hold an id. Bounded by maxTesters. */
+    get size(): number;
+    /** Whether this id was ever assigned — for `--tester` miss messages. */
+    has(tester: string): boolean;
+}
+/**
+ * Is this a well-formed tester id? Used at the query boundary so a malformed
+ * `--tester` filters to nothing rather than erroring or matching broadly.
+ */
+export declare function isTesterId(s: unknown): s is string;

package/dist/relay/testers.js

@@ -0,0 +1,144 @@
+// The tester registry: the one place a client-supplied session key becomes a
+// tester id the creator can read.
+//
+// A TESTER is one browser tab on one preview, recognised across refreshes. It is
+// deliberately NOT called a device: a tab is what the key can honestly
+// distinguish, one person with two tabs is two testers, and over-claiming is how
+// a debugging coordinate turns into an identity.
+//
+// The whole structure lives in the `vincentt preview` process and dies with it.
+// It is NEVER persisted: a tester id surviving a restart would be exactly the
+// cross-session correlator this design refuses (B22).
+//
+// Pure and dependency-free, like store.ts beside it, so every rule below is
+// unit-testable without a socket.
+import { CLIENT_SESSION_ID_RE, TESTER_ID_RE } from "@vincentt-xr/harness/events";
+/**
+ * Attributed testers per run. Justified against D-Many-viewers-are-normal's
+ * 40-person demo, NOT against the platform's MaxConcurrentStreams = 256 — those
+ * count different things. 256 is per-session CONCURRENT CONNECTIONS, and one tab
+ * opens 2-6 under HTTP/1.1, so 64 tabs already exceeds what the platform admits
+ * and the platform's cap binds first. Memory does not choose this number: 64
+ * entries is about 4 KB.
+ *
+ * That argument holds ONLY because minting requires a WebSocket the harness
+ * opened — see `resolve` versus `attribute`. A door that could mint without a
+ * stream would not be bounded by the platform's stream cap at all, and filling
+ * this registry is a denial of the creator's live terminal, not merely of an id.
+ */
+export const MAX_TESTERS = 64;
+/**
+ * Refused keys remembered, so the cap warning prints ONCE per refused session
+ * rather than once per batch.
+ *
+ * This set is what makes print-once bounded. The key is client-supplied, so
+ * without a cap here its size is a number a client chooses by cycling
+ * sessionStorage. Past this many, further sessions are still refused but no
+ * longer remembered — so a pathological client can re-trigger its own warning
+ * line. That is the correct failure: noisy, local and self-inflicted, versus
+ * unbounded memory on the creator's machine.
+ */
+export const MAX_REFUSED_TOMBSTONES = 256;
+const UNATTRIBUTED = { warnCapReached: false };
+export class TesterRegistry {
+    maxTesters;
+    maxRefused;
+    /** Insertion-ordered, so ids read in arrival order. */
+    byKey = new Map();
+    /** Refused keys, for print-once. Holds no id — these were never assigned one. */
+    refused = new Set();
+    next = 1;
+    constructor(maxTesters = MAX_TESTERS, maxRefused = MAX_REFUSED_TOMBSTONES) {
+        this.maxTesters = maxTesters;
+        this.maxRefused = maxRefused;
+        // TESTER_ID_RE tops out at t999, and `--tester` validates against it. A cap
+        // above that would mint ids the filter then refuses, making those testers
+        // permanently unselectable — a silent failure that would surface only to
+        // whoever raised the cap.
+        if (maxTesters > 999) {
+            throw new Error(`maxTesters ${maxTesters} exceeds the t999 id grammar`);
+        }
+    }
+    /**
+     * Resolve a client-supplied key to a tester id, assigning one on first sight.
+     *
+     * The key is validated against the SAME grammar the client mints, with no
+     * sanitize-and-keep branch — the readViewerLabel discipline, applied to the
+     * field beside the label that never had it. A key that misses the grammar is
+     * un-attributed: its events are still ingested, only the tester tag is absent.
+     *
+     * Entries are NEVER removed for the life of the process. That mirrors
+     * viewersSeen in the event store and for its stated reason: the ring buffer
+     * holds events that outlive their producer, and dropping a tester's id would
+     * make its already-stored events unfilterable — worse than never having
+     * labelled them. `--tester t1` must keep answering for the tester who just hit
+     * the bug, because that is the moment the creator runs it.
+     */
+    attribute(key) {
+        if (typeof key !== "string" || !CLIENT_SESSION_ID_RE.test(key))
+            return UNATTRIBUTED;
+        const existing = this.byKey.get(key);
+        if (existing !== undefined)
+            return { tester: existing, warnCapReached: false };
+        if (this.byKey.size >= this.maxTesters) {
+            // REFUSE. Never recycle.
+            //
+            // Every natural cap implementation merges or splits silently. `hash(key) %
+            // N` is the one a reader reaches for because it is stateless, and it
+            // deterministically collides the 65th tester with an existing one.
+            // LRU-evict is the same failure mirrored: one tester reappears as two.
+            // Refusing is the only branch whose failure is VISIBLE.
+            if (this.refused.has(key))
+                return UNATTRIBUTED;
+            if (this.refused.size < this.maxRefused)
+                this.refused.add(key);
+            return { warnCapReached: true };
+        }
+        const tester = `t${this.next++}`;
+        this.byKey.set(key, tester);
+        return { tester, warnCapReached: false };
+    }
+    /**
+     * Resolve a key WITHOUT ever assigning one — the read-only door.
+     *
+     * The annotation POST uses this, and the distinction is load-bearing. That
+     * route is UNAUTHENTICATED and reachable by anyone holding the preview's
+     * capability URL, so if it could mint, 64 bare `fetch` calls would exhaust the
+     * registry before the creator's own phone ever connected. Entries are never
+     * evicted, so that state would be permanent for the run — and because the
+     * terminal only prints attributed events, the creator's live stream would go
+     * blank for every real tester.
+     *
+     * Minting requires a WebSocket the harness actually opened. An annotation can
+     * therefore be attributed to a tester that already exists, and is otherwise
+     * un-attributed, which is the correct failure: the creator still gets their
+     * bug report, it just carries no id.
+     */
+    resolve(key) {
+        if (typeof key !== "string")
+            return undefined;
+        return this.byKey.get(key);
+    }
+    /** Ids assigned so far, in arrival order. Never includes a refused session. */
+    testers() {
+        return [...this.byKey.values()];
+    }
+    /** How many keys hold an id. Bounded by maxTesters. */
+    get size() {
+        return this.byKey.size;
+    }
+    /** Whether this id was ever assigned — for `--tester` miss messages. */
+    has(tester) {
+        for (const t of this.byKey.values())
+            if (t === tester)
+                return true;
+        return false;
+    }
+}
+/**
+ * Is this a well-formed tester id? Used at the query boundary so a malformed
+ * `--tester` filters to nothing rather than erroring or matching broadly.
+ */
+export function isTesterId(s) {
+    return typeof s === "string" && TESTER_ID_RE.test(s);
+}

package/dist/shared/authError.d.ts

@@ -0,0 +1 @@
+export declare function authFailureMessage(label: string, status: number, detail: string): string;

package/dist/shared/authError.js

@@ -0,0 +1,11 @@
+// A rejected PAT (401 from an authenticated call) is, after the auth cutover, the
+// universal first-run state: every existing `vct_` token was invalidated, so the raw
+// "(401): <body>" is unactionable noise for every user at once. Name the cause and give
+// the one instruction that fixes it. Any other status keeps its existing "(<n>): <body>"
+// shape — a 500/timeout is a different problem and must not be mislabeled a stale token.
+export function authFailureMessage(label, status, detail) {
+    if (status === 401) {
+        return "Your Vincentt access token is no longer valid — run `vincentt login` to sign in again.";
+    }
+    return `${label} (${status})${detail ? `: ${detail}` : ""}`;
+}