berry-agent 0.1.0-alpha.1

package/dist/host/plugin-install.js

@@ -0,0 +1,480 @@
+/**
+ * host/plugin-install — 三源装机执行器 + 收割 + update 分派（03 §5.4——
+ * 成熟度缺口 #10 装机面落码批 10b）。
+ *
+ * 三源（§5.4 物理布局/凭证纪律）：
+ *  - **npm**：`npm install --prefix <dataDir>/plugins` 进程外 spawn（07 §5
+ *    「用户显式动作族」——不进 exec 沙箱体系）；供应链四件套执法——
+ *    `--save-exact`（依赖记录钉版落锚）/`--omit=dev`/`--min-release-age`
+ *    （静置窗，缺省 1440 分钟）/`--ignore-scripts`（安装期脚本缺省禁跑）
+ *    + `--omit=peer --legacy-peer-deps`（承 berry 实践条款）；装机树锚
+ *    package.json（缺锚 npm 会向上爬找父 package.json 污染用户文件——锚
+ *    是防线非装饰）；integrity 从 `<prefix>/.package-lock.json` 收割落账
+ *    （tarball 凭证——§5.4「dist-tag 不算凭证」）。
+ *  - **git**：tmp 克隆 → checkout ref → HEAD commit 收割落账（精确 commit
+ *    锁定）→ rename 落 `plugins/git/<host>/<首段>/<repo>/`（分层防撞名）。
+ *  - **local**：直引不拷贝（installPath = canonical 绝对；§5.5 不删用户
+ *    目录）——无凭证字段。
+ *
+ * 收割（§5.4 词表账本）：jiti 求值入口模块读 `events` 导出——「装机零生效」
+ * 的唯一例外（仅模块求值，零 apply 零注册）；jiti 参数与装载器同形（虚拟面
+ * 四键直注 + import 门禁 transform + fsCache 关——同律不因装机时点放宽）。
+ * 纯声明包（declared-payload 态）零码收割（declaredEvents = []）。
+ *
+ * 失败回滚：装机物落位后清单校验/收割失败 = rm 装机物再拒（不留半装机残影
+ * ——账本未落，回滚后两账一致空态）。
+ *
+ * spawn 注入面：测试注假件零真网络（npm/git 两执行器的 argv 断言 + 落账
+ * 编舞可测）；local 源与收割真跑（本地 fixture 零网络）。
+ */
+import { execFile } from 'node:child_process';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { createJiti } from 'jiti';
+import { BaseError } from '../contracts/index.js';
+import { installPathForGit, installPathForLocal, installPathForNpm, ledgerPath, parentDir, readLedger, resolveInstallPath, upsertLedgerEntry, } from './plugin-store.js';
+import { parseManifest } from './manifest.js';
+import { createGateTransform } from './import-gate.js';
+import { loadDefaultVirtualFaces, resolvePkgMain } from './loader.js';
+/**
+ * ref 单源词法（CLI `plugins install <ref>` 与账本 ref 字段同一表示——
+ * 无变换直通）：`npm:<pkg>[@<version>]` / `git:<url>[#<ref>]` /
+ * `local:<abs-path>`。前缀三选一强制（无前缀 = 用法错——不猜默认源）。
+ */
+export function parsePluginRef(ref) {
+    if (ref.startsWith('npm:')) {
+        const spec = ref.slice('npm:'.length);
+        if (spec.length === 0)
+            return { ok: false, message: 'npm ref 缺包名（形如 npm:acme-widgets@1.2.0）' };
+        const at = spec.lastIndexOf('@');
+        // scoped 包 @scope/pkg：@ 在位 0 是 scope 前缀非版本分隔——只认 >0 的 @
+        if (at > 0) {
+            return { ok: true, parsed: { source: 'npm', pkg: spec.slice(0, at), version: spec.slice(at + 1) } };
+        }
+        return { ok: true, parsed: { source: 'npm', pkg: spec } };
+    }
+    if (ref.startsWith('git:')) {
+        const spec = ref.slice('git:'.length);
+        if (spec.length === 0)
+            return { ok: false, message: 'git ref 缺 url（形如 git:https://github.com/o/r.git#v1.2.0）' };
+        const hash = spec.lastIndexOf('#');
+        if (hash >= 0) {
+            const gitRef = spec.slice(hash + 1);
+            if (gitRef.length === 0)
+                return { ok: false, message: 'git ref 的 # 后为空（分支/tag/commit）' };
+            return { ok: true, parsed: { source: 'git', url: spec.slice(0, hash), gitRef } };
+        }
+        return { ok: true, parsed: { source: 'git', url: spec } };
+    }
+    if (ref.startsWith('local:')) {
+        const spec = ref.slice('local:'.length);
+        if (spec.length === 0)
+            return { ok: false, message: 'local ref 缺路径（形如 local:/abs/path/to/plugin）' };
+        return { ok: true, parsed: { source: 'local', path: spec } };
+    }
+    return { ok: false, message: `ref 须自含源前缀 npm:/git:/local:（得 "${ref}"）——与装机账本 ref 字段同形` };
+}
+/* ---------------- min-release-age 配置解析（§5.4 供应链③） ---------------- */
+/** 静置窗缺省（分钟）——24h，03 §5.4 装机面落码批定形 */
+export const DEFAULT_MIN_RELEASE_AGE_MINUTES = 1440;
+/** env 名（07 §2.1 名册在册位——BERRY_AGENT_PLUGIN_MIN_RELEASE_AGE） */
+export const MIN_RELEASE_AGE_ENV = 'BERRY_AGENT_PLUGIN_MIN_RELEASE_AGE';
+/**
+ * 静置窗解析（CLI 旗标 > env > 缺省 1440）。无效值（非数字/负数/NaN）=
+ * fail-loud（短命装机动作当场红优于静默降级——与 LOG_LEVEL 长跑让位律
+ * 分立两律）。
+ */
+export function resolveMinReleaseAge(input) {
+    if (input.cliFlag !== undefined)
+        return input.cliFlag; // CLI 解析层已验正整数
+    const raw = input.env?.[MIN_RELEASE_AGE_ENV];
+    if (raw !== undefined && raw !== '') {
+        const n = Number(raw);
+        if (!Number.isFinite(n) || n < 0 || !Number.isInteger(n)) {
+            throw new BaseError('PLUGIN_INSTALL_FAILED', `${MIN_RELEASE_AGE_ENV}="${raw}" 坏形——须为非负整数分钟数（0 = 显式关窗）`);
+        }
+        return n;
+    }
+    return DEFAULT_MIN_RELEASE_AGE_MINUTES;
+}
+/** 缺省真身（maxBuffer 放大——npm 安装输出可观；非零退出 = reject 带 stderr） */
+export function createDefaultSpawnRunner() {
+    const runFile = promisify(execFile);
+    return {
+        run: (cmd, args, options) => runFile(cmd, [...args], { cwd: options.cwd, maxBuffer: 64 * 1024 * 1024 }),
+    };
+}
+/* ---------------- 装机编舞主入口 ---------------- */
+/**
+ * install 编舞（§5.4）：撞名拒（同 id 已装指路 update）→ 按源执行 → 清单
+ * 校验 → 收割 → 落账。执行器产出 installPath + 凭证字段；收割失败/清单坏形
+ * = 回滚装机物再拒（不留半装机残影）。core: 前缀 id 拒（官方件身份——非
+ * 装机物）。`replacingId` = update 分派的换装豁免位（npm 重装腿复用本编舞
+ * 时旧条目尚在场——恰是被替换者，不构成撞名；其余 id 照拒）。
+ */
+export async function installPlugin(deps, ref, opts = {}) {
+    const parsed = parsePluginRef(ref);
+    if (!parsed.ok)
+        return parsed;
+    // 账本前置读（坏账本拒写防覆盖——与 upsertLedgerEntry 内防线双检）
+    const ledgerRead = readLedger(deps.dataDir, deps.fs);
+    if (!ledgerRead.ok) {
+        return {
+            ok: false,
+            message: `装机账本损坏（${ledgerPath(deps.dataDir)}）：${ledgerRead.reason}——拒写防覆盖（03 §5.4）`,
+        };
+    }
+    // 执行器先行（装机物落位 + manifest 读——失败红即拒，账面零动作）
+    let product;
+    try {
+        product =
+            parsed.parsed.source === 'npm'
+                ? await runNpmInstall(deps, parsed.parsed)
+                : parsed.parsed.source === 'git'
+                    ? await runGitInstall(deps, parsed.parsed)
+                    : runLocalInstall(deps, parsed.parsed);
+    }
+    catch (err) {
+        return { ok: false, message: err instanceof Error ? err.message : String(err) };
+    }
+    // 清单校验（§1.2 拒绝式——装机时点红优于装载时点）
+    if (!product.manifest.ok) {
+        rollbackInstall(deps, product.installPath);
+        return { ok: false, message: `清单校验失败（${ref}）：${product.manifest.message}` };
+    }
+    const manifest = product.manifest.manifest;
+    if (manifest.id.startsWith('core:')) {
+        rollbackInstall(deps, product.installPath);
+        return { ok: false, message: `清单 id "${manifest.id}" 带官方前缀——core: 为官方插件保留（03 §1.2），装机拒` };
+    }
+    if (ledgerRead.entries.some((e) => e.id === manifest.id && e.id !== opts.replacingId)) {
+        rollbackInstall(deps, product.installPath);
+        return {
+            ok: false,
+            message: `插件 ${manifest.id} 已装机（源 ${ledgerRead.entries.find((e) => e.id === manifest.id).source}）——换版本走 update，先卸走 uninstall（03 §5.4）`,
+        };
+    }
+    // 收割（§5.4 词表账本——装机零生效唯一例外：仅模块求值读 events 导出）
+    let declaredEvents;
+    try {
+        declaredEvents = await harvestEvents(deps, resolveInstallPath(deps.dataDir, product.installPath), product.installPath, manifest);
+    }
+    catch (err) {
+        rollbackInstall(deps, product.installPath);
+        return {
+            ok: false,
+            message: `收割失败（${ref}）——装机回滚：${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // 落账（条目数组形原子写——plugin-store 执法）
+    const now = deps.now ?? (() => new Date()); // Date 构造子裸调用返 string（JS 遗留）——显式闭包归一
+    const entry = {
+        id: manifest.id,
+        source: parsed.parsed.source,
+        ref,
+        version: manifest.version ?? product.version,
+        ...(product.integrity !== undefined ? { integrity: product.integrity } : {}),
+        ...(product.commit !== undefined ? { commit: product.commit } : {}),
+        installedAt: now().toISOString(),
+        installPath: product.installPath,
+        declaredEvents,
+    };
+    upsertLedgerEntry(deps.dataDir, entry, deps.fs);
+    // 生命周期归因账（05 §1.1）：装机成功事实落 audit_events——词形
+    // {id, source, version}；version 位缺席不落键（git/local 源清单可能无
+    // 版本位）。replacingId 场景（update npm 重装腿）已在调用侧剥 sink，
+    // 到达此处的恒为首次装机
+    deps.onLifecycleAudit?.('plugin/installed', {
+        id: manifest.id,
+        source: parsed.parsed.source,
+        ...(entry.version !== undefined ? { version: entry.version } : {}),
+    });
+    return {
+        ok: true,
+        entry,
+        text: `已装机：${manifest.id}（源 ${parsed.parsed.source}，${product.installPath}）——装机零生效，启用走 mount（下次启动装载生效）`,
+    };
+}
+/** 装机物回滚（清单/收割失败腿——local 源不删〔直引非装机物〕） */
+function rollbackInstall(deps, installPath) {
+    if (installPath === '' || installPath.startsWith('/'))
+        return; // local 绝对表示 = 用户源不删
+    try {
+        deps.fs.rm(resolveInstallPath(deps.dataDir, installPath), { recursive: true, force: true });
+    }
+    catch {
+        // 回滚失败不吞装机油——主错误照呈（残影目录下次 install 前置 rm 收敛）
+    }
+}
+/* ---------------- npm 源执行器 ---------------- */
+/**
+ * npm 源执行（§5.4 四件套执法）。锚 package.json 缺席即写最小锚（防 npm
+ * 向上爬父目录污染用户文件）；`--prefix` 装进装机树；integrity/version 从
+ * `.package-lock.json` 收割（tarball 凭证真源）。
+ */
+async function runNpmInstall(deps, parsed) {
+    const pluginsDir = join(deps.dataDir, 'plugins');
+    deps.fs.mkdir(pluginsDir, { recursive: true });
+    // 锚 package.json（缺席才写——在场保用户/前次装机产物，不覆盖）
+    if (deps.fs.read(join(pluginsDir, 'package.json')) === null) {
+        deps.fs.write(join(pluginsDir, 'package.json'), `${JSON.stringify({ name: 'berry-agent-plugin-tree', private: true }, null, 2)}\n`);
+    }
+    const argv = [
+        'install',
+        '--prefix',
+        pluginsDir,
+        '--save-exact', // ① 直接依赖钉版（依赖记录 exact 无 ranges）
+        '--omit=dev', // ② devDependencies 不装
+        '--omit=peer',
+        '--legacy-peer-deps',
+        '--ignore-scripts', // ④ 安装期脚本禁跑（白名单开面归点火日）
+        ...buildMinReleaseAgeFlags(deps),
+        parsed.version !== undefined ? `${parsed.pkg}@${parsed.version}` : parsed.pkg,
+    ];
+    try {
+        await deps.spawn.run('npm', argv, {});
+    }
+    catch (err) {
+        throw new BaseError('PLUGIN_INSTALL_FAILED', npmFailureMessage(err, buildMinReleaseAgeFlags(deps).join(' ')), {
+            cause: err,
+        });
+    }
+    // 凭证收割：.package-lock.json 的 packages[<装机目录>].integrity + version
+    const installPath = installPathForNpm(parsed.pkg);
+    const lockText = deps.fs.read(join(pluginsDir, '.package-lock.json'));
+    const lock = lockText === null
+        ? undefined
+        : JSON.parse(lockText);
+    const lockEntry = lock?.packages?.[`node_modules/${parsed.pkg}`];
+    return {
+        installPath,
+        manifest: readManifestAt(deps, installPath),
+        version: lockEntry?.version,
+        integrity: lockEntry?.integrity,
+    };
+}
+/** min-release-age 旗标族（0 = 显式关窗 → 不传旗标——npm 无「关闭」值形） */
+function buildMinReleaseAgeFlags(deps) {
+    const minutes = resolveMinReleaseAge({
+        ...(deps.env !== undefined ? { env: deps.env } : {}),
+        ...(deps.minReleaseAgeOverride !== undefined ? { cliFlag: deps.minReleaseAgeOverride } : {}),
+    });
+    return minutes <= 0 ? [] : ['--min-release-age', String(minutes)];
+}
+/** npm 失败增补指路（--min-release-age 旧版不识 → 指路升级） */
+function npmFailureMessage(err, flagText) {
+    const stderr = err instanceof Error ? (err.stderr ?? '') : '';
+    const message = err instanceof Error ? err.message : String(err);
+    const ageHint = stderr.includes('min-release-age') || stderr.includes('Unknown cli flag') || stderr.includes('unknown option')
+        ? `——npm 不识 ${flagText}：--min-release-age 须 npm ≥11.5（npm -v 自查），或设 ${MIN_RELEASE_AGE_ENV}=0 关窗`
+        : '';
+    return `npm install 失败：${message}${ageHint}`;
+}
+/* ---------------- git 源执行器 ---------------- */
+/**
+ * git 源执行：tmp 克隆（默认 branch）→ checkout gitRef（detach——branch/
+ * tag/commit 皆可）→ HEAD commit 收割 → 落位 `plugins/git/<host>/<首段>/
+ * <repo>/`（目标在场先 rm——幂等重装/撞名目录收敛）。克隆浅化不启用
+ * （checkout 任意历史 commit 需全史——--depth 与 commit ref 冲突）。
+ */
+async function runGitInstall(deps, parsed) {
+    const tmp = mkdtempSync(join(deps.tmpRoot ?? tmpdir(), 'berry-git-install-'));
+    try {
+        await deps.spawn.run('git', ['clone', parsed.url, tmp], {});
+        if (parsed.gitRef !== undefined) {
+            await deps.spawn.run('git', ['-C', tmp, 'checkout', '--detach', parsed.gitRef], {});
+        }
+        const head = await deps.spawn.run('git', ['-C', tmp, 'rev-parse', 'HEAD'], {});
+        const commit = head.stdout.trim();
+        const installPath = installPathForGit(parsed.url); // 坏 url 抛 PLUGIN_INSTALL_FAILED——ref 前置已校，保底
+        const target = resolveInstallPath(deps.dataDir, installPath);
+        deps.fs.mkdir(parentDir(target), { recursive: true });
+        deps.fs.rm(target, { recursive: true, force: true }); // 幂等（在场旧树先清）
+        deps.fs.rename(tmp, target);
+        return {
+            installPath,
+            manifest: readManifestAt(deps, installPath),
+            commit,
+            version: undefined,
+        };
+    }
+    finally {
+        // rename 成功后 tmp 已不存在——force rm 幂等收尾
+        deps.fs.rm(tmp, { recursive: true, force: true });
+    }
+}
+/* ---------------- local 源执行器 ---------------- */
+/** local 源执行：直引不拷贝（installPath = canonical 绝对；§5.4 表示法） */
+function runLocalInstall(deps, parsed) {
+    let installPath;
+    try {
+        installPath = installPathForLocal(parsed.path);
+    }
+    catch (err) {
+        throw new BaseError('PLUGIN_INSTALL_FAILED', `local 路径坏形（${parsed.path}）：${err instanceof Error ? err.message : String(err)}`, {
+            cause: err,
+        });
+    }
+    return { installPath, manifest: readManifestAt(deps, installPath) };
+}
+/* ---------------- 清单读取（三源共用） ---------------- */
+/** 装机目录读 package.json 过清单校验（§1.2 拒绝式——官方位 false） */
+function readManifestAt(deps, installPath) {
+    const pluginDir = resolveInstallPath(deps.dataDir, installPath);
+    const text = deps.fs.read(join(pluginDir, 'package.json'));
+    if (text === null) {
+        return {
+            ok: false,
+            code: 'PLUGIN_SHAPE_INVALID',
+            message: `装机目录无 package.json（${pluginDir}）——三源执行产物异常`,
+        };
+    }
+    try {
+        return parseManifest(JSON.parse(text));
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: 'PLUGIN_SHAPE_INVALID',
+            message: `package.json 坏 JSON（${pluginDir}）：${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+/* ---------------- 收割（§5.4 词表账本） ---------------- */
+/**
+ * install 收割：jiti 求值入口模块读 `events` 导出（§1.3——装机零生效唯一
+ * 例外）。与装载器同形：虚拟面四键直注（顶层 import 'berry-agent' 不炸）+
+ * import 门禁 transform（03 §3.3 同律——装机时点不放宽）+ fsCache 关（门
+ * 禁身份不入缓存键）。纯声明包（declared-payload）零码收割。非字符串数组
+ * events 导出 = 收割失败（词表账本容不得坏形）。
+ */
+async function harvestEvents(deps, pluginDir, installPath, manifest) {
+    if (manifest.entryPlan.kind === 'declared-payload')
+        return []; // 纯声明包零码
+    const entryFile = manifest.entryPlan.kind === 'entry-file' ? manifest.entryPlan.entry : resolvePkgMain(pluginDir);
+    const entryId = join(pluginDir, entryFile);
+    const jiti = deps.jitiFactory?.(pluginDir, manifest.id) ??
+        createJiti(join(pluginDir, 'package.json'), {
+            transform: createGateTransform({ pluginId: manifest.id, pluginDir }),
+            interopDefault: true,
+            moduleCache: true,
+            fsCache: false, // 与装载器同律（门禁身份不入缓存键）
+            virtualModules: await loadDefaultVirtualFaces(),
+        });
+    let namespace;
+    try {
+        namespace = (await jiti.import(entryId));
+    }
+    catch (err) {
+        throw new BaseError('PLUGIN_INSTALL_FAILED', `收割求值入口模块失败（${installPath}/${entryFile}）：${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    const events = namespace['events'];
+    if (events === undefined)
+        return [];
+    if (!Array.isArray(events) || events.some((e) => typeof e !== 'string' || e.length === 0)) {
+        throw new BaseError('PLUGIN_SHAPE_INVALID', `入口 events 导出须字符串数组（插件 ${manifest.id}）——词表账本容不得坏形`);
+    }
+    return events;
+}
+/* ---------------- update 分派（§5.4 按源） ---------------- */
+/**
+ * update 编舞（§5.4 按源分派）：npm 重装（拉最新满足窗龄版——`--save-exact`
+ * 锚树 + 无版本 spec = latest 受 min-release-age 窗检；新 integrity/version
+ * 落账）；git 删目录按原 ref 重克隆（新 commit）；local no-op（源动了下次
+ * 装载即新——§5.4 既有条款）。enabled 行不动（装机物换血、行引用 id 不变）。
+ */
+export async function updatePlugin(deps, id) {
+    const ledgerRead = readLedger(deps.dataDir, deps.fs);
+    if (!ledgerRead.ok) {
+        return { ok: false, message: `装机账本损坏：${ledgerRead.reason}——拒写防覆盖（03 §5.4）` };
+    }
+    const current = ledgerRead.entries.find((e) => e.id === id);
+    if (current === undefined) {
+        return { ok: false, message: `插件 ${id} 未装机——无可更新（装机清单见 plugins list）` };
+    }
+    if (current.source === 'local') {
+        return { ok: true, entry: current, text: `local 源直引不拷贝——源目录变更下次装载即生效（03 §5.4 no-op 分派）` };
+    }
+    // local 之外的 ref 重解析（账本 ref 与 CLI 同词法——单源往返）
+    const parsed = parsePluginRef(current.ref);
+    if (!parsed.ok) {
+        return { ok: false, message: `账本 ref 坏形（${current.ref}）：${parsed.message}——重装可重建` };
+    }
+    if (parsed.parsed.source === 'local') {
+        // 病理态保底（local 已在上方 no-op 返回——账本 source 与 ref 前缀不一致）
+        return { ok: false, message: `账本 source 与 ref 前缀不一致（${current.ref}）——重装可重建` };
+    }
+    if (parsed.parsed.source === 'npm') {
+        // 重装：旧装机物先清（spec 无版本 = 拉最新满足窗龄；upsert 后见胜出）。
+        // 换装豁免位传被替换 id——旧条目恰是替换目标不构成撞名（缺此豁免则
+        // installPlugin 撞名检查恒拒自家重装腿）。sink 剥离后再传——防
+        // installPlugin 成功尾落错词 installed（本腿语义是 updated）
+        const { onLifecycleAudit, ...rest } = deps;
+        const installPath = installPathForNpm(parsed.parsed.pkg);
+        rest.fs.rm(resolveInstallPath(rest.dataDir, installPath), { recursive: true, force: true });
+        const outcome = await installPlugin(rest, current.ref, { replacingId: id });
+        if (outcome.ok && onLifecycleAudit !== undefined) {
+            // 换装成功事实（05 §1.1）：from 缺席容许（旧账本无版本位）；npm 腿
+            // version 恒在（lock 收割），to 缺席不设防（兜底与 git 腿同形）
+            onLifecycleAudit('plugin/updated', {
+                id,
+                ...(current.version !== undefined ? { from: current.version } : {}),
+                ...(outcome.entry.version !== undefined ? { to: outcome.entry.version } : {}),
+            });
+        }
+        return outcome;
+    }
+    // git 重克隆（runGitInstall 目标在场先 rm——幂等腿复用）
+    let product;
+    try {
+        product = await runGitInstall(deps, parsed.parsed);
+    }
+    catch (err) {
+        return { ok: false, message: err instanceof Error ? err.message : String(err) };
+    }
+    if (!product.manifest.ok) {
+        rollbackInstall(deps, product.installPath);
+        return { ok: false, message: `更新后清单校验失败（${id}）：${product.manifest.message}` };
+    }
+    const manifest = product.manifest.manifest;
+    if (manifest.id !== id) {
+        rollbackInstall(deps, product.installPath);
+        return { ok: false, message: `更新后清单 id 变更（${id} → ${manifest.id}）——装机身份漂移拒（卸后重装走两步）` };
+    }
+    let declaredEvents;
+    try {
+        declaredEvents = await harvestEvents(deps, resolveInstallPath(deps.dataDir, product.installPath), product.installPath, manifest);
+    }
+    catch (err) {
+        rollbackInstall(deps, product.installPath);
+        return {
+            ok: false,
+            message: `更新收割失败（${id}）——装机回滚：${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    const entry = {
+        ...current,
+        commit: product.commit,
+        installedAt: (deps.now ?? (() => new Date()))().toISOString(),
+        installPath: product.installPath,
+        declaredEvents,
+    };
+    upsertLedgerEntry(deps.dataDir, entry, deps.fs);
+    // 换装成功事实（05 §1.1）：git 溢词形 {id, from?, to}——但 git 源
+    // entry.version 继承旧账恒不变（变更实质在 commit 位），落 version 会造
+    // 「版本换血」误读；from/to 落 commit 值（git 源的版本标识即 commit——
+    // 03 §5.4 精确锁定语义；npm 腿同键落 semver，源别可回 installed 词
+    // source 位对拍）。旧 commit 缺席（早期账本）from 不落
+    deps.onLifecycleAudit?.('plugin/updated', {
+        id,
+        ...(current.commit !== undefined ? { from: current.commit } : {}),
+        ...(product.commit !== undefined ? { to: product.commit } : {}),
+    });
+    return {
+        ok: true,
+        entry,
+        text: `已更新：${id}（源 git，commit ${product.commit?.slice(0, 7) ?? '?'}）——下次启动装载生效`,
+    };
+}

package/dist/host/plugin-reload.js

@@ -0,0 +1,124 @@
+/**
+ * host/plugin-reload — /reload 排队编舞件（03 §5.7——热重载的编舞与失败三档）。
+ *
+ * 职责 = 把「重跑装载」变成一条**可排队、可串行、失败分档**的编舞：
+ *  - **busy 判据** = 任一 run 在飞（03 §5.7「会话运行中」——单对话本体）；
+ *    busy 期 /reload 进 **pending 单槽**——连发并槽 coalesce（reload 读盘为
+ *    准、无请求参数，「最后态」即当前盘面，单槽布尔即完备表达）；
+ *  - **run 收场即执行**：onRunSettled 订阅驱动终态边界（04 §2 三值——settled
+ *    即非 busy 判定点），pending 在场且此刻不 busy → 出槽入链；
+ *  - **失败三档**（由轻到重，03 §5.7）：
+ *    ① 启用清单校验失败 = **拒换**——preflight 前置于一切回卷（旧装载态
+ *    原封不动继续跑，报告行级错误与修复指引）；
+ *    ② 行级装载失败 = **换入 + 报告**——bootPlugins 行级隔离降级内置
+ *    （boot-failures.json 点名 + warn 横幅 + failed 面汇总），本件只回执
+ *    汇总计数，不重复执法；
+ *    ③ disposer 回卷失败 = **降级存活**——回卷抛错不阻断换入（宿主进程
+ *    不死），聚合报告回卷失败清单，旧代残迹随下一轮全量重载收口；
+ *  - **reloadChain 串行**：in-flight promise 链——并发 /reload 恒串行不
+ *    交错（链尾吞错自愈，后续请求不受前次失败连坐）。
+ *
+ * 换入语义边界（本件不执法、由闭包真身承载）：reapply 成功 = 装配根重跑
+ * bootPlugins 并把新代句柄写回闭包晚绑定位（boot 取值器/换代槽/skills 层
+ * 重同步随 reapply 闭包内完成——assembly 接线位见彼处注释）。
+ *
+ * 救援环律（07 §5 --no-plugins 条款）：「/reload 读盘不受旗标影响」——
+ * reapply 闭包在装配侧以 noPlugins: false 形构造（旗标只管启动期短路，
+ * 人面显式 reload 即显式装载请求），本件零旗标知识。
+ */
+/** 编舞注入面（全部闭包真身——本件零 db/fs/驱动知识，词面独立律） */
+import { formatPluginFailureText } from './boot-failures.js';
+/**
+ * 组装 /reload 编舞器。订阅生命周期：onRunSettled 订阅随编舞器终身（进程
+ * 级单例——TUI 入口构造一次；不设 dispose 面，进程退出即回收）。
+ */
+export function createPluginReloader(options) {
+    const warn = options.warn ?? ((message) => process.stderr.write(`${message}\n`));
+    /** pending 单槽（coalesce 判据位——true = busy 期有请求待执行） */
+    let pending = false;
+    /** reloadChain（in-flight promise 链尾——串行执法位） */
+    let chain = Promise.resolve();
+    /** 单次重载编舞（失败三档执法序：①preflight → ③rollback → ②reapply） */
+    const runOnce = async () => {
+        // ① 清单校验失败 = 拒换——旧装载态原封不动（回卷零调用）
+        try {
+            options.preflight();
+        }
+        catch (err) {
+            options.report(`重载已拒（启用清单校验失败——旧装载态继续运行）：${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        // ③ 回卷旧代——失败降级存活：聚合报告后继续换入（残迹随下轮重载收口）
+        let rollbackFailedIds = [];
+        try {
+            const receipt = await options.rollback();
+            rollbackFailedIds = receipt.failed;
+            if (receipt.failed.length > 0) {
+                warn(`插件回卷部分失败（${receipt.failed.join('、')}）——残迹随下一轮重载收口`);
+            }
+        }
+        catch (err) {
+            warn(`插件回卷失败（降级存活，继续换入）：${err instanceof Error ? err.message : String(err)}`);
+            rollbackFailedIds = ['<rollback>'];
+        }
+        // ② 换入新代——行级失败已由装载序内置隔离（boot-failures 记账 + 横幅），
+        //    本层只回执汇总；抛错（core: fail-loud 等罕见尾路径）= 降级存活报告
+        try {
+            const receipt = await options.reapply();
+            const lines = [`插件已重载：启用 ${receipt.enabled}/${receipt.total}`];
+            if (receipt.addedTools.length > 0) {
+                // 新代工具面 diff 呈现（03 §2.8——新增工具名逐插件；无新增不加行不造噪声）
+                lines.push(`新增工具面：${receipt.addedTools.map((a) => `${a.pluginId} → ${a.tools.join('、')}`).join('；')}`);
+            }
+            if (receipt.failures.length > 0) {
+                // 行级失败附错误文本（03 §5.7② obs-a 呈现三面之③——与 plugins list
+                // 失败分区同形行；boot-failures.json 已由装载序记账）
+                lines.push(`行级失败（隔离降级，已记 boot-failures）：\n${receipt.failures.map((f) => `  ${f.id}  ${formatPluginFailureText(f)}`).join('\n')}`);
+            }
+            if (rollbackFailedIds.length > 0) {
+                lines.push(`上代回卷残留（下轮重载收口）：${rollbackFailedIds.join('、')}`);
+            }
+            options.report(lines.join('\n'));
+        }
+        catch (err) {
+            options.report(`重载失败（旧装载面已回卷、新代未立）：${err instanceof Error ? err.message : String(err)}——修复后可再 /reload；仍失败可用 --no-plugins 启动排查`);
+        }
+    };
+    /** 入链（串行执法——链尾吞错自愈，后续请求不受前次失败连坐） */
+    const enqueue = () => {
+        chain = chain.then(runOnce).catch((err) => {
+            // runOnce 内部已分档吞错，此处是防御性兜底（编舞自身异常不反噬链）
+            warn(`/reload 编舞异常：${err instanceof Error ? err.message : String(err)}`);
+        });
+    };
+    // run 收场即执行：pending 在场且此刻不 busy → 出槽入链（settled 边界后
+    // 仍 busy = 多会话交错——保持排队等下一个终态边界）
+    options.onRunSettled(() => {
+        if (pending && !options.isBusy()) {
+            pending = false;
+            enqueue();
+        }
+    });
+    return {
+        request: () => {
+            if (options.isBusy()) {
+                // busy 期并槽 coalesce——连发只跑最后态（读盘为准，单槽即完备）
+                if (!pending)
+                    options.report('会话运行中——/reload 已排队，本轮收场后执行');
+                pending = true;
+                return;
+            }
+            enqueue();
+        },
+        hasPending: () => pending,
+        settle: () => chain,
+    };
+}
+/** RollbackReceipt 构造速记（rollback 闭包真身侧使用——空代 no-op 形） */
+export function emptyRollbackReceipt() {
+    return { disposed: [], failed: [] };
+}
+/** LoadReport.unload 回执 → RollbackReceipt 适配（failed 对象面 → id 清单——呈现形） */
+export function rollbackFromReport(receipt) {
+    return { disposed: receipt.disposed, failed: receipt.failed.map((f) => f.id) };
+}