dsh-vscode-mode 0.12.0 → 0.13.0

package/src/devForm.ts

@@ -1,133 +1,293 @@
-/**
- * dsh-vscode-mode host — 开发形态管理（安装形态切换）。
- * 开发形态 = profile 中以 link: 依赖 + junction 指向工作区的安装（用于插件开发）；
- * 关闭 = 改回版本依赖 + 删 junction + pnpm install 装配正式版。
- * 切换后需重启 DSH 生效（运行中的代码仍是旧形态）。
- * 与 compat.ts 存在模块环（devForm 用 pluginVersionOf、compat 用 readDevForm），
- * 双方仅在函数体内交叉使用，模块求值期无依赖，ESM 安全。
- * 作者 ddj 2026-08-24
- */
-import { existsSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { homedir } from 'node:os'
+/** 当前运行 profile 的开发形态切换；失败恢复 manifest、lockfile 与原安装入口。 */
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve } from 'node:path'
 import { PLUGIN_NAME, pluginVersionOf } from './compat.js'
+import { dshHome } from './paths.js'
+import { childEnv } from './childEnv.js'
 import type { DevFormInfo } from './shared/compat.js'
 import type { Ctx } from './store.js'
 
-/** 扫描 $DSH_HOME/profiles 找到依赖本插件的 profile 目录（无 env 依赖，多 profile 安全）。 */
-export function findProfileDir(): string | undefined {
-  const home = process.env.DSH_HOME ?? join(homedir(), '.dsh')
+/** 官方 dsh profile-boot 提供的当前运行事实；不从 inventory 猜测。 */
+interface ProfileContext {
+  dir: string
+  packageManager?: { command: string; args?: string[]; env?: NodeJS.ProcessEnv }
+}
+type SwitchResult = { ok: boolean; error?: string; restart: boolean }
+interface ProfileBackup {
+  dir: string
+  link: string
+  savedLink: string
+  hadLink: boolean
+  files: { path: string; text: Buffer | undefined }[]
+}
+const switching = new Set<string>()
+
+// --region 运行上下文
+/**
+ * 获取官方 profileContext 服务；服务存在但无有效目录时拒绝猜测。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param ctx 可选运行上下文
+ * @returns 官方服务对象或缺失
+ * @throws 服务对象目录无效
+ */
+function profileOf(ctx?: Ctx): ProfileContext | undefined {
+  const profile = ctx?.get?.('profileContext')
+  if (profile === undefined || profile === null) return undefined
+  if (typeof profile.dir !== 'string' || !isAbsolute(profile.dir)) throw new Error('当前 profileContext.dir 无效')
+  return profile as ProfileContext
+}
+
+/**
+ * 检查 manifest 是否明确依赖本插件；坏 manifest 不作候选。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param dir profile 目录
+ * @returns 是否包含插件依赖
+ */
+function ownsPlugin(dir: string): boolean {
   try {
-    for (const name of readdirSync(join(home, 'profiles'))) {
-      const pkgFile = join(home, 'profiles', name, 'package.json')
-      if (!existsSync(pkgFile)) continue
-      try {
-        const pkg = JSON.parse(readFileSync(pkgFile, 'utf8')) as { dependencies?: Record<string, unknown> } | undefined
-        if (pkg?.dependencies?.[PLUGIN_NAME]) return dirname(pkgFile)
-      } catch {
-        /* 坏 manifest 跳过该 profile */
-      }
-    }
-  } catch {
-    /* profiles 目录不存在时放弃 */
-  }
-  return undefined
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8').replace(/^\uFEFF/, ''))
+    return typeof pkg?.dependencies?.[PLUGIN_NAME] === 'string'
+  } catch { return false }
 }
 
 /**
- * 读取当前开发形态（manifest link: 判定）。
- * @author ddj 2026年08月24号
- * @returns 开发形态状态
+ * 优先使用真实运行 profile；旧宿主仅允许唯一候选回退，多候选拒绝。
+ * @public
+ * @author ddj 2026年09月28号
+ * @param ctx DSH host 上下文（可选，旧宿主兼容）
+ * @returns 当前 profile 目录；无有效或唯一候选时 undefined
  */
-export function readDevForm(): DevFormInfo {
-  const profileDir = findProfileDir()
-  if (!profileDir) return { enabled: false }
+export function findProfileDir(ctx?: Ctx): string | undefined {
   try {
-    const text = readFileSync(join(profileDir, 'package.json'), 'utf8').replace(/^\uFEFF/, '')
-    const pkg = JSON.parse(text) as { dependencies?: Record<string, unknown> } | undefined
+    const profile = profileOf(ctx)
+    if (profile) return ownsPlugin(profile.dir) ? profile.dir : undefined
+    const homePath = ctx?.get?.('dshHomePath')
+    const root = join(typeof homePath === 'function' ? homePath() : dshHome(), 'profiles')
+    const candidates = readdirSync(root).map((name) => join(root, name)).filter(ownsPlugin)
+    return candidates.length === 1 ? candidates[0] : undefined
+  } catch { return undefined }
+}
+
+/**
+ * 读取选中 profile 的 link 依赖状态。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param dir 已选定目录
+ * @returns 开发形态；无法读取时未开启
+ */
+function readProfileForm(dir: string): DevFormInfo {
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8').replace(/^\uFEFF/, ''))
     const spec = pkg?.dependencies?.[PLUGIN_NAME]
-    if (typeof spec === 'string' && spec.startsWith('link:')) {
-      return { enabled: true, path: spec.slice('link:'.length) }
-    }
-  } catch {
-    /* manifest 不可读视为非开发形态 */
-  }
+    if (typeof spec === 'string' && spec.startsWith('link:')) return { enabled: true, path: spec.slice(5) }
+  } catch { /* 只读探测失败 */ }
   return { enabled: false }
 }
 
 /**
- * 规划切换后的 manifest 文本（纯函数，可单测；非法 JSON 抛错）。
- * @author ddj 2026年08月24号
+ * 读取当前运行 profile 的开发形态。
+ * @public
+ * @author ddj 2026年09月28号
+ * @param ctx DSH host 上下文
+ * @returns 开发形态状态
+ */
+export function readDevForm(ctx?: Ctx): DevFormInfo {
+  const dir = findProfileDir(ctx)
+  return dir ? readProfileForm(dir) : { enabled: false }
+}
+// --endregion
+
+/**
+ * 规划切换后的 manifest，保留其它字段。
+ * @public
+ * @author ddj 2026年09月28号
  * @param text 原 manifest 文本
- * @param enabled 目标形态（true=link:，false=版本）
- * @param path 工作区路径（开启时必填）
- * @param version 版本号（关闭时使用，写入 ^<version>）
- * @returns 新 manifest 文本（无 BOM，2 空格缩进）
+ * @param enabled true 为开发链接
+ * @param path 开发目录
+ * @param version 正式版本号
+ * @returns 新 manifest 文本
+ * @throws JSON 或 dependencies 无效
  */
 export function planManifest(text: string, enabled: boolean, path: string, version: string): string {
   const data = JSON.parse(text.replace(/^\uFEFF/, '')) as { dependencies?: Record<string, unknown> }
-  if (!data.dependencies || typeof data.dependencies !== 'object') {
+  if (!data.dependencies || typeof data.dependencies !== 'object' || Array.isArray(data.dependencies)) {
     throw new Error('profile package.json 缺少 dependencies 字段')
   }
   data.dependencies[PLUGIN_NAME] = enabled ? 'link:' + path.replace(/\\/g, '/') : '^' + version
   return JSON.stringify(data, null, 2) + '\n'
 }
 
-/** 建立或移除 node_modules 下的开发 junction（目标不存在时开启失败）。 */
-function applyJunction(profileDir: string, enabled: boolean, target: string): void {
-  const linkDir = join(profileDir, 'node_modules', PLUGIN_NAME)
-  if (existsSync(linkDir)) rmSync(linkDir, { recursive: true, force: true })
-  if (!enabled) return
-  if (!existsSync(target)) throw new Error('工作区路径不存在：' + target)
-  symlinkSync(target, linkDir, 'junction')
+// --region 切换事务
+/**
+ * 检查开发目录属于本插件且不位于会被替换的 node_modules 内。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param dir profile 目录
+ * @param target 用户目标路径
+ * @returns 真实绝对目录
+ * @throws 目录、包身份或位置不安全
+ */
+function checkTarget(dir: string, target: string): string {
+  if (!target || !isAbsolute(target)) throw new Error('开启开发形态需要提供工作区绝对路径')
+  const full = realpathSync(target)
+  if (!statSync(full).isDirectory()) throw new Error('工作区路径不是目录：' + target)
+  const pkg = JSON.parse(readFileSync(join(full, 'package.json'), 'utf8').replace(/^\uFEFF/, ''))
+  if (pkg?.name !== PLUGIN_NAME) throw new Error('工作区 package.json.name 必须是 ' + PLUGIN_NAME)
+  const modules = join(dir, 'node_modules')
+  const moduleRoot = existsSync(modules) ? realpathSync(modules) : resolve(realpathSync(dir), 'node_modules')
+  const inside = relative(moduleRoot, full)
+  if (!inside || (!inside.startsWith('..' + (process.platform === 'win32' ? '\\' : '/')) && !isAbsolute(inside))) {
+    throw new Error('开发源码不能位于当前 profile 的 node_modules 内')
+  }
+  return full
+}
+
+/**
+ * 删除安装入口；链接仅 unlink，绝不递归其源码目标。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param path 安装入口或备份入口
+ * @throws 删除失败
+ */
+function removeEntry(path: string): void {
+  const info = lstatSync(path, { throwIfNoEntry: false })
+  if (!info) return
+  if (info.isSymbolicLink()) unlinkSync(path)
+  else rmSync(path, { recursive: true, force: true })
+}
+
+/**
+ * 在首次写入前保存 manifest/lockfile 原字节，并移动原安装入口保留链接身份。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param dir profile 目录
+ * @returns 可回滚的备份
+ * @throws 备份失败；尚未修改 manifest
+ */
+function backupProfile(dir: string): ProfileBackup {
+  const files = ['package.json', 'pnpm-lock.yaml'].map((name) => {
+    const path = join(dir, name)
+    return { path, text: existsSync(path) ? readFileSync(path) : undefined }
+  })
+  const backupDir = mkdtempSync(join(dir, '.vscode-mode-backup-'))
+  const link = join(dir, 'node_modules', PLUGIN_NAME)
+  const savedLink = join(backupDir, 'module')
+  const hadLink = !!lstatSync(link, { throwIfNoEntry: false })
+  try {
+    for (const file of files) {
+      if (file.text !== undefined) writeFileSync(join(backupDir, relative(dir, file.path)), file.text)
+    }
+    if (hadLink) renameSync(link, savedLink)
+    return { dir: backupDir, link, savedLink, hadLink, files }
+  } catch (error) {
+    rmSync(backupDir, { recursive: true, force: true })
+    throw error
+  }
 }
 
 /**
- * 切换开发形态：改 manifest → 建/删 junction → pnpm install（subprocess）。
- * @author ddj 2026年08月24号
- * @param ctx DSH host 上下文（subprocess 服务）
+ * 恢复原安装入口和配置文件；恢复失败时保留备份供恢复。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param saved 原状态备份
+ * @throws 回滚失败，错误包含备份位置
+ */
+function restoreProfile(saved: ProfileBackup): void {
+  const failures: string[] = []
+  try {
+    removeEntry(saved.link)
+    if (saved.hadLink) renameSync(saved.savedLink, saved.link)
+  } catch (error) { failures.push(String(error)) }
+  for (const file of saved.files) {
+    try {
+      if (file.text === undefined) rmSync(file.path, { force: true })
+      else writeFileSync(file.path, file.text)
+    } catch (error) { failures.push(String(error)) }
+  }
+  if (failures.length) throw new Error('回滚失败，备份保留于 ' + saved.dir + '：' + failures.join('; '))
+  rmSync(saved.dir, { recursive: true, force: true })
+}
+
+/**
+ * 执行已预检的切换；安装失败时恢复原入口及 manifest/lockfile。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param ctx host 上下文
+ * @param dir 已确定的 profile
  * @param enabled 目标形态
- * @param path 工作区绝对路径（开启时必填）
- * @returns 切换结果（restart=true 表示需重启 DSH 生效）
+ * @param target 已预检目标
+ * @returns 事务结果；成功需重启
  */
-export async function setDevForm(ctx: Ctx, enabled: boolean, path?: string): Promise<{ ok: boolean; error?: string; restart: boolean }> {
-  const profileDir = findProfileDir()
-  if (!profileDir) return { ok: false, error: '未找到依赖本插件的 profile（检查 DSH_HOME/profiles）', restart: false }
-  const current = readDevForm()
-  const target = (path ?? current.path ?? '').replace(/\\/g, '/')
-  if (enabled && !target) return { ok: false, error: '开启开发形态需要提供工作区路径（path 参数）', restart: false }
-  if (enabled === current.enabled && (!enabled || target === current.path)) {
-    return { ok: true, restart: false }
+async function switchProfile(ctx: Ctx, dir: string, enabled: boolean, target: string): Promise<SwitchResult> {
+  const version = pluginVersionOf()
+  if (!version) throw new Error('读取插件版本失败，无法写入版本依赖')
+  const next = planManifest(readFileSync(join(dir, 'package.json'), 'utf8'), enabled, target, version)
+  const saved = backupProfile(dir)
+  try {
+    writeFileSync(join(dir, 'package.json'), next, 'utf8')
+    mkdirSync(join(dir, 'node_modules'), { recursive: true })
+    if (enabled) symlinkSync(target, saved.link, 'junction')
+    await runPnpmInstall(ctx, dir)
+  } catch (error) {
+    restoreProfile(saved)
+    throw error
   }
   try {
-    const pkgFile = join(profileDir, 'package.json')
-    const version = pluginVersionOf()
-    if (!version) return { ok: false, error: '读取插件版本失败，无法写入版本依赖', restart: false }
-    const next = planManifest(readFileSync(pkgFile, 'utf8').replace(/^\uFEFF/, ''), enabled, target, version)
-    writeFileSync(pkgFile, next, 'utf8')
-    applyJunction(profileDir, enabled, target)
-    const installError = await runPnpmInstall(ctx, profileDir)
-    return { ok: !installError, error: installError, restart: true }
+    removeEntry(saved.savedLink)
+    rmSync(saved.dir, { recursive: true, force: true })
   } catch (error) {
-    return { ok: false, error: String(error), restart: false }
+    return { ok: true, error: '切换成功，旧安装备份清理失败：' + saved.dir + '：' + String(error), restart: true }
   }
+  return { ok: true, restart: true }
 }
 
-/** 在 profile 目录执行 pnpm install（subprocess 契约：spawn({argv,cwd,stdio,graceMs})）。 */
-async function runPnpmInstall(ctx: Ctx, profileDir: string): Promise<string | undefined> {
-  const sub = ctx.get('subprocess')
-  if (!sub || typeof sub.spawn !== 'function') return 'manifest/junction 已更新，但缺少 subprocess：请手动在 profile 目录运行 pnpm install'
-  const handle = sub.spawn({
-    argv: ['pnpm', 'install'],
+/**
+ * 预检运行 profile、目标与安装服务，再串行执行可回滚切换。
+ * @public
+ * @author ddj 2026年09月28号
+ * @param ctx DSH host 上下文
+ * @param enabled 目标形态
+ * @param path 开发工作区绝对路径
+ * @returns 结果与是否需重启；失败不提交切换
+ */
+export async function setDevForm(ctx: Ctx, enabled: boolean, path?: string): Promise<SwitchResult> {
+  const dir = findProfileDir(ctx)
+  if (!dir) return { ok: false, error: '无法唯一定位当前 profile；请检查 profileContext 或 DSH_HOME/profiles', restart: false }
+  const key = process.platform === 'win32' ? resolve(dir).toLowerCase() : resolve(dir)
+  if (switching.has(key)) return { ok: false, error: '该 profile 正在切换开发形态', restart: false }
+  switching.add(key)
+  try {
+    const current = readProfileForm(dir)
+    const raw = path ?? current.path ?? ''
+    const target = enabled ? checkTarget(dir, raw) : ''
+    if (enabled === current.enabled && (!enabled || resolve(dir, current.path ?? '') === target)) return { ok: true, restart: false }
+    if (typeof ctx?.get?.('subprocess')?.spawn !== 'function') throw new Error('缺少 subprocess 服务，未修改 profile')
+    return await switchProfile(ctx, dir, enabled, target)
+  } catch (error) {
+    return { ok: false, error: String(error), restart: false }
+  } finally { switching.delete(key) }
+}
+
+/**
+ * 使用官方 profileContext.packageManager 运行 Desktop 内置 pnpm；旧宿主使用 PATH。
+ * @private
+ * @author ddj 2026年09月28号
+ * @param ctx host 上下文
+ * @param profileDir profile 工作目录
+ * @throws 启动失败或非零退出；只需退出码，stdio 使用 inherit
+ */
+async function runPnpmInstall(ctx: Ctx, profileDir: string): Promise<void> {
+  const runner = profileOf(ctx)?.packageManager
+  const handle = ctx.get('subprocess').spawn({
+    argv: [runner?.command ?? 'pnpm', ...runner?.args ?? [], 'install'],
     cwd: profileDir,
-    stdio: { stdout: { maxBytes: 1 << 16 }, stderr: { maxBytes: 1 << 16 }, stdin: 'ignore' },
+    env: childEnv(runner?.env),
+    stdio: { stdout: 'inherit', stderr: 'inherit', stdin: 'ignore' },
     graceMs: 120000,
   })
   const outcome = await handle.done
-  const code = outcome?.exitCode ?? outcome?.code
-  if (code !== 0) {
-    const stderr = handle.collected?.stderr?.readFrom(0).text ?? ''
-    return 'pnpm install 失败（exit ' + code + '）：' + stderr.slice(0, 500)
-  }
-  return undefined
+  if (outcome?.exitCode !== 0) throw new Error('pnpm install 失败（exit ' + String(outcome?.exitCode) + '）')
 }
+// --endregion

package/src/externalHandoff.ts

@@ -1,70 +1,111 @@
-/**
- * dsh-vscode-mode host — 深链移交（避免重复打开 DSH 页面）。
- * launcher 投递待打开请求（edrv.external.handoff）→ 已打开页面 3s 轮询领取（edrv.external.pending）
- * 并就地执行打开规则；15s 内无页面轮询过 = 无活跃页面 → launcher 回退打开新页。
- * token 防多实例串扰；TTL 兜底防陈旧悬挂。模块级状态（host 单进程单例）。
- * 作者 ddj 2026-09-08
- */
 import { randomUUID } from 'node:crypto'
+import { OPEN_TTL_MS } from './shared/externalOpen.js'
 
-/** 一次外部打开请求（launcher 投递）。 */
-export interface ExternalOpenRequest {
-  paths: string[]
-  line?: number
-  column?: number
+export interface ExternalOpenRequest { paths: string[]; line?: number; column?: number }
+export interface OpenClaim extends ExternalOpenRequest { token: string; leaseId: string }
+export interface OpenReceipt { token: string; clientId: string; leaseId: string; success: boolean; error?: string }
+interface Pending extends ExternalOpenRequest {
+  token: string; at: number; clientId?: string; leaseId?: string; leaseAt?: number
+  success?: boolean; error?: string
 }
-
-/** 待打开 TTL：超时未领取即丢弃（launcher 回退已自行处理）。 */
-const PENDING_TTL_MS = 60_000
-/** 活跃页面判定窗口：窗口内有过 pending 轮询 = 有页面在。 */
-const PRESENCE_WINDOW_MS = 15_000
-
-let pending: (ExternalOpenRequest & { token: string; at: number }) | null = null
+const pending = new Map<string, Pending>()
+const LEASE_MS = 30_000
 let lastPollAt = 0
 
-/**
- * 投递一次外部打开请求；返回活跃页面数（0 = launcher 应回退开新页）与移交 token。
- * @author ddj 2026年09月08号
- * @param req 打开请求
- * @returns 活跃页面数与 token
+/** @public @author ddj 2026年09月28号
+ * Queue a bounded request without replacing earlier opens.
+ * @param req Paths and navigation coordinates.
+ * @param token Optional inbox request ID.
+ * @param createdAt Original producer timestamp; queue ingestion never extends it.
+ * @returns Presence and stable request token.
  */
-export function handoffOpen(req: ExternalOpenRequest): { clients: number; token: string } {
-  const token = randomUUID()
-  pending = { ...req, token, at: Date.now() }
-  return { token, clients: clientsAlive() ? 1 : 0 }
+export function handoffOpen(req: ExternalOpenRequest, token: string = randomUUID(), createdAt = Date.now()): { clients: number; token: string } {
+  prunePending()
+  const clients = Date.now() - lastPollAt <= 15_000 ? 1 : 0
+  if (!Number.isSafeInteger(createdAt) || createdAt + OPEN_TTL_MS <= Date.now()) return { token, clients }
+  if (!pending.has(token)) {
+    if (pending.size >= 128) throw new Error('外部打开队列已满')
+    pending.set(token, { ...req, paths: [...req.paths], token, at: createdAt })
+  }
+  return { token, clients }
 }
 
-/**
- * 页面轮询：刷新活跃态并领取待打开请求（取走即清，多页面仅一方执行）。
- * @author ddj 2026年09月08号
- * @returns 待打开请求或 null
+/** @public @author ddj 2026年09月28号
+ * Claim one request; repeated heartbeats renew this client's active lease.
+ * @param args Authenticated page identity.
+ * @returns A leased request or null.
  */
-export function pollPending(): ExternalOpenRequest | null {
+export function pollPending(args: { clientId: string; busy?: boolean }): OpenClaim | null {
   lastPollAt = Date.now()
-  if (!pending) return null
-  if (Date.now() - pending.at > PENDING_TTL_MS) {
-    pending = null
+  prunePending()
+  if (!args?.clientId || args.clientId.length > 128) return null
+  const active = [...pending.values()].find((row) => row.clientId === args.clientId && row.success === undefined)
+  if (active && Date.now() - (active.leaseAt ?? 0) < LEASE_MS) {
+    active.leaseAt = Date.now()
     return null
   }
-  const taken: ExternalOpenRequest = { paths: pending.paths, line: pending.line, column: pending.column }
-  pending = null
-  return taken
+  if (args.busy) return null
+  for (const row of pending.values()) {
+    if (row.success !== undefined || (row.leaseAt && Date.now() - row.leaseAt < LEASE_MS)) continue
+    row.clientId = args.clientId
+    row.leaseId = randomUUID()
+    row.leaseAt = Date.now()
+    return { paths: row.paths, line: row.line, column: row.column, token: row.token, leaseId: row.leaseId }
+  }
+  return null
 }
 
-/**
- * 查询移交是否已被页面领取（take=true 时未领取则取走清除，供 launcher 回退开新页）。
- * @author ddj 2026年09月08号
- * @param token 移交 token
- * @param take 未领取时是否取走清除
- * @returns delivered=true = 已有页面领取（或已被更新的请求取代）
+/** @public @author ddj 2026年09月28号
+ * Accept only the current lease's actual editor completion.
+ * @param receipt Claimed request identity and result.
+ * @returns Whether the receipt was accepted.
  */
-export function pendingState(token: string, take: boolean): { delivered: boolean } {
-  const delivered = pending === null || pending.token !== token
-  if (take && !delivered) pending = null
-  return { delivered }
+export function ackPending(receipt: OpenReceipt): boolean {
+  prunePending()
+  const row = pending.get(receipt.token)
+  if (!row || Date.now() >= row.at + OPEN_TTL_MS || row.clientId !== receipt.clientId || row.leaseId !== receipt.leaseId) return false
+  if (!row.leaseAt || Date.now() - row.leaseAt >= LEASE_MS) return false
+  if (row.success !== undefined) return row.success === receipt.success
+  row.success = receipt.success === true
+  row.error = receipt.error?.slice(0, 1000)
+  return true
 }
 
-/** 活跃页面判定。 */
-function clientsAlive(): boolean {
-  return Date.now() - lastPollAt <= PRESENCE_WINDOW_MS
+/** @public @author ddj 2026年09月28号
+ * Inspect completion; absence and mere delivery never imply success.
+ * @param token Request identity.
+ * @param take Legacy cancellation flag, only cancels unclaimed requests.
+ * @returns Terminal completion state.
+ */
+export function pendingState(token: string, take = false): { delivered: boolean; completed: boolean; error?: string } {
+  prunePending()
+  const row = pending.get(token)
+  if (take && row && !row.leaseId) cancelPending(token, '打开已取消')
+  return { delivered: row?.success === true, completed: row?.success !== undefined, error: row?.error }
 }
+
+/** @public @author ddj 2026年09月28号
+ * Cancel queued or claimed work while retaining its identity against replay.
+ * @param token Original request ID.
+ * @param error Terminal diagnostic.
+ */
+export function cancelPending(token: string, error = '打开超时，请重试'): void {
+  const row = pending.get(token)
+  if (!row) return
+  if (row.success === undefined) { row.success = false; row.error = error }
+  row.clientId = undefined
+  row.leaseId = undefined
+  row.leaseAt = undefined
+}
+
+/** @private @author ddj 2026年09月28号 Expire at the original deadline and retain bounded replay tombstones. */
+function prunePending(): void {
+  const now = Date.now()
+  for (const [key, row] of pending) {
+    if (now >= row.at + OPEN_TTL_MS && row.success === undefined) cancelPending(key)
+    if (now >= row.at + OPEN_TTL_MS * 2) pending.delete(key)
+  }
+}
+
+/** @public @author ddj 2026年09月28号 Release profile-scoped state during host disposal. */
+export function clearPending(): void { pending.clear(); lastPollAt = 0 }

package/src/fileOpenSettings.ts

@@ -8,8 +8,7 @@
  * 全程 try/catch，不产生未捕获 rejection。
  * 作者 ddj 2026年08月24号 / 2026年08月26号 / 2026年09月02号 / 2026年09月22号 / 2026年09月23号
  */
-import { createRequire } from 'node:module'
-import { pathToFileURL } from 'node:url'
+import { loadHostModule as hostImport } from './hostImport.js'
 import type { Ctx } from './store.js'
 import { KEYBINDING_DEFAULTS } from './shared/keybindings.js'
 import { EDITOR_LIMIT_DEFAULT } from './shared/editorLimit.js'
@@ -56,28 +55,6 @@ export type SettingsDepsLoader = () => Promise<SettingsDeps | null>
 
 let depsPromise: Promise<SettingsDeps | null> | undefined
 
-/**
- * 宿主锚点动态导入：先经 process.argv[1]（DSH 启动脚本所在树）解析并加载目标包，
- * 避开本插件自身 node_modules 的 dev 依赖副本（dev-link 下 import() 相对插件位置
- * 解析，会命中 rc 线旧包 dsh-settings@0.1.0-rc.8）；argv[1] 缺失或解析失败回退
- * 普通 specifier import。
- * @author ddj 2026年09月15号
- * @param specifier 包名
- * @returns 加载的模块命名空间
- */
-async function hostImport(specifier: string): Promise<unknown> {
-  const entry = process.argv[1]
-  if (entry) {
-    try {
-      const resolved = createRequire(entry).resolve(specifier)
-      return await import(pathToFileURL(resolved).href)
-    } catch {
-      /* 锚点不可用：回退普通 import */
-    }
-  }
-  return import(specifier)
-}
-
 /**
  * schema 库候选名（新名在前）。
  * DSH 官方自 0.1.5 起把 vendored 包改名为 @deepseek-ai/schemastery 并全树改用新名，

package/src/hostImport.ts

@@ -0,0 +1,19 @@
+/** Host-anchored optional package imports. @author ddj 2026年09月28号 */
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+
+/**
+ * Resolve against the running DSH entry before the plugin's development dependencies.
+ * Import failures after successful resolution are preserved, not hidden by an older copy.
+ * @author ddj 2026年09月28号
+ * @param specifier Host package name.
+ * @returns The evaluated host module namespace.
+ */
+export async function loadHostModule(specifier: string): Promise<unknown> {
+  const anchor = process.argv[1]
+  let resolved: string | undefined
+  if (anchor) {
+    try { resolved = createRequire(anchor).resolve(specifier) } catch { /* Source-only tests may have no Host tree. */ }
+  }
+  return import(resolved ? pathToFileURL(resolved).href : specifier)
+}