@iseoane/agent-depot 0.2.0 → 0.3.0

package/dist/src/skill-discovery.js

@@ -0,0 +1,467 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { lstat, readdir, readFile } from "node:fs/promises";
+import { assertNoSymlinkPath } from "./path-safety.js";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { defaultGitSourceCachePath, GitSourceSnapshotAccess, SKILL_TREE_LIMITS, validateSkillDirectoryPath, } from "./git-source.js";
+import { AGENT_DEPOT_PACKAGE_VERSION, } from "./project-manifest.js";
+export const EXCLUDED_LIFECYCLE_SEGMENTS = Object.freeze([
+    "in-progress",
+    "beta",
+    "deprecated",
+    "retired",
+]);
+const excludedLifecycleSegments = new Set(EXCLUDED_LIFECYCLE_SEGMENTS);
+/**
+ * The package-owned root used for built-in skills. A missing root is an empty
+ * built-in Source, which lets packages ship no built-in skills yet.
+ */
+export function defaultBuiltInSkillsRoot() {
+    return path.join(findPackageRoot(path.dirname(fileURLToPath(import.meta.url))), "skills");
+}
+/** Walks up from a module directory (src/ or dist/src/) to the nearest package.json. */
+function findPackageRoot(startDirectory) {
+    let current = startDirectory;
+    for (;;) {
+        if (existsSync(path.join(current, "package.json"))) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return path.resolve(startDirectory, "..");
+        }
+        current = parent;
+    }
+}
+/** Default read-only Source access used by the application operation. */
+export class NodeSourceContentAccess {
+    builtInRoot;
+    readFile;
+    readBinaryFile;
+    gitSnapshots;
+    constructor(options = {}) {
+        this.builtInRoot = options.builtInRoot ?? defaultBuiltInSkillsRoot();
+        this.readFile = options.readFile ?? ((filePath) => readFile(filePath, "utf8"));
+        this.readBinaryFile = options.readBinaryFile ?? ((filePath) => readFile(filePath));
+        this.gitSnapshots = new GitSourceSnapshotAccess({
+            cachePath: options.gitCachePath ?? defaultGitSourceCachePath(),
+        });
+    }
+    async readSnapshot(source) {
+        if (source.kind === "builtin") {
+            return readDirectorySnapshot(this.builtInRoot, this.readFile);
+        }
+        return this.gitSnapshots.readSnapshot(source);
+    }
+    async readSkillTree(source, skillPath) {
+        return (await this.readSkillTreeSnapshot(source, skillPath)).files;
+    }
+    async readSkillTreeSnapshot(source, skillPath) {
+        const selectedPath = validateSkillDirectoryPath(skillPath);
+        if (source.kind === "builtin") {
+            return Object.freeze({
+                files: await readSelectedSkillDirectory(this.builtInRoot, selectedPath, this.readBinaryFile),
+                ...(AGENT_DEPOT_PACKAGE_VERSION === undefined
+                    ? {}
+                    : { resolvedVersion: Object.freeze({ kind: "builtin-package", version: AGENT_DEPOT_PACKAGE_VERSION }) }),
+            });
+        }
+        const snapshot = await this.gitSnapshots.readSkillTreeSnapshot(source, selectedPath);
+        return Object.freeze({
+            files: snapshot.files,
+            resolvedVersion: Object.freeze({ kind: "git-commit", commit: snapshot.resolvedVersion }),
+        });
+    }
+    async readResolvedVersion(source) {
+        if (source.kind === "builtin") {
+            return AGENT_DEPOT_PACKAGE_VERSION === undefined
+                ? undefined
+                : Object.freeze({ kind: "builtin-package", version: AGENT_DEPOT_PACKAGE_VERSION });
+        }
+        return Object.freeze({
+            kind: "git-commit",
+            commit: await this.gitSnapshots.readResolvedCommit(source),
+        });
+    }
+}
+export function createSourceContentAccess(options = {}) {
+    return new NodeSourceContentAccess(options);
+}
+/**
+ * Creates a deterministic content baseline for a safely captured Skill tree.
+ * Paths and bytes are included; executable mode is intentionally excluded so
+ * adoption and update checks use the same content identity across platforms.
+ */
+export function skillTreeBaseline(files) {
+    const sorted = [...files].sort((left, right) => Buffer.compare(Buffer.from(left.path, "utf8"), Buffer.from(right.path, "utf8")));
+    const seen = new Set();
+    const hash = createHash("sha256");
+    hash.update("agent-depot-skill-tree-v1\0", "utf8");
+    for (const file of sorted) {
+        if (seen.has(file.path)) {
+            throw new Error(`Skill tree contains a duplicate path: ${file.path}`);
+        }
+        seen.add(file.path);
+        const pathBytes = Buffer.from(file.path, "utf8");
+        hash.update(`${pathBytes.byteLength}:`, "utf8");
+        hash.update(pathBytes);
+        hash.update(`${file.content.byteLength}:`, "utf8");
+        hash.update(file.content);
+        hash.update("\0", "utf8");
+    }
+    return Object.freeze({ algorithm: "sha256", digest: hash.digest("hex") });
+}
+/** Discovers candidates from explicitly selected Sources in selection order. */
+export async function discoverSkillsFromSources(sources, contentAccess) {
+    const candidates = [];
+    for (const source of sources) {
+        const files = [...await contentAccess.readSnapshot(source)].sort((left, right) => left.path.localeCompare(right.path));
+        for (const file of files) {
+            const normalizedPath = normalizeSourcePath(file.path);
+            if (!normalizedPath || path.posix.basename(normalizedPath) !== "SKILL.md") {
+                continue;
+            }
+            const directoryPath = path.posix.dirname(normalizedPath);
+            const segments = directoryPath === "." ? [] : directoryPath.split("/");
+            if (segments.some((segment) => excludedLifecycleSegments.has(segment))) {
+                continue;
+            }
+            const metadata = parseSkillFrontmatter(file.content);
+            if (!metadata) {
+                continue;
+            }
+            candidates.push({
+                sourceId: source.id,
+                path: directoryPath,
+                name: metadata.name,
+                description: metadata.description,
+            });
+        }
+    }
+    return Object.freeze(candidates);
+}
+/** Collects scalar frontmatter values up to the closing delimiter; undefined when malformed or unclosed. */
+function readFrontmatterValues(lines) {
+    const values = new Map();
+    let index = 1;
+    while (index < lines.length) {
+        const line = lines[index];
+        if (/^(?:---|\.\.\.)\s*$/u.test(line)) {
+            return values;
+        }
+        if (line.trim() === "" || /^\s*#/u.test(line)) {
+            index += 1;
+            continue;
+        }
+        const next = readFrontmatterEntry(lines, index, values);
+        if (next === undefined) {
+            return undefined;
+        }
+        index = next;
+    }
+    return undefined;
+}
+/** Reads one top-level entry starting at index and returns the next index, or undefined when malformed. */
+function readFrontmatterEntry(lines, index, values) {
+    const line = lines[index];
+    const match = /^(?<key>[A-Za-z][A-Za-z0-9_-]*)\s*:\s*(?<value>.*)$/u.exec(line);
+    if (!match || line.startsWith(" ") || line.startsWith("\t")) {
+        return undefined;
+    }
+    const key = match.groups?.key;
+    const rawValue = match.groups?.value ?? "";
+    if (!key) {
+        return undefined;
+    }
+    if (key === "metadata" && rawValue.trim() === "") {
+        return consumeNestedMapping(lines, index + 1);
+    }
+    if (/^[|>][+-]?\d*\s*$/u.test(rawValue)) {
+        const block = [];
+        let next = index + 1;
+        while (next < lines.length) {
+            const blockLine = lines[next];
+            if (blockLine.trim() !== "" && !/^[ \t]/u.test(blockLine)) {
+                break;
+            }
+            block.push(blockLine);
+            next += 1;
+        }
+        values.set(key, normalizeBlockScalar(block, rawValue.startsWith(">")));
+        return next;
+    }
+    const scalar = parseScalar(rawValue);
+    if (scalar === undefined) {
+        return undefined;
+    }
+    values.set(key, scalar);
+    return index + 1;
+}
+/** Parses the required YAML frontmatter fields without evaluating arbitrary YAML. */
+export function parseSkillFrontmatter(content) {
+    const lines = content.replace(/^\uFEFF/u, "").replace(/\r\n?/gu, "\n").split("\n");
+    if (!/^---\s*$/u.test(lines[0] ?? "")) {
+        return undefined;
+    }
+    const values = readFrontmatterValues(lines);
+    if (!values) {
+        return undefined;
+    }
+    const nameValue = values.get("name");
+    const descriptionValue = values.get("description");
+    const name = typeof nameValue === "string" ? nameValue.trim() : undefined;
+    const description = typeof descriptionValue === "string" ? descriptionValue.trim() : undefined;
+    if (!name || !description) {
+        return undefined;
+    }
+    return { name, description };
+}
+async function readSelectedSkillDirectory(root, selectedPath, readBinaryFile) {
+    const rootKind = await safePathKind(root);
+    if (rootKind !== "directory") {
+        throw new Error(`Built-in Source root is not a directory: ${root}`);
+    }
+    await assertNoSymlinkPath(root, "Selected Skill path");
+    const selectedDirectory = path.join(root, ...selectedPath.split("/"));
+    if ((await safePathKind(selectedDirectory)) !== "directory") {
+        throw new Error(`Selected Skill directory is not available: ${selectedPath}`);
+    }
+    await assertNoSymlinkPath(selectedDirectory, "Selected Skill path");
+    const files = [];
+    let totalBytes = 0;
+    let hasSkillManifest = false;
+    await walkSelectedSkillDirectory(root, selectedDirectory, selectedPath, files, readBinaryFile, (byteLength, relativePath) => {
+        if (byteLength > SKILL_TREE_LIMITS.maxFileBytes) {
+            throw new Error(`Selected Skill file exceeds the safe size limit: ${relativePath}`);
+        }
+    }, (byteLength) => {
+        totalBytes += byteLength;
+        if (totalBytes > SKILL_TREE_LIMITS.maxTotalBytes) {
+            throw new Error("Selected Skill tree exceeds the safe total size limit");
+        }
+    }, () => {
+        if (files.length >= SKILL_TREE_LIMITS.maxFiles) {
+            throw new Error("Selected Skill tree contains too many files");
+        }
+    }, (relativePath) => {
+        if (relativePath === `${selectedPath}/SKILL.md`) {
+            hasSkillManifest = true;
+        }
+    });
+    if (!hasSkillManifest) {
+        throw new Error(`Selected Skill directory does not contain ${selectedPath}/SKILL.md`);
+    }
+    files.sort((left, right) => left.path.localeCompare(right.path));
+    return Object.freeze(files);
+}
+async function walkSelectedSkillDirectory(root, absoluteDirectory, relativeDirectory, files, readBinaryFile, assertFileSize, assertTotalBytes, assertFileCount, observeFile) {
+    await assertNoSymlinkPath(absoluteDirectory, "Selected Skill path");
+    const entries = await readdir(absoluteDirectory, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+        const relativePath = `${relativeDirectory}/${entry.name}`;
+        try {
+            validateSkillDirectoryPath(relativePath);
+        }
+        catch {
+            throw new Error(`Selected Skill tree contains an unsafe path: ${relativePath}`);
+        }
+        const absolutePath = path.join(root, ...relativePath.split("/"));
+        if (entry.isSymbolicLink()) {
+            throw new Error(`Selected Skill tree contains a symbolic link: ${relativePath}`);
+        }
+        if (entry.isDirectory()) {
+            if ((await safePathKind(absolutePath)) !== "directory") {
+                throw new Error(`Selected Skill tree entry changed while reading: ${relativePath}`);
+            }
+            await walkSelectedSkillDirectory(root, absolutePath, relativePath, files, readBinaryFile, assertFileSize, assertTotalBytes, assertFileCount, observeFile);
+            continue;
+        }
+        if (!entry.isFile()) {
+            throw new Error(`Selected Skill tree contains an unsupported file: ${relativePath}`);
+        }
+        assertFileCount();
+        await assertNoSymlinkPath(absolutePath, "Selected Skill path");
+        const information = await lstat(absolutePath);
+        if (!information.isFile()) {
+            throw new Error(`Selected Skill tree entry changed while reading: ${relativePath}`);
+        }
+        assertFileSize(information.size, relativePath);
+        const content = await readBinaryFile(absolutePath);
+        const byteLength = content.byteLength;
+        assertFileSize(byteLength, relativePath);
+        assertTotalBytes(byteLength);
+        observeFile(relativePath);
+        files.push({ path: relativePath, content, executable: (information.mode & 0o111) !== 0 });
+    }
+}
+async function readDirectorySnapshot(root, readTextFile) {
+    const rootKind = await safePathKind(root);
+    if (rootKind === "missing") {
+        return Object.freeze([]);
+    }
+    if (rootKind !== "directory") {
+        throw new Error(`Built-in Source root is not a directory: ${root}`);
+    }
+    const files = [];
+    await walkDirectory(root, "", files, readTextFile);
+    return Object.freeze(files);
+}
+async function walkDirectory(root, relativeDirectory, files, readTextFile) {
+    const absoluteDirectory = relativeDirectory ? path.join(root, relativeDirectory) : root;
+    const entries = await readdir(absoluteDirectory, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+        const relativePath = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name;
+        const absolutePath = path.join(root, relativePath);
+        if (entry.isSymbolicLink()) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            if (excludedLifecycleSegments.has(entry.name)) {
+                continue;
+            }
+            await walkDirectory(root, relativePath, files, readTextFile);
+            continue;
+        }
+        if (!entry.isFile() || entry.name !== "SKILL.md" || (await safePathKind(absolutePath)) !== "file") {
+            continue;
+        }
+        files.push({
+            path: relativePath.split(path.sep).join("/"),
+            content: await readTextFile(absolutePath),
+        });
+    }
+}
+async function safePathKind(candidate) {
+    try {
+        const information = await lstat(candidate);
+        if (information.isSymbolicLink()) {
+            return "symlink";
+        }
+        if (information.isDirectory()) {
+            return "directory";
+        }
+        return "file";
+    }
+    catch (error) {
+        if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+            return "missing";
+        }
+        throw error;
+    }
+}
+function normalizeSourcePath(candidate) {
+    if (typeof candidate !== "string" || candidate.length === 0 || candidate.includes("\\")) {
+        return undefined;
+    }
+    const normalized = path.posix.normalize(candidate);
+    if (normalized === "." || normalized.startsWith("../") || normalized.startsWith("/")) {
+        return undefined;
+    }
+    return normalized;
+}
+const MAX_NESTED_MAPPING_DEPTH = 32;
+function consumeNestedMapping(lines, start, depth = 0) {
+    if (depth > MAX_NESTED_MAPPING_DEPTH) {
+        return undefined;
+    }
+    let index = start;
+    let indentation;
+    let hasEntry = false;
+    while (index < lines.length) {
+        const line = lines[index];
+        if (line.trim() === "" || /^\s*#/u.test(line)) {
+            index += 1;
+            continue;
+        }
+        if (/^(?:---|\.\.\.)\s*$/u.test(line) || !/^\s/u.test(line)) {
+            break;
+        }
+        if (/^\t/u.test(line)) {
+            return undefined;
+        }
+        const lineIndentation = line.match(/^ */u)?.[0].length ?? 0;
+        indentation ??= lineIndentation;
+        if (lineIndentation !== indentation) {
+            return undefined;
+        }
+        const next = consumeNestedEntry(lines, index, indentation, depth);
+        if (next === undefined) {
+            return undefined;
+        }
+        index = next;
+        hasEntry = true;
+    }
+    return hasEntry ? index : undefined;
+}
+/** Consumes one nested mapping entry (scalar, block scalar or child mapping); undefined when malformed. */
+function consumeNestedEntry(lines, index, indentation, depth) {
+    const match = /^ +(?<key>[A-Za-z][A-Za-z0-9_-]*)\s*:\s*(?<value>.*)$/u.exec(lines[index]);
+    if (!match) {
+        return undefined;
+    }
+    const rawValue = match.groups?.value ?? "";
+    if (rawValue === "") {
+        return consumeNestedMapping(lines, index + 1, depth + 1);
+    }
+    if (/^[|>][+-]?\d*\s*$/u.test(rawValue)) {
+        return consumeNestedBlockScalar(lines, index + 1, indentation);
+    }
+    return parseScalar(rawValue) === undefined ? undefined : index + 1;
+}
+function consumeNestedBlockScalar(lines, start, indentation) {
+    let index = start;
+    while (index < lines.length) {
+        const blockLine = lines[index];
+        if (blockLine.trim() !== "" && (!/^\s/u.test(blockLine) || (blockLine.match(/^ */u)?.[0].length ?? 0) <= indentation)) {
+            break;
+        }
+        if (/^\t/u.test(blockLine)) {
+            return undefined;
+        }
+        index += 1;
+    }
+    return index;
+}
+function parseScalar(rawValue) {
+    const value = rawValue.trim();
+    if (value.startsWith("\"")) {
+        if (!value.endsWith("\"") || value.length < 2) {
+            return undefined;
+        }
+        try {
+            const parsed = JSON.parse(value);
+            return typeof parsed === "string" ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (value.startsWith("'")) {
+        if (!value.endsWith("'") || value.length < 2) {
+            return undefined;
+        }
+        return value.slice(1, -1).replace(/''/gu, "'");
+    }
+    const plain = value.replace(/\s+#.*$/u, "").trim();
+    if (!plain || /^(?:null|~|\[|\{|\]|\})$/iu.test(plain)) {
+        return undefined;
+    }
+    if (/^(?:true|false)$/iu.test(plain)) {
+        return plain.toLowerCase() === "true";
+    }
+    return plain;
+}
+function normalizeBlockScalar(lines, folded) {
+    const nonEmpty = lines.filter((line) => line.trim() !== "");
+    const indentation = nonEmpty.length === 0
+        ? 0
+        : Math.min(...nonEmpty.map((line) => line.match(/^[ \t]*/u)?.[0].length ?? 0));
+    const normalized = lines.map((line) => line.slice(indentation));
+    if (!folded) {
+        return normalized.join("\n").trim();
+    }
+    return normalized.join("\n").replace(/\n(?=\S)/gu, " ").trim();
+}

package/dist/src/skill-hosts.js

@@ -0,0 +1,103 @@
+import path from "node:path";
+import { addProjectSkillHosts, inspectProjectSkillHostAddition, inspectProjectSkillRemoval, removeProjectSkill, } from "./project-installation.js";
+import { assertManagedInstallationRecordsUnchanged, assertRemovalInspectionUnchanged, executeSkillRemoval, planSkillRemoval, SkillSelectionError, } from "./skill-removal.js";
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function uniqueHosts(hosts, verb) {
+    const unique = [...new Set(hosts)];
+    if (unique.length === 0)
+        throw new SkillSelectionError(`Name at least one Host to ${verb}`);
+    return unique;
+}
+/** Plan step: validates the Hosts, inspects the installation and previews the new locations. */
+export async function planHostAddition(selection, hosts, options) {
+    const added = uniqueHosts(hosts, "add");
+    const present = added.filter((host) => selection.hosts.includes(host));
+    if (present.length > 0) {
+        throw new SkillSelectionError(`Skill ${JSON.stringify(selection.path)} is already exposed to ${present.join(", ")}`);
+    }
+    const inspection = await inspectProjectSkillHostAddition(selection, added, options);
+    const preview = [`  add hosts ${added.join(", ")} to ${JSON.stringify(selection.path)} (installed content and version are unchanged)`];
+    for (const location of inspection.createPaths) {
+        preview.push(`    create ${location} as a symlink to ${inspection.canonicalPath}`);
+    }
+    if (inspection.createPaths.length === 0) {
+        preview.push(`    no files change: ${inspection.canonicalPath} already serves these hosts`);
+    }
+    preview.push("    ADDITIONAL HOST EXPOSURE: this exposes the installed Skill to more hosts and needs explicit confirmation");
+    const updated = { ...selection, hosts: [...selection.hosts, ...added] };
+    return { selection, hosts: added, updated, inspection, preview };
+}
+/** Execute step: needs the additional-host confirmation, creates the locations, then updates the record. */
+export async function executeHostAddition(plan, operations, options, initialManaged, confirmAdditionalHostExposure) {
+    if (!confirmAdditionalHostExposure) {
+        throw new Error("Adding a Host is an additional Host exposure and needs explicit confirmation; no path was changed");
+    }
+    const { listUserGlobalInstallations: list, updateUserGlobalInstallation: update } = operations;
+    if (!list || !update)
+        throw new Error("Configured Source operations cannot update user-global Skills");
+    assertManagedInstallationRecordsUnchanged(initialManaged, await list.call(operations));
+    const transaction = await addProjectSkillHosts(plan.selection, plan.hosts, plan.inspection, options);
+    try {
+        await update.call(operations, plan.updated);
+    }
+    catch (error) {
+        try {
+            await transaction.rollback();
+        }
+        catch (rollbackError) {
+            throw new AggregateError([error, rollbackError], `Updating the installation record failed (${describe(error)}) and rolling back the new Host locations also failed (${describe(rollbackError)}); check the Claude location by hand`);
+        }
+        throw error;
+    }
+}
+/** Plan step: removing every recorded Host is a full removal; otherwise only the removed Hosts' own locations go. */
+export async function planHostRemoval(selection, hosts, options) {
+    const removed = uniqueHosts(hosts, "remove");
+    const unknown = removed.filter((host) => !selection.hosts.includes(host));
+    if (unknown.length > 0) {
+        throw new SkillSelectionError(`Host ${unknown.join(", ")} is not recorded for this Skill; recorded hosts: ${selection.hosts.join(", ")}`);
+    }
+    const remaining = selection.hosts.filter((host) => !removed.includes(host));
+    if (remaining.length === 0) {
+        return { kind: "full", plan: await planSkillRemoval([selection], options) };
+    }
+    const inspection = await inspectProjectSkillRemoval(selection, options);
+    const claudePath = path.join(path.resolve(options.projectRoot), ".claude", "skills", inspection.skillName);
+    const canonicalPath = path.join(path.resolve(options.projectRoot), ".agents", "skills", inspection.skillName);
+    if (removed.includes("claude") && inspection.paths[0] === claudePath) {
+        throw new SkillSelectionError(`Cannot remove Host claude: ${claudePath} is the only copy of this Skill and the remaining hosts (${remaining.join(", ")}) need it; remove the whole Skill instead`);
+    }
+    const deletePaths = removed.includes("claude") && inspection.paths.includes(claudePath) ? [claudePath] : [];
+    const preview = [`  remove hosts ${removed.join(", ")} from ${JSON.stringify(selection.path)}; remaining hosts: ${remaining.join(", ")}`];
+    if (deletePaths.length > 0) {
+        preview.push(`    delete ${claudePath} (managed Claude symlink)`, `    keep ${canonicalPath} (serves the remaining hosts)`);
+    }
+    else {
+        preview.push(`    no files are deleted: ${inspection.paths[0]} is kept for the remaining hosts`);
+    }
+    return { kind: "hosts", selection, removed, remaining, inspection, deletePaths, preview };
+}
+/** Execute step: rechecks, deletes only the removed Hosts' locations, then updates the record. */
+export async function executeHostRemoval(plan, operations, options, initialManaged) {
+    if (plan.kind === "full") {
+        await executeSkillRemoval(plan.plan, operations, options, initialManaged);
+        return;
+    }
+    const { listUserGlobalInstallations: list, updateUserGlobalInstallation: update } = operations;
+    if (!list || !update)
+        throw new Error("Configured Source operations cannot update user-global Skills");
+    assertRemovalInspectionUnchanged(plan.inspection, await inspectProjectSkillRemoval(plan.selection, options));
+    assertManagedInstallationRecordsUnchanged(initialManaged, await list.call(operations));
+    await removeProjectSkill(plan.selection, plan.inspection, options, plan.deletePaths);
+    try {
+        await update.call(operations, { ...plan.selection, hosts: plan.remaining });
+    }
+    catch (error) {
+        if (plan.deletePaths.length === 0)
+            throw error;
+        throw new Error(`Deleted ${plan.deletePaths.join(", ")} but the installation record was not updated (${describe(error)}); the record still lists ${plan.removed.join(", ")}. ` +
+            `Rerun \`agent-depot skill remove ${JSON.stringify(plan.selection.path)} --host ${plan.removed.join(" --host ")}\` to reconcile the record; the missing location is tolerated.`, { cause: error });
+    }
+}