@catalyst-cloud/cli 0.14.7 → 0.14.8

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.14.8
+
+- Onboarding on a computer with no browser, such as a Docker container, prints the Catalyst page that finishes each Linear and GitHub approval and keeps waiting, instead of stopping.
+- Onboarding accepts cloud repository IDs such as `tenant-9:owner__repo`, so registering a project no longer fails on them.
+- When the sign-in expires during a provider approval, onboarding stops and says to run `catalyst login`, instead of waiting for the approval to time out.
+- Steps that wait name the next action and the page to use, and the end of a run lists what is left.
+- `catalyst login` says the browser opened only when it did.
+- Onboarding finishes once everything work needs is in place. Repository settings, values and the daily update are listed as next steps instead of blocking.
+
 ## 0.14.7
 
 - Setup uses cloud reads by default and offers local sync as an option. Onboarding preserves verified account and repository choices when it resumes.

package/README.md

@@ -153,14 +153,14 @@ Nothing, by default. After `login`, every read, write, ask and explanation goes
 | process | needed for | what it holds on disk | lifetime |
 | --- | --- | --- | --- |
 | none | every read, write, ask and explain | `customer.json` and `contract.json` | the default after login |
-| `catalyst replica start` | local SQL, cheap repeated reads, and local event `tail`, `wait-for`, and `query` | one SQLite file plus a bounded event cache under `$XDG_STATE_HOME/catalyst/events/` (fallback `~/.local/state/catalyst/events/`) | one long-running process; foreground by default, `--detach` writes a pidfile beside the database and returns; `login --start-replica` does the same at the end of login |
+| `catalyst replica start` | local SQL, cheap repeated reads, and a shared local event cache read with `events ... --from-cache` | one SQLite file plus a bounded event cache under `$XDG_STATE_HOME/catalyst/events/` (fallback `~/.local/state/catalyst/events/`) | one long-running process; foreground by default, `--detach` writes a pidfile beside the database and returns; `login --start-replica` does the same at the end of login |
 | `catalyst watch` | a project owner reacting to its scope | one cursor file (`~/.config/catalyst-cloud/watch-cursor.json`) stamped with the account | lives inside the session that armed it; exits with it |
 
 CLI and skill reads use the cloud API by default, including on a machine with a fresh local replica. No background writer or local database is needed. `catalyst query ... --source replica` explicitly chooses the optional local view; the first stderr line names the source. Local sync does not promise offline browsing.
 
 For a local view, `catalyst replica status` checks the writer, heartbeat and cursor. It exits `0` for fresh, `1` for present but stale, `2` for not connected, `3` for absent. `replica status --probe` compares its cursor with the cloud head. These diagnostics do not change the default read source, and an absent replica does not make `catalyst ready` fail.
 
-`catalyst events status --probe` checks the event cache's own cursor and compares it with the cloud head; `replica status --probe` checks the separate entity-replica cursor. A fresh replica does not prove event freshness. `events tail` follows new cached events, `events wait-for --ticket ... --timeout ...` performs a bounded wait, and `events query` reads retained history. Those three commands only read the cache; `events status --probe` makes the cloud comparison. The replica process is the single writer and reports an event-sync failure without terminating a healthy entity replica. The event cache keeps closed daily segments for at most seven days or 256 MiB per account and reports an explicit gap when a requested sequence has retired.
+`catalyst events tail`, `wait-for`, `query` and `status` read from the cloud by default, with no local file. `events tail` prints one JSON line per new event and stays in the foreground; `events wait-for --ticket ... --timeout ...` prints the first match and exits 0, or exits 1 when none arrives in time; `events query` reads one page of filtered history (`--ticket`, `--type`, `--limit` up to 200, `--order desc|asc`, `--before`, `--after`); `events status` names the cloud head. Add `--from-cache` to read this machine's local event cache instead, which pays off when several agents on one machine share one cloud connection. `catalyst events status --from-cache --probe` checks the cache's own cursor against the cloud head; `replica status --probe` checks the separate entity-replica cursor. A fresh replica does not prove event freshness. The replica process is the single writer and reports an event-sync failure without terminating a healthy entity replica. The event cache keeps closed daily segments for at most seven days or 256 MiB per account and reports an explicit gap when a requested sequence has retired.
 
 The replica is a Node process, not a service: the supported path is the plain command, and `skills/catalyst-onboard/references/local-sync.md` gives launchd and systemd examples for people who want the writer to survive a reboot.
 

package/dist/args.js

@@ -107,27 +107,39 @@ export const FLAG_TABLES = {
         },
     },
     events: {
+        "from-cache": {
+            value: false,
+            help: "read the local event cache instead of the cloud (opt-in local sync)",
+        },
         probe: {
             value: false,
-            help: "status: compare the local event cursor with the cloud event head",
+            help: "status --from-cache: compare the local event cursor with the cloud event head",
         },
         type: { value: true, help: "exact event type" },
         ticket: {
             value: true,
-            help: "ticket identifier found in the event payload",
+            help: "ticket identifier found in the event",
         },
         after: {
             value: true,
-            help: "event sequence to read after (tail/wait default to local head)",
+            help: "event sequence to read after (tail and wait-for default to new events only)",
+        },
+        before: {
+            value: true,
+            help: "query: event sequence to read before (newest-first paging)",
+        },
+        order: { value: true, help: "query: desc (newest first, default) or asc" },
+        limit: {
+            value: true,
+            help: "query: maximum matching events (default 50; at most 200 from the cloud)",
         },
-        limit: { value: true, help: "query: maximum matching events (default 50)" },
         timeout: {
             value: true,
             help: "wait-for: bounded wait in seconds (default 300)",
         },
         directory: {
             value: true,
-            help: "event cache directory (default: SDK XDG path)",
+            help: "with --from-cache: event cache directory (default: SDK XDG path)",
         },
     },
     explain: {

package/dist/browser.js

@@ -3,12 +3,15 @@
 // this never throws into the login flow — the caller wraps it, and a spawn failure is swallowed here.
 import { spawn } from "node:child_process";
 /** The platform's "open this URL" command. `open` on macOS, `start` via cmd on Windows, else xdg-open. */
-export function openBrowser(url) {
-    const [cmd, args] = process.platform === "darwin"
+function opener(url, platform = process.platform) {
+    return platform === "darwin"
         ? ["open", [url]]
-        : process.platform === "win32"
+        : platform === "win32"
             ? ["cmd", ["/c", "start", "", url]]
             : ["xdg-open", [url]];
+}
+export function openBrowser(url) {
+    const [cmd, args] = opener(url);
     try {
         const child = spawn(cmd, [...args], { stdio: "ignore", detached: true });
         child.on("error", () => { }); // no opener installed — the printed URL is the fallback
@@ -18,3 +21,34 @@ export function openBrowser(url) {
         // spawn itself threw (unusual) — the code and URL on screen are the fallback
     }
 }
+/** Login's opener: rejects when no opener ran (none installed, or it exited non-zero, as xdg-open does
+ *  with no browser), so login claims an opened browser only when one did. An opener still running
+ *  after `waitMs` launched something and counts as opened. */
+export function openBrowserChecked(url, options = {}) {
+    const [cmd, args] = opener(url, options.platform);
+    const launch = options.launch ??
+        ((command, list) => spawn(command, [...list], { stdio: "ignore", detached: true }));
+    return new Promise((resolve, reject) => {
+        const fail = () => reject(new Error("browser-unavailable"));
+        let child;
+        try {
+            child = launch(cmd, args);
+        }
+        catch {
+            return fail();
+        }
+        child.unref();
+        const timer = setTimeout(resolve, options.waitMs ?? 3_000);
+        child.once("error", () => {
+            clearTimeout(timer);
+            fail();
+        });
+        child.once("exit", (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve();
+            else
+                fail();
+        });
+    });
+}

package/dist/cli.js

@@ -8,7 +8,7 @@ import { loadContract, pickPath } from "./contract.js";
 import { CliError, MeError, UsageError } from "./errors.js";
 import { fetchMe } from "./transport.js";
 import { bearerFor, deviceFlowLogin } from "./oauth.js";
-import { openBrowser as defaultOpenBrowser } from "./browser.js";
+import { openBrowserChecked as defaultOpenBrowser } from "./browser.js";
 import { cmdAccounts, cmdExplain, cmdHistory, cmdQueue, cmdRunning, } from "./execution.js";
 import { cmdQuery } from "./query.js";
 import { cmdReady } from "./ready.js";
@@ -38,6 +38,7 @@ import { cmdConnections } from "./connections.js";
 import { cmdOnboard, onboardErrorJournal } from "./onboard.js";
 import { createClackOnboardUi, shouldUseOnboardUi, } from "./onboard-ui.js";
 import { createOnboardRuntime } from "./onboard-runtime.js";
+import { savedOnboardBaseUrl } from "./onboard-next.js";
 import { onboardingReadyReport, observeCloudOnboarding, } from "./onboard-ready.js";
 import { selectedOnboardTeam } from "./onboard-existing.js";
 export { CONFIG_MODE, DEFAULT_BASE_URL, FIRST_STAMPED_VERSION, LEGACY_PACKAGE_NAME, PACKAGE_NAME, PROVENANCE_MARKER, CliError, MeError, UsageError, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, fetchMe, formatMode, installedBundleVersion, installSkills, loadConfig, modernCliPath, normalizeBaseUrl, parseArgs, parseChangelogEntry, parseProvenanceVersion, readChangelog, readManifest, resolveSkillsDir, saveConfig, skillsSourceDir, updateNoticeLine, writeConfig, };
@@ -72,7 +73,7 @@ export function usageText() {
         "  catalyst query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>>",
         '  catalyst replica <start [--detach]|stop|status [--probe]|sql "<select>"|schema [table]>',
         "  catalyst runtime <status [--json]|install|path|uninstall>   (a pinned Node this CLI manages itself)",
-        "  catalyst events <tail|wait-for|query|status [--probe]> [--type NAME] [--ticket CTC-N] [--after SEQUENCE]",
+        "  catalyst events <tail|wait-for|query|status> [--type NAME] [--ticket CTC-N] [--after SEQUENCE] [--from-cache]",
         "  catalyst explain <ticket> | history <ticket> | running [--ticket T --phase P] | queue [--team K]",
         "  catalyst watch [--team K] [--ticket T]... [--project P] [--exec CMD]",
         "  catalyst write <comment|state|label|create|reaction|attachment|session> ...",
@@ -253,10 +254,7 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                     }
                     if (input.isTTY) {
                         try {
-                            ui = createClackOnboardUi(await import("@clack/prompts"), {
-                                input,
-                                output: process.stdout,
-                            });
+                            ui = createClackOnboardUi(await import("@clack/prompts"), { input, output: process.stdout }, { baseUrl: () => savedOnboardBaseUrl(ctx.home) });
                         }
                         catch (error) {
                             terminal?.destroy();

package/dist/config.js

@@ -1,5 +1,3 @@
-// config.ts — ~/.config/catalyst-cloud/customer.json and its siblings. The ONLY place the base URL
-// and the `/api/v1` prefix are joined: the SDK wants the base with the prefix, GET /me without.
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { dirname, join } from "node:path";
@@ -22,6 +20,7 @@ export function defaultCtx() {
         env: process.env,
         home: process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? "/",
         stdout: (line) => console.log(line),
+        stdoutStream: process.stdout,
         stderr: (line) => console.error(line),
         fetch: fetch,
         now: () => new Date(),

package/dist/consent-browser.js

@@ -0,0 +1,58 @@
+import { spawn } from "node:child_process";
+/** Consent links are credentials. Keep them out of errors and join the opener before continuing. */
+export function createConsentBrowserOpener(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const killGraceMs = options.killGraceMs ?? 500;
+    const launch = options.launch ?? ((command, args) => spawn(command, [...args], { stdio: "ignore", detached: false }));
+    return async (url, signal) => {
+        if (signal?.aborted)
+            throw new DOMException("Browser opening interrupted", "AbortError");
+        const [command, args] = platform === "darwin"
+            ? ["open", [url]]
+            : platform === "win32"
+                ? ["cmd", ["/c", "start", "", url]]
+                : ["xdg-open", [url]];
+        let child;
+        try {
+            child = launch(command, args);
+        }
+        catch {
+            throw new Error("Browser could not open");
+        }
+        await new Promise((resolve, reject) => {
+            let interrupted = false;
+            let expired = false;
+            let failed = false;
+            let killTimer;
+            const stop = () => {
+                child.kill("SIGTERM");
+                killTimer ??= setTimeout(() => { child.kill("SIGKILL"); }, killGraceMs);
+            };
+            const abort = () => { interrupted = true; stop(); };
+            const timer = setTimeout(() => { expired = true; stop(); }, timeoutMs);
+            child.once("error", () => { failed = true; });
+            child.once("close", (code) => {
+                clearTimeout(timer);
+                if (killTimer)
+                    clearTimeout(killTimer);
+                signal?.removeEventListener("abort", abort);
+                if (interrupted)
+                    reject(new DOMException("Browser opening interrupted", "AbortError"));
+                else if (failed || expired || code !== 0)
+                    reject(new Error("Browser could not open"));
+                else
+                    resolve();
+            });
+            signal?.addEventListener("abort", abort, { once: true });
+            if (signal?.aborted)
+                abort();
+        });
+    };
+}
+export const openConsentBrowser = createConsentBrowserOpener();
+/** The web page that finishes a consent step when no browser opens here. The signed link stays private. */
+export function finishOnTheWeb(baseUrl, page, action) {
+    const origin = baseUrl.replace(/\/+$/, "");
+    return `No browser opened on this computer. In a browser signed in to Catalyst, open ${origin}/settings/${page} and ${action}. Setup keeps waiting here.`;
+}

package/dist/env/onboard-draft-store.js

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+import { isRepositoryId } from "../repository-id.js";
 import { constants } from "node:fs";
 import { lstat, mkdir, open, unlink } from "node:fs/promises";
 import { isAbsolute, join, parse, resolve, sep } from "node:path";
@@ -18,8 +20,7 @@ export async function storeOnboardDraft(input, fsOps = defaultFs) {
     const signal = input?.signal;
     if (typeof runId !== "string" ||
         !OPAQUE_ID_RE.test(runId) ||
-        typeof repoId !== "string" ||
-        !OPAQUE_ID_RE.test(repoId) ||
+        !isRepositoryId(repoId) ||
         typeof home !== "string" ||
         !isAbsolute(home) ||
         typeof toml !== "string" ||
@@ -36,7 +37,13 @@ export async function storeOnboardDraft(input, fsOps = defaultFs) {
         if (stateRoot === parse(stateRoot).root || stateRoot === resolve(home))
             return { state: "rejected" };
         runDir = join(stateRoot, "install", "drafts", runId);
-        destination = join(runDir, `${repoId}.toml`);
+        // Keep earlier slug filenames resumable. New cloud IDs use a portable bounded filename;
+        // punctuation normalization would collide and raw IDs can exceed NAME_MAX.
+        // The @ namespace cannot collide with any earlier slug filename.
+        const filename = OPAQUE_ID_RE.test(repoId)
+            ? `${repoId}.toml`
+            : `repo@${createHash("sha256").update(repoId, "utf8").digest("hex")}.toml`;
+        destination = join(runDir, filename);
     }
     catch {
         return { state: "rejected" };

package/dist/env/settings-authority.js

@@ -1,3 +1,4 @@
+import { isRepositoryId } from "../repository-id.js";
 import { createHash } from "node:crypto";
 import { constants } from "node:fs";
 import { lstat, open, realpath } from "node:fs/promises";
@@ -12,7 +13,8 @@ const refused = () => ({
 const opaque = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
 function snapshotContext(raw) {
     if (!raw ||
-        ![raw.accountId, raw.personId, raw.teamId, raw.repoId].every((id) => typeof id === "string" && opaque.test(id)))
+        !isRepositoryId(raw.repoId) ||
+        ![raw.accountId, raw.personId, raw.teamId].every((id) => typeof id === "string" && opaque.test(id)))
         return null;
     if (!["owner", "admin", "member"].includes(raw.role) ||
         !/^[A-Z][A-Z0-9]{0,15}$/.test(raw.teamKey))

package/dist/events-cloud-tail.js

@@ -1,20 +1,32 @@
 import { cloudEvents } from "./events-cloud.js";
-/** The same matching rules as the local tail, so a filter means one thing from either source. */
+// A lease causation names its ticket: `lease:<ticket>/<phase>#<nonce>` (event-index/fields.ts).
+const CAUSED_BY_LEASE = /^lease:([^/]+)\/[^#]+#/;
+// The index stores at most this many UTF-8 bytes of ticket; a longer value is not indexed.
+const MAX_INDEXED_TICKET_BYTES = 64;
+function boundedTicket(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return null;
+    return new TextEncoder().encode(value).length > MAX_INDEXED_TICKET_BYTES ? null : value;
+}
+/** The ticket an event is about, resolved exactly as the cloud's event index resolves it
+ *  (catalyst-cloud apps/mirror/src/event-index/fields.ts): a `ticket` entity's id, then
+ *  `payload.ticket`, then the lease that caused it, each at most 64 bytes. A body-unavailable stub
+ *  carries the index's own `ticket`. Nothing else counts, so `--from-cache` matches exactly what the
+ *  cloud path returns. */
+export function eventTicket(event) {
+    const e = event;
+    if (e.bodyUnavailable === true)
+        return boundedTicket(e.ticket);
+    const fromEntity = e.entity?.type === "ticket" ? boundedTicket(e.entity.id) : null;
+    const payload = e.payload && typeof e.payload === "object" ? e.payload : undefined;
+    const lease = typeof e.causationId === "string" ? CAUSED_BY_LEASE.exec(e.causationId) : null;
+    return fromEntity ?? boundedTicket(payload?.ticket) ?? boundedTicket(lease?.[1]);
+}
+/** The type and ticket filter, the same on the cloud and the local cache paths. */
 export function eventMatches(filter) {
     const ticket = filter.ticket?.toUpperCase();
     return (event) => (!filter.type || event.type === filter.type) &&
-        (!ticket || payloadReferences(event.payload, ticket));
-}
-function payloadReferences(value, ticket) {
-    if (typeof value === "string")
-        return value.toUpperCase() === ticket;
-    if (Array.isArray(value))
-        return value.some((item) => payloadReferences(item, ticket));
-    if (!value || typeof value !== "object")
-        return false;
-    return Object.entries(value).some(([key, item]) => ["ticket", "identifier", "workItemKey", "issueIdentifier"].includes(key) && typeof item === "string"
-        ? item.toUpperCase() === ticket
-        : payloadReferences(item, ticket));
+        (!ticket || eventTicket(event)?.toUpperCase() === ticket);
 }
 function pipeClosed(error) {
     const code = error?.code;

package/dist/events-cloud.js

@@ -11,6 +11,22 @@ const maxLagPoll = 8_000;
 // CTC-4562 — once the cloud pushes events, the replay is only a safety net for a silent socket.
 const pushedFallback = 600_000;
 const polledFallback = 30_000;
+/** A short, credential-free name for why the cloud could not be reached. */
+export function unreachableKind(error) {
+    if (error instanceof RetryRequest)
+        return "service unavailable";
+    const name = error?.name;
+    if (name === "TimeoutError" || name === "AbortError")
+        return "timed out";
+    if (error instanceof TypeError)
+        return "network error";
+    return "service unavailable";
+}
+/** CTC-4554 — an unreachable cloud is a named failure with its own exit code, never a crash. The
+ *  message names only the kind: a transport error can carry a URL with a credential in it. */
+export function unreachableError(error) {
+    return new CliError(`the cloud event service is unreachable (${unreachableKind(error)}); try again shortly`, "events-unreachable", 4);
+}
 function sequence(value) {
     return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
 }
@@ -79,17 +95,32 @@ async function send(ctx, url, accept, allowed, signal) {
         throw new CliError("cloud event access refused; check catalyst status and sign in again", "events-auth", 2, response.status);
     }
     if (response.status !== 200 && !allowed.includes(response.status)) {
-        await response.body?.cancel();
         if (response.status >= 500 || response.status === 429) {
+            await response.body?.cancel();
             const raw = response.headers.get("retry-after");
             const seconds = raw === null ? NaN : Number(raw);
             const delay = Number.isFinite(seconds) ? seconds * 1_000 : raw ? Date.parse(raw) - ctx.now().getTime() : 0;
             throw new RetryRequest(Number.isFinite(delay) ? Math.min(300_000, Math.max(0, delay)) : 0);
         }
-        throw new CliError(`cloud event request refused (HTTP ${response.status})`, "events-http", 2, response.status);
+        throw new CliError(`cloud event request refused (HTTP ${response.status}${await refusalReason(response)})`, "events-http", 2, response.status);
     }
     return response;
 }
+/** The server's own reason for a refusal, e.g. `: unknown_event_type (nope)`; empty when it gave none. */
+async function refusalReason(response) {
+    try {
+        const text = await response.text();
+        if (text.length > maxLine)
+            return "";
+        const body = JSON.parse(text);
+        if (typeof body.error !== "string")
+            return "";
+        return `: ${body.error}${Array.isArray(body.types) ? ` (${body.types.join(", ")})` : ""}`;
+    }
+    catch {
+        return "";
+    }
+}
 /** Probe the head without downloading the backlog. An ahead-of-head cursor is deliberate. */
 export async function cloudEventHead(ctx, signal = AbortSignal.timeout(15_000)) {
     const response = await request(ctx, Number.MAX_SAFE_INTEGER, signal);
@@ -104,12 +135,76 @@ export async function cloudEventHead(ctx, signal = AbortSignal.timeout(15_000))
         await response.body?.cancel();
     }
 }
+/** CTC-4554 — read one page of `GET /api/v1/events/query`. A refusal names the server's reason. */
+export async function queryCloudEvents(ctx, query, signal = AbortSignal.timeout(30_000)) {
+    const url = eventsUrl(ctx, "query", {
+        order: query.order,
+        limit: String(query.limit),
+        type: query.type,
+        ticket: query.ticket,
+        afterSeq: query.afterSeq === undefined ? undefined : String(query.afterSeq),
+        beforeSeq: query.beforeSeq === undefined ? undefined : String(query.beforeSeq),
+    });
+    let response;
+    try {
+        response = await send(ctx, url, "application/json", [400, 404, 413], signal);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw unreachableError(error);
+    }
+    if (response.status === 404) {
+        await response.body?.cancel();
+        throw new CliError("this cloud does not serve the events query yet; read the local cache with --from-cache", "events-unavailable", 2, 404);
+    }
+    const text = await response.text();
+    if (text.length > maxQueryBody)
+        throw protocol("cloud event query response exceeds its size limit");
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw protocol("cloud event query returned invalid JSON");
+    }
+    const page = (body && typeof body === "object" ? body : {});
+    if (response.status !== 200) {
+        const reason = typeof page.error === "string" ? page.error : "no reason given";
+        const detail = Array.isArray(page.types) ? ` (${page.types.join(", ")})` : "";
+        throw new CliError(`the cloud refused the events query: ${reason}${detail} (HTTP ${response.status})`, "events-http", 2, response.status);
+    }
+    const account = requireConfig(ctx).account;
+    if (!Array.isArray(page.events))
+        throw protocol("cloud event query returned an invalid page");
+    for (const value of page.events) {
+        const event = (value && typeof value === "object" ? value : {});
+        if (event.tenantId !== account || !sequence(event.sequence) || typeof event.eventId !== "string" || typeof event.type !== "string")
+            throw protocol("cloud event query contains an invalid tenant or event");
+    }
+    const next = page.next;
+    if (next !== null && !(next && (next.param === "beforeSeq" || next.param === "afterSeq") && sequence(next.value)))
+        throw protocol("cloud event query returned an invalid next cursor");
+    const coverage = (page.coverage ?? {});
+    const bound = (v) => (sequence(v) ? v : null);
+    return {
+        events: page.events,
+        next: next === null ? null : { param: next.param, value: next.value },
+        coverage: { indexedFromSeq: bound(coverage.indexedFromSeq), indexedToSeq: bound(coverage.indexedToSeq) },
+    };
+}
 function validEvent(ctx, value, cursor) {
     if (!value || typeof value !== "object")
         return false;
     const event = value;
-    return event.tenantId === requireConfig(ctx).account && sequence(event.sequence) && event.sequence > cursor &&
-        typeof event.eventId === "string" && typeof event.type === "string" && typeof event.recordedAt === "string" && "payload" in event;
+    if (event.tenantId !== requireConfig(ctx).account || !sequence(event.sequence) || event.sequence <= cursor ||
+        typeof event.eventId !== "string" || typeof event.type !== "string")
+        return false;
+    // CTC-4554 — an event whose archived body is unavailable arrives as a stub (tenantId, sequence,
+    // eventId, type, ticket, bodyUnavailable, reason). It is printed as is, and the cursor moves past it.
+    if (event.bodyUnavailable === true)
+        return true;
+    return typeof event.recordedAt === "string" && "payload" in event;
 }
 // A page closed early by its consumer ends with undefined.
 async function* replay(ctx, after, signal) {
@@ -188,11 +283,24 @@ async function* replay(ctx, after, signal) {
 // `coverage.indexedToSeq` may trail the head; the reader polls until it catches up.
 async function* queryPage(ctx, after, filter, signal) {
     const url = eventsUrl(ctx, "query", { order: "asc", afterSeq: String(after), limit: String(queryLimit), type: filter.type, ticket: filter.ticket });
-    const response = await send(ctx, url, "application/json", [404], signal);
+    const response = await send(ctx, url, "application/json", [404, 413], signal);
     if (response.status === 404) {
         await response.body?.cancel();
         return "absent";
     }
+    if (response.status === 413) {
+        // CTC-4554 — one event over the 1 MiB page limit: skip it with a warning and move past it,
+        // rather than failing the tail and hitting the same event on every resume.
+        let skipped = {};
+        try {
+            skipped = JSON.parse(await response.text());
+        }
+        catch { /* named below */ }
+        if (!sequence(skipped.sequence) || skipped.sequence <= after)
+            throw protocol("cloud event query refused an over-limit event without naming it");
+        ctx.stderr(`events: skipped event ${skipped.sequence}: it is larger than the 1 MiB page limit${sequence(skipped.eventBytes) ? ` (${skipped.eventBytes} bytes)` : ""}`);
+        return { through: skipped.sequence, more: true };
+    }
     const text = await response.text();
     if (text.length > maxQueryBody)
         throw protocol("cloud event query response exceeds its size limit");
@@ -281,6 +389,9 @@ export async function* cloudEvents(ctx, options, deps = {}) {
     // A filter reads the server's index; a server without the route gets the backbone for the whole run.
     let indexed = Boolean(filter.type || filter.ticket);
     let lagPoll = 1_000;
+    // CTC-4554 — consecutive failed attempts, so a caller can tell an outage from a quiet stream.
+    let failures = 0;
+    let failingSince;
     while (!signal.aborted) {
         let socket;
         let heartbeat;
@@ -457,6 +568,11 @@ export async function* cloudEvents(ctx, options, deps = {}) {
                 if (!end)
                     return;
                 backoff = 1_000;
+                if (failures > 0) {
+                    failures = 0;
+                    failingSince = undefined;
+                    deps.onHealthy?.();
+                }
                 if (failure)
                     throw failure;
                 cursor = Math.max(cursor, end.through);
@@ -483,6 +599,9 @@ export async function* cloudEvents(ctx, options, deps = {}) {
             if (error instanceof RetryRequest)
                 retryDelay = error.delayMs;
             // Never propagate socket URLs or transport exceptions: they can contain bearer credentials.
+            failures += 1;
+            failingSince ??= ctx.now().getTime();
+            deps.onTrouble?.({ failures, sinceMs: failingSince });
         }
         finally {
             clearInterval(heartbeat);