@catalyst-cloud/cli 0.16.30 → 0.16.31

package/dist/update.js

@@ -0,0 +1,586 @@
+// update.ts — one release check for every component an install keeps (CTC-6708). It reads what is
+// installed, reads the approved release once, and decides for each component on its own: current,
+// behind, held by the owner's setting, newer than approved, absent, or unknown with a reason. A held
+// or failed component never blocks the others, and nothing in a check changes the machine.
+//
+// The approved record comes from one read: the enrolled machine's desired-release answer when a
+// runner is installed (its images and its `components` share one snapshot), else the signed-in
+// member route. The runner, supervisor and watchdog move through runner-update.ts's engine with that
+// same read, so the image half and the component half can never come from different approvals.
+//
+// This CLI applies the image components itself, moves the CLI to the approved version (installed
+// beside the running one and selected through the person's own command: update-cli.ts), and then
+// restarts a running local replica on it with its data (update-replica.ts). The Cloud skills pack
+// moves to its own approved version from that version's package, even while the CLI is held
+// (update-skills.ts), and its Claude plugin form moves through Claude Code when the plugin's
+// marketplace serves the approved version (update-plugin.ts). The Dev pack carries no version this CLI can read, so it is reported, never
+// moved. A project's SDK is reported
+// with its update command; an applying run changes a project's files only when its owner turned that
+// project's SDK updates on, and a check never does.
+import { compareVersions, hostApproval, readApprovalCache, readMemberApproval, supportedReleaseLine, writeApprovalCache, } from "./approved-release.js";
+import { loadConfig } from "./config.js";
+import { applyCliUpdate } from "./update-cli.js";
+import { readInventory } from "./update-inventory.js";
+import { restartPending, restartReplica } from "./update-replica.js";
+import { applyCloudPackUpdate } from "./update-skills.js";
+import { applyCloudPluginUpdate, CLOUD_PLUGIN_COMMAND } from "./update-plugin.js";
+import { onboardStatePath, readOnboardJournal } from "./onboard.js";
+import { effectivePolicy, projectIdentityHolds, readUpdatePolicy, UPDATE_COMPONENTS, withMigratedHolds, } from "./update-policy.js";
+import { applySdkUpdate, inspectSdkProject } from "./update-sdk.js";
+import { decideRelease, isRecord, parseDesiredRelease, RELEASE_COMPONENTS, runRunnerUpdate, } from "./runner-update.js";
+export const COMPONENT_LABELS = {
+    runner: "Runner",
+    supervisor: "Supervisor",
+    watchdog: "Watchdog",
+    cli: "CLI",
+    "skills-cloud": "Cloud skills",
+    "skills-cloud-plugin": "Cloud skills plugin",
+    "skills-dev": "Dev skills",
+    replica: "Local replica",
+};
+const SDK_LABELS = {
+    "@catalyst-cloud/sdk": "SDK",
+    "@catalyst-cloud/sdk-replica-node": "SDK replica (Node)",
+    "@catalyst-cloud/sdk-replica-browser": "SDK replica (browser)",
+};
+/** Setup's record says the owner turned the installer's daily update off. Unreadable is no evidence. */
+function dailyUpdateOff(ctx) {
+    try {
+        return readOnboardJournal(onboardStatePath(ctx.home, ctx.env))?.dailyUpdate?.state === "off";
+    }
+    catch {
+        return false;
+    }
+}
+/** The owner's saved settings, with the holds their setup choices carry (update-policy.ts). */
+export function readEffectivePolicy(ctx) {
+    return withMigratedHolds(readUpdatePolicy(ctx.home), dailyUpdateOff(ctx));
+}
+/** An engine whose desired-release read happens once per pass, however many readers ask. */
+export function sharedReleaseRead(engine) {
+    const reads = new Map();
+    const read = (dir, signal) => {
+        let pending = reads.get(dir);
+        if (!pending) {
+            pending = engine.desiredRelease(dir, signal);
+            reads.set(dir, pending);
+        }
+        return pending;
+    };
+    return { ...engine, desiredRelease: read, read: (dir) => read(dir) };
+}
+function imageApproval(read) {
+    const decision = decideRelease(null, read);
+    if (decision.action === "retain")
+        return { release: null, reason: decision.reason };
+    const body = read.kind === "answered" && isRecord(read.body) ? read.body.release : null;
+    return { release: parseDesiredRelease(body), reason: "approved" };
+}
+const shortDigest = (reference) => reference.slice(reference.indexOf("@") + 1, reference.indexOf("@") + 20);
+function versionStatus(installed, approved, enabled) {
+    const order = compareVersions(installed, approved);
+    if (order === 0)
+        return { status: "current", reason: "current" };
+    if (order > 0)
+        return { status: "installed_newer", reason: "installed_newer" };
+    return enabled ? { status: "update_available", reason: "behind_approved" } : { status: "held", reason: "owner_setting" };
+}
+function imageRows(inventory, policy, approval) {
+    return RELEASE_COMPONENTS.map((id) => {
+        const p = effectivePolicy(policy, id);
+        const row = { id, policy: p.enabled ? "on" : "off", policySource: p.source, action: null };
+        const images = inventory.images;
+        if (!images.installed)
+            return { ...row, installed: null, approved: null, status: "not_installed", reason: "not_installed" };
+        const installedRef = images.references[id];
+        const release = approval?.release ?? null;
+        const approvedRef = release?.images[id].reference ?? null;
+        const installedLabel = installedRef === null
+            ? null
+            : release && installedRef === approvedRef
+                ? `generation ${release.generation}`
+                : images.generation !== null
+                    ? `generation ${images.generation}`
+                    : shortDigest(installedRef);
+        const base = {
+            ...row,
+            installed: installedLabel,
+            approved: release ? `generation ${release.generation}` : null,
+            installedReference: installedRef,
+            approvedReference: approvedRef,
+        };
+        if (installedRef === null)
+            return { ...base, status: "unknown", reason: "image_unreadable" };
+        if (!release)
+            return { ...base, status: "approval_unavailable", reason: approval?.reason ?? "approval_unavailable" };
+        if (installedRef === approvedRef)
+            return { ...base, status: "current", reason: "current" };
+        if (images.generation !== null && images.generation > release.generation)
+            return { ...base, status: "installed_newer", reason: "not_newer" };
+        return p.enabled ? { ...base, status: "update_available", reason: "behind_approved" } : { ...base, status: "held", reason: "owner_setting" };
+    });
+}
+function componentRows(inventory, policy, release, unavailable, crossTrain) {
+    const row = (id) => {
+        const p = effectivePolicy(policy, id);
+        return { id, policy: p.enabled ? "on" : "off", policySource: p.source, enabled: p.enabled };
+    };
+    const finish = (r, rest) => ({
+        id: r.id,
+        policy: r.policy,
+        policySource: r.policySource,
+        ...rest,
+    });
+    const cliTarget = release?.members.cli ?? null;
+    const cli = row("cli");
+    const cliRow = (() => {
+        const installed = inventory.cli.version;
+        if (cliTarget === null)
+            return finish(cli, { installed, approved: null, status: "approval_unavailable", reason: unavailable, action: null });
+        if (crossTrain)
+            return finish(cli, { installed, approved: cliTarget, status: "cross_train", reason: "cross_train", action: null });
+        // An applying run moves the CLI itself: no command to hand the owner.
+        return finish(cli, { installed, approved: cliTarget, ...versionStatus(installed, cliTarget, cli.enabled), action: null });
+    })();
+    const packRow = (id, pack) => {
+        const r = row(id);
+        const target = release?.skills[pack] ?? null;
+        const found = inventory.skills[pack];
+        const approved = target?.version ?? null;
+        if (found.state === "not_installed")
+            return finish(r, { installed: null, approved, status: "not_installed", reason: "not_installed", action: null });
+        if (found.state === "unknown")
+            return finish(r, { installed: null, approved, status: "unknown", reason: found.reason, action: null });
+        if (target === null)
+            return finish(r, { installed: found.version, approved: null, status: "approval_unavailable", reason: unavailable, action: null });
+        if (crossTrain)
+            return finish(r, { installed: found.version, approved, status: "cross_train", reason: "cross_train", action: null });
+        const decided = versionStatus(found.version, target.version, r.enabled);
+        return finish(r, {
+            installed: found.version,
+            approved,
+            ...decided,
+            // An applying run moves the Cloud pack itself; the Dev pack's command is the owner's to run.
+            action: decided.status === "update_available" && pack === "dev" ? `npx skills add https://github.com/${target.repository}/tree/${target.commit} --all -g` : null,
+        });
+    };
+    // CTC-6791: the Claude plugin form follows the Cloud pack's setting, and is listed only where it is installed.
+    const pluginRow = (() => {
+        const found = inventory.plugin;
+        if (found.state === "not_installed")
+            return null;
+        const r = { ...row("skills-cloud"), id: "skills-cloud-plugin" };
+        const approved = release?.members.plugin ?? null;
+        if (found.state === "unknown")
+            return finish(r, { installed: null, approved, status: "unknown", reason: found.reason, action: null });
+        if (approved === null)
+            return finish(r, { installed: found.version, approved: null, status: "approval_unavailable", reason: unavailable, action: null });
+        if (crossTrain)
+            return finish(r, { installed: found.version, approved, status: "cross_train", reason: "cross_train", action: null });
+        const decided = versionStatus(found.version, approved, r.enabled);
+        // An applying run moves it through Claude Code; with no `claude` command found, the owner runs it.
+        return finish(r, { installed: found.version, approved, ...decided, action: decided.status === "update_available" && found.claude === null ? CLOUD_PLUGIN_COMMAND : null });
+    })();
+    const replica = row("replica");
+    const replicaRow = (() => {
+        const found = inventory.replica;
+        if (found.state === "not_installed")
+            return finish(replica, { installed: null, approved: cliTarget, status: "not_installed", reason: "not_installed", action: null });
+        if (found.state === "unknown")
+            return finish(replica, { installed: null, approved: cliTarget, status: "unknown", reason: found.reason, action: null });
+        if (found.state === "stopped")
+            return finish(replica, { installed: null, approved: cliTarget, status: "stopped", reason: "stopped", action: null });
+        if (cliTarget === null)
+            return finish(replica, { installed: found.version, approved: null, status: "approval_unavailable", reason: unavailable, action: null });
+        if (crossTrain)
+            return finish(replica, { installed: found.version, approved: cliTarget, status: "cross_train", reason: "cross_train", action: null });
+        // CTC-6743: a running writer that recorded no version started on a CLI from before writers
+        // recorded one, so it is older than any approved CLI and restarts like any other old writer.
+        const order = found.version === null ? -1 : compareVersions(found.version, cliTarget);
+        const base = { installed: found.version, approved: cliTarget, action: null };
+        if (order === 0)
+            return finish(replica, { ...base, status: "current", reason: "current" });
+        if (order > 0)
+            return finish(replica, { ...base, status: "installed_newer", reason: "installed_newer" });
+        if (!replica.enabled)
+            return finish(replica, { ...base, status: "held", reason: "owner_setting" });
+        // The replica runs on the installed CLI: it moves when the CLI does.
+        if (compareVersions(inventory.cli.version, cliTarget) < 0)
+            return cli.enabled
+                ? finish(replica, { ...base, status: "restart_after_cli", reason: "cli_update_pending" })
+                : finish(replica, { ...base, status: "waiting_for_cli", reason: "dependency_held" });
+        return finish(replica, { ...base, status: "update_available", reason: "restart_needed" });
+    })();
+    return [cliRow, packRow("skills-cloud", "cloud"), ...(pluginRow ? [pluginRow] : []), packRow("skills-dev", "dev"), replicaRow];
+}
+function projectReports(policy, release, extra) {
+    const reports = [];
+    for (const project of policy.projects) {
+        if (!projectIdentityHolds(project)) {
+            reports.push({
+                path: project.path,
+                packageManager: null,
+                packages: [],
+                status: "unknown",
+                reason: "project_identity_changed",
+                command: null,
+                packageManagerCommand: null,
+                registered: true,
+                policy: project.sdk,
+                applied: null,
+            });
+            continue;
+        }
+        reports.push({ ...inspectSdkProject(project.path, release), registered: true, policy: project.sdk, applied: null });
+    }
+    if (extra !== undefined && !reports.some((r) => r.path === extra))
+        reports.push({ ...inspectSdkProject(extra, release), registered: false, policy: "notify", applied: null });
+    return reports;
+}
+/** Map the image engine's result onto the three image rows it moved. */
+function applyImageResult(rows, result) {
+    for (const row of rows) {
+        if (row.status === "not_installed")
+            continue;
+        if (result.outcome === "updated" || result.outcome === "recorded") {
+            row.status = "updated";
+            row.reason = result.outcome;
+            row.installed = row.approved;
+            row.installedReference = row.approvedReference ?? row.installedReference ?? null;
+        }
+        else if (result.outcome === "deferred_busy" || result.outcome === "retained") {
+            if (row.status === "update_available") {
+                row.status = "pending";
+                row.reason = result.detail;
+            }
+        }
+        else if (result.outcome === "failed" || result.outcome === "rolled_back") {
+            if (row.status === "update_available") {
+                row.status = "failed";
+                row.reason = result.detail;
+            }
+        }
+    }
+}
+function aggregateExit(report) {
+    if (report.components.some((c) => c.status === "failed"))
+        return 1;
+    if (report.projects.some((p) => p.applied?.outcome === "failed"))
+        return 1;
+    if (report.images && report.images.exitCode !== 0)
+        return 1;
+    // No usable approval for anything: the check could not answer.
+    const imagesAnswered = report.components.some((c) => RELEASE_COMPONENTS.some((id) => id === c.id) && c.approved !== null);
+    if (report.unavailable && !imagesAnswered)
+        return 1;
+    // Applying: an enabled component that is behind and that this CLI does not move needs the owner.
+    if (report.mode === "apply" && report.components.some((c) => c.status === "update_available" && c.action !== null))
+        return 1;
+    return 0;
+}
+/** One release check. Check mode reads only: no lock, no cache, no settings and no install change. */
+export async function runUpdate(ctx, options) {
+    const policy = readEffectivePolicy(ctx);
+    const inventory = readInventory(ctx, options.imagesDir);
+    let engine = null;
+    let approval;
+    let images = null;
+    if (inventory.images.installed) {
+        engine = sharedReleaseRead(options.engine());
+        const read = await engine.read(options.imagesDir);
+        images = imageApproval(read);
+        approval = hostApproval(read);
+        // The runner's own read failed (Docker stopped, say): a signed-in CLI can still ask the member
+        // route. Its answer names the components; the images keep the host's verdict.
+        if (approval.kind === "unavailable" && (approval.reason === "host_unreadable" || approval.reason === "unreachable")) {
+            const member = await readMemberApproval(ctx);
+            if (member.kind === "approved" || member.reason !== "signed_out")
+                approval = member;
+        }
+    }
+    else {
+        approval = await readMemberApproval(ctx);
+    }
+    const release = approval.kind === "approved" ? approval.release : null;
+    const supported = supportedReleaseLine();
+    const crossTrain = release !== null && release.releaseLine !== supported ? { supported, approved: release.releaseLine } : null;
+    const unavailableReason = approval.kind === "unavailable" ? approval.reason : "approval_unavailable";
+    const cached = approval.kind === "unavailable" ? readApprovalCache(ctx.home) : null;
+    const imageList = imageRows(inventory, policy, crossTrain ? { release: null, reason: "cross_train" } : images);
+    const components = [...imageList, ...componentRows(inventory, policy, release, unavailableReason, crossTrain !== null)];
+    // A writer an earlier restart stopped is not one its owner stopped: it is started again.
+    const stoppedRow = components.find((c) => c.id === "replica" && c.status === "stopped");
+    if (stoppedRow && inventory.replica.state === "stopped" && restartPending(ctx.home, inventory.replica.dbPath))
+        Object.assign(stoppedRow, { status: "pending", reason: "restart_interrupted" });
+    const projects = projectReports(policy, crossTrain ? null : release, options.project);
+    let imageResult = options.imageResult ?? null;
+    if (options.mode === "apply" && engine !== null && imageResult === null && crossTrain === null) {
+        // Re-read the owner's settings just before anything moves: a hold set during the read wins.
+        const current = readEffectivePolicy(ctx);
+        const held = RELEASE_COMPONENTS.filter((id) => !effectivePolicy(current, id).enabled);
+        if (held.length === 0) {
+            imageResult = await runRunnerUpdate(engine, { dir: options.imagesDir });
+            applyImageResult(imageList, imageResult);
+        }
+        else {
+            // The image engine moves all three together; one held image holds its peers until it is lifted.
+            for (const row of imageList)
+                if (row.status === "update_available") {
+                    row.status = "held";
+                    row.reason = "peer_image_held";
+                }
+        }
+    }
+    if (options.mode === "apply" && release !== null && crossTrain === null) {
+        // Re-read the owner's settings just before the CLI and replica move: a hold set during the read wins.
+        const current = readEffectivePolicy(ctx);
+        const cliRow = components.find((c) => c.id === "cli");
+        const replicaRow = components.find((c) => c.id === "replica");
+        if (cliRow && cliRow.status === "update_available" && cliRow.approved !== null) {
+            if (!effectivePolicy(current, "cli").enabled)
+                Object.assign(cliRow, { status: "held", reason: "owner_setting" });
+            else {
+                const moved = (options.cliApply ?? applyCliUpdate)(ctx.home, inventory.cli.version, cliRow.approved);
+                if (moved.outcome === "failed")
+                    Object.assign(cliRow, { status: "failed", reason: moved.detail });
+                else if (moved.outcome === "current")
+                    // Already selected (or newer): the person's own command runs `moved.version`.
+                    Object.assign(cliRow, { status: moved.detail === "installed_newer" ? "installed_newer" : "current", reason: moved.detail, installed: moved.version });
+                else
+                    Object.assign(cliRow, { status: "updated", reason: moved.detail, installed: moved.version });
+            }
+        }
+        const packRow = components.find((c) => c.id === "skills-cloud");
+        const pack = inventory.skills.cloud;
+        if (packRow && packRow.status === "update_available" && packRow.approved !== null && pack.state === "installed") {
+            if (!effectivePolicy(current, "skills-cloud").enabled)
+                Object.assign(packRow, { status: "held", reason: "owner_setting" });
+            else {
+                const moved = (options.packApply ?? applyCloudPackUpdate)(ctx.home, pack.dir, packRow.approved);
+                if (moved.outcome === "updated")
+                    Object.assign(packRow, { status: "updated", reason: moved.detail, installed: moved.version });
+                else if (moved.outcome === "linked")
+                    Object.assign(packRow, { status: "unknown", reason: moved.detail });
+                else
+                    Object.assign(packRow, { status: "failed", reason: moved.detail, installed: moved.version ?? packRow.installed });
+            }
+        }
+        const pluginRow = components.find((c) => c.id === "skills-cloud-plugin");
+        const plugin = inventory.plugin;
+        if (pluginRow && pluginRow.status === "update_available" && pluginRow.approved !== null && plugin.state === "installed" && plugin.claude !== null) {
+            if (!effectivePolicy(current, "skills-cloud").enabled)
+                Object.assign(pluginRow, { status: "held", reason: "owner_setting" });
+            else {
+                const moved = (options.pluginApply ?? applyCloudPluginUpdate)(ctx.home, ctx.env, pluginRow.approved, plugin.scope, { claudePath: plugin.claude });
+                if (moved.outcome === "updated")
+                    Object.assign(pluginRow, { status: "updated", reason: moved.detail, installed: moved.version });
+                else if (moved.outcome === "waiting")
+                    Object.assign(pluginRow, { status: "pending", reason: moved.detail });
+                else if (moved.outcome === "no_claude")
+                    Object.assign(pluginRow, { action: CLOUD_PLUGIN_COMMAND });
+                else
+                    Object.assign(pluginRow, { status: "failed", reason: moved.detail, installed: moved.version ?? pluginRow.installed });
+            }
+        }
+        if (replicaRow && replicaRow.approved !== null) {
+            const cliRuns = cliRow?.status === "updated" || cliRow?.status === "current" || cliRow?.status === "installed_newer";
+            const due = (replicaRow.status === "restart_after_cli" && cliRuns) ||
+                (replicaRow.status === "update_available" && replicaRow.reason === "restart_needed") ||
+                (replicaRow.status === "pending" && replicaRow.reason === "restart_interrupted");
+            if (replicaRow.status === "restart_after_cli" && cliRow?.status === "failed")
+                Object.assign(replicaRow, { status: "pending", reason: "cli_update_failed" });
+            else if (due && !effectivePolicy(current, "replica").enabled)
+                Object.assign(replicaRow, { status: "held", reason: "owner_setting" });
+            else if (due) {
+                const restart = options.replicaRestart ??
+                    (async (target) => {
+                        const cfg = loadConfig(ctx.home);
+                        // The person's own `catalyst`: it loads the selected version itself (bin/launch.js).
+                        const launcher = process.argv[1];
+                        if (!cfg || launcher === undefined)
+                            return { outcome: "failed", detail: "writer_unidentified", version: null };
+                        return restartReplica(ctx, cfg, target, { launcher });
+                    });
+                // The version the person's own command runs now, which the new writer must report.
+                const target = cliRuns ? (cliRow?.installed ?? replicaRow.approved) : inventory.cli.version;
+                const restarted = await restart(target);
+                if (restarted.outcome === "updated")
+                    Object.assign(replicaRow, { status: "updated", reason: restarted.detail, installed: restarted.version });
+                else if (restarted.outcome === "stopped")
+                    Object.assign(replicaRow, { status: "stopped", reason: "stopped", installed: null });
+                else
+                    Object.assign(replicaRow, { status: "failed", reason: restarted.detail, installed: restarted.version ?? replicaRow.installed });
+            }
+        }
+        // Only a project whose owner turned its SDK updates on, still the directory they registered.
+        for (const project of projects)
+            if (project.registered && project.policy === "auto" && project.status === "update_available") {
+                const result = applySdkUpdate(ctx.home, project.path, release, options.sdkExec);
+                Object.assign(project, result.project, { applied: { outcome: result.outcome, detail: result.detail, moved: result.moved } });
+            }
+    }
+    if (options.mode === "apply" && release !== null)
+        writeApprovalCache(ctx.home, { observedAtMs: ctx.now().getTime(), release });
+    const report = {
+        schemaVersion: 1,
+        mode: options.mode,
+        release: release ? { id: release.approvalId, generation: release.generation, releaseLine: release.releaseLine, source: approval.kind === "approved" ? approval.source : "network" } : null,
+        unavailable: approval.kind === "unavailable"
+            ? {
+                reason: approval.reason,
+                lastObserved: cached ? { id: cached.release.approvalId, generation: cached.release.generation, observedAtMs: cached.observedAtMs } : null,
+            }
+            : null,
+        crossTrain,
+        components,
+        projects,
+        images: imageResult,
+        approved: release,
+    };
+    return { ...report, exitCode: aggregateExit(report) };
+}
+const STATUS_TEXT = {
+    current: () => "current",
+    update_available: () => "update available",
+    held: (c) => (c.reason === "peer_image_held" ? "held with a held image" : "held by owner's setting"),
+    not_installed: () => "not installed",
+    unknown: (c) => `unknown (${c.reason})`,
+    installed_newer: () => "newer than approved; kept",
+    approval_unavailable: () => "no approved version",
+    restart_after_cli: () => "restart after CLI update",
+    waiting_for_cli: (c) => `waiting for CLI ${c.approved ?? "update"}`,
+    stopped: () => "stopped; stays stopped",
+    cross_train: () => "kept on this train",
+    updated: () => "updated",
+    pending: (c) => `waiting (${c.reason})`,
+    failed: (c) => `failed (${c.reason})`,
+};
+const UNAVAILABLE_TEXT = {
+    signed_out: "sign in with catalyst login.",
+    host_unreadable: "this machine's runner could not read it; check that Docker is running.",
+    credential_refused: "sign in with catalyst login.",
+    unreachable: "the service could not be reached.",
+    not_provided: "this workspace does not yet provide component versions.",
+    response_invalid: "the service sent a release this CLI cannot read.",
+    envelope_mismatch: "the image and component approvals name different releases.",
+};
+const cell = (text, width) => (text.length >= width ? `${text} ` : text.padEnd(width));
+function sdkRows(project) {
+    if (project.packages.length === 0)
+        return [{ label: `SDK ${project.path}`, installed: "-", approved: "-", status: project.status === "no_sdk" ? "no SDK declared" : `unknown (${project.reason})` }];
+    const status = project.applied
+        ? project.applied.outcome === "updated"
+            ? "updated"
+            : project.applied.outcome === "failed"
+                ? `failed (${project.applied.detail}); package files put back`
+                : `not changed (${project.applied.detail})`
+        : project.status === "update_available"
+            ? project.policy === "notify"
+                ? "notification only"
+                : "update available"
+            : project.status === "unknown"
+                ? `unknown (${project.reason})`
+                : project.status === "approval_unavailable"
+                    ? "no approved version"
+                    : project.status === "installed_newer"
+                        ? "newer than approved; kept"
+                        : "current";
+    return project.packages.map((p) => ({
+        label: `${SDK_LABELS[p.name] ?? p.name} ${project.path}`,
+        installed: p.installed ?? p.locked ?? p.declared,
+        approved: p.approved ?? "-",
+        status,
+    }));
+}
+/** The person-readable report: a header, one row per component and SDK package, then what to run. */
+export function updateReportLines(report) {
+    const lines = [];
+    const unchanged = report.mode === "check" ? "Nothing was changed." : null;
+    if (report.release) {
+        lines.push(`Approved release: ${report.release.id}, generation ${report.release.generation}, train ${report.release.releaseLine}`);
+    }
+    else if (report.unavailable) {
+        lines.push(`Approved release unavailable: ${UNAVAILABLE_TEXT[report.unavailable.reason]}`);
+        if (report.unavailable.lastObserved)
+            lines.push(`Last observed release: ${report.unavailable.lastObserved.id}, generation ${report.unavailable.lastObserved.generation}. It was not used to apply updates.`);
+        const anyImage = report.components.some((c) => c.approved !== null);
+        if (!anyImage) {
+            lines.push(report.mode === "check" ? "Nothing was changed." : "No components were changed.");
+            return lines;
+        }
+    }
+    if (report.crossTrain)
+        lines.push(`Automatic updates stay on train ${report.crossTrain.supported}. The approved release is on train ${report.crossTrain.approved}; no components were changed.`);
+    lines.push(`${cell("Component", 19)}${cell("Installed", 16)}${cell("Approved", 16)}Status`);
+    for (const c of report.components)
+        lines.push(`${cell(COMPONENT_LABELS[c.id], 19)}${cell(c.installed ?? "-", 16)}${cell(c.approved ?? "-", 16)}${STATUS_TEXT[c.status](c)}`);
+    for (const project of report.projects)
+        for (const r of sdkRows(project))
+            lines.push(`${cell(r.label, 19)}${cell(r.installed, 16)}${cell(r.approved, 16)}${r.status}`);
+    if (report.projects.length === 0)
+        lines.push("SDK projects: none registered");
+    for (const c of report.components)
+        if (c.action !== null && (c.status === "update_available" || c.status === "pending"))
+            lines.push(`${COMPONENT_LABELS[c.id]}: this CLI does not install ${c.approved ?? "it"} by itself yet. Run: ${c.action}`);
+    for (const project of report.projects)
+        if (project.command !== null && project.applied?.outcome !== "updated")
+            lines.push(`Update this project's SDK: ${project.command}`);
+    // CTC-6741: a failed CLI move leaves the running version in place; say so, and when it is tried again.
+    const cli = report.components.find((c) => c.id === "cli");
+    if (cli?.status === "failed")
+        lines.push(`CLI: the update to ${cli.approved ?? "the approved version"} failed (${cli.reason}). You keep running ${cli.installed ?? "the installed version"}. The next release check tries again: within 15 minutes when automatic updates are on, or run catalyst update.`);
+    const plugin = report.components.find((c) => c.id === "skills-cloud-plugin");
+    if (plugin?.status === "updated")
+        lines.push(`Cloud skills plugin: run /reload-plugins in Claude Code, or restart it, to load ${plugin.installed ?? plugin.approved}.`);
+    if (unchanged)
+        lines.push("Checked the approved release; nothing was changed.");
+    else {
+        const held = report.components.some((c) => c.status === "held" || c.status === "waiting_for_cli");
+        lines.push(report.exitCode !== 0
+            ? "Release check finished with components that need attention."
+            : held
+                ? "Release check finished with held components."
+                : "Release check finished.");
+    }
+    return lines;
+}
+/** The report as `--json` prints it: the decision model, without internal engine detail. */
+export function updateReportJson(report) {
+    return {
+        schemaVersion: report.schemaVersion,
+        mode: report.mode,
+        release: report.release,
+        unavailable: report.unavailable,
+        crossTrain: report.crossTrain,
+        // CTC-6792: the commit each skills pack was approved at, so the installer's daily job installs
+        // exactly that commit. Null when no release was read, or when it is on another train.
+        approvedSkills: report.approved !== null && report.crossTrain === null ? report.approved.skills : null,
+        components: report.components,
+        projects: report.projects.map((p) => ({
+            path: p.path,
+            registered: p.registered,
+            policy: p.policy,
+            packageManager: p.packageManager,
+            packages: p.packages,
+            status: p.status,
+            reason: p.reason,
+            command: p.command,
+            packageManagerCommand: p.packageManagerCommand,
+            applied: p.applied,
+        })),
+        exitCode: report.exitCode,
+    };
+}
+/** Every component's effective setting, for `catalyst update policy`. */
+export function policyLines(policy) {
+    const lines = ["Automatic updates:"];
+    for (const id of UPDATE_COMPONENTS) {
+        const p = effectivePolicy(policy, id);
+        lines.push(`${cell(COMPONENT_LABELS[id], 19)}${cell(p.enabled ? "on" : "off", 5)}(${p.source})`);
+    }
+    if (policy.projects.length === 0)
+        lines.push("SDK projects: none registered");
+    for (const project of policy.projects)
+        lines.push(`${cell(`SDK ${project.path}`, 19)}${cell(project.sdk === "auto" ? "on" : "off", 5)}(${project.source}${project.sdk === "notify" ? ", notify only" : ""})`);
+    return lines;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.16.30",
+  "version": "0.16.31",
   "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.30 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.31 — 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.30 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.31 — 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.30 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.31 — written in this repository for customer accounts -->
 
 # Onboard me
 

package/skills/catalyst-onboard/references/skill-sources.md

@@ -15,6 +15,14 @@ Global (`-g`) installs go to `~/.agents/skills/`, linked from `~/.claude/skills/
 
 `npx skills add --all` replaces same-named directories and links. Before running it on an existing machine, inspect every same-named destination and proceed only when each is absent or a verified, unmodified copy of the intended pack (a lock entry verifies nothing on disk). Resolve any other copy first. Schedule only the installer, never raw add commands.
 
+## Keeping each pack current
+
+Check installed components with `catalyst update --check --json`. Read each component's installed version, approved version, status and reason.
+Apply enabled updates with `catalyst update` when the person asks you to update. For a component it does not install itself, it prints the exact command; offer that command the same way.
+Keep every saved component hold. Do not turn a hold off without the person's instruction.
+For a project's SDK, run `catalyst update --check --project <absolute project path>` and show the command it names. Run that command only when the person asks to update that project.
+After a plugin update, start a new agent session to load the installed version.
+
 ## Is each pack there
 
 `catalyst ready` checks the Cloud pack only. Look for `catalyst-onboard/SKILL.md` (Cloud) and `research-codebase/SKILL.md` (development) in the intended directory.

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.30 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.31 — written in this repository for customer accounts -->
 
 # Run this project