@catalyst-cloud/cli 0.16.30 → 0.16.31

package/dist/runner-auto-update.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { CLAUDE_PATH_ENV } from "./update-plugin.js";
 // 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.
@@ -40,7 +41,7 @@ export function launchAgentPlist(deps, dir) {
         '<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>`,
+        `<key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(deps.path)}</string><key>HOME</key><string>${xml(deps.home)}</string>${deps.claude ? `<key>${CLAUDE_PATH_ENV}</key><string>${xml(deps.claude)}</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.
@@ -61,6 +62,7 @@ export function systemdUnits(deps, dir) {
             "[Service]",
             "Type=oneshot",
             `Environment=${unitWord(`PATH=${deps.path}`)}`,
+            ...(deps.claude ? [`Environment=${unitWord(`${CLAUDE_PATH_ENV}=${deps.claude}`)}`] : []),
             `ExecStart=${[deps.cli, "runner", "update", "--auto", "--dir", dir].map(unitWord).join(" ")}`,
             "",
         ].join("\n"),

package/dist/runner-command.js

@@ -1,9 +1,12 @@
 import { isAbsolute, resolve } from "node:path";
 import { flagBool, flagString, positionals } from "./args.js";
-import { UsageError } from "./errors.js";
+import { CliError, UsageError } from "./errors.js";
 import { autoUpdateStatus, disableAutoUpdate, enableAutoUpdate, scheduledPath, } from "./runner-auto-update.js";
-import { dockerRunnerUpdateEngine, readReleaseState, runnerDir, runRunnerUpdate, updateResultLines, } from "./runner-update.js";
+import { dockerRunnerUpdateEngine, readReleaseState, RELEASE_COMPONENTS, runnerDir, runRunnerUpdate, updateResultLines, } from "./runner-update.js";
 import { dockerFleetUpdateEngine, runFleetUpdate } from "./runner-update-fleet.js";
+import { runUpdate, sharedReleaseRead, updateReportJson, updateReportLines } from "./update.js";
+import { effectivePolicy, readUpdatePolicy, setComponentPolicy } from "./update-policy.js";
+import { resolveClaude } from "./update-plugin.js";
 import { cmdRunnerLifecycle, RUNNER_LIFECYCLE_ACTIONS } from "./runner.js";
 const USAGE = "catalyst runner [status] | stop | start | uninstall [--yes] [--delete-checkouts] | runner update [--check] [--dir <runner directory>] [--fleet] | runner auto-update [status|on|off]";
 const UPDATE_FLAGS = ["check", "auto", "dir", "fleet"];
@@ -13,6 +16,7 @@ function schedulerDeps(ctx, deps) {
         home: ctx.home,
         cli,
         path: scheduledPath(cli, process.execPath, ctx.env.PATH),
+        claude: resolveClaude(ctx.home, ctx.env),
         ...deps.scheduler,
     };
 }
@@ -36,6 +40,17 @@ function statusLine(status) {
         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.`;
 }
+/** Why this machine's images must not move now: an owner's hold, or settings that cannot be read
+ *  (which never count as "everything on"). Null when every image may move. */
+function imageHold(ctx) {
+    try {
+        const policy = readUpdatePolicy(ctx.home);
+        return RELEASE_COMPONENTS.some((id) => !effectivePolicy(policy, id).enabled) ? "owner_setting" : null;
+    }
+    catch {
+        return "update_policy_unreadable";
+    }
+}
 /** 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));
@@ -60,17 +75,78 @@ export async function cmdRunner(args, ctx, deps = {}) {
         const fleet = flagBool(args, "fleet");
         if (fleet && dirFlag === undefined)
             throw new UsageError("--fleet needs --dir, the directory that holds compose.json");
+        // One desired-release read serves the image check and the component report (CTC-6708).
+        const engine = sharedReleaseRead(deps.engine ?? dockerRunnerUpdateEngine({ env: ctx.env }));
+        // The 15-minute schedule runs `runner update --auto`. After the images it carries on with every
+        // other component (the CLI, the Cloud pack, the replica, opted-in SDK projects), on the same
+        // release read, so one schedule keeps the whole install on the approved release (CTC-6708). An
+        // image hold keeps only the images. A check never applies; with --json the components join the
+        // one JSON result, otherwise they get one line, and only when a release was read.
+        const components = async (imageResult) => {
+            if (!auto || fleet || check)
+                return null;
+            const report = await runUpdate(ctx, { mode: "apply", imagesDir: dir(), engine: () => engine, ...(imageResult ? { imageResult } : {}), ...deps.components });
+            if (report.approved === null)
+                return null;
+            const rows = report.components.filter((c) => !RELEASE_COMPONENTS.some((id) => id === c.id));
+            return {
+                rows,
+                line: `${ctx.now().toISOString()} components ${rows.map((c) => `${c.id}=${c.status}${c.status === "failed" || c.status === "pending" ? `(${c.reason})` : ""}`).join(" ")}`,
+                exitCode: rows.some((c) => c.status === "failed") || report.projects.some((p) => p.applied?.outcome === "failed") ? 1 : 0,
+            };
+        };
+        const print = (result, extra) => {
+            if (args.json)
+                ctx.stdout(JSON.stringify(extra ? { ...result, components: extra.rows } : result));
+            else if (auto) {
+                ctx.stdout(`${ctx.now().toISOString()} ${result.outcome} ${result.detail} generation=${result.generation ?? "none"}`);
+                if (extra)
+                    ctx.stdout(extra.line);
+            }
+            else
+                for (const line of updateResultLines(result))
+                    ctx.stdout(line);
+            return Math.max(result.exitCode, extra?.exitCode ?? 0);
+        };
+        // An owner's image hold stops this command's image work too, including the schedule's (CTC-6708).
+        const hold = check ? null : imageHold(ctx);
+        if (hold !== null) {
+            const retained = { outcome: "retained", detail: hold, generation: readReleaseState(dir()).generation, exitCode: hold === "owner_setting" ? 0 : 1 };
+            // Unreadable settings move nothing; a hold leaves the other components to the release check.
+            return print(retained, hold === "owner_setting" ? await components(undefined) : null);
+        }
         const result = fleet
             ? await runFleetUpdate(deps.fleetEngine ?? dockerFleetUpdateEngine({ env: ctx.env }), { dir: dir(), check })
-            : await runRunnerUpdate(deps.engine ?? dockerRunnerUpdateEngine({ env: ctx.env }), { 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;
+            : await runRunnerUpdate(engine, { dir: dir(), check });
+        // `runner update --check` also lists every installed component against the approved release, as
+        // `catalyst update --check` does. The image fields stay where scripts already read them.
+        if (check && !fleet && !auto) {
+            let report;
+            try {
+                report = await runUpdate(ctx, { mode: "check", imagesDir: dir(), engine: () => engine, imageResult: result });
+            }
+            catch (err) {
+                // Unreadable update settings cost the component report only; the image result still prints.
+                if (!(err instanceof CliError))
+                    throw err;
+                ctx.stderr(`catalyst: ${err.message}`);
+                if (args.json)
+                    ctx.stdout(JSON.stringify(result));
+                else
+                    for (const line of updateResultLines(result))
+                        ctx.stdout(line);
+                return result.exitCode;
+            }
+            if (args.json) {
+                const { schemaVersion, release, components, projects } = updateReportJson(report);
+                ctx.stdout(JSON.stringify({ ...result, schemaVersion, release, components, projects }));
+            }
+            else
+                for (const line of [...updateResultLines(result), ...updateReportLines(report)])
+                    ctx.stdout(line);
+            return result.exitCode;
+        }
+        return print(result, await components(result));
     }
     if (action === "auto-update" && parts.length <= 2) {
         const mode = parts[1] ?? "status";
@@ -84,6 +160,11 @@ export async function cmdRunner(args, ctx, deps = {}) {
             status = autoUpdateStatus(scheduler);
         else
             throw new UsageError(USAGE);
+        // The owner's explicit on/off is also their setting for the three images, so a release check
+        // reports them as held (CTC-6708). Setup's own call (enableRunnerAutoUpdate) never lifts a hold.
+        if (mode === "off" || (mode === "on" && status.state === "on"))
+            for (const id of RELEASE_COMPONENTS)
+                setComponentPolicy(ctx.home, id, mode === "on");
         if (args.json) {
             const state = mode === "status" && dirFlag !== undefined ? readReleaseState(dirFlag) : undefined;
             ctx.stdout(JSON.stringify({ ...status, ...(state ? { release: state } : {}) }));

package/dist/runner-update.js

@@ -11,12 +11,19 @@ import { dockerRunnerEngine, parseEnvText, persistedCustody, prepareRunnerImages
 //
 //   - 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;
+//   - no phase container exists for this host, unless the update is in place (below);
 //   - 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.
 //
+// In place (CTC-6709): when the release names its supervisor's journal format and it equals the
+// format of the supervisor a failure would go back to, as recorded when that supervisor was applied,
+// running phases are not waited out. The supervisor is recreated and re-adopts them, and they finish
+// on the image they were granted. A rollback lands on a supervisor that reads the same journal. A
+// format that differs, or is unknown on either side, waits for an idle machine as above, because an
+// older supervisor that meets a newer journal refuses to start.
+//
 // 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
@@ -26,6 +33,7 @@ import { dockerRunnerEngine, parseEnvText, persistedCustody, prepareRunnerImages
 export const RELEASE_STATE_FILE = "release-state.json";
 export const PREVIOUS_ENV_FILE = ".env.release-previous";
 const LOCK_FILE = "update.lock";
+const PENDING_REMOVAL_KEPT = 20;
 const READY_DEADLINE_MS = 5 * 60_000;
 const READY_POLL_MS = 5_000;
 const ATTEMPT_HOST_LABEL = "dev.catalystcloud.attempt.host-id";
@@ -77,10 +85,18 @@ export function parseDesiredRelease(input) {
             return null;
         images[component] = { reference, sourceSha: value.sourceSha };
     }
+    // Only the supervisor carries a journal format, a positive integer, as catalyst-cloud's parser.
+    const supervisor = input.supervisor;
+    if (supervisor.journalFormat !== undefined && !posInt(supervisor.journalFormat))
+        return null;
+    for (const component of ["runner", "watchdog"])
+        if (input[component].journalFormat !== undefined)
+            return null;
+    const journalFormat = supervisor.journalFormat === undefined ? null : supervisor.journalFormat;
     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 };
+    return { releaseId: id, generation: input.generation, approvedAtMs: input.approvedAtMs, images, journalFormat };
 }
 /** Whether to move. Every answer except a valid, strictly newer generation keeps the current images. */
 export function decideRelease(appliedGeneration, read) {
@@ -103,7 +119,7 @@ export function decideRelease(appliedGeneration, read) {
     return { action: "update", release };
 }
 export function readReleaseState(dir) {
-    const empty = { version: 1, generation: null, releaseId: null, appliedAtMs: null, previous: null, last: null };
+    const empty = { version: 1, generation: null, releaseId: null, appliedAtMs: null, previous: null, journal: null, pendingRemoval: [], last: null };
     try {
         const parsed = JSON.parse(readFileSync(join(dir, RELEASE_STATE_FILE), "utf8"));
         if (!isRecord(parsed) || parsed.version !== 1)
@@ -114,6 +130,12 @@ export function readReleaseState(dir) {
             releaseId: typeof parsed.releaseId === "string" ? parsed.releaseId : null,
             appliedAtMs: posInt(parsed.appliedAtMs) ? parsed.appliedAtMs : null,
             previous: isRecord(parsed.previous) ? parsed.previous : null,
+            journal: isRecord(parsed.journal) && posInt(parsed.journal.format) && typeof parsed.journal.supervisor === "string"
+                ? { format: parsed.journal.format, supervisor: parsed.journal.supervisor }
+                : null,
+            pendingRemoval: Array.isArray(parsed.pendingRemoval)
+                ? parsed.pendingRemoval.filter((ref) => typeof ref === "string").slice(0, PENDING_REMOVAL_KEPT)
+                : [],
             last: isRecord(parsed.last) ? parsed.last : null,
         };
     }
@@ -161,6 +183,8 @@ export async function runRunnerUpdate(engine, options) {
     if (!options.check && lock === null)
         return { outcome: "retained", detail: "update_running", generation: readReleaseState(dir).generation, exitCode: 0 };
     try {
+        if (!options.check)
+            await retryPendingRemoval(engine, dir, options.signal);
         const result = await update(engine, options, now);
         if (!options.check) {
             const state = readReleaseState(dir);
@@ -173,6 +197,19 @@ export async function runRunnerUpdate(engine, options) {
             releaseLock(dir, lock);
     }
 }
+/** Try again to remove images an earlier update replaced but could not remove, never one `.env`
+ *  names now (a setup run or a person may have put it back). */
+async function retryPendingRemoval(engine, dir, signal) {
+    const state = readReleaseState(dir);
+    if (state.pendingRemoval.length === 0)
+        return;
+    const inUse = new Set(Object.values(imagesOf(readEnvFile(join(dir, ".env")) ?? {})));
+    const removable = state.pendingRemoval.filter((ref) => !inUse.has(ref));
+    if (removable.length === 0)
+        return;
+    const kept = await engine.removeImages(removable, signal);
+    writeReleaseState(dir, { ...state, pendingRemoval: [...new Set([...state.pendingRemoval.filter((ref) => inUse.has(ref)), ...kept])] });
+}
 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) {
@@ -208,8 +245,10 @@ async function update(engine, options, now) {
             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 });
+    const record = (outcome, detail, previous, unremoved = []) => {
+        const journal = release.journalFormat === null ? null : { format: release.journalFormat, supervisor: target.supervisor };
+        const pendingRemoval = [...new Set([...state.pendingRemoval, ...unremoved])].slice(-PENDING_REMOVAL_KEPT);
+        writeReleaseState(dir, { ...state, generation: release.generation, releaseId: release.releaseId, appliedAtMs: now(), previous, journal, pendingRemoval });
         return { outcome, detail, generation: release.generation, exitCode: 0, ...tagged };
     };
     if (options.check)
@@ -229,12 +268,17 @@ async function update(engine, options, now) {
         }
     }
     const rollbackImages = rollbackText === null ? null : imagesOf(parseEnvText(rollbackText));
+    // In place only when the supervisor a failure goes back to reads the release's journal format.
+    const inPlace = release.journalFormat !== null && state.journal !== null && rollbackImages !== null
+        && state.journal.format === release.journalFormat && state.journal.supervisor === rollbackImages.supervisor;
     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);
+    if (!inPlace) {
+        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);
@@ -257,7 +301,7 @@ async function update(engine, options, now) {
         await restoreCustody(rollbackImages ?? current);
         return done("retained", "supervisor_stop_failed", tagged);
     }
-    const busyAfterStop = await engine.attemptContainers(dir, hostId, signal);
+    const busyAfterStop = inPlace ? 0 : await engine.attemptContainers(dir, hostId, signal);
     if (busyAfterStop !== 0) {
         await engine.composeUp(dir, signal);
         await restoreCustody(rollbackImages ?? current);
@@ -273,9 +317,12 @@ async function update(engine, 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);
+        // An image still in use, such as the runner image under phases left running, is kept for a later run.
+        const unremoved = changed.length > 0
+            ? await engine.removeImages(changed.map((c) => current[c]).filter((ref) => ref !== ""), signal)
+            : [];
+        const applied = changed.length > 0 ? `updated:${changed.join(",")}` : "reconciled";
+        return record("updated", inPlace ? `${applied}:in_place` : applied, changed.length > 0 ? current : state.previous, unremoved);
     }
     if (rollbackText === null || rollbackImages === null)
         return done("failed", "new_supervisor_not_ready_no_previous", { ...tagged, exitCode: 1 });
@@ -461,8 +508,17 @@ export function dockerRunnerUpdateEngine(deps = {}) {
             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 });
+            const kept = [];
+            for (const ref of images) {
+                if ((await docker(["image", "rm", ref], { signal, timeoutMs: 120_000 })).code === 0)
+                    continue;
+                // Only Docker saying the image does not exist counts as removed. A refusal, or a daemon that
+                // did not answer, keeps it for the next run.
+                const inspect = await docker(["image", "inspect", "--format", "{{.Id}}", ref], { signal });
+                if (inspect.code === 0 || !/No such image/i.test(inspect.stderr ?? ""))
+                    kept.push(ref);
+            }
+            return kept;
         },
         async supervisorReadySinceStart(dir, signal) {
             const compose = runnerComposeArgs(dir);

package/dist/update-cli.js

@@ -0,0 +1,234 @@
+// update-cli.ts — the CLI moves itself to the approved version (CTC-6708). A release check never
+// replaces the code under the process doing the update: it installs the approved CLI into its own
+// directory under ~/.config/catalyst-cloud/cli-runtimes/cli-<version>, checks the package name,
+// the version and that `--version` answers from it, and only then switches one small record
+// (active.json) to it. The person's own `catalyst` command stays where it is: its launcher
+// (bin/launch.js) reads that record and runs the selected version, so npm's bins, scheduled jobs and
+// the saved launcher path never move.
+//
+// A failed install, a wrong package or a version that does not answer leaves the record as it was,
+// so the CLI that was running stays the one that runs. Earlier versions' directories are kept: a
+// replica still running on one keeps its code until it restarts.
+//
+// The launcher only ever moves forward. A record naming a version at or below the launcher's own
+// (an owner who reinstalled a newer CLI by hand, say) is ignored, and so is any record whose
+// directory is not this install's own runtime directory for that version.
+import { spawnSync } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { configDirFor, PACKAGE_NAME } from "./config.js";
+// bin/launch.js imports this module before dist/cli.js, on runtimes too old to load the rest of the
+// CLI, so it imports only config.js and node built-ins. These three mirror approved-release.ts's.
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const exactVersion = (v) => (typeof v === "string" && /^(0|[1-9]\d{0,5})\.(0|[1-9]\d{0,5})\.(0|[1-9]\d{0,5})$/.test(v) ? v : null);
+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;
+}
+/** Set to a bin's own path, that bin's launcher runs itself and never selects (the staged check). */
+export const ACTIVE_RUNTIME_ENV = "CATALYST_CLI_ACTIVE_RUNTIME";
+export function cliRuntimesDirFor(home) {
+    return join(configDirFor(home), "cli-runtimes");
+}
+export function activeRuntimePathFor(home) {
+    return join(cliRuntimesDirFor(home), "active.json");
+}
+/** The one directory a given version may live in: a record naming any other path is refused. */
+export function runtimeRootFor(home, version) {
+    return join(cliRuntimesDirFor(home), `cli-${version}`);
+}
+const packageDir = (root) => join(root, "node_modules", ...PACKAGE_NAME.split("/"));
+export function readActiveRuntime(home) {
+    try {
+        const raw = JSON.parse(readFileSync(activeRuntimePathFor(home), "utf8"));
+        if (!isRecord(raw) || raw.version !== 1 || typeof raw.root !== "string" || typeof raw.activatedAtMs !== "number")
+            return null;
+        const cliVersion = exactVersion(raw.cliVersion);
+        if (cliVersion === null || raw.root !== runtimeRootFor(home, cliVersion))
+            return null;
+        const prev = raw.previous;
+        const previous = isRecord(prev) && typeof prev.root === "string" && exactVersion(prev.cliVersion) !== null
+            ? { cliVersion: String(prev.cliVersion), root: prev.root }
+            : null;
+        return { version: 1, cliVersion, root: raw.root, activatedAtMs: raw.activatedAtMs, previous };
+    }
+    catch {
+        return null;
+    }
+}
+/** The installed CLI's version in `root`, when its package is the CLI and its directory is private. */
+function runtimeVersionAt(root) {
+    try {
+        // A directory others can write to could have its code swapped: never run from one.
+        if ((statSync(root).mode & 0o022) !== 0)
+            return null;
+        const manifest = JSON.parse(readFileSync(join(packageDir(root), "package.json"), "utf8"));
+        if (!isRecord(manifest) || manifest.name !== PACKAGE_NAME)
+            return null;
+        return exactVersion(manifest.version);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The bin the launcher should run instead of its own code, or null to run its own: no record, a
+ * record outside this install's runtime directory, a version not newer than `ownVersion`, or a
+ * directory whose package does not match the record.
+ */
+export function activeRuntimeBin(home, ownVersion, binFile = "catalyst.js") {
+    const active = readActiveRuntime(home);
+    const own = exactVersion(ownVersion);
+    if (active === null || own === null || compareVersions(active.cliVersion, own) <= 0)
+        return null;
+    if (runtimeVersionAt(active.root) !== active.cliVersion)
+        return null;
+    // The same bin file the person ran (bin/launch.js passes its own name), so a deprecated name keeps its notice.
+    const bin = join(packageDir(active.root), "bin", basename(binFile));
+    return existsSync(bin) ? bin : null;
+}
+export const spawnCliCommand = (argv, cwd, env) => {
+    const [cmd, ...args] = argv;
+    if (cmd === undefined)
+        return { status: 1, stdout: "", stderr: "no command" };
+    const run = spawnSync(cmd, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8", timeout: 10 * 60_000 });
+    return { status: run.error ? 1 : run.status, stdout: run.stdout ?? "", stderr: run.error ? run.error.message : (run.stderr ?? "") };
+};
+/**
+ * Install exact `version` of the CLI into its own directory and check it, without selecting it:
+ * its package name and version, and that its `--version` answers with that version. An already
+ * checked directory is reused. The skills pack update reads its bundled skills from here too.
+ */
+export function stageCliRuntime(home, version, deps = {}) {
+    if (exactVersion(version) === null)
+        return { ok: false, detail: "target_invalid" };
+    const dir = cliRuntimesDirFor(home);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const root = runtimeRootFor(home, version);
+    if (runtimeVersionAt(root) === version)
+        return { ok: true, root };
+    // One staging at a time: another release check could otherwise remove the directory this one just
+    // put in place, while processes run from it.
+    const lock = join(dir, ".staging.lock");
+    if (!takeLock(lock))
+        return { ok: false, detail: "update_running" };
+    try {
+        return stageLocked(dir, root, version, deps);
+    }
+    finally {
+        try {
+            unlinkSync(lock);
+        }
+        catch {
+            // released already
+        }
+    }
+}
+/** Longer than npm's own timeout, so a live staging's lock is never taken over. */
+const STAGING_LOCK_STALE_MS = 15 * 60_000;
+function takeLock(path) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            closeSync(openSync(path, "wx", 0o600));
+            return true;
+        }
+        catch {
+            // A run killed mid-install leaves its lock behind; past the stale age it is taken over.
+            try {
+                if (Date.now() - statSync(path).mtimeMs <= STAGING_LOCK_STALE_MS)
+                    return false;
+                unlinkSync(path);
+            }
+            catch {
+                // gone already: try again
+            }
+        }
+    }
+    return false;
+}
+function stageLocked(dir, root, version, deps) {
+    const exec = deps.exec ?? spawnCliCommand;
+    const env = deps.env ?? process.env;
+    // Another check may have finished it while this one waited for the lock.
+    if (runtimeVersionAt(root) === version)
+        return { ok: true, root };
+    const staging = join(dir, `.staging-cli-${version}-${process.pid}-${Date.now()}`);
+    const fail = (detail) => {
+        rmSync(staging, { recursive: true, force: true });
+        return { ok: false, detail };
+    };
+    mkdirSync(staging, { mode: 0o700 });
+    // An exact version of the one CLI package: never a tag or range, never a global install.
+    const install = exec(["npm", "install", "--prefix", staging, "--no-save", "--no-audit", "--no-fund", "--omit=dev", `${PACKAGE_NAME}@${version}`], staging, env);
+    if (install.status !== 0)
+        return fail("install_failed");
+    if (runtimeVersionAt(staging) !== version)
+        return fail("package_mismatch");
+    const stagedBin = join(packageDir(staging), "bin", "catalyst.js");
+    const smoke = exec([deps.nodePath ?? process.execPath, stagedBin, "--version"], staging, { ...env, [ACTIVE_RUNTIME_ENV]: stagedBin });
+    if (smoke.status !== 0 || !smoke.stdout.split(/\s+/).includes(version))
+        return fail("smoke_failed");
+    try {
+        rmSync(root, { recursive: true, force: true });
+        renameSync(staging, root);
+    }
+    catch {
+        return fail("activate_failed");
+    }
+    return { ok: true, root };
+}
+/** The skills a staged CLI package bundles. */
+export const stagedSkillsDir = (root) => join(packageDir(root), "skills");
+/** Install `target` of the CLI beside the running one, check it answers, then select it. */
+export function applyCliUpdate(home, ownVersion, target, deps = {}) {
+    const version = exactVersion(target);
+    const before = readActiveRuntime(home);
+    const running = before && activeRuntimeBin(home, ownVersion) !== null ? before.cliVersion : ownVersion;
+    if (version === null)
+        return { outcome: "failed", detail: "target_invalid", version: running };
+    // Never a move down: a CLI already past the target keeps running.
+    if (compareVersions(running, version) >= 0)
+        return { outcome: "current", detail: compareVersions(running, version) === 0 ? "current" : "installed_newer", version: running };
+    const staged = stageCliRuntime(home, version, deps);
+    if (!staged.ok)
+        return { outcome: "failed", detail: staged.detail, version: running };
+    const root = staged.root;
+    const record = {
+        version: 1,
+        cliVersion: version,
+        root,
+        activatedAtMs: (deps.now ?? Date.now)(),
+        previous: before ? { cliVersion: before.cliVersion, root: before.root } : null,
+    };
+    const path = activeRuntimePathFor(home);
+    const priorBytes = existsSync(path) ? readFileSync(path) : null;
+    const write = (bytes) => {
+        const tmp = `${path}.${process.pid}.tmp`;
+        try {
+            writeFileSync(tmp, bytes, { mode: 0o600 });
+            renameSync(tmp, path);
+            return true;
+        }
+        catch {
+            rmSync(tmp, { force: true });
+            return false;
+        }
+    };
+    if (!write(`${JSON.stringify(record, null, 2)}\n`))
+        return { outcome: "failed", detail: "activate_failed", version: running };
+    // Read back what the stable command will now run; put the earlier record back if it is not this one.
+    if (compareVersions(version, ownVersion) > 0 && activeRuntimeBin(home, ownVersion) === null) {
+        if (priorBytes === null)
+            rmSync(path, { force: true });
+        else
+            write(priorBytes);
+        return { outcome: "failed", detail: "activate_failed", version: running };
+    }
+    return { outcome: "updated", detail: "activated", version };
+}