@avantf/dsh-plugin-base 0.5.3 → 0.6.0

package/lib/providers/runtime_deps.js

@@ -0,0 +1,1214 @@
+/**
+ * The built-in `runtime-deps` provider: ONE shared, SPEC-ADDRESSED store of runtime npm packages,
+ * shared by every plugin that declares the same dependency set.
+ *
+ * The layout is `<home>/<item.target.root>/<key>/` (the canonical `item.target.root` is
+ * {@link RUNTIME_DEPS_DIR}):
+ *
+ * ```text
+ * <key>/
+ *   package.json        # generated from the spec (dependencies + host-provided peers)
+ *   pnpm-lock.yaml      # whatever lockfile the selected manager wrote (or the caller's copy)
+ *   node_modules/
+ *   .runtime.json       # key, packages, lock hash, platform, ABI, attempts, integrity
+ *   .ready              # only after verify + the core's atomic rename
+ *   install.json        # the provisioner's own version manifest (written by the core)
+ * ```
+ *
+ * `key` is `sha256(canonical packages + verify entries + lockfile hash + platform + arch + Node ABI +
+ * manager name/version per attempt + attempt (source + env + allowScripts) + peer name/range/resolved
+ * host copy (dir + version))`.
+ * A changed package/verify/lock/env/platform/peer range is therefore a NEW root; an existing root is
+ * never mutated. The key is a digest of the DECLARED spec, not of the bytes a manager fetched: without
+ * a caller lockfile the same key can install different package versions at different times or on
+ * different machines. What the root does guarantee is "installed once, then never rewritten locally".
+ *
+ * The provider names no package: everything it installs, verifies and links comes from
+ * {@link RuntimeDepsSpec}. Host singletons are declared in `spec.peers` and are LINKED from the
+ * caller's tree, never fetched from a registry (they are written as optional peer dependencies and
+ * the managers are told not to auto-install peers); both the range and the version actually linked
+ * into the root are part of what the root has to satisfy, and a reuse compares the actual link
+ * TARGET with the resolved host copy. A copy fallback (a filesystem that refuses symlinks) has no
+ * target to compare: its identity is version-level, and `.runtime.json` says so in `copiedPeers`.
+ *
+ * A failed install records every attempt (in the error and in the provisioner's report/status),
+ * removes its own staging tree and leaves no root behind — a failed item is a
+ * report, never a blocked plugin mount. Garbage collection is EXPLICIT (`gcRuntimeDeps` on
+ * `./internal`), never at startup.
+ *
+ * @module providers/runtime_deps
+ */
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { basename, dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
+import { ProvisionError, reasonOf } from '../errors.js';
+import { defaultFs, exists, linkOrCopy } from '../fs.js';
+import { sriOfSha256 } from '../integrity.js';
+import { assertSafeRelativePath, versionSegment } from '../layout.js';
+import { defaultLock, pidIsAlive } from '../lock.js';
+import { decodeJson } from '../manifest.js';
+import { assertPackageName } from '../package-name.js';
+import { assertRange, satisfiesRange } from '../semver.js';
+import { readStatus } from '../state.js';
+import { packageVersionOf, resolvePeerDir } from './npm.js';
+/** The kind the runtime-dependency provider claims. */
+export const RUNTIME_DEPS_KIND = 'runtime-deps';
+/**
+ * The canonical `item.target.root` for the shared store. A caller may put the store elsewhere, but
+ * then it is a different shared root: the store is shared through the HOME + target.root pair.
+ */
+export const RUNTIME_DEPS_DIR = 'deps/runtime';
+/** The per-root record, written into staging before `.ready`. */
+const RECORD_FILE = '.runtime.json';
+/** The completion marker; the root is immutable once it exists. */
+const READY_FILE = '.ready';
+/** Per-key locks live here, beside (not inside) the roots they protect. */
+const LOCKS_DIR = '.locks';
+/** Staging entries are SIBLINGS of the key roots (same path depth), so a manager's relative
+ *  symlinks (npm `file:` deps, pnpm's `node_modules` links) survive the atomic rename unchanged. */
+const STAGING_PREFIX = '.staging-';
+/** The record/completion schema this build writes and reads. */
+const RECORD_SCHEMA_VERSION = 1;
+/** How long a waiter waits for a concurrent writer of the same key. */
+const DEFAULT_LOCK_TIMEOUT_MS = 300_000;
+/** A lock whose holder pid is gone may be reclaimed after this age. */
+const DEFAULT_STALE_LOCK_MS = 10_000;
+/** Cap on the manager output kept for diagnostics (each stream). */
+const MAX_OUTPUT_CHARS = 16_384;
+/** Staging sequence, monotonic per process (the `.staging-…` sibling names stay unique). */
+let stagingSequence = 0;
+/** Lockfile names a package manager actually consumes. */
+const MANAGER_LOCKFILES = ['pnpm-lock.yaml', 'package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock'];
+// ─────────────────────────────────────────────────────────────────────────────
+// Pure helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+function sortedRecord(value) {
+    return Object.fromEntries(Object.entries(value).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)));
+}
+/** JSON with object keys sorted recursively; the content-address input must not depend on insertion order. */
+function canonicalJson(value) {
+    if (value === undefined)
+        return 'null';
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(entry => canonicalJson(entry)).join(',')}]`;
+    const record = value;
+    const entries = Object.keys(record)
+        .sort((left, right) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(key => `${JSON.stringify(key)}:${canonicalJson(record[key])}`);
+    return `{${entries.join(',')}}`;
+}
+function sha256Hex(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function encodeJson(value) {
+    return new TextEncoder().encode(`${JSON.stringify(value, null, 2)}\n`);
+}
+function tail(value, limit = 400) {
+    const trimmed = value.trim();
+    if (trimmed.length <= limit)
+        return trimmed;
+    return `…${trimmed.slice(trimmed.length - limit)}`;
+}
+/**
+ * Scrub credentials out of text that came from a package manager.
+ *
+ * A failed attempt's `stderr`/`stdout` ends up in `status.json.last_error`, in the log and in the
+ * item's reason, and a manager happily echoes the URL it talked to — userinfo, a scoped-registry
+ * `_authToken`, a proxy/bearer token, a `password=`/`token=` parameter. The attempt's `env` VALUES are
+ * never persisted (only their keys), so this is the other half of the same promise. Scrubbing is
+ * deliberately blunt: a false positive costs a masked word in a diagnostic, a miss costs a token.
+ */
+function redact(value) {
+    return (value
+        // `Authorization: Bearer …` / `Basic …` FIRST: the scheme word itself is not the secret, and the
+        // auth-ish `key: value` rule below would otherwise strip the scheme and leave the token behind.
+        .replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{4,}/giu, '$1 ***')
+        // `//registry.example/:_authToken=…`, `_auth=…`, `_password=…`, `token: …`
+        .replace(/\b(_authToken|_auth|_password|_token|token|password|secret|authorization)\b(\s*[:=]\s*)"?[^\s"&,;]+"?/giu, '$1$2***')
+        // `https://user:pass@host/…`, `http://token@host/…`
+        .replace(/\b([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/giu, '$1***@'));
+}
+/** The shared store root for one item. */
+export function runtimeDepsStore(home, targetRoot = RUNTIME_DEPS_DIR) {
+    assertSafeRelativePath(targetRoot);
+    // `join` is the SAME normalisation the core's `publish()` applies; normalising separators here
+    // instead would make probe and publish disagree on a POSIX path such as `deps\\runtime`.
+    const store = join(home, targetRoot);
+    if (store === home)
+        throw new ProvisionError('invalid-option', `runtime-deps 的 target.root 不能是 home 本身：${JSON.stringify(targetRoot)}`);
+    return store;
+}
+/** The per-key lock path; the lock files sit beside the roots, never inside one. */
+export function runtimeDepsLockPath(store, key) {
+    return join(store, LOCKS_DIR, `${key}.lock`);
+}
+/** Parse and validate the generic spec. Base tells no package what to do; it only checks shapes. */
+function parseSpec(item) {
+    const raw = item.spec;
+    if (!isRecord(raw))
+        throw new ProvisionError('invalid-option', `runtime-deps 的 spec 必须是对象：${item.id}`);
+    const packagesRaw = raw['packages'];
+    if (!isRecord(packagesRaw) || Object.keys(packagesRaw).length === 0) {
+        throw new ProvisionError('invalid-option', `runtime-deps 的 spec.packages 必须是非空对象：${item.id}`);
+    }
+    const packages = {};
+    for (const [name, spec] of Object.entries(packagesRaw)) {
+        assertPackageName(name);
+        if (typeof spec !== 'string' || spec.trim() === '') {
+            throw new ProvisionError('invalid-option', `runtime-deps 的 spec.packages["${name}"] 必须是非空的依赖说明：${item.id}`);
+        }
+        packages[name] = spec;
+    }
+    const sourcesRaw = raw['sources'];
+    if (!Array.isArray(sourcesRaw) || sourcesRaw.length === 0) {
+        throw new ProvisionError('invalid-option', `runtime-deps 的 spec.sources 必须是非空数组：${item.id}`);
+    }
+    const sources = [];
+    const sourceIds = new Set();
+    for (const [index, candidate] of sourcesRaw.entries()) {
+        if (!isRecord(candidate))
+            throw new ProvisionError('invalid-option', `runtime-deps 的 spec.sources[${String(index)}] 必须是对象：${item.id}`);
+        const id = text(candidate['id']);
+        if (id === undefined)
+            throw new ProvisionError('invalid-option', `runtime-deps 的 spec.sources[${String(index)}].id 缺失：${item.id}`);
+        if (sourceIds.has(id))
+            throw new ProvisionError('invalid-option', `runtime-deps 的 spec.sources 中 id 重复：${id}（${item.id}）`);
+        sourceIds.add(id);
+        const registry = text(candidate['registry']);
+        const cache = text(candidate['cache']);
+        if (registry === undefined && cache === undefined) {
+            throw new ProvisionError('invalid-option', `runtime-deps 的 source "${id}" 至少要给 registry 或 cache 之一：${item.id}`);
+        }
+        sources.push({
+            id,
+            ...(registry === undefined ? {} : { registry }),
+            ...(cache === undefined ? {} : { cache }),
+        });
+    }
+    const attemptsRaw = raw['attempts'];
+    if (!Array.isArray(attemptsRaw) || attemptsRaw.length === 0) {
+        throw new ProvisionError('invalid-option', `runtime-deps 的 spec.attempts 必须是非空数组：${item.id}`);
+    }
+    const attempts = [];
+    for (const [index, candidate] of attemptsRaw.entries()) {
+        if (!isRecord(candidate))
+            throw new ProvisionError('invalid-option', `runtime-deps 的 spec.attempts[${String(index)}] 必须是对象：${item.id}`);
+        const source = text(candidate['source']);
+        if (source === undefined || !sourceIds.has(source)) {
+            throw new ProvisionError('invalid-option', `runtime-deps 的 spec.attempts[${String(index)}].source 必须是已声明的 source id：${String(source)}（${item.id}）`);
+        }
+        const manager = candidate['manager'];
+        if (manager !== undefined && manager !== 'npm' && manager !== 'pnpm') {
+            throw new ProvisionError('invalid-option', `runtime-deps 的 spec.attempts[${String(index)}].manager 只能是 npm 或 pnpm：${String(manager)}（${item.id}）`);
+        }
+        const env = candidate['env'];
+        if (env !== undefined) {
+            if (!isRecord(env) || Object.values(env).some(value => typeof value !== 'string')) {
+                throw new ProvisionError('invalid-option', `runtime-deps 的 spec.attempts[${String(index)}].env 必须是 string→string：${item.id}`);
+            }
+        }
+        const allowScripts = candidate['allowScripts'];
+        if (allowScripts !== undefined && typeof allowScripts !== 'boolean') {
+            throw new ProvisionError('invalid-option', `runtime-deps 的 spec.attempts[${String(index)}].allowScripts 必须是布尔值：${item.id}`);
+        }
+        attempts.push({
+            source,
+            ...(manager === undefined ? {} : { manager }),
+            ...(env === undefined ? {} : { env: env }),
+            ...(allowScripts === undefined ? {} : { allowScripts }),
+        });
+    }
+    const verifyRaw = raw['verify'];
+    if (!Array.isArray(verifyRaw) || verifyRaw.some(entry => typeof entry !== 'string' || entry.trim() === '')) {
+        throw new ProvisionError('invalid-option', `runtime-deps 的 spec.verify 必须是字符串数组：${item.id}`);
+    }
+    // An empty `verify` would let a manager that exits 0 without installing anything still pass
+    // `verifyTree` (package.json/node_modules exist). A root must resolve at least one declared entry.
+    if (verifyRaw.length === 0) {
+        throw new ProvisionError('invalid-option', `runtime-deps 的 spec.verify 不能为空（至少一个可解析项，通常取 spec.packages 的键）：${item.id}`);
+    }
+    const peersRaw = raw['peers'];
+    const peers = {};
+    if (peersRaw !== undefined) {
+        if (!isRecord(peersRaw))
+            throw new ProvisionError('invalid-option', `runtime-deps 的 spec.peers 必须是对象：${item.id}`);
+        for (const [name, range] of Object.entries(peersRaw)) {
+            assertPackageName(name, 'peer 名');
+            if (typeof range !== 'string' || range.trim() === '') {
+                throw new ProvisionError('invalid-option', `runtime-deps 的 spec.peers["${name}"] 必须是非空区间：${item.id}`);
+            }
+            // A range outside the supported semver subset must not be "assumed satisfied": it is a
+            // declaration error and it would decide which host singleton a shared root may carry.
+            try {
+                assertRange(range);
+            }
+            catch (error) {
+                throw new ProvisionError('invalid-option', `runtime-deps 的 spec.peers["${name}"] 不是受支持的版本区间：${JSON.stringify(range)}（${reasonOf(error).message}）`);
+            }
+            peers[name] = range;
+        }
+    }
+    const lockfile = raw['lockfile'];
+    if (lockfile !== undefined && (typeof lockfile !== 'string' || lockfile.trim() === '')) {
+        throw new ProvisionError('invalid-option', `runtime-deps 的 spec.lockfile 必须是路径字符串：${item.id}`);
+    }
+    return {
+        packages,
+        sources,
+        attempts,
+        verify: verifyRaw,
+        ...(peersRaw === undefined ? {} : { peers }),
+        ...(lockfile === undefined ? {} : { lockfile }),
+    };
+}
+/**
+ * The resource identity: a digest of the declared set, pure and never throwing (declare must not
+ * break).
+ *
+ * `item.target.root` is part of the digest: the SAME spec under a different root is a different
+ * physical store, so two such items must not collapse into one status row (and one handle). The
+ * content key stays spec-only — it names the DECLARED set, not the store.
+ */
+function identityName(item) {
+    // `target` is required by the item schema; the optional chain keeps `identify()` total for a
+    // malformed item (declare() must never throw).
+    const root = item.target?.root;
+    let digest;
+    try {
+        digest = sha256Hex(canonicalJson({ root: root ?? null, spec: item.spec ?? null }));
+    }
+    catch {
+        digest = sha256Hex(`${String(root)}\u0000${String(item.spec)}`);
+    }
+    return `deps-${digest.slice(0, 16)}`;
+}
+/** The root directory name for one key, using the SAME segment derivation the core applies in
+ *  `publish()` (`versionSegment`): a very long HOME would otherwise bypass the core's path budget,
+ *  and probe/plan/install would look at a path `publish()` never creates. */
+function rootNameOf(home, item, key) {
+    return versionSegment(home, item.target.root, identityName(item), key);
+}
+/** A source by id (already validated by {@link parseSpec}). */
+function sourceOf(spec, id) {
+    const source = spec.sources.find(candidate => candidate.id === id);
+    if (source === undefined)
+        throw new ProvisionError('invalid-option', `runtime-deps 引用了未声明的 source：${id}`);
+    return source;
+}
+/** The manager arguments for one attempt. No package name is ever composed here. */
+function managerArgs(manager, source, attempt) {
+    const args = manager === 'npm'
+        ? ['install', '--no-audit', '--no-fund', '--loglevel=error', '--legacy-peer-deps']
+        : [
+            'install',
+            '--reporter=silent',
+            '--config.auto-install-peers=false',
+            '--config.strict-peer-dependencies=false',
+            '--config.confirmModulesPurge=false',
+            // The generated manifest is ours alone and the package.json has already been checked by the
+            // provider: pnpm's "which dependencies may run build scripts" gate would otherwise block the
+            // very postinstall an `allowScripts: true` attempt asked for. Script permission is decided by
+            // `--ignore-scripts` below, not by the manager's interactive approval state.
+            '--config.strict-dep-builds=false',
+            '--ignore-workspace',
+        ];
+    if (source.registry !== undefined)
+        args.push(`--registry=${source.registry}`);
+    if (source.cache !== undefined) {
+        args.push(manager === 'npm' ? `--cache=${source.cache}` : `--store-dir=${source.cache}`);
+    }
+    // A cache-only source is a LOCAL store: it must not silently reach the network.
+    if (source.registry === undefined && source.cache !== undefined)
+        args.push('--offline');
+    // Lifecycle scripts are OFF unless the caller's attempt explicitly asks for them.
+    if (attempt.allowScripts !== true)
+        args.push('--ignore-scripts');
+    return args;
+}
+/**
+ * npm/pnpm config keys that describe the TRANSPORT (a proxy, a CA bundle), not a package SOURCE.
+ * They survive the `npm_config_*` scrub below: an operator's proxy is not an undeclared registry.
+ */
+const TRANSPORT_NPM_CONFIG = [
+    'proxy',
+    'http-proxy',
+    'https-proxy',
+    'noproxy',
+    'no-proxy',
+    'cafile',
+    'ca',
+];
+/** The prefix npm and pnpm read their config from. */
+const NPM_CONFIG_PREFIX = 'npm_config_';
+/**
+ * The environment a manager process gets: this process's environment plus the attempt's overrides.
+ *
+ * When the attempt names a registry, inherited `npm_config_*` (npm and pnpm both read the environment
+ * as config) could point the manager at a source the spec never declared — `npm_config_registry`, or a
+ * scoped `npm_config_@scope:registry` that even outranks `--registry`. The attempt list is the only
+ * place a source may be named, so those keys are dropped for such an attempt. The attempt's OWN
+ * `env` is kept verbatim: it is a declaration, and it is part of the content key.
+ */
+function attemptEnv(attempt, source) {
+    const env = { ...process.env };
+    if (source.registry !== undefined) {
+        for (const name of Object.keys(env)) {
+            if (!name.toLowerCase().startsWith(NPM_CONFIG_PREFIX))
+                continue;
+            if (TRANSPORT_NPM_CONFIG.includes(name.toLowerCase().slice(NPM_CONFIG_PREFIX.length)))
+                continue;
+            delete env[name];
+        }
+    }
+    return { ...env, ...(attempt.env ?? {}) };
+}
+/** The absolute lockfile path the spec names. */
+function lockfilePath(lockfile) {
+    return isAbsolute(lockfile) ? lockfile : resolvePath(lockfile);
+}
+/** Read the caller's lockfile once; its bytes and digest are part of the key. */
+async function readLockfile(fs, lockfile) {
+    if (lockfile === undefined)
+        return { bytes: undefined, hash: '', name: undefined };
+    const path = lockfilePath(lockfile);
+    let bytes;
+    try {
+        bytes = await fs.readFile(path);
+    }
+    catch (error) {
+        throw new ProvisionError('invalid-option', `runtime-deps 读不到 lockfile：${path}（${reasonOf(error).message}）`);
+    }
+    return { bytes, hash: sha256Hex(bytes), name: basename(path) };
+}
+/** The generated `package.json` for a root: dependencies + optional host peers. */
+function packageJsonOf(spec) {
+    const peerNames = Object.keys(spec.peers ?? {}).sort();
+    return {
+        name: 'dsh-runtime-deps',
+        private: true,
+        version: '0.0.0',
+        description: 'Runtime dependencies managed by @avantf/dsh-plugin-base (spec-addressed, install-once)',
+        dependencies: sortedRecord(spec.packages),
+        ...(peerNames.length === 0
+            ? {}
+            : {
+                peerDependencies: sortedRecord(spec.peers ?? {}),
+                // Host peers are LINKED after the manager run; telling the manager they are optional keeps
+                // npm from fetching them from the registry in the first place.
+                peerDependenciesMeta: Object.fromEntries(peerNames.map(name => [name, { optional: true }])),
+            }),
+    };
+}
+/** Remove a leftover install tree (between attempts) without touching the caller's lockfile. */
+async function cleanInstallTree(fs, staging, providedLockName) {
+    await fs.rm(join(staging, 'node_modules'), { recursive: true }).catch(() => undefined);
+    for (const name of MANAGER_LOCKFILES) {
+        if (name === providedLockName)
+            continue;
+        await fs.rm(join(staging, name)).catch(() => undefined);
+    }
+}
+/** Write the generated package.json and (when given) the caller's lockfile into staging. */
+async function seedStaging(fs, staging, spec, lock) {
+    await fs.writeFile(join(staging, 'package.json'), encodeJson(packageJsonOf(spec)));
+    if (lock.bytes !== undefined && lock.name !== undefined && MANAGER_LOCKFILES.includes(lock.name)) {
+        await fs.writeFile(join(staging, lock.name), lock.bytes);
+    }
+}
+/** win32 long-path prefix (`\\?\`) that `realpath`/junctions can report; neither the key nor a
+ *  comparison may see it. */
+function withoutLongPathPrefix(path) {
+    return process.platform === 'win32' ? path.replace(/^\\\\\?\\/u, '') : path;
+}
+/**
+ * The directory a peer is linked FROM: absolute and, when the IO seam can answer, symlink-free.
+ *
+ * The key, the symlink TARGET and the probe's `readlink` comparison all use this one string, so the
+ * same physical host copy names one root however the caller spelled it (`…/node_modules/zod`,
+ * `…/node_modules/../node_modules/zod`, or a symlink to that directory). The key commits to the
+ * physical copy, not to a spelling: otherwise one singleton gets linked twice, and a root is built
+ * on a path that merely happens to point at the same directory today.
+ *
+ * An fs without `realpath` (an injected seam) keeps path-level identity. That bound is stated in
+ * `docs/RUNTIME_DEPS.md` rather than papered over here.
+ */
+async function canonicalPeerDir(ctx, dir) {
+    const absolute = withoutLongPathPrefix(resolvePath(dir));
+    if (ctx.fs.realpath === undefined)
+        return absolute;
+    try {
+        return withoutLongPathPrefix(await ctx.fs.realpath(absolute));
+    }
+    catch {
+        // Missing or unreadable: keep the spelled (absolute) path. The link then cannot be made and the
+        // item fails as `peer/unsatisfied` — the caller's own diagnosis — instead of a realpath error.
+        return absolute;
+    }
+}
+/** Resolve every declared host peer; a declared peer that cannot be resolved is `peer/unsatisfied`. */
+async function resolvePeers(spec, ctx, peerDirs) {
+    const links = [];
+    for (const [name, range] of Object.entries(spec.peers ?? {}).sort(([left], [right]) => (left < right ? -1 : 1))) {
+        const declared = peerDirs?.[name] ?? resolvePeerDir(name, ctx);
+        if (declared === undefined) {
+            throw new ProvisionError('peer/unsatisfied', `runtime-deps 的 peer ${name}@${range} 不可满足（调用方未提供目录，也无法从加载 base 的树解析到）`);
+        }
+        // One string for all three uses — key input, symlink target, probe comparison.
+        const dir = await canonicalPeerDir(ctx, declared);
+        const installed = await packageVersionOf(ctx, dir);
+        // `parseSpec` already rejected an out-of-subset range, so this call cannot throw: a false here
+        // means the HOST copy genuinely does not satisfy the declared range.
+        if (installed !== undefined && !satisfiesRange(installed, range)) {
+            throw new ProvisionError('peer/unsatisfied', `runtime-deps 的 peer ${name} 需要 ${range}，调用方解析到的是 ${installed}`);
+        }
+        links.push({ name, dir, range, version: installed });
+    }
+    return links;
+}
+/** Link each host peer into the staging tree; a peer already fetched by a manager is replaced.
+ *  Returns how each peer was placed, because a copy fallback weakens the root's peer identity. */
+async function linkPeers(ctx, staging, peers) {
+    const modes = [];
+    for (const peer of peers) {
+        const linkPath = join(staging, 'node_modules', ...peer.name.split('/'));
+        await ctx.fs.rm(linkPath, { recursive: true }).catch(() => undefined);
+        const mode = await linkOrCopy(ctx.fs, peer.dir, linkPath, {
+            onFallback: () => ctx.logger.warn(`runtime-deps 的 peer ${peer.name} 退化为复制：根对这个 peer 的身份只是版本级（没有 symlink 目标可比），记为 copiedPeers`),
+        });
+        modes.push({ name: peer.name, mode });
+        if (mode === 'linked')
+            ctx.logger.debug(`runtime-deps: linked peer ${peer.name} → ${peer.dir}`);
+        // linkOrCopy creates the parent directory; the package.json check is the verification half.
+        if (!(await exists(ctx.fs, join(linkPath, 'package.json')))) {
+            throw new ProvisionError('peer/unsatisfied', `runtime-deps 的 peer ${peer.name} 链接后缺少 package.json：${linkPath}`);
+        }
+    }
+    return modes;
+}
+/** The `version` of the package installed at `dir`, or `undefined` when there is no readable one. */
+async function packageVersionAt(fs, dir) {
+    try {
+        const raw = decodeJson(await fs.readFile(join(dir, 'package.json')));
+        return isRecord(raw) ? text(raw['version']) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A path as it should be compared with a peer link target.
+ *
+ * The target is read the way the OS reads it — relative to the link itself — and, on win32, compared
+ * case-insensitively and without the `\\?\` prefix a junction can report: a mismatch here would mean
+ * "not this key's root", i.e. a rebuild on EVERY probe, so the comparison must not fail on spelling.
+ */
+function comparablePath(path, linkPath) {
+    const absolute = withoutLongPathPrefix(resolvePath(dirname(linkPath), path));
+    return process.platform === 'win32' ? absolute.toLowerCase() : absolute;
+}
+/** Verify a staged/published root: the caller's `verify` entries plus the peer links. */
+async function verifyTree(fs, root, spec, peers) {
+    const packageJson = join(root, 'package.json');
+    if (!(await exists(fs, packageJson))) {
+        throw new ProvisionError('verify/failed', `runtime-deps 的根缺少 package.json：${root}`);
+    }
+    if (!(await exists(fs, join(root, 'node_modules')))) {
+        throw new ProvisionError('verify/failed', `runtime-deps 的根缺少 node_modules：${root}`);
+    }
+    const req = createRequire(packageJson);
+    for (const entry of spec.verify) {
+        let resolved;
+        try {
+            resolved = req.resolve(entry);
+        }
+        catch (error) {
+            throw new ProvisionError('verify/failed', `runtime-deps 的 verify 项无法解析：${entry}（${reasonOf(error).message}）`);
+        }
+        // `require.resolve` caches its result per process; a file deleted after the first resolve would
+        // otherwise still "resolve". The resolved path existing is the half that cannot be cached.
+        if (!(await exists(fs, resolved))) {
+            throw new ProvisionError('verify/failed', `runtime-deps 的 verify 项解析到不存在的文件：${entry} → ${resolved}`);
+        }
+    }
+    for (const peer of peers) {
+        const peerDir = join(root, 'node_modules', ...peer.name.split('/'));
+        if (!(await exists(fs, join(peerDir, 'package.json')))) {
+            throw new ProvisionError('verify/failed', `runtime-deps 的 peer ${peer.name} 在根里不可解析：${root}`);
+        }
+        // The key commits to the resolved host COPY, not just to a version, so the link target is what
+        // proves a root is still the tree this spec resolved: another directory holding the same version
+        // is a different physical instance, and handing it out would give a plugin someone else's singleton.
+        // A COPY fallback has no target to compare — its identity is version-level, and `.runtime.json`
+        // records that fact in `copiedPeers` (`install`/`probe` explain it); the checks below still apply.
+        const linkTarget = await fs.readlink(peerDir);
+        if (linkTarget !== undefined && comparablePath(linkTarget, peerDir) !== comparablePath(peer.dir, peerDir)) {
+            throw new ProvisionError('verify/failed', `runtime-deps 的 peer ${peer.name} 在根里链接到 ${linkTarget}，与本 key 解析到的宿主副本 ${peer.dir} 不一致：${root}`);
+        }
+        // The LINKED copy is what a plugin actually loads, so its VERSION — not just its existence — has
+        // to satisfy the range declared here. Otherwise a root linked against a host singleton of another
+        // version would be handed out as if it were this spec's.
+        const linked = await packageVersionAt(fs, peerDir);
+        if (linked === undefined) {
+            throw new ProvisionError('verify/failed', `runtime-deps 的 peer ${peer.name} 在根里没有可读的版本：${peerDir}`);
+        }
+        const range = spec.peers?.[peer.name] ?? peer.range;
+        if (!satisfiesRange(linked, range)) {
+            throw new ProvisionError('verify/failed', `runtime-deps 的 peer ${peer.name} 在根里是 ${linked}，不满足 ${range}：${root}`);
+        }
+    }
+}
+/** Read the completion record of a root; anything inconsistent is "not ready", never a throw. */
+async function readReadyRoot(fs, root, key) {
+    if (!(await exists(fs, join(root, READY_FILE))))
+        return undefined;
+    let raw;
+    try {
+        raw = decodeJson(await fs.readFile(join(root, RECORD_FILE)));
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(raw))
+        return undefined;
+    if (raw['schemaVersion'] !== RECORD_SCHEMA_VERSION || raw['kind'] !== RUNTIME_DEPS_KIND || raw['state'] !== 'ready')
+        return undefined;
+    if (raw['key'] !== key)
+        return undefined;
+    // The record is a handle a plugin reads; a malformed one is "not ready", never a half-truth.
+    if (!isRecord(raw['packages']) || !Array.isArray(raw['attempts']) || !Array.isArray(raw['peers']))
+        return undefined;
+    if (typeof raw['integrity'] !== 'string' || typeof raw['installedAt'] !== 'string')
+        return undefined;
+    if (!(await exists(fs, join(root, 'package.json'))))
+        return undefined;
+    if (!(await exists(fs, join(root, 'node_modules'))))
+        return undefined;
+    return raw;
+}
+/** How long a detected manager version is trusted. */
+const MANAGER_VERSION_TTL_MS = 60_000;
+/**
+ * Spawn a package manager. On win32 the manager is a `.cmd` shim, which Node refuses to spawn
+ * without a shell (CVE-2024-27980); `cmd.exe /d /s /c` is the same shape `scripts/lib/win-spawn.mjs`
+ * pins for the build scripts, kept local because `src/` must not import the repo's scripts.
+ */
+function spawnManager(manager, args, options) {
+    if (process.platform !== 'win32')
+        return spawn(manager, [...args], { ...options, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    const comspec = process.env['ComSpec'] ?? 'cmd.exe';
+    // The arguments are fixed flags plus a caller-configured registry/cache URL; quoting each one keeps
+    // `&`/`|` inside it from becoming a command separator.
+    const line = [manager, ...args].map(quoteWindows).join(' ');
+    return spawn(comspec, ['/d', '/s', '/c', line], { ...options, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+}
+function quoteWindows(value) {
+    return /[\s"&|<>^]/u.test(value) ? `"${value.replaceAll('"', '\\"')}"` : value;
+}
+/** Default runner: spawn the manager in `cwd`; capture capped output; honour timeout/abort. */
+function defaultRun(input) {
+    return new Promise(resolvePromise => {
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        let timer;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            input.signal?.removeEventListener('abort', onAbort);
+            resolvePromise(result);
+        };
+        const child = spawnManager(input.manager, input.args, {
+            cwd: input.cwd,
+            env: input.env,
+        });
+        const onAbort = () => {
+            child.kill('SIGKILL');
+        };
+        if (input.timeoutMs !== undefined && input.timeoutMs > 0) {
+            timer = setTimeout(() => child.kill('SIGKILL'), input.timeoutMs);
+        }
+        if (input.signal?.aborted === true)
+            onAbort();
+        else
+            input.signal?.addEventListener('abort', onAbort, { once: true });
+        child.stdout?.on('data', (chunk) => {
+            if (stdout.length < MAX_OUTPUT_CHARS)
+                stdout += chunk.toString('utf8').slice(0, MAX_OUTPUT_CHARS - stdout.length);
+        });
+        child.stderr?.on('data', (chunk) => {
+            if (stderr.length < MAX_OUTPUT_CHARS)
+                stderr += chunk.toString('utf8').slice(0, MAX_OUTPUT_CHARS - stderr.length);
+        });
+        child.on('error', error => {
+            finish({ code: -1, stdout, stderr: `${stderr}${error.message}` });
+        });
+        child.on('close', code => {
+            finish({ code: code ?? -1, stdout, stderr });
+        });
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// The provider
+// ─────────────────────────────────────────────────────────────────────────────
+/** Build the built-in shared runtime-dependency provider.
+ *  @stable */
+export function runtimeDepsProvider(options = {}) {
+    const defaultManager = options.manager ?? 'pnpm';
+    const lockTimeoutMs = options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+    const staleLockMs = options.staleLockMs ?? DEFAULT_STALE_LOCK_MS;
+    const clock = options.clock ?? Date.now;
+    const platform = options.target?.platform ?? process.platform;
+    const arch = options.target?.arch ?? process.arch;
+    const nodeAbi = options.target?.abi ?? process.versions.modules ?? 'unknown';
+    const run = options.run ?? defaultRun;
+    const managerVersions = new Map();
+    const detectManagerVersion = (manager) => {
+        const injected = options.managerVersion?.(manager);
+        if (injected !== undefined)
+            return Promise.resolve(injected);
+        const cached = managerVersions.get(manager);
+        if (cached !== undefined && clock() - cached.at < MANAGER_VERSION_TTL_MS)
+            return Promise.resolve(cached.value);
+        return new Promise(resolvePromise => {
+            const child = spawnManager(manager, ['--version'], {});
+            let stdout = '';
+            const timer = setTimeout(() => child.kill('SIGKILL'), 10_000);
+            child.stdout?.on('data', (chunk) => {
+                if (stdout.length < 256)
+                    stdout += chunk.toString('utf8');
+            });
+            // Drain stderr: `spawnManager` pipes it, and an unread pipe could block a chatty manager.
+            child.stderr?.resume();
+            child.on('error', () => {
+                clearTimeout(timer);
+                resolvePromise('missing');
+            });
+            child.on('close', code => {
+                clearTimeout(timer);
+                const first = stdout.trim().split(/\r?\n/u)[0];
+                const value = code === 0 && first !== undefined && first !== '' ? first : code === 0 ? 'unknown' : 'missing';
+                managerVersions.set(manager, { value, at: clock() });
+                resolvePromise(value);
+            });
+        });
+    };
+    /** The content key and the lockfile/integrity facts that belong with it. */
+    const keyOf = async (spec, fs, peersOfKey) => {
+        const lock = await readLockfile(fs, spec.lockfile);
+        const attempts = [];
+        for (const attempt of spec.attempts) {
+            const source = sourceOf(spec, attempt.source);
+            const manager = attempt.manager ?? defaultManager;
+            attempts.push({
+                source: {
+                    id: source.id,
+                    registry: source.registry ?? null,
+                    cache: source.cache ?? null,
+                },
+                env: Object.fromEntries(Object.entries(attempt.env ?? {}).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))),
+                allowScripts: attempt.allowScripts ?? false,
+                manager: { name: manager, version: await detectManagerVersion(manager) },
+            });
+        }
+        const packages = sortedRecord(spec.packages);
+        // Peers are identified by EVERYTHING a root commits to: the name, the declared range, and the host
+        // copy that will actually be linked (directory + version). A root physically links that directory,
+        // so a different copy of the same singleton version is a different root too — otherwise the first
+        // installer would hand every other plugin ITS host instance.
+        const peers = [...peersOfKey]
+            .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))
+            .map(peer => ({ name: peer.name, range: peer.range, dir: peer.dir, version: peer.version ?? null }));
+        // `verify` is part of the key like `packages` is: it decides whether a root satisfies the spec,
+        // so a spec with a different (or additional) verify entry must get its own root instead of
+        // failing — and then deleting — another spec's root.
+        const verify = [...spec.verify].sort();
+        const key = sha256Hex(canonicalJson({
+            schemaVersion: RECORD_SCHEMA_VERSION,
+            packages,
+            verify,
+            lockHash: lock.hash,
+            platform,
+            arch,
+            nodeAbi,
+            attempts,
+            peers,
+        }));
+        const integrity = sriOfSha256(sha256Hex(canonicalJson({ key, packages, verify, lockHash: lock.hash, peers })));
+        return { key, lockHash: lock.hash, lockBytes: lock.bytes, lockName: lock.name, integrity };
+    };
+    const storeOf = (home, item) => runtimeDepsStore(home, item.target.root);
+    /** The published root of one key: `targetDir()` and the core's `publish()` must agree on this. */
+    const rootOf = (home, item, key) => join(storeOf(home, item), rootNameOf(home, item, key));
+    const attemptRecord = (spec, attempt, result, started, code, detail) => {
+        const source = sourceOf(spec, attempt.source);
+        return {
+            source: source.id,
+            // The registry is caller-configured and may be `https://user:pass@host/` or carry a
+            // `_authToken`: this record lands in `.runtime.json`, inside a store every plugin can read.
+            // Redacting keeps the endpoint (the audit value) and drops the credential.
+            ...(source.registry === undefined ? {} : { registry: redact(source.registry) }),
+            ...(source.cache === undefined ? {} : { cache: source.cache }),
+            manager: attempt.manager ?? defaultManager,
+            envKeys: Object.keys(attempt.env ?? {}).sort(),
+            allowScripts: attempt.allowScripts ?? false,
+            result,
+            ...(code === undefined ? {} : { code }),
+            // The detail is persisted (`.runtime.json`, `status.json.last_error`) and logged: manager output
+            // can echo a registry userinfo or a token, so it is scrubbed on the way in.
+            ...(detail === undefined ? {} : { detail: tail(redact(detail)) }),
+            ms: Math.max(0, clock() - started),
+        };
+    };
+    const writeRecord = async (fs, staging, keyInfo, spec, attempts, peers, linkModes) => {
+        const record = {
+            schemaVersion: RECORD_SCHEMA_VERSION,
+            kind: RUNTIME_DEPS_KIND,
+            state: 'ready',
+            key: keyInfo.key,
+            packages: sortedRecord(spec.packages),
+            lockHash: keyInfo.lockHash,
+            platform,
+            arch,
+            nodeAbi,
+            attempts,
+            peers: peers.map(peer => peer.name).sort(),
+            copiedPeers: linkModes.filter(link => link.mode === 'copied').map(link => link.name).sort(),
+            integrity: keyInfo.integrity,
+            installedAt: new Date(clock()).toISOString(),
+        };
+        // Order matters: the record is readable before the completion marker appears.
+        await fs.writeFile(join(staging, RECORD_FILE), encodeJson(record));
+        await fs.writeFile(join(staging, READY_FILE), encodeJson({ key: keyInfo.key, installedAt: record.installedAt }));
+        return record;
+    };
+    const resolvedOf = (item, keyInfo, root, source) => ({
+        name: identityName(item),
+        version: keyInfo.key,
+        dir: root,
+        entryDir: root,
+        integrity: keyInfo.integrity,
+        source,
+    });
+    return {
+        id: options.id ?? '@avantf/dsh-plugin-base/runtime-deps',
+        kinds: [RUNTIME_DEPS_KIND],
+        identify(item) {
+            // Never throws: `declare()` is on the plugin's mount path, and an invalid spec must become a
+            // FAILED item (reported by `ensure`) rather than a thrown declaration.
+            return { name: identityName(item) };
+        },
+        targetDir(_item, ref) {
+            // The published unit is the core's version SEGMENT, not the raw version: `publish()` falls back
+            // to a short hash when the absolute path would exceed the path budget, and `rootOf()` derives
+            // the same segment, so probe/plan/install look at exactly this directory.
+            return ref.segment;
+        },
+        async probe(item, ctx) {
+            const spec = parseSpec(item);
+            // Peers are resolved BEFORE the key: which host copy is linked is part of the root's identity.
+            // A host peer that cannot be resolved (or whose version no longer satisfies the declared range)
+            // throws here — a declaration error no reinstall could fix.
+            const peers = await resolvePeers(spec, ctx, options.peerDirs);
+            const keyInfo = await keyOf(spec, ctx.fs, peers);
+            const root = rootOf(ctx.home, item, keyInfo.key);
+            const record = await readReadyRoot(ctx.fs, root, keyInfo.key);
+            if (record === undefined)
+                return { found: false };
+            // `.ready` promises "verified at publish time"; a probe re-checks the cheap half so a root
+            // whose host links moved (or whose tree was damaged) is rebuilt instead of handed to a plugin
+            // that would fail on import.
+            try {
+                await verifyTree(ctx.fs, root, spec, peers);
+            }
+            catch (error) {
+                ctx.logger.warn(`runtime-deps: root ${root} 不再通过校验，将重建（${reasonOf(error).message}）`);
+                return { found: false };
+            }
+            // A copied peer has no link target to compare, so this root's peer identity is version-level.
+            // Say it where the reuse is decided, not only where the copy was made.
+            if (record.copiedPeers !== undefined && record.copiedPeers.length > 0) {
+                ctx.logger.debug(`runtime-deps: ${root} 的 peer ${record.copiedPeers.join(', ')} 以复制方式落盘，identity 为版本级（记录在 .runtime.json 的 copiedPeers）`);
+            }
+            return { found: true, version: keyInfo.key, dir: root, source: 'managed' };
+        },
+        async plan(item, ctx) {
+            const spec = parseSpec(item);
+            // The plan must name the SAME root the install would: peer identity is key material, so a peer
+            // that cannot be resolved leaves the item "cannot plan" rather than a different action.
+            const peers = await resolvePeers(spec, ctx, options.peerDirs);
+            const keyInfo = await keyOf(spec, ctx.fs, peers);
+            const root = rootOf(ctx.home, item, keyInfo.key);
+            const ready = await readReadyRoot(ctx.fs, root, keyInfo.key);
+            return ready === undefined ? { action: 'install' } : { action: 'present', version: keyInfo.key };
+        },
+        async install(item, ctx) {
+            const spec = parseSpec(item);
+            // Peers are resolved BEFORE any reuse/install (and before the lock): a declared host singleton
+            // that cannot be linked — or whose host version no longer matches — is not something a
+            // different registry, or a rebuilt root, could fix, and the resolved identity IS part of the key.
+            const peers = await resolvePeers(spec, ctx, options.peerDirs);
+            const keyInfo = await keyOf(spec, ctx.fs, peers);
+            const store = storeOf(ctx.home, item);
+            const root = rootOf(ctx.home, item, keyInfo.key);
+            // Defense in depth: both names are hex digests, but the core joins them into a path.
+            assertSafeRelativePath(keyInfo.key);
+            const lock = ctx.lock ?? defaultLock();
+            const handle = await lock.acquire(runtimeDepsLockPath(store, keyInfo.key), { timeoutMs: lockTimeoutMs, staleMs: staleLockMs });
+            try {
+                // Another process may have published the same key while this one waited for the lock.
+                if ((await readReadyRoot(ctx.fs, root, keyInfo.key)) !== undefined) {
+                    try {
+                        await verifyTree(ctx.fs, root, spec, peers);
+                        ctx.logger.info(`runtime-deps: reusing ${root}（key ${keyInfo.key.slice(0, 12)}…）`);
+                        // Nothing was placed by THIS call: the core reports the item as `present`.
+                        return { ...resolvedOf(item, keyInfo, root, 'managed'), reused: true };
+                    }
+                    catch (error) {
+                        ctx.logger.warn(`runtime-deps: 已有的根 ${root} 不再通过校验，重建（${reasonOf(error).message}）`);
+                        // Destroying a ready root is only safe because the key covers what a root must satisfy —
+                        // packages, verify entries and peer name/range/resolved-copy identity. A spec that
+                        // declares anything else has a different key and a different root, so this can only ever
+                        // replace OUR OWN tree.
+                        await ctx.fs.rm(root, { recursive: true });
+                    }
+                }
+                // A root without `.ready` is a failed/interrupted attempt: it is not a version to keep.
+                if (await exists(ctx.fs, root)) {
+                    ctx.logger.warn(`runtime-deps: 移除未完成的根 ${root}（没有 ${READY_FILE}）`);
+                    await ctx.fs.rm(root, { recursive: true });
+                }
+                // Staging lives INSIDE the store (same filesystem as the key root, so the rename is atomic).
+                // It is never published directly: `.ready` + the core's install.json are written in it first.
+                stagingSequence += 1;
+                const staging = join(store, `${STAGING_PREFIX}${keyInfo.key}-${String(process.pid)}-${String(stagingSequence)}-${Math.random().toString(36).slice(2, 8)}`);
+                await ctx.fs.mkdir(staging);
+                const records = [];
+                try {
+                    for (const attempt of spec.attempts) {
+                        const source = sourceOf(spec, attempt.source);
+                        const manager = attempt.manager ?? defaultManager;
+                        const started = clock();
+                        try {
+                            // Every attempt starts from the same generated manifest: a manager that failed (or a
+                            // publish that did not reach the rename) must not leave a half-written tree behind.
+                            await cleanInstallTree(ctx.fs, staging, keyInfo.lockName);
+                            await seedStaging(ctx.fs, staging, spec, { bytes: keyInfo.lockBytes, name: keyInfo.lockName });
+                            const result = await run({
+                                manager,
+                                args: managerArgs(manager, source, attempt),
+                                cwd: staging,
+                                env: attemptEnv(attempt, source),
+                                ...(ctx.policy.timeoutMs !== undefined && ctx.policy.timeoutMs > 0 ? { timeoutMs: ctx.policy.timeoutMs } : {}),
+                                ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
+                            });
+                            if (result.code !== 0) {
+                                throw new ProvisionError('runtime-deps/install-failed', `runtime-deps 的 ${manager} install 失败（source ${source.id}，exit ${String(result.code)}）：${tail(redact(result.stderr || result.stdout)) || '无输出'}`);
+                            }
+                            const linkModes = await linkPeers(ctx, staging, peers);
+                            // Verify BEFORE `.ready`: the marker is a promise, not a hope.
+                            await verifyTree(ctx.fs, staging, spec, peers);
+                            const record = await writeRecord(ctx.fs, staging, keyInfo, spec, [
+                                ...records,
+                                attemptRecord(spec, attempt, 'ok', started),
+                            ], peers, linkModes);
+                            ctx.logger.info(`runtime-deps: installed ${String(Object.keys(spec.packages).length)} package(s) into ${root} ` +
+                                `（${manager}，source ${source.id}，integrity ${record.integrity.slice(0, 23)}…）`);
+                            // The core writes its own install.json into staging and atomically renames the tree to
+                            // `<home>/<target.root>/<segment>`. That rename is the publication point.
+                            const resolved = await ctx.publish(staging, {
+                                name: identityName(item),
+                                version: keyInfo.key,
+                                integrity: record.integrity,
+                                source: 'installed',
+                            });
+                            return resolved;
+                        }
+                        catch (error) {
+                            const { code, message } = reasonOf(error);
+                            records.push(attemptRecord(spec, attempt, 'failed', started, code, message));
+                            ctx.logger.warn(`runtime-deps: attempt ${source.id}/${manager} 失败：${message}`);
+                        }
+                    }
+                    const summary = records
+                        .map(record => `${record.source}/${record.manager}: ${record.code ?? 'failed'}（${record.detail ?? ''}）`)
+                        .join('; ');
+                    throw new ProvisionError('runtime-deps/install-failed', `runtime-deps 的所有 attempts 都失败（key ${keyInfo.key.slice(0, 12)}…）：${summary}`, JSON.stringify(records));
+                }
+                finally {
+                    // Remove whatever is left under the staging NAME. On the normal path the core's rename
+                    // already consumed it (rm on a missing path is a no-op); on a failed attempt the tree is
+                    // garbage; and when `publish()` decides an equivalent root is already in place it returns
+                    // WITHOUT renaming — the staging tree is then this call's own leftover, not a root.
+                    await ctx.fs.rm(staging, { recursive: true }).catch(() => undefined);
+                }
+            }
+            finally {
+                handle.dispose();
+            }
+        },
+        async verify(item, resolved, ctx) {
+            const spec = parseSpec(item);
+            const key = resolved.version ?? basename(resolved.dir);
+            const record = await readReadyRoot(ctx.fs, resolved.dir, key);
+            if (record === undefined) {
+                throw new ProvisionError('verify/failed', `runtime-deps 的根没有可用的 ${READY_FILE}/${RECORD_FILE}：${resolved.dir}`);
+            }
+            const peers = await resolvePeers(spec, ctx, options.peerDirs);
+            await verifyTree(ctx.fs, resolved.dir, spec, peers);
+        },
+    };
+}
+/**
+ * Status rows are the family's recorded plugin→resource references.
+ *
+ * `reliable` is false when the file exists but cannot be understood (a newer schema, corrupt JSON,
+ * STRUCTURAL damage — `rows` not an array, a row without `key`/`version`, an IO error): GC must then
+ * treat EVERY root as possibly referenced and remove nothing. Treating an unreadable record as "no
+ * references" would turn one bad file into deleting every shared root — and a partially understood
+ * one (the old lenient reader dropped the rows it could not parse) is the same failure with a smaller
+ * blast radius, which is why `readStatus` reports it as `unreadable` instead.
+ *
+ * `absent` is the same "cannot tell" for a DIFFERENT reason: there is no status plane at all. A
+ * home whose plugin has not recorded anything yet, or whose `status.json` was removed, must not have
+ * its whole shared store deleted because a missing file reads as "no references".
+ */
+async function referencedRuntimeDepsKeys(fs, home) {
+    const keys = new Set();
+    try {
+        const read = await readStatus(fs, home);
+        if (read.kind === 'none')
+            return { keys, reliable: true, absent: true };
+        if (read.kind === 'unreadable' || read.kind === 'too-new')
+            return { keys, reliable: false, absent: false };
+        for (const row of read.rows) {
+            if (row.version === '')
+                continue;
+            if (!row.key.startsWith(`${RUNTIME_DEPS_KIND}+`))
+                continue;
+            keys.add(row.version);
+        }
+    }
+    catch {
+        return { keys, reliable: false, absent: false };
+    }
+    return { keys, reliable: true, absent: false };
+}
+/** Is `value` a content key (the 64-hex digest this provider uses as a root's version)? */
+function isContentKey(value) {
+    return /^[0-9a-f]{64}$/u.test(value);
+}
+/**
+ * The content key a root directory holds.
+ *
+ * Normally the DIRECTORY NAME is the key. It is not when the core shortened the path
+ * (`versionSegment`): then only the provider's own record names the key. A root whose key cannot be
+ * determined is never removed — "cannot tell" must not delete a live root.
+ */
+async function rootContentKey(fs, path, entry) {
+    try {
+        const raw = decodeJson(await fs.readFile(join(path, RECORD_FILE)));
+        if (isRecord(raw)) {
+            const key = raw['key'];
+            if (typeof key === 'string' && key !== '')
+                return key;
+        }
+    }
+    catch {
+        // A root without a readable record falls through to the name.
+    }
+    return isContentKey(entry) ? entry : undefined;
+}
+/**
+ * Parse `<key>-<pid>-<seq>-<rand>` out of a staging name this build wrote. `undefined` means the
+ * name did not come from this provider (a manual/older tree), so only mtime can judge it.
+ */
+function parseStagingName(entry) {
+    const match = /^\.staging-([0-9a-f]{64})-(\d+)/u.exec(entry);
+    const key = match?.[1];
+    const pidText = match?.[2];
+    if (key === undefined || pidText === undefined)
+        return undefined;
+    const pid = Number(pidText);
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return undefined;
+    return { key, pid };
+}
+/**
+ * Remove roots no recorded plugin references. EXPLICIT: this is an operator action, never a startup
+ * step, because a running plugin may hold a key that has not reached `status.json` yet.
+ *
+ * A root is kept when its key is in `keep` or in a `runtime-deps` status row's `version` (the
+ * content key this provider reports). Roots in use by a live per-key lock are skipped, never stolen.
+ */
+export async function gcRuntimeDeps(options) {
+    const fs = options.fs ?? defaultFs();
+    const clock = options.clock ?? Date.now;
+    const staleMs = options.staleMs ?? DEFAULT_STALE_LOCK_MS;
+    const stagingGraceMs = options.stagingGraceMs ?? 60 * 60 * 1000;
+    const logger = options.logger;
+    const store = runtimeDepsStore(options.home, options.root ?? RUNTIME_DEPS_DIR);
+    if (!(await exists(fs, store)))
+        return { removed: [], kept: [], skipped: [], cleaned: [] };
+    const { keys: referenced, reliable, absent } = await referencedRuntimeDepsKeys(fs, options.home);
+    const keep = new Set(options.keep ?? []);
+    const lock = options.lock ?? defaultLock();
+    const handle = await lock.acquire(join(store, '.gc.lock'), { timeoutMs: 10_000, staleMs });
+    const removed = [];
+    const kept = [];
+    const skipped = [];
+    const cleaned = [];
+    let warnedAbsent = false;
+    try {
+        let entries;
+        try {
+            entries = await fs.readdir(store);
+        }
+        catch {
+            return { removed, kept, skipped, cleaned };
+        }
+        for (const entry of [...entries].sort()) {
+            if (entry.startsWith('.'))
+                continue;
+            const path = join(store, entry);
+            const info = await fs.stat(path);
+            if (info?.isDirectory !== true)
+                continue;
+            const key = await rootContentKey(fs, path, entry);
+            if (key === undefined) {
+                // The root's key cannot be determined: it might be the very root a plugin is using.
+                skipped.push(entry);
+                logger?.warn(`runtime-deps gc: 无法确定根 ${path} 的内容 key（记录不可读），保留`);
+                continue;
+            }
+            if (referenced.has(key) || keep.has(key)) {
+                kept.push(entry);
+                continue;
+            }
+            if (!reliable) {
+                // The recorded references cannot be read: every root is "possibly referenced".
+                skipped.push(entry);
+                continue;
+            }
+            if (absent) {
+                // There is no recorded reference at all: a missing plane is "cannot tell", not "unused".
+                if (!warnedAbsent) {
+                    warnedAbsent = true;
+                    logger?.warn(`runtime-deps gc: ${options.home} 没有 status.json，无法判断根是否仍被引用；本次不删除任何根`);
+                }
+                skipped.push(entry);
+                continue;
+            }
+            // A live per-key lock means an install is writing this key right now: do not remove it.
+            if (await lockHeldByLiveProcess(fs, runtimeDepsLockPath(store, key))) {
+                skipped.push(entry);
+                continue;
+            }
+            if (options.dryRun === true) {
+                skipped.push(entry);
+                continue;
+            }
+            try {
+                await fs.rm(path, { recursive: true });
+                removed.push(entry);
+                logger?.info(`runtime-deps gc: removed ${path}`);
+            }
+            catch (error) {
+                skipped.push(entry);
+                logger?.warn(`runtime-deps gc: 无法移除 ${path}（${reasonOf(error).message}）`);
+            }
+        }
+        // Interrupted staging trees: their writer is gone (or old enough) and they can never be published.
+        for (const entry of await fs.readdir(store).catch(() => [])) {
+            if (!entry.startsWith(STAGING_PREFIX))
+                continue;
+            const path = join(store, entry);
+            const info = await fs.stat(path);
+            if (info === undefined)
+                continue;
+            // A staging name this build wrote names its key and its writer. A SLOW install is not a stale
+            // one: past the grace period an mtime says nothing about whether the writer is still alive, so
+            // a live pid (or a live per-key lock, i.e. a waiter about to become the writer) protects it.
+            const staged = parseStagingName(entry);
+            if (staged !== undefined) {
+                if (pidIsAlive(staged.pid)) {
+                    skipped.push(entry);
+                    continue;
+                }
+                if (await lockHeldByLiveProcess(fs, runtimeDepsLockPath(store, staged.key))) {
+                    skipped.push(entry);
+                    continue;
+                }
+            }
+            if (clock() - info.mtimeMs < stagingGraceMs)
+                continue;
+            if (options.dryRun === true) {
+                skipped.push(entry);
+                continue;
+            }
+            try {
+                await fs.rm(path, { recursive: true });
+                cleaned.push(entry);
+            }
+            catch {
+                skipped.push(entry);
+            }
+        }
+        // Dead lock files (a live holder is never reclaimed). The next `acquire` would do this too; GC
+        // makes the store tidy instead of leaving one stale file per crashed process.
+        const locksRoot = join(store, LOCKS_DIR);
+        for (const entry of await fs.readdir(locksRoot).catch(() => [])) {
+            if (!entry.endsWith('.lock'))
+                continue;
+            const path = join(locksRoot, entry);
+            const info = await fs.stat(path);
+            if (info === undefined)
+                continue;
+            if (await lockHeldByLiveProcess(fs, path))
+                continue;
+            if (clock() - info.mtimeMs <= staleMs)
+                continue;
+            if (options.dryRun === true) {
+                skipped.push(join(LOCKS_DIR, entry));
+                continue;
+            }
+            try {
+                await fs.rm(path);
+                cleaned.push(join(LOCKS_DIR, entry));
+            }
+            catch {
+                skipped.push(join(LOCKS_DIR, entry));
+            }
+        }
+    }
+    finally {
+        handle.dispose();
+    }
+    return { removed, kept, skipped, cleaned };
+}
+/** Is the control-plane lock at `path` held by a process that still exists? */
+async function lockHeldByLiveProcess(fs, path) {
+    let raw;
+    try {
+        raw = decodeJson(await fs.readFile(path));
+    }
+    catch {
+        return false;
+    }
+    if (!isRecord(raw))
+        return false;
+    const pid = raw['pid'];
+    return typeof pid === 'number' && pidIsAlive(pid);
+}
+//# sourceMappingURL=runtime_deps.js.map