@catalyst-cloud/cli 0.16.25 → 0.16.28

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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).
+
+## 0.16.26
+
+Not published. Its changes ship in 0.16.27.
+
 ## 0.16.25
 
 A self-hosted machine that runs several teams' work from one `compose.json` can now take each approved release by itself. Run `catalyst runner update --fleet --dir <the folder that holds compose.json>`, by hand or on a schedule. It switches only the supervisor to the approved images and leaves work that is already running alone. If the machine's teams are not ready again within four minutes, it puts the previous images back. `--check` shows what would change without changing anything.

package/README.md

@@ -166,6 +166,19 @@ With a person at the terminal, `catalyst onboard` starts each of these approvals
 
 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.
 
+### Stopping or removing this machine's runner
+
+Run these on the machine itself:
+
+| command | what it does |
+| -- | -- |
+| `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`. |
+
+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.
+
 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.
 
 | Exit | Meaning |
@@ -201,6 +214,24 @@ Open a new session and ask about your own cloud account. The skills read the con
 
 `catalyst team list` inventories visible teams without running readiness checks. `team check ENG` prints readiness for one team; `team check --all` runs checks for every team. `team map ENG`, `team adopt ENG`, and `team migrate ENG` print a plan and exit 3 before changing configuration; review the plan and rerun the chosen command with `--yes --plan-hash <hash>` from that preview. `team adopt ENG --undo` previews the exact previously created stages, and `team migrate ENG --retire` requires its own confirmation after the ticket move. `team checklist ENG` prints the same manual setup lines as the browser. These commands use the member's own login; an admin or owner seat is required for setup, and Adopt and Migrate also need that member's personal Linear connection.
 
+## Repository status and pauses
+
+Use your existing login to list the repositories visible to you, their status and attached projects:
+
+```sh
+catalyst repo status
+catalyst repo status --json
+catalyst repo pause acme/app --reason "flaky deploy"
+catalyst repo resume acme/app --reason "deploy fixed"
+catalyst repo resume acme/app
+```
+
+Any workspace member can read status. Pausing or resuming requires a workspace owner or admin. Pause requires a reason; resume accepts an optional reason. A supplied reason must contain 1 to 500 characters after trimming. These commands work outside a local checkout.
+
+Paused rows show who paused the repository (their email, or the key or operator that paused it), when and why, when those details are available. An empty list means no repositories are visible to your login. After a write, the command reads and prints the repository's current state. If that read fails, it reports that the write succeeded and status could not be read; check `catalyst repo status` before repeating a write.
+
+`--json` preserves the list response for status and prints the refreshed repository row for a write. An older cloud reports that repository status is not served yet and needs a newer cloud. Agents can use `catalyst capabilities --json` to check route availability against the cached cloud contract.
+
 ## What has to be running
 
 Nothing, by default. After `login`, every read, write, ask and explanation goes to the cloud's origin-fresh API with the config file and the cached contract on disk. Two optional processes exist for people who want them:
@@ -215,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.
 
@@ -270,6 +316,8 @@ A `customer.json` written by an older bundle is still read unchanged; it gains t
 
 ## Uninstalling
 
+If this machine runs Catalyst's work, run `catalyst runner uninstall` first (see "Stopping or removing this machine's runner").
+
 Remove the skills the way you installed them: `/plugin uninstall catalyst@catalyst-cloud` in Claude Code, or delete the skill directories (`catalyst-github`, `catalyst-linear`, `catalyst-onboard`, `run-this-project`, `unstick`, `what-needs-me`, `what-this-repo-needs`, `whats-happening`) from wherever `npx skills add` wrote them. Skills an earlier release shipped (`catalyst-setup`, `connect-me`, `how-catalyst-works`) go the same way; the CLI removes its own stamped copies of them when it installs or refreshes skills. Then remove what the CLI wrote:
 
 ```sh

package/dist/args.js

@@ -26,6 +26,8 @@ export const FLAG_TABLES = {
         auto: { value: false, help: "one-line output for the scheduled run" },
         dir: { value: true, help: "the runner directory (default: the one setup created)" },
         fleet: { value: false, help: "update a multi-team supervisor fleet's compose.json in --dir" },
+        yes: { value: false, help: "uninstall: confirm without a terminal" },
+        "delete-checkouts": { value: false, help: "uninstall: also delete the repository and thoughts checkouts" },
     },
     login: {
         "start-replica": {
@@ -66,6 +68,10 @@ export const FLAG_TABLES = {
             value: false,
             help: "include the optional local sync setup in this plan",
         },
+        "remove-local-data": {
+            value: false,
+            help: "with local sync off, stop existing local writers and delete the listed replica and event-cache files; keep login, contract and settings",
+        },
         runner: {
             value: false,
             optionalValue: true,
@@ -152,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)",
@@ -472,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: {
@@ -486,7 +501,7 @@ export const FLAG_TABLES = {
         },
         data: {
             value: false,
-            help: "historical flag; shared data folders are always kept",
+            help: "include the listed replica DB, sidecars and local event cache; shared data folders, login, contract and settings are kept",
         },
         yes: {
             value: false,
@@ -494,6 +509,7 @@ export const FLAG_TABLES = {
         },
     },
     repo: {
+        reason: { value: true, help: "pause: required; resume: optional; 1 to 500 characters after trimming (owner or admin)" },
         write: {
             value: false,
             help: "agents-block: write or update the block in AGENTS.md (working tree only)",
@@ -545,10 +561,10 @@ export const FLAG_TABLES = {
 };
 export const VERB_USAGE = {
     hosts: "hosts [list] | hosts remove <name-or-id> [--yes] | hosts rename <name-or-id> <new-name> [--json]",
-    runner: "runner update [--check] [--dir <runner directory>] [--fleet] | runner auto-update [status|on|off]",
+    runner: "runner [status] | runner stop | runner start | runner uninstall [--yes] [--delete-checkouts] | runner update [--check] [--dir <runner directory>] [--fleet] | runner auto-update [status|on|off] [--json]",
     setup: "setup [onboard options]   (sets up Catalyst step by step; same as catalyst onboard) | setup --engine <file> --engine-sha256 <hex> [-- <install options>]   (run by install.sh; install.sh --help lists the options)",
     login: "login [--base-url <url>] [--start-replica]   (keyless; or --key <personal-key> / CATALYST_CLOUD_TOKEN)",
-    onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--coding-account <slot>] [--resume-from <step>] [--only <step>] [--local-sync] [--runner|--no-runner] [--no-color] [--yes] [--dry-run] [--json] | onboard --headless [--key-file <path>] [--team ...] [--repo ...]... [--coding-account ...] [--runner yes|no] [--json]",
+    onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--coding-account <slot>] [--resume-from <step>] [--only <step>] [--local-sync] [--remove-local-data] [--runner|--no-runner] [--no-color] [--yes] [--dry-run] [--json] | onboard --headless [--key-file <path>] [--team ...] [--repo ...]... [--coding-account ...] [--runner yes|no] [--remove-local-data] [--json]",
     install: "install [--skills-dir <dir>] [--force]",
     status: "status",
     notice: "notice",
@@ -557,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]",
@@ -575,9 +591,10 @@ 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 <agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]> [--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)",
     legacy: "legacy [--remove [--data] [--yes]] [--json]",
     connections: "connections personal <linear|github> <start|status> [--wait <seconds>] [--json]",
     release: "release <ticket> --because <what changed> [--retry-unchanged] [--dry-run] [--json] | release --class <failure-class> --team <K> --because <what changed> [--retry-unchanged] [--dry-run] [--limit N] [--json]",

package/dist/capabilities.js

@@ -8,6 +8,8 @@ export const CAPABILITIES = [
     { verb: "hosts", does: "list this account's machines, current use and live capacity", needs: "member", routes: [], since: "0.16.0" },
     { verb: "hosts remove|rename", does: "remove or rename a self-hosted machine in this account", needs: "admin", routes: [], since: "0.16.0" },
     { verb: "runner update|auto-update", does: "move this machine's self-hosted runner to the release Catalyst approved, and check for one every 15 minutes", needs: "member", routes: [], since: "0.16.16" },
+    { verb: "runner status|stop|start", does: "stop this machine's self-hosted runner taking work, or start it again with the same registration", needs: "member", routes: [], since: "0.16.27" },
+    { verb: "runner uninstall", does: "remove this machine's self-hosted runner and revoke its registration and runner key", needs: "admin", routes: [], since: "0.16.27" },
     // CTC-4680: plain `catalyst setup` runs the onboard flow, so install.sh may hand off to it. install.sh
     // reads this flag rather than `setup --help`, which already exits 0 on 0.15.x.
     { verb: "setup", does: "set up Catalyst step by step, or show install.sh's plan, progress and sign-in in this terminal", needs: "member", routes: [], since: "0.15.0", engineProtocol: 1, bootstrapHandoff: true, bootstrapHandoffVersion: 2 },
@@ -28,6 +30,8 @@ export const CAPABILITIES = [
     { verb: "team checklist", does: "print what adopting the workflow would do to a team", needs: "admin", routes: [agent("GET", "team-workflow")], since: "0.9.5" },
     { verb: "project wip-limit get", does: "read a project's new-start WIP limit, where it comes from, and its work in progress now", needs: "member", routes: [agent("GET", "team-wip-limit")], since: "0.13.1" },
     { verb: "project wip-limit set", does: "set a project's new-start WIP limit (0 to 9999, or back to the workspace default)", needs: "admin", routes: [agent("POST", "team-wip-limit")], since: "0.13.1" },
+    { verb: "repo status", does: "list visible repositories with their state, pause details and projects", needs: "member", routes: [agent("GET", "repos")], since: "0.16.27" },
+    { verb: "repo pause|resume", does: "pause or resume a repository as a workspace owner or admin", needs: "admin", routes: [agent("GET", "repos"), agent("POST", "repos/pause"), agent("POST", "repos/resume")], since: "0.16.27" },
     { verb: "repo agents-block", does: "add or refresh the one Catalyst block in a checkout's AGENTS.md, in the working tree, for the person to commit and open as a pull request", needs: "member", routes: [], since: "0.13.1" },
     { verb: "repo agent-setup", does: "read a checkout's agent setup (AGENTS.md, CLAUDE.md, .agents and .claude skills and rules) and, on request, make it portable in the working tree", needs: "member", routes: [], since: "0.13.1" },
     { verb: "env shell", does: "open this repository's environment on this computer: Catalyst's image, the declared toolchain and variables (needs Docker; no login for Catalyst's image)", needs: "member", routes: [], since: "0.16.20" },

package/dist/cli.js

@@ -47,8 +47,9 @@ 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, } from "./onboard.js";
+import { cmdOnboard, onboardErrorJournal, onboardStatePath, readOnboardJournal, } from "./onboard.js";
 import { createClackOnboardUi, shouldUseOnboardUi, } from "./onboard-ui.js";
 import { createOnboardRuntime } from "./onboard-runtime.js";
 import { argvRequestsHeadless, headlessOnboardDeps, headlessUsageRefusal, onboardHeadlessRequested, runOnboardHeadless, } from "./onboard-headless.js";
@@ -85,6 +86,7 @@ export function usageText() {
         "  catalyst status | notice | me | ready | accounts",
         "  catalyst seat checkout --size big|med --harness claude,codex,opencode [--session-id ID] [--stage STAGE]",
         "  catalyst hosts [list] | hosts remove <name-or-id> [--yes] | hosts rename <name-or-id> <new-name>",
+        "  catalyst runner [status] | runner stop | runner start | runner uninstall [--yes] [--delete-checkouts]   (this machine's self-hosted runner)",
         "  catalyst runner update [--check] | runner auto-update [status|on|off]   (move this machine's runner to the approved release)",
         "  catalyst mcp add|list|remove (vault references only) | mcp status <name>   (a server's state, grants and last 50 tool calls)",
         "  catalyst contract [--refresh] [--path <a.b.c>]",
@@ -92,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> ...",
@@ -106,9 +109,12 @@ export function usageText() {
         "  catalyst project list [--json]   (all workspace projects, including those with no stage mapping)",
         "  catalyst stage <start|renew|done|fail> <ticket> <phase>   (a cloud-claimed local phase)",
         "  catalyst project wip-limit <get|set <n>|set default> [--team K]   (a project's new-start WIP limit; members read, owners and admins set)",
+        "  catalyst repo pause <owner/name> --reason <text> | repo resume <owner/name> [--reason <text>]   (owner or admin; reason: 1 to 500 trimmed characters)",
+        "  catalyst repo status [--json]   (visible workspace repositories and their paused state; needs login)",
         "  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.",
@@ -131,6 +137,15 @@ export function usageText() {
  * the `catalyst` launcher beside it, once, on the next run of either name. Read and write back to
  * back, so the window for racing a concurrent OAuth refresh is as small as the update notice's.
  */
+/** Setup's saved local sync choice; an unreadable record reads as off, which only adds a hint. */
+function savedLocalSync(ctx) {
+    try {
+        return readOnboardJournal(onboardStatePath(ctx.home, ctx.env))?.localSync === true;
+    }
+    catch {
+        return false;
+    }
+}
 function migrateLegacyCliPath(ctx) {
     let cfg;
     try {
@@ -520,9 +535,11 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
             case "repo":
                 return await cmdRepo(args, ctx);
             case "legacy":
-                return await cmdLegacy(args, ctx, deps.legacy ?? {});
+                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":
@@ -587,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/hosts.js

@@ -8,7 +8,7 @@ async function confirmRemove(name) {
     return confirmYesNo(`Remove ${name} from this account? It will stop receiving work. [y/N] `);
 }
 export function machineLines(inventory) {
-    const lines = inventory.machines.map((m) => `${m.name} | ${m.ownership === "self_hosted" ? "Self-hosted" : "Catalyst's"} | ${m.teams.join(", ")} | ${m.slots} slots, ${m.inUse} in use, ${m.free} free | ${m.status} | last check-in ${m.lastCheckInAtMs === null ? "never" : new Date(m.lastCheckInAtMs).toISOString()}`);
+    const lines = inventory.machines.map((m) => `${m.name} | ${m.ownership === "self_hosted" ? "Self-hosted" : "Catalyst's"} | ${m.teams.join(", ")} | ${m.slots} slots, ${m.inUse} in use, ${m.free} free | ${m.stopped === true ? "stopped" : m.status} | last check-in ${m.lastCheckInAtMs === null ? "never" : new Date(m.lastCheckInAtMs).toISOString()}`);
     if (lines.length === 0)
         lines.push("No machines are enrolled for this account.");
     const c = inventory.capacity;