@skaile/workspaces 5.17.0 → 5.18.0

package/dist/{chunk-W44KA24A.js → chunk-TDQ2ERCM.js}

@@ -1,19 +1,20 @@
-import { unregisteredLibraryNames, renamedLibraryName, resolveConfig, RemoteCatalogSource, OfflineError, describeCatalogError, CatalogHttpError, scanUnlistedAssets, storeManifestFile, missingLibraryDirMessage } from './chunk-D3PU3C6F.js';
-import { SEMVER_RE, invalidSemverMessage, flowFileNameError, readManifestSourceConfig, discoverAssetsInTree, isManifestMode } from './chunk-ES6ARJPQ.js';
-import { installTargetOf, readKeptLegacyCopies, writeKeptLegacyCopies, canonicalEntryRef, diffDeployedAgent, deployedAssetDrift, deployAll, removeAsset, createScaffold, installAgent } from './chunk-FSLVMZXR.js';
+import { unregisteredLibraryNames, renamedLibraryName, resolveConfig, RemoteCatalogSource, OfflineError, describeCatalogError, CatalogHttpError, scanUnlistedAssets, storeManifestFile, missingLibraryDirMessage } from './chunk-VKPBUPH7.js';
+import { SEMVER_RE, invalidSemverMessage, flowFileNameError, readManifestSourceConfig, discoverAssetsInTree, isManifestMode } from './chunk-HPVMTX6M.js';
+import { parseFlowDefinition } from './chunk-X3RMRJNR.js';
+import { installTargetOf, readKeptLegacyCopies, writeKeptLegacyCopies, canonicalEntryRef, diffDeployedAgent, deployedAssetDrift, assertNoLibrarySymlinks, deployAll, removeAsset, createScaffold, installAgent } from './chunk-YZ3N7IUU.js';
 import { appendHistory, getRecentHistory, clearHistory } from './chunk-KTBKW2FI.js';
 import { commitChanges } from './chunk-UQ6LFBPZ.js';
-import { driverTargetSupportsAgents, CODEX_IDENTITY_DIR } from './chunk-6GSE63K2.js';
-import { isScaffoldBody } from './chunk-YK3XLEQJ.js';
-import { resolveConfiguredDriverTarget, GLOBAL_INSTALL_DIR_NAME, resolveLibraryDir, buildLibraryLockEntries, computeHash, buildLockFile, writeLock, readLock, verifyLock, mergeLockFile, resyncLockSources, extractForPatch, generatePatch, savePatch, applyPatch, LOCK_SCHEMA_VERSION } from './chunk-PIC23DDE.js';
-import { resolveRuntimeAssets, factoryAssetRoots } from './chunk-5RDZ5JHH.js';
-import { deployedBase, isDeployed, deployedPaths, deployedDir } from './chunk-D54T2F54.js';
-import { resolveSkWorkspaceConfig, effectiveAgentInstances, loadMcpServerDeclarations, resolveGlobalHarnesses, resolveGlobalSkWorkspaceConfig, getGlobalCacheDir, sourceCacheKey, getRepoCommit, matchPin, buildProvenanceIndex, coerceVersion, sourceShortName, readLinks, isCommitOnRemote, resolveAll, agentSourceCacheDir, ensureRepo, scanRepo, SKAILE_YAML_DEFAULT, checkRepoStatus, resolveAgentDefinitionDir, resolveAsset, MAX_PRESET_DEPTH, PresetDepthError, DEFAULT_AGENT_INSTANCE_ID } from './chunk-ZVZTCDUN.js';
+import { driverTargetSupportsAgents, CODEX_IDENTITY_DIR } from './chunk-SRNCN4X2.js';
+import { isScaffoldBody, isScaffoldDescription } from './chunk-CKNIYIV2.js';
+import { resolveConfiguredDriverTarget, GLOBAL_INSTALL_DIR_NAME, resolveLibraryDir, buildLibraryLockEntries, computeHash, buildLockFile, writeLock, readLock, verifyLock, mergeLockFile, resyncLockSources, extractForPatch, generatePatch, savePatch, applyPatch, LOCK_SCHEMA_VERSION } from './chunk-T2TQAH2X.js';
+import { resolveRuntimeAssets, factoryAssetRoots } from './chunk-KC6HGWXN.js';
+import { deployedBase, isDeployed, deployedPaths, deployedDir } from './chunk-5TBFN46Z.js';
+import { resolveSkWorkspaceConfig, effectiveAgentInstances, loadMcpServerDeclarations, resolveGlobalHarnesses, resolveGlobalSkWorkspaceConfig, getGlobalCacheDir, sourceCacheKey, getRepoCommit, matchPin, buildProvenanceIndex, coerceVersion, sourceShortName, readLinks, isCommitOnRemote, resolveAll, agentSourceCacheDir, ensureRepo, scanRepo, SKAILE_YAML_DEFAULT, checkRepoStatus, resolveAgentDefinitionDir, resolveAsset, MAX_PRESET_DEPTH, PresetDepthError, DEFAULT_AGENT_INSTANCE_ID } from './chunk-2NOLF7B2.js';
 import { globalSkaileDir, globalCacheRoot, migrateLegacyDir } from './chunk-L5VSIPQD.js';
 import { DRIVER_TARGETS, SUPPORTED_DRIVER_TARGETS } from './chunk-IG5LZ3WU.js';
-import { listAssetFiles, loadSkPublishManifest } from './chunk-H7R7R5BN.js';
-import { scanDirectory, parseFrontmatter, parseRequires, dedupeRequirements, readAssetBody } from './chunk-YW2BNDSE.js';
-import { parseAssetRef, parseAssetRefLoose, assetRefToStr, slugifyAssetName, depToStr, parseDep } from './chunk-FT4ZHLYR.js';
+import { listAssetFiles, loadSkPublishManifest, isNonAssetDir, isNonAssetFile } from './chunk-CKICWXMU.js';
+import { scanDirectory, parseFrontmatter, parseRequires, dedupeRequirements, readAssetBody } from './chunk-GOCWM7FN.js';
+import { parseAssetRef, parseAssetRefLoose, assetRefToStr, slugifyAssetName, depToStr, parseDep } from './chunk-WDXZA7QW.js';
 import { spawnSync } from 'child_process';
 import { existsSync, rmSync, readFileSync, readdirSync, lstatSync, writeFileSync, unlinkSync, mkdirSync } from 'fs';
 import path, { resolve, dirname, sep, join, relative, posix } from 'path';
@@ -279,17 +280,33 @@ async function markEsmPayload(dir, dest, bytes) {
   } catch {
   }
 }
+function rawPayloadDest(payload) {
+  if (payload.dest !== void 0) return payload.dest;
+  try {
+    return decodeSegment(new URL(payload.url).pathname.split("/").pop() ?? "");
+  } catch {
+    return void 0;
+  }
+}
+async function extraPayloadEntries(dir, dest) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  if (entries.some((e) => e.name === "MCP.md")) return [];
+  return entries.filter((e) => e.name !== dest && e.name !== "package.json").filter((e) => !(e.isDirectory() ? isNonAssetDir(e.name) : isNonAssetFile(e.name))).map((e) => e.name).sort();
+}
+async function pruneExtraPayloadFiles(dir, dest) {
+  for (const name of await extraPayloadEntries(dir, dest)) {
+    await fs.rm(path.join(dir, name), { recursive: true, force: true });
+  }
+}
 async function ensurePayload(projectDir, decl, fetchPayload) {
   const payload = decl.payload;
   if (!payload) return void 0;
-  let dest = payload.dest;
-  if (dest === void 0) {
-    try {
-      dest = decodeSegment(new URL(payload.url).pathname.split("/").pop() ?? "");
-    } catch {
-      dest = void 0;
-    }
-  }
+  const dest = rawPayloadDest(payload);
   if (dest === void 0 || !isPlainName(dest)) {
     return `payload ${payload.url} has no usable file name (${JSON.stringify(dest ?? "")}): a plain file name is required`;
   }
@@ -304,6 +321,7 @@ async function ensurePayload(projectDir, decl, fetchPayload) {
   }
   if (existing && sha(existing) === payload.sha256) {
     await markEsmPayload(dir, dest, existing);
+    await pruneExtraPayloadFiles(dir, dest);
     return void 0;
   }
   let bytes;
@@ -326,6 +344,7 @@ async function ensurePayload(projectDir, decl, fetchPayload) {
     return `payload ${dest} could not be written: ${err instanceof Error ? err.message : String(err)}`;
   }
   await markEsmPayload(dir, dest, bytes);
+  await pruneExtraPayloadFiles(dir, dest);
   return void 0;
 }
 async function removePayloadDir(projectDir, id) {
@@ -444,6 +463,104 @@ function mergeServers(existing, renderable, managedIds, warn, configLabel) {
   }
   return { next, owned, removed };
 }
+function canonicalJson(value) {
+  return JSON.stringify(
+    value,
+    (_key, v) => v && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) : v
+  );
+}
+async function mcpServerDrift(projectDir, driverTarget, opts = {}) {
+  const relConfig = TARGET_MCP_CONFIG[driverTarget];
+  if (!relConfig) return [];
+  const declarations = opts.declarations ?? await loadMcpServerDeclarations(projectDir);
+  const skippedNow = await readNotedSkips(projectDir, driverTarget);
+  const managed = new Set(await readManagedIds(projectDir, driverTarget));
+  let servers = {};
+  try {
+    const file = await readJsonStrict(path.join(projectDir, relConfig));
+    servers = file?.mcpServers ?? {};
+  } catch {
+    return [];
+  }
+  const rel = (p) => path.relative(projectDir, p).split(path.sep).join("/");
+  const out = [];
+  for (const decl of declarations) {
+    if (skippedNow[decl.id] !== void 0 || skipReason(decl)) continue;
+    const drift = { id: decl.id, missing: [], modified: [], extra: [] };
+    const dest = decl.payload ? rawPayloadDest(decl.payload) : void 0;
+    const dir = payloadDir(projectDir, decl.id);
+    if (decl.payload && dest !== void 0 && isPlainName(dest) && dir) {
+      const file = rel(path.join(dir, dest));
+      let actual;
+      try {
+        actual = createHash("sha256").update(await fs.readFile(path.join(dir, dest))).digest("hex");
+      } catch {
+      }
+      if (actual === void 0) {
+        drift.missing.push(file);
+        drift.payload = { file, pinned: decl.payload.sha256 };
+      } else if (actual !== decl.payload.sha256) {
+        drift.modified.push(file);
+        drift.payload = { file, pinned: decl.payload.sha256, actual };
+      }
+      for (const name of await extraPayloadEntries(dir, dest)) {
+        drift.extra.push(rel(path.join(dir, name)));
+      }
+    }
+    const owned = managed.has(decl.id);
+    const lockedHere = opts.locked?.has(decl.id) || opts.locked?.has(decl.id.split("/").pop() ?? "");
+    if (owned || lockedHere) {
+      const expected = JSON.parse(JSON.stringify(buildEntry(decl, projectDir)));
+      const actual = Object.hasOwn(servers, decl.id) ? servers[decl.id] : void 0;
+      const label = `${relConfig} entry "${decl.id}"`;
+      if (actual === void 0) {
+        drift.missing.push(label);
+        drift.entry = { expected, actual };
+      } else if (owned && canonicalJson(actual) !== canonicalJson(expected)) {
+        drift.modified.push(label);
+        drift.entry = { expected, actual };
+      }
+    }
+    if (drift.missing.length + drift.modified.length + drift.extra.length > 0) out.push(drift);
+  }
+  return out;
+}
+function jsonLineDiff(from, to) {
+  const lines = (v) => v === void 0 ? [] : JSON.stringify(v, null, 2).split("\n");
+  const a = lines(from);
+  const b = lines(to);
+  return [
+    ...a.filter((l) => !b.includes(l)).map((l) => `-${l}`),
+    ...b.filter((l) => !a.includes(l)).map((l) => `+${l}`)
+  ];
+}
+function mcpDriftDiff(drift) {
+  const out = [];
+  if (drift.payload) {
+    const { file, pinned, actual } = drift.payload;
+    out.push(`--- ${file} (deployed)`, `+++ ${file} (pinned)`);
+    out.push(
+      actual === void 0 ? "-(file is missing)" : `-sha256 ${actual}`,
+      `+sha256 ${pinned}`
+    );
+  }
+  for (const f of drift.extra)
+    out.push(`--- ${f} (deployed)`, "+++ /dev/null (not part of the asset)");
+  if (drift.entry) {
+    const file = drift.missing.concat(drift.modified).find((f) => f.includes(" entry ")) ?? "MCP config entry";
+    out.push(`--- ${file} (deployed)`, `+++ ${file} (declared)`);
+    out.push(...jsonLineDiff(drift.entry.actual, drift.entry.expected));
+  }
+  return `${out.join("\n")}
+`;
+}
+var readSkippedMcpServers = readNotedSkips;
+function unsetRequiredFields(decl) {
+  return (decl.fields ?? []).filter((f) => f.required === true && f.default === void 0).filter((f) => !(decl.env && Object.hasOwn(decl.env, f.key))).map((f) => f.key);
+}
+function requiredFieldsAdvice(id, keys) {
+  return `needs ${keys.join(", ")} (required): set it with an mcp_servers entry (id: ${id}, env: \u2026) in skaile.yaml`;
+}
 async function renderMcpServerConfig(projectDir, driverTarget, opts) {
   const warn = opts?.warn ?? ((m) => console.warn(`skaile: ${m}`));
   const relConfig = TARGET_MCP_CONFIG[driverTarget];
@@ -480,6 +597,11 @@ async function renderMcpServerConfig(projectDir, driverTarget, opts) {
     relConfig
   );
   for (const id of removed) await removePayloadDir(projectDir, id);
+  for (const decl of declarations) {
+    if (!owned.includes(decl.id) || managedIds.includes(decl.id)) continue;
+    const unset = unsetRequiredFields(decl);
+    if (unset.length > 0) warn(`MCP server "${decl.id}" ${requiredFieldsAdvice(decl.id, unset)}`);
+  }
   const ledgerStale = JSON.stringify(owned) !== JSON.stringify(managedIds);
   if (ledgerStale) await writeManagedIds(projectDir, driverTarget, owned);
   if (Object.keys(next).length === 0 && !existingFile) {
@@ -583,6 +705,7 @@ function lockedAssetFiles(kind, files) {
   });
 }
 var GITHUB_REPO_URL = /github\.com[/:]/i;
+var GIT_URL = /^(?:[a-z][a-z0-9+.-]*:\/\/|[\w.-]+@[\w.-]+:)/i;
 function indexLockByKindName(lock) {
   const lockByKindName = /* @__PURE__ */ new Map();
   for (const [key, entry] of Object.entries(lock?.assets ?? {})) {
@@ -763,6 +886,11 @@ function scaffoldBodyRefs(entries, deployed) {
   }
   return out;
 }
+function scaffoldDescriptionRefs(entries, deployed) {
+  return entries.filter(
+    (e) => deployed.includes(canonicalEntryRef(e)) && isScaffoldDescription(e.kind, e.description)
+  ).map((e) => canonicalEntryRef(e));
+}
 function libraryEntryDepRefs(e) {
   const publisher = e.publisher ?? "";
   const refs = /* @__PURE__ */ new Set();
@@ -775,6 +903,30 @@ function libraryEntryDepRefs(e) {
   }
   return [...refs];
 }
+function assertFlowsLoad(entries) {
+  for (const e of entries) {
+    if (e.kind !== "flow" || !e.source) continue;
+    let file = e.source;
+    let authored;
+    try {
+      if (lstatSync(file).isDirectory()) {
+        const inside = [`${e.name}.flow.yaml`, `${e.name}.flow.yml`, `${e.name}.flow.json`].map((n) => join(file, n)).find((p) => existsSync(p));
+        if (!inside) continue;
+        file = inside;
+      }
+      const raw = readFileSync(file, "utf8");
+      authored = /\.json$/i.test(file) ? JSON.parse(raw) : parse(raw);
+    } catch {
+      continue;
+    }
+    const parsed = parseFlowDefinition(authored);
+    if (parsed.ok) continue;
+    const details = parsed.errors.slice(0, 3).map((issue) => `${issue.path || "<root>"}: ${issue.message}`).join("; ");
+    throw new Error(
+      `${canonicalEntryRef(e).split("#")[0]} is not a flow the flow engine can load (${details}) \u2014 nothing was added; fix the flow in its library or source`
+    );
+  }
+}
 function refIdentity(ref) {
   try {
     const p = parseAssetRef(ref);
@@ -853,6 +1005,12 @@ function parseRefTolerant(ref) {
     return { kind, name, publisher: void 0 };
   }
 }
+var LibraryEntryError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LibraryEntryError";
+  }
+};
 function keptLockEntries(prev, missing) {
   const out = { assets: {}, sources: [], refs: /* @__PURE__ */ new Set(), keysByRef: /* @__PURE__ */ new Map() };
   if (!prev) return out;
@@ -892,6 +1050,7 @@ function relockedRefs(prev, next) {
   if (!prev) return [];
   const fingerprint = (e, key) => [
     e.library?.version ?? "",
+    e.library && !e.library.installed ? e.library.name : "",
     e.library?.sha256 ?? e.sha256,
     key.includes("#0.0.0-sha.") ? "" : e.source?.commit ?? ""
   ].join("\0");
@@ -943,6 +1102,18 @@ 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 libraryCollisionMessage(c) {
+  return `${c.key} exists in ${c.libraries.length} libraries: ${c.held.join(", ")} \u2014 using ${c.chosen} (${c.version}). Highest version wins; an equal version goes to the default library, then by name. ` + (c.differing.length > 0 ? `Same version, different content: ${c.chosen} and ${c.differing.join(", ")} hold ${c.version} with different bytes. ` : "") + `Pin a version (${c.key}#<version>) to choose another.`;
+}
+function libraryCollisionSummary(all) {
+  const libraries = [...new Set(all.flatMap((c) => c.libraries))].sort();
+  const used = /* @__PURE__ */ new Map();
+  for (const c of all) used.set(c.chosen, (used.get(c.chosen) ?? 0) + 1);
+  const usedText = [...used].sort((a, b) => b[1] - a[1]).map(([lib, n]) => `${lib} for ${n}`);
+  const short = (key) => key.slice(key.lastIndexOf("/") + 1);
+  const differing = all.filter((c) => c.differing.length > 0).map((c) => short(c.key));
+  return `${all.length} assets exist in several libraries (${libraries.join(", ")}); using ${usedText.join(", ")}. Highest version wins; an equal version goes to the default library, then by name. ` + (differing.length > 0 ? `Same version, different bytes for: ${differing.join(", ")}. ` : "") + "Pin a version (<ref>#<version>) to choose another; `--verbose` lists each asset.";
+}
 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)}`;
 }
@@ -1087,6 +1258,8 @@ var AssetManager = class {
   indexPathOverride;
   /** Sink for cross-library collision warnings; else `console.warn`. */
   onLibraryCollision;
+  /** Print every colliding asset's full message instead of one summary ({@link AssetManagerOptions.verboseCollisions}). */
+  verboseCollisions;
   /** Store URLs whose failed version lookup was already reported (one warning per URL). */
   warnedStoreVersionLookups = /* @__PURE__ */ new Set();
   /** Stores a lookup could not reach (store URL -> one line why); `add` reports them instead of "not found". */
@@ -1113,6 +1286,7 @@ var AssetManager = class {
     this.catalogUrlOverride = opts.catalogUrl;
     this.indexPathOverride = opts.indexPath;
     this.onLibraryCollision = opts.onLibraryCollision;
+    this.verboseCollisions = opts.verboseCollisions ?? false;
   }
   /** Registered kind names — the `knownKinds` argument of the manifest scanners. */
   get knownKinds() {
@@ -1317,17 +1491,57 @@ 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, onSkippedSymlink, onEnvFile) {
+  deployOptsFor(target, link, onSecretFile) {
     return {
       registry: this.registry,
       driverTarget: target,
       global: this.global,
       cwd: this.projectDir,
       link: link === true,
-      ...onSkippedSymlink ? { onSkippedSymlink: (entry, p) => onSkippedSymlink(canonicalEntryRef(entry), p) } : {},
-      ...onEnvFile ? { onEnvFile: (entry, p) => onEnvFile(canonicalEntryRef(entry), p) } : {}
+      ...onSecretFile ? { onSecretFile: (entry, p) => onSecretFile(canonicalEntryRef(entry), p) } : {}
     };
   }
+  /**
+   * Names of the `mcp-server` assets the lock holds (the declaration ids, unscoped); a missing
+   * `.mcp.json` entry of one counts as drift even before skaile owned it.
+   */
+  lockedMcpNames() {
+    return new Set(
+      Object.keys(this.tryReadLock()?.assets ?? {}).map(parseCanonicalLockKey).filter((id) => id.kind === "mcp-server" && id.name).map((id) => id.name)
+    );
+  }
+  /**
+   * The payloads and managed `.mcp.json` entries of the project's **locked** `mcp-server`
+   * assets that differ from what the declarations render (see {@link mcpServerDrift}), one row
+   * per server, named by the lock identity `mcp-server:@publisher/name`; `key` is the lock key.
+   * An `mcp_servers:` entry of `skaile.yaml` is configuration, not a locked asset: it has no
+   * row. Empty for a global manager and for a project that locks no `mcp-server`.
+   */
+  async mcpDriftRows() {
+    if (this.global) return [];
+    const locked = this.lockedMcpNames();
+    if (locked.size === 0) return [];
+    let rows;
+    try {
+      rows = await mcpServerDrift(this.projectDir, this.driverTarget, { locked });
+    } catch {
+      return [];
+    }
+    const keys = Object.keys(this.tryReadLock()?.assets ?? {});
+    const out = [];
+    for (const drift of rows) {
+      const name = unscopedName(drift.id);
+      const key = keys.find((k) => {
+        const id = parseCanonicalLockKey(k);
+        return id.kind === "mcp-server" && id.name === name;
+      });
+      if (!key) continue;
+      const publisher = parseCanonicalLockKey(key).publisher;
+      const ref = publisher ? `mcp-server:@${publisher}/${name}` : `mcp-server:${name}`;
+      out.push({ ref, key, drift });
+    }
+    return out;
+  }
   /**
    * Render the project's declared MCP servers into the driver target's own
    * native MCP config (`<project>/.mcp.json` for `claude-code`), so the coding
@@ -1337,16 +1551,34 @@ var AssetManager = class {
    * write, and the coding agent's user scope is a large user-state file this
    * must not touch. Never fails an install — a render error is warned and
    * swallowed.
+   *
+   * @returns The payload files and config entries the render wrote back (and the files it
+   *   removed) because they had drifted from the declaration: `install` names them, as it does
+   *   a restored skill file.
    */
   async renderDriverMcpConfig() {
-    if (this.global) return;
+    if (this.global) return [];
+    const before = await this.mcpDriftRows();
     try {
       await renderMcpServerConfig(this.projectDir, this.driverTarget);
     } catch (err) {
       console.warn(
         `skaile: could not render MCP config for ${this.driverTarget}: ${err instanceof Error ? err.message : String(err)}`
       );
+      return [];
+    }
+    if (before.length === 0) return [];
+    const after = await this.mcpDriftRows();
+    const restored = [];
+    for (const { ref, key, drift } of before) {
+      const left = after.find((a) => a.ref === ref)?.drift;
+      const stillWrong = /* @__PURE__ */ new Set([...left?.missing ?? [], ...left?.modified ?? []]);
+      const rewritten = [...drift.missing, ...drift.modified].filter((f) => !stillWrong.has(f));
+      const removed = drift.extra.filter((f) => !left?.extra.includes(f));
+      if (rewritten.length > 0 || removed.length > 0)
+        restored.push({ ref: key, restored: rewritten, removed });
     }
+    return restored;
   }
   /**
    * Render every agent instance of `skaile.yaml` into the driver target's native
@@ -1362,16 +1594,21 @@ var AssetManager = class {
         projectDir: this.projectDir,
         driverTarget: this.driverTarget
       });
+      const details = [];
       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}`;
+        if (at < 0) continue;
+        details.push(result.errors[at]);
+        const { lead, advice } = await this.unboundAgentAdvice(u.ref);
+        result.errors[at] = `agent instance "${u.id}" is bound to ${u.ref} but ${lead} \u2014 ${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 } : {}
+        ...result.errors.length > 0 ? { agentInstanceErrors: result.errors } : {},
+        ...details.length > 0 ? { agentInstanceDetails: details } : {}
       };
     } catch (err) {
       console.warn(
@@ -1610,13 +1847,13 @@ var AssetManager = class {
       candidates.sort(libraryPreference(isDefaultLib, prefer));
       const hit = candidates[0];
       if (hit.entry.version && !SEMVER_RE.test(hit.entry.version)) {
-        throw new Error(
+        throw new LibraryEntryError(
           `${canonicalEntryRef(hit.entry)} (library ${hit.library}): ${invalidSemverMessage(hit.entry.version)}. Set a valid version in the asset file and run \`skaile library index ${hit.library}\`.`
         );
       }
       const flowFileError = hit.entry.kind === "flow" && hit.entry.source ? flowFileNameError({ id: hit.entry.name }, hit.entry.source.split(/[\\/]/).pop()) : void 0;
       if (flowFileError) {
-        throw new Error(
+        throw new LibraryEntryError(
           `${canonicalEntryRef(hit.entry)} (library ${hit.library}): ${flowFileError}. Fix it, then run \`skaile library index ${hit.library}\`.`
         );
       }
@@ -1954,7 +2191,11 @@ 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);
+      const lookup = this.lockedLibrary(
+        origin,
+        snap,
+        want.publisher ? { kind: want.kind, publisher: want.publisher, name: want.name } : void 0
+      );
       if (moved?.library && want.publisher) {
         out.set(
           ref,
@@ -1964,6 +2205,8 @@ var AssetManager = class {
         out.set(ref, lockedLibraryProblem(lookup, origin, plain));
       } else if (lookup.state === "unregistered") {
         out.set(ref, unregisteredLibraryFix(origin, plain));
+      } else if (await this.pinNeverHeld(ref, plain, lookup, out)) {
+        continue;
       } else {
         const renamedTo = await this.renamedFlowRef(lookup, want.publisher, want.kind, want.name);
         out.set(
@@ -1974,6 +2217,22 @@ var AssetManager = class {
     }
     return out;
   }
+  /**
+   * A ref pinned to a version its library never held (`#9.9.9`): the thing to change is the pin
+   * in `skaile.yaml`, not the library (p1096). Sets the fix and returns `true` when it applies.
+   */
+  async pinNeverHeld(ref, plain, lookup, out) {
+    const pin = (ref.split(" ")[0] ?? ref).split("#")[1];
+    if (!pin || lookup.state !== "ok") return false;
+    const held = (await this.resolveLibraryEntries([plain], { quiet: true, library: lookup.name })).entries[0];
+    if (!held?.version || held.version === pin) return false;
+    const name = plain.split(/[:/]/).pop() ?? plain;
+    out.set(
+      ref,
+      `Asset not found: ${plain}#${pin} (${name} has version(s): ${held.version}); change the pin in skaile.yaml`
+    );
+    return true;
+  }
   /**
    * The ref a library now holds a flow under when a project still locks it by the slug of the
    * flow's `name:` (5.12.0 named a flow by `name:`; later releases name it by `id:`), or
@@ -1996,20 +2255,58 @@ var AssetManager = class {
   }
   /** Collision messages already printed by this instance (one warning per ref + library set). */
   warnedLibraryCollisions = /* @__PURE__ */ new Set();
+  /**
+   * Collisions of one `add`, held back until {@link flushLibraryCollisions} so a dependency
+   * tree that touches several colliding assets prints one summary, not one line per asset
+   * (p1097). `null` outside an `add`: a collision then warns at once.
+   */
+  collisionBatch = null;
   /**
    * Warn once when `key` is held by more than one library: names every library
    * with its version and the one chosen, so a silent pick can't surprise.
    */
   warnLibraryCollision(key, candidates, chosen, differing = []) {
-    const libraries = new Set(candidates.map((c) => c.library));
-    if (libraries.size < 2) return;
-    const held = candidates.map((c) => `${c.library} (${c.entry.version || "unversioned"})`);
-    const msg = `${key} exists in ${libraries.size} libraries: ${held.join(", ")} \u2014 using ${chosen.library} (${chosen.entry.version || "unversioned"}). Highest version wins; an equal version goes to the default library, then by name. ` + (differing.length > 0 ? `Same version, different content: ${chosen.library} and ${differing.join(", ")} hold ${chosen.entry.version || "unversioned"} with different bytes. ` : "") + `Pin a version (${key}#<version>) to choose another.`;
+    const libraries = [...new Set(candidates.map((c) => c.library))];
+    if (libraries.length < 2) return;
+    const collision = {
+      key,
+      libraries,
+      held: candidates.map((c) => `${c.library} (${c.entry.version || "unversioned"})`),
+      chosen: chosen.library,
+      version: chosen.entry.version || "unversioned",
+      differing
+    };
+    if (this.collisionBatch) {
+      this.collisionBatch.set(key, collision);
+      return;
+    }
+    this.emitLibraryCollision(libraryCollisionMessage(collision), [key]);
+  }
+  /** Print each distinct collision message once; the sink also gets the keys it names. */
+  emitLibraryCollision(msg, keys) {
     if (this.warnedLibraryCollisions.has(msg)) return;
     this.warnedLibraryCollisions.add(msg);
-    if (this.onLibraryCollision) this.onLibraryCollision(msg);
+    if (this.onLibraryCollision) this.onLibraryCollision(msg, keys);
     else console.warn(`skaile: ${msg}`);
   }
+  /**
+   * End the batch of {@link collisionBatch}: one collision prints its full message; several
+   * print one summary (how many libraries and assets, the library each asset came from, the
+   * assets whose bytes differ). `verboseCollisions` prints every asset's full message instead.
+   */
+  flushLibraryCollisions() {
+    const batch = this.collisionBatch ? [...this.collisionBatch.values()] : [];
+    this.collisionBatch = null;
+    if (batch.length === 0) return;
+    if (batch.length === 1 || this.verboseCollisions) {
+      for (const c of batch) this.emitLibraryCollision(libraryCollisionMessage(c), [c.key]);
+      return;
+    }
+    this.emitLibraryCollision(
+      libraryCollisionSummary(batch),
+      batch.map((c) => c.key)
+    );
+  }
   /** Kind, name and bare publisher of a deploy entry; the publisher comes from its canonical ref. */
   entryIdentity(entry) {
     const ref = parseAssetRefLoose(canonicalEntryRef(entry));
@@ -2207,7 +2504,7 @@ var AssetManager = class {
    * name and URL: the lock does not change because it was installed on another machine. A
    * library renamed on this machine with `library rename` is locked under its new name.
    */
-  async libraryLockEntries(lib) {
+  async libraryLockEntries(lib, relockGit = false) {
     if (lib.entries.length === 0) return {};
     const snap = await this.loadLibraryIndex();
     const previous = Object.entries(this.tryReadLock()?.assets ?? {}).filter(
@@ -2229,15 +2526,28 @@ var AssetManager = class {
           return id.kind === e.kind && id.name === e.name && id.publisher === publisher;
         })?.[1].library;
         if (locked) {
-          const lookup = this.lockedLibrary(locked, snap);
-          const renamedHere = !locked.url && !url && renamedLibraryName(locked.name) === name;
-          if (lookup.state === "ok" && lookup.name === name && !renamedHere) {
+          const lookup = this.lockedLibrary(locked, snap, {
+            kind: e.kind,
+            publisher,
+            name: e.name
+          });
+          const renamedHere = renamedLibraryName(locked.name) === name || lookup.state === "ok" && lookup.matched === "content";
+          const keepName = !renamedHere || Boolean(locked.url) && !relockGit;
+          if (lookup.state === "ok" && lookup.name === name && keepName) {
             lockName = locked.name;
             if (locked.url && url && normalizeRepoUrl(locked.url) === normalizeRepoUrl(url)) {
               url = locked.url;
             }
           }
         }
+        const requires = [
+          ...new Set(
+            libraryEntryDepRefs(e).flatMap((dep) => {
+              const id = memberIdentity(dep);
+              return id?.publisher ? [`${id.kind}:@${id.publisher}/${id.name}`] : [];
+            })
+          )
+        ].sort();
         return {
           kind: e.kind,
           publisher,
@@ -2247,7 +2557,8 @@ var AssetManager = class {
             version: e.version || def?.version || "0.0.0",
             sha256,
             ...url ? { url } : {}
-          }
+          },
+          ...requires.length > 0 ? { requires } : {}
         };
       })
     );
@@ -2306,7 +2617,7 @@ var AssetManager = class {
     for (const [ref, e] of locked) {
       const { publisher, kind, name } = parseCanonicalLockKey(ref);
       if (!publisher || !kind || !name) continue;
-      const lookup = this.lockedLibrary(e.library, snap);
+      const lookup = this.lockedLibrary(e.library, snap, { kind, publisher, name });
       if (lookup.state === "ok") continue;
       const component = this.installTarget(kind);
       const deployed = component !== void 0 && isDeployed(component, name, this.driverTarget, this.global, this.projectDir);
@@ -2339,7 +2650,7 @@ var AssetManager = class {
         missing.push(`${ref} (unparseable lock key)`);
         continue;
       }
-      const lookup = this.lockedLibrary(origin, snap);
+      const lookup = this.lockedLibrary(origin, snap, { kind, publisher, name });
       if (lookup.state !== "ok") {
         missing.push(
           `${ref} (${lockedLibraryProblem(lookup, origin, `${kind}:@${publisher}/${name}`)})`
@@ -2360,9 +2671,14 @@ var AssetManager = class {
       const current = libraryAssetVersion(snap, lookup.name, { kind, publisher, name }, found.version) || "0.0.0";
       const sameVersion = current === origin.version || isPseudoVersion(current) && isPseudoVersion(origin.version);
       if (!sameVersion) {
-        missing.push(
-          `${ref} (library "${lookup.name}" is at ${current}, locked ${origin.version})`
-        );
+        const component = this.installTarget(kind);
+        const newer = gt(coerceVersion(current), coerceVersion(origin.version));
+        const intact = newer && (component === void 0 || isDeployed(component, name, this.driverTarget, this.global, this.projectDir));
+        if (!intact) {
+          missing.push(
+            `${ref} (library "${lookup.name}" is at ${current}, locked ${origin.version}${newer ? "; `skaile update` moves the lock to it" : ""})`
+          );
+        }
         continue;
       }
       if (origin.sha256) {
@@ -2394,6 +2710,30 @@ var AssetManager = class {
       return component !== void 0 && isDeployed(component, id.name, this.driverTarget, this.global, this.projectDir);
     });
   }
+  /** Whether the deployed copy of a library asset is on disk; a kind with no install target has none to check. */
+  lockedCopyDeployed(kind, name) {
+    const component = this.installTarget(kind);
+    return component === void 0 || isDeployed(component, name, this.driverTarget, this.global, this.projectDir);
+  }
+  /**
+   * The library-origin lock entries `install` keeps when the library holds a newer version:
+   * only `update` moves a locked asset, so `install` restores the locked one (p1095).
+   * Keyed by `<publisher>/<kind>:<name>`. `requires` is what the locked version needs: the
+   * lock's own list, or for a lock that predates the field the deployed copy's requirements,
+   * never the newer library entry's.
+   */
+  async keepLockedLibraryEntries(lock) {
+    if (!lock) return void 0;
+    const out = /* @__PURE__ */ new Map();
+    for (const [key, entry] of Object.entries(lock.assets)) {
+      if (!entry.library || entry.library.installed || !entry.library.version) continue;
+      const id = parseCanonicalLockKey(key);
+      if (!id.publisher || !id.kind || !id.name) continue;
+      const requires = entry.requires ?? await this.deployedRequirementsOf(id);
+      out.set(`${id.publisher}/${id.kind}:${id.name}`, { key, entry, requires });
+    }
+    return out.size > 0 ? out : void 0;
+  }
   /**
    * 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.
@@ -2409,7 +2749,7 @@ var AssetManager = class {
    *   `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.
    */
-  lockedLibrary(origin, snap) {
+  lockedLibrary(origin, snap, asset) {
     const { name } = origin;
     if (name === GLOBAL_INSTALL_DIR_NAME) return { state: "unregistered" };
     let byName = { state: "unregistered" };
@@ -2430,13 +2770,29 @@ var AssetManager = class {
       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;
+    if (byName.state === "ok") return byName;
+    if (origin.url) {
+      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);
+      });
+      if (byUrl) return { state: "ok", path: byUrl.path, name: byUrl.name };
+    }
+    const holder = asset && origin.sha256 ? this.libraryHoldingLockedBytes(origin.sha256, asset, snap) : void 0;
+    return holder ? { state: "ok", path: holder.path, name: holder.name, matched: "content" } : byName;
+  }
+  /** The registered library whose files for `asset` hash to `sha256` (the locked bytes), if any. */
+  libraryHoldingLockedBytes(sha256, asset, snap) {
+    if (!snap) return void 0;
+    for (const l of snap.libraries) {
+      if (!existsSync(l.path) || !newestLibraryDef(snap, l.name, asset)) continue;
+      const onDisk = libraryDiskHashes(l.path, /* @__PURE__ */ new Map(), this.registry).get(
+        `${asset.kind}:${asset.name}`
+      );
+      if (onDisk === sha256) return { name: l.name, path: l.path };
+    }
+    return void 0;
   }
   /** On-disk root of the library `origin` names; `null` unless {@link lockedLibrary} says `ok`. */
   libraryPath(origin, snap) {
@@ -2474,7 +2830,7 @@ var AssetManager = class {
       const { publisher, kind, name } = parseCanonicalLockKey(key);
       if (!publisher || !kind || !name) continue;
       const origin = e.library;
-      const lookup = this.lockedLibrary(origin, snap);
+      const lookup = this.lockedLibrary(origin, snap, { kind, publisher, name });
       const resolved = lookup.state === "ok" ? lookup.name : origin.installed ? origin.name : null;
       out.set(`${kind}:${publisher}/${name}`, resolved);
     }
@@ -2559,6 +2915,8 @@ var AssetManager = class {
     const overridesApplied = /* @__PURE__ */ new Set();
     const presets = [];
     const requiredBy = /* @__PURE__ */ new Map();
+    const keptVersions = {};
+    const versionBlocked = [];
     const lib = { entries: [], resolved: /* @__PURE__ */ new Set(), libraryOf: /* @__PURE__ */ new Map() };
     const missing = /* @__PURE__ */ new Set();
     const seen = /* @__PURE__ */ new Set();
@@ -2569,6 +2927,15 @@ var AssetManager = class {
       if (id !== null) declaredById.set(id, d);
     }
     const presetParent = /* @__PURE__ */ new Map();
+    const keepFor = (e, id, asked) => {
+      const locked = opts.keepLocked?.get(id);
+      const lockedVersion = locked?.entry.library?.version;
+      if (!locked || !lockedVersion || !e.version) return void 0;
+      if (isPseudoVersion(lockedVersion) || isPseudoVersion(e.version)) return void 0;
+      if (!gt(coerceVersion(e.version), coerceVersion(lockedVersion))) return void 0;
+      for (const r of asked) if (refIdentity(r) === id && r.includes("#")) return void 0;
+      return locked;
+    };
     const absorb = (hit) => {
       const next = [];
       for (const e of hit.entries) {
@@ -2576,7 +2943,8 @@ var AssetManager = class {
         const id = `${e.publisher}/${e.kind}:${e.name}`;
         seen.add(id);
         covered.add(id);
-        const deps2 = libraryEntryDepRefs(e);
+        const keep = e.kind === "preset" ? void 0 : keepFor(e, id, hit.resolved);
+        const deps2 = keep?.requires ?? libraryEntryDepRefs(e);
         if (e.kind === "preset") {
           const chain = [id];
           for (let up = presetParent.get(id); up !== void 0; up = presetParent.get(up)) {
@@ -2597,6 +2965,13 @@ var AssetManager = class {
             skipped: e.skippedItems ?? 0,
             ...origin ? { library: origin } : {}
           });
+        } else if (keep) {
+          keptVersions[keep.key] = keep.entry;
+          if (!this.lockedCopyDeployed(e.kind, e.name)) {
+            versionBlocked.push(
+              `${keep.key} (library "${origin ?? keep.entry.library?.name}" is at ${e.version}, locked ${keep.entry.library?.version}; the deployed copy is gone and cannot be restored from the newer files \u2014 \`skaile update\` moves the lock to it)`
+            );
+          }
         } else {
           lib.entries.push(e);
           if (origin) lib.libraryOf.set(e, origin);
@@ -2611,7 +2986,10 @@ var AssetManager = class {
           for (const dep of deps2) {
             const depId = refIdentity(dep);
             if (depId !== null && declaredById.has(depId)) continue;
-            requiredBy.set(dep, [...requiredBy.get(dep) ?? [], canonicalEntryRef(e)]);
+            requiredBy.set(dep, [
+              ...requiredBy.get(dep) ?? [],
+              keep ? keep.key : canonicalEntryRef(e)
+            ]);
           }
         }
       }
@@ -2672,7 +3050,16 @@ var AssetManager = class {
       return !lib.resolved.has(m) && !(id !== null && covered.has(id));
     });
     this.keepUnchangedSourceVersions(resolved, [...deps, ...opts.declaredRefs ?? []]);
-    return { resolved, missing: stillMissing, overridesApplied, lib, presets, requiredBy };
+    return {
+      resolved,
+      missing: stillMissing,
+      overridesApplied,
+      lib,
+      presets,
+      requiredBy,
+      keptVersions,
+      versionBlocked
+    };
   }
   /**
    * A source asset without a declared version is keyed `0.0.0-sha.<repo commit>`, so every
@@ -2892,7 +3279,9 @@ var AssetManager = class {
    * @returns {@link InstallResult} summarising what was deployed, what was missing, and any collisions.
    */
   async install(opts) {
-    const { repositories, sources, stores, dependencies, overrides, patches } = this.loadConfig();
+    const config = this.loadConfig();
+    const { repositories, sources, stores, overrides, patches } = config;
+    const dependencies = [...config.dependencies, ...this.lockedAgentBindings(config.dependencies)];
     if (opts?.locked) {
       return this.installLocked(repositories, patches, dependencies);
     }
@@ -2921,14 +3310,25 @@ var AssetManager = class {
       knownKinds: this.knownKinds,
       onSourceError: this.reportSourceError
     });
-    const { resolved, missing, overridesApplied, lib, presets, requiredBy } = await this.resolveLibraryFirst(dependencies, {
+    const keepLocked = opts?.moveLibraries ? void 0 : await this.keepLockedLibraryEntries(lockForLibraries);
+    const {
+      resolved,
+      missing,
+      overridesApplied,
+      lib,
+      presets,
+      requiredBy,
+      keptVersions,
+      versionBlocked
+    } = await this.resolveLibraryFirst(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 ? { preferLocked: await this.lockedPreference() } : { lockedLibraries: await this.lockedLibraryNames() }
+      ...opts?.moveLibraries ? { preferLocked: await this.lockedPreference() } : { lockedLibraries: await this.lockedLibraryNames() },
+      ...keepLocked ? { keepLocked } : {}
     });
     this.assertNoFolderCollision([...resolved, ...lib.entries.map((e) => this.entryIdentity(e))]);
     if (!opts?.force && !(existsSync(this.lockPath) && this.tryReadLock() === null)) {
@@ -2985,17 +3385,22 @@ var AssetManager = class {
       missingHints[ref] = `${fix ? "" : missingHints[ref] ?? ""} (${notes.join("; ")})`;
     }
     const directLock = this.directInstallLockEntries();
-    const libraryLock = { ...directLock, ...await this.libraryLockEntries(lib) };
+    const libraryLock = {
+      ...directLock,
+      ...await this.libraryLockEntries(lib, opts?.moveLibraries === true),
+      ...keptVersions
+    };
     const freshLock = {
       ...buildLockFile(resolved, overridesApplied, libraryLock),
       ...presetsLockSlice(presets)
     };
     await this.keepRequiredByKept(prevLock, kept, Object.keys(freshLock.assets));
+    const entries = [...await this.buildCatalogEntries(resolved, repositories), ...lib.entries];
+    assertNoLibrarySymlinks(entries, this.registry, repositories, opts?.link === true);
     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 missingCopies = await this.incompleteDeploys();
     const unrecordedAgents = this.unrecordedAgentFiles(prevLock);
@@ -3012,9 +3417,9 @@ var AssetManager = class {
       )
     ];
     this.sweepLegacyOmpCopies(entries);
-    await this.renderDriverMcpConfig();
+    const mcpRestored = await this.renderDriverMcpConfig();
     const agentRender = await this.renderAgentInstances();
-    const restored = this.restoredCopies(copyDrift, deployed, missingCopies);
+    const restored = [...this.restoredCopies(copyDrift, deployed, missingCopies), ...mcpRestored];
     const rewritten = this.rewrittenAgentFiles(unrecordedAgents);
     const lockWanted = resolved.length > 0 || lib.entries.length > 0 || existsSync(this.lockPath);
     let lockWritten = false;
@@ -3022,8 +3427,9 @@ var AssetManager = class {
     let moved = [];
     if (lockWanted) {
       const lockData = this.withRenderedAgents(withKeptLockEntries(freshLock, kept));
-      relocked = relockedRefs(prevLock, lockData);
       moved = libraryMoves(prevLock, libraryLock);
+      const movedRefs = new Set(moved.map((m) => m.ref));
+      relocked = relockedRefs(prevLock, lockData).filter((k) => !movedRefs.has(k.split("#")[0]));
       lockWritten = writeLock(this.lockPath, lockData);
     }
     this.recordInstallHistory(deployed, removed);
@@ -3032,11 +3438,13 @@ var AssetManager = class {
     for (const n of storeNotChecked) delete missingHints[n.ref];
     await this.adviseMissing(reportedMissing, missingHints);
     const placeholderBodies = scaffoldBodyRefs(lib.entries, deployed);
+    const placeholderDescriptions = scaffoldDescriptionRefs(lib.entries, deployed);
     return {
       deployed,
       removed,
-      missing: reportedMissing,
+      missing: [...reportedMissing, ...versionBlocked.filter((b) => !reportedMissing.includes(b))],
       ...placeholderBodies.length > 0 ? { placeholderBodies } : {},
+      ...placeholderDescriptions.length > 0 ? { placeholderDescriptions } : {},
       ...storeNotChecked.length > 0 ? { storeNotChecked } : {},
       ...Object.keys(missingHints).length > 0 ? { missingHints } : {},
       ...relocked.length > 0 ? { relocked } : {},
@@ -3410,7 +3818,8 @@ var AssetManager = class {
   async installLocked(repositories, patches, dependencies) {
     const lock = this.tryReadLock();
     if (!lock) {
-      const gaps2 = (await this.projectState()).gaps.filter((g) => g.type !== "agent");
+      const all = (await this.projectState()).gaps;
+      const gaps2 = all.filter((g) => g.type !== "agent");
       if (gaps2.some((g) => g.manualFix)) {
         return {
           deployed: [],
@@ -3422,10 +3831,11 @@ var AssetManager = class {
         };
       }
       if (dependencies.length === 0) {
+        const unbound = all.filter((g) => g.type === "agent");
         return {
           deployed: [],
           removed: [],
-          missing: [],
+          missing: unbound.map((g) => g.message),
           lockWritten: false,
           npmInstalled: [],
           npmFailed: []
@@ -3503,6 +3913,7 @@ var AssetManager = class {
   ${reason}`);
     }
     const library = await this.restoreLibraryLockEntries(lock);
+    assertNoLibrarySymlinks([...resolved, ...library.entries], this.registry, repositories);
     const copyDrift = await this.lockedCopyDrift();
     const missingCopies = await this.incompleteDeploys();
     const unrecordedAgents = this.unrecordedAgentFiles(lock);
@@ -3519,9 +3930,9 @@ var AssetManager = class {
       )
     ];
     this.sweepLegacyOmpCopies([...resolved, ...library.entries]);
-    await this.renderDriverMcpConfig();
+    const mcpRestored = await this.renderDriverMcpConfig();
     const agentRender = await this.renderAgentInstances();
-    const restored = this.restoredCopies(copyDrift, deployed, missingCopies);
+    const restored = [...this.restoredCopies(copyDrift, deployed, missingCopies), ...mcpRestored];
     const rewritten = this.rewrittenAgentFiles(unrecordedAgents);
     const alreadyMissing = new Set(
       library.missing.map((m) => {
@@ -3535,11 +3946,13 @@ var AssetManager = class {
       return !(p && alreadyMissing.has(`${p.kind}:${p.name}`));
     }).map((g) => g.message);
     const placeholderBodies = scaffoldBodyRefs(library.entries, deployed);
+    const placeholderDescriptions = scaffoldDescriptionRefs(library.entries, deployed);
     return {
       deployed,
       removed: [],
       missing: [...library.missing, ...gaps],
       ...placeholderBodies.length > 0 ? { placeholderBodies } : {},
+      ...placeholderDescriptions.length > 0 ? { placeholderDescriptions } : {},
       lockWritten: false,
       ...restored.length > 0 ? { restored } : {},
       ...rewritten.length > 0 ? { rewritten } : {},
@@ -3657,17 +4070,21 @@ var AssetManager = class {
       knownKinds: this.knownKinds,
       onSourceError: this.reportSourceError
     });
-    const { resolved, missing, overridesApplied, lib, presets } = await this.resolveLibraryFirst(
-      [ref],
-      {
+    this.collisionBatch = /* @__PURE__ */ new Map();
+    let resolution;
+    try {
+      resolution = await this.resolveLibraryFirst([ref], {
         provenanceIndex,
         overrides,
         stores,
         declaredRefs: dependencies,
         warnCollisions: true,
         ...opts?.preferLockedLibrary ? { preferLocked: await this.lockedPreference() } : {}
-      }
-    );
+      });
+    } finally {
+      this.flushLibraryCollisions();
+    }
+    const { resolved, missing, overridesApplied, lib, presets } = resolution;
     if (resolved.length === 0 && lib.entries.length === 0 && presets.length === 0) {
       const snap = await this.loadLibraryIndex();
       const bare = (p) => (p ?? "").replace(/^@/, "");
@@ -3752,6 +4169,8 @@ var AssetManager = class {
       );
     }
     const entries = [...await this.buildCatalogEntries(resolved, repositories), ...lib.entries];
+    assertFlowsLoad(entries);
+    assertNoLibrarySymlinks(entries, this.registry, repositories, opts?.link === true);
     const deployed = [
       ...new Set(
         this.targetHarnesses().flatMap(
@@ -3759,7 +4178,7 @@ var AssetManager = class {
             this.entriesForHarness(entries, t),
             repositories,
             patches,
-            this.deployOptsFor(t, opts?.link, opts?.onSkippedSymlink, opts?.onEnvFile)
+            this.deployOptsFor(t, opts?.link, opts?.onSecretFile)
           )
         )
       )
@@ -3776,6 +4195,9 @@ var AssetManager = class {
     for (const placeholder of scaffoldBodyRefs(lib.entries, deployed)) {
       opts?.onPlaceholderBody?.(placeholder);
     }
+    for (const placeholder of scaffoldDescriptionRefs(lib.entries, deployed)) {
+      opts?.onPlaceholderDescription?.(placeholder);
+    }
     this.addDependencyToConfig(ref);
     await this.renderDriverMcpConfig();
     await this.renderAgentInstances();
@@ -4350,9 +4772,12 @@ var AssetManager = class {
     const lock = this.tryReadLock();
     if (!lock) return false;
     let changed = false;
+    const droppedUrls = [];
     for (const key of Object.keys(lock.assets)) {
       const id = parseCanonicalLockKey(key);
       if (id.kind === parsed.kind && id.name === parsed.name && (!parsed.publisher || id.publisher === parsed.publisher)) {
+        const url = lock.assets[key]?.source?.url;
+        if (url) droppedUrls.push(url);
         delete lock.assets[key];
         changed = true;
       }
@@ -4368,7 +4793,7 @@ var AssetManager = class {
         changed = true;
       }
     }
-    if (changed) writeLock(this.lockPath, resyncLockSources(lock));
+    if (changed) writeLock(this.lockPath, resyncLockSources(lock, droppedUrls));
     return changed;
   }
   // ── Query ──────────────────────────────────────────────────────────────
@@ -4614,11 +5039,24 @@ var AssetManager = class {
         (k) => k.kind === parsed.kind && k.name === parsed.name && (!parsed.publisher || k.publisher === parsed.publisher)
       );
       let state;
+      let reason;
       if (!locked) {
         state = "declared";
       } else if (parsed.kind === "mcp-server") {
         const wired = await wiredMcpNames();
-        state = wired.has(parsed.name) || wired.has(unscopedName(parsed.name)) ? "installed" : "drift";
+        const isWired = wired.has(parsed.name) || wired.has(unscopedName(parsed.name));
+        const skippedReason = Object.entries(
+          await readSkippedMcpServers(this.projectDir, this.driverTarget)
+        ).find(([id]) => id === parsed.name || unscopedName(id) === parsed.name)?.[1];
+        const drifted = (await this.mcpDriftRows()).some(
+          (r) => unscopedName(r.drift.id) === unscopedName(parsed.name)
+        );
+        if (isWired && skippedReason !== void 0) {
+          state = "skipped";
+          reason = skippedReason;
+        } else {
+          state = isWired && !drifted ? "installed" : "drift";
+        }
       } else {
         const component = this.installTarget(parsed.kind);
         if (!component) {
@@ -4634,7 +5072,40 @@ var AssetManager = class {
           state = onDisk ? "installed" : "drift";
         }
       }
-      out.push({ ref, kind: parsed.kind, name: parsed.name, state });
+      out.push({ ref, kind: parsed.kind, name: parsed.name, state, ...reason ? { reason } : {} });
+    }
+    return out;
+  }
+  /**
+   * Notes about the project's `mcp-server`s that are not drift and fail nothing: a declared
+   * server skaile does not write to the coding agent's MCP config (`reason` from the last
+   * render), and a required `MCP.md` field nothing sets. `check` and `doctor` print them as
+   * `!` lines; `list` shows the first kind as `skipped`.
+   *
+   * @returns One {@link McpNotice} per note; empty for a global manager.
+   */
+  async mcpNotices() {
+    if (this.global) return [];
+    const out = [];
+    const skipped = await readSkippedMcpServers(this.projectDir, this.driverTarget);
+    for (const [id, reason] of Object.entries(skipped)) {
+      out.push({ id, kind: "skipped", reason, text: `MCP server "${id}" is skipped: ${reason}` });
+    }
+    let decls = [];
+    try {
+      decls = await loadMcpServerDeclarations(this.projectDir);
+    } catch {
+    }
+    for (const decl of decls) {
+      if (skipped[decl.id] !== void 0) continue;
+      const unset = unsetRequiredFields(decl);
+      if (unset.length > 0) {
+        out.push({
+          id: decl.id,
+          kind: "unset-field",
+          text: `MCP server "${decl.id}" ${requiredFieldsAdvice(decl.id, unset)}`
+        });
+      }
     }
     return out;
   }
@@ -5048,7 +5519,7 @@ var AssetManager = class {
         const origin = entry.library;
         const { publisher, kind, name } = parseCanonicalLockKey(ref);
         if (!publisher || !kind || !name) continue;
-        const lookup = this.lockedLibrary(origin, snap);
+        const lookup = this.lockedLibrary(origin, snap, { kind, publisher, name });
         if (lookup.state !== "ok") continue;
         const libPath = lookup.path;
         const scanKey = `${libPath}\0${publisher}`;
@@ -5241,7 +5712,11 @@ var AssetManager = class {
       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 lookup = this.lockedLibrary(e.library, snap, {
+        kind: id.kind,
+        publisher: id.publisher,
+        name: id.name
+      });
       const library = lookup.state === "ok" ? lookup.name : e.library.name;
       for (const r of refs) {
         const hit = (await this.resolveLibraryEntries([r], { library })).entries[0];
@@ -5298,6 +5773,19 @@ var AssetManager = class {
   async diff(ref) {
     const parsed = parseRefTolerant(ref);
     if (!parsed) return { status: "not-found" };
+    if (parsed.kind === "mcp-server") {
+      const wantPub = parsed.publisher?.replace(/^@/, "");
+      const lockedHere = Object.keys(this.tryReadLock()?.assets ?? {}).map(parseCanonicalLockKey).filter((id) => id.kind === "mcp-server" && id.name === parsed.name);
+      if (lockedHere.length > 0) {
+        if (wantPub && !lockedHere.some((id) => id.publisher === wantPub)) {
+          return { status: "not-deployed" };
+        }
+        const row = (await this.mcpDriftRows()).find(
+          (r) => unscopedName(r.drift.id) === unscopedName(parsed.name)
+        );
+        return row ? { status: "differs", diff: mcpDriftDiff(row.drift) } : { status: "identical" };
+      }
+    }
     const entry = await this.lockedLibraryEntry(parsed) ?? this.lockedSourceEntry(parsed) ?? await this.info(ref);
     if (!entry || !existsSync(entry.source)) return { status: "not-found" };
     const wantPublisher = parsed.publisher?.replace(/^@/, "");
@@ -5680,6 +6168,22 @@ var AssetManager = class {
       gaps.push(gap);
       named.add(gapIdentity(gap.ref));
     }
+    const skipped = [];
+    const sourceIndex = await buildProvenanceIndex(
+      this.buildClones(this.loadConfig().repositories),
+      {
+        projectDir: this.projectDir,
+        knownKinds: this.knownKinds,
+        onSourceError: (clone, err) => skipped.push({
+          url: clone.sourceUrl,
+          why: err instanceof Error ? err.message : String(err)
+        })
+      }
+    );
+    for (const gap of await this.sourceOriginGaps(named, sourceIndex)) {
+      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));
@@ -5702,20 +6206,22 @@ var AssetManager = class {
       gaps.push({ type: "modified", ref: d.ref, reason, message: `${d.ref} ${reason}` });
       named.add(gapIdentity(d.ref));
     }
+    for (const { ref, drift } of await this.mcpDriftRows()) {
+      if (named.has(gapIdentity(ref))) continue;
+      const parts = [
+        ...drift.missing.map((f) => `${f} is missing`),
+        ...drift.modified.map((f) => `${f} was edited`),
+        ...drift.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, reason, message: `${ref} ${reason}` });
+      named.add(gapIdentity(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 --locked\` to restore it`;
       gaps.push({ type: "incomplete", ref: d.ref, reason, message: `${d.ref} ${reason}` });
     }
-    const skipped = [];
-    await buildProvenanceIndex(this.buildClones(this.loadConfig().repositories), {
-      projectDir: this.projectDir,
-      knownKinds: this.knownKinds,
-      onSourceError: (clone, err) => skipped.push({
-        url: clone.sourceUrl,
-        why: err instanceof Error ? err.message : String(err)
-      })
-    });
     for (const s of skipped) {
       const reason = `is skipped: ${s.why.replace(`${s.url}: `, "")} \u2014 fix it or run \`skaile source remove\``;
       gaps.push({
@@ -5773,12 +6279,12 @@ var AssetManager = class {
           ""
         );
         return {
-          lead: "the agent is locked but its library cannot supply it here",
+          lead: "its agent is locked and the library cannot supply it here",
           advice: `${register}, ${drop}`
         };
       }
       return {
-        lead: "the agent is locked but not restored here",
+        lead: "its agent is locked and not restored here",
         advice: `run \`skaile install --locked\` first, ${drop}`
       };
     }
@@ -5896,7 +6402,7 @@ var AssetManager = class {
       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 lookup = this.lockedLibrary(origin, snap, { kind, publisher, name });
       const libPath = lookup.state === "ok" ? lookup.path : null;
       if (lookup.state === "ok" && libPath) {
         const scanKey = `${libPath}\0${publisher}`;
@@ -5945,6 +6451,65 @@ var AssetManager = class {
     }
     return gaps;
   }
+  /**
+   * Locked source assets whose source cannot supply them any more: the source is no longer in
+   * `skaile.yaml` `sources:` (`source remove`, a hand edit), or it is there but now publishes
+   * the asset under another publisher (`source add <url> --publisher`). `skaile install` has
+   * nothing to restore them from, so the fix is manual. A source of a store-resolved lock entry
+   * is not told apart from one, so no source is called missing while a `stores:` entry exists.
+   *
+   * @param named - `kind:name` identities already reported; they are skipped.
+   * @param index - What the registered sources publish today.
+   */
+  async sourceOriginGaps(named, index) {
+    let config;
+    try {
+      config = this.loadConfig();
+    } catch {
+      return [];
+    }
+    const storeBacked = config.stores.length > 0 || (await this.globalStoreFallback(config.stores)).length > 0;
+    const registered = new Set(config.sources.map((s) => sourceCacheKey(s.url)));
+    const published = [...index.values()].flat();
+    const gaps = [];
+    for (const [key, entry] of Object.entries(this.tryReadLock()?.assets ?? {})) {
+      const url = entry.source?.url;
+      if (!url || entry.library || !GIT_URL.test(url)) continue;
+      if (normalizeRepoUrl(url) === normalizeRepoUrl(FACTORY_SOURCE_URL)) continue;
+      const { publisher, kind, name } = parseCanonicalLockKey(key);
+      if (!publisher || !kind || !name || named.has(`${kind}:${name}`)) continue;
+      const ref = `${kind}:@${publisher}/${name}`;
+      if (!registered.has(sourceCacheKey(url))) {
+        if (storeBacked && GITHUB_REPO_URL.test(url)) continue;
+        const reason = `is locked, but its source ${url} is not in skaile.yaml sources: any more \u2014 register it again with \`skaile source add ${url}\`, or drop the dependency with \`skaile remove ${ref}\``;
+        gaps.push({ type: "source", ref, reason, message: `${ref} ${reason}`, manualFix: true });
+        continue;
+      }
+      const here = published.filter(
+        (c) => c.kind === kind && c.name === name && sourceCacheKey(c.sourceUrl) === sourceCacheKey(url)
+      );
+      if (here.length > 0 && !here.some((c) => c.publisher === publisher)) {
+        const now = here[0].publisher;
+        const reason = `is locked, but source ${url} publishes it as ${kind}:@${now}/${name} now (the source's publisher changed) \u2014 run \`skaile source add ${url} --publisher ${publisher} --force\` to give it back, or change the ref in skaile.yaml to the new one`;
+        gaps.push({ type: "source", ref, reason, message: `${ref} ${reason}`, manualFix: true });
+      }
+    }
+    return gaps;
+  }
+  /**
+   * The locked assets that come from the source `url` (a `sources:` entry): canonical refs,
+   * `kind:@publisher/name`. `skaile source remove` refuses while this list is not empty.
+   */
+  lockedFromSource(url) {
+    const want = sourceCacheKey(url);
+    const out = [];
+    for (const [key, entry] of Object.entries(this.tryReadLock()?.assets ?? {})) {
+      if (entry.library || !entry.source || sourceCacheKey(entry.source.url) !== want) continue;
+      const { publisher, kind, name } = parseCanonicalLockKey(key);
+      if (kind && name) out.push(publisher ? `${kind}:@${publisher}/${name}` : `${kind}:${name}`);
+    }
+    return out;
+  }
   /**
    * Record, on every agent entry of `lock` that has none, the files the agent's harness
    * rendering occupies and their sha256. Call it after the deploy, so the bytes hashed are the
@@ -6266,7 +6831,14 @@ var AssetManager = class {
         if (!renderedGone) continue;
       }
       const ref = publisher ? `${kind}:@${publisher}/${name}` : `${kind}:${name}`;
-      const reason = "is locked but its deployed copy is missing \u2014 run `skaile install --locked`";
+      const dangling = deployedPaths(
+        component,
+        name,
+        this.driverTarget,
+        this.global,
+        this.projectDir
+      ).find((p) => isSymlink(p) && !existsSync(p));
+      const reason = dangling ? `is locked but its deployed copy is a symlink to nothing (${relative(this.projectDir, dangling)}) \u2014 run \`skaile install --locked\`` : "is locked but its deployed copy is missing \u2014 run `skaile install --locked`";
       gaps.push({ type: "drift", ref, reason, message: `${ref} ${reason}` });
     }
     return gaps;
@@ -6715,6 +7287,33 @@ var AssetManager = class {
     writeFileSync(configPath, stringify(raw, { lineWidth: 120 }));
     return true;
   }
+  /**
+   * The locked agents an agent instance binds (`agents.<id>.ref`, `agent.definition`) that
+   * `declared` does not name, as version-less `agent:@publisher/name`. An agent no lock entry
+   * holds is left out: `install` does not add what the user never added (`skaile add` does).
+   */
+  lockedAgentBindings(declared) {
+    const lock = this.tryReadLock();
+    if (!lock) return [];
+    const locked = Object.keys(lock.assets).map(parseCanonicalLockKey);
+    const named = declared.map(memberIdentity);
+    const out = [];
+    for (const ref of this.declaredAgentInstanceRefs()) {
+      const want = memberIdentity(ref.split("#")[0] ?? ref);
+      if (want?.kind !== "agent") continue;
+      const hit = locked.find(
+        (id) => id.kind === "agent" && id.name === want.name && !!id.publisher && (!want.publisher || id.publisher === want.publisher)
+      );
+      if (!hit?.publisher) continue;
+      if (named.some(
+        (n) => n?.kind === "agent" && n.name === hit.name && (!n.publisher || n.publisher === hit.publisher)
+      ))
+        continue;
+      const canonical = `agent:@${hit.publisher}/${hit.name}`;
+      if (!out.includes(canonical)) out.push(canonical);
+    }
+    return out;
+  }
   /** The refs `skaile.yaml` binds agent instances to: every `agents.<id>.ref` and `agent.definition`. Project mode only. */
   declaredAgentInstanceRefs() {
     if (this.global) return [];
@@ -6796,6 +7395,6 @@ var AssetManager = class {
   }
 };
 
-export { AssetManager, FACTORY_SOURCE_URL, MissingManifestError, installAgentInstances, normalizeRepoUrl, parseCanonicalLockKey, parseRefTolerant, renderMcpServerConfig, softDepName };
-//# sourceMappingURL=chunk-W44KA24A.js.map
-//# sourceMappingURL=chunk-W44KA24A.js.map
+export { AssetManager, FACTORY_SOURCE_URL, LibraryEntryError, MissingManifestError, installAgentInstances, normalizeRepoUrl, parseCanonicalLockKey, parseRefTolerant, renderMcpServerConfig, softDepName };
+//# sourceMappingURL=chunk-TDQ2ERCM.js.map
+//# sourceMappingURL=chunk-TDQ2ERCM.js.map