@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/dsh-scope-rewire.mjs

@@ -0,0 +1,803 @@
+#!/usr/bin/env node
+/**
+ * dsh-scope-rewire.mjs —— profile「`@deepseek-ai` 软链农场」**改线器**（P1-2，2026-10-12）
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 一、它解决什么（为什么必须有工具，而不是"手敲 ln -sf"）
+ * ══════════════════════════════════════════════════════════════════════════
+ * dsh 的 profile 里，`node_modules/@deepseek-ai` 指向**某一个具体 node 前缀的全局 scope**
+ * （本机 = `/opt/homebrew/lib/node_modules/@deepseek-ai`）。换前缀 / 重装 dsh 后若只清旧 scope
+ * 而不重建这些链 ⇒ **宿主新版本 + profile peer 解析到旧版本**的混合版本 ⇒ 前端 boot 永久 pending、
+ * `dsh web` 卡在加载屏（服务端 200 全绿也救不了）。
+ * 这类"改 line 软链农场"的动作在本仓库**踩过四次**（AGENTS 有记）⇒ 必须：**默认 dry-run、
+ * 先备份、有回滚、幂等、写后校验**。手敲 `ln -sf` 四样一样都不占。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 二、两种农场形态（实测本机两种**同时存在**，别再按"284 条链"想当然）
+ * ══════════════════════════════════════════════════════════════════════════
+ * | 形态 | 农场路径 | 真身 | 改线动作 |
+ * |---|---|---|---|
+ * | **整树链接**（`dir-link`） | `profiles/<p>/node_modules/@deepseek-ai` | **一个软链**指向整个 scope 目录 | 换掉这**一个**软链 |
+ * | **行式**（`per-pkg`） | `profiles/node_modules/@deepseek-ai` | 真目录 + **逐包软链** | 逐包改指 / 新增 / 清陈旧 |
+ *
+ * 本机实测（2026-10-12）：`profiles/web/node_modules/@deepseek-ai` = **1 条**软链（穿过去可见 284 个包，
+ * 外界常把这 284 说成"284 条软链"）；`profiles/node_modules/@deepseek-ai` = **240 条**逐包软链，
+ * 其中 **6 条断链**（`dsh-code-runtime` / `dsh-agent-presets` / `cordis-plugin-hmr` / `dsh-settings-file` …，
+ * 这些包在 0.1.7 与 0.2 里**都不存在** ⇒ 改线时应**删除**而不是改指）。
+ *
+ * ## 归属与"唯一真源"
+ * · 形态探测（`locateScopeFarm` / `listFarmPackages` / `readPackageVersion`）**薄委托**给
+ *   `scripts/lib/bootcheck-wiring.mjs` —— 那是 P1-0 建立的"目标 scope 布局"**唯一判据**，
+ *   ⛔ 本文件**不再写第二份**（两套探测迟早漂移：门禁说 0.2 树可用、改线器却认不出它的布局）。
+ * · ⛔ 本文件**不 import** `scripts/lib/dsh-scope.mjs`（它在能力包 `pack.engine` 清单里，
+ *   改它 ⇒ 三个包 digest 漂移 ⇒ 必须提版/重盖章）。本工具**零 pack.engine 成员改动** ⇒ **零提版**。
+ * · 归属：`scripts/dsh-*.mjs` 在 kernel-purity 里已是 **L2（dsh 宿主运维档）** ⇒ 无需登记新条目。
+ *   依赖面刻意收窄到 **node 内建 + 同层 L1/L2 模块**，零第三方、零宿主 import。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 三、用法（**默认 dry-run**；真写必须 `--apply --yes` 两条同时给）
+ * ══════════════════════════════════════════════════════════════════════════
+ * ```
+ * # 1) 只读预演（真机晋级前给用户看的计划；不改一个字节）
+ * node scripts/dsh-scope-rewire.mjs --profile web \
+ *   --target-scope /tmp/dsh-preflight-0.2.0-rc.2/node_modules/@deepseek-ai
+ *
+ * # 2) 真写（晋级时、用户在场）
+ * node scripts/dsh-scope-rewire.mjs --profile web --target-scope <…/@deepseek-ai> --apply --yes
+ *
+ * # 3) 回滚（把计划里打印的"回滚命令"原样跑）
+ * node scripts/dsh-scope-rewire.mjs --rollback <备份目录> --apply --yes
+ * ```
+ * 入参：`--profile <name>`（默认 `web`）｜`--all-profiles`｜`--target-scope <…/@deepseek-ai>`（改线时必填）
+ * ｜`--dsh-home <path>`（默认真实 `~/.dsh`）｜`--apply`（默认关）｜`--yes`（与 `--apply` 同时才真写）
+ * ｜`--backup-dir <path>`（默认 `<数据目录>/backup/scope-rewire-<时间戳>`）｜`--no-shared`（不改父级共享农场）
+ * ｜`--rollback <备份目录>`｜`--json`。
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 四、判据（出口判据，全部机器可判；⛔ 不硬编码 284/289 这类数字）
+ * ══════════════════════════════════════════════════════════════════════════
+ * | # | 判据 | 通过条件 |
+ * |---|---|---|
+ * | V1 | **零断链** | 农场里没有任何"lstat 是软链 ∧ 目标不存在"的条目 |
+ * | V2 | 逐包命中目标 | 目标 scope 提供的**每一个**包，在农场里都可解析且 `realpath` 落在目标农场内 |
+ * | V3 | 无外指 | 农场里没有软链指向目标农场**之外** |
+ * | V4 | **集合一致** | 农场非点条目集合 **==** 目标 scope 包集合（"与目标 scope 实际提供的包集合一致"，不写死数字） |
+ * | V5 | 解析命中 | 从 **profile 目录** `require.resolve('@deepseek-ai/dsh-base')` ⇒ 落在目标农场内，且版本 == 目标 scope 的 `dsh-base` |
+ * 任一条不绿 ⇒ 执行失败 ⇒ **自动回滚到备份**并**非零退出**；回滚自身也要自证（V1 + 目标回到原 scope）。
+ *
+ * ## 安全红线（拒绝执行，而不是"尽力而为"）
+ * · 目标 scope 三种布局都探不到探针包 / 包集合为空 ⇒ **拒绝**（dry-run 也拒绝：计划无从谈起）。
+ * · 农场里有**真目录/真文件**挡在目标包名上（`目录式`农场）⇒ **拒绝**并给手工出路
+ *   （⛔ 不递归删、⛔ 不 rm -rf：删一个真目录 = 丢数据，不在本工具职责内）。
+ * · 任一农场/备份目录落在 `--dsh-home` **之外** ⇒ 拒绝（防"临时 home 演练写进真实 home"）。
+ * · 已同源（集合与目标一致且逐条命中）⇒ **零动作、零写入**（连备份目录都不建），打印「已同源，跳过」。
+ */
+
+import { createHash } from 'node:crypto'
+import {
+  existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync,
+  realpathSync, symlinkSync, unlinkSync, writeFileSync,
+} from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+
+import { listFarmPackages, locateScopeFarm, readPackageVersion, SCOPE_PROBE_PKGS } from './lib/bootcheck-wiring.mjs'
+import { resolveDataDir } from '../core/lib/argent-datadir.mjs'
+
+export const TOOL = 'scripts/dsh-scope-rewire.mjs'
+/** 备份格式版本（备份文件是**回滚的唯一依据**，格式变了必须能认出来）。 */
+export const BACKUP_FORMAT = 1
+/** 探测包：判 V5「解析命中」用（与 bootcheck 同一份清单，⛔ 不另写）。 */
+export const PROBE_PKG = 'dsh-base'
+
+// ── 小工具 ──────────────────────────────────────────────────────────────────
+
+/** lstat 类型（**不跟随**软链：这正是备份要记的"条目真身"）。 */
+export function lstatKind(p) {
+  try {
+    const s = lstatSync(p)
+    return s.isSymbolicLink() ? 'symlink' : s.isDirectory() ? 'dir' : 'file'
+  } catch { return 'missing' }
+}
+
+const realOrNull = (p) => { try { return realpathSync(p) } catch { return null } }
+
+/**
+ * `p` 是否在 `root` 之内。
+ *
+ * ⚠️ 有两种比法，**用错会假红/假绿**（本工具实测第一版就假红过）：
+ * · `follow:false`（**词法**，默认）—— 农场路径必须用它：农场**本身就是一条软链**，
+ *   它的 realpath 天然在 dsh-home **之外**（指向全局 scope），拿 realpath 比会把
+ *   `profiles/web/node_modules/@deepseek-ai` 判成"越界"⇒ 正确动作被拒。判的是"条目挂在哪"。
+ * · `follow:true`（**取最深的已存在祖先再 realpath**）—— 写目标（备份目录）用它：路径可能还不存在，
+ *   但要防"父级是软链、实际写到别处"（`~/.dsh/argent -> /elsewhere`）⇒ 判的是"字节落在哪"。
+ */
+export function isInside(p, root, { follow = false } = {}) {
+  const r = resolve(root)
+  const a = resolve(p)
+  if (!follow) return a === r || a.startsWith(r + '/')
+  let probe = a
+  while (probe !== dirname(probe) && !existsSync(probe)) probe = dirname(probe)
+  const pr = realOrNull(probe) || probe
+  const rr = realOrNull(r) || r
+  return pr === rr || pr.startsWith(rr + '/')
+}
+
+/** 取一个尚未被占用的目录名（`base`、`base-2`、`base-3`…）—— 备份**绝不覆盖**既有备份。 */
+export function uniqueDir(base) {
+  if (!existsSync(base)) return base
+  for (let i = 2; i < 1000; i++) {
+    const c = `${base}-${i}`
+    if (!existsSync(c)) return c
+  }
+  throw new Error(`备份目录名连续 1000 个都被占用：${base}`)
+}
+
+/** shell 单引号安全引用（回滚命令要能**原样粘贴执行**）。 */
+export function shq(s) {
+  return `'${String(s).replace(/'/g, "'\\''")}'`
+}
+
+const sha256 = (text) => createHash('sha256').update(text).digest('hex')
+
+/** 输出通道：`--json` 时 stdout 只留 JSON（人读文案转 stderr）。 */
+function makeOut(json) {
+  return {
+    say: (...a) => { if (!json) console.log(...a); else console.error(...a) },
+    warn: (...a) => console.error(...a),
+  }
+}
+
+// ── 目标 scope 探测 ─────────────────────────────────────────────────────────
+
+/**
+ * 探测目标 scope（**只读**）。布局判据薄委托 `locateScopeFarm`（与 bootcheck 同一份）。
+ * @returns {{ok:boolean, scopeDir:string, farm:string|null, layout:string|null, probe:string|null,
+ *            packages:string[], packageCount:number, dshVersion:string|null, dshBaseVersion:string|null, reason:string|null}}
+ */
+export function probeTargetScope(scopeDir) {
+  const base = {
+    ok: false, scopeDir, farm: null, layout: null, probe: null,
+    packages: [], packageCount: 0, dshVersion: null, dshBaseVersion: null, reason: null,
+  }
+  if (!scopeDir) return { ...base, reason: '未给 --target-scope' }
+  if (!existsSync(scopeDir)) return { ...base, reason: `目标 scope 不存在：${scopeDir}` }
+  const found = locateScopeFarm(scopeDir)
+  if (!found) {
+    return { ...base, reason: `目标 scope 里三种布局（平铺/前缀式/嵌套）都探不到 ${SCOPE_PROBE_PKGS.join(' / ')} 的 package.json ⇒ 不可用：${scopeDir}` }
+  }
+  const packages = listFarmPackages(found.farm)
+  if (packages.length === 0) return { ...base, farm: found.farm, layout: found.layout, reason: `目标 scope 农场为空（0 个包）：${found.farm}` }
+  return {
+    ...base,
+    ok: true,
+    farm: realOrNull(found.farm) || found.farm,
+    layout: found.layout,
+    probe: found.probe,
+    packages,
+    packageCount: packages.length,
+    dshVersion: readPackageVersion(join(found.farm, 'dsh')),
+    dshBaseVersion: readPackageVersion(join(found.farm, PROBE_PKG)),
+  }
+}
+
+// ── 农场快照（改线前 / 改线后 / 回滚后都用它，所以"逐条一致"可机器比对）────────
+
+/**
+ * 快照一个农场（**只读**，不跟随软链）。
+ * @returns {{farm:string, kind:'symlink'|'dir'|'missing', linkTarget:string|null, real:string|null,
+ *            entries:Array<{name:string, kind:string, readlink:string|null, resolves:boolean, real:string|null, dot:boolean}>}}
+ */
+export function snapshotFarm(farmPath) {
+  const kind = lstatKind(farmPath)
+  const out = { farm: farmPath, kind, linkTarget: null, real: realOrNull(farmPath), entries: [] }
+  if (kind === 'missing') return out
+  if (kind === 'symlink') {
+    out.linkTarget = (() => { try { return readlinkSync(farmPath) } catch { return null } })()
+    out.entries = [{ name: '.', kind: 'symlink', readlink: out.linkTarget, resolves: existsSync(farmPath), real: out.real, dot: false }]
+    return out
+  }
+  for (const name of readdirSync(farmPath).sort()) {
+    const p = join(farmPath, name)
+    const k = lstatKind(p)
+    const readlink = k === 'symlink' ? (() => { try { return readlinkSync(p) } catch { return null } })() : null
+    out.entries.push({ name, kind: k, readlink, resolves: existsSync(p), real: realOrNull(p), dot: name.startsWith('.') })
+  }
+  return out
+}
+
+/** 断链条目（lstat 软链 ∧ 目标不存在）—— 判据 V1 的输入。 */
+export function brokenEntries(snap) {
+  if (snap.kind === 'symlink') return snap.entries.filter((e) => e.kind === 'symlink' && !e.resolves).map((e) => e.name === '.' ? `${snap.farm}（整树软链）` : e.name)
+  return snap.entries.filter((e) => e.kind === 'symlink' && !e.resolves).map((e) => e.name)
+}
+
+/** 备份条目里的断链数（回滚自证的**基准**：改线前既存的死链也必须原样回来）。 */
+export function brokenCountOf(entries) {
+  return entries.filter((e) => e.kind === 'symlink' && e.resolves === false).length
+}
+
+/** 现役目标分布（逐条 readlink 的**父目录**计数）—— dry-run 计划里给人看的"现在指向谁"。 */
+export function targetDistribution(snap) {
+  const dist = new Map()
+  for (const e of snap.entries) {
+    if (e.kind !== 'symlink' || !e.readlink) continue
+    const parent = e.readlink.endsWith('/') ? e.readlink.slice(0, -1) : dirname(e.readlink)
+    dist.set(parent, (dist.get(parent) || 0) + 1)
+  }
+  return [...dist.entries()].map(([dir, count]) => ({ dir, count })).sort((a, b) => b.count - a.count)
+}
+
+// ── 改线计划（**纯数据，不落盘**）──────────────────────────────────────────
+
+/**
+ * 生成一个农场的改线计划（纯函数：只读快照 + 目标探测 ⇒ 动作清单）。
+ * @returns {{farm:string, kind:string, sameSource:boolean, actions:Array, blockers:string[],
+ *            counts:{relink:number,create:number,remove:number,skip:number}, brokenBefore:string[],
+ *            staleBefore:string[], dotKept:string[]}}
+ */
+export function planFarmRewire(snap, target) {
+  const actions = []
+  const blockers = []
+  const dotKept = snap.entries.filter((e) => e.dot).map((e) => e.name)
+  const targetSet = new Set(target.packages)
+  const targetReal = target.farm
+
+  // 形态①：整树软链 —— 动作 = 换掉这**一个**软链（同源则零动作）
+  if (snap.kind === 'symlink' || snap.kind === 'missing') {
+    const sameSource = snap.kind === 'symlink' && snap.real === targetReal
+    if (!sameSource) {
+      actions.push({ op: 'relink-scope', at: snap.farm, from: snap.linkTarget, to: targetReal })
+    }
+    return {
+      farm: snap.farm, kind: snap.kind, sameSource, actions, blockers,
+      counts: { relink: actions.length, create: 0, remove: 0, skip: sameSource ? 1 : 0 },
+      brokenBefore: brokenEntries(snap), staleBefore: [], dotKept,
+      entryCount: snap.entries.length,
+    }
+  }
+
+  // 形态②：真目录 + 逐包条目
+  const have = new Map(snap.entries.filter((e) => !e.dot).map((e) => [e.name, e]))
+  const stale = [] // 农场有、目标没有 ⇒ 该清（仅清**软链**）
+  for (const [name, e] of have) {
+    if (targetSet.has(name)) continue
+    if (e.kind === 'symlink') { stale.push(name); actions.push({ op: 'remove', entry: name, at: join(snap.farm, name), was: e.readlink }) }
+    else {
+      blockers.push(`${join(snap.farm, name)} 是真 ${e.kind === 'dir' ? '目录' : '文件'}，且不在目标 scope 的包集合里 —— ⛔ 本工具不删真目录/真文件（那会丢数据）；请人工确认后移走`)
+    }
+  }
+  let relink = 0; let create = 0; let skip = 0
+  for (const pkg of target.packages) {
+    const e = have.get(pkg)
+    const to = join(targetReal, pkg)
+    if (!e) { create++; actions.push({ op: 'create', entry: pkg, at: join(snap.farm, pkg), to }); continue }
+    if (e.kind === 'symlink' && e.real === realOrNull(to)) { skip++; continue }
+    if (e.kind === 'symlink') { relink++; actions.push({ op: 'relink', entry: pkg, at: join(snap.farm, pkg), from: e.readlink, to }); continue }
+    blockers.push(`${join(snap.farm, pkg)} 是真 ${e.kind === 'dir' ? '目录' : '文件'}（**目录式**农场）—— ⛔ 本工具不删真目录（会丢数据）；请人工确认后移走，或改用 --target-scope 之外的迁法`)
+  }
+  const sameSource = blockers.length === 0 && stale.length === 0 && relink === 0 && create === 0
+  return {
+    farm: snap.farm, kind: snap.kind, sameSource, actions, blockers,
+    counts: { relink, create, remove: stale.length, skip },
+    brokenBefore: brokenEntries(snap), staleBefore: stale, dotKept,
+    entryCount: snap.entries.length,
+  }
+}
+
+// ── 落盘：备份 / 改线 / 回滚 ────────────────────────────────────────────────
+
+/** 备份一个农场：写 JSON + **读回自证**（条数与逐条 `name/kind/readlink` 一致）。 */
+function backupFarm(backupDir, slug, profileName, shared, snap, target) {
+  mkdirSync(backupDir, { recursive: true })
+  const file = join(backupDir, `${slug}.json`)
+  const doc = {
+    format: BACKUP_FORMAT,
+    takenAt: new Date().toISOString(),
+    profile: profileName,
+    shared: !!shared,
+    farm: snap.farm,
+    kind: snap.kind,
+    linkTarget: snap.linkTarget,
+    entryCount: snap.entries.length,
+    targetScope: target.farm,
+    targetDshVersion: target.dshVersion,
+    entries: snap.entries.map((e) => ({ name: e.name, kind: e.kind, readlink: e.readlink, resolves: e.resolves })),
+  }
+  const text = `${JSON.stringify(doc, null, 2)}\n`
+  writeFileSync(file, text)
+  // —— 读回自证（⛔ 不信任"写成功"）——
+  const readBack = JSON.parse(readFileSync(file, 'utf8'))
+  const same = readBack.entryCount === doc.entryCount
+    && readBack.entries.length === doc.entries.length
+    && doc.entries.every((e, i) => {
+      const b = readBack.entries[i]
+      return b.name === e.name && b.kind === e.kind && b.readlink === e.readlink
+    })
+  if (!same) throw new Error(`备份读回不一致：${file}（写入 ${doc.entryCount} 条，读回 ${readBack.entryCount} 条）`)
+  return { file, doc, sha256: sha256(text), entryCount: doc.entryCount }
+}
+
+/** 落盘改线计划（只做计划里的动作；真实 fs）。 */
+export function applyFarmRewire(plan) {
+  const done = []
+  if (plan.kind === 'symlink' || plan.kind === 'missing') {
+    for (const a of plan.actions) {
+      if (a.op !== 'relink-scope') continue
+      if (lstatKind(a.at) === 'symlink') unlinkSync(a.at)
+      else if (existsSync(a.at)) throw new Error(`拒绝覆盖非软链条目：${a.at}（这是真目录/真文件）`)
+      mkdirSync(dirname(a.at), { recursive: true })
+      symlinkSync(a.to, a.at)
+      done.push(a)
+    }
+    return done
+  }
+  if (!existsSync(plan.farm)) mkdirSync(plan.farm, { recursive: true })
+  for (const a of plan.actions) {
+    if (a.op === 'remove') {
+      if (lstatKind(a.at) === 'symlink') { unlinkSync(a.at); done.push(a) }
+      continue
+    }
+    if (a.op === 'relink' || a.op === 'create') {
+      const k = lstatKind(a.at)
+      if (k === 'symlink') unlinkSync(a.at)
+      else if (k !== 'missing') throw new Error(`拒绝覆盖非软链条目：${a.at}（这是真 ${k}）`)
+      symlinkSync(a.to, a.at)
+      done.push(a)
+    }
+  }
+  return done
+}
+
+/** 从备份恢复一个农场（**逐条按记录的 readlink 字面恢复**，不重新推导）。 */
+export function rollbackFarm(backupDoc) {
+  const { farm, kind, linkTarget, entries } = backupDoc
+  const done = []
+  if (kind === 'missing') return done
+  if (kind === 'symlink') {
+    const k = lstatKind(farm)
+    if (k === 'symlink') unlinkSync(farm)
+    else if (k !== 'missing') throw new Error(`回滚拒绝覆盖非软链条目：${farm}（这是真 ${k}）`)
+    mkdirSync(dirname(farm), { recursive: true })
+    symlinkSync(linkTarget, farm)
+    return [{ op: 'restore-scope-link', at: farm, to: linkTarget }]
+  }
+  // 真目录农场：先清掉**我们自己造出来的**软链条目，再按记录重建
+  if (!existsSync(farm)) mkdirSync(farm, { recursive: true })
+  for (const name of readdirSync(farm)) {
+    const p = join(farm, name)
+    const k = lstatKind(p)
+    if (k === 'symlink') { unlinkSync(p); done.push({ op: 'clear', at: p }) }
+  }
+  for (const e of entries) {
+    if (e.name === '.' || e.kind !== 'symlink') continue // 真目录/真文件本工具从不删 ⇒ 仍在原地
+    symlinkSync(e.readlink, join(farm, e.name))
+    done.push({ op: 'restore', at: join(farm, e.name), to: e.readlink })
+  }
+  return done
+}
+
+// ── 校验（判据 V1–V5）──────────────────────────────────────────────────────
+
+/** 快照 ↔ 备份**逐条一致**（回滚自证；含 lstat 类型与 readlink 字面）。 */
+export function entriesIdentical(snap, backupEntries) {
+  const a = snap.entries.map((e) => ({ name: e.name, kind: e.kind, readlink: e.readlink }))
+  const b = backupEntries.map((e) => ({ name: e.name, kind: e.kind, readlink: e.readlink }))
+  if (a.length !== b.length) return { ok: false, why: `条数不同：回滚后 ${a.length} / 备份 ${b.length}` }
+  for (let i = 0; i < a.length; i++) {
+    if (a[i].name !== b[i].name || a[i].kind !== b[i].kind || a[i].readlink !== b[i].readlink) {
+      return { ok: false, why: `第 ${i + 1} 条不同：回滚后 ${JSON.stringify(a[i])} / 备份 ${JSON.stringify(b[i])}` }
+    }
+  }
+  return { ok: true, why: `逐条一致（${a.length}/${b.length}）` }
+}
+
+/**
+ * 农场级判据 V1–V4（V5 是 profile 级的，见 {@link verifyProfileResolution}）。
+ * @returns {{ok:boolean, checks:Array<{id:string, ok:boolean, detail:string}>}}
+ */
+export function verifyFarm(farmPath, target) {
+  const snap = snapshotFarm(farmPath)
+  const checks = []
+  const push = (id, ok, detail) => checks.push({ id, ok, detail })
+
+  const broken = brokenEntries(snap)
+  push('V1', broken.length === 0, broken.length === 0 ? '零断链' : `${broken.length} 条断链：${broken.slice(0, 8).join(', ')}`)
+
+  const dotEntries = snap.entries.filter((e) => e.dot)
+  const list = snap.kind === 'symlink' ? [] : snap.entries.filter((e) => !e.dot)
+  // ⚠️ **整树软链**农场的"条目集合"不是那条软链自己（只有 1 个 `.`），而是**透过它可见的包集合**
+  //    —— 本工具第一版在这里判错过（把 `['.']` 与目标包集合比 ⇒ 正确动作被自己的校验打红）。
+  const names = snap.kind === 'symlink' ? listFarmPackages(farmPath) : list.map((e) => e.name)
+  const targetSet = new Set(target.packages)
+
+  // V2：目标 scope 的每一个包，在农场里都可解析且 realpath 落在目标农场内
+  const missPkg = []
+  for (const pkg of target.packages) {
+    const p = join(farmPath, pkg)
+    if (!existsSync(p)) { missPkg.push(pkg); continue }
+    const r = realOrNull(p)
+    if (!(r === target.farm || (r || '').startsWith(target.farm + '/'))) missPkg.push(`${pkg}(⇒${r})`)
+  }
+  push('V2', missPkg.length === 0, missPkg.length === 0
+    ? `目标 scope 的 ${target.packages.length} 个包逐个可解析且落在目标农场内`
+    : `${missPkg.length}/${target.packages.length} 个包没落到目标农场：${missPkg.slice(0, 8).join(', ')}`)
+
+  // V3：无外指软链
+  const outside = []
+  for (const e of list) {
+    if (e.kind !== 'symlink' || !e.readlink) continue
+    const r = realOrNull(join(farmPath, e.name))
+    if (!(r === target.farm || (r || '').startsWith(target.farm + '/'))) outside.push(`${e.name} ⇒ ${r}`)
+  }
+  push('V3', outside.length === 0, outside.length === 0 ? '无指向目标农场之外的软链' : `${outside.length} 条外指：${outside.slice(0, 8).join(', ')}`)
+
+  // V4：集合一致（非点条目 == 目标包集合）—— ⛔ 用判据，不硬编码包数
+  const onlyFarm = names.filter((n) => !targetSet.has(n))
+  const onlyTarget = target.packages.filter((n) => !names.includes(n))
+  const setOk = onlyFarm.length === 0 && onlyTarget.length === 0
+  push('V4', setOk, setOk
+    ? `农场条目集合 == 目标 scope 包集合（${names.length} 个${dotEntries.length ? `；另有 ${dotEntries.length} 个点条目原样保留` : ''}）`
+    : `集合不一致 ⇒ 农场多 ${onlyFarm.length} 个（${onlyFarm.slice(0, 6).join(', ')}）、少 ${onlyTarget.length} 个（${onlyTarget.slice(0, 6).join(', ')}）`)
+
+  return { ok: checks.every((c) => c.ok), checks, snap }
+}
+
+/**
+ * profile 级判据 V5：从**该 profile 目录**解析 `@deepseek-ai/dsh-base` ⇒ 必须落在目标农场内，
+ * 且版本 == 目标 scope 的那份（这就是审计 §C.2 A.2 的判据②）。
+ */
+export function verifyProfileResolution(profileDir, target) {
+  let resolved = null
+  let why = ''
+  try {
+    const req = createRequire(join(profileDir, '__scope_rewire_probe__.cjs'))
+    resolved = realOrNull(req.resolve(`@deepseek-ai/${PROBE_PKG}`))
+  } catch (e) {
+    why = `解析失败：${e && e.code ? e.code : e && e.message}`
+  }
+  if (!resolved) return { ok: false, resolved: null, version: null, why: why || '解析不到' }
+  const inTarget = resolved === target.farm || resolved.startsWith(target.farm + '/')
+  const version = readPackageVersion(dirname(dirname(resolved))) || readPackageVersion(join(target.farm, PROBE_PKG))
+  const verOk = !target.dshBaseVersion || version === target.dshBaseVersion
+  return {
+    ok: inTarget && verOk,
+    resolved,
+    version,
+    why: inTarget
+      ? `@deepseek-ai/${PROBE_PKG} ⇒ ${resolved}（在目标 scope 内；版本 ${version}${verOk ? ' == 目标' : ` ≠ 目标 ${target.dshBaseVersion}`}）`
+      : `@deepseek-ai/${PROBE_PKG} ⇒ ${resolved}，**不在**目标 scope ${target.farm} 内 ⇒ 农场未接好`,
+  }
+}
+
+// ── 农场发现 ────────────────────────────────────────────────────────────────
+
+/** 列 `<dshHome>/profiles` 下的 profile 目录名（**只读**）。 */
+export function listProfiles(dshHome) {
+  const pdir = join(dshHome, 'profiles')
+  if (!existsSync(pdir)) return []
+  return readdirSync(pdir).filter((n) => {
+    if (n === 'node_modules' || n.startsWith('.')) return false
+    try { return lstatSync(join(pdir, n)).isDirectory() } catch { return false }
+  }).sort()
+}
+
+/**
+ * 发现要改线的农场。**共享农场**（`profiles/node_modules/@deepseek-ai`）默认一起改：
+ * 没有自有农场的 profile（headless/tui…）沿 node 解析向上走到它，只改自有农场等于没改。
+ */
+export function discoverFarms({ dshHome, profile, allProfiles, includeShared = true }) {
+  const farms = []
+  const profiles = allProfiles ? listProfiles(dshHome) : [profile]
+  const seen = new Set()
+  const add = (f) => { if (!f.farm || seen.has(f.farm)) return; seen.add(f.farm); farms.push(f) }
+  for (const p of profiles) {
+    add({ profile: p, farm: join(dshHome, 'profiles', p, 'node_modules', '@deepseek-ai'), shared: false })
+  }
+  const sharedFarm = join(dshHome, 'profiles', 'node_modules', '@deepseek-ai')
+  if (includeShared && (existsSync(sharedFarm) || lstatKind(sharedFarm) === 'symlink')) {
+    add({ profile: allProfiles ? '(all)' : profiles[0], farm: sharedFarm, shared: true })
+  }
+  // 只留"农场真的存在"的（不存在的自有农场：报"走共享农场"，不建）
+  return farms.map((f) => ({ ...f, exists: existsSync(f.farm) || lstatKind(f.farm) === 'symlink' }))
+}
+
+// ── 命令行 ──────────────────────────────────────────────────────────────────
+
+export function parseArgs(argv) {
+  const has = (f) => argv.includes(f)
+  const val = (f) => { const i = argv.indexOf(f); return i > -1 ? argv[i + 1] ?? null : null }
+  const o = {
+    profile: val('--profile') || 'web',
+    allProfiles: has('--all-profiles'),
+    targetScope: val('--target-scope'),
+    dshHome: val('--dsh-home'),
+    apply: has('--apply'),
+    yes: has('--yes'),
+    backupDir: val('--backup-dir'),
+    includeShared: !has('--no-shared'),
+    rollback: val('--rollback'),
+    json: has('--json'),
+    help: has('--help') || has('-h'),
+  }
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+$/, '').replace('T', '-')
+  o.timestamp = stamp
+  return o
+}
+
+const USAGE = `用法：
+  node ${TOOL} --profile web --target-scope <…/@deepseek-ai>            # dry-run（默认，只打印计划）
+  node ${TOOL} --profile web --target-scope <…> --apply --yes           # 真写（缺 --yes ⇒ 拒绝）
+  node ${TOOL} --all-profiles --target-scope <…> [--apply --yes]
+  node ${TOOL} --rollback <备份目录> [--apply --yes]
+选项：--dsh-home <path>（默认 ~/.dsh）｜--backup-dir <path>｜--no-shared｜--json`
+
+/** 主流程（可被测试 import 调用；返回 {exitCode, report}）。 */
+export function run(argv = process.argv.slice(2), { cwd = process.cwd() } = {}) {
+  const opts = parseArgs(argv)
+  const out = makeOut(opts.json)
+  const report = { tool: TOOL, mode: null, ok: false, refusals: [], warnings: [] }
+  const refuse = (msg, code = 2) => {
+    report.refusals.push(msg)
+    report.ok = false
+    out.warn(`  ✗ 拒绝执行：${msg}`)
+    if (opts.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+    return { exitCode: code, report }
+  }
+
+  if (opts.help) { console.log(USAGE); return { exitCode: 0, report: { ...report, ok: true, help: true } } }
+
+  // ── dsh-home + 数据目录（⛔ 延迟求值：`--dsh-home` 解析**之后**才算路径）──────
+  const dshHome = opts.dshHome ? resolve(opts.dshHome) : join(homedir(), '.dsh')
+  report.dshHome = dshHome
+  if (!existsSync(dshHome)) return refuse(`--dsh-home 不存在：${dshHome}`)
+
+  const env = { ...process.env }
+  if (opts.dshHome) env.DSH_HOME = dshHome  // 让备份默认落点跟着**隔离 home** 走（内核唯一判据）
+  const dataDir = resolveDataDir({ env, home: dshHome }).dir
+  // ⚠️ 默认备份目录必须**唯一**：秒级时间戳在同一秒内跑两次会撞，而"⛔ 不覆盖既有备份"的守卫
+  //    会把第二次运行直接拒掉（实测踩到：回滚后立刻重跑改线 ⇒ exit 1）。⇒ 在**计划期**就取一个空位，
+  //    这样打印出来的回滚命令与实际落点始终一致。
+  const backupDir = opts.backupDir
+    ? resolve(opts.backupDir)
+    : uniqueDir(join(dataDir, 'backup', `scope-rewire-${opts.timestamp}`))
+  report.dataDir = dataDir
+  report.backupDir = backupDir
+
+  // 隔离红线：`--dsh-home` 是隔离 home 时，备份**不得**落到它外面（取 realpath 比：防父级软链绕出去）
+  if (opts.dshHome && !isInside(backupDir, dshHome, { follow: true })) {
+    return refuse(`备份目录 ${backupDir} 落在 --dsh-home（${dshHome}）之外 ⇒ 违反隔离；请显式给 --backup-dir，或清掉 ARGENT_DATA_DIR`)
+  }
+
+  // ══ 回滚模式 ═════════════════════════════════════════════════════════════
+  if (opts.rollback) {
+    report.mode = 'rollback'
+    const dir = resolve(opts.rollback)
+    const manifestPath = join(dir, 'manifest.json')
+    if (!existsSync(manifestPath)) return refuse(`回滚需要 ${manifestPath}（本工具的备份目录里有它）`)
+    let manifest
+    try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) } catch (e) { return refuse(`manifest 解析失败：${e.message}`) }
+    if (manifest.format !== BACKUP_FORMAT) return refuse(`备份格式版本不符（清单 ${manifest.format} / 本工具 ${BACKUP_FORMAT}）`)
+    report.rollback = { backupDir: dir, farms: manifest.farms }
+    out.say(`\n══ 回滚：${dir} ══`)
+    out.say(`  备份时间：${manifest.takenAt}｜源 dsh-home：${manifest.dshHome}｜改线目标：${manifest.targetScope || '(未知)'}`)
+    if (!opts.apply) {
+      out.say('  ⓘ dry-run（未给 --apply）：下面只列将恢复的农场，一个字节都不写')
+      for (const f of manifest.farms) out.say(`    · ${f.farm}（${f.entryCount} 条，${f.kind}）`)
+      report.ok = true
+      report.planOnly = true
+      if (opts.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+      return { exitCode: 0, report }
+    }
+    if (!opts.yes) return refuse('回滚要真写 ⇒ 必须同时给 --apply 与 --yes（缺 --yes 一律不写）')
+    const results = []
+    for (const f of manifest.farms) {
+      const doc = JSON.parse(readFileSync(f.backupFile, 'utf8'))
+      out.say(`\n── 恢复 ${f.farm}`)
+      try { rollbackFarm(doc) } catch (e) { return refuse(`回滚失败（${f.farm}）：${e.message}`, 1) }
+      const snap = snapshotFarm(f.farm)
+      const ident = entriesIdentical(snap, doc.entries)
+      const broken = brokenEntries(snap)
+      const brokenBefore = brokenCountOf(doc.entries)
+      const brokenOk = broken.length === brokenBefore
+      const ok = ident.ok && brokenOk
+      const note = brokenBefore === 0
+        ? '0 断链 ✅'
+        : `断链数 ${broken.length} == 改线前既存的 ${brokenBefore} 条 ${brokenOk ? '✅（历史死链，回滚**原样**保留才是对的）' : '❌'}`
+      out.say(`   ${ok ? '✅' : '❌'} 回滚自证：${ident.why}｜${note}`)
+      results.push({ farm: f.farm, ok, identical: ident, broken, brokenBefore })
+      if (!ok) { report.ok = false; report.rollbackResults = results; return { exitCode: 1, report } }
+    }
+    report.ok = true
+    report.rollbackResults = results
+    out.say('\n✅ 回滚完成且自证通过（**逐条回到备份** + 断链数与改线前一致）')
+    if (opts.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+    return { exitCode: 0, report }
+  }
+
+  // ══ 改线模式 ═════════════════════════════════════════════════════════════
+  report.mode = opts.apply ? 'apply' : 'dry-run'
+  if (!opts.targetScope) return refuse('改线必须给 --target-scope <…/@deepseek-ai>（⛔ 本工具不自动探测目标 scope）')
+  const target = probeTargetScope(resolve(opts.targetScope))
+  report.target = target
+  if (!target.ok) return refuse(target.reason)
+  if (!existsSync(join(dshHome, 'profiles'))) return refuse(`${dshHome} 下没有 profiles/ 目录 ⇒ 不是 dsh home？`)
+
+  const farms = discoverFarms({ dshHome, profile: opts.profile, allProfiles: opts.allProfiles, includeShared: opts.includeShared })
+  if (farms.length === 0) return refuse('没有发现任何农场（profiles/*/node_modules/@deepseek-ai）')
+  for (const f of farms) {
+    if (!isInside(f.farm, dshHome)) return refuse(`农场 ${f.farm} 落在 --dsh-home（${dshHome}）之外 ⇒ 拒绝`)
+  }
+
+  out.say('\n══ dsh scope 改线计划 ══')
+  out.say(`  模式：${opts.apply ? 'apply（真写）' : 'dry-run（只打印，不写）'}`)
+  out.say(`  dsh-home：${dshHome}${opts.dshHome ? '' : '（真实 home）'}`)
+  out.say(`  目标 scope：${target.farm}`)
+  out.say(`    · 布局=${target.layout}｜探针=${target.probe}｜包数=${target.packageCount}｜dsh=${target.dshVersion}｜dsh-base=${target.dshBaseVersion}`)
+
+  const plans = []
+  for (const f of farms) {
+    const snap = snapshotFarm(f.farm)
+    const plan = planFarmRewire(snap, target)
+    plan.profile = f.profile
+    plan.shared = f.shared
+    plan.exists = f.exists
+    plan.dist = targetDistribution(snap)
+    plan.brokenBefore = brokenEntries(snap)
+    plans.push(plan)
+    out.say(`\n── 农场（${f.shared ? '父级共享' : `profile=${f.profile}`}）：${f.farm}`)
+    if (!f.exists) { out.say('   ⓘ 不存在 ⇒ 该 profile 走父级共享农场，本农场不新建'); continue }
+    out.say(`   形态：${plan.kind === 'symlink' ? '整树软链（dir-link）' : plan.kind === 'dir' ? '逐包软链（per-pkg）' : '缺失'}`)
+    out.say(`   现有链接数：${snap.entries.length}`)
+    if (plan.dist.length) {
+      out.say(`   现有目标分布（逐条 readlink 的父目录计数）：`)
+      for (const d of plan.dist) out.say(`     · ${d.dir}  ×${d.count}`)
+    }
+    out.say(`   断链数：${plan.brokenBefore.length}${plan.brokenBefore.length ? ` ⇒ ${plan.brokenBefore.slice(0, 8).join(', ')}${plan.brokenBefore.length > 8 ? ' …' : ''}` : ''}`)
+    out.say(`   将改指 ${plan.counts.relink} 条 / 新建 ${plan.counts.create} 条 / 删除 ${plan.counts.remove} 条 / 已同源跳过 ${plan.counts.skip} 条`)
+    if (plan.dotKept.length) out.say(`   点条目原样保留（${plan.dotKept.length}）：${plan.dotKept.slice(0, 6).join(', ')}`)
+    if (plan.sameSource) out.say('   ✅ 已同源，跳过（零动作、零写入）')
+    for (const b of plan.blockers) out.say(`   ⛔ 阻断：${b}`)
+  }
+
+  const blockers = plans.flatMap((p) => p.blockers)
+  const writeFarms = plans.filter((p) => p.exists && !p.sameSource)
+  const totalActions = writeFarms.reduce((n, p) => n + p.actions.length, 0)
+
+  report.plans = plans.map((p) => ({
+    profile: p.profile, shared: p.shared, farm: p.farm, kind: p.kind, sameSource: p.sameSource,
+    entries: p.entries ?? undefined, counts: p.counts, brokenBefore: p.brokenBefore,
+    dist: p.dist, blockers: p.blockers, actions: p.actions,
+    entryCount: p.entryCount,
+  }))
+  report.totalActions = totalActions
+
+  const rollbackCommand = (dir) => `node ${TOOL} --dsh-home ${shq(dshHome)} --rollback ${shq(dir)} --apply --yes`
+  if (totalActions === 0) {
+    out.say('\n✅ 全部农场已同源 ⇒ **零动作、零写入**（不建备份目录）')
+    report.rollbackCommand = null
+    report.rollbackNote = '零动作 ⇒ 无需回滚'
+  } else {
+    out.say(`\n  备份目录：${backupDir}`)
+    out.say(`  回滚命令（原文，出事后原样粘贴执行）：`)
+    out.say(`    ${rollbackCommand(backupDir)}`)
+    report.rollbackCommand = rollbackCommand(backupDir)
+  }
+
+  if (blockers.length) {
+    report.ok = false
+    out.warn(`\n  ✗ 拒绝执行：有 ${blockers.length} 条阻断（真目录/真文件挡在目标包名上）—— 见上面逐条`)
+    if (opts.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+    return { exitCode: 2, report }
+  }
+
+  if (!opts.apply) {
+    out.say('\n  ⓘ dry-run 结束：一个字节都没写。真写请加 --apply --yes')
+    report.ok = true
+    if (opts.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+    return { exitCode: 0, report }
+  }
+  if (!opts.yes) {
+    return refuse('--apply 必须与 --yes 同时给（本工具默认不写；缺 --yes 一律不写）')
+  }
+  if (totalActions === 0) {
+    report.ok = true
+    if (opts.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+    return { exitCode: 0, report }
+  }
+
+  // ── 真写：① 备份（读回自证）→ ② 改线 → ③ 校验 → 任一步失败 ⇒ 自动回滚 ──────
+  out.say('\n══ 执行（备份 → 改线 → 校验）══')
+  const manifest = {
+    format: BACKUP_FORMAT, takenAt: new Date().toISOString(), dshHome, backupDir,
+    targetScope: target.farm, targetDshVersion: target.dshVersion, targetPackages: target.packageCount,
+    rollbackCommand: rollbackCommand(backupDir), farms: [],
+  }
+  const doRollback = (reason) => {
+    out.warn(`\n  ✗ ${reason} ⇒ 自动回滚`)
+    for (const f of manifest.farms) {
+      try {
+        const doc = JSON.parse(readFileSync(f.backupFile, 'utf8'))
+        rollbackFarm(doc)
+        const snap = snapshotFarm(f.farm)
+        const ident = entriesIdentical(snap, doc.entries)
+        const broken = brokenEntries(snap)
+        const brokenBefore = brokenCountOf(doc.entries)
+        const bOk = broken.length === brokenBefore
+        out.warn(`    · ${f.farm}：${ident.ok ? '逐条一致 ✅' : `❌ ${ident.why}`}｜断链数 ${broken.length} vs 改线前 ${brokenBefore}：${bOk ? '✅' : '❌'}`)
+      } catch (e) { out.warn(`    · ${f.farm}：回滚异常 ${e.message}`) }
+    }
+    report.ok = false
+    report.rollbackDone = true
+    if (opts.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+    return { exitCode: 1, report }
+  }
+
+  const verifyAll = () => {
+    const perFarm = []
+    const perProfile = []
+    for (const p of writeFarms) {
+      const v = verifyFarm(p.farm, target)
+      perFarm.push({ farm: p.farm, ok: v.ok, checks: v.checks })
+    }
+    for (const prof of (opts.allProfiles ? listProfiles(dshHome) : [opts.profile])) {
+      const dir = join(dshHome, 'profiles', prof)
+      if (!existsSync(dir)) continue
+      const v = verifyProfileResolution(dir, target)
+      perProfile.push({ profile: prof, ok: v.ok, why: v.why })
+    }
+    return { perFarm, perProfile, ok: perFarm.every((f) => f.ok) && perProfile.every((f) => f.ok) }
+  }
+
+  if (!opts.backupDir && existsSync(backupDir)) return refuse(`备份目录已存在（${backupDir}）⇒ 换个时间戳或显式 --backup-dir（⛔ 不覆盖既有备份）`, 1)
+  mkdirSync(backupDir, { recursive: true })
+  try {
+    for (const p of writeFarms) {
+      const snap = snapshotFarm(p.farm)
+      const slug = (p.shared ? 'shared' : `profile-${p.profile}`).replace(/[^A-Za-z0-9._-]/g, '_')
+      const b = backupFarm(backupDir, slug, p.profile, p.shared, snap, target)
+      out.say(`  ✅ 备份 ${p.farm} ⇒ ${b.file}（${b.entryCount} 条，读回自证一致，sha256=${b.sha256.slice(0, 16)}…）`)
+      manifest.farms.push({ profile: p.profile, shared: p.shared, farm: p.farm, kind: snap.kind, entryCount: b.entryCount, backupFile: b.file, sha256: b.sha256 })
+    }
+    writeFileSync(join(backupDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
+    out.say(`  ✅ 备份清单 ⇒ ${join(backupDir, 'manifest.json')}`)
+  } catch (e) {
+    return doRollback(`备份阶段失败：${e.message}`)
+  }
+
+  try {
+    for (const p of writeFarms) {
+      const done = applyFarmRewire(p)
+      out.say(`  ✅ 改线 ${p.farm}（${done.length} 个动作）`)
+    }
+  } catch (e) {
+    return doRollback(`改线阶段失败：${e.message}`)
+  }
+
+  const verdict = verifyAll()
+  report.verification = verdict
+  out.say('\n══ 写后校验 ══')
+  for (const f of verdict.perFarm) {
+    for (const c of f.checks) out.say(`  ${c.ok ? '✅' : '❌'} ${c.id} ${f.farm}\n       ${c.detail}`)
+  }
+  for (const p of verdict.perProfile) out.say(`  ${p.ok ? '✅' : '❌'} V5 profile=${p.profile}：${p.why}`)
+  if (!verdict.ok) return doRollback('写后校验未全绿')
+
+  report.ok = true
+  report.manifest = manifest
+  out.say('\n✅ 改线完成：判据 V1–V5 全绿。回滚命令见上（已写进备份清单）。')
+  out.say(`   回滚：${rollbackCommand(backupDir)}`)
+  if (opts.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  return { exitCode: 0, report }
+}
+
+// ── 直接执行 ────────────────────────────────────────────────────────────────
+const DIRECT = (() => {
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)) } catch { return false }
+})()
+if (DIRECT) {
+  const { exitCode } = run()
+  process.exit(exitCode)
+}