@catalyst-cloud/cli 0.16.29 → 0.16.31

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.16.31
+
+New: `catalyst update` is one release check for everything Catalyst installed on this machine. `catalyst update --check` lists each component (the runner images, the CLI, the Cloud and Dev skills, the Claude plugin form of the Cloud skills, the local replica and each registered project's SDK) with its installed and approved versions, and `catalyst update` moves them to the approved release. `catalyst update policy <component> on|off` holds or releases one component. `catalyst runner update --check` and `catalyst runner auto-update on|off` still work and now cover the same components. The CLI updates itself without breaking the command that is running. If that update fails, the report says so, keeps you on the version you have, and tries again at the next release check. Copied skills never move back to an older version. A running local replica comes back on the new CLI with its synced data. When it cannot, `catalyst replica status` says why and where the data is kept. The Claude plugin moves only to the approved version, and after a move the report tells you to run `/reload-plugins` or restart Claude Code. `catalyst update --json` has a new field, `approvedSkills`, naming the version, repository and full commit each skills pack was approved at. It is `null` when no approval applies.
+
+A busy self-hosted machine no longer waits to go idle before it takes a release. When the new release can read the work records the current one keeps, `catalyst runner update` restarts the machine's supervisor with its running work left in place. Otherwise it waits for an idle machine, as before. An old runner image that running work still used is removed by a later update.
+
+## 0.16.30
+
+An agent seat can now hold a ticket while it works on it. `catalyst lease take <ticket> --agent <seat>` takes the ticket for that seat for a set time (`--ttl <minutes>`). `catalyst lease renew <ticket>` keeps it, and each renewal names one piece of progress: a commit (`--commit`), an artifact (`--artifact`), a finding (`--finding`) or a pull request (`--pr`). `catalyst lease release <ticket>` hands it back, and `catalyst lease show <ticket>` prints who holds it. A refused renewal, for example one that names no new progress, prints the reason and exits 1. A renewal or release refused because the lease already lapsed, or because another seat took the ticket, forgets the lease this machine stored. The machine stores only the seat name and the lease generation, in a file only you can read. New: `catalyst work available` lists, per team, the tickets nobody holds, with the last holder and their progress, and the open pull requests no live lease covers, drafts included. Both commands use your login. Setup run unattended now says what it skipped and names the exact flags each skipped choice needs. The skill references now say how to see whether a repository is paused, and who can pause or resume it.
+
 ## 0.16.29
 
 The CLI now tells Catalyst Cloud which release you have installed: each request to Catalyst Cloud carries the installed version, and so does `catalyst watch` when it connects. Catalyst Cloud can then tell an out-of-date CLI from a current one. Nothing about your requests changes otherwise. On a Mac self-hosted machine, setup now installs a small agent that measures the Mac's disk, so the machine can take work instead of showing zero free slots. When a machine still shows zero free slots, setup and `catalyst ready` now say why: its disk has not been measured yet, or its free space is below the floor (25 GiB by default), with the numbers and the fix. An updated disk sampler also takes effect straight away: setup reloads the running disk agent whenever the sampler script changes, not only when its schedule file does.

package/README.md

@@ -42,7 +42,7 @@ The two packs have different jobs and independent versions. Omit `-g` for a proj
 
 <details><summary><strong>Alternative for Claude Code: the plugin marketplace</strong></summary>
 
-The plugin installs this pack's same `skills/` tree as a managed bundle that updates when we ship. It needs a GitHub SSH key, and it does not load into the session you are already in — run `/reload-plugins` or restart afterwards. Pick one rail for this pack; installing both leaves you with every skill twice. The development pack has its own optional Claude plugin, `catalyst-dev@catalyst-dev-skills`.
+The plugin installs this pack's same `skills/` tree as a managed bundle, and `catalyst update` moves it to the version your workspace approved (see [Updating](#updating)). It needs a GitHub SSH key, and it does not load into the session you are already in — run `/reload-plugins` or restart afterwards. Pick one rail for this pack; installing both leaves you with every skill twice. The development pack has its own optional Claude plugin, `catalyst-dev@catalyst-dev-skills`.
 
 ```
 /plugin marketplace add coalesce-labs/catalyst-cloud-skills
@@ -298,13 +298,16 @@ The package pins the contract range `1.x || 2.x`, recorded in `package.json` und
 - `~/.config/catalyst-cloud/customer.json`, written with mode `0600`, holding your personal key, who you are, and the CLI path.
 - `~/.config/catalyst-cloud/contract.json`, your account's cached contract.
 - `~/.config/catalyst-cloud/published.json`, the cached answer to "what is the newest release" — no credential in it.
+- After `catalyst update` moves the CLI: `~/.config/catalyst-cloud/cli-runtimes/`, one directory per CLI version it installed and `active.json` naming the one your `catalyst` command runs.
 - Only if you start them: `~/.config/catalyst-cloud/replica.db` with its `.pid`, `.writer.lock` and `.writer.state` sidecars, `$XDG_STATE_HOME/catalyst/events/<tenant>/backbone/` (or the home-directory fallback) with bounded daily event segments, and `~/.config/catalyst-cloud/watch-cursor.json`.
 
 The skill files themselves are written by whichever install command you ran, in that tool's own location. Your personal key goes into that one config file and nowhere else.
 
 ## Updating
 
-A plugin install updates when we ship. Skills copied by `npx skills add` do not. After the source and destination check in Install, re-run the Cloud add command to refresh existing skills and pick up new ones. Update the CLI with `npm install -g @catalyst-cloud/cli@latest && catalyst login` — the re-login rewrites the CLI path the skills spawn, so they stop running the old bundle. To run one command against the latest publish without installing, use `npx -p @catalyst-cloud/cli@latest catalyst login`. The next `catalyst` run prints a one-line notice:
+`catalyst update --check` lists each installed component beside the version your workspace approved, says which one is behind and why, and changes nothing. Add `--project <absolute path>` to include a project's SDK; the report gives the one command that moves it, `catalyst update sdk --project <path>`. A project's files change only when you run that command, or after you turn its SDK updates on with `catalyst update policy sdk on --project <path>`. `catalyst update` moves the runner images, the CLI, the Cloud skills (copied on this machine or installed as the Claude plugin), and a running local replica to the approved versions. The new CLI is installed beside the old one, and your `catalyst` command runs it from then on, at the same path. A running replica restarts on it and keeps its synced data; a stopped one stays stopped. The Claude plugin moves through Claude Code, and only when its marketplace serves the approved version; run `/reload-plugins` or restart Claude Code afterwards. When the release check cannot find the `claude` command, it changes nothing and prints the one command that moves the plugin. The development skills are not on the approved release yet: the report lists their version as unknown and gives no command for them, so update them the way you installed them. On a machine whose runner checks for releases every 15 minutes (`catalyst runner auto-update on`), that check moves the same components by itself. Otherwise they move when you run `catalyst update`. Each component is on by default; turn one off with `catalyst update policy <component> off` (for example `cli`), and `catalyst update policy` lists every setting. If you turned the installer's daily update off, the CLI and both skills packs start held, and `catalyst update policy cli on` turns the CLI back on. Add `--json` for a machine-readable report.
+
+A CLI older than `catalyst update` cannot move itself: install it once with `npm install -g @catalyst-cloud/cli@latest && catalyst login`. The re-login rewrites the CLI path the skills spawn, so they stop running the old bundle. To run one command against the latest publish without installing, use `npx -p @catalyst-cloud/cli@latest catalyst login`. The next `catalyst` run prints a one-line notice:
 
 ```
 [catalyst] updated 0.1.1 → 0.2.0: <that version's CHANGELOG.md summary> · update with: npm install -g @catalyst-cloud/cli@latest && catalyst login
@@ -312,7 +315,7 @@ A plugin install updates when we ship. Skills copied by `npx skills add` do not.
 
 A `customer.json` written by an older bundle is still read unchanged; it gains the CLI path and the cached contract the next time you run `catalyst login`.
 
-`catalyst ready` also says when either the installed skills or the CLI is behind the latest publish, naming both versions and the command for each; it is a note, never a failure, and `--offline` (or `CATALYST_SKILLS_OFFLINE=1`) skips the lookup.
+`catalyst ready` also says when either the installed skills or the CLI is behind, naming both versions and the command for each. It compares them with the approved release this machine last read, and only a machine that has not read one yet compares them with the latest publish. It is a note, never a failure, and `--offline` (or `CATALYST_SKILLS_OFFLINE=1`) skips the lookup.
 
 ## Uninstalling
 
@@ -325,6 +328,7 @@ catalyst replica stop
 rm -f ~/.config/catalyst-cloud/customer.json ~/.config/catalyst-cloud/contract.json ~/.config/catalyst-cloud/published.json ~/.config/catalyst-cloud/watch-cursor.json
 rm -f ~/.config/catalyst-cloud/replica.db ~/.config/catalyst-cloud/replica.db.pid ~/.config/catalyst-cloud/replica.db.writer.lock ~/.config/catalyst-cloud/replica.db.writer.state
 rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/catalyst/events"
+rm -rf ~/.config/catalyst-cloud/cli-runtimes
 npm uninstall -g @catalyst-cloud/cli
 ```
 

package/bin/launch.js

@@ -32,6 +32,7 @@
 //     scripts spawn this CLI constantly, and doubling process startup on every call is a real cost.
 //   • ambient unsupported, no pin -> print the verdict and the ONE command; exit 1, never a raw
 //     module-resolution error.
+import { basename } from "node:path";
 import { fileURLToPath } from "node:url";
 
 /** The one stderr line the deprecated name prints in addition to what the program prints. */
@@ -52,6 +53,7 @@ export const DEPRECATED_NAME_LINE =
 export async function launch(invokedAs, binUrl) {
   const argv = process.argv.slice(2);
   const deprecated = invokedAs === "catalyst-skills";
+  if (argv[0] !== "runtime" && (await runSelectedVersion(invokedAs, binUrl))) return;
   const handled = argv[0] === "runtime" ? false : await preflight(invokedAs, binUrl, argv, deprecated);
   if (handled) return;
   const noticeFirst = deprecated && process.stderr.isTTY === true;
@@ -66,6 +68,32 @@ export async function launch(invokedAs, binUrl) {
     });
 }
 
+/**
+ * CTC-6708 — a release check installs the approved CLI in its own directory and records it as the
+ * selected version (dist/update-cli.js). This command stays where npm put it, so scheduled jobs and
+ * saved launcher paths keep working: when the selected version is newer than its own, it loads that
+ * version's bin in this same process (no second process, so a pid, a signal and an exit code are the
+ * selected version's own). The selected version's launcher finds nothing newer and runs. Any doubt
+ * (no record, an unreadable one, a directory that does not hold that version) runs this version, as
+ * before. A release check that runs a staged version to check it sets CATALYST_CLI_ACTIVE_RUNTIME
+ * to that bin's path, so that run never selects. Returns true when it already handled the invocation.
+ */
+async function runSelectedVersion(invokedAs, binUrl) {
+  if (process.env.CATALYST_CLI_ACTIVE_RUNTIME === fileURLToPath(binUrl)) return false;
+  const home = process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? "/";
+  let bin = null;
+  try {
+    const [updateCli, config] = await Promise.all([import("../dist/update-cli.js"), import("../dist/config.js")]);
+    bin = updateCli.activeRuntimeBin(home, config.readManifest().version, basename(fileURLToPath(binUrl)));
+  } catch {
+    return false;
+  }
+  if (!bin) return false;
+  const { pathToFileURL } = await import("node:url");
+  await import(pathToFileURL(bin).href);
+  return true;
+}
+
 /** Returns true when it already handled (and exited) the invocation. */
 async function preflight(invokedAs, binUrl, args, deprecated) {
   const policy = process.env.CATALYST_SKILLS_RUNTIME ?? "auto";

package/dist/approved-release.js

@@ -0,0 +1,210 @@
+// approved-release.ts — the release Catalyst approved for every component an install keeps, read
+// once per release check (CTC-6708). The approved record names each release-train member's exact
+// version together, so the CLI's "newest" answer comes from it, never from npm's `latest` tag.
+//
+// Two transports carry the same record:
+//   - a signed-in CLI reads the member route `GET /api/v1/releases/approved`;
+//   - an enrolled machine's desired-release answer (`GET /api/v1/hosts/desired-release`, read inside
+//     the supervisor container by runner-update.ts) carries it as `release.components`, beside the
+//     digest-pinned images it already names. The host credential never leaves Docker.
+//
+// Parsing is strict: exact stable versions only (no tags, ranges or pre-releases), every version on
+// the record's declared train line, skills packs pinned to one of two known repositories at a full
+// commit. A record on another train is reported and never applied: automatic moves stay on the
+// MAJOR.MINOR line this CLI ships on. The last record read is cached for diagnostics only; a failed
+// read never applies a cached record.
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { configDirFor, loadConfig, readManifest } from "./config.js";
+import { CliError, MeError } from "./errors.js";
+import { isRecord, writePrivateAtomic } from "./runner-update.js";
+import { apiClient } from "./transport.js";
+export const APPROVED_RELEASE_PATH = "/api/v1/releases/approved";
+export const APPROVED_RELEASE_CACHE_FILE = "approved-release.json";
+/** Train members the approved record may name. Only some are installed on a customer's machine;
+ *  the rest are inventory metadata and never something this CLI installs. */
+export const RELEASE_MEMBERS = [
+    "cli",
+    "forwarder",
+    "plugin",
+    "sdk",
+    "sdk-replica-node",
+    "sdk-replica-browser",
+    "schema",
+    "replicate",
+    "read-model",
+    "design",
+    "installer",
+];
+export const SKILL_PACKS = ["cloud", "dev"];
+/** The only repository each pack may come from. A record naming another is refused whole. */
+export const SKILL_PACK_REPOSITORIES = {
+    cloud: "coalesce-labs/catalyst-cloud-skills",
+    dev: "coalesce-labs/catalyst-dev-skills",
+};
+const STABLE_VERSION = /^(0|[1-9]\d{0,5})\.(0|[1-9]\d{0,5})\.(0|[1-9]\d{0,5})$/;
+const RELEASE_LINE = /^(0|[1-9]\d{0,5})\.(0|[1-9]\d{0,5})$/;
+const COMMIT = /^[0-9a-f]{40}$/;
+const APPROVAL_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+const posInt = (value) => typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+/** An exact stable version, or null. Unlike skills.ts's lenient `semverOlder`, this is the authority
+ *  check: `0.16.28` passes; `latest`, `^0.16.28`, `0.16.28-rc.1`, `v0.16.28` and `0.16` do not. */
+export function exactVersion(value) {
+    return typeof value === "string" && STABLE_VERSION.test(value) ? value : null;
+}
+/** MAJOR.MINOR of an exact version. */
+export function trainOf(version) {
+    return version.split(".").slice(0, 2).join(".");
+}
+/** Compare two exact versions: negative when `a` is older, 0 when equal, positive when newer. */
+export function compareVersions(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/** The train this CLI ships on; automatic updates never leave it. */
+export function supportedReleaseLine() {
+    return trainOf(readManifest().version);
+}
+/** Parse the approved record from an unknown body. Any malformed field refuses the whole record. */
+export function parseApprovedRelease(input) {
+    const invalid = { ok: false, reason: "response_invalid" };
+    if (!isRecord(input) || input.schemaVersion !== 1)
+        return invalid;
+    if (typeof input.approvalId !== "string" || !APPROVAL_ID.test(input.approvalId))
+        return invalid;
+    if (!posInt(input.generation) || !posInt(input.approvedAtMs))
+        return invalid;
+    if (typeof input.releaseLine !== "string" || !RELEASE_LINE.test(input.releaseLine))
+        return invalid;
+    const releaseLine = input.releaseLine;
+    if (!isRecord(input.members))
+        return invalid;
+    const members = {};
+    for (const member of RELEASE_MEMBERS) {
+        const value = input.members[member];
+        if (value === undefined)
+            continue;
+        const version = exactVersion(value);
+        if (version === null || trainOf(version) !== releaseLine)
+            return invalid;
+        members[member] = version;
+    }
+    if (members.cli === undefined)
+        return invalid;
+    const skills = {};
+    if (input.skills !== undefined) {
+        if (!isRecord(input.skills))
+            return invalid;
+        for (const pack of SKILL_PACKS) {
+            const value = input.skills[pack];
+            if (value === undefined)
+                continue;
+            if (!isRecord(value))
+                return invalid;
+            const version = exactVersion(value.version);
+            if (version === null || trainOf(version) !== releaseLine)
+                return invalid;
+            if (value.repository !== SKILL_PACK_REPOSITORIES[pack])
+                return invalid;
+            if (typeof value.commit !== "string" || !COMMIT.test(value.commit))
+                return invalid;
+            skills[pack] = { version, repository: value.repository, commit: value.commit };
+        }
+    }
+    return {
+        ok: true,
+        release: { approvalId: input.approvalId, generation: input.generation, approvedAtMs: input.approvedAtMs, releaseLine, members, skills },
+    };
+}
+/** Read the member route with this machine's sign-in. Never throws; every failure is a reason. */
+export async function readMemberApproval(ctx) {
+    let cfg;
+    try {
+        cfg = loadConfig(ctx.home);
+    }
+    catch {
+        return { kind: "unavailable", reason: "signed_out" };
+    }
+    if (!cfg)
+        return { kind: "unavailable", reason: "signed_out" };
+    try {
+        const res = await apiClient(cfg, ctx).getJson(APPROVED_RELEASE_PATH, { accept: [404] });
+        if (res.status === 404)
+            return { kind: "unavailable", reason: "not_provided" };
+        const body = isRecord(res.body) && res.body.ok === true ? res.body.release : res.body;
+        const parsed = parseApprovedRelease(body);
+        return parsed.ok ? { kind: "approved", release: parsed.release, source: "network" } : { kind: "unavailable", reason: parsed.reason };
+    }
+    catch (err) {
+        if (err instanceof MeError && err.kind === "network")
+            return { kind: "unavailable", reason: "unreachable" };
+        if (err instanceof CliError && (err.status === 401 || err.status === 403))
+            return { kind: "unavailable", reason: "credential_refused" };
+        if (err instanceof MeError && err.kind === "shape")
+            return { kind: "unavailable", reason: "response_invalid" };
+        return { kind: "unavailable", reason: "unreachable" };
+    }
+}
+/** The component record a host's desired-release answer carries, from the same read the image
+ *  update used. A legacy answer with images only reads `not_provided`; a record whose generation is
+ *  not the image generation reads `envelope_mismatch`, so the two halves never mix snapshots. */
+export function hostApproval(read) {
+    if (read.kind === "no_credential")
+        return { kind: "unavailable", reason: "host_unreadable" };
+    if (read.kind === "unreachable")
+        return { kind: "unavailable", reason: "unreachable" };
+    if (read.status === 401 || read.status === 403)
+        return { kind: "unavailable", reason: "credential_refused" };
+    // 404 and 503 are the cloud saying it has no approved release to name; anything else failed.
+    if (read.status === 404 || read.status === 503)
+        return { kind: "unavailable", reason: "not_provided" };
+    if (read.status !== 200)
+        return { kind: "unavailable", reason: "unreachable" };
+    if (!isRecord(read.body) || read.body.ok !== true || !isRecord(read.body.release))
+        return { kind: "unavailable", reason: "response_invalid" };
+    const release = read.body.release;
+    if (release.components === undefined)
+        return { kind: "unavailable", reason: "not_provided" };
+    const parsed = parseApprovedRelease(release.components);
+    if (!parsed.ok)
+        return { kind: "unavailable", reason: parsed.reason };
+    if (parsed.release.generation !== release.generation)
+        return { kind: "unavailable", reason: "envelope_mismatch" };
+    return { kind: "approved", release: parsed.release, source: "host" };
+}
+export function approvalCachePathFor(home) {
+    return join(configDirFor(home), APPROVED_RELEASE_CACHE_FILE);
+}
+/** The last approved record an applying check read, for an offline diagnostic. Never applied. */
+export function readApprovalCache(home) {
+    const path = approvalCachePathFor(home);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (!isRecord(parsed) || !posInt(parsed.observedAtMs))
+            return null;
+        const release = parseApprovedRelease(parsed.release);
+        return release.ok ? { observedAtMs: parsed.observedAtMs, release: release.release } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Best effort: a read-only home keeps working without its diagnostic cache. */
+export function writeApprovalCache(home, cache) {
+    try {
+        const path = approvalCachePathFor(home);
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writePrivateAtomic(path, `${JSON.stringify({ observedAtMs: cache.observedAtMs, release: { schemaVersion: 1, ...cache.release } }, null, 2)}\n`);
+    }
+    catch {
+        // the diagnostic cache is optional
+    }
+}

package/dist/args.js

@@ -29,6 +29,11 @@ export const FLAG_TABLES = {
         yes: { value: false, help: "uninstall: confirm without a terminal" },
         "delete-checkouts": { value: false, help: "uninstall: also delete the repository and thoughts checkouts" },
     },
+    update: {
+        check: { value: false, help: "read the approved release and list every component against it, without changing anything" },
+        project: { value: true, help: "also check this project's SDK (an absolute path); with policy sdk, the project the setting is for" },
+        dir: { value: true, help: "the runner directory (default: the one setup created)" },
+    },
     login: {
         "start-replica": {
             value: false,
@@ -508,6 +513,19 @@ export const FLAG_TABLES = {
             help: "with --remove: answer the question yes (a run with no terminal only reports otherwise)",
         },
     },
+    lease: {
+        agent: { value: true, help: "the seat's name, 1 to 40 of a-z, 0-9 and - (take: required; renew, release: when this machine holds the ticket for several seats)" },
+        ttl: { value: true, help: "take, renew: minutes until the lease lapses without a renewal (the cloud keeps it between 5 and 60; default 30)" },
+        commit: { value: true, help: "renew: the full 40-character sha of a commit you pushed" },
+        artifact: { value: true, help: "renew: a thoughts path or check-run id you wrote" },
+        finding: { value: true, help: "renew: a comment or review id you posted" },
+        pr: { value: true, help: "renew: the number of a pull request you opened" },
+        note: { value: true, help: "renew: a few words about the progress (not part of what counts as new)" },
+        generation: { value: true, help: "renew, release: the generation the take printed (default: the one this machine stored)" },
+    },
+    work: {
+        team: { value: true, help: "available: one team's key (default: every team in the workspace contract)" },
+    },
     repo: {
         reason: { value: true, help: "pause: required; resume: optional; 1 to 500 characters after trimming (owner or admin)" },
         write: {
@@ -562,6 +580,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]",
     runner: "runner [status] | runner stop | runner start | runner uninstall [--yes] [--delete-checkouts] | runner update [--check] [--dir <runner directory>] [--fleet] | runner auto-update [status|on|off] [--json]",
+    update: "update [--check] [--project <absolute path>] [--dir <runner directory>] | update sdk --project <absolute path> | update policy [<component> on|off] | update policy sdk on|off --project <absolute path> [--json]   (components: runner, supervisor, watchdog, cli, skills-cloud, skills-dev, replica)",
     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] [--remove-local-data] [--runner|--no-runner] [--no-color] [--yes] [--dry-run] [--json] | onboard --headless [--key-file <path>] [--team ...] [--repo ...]... [--coding-account ...] [--runner yes|no] [--remove-local-data] [--json]",
@@ -594,6 +613,8 @@ export const VERB_USAGE = {
     messages: "messages read --ticket CTC-N [--since SEQUENCE] [--json]",
     capabilities: "capabilities [--json]",
     project: "project <list [--json] | wip-limit <get|set <n>|set default> [--team K] [--json]>",
+    lease: "lease <take <ticket> --agent <seat> [--ttl <minutes>] | renew <ticket> (--commit <sha>|--artifact <path or id>|--finding <id>|--pr <number>) [--note <text>] [--agent <seat>] [--generation <n>] | release <ticket> [--agent <seat>] [--generation <n>] | show <ticket>> [--json]   (a seat's ticket lease: take, renew with new progress, release, read; needs login)",
+    work: "work available [--team K] [--json]   (per team: tickets nobody holds, with the last holder and progress, and open pull requests no live lease covers, drafts included)",
     repo: "repo <status|pause <owner/name> --reason <text>|resume <owner/name> [--reason <text>]|agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]> [--json]   (status: visible workspace repositories; agents-block/agent-setup: local checkout)",
     legacy: "legacy [--remove [--data] [--yes]] [--json]",
     connections: "connections personal <linear|github> <start|status> [--wait <seconds>] [--json]",

package/dist/capabilities.js

@@ -8,6 +8,9 @@ export const CAPABILITIES = [
     { verb: "hosts", does: "list this account's machines, current use and live capacity", needs: "member", routes: [], since: "0.16.0" },
     { verb: "hosts remove|rename", does: "remove or rename a self-hosted machine in this account", needs: "admin", routes: [], since: "0.16.0" },
     { verb: "runner update|auto-update", does: "move this machine's self-hosted runner to the release Catalyst approved, and check for one every 15 minutes", needs: "member", routes: [], since: "0.16.16" },
+    { verb: "update", does: "list every installed component against the release Catalyst approved, move the runner images to it, and name the command for the rest", needs: "member", routes: [], since: "0.16.31" },
+    { verb: "update sdk", does: "move one project's Catalyst SDK to the approved versions with its own package manager, when the person asks", needs: "member", routes: [], since: "0.16.31" },
+    { verb: "update policy", does: "turn automatic updates off or on for one installed component, or set a project's SDK to notify only", needs: "member", routes: [], since: "0.16.31" },
     { verb: "runner status|stop|start", does: "stop this machine's self-hosted runner taking work, or start it again with the same registration", needs: "member", routes: [], since: "0.16.27" },
     { verb: "runner uninstall", does: "remove this machine's self-hosted runner and revoke its registration and runner key", needs: "admin", routes: [], since: "0.16.27" },
     // CTC-4680: plain `catalyst setup` runs the onboard flow, so install.sh may hand off to it. install.sh
@@ -32,6 +35,8 @@ export const CAPABILITIES = [
     { verb: "project wip-limit set", does: "set a project's new-start WIP limit (0 to 9999, or back to the workspace default)", needs: "admin", routes: [agent("POST", "team-wip-limit")], since: "0.13.1" },
     { verb: "repo status", does: "list visible repositories with their state, pause details and projects", needs: "member", routes: [agent("GET", "repos")], since: "0.16.27" },
     { verb: "repo pause|resume", does: "pause or resume a repository as a workspace owner or admin", needs: "admin", routes: [agent("GET", "repos"), agent("POST", "repos/pause"), agent("POST", "repos/resume")], since: "0.16.27" },
+    { verb: "lease take|renew|release|show", does: "hold the ticket a seat works through a ticket lease that lapses without new progress, instead of a label", needs: "member", routes: [agent("POST", "ticket-lease/take"), agent("POST", "ticket-lease/renew"), agent("POST", "ticket-lease/release"), agent("GET", "ticket-lease")], since: "0.16.30" },
+    { verb: "work available", does: "list tickets nobody holds, with the last holder and progress, and open pull requests no lease covers", needs: "member", routes: [], since: "0.16.30" },
     { verb: "repo agents-block", does: "add or refresh the one Catalyst block in a checkout's AGENTS.md, in the working tree, for the person to commit and open as a pull request", needs: "member", routes: [], since: "0.13.1" },
     { verb: "repo agent-setup", does: "read a checkout's agent setup (AGENTS.md, CLAUDE.md, .agents and .claude skills and rules) and, on request, make it portable in the working tree", needs: "member", routes: [], since: "0.13.1" },
     { verb: "env shell", does: "open this repository's environment on this computer: Catalyst's image, the declared toolchain and variables (needs Docker; no login for Catalyst's image)", needs: "member", routes: [], since: "0.16.20" },

package/dist/cli-update-notice.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { configDirFor, publishedCachePathFor } from "./config.js";
-import { latestPublishedVersion } from "./published.js";
+import { newestCliVersion } from "./published.js";
 import { semverOlder } from "./semver.js";
 const DAY_MS = 24 * 60 * 60 * 1000;
 const RELEASE = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
@@ -62,12 +62,15 @@ export async function maybePrintPublishedUpdateNotice(ctx, options) {
             rmSync(temporary, { force: true });
         }
         // Record the attempt before the bounded lookup, including failures, so offline commands do
-        // not repeatedly contact npm. Reuse ready's anonymous request and version cache.
-        const reply = await latestPublishedVersion(ctx);
+        // not repeatedly contact npm. Reuse ready's anonymous request and version cache. Once this
+        // install has read an approved release, that is the version named (CTC-6708).
+        const reply = await newestCliVersion(ctx);
         if (reply.latest &&
             RELEASE.test(reply.latest) &&
             semverOlder(options.version, reply.latest)) {
-            ctx.stderr(`Catalyst ${reply.latest} is out. Update with: npm install -g @catalyst-cloud/cli@latest`);
+            ctx.stderr(reply.source === "approved"
+                ? `Catalyst ${reply.latest} is approved for this workspace. Update with: catalyst update`
+                : `Catalyst ${reply.latest} is out. Update with: npm install -g @catalyst-cloud/cli@latest`);
         }
     }
     catch {

package/dist/cli.js

@@ -1,5 +1,6 @@
 import { cmdHosts } from "./hosts.js";
 import { cmdRunner } from "./runner-command.js";
+import { cmdUpdate } from "./update-command.js";
 import { cmdSeat } from "./seat.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.
@@ -21,6 +22,7 @@ import { openBrowserChecked as defaultOpenBrowser } from "./browser.js";
 import { cmdAccounts, cmdExplain, cmdHistory, cmdQueue, cmdRunning, } from "./execution.js";
 import { cmdQuery } from "./query.js";
 import { maybePrintPublishedUpdateNotice } from "./cli-update-notice.js";
+import { semverOlder } from "./semver.js";
 import { cmdReady } from "./ready.js";
 import { cmdReplica } from "./replica.js";
 import { cmdRuntime } from "./runtime-verb.js";
@@ -46,6 +48,7 @@ import { cmdTeam } from "./team.js";
 import { cmdCapabilities } from "./capabilities.js";
 import { cmdProject } from "./project.js";
 import { cmdRepo } from "./repo.js";
+import { cmdLease, cmdWork } from "./lease.js";
 import { cmdLegacy } from "./legacy.js";
 import { cmdIdentity } from "./identity.js";
 import { cmdMessages } from "./messages.js";
@@ -89,6 +92,7 @@ export function usageText() {
         "  catalyst hosts [list] | hosts remove <name-or-id> [--yes] | hosts rename <name-or-id> <new-name>",
         "  catalyst runner [status] | runner stop | runner start | runner uninstall [--yes] [--delete-checkouts]   (this machine's self-hosted runner)",
         "  catalyst runner update [--check] | runner auto-update [status|on|off]   (move this machine's runner to the approved release)",
+        "  catalyst update [--check] [--project <path>] | update policy [<component> on|off]   (every installed component against the approved release)",
         "  catalyst mcp add|list|remove (vault references only) | mcp status <name>   (a server's state, grants and last 50 tool calls)",
         "  catalyst contract [--refresh] [--path <a.b.c>]",
         "  catalyst query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>>",
@@ -113,6 +117,8 @@ export function usageText() {
         "  catalyst repo pause <owner/name> --reason <text> | repo resume <owner/name> [--reason <text>]   (owner or admin; reason: 1 to 500 trimmed characters)",
         "  catalyst repo status [--json]   (visible workspace repositories and their paused state; needs login)",
         "  catalyst repo <agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]>   (a checkout's AGENTS.md block and portable agent layout; working tree only)",
+        "  catalyst lease <take <ticket> --agent <seat> [--ttl <minutes>]|renew <ticket> --commit|--artifact|--finding|--pr <ref> [--note <text>]|release <ticket>|show <ticket>> [--json]   (a seat's ticket lease; needs login)",
+        "  catalyst work available [--team K] [--json]   (tickets nobody holds and open pull requests no lease covers)",
         "  catalyst legacy [--remove [--data] [--yes]]   (leftovers of the old local Catalyst runtime: list them; remove them only on a yes)",
         "  catalyst identity linear <status|options|set> [<linearUserId>] [--json]",
         "  catalyst messages read --ticket CTC-N [--since SEQUENCE] [--json]   (messages sent to a ticket on your teams)",
@@ -195,6 +201,10 @@ function maybePrintUpdateNotice(args, ctx) {
     const manifest = readManifest();
     if (cfg.lastSkillBundleVersion === manifest.version)
         return;
+    // CTC-6741: a newer CLI selected by `catalyst update` records its own bundle here, and the older
+    // npm-installed one still runs for `catalyst runtime`. Copied skills only ever move forward.
+    if (cfg.lastSkillBundleVersion && semverOlder(manifest.version, cfg.lastSkillBundleVersion))
+        return;
     const previous = cfg.lastSkillBundleVersion;
     if (previous) {
         const entry = parseChangelogEntry(readChangelog(), manifest.version);
@@ -548,6 +558,10 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdProject(args, ctx);
             case "repo":
                 return await cmdRepo(args, ctx);
+            case "lease":
+                return await cmdLease(args, ctx);
+            case "work":
+                return await cmdWork(args, ctx);
             case "legacy":
                 return await cmdLegacy(args, ctx, { localSyncSelected: savedLocalSync(ctx), ...deps.legacy });
             case "identity":
@@ -558,6 +572,8 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdHosts(args, ctx, deps.hosts);
             case "runner":
                 return await cmdRunner(args, ctx, deps.runner);
+            case "update":
+                return await cmdUpdate(args, ctx, deps.update);
             case "connections":
                 return await cmdConnections(args, ctx, deps.connections ?? {});
             default:
@@ -624,8 +640,11 @@ const VERB_HELP_KNOWN = Object.fromEntries([
     "capabilities",
     "project",
     "repo",
+    "lease",
+    "work",
     "legacy",
     "onboard",
+    "update",
 ].map((v) => [v, true]));
 /** CTC-4680: the Pixel Nucleus mark belongs to `catalyst setup` alone. `setup` runs the onboard
  *  flow, so this is read from the verb typed, before setup becomes onboard. */