@skaile/workspaces 5.7.0 → 5.8.0

package/dist/{chunk-D5HOETOB.js → chunk-H7QUDDKH.js}

@@ -1,20 +1,20 @@
-import { getStoreManifestsDir } from './chunk-DFFD4BFG.js';
-import { readManifestSourceConfig, discoverAssetsInTree } from './chunk-6VRJH4MR.js';
-import { installAgent, installTargetOf, deployAll, removeAsset, canonicalEntryRef, createScaffold } from './chunk-74EEFB52.js';
+import { getStoreManifestsDir } from './chunk-4MQS7CAF.js';
+import { readManifestSourceConfig, isManifestMode, discoverAssetsInTree } from './chunk-Y7QA2OLD.js';
+import { installAgent, installTargetOf, canonicalEntryRef, deployAll, removeAsset, createScaffold } from './chunk-YSHVQGUS.js';
 import { appendHistory, getRecentHistory, clearHistory } from './chunk-KTBKW2FI.js';
 import { commitChanges } from './chunk-UQ6LFBPZ.js';
-import { driverTargetSupportsAgents, CODEX_IDENTITY_DIR } from './chunk-AVCUPPG6.js';
-import { resolveConfiguredDriverTarget, GLOBAL_INSTALL_DIR_NAME, resolveLibraryDir, buildLibraryLockEntries, writeLock, buildLockFile, readLock, verifyLock, mergeLockFile, extractForPatch, generatePatch, savePatch, applyPatch } from './chunk-OOLT6HGP.js';
-import { resolveRuntimeAssets, factoryAssetRoots } from './chunk-SWO25LTO.js';
-import { deployedBase, deployedDir, isDeployed } from './chunk-G67BOI2J.js';
-import { resolveSkWorkspaceConfig, effectiveAgentInstances, resolveAgentDefinitionDir, loadMcpServerDeclarations, resolveGlobalHarnesses, resolveGlobalSkWorkspaceConfig, getGlobalCacheDir, sourceCacheKey, getRepoCommit, matchPin, coerceVersion, resolveAll, buildProvenanceIndex, ensureRepo, sourceShortName, scanRepo, SKAILE_YAML_DEFAULT, checkRepoStatus, resolveAsset, readLinks, storeManifestSlug } from './chunk-LCU5U5IW.js';
+import { driverTargetSupportsAgents, CODEX_IDENTITY_DIR } from './chunk-EF7NPDDU.js';
+import { resolveConfiguredDriverTarget, GLOBAL_INSTALL_DIR_NAME, resolveLibraryDir, buildLibraryLockEntries, buildLockFile, writeLock, readLock, verifyLock, mergeLockFile, extractForPatch, generatePatch, savePatch, applyPatch } from './chunk-36AFURKZ.js';
+import { resolveRuntimeAssets, factoryAssetRoots } from './chunk-GB7WDMH2.js';
+import { deployedBase, deployedDir, isDeployed, deployedPaths } from './chunk-PMECEZK3.js';
+import { resolveSkWorkspaceConfig, effectiveAgentInstances, resolveAgentDefinitionDir, loadMcpServerDeclarations, resolveGlobalHarnesses, resolveGlobalSkWorkspaceConfig, getGlobalCacheDir, sourceCacheKey, getRepoCommit, matchPin, resolveAll, buildProvenanceIndex, ensureRepo, sourceShortName, scanRepo, SKAILE_YAML_DEFAULT, checkRepoStatus, coerceVersion, resolveAsset, readLinks, MAX_PRESET_DEPTH, PresetDepthError, storeManifestSlug } from './chunk-JAKOMFC6.js';
 import { globalSkaileDir, globalCacheRoot, migrateLegacyDir } from './chunk-L5VSIPQD.js';
 import { DRIVER_TARGETS } from './chunk-CPSIPIX7.js';
-import { scanDirectory, parseRequires } from './chunk-TTPSDC2G.js';
-import { parseAssetRef, parseAssetRefLoose, assetRefToStr, slugifyAssetName } from './chunk-O7VPNKYN.js';
+import { scanDirectory, parseRequires } from './chunk-GTILM2CI.js';
+import { parseAssetRef, parseAssetRefLoose, assetRefToStr, slugifyAssetName, depToStr } from './chunk-QVNRCDTV.js';
 import { spawnSync } from 'child_process';
 import { existsSync, rmSync, readdirSync, lstatSync, unlinkSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
-import path, { join, resolve, dirname, sep, posix } from 'path';
+import path, { join, resolve, dirname, sep, relative, posix } from 'path';
 import { gt } from 'semver';
 import { stringify, parse } from 'yaml';
 import fs from 'fs/promises';
@@ -375,6 +375,26 @@ function libraryDiskHashes(libPath, cache, registry) {
   }
   return hashes;
 }
+function withLibraryFiles(entry, libPath, cache, registry) {
+  let byManifest = cache.get(libPath);
+  if (!byManifest) {
+    byManifest = /* @__PURE__ */ new Map();
+    const sourceConfig = readManifestSourceConfig(libPath, "library");
+    if (sourceConfig && isManifestMode(sourceConfig)) {
+      for (const a of discoverAssetsInTree(libPath, { sourceConfig, registry }).assets) {
+        const { assetRoot, files: files2 } = a.fileFilter;
+        byManifest.set(
+          resolve(a.manifestPath),
+          filesUnderManifestDir(files2, relative(assetRoot, a.manifestPath).split(sep).join("/"))
+        );
+      }
+    }
+    cache.set(libPath, byManifest);
+  }
+  const files = byManifest.get(resolve(entry.source));
+  if (files) entry.files = files;
+  return entry;
+}
 function newestLibraryDef(snap, libraryName, id) {
   const lib = snap?.libraries.find((l) => l.name === libraryName);
   if (!snap || !lib) return void 0;
@@ -386,6 +406,17 @@ function newestLibraryDef(snap, libraryName, id) {
   }
   return best;
 }
+function libraryPreference(isDefaultLib) {
+  return (a, b) => {
+    const va = coerceVersion(a.entry.version ?? "");
+    const vb = coerceVersion(b.entry.version ?? "");
+    if (gt(va, vb)) return -1;
+    if (gt(vb, va)) return 1;
+    const da = isDefaultLib.get(a.library) ? 0 : 1;
+    const db = isDefaultLib.get(b.library) ? 0 : 1;
+    return da - db || a.library.localeCompare(b.library);
+  };
+}
 function qualifyDepRef(ref, fallback) {
   const hash = ref.indexOf("#");
   const head = hash === -1 ? ref : ref.slice(0, hash);
@@ -407,7 +438,7 @@ function libraryEntryDepRefs(e) {
   }
   for (const r of e.requires ?? []) {
     const p = r.publisher ?? publisher;
-    if (p) refs.add(assetRefToStr({ kind: r.kind, name: r.name, publisher: p }));
+    if (p) refs.add(assetRefToStr({ kind: r.kind, name: r.name, publisher: p, pin: r.pin }));
   }
   return [...refs];
 }
@@ -489,6 +520,56 @@ function parseRefTolerant(ref) {
     return { kind, name, publisher: void 0 };
   }
 }
+function keptLockEntries(prev, missing) {
+  const out = { assets: {}, sources: [], refs: /* @__PURE__ */ new Set() };
+  if (!prev) return out;
+  for (const ref of missing) {
+    const want = parseRefTolerant(ref.split(" ")[0] ?? ref);
+    if (!want) continue;
+    for (const [key, entry] of Object.entries(prev.assets)) {
+      if (entry.library?.installed) continue;
+      const id = parseCanonicalLockKey(key);
+      if (id.kind !== want.kind || id.name !== want.name) continue;
+      if (want.publisher && id.publisher !== want.publisher) continue;
+      out.assets[key] = entry;
+      out.refs.add(ref);
+      const src = entry.source ? prev.sources.find((s) => s.url === entry.source?.url) : void 0;
+      if (src) out.sources.push(src);
+    }
+  }
+  return out;
+}
+function withKeptLockEntries(lock, kept) {
+  if (Object.keys(kept.assets).length === 0) return lock;
+  const sources = new Map(lock.sources.map((s) => [s.url, s]));
+  for (const s of kept.sources) if (!sources.has(s.url)) sources.set(s.url, s);
+  return {
+    ...lock,
+    // v4 once a library-origin entry is present (see buildLockFile).
+    schema_version: lock.schema_version === 4 || Object.values(kept.assets).some((e) => e.library) ? 4 : 3,
+    assets: { ...lock.assets, ...kept.assets },
+    sources: [...sources.values()].sort((a, b) => a.url.localeCompare(b.url))
+  };
+}
+function relockedRefs(prev, next) {
+  if (!prev) return [];
+  const fingerprint = (e) => [e.library?.version ?? "", e.library?.sha256 ?? e.sha256, e.source?.commit ?? ""].join("\0");
+  const out = [];
+  for (const [key, entry] of Object.entries(next.assets)) {
+    if (entry.library?.installed) continue;
+    const id = parseCanonicalLockKey(key);
+    const before = prev.assets[key] ? [key, prev.assets[key]] : Object.entries(prev.assets).find(([k]) => {
+      const o = parseCanonicalLockKey(k);
+      return o.kind === id.kind && o.name === id.name && o.publisher === id.publisher;
+    });
+    if (!before) continue;
+    if (before[0] !== key || fingerprint(before[1]) !== fingerprint(entry)) out.push(key);
+  }
+  return out;
+}
+function unregisteredLibraryFix(library, ref) {
+  return `register library "${library}" again with \`skaile library init ${library} --path <dir>\`, or drop the dependency with \`skaile remove ${ref}\``;
+}
 function memberIdentity(ref) {
   const parsed = parseRefTolerant(ref.trim());
   if (!parsed) return null;
@@ -828,6 +909,46 @@ var AssetManager = class {
     const resolved = /* @__PURE__ */ new Set();
     const libraryOf = /* @__PURE__ */ new Map();
     if (missing.length === 0) return { entries: [], resolved, libraryOf };
+    const scan = await this.scanLibraries();
+    if (!scan) return { entries: [], resolved, libraryOf };
+    const { byKey, isDefaultLib, libraryDir } = scan;
+    const entries = [];
+    const fileSets = /* @__PURE__ */ new Map();
+    const allCandidates = [...byKey.values()].flat();
+    for (const ref of missing) {
+      const parsed = parseRefTolerant(ref);
+      if (!parsed) continue;
+      const hash = ref.indexOf("#");
+      const pin = parsed.pin ?? (hash >= 0 ? ref.slice(hash + 1) : void 0);
+      const key = parsed.publisher ? `${parsed.kind}:@${parsed.publisher}/${parsed.name}` : void 0;
+      const pool = key ? byKey.get(key) ?? [] : allCandidates.filter((c) => c.entry.kind === parsed.kind && c.entry.name === parsed.name);
+      const candidates = pool.filter((c) => !pin || matchPin(pin, c.entry.version ?? ""));
+      if (candidates.length === 0) continue;
+      candidates.sort(libraryPreference(isDefaultLib));
+      const hit = candidates[0];
+      if (!opts.quiet) {
+        this.warnLibraryCollision(
+          `${hit.entry.kind}:@${hit.entry.publisher}/${hit.entry.name}`,
+          candidates,
+          hit
+        );
+      }
+      withLibraryFiles(hit.entry, libraryDir.get(hit.library), fileSets, this.registry);
+      entries.push(hit.entry);
+      libraryOf.set(hit.entry, hit.library);
+      resolved.add(ref);
+    }
+    return { entries, resolved, libraryOf };
+  }
+  /**
+   * Scan every candidate library (the set {@link resolveLibraryEntries} resolves from)
+   * into `kind:@publisher/name` → every holder, across all libraries and versions.
+   *
+   * @param minRoots - Return `null` without scanning when fewer candidate libraries
+   *   exist (a cross-library question needs at least two).
+   * @returns `null` when there is no candidate library or none holds an asset.
+   */
+  async scanLibraries(minRoots = 1) {
     const roots = [];
     for (const l of (await this.loadLibraryIndex())?.libraries ?? []) {
       if (l.name === GLOBAL_INSTALL_DIR_NAME) continue;
@@ -849,8 +970,9 @@ var AssetManager = class {
       }
     } catch {
     }
-    if (roots.length === 0) return { entries: [], resolved, libraryOf };
+    if (roots.length === 0 || roots.length < minRoots) return null;
     const byKey = /* @__PURE__ */ new Map();
+    const libraryDir = new Map(roots.map((r) => [r.name, r.dir]));
     const isDefaultLib = new Map(roots.map((r) => [r.name, r.isDefault]));
     for (const { name, dir } of roots) {
       const publisher = readDeclaredPublisher(dir) ?? slugifyAssetName(name);
@@ -861,56 +983,49 @@ var AssetManager = class {
         else byKey.set(key, [{ entry, library: name }]);
       }
     }
-    if (byKey.size === 0) return { entries: [], resolved, libraryOf };
-    const entries = [];
-    const allCandidates = [...byKey.values()].flat();
-    for (const ref of missing) {
-      const parsed = parseRefTolerant(ref);
-      if (!parsed) continue;
-      const hash = ref.indexOf("#");
-      const pin = parsed.pin ?? (hash >= 0 ? ref.slice(hash + 1) : void 0);
-      const key = parsed.publisher ? `${parsed.kind}:@${parsed.publisher}/${parsed.name}` : void 0;
-      const pool = key ? byKey.get(key) ?? [] : allCandidates.filter((c) => c.entry.kind === parsed.kind && c.entry.name === parsed.name);
-      const candidates = pool.filter((c) => !pin || matchPin(pin, c.entry.version ?? ""));
-      if (candidates.length === 0) continue;
-      candidates.sort((a, b) => {
-        const va = coerceVersion(a.entry.version ?? "");
-        const vb = coerceVersion(b.entry.version ?? "");
-        if (gt(va, vb)) return -1;
-        if (gt(vb, va)) return 1;
-        const da = isDefaultLib.get(a.library) ? 0 : 1;
-        const db = isDefaultLib.get(b.library) ? 0 : 1;
-        return da - db || a.library.localeCompare(b.library);
-      });
-      const hit = candidates[0];
-      if (!opts.quiet) {
-        this.warnLibraryCollision(
-          `${hit.entry.kind}:@${hit.entry.publisher}/${hit.entry.name}`,
-          candidates,
-          hit
-        );
-      }
-      entries.push(hit.entry);
-      libraryOf.set(hit.entry, hit.library);
-      resolved.add(ref);
+    return byKey.size === 0 ? null : { byKey, isDefaultLib, libraryDir };
+  }
+  /**
+   * Every ref that more than one registered library holds, with one row per holder
+   * (all libraries, all versions) in the order `add` prefers them: the first row is
+   * the one `add <ref>` deploys. The local index keeps a single row per ref and
+   * version, so `search` reads this to show equal-version copies in both libraries.
+   *
+   * @returns `kind:@publisher/name` → holders; refs held by one library are absent.
+   */
+  async libraryHolders() {
+    const out = /* @__PURE__ */ new Map();
+    const scan = await this.scanLibraries(2);
+    if (!scan) return out;
+    for (const [key, candidates] of scan.byKey) {
+      if (new Set(candidates.map((c) => c.library)).size < 2) continue;
+      const sorted = [...candidates].sort(libraryPreference(scan.isDefaultLib));
+      out.set(
+        key,
+        sorted.map((c, i) => ({
+          library: c.library,
+          version: c.entry.version ?? "",
+          description: c.entry.description ?? "",
+          picked: i === 0
+        }))
+      );
     }
-    return { entries, resolved, libraryOf };
+    return out;
   }
   /**
-   * Explain misses caused by a publisher change, for every missed publisher-qualified
-   * ref at once (one library scan, one lock read). Per ref:
-   * - `did you mean <ref>?` when a registered library holds the same kind + name
-   *   under another publisher;
-   * - `locked as <lockRef>; run skaile install to re-resolve` when the lock holds the
-   *   same kind + name under another publisher, records the library it came from, and
-   *   that library now holds the asset under yet another publisher than the locked
-   *   one. An unrelated asset that merely shares kind + name does not qualify.
+   * Where each missed publisher-qualified ref went when its publisher changed, for every
+   * ref at once (one library scan, one lock read):
+   * - `moved` when a registered library holds the same kind + name under another publisher;
+   * - `lockedAs` when the lock holds the same kind + name under another publisher, records
+   *   the library it came from, and that library now holds the asset under yet another
+   *   publisher than the locked one. An unrelated asset that merely shares kind + name does
+   *   not qualify.
    *
    * @param refs - Missed refs; a trailing `(reason)` after the first space is ignored.
-   * @returns hint text per ref, only for refs that have one. Never warns.
+   * @returns one finding per ref that has one. Never warns.
    */
-  async publisherChangeHints(refs) {
-    const out = {};
+  async publisherChangeFindings(refs) {
+    const out = /* @__PURE__ */ new Map();
     const wanted = /* @__PURE__ */ new Map();
     for (const ref of refs) {
       const parsed = parseRefTolerant(ref.split(" ")[0] ?? ref);
@@ -925,20 +1040,83 @@ var AssetManager = class {
     for (const [ref, w] of wanted) {
       const moved = lib.entries.find((e) => e.kind === w.kind && e.name === w.name);
       const movedLibrary = moved ? lib.libraryOf.get(moved) : void 0;
-      const hints = [];
+      const finding = {};
       for (const [key, entry] of lockEntries) {
         const id = parseCanonicalLockKey(key);
         if (id.kind === w.kind && id.name === w.name && id.publisher && id.publisher !== w.publisher && entry.library && moved && movedLibrary === entry.library.name && moved.publisher !== id.publisher) {
-          hints.push(
-            `locked as ${id.kind}:@${id.publisher}/${id.name}; run skaile install to re-resolve`
-          );
+          finding.lockedAs = `${id.kind}:@${id.publisher}/${id.name}`;
           break;
         }
       }
       if (moved && moved.publisher !== w.publisher) {
-        hints.push(`did you mean ${moved.kind}:@${moved.publisher}/${moved.name}?`);
+        finding.moved = {
+          ref: `${moved.kind}:@${moved.publisher}/${moved.name}`,
+          ...movedLibrary ? { library: movedLibrary } : {}
+        };
+      }
+      if (finding.lockedAs || finding.moved) out.set(ref, finding);
+    }
+    return out;
+  }
+  /**
+   * Explain misses caused by a publisher change, as parenthesized hint text per ref:
+   * `did you mean <ref>?` when a registered library holds the same kind + name under
+   * another publisher, and `locked as <lockRef>; run skaile install to re-resolve` when
+   * the lock holds it under the library's previous publisher (see
+   * {@link AssetManager.publisherChangeFindings}).
+   *
+   * @param refs - Missed refs; a trailing `(reason)` after the first space is ignored.
+   * @returns hint text per ref, only for refs that have one. Never warns.
+   */
+  async publisherChangeHints(refs) {
+    const out = {};
+    for (const [ref, f] of await this.publisherChangeFindings(refs)) {
+      const hints = [];
+      if (f.lockedAs) hints.push(`locked as ${f.lockedAs}; run skaile install to re-resolve`);
+      if (f.moved) hints.push(`did you mean ${f.moved.ref}?`);
+      out[ref] = hints.map((h) => ` (${h})`).join("");
+    }
+    return out;
+  }
+  /**
+   * What the user has to change for each ref that is locked from a library but resolves
+   * nowhere any more, where `skaile install` cannot help: the library is not registered
+   * (renamed away or removed), the library now publishes the asset under another
+   * publisher, or the library no longer holds it. A ref the lock does not tie to a
+   * library has no entry.
+   *
+   * @param refs - Declared or locked refs, `kind:@publisher/name` (a trailing `(reason)`
+   *   after the first space is ignored).
+   * @returns a phrase per ref that follows the ref name, without parentheses.
+   */
+  async unresolvedFixes(refs) {
+    const out = /* @__PURE__ */ new Map();
+    if (refs.length === 0) return out;
+    const lockEntries = Object.entries(this.tryReadLock()?.assets ?? {});
+    const snap = await this.loadLibraryIndex();
+    const findings = await this.publisherChangeFindings(refs);
+    for (const ref of refs) {
+      const want = parseRefTolerant(ref.split(" ")[0] ?? ref);
+      if (!want) continue;
+      const origin = lockEntries.map(([key, e]) => ({ id: parseCanonicalLockKey(key), library: e.library })).find(
+        ({ id, library }) => library && !library.installed && id.kind === want.kind && id.name === want.name && (!want.publisher || id.publisher === want.publisher)
+      )?.library;
+      if (!origin) continue;
+      const plain = want.publisher ? `${want.kind}:@${want.publisher}/${want.name}` : `${want.kind}:${want.name}`;
+      const moved = findings.get(ref)?.moved;
+      if (moved?.library && want.publisher) {
+        out.set(
+          ref,
+          `did you mean ${moved.ref}? Change the ref in skaile.yaml to it, or keep the old ref with \`skaile library set ${moved.library} publisher=${want.publisher}\``
+        );
+      } else if (!this.libraryPath(origin.name, snap)) {
+        out.set(ref, unregisteredLibraryFix(origin.name, plain));
+      } else {
+        out.set(
+          ref,
+          `library "${origin.name}" no longer holds it \u2014 restore it there, or drop the dependency with \`skaile remove ${plain}\``
+        );
       }
-      if (hints.length > 0) out[ref] = hints.map((h) => ` (${h})`).join("");
     }
     return out;
   }
@@ -958,6 +1136,56 @@ var AssetManager = class {
     if (this.onLibraryCollision) this.onLibraryCollision(msg);
     else console.warn(`skaile: ${msg}`);
   }
+  /** Kind, name and bare publisher of a deploy entry; the publisher comes from its canonical ref. */
+  entryIdentity(entry) {
+    const ref = parseAssetRefLoose(canonicalEntryRef(entry));
+    return {
+      kind: entry.kind,
+      name: entry.name,
+      publisher: ref?.publisher ?? entry.publisher?.replace(/^@/, "")
+    };
+  }
+  /**
+   * Refuse assets of one kind and name from different publishers: they deploy into the
+   * same folder, so the later one would silently overwrite the earlier. Throws one line
+   * naming the folder and the asset that holds it.
+   *
+   * @param incoming - Assets about to be deployed. Two of them clashing is refused.
+   * @param held - Assets the project already declares or has locked; one of them
+   *   clashing with an incoming asset is refused when its folder is on disk.
+   */
+  assertNoFolderCollision(incoming, held = []) {
+    const refOf = (a) => assetRefToStr({ kind: a.kind, name: a.name, publisher: a.publisher });
+    const differs = (a, b) => !!a.publisher && !!b.publisher && a.publisher !== b.publisher;
+    const shown = (dir) => this.global ? dir : relative(this.projectDir, dir);
+    const seen = /* @__PURE__ */ new Map();
+    for (const a of incoming) {
+      if (!a.kind || !a.name) continue;
+      const component = installTargetOf(this.registry, a.kind);
+      if (!component) continue;
+      const slot = `${component}/${a.name}`;
+      const prior = seen.get(slot);
+      if (prior && differs(prior, a)) {
+        const dir2 = deployedDir(component, a.name, this.driverTarget, this.global, this.projectDir);
+        throw new Error(
+          `${refOf(prior)} and ${refOf(a)} both deploy to ${shown(dir2)} \u2014 keep only one of them`
+        );
+      }
+      if (!prior) seen.set(slot, a);
+      const holder = held.find(
+        (h) => !!h.kind && h.name === a.name && installTargetOf(this.registry, h.kind) === component && differs(h, a)
+      );
+      if (!holder) continue;
+      const target = this.targetHarnesses().find(
+        (t) => isDeployed(component, a.name, t, this.global, this.projectDir)
+      );
+      if (!target) continue;
+      const dir = deployedDir(component, a.name, target, this.global, this.projectDir);
+      throw new Error(
+        `${refOf(a)} would overwrite ${shown(dir)}, which ${refOf(holder)} already holds \u2014 run skaile remove ${refOf(holder)} first`
+      );
+    }
+  }
   /**
    * Open the local index and snapshot its libraries + asset definitions.
    * Best-effort: no index file (never indexed), or any open/guard failure,
@@ -1022,6 +1250,7 @@ var AssetManager = class {
     if (locked.length === 0) return { entries, missing };
     const snap = await this.loadLibraryIndex();
     const diskHashes = /* @__PURE__ */ new Map();
+    const fileSets = /* @__PURE__ */ new Map();
     for (const [ref, e] of locked) {
       const origin = e.library;
       const { publisher, kind, name } = parseCanonicalLockKey(ref);
@@ -1032,7 +1261,7 @@ var AssetManager = class {
       const libPath = this.libraryPath(origin.name, snap);
       if (!libPath) {
         missing.push(
-          `${ref} (library "${origin.name}" is not registered \u2014 renamed or removed? re-lock with \`skaile install\`)`
+          `${ref} (library "${origin.name}" is not registered \u2014 renamed or removed? ${unregisteredLibraryFix(origin.name, `${kind}:@${publisher}/${name}`)}; \`skaile install\` re-locks it when another library holds it now)`
         );
         continue;
       }
@@ -1060,7 +1289,7 @@ var AssetManager = class {
           continue;
         }
       }
-      entries.push(found);
+      entries.push(withLibraryFiles(found, libPath, fileSets, this.registry));
     }
     return { entries, missing };
   }
@@ -1099,7 +1328,8 @@ var AssetManager = class {
       stores: opts.stores,
       storeFetcher: this.storeFetcherFor(opts.stores),
       projectDir: this.projectDir,
-      knownKinds: this.knownKinds
+      knownKinds: this.knownKinds,
+      declaredRefs: opts.declaredRefs
     });
     if (first.missing.length === 0) return first;
     const fallback = await this.globalStoreFallback(opts.stores);
@@ -1112,7 +1342,8 @@ var AssetManager = class {
         stores,
         storeFetcher: this.storeFetcherFor(stores),
         projectDir: this.projectDir,
-        knownKinds: this.knownKinds
+        knownKinds: this.knownKinds,
+        declaredRefs: opts.declaredRefs
       });
       return retry.missing.length < first.missing.length ? retry : first;
     } catch {
@@ -1146,16 +1377,50 @@ var AssetManager = class {
     const missing = /* @__PURE__ */ new Set();
     const seen = /* @__PURE__ */ new Set();
     const covered = /* @__PURE__ */ new Set();
+    const declaredById = /* @__PURE__ */ new Map();
+    for (const d of opts.declaredRefs ?? []) {
+      const id = refIdentity(d);
+      if (id !== null) declaredById.set(id, d);
+    }
+    const presetParent = /* @__PURE__ */ new Map();
     const absorb = (hit) => {
       const next = [];
       for (const e of hit.entries) {
-        lib.entries.push(e);
         const origin = hit.libraryOf.get(e);
-        if (origin) lib.libraryOf.set(e, origin);
         const id = `${e.publisher}/${e.kind}:${e.name}`;
         seen.add(id);
         covered.add(id);
-        next.push(...libraryEntryDepRefs(e));
+        const deps2 = libraryEntryDepRefs(e);
+        if (e.kind === "preset") {
+          const chain = [id];
+          for (let up = presetParent.get(id); up !== void 0; up = presetParent.get(up)) {
+            chain.unshift(up);
+          }
+          if (chain.length > MAX_PRESET_DEPTH) {
+            throw new PresetDepthError("depth", canonicalEntryRef(e), chain);
+          }
+          for (const dep of deps2) {
+            const depId = refIdentity(dep);
+            if (depId === null || !depId.includes("/preset:")) continue;
+            if (chain.includes(depId)) throw new PresetDepthError("cycle", dep, [...chain, depId]);
+            if (!presetParent.has(depId)) presetParent.set(depId, id);
+          }
+          presets.push({
+            ref: canonicalEntryRef(e),
+            assets: deps2.filter((d) => !d.startsWith("preset:")).length,
+            skipped: e.skippedItems ?? 0,
+            ...origin ? { library: origin } : {}
+          });
+        } else {
+          lib.entries.push(e);
+          if (origin) lib.libraryOf.set(e, origin);
+        }
+        next.push(
+          ...deps2.map((dep) => {
+            const depId = refIdentity(dep);
+            return depId !== null && declaredById.get(depId) || dep;
+          })
+        );
       }
       for (const r of hit.resolved) lib.resolved.add(r);
       return next;
@@ -1175,7 +1440,7 @@ var AssetManager = class {
       const libraryTried = new Set(
         fresh.filter((ref) => {
           const id = refIdentity(ref);
-          return id !== null && !id.includes("/preset:") && (opts.provenanceIndex.get(id)?.length ?? 0) === 0;
+          return id !== null && (opts.provenanceIndex.get(id)?.length ?? 0) === 0;
         })
       );
       const hit = await this.resolveLibraryEntries([...libraryTried]);
@@ -1371,7 +1636,7 @@ var AssetManager = class {
   async install(opts) {
     const { repositories, sources, stores, dependencies, overrides, patches } = this.loadConfig();
     if (opts?.locked) {
-      return this.installLocked(repositories, patches);
+      return this.installLocked(repositories, patches, dependencies);
     }
     const cloneError = this.ensureSourceClones(repositories, sources);
     if (cloneError) return cloneError;
@@ -1381,13 +1646,30 @@ var AssetManager = class {
     });
     const { resolved, missing, overridesApplied, lib, presets } = await this.resolveLibraryFirst(
       dependencies,
-      { provenanceIndex, overrides, stores }
+      { provenanceIndex, overrides, stores, declaredRefs: dependencies }
     );
+    this.assertNoFolderCollision([...resolved, ...lib.entries.map((e) => this.entryIdentity(e))]);
     const stillMissing = missing.filter((m) => !lib.resolved.has(m));
     const missingHints = await this.publisherChangeHints(stillMissing);
+    const prevLock = this.tryReadLock();
+    const kept = keptLockEntries(prevLock, stillMissing);
+    const fixes = await this.unresolvedFixes(stillMissing);
+    for (const ref of /* @__PURE__ */ new Set([...kept.refs, ...fixes.keys()])) {
+      const fix = fixes.get(ref);
+      const notes = [
+        kept.refs.has(ref) ? "the deployed copy and its lock entry are kept" : void 0,
+        fix
+      ].filter((n) => n !== void 0);
+      missingHints[ref] = `${fix ? "" : missingHints[ref] ?? ""} (${notes.join("; ")})`;
+    }
     const directLock = this.directInstallLockEntries();
     const libraryLock = { ...directLock, ...await this.libraryLockEntries(lib) };
-    const removed = this.reconcileRemovedAssets(resolved, new Set(Object.keys(libraryLock)));
+    const freshLock = buildLockFile(resolved, overridesApplied, libraryLock);
+    await this.keepRequiredByKept(prevLock, kept, Object.keys(freshLock.assets));
+    const removed = this.reconcileRemovedAssets(
+      resolved,
+      /* @__PURE__ */ new Set([...Object.keys(libraryLock), ...Object.keys(kept.assets)])
+    );
     const entries = [...await this.buildCatalogEntries(resolved, repositories), ...lib.entries];
     const deployed = [
       ...new Set(
@@ -1399,8 +1681,11 @@ var AssetManager = class {
     await this.renderDriverMcpConfig();
     const agentRender = this.renderAgentInstances();
     const lockWritten = resolved.length > 0 || lib.entries.length > 0 || existsSync(this.lockPath);
+    let relocked = [];
     if (lockWritten) {
-      writeLock(this.lockPath, buildLockFile(resolved, overridesApplied, libraryLock));
+      const lockData = withKeptLockEntries(freshLock, kept);
+      relocked = relockedRefs(prevLock, lockData);
+      writeLock(this.lockPath, lockData);
     }
     this.recordInstallHistory(deployed, removed);
     const { npmInstalled, npmFailed } = await this.installRuntimeAssetDeps();
@@ -1409,6 +1694,7 @@ var AssetManager = class {
       removed,
       missing: stillMissing,
       ...Object.keys(missingHints).length > 0 ? { missingHints } : {},
+      ...relocked.length > 0 ? { relocked } : {},
       lockWritten,
       npmInstalled,
       npmFailed,
@@ -1416,6 +1702,49 @@ var AssetManager = class {
       ...agentRender
     };
   }
+  /**
+   * Extend `kept` (see {@link keptLockEntries}) with every previous lock entry a kept asset
+   * requires, transitively, that the new lock (`freshKeys`) does not already carry. The lock
+   * records no edges, so they are read from the kept asset's deployed copy, where the
+   * requirement is publisher-qualified the same way a library scan does it. A copy that
+   * cannot be read has no known requirements.
+   */
+  async keepRequiredByKept(prev, kept, freshKeys) {
+    if (!prev) return;
+    const fresh = freshKeys.map(parseCanonicalLockKey);
+    const queue = Object.keys(kept.assets);
+    for (const key of queue) {
+      for (const dep of await this.deployedRequirements(key)) {
+        const want = memberIdentity(dep);
+        if (!want) continue;
+        const matches = (id) => id.kind === want.kind && id.name === want.name && (!want.publisher || !id.publisher || id.publisher === want.publisher);
+        if (fresh.some(matches)) continue;
+        for (const [depKey, entry] of Object.entries(prev.assets)) {
+          if (depKey in kept.assets || entry.library?.installed) continue;
+          if (!matches(parseCanonicalLockKey(depKey))) continue;
+          kept.assets[depKey] = entry;
+          queue.push(depKey);
+          const src = entry.source ? prev.sources.find((s) => s.url === entry.source?.url) : void 0;
+          if (src) kept.sources.push(src);
+        }
+      }
+    }
+  }
+  /** Publisher-qualified refs the deployed copy of the asset behind lock `key` requires. */
+  async deployedRequirements(key) {
+    const { kind, name, publisher } = parseCanonicalLockKey(key);
+    const component = kind ? this.installTarget(kind) : void 0;
+    if (!kind || !name || !component) return [];
+    const dir = deployedDir(component, name, this.driverTarget, this.global, this.projectDir);
+    if (!existsSync(dir)) return [];
+    try {
+      const scanned = await scanDirectory(dir, publisher ?? "", { knownKinds: this.knownKinds });
+      const own = scanned.find((e) => e.kind === kind && e.name === name);
+      return own ? libraryEntryDepRefs(own) : [];
+    } catch {
+      return [];
+    }
+  }
   /**
    * Ensure all source clones are present/up to date. Returns an early
    * {@link InstallResult} describing the failed source on the first error, or
@@ -1480,6 +1809,7 @@ var AssetManager = class {
       for (const ref of Object.keys(oldLock.assets)) {
         if (!resolvedRefs.has(ref)) {
           const { kind, name } = parseCanonicalLockKey(ref);
+          if (kind === "preset") continue;
           if (kind && name) {
             for (const t of this.targetHarnesses()) removeAsset(kind, name, this.deployOptsFor(t));
             removed.push(ref);
@@ -1605,11 +1935,12 @@ var AssetManager = class {
     }
     return { npmInstalled, npmFailed };
   }
-  async installLocked(repositories, patches) {
+  async installLocked(repositories, patches, dependencies) {
     const lock = this.tryReadLock();
     if (!lock) {
       throw new Error("No lock file found. Run `skaile install` first.");
     }
+    this.assertNoFolderCollision(Object.keys(lock.assets).map(parseCanonicalLockKey));
     const declBySlug = new Map(Object.entries(repositories));
     const factoryUrl = normalizeRepoUrl(FACTORY_SOURCE_URL);
     const factoryDir = Object.values(repositories).find((d) => d.factory)?.path ?? null;
@@ -1634,6 +1965,16 @@ var AssetManager = class {
       throw new Error(`Lock file verification failed:
   ${issues.join("\n  ")}`);
     }
+    const presetGaps = await this.declaredPresetGaps(dependencies, lock);
+    if (presetGaps.size > 0) {
+      const lines = [...presetGaps].flatMap(
+        ([preset, gaps2]) => gaps2.map((g) => `${preset} item ${g.ref}`)
+      );
+      throw new Error(
+        `Lock file does not pin every item of the declared presets (not resolved by \`skaile install\`):
+  ${lines.join("\n  ")}`
+      );
+    }
     const resolved = [];
     for (const [ref, entry] of Object.entries(lock.assets)) {
       if (!entry.source) continue;
@@ -1672,10 +2013,20 @@ var AssetManager = class {
     ];
     await this.renderDriverMcpConfig();
     const agentRender = this.renderAgentInstances();
+    const alreadyMissing = new Set(
+      library.missing.map((m) => {
+        const p = parseRefTolerant(m.split(" ")[0] ?? m);
+        return p ? `${p.kind}:${p.name}` : m;
+      })
+    );
+    const gaps = (await this.lockGaps()).filter((g) => {
+      const p = parseRefTolerant(g.ref);
+      return !(p && alreadyMissing.has(`${p.kind}:${p.name}`));
+    }).map((g) => g.message);
     return {
       deployed,
       removed: [],
-      missing: library.missing,
+      missing: [...library.missing, ...gaps],
       lockWritten: false,
       ...agentRender
     };
@@ -1693,27 +2044,41 @@ var AssetManager = class {
    *   store/factory sources. Defaults to copy.
    * @param opts.onLibraryOrigin - Called once per deployed library-origin asset with its
    *   canonical ref and the name of the library it was resolved from.
+   * @param opts.onPresets - Called once with the presets expanded into this add (the
+   *   added preset and any it nests); a library-held preset names its library.
    * @returns Array of asset refs that were deployed in this call.
-   * @throws When the asset cannot be found in any configured repository.
+   * @throws When the asset cannot be found in any configured repository, or when a
+   *   preset's items do not all resolve (nothing is deployed or recorded then).
    */
   async add(ref, opts) {
-    const { repositories, sources, stores, overrides, patches } = this.loadConfig();
-    parseAssetRef(ref);
+    const { repositories, sources, stores, dependencies, overrides, patches } = this.loadConfig();
+    const parsed = parseAssetRef(ref);
     this.ensureSourceClonesQuiet(repositories, sources);
     const provenanceIndex = await buildProvenanceIndex(this.buildClones(repositories), {
       projectDir: this.projectDir,
       knownKinds: this.knownKinds
     });
-    const { resolved, missing, overridesApplied, lib } = await this.resolveLibraryFirst([ref], {
-      provenanceIndex,
-      overrides,
-      stores
-    });
-    if (resolved.length === 0 && lib.entries.length === 0) {
+    const { resolved, missing, overridesApplied, lib, presets } = await this.resolveLibraryFirst(
+      [ref],
+      { provenanceIndex, overrides, stores, declaredRefs: dependencies }
+    );
+    if (resolved.length === 0 && lib.entries.length === 0 && presets.length === 0) {
       throw new Error(
         `Asset not found: ${ref}${(await this.publisherChangeHints([ref]))[ref] ?? ""}${missing.length ? ` (missing: ${missing.join(", ")})` : ""}`
       );
     }
+    if (parsed.kind === "preset" && missing.length > 0) {
+      throw new Error(
+        `Preset ${ref} has items that do not resolve: ${missing.join(", ")} \u2014 nothing was added`
+      );
+    }
+    this.assertNoFolderCollision(
+      [...resolved, ...lib.entries.map((e) => this.entryIdentity(e))],
+      [
+        ...Object.keys(this.tryReadLock()?.assets ?? {}).map(parseCanonicalLockKey),
+        ...dependencies.map((d) => parseAssetRefLoose(d) ?? {})
+      ]
+    );
     if (missing.length > 0) {
       console.warn(
         `skaile: ${ref} was added without unresolved dependencies: ${missing.join(", ")}`
@@ -1734,6 +2099,7 @@ var AssetManager = class {
         if (origin && deployed.includes(deployedRef)) opts.onLibraryOrigin(deployedRef, origin);
       }
     }
+    if (presets.length > 0) opts?.onPresets?.(presets);
     this.addDependencyToConfig(ref);
     await this.renderDriverMcpConfig();
     this.renderAgentInstances();
@@ -1802,7 +2168,7 @@ var AssetManager = class {
       const out = [];
       const seen = /* @__PURE__ */ new Set();
       for (const p of await this.search(void 0, "preset")) {
-        const members = [...p.dependencies, ...p.requires.map((d) => `${d.kind}:${d.name}`)];
+        const members = [...p.dependencies, ...p.requires.map(depToStr)];
         if (!members.some((m) => sameAsset(memberIdentity(m), target))) continue;
         const publisher = p.publisher?.replace(/^@/, "");
         const presetId = { kind: "preset", name: p.name, publisher };
@@ -1988,20 +2354,103 @@ var AssetManager = class {
    * more (e.g. its library file was deleted): the declaration and lock entry
    * would otherwise be stuck behind a "not deployed" refusal.
    *
+   * Removes only `ref` itself; use {@link removeWithDependencies} to also drop the
+   * dependencies it leaves orphaned.
+   *
    * Deliberately does NOT re-render the driver target's MCP config: the render
    * step is async (the declaration resolver is), and making this synchronous
    * method async would break every external caller. A removed MCP server's
    * generated entry is dropped by the next {@link AssetManager.install} — see
    * {@link renderMcpServerConfig}.
    *
-   * @param ref - Asset ref in `kind:name` form (e.g. `skill:my-skill`).
+   * @param ref - Asset ref: `kind:@publisher/name`, or the short `kind:name` /
+   *   `name` form when exactly one declared, locked or deployed asset matches it.
    * @returns `true` if anything changed (files undeployed, declaration or lock
    *   entry removed), `false` if the asset was neither deployed nor declared.
    *   A `preset:` ref has no deployed files: only its declaration goes — its
    *   expanded items leave with the next `skaile install`.
+   * @throws When `ref` is malformed, or a short ref matches several assets (the
+   *   message lists them).
    */
   remove(ref) {
-    const parsed = parseAssetRef(ref);
+    const target = this.resolveRemoveTarget(ref);
+    return target ? this.removeResolved(target) : false;
+  }
+  /**
+   * {@link remove} `ref`, then drop the dependencies that removal left orphaned:
+   * locked assets `ref` required (directly or through one another) that
+   * `skaile.yaml` no longer declares and no remaining locked asset requires. A
+   * preset's items count as its requirements. They are undeployed and unlocked;
+   * a dependency still declared or required elsewhere stays.
+   *
+   * @returns `changed` as {@link remove}; `pruned` the canonical refs
+   *   (`kind:@publisher/name`) of the dependencies dropped as well.
+   */
+  async removeWithDependencies(ref) {
+    const target = this.resolveRemoveTarget(ref);
+    if (!target) return { changed: false, pruned: [] };
+    const asked = target.publisher ? assetRefToStr({ kind: target.kind, name: target.name, publisher: target.publisher }) : `${target.kind}:${target.name}`;
+    let entry = null;
+    try {
+      entry = await this.info(asked);
+    } catch {
+    }
+    const requiredRefs = entry ? libraryEntryDepRefs(entry) : [];
+    const changed = this.removeResolved(target);
+    if (!changed || requiredRefs.length === 0) return { changed, pruned: [] };
+    return { changed, pruned: await this.pruneOrphans(requiredRefs) };
+  }
+  /**
+   * Resolve the identity {@link remove} acts on. A publisher-qualified ref is taken
+   * as written; a short ref (`kind:name`, or just `name`) is matched on kind + name
+   * against the declared dependencies, the lock and the deployed assets, like
+   * `why` / `diff` do.
+   *
+   * @returns the identity, or `null` when a name-only ref matches nothing.
+   * @throws On a malformed ref, or when a short ref matches more than one asset.
+   */
+  resolveRemoveTarget(ref) {
+    const trimmed = ref.trim();
+    try {
+      return parseAssetRef(trimmed);
+    } catch (err) {
+      if (!(err instanceof Error) || !err.message.startsWith("publisher required")) throw err;
+      const colon = trimmed.indexOf(":");
+      const rawKind = colon === -1 ? void 0 : trimmed.slice(0, colon).trim();
+      const kind = rawKind === "mcp" ? "mcp-server" : rawKind;
+      const hash = trimmed.indexOf("#", colon + 1);
+      const name = trimmed.slice(colon + 1, hash === -1 ? void 0 : hash).trim();
+      if (!name || /[@/\s]/.test(name)) throw err;
+      const found = [];
+      const note = (id) => {
+        if (!id?.kind || id.name !== name || kind && id.kind !== kind) return;
+        found.push({ kind: id.kind, name: id.name, publisher: id.publisher });
+      };
+      try {
+        for (const dep of this.loadConfig().dependencies) note(memberIdentity(dep));
+      } catch {
+      }
+      for (const key of Object.keys(this.tryReadLock()?.assets ?? {})) {
+        note(parseCanonicalLockKey(key));
+      }
+      for (const e of this.listDeployed()) note(e);
+      const qualified = found.filter((f) => f.publisher);
+      const distinct = /* @__PURE__ */ new Map();
+      for (const f of found) {
+        if (!f.publisher && qualified.some((q) => q.kind === f.kind)) continue;
+        distinct.set(`${f.kind}:${f.publisher ?? ""}/${f.name}`, f);
+      }
+      const matches = [...distinct.values()];
+      if (matches.length > 1) {
+        const list = matches.map((m) => m.publisher ? `${m.kind}:@${m.publisher}/${m.name}` : `${m.kind}:${m.name}`).join(", ");
+        throw new Error(`"${ref}" matches several assets (${list}) \u2014 name one with its full ref.`);
+      }
+      if (matches.length === 1) return matches[0];
+      return kind ? { kind, name } : null;
+    }
+  }
+  /** Undeploy `parsed` from every target harness and drop its declaration and lock entry. */
+  removeResolved(parsed) {
     let undeployed = false;
     for (const t of this.targetHarnesses()) {
       if (removeAsset(parsed.kind, parsed.name, this.deployOptsFor(t))) undeployed = true;
@@ -2019,6 +2468,38 @@ var AssetManager = class {
     }
     return changed;
   }
+  /**
+   * Drop the locked assets among `requiredRefs` (and what they require in turn) that
+   * nothing needs any more: not declared in `skaile.yaml`, not required by a locked
+   * asset outside that set. Call after the requiring asset is gone.
+   *
+   * @returns the canonical refs of the assets dropped.
+   */
+  async pruneOrphans(requiredRefs) {
+    const lock = this.tryReadLock();
+    if (!lock) return [];
+    const { requires, roots, findKey } = await this.lockedGraph(lock);
+    const closure = (seeds) => {
+      const out = new Set(seeds);
+      for (const node of out) for (const dep of requires.get(node) ?? []) out.add(dep);
+      return out;
+    };
+    const candidates = closure(requiredRefs.map(findKey).filter((k) => !!k));
+    const needed = closure([
+      ...roots,
+      ...Object.keys(lock.assets).filter((k) => !candidates.has(k))
+    ]);
+    const pruned = [];
+    for (const key of candidates) {
+      if (needed.has(key) || !lock.assets[key]) continue;
+      const { kind, name, publisher } = parseCanonicalLockKey(key);
+      if (!kind || !name) continue;
+      this.removeResolved({ kind, name, publisher });
+      this.pruneLockEntry({ kind, name, publisher });
+      pruned.push(publisher ? assetRefToStr({ kind, name, publisher }) : `${kind}:${name}`);
+    }
+    return pruned;
+  }
   /**
    * Drop every lock entry matching a removed asset's identity, version-agnostic so
    * a content-sha pseudo-version key is pruned too. Symmetric with {@link add}'s
@@ -2199,9 +2680,15 @@ var AssetManager = class {
     for (const { kind, name, component: k } of tracked.values()) {
       const legacy = deployedDir(k, name, "claude-code", false, this.projectDir);
       if (legacy === deployedDir(k, name, this.driverTarget, false, this.projectDir)) continue;
-      if (isDeployed(k, name, "claude-code", false, this.projectDir)) {
-        out.push({ kind, name, path: legacy });
-      }
+      const found = deployedPaths(k, name, "claude-code", false, this.projectDir).find((p) => {
+        try {
+          lstatSync(p);
+          return true;
+        } catch {
+          return false;
+        }
+      });
+      if (found) out.push({ kind, name, path: found });
     }
     return out.sort((a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name));
   }
@@ -2235,6 +2722,7 @@ var AssetManager = class {
     const dependencies = resolveSkWorkspaceConfig(this.projectDir).dependencies ?? [];
     const lock = this.tryReadLock();
     const lockKeys = lock ? Object.keys(lock.assets).map(parseCanonicalLockKey) : [];
+    const presetGaps = await this.declaredPresetGaps(dependencies, lock);
     let wiredMcps;
     const wiredMcpNames = async () => {
       if (wiredMcps === void 0) {
@@ -2257,7 +2745,7 @@ var AssetManager = class {
         continue;
       }
       if (kind && parsed.kind !== kind) continue;
-      const locked = parsed.kind === "preset" ? lock !== null : lockKeys.some(
+      const locked = parsed.kind === "preset" ? lock !== null && !presetGaps.get(ref)?.length : lockKeys.some(
         (k) => k.kind === parsed.kind && k.name === parsed.name && (!parsed.publisher || k.publisher === parsed.publisher)
       );
       let state;
@@ -2285,6 +2773,38 @@ var AssetManager = class {
     }
     return out;
   }
+  /**
+   * Library-locked assets whose deployed directory lacks files the deploy writes —
+   * a deleted `build.py` / `scripts/` helper next to an intact `SKILL.md`. The
+   * expected set is the library entry's file set (every file under its manifest
+   * `root:`), the same bytes the lock hashes; only presence is checked, so a
+   * local edit never counts. An asset with no deployed directory is not listed
+   * (`listDeclared` reports it as drift); an agent is rendered, not copied, so it
+   * has no file mirror to compare. `skaile install` restores what is listed.
+   *
+   * @returns One {@link IncompleteDeploy} per affected asset; empty when healthy
+   *   or when the project has no lock.
+   */
+  async incompleteDeploys() {
+    const lock = this.tryReadLock();
+    if (!lock) return [];
+    const locked = Object.entries(lock.assets).filter(([, e]) => e.library !== void 0 && !e.library.installed).map(([key]) => key);
+    if (locked.length === 0) return [];
+    const lib = await this.resolveLibraryEntries(locked, { quiet: true });
+    const out = [];
+    for (const entry of lib.entries) {
+      const component = this.installTarget(entry.kind);
+      if (!entry.files || !component || component === "agent") continue;
+      const dest = join(
+        deployedBase(component, this.driverTarget, this.global, this.projectDir),
+        entry.name
+      );
+      if (!existsSync(dest)) continue;
+      const missing = entry.files.filter((rel) => !existsSync(join(dest, rel)));
+      if (missing.length > 0) out.push({ ref: canonicalEntryRef(entry), missing });
+    }
+    return out;
+  }
   /**
    * Per-harness reconciliation of the **global** declared deps
    * (`~/.skaile/skaile.yaml`) against each global harness's deploy dir. The
@@ -2382,29 +2902,115 @@ var AssetManager = class {
     }
     return repoStatuses;
   }
+  /**
+   * Requirement graph of the locked assets, for {@link tree} / {@link why} / removal pruning.
+   *
+   * The lock records no edges, so they are rebuilt from each locked asset's own
+   * declaration (`requires`, manifest `dependencies`, a preset's items) — the same
+   * source the install walk reads, via {@link info}. An asset that no source or
+   * library can be found for has no known requirements. Nodes are lock keys, plus
+   * each declared `preset:` that the lock does not carry (a preset is expanded at
+   * install, never locked), keyed by its declared ref.
+   *
+   * @returns `requires` (node → the lock keys it requires), `roots` (nodes
+   *   `skaile.yaml` declares) and `findKey` (a ref → its lock key, version-agnostic).
+   */
+  async lockedGraph(lock) {
+    const locked = Object.keys(lock.assets).map((key) => ({ key, ...parseCanonicalLockKey(key) }));
+    const findKey = (ref) => {
+      const id = memberIdentity(ref);
+      if (!id) return void 0;
+      return locked.find(
+        (l) => l.kind === id.kind && l.name === id.name && (!id.publisher || !l.publisher || l.publisher === id.publisher)
+      )?.key;
+    };
+    const requires = /* @__PURE__ */ new Map();
+    const link = async (node, ref) => {
+      const out = [];
+      try {
+        const entry = await this.info(ref);
+        for (const dep of entry ? libraryEntryDepRefs(entry) : []) {
+          const key = findKey(dep);
+          if (key && key !== node && !out.includes(key)) out.push(key);
+        }
+      } catch {
+      }
+      requires.set(node, out);
+    };
+    for (const l of locked) {
+      await link(
+        l.key,
+        l.publisher ? `${l.kind}:@${l.publisher}/${l.name}` : `${l.kind}:${l.name}`
+      );
+    }
+    const roots = [];
+    let declared = [];
+    try {
+      declared = this.loadConfig().dependencies;
+    } catch {
+    }
+    for (const dep of declared) {
+      const key = findKey(dep);
+      if (key) {
+        if (!roots.includes(key)) roots.push(key);
+      } else if (memberIdentity(dep)?.kind === "preset" && !roots.includes(dep)) {
+        await link(dep, dep);
+        roots.push(dep);
+      }
+    }
+    return { requires, roots, findKey };
+  }
   /**
    * Build the resolved dependency tree from the lock file.
    *
+   * Required assets nest under the asset that requires them (see {@link lockedGraph});
+   * an asset required by several parents appears under each, and a dependency cycle
+   * is cut where it would repeat.
+   *
    * @returns Root {@link DependencyNode} with `ref === "project"` whose children
-   *   are the directly-declared dependencies, each with their own transitive subtrees.
+   *   are the directly-declared assets, followed by locked assets nothing requires,
+   *   each with the assets it requires as children.
    *   Returns a single node with `ref === "(no lock file)"` when no lock exists.
    */
-  tree() {
+  async tree() {
     const lock = this.tryReadLock();
     if (!lock) return { ref: "(no lock file)", children: [] };
-    return {
-      ref: "project",
-      children: Object.keys(lock.assets).map((ref) => ({ ref, children: [] }))
+    const { requires, roots } = await this.lockedGraph(lock);
+    const required = new Set([...requires.values()].flat());
+    const build = (ref, path2) => ({
+      ref,
+      children: (requires.get(ref) ?? []).filter((child) => !path2.has(child)).map((child) => build(child, /* @__PURE__ */ new Set([...path2, child])))
+    });
+    const shown = /* @__PURE__ */ new Set();
+    const top = [];
+    const addTop = (ref) => {
+      const node = build(ref, /* @__PURE__ */ new Set([ref]));
+      top.push(node);
+      const walk = (n) => {
+        shown.add(n.ref);
+        for (const c of n.children) walk(c);
+      };
+      walk(node);
     };
+    const lockKeys = Object.keys(lock.assets);
+    for (const ref of roots) addTop(ref);
+    for (const ref of lockKeys) if (!roots.includes(ref) && !required.has(ref)) addTop(ref);
+    for (const ref of lockKeys) if (!shown.has(ref)) addTop(ref);
+    return { ref: "project", children: top };
   }
   /**
-   * Explain why an asset is installed by tracing its dependency chain in the lock file.
+   * Explain why an asset is installed by tracing its dependency chain.
+   *
+   * The chain is read from the requirement graph ({@link lockedGraph}): the asset,
+   * then the asset that requires it, and so on up to a dependency `skaile.yaml`
+   * declares (the shortest such path; cycles are not followed twice).
    *
    * @param ref - Asset ref in `kind:name` form.
-   * @returns Chain of refs from the asset back to `"direct (skaile.yaml)"`, or `[]` when
-   *   the asset is not in the lock file.
+   * @returns Chain of refs from the asset back to `"direct (skaile.yaml)"`; an asset
+   *   no declared dependency reaches ends in `"not required by a declared dependency"`
+   *   instead. `[]` when the asset is not in the lock file.
    */
-  why(ref) {
+  async why(ref) {
     const lock = this.tryReadLock();
     if (!lock) return [];
     const bare = (s) => s.includes("#") ? s.slice(0, s.indexOf("#")) : s;
@@ -2417,7 +3023,29 @@ var AssetManager = class {
     };
     const key = lock.assets[ref] ? ref : Object.keys(lock.assets).find(matchesIdentity);
     if (!key) return [];
-    return [key, "direct (skaile.yaml)"];
+    const { requires, roots } = await this.lockedGraph(lock);
+    if (roots.includes(key)) return [key, "direct (skaile.yaml)"];
+    const requirers = /* @__PURE__ */ new Map();
+    for (const [node, deps] of requires) {
+      for (const dep of deps) requirers.set(dep, [...requirers.get(dep) ?? [], node]);
+    }
+    const child = /* @__PURE__ */ new Map();
+    const seen = /* @__PURE__ */ new Set([key]);
+    const queue = [key];
+    for (let node = queue.shift(); node !== void 0; node = queue.shift()) {
+      for (const parent of requirers.get(node) ?? []) {
+        if (seen.has(parent)) continue;
+        seen.add(parent);
+        child.set(parent, node);
+        if (roots.includes(parent)) {
+          const chain = [];
+          for (let c = parent; c !== void 0; c = child.get(c)) chain.push(c);
+          return [...chain.reverse(), "direct (skaile.yaml)"];
+        }
+        queue.push(parent);
+      }
+    }
+    return [key, "not required by a declared dependency"];
   }
   /**
    * List installed assets that have a newer upstream available.
@@ -2431,13 +3059,16 @@ var AssetManager = class {
    *   than the locked one (`latestVersion`, `library` set), or the same version with
    *   different bytes (`contentChanged`). `behind` is 0. An unregistered library is a
    *   `problem` row.
+   * - **Lock gaps** — every {@link AssetManager.lockGaps} gap (a declared dependency or a
+   *   deployed asset's `requires` with no lock entry, a lock that contradicts a
+   *   `skaile.yaml` pin) as a `problem` row, so `outdated` agrees with `check`.
    *
    * @returns Array of {@link OutdatedEntry} objects.
    */
   async outdated() {
     const { repositories } = this.loadConfig();
     const lock = this.tryReadLock();
-    if (!lock) return [];
+    if (!lock) return this.addLockGapRows([]);
     const result = [];
     const reported = /* @__PURE__ */ new Set();
     const commitCounts = /* @__PURE__ */ new Map();
@@ -2479,6 +3110,9 @@ var AssetManager = class {
         if (!publisher || !kind || !name) continue;
         const libPath = this.libraryPath(origin.name, snap);
         if (!libPath) {
+          const canonical = `${kind}:@${publisher}/${name}`;
+          const heldElsewhere = (await this.resolveLibraryEntries([canonical], { quiet: true })).resolved.size > 0;
+          const fix = heldElsewhere ? void 0 : (await this.unresolvedFixes([canonical])).get(canonical) ?? unregisteredLibraryFix(origin.name, canonical);
           result.push({
             kind,
             name,
@@ -2486,7 +3120,12 @@ var AssetManager = class {
             currentVersion: origin.version,
             behind: 0,
             library: origin.name,
-            problem: `library "${origin.name}" is not registered (renamed or removed?)`
+            ...fix === void 0 ? {
+              problem: `library "${origin.name}" is not registered (renamed?) \u2014 run \`skaile install\` to re-lock it against the library that holds it now`
+            } : {
+              problem: `library "${origin.name}" is not registered (renamed or removed?) \u2014 ${fix}`,
+              manualFix: true
+            }
           });
           reported.add(ref);
           continue;
@@ -2550,7 +3189,30 @@ var AssetManager = class {
         problem: "deployed copy missing"
       });
     }
-    return result;
+    return this.addLockGapRows(result);
+  }
+  /**
+   * Append one `problem` row per {@link AssetManager.lockGaps} gap whose asset is not
+   * listed yet, so `outdated` reports the same set `check` and `install --locked` fail on.
+   */
+  async addLockGapRows(rows) {
+    const listed = new Set(rows.map((r) => `${r.kind}:${r.name}`));
+    for (const gap of await this.lockGaps()) {
+      const parsed = parseRefTolerant(gap.ref);
+      const id = parsed ? `${parsed.kind}:${parsed.name}` : gap.ref;
+      if (listed.has(id)) continue;
+      listed.add(id);
+      rows.push({
+        kind: parsed?.kind ?? "",
+        name: parsed?.name ?? gap.ref,
+        publisher: parsed?.publisher ?? "",
+        currentVersion: "",
+        behind: 0,
+        problem: gap.reason,
+        ...gap.manualFix ? { manualFix: true } : {}
+      });
+    }
+    return rows;
   }
   /**
    * Produce a unified diff from the deployed asset to its catalog source: `-` lines
@@ -2578,10 +3240,20 @@ var AssetManager = class {
       parsed.name
     );
     if (!existsSync(deployedPath)) return { status: "not-deployed" };
-    const r = spawnSync("diff", ["-ruN", deployedPath, entry.source], { encoding: "utf8" });
-    if (r.status === 1) return { status: "differs", diff: r.stdout };
-    if (r.status === 0) return { status: "identical" };
-    throw new Error(`diff failed for ${ref}: ${r.stderr || r.error?.message || "unknown error"}`);
+    const pairs = entry.files ? entry.files.map((rel) => [join(deployedPath, rel), join(dirname(entry.source), rel)]) : [[deployedPath, entry.source]];
+    const diffs = [];
+    for (const [from, to] of pairs) {
+      const r = spawnSync("diff", [entry.files ? "-uN" : "-ruN", from, to], {
+        encoding: "utf8"
+      });
+      if (r.status === 1) diffs.push(r.stdout);
+      else if (r.status !== 0) {
+        throw new Error(
+          `diff failed for ${ref}: ${r.stderr || r.error?.message || "unknown error"}`
+        );
+      }
+    }
+    return diffs.length > 0 ? { status: "differs", diff: diffs.join("") } : { status: "identical" };
   }
   // ── Lock ───────────────────────────────────────────────────────────────
   /**
@@ -2602,7 +3274,8 @@ var AssetManager = class {
     const { resolved, overridesApplied, lib } = await this.resolveLibraryFirst(dependencies, {
       provenanceIndex,
       overrides,
-      stores
+      stores,
+      declaredRefs: dependencies
     });
     const libraryLock = await this.libraryLockEntries(lib);
     const lockData = buildLockFile(resolved, overridesApplied, libraryLock);
@@ -2709,7 +3382,7 @@ var AssetManager = class {
    * @returns Array of {@link DepIssue} objects. An empty array means the workspace is healthy.
    */
   async doctor() {
-    const { repositories } = this.loadConfig();
+    const { repositories, dependencies } = this.loadConfig();
     const deployed = this.listDeployed();
     const issues = [];
     const lock = this.tryReadLock();
@@ -2725,20 +3398,23 @@ var AssetManager = class {
       );
       if (!full) {
         if (publisher) {
+          const canonical = `${entry.kind}:@${publisher}/${entry.name}`;
+          const fix = (await this.unresolvedFixes([canonical])).get(canonical);
           issues.push({
             assetKind: entry.kind,
             assetName: entry.name,
             depKind: entry.kind,
             depName: entry.name,
             inRepos: false,
-            unresolved: true
+            unresolved: true,
+            ...fix ? { fix } : {}
           });
         }
         continue;
       }
       const gaps = [];
       for (const req of full.requires) {
-        const dep = memberIdentity(`${req.kind}:${req.name}`);
+        const dep = memberIdentity(depToStr(req));
         if (!dep) continue;
         const depComponent = this.installTarget(dep.kind);
         if (depComponent && !isDeployed(depComponent, dep.name, this.driverTarget, this.global, this.projectDir)) {
@@ -2749,18 +3425,191 @@ var AssetManager = class {
             assetKind: entry.kind,
             assetName: entry.name,
             depKind: req.kind,
-            depName: req.name,
+            depName: req.publisher ? `@${req.publisher}/${req.name}` : req.name,
             inRepos
           };
           issues.push(issue);
-          if (!inRepos) gaps.push({ issue, ref: `${dep.kind}:${dep.name}` });
+          if (!inRepos) gaps.push({ issue, ref: depToStr(req) });
         }
       }
       const inLibrary = await this.resolveLibraryEntries(gaps.map((g) => g.ref));
       for (const g of gaps) g.issue.inRepos = inLibrary.resolved.has(g.ref);
     }
+    for (const [presetRef, gaps] of await this.declaredPresetGaps(dependencies, lock)) {
+      const preset = parseRefTolerant(presetRef);
+      if (!preset) continue;
+      for (const g of gaps) {
+        const item = parseRefTolerant(g.ref);
+        if (!item) continue;
+        issues.push({
+          assetKind: "preset",
+          assetName: preset.name,
+          depKind: item.kind,
+          depName: item.publisher ? `@${item.publisher}/${item.name}` : item.name,
+          inRepos: g.resolvable
+        });
+      }
+    }
     return issues;
   }
+  /**
+   * Everything the lock does not cover or contradicts, in one list: the set
+   * `skaile check`, `skaile install --locked` and `skaile outdated` all report.
+   *
+   * - `declared` — a `skaile.yaml` dependency with no lock entry (library or source gone,
+   *   unresolvable ref, never installed);
+   * - `invalid` — a `dependencies:` entry that is not a parseable ref;
+   * - `drift` — declared + locked but its deployed files are missing;
+   * - `pin` — a declared `#pin` that no lock entry for that asset satisfies;
+   * - `requires` — a deployed asset's `requires` that is not deployed (so not locked either);
+   * - `unresolved` — a lock-managed asset that no source or library holds any more.
+   *
+   * Project mode only: a global manager (`global: true`) returns `[]`. A project without
+   * `skaile.yaml` has no declared set, so only the `requires` / `unresolved` gaps of
+   * deployed assets can appear.
+   *
+   * @returns One {@link LockGap} per gap; empty when the lock covers everything declared.
+   */
+  async lockGaps() {
+    if (this.global) return [];
+    const gaps = [];
+    const issues = await this.doctor();
+    for (const i of issues) {
+      if (i.unresolved) {
+        const ref = `${i.assetKind}:${i.assetName}`;
+        const reason = `is locked but no source or library provides it any more \u2014 its requirements cannot be checked${i.fix ? ` (${i.fix})` : ""}`;
+        gaps.push({
+          type: "unresolved",
+          ref,
+          reason,
+          message: `${ref} ${reason}`,
+          ...i.fix ? { manualFix: true } : {}
+        });
+        continue;
+      }
+      const asset = `${i.assetKind}:${i.assetName}`;
+      const dep = `${i.depKind}:${i.depName}`;
+      const fix = i.inRepos ? "fixable" : "not found";
+      gaps.push({
+        type: "requires",
+        ref: dep,
+        reason: `is required by ${asset} but neither deployed nor locked (${fix})`,
+        message: `${asset} requires ${dep} (${fix})`
+      });
+    }
+    let declared = [];
+    try {
+      declared = await this.listDeclared();
+    } catch {
+      return gaps;
+    }
+    const unlocked = declared.filter((d) => d.state === "declared").map((d) => d.ref);
+    const hints = await this.publisherChangeHints(unlocked);
+    const lockKeys = Object.keys(this.tryReadLock()?.assets ?? {});
+    for (const d of declared) {
+      if (d.kind === "preset" && issues.some((i) => i.assetKind === "preset" && i.assetName === d.name)) {
+        continue;
+      }
+      let gap;
+      if (d.state === "invalid") {
+        gap = {
+          type: "invalid",
+          reason: "is not a valid asset ref (expected kind:@<publisher>/<name>#<version>)"
+        };
+      } else if (d.state === "drift") {
+        gap = {
+          type: "drift",
+          reason: "is declared and locked but not materialized \u2014 run `skaile install`"
+        };
+      } else if (d.state === "declared") {
+        const hint = hints[d.ref];
+        gap = hint ? { type: "declared", reason: `is declared but does not resolve${hint}`, manualFix: true } : {
+          type: "declared",
+          reason: "is declared but does not resolve \u2014 run `skaile install`"
+        };
+      } else {
+        const want = parseAssetRef(d.ref);
+        if (!want.pin || want.kind === "preset") continue;
+        const held = lockKeys.map((key) => ({ key, id: parseCanonicalLockKey(key) })).filter(
+          ({ id }) => id.kind === want.kind && id.name === want.name && (!want.publisher || id.publisher === want.publisher)
+        );
+        if (held.length > 0 && !held.some(({ id }) => !id.version || matchPin(want.pin, id.version))) {
+          gap = {
+            type: "pin",
+            reason: `is pinned in skaile.yaml but the lock holds ${held.map((h) => h.key).join(", ")} \u2014 run \`skaile install\``
+          };
+        }
+      }
+      if (gap) gaps.push({ ...gap, ref: d.ref, message: `${d.ref} ${gap.reason}` });
+    }
+    return gaps;
+  }
+  /**
+   * Items of each declared `preset:` dependency that the lock does not cover.
+   *
+   * A preset is never locked itself; the lock lists only its expanded items, so an
+   * item missing from the lock never resolved (or was declared after the last
+   * install). Presets are read from the local sources and libraries (nested presets
+   * followed); one only a store holds cannot be read without the network and
+   * reports no gaps. Without a lock nothing is reported: `list` and `check` already
+   * show a never-installed declaration as `declared`.
+   *
+   * @param declared - The `dependencies:` refs as written in `skaile.yaml`.
+   * @param lock - The current lock, or `null` when none exists.
+   * @returns Declared preset ref → its uncovered items; `resolvable` is `true` when a
+   *   local source or library offers the item (so `skaile install` can fix it).
+   *   Presets without gaps are absent.
+   */
+  async declaredPresetGaps(declared, lock) {
+    const gaps = /* @__PURE__ */ new Map();
+    if (!lock) return gaps;
+    const presetRefs = declared.filter((d) => parseRefTolerant(d)?.kind === "preset");
+    if (presetRefs.length === 0) return gaps;
+    const { repositories } = this.loadConfig();
+    const provenanceIndex = await buildProvenanceIndex(this.buildClones(repositories), {
+      projectDir: this.projectDir,
+      knownKinds: this.knownKinds
+    });
+    const lockKeys = Object.keys(lock.assets).map(parseCanonicalLockKey);
+    const sourceCandidate = (ref) => {
+      const p = parseRefTolerant(ref);
+      if (!p?.publisher) return void 0;
+      const hash = ref.indexOf("#");
+      const pin = p.pin ?? (hash >= 0 ? ref.slice(hash + 1) : void 0);
+      return (provenanceIndex.get(`${p.publisher}/${p.kind}:${p.name}`) ?? []).filter((c) => matchPin(pin, c.version)).sort((a, b) => {
+        const va = coerceVersion(a.version);
+        const vb = coerceVersion(b.version);
+        return gt(va, vb) ? -1 : gt(vb, va) ? 1 : 0;
+      })[0];
+    };
+    const itemsOf = async (ref) => {
+      const src = sourceCandidate(ref);
+      if (src) return (src.deps ?? []).map((d) => qualifyDepRef(d, src.publisher));
+      const entry = (await this.resolveLibraryEntries([ref], { quiet: true })).entries[0];
+      return entry ? libraryEntryDepRefs(entry) : null;
+    };
+    const resolvableLocally = async (ref) => sourceCandidate(ref) !== void 0 || (await this.resolveLibraryEntries([ref], { quiet: true })).resolved.has(ref);
+    const isLocked = (item) => lockKeys.some(
+      (k) => k.kind === item.kind && k.name === item.name && (!item.publisher || k.publisher === item.publisher)
+    );
+    for (const presetRef of presetRefs) {
+      const out = [];
+      const visited = /* @__PURE__ */ new Set();
+      const walk = async (ref) => {
+        if (visited.has(ref)) return;
+        visited.add(ref);
+        for (const item of await itemsOf(ref) ?? []) {
+          const p = parseRefTolerant(item);
+          if (!p) continue;
+          if (p.kind === "preset") await walk(item);
+          else if (!isLocked(p)) out.push({ ref: item, resolvable: await resolvableLocally(item) });
+        }
+      };
+      await walk(presetRef);
+      if (out.length > 0) gaps.set(presetRef, out);
+    }
+    return gaps;
+  }
   // ── Scaffold ───────────────────────────────────────────────────────────
   /**
    * Create a minimal asset scaffold directory (delegates to {@link createScaffold}).
@@ -2829,15 +3678,21 @@ var AssetManager = class {
       const { kind, name } = parseCanonicalLockKey(ref);
       const component = kind ? this.installTarget(kind) : void 0;
       if (!kind || !name || !component) continue;
-      const dest = deployedDir(component, name, this.driverTarget, this.global, this.projectDir);
-      try {
-        const stat = lstatSync(dest);
-        if (stat.isSymbolicLink()) unlinkSync(dest);
-        else rmSync(dest, { recursive: true, force: true });
-        removed.push(ref);
-      } catch {
-        removed.push(ref);
+      for (const dest of deployedPaths(
+        component,
+        name,
+        this.driverTarget,
+        this.global,
+        this.projectDir
+      )) {
+        try {
+          const stat = lstatSync(dest);
+          if (stat.isSymbolicLink()) unlinkSync(dest);
+          else rmSync(dest, { recursive: true, force: true });
+        } catch {
+        }
       }
+      removed.push(ref);
     }
     return removed;
   }
@@ -2973,5 +3828,5 @@ var AssetManager = class {
 };
 
 export { AssetManager, FACTORY_SOURCE_URL, MissingManifestError, installAgentInstances, normalizeRepoUrl, parseCanonicalLockKey, parseRefTolerant, renderMcpServerConfig, softDepName };
-//# sourceMappingURL=chunk-D5HOETOB.js.map
-//# sourceMappingURL=chunk-D5HOETOB.js.map
+//# sourceMappingURL=chunk-H7QUDDKH.js.map
+//# sourceMappingURL=chunk-H7QUDDKH.js.map