@catalyst-cloud/cli 0.16.27 → 0.16.29

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.16.29
+
+The CLI now tells Catalyst Cloud which release you have installed: each request to Catalyst Cloud carries the installed version, and so does `catalyst watch` when it connects. Catalyst Cloud can then tell an out-of-date CLI from a current one. Nothing about your requests changes otherwise. On a Mac self-hosted machine, setup now installs a small agent that measures the Mac's disk, so the machine can take work instead of showing zero free slots. When a machine still shows zero free slots, setup and `catalyst ready` now say why: its disk has not been measured yet, or its free space is below the floor (25 GiB by default), with the numbers and the fix. An updated disk sampler also takes effect straight away: setup reloads the running disk agent whenever the sampler script changes, not only when its schedule file does.
+
+## 0.16.28
+
+`catalyst events wait-for` can now wait on a repository (`--repo owner/name`), a branch (`--ref owner/name:branch`), a pull request (`--pr owner/name#n`), a work session (`--session KEY-123/phase#n`), events addressed to you (`--to me`) or a family of event types (`--type pr.*`). An agent can wait hours for a review or a conflict on its own branch: the wait holds one connection, prints each matching event as one JSON line, and after a dropped connection picks up where it left off without missing or repeating an event. Two new exit codes say why a wait ended without a match. 2 means the cloud refused the wait, for example on a ticket outside your teams, or the wait failed. 3 means `--from-cache` found no local event cache. A wait still exits 1 on a timeout and 4 on an outage, as before, and on a timeout it names the `--after` to resume from. New: `catalyst messages read --ticket KEY-123` prints the messages sent to a ticket on your teams, with each sender and time.
+
 ## 0.16.27
 
 A large workspace's local replica now finishes its first download instead of stopping after 30 seconds: it waits as long as data keeps arriving, and gives up only after 150 seconds with no progress. New commands: `catalyst repo status` lists your repositories and whether each is paused, and `catalyst repo pause|resume` pauses or resumes one (owners and admins). `catalyst runner status|stop|start|uninstall` stops a self-hosted machine taking work, starts it again with the same registration, or removes it and revokes its registration. Setup with local sync off now lists an old local replica's files with their sizes and removes them only after you say yes. Setup with local sync on keeps using the replica you already have. On a Mac where Docker Desktop does not share your home folder, setup now says which setting to change (Settings, then Resources, then File sharing).

package/README.md

@@ -164,7 +164,7 @@ Before any network call, the run checks that every input is present. Each missin
 
 With a person at the terminal, `catalyst onboard` starts each of these approvals itself and prints the exact link to approve.
 
-With `--runner yes`, setup starts the self-hosted runner and verifies enrollment, advertised capacity and team admission. This needs Docker with Compose, pinned host images and an organization key file (`CATALYST_RUNNER_ORG_KEY_FILE`). When images, a key or admission are missing, exit 11 names that gate. A failed setup step exits 10. Use `--runner no` to skip the machine's runner. Unlike the interactive optional runner step, an explicitly requested headless runner must finish before exit 0.
+With `--runner yes`, setup starts the self-hosted runner and verifies enrollment, advertised capacity and team admission. This needs Docker with Compose, pinned host images and an organization key file (`CATALYST_RUNNER_ORG_KEY_FILE`). When images, a key or admission are missing, exit 11 names that gate. A failed setup step exits 10. Use `--runner no` to skip the machine's runner. Unlike the interactive optional runner step, an explicitly requested headless runner must finish before exit 0. On a Mac, setup also installs the `dev.catalystcloud.host-disk` LaunchAgent, which measures the Mac's free disk space every 10 seconds, because Docker's virtual machine cannot see it. It needs Python 3 from Apple's Command Line Tools or Homebrew. When the machine takes no work because the disk Docker uses has less than 25 GiB free (`CATALYST_HOST_FREE_FLOOR_GIB` changes the amount) or has no fresh measurement, exit 11 says which, with the fix, and `catalyst ready` fails its `runner:disk` check the same way. If setup cannot tell which folder holds your Docker engine's disk image, set `CATALYST_HOST_DISK_PATH` to that folder.
 
 ### Stopping or removing this machine's runner
 
@@ -175,9 +175,9 @@ Run these on the machine itself:
 | `catalyst runner stop` | The machine takes no new work. Work it already started finishes or reaches its deadline. Its registration, settings and checkouts are kept, and `catalyst hosts` shows it as `stopped`. |
 | `catalyst runner start` | Starts it again with the same registration. |
 | `catalyst runner status` | Says whether it is running, stopped or not installed. |
-| `catalyst runner uninstall` | Asks first (`--yes` confirms without a terminal; an owner or admin login is needed). It stops new work, revokes the machine's registration and the runner key setup issued, and switches the project's runner admission off when no other machine runs it. Then it removes the runner's containers, their volumes and the session network, and the setup files in the runner folder. On macOS it also removes the storage LaunchAgent and its folders. On Linux it also removes the session-egress units, their script and state, and the `inet catalyst_session` nftables table, through `sudo`. |
+| `catalyst runner uninstall` | Asks first (`--yes` confirms without a terminal; an owner or admin login is needed). It stops new work, revokes the machine's registration and the runner key setup issued, and switches the project's runner admission off when no other machine runs it. Then it removes the runner's containers, their volumes and the session network, and the setup files in the runner folder. On macOS it also removes the storage LaunchAgent and its folders, and the disk-measuring LaunchAgent setup installed. On Linux it also removes the session-egress units, their script and state, and the `inet catalyst_session` nftables table, through `sudo`. |
 
-Uninstall removes only what setup created. Anything that does not match what setup wrote, such as a network with another label or a changed unit file, is left in place. Your repository and thoughts checkouts are kept unless you add `--delete-checkouts`. The command ends with a "Left behind" list naming everything it did not remove. When a step fails, such as a cloud call while you are offline, it says which one and exits 1. Run it again: it picks up where the last run stopped. Do not delete the runner folder by hand while the runner is installed. That deletes its settings while its containers keep running.
+Uninstall removes only what setup created. Anything that does not match what setup wrote, such as a network with another label, a changed unit file or a disk-measuring LaunchAgent that writes somewhere else, is left in place. Your repository and thoughts checkouts are kept unless you add `--delete-checkouts`. The command ends with a "Left behind" list naming everything it did not remove. When a step fails, such as a cloud call while you are offline, it says which one and exits 1. Run it again: it picks up where the last run stopped. Do not delete the runner folder by hand while the runner is installed. That deletes its settings while its containers keep running.
 
 With `--json`, stdout carries exactly one document: the onboarding receipt plus a `headless` block (`schema: "catalyst-onboard-headless/1"`). The block holds the resolved `inputs` (the key appears only as its source: `env`, `file` or `saved`), and lists of items under `missing`, `refused`, `failed`, `deferred` and `warnings`. Each item has `id`, `kind` (`input`, `grant` or `step`), `reason` and a one-line `text`, plus `flag`, `env` and `url` where they apply. Everything else goes to stderr.
 
@@ -246,7 +246,22 @@ CLI and skill reads use the cloud API by default, including on a machine with a
 
 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 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.
+`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.
+
+`events wait-for` can also wait on a repository (`--repo owner/name`), a branch (`--ref owner/name:branch`), a pull request (`--pr owner/name#n`), a phase session (`--session TICKET/phase#n`), events addressed to you (`--to me`), or a family of types (`--type pr.*`). Values of one flag are OR'ed and different flags are AND'ed, and `--repo`, `--ref`, `--pr` and `--session` can repeat. Such a wait holds one connection and prints nothing until a match, so a long `--timeout` such as 14400 costs nothing while it waits. It prints every matching event as one JSON line. After a dropped connection it replays from its cursor, so no event is missed or printed twice.
+
+| `wait-for` exit | Meaning |
+| --- | --- |
+| 0 | a match, printed on stdout |
+| 1 | none arrived in time; with a scope flag, stderr names the `--after` to resume from |
+| 2 | the cloud refused the wait (for example a ticket outside your teams), or the wait failed; stderr gives the reason |
+| 3 | `--from-cache` and the local event cache is absent or its writer stopped |
+| 4 | the cloud was unreachable for five attempts in a row: an outage, not a timeout |
+| 130 | interrupted |
+
+`catalyst messages read --ticket KEY-123 [--since SEQUENCE]` prints the messages sent to a ticket on your teams, with each sender and time, for example after a wait on `--type comms.message.posted` returns.
+
+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

@@ -158,11 +158,16 @@ export const FLAG_TABLES = {
             value: false,
             help: "status --from-cache: compare the local event cursor with the cloud event head",
         },
-        type: { value: true, help: "exact event type" },
+        type: { value: true, help: "exact event type, or for wait-for a family such as pr.*" },
         ticket: {
             value: true,
             help: "ticket identifier found in the event",
         },
+        repo: { value: true, repeat: true, help: "wait-for: repository as owner/name (repeatable)" },
+        ref: { value: true, repeat: true, help: "wait-for: branch as owner/name:branch (repeatable)" },
+        pr: { value: true, repeat: true, help: "wait-for: pull request as owner/name#number (repeatable)" },
+        session: { value: true, repeat: true, help: "wait-for: phase session as TICKET/phase#attempt (repeatable)" },
+        to: { value: true, help: "wait-for: me, for events addressed to this login" },
         after: {
             value: true,
             help: "event sequence to read after (tail and wait-for default to new events only)",
@@ -478,6 +483,10 @@ export const FLAG_TABLES = {
         },
     },
     identity: {},
+    messages: {
+        ticket: { value: true, help: "read: the ticket whose messages to read" },
+        since: { value: true, help: "read: the first message sequence to read (inclusive)" },
+    },
     capabilities: {},
     project: {
         team: {
@@ -564,7 +573,7 @@ export const VERB_USAGE = {
     query: "query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>> [--team K] [--project P] [--state S] [--limit N] [--all] [--source replica|api] [--json]",
     replica: 'replica <start [--detach]|stop|status [--probe] [--json]|sql "<select>"|schema [table]> [--db <path>]',
     runtime: "runtime <status [--json]|install|path|uninstall>",
-    events: "events <tail|wait-for|query|status [--probe] [--json]> [--type NAME] [--ticket CTC-N] [--after SEQUENCE] [--limit N] [--timeout SECONDS] [--directory PATH]",
+    events: "events <tail|wait-for|query|status [--probe] [--json]> [--type NAME] [--ticket CTC-N] [--repo O/N] [--ref O/N:BRANCH] [--pr O/N#N] [--session T/PHASE#N] [--to me] [--after SEQUENCE] [--limit N] [--timeout SECONDS] [--directory PATH]",
     explain: "explain <ticket> [--history] [--json]",
     history: "history <ticket> [--json]",
     running: "running [--ticket T --phase P] [--json]",
@@ -582,6 +591,7 @@ export const VERB_USAGE = {
     secret: "secret set <NAME> --repo <owner/name> [--command '<cmd>'] [--json]   (value from --command, stdin, or a hidden prompt) | secret import <file> --repo <owner/name> [--names NAME[,NAME...]] [--rotate NAME]... [--json]",
     var: "var <set NAME|import <file>> [--repo <owner/name>] [--names NAME[,NAME...]] [--json]   (plain environment variables; set reads stdin or a hidden prompt)",
     identity: "identity linear <status|options|set> [<linearUserId>] [--json]",
+    messages: "messages read --ticket CTC-N [--since SEQUENCE] [--json]",
     capabilities: "capabilities [--json]",
     project: "project <list [--json] | wip-limit <get|set <n>|set default> [--team K] [--json]>",
     repo: "repo <status|pause <owner/name> --reason <text>|resume <owner/name> [--reason <text>]|agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]> [--json]   (status: visible workspace repositories; agents-block/agent-setup: local checkout)",

package/dist/cli-version.js

@@ -0,0 +1,41 @@
+const HEADER = "x-catalyst-cli-version";
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+/** Public package metadata on the selected cloud API transport. All fetch semantics stay intact. */
+export function reportCliVersion(transport, version, origins) {
+    if (version.length > 80 || !VERSION.test(version))
+        return transport;
+    return (input, init) => {
+        let url;
+        try {
+            url = new URL(input instanceof Request ? input.url : String(input));
+            const selected = origins().some(origin => {
+                try {
+                    return new URL(origin).origin === url.origin;
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (!selected || !(url.pathname.startsWith("/api/v1/") || ["/snapshot", "/changes", "/events"].includes(url.pathname)))
+                return transport(input, init);
+        }
+        catch {
+            return transport(input, init);
+        }
+        return transport(input, { ...init, headers: withVersion(init?.headers ?? (input instanceof Request ? input.headers : undefined), version) });
+    };
+}
+function withVersion(headers, version) {
+    // A Headers from another realm or library fails instanceof, and Object.entries would read it as
+    // empty and drop every header the caller sent. Anything iterable that is not an array is copied.
+    if (headers instanceof Headers || (!Array.isArray(headers) && typeof headers?.forEach === "function")) {
+        const copy = new Headers(headers);
+        copy.set(HEADER, version);
+        return copy;
+    }
+    if (Array.isArray(headers))
+        return [...headers.filter(([name]) => name.toLowerCase() !== HEADER), [HEADER, version]];
+    const record = Object.fromEntries(Object.entries(headers ?? {}).filter(([name]) => name.toLowerCase() !== HEADER));
+    record[HEADER] = version;
+    return record;
+}

package/dist/cli.js

@@ -8,6 +8,7 @@ import { existsSync, openSync, closeSync } from "node:fs";
 import { ReadStream as TerminalInput } from "node:tty";
 import { Writable } from "node:stream";
 import { parseArgs, positionals, verbHelp } from "./args.js";
+import { reportCliVersion } from "./cli-version.js";
 import { CONFIG_MODE, DEFAULT_BASE_URL, LEGACY_PACKAGE_NAME, PACKAGE_NAME, cliPath, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, formatMode, installerOwnsSkills, INSTALL_COMMAND, loadConfig, modernCliPath, normalizeBaseUrl, readManifest, requireConfig, saveConfig, writeConfig, } from "./config.js";
 import { loadContract, pickPath } from "./contract.js";
 import { CliError, MeError, UsageError } from "./errors.js";
@@ -47,6 +48,7 @@ import { cmdProject } from "./project.js";
 import { cmdRepo } from "./repo.js";
 import { cmdLegacy } from "./legacy.js";
 import { cmdIdentity } from "./identity.js";
+import { cmdMessages } from "./messages.js";
 import { cmdConnections } from "./connections.js";
 import { cmdOnboard, onboardErrorJournal, onboardStatePath, readOnboardJournal, } from "./onboard.js";
 import { createClackOnboardUi, shouldUseOnboardUi, } from "./onboard-ui.js";
@@ -93,6 +95,7 @@ export function usageText() {
         '  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> [--type NAME] [--ticket CTC-N] [--after SEQUENCE] [--from-cache]",
+        "  catalyst events wait-for [--repo O/N] [--ref O/N:BRANCH] [--pr O/N#N] [--session T/PHASE#N] [--to me] [--type pr.*] [--timeout SECONDS]   (one connection; nothing printed until a match)",
         "  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> ...",
@@ -112,6 +115,7 @@ export function usageText() {
         "  catalyst repo <agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]>   (a checkout's AGENTS.md block and portable agent layout; working tree only)",
         "  catalyst legacy [--remove [--data] [--yes]]   (leftovers of the old local Catalyst runtime: list them; remove them only on a yes)",
         "  catalyst identity linear <status|options|set> [<linearUserId>] [--json]",
+        "  catalyst messages read --ticket CTC-N [--since SEQUENCE] [--json]   (messages sent to a ticket on your teams)",
         "  catalyst connections personal <linear|github> <start|status> [--wait <seconds>] [--json]",
         "",
         "Every verb takes --help. --json makes the output machine-readable.",
@@ -277,6 +281,19 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
         command: args.command,
         version: manifest.version,
     });
+    ctx = {
+        ...ctx,
+        fetch: reportCliVersion(ctx.fetch, manifest.version, () => {
+            let configured;
+            try {
+                configured = loadConfig(ctx.home)?.baseUrl;
+            }
+            catch {
+                // The command reports its existing config error.
+            }
+            return [args.baseUrl, ctx.env.CATALYST_CLOUD_BASE_URL, configured, DEFAULT_BASE_URL].filter((origin) => typeof origin === "string");
+        }),
+    };
     try {
         if (args.command !== "onboard") {
             migrateLegacyCliPath(ctx);
@@ -535,6 +552,8 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdLegacy(args, ctx, { localSyncSelected: savedLocalSync(ctx), ...deps.legacy });
             case "identity":
                 return await cmdIdentity(args, ctx, deps.identity ?? {});
+            case "messages":
+                return await cmdMessages(args, ctx, deps.messages ?? {});
             case "hosts":
                 return await cmdHosts(args, ctx, deps.hosts);
             case "runner":
@@ -599,6 +618,7 @@ const VERB_HELP_KNOWN = Object.fromEntries([
     "environment",
     "connections",
     "identity",
+    "messages",
     "mcp",
     "team",
     "capabilities",

package/dist/events.js

@@ -1,4 +1,4 @@
-import { flagInt, flagString, positionals } from "./args.js";
+import { flagInt, flagList, flagString, positionals } from "./args.js";
 import { normalizeBaseUrl, requireConfig } from "./config.js";
 import { CliError, UsageError } from "./errors.js";
 import { authStrategyFor } from "./oauth.js";
@@ -39,6 +39,13 @@ export async function cmdEvents(args, ctx, deps = {}) {
         throw new UsageError("events needs a subcommand: tail | wait-for | query | status");
     if (!["tail", "wait-for", "query", "status"].includes(sub))
         throw new UsageError(`unknown events subcommand: ${sub}`);
+    // CTC-6650 — a scope key or a type family runs on the SDK's wait; the --type/--ticket path is unchanged.
+    const scope = scopeFilter(args);
+    if (scope) {
+        if (sub !== "wait-for")
+            throw new UsageError("--repo, --ref, --pr, --session, --to and a type family such as pr.* work with wait-for only");
+        return cmdScopedWait(args, ctx, deps, scope);
+    }
     // CTC-4554 — the cloud is the default source; the local event file is the opt-in.
     if (args.flags["from-cache"] !== true) {
         if (flagString(args, "directory") !== undefined)
@@ -118,6 +125,144 @@ function startingCursor(args, name = "after") {
         throw new UsageError(`--${name} must be a non-negative event sequence`);
     return parsed;
 }
+const SCOPE_KEYS = ["repo", "ref", "pr", "session"];
+/** The SDK filter when the wait names a scope key or a type family, or null for the original path. */
+function scopeFilter(args) {
+    const filter = {};
+    for (const key of SCOPE_KEYS) {
+        const values = flagList(args, key);
+        if (values.length)
+            filter[key] = values;
+    }
+    const to = flagString(args, "to");
+    if (to !== undefined) {
+        if (to !== "me")
+            throw new UsageError("--to accepts only me");
+        filter.to = "me";
+    }
+    const type = flagString(args, "type");
+    if (Object.keys(filter).length === 0 && !type?.endsWith(".*"))
+        return null;
+    const ticket = flagString(args, "ticket");
+    return { ...filter, ...(type ? { type } : {}), ...(ticket ? { ticket } : {}) };
+}
+/** Counts consecutive failed requests, so a wait that cannot reach the cloud ends as an outage. */
+function outageFetch(base, signal, onOutage, now) {
+    let failures = 0;
+    let sinceMs = 0;
+    const trouble = () => {
+        if (failures === 0)
+            sinceMs = now();
+        failures += 1;
+        if (failures >= OUTAGE_ATTEMPTS)
+            onOutage(failures, sinceMs);
+    };
+    return async (input, init) => {
+        try {
+            const response = await base(input, init);
+            if (response.status >= 500)
+                trouble();
+            else
+                failures = 0;
+            return response;
+        }
+        catch (error) {
+            // A request the SDK timed out counts; one cancelled because this wait ended does not.
+            if (!signal.aborted)
+                trouble();
+            throw error;
+        }
+    };
+}
+/** `wait-for` with scope keys: the SDK's wait, under the CLI's documented exit codes. */
+async function cmdScopedWait(args, ctx, deps, filter) {
+    const cfg = requireConfig(ctx);
+    const timeout = flagInt(args, "timeout", 300);
+    if (timeout < 0)
+        throw new UsageError("--timeout must be zero or more seconds");
+    const after = startingCursor(args);
+    const fromCache = args.flags["from-cache"] === true;
+    if (!fromCache && flagString(args, "directory") !== undefined)
+        throw new UsageError("--directory names the local event cache; add --from-cache to read it");
+    const sdk = await (deps.loadSdk ?? loadEventsSdk)();
+    const { waitForEvents, waitForCachedEvents } = sdk;
+    if (!waitForEvents || !waitForCachedEvents)
+        throw new CliError("the installed SDK cannot wait on scope keys; upgrade the catalyst CLI", "sdk-upgrade-required");
+    const controller = new AbortController();
+    const abort = () => controller.abort(deps.signal?.reason);
+    if (deps.signal?.aborted)
+        abort();
+    else
+        deps.signal?.addEventListener("abort", abort, { once: true });
+    let interrupted = false;
+    let outage;
+    const removeInterrupt = (deps.onInterrupt ?? processInterrupts)(() => {
+        interrupted = true;
+        controller.abort(new Error("interrupted"));
+    });
+    try {
+        let result;
+        if (fromCache) {
+            result = await waitForCachedEvents({
+                tenantId: cfg.account,
+                directory: flagString(args, "directory") ?? sdk.defaultEventCacheDirectory(cfg.account),
+                filter,
+                after,
+                timeoutMs: timeout * 1_000,
+                signal: controller.signal,
+            });
+        }
+        else {
+            const auth = authStrategyFor(ctx, cfg);
+            if (auth.kind === "cookie")
+                throw new CliError("event waits require a token or OAuth session", "events-auth");
+            result = await waitForEvents({
+                baseUrl: normalizeBaseUrl(cfg.baseUrl),
+                auth,
+                tenantId: cfg.account,
+                filter,
+                after,
+                timeoutMs: timeout * 1_000,
+                signal: controller.signal,
+                fetch: outageFetch(ctx.fetch, controller.signal, (failures, sinceMs) => {
+                    if (outage)
+                        return;
+                    outage = { failures, sinceMs };
+                    controller.abort(new Error("cloud unreachable"));
+                }, () => ctx.now().getTime()),
+            });
+        }
+        const resume = (cursor) => (cursor === null || cursor === undefined ? "" : `; resume with --after ${cursor}`);
+        switch (result.outcome) {
+            case "matched":
+                for (const event of result.events)
+                    ctx.stdout(JSON.stringify(event));
+                return 0;
+            case "timeout":
+                ctx.stderr(`events: no matching event within ${timeout} s${resume(result.cursor)}`);
+                return 1;
+            case "aborted":
+                if (interrupted)
+                    return 130;
+                if (outage) {
+                    ctx.stderr(`events: the cloud event service was unreachable for ${outage.failures} attempts over ${Math.round((ctx.now().getTime() - outage.sinceMs) / 1_000)} s; this is an outage, not a timeout${resume(result.cursor)}`);
+                    return 4;
+                }
+                return 1;
+            case "refused":
+                throw new CliError(`events: ${result.source === "filter" ? "the filter was refused" : `the cloud refused the wait${result.status === null ? "" : ` (${result.status})`}`}${result.key ? ` on --${result.key}${result.value === null ? "" : ` ${result.value}`}` : ""}: ${result.reason}`, "events-refused");
+            default:
+                // The remaining outcome is "failed"; a default keeps every path ending in a return or throw.
+                if (result.code === "cache-missing" || result.code === "cache-writer-stopped")
+                    throw new CliError(`events: ${result.reason}. Start the local writer with: catalyst replica start --detach, or drop --from-cache to read from the cloud`, "events-absent", 3);
+                throw new CliError(`events: the wait failed (${result.code}): ${result.reason}${resume(result.resumeFrom ?? result.cursor)}`, "events-failed");
+        }
+    }
+    finally {
+        removeInterrupt();
+        deps.signal?.removeEventListener("abort", abort);
+    }
+}
 function eventFilter(args) {
     const type = flagString(args, "type");
     const ticket = flagString(args, "ticket")?.toUpperCase();

package/dist/messages.js

@@ -0,0 +1,47 @@
+import { flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { CliError, UsageError } from "./errors.js";
+import { bearerFor } from "./oauth.js";
+import { loadHttpSdk } from "./sdk.js";
+function failure(result) {
+    const reason = "reason" in result && typeof result.reason === "string" ? `: ${result.reason}` : "";
+    return `messages: ${result.outcome}${"status" in result && result.status ? ` (${result.status})` : ""}${reason}`;
+}
+export async function cmdMessages(args, ctx, deps = {}) {
+    const [action, ...extra] = positionals(args);
+    if (action !== "read" || extra.length)
+        throw new UsageError("messages takes: read --ticket CTC-N [--since SEQUENCE]");
+    const ticket = flagString(args, "ticket")?.trim().toUpperCase();
+    if (!ticket)
+        throw new UsageError("messages read needs --ticket CTC-N");
+    const rawSince = flagString(args, "since");
+    const since = rawSince === undefined ? undefined : Number(rawSince);
+    if (since !== undefined && (!Number.isSafeInteger(since) || since < 0))
+        throw new UsageError("--since must be a non-negative message sequence");
+    const cfg = requireConfig(ctx);
+    const createClient = deps.createClient ?? (async (options) => (await loadHttpSdk()).createTenantClient(options));
+    const client = await createClient({ key: await bearerFor(ctx, cfg), baseUrl: cfg.baseUrl, fetch: ctx.fetch });
+    if (!client.messages)
+        throw new CliError("the installed SDK cannot read messages; upgrade the catalyst CLI", "sdk-upgrade-required");
+    const result = await client.messages.read({ ticket, ...(since === undefined ? {} : { since }) });
+    if (result.outcome !== "ok") {
+        if (args.json)
+            ctx.stdout(JSON.stringify(result));
+        else
+            ctx.stderr(failure(result));
+        return 1;
+    }
+    if (args.json)
+        ctx.stdout(JSON.stringify({ ticket: result.ticket, messages: result.messages, next: result.next }));
+    else if (result.messages.length === 0)
+        ctx.stdout(`${result.ticket}: no messages${since === undefined ? "" : ` at or after ${since}`}`);
+    else
+        for (const message of result.messages) {
+            ctx.stdout(`#${message.seq} ${message.sentAt} ${message.from.label} (${message.kind})`);
+            for (const line of message.body.split("\n"))
+                ctx.stdout(`  ${line}`);
+        }
+    if (result.next !== null)
+        ctx.stderr(`more: re-run with --since ${result.next}`);
+    return 0;
+}

package/dist/onboard-next.js

@@ -3,6 +3,7 @@ import { GITHUB_CONFIRM_ACCESS } from "./onboard-github-copy.js";
 import { INSTALL_COMMAND, loadConfig, normalizeBaseUrl } from "./config.js";
 import { githubInstallationPage } from "./onboard-permissions.js";
 import { valuesFacts, valuesFix } from "./ready-copy.js";
+import { DEFAULT_HOST_FREE_FLOOR_GIB, isRunnerDiskUnmeasured, runnerDiskCopy } from "./onboard-runner-disk.js";
 /** What a person reads for a step that is not done. Each line ends in an action they can take. */
 const REASONS = {
     legacy_cleanup_failed: "An earlier Catalyst installation could not be removed. Run catalyst legacy --remove to see the exact item and its blocker, fix that blocker, then run catalyst setup again. Shared data folders are kept.",
@@ -158,6 +159,10 @@ const REASONS = {
     runner_compose_not_running: "The runner's supervisor is not running. Run docker compose -p catalyst-host logs supervisor to see why, then run catalyst onboard again.",
     runner_enrollment_unverified: "The runner started but has not enrolled yet. Run docker compose -p catalyst-host logs supervisor to see why, or run catalyst onboard again in a minute.",
     runner_needs_runner_flag: "This machine was set up to run Catalyst's work, but its runner is not running or not enrolled. To bring it up, run catalyst onboard --runner.",
+    runner_host_disk_sampler_python_missing: "Setup needs Python 3 to measure this Mac's disk for the runner. Install Apple's Command Line Tools with xcode-select --install, or python3 from Homebrew, then run catalyst setup --runner.",
+    runner_host_disk_location_unverified: "Setup could not tell which disk holds your Docker engine's virtual machine, so it cannot measure this Mac's free space for the runner. Set CATALYST_HOST_DISK_PATH to that folder (for a relocated Docker Desktop disk image, the folder chosen in Settings, Resources, Advanced), then run catalyst setup --runner.",
+    runner_host_disk_sampler_failed: "Setup could not start the dev.catalystcloud.host-disk LaunchAgent that measures this Mac's disk, so the runner will advertise zero free slots. Run launchctl print gui/$(id -u)/dev.catalystcloud.host-disk, or user/$(id -u)/dev.catalystcloud.host-disk when no one is logged in at the console, to see why, then run catalyst setup --runner.",
+    runner_host_disk_sampler_not_repeating: "Setup loaded the dev.catalystcloud.host-disk LaunchAgent, but launchd did not keep it measuring this Mac's disk: it published no new sample within 25 seconds, so the runner will advertise zero free slots. launchd can hold back an agent loaded from an SSH session. Log in to this Mac's desktop, at the console or over Screen Sharing, and run catalyst setup --runner in Terminal there. To see what launchd did, run launchctl print gui/$(id -u)/dev.catalystcloud.host-disk and read its runs and pended lines.",
     runner_capability_pending: "The runner enrolled but has not reported its capacity yet. Run catalyst onboard again in a minute.",
     runner_admission_unverified: "Setup could not read whether the team's pool admits runner hosts. Run catalyst onboard again to retry.",
     github_app_permissions_outdated: `The existing GitHub App installation needs updated permissions accepted. ${GITHUB_CONFIRM_ACCESS} An organization owner on GitHub opens the App's installation page, chooses Review permissions, then Accept new permissions. Run catalyst onboard afterward.`,
@@ -454,6 +459,26 @@ export function onboardReasonText(step, context = {}) {
             : "on the web app's Account API keys page";
         return `The runner is enrolled, but it takes no work without an organization key. A workspace owner or administrator runs catalyst onboard --runner on this machine; it mints the key and stores it for the runner. If their cloud cannot mint one yet, they create one with the mirror:read, mirror:write and mirror:feed scopes ${where}, save it in a file only they can read, and run catalyst onboard --runner with CATALYST_RUNNER_ORG_KEY_FILE set to that file.`;
     }
+    if (reason === "runner_host_disk_sampler_conflict") {
+        // Both settings are needed: a custom directory turns off setup's sampler, and the sample file
+        // name is then empty unless it is set too.
+        const safe = (value) => typeof value === "string" && /^\/[^\x00-\x1f'"]{0,500}$/.test(value) ? value : null;
+        const dir = safe(step.evidence?.sampleDir) ?? "<directory the other agent writes to>";
+        const file = safe(step.evidence?.sampleFile) ?? "/var/lib/catalyst/host-disk/<its file name>";
+        return `Another dev.catalystcloud.host-disk LaunchAgent on this Mac writes its disk sample somewhere else, so setup left it alone and the runner has no disk measurement. To use that agent's sample, set both CATALYST_HOST_DISK_SAMPLE_DIR=${dir} and CATALYST_HOST_DISK_SAMPLE_FILE=${file}, then run catalyst setup --runner; the directory alone leaves the runner without a sample file. Or remove the other agent: run launchctl bootout gui/$(id -u)/dev.catalystcloud.host-disk and launchctl bootout user/$(id -u)/dev.catalystcloud.host-disk (one of them reports it is not loaded), delete ~/Library/LaunchAgents/dev.catalystcloud.host-disk.plist, then run catalyst setup --runner.`;
+    }
+    if (reason === "runner_host_disk_below_floor" || reason === "runner_host_disk_unmeasured") {
+        const e = step.evidence ?? {};
+        const num = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+        const floorGiB = num(e.floorGiB) ?? DEFAULT_HOST_FREE_FLOOR_GIB, availableGiB = num(e.availableGiB);
+        if (reason === "runner_host_disk_below_floor" && availableGiB === null)
+            return `The runner advertises zero free slots: the disk it measures has less than ${floorGiB} GiB free. Free disk space, then run catalyst ready to see how much is free.`;
+        const detail = typeof e.diskDetail === "string" && isRunnerDiskUnmeasured(e.diskDetail) ? e.diskDetail : "physical_host_disk_sample_required";
+        const copy = runnerDiskCopy(reason === "runner_host_disk_below_floor" && availableGiB !== null
+            ? { state: "below_floor", availableGiB, floorGiB }
+            : { state: "unmeasured", detail, floorGiB }, e.vm === true);
+        return `${copy.line} ${copy.fix}`;
+    }
     if (reason === "runner_host_not_ready") {
         const failing = step.evidence?.failing;
         const checks = typeof failing === "string" && /^[a-z0-9.,_-]{1,500}$/.test(failing)