@catalyst-cloud/cli 0.16.33 → 0.16.35

package/dist/update-plugin.js

@@ -1,64 +1,131 @@
-// 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";
+// Select the verified approved Cloud checkout through Claude's supported marketplace commands.
+import { accessSync, constants, existsSync, readFileSync } from "node:fs";
+import { delimiter, dirname, join, resolve } from "node:path";
 import { exactVersion } from "./approved-release.js";
 import { spawnCliCommand } from "./update-cli.js";
+import { contentDigest, record, repositoryFor, skillReleaseDir, stageSkillSource, verifiedSkillSource } from "./update-skill-source.js";
+import { plainDirectory } from "./update-skill-state.js";
+import { withSkillUpdateLock } from "./update-skills.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");
+export const CLOUD_PLUGIN_COMMAND = "catalyst update";
+export function claudeConfigDir(home, env) { return env.CLAUDE_CONFIG_DIR || join(home, ".claude"); }
+const readJson = (path) => JSON.parse(readFileSync(path, "utf8"));
+const cloudGitSource = (source) => {
+    if (source.source === "github" && source.repo === repositoryFor("cloud"))
+        return `https://github.com/${repositoryFor("cloud")}.git`;
+    if (source.source === "git" && (source.url === `https://github.com/${repositoryFor("cloud")}.git` || source.url === `https://github.com/${repositoryFor("cloud")}`))
+        return String(source.url);
+    return null;
+};
+/** A project or managed declaration must not be redirected by a home-directory updater. */
+function hasOverride(home, env, entries) {
+    if (entries.some((entry) => !record(entry) || entry.scope !== "user"))
+        return true;
+    const config = claudeConfigDir(home, env);
+    const files = [join(config, "managed-settings.json"), join(config, "settings.local.json")];
+    if (process.platform === "linux")
+        files.push("/etc/claude-code/managed-settings.json");
+    if (process.platform === "darwin")
+        files.push("/Library/Application Support/ClaudeCode/managed-settings.json");
+    if (process.platform === "win32" && env.ProgramFiles)
+        files.push(join(env.ProgramFiles, "ClaudeCode/managed-settings.json"));
+    // Claude records project identity even when another plugin owns that scope.
+    const registry = readJson(join(config, "plugins/installed_plugins.json"));
+    if (record(registry) && record(registry.plugins))
+        for (const values of Object.values(registry.plugins)) {
+            if (!Array.isArray(values))
+                continue;
+            for (const value of values)
+                if (record(value) && typeof value.projectPath === "string") {
+                    files.push(join(value.projectPath, ".claude/settings.json"), join(value.projectPath, ".claude/settings.local.json"));
+                }
+        }
+    let cwd = resolve(env.PWD ?? home);
+    while (true) {
+        files.push(join(cwd, ".claude/settings.json"), join(cwd, ".claude/settings.local.json"));
+        const parent = dirname(cwd);
+        if (parent === cwd)
+            break;
+        cwd = parent;
+    }
+    for (const path of new Set(files)) {
+        if (path === join(config, "settings.json") || !existsSync(path))
+            continue;
+        const value = readJson(path);
+        if (record(value) && record(value.extraKnownMarketplaces) && value.extraKnownMarketplaces[CLOUD_MARKETPLACE] !== undefined)
+            return true;
+    }
+    return false;
 }
-function readJson(path) {
-    return JSON.parse(readFileSync(path, "utf8"));
+function pluginManifest(dir, version) {
+    try {
+        const marketplace = readJson(join(dir, ".claude-plugin/marketplace.json"));
+        const plugin = readJson(join(dir, ".claude-plugin/plugin.json"));
+        if (!record(marketplace) || marketplace.name !== CLOUD_MARKETPLACE || !Array.isArray(marketplace.plugins))
+            return false;
+        const entries = marketplace.plugins.filter((entry) => record(entry) && entry.name === "catalyst");
+        if (entries.length !== 1 || !record(entries[0]) || entries[0].source !== "./")
+            return false;
+        if (!record(plugin) || plugin.name !== "catalyst" || plugin.version !== version)
+            return false;
+        const paths = typeof plugin.skills === "string" ? [plugin.skills] : plugin.skills;
+        return Array.isArray(paths) && paths.length > 0 && paths.every((path) => typeof path === "string" && /^\.\/skills\/(?:[a-zA-Z0-9_-]+\/?)?$/.test(path) && plainDirectory(join(dir, path)));
+    }
+    catch {
+        return false;
+    }
 }
-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) {
+    const config = claudeConfigDir(home, env);
     let registry;
     try {
-        registry = readJson(join(claudeConfigDir(home, env), "plugins", "installed_plugins.json"));
+        registry = readJson(join(config, "plugins/installed_plugins.json"));
     }
-    catch (err) {
-        return err.code === "ENOENT" ? { state: "not_installed" } : { state: "unknown", reason: "plugin_registry_unreadable" };
+    catch (error) {
+        return error instanceof Error && "code" in error && error.code === "ENOENT" ? { state: "not_installed" } : { state: "unknown", reason: "plugin_registry_unreadable" };
     }
-    const entries = isRecord(registry) && isRecord(registry.plugins) ? registry.plugins[CLOUD_PLUGIN_ID] : undefined;
+    const entries = record(registry) && record(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;
+        if (hasOverride(home, env, entries))
+            return { state: "unknown", reason: "plugin_scope_unsupported" };
+        const entry = entries[0];
+        const version = record(entry) ? exactVersion(entry.version) : null;
+        if (version === null)
+            return { state: "unknown", reason: "version_unreadable" };
+        const known = readJson(join(config, "plugins/known_marketplaces.json"));
+        const marketplace = record(known) ? known[CLOUD_MARKETPLACE] : null;
+        const settings = readJson(join(config, "settings.json"));
+        const declared = record(settings) && record(settings.extraKnownMarketplaces) ? settings.extraKnownMarketplaces[CLOUD_MARKETPLACE] : null;
+        if (!record(marketplace) || !record(marketplace.source) || typeof marketplace.installLocation !== "string" || !record(declared) || !record(declared.source) || marketplace.scope !== undefined && marketplace.scope !== "user")
+            return { state: "unknown", reason: "installation_owner_unknown" };
+        const source = marketplace.source;
+        const dir = marketplace.installLocation;
+        if (!plainDirectory(dir))
+            return { state: "unknown", reason: "installation_owner_unknown" };
+        const git = cloudGitSource(source);
+        if (git) {
+            if (cloudGitSource(declared.source) !== git || source.ref !== declared.source.ref || source.ref !== undefined && (typeof source.ref !== "string" || source.ref.length === 0 || /[#\r\n]/.test(source.ref)))
+                return { state: "unknown", reason: "source_mismatch" };
+            return { state: "installed", version, scope: "user", claude: resolveClaude(home, env), commit: null, source: { kind: "git", argument: `${source.source === "github" ? repositoryFor("cloud") : git.replace(/\.git$/, "") + ".git"}${typeof source.ref === "string" ? `#${source.ref}` : ""}`, gitUrl: git, dir, commit: null } };
+        }
+        if (source.source !== "directory" || source.path !== dir || declared.source.source !== "directory" || declared.source.path !== dir)
+            return { state: "unknown", reason: "source_mismatch" };
+        const manifest = readJson(join(dir, "package.json"));
+        const commit = dir.slice(dir.lastIndexOf("/") + 1);
+        if (dir !== skillReleaseDir(home, "cloud", commit) || !/^[a-f0-9]{40}$/.test(commit) || !record(manifest) || exactVersion(manifest.version) === null)
+            return { state: "unknown", reason: "installation_owner_unknown" };
+        const target = { repository: repositoryFor("cloud"), version: String(manifest.version), commit };
+        if (!verifiedSkillSource(home, "cloud", target))
+            return { state: "unknown", reason: "local_changes" };
+        if (!pluginManifest(dir, version))
+            return { state: "unknown", reason: "source_mismatch" };
+        return { state: "installed", version, scope: "user", claude: resolveClaude(home, env), commit, source: { kind: "directory", argument: dir, dir, commit } };
     }
     catch {
-        return null;
+        return { state: "unknown", reason: "installation_owner_unknown" };
     }
 }
 /** The schedule's record of the `claude` command found when it was set up. */
@@ -80,20 +147,76 @@ export function resolveClaude(home, env) {
     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 = {}) {
+export function applyCloudPluginUpdate(home, env, target, pluginVersion, scope, deps = {}) {
+    const failed = (detail) => ({ outcome: "failed", detail, version: null, commit: null });
+    if (scope !== "user")
+        return failed("plugin_scope_unsupported");
     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 };
+    return withSkillUpdateLock(home, failed("update_in_progress"), () => {
+        const before = cloudPluginInventory(home, env);
+        if (before.state !== "installed")
+            return failed(before.state === "unknown" ? before.reason : "not_installed");
+        const exec = deps.exec ?? spawnCliCommand;
+        const childEnv = { ...env, HOME: home, CLAUDE_CONFIG_DIR: claudeConfigDir(home, env), PWD: home };
+        if (before.source.kind === "git") {
+            // Only an unmodified, correctly sourced Git checkout can be adopted.
+            const origin = spawnCliCommand(["git", "-c", "core.hooksPath=/dev/null", "remote", "get-url", "origin"], before.source.dir, childEnv);
+            const clean = spawnCliCommand(["git", "-c", "core.hooksPath=/dev/null", "status", "--porcelain", "--untracked-files=all", "--ignored"], before.source.dir, childEnv);
+            if (origin.status !== 0 || origin.stdout.trim().replace(/\.git$/, "") !== before.source.gitUrl?.replace(/\.git$/, ""))
+                return failed("source_mismatch");
+            if (clean.status !== 0 || clean.stdout.trim() !== "")
+                return failed("local_changes");
+        }
+        let beforeDigest;
+        try {
+            beforeDigest = contentDigest(before.source.dir, true);
+        }
+        catch {
+            return failed("local_changes");
+        }
+        const source = stageSkillSource(home, "cloud", target, { ...deps, env });
+        if (!source.ok)
+            return failed(source.detail);
+        if (!pluginManifest(source.dir, pluginVersion))
+            return failed("source_mismatch");
+        const unchanged = cloudPluginInventory(home, env);
+        if (unchanged.state !== "installed" || unchanged.source.dir !== before.source.dir || unchanged.version !== before.version || contentDigest(before.source.dir, true) !== beforeDigest)
+            return failed("source_mismatch");
+        const select = (argument) => exec([claude, "plugin", "marketplace", "add", argument, "--scope", "user"], home, childEnv).status === 0;
+        const update = () => exec([claude, "plugin", "update", CLOUD_PLUGIN_ID, "--scope", "user"], home, childEnv).status === 0;
+        let failure;
+        try {
+            if (!select(source.dir))
+                failure = "marketplace_update_failed";
+            else if (!update())
+                failure = "update_failed";
+            else {
+                const after = cloudPluginInventory(home, env);
+                if (after.state === "installed" && after.source.dir === source.dir && after.commit === target.commit && after.version === pluginVersion && contentDigest(source.dir, true) === source.digest)
+                    return { outcome: "updated", detail: "approved_commit_installed", version: after.version, commit: after.commit };
+                failure = "verify_failed";
+            }
+        }
+        catch {
+            failure = "update_failed";
+        }
+        // Never remove the marketplace or hand-edit Claude's registries. Restore through the same API.
+        try {
+            const restored = select(before.source.argument);
+            let now = cloudPluginInventory(home, env);
+            if (restored && (now.state !== "installed" || now.version !== before.version)) {
+                if (!update())
+                    return failed("rollback_failed");
+                now = cloudPluginInventory(home, env);
+            }
+            if (!restored || now.state !== "installed" || now.source.dir !== before.source.dir || now.version !== before.version || now.source.argument !== before.source.argument || contentDigest(now.source.dir, true) !== beforeDigest)
+                return failed("rollback_failed");
+        }
+        catch {
+            return failed("rollback_failed");
+        }
+        return failed(failure);
+    });
 }

package/dist/update-skill-source.js

@@ -0,0 +1,145 @@
+// Exact approved Git checkouts. No lifecycle scripts or floating branches are executed.
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+import { exactVersion, SKILL_PACK_REPOSITORIES } from "./approved-release.js";
+import { configDirFor } from "./config.js";
+import { spawnCliCommand } from "./update-cli.js";
+export const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const safeName = (value) => /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(value);
+export const repositoryFor = (pack) => SKILL_PACK_REPOSITORIES[pack];
+export const skillReleaseDir = (home, pack, commit) => join(configDirFor(home), "skill-releases", pack, commit);
+/** Hash all bytes, names and executable modes, including ignored and untracked files.
+ * Hash checkout metadata links without following them. Skill trees and manifests
+ * still refuse symlinks, and special files are refused everywhere. */
+export function contentDigest(dir, checkout = false) {
+    const hash = createHash("sha256");
+    const visit = (path, relative) => {
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink()) {
+            if (!checkout || relative === "" || ["skills", "package.json", ".claude-plugin"].some((root) => relative === root || relative.startsWith(`${root}/`)))
+                throw new Error("unsafe_path");
+            const target = readlinkSync(path);
+            const resolved = resolve(dirname(path), target);
+            if (isAbsolute(target) || resolved !== resolve(dir) && !resolved.startsWith(`${resolve(dir)}${sep}`))
+                throw new Error("unsafe_path");
+            hash.update(`symlink\0${relative}\0${target}\0`);
+            return;
+        }
+        if (stat.isDirectory()) {
+            hash.update(`directory\0${relative}\0`);
+            for (const name of readdirSync(path).sort()) {
+                if (checkout && relative === "" && name === ".git")
+                    continue;
+                if (name === ".git")
+                    throw new Error("unsafe_path");
+                visit(join(path, name), relative ? `${relative}/${name}` : name);
+            }
+        }
+        else if (stat.isFile()) {
+            const bytes = readFileSync(path);
+            hash.update(`file\0${relative}\0${stat.mode & 0o111 ? "executable" : "regular"}\0${bytes.length}\0`);
+            hash.update(bytes);
+        }
+        else
+            throw new Error("unsafe_path");
+    };
+    visit(dir, "");
+    return hash.digest("hex");
+}
+function gitEnv(env) {
+    const clean = Object.fromEntries(Object.entries(env).filter(([key]) => !key.startsWith("GIT_")));
+    return { ...clean, GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null" };
+}
+/** Git's tree identity for global skills-lock v3, with a private index and forced ignored files. */
+export function skillTreeHash(dir, env = process.env) {
+    contentDigest(dir);
+    const temporary = mkdtempSync(join(tmpdir(), "catalyst-skill-index-"));
+    const run = (args) => {
+        const result = spawnCliCommand(["git", "-c", "core.hooksPath=/dev/null", ...args], temporary, gitEnv(env));
+        if (result.status !== 0)
+            throw new Error("tree_hash_failed");
+        return result.stdout.trim();
+    };
+    try {
+        run(["init", "--bare", "--quiet"]);
+        const prefix = [`--git-dir=${temporary}`, `--work-tree=${dir}`, "-c", "core.fileMode=true", "-c", "core.autocrlf=false"];
+        run([...prefix, "add", "--force", "--all", "--", "."]);
+        return run([...prefix, "write-tree"]);
+    }
+    finally {
+        rmSync(temporary, { recursive: true, force: true });
+    }
+}
+function verifyManifest(dir, target) {
+    const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    if (!record(manifest) || manifest.version !== target.version)
+        throw new Error("source_mismatch");
+    if (!readdirSync(join(dir, "skills")).some((name) => safeName(name) && existsSync(join(dir, "skills", name, "SKILL.md"))))
+        throw new Error("source_mismatch");
+    for (const name of readdirSync(join(dir, "skills")))
+        if (!safeName(name))
+            throw new Error("unsafe_path");
+    const plugin = join(dir, ".claude-plugin", "plugin.json");
+    if (existsSync(plugin)) {
+        const value = JSON.parse(readFileSync(plugin, "utf8"));
+        if (!record(value) || value.version !== target.version)
+            throw new Error("source_mismatch");
+    }
+}
+/** Read-only cache verification also used by plugin inventory. */
+export function verifiedSkillSource(home, pack, target) {
+    try {
+        if (target.repository !== repositoryFor(pack) || !/^[a-f0-9]{40}$/.test(target.commit) || exactVersion(target.version) === null)
+            return null;
+        const dir = skillReleaseDir(home, pack, target.commit);
+        const saved = JSON.parse(readFileSync(`${dir}.json`, "utf8"));
+        if (!record(saved) || saved.commit !== target.commit || saved.version !== target.version || saved.repository !== target.repository)
+            return null;
+        verifyManifest(dir, target);
+        const digest = contentDigest(dir, true);
+        return digest === saved.digest ? { dir, digest } : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function stageSkillSource(home, pack, target, deps = {}) {
+    if (target.repository !== repositoryFor(pack) || !/^[a-f0-9]{40}$/.test(target.commit) || exactVersion(target.version) === null)
+        return { ok: false, detail: "source_mismatch" };
+    const final = skillReleaseDir(home, pack, target.commit);
+    if (existsSync(final)) {
+        const verified = verifiedSkillSource(home, pack, target);
+        return verified ? { ok: true, ...verified } : { ok: false, detail: "local_changes" };
+    }
+    const parent = join(configDirFor(home), "skill-releases", pack);
+    mkdirSync(parent, { recursive: true, mode: 0o700 });
+    const staging = mkdtempSync(join(parent, ".staging-"));
+    const exec = deps.exec ?? spawnCliCommand;
+    const env = gitEnv(deps.env ?? process.env);
+    const run = (...args) => {
+        const result = exec(["git", "-c", "core.hooksPath=/dev/null", ...args], staging, env);
+        if (result.status !== 0)
+            throw new Error("fetch_failed");
+        return result.stdout.trim();
+    };
+    try {
+        run("init", "--quiet");
+        run("fetch", "--depth=1", "--no-tags", "--", deps.repositoryUrl?.(target.repository) ?? `https://github.com/${target.repository}.git`, target.commit);
+        run("-c", "advice.detachedHead=false", "checkout", "--detach", "FETCH_HEAD");
+        if (run("rev-parse", "HEAD") !== target.commit)
+            throw new Error("source_mismatch");
+        const digest = contentDigest(staging, true);
+        verifyManifest(staging, target);
+        writeFileSync(`${final}.json`, JSON.stringify({ ...target, digest }), { mode: 0o600 });
+        renameSync(staging, final);
+        return { ok: true, dir: final, digest };
+    }
+    catch (error) {
+        return { ok: false, detail: error instanceof Error ? error.message : "fetch_failed" };
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}

package/dist/update-skill-state.js

@@ -0,0 +1,175 @@
+// Read-only ownership discovery. A stamp or npx lock is an adoption candidate, not proof.
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { exactVersion } from "./approved-release.js";
+import { configDirFor } from "./config.js";
+import { installedBundleVersion } from "./skills.js";
+import { contentDigest, record, repositoryFor, safeName } from "./update-skill-source.js";
+const receiptsPath = (home) => join(configDirFor(home), "skill-installations.json");
+export const skillLockPath = (home, env) => env.XDG_STATE_HOME ? join(env.XDG_STATE_HOME, "skills/.skill-lock.json") : join(home, ".agents/.skill-lock.json");
+const canonicalDir = (home) => join(home, ".agents/skills");
+const unknown = (present, reason = "installation_owner_unknown") => ({ present, candidate: false, commit: null, version: null, kind: "unknown", reason, destinations: [] });
+// The global npx lock records the SKILL.md path; receipts use its containing tree.
+const lockSkillFolder = (path) => typeof path === "string" ? path.replace(/\/SKILL\.md$/, "") : null;
+/** Reject linked ancestors too, so a receipt cannot authorize writes through a changed root. */
+export function plainDirectory(path) {
+    try {
+        return isAbsolute(path) && realpathSync(path) === resolve(path) && lstatSync(path).isDirectory() && !lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+export function destinationMatches(destination) {
+    try {
+        return plainDirectory(destination.path) && contentDigest(destination.path) === destination.digest && destination.links.every((link) => lstatSync(link).isSymbolicLink() && realpathSync(link) === destination.path);
+    }
+    catch {
+        return false;
+    }
+}
+function parseReceipt(value, home, pack, dir, env) {
+    if (!record(value) || value.pack !== pack || value.repository !== repositoryFor(pack) || typeof value.commit !== "string" || !/^[a-f0-9]{40}$/.test(value.commit) || exactVersion(value.version) === null || value.dir !== dir || (value.kind !== "legacy" && value.kind !== "npx") || !Array.isArray(value.destinations))
+        return null;
+    if (value.kind === "npx" && value.lockPath !== skillLockPath(home, env))
+        return null;
+    const destinations = [];
+    for (const d of value.destinations) {
+        if (!record(d) || typeof d.name !== "string" || !safeName(d.name) || d.path !== join(value.kind === "npx" ? canonicalDir(home) : dir, d.name) || typeof d.digest !== "string" || !/^[a-f0-9]{64}$/.test(d.digest) || d.skillPath !== `skills/${d.name}` || !Array.isArray(d.links) || !d.links.every((link) => typeof link === "string" && agentDirs(home, dir).some((root) => link === join(root, String(d.name)))))
+            return null;
+        if (destinations.some((old) => old.name === d.name))
+            return null;
+        if (value.kind === "npx" && (typeof d.lockHash !== "string" || !/^[a-f0-9]{40}$/.test(d.lockHash)))
+            return null;
+        destinations.push({ name: d.name, path: String(d.path), digest: d.digest, skillPath: String(d.skillPath), links: d.links, ...(typeof d.lockHash === "string" ? { lockHash: d.lockHash } : {}) });
+    }
+    return { pack, repository: repositoryFor(pack), commit: value.commit, version: String(value.version), kind: value.kind, dir, destinations, ...(value.kind === "npx" ? { lockPath: String(value.lockPath) } : {}) };
+}
+function agentDirs(home, selected) {
+    return [...new Set([selected, ...[".claude", ".codex", ".cursor", ".opencode", ".config/opencode"].map((agent) => join(home, agent, "skills"))])];
+}
+export function readSkillLock(path) {
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        return record(raw) && raw.version === 3 && record(raw.skills) ? { ...raw, version: 3, skills: raw.skills } : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function inspectSkillInstallation(home, env, pack, dir) {
+    const transaction = join(configDirFor(home), ".skill-transaction.json");
+    if (existsSync(transaction)) {
+        try {
+            const pending = JSON.parse(readFileSync(transaction, "utf8"));
+            if (record(pending) && pending.pack === pack && pending.dir === dir)
+                return { ...unknown(true, "update_interrupted"), candidate: true };
+        }
+        catch {
+            return unknown(true, "recovery_failed");
+        }
+    }
+    const receiptPath = receiptsPath(home);
+    if (existsSync(receiptPath)) {
+        try {
+            const raw = JSON.parse(readFileSync(receiptPath, "utf8"));
+            if (!record(raw) || raw.version !== 1 || !record(raw.packs))
+                return unknown(true, "source_mismatch");
+            if (raw.packs[pack] !== undefined) {
+                const receipt = parseReceipt(raw.packs[pack], home, pack, dir, env);
+                if (!receipt)
+                    return unknown(true, "source_mismatch");
+                if (receipt.lockPath) {
+                    const lock = readSkillLock(receipt.lockPath);
+                    if (!lock || !receipt.destinations.every((destination) => {
+                        const entry = lock.skills[destination.name];
+                        return record(entry) && entry.source === receipt.repository && entry.sourceType === "github" && lockSkillFolder(entry.skillPath) === destination.skillPath && entry.ref === receipt.commit && entry.skillFolderHash === destination.lockHash;
+                    }))
+                        return { ...unknown(true, "source_mismatch"), receipt, destinations: receipt.destinations, lockPath: receipt.lockPath };
+                }
+                const valid = receipt.destinations.every(destinationMatches);
+                // An empty receipt records removal of the last owned, retired name.
+                return { present: receipt.destinations.length > 0, candidate: valid, commit: valid ? receipt.commit : null, version: receipt.version, kind: receipt.kind, reason: valid ? "verified" : "local_changes", destinations: receipt.destinations, receipt, lockPath: receipt.lockPath };
+            }
+        }
+        catch {
+            return unknown(true, "source_mismatch");
+        }
+    }
+    const lockPath = skillLockPath(home, env);
+    const lock = readSkillLock(lockPath);
+    const owned = Object.entries(lock?.skills ?? {}).filter(([, entry]) => record(entry) && entry.source === repositoryFor(pack));
+    if (owned.length > 0) {
+        const destinations = [];
+        for (const [name, entry] of owned) {
+            if (!safeName(name) || !record(entry) || entry.sourceType !== "github" || lockSkillFolder(entry.skillPath) !== `skills/${name}` || typeof entry.skillFolderHash !== "string" || !/^[a-f0-9]{40}$/.test(entry.skillFolderHash))
+                return unknown(true);
+            const path = join(canonicalDir(home), name);
+            if (!existsSync(path))
+                continue;
+            if (!plainDirectory(path))
+                return unknown(true);
+            try {
+                const links = agentDirs(home, dir).map((root) => join(root, name)).filter((link) => {
+                    try {
+                        return lstatSync(link).isSymbolicLink() && realpathSync(link) === path;
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+                destinations.push({ name, path, links, digest: contentDigest(path), skillPath: `skills/${name}`, lockHash: entry.skillFolderHash });
+            }
+            catch {
+                return unknown(true, "local_changes");
+            }
+        }
+        return { present: destinations.length > 0, candidate: true, commit: null, version: null, kind: "npx", reason: "commit_unrecorded", destinations, lockPath };
+    }
+    let names = [];
+    try {
+        names = readdirSync(dir).filter(safeName);
+    }
+    catch {
+        return unknown(false);
+    }
+    const legacy = [];
+    let version = null;
+    if (pack === "cloud") {
+        for (const name of names) {
+            const found = installedBundleVersion(dir, [name]);
+            if (found.version === null && found.unstamped.length === 0)
+                continue;
+            // Contradictory global evidence must not fall back to a provenance stamp.
+            if (lock?.skills[name] !== undefined || !plainDirectory(join(dir, name)) || found.version === null)
+                return unknown(true);
+            if (version !== null && version !== found.version)
+                return unknown(true);
+            version = found.version;
+            try {
+                legacy.push({ name, path: join(dir, name), links: [], digest: contentDigest(join(dir, name)), skillPath: `skills/${name}` });
+            }
+            catch {
+                return unknown(true, "local_changes");
+            }
+        }
+    }
+    if (legacy.length > 0)
+        return { present: true, candidate: true, commit: null, version, kind: "legacy", reason: "commit_unrecorded", destinations: legacy };
+    return unknown(pack === "dev" && existsSync(join(dir, "research-codebase/SKILL.md")));
+}
+/** Caller holds the installation lock. Publish last, preserving the other pack's receipt. */
+export function writeSkillReceipt(home, receipt) {
+    const path = receiptsPath(home);
+    let packs = {};
+    if (existsSync(path)) {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (!record(raw) || raw.version !== 1 || !record(raw.packs))
+            throw new Error("receipt_invalid");
+        packs = raw.packs;
+    }
+    mkdirSync(configDirFor(home), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, JSON.stringify({ version: 1, packs: { ...packs, [receipt.pack]: receipt } }), { mode: 0o600 });
+    renameSync(temporary, path);
+}