@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/argent-upgrade.mjs

@@ -0,0 +1,1046 @@
+#!/usr/bin/env node
+/**
+ * argent-upgrade.mjs — Argent 自举式完整升级器（v0.9 产品语义）
+ *
+ * 「检查更新 = 完整升级」：无论当前插件版本多旧，升级逻辑本体随 git 分发、
+ * 从磁盘读取、不依赖运行中的插件代码——先 pull 再执行最新逻辑，杜绝半升级。
+ *
+ * 用法：
+ *   node argent-upgrade.mjs check               # 检测远端版本（git fetch + origin/main VERSION）
+ *   node argent-upgrade.mjs run                 # 完整升级（pull + preset/skills + patch 组合校正 + 插件同步）
+ *   node argent-upgrade.mjs run --restart       # 同上，完成后自动重启 dsh web（macOS launchd 场景）
+ *   node argent-upgrade.mjs run --json          # JSON 输出（core /api/argent-state/update 端点调用）
+ *   node argent-upgrade.mjs migrate-deps         # 存量迁移：profile 的遗留 `file:` 依赖 ⇒ npm 名（**默认干跑**）
+ *   node argent-upgrade.mjs migrate-deps --apply  # 真的写（写前备份 + sha256 + 审计 + 读回验收；幂等）
+ *   node argent-upgrade.mjs migrate-deps --apply --allow-package-manager  # 显式允许跑包管理器（⛔ 默认不跑）
+ *
+ * 目标组合（v0.9 产品定义，随版本演进修改此处）：
+ *   业务型（有 kanban/gateway/notify 任一或 gateway.json）→ core/skin/kanban/notify/drive/gateway
+ *   对话型（仅 core/skin）                        → core/skin
+ * v0.8 起摘除的插件（组合外出现即移除行）：files / instances / instances-local / tool-instances / packs / ml
+ *
+ * ## 技能同步**只发外发集**（2026-10-04；D5）
+ * 第 3 步只同步 **`classify()` 判定的 external**（= 所有 `verticals/<id>/manifest.json#skills` 的并集），
+ * **内部角色技能（`skills/internal.json`）不外发**；宿主技能根里**已有的**内部/旧技能**只报告不删**
+ * （客户机现状 = 5 外发 + 6 内部 + 旧 hermes 期技能 ⇒ 报告里列"多出"清单，删不删由人决定）。
+ * 判据**不在本文件**：唯一实现是 `scripts/check-skill-classification.mjs#classify()`。
+ */
+
+import { homedir } from 'node:os'
+import { basename, dirname, join, resolve } from 'node:path'
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, cpSync, readdirSync, copyFileSync } from 'node:fs'
+import { execFileSync, spawn } from 'node:child_process'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+import {
+  applyDepsMigration, planDepsMigration, realVersionOf, knownPluginId, renderPlan,
+} from './lib/deps-migrate.mjs'
+import { retirePlugins as retirePluginsImpl } from './lib/profile-retire.mjs'
+import { BUNDLE_LAYER_PLUGINS, bundleLayerRows, pluginRowName, retiredRowIds, targetCombos, compositionRows } from './lib/plugin-lifecycle.mjs'
+import { PLUGIN_IDS, canonicalPluginName, migrateBundleNames, migrateDependencyKeys, staleDepsStillReferenced } from './lib/plugin-packages.mjs'
+import { pruneStalePresets } from './lib/preset-sync.mjs'
+import { MECHANISM, detectPresetMechanism, mechanismNote } from './lib/preset-mechanism.mjs'
+import { installPresets, resolveInstalledSelection, applyPresetSelection, materializeBundleDir, checkPresetSelectionConsistency, resolveBundleDir } from './lib/preset-install.mjs'
+import { resolveDshScopeDir } from './lib/dsh-scope.mjs'
+import { composeFix, composeNew, migratePluginRowNames } from './lib/patch-compose.mjs'
+// 技能归类判据：**唯一实现在门禁里**（本文件不写第二份名单、不自己读 manifest —— 照抄即漂移）。
+// 内容摘要（`skillDigest`）同样复用外发安装器的实现：两边对"内容一致"必须是同一把尺子，
+// 否则升级器与安装器会互相判对方"不一致"而反复覆盖。
+import { classify, SKILL_FILE } from './check-skill-classification.mjs'
+import { skillDigest } from './skill-install.mjs'
+
+const HOME = homedir()
+// 克隆目录：**接受两个名字**（2026-09-30 实测发现 install-argent.mjs 用 ARGENT_DISH_HOME，
+// 本文件此前只用 ARGENT_HOME ⇒ 设了一个不影响另一个，测试与自定义安装路径都会误判为「~/.argent-dsh 脏」）。
+const ARGENT_HOME = process.env.ARGENT_DISH_HOME || process.env.ARGENT_HOME || join(HOME, '.argent-dsh')
+const DSH_HOME = process.env.DSH_HOME || join(HOME, '.dsh')
+const PROFILE = process.env.DSH_PROFILE || 'web'
+const PROFILE_DIR = join(DSH_HOME, 'profiles', PROFILE)
+const PROFILE_NM = join(PROFILE_DIR, 'node_modules')
+const PRESET_ROOT = join(DSH_HOME, '.agent-presets')
+// `migrate-deps` 取插件真实版本时的**两个候选落点**（与安装器的版本体检同口径：克隆 → 本文件所在的树）
+const REPO_FALLBACK = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const SKILLS_DIR = join(DSH_HOME, 'skills')
+const PATCH_PATH = join(PROFILE_DIR, 'cordis.patch.yml')
+
+const args = process.argv.slice(2)
+const MODE = args[0] || 'help'
+const FLAG_JSON = args.includes('--json')
+const FLAG_RESTART = args.includes('--restart')
+/**
+ * ⛔ **显式**才允许升级器替用户修 profile 组合（= `profile-doctor --fix`）。
+ * 2026-10-03 事故：`run` 的第 7.5 步**无条件**带 `--fix` ⇒ 每次升级都会在 **web profile**
+ * （`~/.dsh/AGENTS.md` 明令避免跑 pnpm 的那棵树）上跑一次 `dsh plugin install`（pnpm install），
+ * 并把 5 条 `file:` 依赖从已消失的临时目录**静默**重指到仓库。
+ * 现在：默认**只做只读体检**（门禁照旧拦自动重启），修组合/动包管理器必须显式开这个开关。
+ */
+const FLAG_PROFILE_FIX = args.includes('--with-profile-fix')
+/**
+ * `migrate-deps` 的开关（0.6.0 W8）。
+ * ⛔ **默认干跑**：不带 `--apply` 只打印计划；⛔ **默认不跑包管理器**：要跑必须 `--allow-package-manager`
+ * （AGENTS 红线：在 web profile 上裸跑 `pnpm install` 可能把 profile 弄坏 —— 2026-10-03 事故）。
+ */
+const FLAG_APPLY = args.includes('--apply')
+const FLAG_ALLOW_PM = args.includes('--allow-package-manager')
+const FLAG_DATA_DIR = (() => { const i = args.indexOf('--data-dir'); return i > -1 ? args[i + 1] || '' : '' })()
+/** `--repo <dir>`：`migrate-deps` 读插件**真实版本**的克隆根（夹具/多克隆机器用；缺省 `ARGENT_HOME`→本仓）。 */
+const FLAG_REPO = (() => { const i = args.indexOf('--repo'); return i > -1 ? args[i + 1] || '' : '' })()
+const RESTART_LABEL = 'com.whyshu.dsh-web'
+
+// 组合目标来自 scripts/plugin-composition.json（**唯一真源**，客户机预检也读它）：
+// patch 行 + bundle 层插件都要装进 profile；bundle 层那部分不进 patch 文件（见 patch-compose）。
+const TARGET_COMBO = Object.fromEntries(
+  Object.entries(targetCombos()).map(([type, c]) => [type, [...c.patch, ...c.bundles]]),
+)
+const RETIRED = retiredRowIds()
+const CRITICAL_SCRIPTS = ['invoice_runner.py', 'invoice_stageb.py', 'poll-invoice.sh', 'poll-fulfillment.sh', 'daily-report.mjs', 'init-ml.sh', 'orchestrator.py', 'fulfillment.js']
+
+const out = (obj) => { console.log(FLAG_JSON ? JSON.stringify(obj, null, 2) : formatHuman(obj)) }
+function formatHuman(o) {
+  if (o.error) return `✗ ${o.error}`
+  const ls = []
+  if (o.current) ls.push(`当前版本 ${o.current}`)
+  if (o.remote) ls.push(`远端版本 ${o.remote}`)
+  if (o.updateAvailable === true) ls.push('→ 有可用更新')
+  if (o.updateAvailable === false) ls.push('→ 已是最新')
+  if (o.comboType) ls.push(`实例类型: ${o.comboType}`)
+  if (o.targetCombo) ls.push(`目标组合: ${o.targetCombo.join(', ')}`)
+  ;(o.steps || []).forEach((s) => ls.push(
+    s.ok === false ? `  ✗ ${s.text}` : s.warn ? `  ⚠ ${s.text}` : `  ✓ ${s.text}`,
+  ))
+  if (o.profileFix) {
+    ls.push(o.profileFix.executed
+      ? `  🔧 profile 组合修复: 已执行（--with-profile-fix 显式开启；包管理器=${
+        o.profileFix.plan && o.profileFix.plan.runsPackageManager ? '已跑' : '未跑（无依赖需要重指）'}）`
+      : '  ⏭ profile 组合修复: 已跳过（默认只做只读体检；要执行须显式 --with-profile-fix）')
+  }
+  if (o.restartRequired) ls.push(`⚠ 需要重启 dsh web 生效${o.restartHint ? `（${o.restartHint}）` : ''}`)
+  return ls.join('\n')
+}
+
+function runCmd(cmd, argArr, opts = {}) {
+  return execFileSync(cmd, argArr, { encoding: 'utf8', timeout: opts.timeout || 120000 })
+}
+function runCmdSafe(cmd, argArr, opts = {}) {
+  // `env` 可注入：doctor 等子进程**按 `DSH_HOME` 解析 home**（它们没有 `--dsh-home` 开关）⇒
+  // 必须把本脚本解析出来的 home 显式传下去，否则子进程会退回真实 `~/.dsh`（数据外泄，实测同类事故）。
+  const options = { encoding: 'utf8', timeout: opts.timeout || 120000 }
+  if (opts.env) options.env = opts.env
+  try { return { ok: true, stdout: execFileSync(cmd, argArr, options) } }
+  catch (e) { return { ok: false, stdout: e.stdout || '', stderr: e.stderr || '', message: String(e.message).split('\n')[0] } }
+}
+
+function readVersion(dir) {
+  try { return readFileSync(join(dir, 'VERSION'), 'utf8').trim() }
+  catch { return null }
+}
+
+/** profile-doctor `--json` 报告（拿不到 / 解析失败 ⇒ null，调用方退回文本判据）。 */
+function parseDoctorJson(text) {
+  const s = String(text || '')
+  const i = s.indexOf('{')
+  if (i < 0) return null
+  try { return JSON.parse(s.slice(i)) } catch { return null }
+}
+
+/**
+ * `--with-profile-fix` 的**执行前声明**（⛔ 不得静默）：把 doctor 的修复计划翻成人话，
+ * 逐条说明它将改哪些 `file:` 依赖、摘/补哪些 patch 行、**是否跑包管理器**。
+ * 输出走 stderr（JSON 模式下 stdout 必须保持纯 JSON）。
+ */
+function describeProfileFix(plan, profile) {
+  const ls = ['[upgrade] ⚠ 即将执行 profile-doctor --fix（--with-profile-fix 已显式开启）—— 改动前置声明：']
+  if (!plan) {
+    ls.push('  · 预检未给出计划（doctor --json 不可用）—— 仍会执行 --fix，请自行核对 doctor 输出')
+    return ls
+  }
+  const deps = plan.depsToRepoint || []
+  ls.push(deps.length
+    ? `  · 将重指 ${deps.length} 条 file: 依赖：${deps.map((d) => `${d.name} → ${d.to}`).join('；')}`
+    : '  · 不改任何 file: 依赖（依赖路径均已规范）')
+  ls.push(`  · 将摘除退役/重复 patch 行：${plan.patchRowsToDrop || 0} 行；补齐必需行：${(plan.requiredRowsToAdd || []).join(', ') || '无'}`)
+  if (plan.runsPackageManager) {
+    ls.push(`  · ⛔ **将运行包管理器**：${plan.packageManagerCommand || `dsh plugin --profile ${profile} install`}`)
+    ls.push('      （= pnpm install；web profile 上是 `~/.dsh/AGENTS.md` 明令避免的动作，仅因你显式开了开关才做）')
+  } else {
+    ls.push('  · 不运行包管理器（没有任何依赖需要重指 ⇒ 不会触发 pnpm install）')
+  }
+  ls.push('  （反悔：Ctrl-C 中断即可；改前 doctor 会把 package.json / cordis.patch.yml 备份到 ~/.dsh/argent/backup/）')
+  return ls
+}
+
+// ── 实例类型判定 + 目标组合 ───────────────────────────────
+function detectCombo() {
+  let patchText = ''
+  try { patchText = readFileSync(PATCH_PATH, 'utf8') } catch { /* 无 patch */ }
+  const gwJson = join(DSH_HOME, 'argent', 'gateway.json')
+  const business =
+    /argent-(kanban|notify|gateway)/.test(patchText) ||
+    existsSync(gwJson)
+  return business ? 'business' : 'chat'
+}
+
+/**
+ * 写前备份（**唯一实现**；未改动/备份失败都不改客户文件 —— 与安装器 `backupPatchFile` 同纪律）。
+ *
+ * 由来（2026-10-13）：本文件此前只在 `ensureBundles`/`retirePlugins` 里**各自内联**了一份
+ * `copyFileSync(...)` 备份 ⇒ 新增写入点时极易漏备份（W9 的行名/依赖键/bundles 迁移全是新写入点）。
+ * @returns {{path: string} | null} null = 备份失败 ⇒ 调用方**必须**放弃本次改写
+ */
+function backupFile(target, _content, why) {
+  try {
+    const dir = join(DSH_HOME, 'argent', 'backup')
+    mkdirSync(dir, { recursive: true })
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+    const base = join(dir, `${basename(target)}.${stamp}`)
+    let dst = base
+    for (let i = 2; existsSync(dst); i += 1) dst = `${base}.${i}`   // 同秒冲突 ⇒ 加序号（⛔ 不覆盖上一份）
+    copyFileSync(target, dst)
+    const rollback = `cp ${JSON.stringify(dst)} ${JSON.stringify(target)}`
+    writeFileSync(`${dst}.why.txt`, `${why}\n回滚：${rollback}\n`, { mode: 0o600 })
+    console.log(`  ↳ 写前备份：${dst}\n  ↳ 回滚：${rollback}`)
+    return { path: dst, why, rollback }
+  } catch (e) {
+    console.error(`[upgrade] ⛔ 写前备份失败（${e.message}）⇒ 本次**不改** ${target}`)
+    return null
+  }
+}
+
+// ── 落位目录迁移（**第四处** profile 面向字符串：`node_modules/<名>`）──────
+/**
+ * 已知插件的裸名落位（`node_modules/argent-flow`）⇒ 包名落位（`node_modules/@whyshu/argent-flow`）。
+ *
+ * 为什么必须与**行名迁移**同时做（2026-10-13）：组合行的 `name:` 一旦变成包名，dsh 就按那个名字
+ * 在 profile 里解析 —— 落位还叫裸名 ⇒ **那一行解析不到**（⛔ 装完不报错，表现为插件静默不加载）。
+ * 反过来，只迁落位不迁行名也一样坏。所以两者是**同一个原子动作**。
+ * 判据刻意保守：
+ *   · 只碰**本仓已知插件**（`plugin-packages.mjs` 名单），未知/别人的包一律不动；
+ *   · 两处都在 ⇒ 删裸名那份（同一个插件 ⛔ 不许有两份）；
+ *   · 只有裸名 ⇒ `cp + rm`（跨设备/软链场景下比 rename 稳）。
+ */
+function migrateBareLandings() {
+  const moved = []
+  const pruned = []
+  for (const id of PLUGIN_IDS) {
+    const canonical = canonicalPluginName(id)
+    if (canonical === id) continue
+    const bare = join(PROFILE_NM, id)
+    if (!existsSync(bare)) continue
+    const dest = join(PROFILE_NM, ...canonical.split('/'))
+    if (existsSync(dest)) { rmSync(bare, { recursive: true, force: true }); pruned.push(id); continue }
+    mkdirSync(dirname(dest), { recursive: true })
+    cpSync(bare, dest, { recursive: true })
+    rmSync(bare, { recursive: true, force: true })
+    moved.push(id)
+  }
+  return { moved, pruned }
+}
+
+// ── patch 组合校正：只删组合外 argent 行/补缺失行，保留注释与官方行 ──
+/**
+ * 该插件在 profile 里**有没有落位**。
+ *
+ * ⚠️ W9（2026-10-13）：落位名是**包名**（`node_modules/@whyshu/argent-*`），⛔ 不是目录名。
+ * 只认裸名会把"已 scoped 落位"的插件判成**悬挂** ⇒ 升级器**把活着的行摘掉**（⛔ 且不报错）。
+ * ⇒ 两个名字都找（`plugin-packages.mjs#canonicalPluginName` 是搬迁真源）。
+ */
+function landedInProfile(ref) {
+  for (const n of [String(ref), canonicalPluginName(ref)]) {
+    if (!n) continue
+    if (existsSync(join(PROFILE_NM, ...n.split('/')))) return true
+  }
+  return false
+}
+
+/** 悬挂行：包没装在 profile 里，规范根里也没有源码 ⇒ 这行永远加载失败，摘掉。 */
+function danglingRow(plugin) {
+  if (landedInProfile(plugin)) return false
+  for (const root of [join(ARGENT_HOME, 'plugins'), join(DSH_HOME, 'argent', 'packs-cache')]) {
+    if (existsSync(join(root, plugin))) return false
+  }
+  return true
+}
+
+/**
+ * 把 bundle 层插件登记进 profile `package.json` 的 `dsh.profile.bundles`（幂等、改前备份）。
+ * 只登记**已装**的（node_modules 里有），不登记空气。
+ *
+ * ⚠️ W9（2026-10-13，用户 MBP 现场）：条目是**包名**（`@whyshu/argent-skin`）——
+ * 裸名（`argent-skin`）在 profile 里**解析不到** ⇒ bundle 加载不到 ⇒ **皮肤/UI 壳静默不加载**。
+ * 旧实现把 `BUNDLE_LAYER_PLUGINS`（**id**）直接 push 进这张表，就是那个裸名的**写入点**。
+ * 现在：① 存量裸名条目**先迁移**（`migrateBundleNames`，幂等、保序）；② 新登记一律写包名；
+ * ③ 落位判据两个名字都认（见 {@link landedInProfile}）。
+ */
+function ensureBundles() {
+  const pkgPath = join(PROFILE_DIR, 'package.json')
+  let pkg = null
+  try { pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) } catch { return { added: [], renamed: [], stale: [], backup: null } }
+  pkg.dsh = pkg.dsh || {}
+  pkg.dsh.profile = pkg.dsh.profile || {}
+  const mig = migrateBundleNames(pkg.dsh.profile.bundles)
+  const bundles = mig.bundles
+  const added = []
+  for (const row of bundleLayerRows()) {
+    if (bundles.includes(row.name) || !landedInProfile(row.id)) continue
+    bundles.push(row.name)
+    added.push(row.name)
+  }
+  let backup = null
+  const changed = added.length > 0 || mig.renamed.length > 0 || mig.stale.length > 0
+  if (changed) {
+    const bak = backupFile(pkgPath, '', 'W9 bundles 条目迁移（裸名 → npm 名）')
+    if (!bak) return { added: [], renamed: [], stale: [], backup: null, refused: true }
+    backup = bak.path
+    pkg.dsh.profile.bundles = bundles
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8')
+  }
+  return { added, renamed: mig.renamed, stale: mig.stale, backup }
+}
+
+/**
+ * **依赖键**迁移：存量 profile 的裸键（`argent-core`）⇒ npm 名（`@whyshu/argent-core`）。
+ *
+ * ⚠️ W9 漏迁（2026-10-13）：安装器的 `normalizeProfileDeps()` 在**新装路径**上做这件事，
+ * 但升级路径在 `install-argent.mjs` 里 `process.exit(0)`（第 2.1 步"完整升级"之后即退出）
+ * ⇒ **这一段从不执行**。于是"重跑安装命令"在存量机器上并不迁移依赖键。
+ * 判据/摘键时机与安装器**同一份实现**（`plugin-packages.mjs` + `staleDepsStillReferenced`）：
+ * 先看组合行还有没有裸名，有则**宁可留一个无害别名，也不制造断链**。
+ */
+function normalizeDepKeys() {
+  const pkgPath = join(PROFILE_DIR, 'package.json')
+  let pkg = null
+  try { pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) } catch { return { renamed: [], dropped: [], refused: false } }
+  if (!pkg || typeof pkg.dependencies !== 'object' || pkg.dependencies === null) return { renamed: [], dropped: [], refused: false }
+  let patchText = ''
+  try { patchText = readFileSync(PATCH_PATH, 'utf8') } catch { /* 无 patch */ }
+  const mig = migrateDependencyKeys(pkg.dependencies)
+  const stillUsed = new Set(staleDepsStillReferenced(patchText, mig.stale))
+  const dropped = mig.stale.filter((k) => !stillUsed.has(k))
+  if (!mig.renamed.length && !dropped.length) return { renamed: [], dropped: [], refused: false }
+  const bak = backupFile(pkgPath, '', 'W9 依赖键迁移（裸名 → npm 名）')
+  if (!bak) return { renamed: [], dropped: [], refused: true }
+  for (const k of dropped) delete mig.deps[k]
+  writeFileSync(pkgPath, `${JSON.stringify({ ...pkg, dependencies: mig.deps }, null, 2)}\n`)
+  return { renamed: mig.renamed, dropped, stillUsed: [...stillUsed], refused: false }
+}
+
+function fixPatch(type) {
+  // ⚠️ W9（2026-10-12）：patch 层的 `name:` 是 **npm 包名**（`@whyshu/argent-*`），
+  // 而组合 id 仍是裸 id ⇒ 这里给 `composeFix` 的是 `{id, name}` 行
+  // （真源 `compositionRows()`；口径见 `scripts/lib/plugin-packages.mjs`）。
+  const rows = compositionRows(type)
+  const target = rows.map((r) => r.id)
+  let text = null
+  try { text = readFileSync(PATCH_PATH, 'utf8') } catch { text = null }
+  if (text === null) {
+    mkdirSync(PROFILE_DIR, { recursive: true })
+    writeFileSync(PATCH_PATH, composeNew({ target: rows, type, bundleLayer: BUNDLE_LAYER_PLUGINS }), 'utf8')
+    return { changed: true, dropped: [], migrated: [], added: target.filter((p) => !BUNDLE_LAYER_PLUGINS.includes(p)) }
+  }
+  // 编辑逻辑在 lib/patch-compose.mjs（纯函数 + 离线门禁）：这里只做读写与判据注入
+  const res = composeFix({
+    text,
+    target: rows,
+    bundleLayer: BUNDLE_LAYER_PLUGINS,
+    retired: RETIRED,
+    dangling: danglingRow,
+  })
+  // ── W9 漏迁（2026-10-13）：**所有已知插件的行名**都归一为包名 ────────────────────────────
+  // `composeFix` 只给**目标组合内**的行改 name（非目标行原样保留）⇒ 一个"不在本实例目标组合、
+  // 但确实装着"的插件（如 chat 实例里的 `argent-flow`）会留着**裸名** `name: 'argent-flow'`，
+  // 而它的落位是/将是 scoped ⇒ 那一行解析不到（⛔ 装完不报错）。判据与安装器 `patchSelfcheck`
+  // 同一份实现（`patch-compose.mjs#migratePluginRowNames`），⛔ 本文件不写第二套。
+  const renamed = [...(res.renamed || [])]
+  const mig = migratePluginRowNames({
+    text: res.changed ? res.text : text,
+    nameOf: (id) => (PLUGIN_IDS.includes(id) ? pluginRowName(id) : undefined),
+  })
+  for (const r of mig.renamed) if (!renamed.some((x) => x.id === r.id)) renamed.push(r)
+  const changed = res.changed || mig.changed
+  const nextText = mig.changed ? mig.text : (res.changed ? res.text : text)
+  if (changed) {
+    // ⛔ 没有回滚点就不改客户文件（与安装器 `backupPatchFile` 同纪律）
+    const bak = backupFile(PATCH_PATH, text, `组合编辑/行名迁移（${type}）`
+      + (renamed.length ? `：${renamed.map((r) => `${r.id} ${r.from} → ${r.to}`).join('；')}` : ''))
+    if (!bak) return { changed: false, dropped: [], migrated: [], added: [], renamed: [], refused: true }
+    writeFileSync(PATCH_PATH, nextText, 'utf8')
+  }
+  return { changed, dropped: res.dropped, migrated: res.migrated, added: res.added, renamed }
+}
+
+// ── 插件同步（目标组合从基座镜像到运行库）────────────────
+/**
+ * 把目标组合的插件**镜像**进 profile 的 `node_modules/`。
+ *
+ * ⚠️ W9 漏迁（2026-10-13，**第四处**：`node_modules/<名>` 落位路径）：落位名必须是**包名**
+ * （`node_modules/@whyshu/argent-flow`）—— 组合行的 `name:` 已是包名（见 `fixPatch` 的行名迁移），
+ * 而"落位 = 目录名"（裸 id）⇒ 那一行**解析不到**（⛔ 装完不报错，表现为插件静默不加载）。
+ * 同一个插件的两个名字**不许同时在**盘上 ⇒ 写 scoped 落位时顺手清掉旧裸名目录。
+ * 未知插件（不在 `plugin-packages.mjs` 名单里）**逐字原样**（⛔ 不猜、不越权）。
+ */
+function syncPlugins(type) {
+  const target = TARGET_COMBO[type]
+  const synced = []
+  const moved = []
+  for (const p of target) {
+    const src = join(ARGENT_HOME, 'plugins', p)
+    if (!existsSync(src)) continue
+    const canonical = canonicalPluginName(p)
+    const dest = join(PROFILE_NM, ...canonical.split('/'))
+    mkdirSync(dirname(dest), { recursive: true })
+    rmSync(dest, { recursive: true, force: true })
+    cpSync(src, dest, { recursive: true })
+    // 旧裸名落位（`node_modules/argent-flow`）在 scoped 落位写好后一律清掉（⛔ 不留两份）
+    const bare = join(PROFILE_NM, p)
+    if (canonical !== p && existsSync(bare)) {
+      rmSync(bare, { recursive: true, force: true })
+      moved.push(`${p} → ${canonical}`)
+    }
+    synced.push(p)
+  }
+  return { synced, moved }
+}
+
+// ── 插件退役收敛（把 profile 真正收敛到目标组合）────────────
+// 实现见 scripts/lib/profile-retire.mjs（纯函数、可离线测试）；这里只注入路径。
+function retirePlugins(type) {
+  return retirePluginsImpl({
+    profileNm: PROFILE_NM,
+    profileDir: PROFILE_DIR,
+    target: TARGET_COMBO[type],
+    // 规范插件根：仓库 plugins/ + 能力包缓存（判据是「源码是否还在」，不是「在不在组合里」）
+    canonicalRoots: [join(ARGENT_HOME, 'plugins'), join(DSH_HOME, 'argent', 'packs-cache')],
+    backupDir: join(DSH_HOME, 'argent', 'backup'),
+    log: (m) => console.log(m),
+  })
+}
+
+// ── 技能同步（**只发外发集**；内部技能不外发、宿主多出只报告不删）────────────
+/**
+ * 归类（**复用门禁的唯一实现**；本文件不写第二份名单）。
+ * 兜底：`classify()` 抛错 ⇒ 返回 `ok:false` + 空外发集（**不同步任何东西**，绝不猜名单）。
+ * @param {{root?:string}} [opts] root = 要同步的技能所在的树（默认 `ARGENT_HOME`）
+ */
+export function classifySkills({ root = ARGENT_HOME } = {}) {
+  try {
+    return classify({ root })
+  } catch (e) {
+    return {
+      ok: false, root, external: [], internal: [], unclassified: [], sources: [], warnings: [],
+      errors: [{ rule: 'G0', message: `classify() 抛错：${e && e.message ? e.message : String(e)}` }],
+      counts: { external: 0, internal: 0, skillDirs: 0, unclassified: 0 },
+    }
+  }
+}
+
+/** 宿主技能根下的**目录**名（排序；非目录/点文件不算技能）。 */
+export function hostSkillDirs(dstRoot) {
+  try {
+    return readdirSync(dstRoot, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+      .map((e) => e.name).sort()
+  } catch { return [] }
+}
+
+/**
+ * **执行**技能同步（纯路径参数，便于离线夹具回归）。
+ *
+ * 硬约束（2026-10-04 客户机实测缺口，D5）：
+ *   · 只写 `external` 里的技能 —— 外发集 = `verticals/<id>/manifest.json#skills` 的并集（由 `classify()` 给）；
+ *   · **内部技能（`internal`）一个都不写**；`srcRoot` 里的其它目录（未归类/内部）也不写；
+ *   · 宿主技能根里**已有的**目录（内部技能 / 旧技能 / 用户自建）**一个都不删** ——
+ *     `hostInternal`（按设计不同步的）与 `hostExtra`（不在外发集里的旧/未知技能）只**报告**；
+ *   · **幂等**：目标内容 sha 与源一致 ⇒ 跳过（不 rm/cp ⇒ mtime 不变），重复跑不反复写盘。
+ *
+ * @returns {{synced:string[], written:string[], skipped:string[], missing:string[],
+ *            hostInternal:string[], hostExtra:string[]}}
+ */
+export function syncSkills({ srcRoot, dstRoot, external = [], internal = [] } = {}) {
+  const written = []
+  const skipped = []
+  const missing = []
+  const ext = [...external]
+  if (ext.length) mkdirSync(dstRoot, { recursive: true })
+  for (const name of ext) {
+    const src = join(srcRoot, name)
+    // 归类门禁 G4 本该拦住"声明了却不存在"；这里再挡一次（**绝不**为一个不存在的技能去删宿主的同名目录）
+    if (!existsSync(join(src, SKILL_FILE))) { missing.push(name); continue }
+    const dst = join(dstRoot, name)
+    if (existsSync(join(dst, SKILL_FILE))) {
+      try {
+        if (skillDigest(dst).digest === skillDigest(src).digest) { skipped.push(name); continue }
+      } catch { /* 读不动/坏目录 ⇒ 按需覆盖（下面走正常写入路径） */ }
+    }
+    rmSync(dst, { recursive: true, force: true })
+    cpSync(src, dst, { recursive: true })
+    written.push(name)
+  }
+  const host = hostSkillDirs(dstRoot)
+  const extSet = new Set(ext)
+  const intSet = new Set(internal)
+  return {
+    synced: [...ext],
+    written,
+    skipped,
+    missing,
+    // 「宿主多出」两分：内部技能（按设计不外发，但客户机旧装机残留会留着）与**其它**（旧技能/用户自建）
+    hostInternal: host.filter((n) => intSet.has(n)),
+    hostExtra: host.filter((n) => !extSet.has(n) && !intSet.has(n)),
+  }
+}
+
+// ── check：远端版本检测 ────────────────────────────────────
+function doCheck() {
+  const current = readVersion(ARGENT_HOME)
+  const fetch = runCmdSafe('git', ['-C', ARGENT_HOME, 'fetch', 'origin'], { timeout: 45000 })
+  let remote = null
+  if (fetch.ok) {
+    const show = runCmdSafe('git', ['-C', ARGENT_HOME, 'show', 'origin/main:VERSION'], { timeout: 15000 })
+    if (show.ok) remote = String(show.stdout).trim() || null
+  }
+  out({
+    ok: true,
+    current,
+    remote,
+    updateAvailable: remote && current && remote !== current ? true : (remote ? false : null),
+    fetchError: fetch.ok ? null : fetch.message,
+  })
+}
+
+// ── migrate-deps：存量迁移（遗留 `file:` 依赖 ⇒ npm 名；**默认干跑**）─────────
+/**
+ * 唯一实现 = `scripts/lib/deps-migrate.mjs`（本函数只做取数/排版/开关）。
+ *
+ * 四条纪律（都有夹具）：① 默认干跑（不带 `--apply` 零写入）② 写前备份（时间戳 + sha256 + 回滚命令）
+ * ③ 读回验收 + 审计 JSONL ④ 幂等（已迁过 ⇒ 零写入，连 mtime 都不动）。
+ * ⛔ **不裸跑包管理器**：`--allow-package-manager` 才跑，且**跑之前**先把计划打印出来。
+ */
+async function doMigrateDeps() {
+  const pkgPath = join(PROFILE_DIR, 'package.json')
+  let pkg = null
+  try { pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) }
+  catch (e) {
+    out({ ok: false, error: `读不到 profile package.json（${pkgPath}）：${String((e && e.message) || e).split('\n')[0]}`, pkgPath })
+    process.exitCode = 2
+    return
+  }
+  const plan = planDepsMigration({
+    pkg,
+    knownId: knownPluginId,
+    // 真实版本的**候选落点**（保序）：`--repo`（夹具/多克隆机器）→ `ARGENT_HOME`（`~/.argent-dsh`，
+    //   **存量客户机真正在用的克隆**）→ 本文件所在的树。⛔ 三个都读不到 ⇒ 该条 `blocked`（不编版本号）。
+    versionOf: (id) => [FLAG_REPO, ARGENT_HOME, REPO_FALLBACK]
+      .filter(Boolean)
+      .map((root) => realVersionOf(root, id))
+      .find((v) => v) || '',
+  })
+  const rendered = renderPlan(plan, { profilePkgPath: pkgPath, apply: FLAG_APPLY, runPackageManager: FLAG_ALLOW_PM })
+  const result = {
+    ok: plan.ok, mode: FLAG_APPLY ? 'apply' : 'dry-run', pkgPath,
+    changed: plan.changed, blocked: plan.blocked, packageManager: FLAG_ALLOW_PM,
+    plan: plan.entries, lines: rendered.lines, rollback: rendered.rollback,
+  }
+  if (!FLAG_APPLY) {
+    if (!FLAG_JSON) console.log(rendered.lines.join('\n'))
+    out({ ...result, applied: false, note: '默认干跑：加 --apply 才写；⛔ 本命令不会自己跑包管理器' })
+    process.exitCode = plan.ok ? 0 : 2
+    return
+  }
+  if (!plan.ok) {
+    // ⛔ 拒绝半截迁移：有受阻条目 ⇒ 一条都不写（要么全可迁、要么先把证据补齐）
+    if (!FLAG_JSON) console.log(rendered.lines.join('\n'))
+    out({ ...result, applied: false, error: `有 ${plan.blocked.length} 条受阻 ⇒ ⛔ 拒绝写入（避免半截迁移）` })
+    process.exitCode = 1
+    return
+  }
+  // ⚠️ 内核数据目录判据**懒加载**（本文件被 `run` 路径 import 时不该依赖 core/ 存在 ——
+  //   夹具/老克隆只拷 `scripts/`；静态 import 会让 `run` 直接 ERR_MODULE_NOT_FOUND 假红）。
+  let dataDir = ''
+  try {
+    const kernel = await import('./lib/argent-datadir.mjs')
+    dataDir = kernel.resolveDataDir({ env: { ...process.env, DSH_HOME }, home: HOME }).dir
+  } catch (e) {
+    if (!FLAG_DATA_DIR) {
+      out({ ok: false, error: `取不到内核数据目录判据（core/lib/argent-datadir.mjs 不在本树）⇒ ⛔ 拒绝猜目录；显式给 --data-dir <目录>` })
+      process.exitCode = 2
+      return
+    }
+  }
+  const backupDir = join(FLAG_DATA_DIR || dataDir, 'backup')
+  const auditPath = join(FLAG_DATA_DIR || dataDir, 'deps-migrate-audit.jsonl')
+  const applied = applyDepsMigration({
+    pkgPath, pkg, plan, auditPath, backupDir, reason: 'W8 file:→npm',
+    // 读回验收用**同一套判据**重算（否则"缺版本"这类条目会两套结论 ⇒ 假红）
+    replan: (doc) => planDepsMigration({
+      pkg: doc, knownId: knownPluginId,
+      versionOf: (id) => [FLAG_REPO, ARGENT_HOME, REPO_FALLBACK].filter(Boolean).map((root) => realVersionOf(root, id)).find((v) => v) || '',
+    }),
+  })
+  if (!FLAG_JSON) {
+    console.log(rendered.lines.join('\n'))
+    if (applied.wrote) {
+      console.log(`✅ 已迁移 ${plan.changed} 条依赖`)
+      console.log(`   备份：${applied.backup}（sha256 ${applied.backupSha}）`)
+      console.log(`   回滚：${applied.rollback}`)
+      console.log(`   审计：${applied.audit || '（未写）'}`)
+      console.log(`   验收：${applied.verify}`)
+    }
+  }
+  out({ ...result, applied: applied.wrote, apply: applied })
+  process.exitCode = applied.ok ? 0 : 1
+}
+
+// ── run：完整升级 ─────────────────────────────────────────
+async function doRun() {
+  const steps = []
+  // 缺陷 1（2026-10-12）：本次该落的角色集合 + 是否需要收尾重施。
+  // 为什么升级也要"收尾重施"：第 2 步收窄之后，第 6.5/7.5 步（退役插件收敛、profile-doctor --fix）
+  // 都可能重解析 profile 依赖 ⇒ 把副本换成指向货架的链（14 个 patch 全回来）。
+  let UPGRADE_PRESET_LANDING = null
+  let PENDING_PRESET_REAPPLY = false
+  // 内部角色授权（`agents.json#internalRoles`）—— 第 2 步与第 7.6 步的**不变式**都用它：
+  // 未授权时落盘集合若含 `visibility: internal` 的角色 ⇒ `applyPresetSelection` 判红并拒绝写出。
+  let PRESET_ALLOW_INTERNAL = false
+  // **可信已装集**（唯一来源：可信痕迹 → agents.json#roles 并集 → 空集）。第 2 步算一次，
+  // 第 7.6 步的回落也用它 —— ⛔ 7.6 不再直接读痕迹（不可信痕迹会把收尾重新放大回去）。
+  let PRESET_INSTALLED = { ids: [], source: 'none', rejected: '' }
+  // 0) 工作区预检（未提交改动会阻塞 pull——硬错误，请用户先清理，杜绝半升级）
+  const st = runCmdSafe('git', ['-C', ARGENT_HOME, 'status', '--porcelain'])
+  const dirty = (st.stdout || '').trim().split('\n').filter(Boolean)
+  if (dirty.length) {
+    out({ ok: false, error: `~/.argent-dsh 有未提交改动（${dirty.slice(0, 5).join('; ')}）——请先提交或还原（KB-032），再运行更新` })
+    process.exit(2)
+  }
+  // 1) git pull
+  const pull = runCmdSafe('git', ['-C', ARGENT_HOME, 'pull', '--ff-only'], { timeout: 120000 })
+  const pulled = pull.ok || /up to date|Already up/i.test(String(pull.stdout || ''))
+  steps.push({ ok: pull.ok, text: `git pull: ${pull.ok ? (String(pull.stdout || '').trim().split('\n')[0] || '已是最新') : pull.message}` })
+  // 2) preset 全量同步（**按 dsh 机制分派**：0.1.7 起行式，不再扫目录）
+  // P1-3b（2026-10-12）：scope 定位改用真源 `resolveDshScopeDir()`（**npx 感知** + 探不到 ⇒ null）。
+  // 老实现走遗留 `resolveDshScope()`，它在"纯 npx 机器"上**静默回一个不存在的路径** ⇒
+  // `detectPresetMechanism()` 得 `unknown` ⇒ 本步静默退到"目录式"（往 `.agent-presets/` 拷，
+  // 在 npx/0.2 宿主上根本不生效）。换真源后：npx 机器上机制**判得对**（= 行式）。
+  // ⚠️ 遗留缺口（⛔ 本批不改，已登记在 docs/Argent-0.5.0-适配实施计划.md）：机制仍为 `unknown`
+  //    （真的解析不到 scope）时，下面 `else if (existsSync(srcPresets))` 仍会走目录式 ——
+  //    那是**既存的降级路径**，要不要改成响亮失败是独立决策。
+  const _scopeHit = resolveDshScopeDir()
+  // 0.6.0 F1 修复批（2026-10-14）：探不到 scope ⇒ 本步是**可选增强**（探不到也能继续，只是机制判成
+  // unknown ⇒ 走下面那条目录式）⇒ **降级但响亮**：点名根因 + 给出下一步命令（⛔ 不静默）。
+  if (!_scopeHit) {
+    steps.push({ ok: true, text: '⚠ 探不到宿主 scope（**可能是 npx 形态**：`~/.npm/_npx/<hash>/node_modules/@deepseek-ai`）' +
+      '⇒ preset 机制判成 unknown、本步退到目录式；要判准请显式给 `--scope-dir <…/@deepseek-ai>` / `DSH_SCOPE=<…>` / `DSH_BIN=<该 scope 自带的 dsh>`' })
+  }
+  const presetMechanism = detectPresetMechanism(_scopeHit ? _scopeHit.dir : '')
+  let presets = 0
+  const srcPresets = join(ARGENT_HOME, 'presets')
+  if (presetMechanism === MECHANISM.ROWS) {
+    // A 批（2026-10-10）：**升级必须重新施加"角色子集"**，否则一次升级就把 `--agent` 落盘时的
+    // 收窄（例：装 HR 只落 2 个角色）**全部还原**成 14 个 —— 用户口径"只装这个智能体相关的东西"
+    // 会在第一次升级后静默失效。口径与安装器**同一份实现**（`presetSelectionForAgents`）：
+    //   · `<dshHome>/argent/agents.json` 记着本机装了哪些智能体、是否 `--internal-roles`；
+    //   · 有智能体记录 ⇒ **agentScoped**（只落它们的角色 + 恒装 + 已装）；
+    //   · 没有记录 ⇒ 默认档（客户可见集 ∪ 已装集；内部角色不落）。
+    // ⛔ 两个记录都没有（老机器 / 首次升级）⇒ `onlyPresets = null` ⇒ **与改动前逐字节一致**。
+    // ⚠️ 缺陷 1（2026-10-12 真机实测）：「已装集」的判据 = **选择痕迹**
+    //    `presets.selection.json#kept`，⛔ 不是 `package.json#dsh.bundle.patch`（后者在 profile 副本
+    //    被 pnpm 换回货架链之后读到的就是货架自带的 14 条 ⇒ 收窄被静默放大回去）。
+    // ⚠️ 追修批（2026-10-12 下半场）：**唯一来源**收口到 `resolveInstalledSelection()`
+    //    —— 痕迹不可信（含内部角色而本机未授权内部角色，现场 `kept:14`/`excluded:[]` 就是这个形态）
+    //    时按"痕迹缺失"处理，退回 `agents.json#roles` 并集；两级都没有 ⇒ 空集（首次安装语义）。
+    //    并：**升级档 = 默认安装档**（客户可见集 ∪ 已装集 ∪ 本智能体角色）。
+    //    ⛔ 不再用 `agentScoped: agents.length>0` —— 那会把"客户可见集"整个排除掉，
+    //    让一台现场已是 14（或 7）的机器只落 `general+hr` 两个角色（实测得 2，见回归①）。
+    let onlyPresets = null
+    let selectionWhy = ''
+    try {
+      const agLib = await import(pathToFileURL(join(ARGENT_HOME, 'scripts', 'argent-agents.mjs')).href)
+      const shelf = JSON.parse(readFileSync(join(ARGENT_HOME, 'plugins', 'argent-presets', 'presets.json'), 'utf8'))
+      // ⚠️ W9：profile 里 bundle 的落点是**包名**（`@whyshu/argent-presets`），存量机器上仍是旧裸名
+      //    目录 ⇒ 一律走真源 `resolveBundleDir()`（**两个名字都找**，⛔ 不写死其中一个）。
+      const bundleDir = resolveBundleDir(PROFILE_DIR)
+      const ledgerPath = join(DSH_HOME, 'argent', 'agents.json')
+      const ledger = existsSync(ledgerPath) ? JSON.parse(readFileSync(ledgerPath, 'utf8')) : null
+      const agents = (ledger && Array.isArray(ledger.agents)) ? ledger.agents : []
+      PRESET_ALLOW_INTERNAL = !!(ledger && ledger.internalRoles)
+      const installed = resolveInstalledSelection({ bundleDir, ledger, allowInternal: PRESET_ALLOW_INTERNAL })
+      PRESET_INSTALLED = installed
+      if (installed.rejected) {
+        // **响亮报告**：不可信痕迹一律不采信，也⛔不静默改它（下一句就把它按正确集合重写）
+        steps.push({ ok: true, text: `⚠ 选择痕迹不可信 ⇒ 已装集退回 agents.json 角色：${installed.rejected}` })
+      }
+      onlyPresets = agLib.presetSelectionForAgents({
+        presets: shelf, agents, agentScoped: false, internal: PRESET_ALLOW_INTERNAL, previous: installed.ids,
+      })
+      selectionWhy = `升级重新施加角色子集（智能体：${agents.length ? agents.map((a) => a.id).join('、') : '无记录'}`
+        + `；已装集来源：${installed.source === 'trace' ? '选择痕迹' : installed.source === 'agents' ? 'agents.json 角色并集' : '无（首次安装语义）'}`
+        + `）${PRESET_ALLOW_INTERNAL ? ' --internal-roles' : ''}`
+    } catch (e) {
+      steps.push({ ok: true, text: `角色子集策略未施加（${String(e.message || e).split('\n')[0]}）⇒ 按全量同步（旧行为）` })
+    }
+    {
+      // ⚠️ W9：bundle 落点 = **包名**（`@whyshu/argent-presets`）；存量机器上是旧裸名目录 ⇒
+      //    走真源 `resolveBundleDir()`（两个名字都找，⛔ 不写死其中一个）。
+      const bundleDir = resolveBundleDir(PROFILE_DIR)
+      // 没算出集合时**回落选择痕迹**（自愈：pnpm 抹掉痕迹前的那次收窄结果）
+      const want = (Array.isArray(onlyPresets) && onlyPresets.length) ? onlyPresets : PRESET_INSTALLED.ids
+      if (want.length) {
+        UPGRADE_PRESET_LANDING = { kept: [...want], why: selectionWhy || '升级按选择痕迹' }
+        PENDING_PRESET_REAPPLY = true
+      }
+    }
+    // 行式：装 argent-presets bundle + 登记 bundles/注册表默认值（roles 受 onlyPresets 收窄）
+    const res = installPresets({
+      mechanism: presetMechanism,
+      repo: ARGENT_HOME,
+      profileDir: PROFILE_DIR,
+      presetId: 'argent-general',
+      onlyPresets,
+      selectionWhy,
+      allowInternal: PRESET_ALLOW_INTERNAL,
+      log: () => {},
+    })
+    if (res.ok && res.selection && res.selection.kept.length) {
+      UPGRADE_PRESET_LANDING = { kept: [...res.selection.kept], why: selectionWhy || '升级落盘集合' }
+      PENDING_PRESET_REAPPLY = true
+    }
+    presets = res.ok ? Object.keys(JSON.parse(readFileSync(join(resolveBundleDir(PROFILE_DIR), 'presets.json'), 'utf8'))).length : 0
+    steps.push({
+      ok: res.ok,
+      text: res.ok
+        ? `preset 同步（行式）: ${presets} 个角色 → profile bundles（${mechanismNote(presetMechanism)}）`
+          + (onlyPresets ? `｜策略：${selectionWhy}` : '')
+        : `preset 同步失败：${res.reason}`,
+    })
+  } else if (existsSync(srcPresets)) {
+    mkdirSync(PRESET_ROOT, { recursive: true })
+    for (const name of readdirSync(srcPresets, { withFileTypes: true })) {
+      if (!name.isDirectory()) continue
+      if (!existsSync(join(srcPresets, name.name, 'format-version.txt'))) continue
+      const src = join(srcPresets, name.name)
+      const dst = join(PRESET_ROOT, name.name)
+      rmSync(dst, { recursive: true, force: true })
+      cpSync(src, dst, { recursive: true })
+      presets++
+    }
+    steps.push({ ok: presets > 0, text: `preset 同步（目录式）: ${presets} 个角色 → .agent-presets/` })
+  }
+  // 仓库当前提供的角色（判据：带安装器标记 format-version.txt）
+  const shippedPresets = new Set(
+    existsSync(srcPresets) ? readdirSync(srcPresets).filter((d) => existsSync(join(srcPresets, d, 'format-version.txt'))) : [],
+  )
+  // 2.5) 清理**旧版残留**角色（会直接把 0.1.5 挡在启动门外，见 lib/preset-sync.mjs 注释）
+  const prune = pruneStalePresets({
+    presetRoot: PRESET_ROOT,
+    shipped: shippedPresets,
+    backupDir: join(DSH_HOME, 'argent', 'backup'),
+    log: (m) => console.log(m),
+  })
+  if (prune.stale.length) {
+    steps.push({ ok: true, text: `旧版残留角色已清理: ${prune.stale.join(', ')}（备份 ${prune.backup || '失败'}）` })
+  } else if (prune.skipped) {
+    steps.push({ ok: false, text: '跳过残留角色清理：仓库未提供任何 preset（源目录缺失？）—— 已刻意不动运行时角色' })
+  }
+  // 3) skills 同步（**只发外发集**：内部角色技能不外发；宿主多出只报告不删）
+  // 判据来自 `classify()`（唯一实现），本文件**不写第二份名单、不自己读 manifest**。
+  const srcSkills = join(ARGENT_HOME, 'skills')
+  const skillCls = classifySkills({ root: ARGENT_HOME })
+  const skillRes = syncSkills({
+    srcRoot: srcSkills,
+    dstRoot: SKILLS_DIR,
+    external: skillCls.external,
+    internal: skillCls.internal,
+  })
+  if (!skillCls.ok) {
+    // 归类门禁红 ≠ 外发集不可用：外发集仍严格等于业务线声明 ⇒ 照发（且**未归类目录一个都不发、不删**）
+    steps.push({
+      ok: false,
+      text: `技能归类门禁不通过（${skillCls.errors.length} 条）—— 外发集仍按业务线声明同步、未归类目录不同步也不删；`
+        + '请先跑 `node scripts/check-skill-classification.mjs`',
+    })
+  }
+  if (!skillCls.external.length) {
+    steps.push({
+      ok: false,
+      text: `技能同步: 跳过 —— 外发集为空（${join(ARGENT_HOME, 'verticals')} 下读不到 manifest#skills？）`
+        + '**不猜名单、不同步**（跑 scripts/sync-scripts.sh 补齐业务线真源后重试）',
+    })
+  } else {
+    steps.push({
+      ok: skillRes.missing.length === 0,
+      text: `技能同步: ${skillRes.synced.length} 项（外发集；内部 ${skillCls.internal.length} 项按设计不同步）`
+        + (skillRes.written.length ? `，写入 ${skillRes.written.length} 项：${skillRes.written.join(', ')}` : '，内容已一致（幂等跳过，未重复写）')
+        + (skillRes.missing.length ? `；⚠ 源缺 ${SKILL_FILE}：${skillRes.missing.join(', ')}` : ''),
+    })
+  }
+  const hostExtra = [...skillRes.hostInternal, ...skillRes.hostExtra]
+  if (hostExtra.length) {
+    const shown = hostExtra.slice(0, 8)
+    steps.push({
+      ok: true, warn: true,
+      text: `宿主技能根多出 ${hostExtra.length} 项（不在外发集；**只报告不删**）：${shown.join(', ')}`
+        + (hostExtra.length > shown.length ? ` …（另 ${hostExtra.length - shown.length} 项见 --json）` : '')
+        + (skillRes.hostInternal.length ? `｜其中按设计不外发的内部技能 ${skillRes.hostInternal.length} 项` : ''),
+    })
+  }
+  // 4) scripts 自检
+  const missingScripts = CRITICAL_SCRIPTS.filter((f) => !existsSync(join(ARGENT_HOME, 'scripts', f)))
+  steps.push({ ok: missingScripts.length === 0, text: missingScripts.length ? `scripts 缺失: ${missingScripts.join(', ')}` : 'scripts 就绪（关键脚本均在）' })
+  // 5) 落位目录迁移（W9 漏迁的第四处，**先于**行名迁移：行名 scoped 而落位还是裸名 ⇒ 那一行解析不到）
+  const landings = migrateBareLandings()
+  if (landings.moved.length || landings.pruned.length) {
+    steps.push({
+      ok: true,
+      text: `落位目录迁移到 npm 名: ${landings.moved.join(', ') || '无'}`
+        + `${landings.pruned.length ? `；清掉重复的裸名落位 ${landings.pruned.join(', ')}` : ''}`,
+    })
+  }
+  // 5.5) patch 组合校正
+  const type = detectCombo()
+  const patchRes = fixPatch(type)
+  if (patchRes.migrated && patchRes.migrated.length) {
+    steps.push({ ok: true, text: `bundle 层迁移: 摘 patch 行 ${patchRes.migrated.join(', ')}（改由 dsh.profile.bundles 加载）` })
+  }
+  if (patchRes.renamed && patchRes.renamed.length) {
+    steps.push({ ok: true, text: `组合行名迁移到 npm 名: ${patchRes.renamed.map((r) => `${r.id} ${r.from} → ${r.to}`).join('；')}` })
+  }
+  steps.push({ ok: true, text: patchRes.changed ? `组合校正: ${type}（移除 ${patchRes.dropped.join(', ') || '无'}，补齐 ${patchRes.added.join(', ') || '无'}）` : `组合已是最新（${type}: ${TARGET_COMBO[type].join('/')}）` })
+  // 6) 插件同步（**落位名 = 包名**；旧裸名目录顺手清掉）
+  const syncedRes = syncPlugins(type)
+  const synced = syncedRes.synced
+  steps.push({ ok: synced.length > 0, text: `插件同步: ${synced.join(', ') || '无'} → profile「${PROFILE}」` })
+  if (syncedRes.moved.length) {
+    steps.push({ ok: true, text: `落位路径迁移到 npm 名: ${syncedRes.moved.join('；')}（⛔ 不留两份）` })
+  }
+  // 6.5) 退役插件收敛（副本 + 依赖行一起清理，否则 doctor 报 dep-missing 卡住重启门禁）
+  const bundled = ensureBundles()
+  if (bundled.added.length) {
+    steps.push({ ok: true, text: `bundle 层登记: ${bundled.added.join(', ')} → dsh.profile.bundles（备份 ${bundled.backup ? '已存' : '失败'}）` })
+  }
+  // W9 漏迁的第三处：存量 `bundles` 里的**裸名**条目（`argent-skin`）在 profile 里解析不到
+  // ⇒ bundle 加载不到、**皮肤/UI 壳静默不加载**（装完零报错）。这里当场迁到包名并响亮报告。
+  if (bundled.refused) {
+    steps.push({ ok: false, text: 'bundles 条目迁移被跳过（写前备份失败 ⇒ 不制造不可逆改动）' })
+  }
+  if (bundled.renamed.length || bundled.stale.length) {
+    steps.push({
+      ok: true,
+      text: `bundles 条目迁移到 npm 名: ${bundled.renamed.map((r) => `${r.from} → ${r.to}`).join('；') || '无'}`
+        + `${bundled.stale.length ? `；摘陈旧别名 ${bundled.stale.join(', ')}` : ''}（备份 ${bundled.backup ? '已存' : '失败'}）`,
+    })
+  }
+  // 6.6) 依赖键迁移（W9 漏迁的第二处；安装器那段在升级路径上**不会被执行** —— 见 normalizeDepKeys）
+  const depMig = normalizeDepKeys()
+  if (depMig.renamed.length || depMig.dropped.length) {
+    steps.push({
+      ok: true,
+      text: `依赖键迁移到 npm 名: ${depMig.renamed.map((r) => `${r.from} → ${r.to}`).join('；') || '无'}`
+        + `${depMig.dropped.length ? `；摘无人引用的旧裸键 ${depMig.dropped.join(', ')}` : ''}`,
+    })
+  } else if (depMig.refused) {
+    steps.push({ ok: false, text: '依赖键迁移被跳过（写前备份失败 ⇒ 不制造不可逆改动）' })
+  }
+  const retired = retirePlugins(type)
+  if (retired.removed.length || retired.depsDropped.length) {
+    steps.push({
+      ok: true,
+      text: `退役插件收敛: 删副本 ${retired.removed.join(', ') || '无'}；摘依赖 ${retired.depsDropped.join(', ') || '无'}`,
+    })
+  }
+  // 7) 汇总
+  const version = readVersion(ARGENT_HOME)
+  // 重启判据只看**真的写盘**（幂等跳过不算 —— 否则每次 `run` 都会要求重启）
+  const restartRequired = patchRes.changed || skillRes.written.length > 0 || synced.length > 0
+    || landings.moved.length > 0 || landings.pruned.length > 0
+    || bundled.added.length > 0 || bundled.renamed.length > 0 || bundled.stale.length > 0
+    || depMig.renamed.length > 0 || depMig.dropped.length > 0
+  const isMac = process.platform === 'darwin'
+  const result = {
+    ok: pulled,
+    current: readVersion(ARGENT_HOME),
+    comboType: type,
+    targetCombo: TARGET_COMBO[type],
+    version,
+    steps,
+    patchChanged: patchRes.changed,
+    synced,
+    // 技能同步：外发集写盘清单 + **按设计不同步的内部清单**（D5；宿主多出只报告不删）
+    skillsSync: {
+      source: 'scripts/check-skill-classification.mjs#classify()（真源 = verticals/*/manifest.json#skills）',
+      external: skillCls.external,
+      written: skillRes.written,
+      skipped: skillRes.skipped,
+      missing: skillRes.missing,
+      hostInternal: skillRes.hostInternal,
+      hostExtra: skillRes.hostExtra,
+      classifyOk: skillCls.ok,
+      classifyErrors: skillCls.errors.map((e) => `[${e.rule}] ${e.message}`),
+    },
+    skippedInternal: skillCls.internal,
+    restartRequired,
+    restartHint: isMac ? '请重启 dsh web（或加 --restart 自动重启）' : '请重启 dsh web（Windows: 关闭进程重开）',
+  }
+  // 7.5) **重启前门禁**：profile 组合体检（profile-doctor）
+  // 由来（2026-09-14）：`argent-skin` 同时出现在 bundles 与 cordis.patch.yml
+  // ⇒ 加载器报 `duplicate loader entry id` ⇒ dsh web 启动即失败，在 KeepAlive 下 crash loop。
+  // 若组合是坏的，**绝不能**自动重启（那会把服务打进崩溃循环），必须先修或中止。
+  //
+  // ⛔ 2026-10-03：**默认不再 `--fix`**。旧实现无条件带 `--fix`，而 doctor 的 `--fix` 会
+  //   ① 重指 `file:` 依赖（把已消失的临时目录换成仓库路径）② 为让 node_modules 跟上而跑
+  //   `dsh plugin install`（= **pnpm install**）。这两件事都在 web profile 上真实发生过
+  //   （`~/.dsh/AGENTS.md` 明令避免在那棵树上跑 pnpm），且**没有任何提示**。
+  //   现在的姿态：默认只做**只读**体检（门禁语义不变：不通过就不自动重启）；
+  //   要让它动手必须显式 `--with-profile-fix`，且**执行前**先打印它会改什么、要不要跑包管理器。
+  const doctorPath = join(dirname(process.argv[1] ?? process.cwd()), 'profile-doctor.mjs')
+  let doctorBlocked = false
+  if (existsSync(doctorPath)) {
+    // 只读预检（--json）：拿到问题清单 + "若加 --fix 会做什么"的计划
+    // ⚠️ 显式传 DSH_HOME：doctor 按环境变量解析 home（没有 --dsh-home 开关）⇒ 不传就可能去改真实 ~/.dsh
+    const probe = runCmdSafe(process.execPath, [doctorPath, '--profile', PROFILE, '--json'], { timeout: 420000, env: { ...process.env, DSH_HOME } })
+    const pre = parseDoctorJson(probe.stdout)
+    const checkOk = pre ? pre.ok : probe.ok
+    const summary = pre ? pre.reportLines.slice(-8) : String(probe.stdout || probe.message || '').split('\n').filter(Boolean).slice(-8)
+    result.profileFix = {
+      requested: FLAG_PROFILE_FIX,
+      executed: false,
+      skipped: true,
+      reason: '默认跳过 profile --fix（只读体检；要修组合/动包管理器须显式 --with-profile-fix）',
+      plan: pre ? pre.fixPlan : null,
+      checkOk,
+    }
+    let fixOk = checkOk
+    if (FLAG_PROFILE_FIX) {
+      // **执行前**如实声明：改哪些 file: 依赖、是否跑包管理器（⛔ 不得静默）
+      const disclosure = describeProfileFix(pre ? pre.fixPlan : null, PROFILE)
+      for (const line of disclosure) console.error(line)
+      const d = runCmdSafe(process.execPath,
+        [doctorPath, '--profile', PROFILE, '--fix', '--allow-package-manager', '--json'],
+        { timeout: 420000, env: { ...process.env, DSH_HOME } })
+      const dJson = parseDoctorJson(d.stdout)
+      fixOk = dJson ? dJson.ok : d.ok
+      const fixLines = (dJson ? dJson.reportLines : `${d.stdout || ''}${d.stderr || ''}`.split('\n')).filter(Boolean)
+      for (const line of fixLines) console.error(String(line))   // doctor 报告走 stderr（stdout 留给 --json / 人类报告）
+      result.profileFix = {
+        requested: true,
+        executed: true,
+        skipped: false,
+        allowPackageManager: true,
+        plan: pre ? pre.fixPlan : null,
+        disclosure,
+        ok: fixOk,
+        fixes: dJson ? dJson.fixes : null,
+      }
+      result.doctor = { ok: fixOk, summary: fixLines.filter((l) => l.includes('[doctor]') || l.includes('✅') || l.includes('✗') || l.includes('🔧') || l.includes('⚠')).slice(-8).map((l) => String(l).trim()) }
+      steps.push({ ok: fixOk, text: `profile 组合体检+修复（--with-profile-fix）: ${fixOk ? '通过' : '仍有问题（见下方）'}` })
+    } else {
+      result.doctor = { ok: checkOk, summary: summary.map((l) => String(l).trim()) }
+      steps.push({
+        ok: checkOk,
+        text: `profile 组合体检（**只读**，未执行 --fix）: ${checkOk ? '通过' : '发现问题'}`
+          + (checkOk ? '' : '；⛔ 未自动修复（默认跳过；确需修复请显式 --with-profile-fix）'),
+      })
+    }
+    if (!fixOk) {
+      doctorBlocked = true
+      result.restartRequired = false
+      result.restartHint = '⚠ profile 组合体检未通过 —— **已阻止自动重启**（否则可能崩溃循环）；请先按 profile-doctor 输出修复'
+        + (FLAG_PROFILE_FIX ? '' : '（本轮**未**自动修复：加 --with-profile-fix 才会执行 doctor --fix）')
+      console.error('[upgrade] profile-doctor 未通过 —— 已阻止自动重启：')
+      for (const line of (result.doctor.summary || []).slice(-8)) console.error('  ' + String(line).trim())
+    }
+  }
+
+  // 7.6) 角色落盘集合：**收尾重施**（缺陷 1，2026-10-12 真机实测）
+  // 第 2 步收窄之后，第 6.5/7.5 步都可能重解析 profile 依赖（doctor --fix 甚至会跑包管理器）
+  // ⇒ profile 副本被换成指向货架的链（14 个 patch 全回来、选择痕迹消失）。这里按第 2 步算出的
+  // **同一目标集合**再施加一次，并核对"三处集合 + 痕迹"四者相等。
+  // ⚠️ 追修批：这一步必须**从货架重播**再收窄（`reseedFromShelf`）—— 第 2 步若已把副本收窄到 7，
+  //    就地再收窄一次永远只能得 7（`kept ⊆ universe`）⇒ `--internal-roles` 装不回来、
+  //    且自检会拿"期望 14 ≠ 落盘 7"判**假红**。货架恒全集，收窄按目标集合。
+  // ⚠️ 不变式（落盘不得含内部角色，未授权时）在这一步同样自检，违反 ⇒ 判红。
+  if (presetMechanism === MECHANISM.ROWS) {
+    // ⚠️ W9：同上 —— 收尾重施的落点也必须是**包名目录**（两个名字都找）。
+    const bundleDir = resolveBundleDir(PROFILE_DIR)
+    const want = (UPGRADE_PRESET_LANDING && UPGRADE_PRESET_LANDING.kept.length)
+      ? UPGRADE_PRESET_LANDING.kept
+      : PRESET_INSTALLED.ids
+    if (PENDING_PRESET_REAPPLY && want.length && existsSync(bundleDir)) {
+      const shelfSrc = join(ARGENT_HOME, 'plugins', 'argent-presets')
+      const mat = materializeBundleDir(bundleDir, shelfSrc)
+      if (!mat.ok) {
+        steps.push({ ok: false, text: `角色落盘集合收尾未通过：${mat.reason}` })
+      } else {
+        const why = `${(UPGRADE_PRESET_LANDING && UPGRADE_PRESET_LANDING.why) || '升级按选择痕迹'}｜收尾重施（doctor 之后）`
+        const sel = applyPresetSelection(bundleDir, want, { why, log: () => {}, shelfSrc, allowInternal: PRESET_ALLOW_INTERNAL, reseedFromShelf: true })
+        if (sel.refused) {
+          steps.push({ ok: false, text: `角色落盘集合收尾**判红并拒绝写出**：${sel.note}` })
+        } else {
+          const chk = checkPresetSelectionConsistency(bundleDir, want)
+          steps.push({
+            ok: chk.ok,
+            text: `角色落盘集合收尾：${chk.shelf.length} 个${sel.reseeded ? '（已按货架重播后收窄）' : mat.materialized ? '（副本曾被包管理器换成软链 ⇒ 已实体化）' : ''}`
+              + (chk.ok ? '；三处集合 + 痕迹一致' : `；⚠ 不一致：${chk.problems.join('；')}`),
+          })
+        }
+      }
+    }
+  }
+
+  // 8) 自动重启（--restart，macOS launchd）
+  if (FLAG_RESTART && restartRequired && isMac && !doctorBlocked) {
+    const lt = runCmdSafe('launchctl', ['list'])
+    if (lt.ok && lt.stdout.includes(RESTART_LABEL)) {
+      const uid = process.getuid?.() ?? 501
+      result.restartScheduled = true
+      result.restartHint = `已调度自动重启（${RESTART_LABEL}，约 3 秒后执行，服务自动恢复）`
+      setTimeout(() => {
+        try {
+          const kid = spawn('launchctl', ['kickstart', '-k', `gui/${uid}/${RESTART_LABEL}`], { detached: true, stdio: 'ignore' })
+          kid.unref()
+        } catch { /* 忽略 */ }
+      }, 3000)
+    } else {
+      result.restartHint = '未检测到 launchd 托管（com.whyshu.dsh-web），请手动重启'
+    }
+  }
+  out(result)
+}
+
+// ── help ──────────────────────────────────────────────────
+// ⚠️ CLI 只在**被直接执行**时跑：`scripts/tests/upgrade-skill-whitelist.test.mjs` 要 `import` 本模块的
+// 纯函数（`syncSkills` / `classifySkills`）做离线回归 —— 若无条件执行，import 一次就打印一遍 help
+// 并可能按测试进程的 argv 误跑 `run`（那是会写盘的）。
+// 「是否直接执行」= 共享判据 `scripts/lib/is-direct-run.mjs`（realpath 比对；软链下不退化为"静默不跑"）。
+// 历史：本文件曾内联这份实现，而其它脚本仍用 `pathToFileURL(argv[1]) === import.meta.url`
+// （`/tmp` → `/private/tmp`、`/var/folders` → `/private/var/folders` 时**假否定** ⇒ CLI 静默不跑）。
+// 2026-10-04 起**唯一实现**在 helper 里，全仓库 scripts/*.mjs 共用（回归 scripts/tests/is-direct-run.test.mjs）。
+function main() {
+  if (MODE === 'check') doCheck()
+  else if (MODE === 'run') doRun().catch((e) => { console.error(`✗ 升级执行失败：${String((e && e.message) || e).split('\n')[0]}`); process.exitCode = 1 })
+  else if (MODE === 'migrate-deps') doMigrateDeps().catch((e) => { console.error(`✗ 依赖迁移失败：${String((e && e.message) || e).split('\n')[0]}`); process.exitCode = 1 })
+  else help()
+}
+function help() {
+  console.log(`Argent 自举升级器（v0.9）
+用法:
+  node argent-upgrade.mjs check            检测远端版本
+  node argent-upgrade.mjs run [--restart]  完整升级（--restart=完成后自动重启 dsh web）
+  node argent-upgrade.mjs run --json       JSON 输出
+  node argent-upgrade.mjs migrate-deps [--apply] [--allow-package-manager] [--data-dir <dir>]
+                                           存量迁移：profile 的**遗留 \`file:\` 依赖** ⇒ npm 名（\`@whyshu/…\`）。
+                                           ⛔ 默认**干跑**（先打印"改哪些依赖 / 是否跑包管理器 / 影响哪些 face"）；
+                                           加 \`--apply\` 才写：**写前备份（时间戳 + sha256 + 回滚命令）→ 改 manifest
+                                           → 读回验收 → 审计 JSONL**；**幂等**（已迁过 ⇒ 零写入，连 mtime 都不动）。
+                                           ⛔ 默认**不跑包管理器**（红线：裸跑 pnpm 会把 profile 弄坏）；
+                                           要动它必须显式 \`--allow-package-manager\`（沿用 profile-doctor 的口径）。
+  node argent-upgrade.mjs run --with-profile-fix
+                                           显式允许升级器修 profile 组合（= profile-doctor --fix）。
+                                           ⛔ 默认**不修**（只做只读体检）：该修复会重指 file: 依赖，
+                                           必要时还会跑包管理器（dsh plugin install = pnpm install），
+                                           在 web profile 上属红线动作（见 ~/.dsh/AGENTS.md，2026-10-03 事故）。
+                                           开了开关会**先打印**它要改什么、是否跑包管理器，再执行。
+技能同步: **只发外发集**（外发 = verticals/*/manifest.json#skills 的并集；判据见 scripts/check-skill-classification.mjs）。
+          内部角色技能（skills/internal.json）**不外发**；宿主技能根里已有的内部/旧技能**只报告不删**。
+环境: ARGENT_DISH_HOME（别名 ARGENT_HOME）/ DSH_HOME / DSH_PROFILE 可覆盖（默认 ~/.argent-dsh / ~/.dsh / web）`)
+}
+
+if (isDirectRun(import.meta.url)) main()