@catalyst-cloud/cli 0.16.0 → 0.16.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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.

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,
@@ -480,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]",

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-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`,
     };
 };

package/dist/onboard-next.js

@@ -5,6 +5,7 @@ import { githubInstallationPage } from "./onboard-permissions.js";
 import { valuesFacts, valuesFix } from "./ready-copy.js";
 /** What a person reads for a step that is not done. Each line ends in an action they can take. */
 const REASONS = {
+    legacy_cleanup_failed: "An earlier Catalyst installation could not be removed. Run catalyst legacy --remove to see the exact item and its blocker, fix that blocker, then run catalyst setup again. Shared data folders are kept.",
     account_identity_unverified: "Your login changed while AI accounts were checked. Run catalyst onboard again to verify your person and workspace.",
     account_inventory_unavailable: "AI accounts could not be read. Run catalyst onboard again to retry.",
     account_inventory_unverified: "The server did not return a fresh supported AI account list. Run catalyst onboard after the server update.",
@@ -53,6 +54,11 @@ const REASONS = {
     local_sync_not_selected: "Using cloud reads. Local sync was not selected.",
     local_sync_capability_unavailable: "Local sync was selected but could not be verified.",
     member_scope: "Your workspace administrator handles this step.",
+    returning_workspace_move_on: "Existing projects were left in place while this computer was set up. Run catalyst ready to review their checks, or catalyst setup --team <TEAM KEY> to repair one.",
+    returning_inventory_unverified: "Setup could not verify this workspace's existing projects. Run catalyst ready to check the workspace, then run catalyst setup again. Its projects have been kept in place.",
+    returning_project_cleanup_requested: "Review the selected project's archive preview before making any change.",
+    returning_project_cleanup_unverified: "Setup could not confirm this project's archive state. Run catalyst project list to inspect it, then run catalyst setup again to review any remaining changes. Do not repeat an archive based on this message alone.",
+    returning_project_cleanup_changed: "This project's repositories changed after the preview. Run catalyst setup again to review its current project list before archiving.",
     member_team_required: "Setup needs your Linear team to check what Catalyst can work on. Run catalyst setup again with --team <KEY>, using your team's key from Linear.",
     onboarding_checks_pending: "Some required checks are still unverified.",
     interrupted: "Setup paused. Run the same command to resume.",
@@ -73,7 +79,7 @@ const REASONS = {
     team_read_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
     team_create_unavailable: "The Linear team could not be created, and nothing was created. Run catalyst onboard to try again, or create the team in Linear and pick it.",
     team_create_unverified: "Setup could not confirm whether the Linear team was created. Check Linear for it before creating it again.",
-    team_create_grant_required: "Your own Linear connection is missing or has lapsed. Reconnect it in Settings → Connected accounts, then run catalyst onboard. Nothing was created.",
+    team_create_grant_required: "Your own Linear connection is missing or has lapsed. Reconnect it with catalyst connections personal linear start and approve the link it prints, then run catalyst onboard. Nothing was created.",
     team_create_identity_unverified: "Your login changed while setup was creating a team. Resume with the original workspace and person.",
     team_choice_required: "Choose an existing team with catalyst onboard --team <team ID or key>.",
     team_selection_unverified: "Your selected Linear team could not be verified. Run catalyst onboard --team <team ID or key> to choose again.",
@@ -101,13 +107,15 @@ const REASONS = {
     verification_pending: "Setup made the change but could not confirm it yet. Run catalyst onboard again to check.",
     automations_compatible: "Nothing to change.",
     workflow_unavailable: "Setup could not read the team's workflow. Run catalyst onboard again to retry.",
+    capacity_context_unverified: "Setup could not confirm this project's registered repositories and its default repository for capacity. Run catalyst ready to see the project checks, then run catalyst setup again. Starting a ticket checks its own repository's admission.",
+    capacity_identity_unverified: "Setup could not confirm your workspace and administrator role for the capacity check. Run catalyst login, then run catalyst setup again.",
     capacity_admission_unverified: "No runner is allowed to take work for this workspace yet. Enroll a self-hosted runner host, or ask Catalyst to enable cloud runners for it. Then run catalyst onboard.",
     capacity_currently_full: "Every runner slot for this repository is in use. Run catalyst onboard again after current work finishes.",
     capacity_unavailable: "Setup could not read runner capacity. Run catalyst onboard again to retry.",
     runner_not_selected: "This setup does not start a runner on this machine. To start one, run catalyst onboard --runner.",
     runner_docker_missing: "A runner needs Docker with Compose (Docker Desktop, OrbStack or Docker Engine), and setup could not reach it. Start Docker, or install it, then run catalyst onboard --runner.",
     runner_identity_unverified: "A workspace owner or administrator enrolls a runner. Sign in as one with catalyst login, then run catalyst onboard --runner.",
-    runner_context_unverified: "Setup could not confirm the selected Linear team. Run catalyst onboard again.",
+    runner_context_unverified: "Setup could not confirm a project for this machine. Keep its existing installation and credentials. Run catalyst setup --runner --team <TEAM KEY> for the project this machine should serve.",
     runner_directory_unavailable: "Setup could not prepare the runner folder in Catalyst's state directory. Check its permissions, then run catalyst onboard again.",
     runner_image_unpinned: "Each runner image must be pinned as name@sha256:<digest>, and Catalyst's runner image is not public yet. Ask Catalyst support to load it here and set CATALYST_RUNNER_IMAGE to the reference they give you. A CATALYST_SUPERVISOR_IMAGE or CATALYST_WATCHDOG_IMAGE override takes the same form. Then run catalyst onboard --runner.",
     runner_image_emulated: "A runner image here is built for another processor, and Catalyst does not run work under emulation. Ask Catalyst support for the image built for this processor, then run catalyst onboard again.",
@@ -115,9 +123,12 @@ const REASONS = {
     runner_session_network_failed: "Docker could not create the catalyst-session-v1 network. Check that Docker is running, then run catalyst onboard again.",
     runner_docker_socket_unreadable: "Setup could not read the group of the Docker socket at /var/run/docker.sock. Check that Docker is running, then run catalyst onboard again.",
     runner_engine_unsupported: "Runner setup needs local Docker Desktop or OrbStack on Mac, or native Linux Docker at /var/run/docker.sock. Select a supported local engine, then run catalyst onboard --runner.",
+    runner_installation_unverified: "Setup found a possible existing machine installation but could not verify its Compose files and identity. Keep its files and credentials. Run docker compose -p catalyst-host logs supervisor to check it, then run catalyst setup --runner again.",
     runner_enrollment_unavailable: "Setup could not read this workspace's runner hosts. Run catalyst onboard again to retry.",
     runner_enrolled_for_other_team: "This runner is enrolled for another Linear team. Keep using that team, or ask your administrator to revoke the old enrollment before setting up this machine for the selected team.",
-    runner_enrollment_stale: "This machine still holds the credential of a runner enrollment that was revoked. Stop the runner with docker compose -p catalyst-host down, remove the credential with docker volume rm catalyst-host_host-credential (this also removes the organization key), then run catalyst onboard --runner.",
+    runner_enrollment_revoked: "Catalyst confirms that this machine's saved enrollment was revoked. Keep its credential and organization key. Ask your workspace administrator to review the enrollment before replacing it, then run catalyst setup --runner.",
+    runner_credential_unverified: "Setup could not read this machine's saved enrollment. Keep its credential and organization key. Run docker compose -p catalyst-host logs supervisor to check the error, then run catalyst setup --runner.",
+    runner_enrollment_stale: "Setup could not match this machine's saved enrollment with Catalyst. Keep its credential and organization key, then run catalyst setup --runner to check again.",
     runner_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard.",
     runner_join_token_unavailable: "Catalyst did not issue a join token for this machine. Run catalyst onboard again to retry.",
     runner_session_network_unavailable: "Docker could not inspect the runner session network. Check engine access and run the same setup command again. Setup has not created a replacement network.",
@@ -337,13 +348,10 @@ export function onboardReasonText(step, context = {}) {
     // A member is told which admin action is left and where an admin takes it.
     if (reason === "member_scope") {
         const key = onboardTeamKey(context.journal);
+        if (step.id === "linear.adopt")
+            return `Only a Catalyst owner or admin can set up the team's Catalyst workflow. Ask one to run catalyst team adopt ${key ?? "<TEAM KEY>"}.`;
         const adminOnly = {
             "linear.workspace": ["connect Linear", "/settings/connections", " and connect it there"],
-            "linear.adopt": [
-                "set up the team's Catalyst workflow",
-                key ? `/settings/linear-teams/${encodeURIComponent(key)}/adopt` : "/settings/linear-teams",
-                "",
-            ],
         };
         const admin = adminOnly[step.id];
         if (admin) {
@@ -374,7 +382,7 @@ export function onboardReasonText(step, context = {}) {
         const where = context.baseUrl
             ? `at ${normalizeBaseUrl(context.baseUrl)}/settings/coding-accounts`
             : "in the web app on the Settings → AI accounts page";
-        return `No AI account in this workspace can take work yet. A workspace owner or administrator checks them ${where}: one may need its key replaced, or may have reached its usage limit. Then run catalyst onboard.`;
+        return `No AI account in this workspace can take work yet. Run catalyst accounts to see which one needs work. A workspace owner or administrator fixes it ${where}, since no command does that yet: one may need its key replaced, or may have reached its usage limit. Then run catalyst onboard.`;
     }
     if (reason === "account_enrollment_required") {
         const where = context.baseUrl
@@ -425,7 +433,7 @@ export function onboardReasonText(step, context = {}) {
         const where = context.baseUrl
             ? `at ${normalizeBaseUrl(context.baseUrl)}/settings/account-keys`
             : "on the web app's Account API keys page";
-        return `The runner is enrolled, but it takes no work without an organization key. A workspace owner or administrator creates one with the mirror:read, mirror:write and mirror:feed scopes ${where} and saves it in a file only they can read. Then run catalyst onboard --runner with CATALYST_RUNNER_ORG_KEY_FILE set to that file.`;
+        return `The runner is enrolled, but it takes no work without an organization key. A workspace owner or administrator runs catalyst onboard --runner on this machine; it mints the key and stores it for the runner. If their cloud cannot mint one yet, they create one with the mirror:read, mirror:write and mirror:feed scopes ${where}, save it in a file only they can read, and run catalyst onboard --runner with CATALYST_RUNNER_ORG_KEY_FILE set to that file.`;
     }
     if (reason === "runner_host_not_ready") {
         const failing = step.evidence?.failing;

package/dist/onboard-project-cleanup.js

@@ -0,0 +1,100 @@
+import { loadConfig, normalizeBaseUrl } from "./config.js";
+import { readExistingOnboardJson } from "./onboard-existing.js";
+import { readReturningProjects } from "./onboard-returning.js";
+const waiting = (reason) => ({ state: "waiting", reason });
+const signature = (project) => JSON.stringify([...(project.repositories ?? [])].sort((a, b) => a.id.localeCompare(b.id)));
+/** Archiving uses the existing reversible project action. Only the explicitly reviewed scope
+ * is changed, after fresh inventory and identity checks. A failed write is never assumed absent. */
+export async function archiveReturningProject(project, ctx, journal, confirm, signal) {
+    const cfg = loadConfig(ctx.home);
+    const sameIdentity = () => {
+        const now = loadConfig(ctx.home);
+        return cfg?.user && now?.user && cfg.account === journal.account &&
+            cfg.user.id === journal.membershipId && now.account === cfg.account &&
+            now.user.id === cfg.user.id && ["owner", "admin"].includes(now.user.role) &&
+            normalizeBaseUrl(now.baseUrl) === journal.baseUrl && normalizeBaseUrl(cfg.baseUrl) === journal.baseUrl;
+    };
+    if (!sameIdentity() || !confirm)
+        return waiting("returning_project_cleanup_unverified");
+    const fresh = await readReturningProjects(ctx, journal, signal);
+    const selected = "projects" in fresh ? fresh.projects.find(p => p.id === project.id) : undefined;
+    if (!selected?.repositories?.length || selected.repositories.length > 64 || !sameIdentity())
+        return waiting("returning_project_cleanup_unverified");
+    const linked = async () => {
+        const names = new Set();
+        const boundedRead = signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000);
+        for (const row of selected.repositories) {
+            const read = await readExistingOnboardJson(ctx, `/api/v1/me/projects/${encodeURIComponent(row.id)}/repositories`, boundedRead);
+            if ("reason" in read || !read.body || typeof read.body !== "object")
+                return null;
+            const body = read.body;
+            if (!body.project || typeof body.project !== "object" ||
+                !("id" in body.project) || body.project.id !== row.id ||
+                !("teamId" in body.project) || body.project.teamId !== selected.id ||
+                !Array.isArray(body.repositories) || !body.repositories.length || body.repositories.length > 10_000)
+                return null;
+            const returnedNames = new Set();
+            for (const repository of body.repositories) {
+                if (!repository || typeof repository !== "object" || !("fullName" in repository) ||
+                    typeof repository.fullName !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}\/[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/.test(repository.fullName))
+                    return null;
+                names.add(repository.fullName);
+                returnedNames.add(repository.fullName);
+            }
+            if (!returnedNames.has(row.name))
+                return null;
+        }
+        return [...names].sort();
+    };
+    const linkedNames = await linked();
+    if (!linkedNames || !sameIdentity())
+        return waiting("returning_project_cleanup_unverified");
+    const lines = [
+        `Archive ${selected.name} (${selected.key}) in Catalyst.`,
+        ...linkedNames.map(name => `Repository affected: ${name}.`),
+        "Archiving removes this project’s repository registrations. Mirroring may stop where no other registration keeps a repository active.",
+        "The project and its repository links are kept so it can be reactivated. Linear tickets and GitHub repositories are kept.",
+        "New work may be held when these repositories are no longer registered for this project.",
+    ];
+    if (!(await confirm(selected, lines)))
+        return { state: "done", reason: "returning_project_cleanup_declined" };
+    if (signal?.aborted || !sameIdentity())
+        return waiting("returning_project_cleanup_unverified");
+    const rechecked = await readReturningProjects(ctx, journal, signal);
+    const current = "projects" in rechecked ? rechecked.projects.find(p => p.id === selected.id) : undefined;
+    if (!current || signature(current) !== signature(selected) || !sameIdentity())
+        return waiting("returning_project_cleanup_changed");
+    const recheckedLinks = await linked();
+    if (!recheckedLinks || JSON.stringify(recheckedLinks) !== JSON.stringify(linkedNames) || !sameIdentity())
+        return waiting("returning_project_cleanup_changed");
+    const bearer = cfg?.key || (cfg?.auth && Date.parse(cfg.auth.expiresAt) - ctx.now().getTime() > 30_000
+        ? cfg.auth.accessToken : undefined);
+    if (!bearer)
+        return waiting("returning_project_cleanup_unverified");
+    const bounded = signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000);
+    for (const row of selected.repositories) {
+        if (bounded.aborted || !sameIdentity())
+            return waiting("returning_project_cleanup_unverified");
+        try {
+            const response = await ctx.fetch(`${journal.baseUrl}/api/v1/me/repositories/${encodeURIComponent(row.id)}/archive`, {
+                method: "POST", redirect: "error", signal: bounded,
+                headers: { authorization: `Bearer ${bearer}`, accept: "application/json", "content-type": "application/json" },
+                body: "{}",
+            });
+            if (response.status !== 200)
+                return waiting("returning_project_cleanup_unverified");
+            const body = await response.json();
+            const returned = body && typeof body === "object" && "repository" in body ? body.repository : null;
+            if (!returned || typeof returned !== "object" || !("id" in returned) || returned.id !== row.id ||
+                !("linearTeamId" in returned) || returned.linearTeamId !== selected.id ||
+                !("status" in returned) || returned.status !== "archived")
+                return waiting("returning_project_cleanup_unverified");
+            journal.changes.push({ kind: "project-archive", label: `Archived ${selected.name}: ${row.name}`,
+                undo: "Reactivate the project from its Catalyst project page." });
+        }
+        catch {
+            return waiting("returning_project_cleanup_unverified");
+        }
+    }
+    return { state: "done" };
+}