@homespunapps/cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lalit Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @homespunapps/cli
+
+Command-line client for the [Homespun](https://github.com/aerolalit/homespun) relay:
+hand a human a rich interactive UI by URL and capture their answer as structured
+data — from any agent (cron job, chat bot, CI, headless server).
+
+## Install
+
+```sh
+npm install -g @homespunapps/cli
+# or, no install:
+npx @homespunapps/cli <command>
+```
+
+The binary is `homespun`.
+
+## Try it
+
+Register once, then `homespun demo` spins up a short-lived sample app on the hosted
+relay, opens it in your browser, and prints the structured event back in your
+terminal the moment you interact (the demo app is cleaned up on exit):
+
+```sh
+npx @homespunapps/cli agent register --name "my-agent"   # one-time, hosted relay
+npx @homespunapps/cli demo                               # Node 20+ — round-trip in ~60s
+```
+
+Add `--no-open` on a headless / SSH box and it just prints the URL.
+
+## Setup
+
+```sh
+export HOMESPUN_URL=https://homespun.dev   # or your self-hosted relay
+homespun agent register --name "my-agent"            # provisions and saves an API key
+```
+
+`homespun agent register` writes the URL + API key to
+`${XDG_CONFIG_HOME:-~/.config}/homespun/config.json`. Subsequent commands need
+only `HOMESPUN_URL` (or nothing) in the environment.
+
+Override per-invocation with `--url <url>` and `--api-key <key>`.
+
+## Commands
+
+Uniform `homespun <noun> <verb> [options]`:
+
+```
+homespun demo                      Zero-setup guided tour — see the round-trip live
+homespun agent register            Provision an agent API key and save it locally
+homespun agent logout              Clear the locally-saved URL + API key
+homespun create            Create an app — returns app_id, urls, tokens
+homespun show <id>         Non-blocking snapshot: metadata + event log
+homespun send <id>         Emit an agent event into an app
+homespun watch <id>        Stream an app's events as JSON-lines on stdout
+homespun delete <id>       Close / delete an app
+homespun template <verb>           Manage reusable, versioned templates
+homespun key list | revoke         Inspect or revoke your agent's API key
+homespun taste get | set | clear   Read / write / clear UI-taste notes
+homespun feedback create | list    Submit / list one-shot feedback to the operator
+homespun config show               Show the resolved relay config (no network call)
+homespun skill show | version      Fetch the relay's SKILL.md (or its version)
+```
+
+Run `homespun <noun> --help` for that noun's verbs, and
+`homespun <noun> <verb> --help` for verb-specific options.
+
+## Output
+
+stdout is machine-readable JSON. Errors go to stderr as
+`{"error":{"code","message"}}` with a non-zero exit.
+
+```sh
+SESSION=$(homespun create --template ./form.html --name "Quick poll" --event-schema ./q.json | jq -r .app_id)
+homespun watch "$SESSION" | jq 'select(.type == "human_response")'
+```
+
+## Links
+
+- Repo: <https://github.com/aerolalit/homespun>
+- Spec: <https://github.com/aerolalit/homespun/blob/main/docs/SPEC.md>
+- License: MIT

package/dist/argv.js

@@ -0,0 +1,140 @@
+// Tiny hand-rolled argv parser. No CLI framework.
+//
+// Supports:
+//   --flag value      --flag=value      --bool      -h
+// Everything that isn't a flag (or a flag's value) is a positional.
+/**
+ * Thrown for any argv-level user error: missing value, duplicate flag, or
+ * (when a runner calls assertKnownFlags) an unknown flag. `hint` rides
+ * alongside the message and ends up in the error envelope so callers see a
+ * single line pointing them at the right --help.
+ */
+export class ArgvError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.name = "ArgvError";
+        if (hint !== undefined)
+            this.hint = hint;
+    }
+}
+/**
+ * Parse argv tokens. `booleanFlags` lists flags that never consume a value
+ * (e.g. --json, --once, --help); everything else with a `--name` form
+ * consumes the next token unless written as `--name=value`.
+ *
+ * Bails with ArgvError on the first duplicate (`--foo x --foo y` or
+ * `--once --once`) so a typo'd repeat doesn't silently overwrite the first
+ * value the way a plain `Map.set` would.
+ *
+ * Does NOT throw on a value-flag with no following value. Instead it
+ * records the name in `danglingValueFlags` so `assertKnownFlags` can
+ * produce the right message — "unknown flag(s)" for typos, "requires a
+ * value" for genuine known-flag-missing-value cases. Without this split,
+ * the message was non-uniform (a `--bogus` at end of argv said "requires
+ * a value" while `--bogus something` said "unknown flag(s)" — same root
+ * cause, two messages).
+ */
+export function parseArgs(tokens, booleanFlags) {
+    const positionals = [];
+    const flags = new Map();
+    const bools = new Set();
+    const danglingValueFlags = new Set();
+    for (let i = 0; i < tokens.length; i++) {
+        const tok = tokens[i];
+        if (tok === "-h" || tok === "--help") {
+            bools.add("help");
+            continue;
+        }
+        if (tok.startsWith("--")) {
+            const body = tok.slice(2);
+            const eq = body.indexOf("=");
+            if (eq !== -1) {
+                const key = body.slice(0, eq);
+                if (flags.has(key)) {
+                    throw new ArgvError(`duplicate flag: --${key}`);
+                }
+                flags.set(key, body.slice(eq + 1));
+                continue;
+            }
+            if (booleanFlags.has(body)) {
+                if (bools.has(body)) {
+                    throw new ArgvError(`duplicate flag: --${body}`);
+                }
+                bools.add(body);
+                continue;
+            }
+            const next = tokens[i + 1];
+            if (next === undefined || next.startsWith("--")) {
+                // No value follows. Don't decide whether this is a typo or a
+                // forgotten value — record it; assertKnownFlags resolves both
+                // with one consistent message shape (see the field doc on
+                // ParsedArgs).
+                danglingValueFlags.add(body);
+                continue;
+            }
+            if (flags.has(body)) {
+                throw new ArgvError(`duplicate flag: --${body}`);
+            }
+            flags.set(body, next);
+            i++;
+            continue;
+        }
+        positionals.push(tok);
+    }
+    return { positionals, flags, bools, danglingValueFlags };
+}
+/**
+ * Flags every command accepts. Kept here (not in each command's allow-list)
+ * so adding a new global flag updates one place. `url` / `api-key` are the
+ * relay-target overrides; `help` / `json` are universal display modes.
+ */
+const GLOBAL_FLAGS = ["url", "api-key", "profile"];
+const GLOBAL_BOOLS = ["help", "json"];
+/**
+ * Reject anything the per-command allow-list (plus the globals above) does
+ * not name. Run from each leaf runner before it starts pulling values out of
+ * `args`. The thrown ArgvError carries a hint pointing at the verb's own
+ * --help, so a user fixing a typo lands on the canonical list of flags.
+ *
+ * Why per-command and not at parse time: the parser is single-pass and
+ * generic on purpose — adding a new flag to one verb should not require a
+ * shared registry. Keeping the allow-list co-located with the runner that
+ * consumes it means the two cannot drift.
+ *
+ * Also resolves the parser's `danglingValueFlags`: an unknown name there
+ * is reported alongside other unknowns ("unknown flag(s): --bogus"); a
+ * known name there apps as "--name requires a value". This is what
+ * keeps the error message uniform for a typo whether or not a value
+ * follows it.
+ */
+export function assertKnownFlags(args, knownFlags, knownBools, helpCommand) {
+    const flagSet = new Set([...GLOBAL_FLAGS, ...knownFlags]);
+    const boolSet = new Set([...GLOBAL_BOOLS, ...knownBools]);
+    const dangling = args.danglingValueFlags ?? new Set();
+    const unknown = [];
+    for (const k of args.flags.keys()) {
+        if (!flagSet.has(k) && !boolSet.has(k))
+            unknown.push(`--${k}`);
+    }
+    for (const k of args.bools) {
+        if (!boolSet.has(k) && !flagSet.has(k))
+            unknown.push(`--${k}`);
+    }
+    for (const k of dangling) {
+        if (!flagSet.has(k) && !boolSet.has(k))
+            unknown.push(`--${k}`);
+    }
+    if (unknown.length > 0) {
+        throw new ArgvError(`unknown flag(s): ${unknown.join(", ")}`, `run \`${helpCommand} --help\` for the supported flags`);
+    }
+    // No unknowns — but a known value-flag may still have been left without
+    // a value. Handle the first such case with the pre-existing message
+    // shape ("--name requires a value"). Reporting only the first keeps the
+    // message simple; the user fixes that flag, re-runs, sees the next one.
+    for (const k of dangling) {
+        if (flagSet.has(k)) {
+            throw new ArgvError(`--${k} requires a value`);
+        }
+    }
+}

package/dist/commands/agent.js

@@ -0,0 +1,62 @@
+// `homespun agent` — agent-lifecycle operations: register a new API key, or
+// clear the locally-saved one.
+//
+// Both verbs are about the calling agent's identity on this machine:
+//   register   provision an API key from the relay (one-shot bootstrap)
+//   logout     clear the locally-saved relay URL + API key
+//
+// This file is a thin dispatcher — actual logic lives in register.ts and
+// logout.ts.
+import { runRegister } from "./register.js";
+import { runLogout } from "./logout.js";
+import { runClaim } from "./claim.js";
+import { runSetKey } from "./set-key.js";
+import { fail } from "../output.js";
+export const agentHelp = `homespun agent — manage this agent's identity on the relay
+
+Usage:
+  homespun agent <verb> [options]
+
+Verbs:
+  register          Provision an agent API key (POST /v1/register) and save it
+                    to the CLI config file. Run this once before other commands.
+  claim <code>      Bind this agent to a human via a one-shot claim code the
+                    human generated in their Settings UI (POST /v1/agents/claim).
+                    One-way; no unclaim in v1.
+  set-key <key>     Save a new API key into the CLI config file. Used after
+                    regenerating the agent's key in the relay's My-agents UI:
+                    the human pastes the new key here so subsequent commands
+                    authenticate as the same agent.
+  logout            Clear the locally-saved relay URL + API key. Does NOT
+                    revoke the key on the relay — use 'homespun key revoke' for
+                    that.
+
+Run \`homespun agent <verb> --help\` for verb-specific options.`;
+export async function runAgent(args) {
+    // Strip the first positional (the verb) so each verb runner sees its
+    // own arguments at positionals[0..n].
+    const verbArgs = {
+        ...args,
+        positionals: args.positionals.slice(1),
+    };
+    const verb = args.positionals[0];
+    switch (verb) {
+        case "register":
+            await runRegister(verbArgs);
+            break;
+        case "claim":
+            await runClaim(verbArgs);
+            break;
+        case "set-key":
+            await runSetKey(verbArgs);
+            break;
+        case "logout":
+            await runLogout(verbArgs);
+            break;
+        case undefined:
+            fail("missing verb — usage: homespun agent <register|claim|set-key|logout> (run 'homespun agent --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown agent verb '${verb}' — expected register|claim|set-key|logout (run 'homespun agent --help')`, "invalid_args");
+    }
+}

package/dist/commands/apps.js

@@ -0,0 +1,368 @@
+// `homespun apps` — v2 app lifecycle management (spec-cli §3.2): list / show /
+// update / delete / wake, plus `watch` (spec-cli §3.4).
+//
+// Naming note (deviation from spec-cli's literal top-level `homespun watch`):
+// this branch still carries the UNCHANGED v1 `homespun watch <homespun-id>` command
+// (packages/cli/src/commands/watch.ts) — v2's schema/routes are additive
+// during this expand/contract migration (spec-schema §6 sequencing note),
+// and the v1 command's existing tests must keep passing. Reusing the bare
+// `watch` noun for a different resource (App vs. Homespun) would silently break
+// it. `homespun apps watch <app>` gets the identical behavior spec-cli §3.4
+// describes, nested under the noun that already owns every other v2 app
+// lifecycle verb; the noun collision is resolved (not worked around) at the
+// v1-removal cutover PR, where `homespun watch`/`homespun share` are freed up for v2
+// to reclaim verbatim.
+import { HomespunApiError, appWsUrlFromAppUrl, openAppStream, } from "@homespunapps/core";
+import { assertKnownFlags } from "../argv.js";
+import { makeClient, resolveConfig } from "../config.js";
+import { fail, failFromError, printJson, printJsonLine } from "../output.js";
+import { resolveAppId } from "../resolve-app.js";
+export const appsHelp = `homespun apps — app lifecycle management
+
+Usage:
+  homespun apps list   [--status active|dormant|archived|all] [--limit] [--cursor] [--slug <slug>]
+  homespun apps show   <app>
+  homespun apps update <app> --visibility <private|link|public>
+  homespun apps delete <app> [--yes]
+  homespun apps wake   <app>
+  homespun apps watch  <app> [--since <cursor>] [--collection <name[,name2,...]>]
+                   [--once] [--timeout <secs>]
+
+<app> accepts either the app_id or its slug (resolved via GET /v1/apps?slug=
+when it doesn't look like a cuid).
+
+watch streams the app's change feed as JSON-lines on stdout — one compact
+SerializedFeedEntry object per line, identical whether served over the live
+WebSocket (primary) or the long-poll fallback (used automatically when the
+WS upgrade fails, e.g. self-host mode has no WS support yet, or a locked-down
+network blocks outbound WS). A dormancy transition mid-watch emits a single
+{"type":"_dormant"} line and exits 0.
+
+Output (JSON; JSON-lines for watch). Errors on stderr:
+{"error":{"code","message"}} with non-zero exit.`;
+export async function runApps(args) {
+    const verb = args.positionals[0];
+    if ((verb === undefined || verb === "help") && args.bools.has("help")) {
+        process.stdout.write(appsHelp + "\n");
+        return;
+    }
+    if (verb === undefined) {
+        fail("missing verb — homespun apps <list|show|update|delete|wake|watch>", "invalid_args");
+    }
+    const sub = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+        ...(args.danglingValueFlags !== undefined
+            ? { danglingValueFlags: args.danglingValueFlags }
+            : {}),
+    };
+    switch (verb) {
+        case "list":
+            return runList(sub);
+        case "show":
+            return runShow(sub);
+        case "update":
+            return runUpdate(sub);
+        case "delete":
+            return runDelete(sub);
+        case "wake":
+            return runWake(sub);
+        case "watch":
+            return runWatch(sub);
+        default:
+            fail(`unknown verb '${verb}' — homespun apps <list|show|update|delete|wake|watch>`, "invalid_args");
+    }
+}
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+async function runList(args) {
+    assertKnownFlags(args, ["status", "limit", "cursor", "slug", "url", "api-key"], ["help"], "homespun apps list");
+    const status = args.flags.get("status");
+    if (status !== undefined &&
+        !["active", "dormant", "archived", "all"].includes(status)) {
+        fail("--status must be active|dormant|archived|all", "invalid_args");
+    }
+    const limitRaw = args.flags.get("limit");
+    const limit = limitRaw !== undefined ? Number(limitRaw) : undefined;
+    if (limit !== undefined && !Number.isInteger(limit)) {
+        fail("--limit must be an integer", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const page = await client.listApps({
+            status,
+            limit,
+            cursor: args.flags.get("cursor"),
+            slug: args.flags.get("slug"),
+        });
+        printJson(page);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// show
+// ---------------------------------------------------------------------------
+async function runShow(args) {
+    assertKnownFlags(args, ["url", "api-key"], ["help"], "homespun apps show");
+    const appArg = args.positionals[0];
+    if (!appArg)
+        fail("usage: homespun apps show <app>", "invalid_args");
+    const client = makeClient(args);
+    const id = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.getApp(id));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// update
+// ---------------------------------------------------------------------------
+async function runUpdate(args) {
+    assertKnownFlags(args, ["visibility", "url", "api-key"], ["help"], "homespun apps update");
+    const appArg = args.positionals[0];
+    if (!appArg) {
+        fail("usage: homespun apps update <app> --visibility <private|link|public>", "invalid_args");
+    }
+    const visibility = args.flags.get("visibility");
+    if (visibility === undefined) {
+        fail("--visibility is required", "invalid_args");
+    }
+    if (!["private", "link", "public"].includes(visibility)) {
+        fail("--visibility must be private|link|public", "invalid_args");
+    }
+    const client = makeClient(args);
+    const id = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.updateApp(id, visibility));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// delete
+// ---------------------------------------------------------------------------
+async function runDelete(args) {
+    assertKnownFlags(args, ["url", "api-key"], ["yes", "help"], "homespun apps delete");
+    const appArg = args.positionals[0];
+    if (!appArg)
+        fail("usage: homespun apps delete <app> [--yes]", "invalid_args");
+    if (!args.bools.has("yes")) {
+        fail("'homespun apps delete' permanently removes the app and all its data — it is destructive. Pass --yes to confirm.", "invalid_args");
+    }
+    const client = makeClient(args);
+    const id = await resolveAppId(client, appArg);
+    try {
+        await client.deleteApp(id);
+        printJson({ deleted: true, app_id: id });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// wake
+// ---------------------------------------------------------------------------
+async function runWake(args) {
+    assertKnownFlags(args, ["url", "api-key"], ["help"], "homespun apps wake");
+    const appArg = args.positionals[0];
+    if (!appArg)
+        fail("usage: homespun apps wake <app>", "invalid_args");
+    const client = makeClient(args);
+    const id = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.wakeApp(id));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// watch — WS primary, long-poll fallback; identical JSON-lines either way
+// ---------------------------------------------------------------------------
+/**
+ * The one function that turns an `AppFeedEntry` into stdout output — called
+ * from BOTH the WS entry handler and the long-poll loop below, so the two
+ * transports are provably byte-identical in what they print (spec-cli §5).
+ * Exported for unit testing.
+ */
+export function printFeedEntryLine(entry, collectionFilter) {
+    if (collectionFilter !== null &&
+        !collectionFilter.has(entry.collection_name)) {
+        return;
+    }
+    printJsonLine(entry);
+}
+/** Parse `--collection a,b,c` into a filter set, or null when omitted. */
+export function parseCollectionFilter(raw) {
+    if (raw === undefined)
+        return null;
+    const names = raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    return new Set(names);
+}
+/**
+ * True iff `err` is the relay's "app is dormant" 409 (assertAppActiveForData
+ * on the long-poll route) — the long-poll transport's ONLY signal for the
+ * same dormancy transition the WS path gets as an explicit `_dormant` frame.
+ * Exported for unit testing.
+ */
+export function isDormantConflict(err) {
+    return (err instanceof HomespunApiError &&
+        err.code === "conflict" &&
+        err.message === "app is dormant");
+}
+async function runWatch(args) {
+    assertKnownFlags(args, ["since", "collection", "timeout", "url", "api-key"], ["once", "help"], "homespun apps watch");
+    const appArg = args.positionals[0];
+    if (!appArg)
+        fail("usage: homespun apps watch <app>", "invalid_args");
+    const sinceRaw = args.flags.get("since");
+    let since = 0;
+    if (sinceRaw !== undefined) {
+        const n = Number(sinceRaw);
+        if (!Number.isInteger(n) || n < 0) {
+            fail("--since must be a non-negative integer cursor", "invalid_args");
+        }
+        since = n;
+    }
+    const collectionFilter = parseCollectionFilter(args.flags.get("collection"));
+    const once = args.bools.has("once");
+    let timeoutSec = null;
+    const timeoutRaw = args.flags.get("timeout");
+    if (timeoutRaw !== undefined) {
+        const t = Number(timeoutRaw);
+        if (!Number.isFinite(t) || t <= 0) {
+            fail("--timeout must be a positive number", "invalid_args");
+        }
+        timeoutSec = t;
+    }
+    const cfg = resolveConfig(args);
+    const client = makeClient(args);
+    let appId;
+    let appUrl;
+    try {
+        appId = await resolveAppId(client, appArg);
+        appUrl = (await client.getApp(appId)).url;
+    }
+    catch (e) {
+        failFromError(e);
+    }
+    let exited = false;
+    let timer;
+    const finish = (code) => {
+        if (exited)
+            return;
+        exited = true;
+        if (timer)
+            clearTimeout(timer);
+        process.exit(code);
+    };
+    if (timeoutSec !== null) {
+        timer = setTimeout(() => {
+            fail(`no terminal condition met within ${timeoutSec}s`, "ws_timeout");
+        }, timeoutSec * 1000);
+    }
+    const emitDormant = () => {
+        printJsonLine({ type: "_dormant" });
+        finish(0);
+    };
+    // Long-poll fallback loop (spec-cli §5) — GET /v1/apps/:id/feed?wait=25.
+    // Uses the SAME printFeedEntryLine as the WS entry handler below, so a
+    // caller piping `homespun apps watch` output can never tell which transport
+    // served a given line.
+    async function runLongPoll(startSince) {
+        let cursor = startSince;
+        while (!exited) {
+            let page;
+            try {
+                page = await client.getAppFeed(appId, { since: cursor, wait: 25 });
+            }
+            catch (e) {
+                if (isDormantConflict(e)) {
+                    emitDormant();
+                    return;
+                }
+                failFromError(e);
+                return;
+            }
+            for (const entry of page.entries) {
+                printFeedEntryLine(entry, collectionFilter);
+                cursor = Math.max(cursor, entry.seq);
+                if (once) {
+                    finish(0);
+                    return;
+                }
+            }
+            cursor = Math.max(cursor, page.cursor);
+        }
+    }
+    let wsConnected = false;
+    let fellBack = false;
+    const wsUrl = appWsUrlFromAppUrl(appUrl);
+    const handle = openAppStream({ wsUrl, apiKey: cfg.apiKey, since }, {
+        onHello: () => {
+            wsConnected = true;
+        },
+        onEntry: (entry) => {
+            printFeedEntryLine(entry, collectionFilter);
+            if (once)
+                finish(0);
+        },
+        onDormant: () => {
+            emitDormant();
+        },
+        onResync: () => {
+            printJsonLine({ type: "resync" });
+        },
+        onClose: ({ code, reason }) => {
+            if (exited)
+                return;
+            // If we've already fallen back (this close is very likely the
+            // trailing `close` frame ~50ms behind the `error` event that
+            // triggered the fallback), the long-poll loop now OWNS termination —
+            // this handler must be a no-op, not call fail() and exit(1) out from
+            // under the just-started long-poll (the HIGH bug this guards).
+            if (fellBack)
+                return;
+            if (!wsConnected) {
+                fellBack = true;
+                void runLongPoll(since);
+                return;
+            }
+            if (code === 1000 || code === 1001) {
+                finish(0);
+                return;
+            }
+            fail(`app stream closed abnormally (code ${code})${reason ? ": " + reason : ""}`, "ws_closed_abnormally", { code, reason });
+        },
+        onError: () => {
+            if (exited)
+                return;
+            if (fellBack)
+                return;
+            if (!wsConnected) {
+                fellBack = true;
+                void runLongPoll(since);
+                return;
+            }
+            // A transport error after a successful connect — fall through to
+            // the same terminal handling `onClose` would give a non-clean close.
+        },
+    });
+    process.on("SIGINT", () => {
+        handle.close();
+        finish(0);
+    });
+    await new Promise(() => {
+        /* never resolves — SIGINT or a terminal condition exits */
+    });
+}