@skaile/workspaces 6.0.0 → 6.2.0

package/dist/asset-manager/src/index.d.ts

@@ -11,8 +11,9 @@
  */
 import type { AssetRef, CatalogEntry, HarnessName, LockFile, StoreFetcher } from "@skaile/workspaces/core";
 import type { IAssetKindRegistry } from "@skaile/workspaces/plugins";
+import { FACTORY_SOURCE_URL } from "@skaile/workspaces/core";
 import type { PresetExpansion } from "@skaile/workspaces/core";
-import type { AssetFetcher } from "@skaile/workspaces/library";
+import type { AssetFetcher, Library } from "@skaile/workspaces/library";
 import type { HistoryEntry } from "./history.js";
 import { type InstalledAgentInstance } from "./install-instances.js";
 import type { ScaffoldOptions } from "./installer.js";
@@ -24,6 +25,36 @@ import { type DeployableEntry } from "./installer.js";
  * explicit user declaration.
  */
 export declare function normalizeRepoUrl(url: string): string;
+/**
+ * The checks one library asset must pass before `add` deploys it, as the lines `skaile validate`
+ * prints for it (`<file> [<tag>] - <text>`). The asset manager does not know the per-kind checks
+ * (they live with `validate`), so the host registers them once at startup; none registered means
+ * `add` runs no such check (library use without the CLI). An asset the check refuses is never
+ * deployed, as one the manifest does not list is not (p1550).
+ */
+export type LibraryAssetCheck = (asset: {
+    kind: string;
+    name: string;
+    source: string;
+}, libraryPath: string) => string[];
+/** Register (or with `undefined`, remove) the {@link LibraryAssetCheck} `add` runs per library asset. */
+export declare function setLibraryAssetCheck(check: LibraryAssetCheck | undefined): void;
+/**
+ * A first-party manifest entry of a library whose asset file now names another asset (`name:`, a
+ * flow's `id:`), before `library index` renamed the entry: `publisher` is the entry's own or the
+ * manifest's, `file` the asset file relative to the library and `now` the name it carries.
+ */
+export interface RenamedLibraryEntry {
+    kind: string;
+    name: string;
+    publisher?: string;
+    file: string;
+    now: string;
+}
+/** The {@link RenamedLibraryEntry}s of the library at `libraryPath`. Registered by the host, as {@link LibraryAssetCheck}. */
+export type RenamedEntryLookup = (libraryPath: string) => RenamedLibraryEntry[];
+/** Register (or with `undefined`, remove) the {@link RenamedEntryLookup} `add` asks when a ref resolves to nothing (p1603). */
+export declare function setRenamedEntryLookup(lookup: RenamedEntryLookup | undefined): void;
 /** One row of {@link AssetManager.libraryHolders}: a library holding a ref at one version. */
 export interface LibraryHolder {
     library: string;
@@ -64,6 +95,12 @@ export declare function parseCanonicalLockKey(key: string): {
     name?: string;
     version?: string;
 };
+/**
+ * Replace the `diff -u` timestamps of the `---` / `+++` header lines with a label of the side
+ * (`--- <file> (deployed)`, `+++ <file> (library)`). A file that is missing on one side shows
+ * the epoch there (`1970-01-01`), which says nothing a reader wants (p1693).
+ */
+export declare function labelDiffHeaders(diff: string, from: string, to: string): string;
 /**
  * Bare asset name of a soft-dep target ref (`@pub/name@ver` → `name`); splits the
  * version off the *last* `@` since the leading one is the scope sigil. The
@@ -96,6 +133,22 @@ export interface LibraryMove {
     /** Library name the asset resolved from now. */
     to: string;
 }
+/** One asset a `skaile add --dry-run` would deploy. */
+export interface AddPlanItem {
+    /** `kind:@publisher/name`. */
+    ref: string;
+    version: string;
+    /** `library <name>`, `source <name>`, `factory` or `store`. */
+    origin: string;
+    /** True for the asset that was asked for; false for a dependency it pulls. */
+    requested: boolean;
+    /** Deploy folders per harness target (project-relative, or `~`-relative for a global add). Empty for an agent. */
+    folders: string[];
+    /** Files of the asset, relative to its folder, when the resolver knows them. Empty for an agent. */
+    files: string[];
+    /** The native agent files each harness target gets, for an agent: it is rendered, not copied (p1621). */
+    renders: string[];
+}
 /**
  * Reconciliation state of a declared dependency relative to the lock + disk.
  * `invalid` flags a `dependencies:` entry that isn't a parseable canonical ref —
@@ -134,9 +187,19 @@ export interface IncompleteDeploy {
     missing: string[];
 }
 /**
- * A tracked asset whose copy still sits in the previous default deploy dir
- * (`.claude/…`) although the project now deploys to another harness. See
- * {@link AssetManager.listLegacyClaudeDeployed}.
+ * A tracked asset whose copy still sits in the project dirs of a harness the
+ * project no longer deploys to. See {@link AssetManager.listStaleHarnessCopies}.
+ */
+export interface StaleHarnessCopy {
+    /** The harness whose dir holds the stale copy. */
+    harness: HarnessName;
+    kind: string;
+    name: string;
+    /** Absolute path of the stale copy. */
+    path: string;
+}
+/**
+ * @deprecated Use {@link StaleHarnessCopy}, which also names the harness of the stale copy.
  */
 export interface LegacyDeployedAsset {
     kind: string;
@@ -194,7 +257,7 @@ export type { DeployOptions, ScaffoldOptions } from "./installer.js";
 export type { DeployableEntry } from "./installer.js";
 export { createScaffold, deployAll, installTargetOf, removeAsset, SCAFFOLD_KINDS, } from "./installer.js";
 export type { RenderMcpConfigOptions, RenderMcpConfigResult, SkippedMcpServer, } from "./mcp-config.js";
-export { renderMcpServerConfig } from "./mcp-config.js";
+export { mcpNotRunnableReason, renderMcpServerConfig } from "./mcp-config.js";
 export type { Log } from "./renderers.js";
 export { renderAgentToFramework } from "./renderers.js";
 /**
@@ -317,6 +380,14 @@ export interface InstallResult {
      * content. A re-lock can happen with nothing to deploy. Absent when none changed.
      */
     relocked?: string[];
+    /**
+     * Global entries a 5.12.0 record left without a harness subset, now limited to the one harness
+     * that holds their copy (`ref` is `kind:@publisher/name`). Absent when nothing was inferred.
+     */
+    inferredHarnesses?: Array<{
+        ref: string;
+        harnesses: HarnessName[];
+    }>;
     /**
      * Library-origin assets whose lock entry now names another library than before. `install`
      * keeps a locked asset on its library; only `update`, a pin, or a locked library that no
@@ -335,6 +406,12 @@ export interface InstallResult {
      * POSIX paths. Absent when every deployed copy already matched.
      */
     restored?: RestoredAsset[];
+    /**
+     * One line per locked library that is not registered here but whose assets `install --locked`
+     * restored from the lock `url:` with the locked hash: the notice that the library is not
+     * registered, and how to register it. Not a failure: `missing` stays empty (OQ8, p1655).
+     */
+    libraryNotices?: string[];
     /**
      * Rendered agent files that a lock without `rendered:` entries (written by a CLI before
      * 5.12.0) did not cover and that this run wrote with other content, because the render of
@@ -511,6 +588,12 @@ export interface RemoveResult {
         refs: string[];
         paths: string[];
     }[];
+    /**
+     * `mcp_servers` entries of `skaile.yaml` that were dropped with a removed `mcp-server` because
+     * they only set values for it (an `env` override with no `command` or `url` of its own), as
+     * `mcp_servers entry "<id>"`. An entry that can run alone stays.
+     */
+    droppedSettings?: string[];
 }
 /**
  * A missing dependency detected by `AssetManager.doctor()`.
@@ -557,6 +640,8 @@ export interface LockGap {
     message: string;
     /** Set when `skaile install` cannot fix the gap; `reason` then names what to change instead. */
     manualFix?: true;
+    /** Set on the gap of a `sources:` entry whose clone the walk could not read. `install --locked` restores from the lock alone, so it does not count that as missing. */
+    unreadableSource?: true;
 }
 /**
  * The project's state as {@link AssetManager.projectState} computes it: the one verdict
@@ -684,10 +769,7 @@ export interface AssetManagerOptions {
      */
     verboseCollisions?: boolean;
 }
-/** Canonical git URL identity for the bundled factory source. Never fetched —
- * the bytes live inside the package (`factory-assets/`); the URL is only the
- * match key the provenance walker and `candidateToCatalogEntry` key off. */
-export declare const FACTORY_SOURCE_URL = "https://github.com/skaile-ai/ai-assets";
+export { FACTORY_SOURCE_URL };
 /**
  * Programmatic API for managing AI assets in a Skaile workspace.
  *
@@ -787,11 +869,41 @@ export declare class AssetManager {
     private entryHarnessRecord;
     /** Keep the entries a recorded `--harness` limit sends to `target` (all of them in project mode). */
     private entriesForHarness;
+    /**
+     * A 5.12.0 global record has no `global_asset_harnesses:` key, yet `add --global --harness`
+     * wrote one copy only. On the first global `install`, an entry with exactly one existing copy
+     * among several default harnesses is that harness's subset (OQ6): record it, so the install
+     * does not fan the asset out to harnesses the user never asked for (p1442). A copy under the
+     * 5.12.0 omp folder (`~/.omp/skills`) counts as an omp copy. Nothing is inferred once the key
+     * exists (an entry without a row then means "every harness"), with one default harness, or
+     * with no copy yet. Global mode only; returns the rows written.
+     */
+    private inferLegacyHarnessSubsets;
     /**
      * Set (or, with `harnesses` undefined, clear) the harness row of `ref` in the parsed
      * `~/.skaile/skaile.yaml` `raw`. Returns whether `raw` changed.
      */
     private setEntryHarnessRow;
+    /** The harness row of `kind:name` (publisher must agree when both sides have one) in the parsed `raw`. */
+    private harnessRowIn;
+    /**
+     * The harness row `add --global --harness <requested>` leaves for `ref`: the recorded set plus
+     * `requested`. An asset declared with no row goes to every global harness, so its set is that
+     * default; `undefined` (no row) when `requested` is already part of it. A new asset gets
+     * `requested` alone.
+     */
+    private widenedHarnessRow;
+    /**
+     * After `add --global --harness X`: widen the row of every other entry of the add that has one
+     * (a requirement declared on its own with `--harness`), so the copy now deployed into X stays
+     * managed. Entries with no row already go to every harness.
+     */
+    private widenDependencyRows;
+    /**
+     * `add --global --harness X --only`: name each harness that leaves the asset's set but still
+     * holds a copy. The copy stays on disk; `remove --global --harness <h>` deletes it.
+     */
+    private reportDroppedCopies;
     /**
      * Delete the copies a 5.12.0 global install left in `~/.omp/skills`, `~/.omp/agents`,
      * `~/.omp/prompts` and `~/.omp/contracts` (omp reads `~/.omp/agent/<dir>`) for the assets just
@@ -832,6 +944,10 @@ export declare class AssetManager {
     /** Deploy options for one harness. In global mode, `harness` is the
      * fan-out target (not the constructor's `harness`, which is project-only). */
     private deployOptsFor;
+    /** Agent name → the `../` compose folder files its lock entry records (`LockEntry.composed`). */
+    private composedRecords;
+    /** `install`'s `Missing:` line for a `../` compose folder the library moved past the lock. */
+    private composedDriftLine;
     /**
      * Names of the `mcp-server` assets the lock holds (the declaration ids, unscoped); a missing
      * `.mcp.json` entry of one counts as drift even before skaile owned it.
@@ -959,6 +1075,15 @@ export declare class AssetManager {
         entry: CatalogEntry;
         library: string;
     }>>;
+    /**
+     * The version `add` deploys for each asset of a source clone registered as a `reader`
+     * library, when its file declares none: the repo commit pseudo-version (p855). `search`
+     * reads this where no project is in scope, so it lists what `add` locks, not the index
+     * default.
+     *
+     * @returns `<library>\0<kind>:@<publisher>/<name>` -> version; only assets that declare none.
+     */
+    sourceAssetVersions(): Promise<Map<string, string>>;
     /**
      * Every origin that holds `ref` (`kind:@publisher/name`) with the version it holds, in
      * the order `add <ref>` prefers them, so the first row is the one `add` deploys: the
@@ -1111,6 +1236,15 @@ export declare class AssetManager {
      * yields `null` — a lock/outdated read must never create `index.db` or throw.
      */
     private loadLibraryIndex;
+    /**
+     * Ids of the registered libraries that are the clone of a source this project does not
+     * declare. `source add` registers the clone as a machine-wide reader library so `search`
+     * and the indexer can read it, but a `sources:` clone belongs to the projects that declare
+     * it (OQ12, p321): another project neither resolves it, nor ties with it by name, nor has
+     * `update` re-pin its locked assets to it. A reader library the user registered by hand
+     * (`library init --reader --git`) lives outside the sources cache and is never hidden.
+     */
+    undeclaredSourceClones(libraries: readonly Library[]): Set<string>;
     /**
      * Library-origin lock entries for the assets {@link resolveLibraryEntries}
      * matched. The locked version is the one actually deployed: the on-disk
@@ -1153,11 +1287,33 @@ export declare class AssetManager {
      * `install --locked`. An entry is restored only when its library is still
      * registered/on disk, still holds the asset, and still offers the locked
      * version; anything else is reported in `missing` with the reason.
+     *
+     * @param opts.storeFallback - `install --locked` only: an entry whose library is not registered
+     *   here is restored from a store that serves the locked sha256 (OQ15, p1490). Reads such as
+     *   the drift check never ask a store.
      */
     private restoreLibraryLockEntries;
+    /**
+     * Whether a library-origin lock entry was restored from its lock url: its library is not
+     * registered here, and the project's store cache holds the locked version (`install --locked`
+     * fetched and SHA-verified it there against the sha256 the lock recorded). Such an entry is
+     * as restorable as a source- or store-origin one: `check` and `doctor` read its requirements
+     * from the deployed copy and do not ask for the library (OQ8, p1655). An unregistered library
+     * that never restored anything here stays a gap.
+     */
+    private restoredFromLockUrl;
+    /**
+     * The store's copy of a library-origin lock entry whose library is not registered here: a
+     * store (project `stores:` or the global catalog) that serves `kind:@publisher/name#version`
+     * under the very sha256 the lock recorded holds the same bytes. The entry is fetched and
+     * verified like any store asset; the lock stays as it is. `null` when the lock has no hash,
+     * no store answers, or the hash differs (OQ15, p1490).
+     */
+    private storeEntryForLockedLibraryAsset;
     /**
      * Whether a deployed copy exists for the lock entries `install` kept for the unresolved
-     * `ref`. A kind with no install target has no deployed copy.
+     * `ref`. A kind with no install target has none, except an `mcp-server`: its copy is the
+     * `.mcp.json` entry skaile wrote and the payload that entry points into (p792).
      */
     private keptCopyDeployed;
     /** Whether the deployed copy of a library asset is on disk; a kind with no install target has none to check. */
@@ -1205,6 +1361,12 @@ export declare class AssetManager {
      * exactly one locked asset.
      */
     lockedRefsNamed(kind: string, name: string): string[];
+    /**
+     * The library a library-origin lock entry of `kind` and `name` (and `publisher`, when given)
+     * resolves to on this machine, or `undefined` when the lock holds no such entry, it is not
+     * from a library, or its library is not here. `info` prints it next to `source:`.
+     */
+    lockedLibraryOf(kind: string, name: string, publisher?: string): Promise<string | undefined>;
     /**
      * 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
@@ -1223,6 +1385,24 @@ export declare class AssetManager {
      * ({@link lockedLibraryNames}, a `library rename` followed) and the sha256 it locked.
      */
     private lockedPreference;
+    /**
+     * Canonical refs of the locked source assets that share a source URL with `resolved` but
+     * are locked at another commit than the one `resolved` carries for it. Assets in `resolved`
+     * and library-origin entries are skipped.
+     */
+    private staleSourceSiblingRefs;
+    /**
+     * The lock entries that came from a source or the store (a `source:`, no `library:`), by
+     * identity `<publisher>/<kind>:<name>` -> locked version. The lock's origin
+     * wins: a library registered later that holds the same ref does not take such an asset
+     * (`update`, `install`, `add`; OQ15, p1490).
+     */
+    private lockedOriginVersions;
+    /**
+     * Say which registered library holds a ref the lock keeps on its source or the store: the
+     * candidate that lost, with the way to switch (p1490). Printed once per `add`.
+     */
+    private noteLosingLibraries;
     /** A candidate's stable identity key (`<publisher>/<kind>:<name>@<version>`). */
     private candidateKey;
     /**
@@ -1399,6 +1579,45 @@ export declare class AssetManager {
      * from the lock are named, nothing is removed, and `--force` prunes anyway (OQ6).
      */
     private assertNoHandEditsPruned;
+    /**
+     * Report (and, without `force`, guard) the files a re-lock deletes from a deployed copy
+     * (OQ5, p1441): the asset is locked already and its library or source now holds other content
+     * (`next` re-locks it), and the deployed folder holds files the new content does not ship. The
+     * deploy clears them. Two cases:
+     *  - the deployed copy still equals what `prevLock` recorded (per-file sha256 for a source
+     *    or store asset, the library hash for a library asset): the new version dropped those
+     *    files, nobody edited them, so they are deleted and come back as `removed` rows (an
+     *    `install`/`update` prints `Removed <file> (not part of <ref>)`), without a refusal;
+     *  - the copy diverged (a file the previous content did not ship, an edited file, or no hash
+     *    to compare): without `force` this throws one error naming the files and changes nothing.
+     *    A source or store asset names only the files the previous content did not ship (or that
+     *    were edited); a library asset records no file list, so it names every file to delete.
+     *
+     * @param entries - The catalog entries about to be deployed.
+     * @param next - The lock the run is about to write (or merge).
+     * @param libraryOf - The library each library-origin entry came from.
+     */
+    private relockDeletions;
+    /**
+     * Stop `install` from overwriting a hand-edited rendered agent file that no lock entry
+     * records (OQ5, p1440): the lock is gone (or never held the agent), so nothing tells an edit
+     * from a stale render, and the deploy would replace the file without a word. Checks the file
+     * named after each agent about to be deployed and the file of each agent instance whose bound
+     * agent has no lock entry. Throws one error naming each file that exists and differs from its
+     * render and changes nothing; `--force` (the caller skips this check) overwrites. A file that
+     * equals its render is not an edit. Project mode only.
+     */
+    private assertNoUnrecordedAgentOverwrite;
+    /**
+     * Stop a re-lock from replacing a hand edit of a deployed copy (OQ6, p1641): the asset is locked
+     * already, its library or source now holds other content (`next` re-locks it), and a deployed
+     * file differs from what the lock covers and from the new content. The deploy would replace
+     * the file without a word. Throws one error naming each file and changes nothing; `--force`
+     * (the caller skips this check) replaces them. An agent's rendered files are compared with the
+     * hashes the lock records. A file the new content brings back byte for byte loses nothing.
+     * Project mode only.
+     */
+    private assertNoHandEditsOverwritten;
     /**
      * Remove stale assets — those recorded in the old lock but absent from the
      * newly resolved set (`resolved` source candidates plus `keep`, the canonical
@@ -1440,6 +1659,12 @@ export declare class AssetManager {
      */
     private adviseMissing;
     private installLocked;
+    /**
+     * One notice line per locked library that is not registered here and whose assets
+     * `install --locked` restored from the lock url: names the library, how many assets came from
+     * the url, and how to register the library to move the lock later (OQ8, p1655).
+     */
+    private lockUrlRestoreNotices;
     /**
      * The versions of `parsed`'s name that a source, a library or a store holds, newest first,
      * for the `Asset not found` of a pinned ref. Empty for an unpinned ref (nothing was ruled
@@ -1447,6 +1672,25 @@ export declare class AssetManager {
      * adds nothing here: its failure is reported by the caller.
      */
     private availableVersions;
+    /**
+     * The refs of the other kinds that a source or a library holds under the same publisher and
+     * name as `parsed` (`agent:@pub/captain` for a `@pub/captain` that is no skill), for the
+     * `Did you mean` of an `add` that missed.
+     */
+    private otherKindRefs;
+    /**
+     * The `Did you mean agent:@pub/name?` sentence for a ref written without a kind (`@pub/name`,
+     * which means `skill`) that names no asset: the refs of other kinds under the same name that
+     * a source, a library, the lock or `skaile.yaml` holds (p1425). `undefined` when the ref has a
+     * kind or nothing of another kind answers to it. `add`, `diff`, `update`, `info`, `remove` and
+     * `why` end their not-found line with it.
+     */
+    otherKindHint(ref: string): Promise<string | undefined>;
+    /**
+     * What `add` would deploy for the resolved candidates and library entries, without touching
+     * the project: one item per asset with its origin, version, deploy folders and files.
+     */
+    private planAddItems;
     /**
      * Parse the ref `add` was given. A ref the grammar rejects fails with the parser's message
      * minus its manifest-migration advice (it points at a skill that is not for `add`), and:
@@ -1499,6 +1743,14 @@ export declare class AssetManager {
         force?: boolean;
         /** Called per `.env` file in an asset's directory that a copy deploy leaves out. */
         onSecretFile?: (ref: string, path: string) => void;
+        /** Resolve and check everything, write nothing, and hand the plan to `onPlan`. */
+        dryRun?: boolean;
+        /** Global `--harness`: replace the recorded harness set instead of adding to it (`--only`). */
+        only?: boolean;
+        /** With `only`: called per harness that drops out of the set but still holds a copy. */
+        onDroppedCopy?: (ref: string, harness: HarnessName, path: string) => void;
+        /** Called once with the plan of a `dryRun` add. */
+        onPlan?: (plan: AddPlanItem[]) => void;
     }): Promise<string[]>;
     /**
      * Report the body-link **soft dependencies** of the given assets that are not
@@ -1664,6 +1916,13 @@ export declare class AssetManager {
      * @throws On a malformed ref, or when a short ref matches more than one asset.
      */
     private resolveRemoveTarget;
+    /**
+     * The refs among `refs` (`skill:@publisher/name`, `skill:name`, with or without `#version`)
+     * that are not deployed for this manager's harnesses and scope, judged as `check` judges a
+     * requirement. A ref that does not parse or names a kind this build does not install is
+     * never reported. `run <flow> --dry-run` names the node skills a flow still lacks (p1757).
+     */
+    undeployedSkills(refs: readonly string[]): string[];
     /**
      * The reverse guard of {@link removeWithDependencies}: which other locked assets (and
      * declared presets) require `target`. Their requirements are read the way {@link lockedGraph}
@@ -1693,6 +1952,16 @@ export declare class AssetManager {
      * it is kept and named in `opts.kept` unless `opts.force`.
      */
     private removeResolved;
+    /**
+     * After an `mcp-server` asset left the project: drop what would keep it rendered. Its staged
+     * store bytes under `.skaile/cache/store/<publisher>/mcp-server/<name>/` go (an `mcp_servers:`
+     * entry of the same id would otherwise keep loading them), and so does an `mcp_servers:` entry
+     * that only sets values for it: `env` and the like, with no `command`, `url` or recipe of its
+     * own. An entry that can run alone is the user's own server and stays.
+     *
+     * @returns The dropped `mcp_servers` entries, as `mcp_servers entry "<id>"`.
+     */
+    private dropRemovedMcpServerSettings;
     /**
      * After `remove --global --harness X`: the harnesses outside `X` that still hold a copy of the
      * asset, or `undefined` when none does (or this is not a harness-limited global remove).
@@ -1760,15 +2029,21 @@ export declare class AssetManager {
     listDeployed(kind?: string): CatalogEntry[];
     /**
      * Tracked assets (`skaile.lock.yaml` or declared in `skaile.yaml`) whose copy
-     * still sits in the project's `.claude/…` dirs although this manager deploys
-     * to another harness. Before the default followed the configured harness every
-     * project deployed to `.claude/`, so an omp/codex project upgraded from then
-     * holds orphans there that `remove` / `clean` / `list` no longer look at.
+     * still sits in the project dirs of another harness (`.claude/…`, `.omp/…`,
+     * `.codex/…`) although this manager deploys to {@link AssetManager.harness}.
+     * A project that moved with `skaile harness set` holds orphans there that
+     * `remove` / `clean` / `list` no longer look at.
      *
-     * Read-only: nothing is deleted. Empty for `claude-code`, for global mode, and
-     * for kinds whose dir is shared with the active target (flows).
+     * Read-only: nothing is deleted. Empty for global mode and for kinds whose
+     * dir is shared with the active target (flows).
      *
-     * @returns One {@link LegacyDeployedAsset} per stale copy, sorted by kind then name.
+     * @returns One {@link StaleHarnessCopy} per stale copy, sorted by harness, kind, then name.
+     */
+    listStaleHarnessCopies(): StaleHarnessCopy[];
+    /**
+     * @deprecated Use {@link AssetManager.listStaleHarnessCopies}, which covers every
+     * other harness folder. This returns only its `.claude/` rows (the old default
+     * deploy dir), in the old shape.
      */
     listLegacyClaudeDeployed(): LegacyDeployedAsset[];
     /**
@@ -1927,6 +2202,11 @@ export declare class AssetManager {
      * @returns Array of {@link OutdatedEntry} objects.
      */
     outdated(): Promise<OutdatedEntry[]>;
+    /**
+     * The `#pin` of every publisher-qualified `skaile.yaml` dependency, keyed `kind:publisher/name`
+     * (no scope sigil). `update` honours it, so `outdated` must not list a move it keeps.
+     */
+    private declaredPinsByIdentity;
     /**
      * List a locked asset whose `skaile.yaml` ref carries a `#version` pin while a source, a
      * library or a store holds a newer one: `locked 0.7.0 -> 0.9.0 (pinned)`. The pin is the
@@ -2090,6 +2370,12 @@ export declare class AssetManager {
      * @returns The {@link ProjectState}; `gaps` is empty when the project is as declared and locked.
      */
     projectState(): Promise<ProjectState>;
+    /**
+     * The first `../` compose folder of the locked library agent `kind:name` whose library copy
+     * changed since the lock, or `undefined` (project scope only). `install --locked` cannot
+     * restore such an agent; `update` moves the lock to the library's copy.
+     */
+    private lockedComposeDrift;
     /**
      * 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}.
@@ -2141,12 +2427,23 @@ export declare class AssetManager {
      * The locked source assets whose source is no longer in `skaile.yaml` `sources:` (`source
      * remove`, a hand edit), keyed by lock key. ONE sentence for it: `check`, `doctor`, `outdated`,
      * `install`, `install --locked` and `update` all say it (p1062), and none re-clones the source.
-     * A source of a store-resolved lock entry is not told apart from one, so no GitHub source is
-     * called missing while a `stores:` entry exists.
+     * A GitHub lock entry that no source declares counts as store-supplied only when a store
+     * lists the ref (OQ3): a configured store alone proves nothing, as it may never have held
+     * the asset. `check`, `doctor` and `outdated` read the store's cached catalog and never touch
+     * the network; `install` and `update` (`online`) ask the store itself.
      *
      * @param inScope - Only these lock keys count (`install` prunes an undeclared entry as usual).
+     * @param online - Ask the stores when the cached catalog does not list the ref.
      */
     private orphanedSourceGaps;
+    /**
+     * `true` when one of `stores` lists `ref` (a canonical lock key): its cached catalog holds it
+     * or, with `online`, the store answers for it. An injected store fetcher is the store client
+     * itself, so it is asked either way. A store an online install cannot ask (unreachable,
+     * air-gapped, `--no-catalog`) may hold the ref; `check` never asks, so a store lists only what
+     * its cached catalog holds.
+     */
+    private storeListsRef;
     /**
      * Locked source assets whose source cannot supply them any more: the source is no longer in
      * `skaile.yaml` `sources:` (`source remove`, a hand edit), or it is there but now publishes
@@ -2163,11 +2460,24 @@ export declare class AssetManager {
      * `kind:@publisher/name`. `skaile source remove` refuses while this list is not empty.
      */
     lockedFromSource(url: string): string[];
+    /**
+     * Record, on every library-origin entry of `lock` that is copied into a harness folder, the
+     * files of the deployed copy and their sha256 (`LockEntry.copied`), so a hand edit is named
+     * even after the library moved past the lock (p1641). Call it after the deploy. An entry that
+     * is unchanged since `prev` keeps its record, or stays without one: the deployed bytes may
+     * carry an edit the deploy did not touch. Project mode only; a `--link` deploy and a patched
+     * asset are not recorded.
+     */
+    private withCopiedFiles;
     /**
      * Record, on every agent entry of `lock` that has none, the files the agent's harness
      * rendering occupies and their sha256. Call it after the deploy, so the bytes hashed are the
      * ones `install` just wrote; {@link lockedCopyDrift} compares later edits with them.
      * Entries that carry a record (kept from an earlier lock) are left as they are.
+     *
+     * @param keepComposedOf - The lock an `install` read: an agent whose `../` compose folder is
+     *   not in the cache keeps that lock's `composed:` record. Omitted by `update` and `add`,
+     *   which copy the library's current bytes.
      */
     private withRenderedAgents;
     /**
@@ -2204,6 +2514,16 @@ export declare class AssetManager {
      * deploy just wrote again: those whose ref is among the `deployed` canonical refs.
      */
     private restoredCopies;
+    /**
+     * Hand edits in the deployed copy of a library asset whose library moved past the lock (a
+     * version bump, or an in-place edit of the same version): {@link restoreLibraryLockEntries}
+     * drops such an entry, so {@link lockedCopyDrift} would not see the edit and `update` would
+     * replace the file without a word (p1641). `covered` holds the `kind:@publisher/name` of the
+     * entries that were compared already. The lock's per-file record (`copied:`) names the edited
+     * files; a lock without one (written before it existed) compares the deployed folder with the
+     * one library hash and names the files that also differ from the library's new content.
+     */
+    private changedLibraryCopyEdits;
     /**
      * 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`