@catalyst-cloud/cli 0.16.29 → 0.16.31

package/dist/update-command.js

@@ -0,0 +1,151 @@
+// update-command.ts — `catalyst update [--check] [--json] [--project <path>] [--dir <path>]` and
+// `catalyst update policy [<component> on|off] [--project <path>]` and
+// `catalyst update sdk --project <path>` (CTC-6708). The release check is update.ts; the owner's
+// settings are update-policy.ts. A policy change applies at once and keeps every other component's
+// setting. `update sdk` is the owner's explicit say-so for one update of one project, and changes no
+// setting.
+import { isAbsolute } from "node:path";
+import { flagBool, flagString, positionals } from "./args.js";
+import { UsageError } from "./errors.js";
+import { dockerRunnerUpdateEngine, runnerDir } from "./runner-update.js";
+import { policyLines, readEffectivePolicy, runUpdate, updateReportJson, updateReportLines } from "./update.js";
+import { applySdkUpdate } from "./update-sdk.js";
+import { canonicalProject, effectivePolicy, isUpdateComponent, readUpdatePolicy, setComponentPolicy, setProjectSdkPolicy, UPDATE_COMPONENTS, } from "./update-policy.js";
+const USAGE = "catalyst update [--check] [--project <absolute path>] [--dir <runner directory>] [--json] | update sdk --project <absolute path> | update policy [<component> on|off] | update policy sdk on|off --project <absolute path>";
+/** How each component reads in a sentence. */
+const SENTENCE_NAMES = {
+    runner: "runner",
+    supervisor: "supervisor",
+    watchdog: "watchdog",
+    cli: "CLI",
+    "skills-cloud": "Cloud skills",
+    "skills-dev": "Dev skills",
+    replica: "local replica",
+};
+function absoluteFlag(args, name) {
+    const value = flagString(args, name);
+    if (value !== undefined && !isAbsolute(value))
+        throw new UsageError(`--${name} must be an absolute path`);
+    return value;
+}
+function cmdPolicy(parts, args, ctx) {
+    const project = absoluteFlag(args, "project");
+    if (flagBool(args, "check") || args.flags.dir !== undefined)
+        throw new UsageError("--check and --dir are not valid with update policy");
+    if (parts.length === 1) {
+        if (project !== undefined)
+            throw new UsageError("update policy lists every setting; --project goes with update policy sdk on|off");
+        const policy = readEffectivePolicy(ctx);
+        if (args.json)
+            ctx.stdout(JSON.stringify({
+                components: UPDATE_COMPONENTS.map((id) => ({ id, ...effectivePolicy(policy, id) })),
+                projects: policy.projects.map((p) => ({ path: p.path, sdk: p.sdk, source: p.source })),
+            }));
+        else
+            for (const line of policyLines(policy))
+                ctx.stdout(line);
+        return 0;
+    }
+    const [, name, value] = parts;
+    if (parts.length !== 3 || (value !== "on" && value !== "off") || name === undefined)
+        throw new UsageError(USAGE);
+    const enabled = value === "on";
+    if (name === "sdk") {
+        if (project === undefined)
+            throw new UsageError("update policy sdk needs --project <absolute path>");
+        const saved = setProjectSdkPolicy(ctx.home, project, enabled ? "auto" : "notify");
+        const text = enabled
+            ? `Automatic SDK updates are on for ${saved.path}. Release checks may update its package files.`
+            : `Automatic SDK updates are off for ${saved.path}. Release checks will only report available updates.`;
+        if (args.json)
+            ctx.stdout(JSON.stringify({ project: saved.path, sdk: saved.sdk, source: saved.source }));
+        else
+            ctx.stdout(text);
+        return 0;
+    }
+    if (project !== undefined)
+        throw new UsageError("--project goes with update policy sdk on|off");
+    if (!isUpdateComponent(name))
+        throw new UsageError(`unknown component: ${name}. Use one of ${UPDATE_COMPONENTS.join(", ")} or sdk`);
+    setComponentPolicy(ctx.home, name, enabled);
+    if (args.json)
+        ctx.stdout(JSON.stringify({ id: name, enabled, source: "owner" }));
+    else
+        ctx.stdout(`Automatic ${SENTENCE_NAMES[name]} updates are ${value}. Other components keep their settings.`);
+    return 0;
+}
+async function cmdSdk(parts, args, ctx, deps) {
+    if (parts.length !== 1)
+        throw new UsageError(USAGE);
+    if (flagBool(args, "check"))
+        throw new UsageError("update sdk updates the project; to only look, run catalyst update --check --project <path>");
+    const flag = absoluteFlag(args, "project");
+    if (flag === undefined)
+        throw new UsageError("update sdk needs --project <absolute path>");
+    const project = canonicalProject(flag).path;
+    const dirFlag = absoluteFlag(args, "dir");
+    const report = await runUpdate(ctx, {
+        mode: "check",
+        imagesDir: dirFlag ?? runnerDir(ctx),
+        project,
+        engine: () => deps.engine ?? dockerRunnerUpdateEngine({ env: ctx.env }),
+    });
+    if (report.approved === null || report.crossTrain !== null) {
+        const lines = report.crossTrain
+            ? [`The approved release is on train ${report.crossTrain.approved}; SDK updates stay on train ${report.crossTrain.supported}.`, "Nothing was changed."]
+            : updateReportLines(report).filter((line) => line.startsWith("Approved release unavailable") || line === "Nothing was changed.");
+        if (args.json)
+            ctx.stdout(JSON.stringify({ project, outcome: "refused", detail: report.crossTrain ? "cross_train" : (report.unavailable?.reason ?? "approval_unavailable"), moved: [] }));
+        else
+            for (const line of lines)
+                ctx.stdout(line);
+        return report.crossTrain ? 0 : 1;
+    }
+    const result = applySdkUpdate(ctx.home, project, report.approved, deps.sdkExec);
+    const registered = readUpdatePolicy(ctx.home).projects.find((p) => p.path === project);
+    if (args.json) {
+        ctx.stdout(JSON.stringify({ project, outcome: result.outcome, detail: result.detail, moved: result.moved }));
+    }
+    else {
+        const manager = result.project.packageManager ?? "its package manager";
+        if (result.outcome === "updated")
+            for (const move of result.moved)
+                ctx.stdout(`${move.name} in ${project}: updated from ${move.from} to ${move.to} with ${manager}.`);
+        else if (result.outcome === "current")
+            ctx.stdout(`SDK ${project}: already on the approved version.`);
+        else if (result.outcome === "refused")
+            ctx.stdout(`SDK ${project}: not changed (${result.detail}).`);
+        else
+            ctx.stdout(`SDK ${project}: the update failed (${result.detail}), and its package files were put back. If ${manager} left a partial install, run ${manager} install there.`);
+        ctx.stdout(`Automatic SDK updates remain ${registered?.sdk === "auto" ? "on" : "off"} for ${project}.`);
+    }
+    return result.outcome === "updated" || result.outcome === "current" ? 0 : 1;
+}
+export async function cmdUpdate(args, ctx, deps = {}) {
+    const parts = positionals(args);
+    if (parts[0] === "policy")
+        return cmdPolicy(parts, args, ctx);
+    if (parts[0] === "sdk")
+        return cmdSdk(parts, args, ctx, deps);
+    if (parts.length > 0)
+        throw new UsageError(USAGE);
+    const dirFlag = absoluteFlag(args, "dir");
+    const project = absoluteFlag(args, "project");
+    const report = await runUpdate(ctx, {
+        mode: flagBool(args, "check") ? "check" : "apply",
+        imagesDir: dirFlag ?? runnerDir(ctx),
+        // Read the project where it really is; an inspection never registers it.
+        ...(project !== undefined ? { project: canonicalProject(project).path } : {}),
+        engine: () => deps.engine ?? dockerRunnerUpdateEngine({ env: ctx.env }),
+        ...(deps.sdkExec ? { sdkExec: deps.sdkExec } : {}),
+        ...(deps.cliApply ? { cliApply: deps.cliApply } : {}),
+        ...(deps.replicaRestart ? { replicaRestart: deps.replicaRestart } : {}),
+        ...(deps.packApply ? { packApply: deps.packApply } : {}),
+    });
+    if (args.json)
+        ctx.stdout(JSON.stringify(updateReportJson(report)));
+    else
+        for (const line of updateReportLines(report))
+            ctx.stdout(line);
+    return report.exitCode;
+}

package/dist/update-inventory.js

@@ -0,0 +1,96 @@
+// update-inventory.ts — what this install has, read without changing anything (CTC-6708). Each
+// component is installed (with the version or image it runs), absent, or unknown with a reason;
+// unknown is never reported as current. Reading it starts no process, contacts no service, and a
+// machine with no runner installation never touches Docker.
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { exactVersion } from "./approved-release.js";
+import { loadConfig, packageRoot, readManifest, updatePackageName } from "./config.js";
+import { parseEnvText } from "./onboard-runner.js";
+import { replicaStatus, writerIsRunning } from "./replica.js";
+import { readReleaseState, RELEASE_COMPONENTS, RELEASE_ENV_KEYS, releaseReference, } from "./runner-update.js";
+import { installedBundleVersion, resolveSkillsDir, skillsSourceDir } from "./skills.js";
+import { cloudPluginInventory } from "./update-plugin.js";
+export function imageInventory(dir) {
+    const envPath = join(dir, ".env");
+    if (!existsSync(envPath) || !existsSync(join(dir, "compose.yaml")))
+        return { installed: false, dir };
+    let env = {};
+    try {
+        env = parseEnvText(readFileSync(envPath, "utf8"));
+    }
+    catch {
+        env = {};
+    }
+    const references = Object.fromEntries(RELEASE_COMPONENTS.map((c) => [c, releaseReference(c, env[RELEASE_ENV_KEYS[c]])]));
+    return { installed: true, dir, references, generation: readReleaseState(dir).generation };
+}
+function bundledSkillNames() {
+    try {
+        return readdirSync(skillsSourceDir(), { withFileTypes: true })
+            .filter((e) => e.isDirectory() && existsSync(join(skillsSourceDir(), e.name, "SKILL.md")))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/** The Cloud pack as installed in the agent skills directory, read from each skill's provenance line. */
+export function cloudPackInventory(ctx, cfg) {
+    const dir = resolveSkillsDir({}, ctx, cfg);
+    const found = installedBundleVersion(dir, bundledSkillNames());
+    if (found.version !== null) {
+        const version = exactVersion(found.version);
+        return version ? { state: "installed", version, dir } : { state: "unknown", reason: "version_unreadable", dir };
+    }
+    if (found.unstamped.length > 0)
+        return { state: "unknown", reason: "version_unstamped", dir };
+    return { state: "not_installed", dir };
+}
+/** The Dev pack ships from its own repository with no provenance stamp this CLI reads, so its
+ *  presence is known (its `research-codebase` skill, as the onboarding guide checks) but its version
+ *  is not. Unknown is never reported as current. */
+export function devPackInventory(ctx, cfg) {
+    const dir = resolveSkillsDir({}, ctx, cfg);
+    return existsSync(join(dir, "research-codebase", "SKILL.md"))
+        ? { state: "unknown", reason: "version_unrecorded", dir }
+        : { state: "not_installed", dir };
+}
+export function replicaInventory(ctx, cfg) {
+    if (!cfg)
+        return { state: "not_installed" };
+    let status;
+    try {
+        status = replicaStatus(ctx, cfg);
+    }
+    catch (err) {
+        return { state: "unknown", reason: err instanceof Error ? err.message : String(err) };
+    }
+    if (status.dbPath === null || status.verdict === "not-configured" || status.verdict === "absent")
+        return { state: "not_installed" };
+    if (!writerIsRunning(status))
+        return { state: "stopped", dbPath: status.dbPath };
+    const version = exactVersion(status.writer?.version);
+    return { state: "running", dbPath: status.dbPath, version, pid: status.writer?.pid ?? status.lockPid ?? status.pidfilePid };
+}
+/** Everything this install has. `imagesDir` is the runner installation to read. */
+export function readInventory(ctx, imagesDir) {
+    let cfg = null;
+    try {
+        cfg = loadConfig(ctx.home);
+    }
+    catch {
+        cfg = null;
+    }
+    const root = packageRoot();
+    return {
+        cli: { version: readManifest().version, packageName: updatePackageName(root), root },
+        images: imageInventory(imagesDir),
+        skills: {
+            cloud: cloudPackInventory(ctx, cfg),
+            dev: devPackInventory(ctx, cfg),
+        },
+        plugin: cloudPluginInventory(ctx.home, ctx.env),
+        replica: replicaInventory(ctx, cfg),
+    };
+}

package/dist/update-plugin.js

@@ -0,0 +1,99 @@
+// update-plugin.ts — the Claude plugin form of the Cloud skills pack moves with the release check
+// (CTC-6791). Claude Code installs the plugin from its own marketplace checkout of this repository,
+// which serves the repository's head, so the release check moves it only when that checkout carries
+// exactly the approved version: it refreshes the marketplace, reads the plugin version the checkout
+// now serves, and asks Claude Code to update the plugin only when that version is the approved one.
+// Claude Code has no way to install a plugin at a pinned version, so a marketplace ahead of the
+// approval leaves the plugin where it is. The 15-minute schedule finds `claude` at the absolute path
+// recorded when it was set up, then on PATH, then in Claude Code's usual install locations; only when
+// none has it is nothing changed, and the report names the command.
+import { accessSync, constants, readFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { exactVersion } from "./approved-release.js";
+import { spawnCliCommand } from "./update-cli.js";
+export const CLOUD_MARKETPLACE = "catalyst-cloud";
+export const CLOUD_PLUGIN_ID = `catalyst@${CLOUD_MARKETPLACE}`;
+/** The one command that moves the plugin, for an owner whose release check cannot run Claude Code. */
+export const CLOUD_PLUGIN_COMMAND = `claude plugin marketplace update ${CLOUD_MARKETPLACE} && claude plugin update ${CLOUD_PLUGIN_ID}`;
+export function claudeConfigDir(home, env) {
+    return env.CLAUDE_CONFIG_DIR || join(home, ".claude");
+}
+function readJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** The Cloud plugin as Claude Code records it: its user-scope install when there is one, else the first. */
+export function cloudPluginInventory(home, env) {
+    let registry;
+    try {
+        registry = readJson(join(claudeConfigDir(home, env), "plugins", "installed_plugins.json"));
+    }
+    catch (err) {
+        return err.code === "ENOENT" ? { state: "not_installed" } : { state: "unknown", reason: "plugin_registry_unreadable" };
+    }
+    const entries = isRecord(registry) && isRecord(registry.plugins) ? registry.plugins[CLOUD_PLUGIN_ID] : undefined;
+    if (!Array.isArray(entries) || entries.length === 0)
+        return { state: "not_installed" };
+    const entry = entries.find((e) => isRecord(e) && e.scope === "user") ?? entries[0];
+    const version = isRecord(entry) ? exactVersion(entry.version) : null;
+    if (version === null)
+        return { state: "unknown", reason: "version_unreadable" };
+    return { state: "installed", version, scope: isRecord(entry) && typeof entry.scope === "string" ? entry.scope : "user", claude: resolveClaude(home, env) };
+}
+/** The plugin version the marketplace checkout serves now, or null when it cannot be read. */
+function servedPluginVersion(home, env) {
+    const plugins = join(claudeConfigDir(home, env), "plugins");
+    let dir = join(plugins, "marketplaces", CLOUD_MARKETPLACE);
+    try {
+        const known = readJson(join(plugins, "known_marketplaces.json"));
+        const entry = isRecord(known) ? known[CLOUD_MARKETPLACE] : undefined;
+        if (isRecord(entry) && typeof entry.installLocation === "string")
+            dir = entry.installLocation;
+    }
+    catch {
+        // No record of where it lives: Claude Code's default checkout directory.
+    }
+    try {
+        const manifest = readJson(join(dir, ".claude-plugin", "plugin.json"));
+        return isRecord(manifest) ? exactVersion(manifest.version) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The schedule's record of the `claude` command found when it was set up. */
+export const CLAUDE_PATH_ENV = "CATALYST_CLAUDE_PATH";
+const executable = (path) => {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** The `claude` command: the schedule's recorded path, then PATH, then Claude Code's usual install locations. */
+export function resolveClaude(home, env) {
+    const recorded = env[CLAUDE_PATH_ENV];
+    const onPath = (env.PATH ?? "").split(delimiter).filter((d) => d.startsWith("/")).map((d) => join(d, "claude"));
+    // Homebrew, /usr/local/bin and node's own directory are already on the schedule's PATH (scheduledPath).
+    const usual = [join(home, ".local", "bin", "claude"), join(home, ".claude", "local", "claude")];
+    return [...(recorded?.startsWith("/") ? [recorded] : []), ...onPath, ...usual].find(executable) ?? null;
+}
+/** Move the Cloud plugin to exact version `target` through Claude Code, when its marketplace serves it. */
+export function applyCloudPluginUpdate(home, env, target, scope, deps = {}) {
+    const claude = deps.claudePath === undefined ? resolveClaude(home, env) : deps.claudePath;
+    if (claude === null)
+        return { outcome: "no_claude", detail: "claude_not_found", version: null };
+    const exec = deps.exec ?? spawnCliCommand;
+    if (exec([claude, "plugin", "marketplace", "update", CLOUD_MARKETPLACE], home, env).status !== 0)
+        return { outcome: "failed", detail: "marketplace_update_failed", version: null };
+    if (servedPluginVersion(home, env) !== target)
+        return { outcome: "waiting", detail: "marketplace_not_approved", version: null };
+    const updated = exec([claude, "plugin", "update", CLOUD_PLUGIN_ID, "--scope", scope], home, env).status === 0;
+    const now = cloudPluginInventory(home, env);
+    const version = now.state === "installed" ? now.version : null;
+    if (!updated)
+        return { outcome: "failed", detail: "update_failed", version };
+    return version === target ? { outcome: "updated", detail: "updated", version } : { outcome: "failed", detail: "verify_failed", version };
+}

package/dist/update-policy.js

@@ -0,0 +1,194 @@
+// update-policy.ts — which installed components update by themselves (CTC-6708). Every component
+// updates by default; an owner turns one off only with an explicit setting, kept in
+// ~/.config/catalyst-cloud/updates.json (mode 0600, apart from the sign-in record). An absent entry
+// means on, so only explicit or migrated choices are stored.
+//
+// A project's SDK is the one exception: Catalyst never edits a customer's repository unasked, so a
+// registered project is notify-only until its owner turns its SDK updates on. Project paths are kept
+// by their real path and the root's device and inode, so a later symlink or moved directory cannot
+// redirect an opt-in to a different repository.
+//
+// Writes take a short exclusive lock and replace the file by rename, so two setting changes at once
+// never lose one of them and a reader never sees half a file.
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, statSync, unlinkSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { configDirFor } from "./config.js";
+import { CliError, UsageError } from "./errors.js";
+import { isRecord, writePrivateAtomic } from "./runner-update.js";
+export const UPDATE_POLICY_FILE = "updates.json";
+const LOCK_STALE_MS = 30_000;
+const LOCK_WAIT_MS = 5_000;
+/** The installed components a release check keeps current. The SDK is per project, not here. */
+export const UPDATE_COMPONENTS = ["runner", "supervisor", "watchdog", "cli", "skills-cloud", "skills-dev", "replica"];
+export function updatePolicyPathFor(home) {
+    return join(configDirFor(home), UPDATE_POLICY_FILE);
+}
+const emptyPolicy = () => ({ version: 1, components: {}, projects: [] });
+export function isUpdateComponent(value) {
+    return UPDATE_COMPONENTS.includes(value);
+}
+/** Read the saved preferences. A missing file is the default (everything on). A file that is not a
+ *  valid record is an error, never silently "everything on": that would undo an owner's hold. */
+export function readUpdatePolicy(home) {
+    const path = updatePolicyPathFor(home);
+    if (!existsSync(path))
+        return emptyPolicy();
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new CliError(`update settings at ${path} are not valid JSON; fix or remove the file`, "update-policy-corrupt", 1);
+    }
+    const policy = parsePolicy(parsed);
+    if (!policy)
+        throw new CliError(`update settings at ${path} are not a settings record this CLI can read; fix or remove the file`, "update-policy-corrupt", 1);
+    return policy;
+}
+function parsePolicy(input) {
+    if (!isRecord(input) || input.version !== 1)
+        return null;
+    const policy = emptyPolicy();
+    if (input.components !== undefined) {
+        if (!isRecord(input.components))
+            return null;
+        for (const [name, value] of Object.entries(input.components)) {
+            if (!isUpdateComponent(name))
+                return null;
+            if (!isRecord(value) || typeof value.enabled !== "boolean")
+                return null;
+            if (value.source !== "owner" && value.source !== "migrated")
+                return null;
+            policy.components[name] = { enabled: value.enabled, source: value.source };
+        }
+    }
+    if (input.projects !== undefined) {
+        if (!Array.isArray(input.projects))
+            return null;
+        for (const value of input.projects) {
+            if (!isRecord(value) || typeof value.path !== "string" || !isAbsolute(value.path))
+                return null;
+            if (value.sdk !== "notify" && value.sdk !== "auto")
+                return null;
+            if (value.source !== "owner" && value.source !== "migrated")
+                return null;
+            if (typeof value.dev !== "number" || typeof value.ino !== "number")
+                return null;
+            policy.projects.push({ path: value.path, sdk: value.sdk, source: value.source, dev: value.dev, ino: value.ino });
+        }
+    }
+    return policy;
+}
+/** The components an installer's daily update kept current: the CLI and both skills packs. */
+export const DAILY_UPDATE_COMPONENTS = ["cli", "skills-cloud", "skills-dev"];
+/**
+ * An owner who turned the installer's daily update off chose not to have the CLI and the skills
+ * packs moved for them. Until they save a setting of their own for one of those, it reads as held,
+ * with source `migrated`. A saved setting always wins, and nothing is written, so a check stays
+ * read-only and a later `update policy … on` lifts it. A missing record is no evidence: no hold.
+ */
+export function withMigratedHolds(policy, dailyUpdateOff) {
+    if (!dailyUpdateOff)
+        return policy;
+    const components = { ...policy.components };
+    for (const id of DAILY_UPDATE_COMPONENTS)
+        components[id] ??= { enabled: false, source: "migrated" };
+    return { ...policy, components };
+}
+export function effectivePolicy(policy, component) {
+    const saved = policy.components[component];
+    return saved ? { enabled: saved.enabled, source: saved.source } : { enabled: true, source: "default" };
+}
+/** A project path as the policy stores it: absolute, real, and a directory. */
+export function canonicalProject(path) {
+    if (!isAbsolute(path))
+        throw new UsageError("--project must be an absolute path");
+    let real;
+    try {
+        real = realpathSync(path);
+    }
+    catch {
+        throw new CliError(`no project at ${path}`, "project-missing", 1);
+    }
+    const stat = statSync(real);
+    if (!stat.isDirectory())
+        throw new CliError(`${path} is not a directory`, "project-missing", 1);
+    return { path: real, dev: stat.dev, ino: stat.ino };
+}
+/** Whether a registered project is still the directory its owner registered. */
+export function projectIdentityHolds(project) {
+    try {
+        if (realpathSync(project.path) !== project.path)
+            return false;
+        const stat = statSync(project.path);
+        return stat.isDirectory() && stat.dev === project.dev && stat.ino === project.ino;
+    }
+    catch {
+        return false;
+    }
+}
+function takePolicyLock(lockPath, nowMs) {
+    const deadline = nowMs() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            closeSync(openSync(lockPath, "wx", 0o600));
+            return;
+        }
+        catch (err) {
+            if (!(err instanceof Error && "code" in err && err.code === "EEXIST"))
+                throw err;
+        }
+        try {
+            if (nowMs() - statSync(lockPath).mtimeMs > LOCK_STALE_MS)
+                unlinkSync(lockPath);
+        }
+        catch {
+            // gone already: try again
+        }
+        if (nowMs() > deadline)
+            throw new CliError("another command is changing the update settings; try again", "update-policy-busy", 1);
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+    }
+}
+/** Change the saved preferences under the lock: read the current file, apply `change`, replace it. */
+export function updateUpdatePolicy(home, change, nowMs = Date.now) {
+    const dir = configDirFor(home);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = updatePolicyPathFor(home);
+    const lockPath = `${path}.lock`;
+    takePolicyLock(lockPath, nowMs);
+    try {
+        const policy = readUpdatePolicy(home);
+        change(policy);
+        writePrivateAtomic(path, `${JSON.stringify(policy, null, 2)}\n`);
+        return policy;
+    }
+    finally {
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            // already released
+        }
+    }
+}
+export function setComponentPolicy(home, component, enabled) {
+    return updateUpdatePolicy(home, (policy) => {
+        policy.components[component] = { enabled, source: "owner" };
+    });
+}
+/** Register a project (or change its SDK setting). The stored path is the real path. */
+export function setProjectSdkPolicy(home, path, sdk) {
+    const project = canonicalProject(path);
+    let saved = null;
+    updateUpdatePolicy(home, (policy) => {
+        const entry = { ...project, sdk, source: "owner" };
+        const at = policy.projects.findIndex((p) => p.path === project.path);
+        if (at === -1)
+            policy.projects.push(entry);
+        else
+            policy.projects[at] = entry;
+        saved = entry;
+    });
+    return saved ?? { ...project, sdk, source: "owner" };
+}

package/dist/update-replica.js

@@ -0,0 +1,120 @@
+// update-replica.ts — a running local replica comes back on the approved CLI with its data
+// (CTC-6708). A detached writer keeps the code it started with, so after the CLI moves, a release
+// check stops the writer it can identify, waits until that process has exited and released the
+// writer lock, then starts a new writer through the person's own `catalyst` command (which runs the
+// selected version) on the same database file. Nothing here deletes, moves or reseeds the database:
+// the new writer resumes from the rows and cursor the old one left.
+//
+// It never starts a second writer: when the old one does not exit inside the deadline, or cannot be
+// identified, the restart stops there with a reason and the next check tries again. Before it stops
+// a writer it records that restart (replica-restart.json), and clears the record only once the new
+// writer reports its version, so a writer that exits after the deadline is started by the next check
+// instead of being taken for one its owner stopped. A replica that was stopped stays stopped.
+// Success is read back from the new writer's own record of the CLI version it runs.
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { configDirFor } from "./config.js";
+import { pendingRestart, pendingRestartPathFor, pidAlive, pidfilePath, replicaStatus, writerIsRunning } from "./replica.js";
+import { ACTIVE_RUNTIME_ENV } from "./update-cli.js";
+/** Whether a restart this CLI began for `dbPath` has not finished: the writer was stopped by it. */
+export function restartPending(home, dbPath) {
+    return pendingRestart(home, dbPath) !== null;
+}
+/** A writer's command line runs `replica start` (bin/launch.js keeps it in one process). */
+export function isReplicaWriter(pid) {
+    const ps = spawnSync("ps", ["-p", String(pid), "-o", "args="], { encoding: "utf8", timeout: 5_000 });
+    return ps.status === 0 && /\sreplica\s+start(\s|$)/.test(ps.stdout);
+}
+/**
+ * The command that starts the new writer. A scheduled run on Linux is a systemd oneshot service, and
+ * when it ends systemd stops every process left in its control group, a detached one included; a
+ * transient scope of the writer's own keeps it running after the release check ends.
+ */
+export function replicaStartCommand(argv, env, platform = process.platform) {
+    const node = [process.execPath, ...argv];
+    return platform === "linux" && env.INVOCATION_ID ? ["systemd-run", "--user", "--scope", "--quiet", "--", ...node] : node;
+}
+const startDetached = (argv, env) => {
+    const run = (command) => {
+        const [cmd, ...args] = command;
+        if (cmd === undefined)
+            return undefined;
+        const child = spawn(cmd, args, { detached: true, stdio: "ignore", env });
+        child.on("error", () => { });
+        child.unref();
+        return child.pid;
+    };
+    // No systemd-run on PATH: start it directly, as `replica start --detach` does.
+    const pid = run(replicaStartCommand(argv, env)) ?? run([process.execPath, ...argv]);
+    if (typeof pid !== "number")
+        throw new Error("detached spawn returned no pid");
+    return pid;
+};
+/** Restart a running replica writer on the CLI the stable command now selects, expecting `target`. */
+export async function restartReplica(ctx, cfg, target, deps) {
+    const status = deps.status ?? (() => replicaStatus(ctx, cfg));
+    const alive = deps.alive ?? pidAlive;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const timeoutMs = deps.timeoutMs ?? 60_000;
+    const pollMs = deps.pollMs ?? 250;
+    const waitFor = async (done) => {
+        for (let waited = 0;; waited += pollMs) {
+            if (done())
+                return true;
+            if (waited >= timeoutMs)
+                return false;
+            await sleep(pollMs);
+        }
+    };
+    const before = status();
+    if (before.dbPath === null)
+        return { outcome: "stopped", detail: "stopped", version: null };
+    const dbPath = before.dbPath;
+    // Stopped: by its owner (it stays stopped), or by an earlier restart that did not finish (it starts).
+    if (!writerIsRunning(before) && !restartPending(ctx.home, dbPath))
+        return { outcome: "stopped", detail: "stopped", version: null };
+    if (writerIsRunning(before)) {
+        // The writer is the process holding the lock (or recorded in its own state, or the pidfile).
+        const pid = before.lockPid ?? before.writer?.pid ?? before.pidfilePid;
+        if (pid === null || !alive(pid) || !(deps.identify ?? isReplicaWriter)(pid))
+            return { outcome: "failed", detail: "writer_unidentified", version: before.writer?.version ?? null };
+        try {
+            mkdirSync(configDirFor(ctx.home), { recursive: true, mode: 0o700 });
+            writeFileSync(pendingRestartPathFor(ctx.home), `${JSON.stringify({ dbPath, target })}\n`, { mode: 0o600 });
+        }
+        catch {
+            // Without the record a late exit would read as an owner's stop: do not stop the writer.
+            return { outcome: "failed", detail: "start_failed", version: before.writer?.version ?? null };
+        }
+        try {
+            (deps.signal ?? ((p) => process.kill(p, "SIGTERM")))(pid);
+        }
+        catch {
+            rmSync(pendingRestartPathFor(ctx.home), { force: true });
+            return { outcome: "failed", detail: "writer_unidentified", version: before.writer?.version ?? null };
+        }
+        const exited = await waitFor(() => !alive(pid) && !writerIsRunning(status()));
+        if (!exited)
+            return { outcome: "failed", detail: "stop_timeout", version: before.writer?.version ?? null };
+    }
+    // Without a staged check's marker, so the person's own command selects the version to run.
+    const env = { ...ctx.env };
+    delete env[ACTIVE_RUNTIME_ENV];
+    let started;
+    try {
+        started = (deps.start ?? startDetached)([deps.launcher, "replica", "start", "--db", dbPath], env);
+        writeFileSync(pidfilePath(dbPath), `${started}\n`);
+    }
+    catch {
+        return { outcome: "failed", detail: "start_failed", version: null };
+    }
+    let now = status();
+    const confirmed = await waitFor(() => {
+        now = status();
+        return writerIsRunning(now) && now.writer?.version === target;
+    });
+    if (!confirmed)
+        return { outcome: "failed", detail: "restart_unconfirmed", version: now.writer?.version ?? null };
+    rmSync(pendingRestartPathFor(ctx.home), { force: true });
+    return { outcome: "updated", detail: "restarted", version: target };
+}