@skaile/workspaces 5.10.0 → 5.11.0

package/dist/{chunk-2JMLDZLP.js → chunk-DZMNFCWB.js}

@@ -1,18 +1,18 @@
-import { unregisteredLibraryNames, scanUnlistedAssets, getStoreManifestsDir, missingLibraryDirMessage } from './chunk-3BEY4WK3.js';
-import { readManifestSourceConfig, isManifestMode, discoverAssetsInTree } from './chunk-GEWAIQZ5.js';
-import { installTargetOf, canonicalEntryRef, deployAll, removeAsset, diffDeployedAgent, createScaffold, installAgent } from './chunk-PE36IF2D.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-6HHE63CO.js';
-import { resolveConfiguredDriverTarget, GLOBAL_INSTALL_DIR_NAME, resolveLibraryDir, buildLibraryLockEntries, buildLockFile, writeLock, readLock, verifyLock, mergeLockFile, extractForPatch, generatePatch, savePatch, applyPatch } from './chunk-2FMEGSBN.js';
-import { resolveRuntimeAssets, factoryAssetRoots } from './chunk-GFCXNFTW.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, 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-JZCSNEHK.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 { loadSkPublishManifest } from './chunk-IXWODEED.js';
-import { scanDirectory, parseRequires, dedupeRequirements } from './chunk-Y34MSWEZ.js';
-import { parseAssetRef, parseAssetRefLoose, assetRefToStr, slugifyAssetName, depToStr } from './chunk-4OV5DSBB.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, { resolve, dirname, sep, join, relative, posix } from 'path';
@@ -40,13 +40,10 @@ function writeLedger(projectDir, ledger) {
 function bindInstance(projectDir, id, instance) {
   const errors = [];
   let srcDir;
-  const addHint = instance.ref.startsWith("agent:") ? ` \u2014 add the agent first: run skaile add ${instance.ref}` : "";
   try {
     srcDir = resolveAgentDefinitionDir(projectDir, instance.ref);
   } catch (err) {
-    errors.push(
-      `agent instance "${id}": ${err instanceof Error ? err.message : String(err)}${addHint}`
-    );
+    errors.push(`agent instance "${id}": ${err instanceof Error ? err.message : String(err)}`);
   }
   if (srcDir !== void 0 && !existsSync(join(srcDir, "agent.yaml"))) {
     errors.push(
@@ -674,10 +671,39 @@ function relockedRefs(prev, next) {
   }
   return out;
 }
+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)}`;
 }
@@ -841,14 +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, onSkippedSymlink) {
+  deployOptsFor(target, link, onSkippedSymlink, onEnvFile) {
     return {
       registry: this.registry,
       driverTarget: target,
       global: this.global,
       cwd: this.projectDir,
       link: link === true,
-      ...onSkippedSymlink ? { onSkippedSymlink: (entry, p) => onSkippedSymlink(canonicalEntryRef(entry), p) } : {}
+      ...onSkippedSymlink ? { onSkippedSymlink: (entry, p) => onSkippedSymlink(canonicalEntryRef(entry), p) } : {},
+      ...onEnvFile ? { onEnvFile: (entry, p) => onEnvFile(canonicalEntryRef(entry), p) } : {}
     };
   }
   /**
@@ -878,13 +905,18 @@ var AssetManager = class {
    * 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 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,
@@ -1024,6 +1056,9 @@ var AssetManager = class {
    *   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.
    */
@@ -1044,10 +1079,40 @@ 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(
+      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 candidates = pool.filter((c) => !pin || matchPin(pin, c.entry.version ?? ""));
+      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];
@@ -1058,16 +1123,7 @@ var AssetManager = class {
           hit
         );
       }
-      let entry = hit.entry;
-      if (!entry.version) {
-        if (snap === void 0) snap = await this.loadLibraryIndex();
-        const def = newestLibraryDef(snap, hit.library, {
-          kind: entry.kind,
-          publisher: entry.publisher ?? "",
-          name: entry.name
-        });
-        if (def?.version) entry = { ...entry, version: def.version };
-      }
+      const entry = hit.entry;
       withLibraryFiles(entry, libraryDir.get(hit.library), fileSets, this.registry);
       entries.push(entry);
       libraryOf.set(entry, hit.library);
@@ -1697,6 +1753,11 @@ var AssetManager = class {
       } 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) => {
@@ -1875,7 +1936,8 @@ var AssetManager = class {
         })
       );
       const hit = await this.resolveLibraryEntries([...libraryTried], {
-        quiet: !opts.warnCollisions
+        quiet: !opts.warnCollisions,
+        lockedLibraries: opts.lockedLibraries
       });
       const next = absorb(hit);
       const rest = fresh.filter((ref) => !hit.resolved.has(ref));
@@ -1892,7 +1954,7 @@ var AssetManager = class {
         presets.push(...r.presets);
         const hit2 = await this.resolveLibraryEntries(
           r.missing.filter((m) => !libraryTried.has(m)),
-          { quiet: !opts.warnCollisions }
+          { quiet: !opts.warnCollisions, lockedLibraries: opts.lockedLibraries }
         );
         next.push(...absorb(hit2));
         for (const m of r.missing) if (!hit2.resolved.has(m)) missing.add(m);
@@ -2065,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) {
@@ -2094,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));
@@ -2122,6 +2195,7 @@ var AssetManager = class {
       /* @__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(
@@ -2129,25 +2203,31 @@ var AssetManager = class {
         )
       )
     ];
+    const restored = this.restoredCopies(copyDrift, deployed);
     await this.renderDriverMcpConfig();
-    const agentRender = this.renderAgentInstances();
+    const agentRender = await this.renderAgentInstances();
     const lockWanted = resolved.length > 0 || lib.entries.length > 0 || existsSync(this.lockPath);
     let lockWritten = false;
     let relocked = [];
+    let moved = [];
     if (lockWanted) {
       const lockData = withKeptLockEntries(freshLock, kept);
       relocked = relockedRefs(prevLock, 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,
@@ -2404,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));
@@ -2468,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(
@@ -2480,8 +2591,9 @@ 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);
@@ -2498,6 +2610,7 @@ var AssetManager = class {
       removed: [],
       missing: [...library.missing, ...gaps],
       lockWritten: false,
+      ...restored.length > 0 ? { restored } : {},
       ...agentRender
     };
   }
@@ -2572,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.
@@ -2635,8 +2750,8 @@ 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];
@@ -2647,7 +2762,7 @@ var AssetManager = class {
             entries,
             repositories,
             patches,
-            this.deployOptsFor(t, opts?.link, opts?.onSkippedSymlink)
+            this.deployOptsFor(t, opts?.link, opts?.onSkippedSymlink, opts?.onEnvFile)
           )
         )
       )
@@ -2662,13 +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 libraryLock = await this.libraryLockEntries(lib);
       const fresh = {
-        ...buildLockFile(resolved, overridesApplied, await this.libraryLockEntries(lib)),
+        ...buildLockFile(resolved, overridesApplied, libraryLock),
         ...presetsLockSlice(presets)
       };
-      writeLock(this.lockPath, mergeLockFile(this.tryReadLock(), fresh));
+      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, {
@@ -2726,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);
@@ -3057,11 +3177,35 @@ var AssetManager = class {
     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 unbound = this.removeAgentBindings(parsed);
@@ -3647,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();
@@ -3672,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.
    *
@@ -3848,6 +4038,7 @@ var AssetManager = class {
     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));
@@ -4113,7 +4304,11 @@ var AssetManager = class {
     const lock = this.tryReadLock();
     const lockedIds = Object.keys(lock?.assets ?? {}).map(parseCanonicalLockKey);
     const requirements = await this.doctor();
-    const gaps = [];
+    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 publisher = lockedIds.find(
@@ -4130,7 +4325,7 @@ var AssetManager = class {
         });
         continue;
       }
-      const asset = `${i.assetKind}:${i.assetName}`;
+      const asset = lockIdentity(i.assetKind, i.assetName);
       const dep = `${i.depKind}:${i.depName}`;
       if (i.inRepos) {
         gaps.push({
@@ -4141,7 +4336,7 @@ var AssetManager = class {
           message: `${asset} requires ${dep} (fixable)`
         });
       } else {
-        const fix = `register the library that holds it with \`skaile library init <name> --path <dir>\`, or drop ${asset} with \`skaile remove ${asset}\``;
+        const fix = requirementNoHolderFix(asset);
         gaps.push({
           type: "requires",
           ref: dep,
@@ -4159,17 +4354,32 @@ var AssetManager = class {
       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:") ? `is bound by agent instance "${u.id}" but no agent was added for it \u2014 run \`skaile add ${u.ref}\` first, or drop the binding from skaile.yaml` : `is bound by agent instance "${u.id}" but resolves to no agent.yaml \u2014 fix the path, or drop the binding from skaile.yaml`;
+      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: "agent",
         ref: u.ref,
@@ -4178,7 +4388,54 @@ var AssetManager = class {
         manualFix: true
       });
     }
-    return { gaps, requirements };
+    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() {
@@ -4266,6 +4523,110 @@ var AssetManager = class {
     }
     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`.
@@ -4336,7 +4697,7 @@ var AssetManager = class {
         } else {
           gap = {
             type: "declared",
-            reason: `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 ${d.ref.split("#")[0]}\``,
+            reason: declaredNoHolderReason(d.ref),
             manualFix: true
           };
         }
@@ -4346,7 +4707,7 @@ var AssetManager = class {
           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: `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 ${d.ref.split("#")[0]}\``,
+            reason: declaredNoHolderReason(d.ref),
             manualFix: true
           };
           gaps.push({ ...gap, ref: d.ref, message: `${d.ref} ${gap.reason}` });
@@ -4715,5 +5076,5 @@ var AssetManager = class {
 };
 
 export { AssetManager, FACTORY_SOURCE_URL, MissingManifestError, installAgentInstances, normalizeRepoUrl, parseCanonicalLockKey, parseRefTolerant, renderMcpServerConfig, softDepName };
-//# sourceMappingURL=chunk-2JMLDZLP.js.map
-//# sourceMappingURL=chunk-2JMLDZLP.js.map
+//# sourceMappingURL=chunk-DZMNFCWB.js.map
+//# sourceMappingURL=chunk-DZMNFCWB.js.map