@deepseek-harness-tui/dsh-tui 0.8.6 → 0.8.7

package/README.md

@@ -88,6 +88,14 @@ sh install.sh
 
 `dsh-tui --resume` 恢复上次会话；Windows 也可用仓库里的 `dsh-tui.cmd`（等价）。
 
+### Herdr
+
+在 [Herdr](https://herdr.dev) pane 中直接运行 `dsh-tui` 即可，无需额外配置。
+dsh-TUI 会通过 Herdr 提供的本地接口上报 `idle`、`working`、`blocked` 状态；
+问卷或工具审批出现时标记为 `blocked`。离开 Herdr 运行时该集成完全不启用。
+Herdr 的 `agent start --kind dsh-tui`、session 身份与服务重启后自动恢复仍需 Herdr
+上游加入原生 agent kind；当前可正常保活、重连和观察手工启动的 pane。
+
 在 VS Code 中运行的完整指南（内置终端直接使用 + companion 扩展
 `dsh-tui-vscode`——**真实集成终端承载、体验与 Claude Code 官方扩展几乎一致、
 已上架 VS Code Marketplace**）见
@@ -122,7 +130,7 @@ npm install -g @deepseek-harness-tui/dsh-tui@<profile-version>
 | `Ctrl+R` | 历史消息搜索 |
 | `/` | 会话内全文搜索（`n`/`N` 跳转） |
 | `Ctrl+V` | 粘贴文本或文件管理器中的文件；图片显示为 `[Image #N]` 并作为持久附件发送 |
-| `Ctrl+X` | 用 `$VISUAL`/`$EDITOR`（如 nvim）打开当前输入编辑，保存退出后回填 |
+| `Ctrl+G` | 用 `$VISUAL`/`$EDITOR`（如 nvim）打开当前输入编辑，保存退出后回填 |
 | `?` | 快捷键菜单（仅输入框为空时响应） |
 | `Shift+↑` | 消息选择模式（Enter 展开单条） |
 | `Ctrl+P` | 切换启动时 loaded-context 面板（面板在屏时有效） |
@@ -145,7 +153,7 @@ macOS 自带 Terminal.app 会自行消费 `⌘` 快捷键，请继续使用 `Ctr
 |---|---|
 | 拖拽选择 | 应用内文本选区，**松开即复制**（OSC 52 + `wl-copy`/`xclip`/`xsel` 原生兜底；tmux 内走 `load-buffer -w`），复制后自动取消选区并弹出「已复制 N 个字符」提示 |
 | 双击 / 三击 | 选词 / 选行，同样即选即复制 |
-| 滚轮 | 滚动消息列表（±3 行/格） |
+| 滚轮 | 仅在 fullscreen 且鼠标跟踪启用时：Help 打开时滚动帮助，否则滚动消息列表（±3 行/格）；默认 inline 模式不会把滚轮事件交给 TUI |
 | `Esc` | 拖拽进行中取消选区（不复制） |
 | 单击消息行 | 展开/收起该行 |
 | 单击「加载更早消息」/「ctrl+e 显示前 N 条」 | 加载更早消息 / 展开全部 |
@@ -298,7 +306,9 @@ pnpm smoke
 ```
 
 `lib/types/` 是忽略入库的生成目录；`pnpm build` 会从干净输出目录重新编译并运行
-构建门禁。npm Git URL 安装通过 `prepare` 生成同一套运行时。渲染、问卷和工具卡
+构建门禁。**Git URL 安装不受支持**（源 manifest 的 `@dsh-std/*` 为 workspace 依赖、
+`vendor/dsh-std` 为子模块、且 pnpm ≥11 默认拒绝 git 依赖的 `prepare` 脚本）；请安装
+registry 包：`dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui`。渲染、问卷和工具卡
 改动还需运行对应回归脚本。
 
 

package/bin/dsh-tui.js

@@ -1,47 +1,103 @@
 #!/usr/bin/env node
 /**
- * dsh-tui — dsh-tui profile 的一键直达启动器。
+ * dsh-tui — 双态启动器（delegating launcher，0.8.7）。
  *
- * 全局安装 @deepseek-harness-tui/dsh-tui 后获得 `dsh-tui` 命令，免去手工
- * 输入 `dsh --profile dsh-tui`：
+ * 同一个文件按“自己住在哪”决定扮演的角色：
  *
- *   1. 检测 dsh CLI（缺失时提示安装 @deepseek-ai/dsh）；
- *   2. 检测 $DSH_HOME/profiles/dsh-tui 是否已初始化，未初始化则自动执行
- *      `dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui@<本包版本>`
- *      自举——版本号与本包对齐，避免 pnpm store 缓存带来的旧版漂移；
- *   3. 已初始化但版本与本包不一致时按方向处理（issue #183）：profile
- *      更新（前向错位）打印一行提示后继续启动（TUI 内 /update 或重新
- *      add）；profile 次版本更旧（反向错位）拒绝启动并给出对齐命令——
- *      该方向 dsh CLI 会把启动器的 bundle patch 套到 profile 旧包上，
- *      启动必然以模块解析错误崩溃；
- *   4. 透传全部参数启动 `dsh --profile dsh-tui`。
+ *   全局安装副本（npm i -g 得到的 `dsh-tui` 命令）→ 瘦壳：
+ *     1. 找到 $DSH_HOME/profiles/dsh-tui 里的同包 bin；
+ *     2. 可读 → 原样转发 argv 委托它执行（完整逻辑永远来自 profile 副本，
+ *        版本随 /update 一起前进，启动器滞后问题从结构上消失）；
+ *     3. 不可读（首次运行）→ 探测 dsh/pnpm 后自举
+ *        `dsh plugin --profile dsh-tui add <本包>@<本包版本>`，成功后委托。
  *
- * `--resume` 由本启动器拦截：读取 TUI 保留的 ~/.dsh-tui/resume.txt
- * （旧路径 ~/.dsh-cc/resume.txt 兜底，直到旧版 TUI 退场——见
- * src/sessionHistory.ts 的启动器契约，issue #120），以
- * DSH_TUI_RESUME_SESSION（并兼容写 DSH_CC_RESUME_SESSION）环境变量喂回，
- * 该 flag 本身不再传给 dsh。
+ *   profile 内副本（被委托执行，或 junction/源码目录里直接运行）→ 完整
+ *   启动逻辑（与 0.8.6 及之前一致）：
+ *     dsh 预检 / profile 版本核对 / --resume 与工作区目标拦截 /
+ *     旧环境变量警告 / `dsh --profile dsh-tui` 启动与退出码透传。
  *
- * 面向用户的消息走下方 MSG 双语表：与 TUI 的语言契约一致——
+ * 自举角色判定用 realpath：Windows Junction 轨（profile 指回仓库）与
+ * `pnpm run dev` 源码运行都会折叠成同一物理目录 → 走完整逻辑，不会
+ * 自己委托自己形成循环。
+ *
+ * 本文件必须保持零 lib/ 依赖：/update 的启动器迁移只覆写这一个文件
+ * （外加 package.json 的版本号），旧全局安装里不存在新 lib 助手时同样
+ * 可用。shellQuote 等小工具在此内联。
+ *
+ * 面向用户的消息走 MSG 双语表：与 TUI 的语言契约一致——
  * `DSH_TUI_LANG` 显式指定时从其值，否则默认中文（同 src/i18n.ts 的缺省）。
  */
 import { spawn, spawnSync } from 'node:child_process'
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { isAbsolute, join, resolve } from 'node:path'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { gt, valid } from 'semver'
-import { shellQuote } from '../lib/types/utils/shellQuote.js'
-import { detectLegacyEnv, RENAMED_ENV } from '../lib/types/utils/paths.js'
 
-const here = fileURLToPath(new URL('.', import.meta.url))
-const ownVersion = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8')).version
+const here = dirname(fileURLToPath(import.meta.url))
+const ownDir = dirname(here)
+const readJson = p => {
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'))
+  } catch {
+    return undefined
+  }
+}
+const ownPackage = readJson(join(ownDir, 'package.json'))
+const ownVersion = ownPackage?.name === '@deepseek-harness-tui/dsh-tui' ? ownPackage.version : undefined
 const PACKAGE = '@deepseek-harness-tui/dsh-tui'
 const PROFILE = 'dsh-tui'
 
-// --- 双语消息表（启动器跑在 TUI boot 之前，无法复用 src/i18n.ts）-------------
-// 与 TUI 一致：DSH_TUI_LANG 显式指定才生效，否则默认中文；旧名 CC_TUI_LANG
-// 仅用于让警告本身以用户习惯的语言显示（配置不再从旧名生效）。
+// --- 内联小工具（见文件头：零 lib 依赖是迁移契约的一部分）---------------------
+// 与 lib/types/utils/shellQuote.js 同语义的最小实现：cmd.exe 以空格拼接参数
+// 且不做转义，含空格/引号的参数必须整体加引号（内层引号与反斜杠转义）。
+const shellQuote = args =>
+  args.map(arg => {
+    const s = String(arg)
+    if (s === '') return '""'
+    if (!/[\s"^]/.test(s)) return s
+    return `"${s.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1')}"`
+  })
+const isWin = process.platform === 'win32'
+const shellOpt = isWin ? { shell: true } : {}
+// DEP0190（issue #148）：shell:true + 非空参数数组触发语法级弃用告警——
+// 转义后拼进命令字符串（空参数数组不触发），非 Windows 保持数组直传。
+const cmd = (command, args) =>
+  isWin ? [`${command} ${shellQuote(args).join(' ')}`, []] : [command, args]
+
+// 内联 semver（解析 + 严格大于）：启动器可能在依赖不完整的环境里被执行
+// （迁移、半损坏安装、测试沙箱），零外部依赖是自保底线。覆盖 semver 的
+// 核心-先行版比较规则：先行版标识符逐段比（数字段按数值、小于字母段），
+// 前缀相同时段数少者更旧，无先行版者最新。
+const parseVersion = v => {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(String(v).trim())
+  return m
+    ? { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), pre: m[4] === undefined ? null : m[4].split('.') }
+    : null
+}
+const isVersionNewer = (a, b) => {
+  const A = parseVersion(a)
+  const B = parseVersion(b)
+  if (A === null || B === null) return false
+  for (const key of ['major', 'minor', 'patch']) {
+    if (A[key] !== B[key]) return A[key] > B[key]
+  }
+  if (A.pre === null) return B.pre !== null
+  if (B.pre === null) return false
+  for (let i = 0; i < Math.max(A.pre.length, B.pre.length); i++) {
+    const x = A.pre[i]
+    const y = B.pre[i]
+    if (x === undefined) return false
+    if (y === undefined) return true
+    if (x === y) continue
+    const xn = /^\d+$/.test(x)
+    const yn = /^\d+$/.test(y)
+    if (xn && yn) return Number(x) > Number(y)
+    if (xn !== yn) return yn
+    return x > y
+  }
+  return false
+}
+
 const lang = (process.env.DSH_TUI_LANG ?? process.env.CC_TUI_LANG) === 'en' ? 'en' : 'zh'
 const MSG = {
   noDsh: {
@@ -64,10 +120,6 @@ const MSG = {
     en: `[dsh-tui] Plugin install failed. Retry manually later:\n  dsh plugin --profile ${PROFILE} add -w ${PACKAGE}@${ownVersion}`,
     zh: `[dsh-tui] 插件安装失败。可稍后手工重试：\n  dsh plugin --profile ${PROFILE} add -w ${PACKAGE}@${ownVersion}`,
   },
-  // no-op 假成功（自举后复查发现判定文件依旧缺失）：pnpm 把包文件残缺的
-  // profile 视为 already up to date，重装什么都不做却报告成功；继续启动
-  // 只会以 cannot resolve profile bundle 崩溃，而崩溃提示的 `plugin
-  // install` 同样 no-op——用户会陷入「每步都成功、每次都崩」的循环。
   bootstrapUnreadable: {
     en: dir =>
       `[dsh-tui] install reported success but the plugin package is still unreadable under:\n` +
@@ -82,60 +134,16 @@ const MSG = {
       `  恢复方法：\n` +
       `  rm -rf ${dir} 后重新运行 dsh-tui`,
   },
-  // Non-fatal skew comes in two directions and each needs its own repair:
-  // a profile NEWER than the launcher (typical after /update) must point at
-  // the global install, while a profile older only in patch must point back
-  // at the profile. The old generic message told forward-skew users to run
-  // /update again — an "Already up to date" loop.
-  profileOutdated: {
-    en: (installed, own) =>
-      `[dsh-tui] note: the profile is running v${installed} but this launcher is v${own}.\n` +
-      `  Align the profile to this launcher:\n` +
-      `  dsh plugin --profile ${PROFILE} add ${PACKAGE}@${own}`,
-    zh: (installed, own) =>
-      `[dsh-tui] 提示：profile 内运行的是 v${installed}，启动器是 v${own}。\n` +
-      `  请把 profile 对齐到启动器版本：\n` +
-      `  dsh plugin --profile ${PROFILE} add ${PACKAGE}@${own}`,
-  },
-  launcherOutdated: {
-    en: (installed, own) =>
-      `[dsh-tui] note: the profile is already v${installed}, but the global launcher is still v${own}.\n` +
-      `  Align the global dsh-tui launcher to the profile:\n` +
-      `  npm install -g ${PACKAGE}@${installed}\n` +
-      `  (if you installed it globally with pnpm: pnpm add -g ${PACKAGE}@${installed})`,
-    zh: (installed, own) =>
-      `[dsh-tui] 提示：profile 已是 v${installed}，但全局启动器仍是 v${own}。\n` +
-      `  请把全局 dsh-tui 启动器对齐到 profile 版本：\n` +
-      `  npm install -g ${PACKAGE}@${installed}\n` +
-      `  （如果你使用 pnpm 全局安装：pnpm add -g ${PACKAGE}@${installed}）`,
-  },
-  // Reverse skew (issue #183): the dsh CLI reads the bundle patch from the
-  // FIRST copy found from its own install anchor — this globally installed
-  // launcher — while the plugin modules load from the profile's copy. A
-  // launcher minor NEWER than the profile means the patch may reference
-  // subpath exports the profile's older package does not have, and boot
-  // crashes opaquely (ERR_PACKAGE_PATH_NOT_EXPORTED) before any TUI code
-  // runs. Fail loud with the fix instead. (Forward skew degrades to a
-  // working local-workspace fallback since 0.7.2 — soft note below.)
-  profileOlderThanLauncher: {
-    en: (installed, own) =>
-      `[dsh-tui] cannot start: the profile runs v${installed} but this launcher is v${own}.\n` +
-      `  The launcher's bundle patch would be applied to the profile's older package,\n` +
-      `  which does not export everything the patch references — boot would crash.\n` +
-      `  Align the profile with the launcher:\n` +
-      `  dsh plugin --profile ${PROFILE} add ${PACKAGE}@${own}\n` +
-      `  (or update everything to the latest release: dsh plugin --profile ${PROFILE} add ${PACKAGE}@latest)`,
-    zh: (installed, own) =>
-      `[dsh-tui] 无法启动：profile 内运行的是 v${installed}，而启动器是 v${own}。\n` +
-      `  启动器的 bundle patch 会套用到 profile 里的旧版包上，其中缺少 patch 引用\n` +
-      `  的子路径导出——启动会以模块解析错误崩溃。请让 profile 与启动器对齐：\n` +
-      `  dsh plugin --profile ${PROFILE} add ${PACKAGE}@${own}\n` +
-      `  （或全部升到最新：dsh plugin --profile ${PROFILE} add ${PACKAGE}@latest）`,
-  },
   launchFailed: {
     en: err => `[dsh-tui] Failed to launch: ${err.message}`,
     zh: err => `[dsh-tui] 启动失败：${err.message}`,
   },
+  delegateFailed: {
+    en: path =>
+      `[dsh-tui] cannot launch the profile copy:\n  ${path}\nReinstall the global launcher:\n  npm install -g ${PACKAGE}@latest`,
+    zh: path =>
+      `[dsh-tui] 无法启动 profile 内副本：\n  ${path}\n请重装全局启动器：\n  npm install -g ${PACKAGE}@latest`,
+  },
   profileExited: {
     en: code => `[dsh-tui] dsh profile exited with code ${code}. Run it directly for diagnostics:\n  dsh --profile ${PROFILE}`,
     zh: code => `[dsh-tui] dsh profile 已退出（退出码 ${code}）。可直接运行以下命令查看诊断：\n  dsh --profile ${PROFILE}`,
@@ -151,55 +159,59 @@ const msg = key => MSG[key][lang]
 // 长会话 OOM——与仓库根 dsh-tui.cmd 保持一致，强制 production。
 process.env.NODE_ENV ??= 'production'
 
-const isWin = process.platform === 'win32'
-// Windows 上 .cmd shim 必须经 shell 启动（Node ≥18.20.2 的安全限制）；
-// 其余平台直接 spawn 无后缀的 dsh。cmd.exe 以空格拼接参数且 Node 不做
-// 转义——shell 路径的所有参数必须先过 shellQuote（同 src/update.ts 的
-// /update 重启路径），否则含空格/引号的参数会被拆断。
-const shellOpt = isWin ? { shell: true } : {}
-// DEP0190（issue #148）：Node ≥22 对「shell:true + 非空参数数组」的调用
-// 发出弃用警告，判定是语法级的——参数已过 shellQuote 也一样告警；且未来
-// 大版本可能升级为运行时错误。把转义后的参数拼进命令字符串传入
-// （shell:true + 空参数数组不触发），非 Windows 路径保持数组直传。
-const cmd = (command, args) =>
-  isWin ? [`${command} ${shellQuote(args).join(' ')}`, []] : [command, args]
-
-// --- 1. dsh CLI 预检 ---------------------------------------------------------
-const probe = spawnSync(...cmd('dsh', ['--version']), { stdio: 'pipe', ...shellOpt })
-if (probe.error || probe.status !== 0) {
-  console.error(msg('noDsh'))
-  process.exit(1)
+const sameDir = (a, b) => {
+  try {
+    return realpathSync(resolve(a)) === realpathSync(resolve(b))
+  } catch {
+    return resolve(a) === resolve(b)
+  }
 }
 
-// --- 2. profile 自举与版本检查 -------------------------------------------------
 const dshHome = process.env.DSH_HOME || join(homedir(), '.dsh')
 const profileDir = join(dshHome, 'profiles', PROFILE)
-// 以已装包的 package.json 可读为准（而非目录存在）：安装中途失败留下的
-// 残骸目录会触发重新安装，而不是以坏 profile 直接启动。
-// 包可读判定文件：installedVersion 读取与自举后的复查共用（残缺 profile
-// 的 no-op 假成功靠它识别——见 bootstrapUnreadable）。
-const installedPkgPath = join(profileDir, 'node_modules', '@deepseek-harness-tui', 'dsh-tui', 'package.json')
-let installedVersion
-try {
-  installedVersion = JSON.parse(readFileSync(installedPkgPath, 'utf8')).version
-} catch {
-  installedVersion = undefined
+const profilePkgDir = join(profileDir, 'node_modules', '@deepseek-harness-tui', 'dsh-tui')
+const profileBin = join(profilePkgDir, 'bin', 'dsh-tui.js')
+const installedPkgPath = join(profilePkgDir, 'package.json')
+const runningInsideProfile = sameDir(ownDir, profilePkgDir)
+
+const forwardExit = child => {
+  child.on('error', err => {
+    console.error(msg('launchFailed')(err))
+    process.exit(1)
+  })
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal)
+    } else {
+      if (code !== null && code !== 0) console.error(msg('profileExited')(code))
+      process.exit(code ?? 0)
+    }
+  })
 }
-if (installedVersion === undefined) {
+
+// 首次运行自举：探测 dsh 与 pnpm，随后 `dsh plugin add` 固定到与启动器一
+// 致的版本（避免 pnpm store 缓存带来的旧版漂移）。-w 重试（issue #239）与
+// 「no-op 假成功」复查（issue #209）在此集中实现，瘦壳与完整逻辑共用。
+const profileReady = () => {
+  try {
+    readFileSync(installedPkgPath, 'utf8')
+    return true
+  } catch {
+    return false
+  }
+}
+const bootstrapProfile = () => {
+  const probe = spawnSync(...cmd('dsh', ['--version']), { stdio: 'pipe', ...shellOpt })
+  if (probe.error || probe.status !== 0) {
+    console.error(msg('noDsh'))
+    process.exit(1)
+  }
   const pnpmProbe = spawnSync(...cmd('pnpm', ['--version']), { stdio: 'pipe', ...shellOpt })
   if (pnpmProbe.error || pnpmProbe.status !== 0) {
     console.error(msg('noPnpm'))
     process.exit(1)
   }
   console.log(msg('bootstrapStart'))
-  // pnpm ≥11 在带 pnpm-workspace.yaml 的 profile 目录里可能拒绝向
-  // workspace root 写依赖（ERR_PNPM_ADDING_TO_ROOT，issue #239）：识别该
-  // 错误时带 -w 重试一次。签名在 stdout——pnpm 的错误报告写 stdout（经
-  // dsh 原样转发），stderr 上只有 dsh 自己的失败说明，识别 stderr 永远
-  // 匹配不到（PR #241 的回归）。因此首次 add 的 stdout/stderr 都走 pipe
-  // 捕获，结束后回放（失败回 stderr 保诊断，成功回 stdout 保进度，代价
-  // 是不再实时）；-w 重试大概率成功，恢复 inherit 让进度实时可见。手工
-  // 重试提示同步带 -w。
   const runAdd = (extraArgs, capture) => spawnSync(
     ...cmd('dsh', ['plugin', '--profile', PROFILE, 'add', ...extraArgs, `${PACKAGE}@${ownVersion}`]),
     { stdio: capture ? ['inherit', 'pipe', 'pipe'] : 'inherit', ...shellOpt },
@@ -219,116 +231,155 @@ if (installedVersion === undefined) {
     console.error(msg('installFailed'))
     process.exit(add.status ?? 1)
   }
-  // 自举后复查：pnpm 对包文件残缺的 profile 视为 already up to date，
-  // add 报告成功却什么都没装（no-op 假成功）。此时继续启动只会以 cannot
-  // resolve profile bundle 崩溃，提示的 `plugin install` 又同样 no-op——
-  // fail loud 给出唯一可靠的恢复路径（删 profile 目录重建）。
+  if (!profileReady()) {
+    console.error(msg('bootstrapUnreadable')(profileDir))
+    process.exit(1)
+  }
+}
+
+// ─── 全局副本：瘦壳角色 ───────────────────────────────────────────────────────
+// DSH_TUI_NO_DELEGATE=1 是测试/调试逃生口：强制走完整逻辑（verify-launcher
+// 的沙箱用它直接驱动全量路径；现场排查委托链时同样可用）。
+if (!runningInsideProfile && ownVersion !== undefined && process.env.DSH_TUI_NO_DELEGATE !== '1') {
+  if (!profileReady()) bootstrapProfile()
+  // 委托 profile 内副本执行全部启动逻辑。外层代际通过
+  // DSH_TUI_LAUNCHER_VERSION 交代（/update 的对齐诊断沿用该契约）。
   try {
-    readFileSync(installedPkgPath, 'utf8')
+    readFileSync(profileBin, 'utf8')
   } catch {
-    console.error(MSG.bootstrapUnreadable[lang](profileDir))
+    console.error(msg('delegateFailed')(profileBin))
     process.exit(1)
   }
-} else if (installedVersion !== ownVersion) {
-  // Reverse skew is fatal (see MSG.profileOlderThanLauncher): compare
-  // major/minor only — patch-level differences never move the patch surface.
-  const majorMinor = v => v.split('-')[0].split('.').slice(0, 2).map(Number)
-  const [installedMajor, installedMinor] = majorMinor(installedVersion)
-  const [ownMajor, ownMinor] = majorMinor(ownVersion)
-  if (installedMajor < ownMajor || (installedMajor === ownMajor && installedMinor < ownMinor)) {
-    console.error(MSG.profileOlderThanLauncher[lang](installedVersion, ownVersion))
-    process.exit(1)
+  process.env.DSH_TUI_LAUNCHER_VERSION = ownVersion
+  const child = spawn(process.execPath, [profileBin, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env: process.env,
+  })
+  forwardExit(child)
+} else {
+  // ─── profile 副本（或源码运行）：完整启动逻辑 ─────────────────────────────
+  // dsh CLI 预检（缺失时给安装指引，先于一切 profile 逻辑）。
+  {
+    const probe = spawnSync(...cmd('dsh', ['--version']), { stdio: 'pipe', ...shellOpt })
+    if (probe.error || probe.status !== 0) {
+      console.error(msg('noDsh'))
+      process.exit(1)
+    }
   }
-
-  // Non-fatal skew: repair in the direction the versions actually moved.
-  // A profile NEWER than the launcher (e.g. right after /update) means the
-  // GLOBAL launcher is stale — never point those users back at /update.
-  // Exact versions only: @latest could skip past the alignment point if a
-  // newer release or a mirror dist-tag is in play.
-  const installedSemver = valid(installedVersion)
-  const ownSemver = valid(ownVersion)
-  if (installedSemver !== null && ownSemver !== null && gt(installedSemver, ownSemver)) {
-    console.error(MSG.launcherOutdated[lang](installedVersion, ownVersion))
-  } else {
-    console.error(MSG.profileOutdated[lang](installedVersion, ownVersion))
+  let installedVersion
+  try {
+    installedVersion = JSON.parse(readFileSync(installedPkgPath, 'utf8')).version
+  } catch {
+    installedVersion = undefined
   }
-}
-
-// --- 3. --resume 拦截 ---------------------------------------------------------
-// 换名过渡（issue #120）：全局 bin 与 profile 内 TUI 包版本可能错位，所以
-// env 双写（新旧名都设），文件读取新路径优先、旧路径兜底。
-// 支持的形态（对齐 issue #53 的诉求）：
-//   --resume <id> / --resume=<id>   恢复指定会话
-//   --resume / -c / --continue      恢复最近一次会话（读 resume.txt）
-// 其余位置参数原样透传给 dsh CLI，由插件经 ctx.cmdlineArgs 读取（初始 prompt）。
-const setResumeEnv = sessionId => {
-  process.env.DSH_TUI_RESUME_SESSION = sessionId
-  process.env.DSH_CC_RESUME_SESSION = sessionId
-}
-const readLastResumeTarget = () => {
-  for (const dir of ['.dsh-tui', '.dsh-cc']) {
+  // 残骸/未初始化 profile：与旧启动器一致地就地自举（add 固定到本包版
+  // 本，成功后版本天然对齐），而不是拒绝启动。
+  if (installedVersion === undefined) {
+    bootstrapProfile()
     try {
-      const sessionId = readFileSync(join(homedir(), dir, 'resume.txt'), 'utf8').trim()
-      if (sessionId) return sessionId
+      installedVersion = JSON.parse(readFileSync(installedPkgPath, 'utf8')).version
     } catch {
-      // 没有历史会话可恢复——静默忽略，正常冷启动。
+      installedVersion = undefined
     }
   }
-  return ''
-}
-const args = []
-const argv = process.argv.slice(2)
-for (let i = 0; i < argv.length; i++) {
-  const a = argv[i]
-  if (a === '--resume' || a === '-c' || a === '--continue' || a.startsWith('--resume=')) {
-    let sessionId = ''
-    if (a.startsWith('--resume=')) {
-      sessionId = a.slice('--resume='.length).trim()
-    } else if (a === '--resume' && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) {
-      sessionId = argv[++i].trim()
+  if (installedVersion !== undefined && ownVersion !== undefined && installedVersion !== ownVersion && !runningInsideProfile) {
+    const majorMinor = v => v.split('-')[0].split('.').slice(0, 2).map(Number)
+    const [installedMajor, installedMinor] = majorMinor(installedVersion)
+    const [ownMajor, ownMinor] = majorMinor(ownVersion)
+    if (installedMajor < ownMajor || (installedMajor === ownMajor && installedMinor < ownMinor)) {
+      console.error(
+        `[dsh-tui] cannot start: the profile runs v${installedVersion} but this launcher is v${ownVersion}.\n` +
+          `  dsh plugin --profile ${PROFILE} add ${PACKAGE}@${ownVersion}`,
+      )
+      process.exit(1)
+    }
+    const installedNewer = installedVersion !== undefined && ownVersion !== undefined && isVersionNewer(installedVersion, ownVersion)
+    if (installedNewer) {
+      console.error(
+        `[dsh-tui] note: the profile is already v${installedVersion}; this launcher copy is v${ownVersion}.\n` +
+          `  npm install -g ${PACKAGE}@${installedVersion}`,
+      )
+    } else {
+      // profile 更旧但同 minor（patch 级错位）：允许启动，指引用 add 把
+      // profile 对齐到启动器版本（精确版本，@latest 可能越过对齐点）。
+      console.error(
+        `[dsh-tui] note: the profile is running v${installedVersion} but this launcher is v${ownVersion}.\n` +
+          `  dsh plugin --profile ${PROFILE} add ${PACKAGE}@${ownVersion}`,
+      )
     }
-    // 裸形态（含 -c/--continue）回退到 resume.txt。
-    if (!sessionId) sessionId = readLastResumeTarget()
-    if (sessionId) setResumeEnv(sessionId)
-  } else if (
-    process.env.DSH_TUI_WORKSPACE_TARGET === undefined
-    && !a.startsWith('-')
-    && (isAbsolute(a) || /^[a-z][a-z0-9+.-]*:\/\//iu.test(a) || existsSync(resolve(a)))
-  ) {
-    // A workspace target is launcher syntax, not an argument for the profile
-    // app. The registry resolves local paths/file URLs and provider URIs.
-    process.env.DSH_TUI_WORKSPACE_TARGET = a
-  } else {
-    args.push(a)
   }
-}
 
-// --- 3.5 旧环境变量警告（必须在 TUI 渲染前输出，fullscreen 下写 stderr 会破坏界面）
-for (const oldName of detectLegacyEnv()) {
-  console.error(MSG.legacyEnv[lang](oldName, RENAMED_ENV[oldName]))
-}
+  // --resume / 工作区目标拦截（issue #120/#53 的启动器契约）。
+  const setResumeEnv = sessionId => {
+    process.env.DSH_TUI_RESUME_SESSION = sessionId
+    process.env.DSH_CC_RESUME_SESSION = sessionId
+  }
+  const readLastResumeTarget = () => {
+    for (const dir of ['.dsh-tui', '.dsh-cc']) {
+      try {
+        const sessionId = readFileSync(join(homedir(), dir, 'resume.txt'), 'utf8').trim()
+        if (sessionId) return sessionId
+      } catch {
+        // 没有历史会话可恢复——静默忽略，正常冷启动。
+      }
+    }
+    return ''
+  }
+  const args = []
+  const argv = process.argv.slice(2)
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--resume' || a === '-c' || a === '--continue' || a.startsWith('--resume=')) {
+      let sessionId = ''
+      if (a.startsWith('--resume=')) {
+        sessionId = a.slice('--resume='.length).trim()
+      } else if (a === '--resume' && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) {
+        sessionId = argv[++i].trim()
+      }
+      if (!sessionId) sessionId = readLastResumeTarget()
+      if (sessionId) setResumeEnv(sessionId)
+    } else if (
+      process.env.DSH_TUI_WORKSPACE_TARGET === undefined
+      && !a.startsWith('-')
+      && (isAbsolute(a) || /^[a-z][a-z0-9+.-]*:\/\//iu.test(a) || existsSync(resolve(a)))
+    ) {
+      process.env.DSH_TUI_WORKSPACE_TARGET = a
+    } else {
+      args.push(a)
+    }
+  }
 
-// --- 4. 启动 ------------------------------------------------------------------
-// Contract for the profile runtime: lets /update diagnose whether the
-// global dsh-tui launcher is older than the profile it just installed.
-// Not a one-shot marker — it must survive restarts so the runtime always
-// knows the launcher generation it boots under.
-process.env.DSH_TUI_LAUNCHER_VERSION = ownVersion
+  // 旧环境变量警告（必须在 TUI 渲染前输出，fullscreen 下写 stderr 会破坏
+  // 界面）。与 utils/paths 的 RENAMED_ENV 同表，内联以维持零 lib 依赖。
+  const RENAMED_ENV = {
+    CC_TUI_THEME: 'DSH_TUI_THEME',
+    CC_TUI_LANG: 'DSH_TUI_LANG',
+    CC_TUI_PERSONA: 'DSH_TUI_PERSONA',
+    CC_TUI_PRESET: 'DSH_TUI_PRESET',
+    CC_TUI_DISABLE_MOUSE: 'DSH_TUI_DISABLE_MOUSE',
+    CC_TUI_DEBUG: 'DSH_TUI_DEBUG',
+    CC_TUI_COMPACT_RATIO: 'DSH_TUI_COMPACT_RATIO',
+    CC_TUI_COMPACT_RETAIN: 'DSH_TUI_COMPACT_RETAIN',
+    DSH_CC_UPDATED_FROM: 'DSH_TUI_UPDATED_FROM',
+    DSH_CC_RENDER_LOG: 'DSH_TUI_RENDER_LOG',
+    DSH_CC_SESSION_ROOT: 'DSH_TUI_SESSION_ROOT',
+    DSH_CC_WORKSPACE: 'DSH_TUI_WORKSPACE',
+  }
+  for (const oldName of Object.keys(RENAMED_ENV)) {
+    if (process.env[oldName] !== undefined) {
+      console.error(msg('legacyEnv')(oldName, RENAMED_ENV[oldName]))
+    }
+  }
 
-const child = spawn(...cmd('dsh', ['--profile', PROFILE, ...args]), {
-  stdio: 'inherit',
-  env: process.env,
-  ...shellOpt,
-})
-child.on('error', err => {
-  console.error(MSG.launchFailed[lang](err))
-  process.exit(1)
-})
-child.on('exit', (code, signal) => {
-  if (signal) {
-    process.kill(process.pid, signal)
-  } else {
-    if (code !== null && code !== 0) console.error(MSG.profileExited[lang](code))
-    process.exit(code ?? 0)
+  // 启动：被委托场景下本副本自己的版本即对齐诊断所见的启动器代际。
+  if (process.env.DSH_TUI_LAUNCHER_VERSION === undefined && ownVersion !== undefined) {
+    process.env.DSH_TUI_LAUNCHER_VERSION = ownVersion
   }
-})
+
+  const child = spawn(...cmd('dsh', ['--profile', PROFILE, ...args]), {
+    stdio: 'inherit',
+    env: process.env,
+    ...shellOpt,
+  })
+  forwardExit(child)
+}