@catalyst-cloud/cli 0.16.32 → 0.16.34

package/dist/update-skills.js

@@ -1,64 +1,263 @@
-// update-skills.ts — the Cloud skills pack moves to its approved version (CTC-6708). The pack
-// ships inside the CLI package of the same version, so a release check installs that exact CLI
-// package into its own directory (update-cli.ts's stageCliRuntime, which checks it and selects
-// nothing), checks that its bundled skills carry the approved version's stamp, and refreshes the
-// copies of those skills this install already made. That works while the CLI itself is held: the
-// pack comes from the staged package, never from the older CLI's own bundle.
-//
-// It changes only what installSkills already treats as its own: a skill folder stamped by this
-// package. A person's own skill of the same name, a symlinked entry (a plugin or the installer's
-// link) and any skill not installed yet are left as they are. Success is read back from the stamps
-// on disk.
-import { existsSync, lstatSync, readdirSync } from "node:fs";
-import { join } from "node:path";
-import { installedBundleVersion, installSkills } from "./skills.js";
+import { randomUUID } from "node:crypto";
+// Reconcile owned filesystem packs to an approved Git commit, publishing the receipt last.
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { configDirFor } from "./config.js";
 import { stageCliRuntime, stagedSkillsDir } from "./update-cli.js";
-const skillNames = (dir) => readdirSync(dir, { withFileTypes: true })
-    .filter((e) => e.isDirectory() && existsSync(join(dir, e.name, "SKILL.md")))
-    .map((e) => e.name);
-/** Stamped Cloud skills that are links: installSkills never writes through one, so copying cannot move them. */
-function linkedPackEntries(skillsDir) {
-    let entries;
+import { contentDigest, record, safeName, skillTreeHash, stageSkillSource } from "./update-skill-source.js";
+import { destinationMatches, inspectSkillInstallation, plainDirectory, readSkillLock, skillLockPath, writeSkillReceipt } from "./update-skill-state.js";
+/** One writer for receipts, adopted locks and plugin source selection. Dead owners are retryable. */
+export function withSkillUpdateLock(home, busy, run) {
+    const root = configDirFor(home);
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const lock = join(root, ".skill-update.lock");
+    const owner = JSON.stringify({ pid: process.pid, token: randomUUID() });
     try {
-        entries = readdirSync(skillsDir);
+        writeFileSync(lock, owner, { flag: "wx", mode: 0o600 });
     }
     catch {
-        return [];
-    }
-    return entries.filter((name) => {
+        // Only one reclaimer can inspect and remove a dead owner's lock. A process interrupted
+        // inside this short section leaves the guard in place and fails closed, never admits peers.
+        const reclaim = `${lock}.reclaim`;
         try {
-            return lstatSync(join(skillsDir, name)).isSymbolicLink() && installedBundleVersion(skillsDir, [name]).version !== null;
+            mkdirSync(reclaim, { mode: 0o700 });
         }
         catch {
-            return false;
+            return busy;
         }
-    });
-}
-/** Refresh the Cloud pack's installed skills in `skillsDir` to exact version `target`. */
-export function applyCloudPackUpdate(home, skillsDir, target, deps = {}) {
-    // Checked before any download, so a linked pack is not fetched again on every run.
-    if (linkedPackEntries(skillsDir).length > 0)
-        return { outcome: "linked", detail: "installation_owner_unknown", version: null };
-    const staged = stageCliRuntime(home, target, deps);
-    if (!staged.ok)
-        return { outcome: "failed", detail: staged.detail, version: null };
-    const source = stagedSkillsDir(staged.root);
-    let names;
+        try {
+            const saved = JSON.parse(readFileSync(lock, "utf8"));
+            if (!record(saved) || typeof saved.pid !== "number" || !Number.isSafeInteger(saved.pid) || saved.pid <= 0)
+                return busy;
+            try {
+                process.kill(saved.pid, 0);
+                return busy;
+            }
+            catch (error) {
+                if (!(error instanceof Error) || !("code" in error) || error.code !== "ESRCH")
+                    return busy;
+            }
+            rmSync(lock);
+            writeFileSync(lock, owner, { flag: "wx", mode: 0o600 });
+        }
+        catch {
+            return busy;
+        }
+        finally {
+            rmSync(reclaim, { recursive: true, force: true });
+        }
+    }
     try {
-        names = skillNames(source);
+        return run();
     }
-    catch {
-        return { outcome: "failed", detail: "pack_mismatch", version: null };
+    finally {
+        try {
+            if (readFileSync(lock, "utf8") === owner)
+                rmSync(lock);
+        }
+        catch { /* Another owner is never unlocked here. */ }
     }
-    // The staged package must carry exactly the approved pack, or nothing is copied.
-    if (names.length === 0 || installedBundleVersion(source, names).version !== target)
-        return { outcome: "failed", detail: "pack_mismatch", version: null };
+}
+/** Recover a durable transaction after a dead writer, validating every destination before writes. */
+function recover(home, env, pack, dir) {
+    const journal = join(configDirFor(home), ".skill-transaction.json");
+    if (!existsSync(journal))
+        return true;
     try {
-        installSkills(skillsDir, { onlyExisting: true }, source, target);
+        const raw = JSON.parse(readFileSync(journal, "utf8"));
+        if (!record(raw) || raw.pack !== pack || raw.dir !== dir || (raw.kind !== "legacy" && raw.kind !== "npx") || !Array.isArray(raw.replacements) || typeof raw.receiptBefore !== "string" && raw.receiptBefore !== null || typeof raw.lockBefore !== "string" && raw.lockBefore !== null)
+            return false;
+        if (raw.kind === "npx" && (raw.lockPath !== skillLockPath(home, env) || typeof raw.lockBefore !== "string"))
+            return false;
+        if (raw.kind === "legacy" && raw.lockPath !== undefined)
+            return false;
+        const roots = [...new Set([dir, ...[".claude", ".codex", ".cursor", ".opencode", ".config/opencode"].map((agent) => join(home, agent, "skills"))])];
+        const entries = [];
+        for (const item of raw.replacements) {
+            if (!record(item) || !record(item.destination))
+                return false;
+            const d = item.destination;
+            if (typeof d.name !== "string" || !safeName(d.name) || d.path !== join(raw.kind === "npx" ? join(home, ".agents/skills") : dir, d.name) || typeof d.digest !== "string" || !/^[a-f0-9]{64}$/.test(d.digest) || !Array.isArray(d.links) || !d.links.every((link) => typeof link === "string" && roots.some((root) => link === join(root, String(d.name)))))
+                return false;
+            const destination = { name: d.name, path: String(d.path), digest: d.digest, links: d.links, skillPath: `skills/${d.name}` };
+            if (item.backup !== `${destination.path}.catalyst-backup` || item.staged !== `${destination.path}.catalyst-staged` || !plainDirectory(dirname(destination.path)))
+                return false;
+            if (existsSync(item.backup)) {
+                if (!plainDirectory(item.backup) || contentDigest(item.backup) !== destination.digest)
+                    return false;
+                // Someone may have edited the selected files after a crash. Never discard those bytes.
+                if (raw.committed !== true && existsSync(destination.path) && (!plainDirectory(destination.path) || contentDigest(destination.path) !== item.nextDigest))
+                    return false;
+            }
+            for (const link of destination.links) {
+                try {
+                    if (!lstatSync(link).isSymbolicLink() || realpathSync(link) !== destination.path)
+                        return false;
+                }
+                catch (error) {
+                    if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT")
+                        return false;
+                }
+            }
+            entries.push({ destination, backup: item.backup, staged: item.staged });
+        }
+        if (raw.committed === true) {
+            const receipt = readFileSync(join(configDirFor(home), "skill-installations.json"), "utf8");
+            if (receipt !== raw.receiptAfter)
+                return false;
+            // The transaction already committed. Finish only its backup cleanup; selected files stay.
+            for (const item of entries) {
+                rmSync(item.backup, { recursive: true, force: true });
+                rmSync(item.staged, { recursive: true, force: true });
+            }
+            rmSync(journal);
+            return true;
+        }
+        for (const item of entries.reverse()) {
+            if (existsSync(item.backup)) {
+                rmSync(item.destination.path, { recursive: true, force: true });
+                renameSync(item.backup, item.destination.path);
+            }
+            for (const link of item.destination.links) {
+                try {
+                    lstatSync(link);
+                }
+                catch {
+                    symlinkSync(item.destination.path, link);
+                }
+            }
+            rmSync(item.staged, { recursive: true, force: true });
+        }
+        if (typeof raw.lockPath === "string" && typeof raw.lockBefore === "string") {
+            const previous = JSON.parse(raw.lockBefore);
+            const lock = readSkillLock(raw.lockPath);
+            if (!record(previous) || !record(previous.skills) || !lock)
+                return false;
+            for (const { destination } of entries)
+                lock.skills[destination.name] = previous.skills[destination.name];
+            writeFileSync(raw.lockPath, JSON.stringify(lock), { mode: 0o600 });
+        }
+        const receiptPath = join(configDirFor(home), "skill-installations.json");
+        if (raw.receiptBefore === null)
+            rmSync(receiptPath, { force: true });
+        else
+            writeFileSync(receiptPath, raw.receiptBefore, { mode: 0o600 });
+        if (!entries.every((entry) => destinationMatches(entry.destination)))
+            return false;
+        rmSync(journal);
+        return true;
     }
     catch {
-        return { outcome: "failed", detail: "install_failed", version: installedBundleVersion(skillsDir, names).version };
+        return false;
     }
-    const now = installedBundleVersion(skillsDir, names).version;
-    return now === target ? { outcome: "updated", detail: "refreshed", version: now } : { outcome: "failed", detail: "verify_failed", version: now };
+}
+export function applyPackUpdate(home, env, pack, dir, target, deps = {}) {
+    const failed = (detail) => ({ outcome: "failed", detail, version: null, commit: null });
+    return withSkillUpdateLock(home, failed("update_in_progress"), () => {
+        if (!recover(home, env, pack, dir))
+            return failed("recovery_failed");
+        const evidence = inspectSkillInstallation(home, env, pack, dir);
+        if (evidence.reason === "local_changes")
+            return failed("local_changes");
+        if (!evidence.present || !evidence.candidate)
+            return { outcome: "linked", detail: "installation_owner_unknown", version: evidence.version, commit: null };
+        if (evidence.commit === target.commit && evidence.version === target.version)
+            return { outcome: "current", detail: "current", version: evidence.version, commit: evidence.commit };
+        try {
+            if (!evidence.receipt) {
+                if (evidence.kind === "npx") {
+                    if (!evidence.destinations.every((d) => skillTreeHash(d.path, env) === d.lockHash))
+                        return failed("local_changes");
+                }
+                else {
+                    if (evidence.version === null)
+                        return failed("installation_owner_unknown");
+                    const baseline = stageCliRuntime(home, evidence.version, { ...deps.baseline, env });
+                    if (!baseline.ok)
+                        return { outcome: "linked", detail: "installation_owner_unknown", version: evidence.version };
+                    if (!evidence.destinations.every((d) => contentDigest(join(stagedSkillsDir(baseline.root), d.name)) === d.digest))
+                        return failed("local_changes");
+                }
+            }
+            const source = stageSkillSource(home, pack, target, { ...deps, env });
+            if (!source.ok)
+                return failed(source.detail);
+            const replacements = [];
+            const after = [];
+            for (const destination of evidence.destinations) {
+                const backup = `${destination.path}.catalyst-backup`, staged = `${destination.path}.catalyst-staged`;
+                if (existsSync(backup) || existsSync(staged) || !plainDirectory(dirname(destination.path)))
+                    return failed("activation_conflict");
+                const next = join(source.dir, destination.skillPath);
+                const retired = !existsSync(join(next, "SKILL.md"));
+                replacements.push({ destination, backup, staged, retired, nextDigest: retired ? null : contentDigest(next) });
+                if (!retired)
+                    after.push({ ...destination, digest: contentDigest(next), lockHash: skillTreeHash(next, env) });
+            }
+            const receiptPath = join(configDirFor(home), "skill-installations.json");
+            const receiptBefore = existsSync(receiptPath) ? readFileSync(receiptPath, "utf8") : null;
+            const lockBefore = evidence.lockPath ? readFileSync(evidence.lockPath, "utf8") : null;
+            const journal = join(configDirFor(home), ".skill-transaction.json");
+            writeFileSync(journal, JSON.stringify({ pack, dir, kind: evidence.kind, replacements, receiptBefore, lockBefore, lockPath: evidence.lockPath }), { mode: 0o600 });
+            try {
+                for (const item of replacements)
+                    if (!item.retired)
+                        cpSync(join(source.dir, item.destination.skillPath), item.staged, { recursive: true, dereference: false });
+                if (!evidence.destinations.every(destinationMatches))
+                    throw new Error("local_changes");
+                const rename = deps.rename ?? renameSync;
+                for (const item of replacements) {
+                    rename(item.destination.path, item.backup);
+                    if (!item.retired)
+                        rename(item.staged, item.destination.path);
+                    else
+                        for (const link of item.destination.links)
+                            rmSync(link);
+                }
+                if (evidence.lockPath) {
+                    if (readFileSync(evidence.lockPath, "utf8") !== lockBefore)
+                        throw new Error("lock_changed");
+                    const lock = readSkillLock(evidence.lockPath);
+                    if (!lock)
+                        throw new Error("source_mismatch");
+                    for (const d of evidence.destinations) {
+                        const next = after.find((item) => item.name === d.name);
+                        if (!next)
+                            delete lock.skills[d.name];
+                        else {
+                            const old = lock.skills[d.name];
+                            if (!record(old))
+                                throw new Error("source_mismatch");
+                            lock.skills[d.name] = { ...old, ref: target.commit, skillFolderHash: next.lockHash };
+                        }
+                    }
+                    const temporary = `${evidence.lockPath}.${process.pid}.tmp`;
+                    writeFileSync(temporary, JSON.stringify(lock), { mode: 0o600 });
+                    renameSync(temporary, evidence.lockPath);
+                }
+                if (!after.every(destinationMatches))
+                    throw new Error("verify_failed");
+                const receipt = { pack, ...target, kind: evidence.kind === "npx" ? "npx" : "legacy", dir, destinations: after, ...(evidence.lockPath ? { lockPath: evidence.lockPath } : {}) };
+                (deps.writeReceipt ?? writeSkillReceipt)(home, receipt);
+                const saved = JSON.parse(readFileSync(receiptPath, "utf8"));
+                if (!record(saved) || !record(saved.packs) || JSON.stringify(saved.packs[pack]) !== JSON.stringify(receipt) || !after.every(destinationMatches))
+                    throw new Error("verify_failed");
+                // Keep a durable committed marker until fixed-name backups are all removed.
+                const committed = `${journal}.tmp`;
+                writeFileSync(committed, JSON.stringify({ pack, dir, kind: evidence.kind, replacements, receiptBefore, lockBefore, lockPath: evidence.lockPath, committed: true, receiptAfter: readFileSync(receiptPath, "utf8") }), { mode: 0o600 });
+                renameSync(committed, journal);
+                for (const item of replacements)
+                    rmSync(item.backup, { recursive: true, force: true });
+                rmSync(journal);
+                return { outcome: "updated", detail: "approved_commit_installed", version: target.version, commit: target.commit };
+            }
+            catch (error) {
+                const restored = recover(home, env, pack, dir);
+                return failed(restored ? error instanceof Error ? error.message : "activate_failed" : "rollback_failed");
+            }
+        }
+        catch (error) {
+            return failed(error instanceof Error ? error.message : "install_failed");
+        }
+    });
 }

package/dist/update.js

@@ -8,21 +8,15 @@
 // 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.
+// Filesystem packs and the user-scope Cloud plugin reconcile exact approved Git commits.
+// CLI, SDK and image versions retain their no-downgrade policies. Each adapter verifies its own
+// installed state, while this coordinator keeps one approval read and rechecks component holds.
 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 { applyPackUpdate } 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";
@@ -148,22 +142,21 @@ function componentRows(inventory, policy, release, unavailable, crossTrain) {
         const target = release?.skills[pack] ?? null;
         const found = inventory.skills[pack];
         const approved = target?.version ?? null;
+        const evidence = found.evidence;
+        const base = { installed: evidence?.version ?? (found.state === "installed" ? found.version : null), approved, installedCommit: evidence?.commit ?? null, approvedCommit: target?.commit ?? null, action: 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 });
+            return finish(r, { ...base, status: "not_installed", reason: "not_installed" });
         if (target === null)
-            return finish(r, { installed: found.version, approved: null, status: "approval_unavailable", reason: unavailable, action: null });
+            return finish(r, { ...base, status: "approval_unavailable", reason: release ? "pack_not_approved" : unavailable });
         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,
-        });
+            return finish(r, { ...base, status: "cross_train", reason: "cross_train" });
+        if (!r.enabled)
+            return finish(r, { ...base, status: "held", reason: "owner_setting" });
+        if (!evidence?.candidate)
+            return finish(r, { ...base, status: "unknown", reason: evidence?.reason ?? "installation_owner_unknown" });
+        if (evidence.commit === target.commit && evidence.version === target.version)
+            return finish(r, { ...base, status: "current", reason: "current" });
+        return finish(r, { ...base, status: "update_available", reason: evidence.commit === null ? "commit_unrecorded" : "commit_mismatch" });
     };
     // CTC-6791: the Claude plugin form follows the Cloud pack's setting, and is listed only where it is installed.
     const pluginRow = (() => {
@@ -172,15 +165,19 @@ function componentRows(inventory, policy, release, unavailable, crossTrain) {
             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 });
+        const target = release?.skills.cloud;
+        const base = { installed: found.state === "installed" ? found.version : null, approved, installedCommit: found.state === "installed" ? found.commit : null, approvedCommit: target?.commit ?? null, action: null };
+        if (!target || !approved)
+            return finish(r, { ...base, status: "approval_unavailable", reason: release ? "pack_not_approved" : unavailable });
         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 });
+            return finish(r, { ...base, status: "cross_train", reason: "cross_train" });
+        if (!r.enabled)
+            return finish(r, { ...base, status: "held", reason: "owner_setting" });
+        if (found.state === "unknown")
+            return finish(r, { ...base, status: "unknown", reason: found.reason });
+        if (found.commit === target.commit && found.version === approved)
+            return finish(r, { ...base, status: "current", reason: "current" });
+        return finish(r, { ...base, status: "update_available", reason: found.claude === null ? "claude_not_found" : found.commit === null ? "commit_unrecorded" : "commit_mismatch", action: found.claude === null ? CLOUD_PLUGIN_COMMAND : null });
     })();
     const replica = row("replica");
     const replicaRow = (() => {
@@ -351,38 +348,42 @@ export async function runUpdate(ctx, options) {
                     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 });
+        for (const name of ["cloud", "dev"]) {
+            const id = name === "cloud" ? "skills-cloud" : "skills-dev";
+            const packRow = components.find((c) => c.id === id);
+            const pack = inventory.skills[name];
+            const target = release.skills[name];
+            if (packRow && target && pack.dir && (packRow.status === "update_available" || packRow.reason === "local_changes")) {
+                if (!effectivePolicy(readEffectivePolicy(ctx), id).enabled)
+                    Object.assign(packRow, { status: "held", reason: "owner_setting" });
+                else {
+                    const moved = (options.packApply ?? applyPackUpdate)(ctx.home, ctx.env, name, pack.dir, target);
+                    if (moved.outcome === "updated" || moved.outcome === "current")
+                        Object.assign(packRow, { status: moved.outcome, reason: moved.detail, installed: moved.version, installedCommit: moved.commit ?? null });
+                    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, installedCommit: null });
+                }
             }
         }
         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)
+        if (pluginRow && pluginRow.status === "update_available" && pluginRow.approved !== null && plugin.state === "installed" && plugin.claude !== null && release.skills.cloud) {
+            if (!effectivePolicy(readEffectivePolicy(ctx), "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 });
+                const moved = (options.pluginApply ?? applyCloudPluginUpdate)(ctx.home, ctx.env, release.skills.cloud, 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 });
+                    Object.assign(pluginRow, { status: "updated", reason: moved.detail, installed: moved.version, installedCommit: moved.commit ?? null });
                 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 (pluginRow?.reason === "local_changes" && pluginRow.policy === "on")
+            Object.assign(pluginRow, { status: "failed" });
         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) ||
@@ -463,7 +464,6 @@ const UNAVAILABLE_TEXT = {
     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) {
@@ -518,11 +518,21 @@ export function updateReportLines(report) {
     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}`);
+    for (const component of report.components) {
+        if (component.approvedCommit && component.status !== "not_installed")
+            lines.push(`${COMPONENT_LABELS[component.id]} commit: ${component.installedCommit ?? "unknown"} -> ${component.approvedCommit}`);
+        if (component.reason === "pack_not_approved")
+            lines.push(`${COMPONENT_LABELS[component.id]}: no approved pack was provided; the installed pack was kept.`);
+        if (component.status === "failed" && component.approvedCommit)
+            lines.push(`${COMPONENT_LABELS[component.id]}: the approved commit was not installed (${component.reason}).${component.reason === "local_changes" ? " Local changes were kept." : ""} Run catalyst update --check --json to inspect the result.`);
+    }
     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}`);
+            lines.push(c.id === "skills-cloud-plugin" && c.reason === "claude_not_found"
+                ? `Cloud skills plugin: Claude Code was not found. Make the claude command available, then run catalyst update.`
+                : `${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}`);

package/package.json

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

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

@@ -17,11 +17,12 @@ Global (`-g`) installs go to `~/.agents/skills/`, linked from `~/.claude/skills/
 
 ## 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.
+Check installed components with `catalyst update --check --json`. For each installed skills pack and Cloud plugin, compare `installedCommit` with `approvedCommit` and read its status and reason. A matching version alone does not prove the approved skills are installed.
+When the person asks to update, run `catalyst update`. Keep every saved component hold. Do not turn a hold off without the person's instruction.
+If the report says `pack_not_approved`, keep that pack and explain that the approved release does not name it. Do not substitute a repository's newest commit or schedule a raw `npx skills add` command.
+If ownership is unknown or local changes are reported, keep those files and show the reason. Do not force a replacement.
 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.
+After a Cloud plugin update, run `/reload-plugins` in Claude Code or start a new session to load it.
 
 ## Is each pack there
 

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

package/skills/unstick/SKILL.md

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

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

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

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

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