@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/lib/deps-migrate.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+/**
+ * deps-migrate —— 存量机器「遗留 `file:` 依赖 ⇒ npm 名」的**唯一实现**（0.6.0 W8，2026-10-14）
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 它解决什么（现场形态，2026-10-03 实测）
+ * ══════════════════════════════════════════════════════════════════════════
+ * 存量客户机的 profile `package.json` 里，Argent 插件是按**本机路径**装的：
+ *   `"argent-core": "file:/private/var/folders/…/tmp.yHwjWMOjNV/repo/plugins/argent-core"`
+ * 那个临时目录早没了 ⇒ 依赖永远解析不到；而 npm 名（`@whyshu/argent-core@1.2.3`）是**随机器走**的。
+ * 本模块把这件事做成一条**可干跑、可回滚、幂等**的迁移：
+ *
+ * | 纪律 | 判据 |
+ * |---|---|
+ * | **默认干跑** | `plan()` 是纯函数（零 IO 副作用）；只有 `apply()` 才写盘 |
+ * | **先备份** | 写前 `cp` 到 `<数据目录>/backup/<名>.<UTC 时间戳>` + **sha256** + **逐字回滚命令** |
+ * | **写后读回** | 写完立刻重新解析并断言目标形态（⛔ 不"写完就算成功"） |
+ * | **幂等** | 已经迁过的机器 ⇒ `plan().changed === 0` ⇒ **零写入**（连 mtime 都不动） |
+ * | **⛔ 不裸跑包管理器** | 默认**不跑**；要跑必须显式 `--allow-package-manager`（AGENTS 红线：会把 profile 弄坏） |
+ * | **审计** | 每次真写追加一行 JSONL（谁/何时/改了什么/备份在哪/回滚命令） |
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 边界（⛔ 改本文件前先读）
+ * ══════════════════════════════════════════════════════════════════════════
+ * 1. **只碰已知 Argent 插件**（判据 = `scripts/lib/plugin-packages.mjs#pluginIdOf`，**唯一真源**）。
+ *    别的 `file:`、别人的 scope、官方 `@deepseek-ai/*` ⇒ 一律 `unknown`/`keep`，⛔ 不越权。
+ * 2. **只迁"顶层包目录"形态**（`file:…/plugins/<id>` / `file:…/packs-cache/<id>.tgz`）。
+ *    **子路径导出**（`file:…/plugins/argent-core/llm-whyshu`）在 npm 上**没有对应包**
+ *    （它是 `argent-core` 的子导出）⇒ 必须**原样留着**（⛔ 迁了就是断链）。
+ * 3. **不改版本语义**：目标版本 = **本机克隆/包留档里那个真实版本**（读不到 ⇒ 该条判 `blocked`，
+ *    ⛔ 不编一个版本号）。壳/智能体用**精确版本**，与安装器 `npmSpecOf()` 同口径。
+ * 4. **两条线共用**：升级器（`scripts/argent-upgrade.mjs migrate-deps`）与安装器的
+ *    依赖键迁移**都调这里的纯函数** —— ⛔ 不许在别处写第二份"file: 怎么迁"。
+ */
+
+import { createHash } from 'node:crypto'
+import { copyFileSync, existsSync, mkdirSync, appendFileSync, readFileSync, writeFileSync } from 'node:fs'
+import { hostname, userInfo } from 'node:os'
+import { dirname, join } from 'node:path'
+import { pluginIdOf, PLUGIN_PACKAGES, npmNameOf, npmSpecOf, readPluginVersion, pluginPackageDir } from './plugin-packages.mjs'
+
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+export const sha256 = (text) => createHash('sha256').update(text).digest('hex')
+
+/** 一条依赖的形态判据（**纯**：只按字符串判，⛔ 不读盘）。 */
+export function classifySpec(spec) {
+  const s = String(spec ?? '').trim()
+  if (!s) return { kind: 'empty' }
+  if (!s.startsWith('file:')) return { kind: 'npm', spec: s }
+  const p = s.slice('file:'.length).replace(/\\/g, '/').replace(/\/+$/, '')
+  const m = p.match(/(?:^|\/)(plugins|packs-cache)\/([^/]+?)(?:\.tgz)?$/)
+  if (!m) {
+    // `file:…/plugins/<id>/<子路径>`（子导出）或任意别的路径
+    const sub = p.match(/(?:^|\/)plugins\/([^/]+)\/.+$/)
+    if (sub) return { kind: 'file-subpath', spec: s, base: sub[1], path: p }
+    return { kind: 'file-other', spec: s, path: p }
+  }
+  return {
+    kind: m[1] === 'packs-cache' ? 'file-tgz' : 'file-plugin',
+    spec: s, base: m[2], path: p,
+  }
+}
+
+/**
+ * 算迁移计划（**纯函数**：只读调用方传进来的 `pkg`；版本从 `versionOf` 回调拿）。
+ *
+ * @param {object} opts
+ * @param {object} opts.pkg          profile 的 `package.json`（已解析）
+ * @param {(id:string)=>string} [opts.versionOf]  取某插件的**真实版本**（读不到 ⇒ ''）
+ * @param {(id:string)=>boolean} [opts.knownId]   该 id 是不是已知 Argent 插件（缺省用 pluginIdOf）
+ * @returns {{ok:boolean, changed:number, entries:Array, deps:object, blocked:string[], notes:string[]}}
+ */
+export function planDepsMigration({ pkg, versionOf = () => '', knownId = null, source = 'profile' } = {}) {
+  const deps = isObj(pkg && pkg.dependencies) ? pkg.dependencies : {}
+  const entries = []
+  const blocked = []
+  const notes = []
+  if (!isObj(pkg && pkg.dependencies)) {
+    notes.push('profile 的 `dependencies` 不是对象（或不存在）⇒ 无可迁移之物')
+    return { ok: true, changed: 0, entries, deps: { ...deps }, blocked, notes, source }
+  }
+  const out = { ...deps }
+  for (const [key, spec] of Object.entries(deps)) {
+    const c = classifySpec(spec)
+    const id = knownId ? (knownId(key) ? knownId(key) : null) : pluginIdOf(key)
+    const row = { key, spec: String(spec), kind: c.kind, id: id || null, action: 'keep', to: null, why: '' }
+
+    if (c.kind === 'file-subpath') {
+      row.action = 'keep'
+      row.why = `子路径导出（${c.base} 的子路径）在 npm 上没有对应包 ⇒ 原样留着（迁了就是断链）`
+      entries.push(row); continue
+    }
+    if (c.kind === 'file-other' || c.kind === 'empty') {
+      row.action = 'keep'
+      row.why = c.kind === 'empty' ? '空值 ⇒ 不动' : '`file:` 指向的既不是插件目录也不是包留档 ⇒ ⛔ 不越权'
+      entries.push(row); continue
+    }
+    if (!id) {
+      row.action = c.kind === 'npm' ? 'already-npm' : 'keep'
+      row.why = c.kind === 'npm'
+        ? '已是非 `file:` 规格且不是已知 Argent 插件 ⇒ 原样（⛔ 不越权）'
+        : `\`file:\` 的 base 不是已知 Argent 插件（${c.base}）⇒ ⛔ 不越权改`
+      entries.push(row); continue
+    }
+    const npm = npmNameOf(id)
+    const needNpmSpec = c.kind === 'file-plugin' || c.kind === 'file-tgz'
+    if (!needNpmSpec) {
+      // 非 `file:`（npm 范围 / tarball 之外的写法）：**只迁键**（spec 原样 —— 来源不是本模块的事）
+      if (key === npm) { row.action = 'already-npm'; row.why = `键已是 npm 名（${npm}）⇒ 无需迁移`; entries.push(row); continue }
+      delete out[key]
+      out[npm] = String(spec)
+      row.action = 'migrate'
+      row.to = `${npm}（spec 原样：${String(spec)}）`
+      row.renamed = true
+      row.why = `裸名键 ⇒ npm 名（spec 原样保留；来源不是本次迁移的对象）`
+      entries.push(row); continue
+    }
+    if (key === npm) {
+      row.action = 'already-npm'
+      row.why = `键已是 npm 名（${npm}）⇒ 无需迁移`
+      entries.push(row); continue
+    }
+    const ver = String(versionOf(id) || '')
+    if (!ver) {
+      row.action = 'blocked'
+      row.why = `读不到 ${id} 的**真实版本**（本机克隆/包留档里都没有）⇒ ⛔ 不编版本号；先补克隆或包留档`
+      blocked.push(`${key} → ${npm}：${row.why}`)
+      entries.push(row); continue
+    }
+    const to = npmSpecOf(id, ver)
+    if (!to) {
+      row.action = 'blocked'
+      row.why = `拼不出 npm 规格（${id}）`
+      blocked.push(`${key}：${row.why}`)
+      entries.push(row); continue
+    }
+    row.action = 'migrate'
+    row.to = to
+    row.why = `遗留 ${c.kind}（${c.path}）⇒ npm 名 ${to}（版本取自本机真实包）`
+    if (key !== npm) {
+      delete out[key]
+      out[npm] = to
+      row.renamed = true
+      row.why += '；**键同时改名**（裸名 ⇒ npm 名）'
+    } else {
+      out[key] = to
+    }
+    entries.push(row)
+  }
+  const changed = entries.filter((e) => e.action === 'migrate').length
+  if (!changed) notes.push('没有需要迁移的依赖 ⇒ 计划为空（幂等：这一步**零写入**）')
+  return { ok: blocked.length === 0, changed, entries, deps: out, blocked, notes, source }
+}
+
+/** 序列化 profile `package.json`（与仓库既有写盘口径一致：2 空格 + 末尾换行）。 */
+export const serializePkg = (pkg, deps) => `${JSON.stringify({ ...pkg, dependencies: deps }, null, 2)}\n`
+
+/**
+ * 备份文件名（UTC 时间戳 + 原文件名；与 `backupFile()` 同风格）。
+ * ⚠️ `reason` 会被 **slug 化**（非 `[A-Za-z0-9._-]` ⇒ `-`）：备份名会被写进**回滚命令**，
+ *    带空白/箭头/中文的文件名在 shell 里是另一个坑（`cp -p "a b" c` 一旦有人少写引号就炸）。
+ */
+export function backupName(file, now = new Date(), reason = '') {
+  const ts = now.toISOString().replace(/[-:]/g, '').replace(/\..+$/, '').replace('T', '-')
+  const slug = String(reason).replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '')
+  const tail = slug ? `.${slug}` : ''
+  return `${file.split('/').pop()}.deps-migrate-${ts}${tail}`
+}
+
+/**
+ * 干跑/真跑的统一渲染（**CLI 与审计共用**；⛔ 别处不再拼一遍）。
+ * @returns {{lines:string[], rollback:string, summary:string}}
+ */
+export function renderPlan(plan, { profilePkgPath = '', apply = false, runPackageManager = false } = {}) {
+  const lines = []
+  const mig = plan.entries.filter((e) => e.action === 'migrate')
+  const kee = plan.entries.filter((e) => e.action === 'keep')
+  const blk = plan.entries.filter((e) => e.action === 'blocked')
+  lines.push(`${apply ? '执行' : '干跑（dry-run）'}：将改 ${mig.length} 条依赖｜不动 ${kee.length} 条｜受阻 ${blk.length} 条`)
+  for (const e of plan.entries) {
+    if (e.action === 'migrate') lines.push(`  → ${e.key}：${e.spec}  ⇒  ${e.to}`)
+    else if (e.action === 'blocked') lines.push(`  ✗ ${e.key}：${e.why}`)
+    else if (e.action === 'keep') lines.push(`  · ${e.key}：保持（${e.why}）`)
+  }
+  lines.push(`包管理器：${runPackageManager ? '**会跑**（--allow-package-manager 显式开启）' : '不跑（默认；⛔ 裸跑 pnpm 会把 profile 弄坏）'}`)
+  lines.push(`影响面（face）：profile package.json${profilePkgPath ? `（${profilePkgPath}）` : ''}`
+    + `${runPackageManager ? ' + node_modules（包管理器装上/更新后同步）' : '（node_modules 不变 —— 未跑包管理器，落位仍是旧来源）'}`)
+  const rollback = profilePkgPath
+    ? `cp -p "${profilePkgPath}.deps-migrate-<时间戳>" "${profilePkgPath}"   # 或：cp -p "<备份路径>" "${profilePkgPath}"`
+    : '（没有 profile package.json ⇒ 无需回滚）'
+  return { lines, rollback, summary: `${mig.length} 条待迁 / ${blk.length} 条受阻` }
+}
+
+/**
+ * 真跑：**先备份 → 改 manifest → 读回验收 → 审计**（幂等：`changed === 0` ⇒ 立刻返回，零写入）。
+ *
+ * ⛔ 本函数**不跑任何包管理器**（那是调用方在显式开关下的职责）。
+ * @returns {{ok:boolean, wrote:boolean, backup:string, backupSha:string, rollback:string,
+ *            audit:string, verify:string, error:string}}
+ */
+export function applyDepsMigration({
+  pkgPath, pkg, plan, auditPath, backupDir, now = new Date(), reason = 'W8 file:→npm',
+  fs = { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync, appendFileSync, dirname },
+  by = '',
+  /**
+   * 读回验收用的**重算器**（可选）。⚠️ 必须与产出 `plan` 的那次用**同一套判据**
+   * （同样的 `knownId`/`versionOf`）—— 否则"缺版本"这类条目在两套判据下结论不同，
+   * 验收会**假红**（实测：夹具里没传 knownId ⇒ 重算时裸键也算待迁 ⇒ 明明迁对了却判失败）。
+   * 缺省 = `(pkg) => planDepsMigration({ pkg })`（仅"spec 还是不是 `file:`"这一层判据）。
+   */
+  replan = null,
+} = {}) {
+  const result = { ok: false, wrote: false, backup: '', backupSha: '', rollback: '', audit: '', verify: '', error: '' }
+  if (!plan || plan.changed === 0) {
+    result.ok = true
+    result.verify = 'nothing-to-do（幂等：零写入）'
+    return result
+  }
+  if (plan.blocked && plan.blocked.length) {
+    result.error = `有 ${plan.blocked.length} 条受阻（${plan.blocked[0]}）⇒ ⛔ 拒绝半截迁移（要么全可迁、要么先补证据）`
+    return result
+  }
+  const before = fs.readFileSync(pkgPath, 'utf8')
+  if (!backupDir) { result.error = '没有备份目录（backupDir 必填）⇒ ⛔ 不写'; return result }
+  const backup = join(backupDir, backupName(pkgPath, now, reason))
+  try {
+    fs.mkdirSync(dirname(backup), { recursive: true })
+    fs.copyFileSync(pkgPath, backup)
+  } catch (e) {
+    result.error = `备份失败（${String((e && e.message) || e)}）⇒ ⛔ 不写`
+    return result
+  }
+  result.backup = backup
+  result.backupSha = sha256(before)
+  result.rollback = `cp -p "${backup}" "${pkgPath}"`
+  const text = serializePkg(pkg, plan.deps)
+  try {
+    fs.writeFileSync(pkgPath, text)
+  } catch (e) {
+    result.error = `写盘失败（${String((e && e.message) || e)}）；备份在 ${backup}`
+    return result
+  }
+  // ── 读回验收（⛔ 不"写完就算成功"）──────────────────────────────────────────
+  let after = null
+  try { after = fs.readFileSync(pkgPath, 'utf8') } catch (e) { result.error = `写后读回失败（${String((e && e.message) || e)}）`; return result }
+  let re = null
+  try {
+    re = (typeof replan === 'function' ? replan : (doc) => planDepsMigration({ pkg: doc }))(JSON.parse(after))
+  } catch (e) {
+    result.error = `写后读回解析失败（${String((e && e.message) || e)}）⇒ 逐字节回滚：${result.rollback}`
+    try { fs.writeFileSync(pkgPath, before) } catch { /* 回滚失败已由 error 表达 */ }
+    return result
+  }
+  if (!re || re.changed !== 0) {
+    result.error = `写后读回验收失败：重算仍显示 ${re ? re.changed : '?'} 条待迁 ⇒ 逐字节回滚：${result.rollback}`
+    try { fs.writeFileSync(pkgPath, before) } catch { /* 回滚失败已由 error 表达 */ }
+    return result
+  }
+  // ⛔ 第二条判据（**内容真的变了**）：写入被静默吞掉 / 写成同一份字节 ⇒ 不算迁移成功。
+  //    只看"重算待迁 0 条"是不够的：**判据本身依赖磁盘内容** ⇒ 内容没变时那条判据会**自洽地通过**。
+  if (sha256(after) === result.backupSha) {
+    result.error = `写后读回：文件**逐字节未变**（写入被静默吞掉）⇒ 不算迁移成功；回滚/排查：${result.rollback}`
+    return result
+  }
+  result.verify = `写后读回：重算待迁 0 条 ∧ 内容已变（before sha256 ${result.backupSha.slice(0, 12)}…）`
+  result.wrote = true
+  if (auditPath) {
+    try {
+      fs.mkdirSync(dirname(auditPath), { recursive: true })
+      const rec = {
+        ts: now.toISOString(),
+        tool: 'deps-migrate',
+        reason,
+        pkgPath,
+        backup: result.backup,
+        backupSha256: result.backupSha,
+        rollback: result.rollback,
+        changed: plan.entries.filter((e) => e.action === 'migrate').map((e) => ({ from: `${e.key}=${e.spec}`, to: e.to })),
+        kept: plan.entries.filter((e) => e.action === 'keep').map((e) => e.key),
+        packageManager: false,
+        by: by || `${(() => { try { return userInfo().username } catch { return 'unknown' } })()}@${hostname()}`,
+      }
+      if (!fs.existsSync(auditPath)) fs.appendFileSync(auditPath, `${JSON.stringify({ _doc: '依赖迁移审计（W8）：谁在什么时候把 file: 依赖迁成了 npm 名。JSONL 追加；与 schedule-audit.jsonl 同风格。' })}\n`)
+      fs.appendFileSync(auditPath, `${JSON.stringify(rec)}\n`)
+      result.audit = auditPath
+    } catch (e) {
+      result.error = `审计追加失败（${String((e && e.message) || e)}）—— 迁移本身已成功并已验收`
+    }
+  }
+  result.ok = true
+  return result
+}
+
+/** 取某插件的**真实版本**（克隆里的 `plugins/<id>/package.json`；读不到 ⇒ ''，⛔ 不编）。 */
+export function realVersionOf(repoRoot, id) {
+  if (!repoRoot) return ''
+  const dir = pluginPackageDir(repoRoot, id)
+  if (!dir || !existsSync(dir)) return ''
+  return readPluginVersion(repoRoot, id) || ''
+}
+
+/** 已知 id 判据（**写侧严格**：只认裸名/本仓 npm 名，⛔ 不认路径形态与别的 scope）。 */
+export function knownPluginId(key) {
+  const s = String(key ?? '').trim()
+  if (!s) return null
+  for (const p of PLUGIN_PACKAGES) {
+    if (s === p.id || s === p.npm) return p.id
+  }
+  return null
+}

package/engine/scripts/lib/dsh-host-resolve.mjs

@@ -0,0 +1,109 @@
+/**
+ * 宿主（dsh）**解析链** —— 唯一真源（纯函数，可离线测试；2026-10-12 用户决定）。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 一、为什么有它
+ * ══════════════════════════════════════════════════════════════════════════
+ * 用户 2026-10-12 定的三条政策：
+ *   ① **彻底删掉 `--install-host`**：Argent ⛔ 不代装宿主（宿主迭代频繁、副本维护不动；装不上客户会
+ *      找我们，而我们解决不了）。理由写进设计 §8.4 的实现注记。
+ *   ② 被拒时给的是 dsh **官方**运行方式（官方 README「运行」）：首选
+ *      **`npx @deepseek-ai/dsh web`**（通过 npm 运行），备选**从源码运行**。
+ *   ③ **npx 形态是官方首选 ⇒ 必须被识别为"有宿主"**（旧口径"npx 不算已安装宿主"**作废**）。
+ *
+ * 解析链（顺序即优先级；**确定且可解释**，每一步都能在输出里看到）：
+ *   PATH 上的 `dsh`  →  `DSH_BIN`  →  **npx 缓存形态**  →  都没有 ⇒ 调用方拒绝 + 官方指引。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 二、npx 缓存形态长什么样
+ * ══════════════════════════════════════════════════════════════════════════
+ * `npx @deepseek-ai/dsh@<版本> web` 跑过之后，npm 会把整棵依赖树留在自己的 `_npx` 缓存里：
+ *   `<npm cache>/_npx/<hash>/node_modules/@deepseek-ai/dsh/package.json`   ← 这里读 version
+ * 所以判据是**读一个 package.json**（纯只读、不联网、不执行 npx）——⛔ 不跑 `npx --version`：
+ * 那可能触发一次真实下载（慢、且把"零网络"变成假的），而版本号在文件里就有。
+ *
+ * 多个候选时的选择规则（`NPX_PICK_RULE`，调用方必须**打印选了哪个**）：
+ *   ① 只认能读出的 `@deepseek-ai/dsh`（坏 JSON / 别的包 ⇒ 跳过，不猜）；
+ *   ② **最近使用优先** = `package.json` 的 mtime 最新（npx 每次跑会刷新它 ⇒ 最接近"你实际在跑的
+ *      那一个"）；③ 同刻（mtime 相同）按**路径升序** —— 保证结果与目录遍历顺序无关、可复现。
+ *   ⚠️ 刻意**不**按"版本号最大"或"优先窗口内版本"挑：客户实际在跑哪个版本，就该按哪个版本判门禁
+ *      （否则我们会在一台实际跑着窗口外版本的机器上"装成功"，且客户不会知道）。
+ */
+
+/**
+ * 一个 package.json 对象是不是 dsh 主包（判据只认 name + 非空 version）。
+ * @param {any} obj
+ * @returns {boolean}
+ */
+export function isDshPackageJson(obj) {
+  return Boolean(obj) && typeof obj === 'object'
+    && obj.name === '@deepseek-ai/dsh'
+    && typeof obj.version === 'string' && obj.version.trim() !== ''
+}
+
+/**
+ * npx 缓存候选目录（按查序返回，已去重）。
+ *   · `npm_config_cache` / `NPM_CONFIG_CACHE`（npm 自己的覆盖）⇒ `<cache>/_npx`
+ *   · `~/.npm/_npx`（macOS/Linux 与 npm 默认）
+ *   · `%LOCALAPPDATA%\npm-cache\_npx`（Windows 默认）
+ * @param {{home?: string, env?: Record<string,string|undefined>}} o
+ * @returns {string[]}
+ */
+export function npxCacheDirs({ home = '', env = {} } = {}) {
+  const out = []
+  const push = (p) => { const v = String(p || '').replace(/[\\/]+$/, ''); if (v && !out.includes(v)) out.push(v) }
+  const cache = env.npm_config_cache || env.NPM_CONFIG_CACHE || ''
+  if (cache) push(`${cache}/_npx`)
+  if (home) push(`${home}/.npm/_npx`)
+  const la = env.LOCALAPPDATA || env.LocalAppData || ''
+  if (la) push(`${la}/npm-cache/_npx`)
+  return out
+}
+
+/**
+ * 扫缓存目录，返回所有"看起来装过 dsh"的候选（**只读**；坏 JSON / 别的包一律跳过，不猜）。
+ * @param {string[]} dirs                    npxCacheDirs() 的产物
+ * @param {{exists:(p:string)=>boolean, readdir:(p:string)=>string[], read:(p:string)=>string, stat:(p:string)=>{mtimeMs:number}}} io
+ * @returns {Array<{pkgDir:string, pkgJson:string, version:string, mtimeMs:number, cacheDir:string, hash:string}>}
+ */
+export function scanNpxCache(dirs, io) {
+  const out = []
+  for (const dir of dirs || []) {
+    if (!dir || !io.exists(dir)) continue
+    let hashes = []
+    try { hashes = io.readdir(dir) } catch { continue }
+    for (const hash of [...hashes].sort()) {
+      const pkgDir = `${dir}/${hash}/node_modules/@deepseek-ai/dsh`
+      const pkgJson = `${pkgDir}/package.json`
+      if (!io.exists(pkgJson)) continue
+      let meta = null
+      try { meta = JSON.parse(io.read(pkgJson)) } catch { continue }   // 坏 JSON ⇒ 跳过（不猜版本）
+      if (!isDshPackageJson(meta)) continue
+      let mtimeMs = 0
+      try { mtimeMs = Number(io.stat(pkgJson).mtimeMs) || 0 } catch { mtimeMs = 0 }
+      out.push({ pkgDir, pkgJson, version: String(meta.version).trim(), mtimeMs, cacheDir: dir, hash })
+    }
+  }
+  return out
+}
+
+/**
+ * 确定性挑选（规则见文件头 `NPX_PICK_RULE`）：mtime 最新优先，同刻按路径升序。
+ * ⛔ 不做"优先窗口内版本"的二次挑选 —— 这台机器实际在跑哪个版本，就按哪个版本判门禁。
+ * @param {Array<object>} cands scanNpxCache() 的产物
+ * @returns {{chosen: object|null, considered: Array<{version:string,pkgDir:string,mtimeMs:number}>}}
+ */
+export function pickNpxHost(cands) {
+  const list = [...(cands || [])].sort((a, b) => {
+    if (b.mtimeMs !== a.mtimeMs) return b.mtimeMs - a.mtimeMs
+    return a.pkgDir < b.pkgDir ? -1 : a.pkgDir > b.pkgDir ? 1 : 0
+  })
+  return {
+    chosen: list.length ? list[0] : null,
+    considered: list.map((c) => ({ version: c.version, pkgDir: c.pkgDir, mtimeMs: c.mtimeMs })),
+  }
+}
+
+/** 选择规则的**人话**（调用方打印它 ⇒ "确定且可解释"）；⛔ 别在别处再写第二份措辞。 */
+export const NPX_PICK_RULE = 'npx 缓存里可能有多个 dsh：按「最近使用优先（package.json mtime 最新），同刻按路径升序」'
+  + '选定一个（⛔ 不按版本号挑：你这台机器实际在跑哪个版本，就按哪个版本判门禁）'