@catalyst-cloud/cli 0.16.30 → 0.16.31

package/CHANGELOG.md

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

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

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

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";
@@ -90,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>>",
@@ -198,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);
@@ -565,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:
@@ -635,6 +644,7 @@ const VERB_HELP_KNOWN = Object.fromEntries([
     "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. */

package/dist/published.js

@@ -4,6 +4,7 @@
 // reason instead of throwing: a customer who cannot reach npm must still get a verdict (CTC-2160).
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+import { readApprovalCache, supportedReleaseLine } from "./approved-release.js";
 import { LEGACY_PACKAGE_NAME, publishedCachePathFor } from "./config.js";
 /** CTC-3479 — asks about the forwarder package whichever package is installed. The release publishes
  *  @catalyst-cloud/cli first and the forwarder last, at one version, so the forwarder's `latest`
@@ -77,3 +78,17 @@ export async function latestPublishedVersion(ctx, opts = {}) {
     writePublishedCache(ctx.home, { fetchedAt: ctx.now().toISOString(), latest });
     return { latest, reason: null, source: "network" };
 }
+/**
+ * CTC-6708 — the CLI's "newest" answer is the approved release once this install has read one: every
+ * applying release check records it, the 15-minute schedule included. Reading it is local, so this
+ * adds no network call. An install that has never read an approved release, or read one on another
+ * train, falls back to the npm lookup above, and its answer stays labelled the latest published version.
+ */
+export async function newestCliVersion(ctx, opts = {}) {
+    const approved = readApprovalCache(ctx.home)?.release;
+    const cli = approved?.members.cli;
+    // CTC-6741: a release on another train is never applied, so it is never the answer either.
+    if (approved && cli && approved.releaseLine === supportedReleaseLine())
+        return { latest: cli, reason: null, source: "approved", ...(approved.skills.cloud ? { skills: approved.skills.cloud.version } : {}) };
+    return latestPublishedVersion(ctx, opts);
+}

package/dist/ready.js

@@ -6,7 +6,7 @@ import { basename, delimiter, dirname, join } from "node:path";
 import { DEFAULT_BASE_URL, LEGACY_PACKAGE_NAME, PACKAGE_NAME, defaultSkillsDirFor, loadConfig, normalizeBaseUrl, readManifest, upgradeCommand, } from "./config.js";
 import { contractVersionInRange, readContractCache } from "./contract.js";
 import { CliError } from "./errors.js";
-import { latestPublishedVersion } from "./published.js";
+import { newestCliVersion } from "./published.js";
 import { replicaStatus, writerIsRunning, } from "./replica.js";
 import { loadHttpSdk } from "./sdk.js";
 import { FIX_COMMAND, detectRuntime, runtimeVerdict, supportedRangeText, } from "./runtime.js";
@@ -234,7 +234,7 @@ export async function readyReport(ctx, deps) {
     const skillsDir = cfg?.skillsDir ?? defaultSkillsDirFor(ctx.home);
     const offline = deps.offline === true || ctx.env.CATALYST_SKILLS_OFFLINE === "1";
     if (!offline) {
-        const pub = await (deps.fetchLatestRelease ?? (() => latestPublishedVersion(ctx)))();
+        const pub = await (deps.fetchLatestRelease ?? (() => newestCliVersion(ctx)))();
         if (pub.latest === null) {
             checks.push({
                 id: "cliRelease",
@@ -252,7 +252,10 @@ export async function readyReport(ctx, deps) {
                     id: "cliRelease",
                     ok: false,
                     note: true,
-                    line: `cliRelease: ${installedCli} installed is older than the latest published ${pub.latest} — upgrade: ${upgradeCommand()}`,
+                    // CTC-6708 — once this install has read an approved release, that is the answer.
+                    line: pub.source === "approved"
+                        ? `cliRelease: ${installedCli} installed is older than the approved ${pub.latest} — update: catalyst update`
+                        : `cliRelease: ${installedCli} installed is older than the latest published ${pub.latest} — upgrade: ${upgradeCommand()}`,
                 });
             }
             // clause 1 — the skill files on disk, read independently of whichever CLI is answering. Both
@@ -262,7 +265,8 @@ export async function readyReport(ctx, deps) {
             // older than any stamp, which is why the stamped half says "oldest STAMPED" and the unstamped
             // names are always printed rather than hidden behind whichever branch happened to win.
             const found = installedBundleVersion(skillsDir, deps.skillNames);
-            const stampBehind = found.version !== null && semverOlder(found.version, pub.latest);
+            const skillsTarget = pub.source === "approved" ? (pub.skills ?? pub.latest) : pub.latest;
+            const stampBehind = found.version !== null && semverOlder(found.version, skillsTarget);
             const unstampedBehind = found.unstamped.length > 0 &&
                 !semverOlder(pub.latest, FIRST_STAMPED_VERSION);
             if (stampBehind || unstampedBehind) {
@@ -277,7 +281,9 @@ export async function readyReport(ctx, deps) {
                     id: "skillsRelease",
                     ok: false,
                     note: true,
-                    line: `skillsRelease: in ${skillsDir} ${facts.join(", and ")}, while the published bundle is ${pub.latest} — update: npx skills update -y`,
+                    line: pub.source === "approved"
+                        ? `skillsRelease: in ${skillsDir} ${facts.join(", and ")}, while the approved bundle is ${skillsTarget} — update: catalyst update`
+                        : `skillsRelease: in ${skillsDir} ${facts.join(", and ")}, while the published bundle is ${pub.latest} — update: npx skills update -y`,
                 });
             }
         }

package/dist/replica.js

@@ -3,10 +3,11 @@
 // `status` is the check every skill runs first and it needs no network and no SDK: the pidfile, the
 // writer-lock heartbeat, and the `sync_meta.cursor` row (read through node:sqlite read-only). Exit
 // 0 fresh, 1 present but stale, 2 not configured, 3 absent. `--probe` adds the one network call.
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { join } from "node:path";
 import { flagBool, flagInt, flagString, positionals } from "./args.js";
-import { apiBase, loadConfig, replicaDbPath, replicaOptedIn } from "./config.js";
+import { apiBase, configDirFor, loadConfig, readManifest, replicaDbPath, replicaOptedIn } from "./config.js";
 import { detachSelf } from "./detach.js";
 import { CliError, UsageError } from "./errors.js";
 import { apiClient } from "./transport.js";
@@ -62,7 +63,8 @@ export function readWriterState(dbPath) {
             typeof rec.consecutiveFailures !== "number" ||
             !(rec.lastError === null || typeof rec.lastError === "string") ||
             !(rec.lastFailureAt === null || typeof rec.lastFailureAt === "number") ||
-            !stoppedOk) {
+            !stoppedOk ||
+            !(rec.version === undefined || typeof rec.version === "string")) {
             return null;
         }
         return rec;
@@ -72,7 +74,7 @@ export function readWriterState(dbPath) {
     }
 }
 export function writeWriterState(dbPath, s, nowMs) {
-    writeFileSync(writerStatePath(dbPath), JSON.stringify({ ...s, updatedAt: nowMs }));
+    writeFileSync(writerStatePath(dbPath), JSON.stringify({ ...s, version: readManifest().version, updatedAt: nowMs }));
 }
 /** Remove the writer state sidecar; a no-op (never throws) when it is already gone. */
 export function clearWriterState(dbPath) {
@@ -83,6 +85,25 @@ export function clearWriterState(dbPath) {
         // already gone
     }
 }
+/** A restart a release check began and has not finished (update-replica.ts, CTC-6708). The owner's
+ *  own `replica stop` clears it, so their stop is never undone. */
+export function pendingRestartPathFor(home) {
+    return join(configDirFor(home), "replica-restart.json");
+}
+/** The restart a release check began for `dbPath` and has not confirmed, with the CLI version it
+ *  expects the new writer to run when the record names one. */
+export function pendingRestart(home, dbPath) {
+    try {
+        const raw = JSON.parse(readFileSync(pendingRestartPathFor(home), "utf8"));
+        if (typeof raw !== "object" || raw === null || raw.dbPath !== dbPath)
+            return null;
+        const target = raw.target;
+        return { dbPath, target: typeof target === "string" ? target : null };
+    }
+    catch {
+        return null;
+    }
+}
 export function pidAlive(pid) {
     if (pid === null || !Number.isInteger(pid) || pid <= 0)
         return false;
@@ -348,7 +369,15 @@ async function cmdStatus(args, ctx) {
             status.lag = status.cursor === null ? head.body.cursor : head.body.cursor - status.cursor;
         }
     }
-    ctx.stdout(args.json ? JSON.stringify(status) : statusLine(status));
+    const restart = status.dbPath !== null && !writerIsRunning(status) ? pendingRestart(ctx.home, status.dbPath) : null;
+    if (args.json)
+        ctx.stdout(JSON.stringify(restart ? { ...status, pendingRestart: restart } : status));
+    else {
+        ctx.stdout(statusLine(status));
+        // CTC-6743: a writer a release check stopped and restarted is down for that reason, not its owner's.
+        if (restart)
+            ctx.stdout(`  a release check restarted it${restart.target ? ` on CLI ${restart.target}` : ""} and the new writer is not running; its synced data is kept at ${status.dbPath}, and the next release check starts it again`);
+    }
     return status.exitCode;
 }
 async function cmdStart(args, ctx, cfg, dbPath, deps) {
@@ -382,7 +411,9 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
         if (recordOwned)
             return;
         recordOwned = true;
-        clearWriterState(dbPath);
+        // CTC-6743: a fresh, healthy record rather than none, so a release check can read the CLI
+        // version this writer runs without waiting for a failed pull to write one.
+        writeWriterState(dbPath, { pid: process.pid, consecutiveFailures: 0, lastError: null, lastFailureAt: null, stopped: null }, ctx.now().getTime());
     };
     const resetFailures = () => {
         if (failures === 0)
@@ -413,6 +444,11 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
             log: (level, msg, extra) => ctx.stderr(`[replica ${level}] ${msg}${extra ? ` ${safeJson(extra)}` : ""}`),
             onStatus: (s) => {
                 ctx.stderr(`[replica] status=${s}`);
+                // CTC-6743: a status means start() already holds the writer lock, so this run owns the
+                // record. Taking it here, not after a long first seed, means a release check never reads a
+                // seeding writer as one with no version and restarts it every interval.
+                if (s === "resyncing" || s === "connecting")
+                    takeOwnershipOfRecord();
                 // A "live" that does NOT follow a re-seed is just the socket coming up — the warm failing
                 // loop passes through it every cycle, so it must not reset the count (CTC-2499).
                 if (s === "resyncing") {
@@ -544,6 +580,7 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
     return 0;
 }
 function cmdStop(ctx, dbPath) {
+    rmSync(pendingRestartPathFor(ctx.home), { force: true });
     const pid = readPidfile(dbPath);
     if (pid === null) {
         ctx.stdout(`no pidfile at ${pidfilePath(dbPath)} — nothing to stop (a foreground writer is stopped with Ctrl-C)`);