@skaile/workspaces 5.11.0 → 5.12.0

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

@@ -1,18 +1,18 @@
-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 { unregisteredLibraryNames, renamedLibraryName, resolveConfig, RemoteCatalogSource, OfflineError, describeCatalogError, CatalogHttpError, scanUnlistedAssets, getStoreManifestsDir, missingLibraryDirMessage } from './chunk-C3BMXXTN.js';
+import { readManifestSourceConfig, discoverAssetsInTree, isManifestMode } from './chunk-7CR2OZPA.js';
+import { installTargetOf, canonicalEntryRef, deployAll, removeAsset, diffDeployedAgent, removeExcludedLeftovers, deployedAssetDrift, createScaffold, installAgent } from './chunk-NJV5SLEK.js';
 import { appendHistory, getRecentHistory, clearHistory } from './chunk-KTBKW2FI.js';
 import { commitChanges } from './chunk-UQ6LFBPZ.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 { driverTargetSupportsAgents, CODEX_IDENTITY_DIR } from './chunk-7QWQTA5S.js';
+import { resolveConfiguredDriverTarget, GLOBAL_INSTALL_DIR_NAME, resolveLibraryDir, buildLibraryLockEntries, computeHash, buildLockFile, writeLock, readLock, verifyLock, mergeLockFile, extractForPatch, generatePatch, savePatch, applyPatch, LOCK_SCHEMA_VERSION } from './chunk-T5TSLSRO.js';
+import { resolveRuntimeAssets, factoryAssetRoots } from './chunk-SHQMPGOL.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-ALEYHUC5.js';
+import { resolveSkWorkspaceConfig, effectiveAgentInstances, loadMcpServerDeclarations, resolveGlobalHarnesses, resolveGlobalSkWorkspaceConfig, getGlobalCacheDir, sourceCacheKey, getRepoCommit, matchPin, buildProvenanceIndex, coerceVersion, sourceShortName, readLinks, isCommitOnRemote, resolveAll, agentSourceCacheDir, ensureRepo, scanRepo, SKAILE_YAML_DEFAULT, checkRepoStatus, resolveAsset, MAX_PRESET_DEPTH, PresetDepthError, DEFAULT_AGENT_INSTANCE_ID, resolveAgentDefinitionDir, storeManifestSlug } from './chunk-PNOGX36L.js';
 import { globalSkaileDir, globalCacheRoot, migrateLegacyDir } from './chunk-L5VSIPQD.js';
 import { DRIVER_TARGETS } from './chunk-CPSIPIX7.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 { loadSkPublishManifest } from './chunk-CTP3XBMF.js';
+import { scanDirectory, parseRequires, dedupeRequirements } from './chunk-XTVSNWLL.js';
+import { parseAssetRef, parseAssetRefLoose, assetRefToStr, slugifyAssetName, depToStr, parseDep } from './chunk-PNTXHTBC.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';
@@ -401,6 +401,19 @@ function filesUnderManifestDir(paths, manifestRel) {
   const manifestDir = posix.dirname(manifestRel);
   return paths.map((p) => posix.relative(manifestDir, p)).filter((rel) => rel !== "" && !rel.startsWith(".."));
 }
+function lockedAssetFiles(kind, files) {
+  const manifestRel = matchManifestPath(
+    kind,
+    files.map((f) => f.path)
+  ) ?? files[0]?.path;
+  if (!manifestRel) return [];
+  const manifestDir = posix.dirname(manifestRel);
+  return files.flatMap((f) => {
+    const rel = posix.relative(manifestDir, f.path);
+    return rel === "" || rel.startsWith("..") ? [] : [{ rel, sha256: f.sha256 }];
+  });
+}
+var GITHUB_REPO_URL = /github\.com[/:]/i;
 function indexLockByKindName(lock) {
   const lockByKindName = /* @__PURE__ */ new Map();
   for (const [key, entry] of Object.entries(lock?.assets ?? {})) {
@@ -435,6 +448,28 @@ function commitsBetween(repoDir, from, to, cache) {
   return count;
 }
 var COMMIT_ID = /^[0-9a-f]{7,64}$/;
+function commitsTouching(repoDir, from, to, dir, cache) {
+  if (!COMMIT_ID.test(from) || !COMMIT_ID.test(to)) return null;
+  if (from === to) return 0;
+  const key = `${from}..${to} -- ${dir}`;
+  const hit = cache.get(key);
+  if (hit !== void 0) return hit;
+  const r = spawnSync("git", ["-C", repoDir, "rev-list", "--count", `${from}..${to}`, "--", dir], {
+    encoding: "utf8",
+    stdio: "pipe"
+  });
+  const n = r.status === 0 ? Number.parseInt(r.stdout.trim(), 10) : Number.NaN;
+  if (!Number.isFinite(n) || n < 0) return null;
+  cache.set(key, n);
+  return n;
+}
+function lockedAssetDir(kind, files) {
+  const manifestRel = matchManifestPath(
+    kind,
+    files.map((f) => f.path)
+  ) ?? files[0]?.path;
+  return manifestRel ? posix.dirname(manifestRel) : ".";
+}
 function libraryDiskHashes(libPath, cache, registry) {
   let hashes = cache.get(libPath);
   if (!hashes) {
@@ -506,7 +541,7 @@ function newestLibraryDef(snap, libraryName, id) {
   }
   return best;
 }
-function libraryPreference(isDefaultLib) {
+function libraryPreference(isDefaultLib, rank) {
   return (a, b) => {
     const va = coerceVersion(a.entry.version ?? "");
     const vb = coerceVersion(b.entry.version ?? "");
@@ -514,7 +549,9 @@ function libraryPreference(isDefaultLib) {
     if (gt(vb, va)) return 1;
     const da = isDefaultLib.get(a.library) ? 0 : 1;
     const db = isDefaultLib.get(b.library) ? 0 : 1;
-    return da - db || a.library.localeCompare(b.library);
+    if (da !== db) return da - db;
+    const byRank = rank ? rank(a) - rank(b) : 0;
+    return byRank || a.library.localeCompare(b.library);
   };
 }
 function qualifyDepRef(ref, fallback) {
@@ -649,8 +686,7 @@ function withKeptLockEntries(lock, kept) {
   for (const s of kept.sources) if (!sources.has(s.url)) sources.set(s.url, s);
   return {
     ...lock,
-    // v4 once a library-origin entry is present (see buildLockFile).
-    schema_version: lock.schema_version === 4 || Object.values(kept.assets).some((e) => e.library) ? 4 : 3,
+    schema_version: LOCK_SCHEMA_VERSION,
     assets: { ...lock.assets, ...kept.assets },
     sources: [...sources.values()].sort((a, b) => a.url.localeCompare(b.url))
   };
@@ -793,6 +829,17 @@ var AssetManager = class {
   onLibraryCollision;
   /** 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". */
+  storeFailures = /* @__PURE__ */ new Map();
+  /** Sources a provenance walk had to skip (source URL → why); one warning per source. */
+  skippedSources = /* @__PURE__ */ new Map();
+  /** `onSourceError` of every provenance walk: name the source once, leave it out, go on. */
+  reportSourceError = (clone, err) => {
+    const why = err instanceof Error ? err.message : String(err);
+    if (this.skippedSources.has(clone.sourceUrl)) return;
+    this.skippedSources.set(clone.sourceUrl, why);
+    console.warn(`skaile: source ${clone.sourceUrl} skipped: ${why}`);
+  };
   constructor(opts) {
     this.projectDir = resolve(opts.projectDir);
     this.global = opts.global ?? false;
@@ -827,15 +874,27 @@ var AssetManager = class {
     return this.global ? globalSkaileDir() : this.projectDir;
   }
   /**
-   * The harnesses a global deploy fans out to: the explicit `harnesses` override
-   * (a `--harness` filter), else `resolveGlobalHarnesses()`. In project mode this
-   * is exactly `[driverTarget]`, so the shared fan-out loop degenerates to the
+   * The harnesses a global deploy fans out to: the explicit `harnesses` override (a `--harness`
+   * filter), else the explicit `global_harnesses:` of `~/.skaile/skaile.yaml`, else every harness
+   * whose root dir exists under `~` plus the harness the project is configured for (a project on
+   * a harness whose dir does not exist yet still gets its user-scope assets). In project mode
+   * this is exactly `[driverTarget]`, so the shared fan-out loop degenerates to the
    * single-target path.
    */
   targetHarnesses() {
     if (!this.global) return [this.driverTarget];
     if (this.harnessesOverride && this.harnessesOverride.length > 0) return this.harnessesOverride;
-    return resolveGlobalHarnesses();
+    const resolved = resolveGlobalHarnesses();
+    if (resolveGlobalSkWorkspaceConfig().global_harnesses?.length) return resolved;
+    const configured = resolveConfiguredDriverTarget(this.projectDir);
+    return configured && !resolved.includes(configured) ? [...resolved, configured] : resolved;
+  }
+  /**
+   * The harnesses `add` / `install` deploy into: `[driverTarget]` for a project, the global
+   * harness set (see {@link AssetManager.targetHarnesses}) for a global manager.
+   */
+  deployTargets() {
+    return this.targetHarnesses();
   }
   get storeCacheDir() {
     if (this.global) return join(globalCacheRoot(), "store");
@@ -1039,6 +1098,31 @@ var AssetManager = class {
     if (c.homepage != null) entry.homepage = c.homepage;
     return entry;
   }
+  /**
+   * The {@link ProvenanceCandidate} a source- or store-origin lock entry stands for: what a
+   * deploy needs to restore the asset from the commit the lock names (`files[]` is the asset's
+   * whole file set). `null` for a library-origin entry or a key that is not a canonical ref.
+   * The source URL is the declared source's own spelling (the bundled factory tree and a
+   * `sources:` entry match their declaration by it).
+   */
+  lockedCandidate(key, entry, repositories) {
+    if (!entry.source) return null;
+    const { publisher, kind, name, version } = parseCanonicalLockKey(key);
+    if (!publisher || !kind || !name) return null;
+    const url = entry.source.url;
+    const factory = Object.values(repositories).find((d) => d.factory);
+    const declared = factory?.url !== void 0 && normalizeRepoUrl(url) === normalizeRepoUrl(factory.url) ? factory : repositories[sourceCacheKey(url)];
+    return {
+      publisher,
+      kind,
+      name,
+      version: version ?? "",
+      sourceUrl: declared?.url ?? url,
+      commit: entry.source.commit,
+      files: entry.files,
+      sha256: entry.sha256
+    };
+  }
   /**
    * Resolve refs the source/store pass could not against the user's registered
    * **libraries** (local authoring places). Each library dir is scanned on disk
@@ -1071,6 +1155,7 @@ var AssetManager = class {
     const { byKey, isDefaultLib, libraryDir } = scan;
     const entries = [];
     const fileSets = /* @__PURE__ */ new Map();
+    const diskHashes = /* @__PURE__ */ new Map();
     let snap;
     const allCandidates = [...byKey.values()].flat();
     for (const ref of missing) {
@@ -1098,23 +1183,34 @@ var AssetManager = class {
       }
       let candidates = pool.filter((c) => !pin || matchPin(pin, c.entry.version ?? ""));
       let lockedLibrary;
+      const lockedMap = opts.preferLocked?.libraries ?? opts.lockedLibraries;
       if (parsed.publisher) {
-        lockedLibrary = opts.lockedLibraries?.get(
+        lockedLibrary = lockedMap?.get(
           `${parsed.kind}:${parsed.publisher.replace(/^@/, "")}/${parsed.name}`
         );
       } else {
-        const same = [...opts.lockedLibraries ?? []].filter(([k]) => {
+        const same = [...lockedMap ?? []].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) {
+      if (lockedLibrary && !opts.preferLocked) {
         const inLocked = candidates.filter((c) => c.library === lockedLibrary);
         if (inLocked.length > 0) candidates = inLocked;
       }
       if (candidates.length === 0) continue;
-      candidates.sort(libraryPreference(isDefaultLib));
+      const prefer = opts.preferLocked ? (c) => {
+        if (lockedLibrary && c.library === lockedLibrary) return 0;
+        const id = `${c.entry.kind}:${(c.entry.publisher ?? "").replace(/^@/, "")}/${c.entry.name}`;
+        const lockedSha = opts.preferLocked?.shas.get(id);
+        const libPath = libraryDir.get(c.library);
+        const onDisk = lockedSha && libPath ? libraryDiskHashes(libPath, diskHashes, this.registry).get(
+          `${c.entry.kind}:${c.entry.name}`
+        ) : void 0;
+        return onDisk !== void 0 && onDisk === lockedSha ? 1 : 2;
+      } : void 0;
+      candidates.sort(libraryPreference(isDefaultLib, prefer));
       const hit = candidates[0];
       if (!opts.quiet && !opts.library) {
         this.warnLibraryCollision(
@@ -1255,7 +1351,8 @@ var AssetManager = class {
     const cloneDirs = new Set(clones.map((c) => resolve(c.localPath)));
     const index = await buildProvenanceIndex(clones, {
       projectDir: this.projectDir,
-      knownKinds: this.knownKinds
+      knownKinds: this.knownKinds,
+      onSourceError: this.reportSourceError
     });
     const factoryUrl = normalizeRepoUrl(FACTORY_SOURCE_URL);
     const hasFactory = Object.values(repositories).some((d) => d.factory);
@@ -1464,6 +1561,34 @@ var AssetManager = class {
       publisher: ref?.publisher ?? entry.publisher?.replace(/^@/, "")
     };
   }
+  /**
+   * Refuse to lock a source commit another machine cannot check out. A commit made in the clone
+   * itself (or one `source sync` could not fast-forward past) is in no remote branch: the lock
+   * would name bytes nobody else has, and `install --locked` there could not restore them.
+   * Linked (dev-override) and user-owned local sources are never checked: their lock is
+   * machine-local by choice.
+   *
+   * @param resolved - Candidates about to be locked.
+   * @param repositories - Source declarations of the project.
+   * @throws With `<url> clone has unpublished commit <sha>` and the way out.
+   */
+  assertSourceCommitsPublished(resolved, repositories) {
+    const links = readLinks(this.projectDir);
+    const checked = /* @__PURE__ */ new Set();
+    for (const c of resolved) {
+      if (!c.commit || /^0+$/.test(c.commit) || checked.has(`${c.sourceUrl}@${c.commit}`)) continue;
+      checked.add(`${c.sourceUrl}@${c.commit}`);
+      const hit = Object.entries(repositories).find(
+        ([, d]) => d.url !== void 0 && !d.factory && d.url === c.sourceUrl
+      );
+      if (!hit || links[hit[0]]) continue;
+      const dir = this.resolveRepoDir(hit[1], hit[0]);
+      if (!dir || isCommitOnRemote(dir, c.commit)) continue;
+      throw new Error(
+        `${c.sourceUrl} clone has unpublished commit ${c.commit.slice(0, 7)} - push it, or reset the clone (git -C ${dir} reset --hard origin/${hit[1].branch ?? "main"}) - nothing was locked`
+      );
+    }
+  }
   /**
    * Refuse assets of one kind and name from different publishers: they deploy into the
    * same folder, so the later one would silently overwrite the earlier. Throws one line
@@ -1771,6 +1896,14 @@ var AssetManager = class {
     const found = this.lockedLibrary(origin, snap);
     return found.state === "ok" ? found.path : null;
   }
+  /**
+   * The `kind:@publisher/name` identities the lock holds for one `kind` and `name`, whatever
+   * their publisher. `diff` uses it to accept a ref without a publisher only when it names
+   * exactly one locked asset.
+   */
+  lockedRefsNamed(kind, name) {
+    return Object.keys(this.tryReadLock()?.assets ?? {}).map(parseCanonicalLockKey).filter((id) => id.kind === kind && id.name === name).map((id) => id.publisher ? `${kind}:@${id.publisher}/${name}` : `${kind}:${name}`);
+  }
   /**
    * Where each library-origin lock entry of this project resolves on this machine: identity
    * `kind:publisher/name` (no scope sigil, no version) → the name the locked library is
@@ -1800,6 +1933,19 @@ var AssetManager = class {
     }
     return out;
   }
+  /**
+   * What `update` prefers when libraries tie: the library each lock entry resolves to here
+   * ({@link lockedLibraryNames}, a `library rename` followed) and the sha256 it locked.
+   */
+  async lockedPreference() {
+    const shas = /* @__PURE__ */ new Map();
+    for (const [key, e] of Object.entries(this.tryReadLock()?.assets ?? {})) {
+      if (!e.library?.sha256 || e.library.installed) continue;
+      const { publisher, kind, name } = parseCanonicalLockKey(key);
+      if (publisher && kind && name) shas.set(`${kind}:${publisher}/${name}`, e.library.sha256);
+    }
+    return { libraries: await this.lockedLibraryNames(), shas };
+  }
   // ── Store fetch-then-deploy ────────────────────────────────────────────
   /** A candidate's stable identity key (`<publisher>/<kind>:<name>@<version>`). */
   candidateKey(c) {
@@ -1865,6 +2011,7 @@ var AssetManager = class {
     const resolved = [];
     const overridesApplied = /* @__PURE__ */ new Set();
     const presets = [];
+    const requiredBy = /* @__PURE__ */ new Map();
     const lib = { entries: [], resolved: /* @__PURE__ */ new Set(), libraryOf: /* @__PURE__ */ new Map() };
     const missing = /* @__PURE__ */ new Set();
     const seen = /* @__PURE__ */ new Set();
@@ -1913,6 +2060,13 @@ var AssetManager = class {
             return depId !== null && declaredById.get(depId) || dep;
           })
         );
+        if (e.kind !== "preset") {
+          for (const dep of deps2) {
+            const depId = refIdentity(dep);
+            if (depId !== null && declaredById.has(depId)) continue;
+            requiredBy.set(dep, [...requiredBy.get(dep) ?? [], canonicalEntryRef(e)]);
+          }
+        }
       }
       for (const r of hit.resolved) lib.resolved.add(r);
       return next;
@@ -1937,7 +2091,8 @@ var AssetManager = class {
       );
       const hit = await this.resolveLibraryEntries([...libraryTried], {
         quiet: !opts.warnCollisions,
-        lockedLibraries: opts.lockedLibraries
+        lockedLibraries: opts.lockedLibraries,
+        preferLocked: opts.preferLocked
       });
       const next = absorb(hit);
       const rest = fresh.filter((ref) => !hit.resolved.has(ref));
@@ -1954,7 +2109,11 @@ var AssetManager = class {
         presets.push(...r.presets);
         const hit2 = await this.resolveLibraryEntries(
           r.missing.filter((m) => !libraryTried.has(m)),
-          { quiet: !opts.warnCollisions, lockedLibraries: opts.lockedLibraries }
+          {
+            quiet: !opts.warnCollisions,
+            lockedLibraries: opts.lockedLibraries,
+            preferLocked: opts.preferLocked
+          }
         );
         next.push(...absorb(hit2));
         for (const m of r.missing) if (!hit2.resolved.has(m)) missing.add(m);
@@ -1965,7 +2124,7 @@ var AssetManager = class {
       const id = refIdentity(m);
       return !lib.resolved.has(m) && !(id !== null && covered.has(id));
     });
-    return { resolved, missing: stillMissing, overridesApplied, lib, presets };
+    return { resolved, missing: stillMissing, overridesApplied, lib, presets, requiredBy };
   }
   /** The catalog fetcher to use: an injected one, else built from `stores`. */
   storeFetcherFor(stores) {
@@ -1980,8 +2139,8 @@ var AssetManager = class {
     let url = this.catalogUrlOverride;
     if (url === void 0) {
       try {
-        const { resolveConfig } = await import('./library/index.js');
-        url = resolveConfig({ projectDir: this.projectDir }).catalog.url;
+        const { resolveConfig: resolveConfig2 } = await import('./library/index.js');
+        url = resolveConfig2({ projectDir: this.projectDir }).catalog.url;
       } catch {
         return [];
       }
@@ -2039,13 +2198,31 @@ var AssetManager = class {
         // from source.url@commit and ignores it, so "" is inert.
         tier: ""
       };
-      const { installPath } = await installFromManifest({
-        manifest,
-        libraryRoot: this.storeCacheDir,
-        targetDir,
-        fetcher: this.injectedAssetFetcher
+      const root = commonDirPrefix(c.files.map((f) => f.path));
+      const intact = c.files.every((f) => {
+        const rel = root && f.path.startsWith(`${root}/`) ? f.path.slice(root.length + 1) : f.path;
+        try {
+          return computeHash(join(targetDir, rel)) === f.sha256;
+        } catch {
+          return false;
+        }
       });
-      staged.set(this.candidateKey(c), join(installPath, this.stagedManifestRel(c)));
+      if (intact) {
+        staged.set(this.candidateKey(c), join(targetDir, this.stagedManifestRel(c)));
+        continue;
+      }
+      try {
+        const { installPath } = await installFromManifest({
+          manifest,
+          libraryRoot: this.storeCacheDir,
+          targetDir,
+          fetcher: this.injectedAssetFetcher
+        });
+        staged.set(this.candidateKey(c), join(installPath, this.stagedManifestRel(c)));
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`${manifest.ref} (${c.sourceUrl} at ${c.commit.slice(0, 7)}): ${reason}`);
+      }
     }
     return staged;
   }
@@ -2155,22 +2332,43 @@ var AssetManager = class {
     if (cloneError) return cloneError;
     const provenanceIndex = await buildProvenanceIndex(this.buildClones(repositories), {
       projectDir: this.projectDir,
-      knownKinds: this.knownKinds
+      knownKinds: this.knownKinds,
+      onSourceError: this.reportSourceError
+    });
+    const { resolved, missing, overridesApplied, lib, presets, requiredBy } = 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() }
     });
-    const { resolved, missing, overridesApplied, lib, presets } = 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 ? {} : { lockedLibraries: await this.lockedLibraryNames() }
-      }
-    );
     this.assertNoFolderCollision([...resolved, ...lib.entries.map((e) => this.entryIdentity(e))]);
+    this.assertSourceCommitsPublished(resolved, repositories);
     const stillMissing = missing.filter((m) => !lib.resolved.has(m));
+    const lockedKeys = new Set(Object.keys(this.tryReadLock()?.assets ?? {}));
+    const unmetByNew = /* @__PURE__ */ new Map();
+    for (const m of stillMissing) {
+      const newcomers = (requiredBy.get(m) ?? []).filter((parent) => !lockedKeys.has(parent));
+      if (newcomers.length > 0) unmetByNew.set(m, newcomers);
+    }
+    if (unmetByNew.size > 0) {
+      const hints = {};
+      for (const [m, parents] of unmetByNew) {
+        const requirer = parents.map((p) => p.split("#")[0]).join(", ");
+        hints[m] = ` is required by ${requirer} (not found \u2014 ${REGISTER_HOLDER}, or drop ${requirer} with \`skaile remove ${parents[0].split("#")[0]}\`) \u2014 nothing was installed`;
+      }
+      return {
+        deployed: [],
+        removed: [],
+        missing: [...unmetByNew.keys()],
+        missingHints: hints,
+        lockWritten: false,
+        npmInstalled: [],
+        npmFailed: []
+      };
+    }
     const missingHints = await this.publisherChangeHints(stillMissing);
     const prevLock = this.tryReadLock();
     const kept = keptLockEntries(prevLock, stillMissing);
@@ -2203,7 +2401,7 @@ var AssetManager = class {
         )
       )
     ];
-    const restored = this.restoredCopies(copyDrift, deployed);
+    let restored = this.restoredCopies(copyDrift, deployed);
     await this.renderDriverMcpConfig();
     const agentRender = await this.renderAgentInstances();
     const lockWanted = resolved.length > 0 || lib.entries.length > 0 || existsSync(this.lockPath);
@@ -2213,6 +2411,7 @@ var AssetManager = class {
     if (lockWanted) {
       const lockData = withKeptLockEntries(freshLock, kept);
       relocked = relockedRefs(prevLock, lockData);
+      restored = [...restored, ...this.removeExcludedLeftovers(relocked)];
       moved = libraryMoves(prevLock, libraryLock);
       lockWritten = writeLock(this.lockPath, lockData);
     }
@@ -2273,7 +2472,8 @@ var AssetManager = class {
     const { kind, name, publisher } = id;
     const component = kind ? this.installTarget(kind) : void 0;
     if (!kind || !name || !component) return [];
-    const dir = deployedDir(component, name, this.driverTarget, this.global, this.projectDir);
+    const keptAgent = kind === "agent" && !this.global ? join(agentSourceCacheDir(this.projectDir), name) : null;
+    const dir = keptAgent && existsSync(keptAgent) ? keptAgent : deployedDir(component, name, this.driverTarget, this.global, this.projectDir);
     if (!existsSync(dir)) return [];
     try {
       const scanned = await scanDirectory(dir, publisher ?? "", { knownKinds: this.knownKinds });
@@ -2397,13 +2597,33 @@ var AssetManager = class {
       return null;
     }
   }
+  /**
+   * A catalog client for `storeUrl` that honours `catalog.cache_ttl` (`0` = air-gapped: no
+   * network, so every lookup that is not cached throws `OfflineError`).
+   */
+  remoteStore(storeUrl) {
+    let cacheTtlMs;
+    try {
+      cacheTtlMs = resolveConfig({ projectDir: this.projectDir }).catalog.cache_ttl * 1e3;
+    } catch {
+    }
+    return new RemoteCatalogSource({ baseUrl: storeUrl, cacheTtlMs });
+  }
+  /**
+   * Remember why a store could not be asked (store URL → one line without a JS error class
+   * name), so `add` can say `store unreachable` instead of a bare `Asset not found`.
+   */
+  noteStoreFailure(storeUrl, err) {
+    const text = err instanceof OfflineError ? `${storeUrl}: air-gapped (catalog.cache_ttl: 0), the store was not asked` : describeCatalogError(err, storeUrl);
+    this.storeFailures.set(storeUrl, text);
+    return text;
+  }
   /** Build a store fetcher from the configured stores, or undefined when none. */
   buildStoreFetcher(stores) {
     if (stores.length === 0) return void 0;
     return {
       getInstallManifest: async (storeUrl, ref) => {
-        const { RemoteCatalogSource, CatalogHttpError } = await import('./library/index.js');
-        const src = new RemoteCatalogSource({ baseUrl: storeUrl });
+        const src = this.remoteStore(storeUrl);
         try {
           const m = await src.getInstallManifest(ref);
           let deps;
@@ -2416,7 +2636,7 @@ var AssetManager = class {
             else if (deps === void 0)
               gap = `has a cached catalog row for ${ref} without dependencies`;
           } catch (err) {
-            gap = `dependency lookup for ${ref} failed \u2014 ${err}`;
+            gap = `dependency lookup for ${ref} failed \u2014 ${describeCatalogError(err, storeUrl)}`;
           }
           if (gap) {
             console.warn(`skaile: store ${storeUrl} ${gap}; installing without its dependencies`);
@@ -2430,23 +2650,23 @@ var AssetManager = class {
           };
         } catch (err) {
           if (err instanceof CatalogHttpError && err.status === 404) return null;
+          this.noteStoreFailure(storeUrl, err);
           throw err;
         }
       },
       getCanonicalDigest: async (storeUrl, ref) => {
-        const { RemoteCatalogSource } = await import('./library/index.js');
-        const src = new RemoteCatalogSource({ baseUrl: storeUrl });
+        const src = this.remoteStore(storeUrl);
         return src.getCanonicalDigest(ref);
       },
       listVersions: async (storeUrl, ref) => {
-        const { RemoteCatalogSource } = await import('./library/index.js');
-        const src = new RemoteCatalogSource({ baseUrl: storeUrl });
+        const src = this.remoteStore(storeUrl);
         try {
           return await src.listVersions(ref);
         } catch (err) {
+          const text = this.noteStoreFailure(storeUrl, err);
           if (!this.warnedStoreVersionLookups.has(storeUrl)) {
             this.warnedStoreVersionLookups.add(storeUrl);
-            console.warn(`skaile: store ${storeUrl} version lookup for ${ref} failed \u2014 ${err}`);
+            console.warn(`skaile: store lookup of ${ref} failed: ${text}`);
           }
           return [];
         }
@@ -2522,20 +2742,46 @@ var AssetManager = class {
     this.assertNoFolderCollision(Object.keys(lock.assets).map(parseCanonicalLockKey));
     const declBySlug = new Map(Object.entries(repositories));
     const factoryUrl = normalizeRepoUrl(FACTORY_SOURCE_URL);
-    const factoryDir = Object.values(repositories).find((d) => d.factory)?.path ?? null;
+    const factoryDecl = Object.values(repositories).find((d) => d.factory);
+    const factoryDir = factoryDecl?.path ?? null;
+    const isFactoryUrl = (url) => factoryDir !== null && normalizeRepoUrl(url) === factoryUrl;
+    const unavailable = [];
     for (const src of lock.sources) {
-      if (factoryDir && normalizeRepoUrl(src.url) === factoryUrl) continue;
+      if (isFactoryUrl(src.url)) continue;
       const slug = sourceCacheKey(src.url);
-      const decl = declBySlug.get(slug) ?? { url: src.url };
-      ensureRepo(decl, slug, this.reposDir, { projectDir: this.projectDir, pin: src.commit });
+      const declared = declBySlug.get(slug);
+      if (!declared && GITHUB_REPO_URL.test(src.url)) continue;
+      try {
+        const dir = ensureRepo(declared ?? { url: src.url }, slug, this.reposDir, {
+          projectDir: this.projectDir,
+          // A lock restore deploys the pinned commit's bytes or fails: never another commit's.
+          .../^0*$/.test(src.commit) ? {} : { pin: src.commit, strictPin: true }
+        });
+        if (!declared) repositories[slug] = { url: src.url, path: dir };
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        unavailable.push(`unavailable: ${src.url} at ${src.commit.slice(0, 7)} (${reason})`);
+      }
+    }
+    if (unavailable.length > 0) {
+      throw new Error(`Lock file verification failed:
+  ${unavailable.join("\n  ")}`);
+    }
+    const candidates = [];
+    const cloneOrigin = {};
+    for (const [key, entry] of Object.entries(lock.assets)) {
+      const candidate = this.lockedCandidate(key, entry, repositories);
+      if (!candidate) continue;
+      candidates.push(candidate);
+      if (isFactoryUrl(candidate.sourceUrl) || this.candidateHasLocalBytes(candidate, repositories)) {
+        cloneOrigin[key] = entry;
+      }
     }
-    const resolveCloneDir = (sourceUrl) => {
-      if (factoryDir && normalizeRepoUrl(sourceUrl) === factoryUrl) return factoryDir;
+    const verification = verifyLock({ ...lock, assets: cloneOrigin }, (sourceUrl) => {
+      if (isFactoryUrl(sourceUrl)) return factoryDir;
       const slug = sourceCacheKey(sourceUrl);
-      const decl = declBySlug.get(slug) ?? { url: sourceUrl };
-      return this.resolveRepoDir(decl, slug);
-    };
-    const verification = verifyLock(lock, resolveCloneDir);
+      return this.resolveRepoDir(repositories[slug] ?? { url: sourceUrl }, slug);
+    });
     if (!verification.ok) {
       const issues = [
         ...verification.drifted.map((r) => `drifted: ${r}`),
@@ -2554,28 +2800,13 @@ var AssetManager = class {
   ${lines.join("\n  ")}`
       );
     }
-    const resolved = [];
-    for (const [ref, entry] of Object.entries(lock.assets)) {
-      if (!entry.source) continue;
-      const { publisher, kind, name } = parseCanonicalLockKey(ref);
-      if (!publisher || !kind || !name) continue;
-      const slug = sourceCacheKey(entry.source.url);
-      const cloneDir = resolveCloneDir(entry.source.url) ?? join(this.reposDir, slug);
-      const mdRel = entry.files.find((f) => /\.(md|yaml)$/i.test(f.path))?.path ?? entry.files[0]?.path ?? "";
-      resolved.push({
-        name,
-        kind,
-        description: "",
-        source: mdRel ? join(cloneDir, mdRel) : cloneDir,
-        // Keep the publisher label slash-free (repo name), not the full cache key.
-        publisher: sourceShortName(entry.source.url),
-        version: entry.source.commit,
-        // The lock key is the canonical ref; `publisher` above is only a clone label.
-        canonicalRef: ref,
-        requires: [],
-        dependencies: []
-      });
-      if (!repositories[slug]) repositories[slug] = { url: entry.source.url, path: cloneDir };
+    let resolved;
+    try {
+      resolved = await this.buildCatalogEntries(candidates, repositories);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      throw new Error(`Lock file verification failed:
+  ${reason}`);
     }
     const library = await this.restoreLibraryLockEntries(lock);
     const copyDrift = await this.lockedCopyDrift();
@@ -2664,7 +2895,8 @@ var AssetManager = class {
       this.ensureSourceClonesQuiet(repositories, sources);
       const index = await buildProvenanceIndex(this.buildClones(repositories), {
         projectDir: this.projectDir,
-        knownKinds: this.knownKinds
+        knownKinds: this.knownKinds,
+        onSourceError: this.reportSourceError
       });
       for (const candidates of index.values()) for (const c of candidates) note(c);
       for (const { entry } of await this.libraryAssets()) note(entry);
@@ -2699,11 +2931,19 @@ var AssetManager = class {
     this.ensureSourceClonesQuiet(repositories, sources);
     const provenanceIndex = await buildProvenanceIndex(this.buildClones(repositories), {
       projectDir: this.projectDir,
-      knownKinds: this.knownKinds
+      knownKinds: this.knownKinds,
+      onSourceError: this.reportSourceError
     });
     const { resolved, missing, overridesApplied, lib, presets } = await this.resolveLibraryFirst(
       [ref],
-      { provenanceIndex, overrides, stores, declaredRefs: dependencies, warnCollisions: true }
+      {
+        provenanceIndex,
+        overrides,
+        stores,
+        declaredRefs: dependencies,
+        warnCollisions: true,
+        ...opts?.preferLockedLibrary ? { preferLocked: await this.lockedPreference() } : {}
+      }
     );
     if (resolved.length === 0 && lib.entries.length === 0 && presets.length === 0) {
       const snap = await this.loadLibraryIndex();
@@ -2721,6 +2961,12 @@ var AssetManager = class {
           );
         }
       }
+      const unreachable = [...this.storeFailures.values()];
+      if (unreachable.length > 0) {
+        throw new Error(
+          `Store unreachable \u2014 ${ref} was not looked up: ${unreachable.join("; ")}. Check the URL with \`skaile catalog test\`; a library or source can still hold the asset.`
+        );
+      }
       throw new Error(
         `Asset not found: ${ref}${(await this.publisherChangeHints([ref]))[ref] ?? ""}${missing.length ? ` (missing: ${missing.join(", ")})` : ""}`
       );
@@ -2742,6 +2988,7 @@ var AssetManager = class {
         }
       }
     }
+    this.assertSourceCommitsPublished(resolved, repositories);
     this.assertNoFolderCollision(
       [...resolved, ...lib.entries.map((e) => this.entryIdentity(e))],
       [
@@ -3542,12 +3789,12 @@ var AssetManager = class {
     return out;
   }
   /**
-   * Library-locked assets whose deployed directory lacks files the deploy writes —
-   * a deleted `build.py` / `scripts/` helper next to an intact `SKILL.md`. The
-   * expected set is the library entry's file set (every file under its manifest
-   * `root:`), the same bytes the lock hashes; only presence is checked, so a
-   * local edit never counts. An asset with no deployed directory is not listed
-   * (`listDeclared` reports it as drift); an agent is rendered, not copied, so it
+   * Locked assets whose deployed directory lacks files the deploy writes — a deleted
+   * `build.py` / `scripts/` helper next to an intact `SKILL.md`. The expected set is the file
+   * set the lock covers: a library entry's files (every file under its manifest `root:`), a
+   * source or store entry's `files[]` (the asset's whole file set at the locked commit). Only
+   * presence is checked, so a local edit never counts. An asset with no deployed directory is
+   * not listed (`listDeclared` reports it as drift); an agent is rendered, not copied, so it
    * has no file mirror to compare. `skaile install` restores what is listed.
    *
    * @returns One {@link IncompleteDeploy} per affected asset; empty when healthy
@@ -3556,10 +3803,25 @@ var AssetManager = class {
   async incompleteDeploys() {
     const lock = this.tryReadLock();
     if (!lock) return [];
+    const out = [];
+    const { patches } = this.loadConfig();
+    for (const [key, entry] of Object.entries(lock.assets)) {
+      if (!entry.source || entry.files.length === 0) continue;
+      const { publisher, kind, name } = parseCanonicalLockKey(key);
+      const component = kind ? this.installTarget(kind) : void 0;
+      if (!publisher || !kind || !name || !component || component === "agent") continue;
+      if (patches[`${kind}:${name}`]) continue;
+      const dest = join(
+        deployedBase(component, this.driverTarget, this.global, this.projectDir),
+        name
+      );
+      if (!existsSync(dest) || lstatSync(dest).isSymbolicLink()) continue;
+      const missing = lockedAssetFiles(kind, entry.files).map((f) => f.rel).filter((rel) => !existsSync(join(dest, rel)));
+      if (missing.length > 0) out.push({ ref: `${kind}:@${publisher}/${name}`, missing });
+    }
     const locked = Object.entries(lock.assets).filter(([, e]) => e.library !== void 0 && !e.library.installed).map(([key]) => key);
-    if (locked.length === 0) return [];
+    if (locked.length === 0) return out;
     const lib = await this.resolveLibraryEntries(locked, { quiet: true });
-    const out = [];
     for (const entry of lib.entries) {
       const component = this.installTarget(entry.kind);
       if (!entry.files || !component || component === "agent") continue;
@@ -3900,7 +4162,17 @@ var AssetManager = class {
         if (!kind || !name) continue;
         const lockedCommit = entry.source.commit || src.commit;
         const moved = lockedCommit && !/^0+$/.test(lockedCommit) && lockedCommit !== status.localHead ? commitsBetween(clone, lockedCommit, status.localHead, commitCounts) : 0;
-        const behind = status.behind + moved;
+        let behind = status.behind + moved;
+        if (behind > 0) {
+          const touching = commitsTouching(
+            clone,
+            COMMIT_ID.test(lockedCommit) && !/^0+$/.test(lockedCommit) ? lockedCommit : status.localHead,
+            status.behind > 0 && status.remoteHead ? status.remoteHead : status.localHead,
+            lockedAssetDir(kind, entry.files),
+            commitCounts
+          );
+          if (touching !== null) behind = touching;
+        }
         if (behind <= 0) continue;
         result.push({
           kind,
@@ -4018,6 +4290,37 @@ var AssetManager = class {
     }
     return null;
   }
+  /**
+   * The deploy entry of a source- or store-origin asset, carrying the file set its lock entry
+   * lists (so a missing or edited helper shows in `diff`, not only the manifest). A source asset
+   * reads from its clone; a store asset from the bytes `add`/`install` staged in the project
+   * store cache. `null` when the lock has no such entry or its bytes are not on disk.
+   *
+   * @param want - Kind, name and optional publisher of the asset.
+   */
+  lockedSourceEntry(want) {
+    const { repositories } = this.loadConfig();
+    for (const [key, e] of Object.entries(this.tryReadLock()?.assets ?? {})) {
+      const id = parseCanonicalLockKey(key);
+      if (!e.source || id.kind !== want.kind || id.name !== want.name) continue;
+      if (want.publisher && id.publisher !== want.publisher) continue;
+      const c = this.lockedCandidate(key, e, repositories);
+      if (!c) continue;
+      if (this.candidateHasLocalBytes(c, repositories)) {
+        return this.candidateToCatalogEntry(c, repositories);
+      }
+      const staged = join(
+        this.storeCacheDir,
+        c.publisher,
+        c.kind,
+        c.name,
+        c.version,
+        this.stagedManifestRel(c)
+      );
+      if (existsSync(staged)) return this.stagedCandidateToEntry(c, staged);
+    }
+    return null;
+  }
   /**
    * Produce a unified diff from the deployed asset to its catalog source: `-` lines
    * are in the deployed copy only (local edits `update` would overwrite), `+` lines
@@ -4035,8 +4338,15 @@ var AssetManager = class {
   async diff(ref) {
     const parsed = parseRefTolerant(ref);
     if (!parsed) return { status: "not-found" };
-    const entry = await this.lockedLibraryEntry(parsed) ?? await this.info(ref);
+    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(/^@/, "");
+    if (wantPublisher) {
+      const lockedHere = Object.keys(this.tryReadLock()?.assets ?? {}).map(parseCanonicalLockKey).filter((id) => id.kind === parsed.kind && id.name === parsed.name);
+      if (lockedHere.length > 0 && !lockedHere.some((id) => id.publisher === wantPublisher)) {
+        return { status: "not-deployed" };
+      }
+    }
     const component = this.installTarget(parsed.kind);
     if (parsed.kind === "preset" && this.presetRecorded(parsed)) return { status: "no-files" };
     if (!component) return { status: "not-deployed" };
@@ -4079,7 +4389,8 @@ var AssetManager = class {
     this.ensureSourceClonesQuiet(repositories, sources);
     const provenanceIndex = await buildProvenanceIndex(this.buildClones(repositories), {
       projectDir: this.projectDir,
-      knownKinds: this.knownKinds
+      knownKinds: this.knownKinds,
+      onSourceError: this.reportSourceError
     });
     const { resolved, overridesApplied, lib } = await this.resolveLibraryFirst(dependencies, {
       provenanceIndex,
@@ -4206,7 +4517,11 @@ var AssetManager = class {
       const full = await this.info(
         publisher ? `${entry.kind}:@${publisher}/${entry.name}` : `${entry.kind}:${entry.name}`
       );
-      if (!full) {
+      const restorable = !full && publisher !== void 0 && Object.entries(lock?.assets ?? {}).some(([key, e]) => {
+        const id = parseCanonicalLockKey(key);
+        return e.source !== void 0 && id.kind === entry.kind && id.name === entry.name && id.publisher === publisher;
+      });
+      if (!full && !restorable) {
         if (publisher) {
           const canonical = `${entry.kind}:@${publisher}/${entry.name}`;
           const fix = (await this.unresolvedFixes([canonical])).get(canonical);
@@ -4222,8 +4537,9 @@ var AssetManager = class {
         }
         continue;
       }
+      const declaredRequires = full ? full.requires : (await this.deployedRequirementsOf({ ...entry, publisher })).map(parseDep);
       const gaps = [];
-      const requirements = dedupeRequirements(full.requires, publisher).map(
+      const requirements = dedupeRequirements(declaredRequires, publisher).map(
         (r) => r.publisher || !publisher ? r : { ...r, publisher }
       );
       for (const req of requirements) {
@@ -4332,8 +4648,8 @@ var AssetManager = class {
           type: "requires",
           ref: dep,
           asset,
-          reason: `is required by ${asset} but neither deployed nor locked (fixable)`,
-          message: `${asset} requires ${dep} (fixable)`
+          reason: `is required by ${asset} but neither deployed nor locked (run skaile install)`,
+          message: `${asset} requires ${dep} (run skaile install)`
         });
       } else {
         const fix = requirementNoHolderFix(asset);
@@ -4378,6 +4694,25 @@ var AssetManager = class {
       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}` });
     }
+    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({
+        type: "source",
+        ref: s.url,
+        reason,
+        message: `source ${s.url} ${reason}`,
+        manualFix: true
+      });
+    }
     for (const u of unboundAgentInstances(this.projectDir, this.driverTarget)) {
       const reason = u.ref.startsWith("agent:") ? await this.unboundAgentReason(u.id, u.ref) : `is bound by agent instance "${u.id}" but resolves to no agent.yaml \u2014 fix the path, or drop the binding from skaile.yaml`;
       gaps.push({
@@ -4411,7 +4746,18 @@ var AssetManager = class {
    */
   async unboundAgentAdvice(ref) {
     const drop = "or drop the binding from skaile.yaml";
-    const publisher = parseRefTolerant(ref)?.publisher;
+    const parsedRef = parseRefTolerant(ref);
+    const publisher = parsedRef?.publisher;
+    const lockedAgent = Object.keys(this.tryReadLock()?.assets ?? {}).some((key) => {
+      const k = parseCanonicalLockKey(key);
+      return k.kind === "agent" && k.name === parsedRef?.name && (!publisher || !k.publisher || k.publisher === publisher);
+    });
+    if (lockedAgent) {
+      return {
+        lead: "the agent is locked but not restored here",
+        advice: `run \`skaile install --locked\` first, ${drop}`
+      };
+    }
     if (publisher && await this.info(ref) !== null) {
       return {
         lead: "no agent was added for it",
@@ -4458,6 +4804,52 @@ var AssetManager = class {
       (g) => names(g.ref) || g.asset && names(g.asset)
     );
   }
+  /**
+   * The {@link ProjectState} gaps of everything `ref` requires, transitively: what `check`
+   * says about the requirements of `ref`, so a command that answers for one asset (`diff`)
+   * does not call it fine while a requirement of it is broken. The requirements are read from
+   * the deployed copies (the lock records no edges), the way `remove` and `install` read them
+   * when no library holds the asset any more. The gaps of `ref` itself are not included
+   * ({@link gapsOf}).
+   *
+   * @param ref - Asset ref in `kind:name` or `kind:@publisher/name` form.
+   */
+  async requirementGapsOf(ref) {
+    const want = parseRefTolerant(ref);
+    if (!want) return [];
+    const gaps = (await this.projectState()).gaps;
+    const lockedIds = Object.keys(this.tryReadLock()?.assets ?? {}).map(parseCanonicalLockKey);
+    const idKey = (id) => `${id.publisher ?? ""}/${id.kind}:${id.name}`;
+    const seen = /* @__PURE__ */ new Set();
+    const queue = [
+      {
+        kind: want.kind,
+        name: want.name,
+        publisher: want.publisher?.replace(/^@/, "") ?? lockedIds.find((l) => l.kind === want.kind && l.name === want.name)?.publisher
+      }
+    ];
+    seen.add(idKey(queue[0]));
+    const out = [];
+    for (const asset of queue) {
+      for (const dep of await this.deployedRequirementsOf(asset)) {
+        const id = memberIdentity(dep);
+        if (!id) continue;
+        const publisher = id.publisher ?? lockedIds.find((l) => l.kind === id.kind && l.name === id.name)?.publisher;
+        const next = { kind: id.kind, name: id.name, publisher };
+        if (seen.has(idKey(next))) continue;
+        seen.add(idKey(next));
+        queue.push(next);
+        for (const g of gaps) {
+          if (out.includes(g)) continue;
+          const p = parseRefTolerant(g.ref);
+          if (p !== null && p.kind === next.kind && p.name === next.name && (!publisher || !p.publisher || p.publisher.replace(/^@/, "") === publisher)) {
+            out.push(g);
+          }
+        }
+      }
+    }
+    return out;
+  }
   /**
    * Locked library assets whose library cannot supply them: the library is not registered
    * (renamed or removed) or no longer holds the asset. Another library holding it makes the
@@ -4523,6 +4915,28 @@ var AssetManager = class {
     }
     return gaps;
   }
+  /**
+   * Remove the files a deploy never writes (`.env`, `.venv/`, `.pytest_cache/`, ...) from the
+   * deployed folders of re-locked assets, as {@link RestoredAsset} rows. The lock covers what
+   * the exclusion list leaves; the extras an older release copied are the owner's to drop, and
+   * this is the one point where they are: the lock was just rewritten.
+   *
+   * @param refs - Lock keys the install re-locked (hash or commit changed).
+   */
+  removeExcludedLeftovers(refs) {
+    const out = [];
+    for (const key of refs) {
+      const { kind, name } = parseCanonicalLockKey(key);
+      const component = kind ? this.installTarget(kind) : void 0;
+      if (!kind || !name || !component || component === "agent") continue;
+      const dest = deployedDir(component, name, this.driverTarget, this.global, this.projectDir);
+      const removed = removeExcludedLeftovers(dest);
+      if (removed.length === 0) continue;
+      const dir = relative(this.projectDir, dest).split(sep).join("/");
+      out.push({ ref: key, restored: [], removed: removed.map((f) => `${dir}/${f}`) });
+    }
+    return out;
+  }
   /**
    * 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.
@@ -4601,25 +5015,14 @@ var AssetManager = class {
       } 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);
+      for (const f of lockedAssetFiles(kind, entry.files)) {
+        const deployedFile = join(dest, f.rel);
         if (!existsSync(deployedFile)) continue;
         try {
-          if (computeHash(deployedFile) !== f.sha256) modified.push(rel);
+          if (computeHash(deployedFile) !== f.sha256) modified.push(f.rel);
         } catch {
-          modified.push(rel);
+          modified.push(f.rel);
         }
       }
       if (modified.length > 0)
@@ -4768,7 +5171,8 @@ var AssetManager = class {
     const { repositories } = this.loadConfig();
     const provenanceIndex = await buildProvenanceIndex(this.buildClones(repositories), {
       projectDir: this.projectDir,
-      knownKinds: this.knownKinds
+      knownKinds: this.knownKinds,
+      onSourceError: this.reportSourceError
     });
     const lockKeys = Object.keys(lock.assets).map(parseCanonicalLockKey);
     const sourceCandidate = (ref) => {
@@ -5076,5 +5480,5 @@ var AssetManager = class {
 };
 
 export { AssetManager, FACTORY_SOURCE_URL, MissingManifestError, installAgentInstances, normalizeRepoUrl, parseCanonicalLockKey, parseRefTolerant, renderMcpServerConfig, softDepName };
-//# sourceMappingURL=chunk-DZMNFCWB.js.map
-//# sourceMappingURL=chunk-DZMNFCWB.js.map
+//# sourceMappingURL=chunk-TVAR4JHA.js.map
+//# sourceMappingURL=chunk-TVAR4JHA.js.map