@catalyst-cloud/cli 0.16.27 → 0.16.28

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 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

@@ -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.js

@@ -47,6 +47,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 +94,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 +114,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.",
@@ -535,6 +538,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 +604,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.16.27",
+  "version": "0.16.28",
   "description": "Set up Catalyst Cloud, check your tickets and manage your account from the command line.",
   "license": "MIT",
   "type": "module",
@@ -53,16 +53,16 @@
     "prepublishOnly": "node scripts/release-train-check.mjs --publish cli"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "0.16.11",
+    "@catalyst-cloud/sdk": "0.16.19",
     "@clack/prompts": "1.8.1",
     "fast-string-width": "3.0.2",
     "fast-wrap-ansi": "0.2.2",
     "smol-toml": "^1.7.1",
     "yaml": "^2.9.0",
-    "@catalyst-cloud/sdk-replica-node": "0.16.11"
+    "@catalyst-cloud/sdk-replica-node": "0.16.19"
   },
   "devDependencies": {
-    "@catalyst-cloud/schema": "0.16.9",
+    "@catalyst-cloud/schema": "0.16.16",
     "@types/node": "^26.3.0",
     "@vitest/coverage-v8": "^4.1.11",
     "typescript": "^7.0.2",

package/skills/catalyst-github/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's GitHub: show a ticket's pull request with its checks, reviews and review threads, say whether it is mergeable under this repository's policy, and explain what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). Use when someone asks "show me the PR", "what are the checks saying", "why hasn't it merged", "what does the queue need", "what does that label mean", or wants the branch and merge conventions Catalyst follows.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.27 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.28 — written in this repository for customer accounts -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-linear/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's view of Linear on the customer's own cloud account. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the cloud API by default, with local replica reads available as an explicit opt-in, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the account's agent proxy as the app actor, with every route, stage id, label id and marker read from the account's contract. Knows what a ticket accumulates as Catalyst works it (phase-outcome comments, the document per phase, the agent session, the labels, the single blocks relation, the bookkeeping marker, the eyes acknowledgement). Use when a person says "show me the ticket", "what did Catalyst write on it", "comment on it", "move it", "label it" or "file a ticket". Not for raising a decision for a human (what-needs-me) and not for pull requests (catalyst-github).
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.27 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.28 — written in this repository for customer accounts -->
 
 # Catalyst Linear
 

package/skills/catalyst-linear/references/reading-from-the-cloud.md

@@ -14,6 +14,8 @@ Cloud reads are the default on every machine. They need no local writer and no l
 | Find a ticket by words | `node scripts/search.mjs <terms>` |
 | What happened to it, event by event? | `catalyst events query --ticket <KEY-123>` |
 | Wait until its phase finishes | `catalyst events wait-for --ticket <KEY-123> --type relay.phase.completed --after <head> --timeout 300` |
+| Wait until its branch or PR changes | `catalyst events wait-for --ref <owner/name:branch> --type pr.* --after <head> --timeout 14400` |
+| What messages were sent to it? | `catalyst messages read --ticket <KEY-123>` |
 
 ## Reading the answer
 
@@ -28,7 +30,9 @@ A smaller read is coming: the cloud will answer a ticket or its execution histor
 `catalyst events` reads the cloud by default and needs no local file.
 
 - `catalyst events query --ticket <KEY-123>` prints the ticket's events, newest first. Add `--type`, `--limit` (up to 200), `--order asc` and `--before` or `--after` to page. An empty page says which sequences the cloud has indexed, so "no match" is not "never happened".
-- To wait for something to happen, first run `catalyst events status --json` and keep its `head`. Then run `catalyst events wait-for --ticket <KEY-123> --type relay.phase.completed --after <head> --timeout 300`. Exit 0 prints the event, exit 1 is a timeout, and exit 4 means the cloud was unreachable.
+- To wait for something to happen, first run `catalyst events status --json` and keep its `head`. Then run `catalyst events wait-for --ticket <KEY-123> --type relay.phase.completed --after <head> --timeout 300`. Exit 0 prints the event, exit 1 is a timeout, exit 2 is a refusal with its reason, and exit 4 means the cloud was unreachable.
+- To wait on a branch, a pull request, a repository, a phase session or messages addressed to you, use `--ref <owner/name:branch>`, `--pr <owner/name#n>`, `--repo <owner/name>`, `--session <KEY-123/phase#n>` or `--to me`, with `--type pr.*` for a family of types. Such a wait prints nothing until a match, so `--timeout 14400` costs nothing while it waits. On a timeout, stderr names the `--after` to resume from.
+- `catalyst messages read --ticket <KEY-123> [--since <sequence>]` prints the messages sent to the ticket, with sender and time.
 - `catalyst events tail --ticket <KEY-123>` stays in the foreground and prints one JSON line per new event.
 
 The ticket filter reads the event's ticket entity, `payload.ticket`, and the lease that caused it. `--from-cache` reads this machine's local event cache instead. It exists only where local sync is on, and it pays off when several agents on one machine share it.

package/skills/catalyst-onboard/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Set up Catalyst Cloud and say whether setup is working. Walks a person from nothing to their first ticket running, one step at a time: the coding account, the project, the integrations and connected accounts, each repository's settings file, then one real ticket moving. Also logs this machine in, reads the readiness verdict with who can fix each failure, and checks the optional local replica. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", "log me in", "which account is this machine on", "am I set up", "what is missing", "why does nothing happen" or "is the replica running", when a login expired, or when a skill script exits 2 saying this machine is not connected. Does every step a key can do through the catalyst CLI, hands over the exact page for the steps only a browser can do, and never claims a step it did not watch succeed.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.27 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.28 — written in this repository for customer accounts -->
 
 # Onboard me
 

package/skills/run-this-project/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Own one Catalyst Cloud project end to end until it closes. Use when the person says "run this project for me", "own this until it ships", "keep this moving", or hands you a project id or a set of tickets to drive. Subscribes to the account's event stream for the scope through the catalyst CLI, reacts to each change in the same turn, makes tickets ready and moves them to dispatch, parks what should stop, chases stalls, escalates inward, and keeps one status summary current. Writes to Linear as the app actor; never polls.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.27 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.28 — written in this repository for customer accounts -->
 
 # Run this project
 

package/skills/unstick/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Get a stuck Catalyst Cloud ticket moving again. Use when the person asks "why is this parked and can you release it?", "unpark this", "get things flowing again", "the outage is over, retry what failed", or hands you a ticket that is not moving. Reads why nothing runs and what holds the ticket through the catalyst CLI, decides whether the recorded cause is fixed, previews the release, releases every governor holding the ticket the right way (or one failure class across a team), and raises an ask only for what a person has to do. Never releases a cause it cannot show changed without saying so.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.27 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.28 — written in this repository for customer accounts -->
 
 # Unstick
 

package/skills/what-needs-me/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   The human's decision inbox on Catalyst Cloud, and the one way an agent raises a decision on their behalf. Use when the person asks "what needs me?", "what am I blocking?", or when active work is gated on a choice only they can make. Lists open asks ranked by how much open work each one holds, files an ask through the cloud's ask route with the account's own template, and records the answer so the held work releases. Never answers as the human, never duplicates an open ask.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.27 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.28 — written in this repository for customer accounts -->
 
 # What needs me
 

package/skills/what-this-repo-needs/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   What environment variable names does this repository need, and where does each one come from? Scans the repository offline (no login, no network) and lists the names in three groups (build/test, deploy-only, bindings), each with where it was found, what uses it, and where a local value would come from. Never reads a value or prints one. Also checks the environment variable table in `.catalyst/catalyst.toml` offline. Use when someone asks "what does catalyst.env.json mean", "what env vars does this repo need", "why does the container need this", or before reviewing or writing the declaration.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.27 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.28 — written in this repository for customer accounts -->
 
 # What this repository needs
 

package/skills/whats-happening/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Use for "what's happening?", "what machines do we have?", "how much capacity do we have?", "where are we?", "why is that stuck?", "what closed?", "what's next?", "how does this work?", "why did it do that?", "how does it prioritise?" and "what does this setting do, where is it set?" in Catalyst Cloud, or asks for something to be done rather than known. Reads the contract via catalyst CLI. Read-only: route work/decisions, never answer as the human.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.27 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.28 — written in this repository for customer accounts -->
 
 # What's happening
 

package/skills/whats-happening/references/reading-from-the-cloud.md

@@ -13,9 +13,11 @@ Cloud reads are the default everywhere and need no local writer or database. Eac
 | what changed since a point | `catalyst query changes --since head` |
 | a ticket's events, newest first | `catalyst events query --ticket KEY-123` |
 | wait for a phase to finish | `catalyst events wait-for --ticket KEY-123 --type relay.phase.completed --after <head> --timeout 300` |
+| wait on a branch or PR | `catalyst events wait-for --ref owner/name:branch --type pr.* --after <head> --timeout 14400` |
+| read a ticket's messages | `catalyst messages read --ticket KEY-123` |
 
 A status-only read of a ticket and of its execution history is coming. No CLI flag selects it yet; read the full record.
 
-Events: `catalyst events` reads the cloud by default. `events status --json` gives the `head` to wait after. Exit 4 from `wait-for` is an outage, not a timeout. `--from-cache` reads the local event cache, which exists only where local sync is on.
+Events: `catalyst events` reads the cloud by default. `events status --json` gives the `head` to wait after. Exit 4 from `wait-for` is an outage, not a timeout; exit 2 is a refusal, with the reason. A wait on `--repo`, `--ref`, `--pr`, `--session` or `--to me` prints nothing until a match, so a long timeout costs nothing. `--from-cache` reads the local event cache, which exists only where local sync is on.
 
 Local SQL: `references/local-replica.md`, only when `configured: true`.