@vincentt-xr/cli 0.8.0 → 0.10.0

package/dist/lib/sourceRefCopy.js

@@ -0,0 +1,116 @@
+// The refusal copy for a `--from` reference that does not parse. Separate from
+// the parser so the grammar stays pure, and separate from the dispatcher so the
+// copy is assertable.
+//
+// Every arm closes with "Nothing was written." — no `else` — because a parse
+// refusal happens before git is ever reached.
+import { formatSourceRef } from "./sourceRef.js";
+export function printSourceRefFailure(print, failure, ctx) {
+    switch (failure.kind) {
+        case "looks_like_url": {
+            print("✗ --from takes owner/repo@tag, not a URL.");
+            print("");
+            if (failure.converted) {
+                const short = formatSourceRef(failure.converted);
+                print(`  From that URL:  ${short}`);
+                print("");
+                print(`  vincentt init ${ctx.dir} --from ${short}`);
+            }
+            else {
+                print("  The gallery card shows the reference in that form.");
+            }
+            break;
+        }
+        case "missing_tag": {
+            print("✗ --from needs a version: owner/repo@tag");
+            print("");
+            print(`  You gave:  ${failure.value}`);
+            print(`  Try:       ${failure.value}@<tag>`);
+            print("");
+            print("  The gallery card's command already includes the tag.");
+            break;
+        }
+        case "missing_repo": {
+            print("✗ --from needs a repository: owner/repo@tag");
+            print("");
+            print(`  You gave:  ${failure.value}`);
+            print("");
+            print("  The gallery card's command already includes the owner and the repository.");
+            break;
+        }
+        case "bad_owner": {
+            print(`✗ "${failure.value}" is not a valid GitHub owner.`);
+            print("");
+            print("  --from takes owner/repo@tag.");
+            break;
+        }
+        case "bad_repo": {
+            print(`✗ "${failure.value}" is not a valid repository name.`);
+            print("");
+            print("  --from takes owner/repo@tag.");
+            break;
+        }
+        case "bad_tag": {
+            print(`✗ "${failure.value}" is not a valid tag.`);
+            print("");
+            print("  --from takes owner/repo@tag.");
+            break;
+        }
+    }
+    print("");
+    print("  Nothing was written.");
+}
+/**
+ * `--template` / `--from` on `create` — the parser refusal, and it is a security
+ * control rather than a scope note. The basis for installing dependencies on the
+ * unauthenticated scaffold path is that `create` can only ever clone our own
+ * hardcoded template at a release-gated ref; this screen is what makes that
+ * structurally true rather than conventional.
+ *
+ * "on `create`" is REQUIRED on line 1 and is not required by the shipped
+ * `printFlagConflict` precedent: `--template` really does exist, on `init`, and the
+ * remedy three lines below depends on that being true. An unqualified claim is one
+ * a creator disproves in one command.
+ *
+ * The creator's own typed arguments are carried through verbatim, so all three
+ * remedy lines are copy-pasteable with no placeholder to guess.
+ */
+export function printCreateSourceFlagRefusal(print, flagName, ctx) {
+    const dir = ctx.dir;
+    print(`✗ There's no \`${flagName}\` option on \`create\`.`);
+    print("");
+    if (flagName === "--from") {
+        print("  `create` scaffolds the standard starter and nothing else. To start from");
+        print("  a gallery template, scaffold first and register after:");
+        print("");
+        print(`  vincentt init ${dir} --from ${ctx.value ?? "owner/repo@tag"}`);
+    }
+    else {
+        print("  `create` scaffolds the standard starter and nothing else. To choose a");
+        print("  template or a version, scaffold first and register after:");
+        print("");
+        print(`  vincentt init ${dir} --template ${ctx.value ?? "<version>"}`);
+    }
+    print(`  cd ${dir}`);
+    print("  vincentt create");
+    print("");
+    print("  Nothing was written.");
+}
+/** `--from` with `--template`, or with an install-enabling flag. */
+export function printFlagConflict(print, conflict, ctx) {
+    const [a, b] = conflict.flags;
+    print(`✗ ${a} and ${b} can't be used together.`);
+    print("");
+    if (conflict.kind === "source") {
+        print("  Both choose which source to scaffold from.");
+        print("");
+        print(`  vincentt init ${ctx.dir} --from owner/repo@tag   Start from a gallery template`);
+        print(`  vincentt init ${ctx.dir} --template 2.1.0        Start from the standard template`);
+    }
+    else {
+        print("  A gallery template is cloned without installing its dependencies.");
+        print("  The install is printed as a next step, to run once you've looked at the source.");
+    }
+    print("");
+    print("  Nothing was written.");
+}

package/dist/preview/command.d.ts

@@ -65,6 +65,17 @@ export declare class PreviewUi {
     events(evs: DiagEvent[], tags: EventTags, opts?: {
         attribute?: boolean;
     }): void;
+    /**
+     * An annotation arrived from the phone. One line per annotation — it is an
+     * event, not a condition, so the once-per-stretch rule that governs advisories
+     * does not apply.
+     *
+     * An un-attributed send is dropped from the terminal for the same reason an
+     * un-attributed event is: column one is the tester, and inventing a
+     * placeholder would read as a real one. The annotation itself is still stored
+     * and still handed over by `vincentt feedback`.
+     */
+    annotation(tags: EventTags): void;
     /**
      * L18. Recovery is announced by the 200 that follows and by NOTHING else — a
      * "recovered!" line would be a second interruption for a non-event.

package/dist/preview/command.js

@@ -12,7 +12,7 @@
 // file works, and an agent reading the transcript gets the same information a
 // human does.
 import * as copy from "./copy.js";
-import { PerfThrottle, palette, renderEvent, uaLabel } from "./stream.js";
+import { PerfThrottle, palette, renderAnnotation, renderEvent, uaLabel, } from "./stream.js";
 import { ViewerRoster } from "./viewers.js";
 import { MAX_TESTERS } from "../relay/testers.js";
 /**
@@ -151,6 +151,24 @@ export class PreviewUi {
                 this.line(`  ${rendered}`);
         }
     }
+    /**
+     * An annotation arrived from the phone. One line per annotation — it is an
+     * event, not a condition, so the once-per-stretch rule that governs advisories
+     * does not apply.
+     *
+     * An un-attributed send is dropped from the terminal for the same reason an
+     * un-attributed event is: column one is the tester, and inventing a
+     * placeholder would read as a real one. The annotation itself is still stored
+     * and still handed over by `vincentt feedback`.
+     */
+    annotation(tags) {
+        const { tester } = tags;
+        if (tester === undefined)
+            return;
+        if (this.deps.filterTester !== undefined && tester !== this.deps.filterTester)
+            return;
+        this.line(`  ${renderAnnotation(tester)}`);
+    }
     // ---- advisories -----------------------------------------------------------
     /**
      * L18. Recovery is announced by the 200 that follows and by NOTHING else — a

package/dist/preview/copy.d.ts

@@ -5,6 +5,13 @@ export interface StartBlockInput {
     /** The forward target, printed BEFORE the URL so the 502 advisory matches it. */
     targetUrl: string;
     url: string;
+    /**
+     * The project's console page, or undefined for a folder with no binding. An
+     * unlinked folder gets NO console line rather than a guessed one — the same rule
+     * `consoleVerbCommand` follows, and for the same reason: a link to the wrong
+     * project is worse than no link.
+     */
+    consoleUrl?: string;
     /** Pre-rendered QR rows, or undefined for non-TTY / piped / --no-qr. */
     qr?: string[];
     expiresInHours: number;

package/dist/preview/copy.js

@@ -38,7 +38,14 @@ export function startBlock(i) {
     if (i.qr && i.qr.length > 0) {
         out.push(...i.qr.map((row) => `    ${row}`), "");
     }
-    out.push("    Scan it, or open the link on any phone. No sign-in needed on the phone.", `    Expires in ${i.expiresInHours}h · Ctrl-C to stop`, "", "  Waiting for a device…", "");
+    out.push("    Scan it, or open the link on any phone. No sign-in needed on the phone.", `    Expires in ${i.expiresInHours}h · Ctrl-C to stop`, "");
+    // BELOW the phone URL and its instruction, never above. The phone address is the
+    // line the creator is waiting on; a second URL printed first is a second thing to
+    // read before the one that matters. Dropped entirely when the folder is unlinked.
+    if (i.consoleUrl) {
+        out.push("  In the console:", "", `    ${i.consoleUrl}`, "");
+    }
+    out.push("  Waiting for a device…", "");
     return out;
 }
 /**

package/dist/preview/runner.d.ts

@@ -96,6 +96,12 @@ export interface StartPreviewOptions {
      * line; the connection's events are still stored, just un-attributed.
      */
     onCapReached?: () => void;
+    /**
+     * An annotation arrived from the phone, tagged with the tester that sent it.
+     * Carries nothing about its content — the terminal states arrival, and the
+     * record itself goes to whoever is consuming the reverse channel.
+     */
+    onAnnotation?: (tags: EventTags) => void;
     /** The tunnel's own state — what drives the L19 reconnect advisories. */
     onTunnelState?: (state: TunnelState) => void;
     /** The creator's dev server is not answering (L18). */

package/dist/preview/runner.js

@@ -83,6 +83,7 @@ export async function startPreview(opts) {
             onEvents: opts.onEvents,
             onAttribute: opts.onAttribute,
             onCapReached: opts.onCapReached,
+            onAnnotation: opts.onAnnotation,
         });
         front = createServer((req, res) => {
             const toRelay = req.url?.startsWith(harnessPath) === true;

package/dist/preview/stream.d.ts

@@ -34,6 +34,17 @@ export declare function renderNetworkWithSize(label: string, e: NetworkEvent, by
 export declare function displayPath(url: string): string;
 export declare function renderLog(label: string, e: LogEvent, p: Palette): string;
 export declare function renderTrace(label: string, e: TraceEvent): string;
+/**
+ * An annotation arrived from the phone. Same column grammar as every other
+ * stream line — tester in column one, kind in the status column, then the fact.
+ *
+ * It states THAT one arrived and nothing else: no message, no id, no screenshot
+ * path, no count, and no command to run. The message is viewer-authored and
+ * hostile, and this line lands in the creator's scrollback and, pasted, in their
+ * agent's context. It is an event and not a condition, so one line per
+ * annotation is correct here where an advisory would print once per stretch.
+ */
+export declare function renderAnnotation(label: string): string;
 /** The dispatcher. Returns null for an event kind the terminal does not print. */
 export declare function renderEvent(label: string, e: DiagEvent, p: Palette): string | null;
 /**

package/dist/preview/stream.js

@@ -134,6 +134,19 @@ export function renderTrace(label, e) {
     const fps = e.fps.toFixed(0);
     return `${labelCol(label)}${padEnd("perf", STATUS_COL)} ${fps} fps · ${e.longTaskCount} long tasks · ${e.longestTaskMs}ms peak`;
 }
+/**
+ * An annotation arrived from the phone. Same column grammar as every other
+ * stream line — tester in column one, kind in the status column, then the fact.
+ *
+ * It states THAT one arrived and nothing else: no message, no id, no screenshot
+ * path, no count, and no command to run. The message is viewer-authored and
+ * hostile, and this line lands in the creator's scrollback and, pasted, in their
+ * agent's context. It is an event and not a condition, so one line per
+ * annotation is correct here where an advisory would print once per stretch.
+ */
+export function renderAnnotation(label) {
+    return `${labelCol(label)}${padEnd("feedback", STATUS_COL)}  annotation received`;
+}
 /** The dispatcher. Returns null for an event kind the terminal does not print. */
 export function renderEvent(label, e, p) {
     if (e.kind === "network")

package/dist/publish/api.d.ts

@@ -46,6 +46,26 @@ export interface ApiErrorDetail {
     mismatched?: number;
     reason?: string;
     path?: string;
+    /**
+     * f10's plan-limit refusal. Bytes are DECIMAL on the wire (1 GB = 10^9), the
+     * same units formatBytes already renders.
+     */
+    figureBytes?: number;
+    allowanceBytes?: number;
+    cutOffAt?: string;
+    from?: string;
+    to?: string;
+    /** The tier in force, when the API names one. */
+    planTier?: string;
+    planName?: string;
+    /**
+     * The org that owns THIS project, as the API names it. It is not the machine's
+     * configured active org and must win over it: a project can belong to an org
+     * the CLI is not currently pointed at, and naming the wrong one in a refusal
+     * tells the creator's agent to go look at an org that was never cut off.
+     */
+    orgName?: string;
+    orgSlug?: string;
 }
 export declare class PublishApiError extends Error {
     readonly status: number;

package/dist/publish/command.d.ts

@@ -18,6 +18,9 @@ export interface PublishDeps {
     sleep: (ms: number) => Promise<void>;
     fetchImpl?: typeof fetch;
     orgName?: () => Promise<string>;
+    /** The active org's slug, for the usage deep link on a plan-limit refusal. */
+    orgSlug?: () => Promise<string | undefined>;
+    consoleUrl?: string;
 }
 export interface PublishOptions {
     distDir?: string;

package/dist/publish/command.js

@@ -148,6 +148,11 @@ export async function publishCommand(deps, opts = {}) {
         address,
         liveVersion: project.liveVersion ?? undefined,
         fetchImpl,
+        org: {
+            name: orgName || undefined,
+            slug: (await deps.orgSlug?.()) || undefined,
+            consoleUrl: deps.consoleUrl,
+        },
     });
 }
 async function runUpload(deps, cfg, i) {
@@ -156,7 +161,7 @@ async function runUpload(deps, cfg, i) {
         opened = await openUpload(cfg, i.projectId, i.manifest.files, i.note, i.fetchImpl);
     }
     catch (err) {
-        for (const l of openErrorLines(err, i.address, i.liveVersion))
+        for (const l of openErrorLines(err, i.address, i.liveVersion, i.org))
             deps.print(l);
         return 1;
     }
@@ -221,6 +226,9 @@ async function commitWithHealing(deps, cfg, i, uploadId) {
         catch (err) {
             if (!(err instanceof PublishApiError))
                 throw err;
+            // The plan limit is a 409 and falls past this branch deliberately. It is
+            // the interlock refusing, not the flip failing, and retrying it three
+            // times would be the retry loop the refusal exists to stop.
             if (err.code === "publish_flip_failed" || err.status === 502) {
                 if (attempt === COMMIT_RETRIES) {
                     for (const l of copy.flipFailed(i.address, i.liveVersion))
@@ -236,15 +244,39 @@ async function commitWithHealing(deps, cfg, i, uploadId) {
                 await deps.sleep(COMMIT_RETRY_DELAY_MS);
                 continue;
             }
-            for (const l of commitErrorLines(err, i.address, i.liveVersion))
+            for (const l of commitErrorLines(err, i.address, i.liveVersion, i.org))
                 deps.print(l);
             return 1;
         }
     }
     return 1;
 }
-function commitErrorLines(err, address, liveVersion) {
+/**
+ * The plan-limit refusal, from the detail the API sends. It is reachable from
+ * open AND from commit, because the interlock lives at the port and every flip
+ * path folds through the same 409.
+ *
+ * The figures come off the wire and are never computed here: a CLI that derived
+ * an allowance would be guessing at another service's state.
+ */
+function planLimitLines(err, org) {
+    return copy.planLimitRefused({
+        // THE WIRE WINS over the machine's configured active org. The API names the
+        // org that owns this project; the local config names whichever org the CLI
+        // was last pointed at, and they are not always the same one.
+        orgName: err.detail.orgName ?? org?.name,
+        orgSlug: err.detail.orgSlug ?? org?.slug,
+        planName: err.detail.planName,
+        figureBytes: err.detail.figureBytes ?? 0,
+        allowanceBytes: err.detail.allowanceBytes ?? 0,
+        cutOffAt: err.detail.cutOffAt,
+        consoleUrl: org?.consoleUrl,
+    });
+}
+function commitErrorLines(err, address, liveVersion, org) {
     switch (err.code) {
+        case "unavailable_plan_limit":
+            return planLimitLines(err, org);
         case "publish_expired":
             return copy.publishExpired(address, liveVersion);
         case "publish_contended":
@@ -267,7 +299,7 @@ function commitErrorLines(err, address, liveVersion) {
             ];
     }
 }
-function openErrorLines(err, address, liveVersion) {
+function openErrorLines(err, address, liveVersion, org) {
     if (!(err instanceof PublishApiError)) {
         return [
             "",
@@ -277,6 +309,9 @@ function openErrorLines(err, address, liveVersion) {
             "",
         ];
     }
+    if (err.code === "unavailable_plan_limit") {
+        return planLimitLines(err, org);
+    }
     if (err.code === "publish_too_large") {
         return copy.tooLargeFromServer(err.detail.observed ?? 0, err.detail.limit ?? 0);
     }

package/dist/publish/copy.d.ts

@@ -132,6 +132,35 @@ export declare function finishing(): string;
 export declare function liveAt(liveUrl: string, version: number): string[];
 /** Prints only if a retry is needed. It says nothing about a failure, because nothing has failed yet. */
 export declare function takingLonger(): string;
+export interface PlanLimitInput {
+    /** The org's display name, and its slug when the CLI holds one. */
+    orgName?: string;
+    orgSlug?: string;
+    /** The plan in force. Absent when the API did not name one — the line is then dropped. */
+    planName?: string;
+    figureBytes: number;
+    allowanceBytes: number;
+    /** RFC3339, from the cutoff marker. */
+    cutOffAt?: string;
+    consoleUrl?: string;
+}
+/**
+ * Flow L32 — the org is cut off and open-publish refused before a byte moved.
+ *
+ * This is NOT flipFailed and must never be folded into it. The API gives the two
+ * distinct wire codes because one means the system working correctly and the
+ * other means the ledger is broken; a creator told "the address didn't switch
+ * over" when they hit a plan limit has been told the platform is malfunctioning.
+ *
+ * The three facts are a STACKED ALIGNED BLOCK because they are a comparison —
+ * the figure against the allowance. Inline they are a sentence to parse; stacked
+ * an agent and a human read them the same way.
+ *
+ * "cannot be done from the CLI" is load-bearing: an agent's default response to a
+ * failure is to retry, and naming the remedy as a human action outside the tool
+ * is the only thing that stops the loop.
+ */
+export declare function planLimitRefused(i: PlanLimitInput): string[];
 /**
  * The cause is NOT named. Every non-healing arm of the commit state machine
  * returns this identically by design, and the CLI must not invent a distinction

package/dist/publish/copy.js

@@ -440,6 +440,92 @@ export function liveAt(liveUrl, version) {
 export function takingLonger() {
     return "!  Taking a moment longer than usual…";
 }
+const SUPPORT_EMAIL = "hello@vincentt.studio";
+/**
+ * Flow L32 — the org is cut off and open-publish refused before a byte moved.
+ *
+ * This is NOT flipFailed and must never be folded into it. The API gives the two
+ * distinct wire codes because one means the system working correctly and the
+ * other means the ledger is broken; a creator told "the address didn't switch
+ * over" when they hit a plan limit has been told the platform is malfunctioning.
+ *
+ * The three facts are a STACKED ALIGNED BLOCK because they are a comparison —
+ * the figure against the allowance. Inline they are a sentence to parse; stacked
+ * an agent and a human read them the same way.
+ *
+ * "cannot be done from the CLI" is load-bearing: an agent's default response to a
+ * failure is to retry, and naming the remedy as a human action outside the tool
+ * is the only thing that stops the loop.
+ */
+export function planLimitRefused(i) {
+    const rows = [];
+    if (i.orgName || i.orgSlug)
+        rows.push(["Organization", orgLabel(i.orgName, i.orgSlug)]);
+    if (i.planName) {
+        rows.push(["Plan", `${i.planName} — ${formatBytes(i.allowanceBytes)} traffic per month`]);
+    }
+    else {
+        rows.push(["Allowance", `${formatBytes(i.allowanceBytes)} traffic per month`]);
+    }
+    rows.push(["Served", `${formatBytes(i.figureBytes)} this month`]);
+    const when = i.cutOffAt ? shortDate(i.cutOffAt) : "";
+    const takenOn = when ? ` on ${when}` : "";
+    return [
+        "",
+        "✗ Vincentt has taken this organization's published addresses offline.",
+        "",
+        ...alignedRows(rows),
+        "",
+        `  Published addresses were taken offline${takenOn} because the organization`,
+        "  went over its monthly traffic allowance. Restoring this is a manual action",
+        "  by a Vincentt operator and cannot be done from the CLI.",
+        "",
+        "  Every version is still stored and the address is still yours.",
+        "",
+        ...remedyLines(i.orgSlug, i.consoleUrl),
+        "  Nothing was uploaded.",
+        "",
+    ];
+}
+function orgLabel(name, slug) {
+    if (name && slug && name !== slug)
+        return `${name} (${slug})`;
+    return name || slug || "";
+}
+/**
+ * Left-aligned label column. Distinct from alignedPair, which right-aligns two
+ * values so magnitudes compare — here the values are prose of different kinds.
+ */
+function alignedRows(rows) {
+    const width = Math.max(...rows.map((r) => r[0].length));
+    return rows.map(([label, value]) => `  ${label.padEnd(width)}   ${value}`);
+}
+/**
+ * f4's rule: where a verb does not exist because the act belongs to another
+ * surface, say where it lives and link to it — and if the link cannot be built,
+ * drop the link and keep the explanation.
+ */
+function remedyLines(orgSlug, consoleUrl) {
+    if (!orgSlug)
+        return [`  Email ${SUPPORT_EMAIL}.`, ""];
+    const base = (consoleUrl ?? "https://console.vincentt.studio").replace(/\/$/, "");
+    return [
+        `  See ${base}/orgs/${orgSlug}/usage, or email`,
+        `  ${SUPPORT_EMAIL}.`,
+        "",
+    ];
+}
+const MONTHS = [
+    "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+    "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+];
+/** `29 Aug` — the date the creator reads, in UTC, matching the marker's own day. */
+function shortDate(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return "";
+    return `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]}`;
+}
 // ---- Flow L29, the server-side failures ---------------------------------------
 /**
  * The cause is NOT named. Every non-healing arm of the commit state machine

package/dist/relay/annotations.d.ts

@@ -1,6 +1,19 @@
 import type { Annotation, AnnotationInput } from "@vincentt-xr/harness/events";
 export declare const ANNOTATIONS_DIR = ".vincentt/annotations";
 export declare function annotationsDir(projectDir: string): string;
+/**
+ * What ended a long-poll. A timeout and a teardown used to be the same value
+ * (`null`), which made a dead session byte-identical to a quiet one on the wire
+ * — so a parked consumer waited forever on a channel that could never speak.
+ */
+export type NextOutcome = {
+    kind: "annotation";
+    annotation: Annotation;
+} | {
+    kind: "timeout";
+} | {
+    kind: "closed";
+};
 export declare class AnnotationStore {
     private readonly projectDir;
     private readonly dir;
@@ -8,6 +21,7 @@ export declare class AnnotationStore {
     private seq;
     private waiters;
     private loaded;
+    private closed;
     constructor(projectDir: string, dir?: string);
     /** Load persisted annotations so seq continues across preview restarts. */
     init(): Promise<void>;
@@ -18,13 +32,23 @@ export declare class AnnotationStore {
     }): Promise<Annotation>;
     /** The first annotation with seq greater than `after`, if one is already held. */
     peekAfter(after: number): Annotation | undefined;
+    /** Every held annotation with seq greater than `after`, in seq order. */
+    listAfter(after: number): Annotation[];
     /**
      * Long-poll: resolve with the first annotation whose seq is greater than
-     * `after`, either immediately (already held) or as soon as one arrives. Resolves
-     * null if none arrives within `timeoutMs`.
+     * `after`, either immediately (already held) or as soon as one arrives.
+     * Resolves `timeout` if none arrives within `timeoutMs`, and `closed` if the
+     * store tore down while the caller was parked.
+     *
+     * `timeoutMs` of 0 means "answer now": nothing held resolves `timeout` on the
+     * next tick rather than parking.
      */
-    nextAfter(after: number, timeoutMs: number): Promise<Annotation | null>;
+    nextAfter(after: number, timeoutMs: number): Promise<NextOutcome>;
     private wake;
-    /** Release any parked waiters on teardown so nothing hangs. */
+    /**
+     * Release any parked waiters on teardown, telling them the channel ENDED. A
+     * teardown that resolved them the same way a timeout does left a parked
+     * consumer unable to tell a dead session from a quiet one.
+     */
     close(): void;
 }

package/dist/relay/annotations.js

@@ -29,6 +29,7 @@ export class AnnotationStore {
     seq = 0;
     waiters = [];
     loaded = false;
+    closed = false;
     constructor(projectDir, dir = annotationsDir(projectDir)) {
         this.projectDir = projectDir;
         this.dir = dir;
@@ -80,22 +81,32 @@ export class AnnotationStore {
     peekAfter(after) {
         return this.items.find((a) => a.seq > after);
     }
+    /** Every held annotation with seq greater than `after`, in seq order. */
+    listAfter(after) {
+        return this.items.filter((a) => a.seq > after);
+    }
     /**
      * Long-poll: resolve with the first annotation whose seq is greater than
-     * `after`, either immediately (already held) or as soon as one arrives. Resolves
-     * null if none arrives within `timeoutMs`.
+     * `after`, either immediately (already held) or as soon as one arrives.
+     * Resolves `timeout` if none arrives within `timeoutMs`, and `closed` if the
+     * store tore down while the caller was parked.
+     *
+     * `timeoutMs` of 0 means "answer now": nothing held resolves `timeout` on the
+     * next tick rather than parking.
      */
     nextAfter(after, timeoutMs) {
         const held = this.peekAfter(after);
         if (held)
-            return Promise.resolve(held);
+            return Promise.resolve({ kind: "annotation", annotation: held });
+        if (this.closed)
+            return Promise.resolve({ kind: "closed" });
         return new Promise((resolve) => {
             const waiter = {
                 after,
                 resolve,
                 timer: setTimeout(() => {
                     this.waiters = this.waiters.filter((w) => w !== waiter);
-                    resolve(null);
+                    resolve({ kind: "timeout" });
                 }, timeoutMs),
             };
             waiter.timer.unref?.();
@@ -107,7 +118,7 @@ export class AnnotationStore {
         for (const w of this.waiters) {
             if (a.seq > w.after) {
                 clearTimeout(w.timer);
-                w.resolve(a);
+                w.resolve({ kind: "annotation", annotation: a });
             }
             else {
                 remaining.push(w);
@@ -115,11 +126,16 @@ export class AnnotationStore {
         }
         this.waiters = remaining;
     }
-    /** Release any parked waiters on teardown so nothing hangs. */
+    /**
+     * Release any parked waiters on teardown, telling them the channel ENDED. A
+     * teardown that resolved them the same way a timeout does left a parked
+     * consumer unable to tell a dead session from a quiet one.
+     */
     close() {
+        this.closed = true;
         for (const w of this.waiters) {
             clearTimeout(w.timer);
-            w.resolve(null);
+            w.resolve({ kind: "closed" });
         }
         this.waiters = [];
     }