@vincentt-xr/cli 0.1.4 → 0.2.0

package/dist/preview/viewers.d.ts

@@ -0,0 +1,113 @@
+import type { UAClass } from "@vincentt-xr/harness/tunnel";
+/** The roster block prints once, on the FOURTH TESTER's arrival, and never again. */
+export declare const ROSTER_AT = 4;
+/**
+ * The reconnect advisory's window (Flow L17). It prints only when a connection
+ * attaches within 120s of a disconnect WITH THE SAME UA CLASS. On a first
+ * connection, or at a demo where four fresh phones arrive, the creator never
+ * sees it.
+ */
+export declare const RECONNECT_WINDOW_MS = 120000;
+export interface Viewer {
+    readonly label: string;
+    readonly uaClass: UAClass;
+    readonly connectedAt: number;
+    /** The tester this connection resolved to, once the harness introduced itself. */
+    readonly tester?: string;
+}
+/** One printable line, or a block of them. The runner writes; this decides. */
+export interface ViewerLines {
+    /** `tester-1 connected · iPhone · Safari` */
+    readonly connect?: string;
+    /**
+     * The `!` reconnect advisory, printed BELOW the connect line so the connect
+     * line stays scannable. Held rather than printed immediately — see
+     * `attribute`.
+     */
+    readonly advisory?: string[];
+    /** The one-time roster block, on the fourth tester. */
+    readonly roster?: string[];
+}
+export declare class ViewerRoster {
+    private readonly live;
+    /** Connections seen, ever. Printed once at the end; never a count of people. */
+    private total;
+    private rosterPrinted;
+    /** The most recent disconnect, for the L17 adjacency check. */
+    private lastDeparture;
+    /** Testers ever seen live, so a refresh is recognised as a return. */
+    private readonly testersSeen;
+    /**
+     * A held advisory per connection, keyed by label. The connection arrives before
+     * the harness mounts, so at connect time we do not yet know whether this is a
+     * known tester — and a hedge printed beside a definite `tester-1 refreshed`
+     * teaches the creator to distrust the definite line. So the advisory is
+     * DEFERRED here and dropped if attribution lands. A retracted line in a piped
+     * transcript is worse than a late one.
+     */
+    private readonly heldAdvisory;
+    /** Live CONNECTIONS. The console counts these; the CLI does not display them. */
+    get size(): number;
+    get totalConnections(): number;
+    /** Live TESTERS — distinct, attributed, currently connected. The display count. */
+    get testerCount(): number;
+    /** Live connections with no tester yet: the pre-mount window, or a crashed app. */
+    get unattributedCount(): number;
+    labels(): string[];
+    has(label: string): boolean;
+    get(label: string): Viewer | undefined;
+    /** Distinct live testers, in arrival order. */
+    liveTesters(): string[];
+    /**
+     * connect records a CONNECTION. It prints nothing about a tester yet, because
+     * the tester is not known until the app mounts — see `attribute`, which is
+     * where the line a creator reads comes from.
+     *
+     * Idempotent per label: the tunnel client fires onViewer on EVERY OPEN frame,
+     * not once per connection, so a viewer that requests forty assets would
+     * otherwise announce itself forty times.
+     */
+    connect(label: string, uaClass: UAClass, now: number): ViewerLines;
+    /**
+     * The harness introduced itself: this connection belongs to `tester`. This is
+     * where the creator's line comes from.
+     *
+     * Returns the connect line on a tester's FIRST connection, `refreshed` when a
+     * tester already seen comes back, and nothing for a second concurrent
+     * connection belonging to a tester already live — which is the ordinary case
+     * for one tab, and the reason one scan now reads as one thing.
+     */
+    attribute(label: string, tester: string): ViewerLines;
+    /**
+     * The advisory leads with the RULE and follows with the instance. Leading with
+     * a guess about this specific connection would teach the creator a hedge rather
+     * than a behavior, and one uncertain sentence on a screen where everything
+     * else is fact teaches them to distrust the labels generally — which is the
+     * opposite of what the labels are for.
+     *
+     * It names CONNECTIONS, not devices, and closes on the fact that testers
+     * survive a refresh — so the remedy for the uncertainty is on the same line as
+     * the uncertainty.
+     */
+    private reconnectAdvisory;
+    disconnect(label: string, now: number): ViewerLines;
+    /**
+     * The roster is a ONE-TIME SIGNPOST, not a live-updating footer. A redrawn
+     * status bar fights Ctrl-C, corrupts scrollback, breaks when the output is
+     * piped to a file — which is exactly what an agent does with it — and turns a
+     * plain stream into a TUI, which is a different product.
+     *
+     * It LEADS WITH A COUNT, and the count is exact: distinct attributed testers
+     * currently live. Never the number ever assigned, never a connection count.
+     * The old disclaimer ("this is not a device count") is gone — it existed only
+     * because the number above it was wrong.
+     */
+    rosterBlock(): string[];
+    /**
+     * The `--viewer` miss (Flow L16). An unknown label is a FACT, not an error,
+     * because labels churn — and the remedy is on the same line.
+     */
+    notFollowing(label: string): string;
+    /** The `--tester` miss. Same shape, different coordinate. */
+    notFollowingTester(tester: string): string;
+}

package/dist/preview/viewers.js

@@ -0,0 +1,242 @@
+// The roster: who is connected, what the connect/disconnect lines say, when the
+// roster block prints, and when the reconnect advisory prints.
+//
+// TWO COORDINATES, and the difference is the whole point of this file:
+//
+//   viewer-N  one CONNECTION. Assigned by the edge at the first HTTP byte, so it
+//             exists immediately — and churns, because a browser opens several
+//             per tab under HTTP/1.1 and a reconnect never reuses a label.
+//   tester-N  one BROWSER TAB, across its refreshes. Assigned by the relay when
+//             the app mounts and the harness introduces itself, so it arrives
+//             LATE — and is stable, which is what makes it the display unit.
+//
+// The creator reads testers. `--viewer` still filters connections for
+// connection-level debugging. Neither is derived from the other.
+//
+// It is a pure state machine over (label, uaClass, tester, now), so every rule
+// below is unit-testable without a terminal or a socket. The runner owns the
+// printing.
+import { uaLabel, uaShort } from "./stream.js";
+/** The roster block prints once, on the FOURTH TESTER's arrival, and never again. */
+export const ROSTER_AT = 4;
+/**
+ * The reconnect advisory's window (Flow L17). It prints only when a connection
+ * attaches within 120s of a disconnect WITH THE SAME UA CLASS. On a first
+ * connection, or at a demo where four fresh phones arrive, the creator never
+ * sees it.
+ */
+export const RECONNECT_WINDOW_MS = 120_000;
+export class ViewerRoster {
+    live = new Map();
+    /** Connections seen, ever. Printed once at the end; never a count of people. */
+    total = 0;
+    rosterPrinted = false;
+    /** The most recent disconnect, for the L17 adjacency check. */
+    lastDeparture = null;
+    /** Testers ever seen live, so a refresh is recognised as a return. */
+    testersSeen = new Set();
+    /**
+     * A held advisory per connection, keyed by label. The connection arrives before
+     * the harness mounts, so at connect time we do not yet know whether this is a
+     * known tester — and a hedge printed beside a definite `tester-1 refreshed`
+     * teaches the creator to distrust the definite line. So the advisory is
+     * DEFERRED here and dropped if attribution lands. A retracted line in a piped
+     * transcript is worse than a late one.
+     */
+    heldAdvisory = new Map();
+    /** Live CONNECTIONS. The console counts these; the CLI does not display them. */
+    get size() {
+        return this.live.size;
+    }
+    get totalConnections() {
+        return this.total;
+    }
+    /** Live TESTERS — distinct, attributed, currently connected. The display count. */
+    get testerCount() {
+        return this.liveTesters().length;
+    }
+    /** Live connections with no tester yet: the pre-mount window, or a crashed app. */
+    get unattributedCount() {
+        let n = 0;
+        for (const v of this.live.values())
+            if (v.tester === undefined)
+                n++;
+        return n;
+    }
+    labels() {
+        return [...this.live.keys()];
+    }
+    has(label) {
+        return this.live.has(label);
+    }
+    get(label) {
+        return this.live.get(label);
+    }
+    /** Distinct live testers, in arrival order. */
+    liveTesters() {
+        const out = [];
+        for (const v of this.live.values()) {
+            if (v.tester !== undefined && !out.includes(v.tester))
+                out.push(v.tester);
+        }
+        return out;
+    }
+    /**
+     * connect records a CONNECTION. It prints nothing about a tester yet, because
+     * the tester is not known until the app mounts — see `attribute`, which is
+     * where the line a creator reads comes from.
+     *
+     * Idempotent per label: the tunnel client fires onViewer on EVERY OPEN frame,
+     * not once per connection, so a viewer that requests forty assets would
+     * otherwise announce itself forty times.
+     */
+    connect(label, uaClass, now) {
+        if (this.live.has(label))
+            return {};
+        this.live.set(label, { label, uaClass, connectedAt: now });
+        this.total++;
+        const advisory = this.reconnectAdvisory(label, uaClass, now);
+        if (advisory)
+            this.heldAdvisory.set(label, advisory);
+        // NOTHING PRINTS HERE. One tab opens two connections under HTTP/1.1, so a
+        // line per connection is what made one QR scan read as two records. The
+        // creator learns about this connection when it resolves to a tester, or —
+        // if it never does — through the un-attributed line below.
+        return {};
+    }
+    /**
+     * The harness introduced itself: this connection belongs to `tester`. This is
+     * where the creator's line comes from.
+     *
+     * Returns the connect line on a tester's FIRST connection, `refreshed` when a
+     * tester already seen comes back, and nothing for a second concurrent
+     * connection belonging to a tester already live — which is the ordinary case
+     * for one tab, and the reason one scan now reads as one thing.
+     */
+    attribute(label, tester) {
+        const v = this.live.get(label);
+        if (v === undefined || v.tester !== undefined)
+            return {};
+        // A tester already live on ANOTHER connection: this is the tab's second
+        // socket, not an arrival.
+        const alreadyLive = this.liveTesters().includes(tester);
+        this.live.set(label, { ...v, tester });
+        // The advisory is dropped: we have a definite answer now.
+        const held = this.heldAdvisory.get(label);
+        this.heldAdvisory.delete(label);
+        if (alreadyLive)
+            return {};
+        const returning = this.testersSeen.has(tester);
+        this.testersSeen.add(tester);
+        if (returning) {
+            // A refresh, or a socket that dropped and came back. Same tester, same
+            // line, whichever it was — the creator's question is "is this the same
+            // person", and the answer is yes in both cases.
+            return { connect: `${tester} refreshed` };
+        }
+        const descriptor = uaLabel(v.uaClass);
+        const out = {
+            connect: descriptor ? `${tester} connected · ${descriptor}` : `${tester} connected`,
+        };
+        // Only an un-attributed neighbour can still justify the hedge; a known
+        // tester's arrival is certain, so the held advisory dies with it.
+        if (held && this.unattributedCount > 0)
+            out.advisory = held;
+        if (!this.rosterPrinted && this.testerCount >= ROSTER_AT) {
+            this.rosterPrinted = true;
+            out.roster = this.rosterBlock();
+        }
+        return out;
+    }
+    /**
+     * The advisory leads with the RULE and follows with the instance. Leading with
+     * a guess about this specific connection would teach the creator a hedge rather
+     * than a behavior, and one uncertain sentence on a screen where everything
+     * else is fact teaches them to distrust the labels generally — which is the
+     * opposite of what the labels are for.
+     *
+     * It names CONNECTIONS, not devices, and closes on the fact that testers
+     * survive a refresh — so the remedy for the uncertainty is on the same line as
+     * the uncertainty.
+     */
+    reconnectAdvisory(label, uaClass, now) {
+        const gone = this.lastDeparture;
+        if (!gone)
+            return undefined;
+        if (gone.label === label)
+            return undefined;
+        if (gone.uaClass !== uaClass)
+            return undefined;
+        if (now - gone.at > RECONNECT_WINDOW_MS)
+            return undefined;
+        return [
+            `! A connection that reconnects gets a new label. If ${gone.label} came back,`,
+            `  it is ${label} now — labels last one connection. Testers survive a refresh.`,
+        ];
+    }
+    disconnect(label, now) {
+        const v = this.live.get(label);
+        if (!v)
+            return {};
+        this.live.delete(label);
+        this.heldAdvisory.delete(label);
+        this.lastDeparture = { uaClass: v.uaClass, label, at: now };
+        // A tester leaves when its LAST connection does. A tab's two sockets close
+        // moments apart, and announcing a departure on the first would print
+        // `disconnected` for someone still looking at the app.
+        if (v.tester === undefined)
+            return {};
+        if (this.liveTesters().includes(v.tester))
+            return {};
+        return { connect: `${v.tester} disconnected` };
+    }
+    /**
+     * The roster is a ONE-TIME SIGNPOST, not a live-updating footer. A redrawn
+     * status bar fights Ctrl-C, corrupts scrollback, breaks when the output is
+     * piped to a file — which is exactly what an agent does with it — and turns a
+     * plain stream into a TUI, which is a different product.
+     *
+     * It LEADS WITH A COUNT, and the count is exact: distinct attributed testers
+     * currently live. Never the number ever assigned, never a connection count.
+     * The old disclaimer ("this is not a device count") is gone — it existed only
+     * because the number above it was wrong.
+     */
+    rosterBlock() {
+        const rule = "─".repeat(65);
+        const byTester = new Map();
+        for (const v of this.live.values()) {
+            if (v.tester !== undefined && !byTester.has(v.tester)) {
+                byTester.set(v.tester, uaShort(v.uaClass));
+            }
+        }
+        const parts = [...byTester].map(([t, ua]) => `${t} ${ua}`.trim());
+        const n = byTester.size;
+        const lines = [rule, `${n} ${n === 1 ? "tester" : "testers"} · ${parts.join(" · ")}`];
+        // Without this, `4 testers` printed while five connections are live is the
+        // original defect in a new place — and the pre-mount gap makes that state
+        // routine, not rare.
+        const pending = this.unattributedCount;
+        if (pending > 0) {
+            lines.push(`+ ${pending} ${pending === 1 ? "connection" : "connections"} not yet attributed`);
+        }
+        lines.push(rule);
+        return lines;
+    }
+    /**
+     * The `--viewer` miss (Flow L16). An unknown label is a FACT, not an error,
+     * because labels churn — and the remedy is on the same line.
+     */
+    notFollowing(label) {
+        const connected = this.labels();
+        return connected.length === 0
+            ? `! No ${label} on this preview right now. Nothing is connected.`
+            : `! No ${label} on this preview right now. Connected: ${connected.join(", ")}.`;
+    }
+    /** The `--tester` miss. Same shape, different coordinate. */
+    notFollowingTester(tester) {
+        const live = this.liveTesters();
+        return live.length === 0
+            ? `! No ${tester} on this preview right now. No testers are connected.`
+            : `! No ${tester} on this preview right now. Connected: ${live.join(", ")}.`;
+    }
+}

package/dist/relay/server.d.ts

@@ -1,6 +1,8 @@
 import { EventStore } from "./store.js";
+import { TesterRegistry } from "./testers.js";
 import { AnnotationStore } from "./annotations.js";
 import { type Dispatcher } from "./injectors.js";
+import type { DiagEvent } from "@vincentt-xr/harness/events";
 export interface RelayOptions {
     port?: number;
     /** WS path the client connects to (default matches HarnessProvider). */
@@ -15,10 +17,40 @@ export interface RelayOptions {
     dispatcher?: Dispatcher;
     /** Injected for tests. */
     makeId?: () => string;
+    /**
+     * Live tap for the CLI's terminal stream. It fires per batch as events land,
+     * so the creator sees a line the moment the phone produces it rather than on
+     * a poll. The relay still buffers everything — this is an addition, not a
+     * replacement, and a missing handler changes nothing.
+     */
+    onEvents?: (events: DiagEvent[], tags: EventTags) => void;
+    /**
+     * Fires ONCE per refused session when the tester cap is reached, so the CLI
+     * can print the one warning line. Once per session rather than once per batch:
+     * the registry holds a tombstone precisely so a chatty refused client cannot
+     * repaint the warning on every flush.
+     */
+    onCapReached?: () => void;
+    /** Injected for tests, so cap behavior is drivable without 64 real clients. */
+    testerRegistry?: TesterRegistry;
+}
+/** Who produced a batch: the connection's viewer label and its resolved tester. */
+export interface EventTags {
+    viewer?: string;
+    tester?: string;
 }
 export interface RelayHandle {
     store: EventStore;
     annotations?: AnnotationStore;
+    /** The run's tester registry — read-only to callers; the relay owns writes. */
+    testers: TesterRegistry;
     close: () => Promise<void>;
 }
 export declare function startRelay(opts?: RelayOptions): RelayHandle;
+/**
+ * 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 declare function readViewerLabel(raw: string | string[] | undefined): string | undefined;

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;
 }