@skaile/workspaces 5.9.0 → 5.11.0

package/dist/{chunk-IMKSM5NL.js → chunk-DZMNFCWB.js}

@@ -1,20 +1,21 @@
-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 { unregisteredLibraryNames, renamedLibraryName, scanUnlistedAssets, getStoreManifestsDir, missingLibraryDirMessage } from './chunk-2F5AWQX5.js';
+import { readManifestSourceConfig, isManifestMode, discoverAssetsInTree } from './chunk-J4RBUFGM.js';
+import { installTargetOf, canonicalEntryRef, deployAll, removeAsset, diffDeployedAgent, deployedAssetDrift, createScaffold, installAgent } from './chunk-FH7W6TJ4.js';
 import { appendHistory, getRecentHistory, clearHistory } from './chunk-KTBKW2FI.js';
 import { commitChanges } from './chunk-UQ6LFBPZ.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 { driverTargetSupportsAgents, CODEX_IDENTITY_DIR } from './chunk-HZXUXHIV.js';
+import { resolveConfiguredDriverTarget, GLOBAL_INSTALL_DIR_NAME, resolveLibraryDir, buildLibraryLockEntries, buildLockFile, writeLock, readLock, verifyLock, mergeLockFile, extractForPatch, generatePatch, savePatch, applyPatch, computeHash } from './chunk-PBBPZYVG.js';
+import { resolveRuntimeAssets, factoryAssetRoots } from './chunk-EDYHEMJA.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 { resolveSkWorkspaceConfig, effectiveAgentInstances, loadMcpServerDeclarations, resolveGlobalHarnesses, resolveGlobalSkWorkspaceConfig, getGlobalCacheDir, sourceCacheKey, getRepoCommit, matchPin, buildProvenanceIndex, coerceVersion, sourceShortName, resolveAll, ensureRepo, scanRepo, SKAILE_YAML_DEFAULT, checkRepoStatus, resolveAsset, readLinks, MAX_PRESET_DEPTH, PresetDepthError, DEFAULT_AGENT_INSTANCE_ID, resolveAgentDefinitionDir, storeManifestSlug } from './chunk-ALEYHUC5.js';
 import { globalSkaileDir, globalCacheRoot, migrateLegacyDir } from './chunk-L5VSIPQD.js';
 import { DRIVER_TARGETS } from './chunk-CPSIPIX7.js';
-import { scanDirectory, parseRequires } from './chunk-GTILM2CI.js';
-import { parseAssetRef, parseAssetRefLoose, assetRefToStr, slugifyAssetName, depToStr } from './chunk-QVNRCDTV.js';
+import { loadSkPublishManifest } from './chunk-ZPWTOUTK.js';
+import { scanDirectory, parseRequires, dedupeRequirements } from './chunk-SBSA3IQA.js';
+import { parseAssetRef, parseAssetRefLoose, assetRefToStr, slugifyAssetName, depToStr } from './chunk-BNMZVPYA.js';
 import { spawnSync } from 'child_process';
 import { existsSync, rmSync, readdirSync, lstatSync, unlinkSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
-import path, { join, resolve, dirname, sep, relative, posix } from 'path';
+import path, { resolve, dirname, sep, join, relative, posix } from 'path';
 import { gt } from 'semver';
 import { stringify, parse } from 'yaml';
 import fs from 'fs/promises';
@@ -36,9 +37,76 @@ function writeLedger(projectDir, ledger) {
   writeFileSync(p, `${JSON.stringify(ledger, null, 2)}
 `, "utf-8");
 }
+function bindInstance(projectDir, id, instance) {
+  const errors = [];
+  let srcDir;
+  try {
+    srcDir = resolveAgentDefinitionDir(projectDir, instance.ref);
+  } catch (err) {
+    errors.push(`agent instance "${id}": ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (srcDir !== void 0 && !existsSync(join(srcDir, "agent.yaml"))) {
+    errors.push(
+      `agent instance "${id}": ${instance.ref} resolves to ${srcDir}, which has no agent.yaml`
+    );
+  }
+  return { srcDir, errors };
+}
+function unboundAgentInstances(projectDir, driverTarget) {
+  if (!driverTargetSupportsAgents(driverTarget)) return [];
+  let instances;
+  try {
+    instances = effectiveAgentInstances(resolveSkWorkspaceConfig(projectDir));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const [id, instance] of Object.entries(instances)) {
+    const { errors } = bindInstance(projectDir, id, instance);
+    if (errors.length > 0) out.push({ id, ref: instance.ref, error: errors.join("; ") });
+  }
+  return out;
+}
+function removeAgentInstanceRenderings(opts) {
+  const { projectDir, driverTarget, ids } = opts;
+  if (!driverTargetSupportsAgents(driverTarget) || ids.length === 0) return [];
+  const ledger = readLedger(projectDir);
+  const previous = ledger.targets[driverTarget];
+  if (!previous) return [];
+  const gone = new Set(ids);
+  const claimed = new Set(
+    Object.entries(previous).filter(([id]) => !gone.has(id)).flatMap(([, files]) => files)
+  );
+  const agentDeployDir = deployedBase("agent", driverTarget, false, projectDir);
+  const removable = [resolve(agentDeployDir), resolve(dirname(agentDeployDir), CODEX_IDENTITY_DIR)];
+  const root = resolve(projectDir);
+  const removed = [];
+  for (const id of gone) {
+    for (const rel of previous[id] ?? []) {
+      if (claimed.has(rel)) continue;
+      const abs = resolve(root, rel);
+      if (!removable.some((dir) => abs.startsWith(dir + sep)) || !existsSync(abs)) continue;
+      rmSync(abs, { recursive: true, force: true });
+      removed.push(rel);
+    }
+  }
+  const owned = Object.fromEntries(Object.entries(previous).filter(([id]) => !gone.has(id)));
+  const nextTargets = { ...ledger.targets };
+  if (Object.keys(owned).length > 0) nextTargets[driverTarget] = owned;
+  else delete nextTargets[driverTarget];
+  if (JSON.stringify(nextTargets) !== JSON.stringify(ledger.targets)) {
+    writeLedger(projectDir, { version: 1, targets: nextTargets });
+  }
+  return removed;
+}
 function installAgentInstances(opts) {
   const { projectDir, driverTarget, log } = opts;
-  const result = { instances: [], removed: [], warnings: [] };
+  const result = {
+    instances: [],
+    removed: [],
+    warnings: [],
+    errors: []
+  };
   if (!driverTargetSupportsAgents(driverTarget)) return result;
   const wsConfig = opts.wsConfig ?? resolveSkWorkspaceConfig(projectDir);
   const instances = effectiveAgentInstances(wsConfig);
@@ -48,20 +116,9 @@ function installAgentInstances(opts) {
   const previous = ledger.targets[driverTarget] ?? {};
   const owned = {};
   for (const [id, instance] of Object.entries(instances)) {
-    let srcDir;
-    try {
-      srcDir = resolveAgentDefinitionDir(projectDir, instance.ref);
-    } catch (err) {
-      result.warnings.push(
-        `agent instance "${id}": ${err instanceof Error ? err.message : String(err)}`
-      );
-    }
-    if (srcDir === void 0 || !existsSync(join(srcDir, "agent.yaml"))) {
-      if (srcDir !== void 0) {
-        result.warnings.push(
-          `agent instance "${id}": ${instance.ref} resolves to ${srcDir}, which has no agent.yaml`
-        );
-      }
+    const { srcDir, errors } = bindInstance(projectDir, id, instance);
+    result.errors.push(...errors);
+    if (srcDir === void 0 || errors.length > 0) {
       if (previous[id]) owned[id] = previous[id];
       continue;
     }
@@ -273,7 +330,30 @@ async function renderMcpServerConfig(projectDir, driverTarget, opts) {
 
 // asset-manager/src/index.ts
 function normalizeRepoUrl(url) {
-  return url.trim().replace(/^git@([^:]+):/, "https://$1/").replace(/^[a-z]+:\/\//i, "").replace(/\.git$/i, "").replace(/\/+$/, "").toLowerCase();
+  return url.trim().replace(/^git@([^:]+):/, "https://$1/").replace(/^[a-z]+:\/\//i, "").replace(/\/+$/, "").replace(/\.git$/i, "").replace(/\/+$/, "").toLowerCase();
+}
+function withoutUrlSecrets(url) {
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) return url;
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol === "http:" || parsed.protocol === "https:" || parsed.password) {
+      parsed.username = "";
+    }
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    return url.replace(/[?#].*$/, "").replace(/^([a-z][a-z0-9+.-]*:\/\/).*@/i, "$1");
+  }
+}
+function libraryRemoteUrl(library) {
+  const config = library.backendConfig;
+  if (library.backend !== "git" || !("url" in config) || typeof config.url !== "string") {
+    return void 0;
+  }
+  const url = config.url.trim();
+  return url ? withoutUrlSecrets(url) : void 0;
 }
 function storeOverlayPathForUrl(url) {
   return join(getStoreManifestsDir(), `${storeManifestSlug(url)}.yaml`);
@@ -375,6 +455,26 @@ function libraryDiskHashes(libPath, cache, registry) {
   }
   return hashes;
 }
+function manifestFileHasAssetsArray(libPath) {
+  try {
+    const doc = parse(readFileSync(join(libPath, "skaile.manifest.yaml"), "utf8"));
+    return Array.isArray(doc?.assets);
+  } catch {
+    return false;
+  }
+}
+function isUnlistedLibraryAsset(entry, libPath) {
+  const manifest = loadSkPublishManifest(libPath);
+  const listed = manifest?.assets ?? [];
+  if (!manifest || manifest.source) return false;
+  if (listed.length === 0 && !manifestFileHasAssetsArray(libPath)) return false;
+  const file = resolve(entry.source);
+  return !listed.some((a) => {
+    if (!a.root || a.source) return false;
+    const root = resolve(libPath, a.root);
+    return file === root || file.startsWith(root + sep);
+  });
+}
 function withLibraryFiles(entry, libPath, cache, registry) {
   let byManifest = cache.get(libPath);
   if (!byManifest) {
@@ -539,6 +639,10 @@ function keptLockEntries(prev, missing) {
   }
   return out;
 }
+function presetsLockSlice(presets) {
+  const refs = [...new Set(presets.map((p) => p.ref))].sort();
+  return refs.length > 0 ? { presets: refs } : {};
+}
 function withKeptLockEntries(lock, kept) {
   if (Object.keys(kept.assets).length === 0) return lock;
   const sources = new Map(lock.sources.map((s) => [s.url, s]));
@@ -567,8 +671,45 @@ function relockedRefs(prev, next) {
   }
   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 libraryMoves(prev, next) {
+  if (!prev) return [];
+  const out = [];
+  for (const [key, entry] of Object.entries(next)) {
+    const to = entry.library;
+    if (!to || to.installed) continue;
+    const id = parseCanonicalLockKey(key);
+    for (const [prevKey, before] of Object.entries(prev.assets)) {
+      const o = parseCanonicalLockKey(prevKey);
+      if (o.kind !== id.kind || o.name !== id.name || o.publisher !== id.publisher) continue;
+      const from = before.library;
+      if (!from || from.installed || from.name === to.name) continue;
+      out.push({ ref: `${id.kind}:@${id.publisher}/${id.name}`, from: from.name, to: to.name });
+      break;
+    }
+  }
+  return out;
+}
+function unregisteredLibraryFix(origin, ref) {
+  const register = origin.url ? `\`skaile library init ${origin.name} --git ${origin.url}\` (no registered library has the remote ${origin.url} either)` : `\`skaile library init ${origin.name} --path <dir>\``;
+  return `register library "${origin.name}" again with ${register}, or drop the dependency with \`skaile remove ${ref}\``;
+}
+function declaredNoHolderReason(ref) {
+  return `is declared but no library or source holds it \u2014 register the library that holds it with \`skaile library init <name> --path <dir>\`, or drop it with \`skaile remove ${ref.split("#")[0]}\``;
+}
+var REGISTER_HOLDER = "register the library that holds it with `skaile library init <name> --path <dir>`";
+function requirementNoHolderFix(asset) {
+  return `${REGISTER_HOLDER}, or drop ${asset} with \`skaile remove ${asset}\``;
+}
+function sameAsset(ref, want) {
+  const p = parseRefTolerant(ref);
+  return p !== null && p.kind === want.kind && p.name === want.name && (!want.publisher || !p.publisher || p.publisher === want.publisher);
+}
+function lockedLibraryProblem(lookup, origin, ref) {
+  return lookup.state === "dir-missing" ? missingLibraryDirMessage({ name: origin.name, path: lookup.path }) : `library "${origin.name}" is not registered \u2014 renamed or removed? ${unregisteredLibraryFix(origin, ref)}`;
+}
+function gapIdentity(ref) {
+  const p = parseRefTolerant(ref);
+  return p ? `${p.kind}:${p.name}` : ref;
 }
 function memberIdentity(ref) {
   const parsed = parseRefTolerant(ref.trim());
@@ -726,13 +867,15 @@ var AssetManager = class {
   }
   /** Deploy options for one harness. In global mode, `driverTarget` is the
    * fan-out target (not the constructor's `driverTarget`, which is project-only). */
-  deployOptsFor(target, link) {
+  deployOptsFor(target, link, onSkippedSymlink, onEnvFile) {
     return {
       registry: this.registry,
       driverTarget: target,
       global: this.global,
       cwd: this.projectDir,
-      link: link === true
+      link: link === true,
+      ...onSkippedSymlink ? { onSkippedSymlink: (entry, p) => onSkippedSymlink(canonicalEntryRef(entry), p) } : {},
+      ...onEnvFile ? { onEnvFile: (entry, p) => onEnvFile(canonicalEntryRef(entry), p) } : {}
     };
   }
   /**
@@ -759,18 +902,27 @@ var AssetManager = class {
    * Render every agent instance of `skaile.yaml` into the driver target's native
    * agent files (`.claude/agents/<id>.md`, …) and prune the renderings of
    * instances that left the config. Runs after the skills deploy, so composed
-   * skills resolve. Project scope only. Never fails an install — a render error
-   * is warned and swallowed.
+   * skills resolve. Project scope only. An instance whose `ref` resolves to no agent is
+   * reported in `agentInstanceErrors`; any other render error is warned and swallowed.
    */
-  renderAgentInstances() {
+  async renderAgentInstances() {
     if (this.global) return {};
     try {
       const result = installAgentInstances({
         projectDir: this.projectDir,
         driverTarget: this.driverTarget
       });
-      for (const w of result.warnings) console.warn(`skaile: ${w}`);
-      return { agentInstances: result.instances, agentFilesRemoved: result.removed };
+      for (const u of unboundAgentInstances(this.projectDir, this.driverTarget)) {
+        if (!u.ref.startsWith("agent:")) continue;
+        const at = result.errors.findIndex((e) => e.startsWith(`agent instance "${u.id}":`));
+        if (at >= 0) result.errors[at] += ` \u2014 ${(await this.unboundAgentAdvice(u.ref)).advice}`;
+      }
+      for (const w of [...result.warnings, ...result.errors]) console.warn(`skaile: ${w}`);
+      return {
+        agentInstances: result.instances,
+        agentFilesRemoved: result.removed,
+        ...result.errors.length > 0 ? { agentInstanceErrors: result.errors } : {}
+      };
     } catch (err) {
       console.warn(
         `skaile: could not render agent instances for ${this.driverTarget}: ${err instanceof Error ? err.message : String(err)}`
@@ -902,6 +1054,11 @@ var AssetManager = class {
    *
    * @param opts.quiet - Skip the cross-library collision warning (a lookup that only
    *   builds an error hint must not warn).
+   * @param opts.library - Resolve only from this library (the one a lock entry names), not
+   *   from every registered one. Never warns: no choice is made between libraries.
+   * @param opts.lockedLibraries - `kind:publisher/name` → the library its lock entry names
+   *   ({@link AssetManager.lockedLibraryNames}). A ref listed here resolves from that library
+   *   when it holds a match, whatever the default library is.
    * @returns the matched deploy entries, the set of `missing` refs covered, and
    *   each entry's originating library name.
    */
@@ -914,6 +1071,7 @@ var AssetManager = class {
     const { byKey, isDefaultLib, libraryDir } = scan;
     const entries = [];
     const fileSets = /* @__PURE__ */ new Map();
+    let snap;
     const allCandidates = [...byKey.values()].flat();
     for (const ref of missing) {
       const parsed = parseRefTolerant(ref);
@@ -921,21 +1079,54 @@ var AssetManager = class {
       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 ?? ""));
+      const scanned = (key ? byKey.get(key) ?? [] : allCandidates.filter(
+        (c) => c.entry.kind === parsed.kind && c.entry.name === parsed.name
+      )).filter((c) => !opts.library || c.library === opts.library);
+      const pool = [];
+      for (const c of scanned) {
+        if (c.entry.version) {
+          pool.push(c);
+          continue;
+        }
+        if (snap === void 0) snap = await this.loadLibraryIndex();
+        const def = newestLibraryDef(snap, c.library, {
+          kind: c.entry.kind,
+          publisher: c.entry.publisher ?? "",
+          name: c.entry.name
+        });
+        pool.push(def?.version ? { ...c, entry: { ...c.entry, version: def.version } } : c);
+      }
+      let candidates = pool.filter((c) => !pin || matchPin(pin, c.entry.version ?? ""));
+      let lockedLibrary;
+      if (parsed.publisher) {
+        lockedLibrary = opts.lockedLibraries?.get(
+          `${parsed.kind}:${parsed.publisher.replace(/^@/, "")}/${parsed.name}`
+        );
+      } else {
+        const same = [...opts.lockedLibraries ?? []].filter(([k]) => {
+          const slash = k.indexOf("/");
+          return k.startsWith(`${parsed.kind}:`) && k.slice(slash + 1) === parsed.name;
+        });
+        if (same.length === 1) lockedLibrary = same[0][1];
+      }
+      if (lockedLibrary) {
+        const inLocked = candidates.filter((c) => c.library === lockedLibrary);
+        if (inLocked.length > 0) candidates = inLocked;
+      }
       if (candidates.length === 0) continue;
       candidates.sort(libraryPreference(isDefaultLib));
       const hit = candidates[0];
-      if (!opts.quiet) {
+      if (!opts.quiet && !opts.library) {
         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);
+      const entry = hit.entry;
+      withLibraryFiles(entry, libraryDir.get(hit.library), fileSets, this.registry);
+      entries.push(entry);
+      libraryOf.set(entry, hit.library);
       resolved.add(ref);
     }
     return { entries, resolved, libraryOf };
@@ -955,11 +1146,12 @@ var AssetManager = class {
       if (existsSync(l.path)) roots.push({ name: l.name, dir: l.path, isDefault: l.isDefault });
     }
     const registered = new Set(roots.map((r) => r.name));
+    const unregistered = unregisteredLibraryNames();
     try {
       const librariesRoot = resolveLibraryDir();
       if (existsSync(librariesRoot)) {
         for (const dirent of readdirSync(librariesRoot, { withFileTypes: true })) {
-          if (dirent.isDirectory() && dirent.name !== GLOBAL_INSTALL_DIR_NAME && !registered.has(dirent.name)) {
+          if (dirent.isDirectory() && dirent.name !== GLOBAL_INSTALL_DIR_NAME && !registered.has(dirent.name) && !unregistered.has(dirent.name)) {
             roots.push({
               name: dirent.name,
               dir: join(librariesRoot, dirent.name),
@@ -1012,10 +1204,117 @@ var AssetManager = class {
     }
     return out;
   }
+  /**
+   * Every asset a registered library holds, read from the library directories themselves
+   * (not the local index, which keeps one row per ref and version and loses a ref when
+   * another library re-publishes it). One row per holder, all versions.
+   *
+   * @returns `[]` when no library holds an asset. Never warns.
+   */
+  async libraryAssets() {
+    const scan = await this.scanLibraries();
+    if (!scan) return [];
+    return [...scan.byKey.values()].flat();
+  }
+  /**
+   * Every origin that holds `ref` (`kind:@publisher/name`) with the version it holds, in
+   * the order `add <ref>` prefers them, so the first row is the one `add` deploys: the
+   * project's source clones and the bundled factory source (highest version first), then
+   * the registered libraries. `add`, `info` and `search` all read this, so the three name
+   * one origin for one ref. Stores are not asked (no network).
+   *
+   * @returns one row per origin and version; `[]` for a ref without a publisher or one
+   *   nothing holds. Never warns.
+   */
+  async refOrigins(ref) {
+    const parsed = parseRefTolerant(ref);
+    if (!parsed?.publisher) return [];
+    const key = `${parsed.kind}:@${parsed.publisher}/${parsed.name}`;
+    return (await this.collectOrigins(key)).get(key) ?? [];
+  }
+  /**
+   * Every ref (`kind:@publisher/name`) that several origins hold at different versions,
+   * with its origins in {@link refOrigins} order. A ref the origins hold at one version
+   * has nothing to choose between and is left out.
+   */
+  async competingOrigins() {
+    const out = /* @__PURE__ */ new Map();
+    for (const [key, origins] of await this.collectOrigins()) {
+      if (new Set(origins.map((o) => o.version)).size > 1) out.set(key, origins);
+    }
+    return out;
+  }
+  /**
+   * The origins of {@link refOrigins} for every ref, or for the one `only` names
+   * (`kind:@publisher/name`), keyed by `kind:@publisher/name`.
+   */
+  async collectOrigins(only) {
+    const { repositories, sources } = this.loadConfig();
+    this.ensureSourceClonesQuiet(repositories, sources);
+    const clones = this.buildClones(repositories);
+    const cloneDirs = new Set(clones.map((c) => resolve(c.localPath)));
+    const index = await buildProvenanceIndex(clones, {
+      projectDir: this.projectDir,
+      knownKinds: this.knownKinds
+    });
+    const factoryUrl = normalizeRepoUrl(FACTORY_SOURCE_URL);
+    const hasFactory = Object.values(repositories).some((d) => d.factory);
+    const out = /* @__PURE__ */ new Map();
+    const originsOf = (key) => {
+      let list = out.get(key);
+      if (!list) {
+        list = [];
+        out.set(key, list);
+      }
+      return list;
+    };
+    for (const candidates of index.values()) {
+      const first = candidates[0];
+      if (!first) continue;
+      const key = `${first.kind}:@${first.publisher}/${first.name}`;
+      if (only !== void 0 && key !== only) continue;
+      const held = [...candidates].sort((a, b) => {
+        const va = coerceVersion(a.version);
+        const vb = coerceVersion(b.version);
+        if (gt(va, vb)) return -1;
+        if (gt(vb, va)) return 1;
+        return a.sourceUrl.localeCompare(b.sourceUrl);
+      });
+      for (const c of held) {
+        const factory = hasFactory && normalizeRepoUrl(c.sourceUrl) === factoryUrl;
+        originsOf(key).push({
+          kind: factory ? "factory" : "source",
+          label: factory ? "factory" : sourceShortName(c.sourceUrl),
+          version: c.version,
+          description: c.description ?? ""
+        });
+      }
+    }
+    const scan = await this.scanLibraries();
+    const prefer = libraryPreference(scan?.isDefaultLib ?? /* @__PURE__ */ new Map());
+    for (const [key, holders] of scan?.byKey ?? []) {
+      if (only !== void 0 && key !== only) continue;
+      for (const c of [...holders].sort(prefer)) {
+        const dir = scan?.libraryDir.get(c.library);
+        if (dir && cloneDirs.has(resolve(dir))) continue;
+        originsOf(key).push({
+          kind: "library",
+          label: c.library,
+          version: c.entry.version ?? "",
+          description: c.entry.description ?? ""
+        });
+      }
+    }
+    return out;
+  }
   /**
    * 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;
+   * - `moved` when a registered library holds the same kind + name under another publisher.
+   *   When the lock ties the missed ref to a library, only that library is looked at (an
+   *   asset of the same name in another library is a different asset). Without a lock
+   *   entry, a library asset the project already declares or locks under its own ref is
+   *   not offered, and two candidate publishers are ambiguous: no hint;
    * - `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
@@ -1035,11 +1334,28 @@ var AssetManager = class {
     }
     if (wanted.size === 0) return out;
     const lockEntries = Object.entries(this.tryReadLock()?.assets ?? {});
-    const bare = [...new Set([...wanted.values()].map((w) => `${w.kind}:${w.name}`))];
-    const lib = await this.resolveLibraryEntries(bare, { quiet: true });
+    const scan = await this.scanLibraries();
+    if (!scan) return out;
+    const held = /* @__PURE__ */ new Set();
+    for (const [key] of lockEntries) {
+      const { publisher, kind, name } = parseCanonicalLockKey(key);
+      if (publisher && kind && name) held.add(`${publisher}/${kind}:${name}`);
+    }
+    for (const d of this.loadConfig().dependencies) {
+      const id = refIdentity(d);
+      if (id !== null) held.add(id);
+    }
     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 origin = lockEntries.map(([key, e]) => ({ id: parseCanonicalLockKey(key), library: e.library })).find(
+        ({ id, library }) => library && !library.installed && id.kind === w.kind && id.name === w.name && id.publisher === w.publisher
+      )?.library?.name;
+      const pool = [...scan.byKey.values()].flat().filter(
+        (c) => c.entry.kind === w.kind && c.entry.name === w.name && c.entry.publisher !== w.publisher && (origin ? c.library === origin : !held.has(`${c.entry.publisher}/${c.entry.kind}:${c.entry.name}`))
+      );
+      const publishers = new Set(pool.map((c) => c.entry.publisher));
+      const best = publishers.size === 1 ? pool.sort(libraryPreference(scan.isDefaultLib))[0] : void 0;
+      const moved = best?.entry;
+      const movedLibrary = best?.library;
       const finding = {};
       for (const [key, entry] of lockEntries) {
         const id = parseCanonicalLockKey(key);
@@ -1104,17 +1420,20 @@ var AssetManager = class {
       if (!origin) continue;
       const plain = want.publisher ? `${want.kind}:@${want.publisher}/${want.name}` : `${want.kind}:${want.name}`;
       const moved = findings.get(ref)?.moved;
+      const lookup = this.lockedLibrary(origin, snap);
       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 if (lookup.state === "dir-missing") {
+        out.set(ref, lockedLibraryProblem(lookup, origin, plain));
+      } else if (lookup.state === "unregistered") {
+        out.set(ref, unregisteredLibraryFix(origin, plain));
       } else {
         out.set(
           ref,
-          `library "${origin.name}" no longer holds it \u2014 restore it there, or drop the dependency with \`skaile remove ${plain}\``
+          `library "${lookup.name}" no longer holds it \u2014 restore it there, or drop the dependency with \`skaile remove ${plain}\``
         );
       }
     }
@@ -1214,27 +1533,120 @@ var AssetManager = class {
    * preferring it would lock a stale version after an in-place bump. The hash is
    * computed from the files on disk, so it matches what `install --locked`
    * re-hashes.
+   *
+   * A git-backed library also records its remote URL. When the previous lock names the
+   * library under another name that {@link lockedLibrary} matched to this one by URL (a
+   * teammate registered the same remote under a different name), the entry keeps the locked
+   * name and URL: the lock does not change because it was installed on another machine.
    */
   async libraryLockEntries(lib) {
     if (lib.entries.length === 0) return {};
     const snap = await this.loadLibraryIndex();
+    const previous = Object.entries(this.tryReadLock()?.assets ?? {}).filter(
+      ([, e]) => e.library !== void 0 && !e.library.installed
+    );
     const diskHashes = /* @__PURE__ */ new Map();
     return buildLibraryLockEntries(
       lib.entries.map((e) => {
         const name = lib.libraryOf.get(e) ?? "";
         const publisher = e.publisher ?? "";
         const def = newestLibraryDef(snap, name, { kind: e.kind, publisher, name: e.name });
-        const libPath = this.libraryPath(name, snap);
+        const libPath = this.libraryPath({ name }, snap);
         const sha256 = (libPath ? libraryDiskHashes(libPath, diskHashes, this.registry).get(`${e.kind}:${e.name}`) : void 0) ?? def?.sha256;
+        const registered = snap?.libraries.find((l) => l.name === name);
+        let lockName = name;
+        let url = registered ? libraryRemoteUrl(registered) : void 0;
+        const locked = previous.find(([key]) => {
+          const id = parseCanonicalLockKey(key);
+          return id.kind === e.kind && id.name === e.name && id.publisher === publisher;
+        })?.[1].library;
+        if (locked) {
+          const lookup = this.lockedLibrary(locked, snap);
+          if (lookup.state === "ok" && lookup.name === name) {
+            lockName = locked.name;
+            if (locked.url && url && normalizeRepoUrl(locked.url) === normalizeRepoUrl(url)) {
+              url = locked.url;
+            }
+          }
+        }
         return {
           kind: e.kind,
           publisher,
           name: e.name,
-          library: { name, version: e.version || def?.version || "0.0.0", sha256 }
+          library: {
+            name: lockName,
+            version: e.version || def?.version || "0.0.0",
+            sha256,
+            ...url ? { url } : {}
+          }
         };
       })
     );
   }
+  /**
+   * Lock keys that `skaile.yaml` still wants: the entries a declared ref names, plus every
+   * entry such an asset requires, transitively. All keys when a `preset:` is declared.
+   */
+  async declaredLockKeys(lock, declared) {
+    const keys = Object.keys(lock.assets);
+    const wanted = declared.map((d) => parseRefTolerant(d.split(" ")[0] ?? d));
+    if (wanted.some((w) => w?.kind === "preset")) return new Set(keys);
+    const matching = (want) => keys.filter((key) => {
+      const id = parseCanonicalLockKey(key);
+      return id.kind === want.kind && id.name === want.name && (!want.publisher || !id.publisher || id.publisher === want.publisher);
+    });
+    const inScope = /* @__PURE__ */ new Set();
+    const queue = [];
+    const add = (key) => {
+      if (inScope.has(key)) return;
+      inScope.add(key);
+      queue.push(key);
+    };
+    for (const w of wanted) if (w) matching(w).forEach(add);
+    for (const key of queue) {
+      for (const dep of await this.deployedRequirementsOf(parseCanonicalLockKey(key))) {
+        const want = memberIdentity(dep);
+        if (want) matching(want).forEach(add);
+      }
+    }
+    return inScope;
+  }
+  /**
+   * The `Missing:` lines of every library-origin lock entry whose library cannot supply
+   * assets on this machine (not registered, or registered with its directory gone). Plain
+   * `install` stops on a non-empty list, the same lines `install --locked` prints: it must
+   * not re-resolve a locked asset from another origin. The ONE function that decides "the
+   * locked library is not here", so a lock-recorded URL fallback extends it in one place.
+   *
+   * Only entries `skaile.yaml` still declares, or that a declared asset requires
+   * (transitively, read from the deployed copy), count. A stale entry nothing declares is
+   * pruned by `install` as usual, so a removed dependency whose library is gone can be
+   * cleaned up. With a declared `preset:` every entry counts: the lock records no edge
+   * from a preset to its items, and the preset's own library may be the one that is gone.
+   *
+   * @param declared - The `dependencies:` refs as written in `skaile.yaml`.
+   */
+  async unavailableLockedLibraries(lock, declared) {
+    const inScope = await this.declaredLockKeys(lock, declared);
+    const locked = Object.entries(lock.assets).filter(
+      ([key, e]) => e.library !== void 0 && !e.library.installed && inScope.has(key)
+    );
+    if (locked.length === 0) return [];
+    const snap = await this.loadLibraryIndex();
+    const lines = [];
+    for (const [ref, e] of locked) {
+      const { publisher, kind, name } = parseCanonicalLockKey(ref);
+      if (!publisher || !kind || !name) continue;
+      const lookup = this.lockedLibrary(e.library, snap);
+      if (lookup.state === "ok") continue;
+      const component = this.installTarget(kind);
+      const deployed = component !== void 0 && isDeployed(component, name, this.driverTarget, this.global, this.projectDir);
+      const problem = lockedLibraryProblem(lookup, e.library, `${kind}:@${publisher}/${name}`);
+      const kept = deployed ? "the deployed copy and its lock entry are kept" : "its lock entry is kept; no deployed copy exists";
+      lines.push(`${ref} (${problem}; ${kept})`);
+    }
+    return lines;
+  }
   /**
    * Re-resolve every library-origin lock entry from its named library, for
    * `install --locked`. An entry is restored only when its library is still
@@ -1258,25 +1670,26 @@ var AssetManager = class {
         missing.push(`${ref} (unparseable lock key)`);
         continue;
       }
-      const libPath = this.libraryPath(origin.name, snap);
-      if (!libPath) {
+      const lookup = this.lockedLibrary(origin, snap);
+      if (lookup.state !== "ok") {
         missing.push(
-          `${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)`
+          `${ref} (${lockedLibraryProblem(lookup, origin, `${kind}:@${publisher}/${name}`)})`
         );
         continue;
       }
+      const libPath = lookup.path;
       const found = (await scanDirectory(libPath, publisher, { knownKinds: this.knownKinds })).find(
         (x) => x.kind === kind && x.name === name
       );
       if (!found) {
-        missing.push(`${ref} (not found in library "${origin.name}")`);
+        missing.push(`${ref} (not found in library "${lookup.name}")`);
         continue;
       }
-      const def = newestLibraryDef(snap, origin.name, { kind, publisher, name });
+      const def = newestLibraryDef(snap, lookup.name, { kind, publisher, name });
       const current = found.version || def?.version || "0.0.0";
       if (current !== origin.version) {
         missing.push(
-          `${ref} (library "${origin.name}" is at ${current}, locked ${origin.version})`
+          `${ref} (library "${lookup.name}" is at ${current}, locked ${origin.version})`
         );
         continue;
       }
@@ -1284,29 +1697,108 @@ var AssetManager = class {
         const onDisk = libraryDiskHashes(libPath, diskHashes, this.registry).get(`${kind}:${name}`);
         if (onDisk !== void 0 && onDisk !== origin.sha256) {
           missing.push(
-            `${ref} (library "${origin.name}" content changed since lock \u2014 or the lock predates the one shared asset hash; re-lock with \`skaile install\`)`
+            `${ref} (library "${lookup.name}" content changed since lock \u2014 or the lock predates the one shared asset hash; re-lock with \`skaile install\`)`
           );
           continue;
         }
       }
+      found.version = current;
       entries.push(withLibraryFiles(found, libPath, fileSets, this.registry));
     }
     return { entries, missing };
   }
   /**
-   * On-disk root of the library named `name`: the registered path from the index
-   * when it exists, else `<libraries dir>/<name>`; `null` when neither is a directory.
+   * Whether a deployed copy exists for the lock entries `install` kept for the unresolved
+   * `ref`. A kind with no install target has no deployed copy.
+   */
+  keptCopyDeployed(kept, ref) {
+    const want = parseRefTolerant(ref.split(" ")[0] ?? ref);
+    if (!want) return false;
+    return Object.keys(kept.assets).some((key) => {
+      const id = parseCanonicalLockKey(key);
+      if (id.kind !== want.kind || id.name !== want.name) return false;
+      if (want.publisher && id.publisher !== want.publisher) return false;
+      const component = this.installTarget(id.kind);
+      return component !== void 0 && isDeployed(component, id.name, this.driverTarget, this.global, this.projectDir);
+    });
+  }
+  /**
+   * How the library `origin` names stands on this machine. THE one lookup of a locked library
+   * ("is it registered here?"): `check`, `outdated`, `install` and `install --locked` all ask it.
+   *
+   * - registered in the index under its name: `ok` at its registered path, or `dir-missing` when
+   *   that directory is gone;
+   * - not registered: a directory `<libraries dir>/<name>` nobody unregistered still counts as a
+   *   hand-made library (`ok`). One `library remove` unregistered without `--purge` does not
+   *   (it stays on disk but no longer resolves), and neither does the reserved `installed` folder.
+   * - otherwise, when the lock recorded the library's remote URL: another registered library
+   *   whose git remote is the same repository (`.git` suffix, trailing `/` and the
+   *   `git@host:o/r` / `https://host/o/r` forms do not matter) and whose directory exists is
+   *   `ok`, with `name` set to the name it is registered under here. The library name is
+   *   machine-local; the remote is what a clone shares.
    */
-  libraryPath(name, snap) {
-    if (name === GLOBAL_INSTALL_DIR_NAME) return null;
+  lockedLibrary(origin, snap) {
+    const { name } = origin;
+    if (name === GLOBAL_INSTALL_DIR_NAME) return { state: "unregistered" };
+    let byName = { state: "unregistered" };
     const registered = snap?.libraries.find((l) => l.name === name)?.path;
-    if (registered && existsSync(registered)) return registered;
-    try {
-      const guess = join(resolveLibraryDir(), name);
-      return existsSync(guess) ? guess : null;
-    } catch {
-      return null;
+    if (registered) {
+      byName = existsSync(registered) ? { state: "ok", path: registered, name } : { state: "dir-missing", path: registered };
+    } else {
+      try {
+        const guess = join(resolveLibraryDir(), name);
+        if (existsSync(guess) && !unregisteredLibraryNames().has(name)) {
+          byName = { state: "ok", path: guess, name };
+        }
+      } catch {
+      }
     }
+    if (byName.state === "unregistered") {
+      const renamed = renamedLibraryName(name);
+      const now = renamed ? snap?.libraries.find((l) => l.name === renamed) : void 0;
+      if (now && existsSync(now.path)) return { state: "ok", path: now.path, name: now.name };
+    }
+    if (byName.state === "ok" || !origin.url) return byName;
+    const wanted = normalizeRepoUrl(origin.url);
+    const byUrl = snap?.libraries.find((l) => {
+      const url = libraryRemoteUrl(l);
+      return l.name !== name && url !== void 0 && normalizeRepoUrl(url) === wanted && existsSync(l.path);
+    });
+    return byUrl ? { state: "ok", path: byUrl.path, name: byUrl.name } : byName;
+  }
+  /** On-disk root of the library `origin` names; `null` unless {@link lockedLibrary} says `ok`. */
+  libraryPath(origin, snap) {
+    const found = this.lockedLibrary(origin, snap);
+    return found.state === "ok" ? found.path : null;
+  }
+  /**
+   * Where each library-origin lock entry of this project resolves on this machine: identity
+   * `kind:publisher/name` (no scope sigil, no version) → the name the locked library is
+   * registered under here. The name differs from the locked one when the lock's remote URL
+   * matched another registered library ({@link lockedLibrary}). A deployed entry whose library
+   * resolves nowhere (not registered, directory gone) maps to `null`.
+   *
+   * Direct `asset install` entries (`library.installed`) are included and resolved the same
+   * way, but they map to the locked library name when that lookup fails: such a copy sits in
+   * the project and does not depend on the library still being registered. A missing or
+   * unreadable lock yields an empty map. `skaile manage` uses it to tick the right library row.
+   */
+  async lockedLibraryNames() {
+    const out = /* @__PURE__ */ new Map();
+    const locked = Object.entries(this.tryReadLock()?.assets ?? {}).filter(
+      ([, e]) => e.library !== void 0
+    );
+    if (locked.length === 0) return out;
+    const snap = await this.loadLibraryIndex();
+    for (const [key, e] of locked) {
+      const { publisher, kind, name } = parseCanonicalLockKey(key);
+      if (!publisher || !kind || !name) continue;
+      const origin = e.library;
+      const lookup = this.lockedLibrary(origin, snap);
+      const resolved = lookup.state === "ok" ? lookup.name : origin.installed ? origin.name : null;
+      out.set(`${kind}:${publisher}/${name}`, resolved);
+    }
+    return out;
   }
   // ── Store fetch-then-deploy ────────────────────────────────────────────
   /** A candidate's stable identity key (`<publisher>/<kind>:<name>@<version>`). */
@@ -1443,7 +1935,10 @@ var AssetManager = class {
           return id !== null && (opts.provenanceIndex.get(id)?.length ?? 0) === 0;
         })
       );
-      const hit = await this.resolveLibraryEntries([...libraryTried]);
+      const hit = await this.resolveLibraryEntries([...libraryTried], {
+        quiet: !opts.warnCollisions,
+        lockedLibraries: opts.lockedLibraries
+      });
       const next = absorb(hit);
       const rest = fresh.filter((ref) => !hit.resolved.has(ref));
       if (rest.length > 0) {
@@ -1458,7 +1953,8 @@ var AssetManager = class {
         for (const o of r.overridesApplied) overridesApplied.add(o);
         presets.push(...r.presets);
         const hit2 = await this.resolveLibraryEntries(
-          r.missing.filter((m) => !libraryTried.has(m))
+          r.missing.filter((m) => !libraryTried.has(m)),
+          { quiet: !opts.warnCollisions, lockedLibraries: opts.lockedLibraries }
         );
         next.push(...absorb(hit2));
         for (const m of r.missing) if (!hit2.resolved.has(m)) missing.add(m);
@@ -1631,6 +2127,9 @@ var AssetManager = class {
    * @param opts.link - When `true`, symlink local-path assets instead of copying them
    *   (the author dev-loop). Machine-local / not for committing; a no-op for
    *   store/factory sources. Defaults to copy.
+   * @param opts.moveLibraries - When `true` (`skaile update`), a locked library asset is
+   *   re-resolved from every library and may move to another one; {@link InstallResult.moved}
+   *   lists the moves. Without it a locked asset stays on the library its lock entry names.
    * @returns {@link InstallResult} summarising what was deployed, what was missing, and any collisions.
    */
   async install(opts) {
@@ -1638,6 +2137,20 @@ var AssetManager = class {
     if (opts?.locked) {
       return this.installLocked(repositories, patches, dependencies);
     }
+    const lockForLibraries = this.tryReadLock();
+    if (lockForLibraries) {
+      const unavailable = await this.unavailableLockedLibraries(lockForLibraries, dependencies);
+      if (unavailable.length > 0) {
+        return {
+          deployed: [],
+          removed: [],
+          missing: unavailable,
+          lockWritten: false,
+          npmInstalled: [],
+          npmFailed: []
+        };
+      }
+    }
     const cloneError = this.ensureSourceClones(repositories, sources);
     if (cloneError) return cloneError;
     const provenanceIndex = await buildProvenanceIndex(this.buildClones(repositories), {
@@ -1646,7 +2159,15 @@ var AssetManager = class {
     });
     const { resolved, missing, overridesApplied, lib, presets } = await this.resolveLibraryFirst(
       dependencies,
-      { provenanceIndex, overrides, stores, declaredRefs: dependencies }
+      {
+        provenanceIndex,
+        overrides,
+        stores,
+        declaredRefs: dependencies,
+        // `install` restores what the lock recorded: a changed default library or a second
+        // library holding the same ref does not move a locked asset. `update` re-resolves.
+        ...opts?.moveLibraries ? {} : { lockedLibraries: await this.lockedLibraryNames() }
+      }
     );
     this.assertNoFolderCollision([...resolved, ...lib.entries.map((e) => this.entryIdentity(e))]);
     const stillMissing = missing.filter((m) => !lib.resolved.has(m));
@@ -1657,20 +2178,24 @@ var AssetManager = class {
     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,
+        kept.refs.has(ref) ? this.keptCopyDeployed(kept, ref) ? "the deployed copy and its lock entry are kept" : "its lock entry is kept; no deployed copy exists" : 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 freshLock = buildLockFile(resolved, overridesApplied, libraryLock);
+    const freshLock = {
+      ...buildLockFile(resolved, overridesApplied, libraryLock),
+      ...presetsLockSlice(presets)
+    };
     await this.keepRequiredByKept(prevLock, kept, Object.keys(freshLock.assets));
-    const removed = this.reconcileRemovedAssets(
+    const { removed, replaced } = this.reconcileRemovedAssets(
       resolved,
       /* @__PURE__ */ new Set([...Object.keys(libraryLock), ...Object.keys(kept.assets)])
     );
     const entries = [...await this.buildCatalogEntries(resolved, repositories), ...lib.entries];
+    const copyDrift = await this.lockedCopyDrift();
     const deployed = [
       ...new Set(
         this.targetHarnesses().flatMap(
@@ -1678,23 +2203,31 @@ var AssetManager = class {
         )
       )
     ];
+    const restored = this.restoredCopies(copyDrift, deployed);
     await this.renderDriverMcpConfig();
-    const agentRender = this.renderAgentInstances();
-    const lockWritten = resolved.length > 0 || lib.entries.length > 0 || existsSync(this.lockPath);
+    const agentRender = await this.renderAgentInstances();
+    const lockWanted = resolved.length > 0 || lib.entries.length > 0 || existsSync(this.lockPath);
+    let lockWritten = false;
     let relocked = [];
-    if (lockWritten) {
+    let moved = [];
+    if (lockWanted) {
       const lockData = withKeptLockEntries(freshLock, kept);
       relocked = relockedRefs(prevLock, lockData);
-      writeLock(this.lockPath, lockData);
+      moved = libraryMoves(prevLock, libraryLock);
+      lockWritten = writeLock(this.lockPath, lockData);
     }
     this.recordInstallHistory(deployed, removed);
     const { npmInstalled, npmFailed } = await this.installRuntimeAssetDeps();
+    await this.adviseMissing(stillMissing, missingHints);
     return {
       deployed,
       removed,
       missing: stillMissing,
       ...Object.keys(missingHints).length > 0 ? { missingHints } : {},
       ...relocked.length > 0 ? { relocked } : {},
+      ...moved.length > 0 ? { moved } : {},
+      ...replaced.length > 0 ? { replaced } : {},
+      ...restored.length > 0 ? { restored } : {},
       lockWritten,
       npmInstalled,
       npmFailed,
@@ -1714,7 +2247,7 @@ var AssetManager = class {
     const fresh = freshKeys.map(parseCanonicalLockKey);
     const queue = Object.keys(kept.assets);
     for (const key of queue) {
-      for (const dep of await this.deployedRequirements(key)) {
+      for (const dep of await this.deployedRequirementsOf(parseCanonicalLockKey(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);
@@ -1730,9 +2263,14 @@ var AssetManager = class {
       }
     }
   }
-  /** Publisher-qualified refs the deployed copy of the asset behind lock `key` requires. */
-  async deployedRequirements(key) {
-    const { kind, name, publisher } = parseCanonicalLockKey(key);
+  /**
+   * Publisher-qualified refs the deployed copy of `id` requires, read from its own
+   * manifest file (`metadata.requires`, a manifest `dependencies:` entry): the one place
+   * the requirements stay knowable when no source or library holds the asset any more.
+   * A copy that is not deployed or cannot be read has no known requirements.
+   */
+  async deployedRequirementsOf(id) {
+    const { kind, name, publisher } = id;
     const component = kind ? this.installTarget(kind) : void 0;
     if (!kind || !name || !component) return [];
     const dir = deployedDir(component, name, this.driverTarget, this.global, this.projectDir);
@@ -1805,21 +2343,32 @@ var AssetManager = class {
       ...keep
     ]);
     const removed = [];
+    const replaced = [];
     if (oldLock) {
       for (const ref of Object.keys(oldLock.assets)) {
         if (!resolvedRefs.has(ref)) {
-          const { kind, name } = parseCanonicalLockKey(ref);
+          const { kind, name, publisher, version } = parseCanonicalLockKey(ref);
           if (kind === "preset") continue;
           if (kind && name) {
             for (const t of this.targetHarnesses()) removeAsset(kind, name, this.deployOptsFor(t));
-            removed.push(ref);
+            const successor = [...resolvedRefs].find((r) => {
+              const o = parseCanonicalLockKey(r);
+              return o.kind === kind && o.name === name && o.publisher === publisher;
+            });
+            if (successor) {
+              replaced.push({
+                ref: `${kind}:${publisher ? `@${publisher}/` : ""}${name}`,
+                from: version ?? "",
+                to: parseCanonicalLockKey(successor).version ?? ""
+              });
+            } else removed.push(ref);
           } else {
             console.warn(`skaile: cannot reconcile unparseable lock key "${ref}" \u2014 left in place.`);
           }
         }
       }
     }
-    return removed;
+    return { removed, replaced };
   }
   /** Append `add`/`remove` history entries for a completed install reconcile. */
   recordInstallHistory(deployed, removed) {
@@ -1935,9 +2484,39 @@ var AssetManager = class {
     }
     return { npmInstalled, npmFailed };
   }
+  /**
+   * Give every ref `install` could not resolve, and that has no hint yet, the fix the shared
+   * {@link AssetManager.projectState} names for it (a declared ref no library or source holds,
+   * a requirement nothing holds). Runs after the deploy, so a requirer is known by then.
+   * Mutates `hints`: ` <reason>` follows the ref in the `Missing:` line.
+   */
+  async adviseMissing(refs, hints) {
+    const open = refs.filter((r) => !hints[r]);
+    if (open.length === 0) return;
+    const { gaps } = await this.projectState();
+    for (const ref of open) {
+      const want = parseRefTolerant(ref.split(" ")[0] ?? ref);
+      if (!want) continue;
+      const gap = gaps.find(
+        (g) => (g.type === "declared" || g.type === "requires") && g.manualFix && sameAsset(g.ref, want)
+      );
+      if (gap) hints[ref] = ` ${gap.reason}`;
+    }
+  }
   async installLocked(repositories, patches, dependencies) {
     const lock = this.tryReadLock();
     if (!lock) {
+      const gaps2 = (await this.projectState()).gaps.filter((g) => g.type !== "agent");
+      if (gaps2.some((g) => g.manualFix)) {
+        return {
+          deployed: [],
+          removed: [],
+          missing: gaps2.map((g) => g.message),
+          lockWritten: false,
+          npmInstalled: [],
+          npmFailed: []
+        };
+      }
       throw new Error("No lock file found. Run `skaile install` first.");
     }
     this.assertNoFolderCollision(Object.keys(lock.assets).map(parseCanonicalLockKey));
@@ -1999,6 +2578,7 @@ var AssetManager = class {
       if (!repositories[slug]) repositories[slug] = { url: entry.source.url, path: cloneDir };
     }
     const library = await this.restoreLibraryLockEntries(lock);
+    const copyDrift = await this.lockedCopyDrift();
     const deployed = [
       ...new Set(
         this.targetHarnesses().flatMap(
@@ -2011,15 +2591,17 @@ var AssetManager = class {
         )
       )
     ];
+    const restored = this.restoredCopies(copyDrift, deployed);
     await this.renderDriverMcpConfig();
-    const agentRender = this.renderAgentInstances();
+    const agentRender = await 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 gaps = (await this.projectState()).gaps.filter((g) => {
+      if (g.type === "agent") return false;
       const p = parseRefTolerant(g.ref);
       return !(p && alreadyMissing.has(`${p.kind}:${p.name}`));
     }).map((g) => g.message);
@@ -2028,9 +2610,68 @@ var AssetManager = class {
       removed: [],
       missing: [...library.missing, ...gaps],
       lockWritten: false,
+      ...restored.length > 0 ? { restored } : {},
       ...agentRender
     };
   }
+  /**
+   * Parse the ref `add` was given. A ref the grammar rejects fails with the parser's message
+   * minus its manifest-migration advice (it points at a skill that is not for `add`), and:
+   * - a publisher-less ref (`report-html`, `skill:report-html`) names the assets of that
+   *   kind and name that `add` can resolve (a source, the bundled factory source or a
+   *   library holds them), so `Did you mean` never names an asset that does not resolve;
+   * - a `@version` suffix (`skill:@acme/x@1.0.0`) says the pin is written `#<version>`.
+   */
+  async parseAddRef(ref, repositories, sources) {
+    try {
+      return parseAssetRef(ref);
+    } catch (err) {
+      if (!(err instanceof Error)) throw err;
+      const advice = " Run the `migrate-skaile-manifest` skill on legacy manifests.";
+      const plain = err.message.endsWith(advice) ? err.message.slice(0, -advice.length) : err.message;
+      if (plain.startsWith("publisher required")) {
+        const matches = await this.resolvableMatches(ref, repositories, sources);
+        const hint = matches.length === 0 ? "" : matches.length === 1 ? ` Did you mean ${matches[0]}?` : ` Did you mean one of: ${matches.join(", ")}?`;
+        throw new Error(`${plain}${hint}`);
+      }
+      const pinned = /^(.*\/[^@#/]+)@([^@#/]+)$/.exec(ref.trim());
+      if (pinned && plain.startsWith("invalid asset name")) {
+        throw new Error(`${plain} To pin a version, write ${pinned[1]}#${pinned[2]}.`);
+      }
+      throw new Error(plain);
+    }
+  }
+  /**
+   * The publisher-qualified refs of the assets named like the publisher-less `ref` that
+   * `add` resolves: held by a source clone, the bundled factory source or a registered
+   * library. A ref without a kind means a skill, as the grammar says.
+   */
+  async resolvableMatches(ref, repositories, sources) {
+    const trimmed = ref.trim();
+    const colon = trimmed.indexOf(":");
+    const rawKind = colon === -1 ? "skill" : 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)) return [];
+    const found = /* @__PURE__ */ new Set();
+    const note = (c) => {
+      if (c.kind === kind && c.name === name && c.publisher) {
+        found.add(assetRefToStr({ kind, name, publisher: c.publisher.replace(/^@/, "") }));
+      }
+    };
+    try {
+      this.ensureSourceClonesQuiet(repositories, sources);
+      const index = await buildProvenanceIndex(this.buildClones(repositories), {
+        projectDir: this.projectDir,
+        knownKinds: this.knownKinds
+      });
+      for (const candidates of index.values()) for (const c of candidates) note(c);
+      for (const { entry } of await this.libraryAssets()) note(entry);
+    } catch {
+    }
+    return [...found].sort();
+  }
   /**
    * Add a single asset (and its transitive dependencies) to the workspace.
    *
@@ -2044,6 +2685,8 @@ 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.onLibraryMoved - Called once per asset whose lock entry named another library
+   *   than the one this add resolved it 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.
@@ -2052,7 +2695,7 @@ var AssetManager = class {
    */
   async add(ref, opts) {
     const { repositories, sources, stores, dependencies, overrides, patches } = this.loadConfig();
-    const parsed = parseAssetRef(ref);
+    const parsed = await this.parseAddRef(ref, repositories, sources);
     this.ensureSourceClonesQuiet(repositories, sources);
     const provenanceIndex = await buildProvenanceIndex(this.buildClones(repositories), {
       projectDir: this.projectDir,
@@ -2060,9 +2703,24 @@ var AssetManager = class {
     });
     const { resolved, missing, overridesApplied, lib, presets } = await this.resolveLibraryFirst(
       [ref],
-      { provenanceIndex, overrides, stores, declaredRefs: dependencies }
+      { provenanceIndex, overrides, stores, declaredRefs: dependencies, warnCollisions: true }
     );
     if (resolved.length === 0 && lib.entries.length === 0 && presets.length === 0) {
+      const snap = await this.loadLibraryIndex();
+      const bare = (p) => (p ?? "").replace(/^@/, "");
+      for (const l of snap?.libraries ?? []) {
+        const libPath = this.libraryPath({ name: l.name }, snap);
+        if (!libPath || !manifestFileHasAssetsArray(libPath)) continue;
+        const unlisted = await scanUnlistedAssets(libPath, l.name, this.registry);
+        const hit = unlisted.find(
+          (u) => !u.registeredAt && u.entry.kind === parsed.kind && u.entry.name === parsed.name && (!parsed.publisher || bare(u.entry.publisher) === bare(parsed.publisher))
+        );
+        if (hit) {
+          throw new Error(
+            `${canonicalEntryRef(hit.entry)} is in library "${l.name}" but not listed in its skaile.manifest.yaml, so only part of its files would be deployed. Run \`skaile library index ${l.name}\`, then add it again.`
+          );
+        }
+      }
       throw new Error(
         `Asset not found: ${ref}${(await this.publisherChangeHints([ref]))[ref] ?? ""}${missing.length ? ` (missing: ${missing.join(", ")})` : ""}`
       );
@@ -2072,6 +2730,18 @@ var AssetManager = class {
         `Preset ${ref} has items that do not resolve: ${missing.join(", ")} \u2014 nothing was added`
       );
     }
+    if (lib.entries.length > 0) {
+      const snap = await this.loadLibraryIndex();
+      for (const e of lib.entries) {
+        const origin = lib.libraryOf.get(e);
+        const libPath = origin ? this.libraryPath({ name: origin }, snap) : null;
+        if (origin && libPath && isUnlistedLibraryAsset(e, libPath)) {
+          throw new Error(
+            `${canonicalEntryRef(e)} is in library "${origin}" but not listed in its skaile.manifest.yaml, so only part of its files would be deployed. Run \`skaile library index ${origin}\`, then add it again.`
+          );
+        }
+      }
+    }
     this.assertNoFolderCollision(
       [...resolved, ...lib.entries.map((e) => this.entryIdentity(e))],
       [
@@ -2080,15 +2750,20 @@ var AssetManager = class {
       ]
     );
     if (missing.length > 0) {
-      console.warn(
-        `skaile: ${ref} was added without unresolved dependencies: ${missing.join(", ")}`
+      throw new Error(
+        `${ref.split("#")[0]} requires ${missing.join(", ")} (not found \u2014 ${REGISTER_HOLDER}, or remove the requirement from the asset's manifest) \u2014 nothing was added`
       );
     }
     const entries = [...await this.buildCatalogEntries(resolved, repositories), ...lib.entries];
     const deployed = [
       ...new Set(
         this.targetHarnesses().flatMap(
-          (t) => deployAll(entries, repositories, patches, this.deployOptsFor(t, opts?.link))
+          (t) => deployAll(
+            entries,
+            repositories,
+            patches,
+            this.deployOptsFor(t, opts?.link, opts?.onSkippedSymlink, opts?.onEnvFile)
+          )
         )
       )
     ];
@@ -2102,10 +2777,18 @@ var AssetManager = class {
     if (presets.length > 0) opts?.onPresets?.(presets);
     this.addDependencyToConfig(ref);
     await this.renderDriverMcpConfig();
-    this.renderAgentInstances();
+    await this.renderAgentInstances();
     if (resolved.length > 0 || lib.entries.length > 0) {
-      const fresh = buildLockFile(resolved, overridesApplied, await this.libraryLockEntries(lib));
-      writeLock(this.lockPath, mergeLockFile(this.tryReadLock(), fresh));
+      const libraryLock = await this.libraryLockEntries(lib);
+      const fresh = {
+        ...buildLockFile(resolved, overridesApplied, libraryLock),
+        ...presetsLockSlice(presets)
+      };
+      const prevLock = this.tryReadLock();
+      if (opts?.onLibraryMoved) {
+        for (const m of libraryMoves(prevLock, libraryLock)) opts.onLibraryMoved(m);
+      }
+      writeLock(this.lockPath, mergeLockFile(prevLock, fresh));
     }
     for (const d of deployed) {
       appendHistory(this.projectDir, {
@@ -2163,16 +2846,16 @@ var AssetManager = class {
     const target = memberIdentity(ref);
     if (!target || target.kind === "preset") return [];
     try {
-      const sameAsset = (id, want) => !!id && id.kind === want.kind && id.name === want.name && (!id.publisher || !want.publisher || id.publisher === want.publisher);
+      const sameAsset2 = (id, want) => !!id && id.kind === want.kind && id.name === want.name && (!id.publisher || !want.publisher || id.publisher === want.publisher);
       const declared = this.loadConfig().dependencies.map(memberIdentity);
       const out = [];
       const seen = /* @__PURE__ */ new Set();
       for (const p of await this.search(void 0, "preset")) {
         const members = [...p.dependencies, ...p.requires.map(depToStr)];
-        if (!members.some((m) => sameAsset(memberIdentity(m), target))) continue;
+        if (!members.some((m) => sameAsset2(memberIdentity(m), target))) continue;
         const publisher = p.publisher?.replace(/^@/, "");
         const presetId = { kind: "preset", name: p.name, publisher };
-        if (declared.some((d) => sameAsset(d, presetId))) continue;
+        if (declared.some((d) => sameAsset2(d, presetId))) continue;
         const presetRef = publisher ? assetRefToStr({ kind: "preset", name: p.name, publisher }) : `preset:${p.name}`;
         if (seen.has(presetRef)) continue;
         seen.add(presetRef);
@@ -2383,19 +3066,39 @@ var AssetManager = class {
    * preset's items count as its requirements. They are undeployed and unlocked;
    * a dependency still declared or required elsewhere stays.
    *
+   * An asset another locked asset (or a declared preset) requires is kept and reported in
+   * `blocked`, nothing changes, unless `opts.force` (see {@link requiredByOthers}).
+   *
    * @returns `changed` as {@link remove}; `pruned` the canonical refs
-   *   (`kind:@publisher/name`) of the dependencies dropped as well.
+   *   (`kind:@publisher/name`) of the dependencies dropped as well; `blocked` when the
+   *   removal was refused.
    */
-  async removeWithDependencies(ref) {
+  async removeWithDependencies(ref, opts) {
     const target = this.resolveRemoveTarget(ref);
     if (!target) return { changed: false, pruned: [] };
+    if (!opts?.force) {
+      const blocked = await this.requiredByOthers(target);
+      if (blocked) return { changed: false, pruned: [], blocked };
+    }
     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) : [];
+    let requiredRefs;
+    if (entry) {
+      requiredRefs = libraryEntryDepRefs(entry);
+    } else {
+      const lockedAs = Object.keys(this.tryReadLock()?.assets ?? {}).map(parseCanonicalLockKey).find(
+        (id) => id.kind === target.kind && id.name === target.name && (!target.publisher || id.publisher === target.publisher)
+      );
+      requiredRefs = await this.deployedRequirementsOf({
+        kind: target.kind,
+        name: target.name,
+        publisher: target.publisher ?? lockedAs?.publisher
+      });
+    }
     const changed = this.removeResolved(target);
     if (!changed || requiredRefs.length === 0) return { changed, pruned: [] };
     return { changed, pruned: await this.pruneOrphans(requiredRefs) };
@@ -2449,15 +3152,65 @@ var AssetManager = class {
       return kind ? { kind, name } : null;
     }
   }
+  /**
+   * The reverse guard of {@link removeWithDependencies}: which other locked assets (and
+   * declared presets) require `target`. Their requirements are read the way {@link lockedGraph}
+   * reads them for pruning. Never touches the project.
+   *
+   * @returns `ref` and `requiredBy` (both `kind:@publisher/name`, version-agnostic), or `null`
+   *   when `target` is not locked or nothing else requires it.
+   */
+  async requiredByOthers(target) {
+    const lock = this.tryReadLock();
+    if (!lock) return null;
+    const { requires, findKey } = await this.lockedGraph(lock);
+    const targetKey = findKey(
+      target.publisher ? assetRefToStr({ kind: target.kind, name: target.name, publisher: target.publisher }) : `${target.kind}:${target.name}`
+    );
+    if (!targetKey) return null;
+    const display = (node) => {
+      if (!lock.assets[node]) return node;
+      const { kind, name, publisher } = parseCanonicalLockKey(node);
+      if (!kind || !name) return node;
+      return publisher ? assetRefToStr({ kind, name, publisher }) : `${kind}:${name}`;
+    };
+    const requiredBy = [...requires].filter(([node, deps]) => node !== targetKey && deps.includes(targetKey)).map(([node]) => display(node));
+    return requiredBy.length > 0 ? { ref: display(targetKey), requiredBy } : null;
+  }
+  /**
+   * Publishers under which the lock or `skaile.yaml` track `kind:name`. A deployed dir carries
+   * no publisher, so this is what says whose copy it is. `undefined` stands for a
+   * publisher-less declaration.
+   */
+  trackedPublishers(kind, name) {
+    const found = /* @__PURE__ */ new Set();
+    const note = (id) => {
+      if (id?.kind === kind && id.name === name) found.add(id.publisher?.replace(/^@/, ""));
+    };
+    for (const key of Object.keys(this.tryReadLock()?.assets ?? {})) {
+      note(parseCanonicalLockKey(key));
+    }
+    try {
+      for (const dep of this.loadConfig().dependencies) note(memberIdentity(dep));
+    } catch {
+    }
+    return found;
+  }
   /** Undeploy `parsed` from every target harness and drop its declaration and lock entry. */
   removeResolved(parsed) {
+    const wantPub = parsed.publisher?.replace(/^@/, "");
+    const tracked = this.trackedPublishers(parsed.kind, parsed.name);
+    const someoneElses = wantPub !== void 0 && tracked.size > 0 && !tracked.has(wantPub) && !tracked.has(void 0);
     let undeployed = false;
-    for (const t of this.targetHarnesses()) {
-      if (removeAsset(parsed.kind, parsed.name, this.deployOptsFor(t))) undeployed = true;
+    if (!someoneElses) {
+      for (const t of this.targetHarnesses()) {
+        if (removeAsset(parsed.kind, parsed.name, this.deployOptsFor(t))) undeployed = true;
+      }
     }
     const undeclared = this.removeDependencyFromConfig(parsed);
-    const unlocked = undeployed || undeclared ? this.pruneLockEntry(parsed) : false;
-    const changed = undeployed || undeclared || unlocked;
+    const unbound = this.removeAgentBindings(parsed);
+    const unlocked = undeployed || undeclared || unbound ? this.pruneLockEntry(parsed) : false;
+    const changed = undeployed || undeclared || unbound || unlocked;
     if (changed) {
       appendHistory(this.projectDir, {
         ref: `${parsed.kind}:${parsed.name}`,
@@ -2518,6 +3271,17 @@ var AssetManager = class {
         changed = true;
       }
     }
+    if (parsed.kind === "preset" && lock.presets) {
+      const kept = lock.presets.filter((key) => {
+        const id = parseCanonicalLockKey(key);
+        return !(id.kind === parsed.kind && id.name === parsed.name && (!parsed.publisher || id.publisher === parsed.publisher));
+      });
+      if (kept.length !== lock.presets.length) {
+        if (kept.length > 0) lock.presets = kept;
+        else delete lock.presets;
+        changed = true;
+      }
+    }
     if (changed) writeLock(this.lockPath, lock);
     return changed;
   }
@@ -2578,6 +3342,7 @@ var AssetManager = class {
     const { repositories } = this.loadConfig();
     const parsed = parseRefTolerant(ref);
     if (!parsed) return null;
+    let best;
     for (const [name, decl] of Object.entries(repositories)) {
       const repoDir = this.resolveRepoDir(decl, name);
       if (!repoDir) continue;
@@ -2585,9 +3350,12 @@ var AssetManager = class {
       const match = entries.find(
         (e) => e.kind === parsed.kind && e.name === parsed.name && (!parsed.publisher || e.publisher === parsed.publisher)
       );
-      if (match) return match;
+      if (match && (!best || gt(coerceVersion(match.version ?? ""), coerceVersion(best.version ?? "")))) {
+        best = match;
+      }
     }
-    const lib = await this.resolveLibraryEntries([ref]);
+    if (best) return best;
+    const lib = await this.resolveLibraryEntries([ref], { quiet: true });
     return lib.entries[0] ?? null;
   }
   /**
@@ -2929,7 +3697,8 @@ var AssetManager = class {
       const out = [];
       try {
         const entry = await this.info(ref);
-        for (const dep of entry ? libraryEntryDepRefs(entry) : []) {
+        const deps = entry ? libraryEntryDepRefs(entry) : lock.assets[node] ? await this.deployedRequirementsOf(parseCanonicalLockKey(node)) : [];
+        for (const dep of deps) {
           const key = findKey(dep);
           if (key && key !== node && !out.includes(key)) out.push(key);
         }
@@ -3022,7 +3791,7 @@ var AssetManager = class {
       return locked.kind === asked.kind && locked.name === asked.name;
     };
     const key = lock.assets[ref] ? ref : Object.keys(lock.assets).find(matchesIdentity);
-    if (!key) return [];
+    if (!key) return asked?.kind === "preset" ? this.whyPreset(lock, asked) : [];
     const { requires, roots } = await this.lockedGraph(lock);
     if (roots.includes(key)) return [key, "direct (skaile.yaml)"];
     const requirers = /* @__PURE__ */ new Map();
@@ -3047,6 +3816,52 @@ var AssetManager = class {
     }
     return [key, "not required by a declared dependency"];
   }
+  /**
+   * The {@link AssetManager.why} chain of a preset. A preset is never a lock asset: its record
+   * is the lock's `presets` slice. Declared in `skaile.yaml` it is `direct`; one only a declared
+   * preset nests is traced through the presets that list it.
+   *
+   * @returns `[]` when the lock does not record the preset.
+   */
+  async whyPreset(lock, asked) {
+    const wanted = memberIdentity(assetRefToStr(asked));
+    const same = (ref) => {
+      const id = memberIdentity(ref);
+      return id !== null && wanted !== null && id.kind === "preset" && id.name === wanted.name && (!id.publisher || !wanted.publisher || id.publisher === wanted.publisher);
+    };
+    const recorded = (lock.presets ?? []).find(same);
+    if (!recorded) return [];
+    let declared = [];
+    try {
+      declared = this.loadConfig().dependencies;
+    } catch {
+    }
+    const roots = declared.filter((d) => memberIdentity(d)?.kind === "preset");
+    if (roots.some(same)) return [recorded, "direct (skaile.yaml)"];
+    const parent = /* @__PURE__ */ new Map();
+    const seen = new Set(roots);
+    const queue = [...roots];
+    for (let node = queue.shift(); node !== void 0; node = queue.shift()) {
+      let items = [];
+      try {
+        const entry = await this.info(node);
+        items = entry ? libraryEntryDepRefs(entry) : [];
+      } catch {
+      }
+      for (const item of items) {
+        if (memberIdentity(item)?.kind !== "preset" || seen.has(item)) continue;
+        seen.add(item);
+        parent.set(item, node);
+        if (same(item)) {
+          const chain = [];
+          for (let c = item; c !== void 0; c = parent.get(c)) chain.push(c);
+          return [...chain, "direct (skaile.yaml)"];
+        }
+        queue.push(item);
+      }
+    }
+    return [recorded, "not required by a declared dependency"];
+  }
   /**
    * List installed assets that have a newer upstream available.
    *
@@ -3057,11 +3872,12 @@ var AssetManager = class {
    * - **Library assets** — a library-origin lock entry whose library files on disk
    *   (not the index, which lags until `skaile library index`) hold a newer version
    *   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`.
+   *   different bytes (`contentChanged`). `behind` is 0.
+   * - **Project state** — every {@link AssetManager.projectState} gap (an unregistered or
+   *   renamed library, a missing deployed copy, 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` lists what `check`, `doctor` and `install --locked` fail
+   *   on. An asset that also has a version row is listed once, with that row.
    *
    * @returns Array of {@link OutdatedEntry} objects.
    */
@@ -3070,7 +3886,6 @@ var AssetManager = class {
     const lock = this.tryReadLock();
     if (!lock) return this.addLockGapRows([]);
     const result = [];
-    const reported = /* @__PURE__ */ new Set();
     const commitCounts = /* @__PURE__ */ new Map();
     for (const src of lock.sources) {
       const slug = sourceCacheKey(src.url);
@@ -3094,7 +3909,6 @@ var AssetManager = class {
           currentVersion: version ?? "",
           behind
         });
-        reported.add(ref);
       }
     }
     const libraryAssets = Object.entries(lock.assets).filter(
@@ -3108,28 +3922,9 @@ var AssetManager = class {
         const origin = entry.library;
         const { publisher, kind, name } = parseCanonicalLockKey(ref);
         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,
-            publisher,
-            currentVersion: origin.version,
-            behind: 0,
-            library: origin.name,
-            ...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;
-        }
+        const lookup = this.lockedLibrary(origin, snap);
+        if (lookup.state !== "ok") continue;
+        const libPath = lookup.path;
         const scanKey = `${libPath}\0${publisher}`;
         let scanned = scans.get(scanKey);
         if (!scanned) {
@@ -3138,7 +3933,7 @@ var AssetManager = class {
         }
         const found = scanned.find((x) => x.kind === kind && x.name === name);
         if (!found) continue;
-        const diskVersion = found.version || newestLibraryDef(snap, origin.name, { kind, publisher, name })?.version;
+        const diskVersion = found.version || newestLibraryDef(snap, lookup.name, { kind, publisher, name })?.version;
         if (diskVersion && gt(coerceVersion(diskVersion), coerceVersion(origin.version))) {
           result.push({
             kind,
@@ -3147,9 +3942,8 @@ var AssetManager = class {
             currentVersion: origin.version,
             behind: 0,
             latestVersion: diskVersion,
-            library: origin.name
+            library: lookup.name
           });
-          reported.add(ref);
           continue;
         }
         if (origin.sha256) {
@@ -3163,41 +3957,24 @@ var AssetManager = class {
               publisher,
               currentVersion: origin.version,
               behind: 0,
-              library: origin.name,
+              library: lookup.name,
               contentChanged: true
             });
-            reported.add(ref);
           }
         }
       }
     }
-    for (const [ref, entry] of Object.entries(lock.assets)) {
-      if (reported.has(ref) || entry.library?.installed) continue;
-      const { publisher, kind, name, version } = parseCanonicalLockKey(ref);
-      const component = kind ? this.installTarget(kind) : void 0;
-      if (!kind || !name || !component) continue;
-      if (isDeployed(component, name, this.driverTarget, this.global, this.projectDir)) {
-        continue;
-      }
-      result.push({
-        kind,
-        name,
-        publisher: publisher ?? "",
-        currentVersion: entry.library?.version ?? version ?? "",
-        behind: 0,
-        ...entry.library ? { library: entry.library.name } : {},
-        problem: "deployed copy missing"
-      });
-    }
     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.
+   * Add one `problem` row per {@link AssetManager.projectState} gap whose asset is not
+   * listed yet, so `outdated` lists the same assets `check`, `doctor` and `install --locked`
+   * fail on. An asset that is behind its source and also broken is listed once, with its
+   * version row.
    */
   async addLockGapRows(rows) {
     const listed = new Set(rows.map((r) => `${r.kind}:${r.name}`));
-    for (const gap of await this.lockGaps()) {
+    for (const gap of (await this.projectState()).gaps) {
       const parsed = parseRefTolerant(gap.ref);
       const id = parsed ? `${parsed.kind}:${parsed.name}` : gap.ref;
       if (listed.has(id)) continue;
@@ -3214,6 +3991,33 @@ var AssetManager = class {
     }
     return rows;
   }
+  /**
+   * The deploy entry of a library-origin asset from the library its lock entry records,
+   * at the locked version when that library still holds it (else its newest). Other
+   * libraries holding the same ref are not consulted: the lock already chose.
+   *
+   * @param want - Kind, name and optional publisher of the asset.
+   * @returns `null` when the lock has no library-origin entry for it, or the recorded
+   *   library is gone or no longer holds it (callers fall back to a general lookup).
+   */
+  async lockedLibraryEntry(want) {
+    const snap = await this.loadLibraryIndex();
+    for (const [key, e] of Object.entries(this.tryReadLock()?.assets ?? {})) {
+      const id = parseCanonicalLockKey(key);
+      if (!e.library || e.library.installed || !id.publisher) continue;
+      if (id.kind !== want.kind || id.name !== want.name) continue;
+      if (want.publisher && id.publisher !== want.publisher) continue;
+      const canonical = `${id.kind}:@${id.publisher}/${id.name}`;
+      const refs = e.library.version ? [`${canonical}#${e.library.version}`, canonical] : [canonical];
+      const lookup = this.lockedLibrary(e.library, snap);
+      const library = lookup.state === "ok" ? lookup.name : e.library.name;
+      for (const r of refs) {
+        const hit = (await this.resolveLibraryEntries([r], { library })).entries[0];
+        if (hit) return hit;
+      }
+    }
+    return null;
+  }
   /**
    * Produce a unified diff from the deployed asset to its catalog source: `-` lines
    * are in the deployed copy only (local edits `update` would overwrite), `+` lines
@@ -3231,10 +4035,16 @@ var AssetManager = class {
   async diff(ref) {
     const parsed = parseRefTolerant(ref);
     if (!parsed) return { status: "not-found" };
-    const entry = await this.info(ref);
+    const entry = await this.lockedLibraryEntry(parsed) ?? await this.info(ref);
     if (!entry || !existsSync(entry.source)) return { status: "not-found" };
     const component = this.installTarget(parsed.kind);
+    if (parsed.kind === "preset" && this.presetRecorded(parsed)) return { status: "no-files" };
     if (!component) return { status: "not-deployed" };
+    if (component === "agent") {
+      const diff = diffDeployedAgent(entry, this.deployOptsFor(this.driverTarget));
+      if (diff === null) return { status: "not-deployed" };
+      return diff === "" ? { status: "identical" } : { status: "differs", diff };
+    }
     const deployedPath = join(
       deployedBase(component, this.driverTarget, this.global, this.projectDir),
       parsed.name
@@ -3413,7 +4223,10 @@ var AssetManager = class {
         continue;
       }
       const gaps = [];
-      for (const req of full.requires) {
+      const requirements = dedupeRequirements(full.requires, publisher).map(
+        (r) => r.publisher || !publisher ? r : { ...r, publisher }
+      );
+      for (const req of requirements) {
         const dep = memberIdentity(depToStr(req));
         if (!dep) continue;
         const depComponent = this.installTarget(dep.kind);
@@ -3432,7 +4245,10 @@ var AssetManager = class {
           if (!inRepos) gaps.push({ issue, ref: depToStr(req) });
         }
       }
-      const inLibrary = await this.resolveLibraryEntries(gaps.map((g) => g.ref));
+      const inLibrary = await this.resolveLibraryEntries(
+        gaps.map((g) => g.ref),
+        { quiet: true }
+      );
       for (const g of gaps) g.issue.inRepos = inLibrary.resolved.has(g.ref);
     }
     for (const [presetRef, gaps] of await this.declaredPresetGaps(dependencies, lock)) {
@@ -3453,30 +4269,52 @@ var AssetManager = class {
     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.
+   * The project's state as one verdict: every way the project differs from what it
+   * declares and locks. `skaile check`, `skaile doctor`, `skaile outdated`, `skaile diff`
+   * and `skaile install --locked` all take their verdict and exit code from this one list,
+   * so one situation reads the same in all five.
    *
    * - `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;
+   * - `drift` — a locked asset whose 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.
+   * - `requires` — a deployed asset's `requires` (or a declared preset's item) that is not
+   *   deployed (so not locked either);
+   * - `unresolved` — a lock-managed deployed asset that no source or library holds any more;
+   * - `library` — a locked library asset whose library is not registered (renamed or
+   *   removed) or no longer holds it, while another library holds it now;
+   * - `incomplete` — a deployed library asset that lacks files of its library entry;
+   * - `content` — a locked library asset whose files in the library changed since the lock
+   *   (or whose lock hash predates the one shared asset hash); `skaile install` re-locks it;
+   * - `agent` — an `agents.<id>.ref` (or `agent.definition`) that binds to no agent.
+   *
+   * An asset appears once for what the lock says about it (`unresolved`, else `library`,
+   * else `drift`). A declared ref no registered library or source holds names
+   * `skaile library init` / `skaile remove`, never `skaile install`: `install` has nothing
+   * to resolve it from.
    *
-   * 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.
+   * Project mode only: a global manager (`global: true`) has no gaps. A project without
+   * `skaile.yaml` has no declared set, so only the lock and deployed-asset gaps can appear.
    *
-   * @returns One {@link LockGap} per gap; empty when the lock covers everything declared.
+   * @returns The {@link ProjectState}; `gaps` is empty when the project is as declared and locked.
    */
-  async lockGaps() {
-    if (this.global) return [];
-    const gaps = [];
-    const issues = await this.doctor();
-    for (const i of issues) {
+  async projectState() {
+    if (this.global) return { gaps: [], requirements: [] };
+    const lock = this.tryReadLock();
+    const lockedIds = Object.keys(lock?.assets ?? {}).map(parseCanonicalLockKey);
+    const requirements = await this.doctor();
+    let gaps = [];
+    const lockIdentity = (kind, name) => {
+      const publisher = lockedIds.find((id) => id.kind === kind && id.name === name)?.publisher;
+      return publisher ? `${kind}:@${publisher}/${name}` : `${kind}:${name}`;
+    };
+    for (const i of requirements) {
       if (i.unresolved) {
-        const ref = `${i.assetKind}:${i.assetName}`;
+        const publisher = lockedIds.find(
+          (id) => id.kind === i.assetKind && id.name === i.assetName
+        )?.publisher;
+        const ref = publisher ? `${i.assetKind}:@${publisher}/${i.assetName}` : `${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",
@@ -3487,27 +4325,351 @@ var AssetManager = class {
         });
         continue;
       }
-      const asset = `${i.assetKind}:${i.assetName}`;
+      const asset = lockIdentity(i.assetKind, i.assetName);
       const dep = `${i.depKind}:${i.depName}`;
-      const fix = i.inRepos ? "fixable" : "not found";
+      if (i.inRepos) {
+        gaps.push({
+          type: "requires",
+          ref: dep,
+          asset,
+          reason: `is required by ${asset} but neither deployed nor locked (fixable)`,
+          message: `${asset} requires ${dep} (fixable)`
+        });
+      } else {
+        const fix = requirementNoHolderFix(asset);
+        gaps.push({
+          type: "requires",
+          ref: dep,
+          asset,
+          reason: `is required by ${asset} but neither deployed nor locked (not found \u2014 ${fix})`,
+          message: `${asset} requires ${dep} (not found \u2014 ${fix})`,
+          manualFix: true
+        });
+      }
+    }
+    const named = new Set(
+      gaps.filter((g) => g.type === "unresolved").map((g) => gapIdentity(g.ref))
+    );
+    for (const gap of await this.libraryOriginGaps(named)) {
+      gaps.push(gap);
+      named.add(gapIdentity(gap.ref));
+    }
+    const libraryHeld = (dep) => {
+      const want = parseRefTolerant(dep);
+      return want !== null && gaps.some((g) => g.type === "library" && sameAsset(g.ref, want));
+    };
+    gaps = gaps.filter((g) => !(g.type === "requires" && libraryHeld(g.ref)));
+    for (const gap of this.undeployedLockGaps(lock, named)) {
+      gaps.push(gap);
+      named.add(gapIdentity(gap.ref));
+    }
+    for (const d of await this.lockedCopyDrift()) {
+      if (named.has(gapIdentity(d.ref))) continue;
+      const parts = [
+        ...d.modified.map((f) => `${f} was edited`),
+        ...d.extra.map((f) => `${f} is not part of the asset`)
+      ];
+      const reason = `is locked, but its deployed copy differs from the lock (${parts.join("; ")}) \u2014 run \`skaile install --locked\` to restore it`;
+      gaps.push({ type: "modified", ref: d.ref, reason, message: `${d.ref} ${reason}` });
+      named.add(gapIdentity(d.ref));
+    }
+    gaps.push(...await this.declaredGaps(requirements, named));
+    for (const d of await this.incompleteDeploys()) {
+      const reason = `is deployed without ${d.missing.join(", ")} \u2014 run \`skaile install\` to restore it`;
+      gaps.push({ type: "incomplete", ref: d.ref, reason, message: `${d.ref} ${reason}` });
+    }
+    for (const u of unboundAgentInstances(this.projectDir, this.driverTarget)) {
+      const reason = u.ref.startsWith("agent:") ? await this.unboundAgentReason(u.id, u.ref) : `is bound by agent instance "${u.id}" but resolves to no agent.yaml \u2014 fix the path, or drop the binding from skaile.yaml`;
       gaps.push({
-        type: "requires",
-        ref: dep,
-        reason: `is required by ${asset} but neither deployed nor locked (${fix})`,
-        message: `${asset} requires ${dep} (${fix})`
+        type: "agent",
+        ref: u.ref,
+        reason,
+        message: `${u.ref} ${reason}`,
+        manualFix: true
       });
     }
-    let declared = [];
+    return {
+      gaps,
+      requirements: requirements.filter(
+        (i) => i.unresolved || !libraryHeld(`${i.depKind}:${i.depName}`)
+      )
+    };
+  }
+  /**
+   * Why the `agent:` ref of agent instance `id` binds to nothing, as the phrase that follows
+   * the ref in a {@link LockGap}; see {@link AssetManager.unboundAgentAdvice}.
+   */
+  async unboundAgentReason(id, ref) {
+    const { lead, advice } = await this.unboundAgentAdvice(ref);
+    return `is bound by agent instance "${id}" but ${lead} \u2014 ${advice}`;
+  }
+  /**
+   * What is wrong with an `agent:` ref bound by an agent instance and what to do (`lead`, then
+   * `advice`). `skaile add` is named only when a registered library or source holds the agent
+   * and `add` takes the ref (it needs a publisher); otherwise the user registers the library
+   * that holds it, writes the publisher, or drops the binding.
+   */
+  async unboundAgentAdvice(ref) {
+    const drop = "or drop the binding from skaile.yaml";
+    const publisher = parseRefTolerant(ref)?.publisher;
+    if (publisher && await this.info(ref) !== null) {
+      return {
+        lead: "no agent was added for it",
+        advice: `run \`skaile add ${ref}\` first, ${drop}`
+      };
+    }
+    if (!publisher) {
+      return {
+        lead: "names no publisher",
+        advice: `write it as agent:@<publisher>/<name> (\`skaile add\` needs the publisher), ${drop}`
+      };
+    }
+    const fix = (await this.unresolvedFixes([ref])).get(ref);
+    if (fix) {
+      const register = fix.replace(/, or drop the dependency with `skaile remove [^`]*`$/, "");
+      return {
+        lead: "no agent was added for it, and `skaile add` cannot resolve it",
+        advice: `${register}, ${drop}`
+      };
+    }
+    return {
+      lead: "no registered library or source holds it",
+      advice: `register the library that holds it with \`skaile library init <name> --path <dir>\`, ${drop}`
+    };
+  }
+  /** @deprecated Use `(await projectState()).gaps`; removed in the next major. */
+  async lockGaps() {
+    return (await this.projectState()).gaps;
+  }
+  /**
+   * The {@link ProjectState} gaps that name `ref`: as the gap's own ref, or as the asset
+   * whose requirement is unmet. A ref without a publisher matches any publisher.
+   *
+   * @param ref - Asset ref in `kind:name` or `kind:@publisher/name` form.
+   */
+  async gapsOf(ref) {
+    const want = parseRefTolerant(ref);
+    if (!want) return [];
+    const names = (gapRef) => {
+      const p = parseRefTolerant(gapRef);
+      return p !== null && p.kind === want.kind && p.name === want.name && (!want.publisher || !p.publisher || p.publisher === want.publisher);
+    };
+    return (await this.projectState()).gaps.filter(
+      (g) => names(g.ref) || g.asset && names(g.asset)
+    );
+  }
+  /**
+   * Locked library assets whose library cannot supply them: the library is not registered
+   * (renamed or removed) or no longer holds the asset. Another library holding it makes the
+   * gap fixable by `skaile install` (it re-locks); otherwise the user registers the library
+   * again or drops the dependency.
+   *
+   * @param named - `kind:name` identities already reported; they are skipped.
+   */
+  async libraryOriginGaps(named) {
+    const locked = Object.entries(this.tryReadLock()?.assets ?? {}).filter(
+      ([, e]) => e.library !== void 0 && !e.library.installed
+    );
+    if (locked.length === 0) return [];
+    const snap = await this.loadLibraryIndex();
+    const scans = /* @__PURE__ */ new Map();
+    const diskHashes = /* @__PURE__ */ new Map();
+    const gaps = [];
+    for (const [key, entry] of locked) {
+      const origin = entry.library;
+      const { publisher, kind, name } = parseCanonicalLockKey(key);
+      if (!publisher || !kind || !name || named.has(`${kind}:${name}`)) continue;
+      const ref = `${kind}:@${publisher}/${name}`;
+      const lookup = this.lockedLibrary(origin, snap);
+      const libPath = lookup.state === "ok" ? lookup.path : null;
+      if (lookup.state === "ok" && libPath) {
+        const scanKey = `${libPath}\0${publisher}`;
+        let scanned = scans.get(scanKey);
+        if (!scanned) {
+          scanned = await scanDirectory(libPath, publisher, { knownKinds: this.knownKinds });
+          scans.set(scanKey, scanned);
+        }
+        const found = scanned.find((x) => x.kind === kind && x.name === name);
+        if (found) {
+          const onDisk = origin.sha256 ? libraryDiskHashes(libPath, diskHashes, this.registry).get(`${kind}:${name}`) : void 0;
+          if (onDisk !== void 0 && onDisk !== origin.sha256) {
+            const diskVersion = found.version || newestLibraryDef(snap, lookup.name, { kind, publisher, name })?.version;
+            if (!diskVersion || !gt(coerceVersion(diskVersion), coerceVersion(origin.version))) {
+              const reason2 = `is locked, but library "${lookup.name}" content changed since lock \u2014 or the lock predates the one shared asset hash; run \`skaile install\` to re-lock it`;
+              gaps.push({ type: "content", ref, reason: reason2, message: `${ref} ${reason2}` });
+            }
+          }
+          continue;
+        }
+      }
+      if (lookup.state === "dir-missing") {
+        const reason2 = `is locked, but ${lockedLibraryProblem(lookup, origin, ref)}`;
+        gaps.push({ type: "library", ref, reason: reason2, message: `${ref} ${reason2}`, manualFix: true });
+        continue;
+      }
+      if (lookup.state === "unregistered") {
+        const reason2 = `is locked, but library "${origin.name}" is not registered (renamed or removed?) \u2014 ${unregisteredLibraryFix(origin, ref)}`;
+        gaps.push({ type: "library", ref, reason: reason2, message: `${ref} ${reason2}`, manualFix: true });
+        continue;
+      }
+      const heldElsewhere = (await this.resolveLibraryEntries([ref], { quiet: true })).resolved.size > 0;
+      if (heldElsewhere) {
+        const reason2 = `is locked, but library "${lookup.name}" no longer holds it \u2014 run \`skaile install\` to re-lock it against the library that holds it now`;
+        gaps.push({ type: "library", ref, reason: reason2, message: `${ref} ${reason2}` });
+        continue;
+      }
+      const reason = `is locked, but library "${lookup.name}" no longer holds it \u2014 restore it there, or drop the dependency with \`skaile remove ${ref}\``;
+      gaps.push({ type: "library", ref, reason, message: `${ref} ${reason}`, manualFix: true });
+    }
+    return gaps;
+  }
+  /**
+   * The {@link RestoredAsset} rows for the drifted copies (see {@link lockedCopyDrift}) a
+   * deploy just wrote again: those whose ref is among the `deployed` canonical refs.
+   */
+  restoredCopies(drifts, deployed) {
+    const rewritten = new Set(deployed.map((d) => d.split("#")[0]));
+    const out = [];
+    for (const d of drifts) {
+      if (!rewritten.has(d.ref)) continue;
+      const { kind, name } = parseCanonicalLockKey(d.key);
+      const component = kind ? this.installTarget(kind) : void 0;
+      if (!kind || !name || !component) continue;
+      const dir = relative(
+        this.projectDir,
+        deployedDir(component, name, this.driverTarget, this.global, this.projectDir)
+      ).split(sep).join("/");
+      out.push({
+        ref: d.key,
+        restored: d.modified.map((f) => `${dir}/${f}`),
+        removed: d.extra.map((f) => `${dir}/${f}`)
+      });
+    }
+    return out;
+  }
+  /**
+   * Locked assets whose deployed copy differs from the bytes the lock covers: a file edited by
+   * hand, or a file the asset does not ship. One row per asset, `ref` being `kind:@publisher/name`
+   * and `key` its lock key. The one comparison behind the `modified` gap and the `Restored` lines
+   * of `install`.
+   *
+   * - A library-origin asset is compared with its library's files, but only while those equal the
+   *   locked hash (changed library content is the `content` gap's business), both modified and
+   *   extra files.
+   * - A source asset is compared with the per-file hashes the lock records (modified files only:
+   *   the lock lists what the source covers, not what the deploy copies).
+   *
+   * An agent (rendered, not copied), a `--link` deploy, an asset with a configured patch, and a
+   * copy that is missing are not compared: other gaps cover them. Project mode only.
+   */
+  async lockedCopyDrift() {
+    if (this.global) return [];
+    const lock = this.tryReadLock();
+    if (!lock) return [];
+    const { patches } = this.loadConfig();
+    const out = [];
+    const deployOpts = {
+      registry: this.registry,
+      driverTarget: this.driverTarget,
+      global: this.global,
+      cwd: this.projectDir
+    };
+    const refOf = (key) => {
+      const { kind, publisher, name } = parseCanonicalLockKey(key);
+      return publisher ? `${kind}:@${publisher}/${name}` : `${kind}:${name}`;
+    };
+    const keyOf = /* @__PURE__ */ new Map();
+    for (const key of Object.keys(lock.assets)) keyOf.set(refOf(key), key);
+    const { entries } = await this.restoreLibraryLockEntries(lock);
+    for (const e of entries) {
+      if (patches[`${e.kind}:${e.name}`]) continue;
+      const drift = deployedAssetDrift(e, deployOpts);
+      if (!drift || drift.modified.length === 0 && drift.extra.length === 0) continue;
+      const ref = `${e.kind}:@${(e.publisher ?? "").replace(/^@/, "")}/${e.name}`;
+      out.push({ ref, key: keyOf.get(ref) ?? ref, ...drift, library: true });
+    }
+    for (const [key, entry] of Object.entries(lock.assets)) {
+      if (!entry.source || entry.files.length === 0) continue;
+      const { kind, name } = parseCanonicalLockKey(key);
+      const component = kind ? this.installTarget(kind) : void 0;
+      if (!kind || !name || !component || component === "agent") continue;
+      if (patches[`${kind}:${name}`]) continue;
+      const dest = deployedDir(component, name, this.driverTarget, this.global, this.projectDir);
+      try {
+        const deployed = lstatSync(dest);
+        if (deployed.isSymbolicLink() || !deployed.isDirectory()) continue;
+      } catch {
+        continue;
+      }
+      const dirs = entry.files.map(
+        (f) => posix.dirname(f.path).split("/").filter((s) => s !== ".")
+      );
+      let common = dirs[0] ?? [];
+      for (const d of dirs.slice(1)) {
+        let i = 0;
+        while (i < common.length && i < d.length && common[i] === d[i]) i++;
+        common = common.slice(0, i);
+      }
+      const prefix = common.length > 0 ? `${common.join("/")}/` : "";
+      const modified = [];
+      for (const f of entry.files) {
+        const rel = f.path.startsWith(prefix) ? f.path.slice(prefix.length) : f.path;
+        const deployedFile = join(dest, rel);
+        if (!existsSync(deployedFile)) continue;
+        try {
+          if (computeHash(deployedFile) !== f.sha256) modified.push(rel);
+        } catch {
+          modified.push(rel);
+        }
+      }
+      if (modified.length > 0)
+        out.push({ ref: refOf(key), key, modified, extra: [], library: false });
+    }
+    return out;
+  }
+  /**
+   * Locked assets (declared or required by one) whose deployed copy is gone: `skaile install`
+   * restores them. Same deployability rule as {@link AssetManager.listDeclared}'s `drift`.
+   *
+   * @param named - `kind:name` identities already reported; they are skipped.
+   */
+  undeployedLockGaps(lock, named) {
+    const gaps = [];
+    for (const [key, entry] of Object.entries(lock?.assets ?? {})) {
+      if (entry.library?.installed) continue;
+      const { publisher, kind, name } = parseCanonicalLockKey(key);
+      const component = kind ? this.installTarget(kind) : void 0;
+      if (!kind || !name || !component || named.has(`${kind}:${name}`)) continue;
+      if (isDeployed(component, name, this.driverTarget, this.global, this.projectDir)) continue;
+      const ref = publisher ? `${kind}:@${publisher}/${name}` : `${kind}:${name}`;
+      const reason = "is locked but its deployed copy is missing \u2014 run `skaile install`";
+      gaps.push({ type: "drift", ref, reason, message: `${ref} ${reason}` });
+    }
+    return gaps;
+  }
+  /**
+   * The `skaile.yaml` side of {@link AssetManager.projectState}: declared refs that do not
+   * parse, never resolved into the lock, are not materialized, or contradict a `#pin`.
+   * A project with no (or an unreadable) `skaile.yaml` has no declared set to reconcile.
+   *
+   * @param requirements - What {@link AssetManager.doctor} found; a declared preset whose
+   *   items it already named needs no second line.
+   * @param named - `kind:name` identities already reported; a declared asset among them
+   *   needs no `drift` line.
+   */
+  async declaredGaps(requirements, named) {
+    let declared;
     try {
       declared = await this.listDeclared();
     } catch {
-      return gaps;
+      return [];
     }
+    const 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)) {
+      if (d.kind === "preset" && requirements.some((i) => i.assetKind === "preset" && i.assetName === d.name)) {
         continue;
       }
       let gap;
@@ -3517,19 +4679,41 @@ var AssetManager = class {
           reason: "is not a valid asset ref (expected kind:@<publisher>/<name>#<version>)"
         };
       } else if (d.state === "drift") {
+        if (named.has(`${d.kind}:${d.name}`)) continue;
         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`"
-        };
+        if (hint) {
+          gap = {
+            type: "declared",
+            reason: `is declared but does not resolve${hint}`,
+            manualFix: true
+          };
+        } else if (await this.declaredRefResolvable(d.ref)) {
+          gap = { type: "declared", reason: "is declared but not locked \u2014 run `skaile install`" };
+        } else {
+          gap = {
+            type: "declared",
+            reason: declaredNoHolderReason(d.ref),
+            manualFix: true
+          };
+        }
       } else {
         const want = parseAssetRef(d.ref);
-        if (!want.pin || want.kind === "preset") continue;
+        if (want.kind === "preset") {
+          if (this.presetRecorded(want) || await this.info(d.ref) !== null) continue;
+          gap = await this.declaredRefResolvable(d.ref) ? { type: "declared", reason: "is declared but not locked \u2014 run `skaile install`" } : {
+            type: "declared",
+            reason: declaredNoHolderReason(d.ref),
+            manualFix: true
+          };
+          gaps.push({ ...gap, ref: d.ref, message: `${d.ref} ${gap.reason}` });
+          continue;
+        }
+        if (!want.pin) 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)
         );
@@ -3544,6 +4728,22 @@ var AssetManager = class {
     }
     return gaps;
   }
+  /** Whether the lock's `presets` slice records `want` (kind, name and, when both carry one, publisher). */
+  presetRecorded(want) {
+    return (this.tryReadLock()?.presets ?? []).some((ref) => {
+      const p = parseRefTolerant(ref);
+      return p !== null && p.kind === want.kind && p.name === want.name && (!want.publisher || !p.publisher || p.publisher === want.publisher);
+    });
+  }
+  /**
+   * Whether `skaile install` can resolve a declared ref: a source or library holds it, or the
+   * project declares a store that may. The global catalog is not asked: a check never goes
+   * to the network.
+   */
+  async declaredRefResolvable(ref) {
+    if (await this.info(ref) !== null) return true;
+    return this.loadConfig().stores.length > 0;
+  }
   /**
    * Items of each declared `preset:` dependency that the lock does not cover.
    *
@@ -3810,6 +5010,54 @@ var AssetManager = class {
     writeFileSync(configPath, stringify(raw, { lineWidth: 120 }));
     return true;
   }
+  /**
+   * Drop the agent instances of `skaile.yaml` (`agents.<id>`, or the `agent.definition`
+   * default) whose `ref` binds to `target`, and the native agent files an install rendered for
+   * them. Only an `agent` target has bindings; project mode only. A `ref` without a publisher
+   * matches any publisher, and a pin is ignored.
+   *
+   * @returns `true` when a binding was removed.
+   */
+  removeAgentBindings(target) {
+    if (this.global || target.kind !== "agent") return false;
+    const configPath = join(this.stateRoot, "skaile.yaml");
+    if (!existsSync(configPath)) return false;
+    let raw;
+    try {
+      raw = parse(readFileSync(configPath, "utf8"));
+    } catch {
+      return false;
+    }
+    if (!raw || typeof raw !== "object") return false;
+    const wantPub = target.publisher?.replace(/^@/, "");
+    const binds = (ref) => {
+      const p = typeof ref === "string" ? parseRefTolerant(ref) : null;
+      if (!p || p.kind !== "agent" || p.name !== target.name) return false;
+      const havePub = p.publisher?.replace(/^@/, "");
+      return wantPub === void 0 || havePub === void 0 || havePub === wantPub;
+    };
+    const ids = [];
+    const instances = raw.agents;
+    if (instances && typeof instances === "object") {
+      for (const [id, instance] of Object.entries(instances)) {
+        if (!binds(instance?.ref)) continue;
+        ids.push(id);
+        delete instances[id];
+      }
+      if (Object.keys(instances).length === 0) delete raw.agents;
+    }
+    if (raw.agent && typeof raw.agent === "object" && binds(raw.agent.definition)) {
+      ids.push(DEFAULT_AGENT_INSTANCE_ID);
+      delete raw.agent.definition;
+      if (Object.keys(raw.agent).length === 0) delete raw.agent;
+    }
+    if (ids.length === 0) return false;
+    writeFileSync(configPath, stringify(raw, { lineWidth: 120 }));
+    for (const driverTarget of this.targetHarnesses()) {
+      removeAgentInstanceRenderings({ projectDir: this.projectDir, driverTarget, ids });
+    }
+    return true;
+  }
   resolveRepoDir(decl, name) {
     const links = readLinks(this.projectDir);
     if (links[name]) {
@@ -3828,5 +5076,5 @@ var AssetManager = class {
 };
 
 export { AssetManager, FACTORY_SOURCE_URL, MissingManifestError, installAgentInstances, normalizeRepoUrl, parseCanonicalLockKey, parseRefTolerant, renderMcpServerConfig, softDepName };
-//# sourceMappingURL=chunk-IMKSM5NL.js.map
-//# sourceMappingURL=chunk-IMKSM5NL.js.map
+//# sourceMappingURL=chunk-DZMNFCWB.js.map
+//# sourceMappingURL=chunk-DZMNFCWB.js.map