@catalyst-cloud/cli 0.15.6 → 0.16.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.16.1
+
+Setup lists your existing projects and lets you finish this computer without choosing a team again.
+
+- Keep your saved machine name when setup finds an existing installation, even if its settings file is missing.
+- Check readiness across projects that share a Linear team, with a clear next action when a check cannot finish.
+- Remove recognized older background jobs automatically. Preserve shared data and explain any cleanup that needs attention.
+- Recheck the existing installation before offering a replacement, and distinguish an ended enrollment from one that could not be verified.
+
+## 0.16.0
+
+The CLI, skills and plugin now share the 0.16 release line with the SDK and installer. The CLI installs the matching Node replica module for local cache commands. Update the CLI and update the Catalyst plugin through your agent's plugin manager.
+
 ## 0.15.6
 
 Setup checks current readiness and waits up to one minute while Catalyst reads repository settings.

package/README.md

@@ -85,7 +85,7 @@ catalyst ready
 
 `catalyst login` with no key opens a device-code login: it prints a short code and a URL, you approve it in your browser, and this machine is connected as you. On a machine with no browser (a remote box, a container) the code and URL still work — approve them from your phone. The short-lived session refreshes silently afterwards, so you log in about once a year. `npx -p @catalyst-cloud/cli catalyst login` works without the global install, and `bunx` works in place of `npx`. A non-default cloud is set with `CATALYST_CLOUD_BASE_URL` or `--base-url <url>`.
 
-Prefer a key? Pass one instead — mint a **personal key** at Settings → API keys in the Catalyst Cloud app (every member can; no admin needed). The environment form keeps it out of your shell history:
+For a script or an unattended machine, where nobody can approve a code, pass a **personal key** instead. Minting one is a browser step: Settings → API keys in the Catalyst Cloud app (every member can; no admin needed). The environment form keeps it out of your shell history:
 
 ```sh
 CATALYST_CLOUD_TOKEN=<your-personal-key> catalyst login
@@ -98,7 +98,8 @@ After a workspace owner connects your cloud account's Linear workspace, connect
 ```sh
 catalyst connections personal linear start
 catalyst connections personal linear status
-# First install the workspace's GitHub App and register its repository in Settings.
+# First install the workspace's GitHub App and register its repository:
+# catalyst onboard --team <KEY> --repo <owner/name>
 catalyst connections personal github start
 catalyst connections personal github status
 ```
@@ -121,7 +122,7 @@ A keyless session's access token is short-lived and rotates on its own: every re
 
 `login` does not install skills; the install command above did that. Re-running `login` after a key rotation, or to switch rails, rewrites the config. `catalyst status` prints which cloud account this machine is connected to and as whom, `catalyst ready` prints one READY or NOT READY verdict with the fix for each failure and who can apply it, and `catalyst --version` prints the package version and its pinned contract range.
 
-The setup skill Catalyst seeds into your repository ends by pointing at this same command. That served skill lives in the Catalyst Cloud application, not here; this is the only connect step a customer runs. Your cloud account's **account key** (Settings → Account keys, admin-minted) is a different credential — for a host or daemon that runs unattended — and is not what a person connects their own agent with: it would strip your name from everything your agent writes, and `login` says so if you use one.
+The setup skill Catalyst seeds into your repository ends by pointing at this same command. That served skill lives in the Catalyst Cloud application, not here; this is the only connect step a customer runs. Your cloud account's **account key** (minted by `catalyst onboard --runner`, run by an owner or admin) is a different credential — for a host or daemon that runs unattended — and is not what a person connects their own agent with: it would strip your name from everything your agent writes, and `login` says so if you use one.
 
 ## Run and resume setup
 
@@ -161,6 +162,8 @@ Before any network call, the run checks that every input is present. Each missin
 | The person's Linear | `linear_personal_grant_missing` | Settings → Connected accounts |
 | The person's GitHub | `github_personal_grant_missing` | Settings → Connected accounts |
 
+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 `--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.
@@ -183,7 +186,7 @@ Local sync is optional. Include it in the plan with `--local-sync` when you need
 ## Requirements
 
 - Node 22.15 or newer (Node 26 works), or bun 1.4 or newer. The bundle uses Node's built-in SQLite module (and, on bun, bun's own `node:sqlite`) for the optional local replica, so there is no native dependency to build; if `better-sqlite3` resolves on the machine it is used instead. `catalyst ready` names the exact reason when the runtime is too old, and `catalyst runtime install` installs a pinned Node under this CLI's own cache — without touching your machine's default Node — if you would rather not upgrade it.
-- Your personal key, minted by you at Settings → API keys. The key is the only account selector: you never type an account id. If your Linear identity is not matched yet, `login` says so; you match it yourself with `catalyst identity linear set` (an identity someone else already claims needs an admin at Settings → Members), and until then "what needs me" shows everyone's asks.
+- Your own login: a keyless `catalyst login`, or for an unattended machine a personal key you mint at Settings → API keys. The credential is the only account selector: you never type an account id. If your Linear identity is not matched yet, `login` says so; you match it yourself with `catalyst identity linear set` (an identity someone else already claims needs an admin at Settings → Members), and until then "what needs me" shows everyone's asks.
 - An agent that discovers skills. Claude Code loads the plugin; Codex, Cursor, OpenCode and the rest read the `skills/<name>/SKILL.md` files the `npx skills` installer writes.
 - Bun is optional, only if you prefer `bunx` over `npx` — bun 1.4 or newer, which is when `node:sqlite` arrives; older bun cannot run this CLI at all.
 
@@ -233,7 +236,7 @@ Some of these only read, and some write: a comment, a card move, an ask, a relea
 
 ## What a key cannot see yet
 
-Your personal key reads everything the skills need — tickets, pull requests, the eligibility explainer, the dispatch queue, fleet activity, per-ticket execution history (`catalyst explain --history <ticket>`: phase attempts, remediation rounds, park state) and coding-account status (`catalyst accounts`: provider, declared and observed state, usage limits, walls, quarantine — never a credential; enrolling or pausing one is `<your cloud>/settings/coding-accounts`). It also releases a parked or held ticket once its cause is fixed: `catalyst release <ticket> --because <what changed>` (the `unstick` skill runs it), recorded against your name and shown in the ticket's history. And it declares what your containers need: `catalyst environment` reads the account-wide declaration, `environment propose --file <path> --approve` proposes and approves it in one compare-and-set, and the values behind the names stay in the cloud — reading needs any active seat, proposing and approving need an admin or owner one. An admin or owner can put a repository's values in from the terminal. `catalyst secret import .env --repo owner/name` stores every name in the file and lists the declared names that still have no value. `catalyst secret set NAME --repo owner/name --command 'op read op://Vault/item/field'` runs the command on your machine and stores its output; with no `--command` it reads the value from stdin, or asks for it without echoing. No value is ever printed, and the cloud's audit records the command, not its output. That is the account's own declaration — a repository's own `.catalyst/catalyst.toml`, which `catalyst-onboard` already reports on, is a separate thing. `catalyst env inventory` lists the environment variable names a repository needs — never a value; `env check` checks the TOML syntax and environment variable table in `.catalyst/catalyst.toml` offline; `env migrate [catalyst.env.json]` prints a TOML environment table from a legacy declaration, with all names optional and values omitted. These commands need no login (the `what-this-repo-needs` skill walks through them). Two things it cannot do, and the skills say so by name rather than guess:
+Your personal key reads everything the skills need — tickets, pull requests, the eligibility explainer, the dispatch queue, fleet activity, per-ticket execution history (`catalyst explain --history <ticket>`: phase attempts, remediation rounds, park state) and coding-account status (`catalyst accounts`: provider, declared and observed state, usage limits, walls, quarantine — never a credential; enrolling or pausing one is `<your cloud>/settings/coding-accounts`, with no command yet). It also releases a parked or held ticket once its cause is fixed: `catalyst release <ticket> --because <what changed>` (the `unstick` skill runs it), recorded against your name and shown in the ticket's history. And it declares what your containers need: `catalyst environment` reads the account-wide declaration, `environment propose --file <path> --approve` proposes and approves it in one compare-and-set, and the values behind the names stay in the cloud — reading needs any active seat, proposing and approving need an admin or owner one. An admin or owner can put a repository's values in from the terminal. `catalyst secret import .env --repo owner/name` stores every name in the file and lists the declared names that still have no value. `catalyst secret set NAME --repo owner/name --command 'op read op://Vault/item/field'` runs the command on your machine and stores its output; with no `--command` it reads the value from stdin, or asks for it without echoing. No value is ever printed, and the cloud's audit records the command, not its output. That is the account's own declaration — a repository's own `.catalyst/catalyst.toml`, which `catalyst-onboard` already reports on, is a separate thing. `catalyst env inventory` lists the environment variable names a repository needs — never a value; `env check` checks the TOML syntax and environment variable table in `.catalyst/catalyst.toml` offline; `env migrate [catalyst.env.json]` prints a TOML environment table from a legacy declaration, with all names optional and values omitted. These commands need no login (the `what-this-repo-needs` skill walks through them). Two things it cannot do, and the skills say so by name rather than guess:
 
 - Read pull-request labels or the reviewer's reaction. The mirror does not carry them; GitHub's own page does.
 - Compute a flow number — cycle time, throughput, or how long pull requests have been open. Nothing serves those yet, so say they are not computed rather than counting something else and calling it that.
@@ -277,7 +280,7 @@ npm uninstall -g @catalyst-cloud/cli
 
 ## If login fails
 
-- `catalyst: GET /me failed (401): credential not accepted — mint a personal key at Settings → API keys and log in again` — the key is stale, mistyped or revoked. Mint a new one, then run `login` again.
+- `catalyst: GET /me failed (401): credential not accepted. Run catalyst login to sign in again; an unattended machine needs a new personal key from Settings → API keys` — the key is stale, mistyped or revoked. Run a keyless `catalyst login`, or on an unattended machine mint a new key, then run `login` again.
 - `catalyst: GET /me failed (403): account-not-operational` — your cloud account is suspended. This is a conversation with your account's admin, not a local fix.
 - `catalyst: could not reach <url>: <detail>` — the machine cannot reach the cloud. The URL is named in the message; check `CATALYST_CLOUD_BASE_URL` or `--base-url`.
 - A line naming two contract versions after `Connected to` — your account serves a contract outside this bundle's `1.x || 2.x` range. The config is written; update the bundle before using the other skills.

package/dist/args.js

@@ -20,6 +20,7 @@ const GLOBAL_FLAGS = {
 };
 /** Per-verb flag tables. A verb absent here accepts only the global flags. */
 export const FLAG_TABLES = {
+    hosts: { yes: { value: false, help: "confirm removal without a terminal" } },
     login: {
         "start-replica": {
             value: false,
@@ -41,6 +42,10 @@ export const FLAG_TABLES = {
     },
     install: {},
     onboard: {
+        "machine-name": {
+            value: true,
+            help: "name this self-hosted machine (default: its hostname)",
+        },
         verbose: { value: false, help: "show granted permissions for connected steps in interactive setup" },
         team: {
             value: true,
@@ -280,6 +285,25 @@ export const FLAG_TABLES = {
             value: false,
             help: "raise: declare that nothing is blocked",
         },
+        "gates-pr": {
+            value: true,
+            repeat: true,
+            help: "raise: a PR whose hold the answer releases (repeatable; needs --released-by)",
+        },
+        "gates-label": {
+            value: true,
+            repeat: true,
+            help: "raise: the hold label the answer removes: hold or hold:preview (repeatable; default hold)",
+        },
+        "released-by": {
+            value: true,
+            repeat: true,
+            help: "raise: an option letter whose answer releases the hold (repeatable)",
+        },
+        "gates-repo": {
+            value: true,
+            help: "raise: the --gates-pr repository as owner/name (default: the account's only repository)",
+        },
         anyone: {
             value: false,
             help: "list: every open ask in the tenant, not only the ones assigned to you",
@@ -461,6 +485,7 @@ 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]",
     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]",
@@ -479,7 +504,7 @@ export const VERB_USAGE = {
     queue: "queue [--team K] [--json]",
     watch: "watch [--team K] [--ticket T]... [--project P] [--exec CMD] [--cursor-file <path>] [--from cursor|head]",
     write: "write <comment <ticket> --body|--stdin [--parent] [--bookkeeping] [--as-user] | state <ticket> --slot|--state-id|--state-type | label <ticket> --add... --remove... | create --team --title [--description|--stdin] [--label] [--priority] | reaction <ticket>|--comment <id> --emoji <e> | attachment <ticket> --title --url | session <ticket> [--title] [--plan-file] [--activity]>",
-    ask: "ask <raise --team --title [--context] [--option]... [--default] --blocks <ticket>...|--nothing-to-block [--ask-key] | accept <askTicket> --answer <commentId> --role <role> | list [--anyone] [--json]>",
+    ask: "ask <raise --team --title [--context] [--option]... [--default] --blocks <ticket>...|--nothing-to-block [--ask-key] [--gates-pr <n>... --released-by <letter>... [--gates-label hold|hold:preview]... [--gates-repo <owner/name>]] | accept <askTicket> --answer <commentId> --role <role> | list [--anyone] [--json]>",
     ready: "ready [--onboarding] [--local-sync] [--json] [--offline]",
     accounts: "accounts [--json]",
     mcp: "mcp <add <name> --url URL <--auth none|--bearer SECRET_NAME|--header NAME=SECRET_NAME...>|list|remove <name>> [--json]",

package/dist/ask.js

@@ -39,6 +39,7 @@ async function raise(args, ctx, doc, api) {
     if (options.length > doc.askTemplate.maxLetteredOptions) {
         throw new UsageError(`ask raise takes at most ${doc.askTemplate.maxLetteredOptions} options`);
     }
+    const gates = askGates(args, options, doc);
     const blocks = [];
     for (const t of flagList(args, "blocks"))
         blocks.push((await resolveIssue(api, t)).id);
@@ -55,10 +56,65 @@ async function raise(args, ctx, doc, api) {
         body.nothingToBlock = true;
     if (flagString(args, "ask-key"))
         body.askKey = flagString(args, "ask-key");
+    if (gates)
+        body.gates = gates;
     const result = await postAgent(api, doc, "ask", body);
     ctx.stdout(args.json ? JSON.stringify(result) : `ask raised: ${String(result.identifier ?? result.id ?? "ok")}${blocks.length ? ` (blocks ${blocks.length})` : ""}`);
     return 0;
 }
+/** The hold labels an answered ask may lift; the cloud's ask route refuses any other with a 400. */
+const GATE_LABELS = ["hold", "hold:preview"];
+const OWNER_NAME = /^[^/\s]+\/[^/\s]+$/;
+/** CTC-5044 — the PR hold an answer releases. Absent unless --gates-pr is given, so an ask without it
+ *  posts exactly the body it always did. Everything the route would refuse (a label outside
+ *  {@link GATE_LABELS}, a letter that is not one of this ask's options) is refused here first, before
+ *  any ticket is resolved or anything is posted. Options are lettered A, B, C in the order given. */
+function askGates(args, options, doc) {
+    const prs = flagList(args, "gates-pr");
+    if (prs.length === 0) {
+        for (const f of ["released-by", "gates-label", "gates-repo"]) {
+            if (flagList(args, f).length || flagString(args, f))
+                throw new UsageError(`ask raise takes --${f} only with --gates-pr <n>`);
+        }
+        return undefined;
+    }
+    const pr = [...new Set(prs.map((n) => {
+            if (!/^[1-9]\d*$/.test(n))
+                throw new UsageError(`--gates-pr must be a PR number (got "${n}")`);
+            return Number(n);
+        }))];
+    const labels = [...new Set(flagList(args, "gates-label"))];
+    for (const l of labels) {
+        if (!GATE_LABELS.includes(l))
+            throw new UsageError(`--gates-label ${l} is not a hold an answer can release; use one of: ${GATE_LABELS.join(", ")}`);
+    }
+    const released = [...new Set(flagList(args, "released-by").map((l) => l.trim().toUpperCase()))];
+    if (released.length === 0)
+        throw new UsageError("--gates-pr needs --released-by <letter>: the option whose answer releases the hold");
+    const letters = options.map((_, i) => String.fromCharCode(65 + i));
+    for (const l of released) {
+        if (!letters.includes(l))
+            throw new UsageError(`--released-by ${l} is not one of this ask's options (${letters.length ? letters.join(", ") : "it has none; add --option"})`);
+    }
+    const registered = doc.merge.repositories.map((r) => `${r.owner}/${r.name}`);
+    const named = flagString(args, "gates-repo");
+    let repo;
+    if (named !== undefined) {
+        if (!OWNER_NAME.test(named))
+            throw new UsageError(`--gates-repo must be owner/name (got "${named}")`);
+        const match = registered.find((r) => r.toLowerCase() === named.toLowerCase());
+        if (registered.length && !match)
+            throw new UsageError(`--gates-repo ${named} is not a repository this account registers (${registered.join(", ")})`);
+        repo = match ?? named;
+    }
+    else if (registered.length === 1) {
+        repo = registered[0];
+    }
+    else {
+        throw new UsageError(`--gates-pr needs --gates-repo <owner/name>: this account registers ${registered.length ? registered.join(", ") : "no repository"}`);
+    }
+    return { repo, pr: pr.length === 1 ? pr[0] : pr, labels: labels.length ? labels : ["hold"], releasedBy: released };
+}
 async function accept(args, ctx, doc, api, rest) {
     const askTicket = rest[0];
     const answer = flagString(args, "answer");

package/dist/capabilities.js

@@ -5,9 +5,11 @@ const agent = (method, name) => ({ method, path: `/api/v1/agent/${name}` });
  *  the person, the workspace, the project, the repository, then work. A new verb is a new row here
  *  in the same change, or `catalyst capabilities` lies to every guide that reads it. */
 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" },
     // 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 },
+    { 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 },
     { verb: "onboard", does: "run and resume Catalyst setup with a saved step record", needs: "member", routes: [], since: "0.14.0", bootstrapHandoff: true, headless: true },
     { verb: "status", does: "say whether this machine is connected, as whom, and to which cloud", needs: "member", routes: [], since: "0.1.0" },
     { verb: "me", does: "read the person's seat, role and Linear identity", needs: "member", routes: [], since: "0.1.0" },

package/dist/cli.js

@@ -1,3 +1,4 @@
+import { cmdHosts } from "./hosts.js";
 // cli.ts — the `catalyst` dispatcher (npm: @catalyst-cloud/cli). Verbs live in
 // their own modules; this file keeps every export the 0.1 tests and the bin import.
 import { createSetupRenderer, setupBanner, } from "./setup-render.js";
@@ -79,6 +80,7 @@ export function usageText() {
         "  catalyst onboard [--resume-from <step>] [--only <step>] [--runner|--no-runner] [--yes] [--dry-run] [--json]",
         `  catalyst ${SETUP_USAGE}`,
         "  catalyst status | notice | me | ready | accounts",
+        "  catalyst hosts [list] | hosts remove <name-or-id> [--yes] | hosts rename <name-or-id> <new-name>",
         "  catalyst mcp add|list|remove (vault references only)",
         "  catalyst contract [--refresh] [--path <a.b.c>]",
         "  catalyst query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>>",
@@ -372,11 +374,11 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                             ...(deps.setupApproved
                                 ? { reviewedSetup: true, confirm: async () => true }
                                 : {}),
-                            beforeStep: async () => {
-                                if (args.flags["dry-run"] !== true)
-                                    await refreshSessionIfShort(ctx, ONBOARD_STEP_MIN_MS);
-                            },
                             ...createOnboardRuntime(args, ctx, {
+                                beforeStep: async () => {
+                                    if (args.flags["dry-run"] !== true)
+                                        await refreshSessionIfShort(ctx, ONBOARD_STEP_MIN_MS);
+                                },
                                 ui,
                                 signinTimeoutMs: deps.onboardSigninTimeoutMs,
                                 stageSignin: (signal) => {
@@ -511,6 +513,8 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdLegacy(args, ctx, deps.legacy ?? {});
             case "identity":
                 return await cmdIdentity(args, ctx, deps.identity ?? {});
+            case "hosts":
+                return await cmdHosts(args, ctx, deps.hosts);
             case "connections":
                 return await cmdConnections(args, ctx, deps.connections ?? {});
             default:
@@ -620,6 +624,7 @@ async function runSetup(argv, ctx, deps) {
                     ...(flags.json ? ["--json"] : []),
                     ...(flags.verbose ? ["--verbose"] : []),
                     ...(flags.localSync ? ["--local-sync"] : []),
+                    ...(flags.runner === undefined ? [] : [flags.runner ? "--runner" : "--no-runner"]),
                     ...(flags.yes || flags.json || !terminal ? ["--yes"] : []),
                 ];
                 let ui;
@@ -726,7 +731,7 @@ async function cmdLogin(args, ctx, deps, personalOnly = false) {
             : ' — your Linear identity is not matched yet, so "what needs me" will show everyone\'s asks until an admin matches it in Settings'}`);
     }
     else {
-        ctx.stderr(`[catalyst] this is your Catalyst workspace's shared key (a host credential), not your own. The skills work, but nothing your agent writes will carry your name, and "what needs me" cannot mean you. Make a personal key at Settings → API keys and sign in with that.`);
+        ctx.stderr(`[catalyst] this is your Catalyst workspace's shared key (a host credential), not your own. The skills work, but nothing your agent writes will carry your name, and "what needs me" cannot mean you. Run catalyst login to sign in as yourself; for an unattended machine, make a personal key at Settings → API keys and sign in with that.`);
     }
     ctx.stdout(`Config written to ${written.path} (mode ${formatMode(written.mode)}, holds your ${auth ? "login session" : "key"} and the CLI path)${written.mode === CONFIG_MODE
         ? ""

package/dist/environment.js

@@ -79,7 +79,7 @@ export function renderRead(r) {
     // never a refusal: the secret may be created next, and a repo may supply the name at checkout.
     const unresolved = r.unresolvedReferences ?? [];
     if (unresolved.length > 0) {
-        lines.push(`referenced but not set on this tenant yet: ${unresolved.join(", ")} — add them in the app, or a phase that needs one will fail on it`);
+        lines.push(`referenced but not set in this workspace yet: ${unresolved.join(", ")}. Set them with catalyst var set or catalyst secret set, or a phase that needs one will fail on it`);
     }
     return lines;
 }

package/dist/execution.js

@@ -51,7 +51,7 @@ export const EXCLUSION_REASONS = {
 export const UNKNOWN_REASONS = {
     ordering_never_published: "the dispatch order has never been published for this team — usually because the team has no saved stage mapping, which does not clear by itself",
     ordering_stale: "the dispatch order is stale",
-    workflow_mapping_unknown: "the team has no saved stage mapping for dispatch, pr, done and canceled (or a mapped stage was deleted); it does not clear by itself — a tenant owner or admin maps the team in Settings → Linear teams",
+    workflow_mapping_unknown: "the team has no saved stage mapping for dispatch, pr, done and canceled (or a mapped stage was deleted); it does not clear by itself; a workspace owner or admin runs catalyst team map <KEY>, or catalyst team adopt <KEY> to create Catalyst's stages",
     ticket_unknown: "the ticket is not in the mirror",
     dependency_snapshot_unknown: "the dependency snapshot has never completed",
     blocker_unknown: "a blocking relation could not be resolved",
@@ -373,7 +373,7 @@ export async function cmdAccounts(args, ctx) {
         return 0;
     }
     if (accounts.length === 0) {
-        ctx.stdout(`No coding accounts are enrolled on this tenant — enrol one at ${normalizeBaseUrl(cfg.baseUrl)}/settings/coding-accounts`);
+        ctx.stdout(`No coding accounts are enrolled in this workspace. A workspace owner or admin adds one at ${normalizeBaseUrl(cfg.baseUrl)}/settings/coding-accounts; there is no command for that yet.`);
         return 0;
     }
     for (const a of accounts)

package/dist/hosts.js

@@ -0,0 +1,89 @@
+import { createInterface } from "node:readline/promises";
+import { positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { CliError, UsageError } from "./errors.js";
+import { apiClient } from "./transport.js";
+import { isMachineInventory, isMachineMutation, } from "./machine-inventory.js";
+import { stdinIsTty } from "./prompt.js";
+async function confirmRemove(name) {
+    if (!stdinIsTty())
+        return false;
+    const prompt = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        return /^(y|yes)$/i.test((await prompt.question(`Remove ${name} from this account? It will stop receiving work. [y/N] `)).trim());
+    }
+    finally {
+        prompt.close();
+    }
+}
+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()}`);
+    if (lines.length === 0)
+        lines.push("No machines are enrolled for this account.");
+    const c = inventory.capacity;
+    lines.push(`Live capacity: ${c.slots} slots (${c.selfHostedSlots} self-hosted, ${c.catalystSlots} from Catalyst), ${c.inUse} in use, ${c.free} free. Stale machines are excluded.`);
+    return lines;
+}
+export async function cmdHosts(args, ctx, deps = {}) {
+    const parts = positionals(args);
+    const action = parts[0] ?? "list";
+    if (!((action === "list" && parts.length <= 1) ||
+        (action === "remove" && parts.length === 2) ||
+        (action === "rename" && parts.length === 3)))
+        throw new UsageError("hosts takes: [list] | remove <name-or-id> [--yes] | rename <name-or-id> <new-name>");
+    if (args.flags.yes === true && action !== "remove")
+        throw new UsageError("--yes is only valid with hosts remove");
+    if (action === "rename" &&
+        !/^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/.test(parts[2]))
+        throw new UsageError("Use 1 to 63 letters, digits, dots, underscores or hyphens, starting with a letter or digit.");
+    const cfg = requireConfig(ctx);
+    const client = apiClient(cfg, ctx);
+    const listed = await client.getJson("/api/v1/hosts/machines", {
+        query: { account: cfg.account },
+    });
+    if (!isMachineInventory(listed.body) || listed.body.account !== cfg.account)
+        throw new CliError("The cloud returned an unreadable machine list.", "shape");
+    if (action === "list") {
+        if (args.json)
+            ctx.stdout(JSON.stringify(listed.body));
+        else
+            for (const line of machineLines(listed.body))
+                ctx.stdout(line);
+        return 0;
+    }
+    const matches = listed.body.machines.filter((m) => m.id === parts[1] || m.name === parts[1]);
+    if (matches.length !== 1)
+        throw new CliError(matches.length === 0
+            ? "No machine matches that name or ID."
+            : "More than one machine has that name. Use its ID.", "machine_not_unique");
+    const machine = matches[0];
+    if (!(action === "remove" ? machine.removable : machine.renameable))
+        throw new CliError("Catalyst manages this cloud machine. Only self-hosted machines can be changed here.", "managed_machine");
+    if (action === "remove" &&
+        args.flags.yes !== true &&
+        !(await (deps.confirm ?? confirmRemove)(machine.name))) {
+        ctx.stdout(args.json
+            ? JSON.stringify({ removed: false, reason: "confirmation_required" })
+            : "Machine kept. Use --yes to confirm removal without a terminal.");
+        return 2;
+    }
+    const path = `/api/v1/hosts/${encodeURIComponent(machine.id)}${action === "rename" ? "/name" : ""}?account=${encodeURIComponent(cfg.account)}`;
+    const result = action === "remove"
+        ? await client.deleteJson(path, { accept: [403] })
+        : await client.postJson(path, { name: parts[2] }, { accept: [403] });
+    if (result.status === 403)
+        throw new CliError("Admin access is required to change machines in this account.", "admin_required", 2, 403);
+    if (!isMachineMutation(result.body) ||
+        result.body.hostId !== machine.id ||
+        (action === "rename" && result.body.name !== parts[2]))
+        throw new CliError("The cloud did not confirm the machine change.", "shape");
+    ctx.stdout(args.json
+        ? JSON.stringify(result.body)
+        : action === "remove"
+            ? `Removed ${machine.name}.`
+            : `Renamed ${machine.name} to ${result.body.name}.`);
+    return 0;
+}

package/dist/legacy.js

@@ -189,8 +189,18 @@ function remove(item, run, platform, uid) {
             const why = platform === "darwin"
                 ? tool("launchctl", ["bootout", `gui/${uid}/${item.name}`], "launchctl bootout")
                 : tool("systemctl", ["--user", "disable", "--now", item.name], "systemctl --user disable --now");
-            if (why !== null)
-                return why;
+            if (why !== null) {
+                if (platform !== "darwin")
+                    return why;
+                // A nonzero bootout may mean the exact owned service was already unloaded.
+                // Prove the scheduler domain works before interpreting its absence response.
+                const domain = run("launchctl", ["print", `gui/${uid}`]);
+                const service = run("launchctl", ["print", `gui/${uid}/${item.name}`]);
+                if (domain.status !== 0 ||
+                    service.status !== 113 ||
+                    !/could not find service|could not find specified service/i.test(service.stderr || service.stdout))
+                    return `${why}. Check launchctl print gui/${uid}/${item.name}, fix the reported scheduler error, then run catalyst legacy --remove.`;
+            }
             unlinkSync(item.path);
             return null;
         }

package/dist/machine-inventory.js

@@ -0,0 +1,37 @@
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const count = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+function machine(value) {
+    return (object(value) &&
+        typeof value.id === "string" &&
+        typeof value.name === "string" &&
+        (value.ownership === "self_hosted" || value.ownership === "catalyst") &&
+        Array.isArray(value.teams) &&
+        value.teams.every((team) => typeof team === "string") &&
+        count(value.slots) &&
+        count(value.inUse) &&
+        count(value.free) &&
+        (value.lastCheckInAtMs === null || count(value.lastCheckInAtMs)) &&
+        (value.status === "live" || value.status === "stale") &&
+        typeof value.removable === "boolean" &&
+        typeof value.renameable === "boolean");
+}
+export function isMachineInventory(value) {
+    if (!object(value) ||
+        typeof value.account !== "string" ||
+        !count(value.readAtMs) ||
+        !Array.isArray(value.machines) ||
+        !value.machines.every(machine) ||
+        !object(value.capacity))
+        return false;
+    return (count(value.capacity.slots) &&
+        count(value.capacity.inUse) &&
+        count(value.capacity.free) &&
+        count(value.capacity.selfHostedSlots) &&
+        count(value.capacity.catalystSlots));
+}
+export function isMachineMutation(value) {
+    return (object(value) &&
+        value.ok === true &&
+        typeof value.hostId === "string" &&
+        (value.name === undefined || typeof value.name === "string"));
+}

package/dist/onboard-capacity.js

@@ -163,7 +163,7 @@ export function onboardCapacityAdapter(input = {}) {
             const expected = binding(ctx, journal), selected = selection(journal), teamId = selectedOnboardTeam(journal), repos = selectedOnboardRepositories(journal);
             if (!expected)
                 return waiting("capacity_identity_unverified");
-            if (!teamId || repos.length !== 1 || repos[0].teamId !== teamId)
+            if (!teamId || repos.length === 0 || repos.some(r => r.teamId !== teamId))
                 return waiting("capacity_context_unverified");
             const controller = new AbortController(), signal = external
                 ? AbortSignal.any([external, controller.signal])
@@ -191,10 +191,9 @@ export function onboardCapacityAdapter(input = {}) {
                 const inventory = await readOnboardRepositoryInventory(ctx, journal, signal);
                 if ("reason" in inventory ||
                     !current() ||
-                    !inventory.repositories.some((r) => r.repoId === repos[0].repoId &&
-                        r.teamId === teamId &&
-                        r.owner.toLowerCase() === repos[0].owner.toLowerCase() &&
-                        r.name.toLowerCase() === repos[0].name.toLowerCase()))
+                    !repos.every(selectedRepo => inventory.repositories.some(r => r.repoId === selectedRepo.repoId && r.teamId === teamId &&
+                        r.owner.toLowerCase() === selectedRepo.owner.toLowerCase() &&
+                        r.name.toLowerCase() === selectedRepo.name.toLowerCase())))
                     return pause("capacity_context_unverified");
                 const read = await readExistingOnboardJson(ctx, route, signal);
                 if ("reason" in read || !current())
@@ -202,7 +201,7 @@ export function onboardCapacityAdapter(input = {}) {
                 if (!(await liveIdentity(ctx, journal, signal)) || !current())
                     return pause("capacity_identity_unverified");
                 const observed = snapshot(read.body, ctx.now().getTime());
-                const bucket = observed?.buckets.find((b) => b.repo === repos[0].repoId), mapped = bucket?.teams.find((t) => t.key === teamKey);
+                const bucket = observed?.buckets.find(b => b.teams.some(t => t.key === teamKey) && repos.some(r => r.repoId === b.repo)), mapped = bucket?.teams.find((t) => t.key === teamKey);
                 if (!observed || !bucket || !mapped)
                     return pause("capacity_context_unverified");
                 if (!mapped.admission || mapped.remaining === null)

package/dist/onboard-github-copy.js

@@ -0,0 +1,2 @@
+/** GitHub can require sudo confirmation before an install or permission change. */
+export const GITHUB_CONFIRM_ACCESS = "GitHub may show Confirm access. Use the two-factor code for the GitHub account you are signed in to.";

package/dist/onboard-github.js

@@ -1,4 +1,5 @@
 import { finishOnTheWeb } from "./consent-browser.js";
+import { GITHUB_CONFIRM_ACCESS } from "./onboard-github-copy.js";
 import { loadConfig, normalizeBaseUrl } from "./config.js";
 import { pollConsent } from "./onboard-consent.js";
 import { GITHUB_PERMISSION, githubInstallationPage, parsePermissions, } from "./onboard-permissions.js";
@@ -468,6 +469,7 @@ export function githubInstallationAdapter(options) {
                     reason: "github_installation_admin_required",
                 };
             // The signed URL is transient credential material: only the browser receives it.
+            ctx.stderr(GITHUB_CONFIRM_ACCESS);
             let browserUnavailable = false;
             try {
                 await options.openBrowser(url, signal);

package/dist/onboard-headless.js

@@ -29,8 +29,8 @@ const pages = (baseUrl) => {
         keys: `${web}/settings/api-keys`,
         connections: `${web}/a/account/connections`,
         personal: `${web}/settings/connected-accounts`,
-        teams: `${web}/settings/linear-teams`,
-        repos: `${web}/settings/repositories`,
+        teams: `${web}/settings/projects`,
+        repos: `${web}/settings/projects`,
         codingAccounts: `${web}/settings/coding-accounts`,
     };
 };