@catalyst-cloud/cli 0.16.16 → 0.16.18

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.16.18
+
+A self-hosted machine now returns to the approved release by itself after setup runs again on it. Before, re-running setup could put older images back while the machine still counted itself current, so it stopped updating. On Linux, the 15-minute update schedule now keeps running after you enable lingering for your user. Install this version, then run `catalyst runner auto-update on` to rewrite the schedule.
+
+## 0.16.17
+
+A self-hosted machine now keeps its own images current. Every 15 minutes it checks for the release Catalyst approved, waits until no work is running on it, switches to the new images, and goes back to the previous ones if the machine is not ready within five minutes. `catalyst runner update --check` shows what would change, and `catalyst runner auto-update status|on|off` controls the schedule. Setup turns it on and now starts new machines on the current approved images. To turn it on for a machine you already set up, run `catalyst runner auto-update on`.
+
 ## 0.16.16
 
 Publishing a browser verification recording now saves its proof card with the required attachment details. Update the CLI before using `browser-verify --publish`.

package/dist/args.js

@@ -21,6 +21,11 @@ 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" } },
+    runner: {
+        check: { value: false, help: "read the approved release and say what would change, without changing it" },
+        auto: { value: false, help: "one-line output for the scheduled run" },
+        dir: { value: true, help: "the runner directory (default: the one setup created)" },
+    },
     login: {
         "start-replica": {
             value: false,
@@ -499,6 +504,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 update [--check] [--dir <runner directory>] | runner auto-update [status|on|off]",
     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

@@ -7,6 +7,7 @@ const agent = (method, name) => ({ method, path: `/api/v1/agent/${name}` });
 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" },
     // CTC-4680: plain `catalyst setup` runs the onboard flow, so install.sh may hand off to it. install.sh
     // reads this flag rather than `setup --help`, which already exits 0 on 0.15.x.
     { verb: "setup", does: "set up Catalyst step by step, or show install.sh's plan, progress and sign-in in this terminal", needs: "member", routes: [], since: "0.15.0", engineProtocol: 1, bootstrapHandoff: true, bootstrapHandoffVersion: 2 },

package/dist/cli.js

@@ -1,4 +1,5 @@
 import { cmdHosts } from "./hosts.js";
+import { cmdRunner } from "./runner-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.
@@ -84,6 +85,7 @@ export function usageText() {
         "  catalyst status | notice | me | ready | accounts",
         "  catalyst seat checkout --size big|med --harness claude,codex,opencode [--session-id ID] [--stage STAGE]",
         "  catalyst hosts [list] | hosts remove <name-or-id> [--yes] | hosts rename <name-or-id> <new-name>",
+        "  catalyst runner update [--check] | runner auto-update [status|on|off]   (move this machine's runner to the approved release)",
         "  catalyst mcp add|list|remove (vault references only)",
         "  catalyst contract [--refresh] [--path <a.b.c>]",
         "  catalyst query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>>",
@@ -523,6 +525,8 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdIdentity(args, ctx, deps.identity ?? {});
             case "hosts":
                 return await cmdHosts(args, ctx, deps.hosts);
+            case "runner":
+                return await cmdRunner(args, ctx, deps.runner);
             case "connections":
                 return await cmdConnections(args, ctx, deps.connections ?? {});
             default:

package/dist/onboard-runner.js

@@ -20,13 +20,14 @@ import { onboardStateRoot, } from "./onboard.js";
 /** The Compose project name the vendored file declares. */
 export const RUNNER_PROJECT = "catalyst-host";
 export const RUNNER_SESSION_NETWORK = "catalyst-session-v1";
-/** Supervisor from ee729b12 (Host images 38138827750); runner from
- * 91a82214 (Runner image 38133282600). The watchdog retains its reviewed pin.
+/** Catalyst's approved host release, generation 2 (hr-a19f7b0859a98147-9a96426c93e32173-63a9b20c3be3dc3e):
+ * runner, supervisor and watchdog all built from catalyst-cloud 2ec4a551. A machine set up from these
+ * pins then follows newer approved releases itself (`catalyst runner update`, CTC-4646).
  * Explicit environment values override these pins; a saved runner image is preserved. */
 export const RUNNER_HOST_IMAGES = {
-    supervisor: "ghcr.io/coalesce-labs/catalyst-supervisor@sha256:3331ebc4204ae3975a4efb2c870c941f9c0f5ab435735e91dc9977941c91e9a8",
-    watchdog: "ghcr.io/coalesce-labs/catalyst-deadline-watchdog@sha256:a5999dbf229ac432b83c2ed3fe43fa251366baceb73af2f57590890a6a758f0d",
-    runner: "ghcr.io/coalesce-labs/catalyst-runner@sha256:9db2bf2c5580e2a1459fd076fa32c9af34456cc639ec3ab92b57b6ad98da67fb",
+    supervisor: "ghcr.io/coalesce-labs/catalyst-supervisor@sha256:9a96426c93e32173a67e849aa5a462e9f5466b872e4117f9a8a7df1972b2a136",
+    watchdog: "ghcr.io/coalesce-labs/catalyst-deadline-watchdog@sha256:63a9b20c3be3dc3ea328d77aa68dece942a40be46cb3126d9a7868e082828feb",
+    runner: "ghcr.io/coalesce-labs/catalyst-runner@sha256:a19f7b0859a9814740935f7aadd8fe5c5c9c5974f9a5956a057b983ada16ea01",
 };
 const IMAGE_REF = /^[a-z0-9][a-z0-9._:/-]{0,255}@sha256:[0-9a-f]{64}$/;
 const HOST_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/;
@@ -42,7 +43,7 @@ const CUSTODY_KEYS = [
     "CATALYST_THOUGHTS_CUSTODY_RESPONSES_DIR",
 ];
 /** A persisted authority selects bindings, never substitutes for a fresh native proof. */
-function persistedCustody(dir, values) {
+export function persistedCustody(dir, values) {
     const present = CUSTODY_KEYS.map(key => values?.[key] ?? "");
     if (present.every(value => !value))
         return "absent";
@@ -70,7 +71,8 @@ const DISK_POLICY_KEYS = [
 function isUnenrolled(value) {
     return value !== null && "unenrolled" in value;
 }
-const spawnDocker = (args, options) => new Promise((resolve, reject) => {
+/** The docker CLI as a child process. Exported for `catalyst runner update`. */
+export const spawnDocker = (args, options) => new Promise((resolve, reject) => {
     const child = spawn("docker", args, {
         env: options.env,
         cwd: options.cwd,
@@ -103,6 +105,23 @@ function composeErrorText(raw) {
     const text = (errors.length > 0 ? errors : lines).slice(0, 3).join(" | ").slice(0, 480);
     return text !== "" ? text : undefined;
 }
+/** The Compose arguments for the installation in `dir`, with the Darwin custody file when its
+ * persisted authority is installed. Null when that authority is only partly present. */
+export function runnerComposeArgs(dir) {
+    const custody = persistedCustody(dir, readEnvFile(join(dir, ".env")));
+    if (custody === "invalid")
+        return null;
+    return [
+        "compose",
+        "--project-name",
+        RUNNER_PROJECT,
+        "--file",
+        join(dir, "compose.yaml"),
+        ...(custody === "installed" ? ["--file", join(dir, "compose.darwin-thoughts.yaml")] : []),
+        "--env-file",
+        join(dir, ".env"),
+    ];
+}
 /** The real engine, through the docker CLI. Compose reads `.env` only: the caller's CATALYST_ and
  * DOCKER_SOCKET_ variables are removed, because Compose prefers an exported value over the file. */
 export function dockerRunnerEngine(deps = {}) {
@@ -116,21 +135,7 @@ export function dockerRunnerEngine(deps = {}) {
             return { code: 1, stdout: "" };
         }
     };
-    const compose = (dir) => {
-        const custody = persistedCustody(dir, readEnvFile(join(dir, ".env")));
-        if (custody === "invalid")
-            return null;
-        return [
-            "compose",
-            "--project-name",
-            RUNNER_PROJECT,
-            "--file",
-            join(dir, "compose.yaml"),
-            ...(custody === "installed" ? ["--file", join(dir, "compose.darwin-thoughts.yaml")] : []),
-            "--env-file",
-            join(dir, ".env"),
-        ];
-    };
+    const compose = runnerComposeArgs;
     const supervisorShell = (dir, script) => {
         const files = compose(dir);
         if (!files)
@@ -583,7 +588,7 @@ function parseHosts(body) {
     return parsed;
 }
 /** `KEY=value` lines; a single-quoted value is unquoted. Anything else is ignored. */
-function readEnvFile(path) {
+export function readEnvFile(path) {
     let text;
     try {
         text = readFileSync(path, "utf8");
@@ -591,6 +596,10 @@ function readEnvFile(path) {
     catch {
         return null;
     }
+    return parseEnvText(text);
+}
+/** `KEY=value` lines of `.env` text, as readEnvFile reads them. */
+export function parseEnvText(text) {
     const values = {};
     for (const line of text.split("\n")) {
         const match = /^([A-Z][A-Z0-9_]*)=(.*)$/.exec(line);
@@ -1176,6 +1185,14 @@ export function onboardRunnerAdapter(input = {}) {
                 return { state: "failed", reason: "runner_compose_failed", evidence: { ...selected,
                         project: RUNNER_PROJECT, ...(up.error ? { composeError: up.error } : {}) } };
             acted = true;
+            if (input.autoUpdate) {
+                try {
+                    input.message?.(input.autoUpdate(p.dir));
+                }
+                catch {
+                    input.message?.("Automatic runner updates could not be turned on. Run catalyst runner auto-update on to try again.");
+                }
+            }
             return { state: "done" };
         },
     };

package/dist/onboard-runtime.js

@@ -27,6 +27,7 @@ import { guardOnboardCapabilities, } from "./onboard-capabilities.js";
 import { onboardSettingsAdapter, } from "./onboard-settings.js";
 import { TIMED_OUT_REASONS } from "./setup-onboard-copy.js";
 import { fetchMe } from "./transport.js";
+import { enableRunnerAutoUpdate } from "./runner-command.js";
 const HOLD_ON_TIMEOUT = [
     "linear.workspace",
     "linear.personal",
@@ -334,6 +335,7 @@ export function createOnboardRuntime(args, ctx, hooks) {
                 : undefined,
             sleep: hooks.sleep,
             message: (text) => (hooks.ui ? hooks.ui.message(text) : ctx.stderr(text)),
+            autoUpdate: hooks.runnerAutoUpdate ?? (hooks.runnerEngine ? undefined : (dir) => enableRunnerAutoUpdate(ctx, dir)),
         }),
         "linear.adopt": onboardWorkflowVerificationAdapter({
             message: (text) => (hooks.ui ? hooks.ui.message(text) : ctx.stderr(text)),

package/dist/runner-auto-update.js

@@ -0,0 +1,176 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+// The schedule that runs `catalyst runner update --auto` every 15 minutes (CTC-4646): a LaunchAgent
+// on macOS, a systemd user timer on Linux. It runs as the person who set the runner up, with the
+// docker command they use, and only ever calls this CLI. Turning it off removes exactly these files.
+export const AUTO_UPDATE_LABEL = "dev.catalystcloud.runner-update";
+export const AUTO_UPDATE_UNIT = "catalyst-runner-update";
+export const AUTO_UPDATE_INTERVAL_SECONDS = 900;
+/** The minutes past each hour the macOS schedule runs at: every 15 minutes. */
+const CALENDAR_MINUTES = [0, 15, 30, 45];
+/** `su` and many ssh sessions leave XDG_RUNTIME_DIR unset, so `systemctl --user` cannot find a
+ *  running user manager. Its socket is at /run/user/<uid>; use that when it exists. */
+function schedulerEnv() {
+    const uid = process.getuid?.();
+    const runtime = uid === undefined ? undefined : `/run/user/${uid}`;
+    return !process.env.XDG_RUNTIME_DIR && runtime && existsSync(runtime)
+        ? { ...process.env, XDG_RUNTIME_DIR: runtime }
+        : process.env;
+}
+const defaultRun = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 15_000, env: schedulerEnv() });
+    return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.error ? r.error.message : (r.stderr ?? "") };
+};
+const xml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+/** systemd's own quoting for one ExecStart/Environment word. */
+const unitWord = (value) => `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "%%")}"`;
+export function launchAgentPath(home) {
+    return join(home, "Library", "LaunchAgents", `${AUTO_UPDATE_LABEL}.plist`);
+}
+export function systemdUnitPaths(home) {
+    const base = join(home, ".config", "systemd", "user");
+    return { service: join(base, `${AUTO_UPDATE_UNIT}.service`), timer: join(base, `${AUTO_UPDATE_UNIT}.timer`) };
+}
+export function launchAgentPlist(deps, dir) {
+    const args = [deps.cli, "runner", "update", "--auto", "--dir", dir];
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0"><dict>',
+        `<key>Label</key><string>${AUTO_UPDATE_LABEL}</string>`,
+        `<key>ProgramArguments</key><array>${args.map((a) => `<string>${xml(a)}</string>`).join("")}</array>`,
+        `<key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(deps.path)}</string><key>HOME</key><string>${xml(deps.home)}</string></dict>`,
+        // A calendar schedule, not StartInterval: on a busy Mac launchd held a StartInterval job as
+        // "pended nondemand spawn" for hours (mini-2, 2026-10-17), and RunAtLoad was pended the same
+        // way. The calendar entries fired on time on that same machine.
+        `<key>StartCalendarInterval</key><array>${CALENDAR_MINUTES.map((m) => `<dict><key>Minute</key><integer>${m}</integer></dict>`).join("")}</array>`,
+        "<key>ProcessType</key><string>Standard</string>",
+        `<key>StandardOutPath</key><string>${xml(join(dir, "update.log"))}</string>`,
+        `<key>StandardErrorPath</key><string>${xml(join(dir, "update.log"))}</string>`,
+        "</dict></plist>",
+        "",
+    ].join("\n");
+}
+export function systemdUnits(deps, dir) {
+    return {
+        service: [
+            "[Unit]",
+            "Description=Catalyst runner update",
+            "",
+            "[Service]",
+            "Type=oneshot",
+            `Environment=${unitWord(`PATH=${deps.path}`)}`,
+            `ExecStart=${[deps.cli, "runner", "update", "--auto", "--dir", dir].map(unitWord).join(" ")}`,
+            "",
+        ].join("\n"),
+        timer: [
+            "[Unit]",
+            "Description=Check for an approved Catalyst runner release every 15 minutes",
+            "",
+            "[Timer]",
+            // Wall-clock, not OnBootSec/OnUnitActiveSec: those are relative to boot and to the last run in
+            // THIS user manager, so a manager that restarts without a reboot (enabling linger, a logout and
+            // login) left the timer "elapsed" with no next run, forever (fresh Ubuntu 24.04, 2026-10-17).
+            `OnCalendar=*:0/${AUTO_UPDATE_INTERVAL_SECONDS / 60}`,
+            "RandomizedDelaySec=60",
+            "Persistent=true",
+            "",
+            "[Install]",
+            "WantedBy=timers.target",
+            "",
+        ].join("\n"),
+    };
+}
+function writeFileAtomic(path, text) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.${process.pid}.tmp`;
+    writeFileSync(temp, text, { mode: 0o644 });
+    renameSync(temp, path);
+}
+export function autoUpdateStatus(deps) {
+    const platform = deps.platform ?? process.platform;
+    const run = deps.run ?? defaultRun;
+    if (platform === "darwin") {
+        const path = launchAgentPath(deps.home);
+        if (!existsSync(path))
+            return { state: "off", detail: "no_launch_agent" };
+        const loaded = run("launchctl", ["print", `gui/${deps.uid ?? process.getuid?.() ?? 0}/${AUTO_UPDATE_LABEL}`]).status === 0;
+        return loaded ? { state: "on", detail: "launch_agent_loaded", path } : { state: "off", detail: "launch_agent_not_loaded" };
+    }
+    if (platform === "linux") {
+        const { timer } = systemdUnitPaths(deps.home);
+        if (!existsSync(timer))
+            return { state: "off", detail: "no_timer" };
+        const enabled = run("systemctl", ["--user", "is-enabled", `${AUTO_UPDATE_UNIT}.timer`]);
+        return enabled.status === 0 ? { state: "on", detail: "timer_enabled", path: timer } : { state: "off", detail: "timer_not_enabled" };
+    }
+    return { state: "unsupported", detail: `platform_${platform}` };
+}
+/** Install and start the schedule. Rewrites the files every time, so a moved CLI or PATH is picked up. */
+export function enableAutoUpdate(deps, dir) {
+    const platform = deps.platform ?? process.platform;
+    const run = deps.run ?? defaultRun;
+    if (platform === "darwin") {
+        const uid = deps.uid ?? process.getuid?.() ?? 0;
+        const path = launchAgentPath(deps.home);
+        const text = launchAgentPlist(deps, dir);
+        const unchanged = existsSync(path) && readFileSync(path, "utf8") === text;
+        const domain = `gui/${uid}`;
+        const loaded = run("launchctl", ["print", `${domain}/${AUTO_UPDATE_LABEL}`]).status === 0;
+        if (unchanged && loaded)
+            return { state: "on", detail: "launch_agent_loaded", path };
+        if (loaded)
+            run("launchctl", ["bootout", `${domain}/${AUTO_UPDATE_LABEL}`]);
+        writeFileAtomic(path, text);
+        const boot = run("launchctl", ["bootstrap", domain, path]);
+        return boot.status === 0
+            ? { state: "on", detail: "launch_agent_loaded", path }
+            : { state: "off", detail: `launchctl_bootstrap_failed:${boot.stderr.trim().slice(0, 160)}` };
+    }
+    if (platform === "linux") {
+        if (run("systemctl", ["--user", "show-environment"]).status !== 0)
+            return { state: "unsupported", detail: "no_systemd_user_manager" };
+        const paths = systemdUnitPaths(deps.home);
+        const units = systemdUnits(deps, dir);
+        writeFileAtomic(paths.service, units.service);
+        writeFileAtomic(paths.timer, units.timer);
+        run("systemctl", ["--user", "daemon-reload"]);
+        const enabled = run("systemctl", ["--user", "enable", "--now", `${AUTO_UPDATE_UNIT}.timer`]);
+        if (enabled.status !== 0)
+            return { state: "off", detail: `systemctl_enable_failed:${enabled.stderr.trim().slice(0, 160)}` };
+        // Without lingering, a user timer stops when this person logs out of a headless machine.
+        const linger = run("loginctl", ["show-user", String(deps.uid ?? process.getuid?.() ?? 0), "--property=Linger"]);
+        return { state: "on", detail: /Linger=yes/.test(linger.stdout) ? "timer_enabled" : "timer_enabled_without_linger", path: paths.timer };
+    }
+    return { state: "unsupported", detail: `platform_${platform}` };
+}
+/** Stop and remove the schedule's own files. Nothing else. */
+export function disableAutoUpdate(deps) {
+    const platform = deps.platform ?? process.platform;
+    const run = deps.run ?? defaultRun;
+    if (platform === "darwin") {
+        const uid = deps.uid ?? process.getuid?.() ?? 0;
+        run("launchctl", ["bootout", `gui/${uid}/${AUTO_UPDATE_LABEL}`]);
+        const path = launchAgentPath(deps.home);
+        if (existsSync(path))
+            unlinkSync(path);
+        return { state: "off", detail: "launch_agent_removed" };
+    }
+    if (platform === "linux") {
+        run("systemctl", ["--user", "disable", "--now", `${AUTO_UPDATE_UNIT}.timer`]);
+        const paths = systemdUnitPaths(deps.home);
+        for (const path of [paths.timer, paths.service])
+            if (existsSync(path))
+                unlinkSync(path);
+        run("systemctl", ["--user", "daemon-reload"]);
+        return { state: "off", detail: "timer_removed" };
+    }
+    return { state: "unsupported", detail: `platform_${platform}` };
+}
+/** PATH for the scheduled run: the CLI's and node's directories first, then the usual docker homes. */
+export function scheduledPath(cli, nodeExecutable, current) {
+    const dirs = [dirname(cli), dirname(nodeExecutable), "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin",
+        ...(current ?? "").split(":")];
+    return [...new Set(dirs.filter((d) => d.startsWith("/")))].join(":");
+}

package/dist/runner-command.js

@@ -0,0 +1,73 @@
+import { isAbsolute, resolve } from "node:path";
+import { flagBool, flagString, positionals } from "./args.js";
+import { UsageError } from "./errors.js";
+import { autoUpdateStatus, disableAutoUpdate, enableAutoUpdate, scheduledPath, } from "./runner-auto-update.js";
+import { dockerRunnerUpdateEngine, readReleaseState, runnerDir, runRunnerUpdate, updateResultLines, } from "./runner-update.js";
+const USAGE = "catalyst runner update [--check] [--dir <runner directory>] | runner auto-update [status|on|off]";
+function schedulerDeps(ctx, deps) {
+    const cli = deps.scheduler?.cli ?? resolve(process.argv[1] ?? "catalyst");
+    return {
+        home: ctx.home,
+        cli,
+        path: scheduledPath(cli, process.execPath, ctx.env.PATH),
+        ...deps.scheduler,
+    };
+}
+function statusLine(status) {
+    if (status.state === "on")
+        return status.detail === "timer_enabled_without_linger"
+            ? "Automatic runner updates are on, every 15 minutes while you are logged in. To keep them running after you log out, run: sudo loginctl enable-linger $USER"
+            : "Automatic runner updates are on: this machine checks for an approved release every 15 minutes.";
+    if (status.state === "off")
+        return `Automatic runner updates are off (${status.detail}). Turn them on with: catalyst runner auto-update on`;
+    if (status.detail === "no_systemd_user_manager")
+        return "Automatic runner updates need your systemd user manager, which is not running for you. Run: sudo loginctl enable-linger $USER, then catalyst runner auto-update on";
+    return `Automatic runner updates are not available on this machine (${status.detail}). Run catalyst runner update yourself.`;
+}
+/** Setup's call: turn the schedule on for `dir` and say what happened in one line. */
+export function enableRunnerAutoUpdate(ctx, dir) {
+    return statusLine(enableAutoUpdate(schedulerDeps(ctx, {}), dir));
+}
+export async function cmdRunner(args, ctx, deps = {}) {
+    const parts = positionals(args);
+    const action = parts[0];
+    const dirFlag = flagString(args, "dir");
+    if (dirFlag !== undefined && !isAbsolute(dirFlag))
+        throw new UsageError("--dir must be an absolute path");
+    const dir = () => dirFlag ?? runnerDir(ctx);
+    if (action === "update" && parts.length === 1) {
+        const check = flagBool(args, "check");
+        const auto = flagBool(args, "auto");
+        const engine = deps.engine ?? dockerRunnerUpdateEngine({ env: ctx.env });
+        const result = await runRunnerUpdate(engine, { dir: dir(), check });
+        if (args.json)
+            ctx.stdout(JSON.stringify(result));
+        else if (auto)
+            ctx.stdout(`${ctx.now().toISOString()} ${result.outcome} ${result.detail} generation=${result.generation ?? "none"}`);
+        else
+            for (const line of updateResultLines(result))
+                ctx.stdout(line);
+        return result.exitCode;
+    }
+    if (action === "auto-update" && parts.length <= 2) {
+        const mode = parts[1] ?? "status";
+        const scheduler = schedulerDeps(ctx, deps);
+        let status;
+        if (mode === "on")
+            status = enableAutoUpdate(scheduler, dir());
+        else if (mode === "off")
+            status = disableAutoUpdate(scheduler);
+        else if (mode === "status")
+            status = autoUpdateStatus(scheduler);
+        else
+            throw new UsageError(USAGE);
+        if (args.json) {
+            const state = mode === "status" && dirFlag !== undefined ? readReleaseState(dirFlag) : undefined;
+            ctx.stdout(JSON.stringify({ ...status, ...(state ? { release: state } : {}) }));
+        }
+        else
+            ctx.stdout(statusLine(status));
+        return status.state === "on" || mode !== "on" ? 0 : 1;
+    }
+    throw new UsageError(USAGE);
+}

package/dist/runner-update.js

@@ -0,0 +1,506 @@
+import { closeSync, existsSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CliError } from "./errors.js";
+import { onboardStateRoot } from "./onboard.js";
+import { dockerRunnerEngine, parseEnvText, persistedCustody, prepareRunnerImages, readEnvFile, runnerComposeArgs, spawnDocker, } from "./onboard-runner.js";
+// `catalyst runner update`: move this machine's self-hosted runner to the release Catalyst approved
+// (CTC-4646). The cloud names one approved runner, supervisor and watchdog by immutable digest with
+// a monotonic generation (catalyst-cloud CTC-5926, GET /api/v1/hosts/desired-release, read with the
+// host's own credential). This command reads it from inside a one-off supervisor container, so the
+// host secret never leaves Docker, then moves only when every check passes:
+//
+//   - the release parses strictly: three digests from the three Catalyst repositories, never a
+//     tag or `latest`, and a generation newer than the one this machine last applied;
+//   - no phase container exists for this host;
+//   - all three images are pulled by digest, natively for this engine, before anything changes;
+//   - on a Mac with private thoughts storage, that storage is re-attested on the new supervisor;
+//   - with the supervisor stopped, so it admits no new work, there is still no phase container.
+//     If one started in between, the supervisor comes back as it was and the update waits.
+//
+// Then it rewrites the three image lines in `.env`, keeps the previous file beside it, and runs
+// `docker compose up`. The release counts as applied only when the running containers are its
+// images and the supervisor logged `host_ready` since it started; a `.env` that already names the
+// release is reconciled the same way, never trusted. Otherwise it restores the previous file, the
+// thoughts storage attestation and the previous images. The outcome is kept in
+// `release-state.json` for `--check` and status readers.
+export const RELEASE_STATE_FILE = "release-state.json";
+export const PREVIOUS_ENV_FILE = ".env.release-previous";
+const LOCK_FILE = "update.lock";
+const READY_DEADLINE_MS = 5 * 60_000;
+const READY_POLL_MS = 5_000;
+const ATTEMPT_HOST_LABEL = "dev.catalystcloud.attempt.host-id";
+const DESIRED_RELEASE_PATH = "/api/v1/hosts/desired-release";
+export const RELEASE_COMPONENTS = ["runner", "supervisor", "watchdog"];
+/** The only repositories a release may name, exactly as catalyst-cloud's HOST_RELEASE_REPOSITORIES. */
+export const RELEASE_REPOSITORIES = {
+    runner: "ghcr.io/coalesce-labs/catalyst-runner",
+    supervisor: "ghcr.io/coalesce-labs/catalyst-supervisor",
+    watchdog: "ghcr.io/coalesce-labs/catalyst-deadline-watchdog",
+};
+export const RELEASE_ENV_KEYS = {
+    runner: "CATALYST_RUNNER_IMAGE",
+    supervisor: "CATALYST_SUPERVISOR_IMAGE",
+    watchdog: "CATALYST_WATCHDOG_IMAGE",
+};
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const posInt = (value) => typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const SHA40 = /^[0-9a-f]{40}$/;
+/** A reference this machine may pull for `component`: its repository, at a digest, with no tag. */
+export function releaseReference(component, value) {
+    if (typeof value !== "string" || value.length > 300)
+        return null;
+    const at = value.indexOf("@");
+    if (at === -1 || value.slice(0, at) !== RELEASE_REPOSITORIES[component])
+        return null;
+    return DIGEST.test(value.slice(at + 1)) ? value : null;
+}
+const shortDigest = (reference) => reference.slice(reference.indexOf("@sha256:") + 8).slice(0, 16);
+/** The host-readable release, parsed as strictly as catalyst-cloud's parseHostDesiredRelease. */
+export function parseDesiredRelease(input) {
+    if (!isRecord(input) || input.version !== 1)
+        return null;
+    if (typeof input.releaseId !== "string" || !posInt(input.generation) || !posInt(input.approvedAtMs))
+        return null;
+    const images = {};
+    for (const component of RELEASE_COMPONENTS) {
+        const value = input[component];
+        if (!isRecord(value))
+            return null;
+        const reference = releaseReference(component, value.reference);
+        if (!reference || value.digest !== reference.slice(reference.indexOf("@") + 1))
+            return null;
+        if (typeof value.sourceSha !== "string" || !SHA40.test(value.sourceSha))
+            return null;
+        const tag = `${RELEASE_REPOSITORIES[component]}:${value.sourceSha}${component === "runner" ? "-multiarch" : ""}`;
+        if (value.tag !== tag)
+            return null;
+        images[component] = { reference, sourceSha: value.sourceSha };
+    }
+    const id = `hr-${shortDigest(images.runner.reference)}-${shortDigest(images.supervisor.reference)}-${shortDigest(images.watchdog.reference)}`;
+    if (input.releaseId !== id)
+        return null;
+    return { releaseId: id, generation: input.generation, approvedAtMs: input.approvedAtMs, images };
+}
+/** Whether to move. Every answer except a valid, strictly newer generation keeps the current images. */
+export function decideRelease(appliedGeneration, read) {
+    const retain = (reason, terminal = false) => ({ action: "retain", reason, terminal });
+    if (read.kind === "no_credential")
+        return retain("no_credential");
+    if (read.kind === "unreachable")
+        return retain("read_unreachable");
+    if (read.status === 401 || read.status === 403)
+        return retain("credential_refused", isRecord(read.body) && read.body.refusal === "host_revoked" && read.body.terminal === true);
+    if (read.status !== 200)
+        return retain("release_unavailable");
+    const release = parseDesiredRelease(isRecord(read.body) && read.body.ok === true ? read.body.release : null);
+    if (!release)
+        return retain("response_invalid");
+    if (appliedGeneration !== null && release.generation < appliedGeneration)
+        return retain("not_newer");
+    if (appliedGeneration !== null && release.generation === appliedGeneration)
+        return { action: "verify", release };
+    return { action: "update", release };
+}
+export function readReleaseState(dir) {
+    const empty = { version: 1, generation: null, releaseId: null, appliedAtMs: null, previous: null, last: null };
+    try {
+        const parsed = JSON.parse(readFileSync(join(dir, RELEASE_STATE_FILE), "utf8"));
+        if (!isRecord(parsed) || parsed.version !== 1)
+            return empty;
+        return {
+            ...empty,
+            generation: posInt(parsed.generation) ? parsed.generation : null,
+            releaseId: typeof parsed.releaseId === "string" ? parsed.releaseId : null,
+            appliedAtMs: posInt(parsed.appliedAtMs) ? parsed.appliedAtMs : null,
+            previous: isRecord(parsed.previous) ? parsed.previous : null,
+            last: isRecord(parsed.last) ? parsed.last : null,
+        };
+    }
+    catch {
+        return empty;
+    }
+}
+/** Write a private file by rename, so a reader never sees half of it. */
+function writePrivateAtomic(path, text) {
+    const temp = `${path}.${process.pid}.tmp`;
+    writeFileSync(temp, text, { mode: 0o600 });
+    renameSync(temp, path);
+}
+function writeReleaseState(dir, state) {
+    writePrivateAtomic(join(dir, RELEASE_STATE_FILE), `${JSON.stringify(state, null, 2)}\n`);
+}
+/** `.env` with each `KEY=` line for `values` replaced in place (or appended), every other line kept. */
+export function rewriteEnvText(text, values) {
+    const pending = new Map(Object.entries(values));
+    const lines = text.split("\n").map((line) => {
+        const key = /^([A-Z][A-Z0-9_]*)=/.exec(line)?.[1];
+        if (key === undefined || !pending.has(key))
+            return line;
+        const value = pending.get(key);
+        pending.delete(key);
+        return `${key}=${value}`;
+    });
+    if (pending.size > 0) {
+        if (lines.length > 0 && lines[lines.length - 1] === "")
+            lines.pop();
+        for (const [key, value] of pending)
+            lines.push(`${key}=${value}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/** One serialized update run. A second concurrent run returns `retained` with `update_running`. */
+export async function runRunnerUpdate(engine, options) {
+    const { dir } = options;
+    const now = options.now ?? Date.now;
+    const envPath = join(dir, ".env");
+    if (!existsSync(envPath) || !existsSync(join(dir, "compose.yaml")))
+        return { outcome: "failed", detail: "runner_not_installed", generation: null, exitCode: 1 };
+    const lock = options.check ? null : takeLock(dir, now());
+    if (!options.check && lock === null)
+        return { outcome: "retained", detail: "update_running", generation: readReleaseState(dir).generation, exitCode: 0 };
+    try {
+        const result = await update(engine, options, now);
+        if (!options.check) {
+            const state = readReleaseState(dir);
+            writeReleaseState(dir, { ...state, last: { atMs: now(), outcome: result.outcome, detail: result.detail, generation: result.generation } });
+        }
+        return result;
+    }
+    finally {
+        if (lock !== null)
+            releaseLock(dir, lock);
+    }
+}
+const imagesOf = (env) => Object.fromEntries(RELEASE_COMPONENTS.map((c) => [c, env[RELEASE_ENV_KEYS[c]] ?? ""]));
+/** The running containers are these images, and the supervisor reported ready since it started. */
+async function running(engine, dir, images, signal) {
+    const live = await engine.services(dir, signal);
+    if (!live?.supervisor?.running || live.supervisor.image !== images.supervisor)
+        return false;
+    if (!live.watchdog?.running || live.watchdog.image !== images.watchdog)
+        return false;
+    return engine.supervisorReadySinceStart(dir, signal);
+}
+async function update(engine, options, now) {
+    const { dir, signal } = options;
+    const envPath = join(dir, ".env");
+    const state = readReleaseState(dir);
+    const done = (outcome, detail, extra = {}) => ({ outcome, detail, generation: state.generation, exitCode: 0, ...extra });
+    const read = await engine.desiredRelease(dir, signal);
+    const decision = decideRelease(state.generation, read);
+    if (decision.action === "retain")
+        return decision.reason === "not_newer"
+            ? done("current", "not_newer")
+            : done("retained", decision.reason, { exitCode: decision.reason === "credential_refused" || decision.reason === "no_credential" ? 1 : 0 });
+    const { release } = decision;
+    const target = Object.fromEntries(RELEASE_COMPONENTS.map((c) => [c, release.images[c].reference]));
+    const envText = readFileSync(envPath, "utf8");
+    const env = readEnvFile(envPath) ?? {};
+    const current = imagesOf(env);
+    const changed = RELEASE_COMPONENTS.filter((c) => current[c] !== target[c]);
+    // Already on this generation: cheap check that `.env` and the running containers are its images
+    // (no log read). A match is current; any drift is moved back below like any other update.
+    if (decision.action === "verify" && changed.length === 0) {
+        const live = await engine.services(dir, signal);
+        if (live?.supervisor?.running && live.supervisor.image === target.supervisor && live.watchdog?.image === target.watchdog)
+            return done("current", "not_newer");
+    }
+    const tagged = { releaseId: release.releaseId };
+    const record = (outcome, detail, previous) => {
+        writeReleaseState(dir, { ...state, generation: release.generation, releaseId: release.releaseId, appliedAtMs: now(), previous });
+        return { outcome, detail, generation: release.generation, exitCode: 0, ...tagged };
+    };
+    if (options.check)
+        return done("planned", changed.length > 0 ? `would_update:${changed.join(",")}` : "already_configured", { ...tagged, generation: release.generation });
+    // `.env` naming the release proves nothing on its own: an earlier run may have stopped after writing
+    // it. Only the running containers, ready, prove the release is applied.
+    if (changed.length === 0 && (await running(engine, dir, target, signal)))
+        return record("recorded", "already_running_release", state.previous);
+    // What a failure goes back to: today's file, or for a half-applied file the one saved before it.
+    let rollbackText = envText;
+    if (changed.length === 0) {
+        try {
+            rollbackText = readFileSync(join(dir, PREVIOUS_ENV_FILE), "utf8");
+        }
+        catch {
+            rollbackText = null;
+        }
+    }
+    const rollbackImages = rollbackText === null ? null : imagesOf(parseEnvText(rollbackText));
+    const hostId = read.kind === "answered" ? read.hostId : "";
+    const busy = await engine.attemptContainers(dir, hostId, signal);
+    if (busy === null)
+        return done("retained", "docker_unavailable");
+    if (busy > 0)
+        return done("deferred_busy", `attempt_containers:${busy}`, tagged);
+    const unprepared = await engine.prepare(RELEASE_COMPONENTS.map((c) => target[c]), signal);
+    if (unprepared !== null)
+        return done("retained", unprepared, tagged);
+    // Mac private thoughts storage records the supervisor image its helper runs. Every path that does
+    // not end on the new release attests it back onto the images the machine keeps.
+    const custodyInstalled = persistedCustody(dir, env) === "installed";
+    const restoreCustody = async (images) => !custodyInstalled || images === null || (await engine.custody(dir, images, signal)) === env.CATALYST_THOUGHTS_CUSTODY_AUTHORITY;
+    if (custodyInstalled) {
+        const authority = await engine.custody(dir, target, signal);
+        // Re-attestation keeps the installed authority. A different one would need setup, not an update.
+        if (authority === null || authority !== env.CATALYST_THOUGHTS_CUSTODY_AUTHORITY) {
+            const restored = await restoreCustody(rollbackImages ?? current);
+            return done(restored ? "retained" : "failed", restored ? "custody_reattest_failed" : "custody_restore_failed", { ...tagged, exitCode: restored ? 0 : 1 });
+        }
+    }
+    // The boundary between phases: stop the supervisor so it admits nothing, then look again. A phase
+    // that started since the first look keeps running, the supervisor comes back, and the update waits.
+    if (!(await engine.stopSupervisor(dir, signal))) {
+        await engine.composeUp(dir, signal);
+        await restoreCustody(rollbackImages ?? current);
+        return done("retained", "supervisor_stop_failed", tagged);
+    }
+    const busyAfterStop = await engine.attemptContainers(dir, hostId, signal);
+    if (busyAfterStop !== 0) {
+        await engine.composeUp(dir, signal);
+        await restoreCustody(rollbackImages ?? current);
+        return busyAfterStop === null
+            ? done("retained", "docker_unavailable", tagged)
+            : done("deferred_busy", `attempt_containers:${busyAfterStop}`, tagged);
+    }
+    // From here the machine changes. The previous file is the rollback.
+    if (changed.length > 0)
+        writePrivateAtomic(join(dir, PREVIOUS_ENV_FILE), envText);
+    writePrivateAtomic(envPath, rewriteEnvText(envText, Object.fromEntries(RELEASE_COMPONENTS.map((c) => [RELEASE_ENV_KEYS[c], target[c]]))));
+    if ((await engine.composeUp(dir, signal)) && (await waitReady(engine, dir, target, options, now))) {
+        // Only once the new release is running and ready: the replaced images free their disk (a runner
+        // image is several GB, against a free-space floor that decides whether the machine takes work).
+        // A rollback or failure never reaches here, so the previous images stay for it.
+        if (changed.length > 0)
+            await engine.removeImages(changed.map((c) => current[c]).filter((ref) => ref !== ""), signal);
+        return record("updated", changed.length > 0 ? `updated:${changed.join(",")}` : "reconciled", changed.length > 0 ? current : state.previous);
+    }
+    if (rollbackText === null || rollbackImages === null)
+        return done("failed", "new_supervisor_not_ready_no_previous", { ...tagged, exitCode: 1 });
+    writePrivateAtomic(envPath, rollbackText);
+    const custodyBack = await restoreCustody(rollbackImages);
+    const restored = (await engine.composeUp(dir, signal)) && (await waitReady(engine, dir, rollbackImages, options, now));
+    return done(restored && custodyBack ? "rolled_back" : "failed", !restored ? "rollback_not_ready" : custodyBack ? "new_supervisor_not_ready" : "custody_restore_failed", { ...tagged, exitCode: 1 });
+}
+async function waitReady(engine, dir, images, options, now) {
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const deadline = now() + (options.readyDeadlineMs ?? READY_DEADLINE_MS);
+    for (;;) {
+        if (options.signal?.aborted)
+            return false;
+        if (await running(engine, dir, images, options.signal))
+            return true;
+        if (now() >= deadline)
+            return false;
+        await sleep(READY_POLL_MS);
+    }
+}
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: the process exists but belongs to someone else.
+        return error.code === "EPERM";
+    }
+};
+/** An exclusive lock file holding the owner's pid. It is taken over only when that process is gone,
+ *  never by age: one run can legitimately take longer than any fixed limit (three image pulls). */
+function takeLock(dir, nowMs) {
+    const path = join(dir, LOCK_FILE);
+    const token = `${process.pid} ${nowMs}\n`;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(path, "wx", 0o600);
+            writeFileSync(fd, token);
+            closeSync(fd);
+            return token;
+        }
+        catch {
+            try {
+                const owner = Number(readFileSync(path, "utf8").split(" ")[0]);
+                if (Number.isSafeInteger(owner) && owner > 0 && alive(owner))
+                    return null;
+                unlinkSync(path);
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+function releaseLock(dir, token) {
+    const path = join(dir, LOCK_FILE);
+    try {
+        if (readFileSync(path, "utf8") === token)
+            unlinkSync(path);
+    }
+    catch {
+        // Already gone.
+    }
+}
+/** Runs inside the supervisor image with its own environment. Prints one JSON object, never the
+ *  secret: the bearer is built and sent from inside the container. */
+const DESIRED_RELEASE_SCRIPT = `(async () => {
+  const out = (v) => process.stdout.write(JSON.stringify(v));
+  let state;
+  try { state = JSON.parse(require("node:fs").readFileSync(process.env.CATALYST_HOST_CREDENTIAL_FILE, "utf8")); }
+  catch { return out({ kind: "no_credential" }); }
+  const e = state && state.enrollment;
+  const base = process.env.CATALYST_MIRROR_URL;
+  if (!state || state.version !== 1 || typeof state.secret !== "string" || !e ||
+      typeof e.tenant !== "string" || typeof e.hostId !== "string" || !base) return out({ kind: "no_credential" });
+  const tenant = Buffer.from(e.tenant, "utf8").toString("base64url");
+  try {
+    const response = await fetch(new URL(${JSON.stringify(DESIRED_RELEASE_PATH)}, base).href, {
+      redirect: "error", signal: AbortSignal.timeout(15000),
+      headers: { authorization: "Bearer ctc_host_" + tenant + "." + e.hostId + "." + state.secret, accept: "application/json" },
+    });
+    let body = null;
+    try { body = await response.json(); } catch {}
+    out({ kind: "answered", status: response.status, body, hostId: e.hostId });
+  } catch (error) {
+    out({ kind: "unreachable", detail: String((error && error.name) || "fetch failed"), hostId: e.hostId });
+  }
+})();`;
+const HOST_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+/** The real engine: the docker CLI and the setup engine's own pull, custody and Compose steps. */
+export function dockerRunnerUpdateEngine(deps = {}) {
+    const exec = deps.exec ?? spawnDocker;
+    const env = Object.fromEntries(Object.entries(deps.env ?? process.env)
+        .filter(([key]) => !key.startsWith("CATALYST_") && !key.startsWith("DOCKER_SOCKET_")));
+    const setup = deps.setup ?? dockerRunnerEngine({ exec, env: deps.env });
+    const docker = async (args, options = {}) => {
+        try {
+            return await exec(args, { env, ...options });
+        }
+        catch {
+            return { code: 1, stdout: "" };
+        }
+    };
+    return {
+        async desiredRelease(dir, signal) {
+            const compose = runnerComposeArgs(dir);
+            if (!compose)
+                return { kind: "no_credential" };
+            const read = await docker([...compose, "run", "--rm", "-T", "--no-deps", "--entrypoint", "bun", "supervisor", "-e", DESIRED_RELEASE_SCRIPT], { cwd: dir, signal, timeoutMs: 120_000 });
+            if (read.code !== 0)
+                return { kind: "no_credential" };
+            try {
+                const parsed = JSON.parse(read.stdout);
+                if (!isRecord(parsed))
+                    return { kind: "no_credential" };
+                const hostId = typeof parsed.hostId === "string" && HOST_ID.test(parsed.hostId) ? parsed.hostId : null;
+                if (parsed.kind === "answered" && hostId && typeof parsed.status === "number")
+                    return { kind: "answered", status: parsed.status, body: parsed.body ?? null, hostId };
+                if (parsed.kind === "unreachable" && hostId)
+                    return { kind: "unreachable", detail: String(parsed.detail ?? "fetch failed").slice(0, 80), hostId };
+                return { kind: "no_credential" };
+            }
+            catch {
+                return { kind: "no_credential" };
+            }
+        },
+        async attemptContainers(_dir, hostId, signal) {
+            if (!HOST_ID.test(hostId))
+                return null;
+            const listed = await docker(["ps", "--all", "--quiet", "--filter", `label=${ATTEMPT_HOST_LABEL}=${hostId}`], { signal });
+            return listed.code === 0 ? listed.stdout.split("\n").filter((line) => line.trim() !== "").length : null;
+        },
+        async prepare(images, signal) {
+            const info = await setup.info(signal);
+            if (!info)
+                return "docker_unavailable";
+            const refused = await prepareRunnerImages(setup, images, info.arch, signal);
+            return refused === null ? null : `${refused.reason}${refused.image ? `:${refused.image}` : ""}`;
+        },
+        async custody(dir, images, signal) {
+            if (!setup.nativeThoughtsCustody)
+                return null;
+            try {
+                const result = await setup.nativeThoughtsCustody({ dir, supervisorImage: images.supervisor, runnerImage: images.runner }, signal);
+                return result.envAuthority;
+            }
+            catch {
+                return null;
+            }
+        },
+        async services(dir, signal) {
+            const compose = runnerComposeArgs(dir);
+            if (!compose)
+                return null;
+            const service = async (name) => {
+                const listed = await docker([...compose, "ps", "--all", "--quiet", name], { cwd: dir, signal });
+                if (listed.code !== 0)
+                    return undefined;
+                const id = listed.stdout.trim();
+                if (id === "")
+                    return null;
+                if (!/^[0-9a-f]{12,64}$/.test(id))
+                    return undefined;
+                const inspected = await docker(["inspect", "--format", "{{.State.Running}}|{{.Config.Image}}|{{.State.StartedAt}}", id], { signal });
+                const [isRunning, image, started] = inspected.stdout.trim().split("|");
+                const startedAtMs = Date.parse(started ?? "");
+                return inspected.code === 0 && image && Number.isFinite(startedAtMs)
+                    ? { running: isRunning === "true", image, startedAtMs } : undefined;
+            };
+            const [supervisor, watchdog] = [await service("supervisor"), await service("deadline-watchdog")];
+            return supervisor === undefined || watchdog === undefined ? null : { supervisor, watchdog };
+        },
+        async stopSupervisor(dir, signal) {
+            const compose = runnerComposeArgs(dir);
+            if (!compose)
+                return false;
+            return (await docker([...compose, "stop", "supervisor"], { cwd: dir, signal, timeoutMs: 120_000 })).code === 0;
+        },
+        async composeUp(dir, signal) {
+            return (await setup.composeUp(dir, signal)).ok;
+        },
+        async removeImages(images, signal) {
+            for (const ref of images)
+                await docker(["image", "rm", ref], { signal, timeoutMs: 120_000 });
+        },
+        async supervisorReadySinceStart(dir, signal) {
+            const compose = runnerComposeArgs(dir);
+            if (!compose)
+                return false;
+            const id = (await docker([...compose, "ps", "--quiet", "supervisor"], { cwd: dir, signal })).stdout.trim();
+            if (!/^[0-9a-f]{12,64}$/.test(id))
+                return false;
+            const started = (await docker(["inspect", "--format", "{{.State.StartedAt}}", id], { signal })).stdout.trim();
+            if (!Number.isFinite(Date.parse(started)))
+                return false;
+            const logs = await docker(["logs", "--since", started, id], { signal, timeoutMs: 30_000 });
+            return `${logs.stdout}\n${logs.stderr ?? ""}`.includes('"event":"host_ready"');
+        },
+    };
+}
+/** The runner directory setup uses. */
+export function runnerDir(ctx) {
+    try {
+        return join(onboardStateRoot(ctx.home, ctx.env), "runner");
+    }
+    catch {
+        throw new CliError("The runner directory could not be found. Run catalyst setup --runner first.", "runner_directory_unavailable", 1);
+    }
+}
+const OUTCOME_TEXT = {
+    current: "The runner is on the approved release.",
+    recorded: "The runner was already on the approved release; recorded it.",
+    updated: "The runner moved to the approved release.",
+    planned: "Checked the approved release; nothing was changed.",
+    deferred_busy: "A phase is running here, so the update waits for the next check.",
+    retained: "Kept the current images.",
+    rolled_back: "The new supervisor did not become ready, so the previous images were restored.",
+    failed: "The update could not finish. Look at the runner with docker compose ps.",
+};
+export function updateResultLines(result) {
+    return [
+        OUTCOME_TEXT[result.outcome],
+        `Release: ${result.releaseId ?? "none"}, generation ${result.generation ?? "none"} (${result.detail}).`,
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.16.16",
+  "version": "0.16.18",
   "description": "Set up Catalyst Cloud, check your tickets and manage your account from the command line.",
   "license": "MIT",
   "type": "module",

package/skills/catalyst-github/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's GitHub: show a ticket's pull request with its checks, reviews and review threads, say whether it is mergeable under this repository's policy, and explain what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). Use when someone asks "show me the PR", "what are the checks saying", "why hasn't it merged", "what does the queue need", "what does that label mean", or wants the branch and merge conventions Catalyst follows.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.16 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.18 — written in this repository for customer accounts -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-linear/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's view of Linear on the customer's own cloud account. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the cloud API by default, with local replica reads available as an explicit opt-in, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the account's agent proxy as the app actor, with every route, stage id, label id and marker read from the account's contract. Knows what a ticket accumulates as Catalyst works it (phase-outcome comments, the document per phase, the agent session, the labels, the single blocks relation, the bookkeeping marker, the eyes acknowledgement). Use when a person says "show me the ticket", "what did Catalyst write on it", "comment on it", "move it", "label it" or "file a ticket". Not for raising a decision for a human (what-needs-me) and not for pull requests (catalyst-github).
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.16 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.18 — written in this repository for customer accounts -->
 
 # Catalyst Linear
 

package/skills/catalyst-onboard/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Set up Catalyst Cloud and say whether setup is working. Walks a person from nothing to their first ticket running, one step at a time: the coding account, the project, the integrations and connected accounts, each repository's settings file, then one real ticket moving. Also logs this machine in, reads the readiness verdict with who can fix each failure, and checks the optional local replica. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", "log me in", "which account is this machine on", "am I set up", "what is missing", "why does nothing happen" or "is the replica running", when a login expired, or when a skill script exits 2 saying this machine is not connected. Does every step a key can do through the catalyst CLI, hands over the exact page for the steps only a browser can do, and never claims a step it did not watch succeed.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.16 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.18 — written in this repository for customer accounts -->
 
 # Onboard me
 

package/skills/run-this-project/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Own one Catalyst Cloud project end to end until it closes. Use when the person says "run this project for me", "own this until it ships", "keep this moving", or hands you a project id or a set of tickets to drive. Subscribes to the account's event stream for the scope through the catalyst CLI, reacts to each change in the same turn, makes tickets ready and moves them to dispatch, parks what should stop, chases stalls, escalates inward, and keeps one status summary current. Writes to Linear as the app actor; never polls.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.16 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.18 — written in this repository for customer accounts -->
 
 # Run this project
 

package/skills/unstick/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Get a stuck Catalyst Cloud ticket moving again. Use when the person asks "why is this parked and can you release it?", "unpark this", "get things flowing again", "the outage is over, retry what failed", or hands you a ticket that is not moving. Reads why nothing runs and what holds the ticket through the catalyst CLI, decides whether the recorded cause is fixed, previews the release, releases every governor holding the ticket the right way (or one failure class across a team), and raises an ask only for what a person has to do. Never releases a cause it cannot show changed without saying so.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.16 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.18 — written in this repository for customer accounts -->
 
 # Unstick
 

package/skills/what-needs-me/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   The human's decision inbox on Catalyst Cloud, and the one way an agent raises a decision on their behalf. Use when the person asks "what needs me?", "what am I blocking?", or when active work is gated on a choice only they can make. Lists open asks ranked by how much open work each one holds, files an ask through the cloud's ask route with the account's own template, and records the answer so the held work releases. Never answers as the human, never duplicates an open ask.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.16 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.18 — written in this repository for customer accounts -->
 
 # What needs me
 

package/skills/what-this-repo-needs/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   What environment variable names does this repository need, and where does each one come from? Scans the repository offline (no login, no network) and lists the names in three groups (build/test, deploy-only, bindings), each with where it was found, what uses it, and where a local value would come from. Never reads a value or prints one. Also checks the environment variable table in `.catalyst/catalyst.toml` offline. Use when someone asks "what does catalyst.env.json mean", "what env vars does this repo need", "why does the container need this", or before reviewing or writing the declaration.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.16 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.18 — written in this repository for customer accounts -->
 
 # What this repository needs
 

package/skills/whats-happening/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Use for "what's happening?", "what machines do we have?", "how much capacity do we have?", "where are we?", "why is that stuck?", "what closed?", "what's next?", "how does this work?", "why did it do that?", "how does it prioritise?" and "what does this setting do, where is it set?" in Catalyst Cloud, or asks for something to be done rather than known. Reads the contract via catalyst CLI. Read-only: route work/decisions, never answer as the human.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.16 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.18 — written in this repository for customer accounts -->
 
 # What's happening