dsh-vscode-mode 0.12.0 → 0.13.0

package/src/mcpRuntime.ts

@@ -0,0 +1,343 @@
+/** Agent-owned project MCP fibers. @author ddj 2026年09月28号 */
+import { loadHostModule } from './hostImport.js'
+import { entriesOf, MCP_PACKAGE, publicConfig, toolsOf } from './mcp.js'
+import { isProjectEntryId } from './compat.js'
+import { matchWorkspace } from './mcpIsolation.js'
+import { listProjects, projectEntryId, reconcileProject } from './mcpProject.js'
+import type { MpcConfig, MpcServer } from './shared/mcp.js'
+import type { Ctx } from './store.js'
+
+export type ProjectDef = { config: MpcConfig; enabled: boolean }
+type Instance = { fiber?: any; key: string; path: string; error?: string; stopping?: Promise<void> }
+type AgentRecord = { instances: Map<string, Instance>; live: boolean }
+export type McpLoader = () => Promise<any>
+const runtimes = new WeakMap<object, McpRuntime>()
+
+/**
+ * Load the official plugin from the running host's installation tree.
+ * @private @author ddj 2026年09月28号
+ * @returns Official MCP plugin namespace; rejects if the host package is absent.
+ */
+async function loadMcp(): Promise<any> {
+  return loadHostModule(MCP_PACKAGE)
+}
+
+/**
+ * Resolve one runtime per host, shared by lifecycle and RPC contexts.
+ * @public @author ddj 2026年09月28号
+ * @param ctx Host context.
+ * @returns Lazy runtime; allocating it does not start connections.
+ */
+export function runtimeOf(ctx: Ctx): McpRuntime {
+  const owner = ctx.root ?? ctx
+  let runtime = runtimes.get(owner)
+  if (!runtime) {
+    runtime = new McpRuntime(ctx)
+    runtimes.set(owner, runtime)
+  }
+  return runtime
+}
+
+/** Agent -> server -> fiber ledger. Configuration alone never opens a connection. */
+export class McpRuntime {
+  readonly projects = new Map<string, Map<string, ProjectDef>>()
+  readonly agents = new Map<any, AgentRecord>()
+  private tail: Promise<unknown> = Promise.resolve()
+  private stopped = false
+  private readonly retired = new WeakSet<object>()
+  private module?: Promise<any>
+
+  /**
+   * Create an idle ledger with an injectable official-plugin resolver.
+   * @public @author ddj 2026年09月28号
+   * @param ctx Host services and lifecycle owner.
+   * @param load Official module resolver, replaceable in targeted tests.
+   */
+  constructor(private readonly ctx: Ctx, private readonly load: McpLoader = loadMcp) {}
+
+  /**
+   * Serialize reconfiguration and creation; a failed operation cannot poison the queue.
+   * @private @author ddj 2026年09月28号
+   * @param action Mutation to execute while the runtime remains live.
+   * @returns Completion of this mutation, including official startup readiness.
+   */
+  private enqueue(action: () => Promise<void>): Promise<void> {
+    const run = async () => { if (!this.stopped) await action() }
+    const next = this.tail.then(run)
+    this.tail = next.catch(() => undefined)
+    return next
+  }
+
+  /**
+   * Find the longest registered workspace containing an agent's cwd.
+   * @public @author ddj 2026年09月28号
+   * @param agent Live agent.
+   * @returns Registered workspace path, or undefined outside managed workspaces.
+   */
+  workspace(agent: any): string | undefined {
+    const paths = (this.ctx.get('workspaceRegistry')?.list?.() ?? []).map((ws: { path: string }) => ws.path)
+    return matchWorkspace(agent?.session?.header?.cwd, paths)
+  }
+
+  /**
+   * Read configured server ownership, including disabled definitions.
+   * @public @author ddj 2026年09月28号
+   * @returns Server name to workspace mapping.
+   */
+  owners(): Map<string, string> {
+    const names = new Map<string, string>()
+    for (const record of this.agents.values()) {
+      for (const [name, instance] of record.instances) names.set(name, instance.path)
+    }
+    for (const [path, defs] of this.projects) for (const name of defs.keys()) names.set(name, path)
+    return names
+  }
+
+  /**
+   * Publish ownership changes before any provider can become visible.
+   * @private @author ddj 2026年09月28号
+   * @sideEffects Refreshes agent restrictions and scoped prompt shadows synchronously.
+   */
+  private changed(): void {
+    this.ctx.emit?.('vscode-mode/mcp-change')
+  }
+
+  /**
+   * Replace one validated file snapshot and update its active agents.
+   * @public @author ddj 2026年09月28号
+   * @param path Registered workspace path.
+   * @param defs Validated source definitions.
+   * @param refresh Optional server whose unchanged fiber must also be recreated.
+   * @returns Completion after old fibers close and replacement startups settle.
+   */
+  replace(path: string, defs: Map<string, ProjectDef>, refresh?: string): Promise<void> {
+    const update = async () => {
+      this.projects.set(path, defs)
+      this.changed()
+      for (const [agent, record] of this.agents) await this.syncAgent(agent, record, refresh)
+      this.changed()
+    }
+    return this.enqueue(update)
+  }
+
+  /**
+   * Attach an agent once and await its project plugin startups.
+   * @public @author ddj 2026年09月28号
+   * @param agent Created or already-active agent.
+   * @returns Completion suitable for the serial agent/created listener.
+   */
+  attach(agent: any): Promise<void> {
+    if (this.stopped || this.retired.has(agent)) return Promise.resolve()
+    let record = this.agents.get(agent)
+    if (!record) {
+      record = { instances: new Map(), live: true }
+      this.agents.set(agent, record)
+    }
+    const target = record
+    const attach = async () => { await this.syncAgent(agent, target); this.changed() }
+    return this.enqueue(attach)
+  }
+
+  /**
+   * Dispose a single connection before releasing its ledger slot.
+   * @private @author ddj 2026年09月28号
+   * @param record Agent ledger.
+   * @param name Server name to stop.
+   * @returns Awaitable Cordis teardown; failures remain visible to the caller.
+   */
+  private async stopOne(record: AgentRecord, name: string): Promise<void> {
+    const instance = record.instances.get(name)
+    if (instance) await this.stopFiber(instance)
+    if (record.instances.get(name) === instance) record.instances.delete(name)
+  }
+
+  /**
+   * Await exact fiber teardown, including a disposer already claimed by its owning scope.
+   * @private @author ddj 2026年09月28号
+   * @param instance Connection ledger entry.
+   * @returns Shared completion of asynchronous Cordis effects.
+   */
+  private stopFiber(instance: Instance): Promise<void> {
+    const close = async () => {
+      const fiber = instance.fiber
+      await fiber?.dispose()
+      while (fiber?.inertia !== undefined) await fiber.inertia
+    }
+    return instance.stopping ??= close()
+  }
+
+  /**
+   * Cancel and drain every fiber owned by a disposed agent.
+   * @public @author ddj 2026年09月28号
+   * @param agent Disposed agent.
+   * @returns Completion of connection cleanup.
+   */
+  async detach(agent: any): Promise<void> {
+    this.retired.add(agent)
+    const record = this.agents.get(agent)
+    if (!record) return
+    record.live = false
+    await Promise.all([...record.instances.keys()].map((name) => this.stopOne(record, name)))
+    this.agents.delete(agent)
+    this.changed()
+  }
+
+  /**
+   * Match the agent ledger to the current enabled definitions.
+   * @private @author ddj 2026年09月28号
+   * @param agent Scoped plugin owner.
+   * @param record Agent ledger.
+   * @param refresh Optional server to reconnect.
+   * @returns Completion of removals and scoped mounts.
+   */
+  private async syncAgent(agent: any, record: AgentRecord, refresh?: string): Promise<void> {
+    if (!record.live || this.stopped) return
+    const path = this.workspace(agent)
+    const defs = this.projects.get(path ?? '') ?? new Map<string, ProjectDef>()
+    for (const [name, instance] of record.instances) {
+      const def = defs.get(name)
+      if (def?.enabled && instance.key === JSON.stringify(def.config) && name !== refresh) continue
+      await this.stopOne(record, name)
+    }
+    for (const [name, def] of defs) {
+      if (!record.live || this.stopped) break
+      if (!def.enabled || record.instances.has(name)) continue
+      await this.mount(agent, record, def.config, path!)
+    }
+  }
+
+  /**
+   * Mount the official plugin through agent.ctx; ACTIVE is not connection evidence.
+   * @private @author ddj 2026年09月28号
+   * @param agent Scoped context owner.
+   * @param record Agent ledger.
+   * @param config Validated source config.
+   * @param path Default stdio working directory.
+   * @returns Settled startup; errors are retained for the project status view.
+   */
+  private async mount(agent: any, record: AgentRecord, config: MpcConfig, path: string): Promise<void> {
+    const instance: Instance = { key: JSON.stringify(config), path }
+    record.instances.set(config.serverName, instance)
+    try {
+      const officialMcp = await (this.module ??= this.load())
+      if (!record.live || this.stopped) return
+      const global = entriesOf(this.ctx).find((entry) => !isProjectEntryId(String(entry.id ?? entry.options?.id ?? '')) && entry.options?.config?.serverName === config.serverName)
+      if (global) throw new Error('serverName 已被全局 MCP 使用：' + config.serverName)
+      const options = config.transport === 'stdio' ? { ...config, cwd: config.cwd || path } : { ...config }
+      instance.fiber = agent.ctx.plugin(officialMcp, options)
+      await instance.fiber
+    } catch (error) {
+      instance.error = String(error)
+      await this.stopFiber(instance)
+      instance.fiber = undefined
+    }
+  }
+
+  /**
+   * Build project status from exact agent scopes without assuming ACTIVE means connected.
+   * @public @author ddj 2026年09月28号
+   * @param path Workspace to summarize.
+   * @returns Masked server views, including configured-only and disabled definitions.
+   */
+  views(path: string): MpcServer[] {
+    const defs = this.projects.get(path) ?? new Map<string, ProjectDef>()
+    return [...defs].map(([name, def]) => this.serverView(path, name, def))
+  }
+
+  /**
+   * Summarize one definition and its connection instances across matching agents.
+   * @private @author ddj 2026年09月28号
+   * @param path Owning workspace.
+   * @param name Server name.
+   * @param def Persisted definition.
+   * @returns Honest status and union of tools visible to its agents.
+   */
+  private serverView(path: string, name: string, def: ProjectDef): MpcServer {
+    const tools = new Map<string, MpcServer['tools'][number]>()
+    const instances: Instance[] = []
+    for (const [agent, record] of this.agents) {
+      if (this.workspace(agent) !== path) continue
+      const instance = record.instances.get(name)
+      if (!instance) continue
+      instances.push(instance)
+      for (const tool of toolsOf(this.ctx, name, agent)) tools.set(tool.name, tool)
+    }
+    const error = instances.find((item) => item.error)?.error
+    const fibers = instances.filter((item) => item.fiber)
+    const failed = error || fibers.some((item) => item.fiber.state === 3)
+    const status = !def.enabled ? 'disabled' : failed ? 'error' : fibers.length === 0 ? 'configured'
+      : fibers.some((item) => item.fiber.state === 1 || item.fiber.state === 0) ? 'connecting' : 'unverified'
+    return {
+      id: projectEntryId(path, name), serverName: name, enabled: def.enabled,
+      transport: def.config.transport, config: publicConfig(def.config as unknown as Record<string, unknown>),
+      status, instanceCount: fibers.length, toolCount: tools.size, tools: [...tools.values()],
+      error: error || (failed ? 'MCP 插件未正常运行' : undefined),
+    }
+  }
+
+  /**
+   * Close every owned connection and prevent queued work from mounting replacements.
+   * @public @author ddj 2026年09月28号
+   * @returns Completion after connection disposal and pending startup work settle.
+   */
+  async dispose(): Promise<void> {
+    this.stopped = true
+    await Promise.all([...this.agents.keys()].map((agent) => this.detach(agent)))
+    await this.tail
+    this.projects.clear()
+    this.module = undefined
+  }
+}
+
+/**
+ * Remove every old global project entry before any agent-scoped mount is attempted.
+ * @public @author ddj 2026年09月28号
+ * @param ctx Host loader context.
+ * @returns Completion of loader removal and connection teardown.
+ */
+export async function clearLegacy(ctx: Ctx): Promise<void> {
+  const loader = ctx.get('loader')
+  for (const entry of entriesOf(ctx)) {
+    if (!isProjectEntryId(String(entry.id ?? entry.options?.id ?? ''))) continue
+    await loader.remove(entry.id)
+  }
+}
+
+/**
+ * Install awaited creation hooks, migrate global entries, and attach existing agents.
+ * @public @author ddj 2026年09月28号
+ * @param ctx Host lifecycle context; installIsolation must already be installed.
+ * @returns Readiness for index.apply to await before advertising startup completion.
+ */
+export async function installMcpRuntime(ctx: Ctx): Promise<void> {
+  const runtime = runtimeOf(ctx)
+  let ready: Promise<void>
+  const initialize = async () => {
+    await clearLegacy(ctx)
+    await listProjects(ctx)
+    for (const agent of ctx.get('agents')?.list?.() ?? []) await runtime.attach(agent)
+  }
+  const created = async ({ agent }: { agent: any }) => {
+    await ready
+    const path = runtime.workspace(agent)
+    if (path) {
+      try { await reconcileProject(ctx, path) }
+      catch (error) { ctx.logger?.warn?.('MCP configuration retained: ' + String(error)) }
+    }
+    await runtime.attach(agent)
+  }
+  const disposed = ({ agent }: { agent: any }) => {
+    void runtime.detach(agent).catch((error) => ctx.logger?.warn?.('MCP disposal failed: ' + String(error)))
+  }
+  const offCreate = ctx.on('agent/created', created)
+  const offDispose = ctx.on('agent/disposed', disposed)
+  const cleanup = async () => {
+    offCreate?.()
+    offDispose?.()
+    await runtime.dispose()
+    runtimes.delete(ctx.root ?? ctx)
+  }
+  ctx.effect(() => cleanup, 'vscode-mode:mcp-runtime')
+  ready = initialize()
+  await ready
+}

package/src/openBridge.ts

@@ -0,0 +1,69 @@
+import { mkdir, readFile, writeFile, rename, unlink } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { assetsDirOf, PLUGIN_ID } from './paths.js'
+import { findProfileDir } from './devForm.js'
+import { checkOpenPath, ensureOpenInbox, secureOpenDir } from './openInbox.js'
+import { INTEGRATION_BASE_DEFAULT } from './shared/integration.js'
+import type { Ctx } from './store.js'
+
+/** @public @author ddj 2026年09月28号
+ * Serialize only public launcher metadata, rejecting INI line injection.
+ * @param baseUrl Selected public Web URL.
+ * @param metadata Profile and local producer metadata.
+ * @returns Complete INI document.
+ */
+export function openIni(baseUrl: string, metadata: Record<string, string> = {}): string {
+  for (const value of [baseUrl, ...Object.values(metadata)]) if (/[\r\n\0]/.test(value)) throw new Error('无效的 launcher 配置')
+  const extra = Object.entries(metadata).map(([key, value]) => key + '=' + value + '\n').join('')
+  return '[dsh]\nbase=' + (baseUrl.trim() || INTEGRATION_BASE_DEFAULT) + '\n' + extra
+}
+
+/** @public @author ddj 2026年09月28号
+ * Write transport metadata and helper without touching OS registration.
+ * @param ctx Active host context.
+ * @param dir Existing launcher or profile bridge directory.
+ * @param baseUrl Configured public Web URL.
+ * @param securedInbox Optional inbox already protected by this caller.
+ */
+export async function writeOpenConfig(ctx: Ctx, dir: string, baseUrl: string, securedInbox?: string): Promise<void> {
+  const profile = findProfileDir(ctx)
+  if (!profile) throw new Error('无法识别当前 DSH profile')
+  const inbox = securedInbox ?? await ensureOpenInbox(profile)
+  const helper = join(dir, 'dsh-open.mjs')
+  await checkOpenPath(dir)
+  await replaceOpen(helper, await readFile(join(assetsDirOf(import.meta.url), 'shell', 'dsh-open.mjs')))
+  const info = ctx.get('profileContext') as { name?: string } | undefined
+  const mode = info?.name === 'desktop' && process.versions.electron ? 'desktop' : 'web'
+  const metadata = { mode, profile, inbox, helper, node: process.execPath, nodeMode: process.versions.electron ? 'electron' : 'node' }
+  await replaceOpen(join(dir, 'dsh-open.ini'), openIni(baseUrl, metadata))
+}
+
+/** @public @author ddj 2026年09月28号
+ * Provision an independent per-profile producer for Unity without a shell-menu marker.
+ * @param ctx Current profile context.
+ * @param baseUrl Selected public Web URL.
+ * @returns Absolute profile bridge INI path.
+ */
+export async function ensureOpenBridge(ctx: Ctx, baseUrl: string): Promise<string> {
+  const profile = findProfileDir(ctx)
+  if (!profile) throw new Error('无法识别当前 DSH profile')
+  const inbox = await ensureOpenInbox(profile)
+  const dir = join(profile, PLUGIN_ID, 'bridge')
+  await mkdir(dir, { recursive: true, mode: 0o700 })
+  await secureOpenDir(dir)
+  await writeOpenConfig(ctx, dir, baseUrl, inbox)
+  return join(dir, 'dsh-open.ini')
+}
+
+/** @private @author ddj 2026年09月28号
+ * Replace a bridge file atomically without following a preexisting file link.
+ * @param path Destination in the validated bridge directory.
+ * @param content Trusted bundled helper or generated metadata.
+ */
+async function replaceOpen(path: string, content: string | Buffer): Promise<void> {
+  await checkOpenPath(dirname(path))
+  const temporary = path + '.' + randomUUID() + '.tmp'
+  await writeFile(temporary, content, { flag: 'wx', mode: 0o600 })
+  try { await rename(temporary, path) } finally { await unlink(temporary).catch(() => {}) }
+}

package/src/openInbox.ts

@@ -0,0 +1,207 @@
+import { spawn } from 'node:child_process'
+import { lstat, mkdir, chmod, open, rename, readdir, unlink } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { findProfileDir } from './devForm.js'
+import { childEnv } from './childEnv.js'
+import { handoffOpen, pendingState, clearPending, cancelPending } from './externalHandoff.js'
+import { OPEN_ID, OPEN_MAX_BYTES, OPEN_TTL_MS, parseInboxOpen } from './shared/externalOpen.js'
+import type { InboxAck, InboxOpen } from './shared/externalOpen.js'
+import type { Ctx } from './store.js'
+
+/** @public @author ddj 2026年09月28号
+ * Resolve the profile-owned open-only directory.
+ * @param profile Absolute active profile directory.
+ * @returns Private inbox root.
+ */
+export function inboxDir(profile: string): string { return join(profile, 'dsh-vscode-mode', 'open-inbox') }
+
+/** @public @author ddj 2026年09月28号
+ * Reject symlink and reparse ancestors before filesystem transport operations.
+ * @param path Existing path to validate.
+ * @throws When any ancestor is a symlink.
+ */
+export async function checkOpenPath(path: string): Promise<void> {
+  let current = resolve(path)
+  for (;;) {
+    const info = await lstat(current)
+    if (info.isSymbolicLink()) throw new Error('外部打开目录不允许符号链接：' + current)
+    const parent = dirname(current)
+    if (parent === current) return
+    current = parent
+  }
+}
+
+/** @private @author ddj 2026年09月28号
+ * Apply a fresh protected ACL granting only the current Windows identity.
+ * @param path Directory being secured.
+ * @returns Completion after PowerShell confirms the ACL.
+ */
+async function lockWindows(path: string): Promise<void> {
+  const literal = "'" + path.replace(/'/g, "''") + "'"
+  const script = [
+    "$ErrorActionPreference='Stop'",
+    "$ProgressPreference='SilentlyContinue'",
+    '$p=' + literal,
+    '$sid=[Security.Principal.WindowsIdentity]::GetCurrent().User',
+    '$a=New-Object Security.AccessControl.DirectorySecurity',
+    '$a.SetAccessRuleProtection($true,$false)',
+    "$r=New-Object Security.AccessControl.FileSystemAccessRule($sid,'FullControl','ContainerInherit,ObjectInherit','None','Allow')",
+    '$a.AddAccessRule($r)',
+    '[IO.Directory]::SetAccessControl($p,$a)',
+  ].join(';')
+  const encoded = Buffer.from(script, 'utf16le').toString('base64')
+  await new Promise<void>((done, fail) => {
+    const child = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-EncodedCommand', encoded], { stdio: ['ignore', 'ignore', 'inherit'], windowsHide: true, env: childEnv(), timeout: 10_000 })
+    child.once('error', fail)
+    child.once('close', (code) => code === 0 ? done() : fail(new Error('无法保护外部打开目录 ACL')))
+  })
+}
+
+/** @public @author ddj 2026年09月28号
+ * Protect an existing transport directory for the current user only.
+ * @param dir Existing directory, with no symlink or reparse ancestors.
+ */
+export async function secureOpenDir(dir: string): Promise<void> {
+  await checkOpenPath(dir)
+  if (process.platform === 'win32') await lockWindows(dir)
+  else await chmod(dir, 0o700)
+}
+
+/** @public @author ddj 2026年09月28号
+ * Create and protect an inbox and both transport subdirectories.
+ * @param profile Active profile directory.
+ * @returns Secured inbox root; throws on unsafe paths or ACL failures.
+ */
+export async function ensureOpenInbox(profile: string): Promise<string> {
+  await checkOpenPath(profile)
+  const root = inboxDir(profile)
+  for (const dir of [dirname(root), root, join(root, 'requests'), join(root, 'acks')]) {
+    try { await lstat(dir); await checkOpenPath(dir) } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+      await mkdir(dir, { mode: 0o700 })
+    }
+    await secureOpenDir(dir)
+  }
+  return root
+}
+
+/** @private @author ddj 2026年09月28号
+ * Read a bounded regular single-link JSON file without accepting inode replacement.
+ * @param path Transport file.
+ * @returns Parsed untrusted JSON.
+ */
+async function readOpenFile(path: string): Promise<unknown> {
+  await checkOpenPath(path)
+  const before = await lstat(path)
+  if (!before.isFile() || before.nlink !== 1 || before.size > OPEN_MAX_BYTES) throw new Error('无效的外部打开文件')
+  if (process.platform !== 'win32' && ((before.mode & 0o077) !== 0 || before.uid !== process.getuid?.())) throw new Error('外部打开文件权限不安全')
+  const handle = await open(path, 'r')
+  try {
+    const after = await handle.stat()
+    if (after.ino !== before.ino || after.dev !== before.dev || after.nlink !== 1 || after.size > OPEN_MAX_BYTES) throw new Error('外部打开文件已替换')
+    const buffer = Buffer.alloc(OPEN_MAX_BYTES + 1)
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0)
+    if (bytesRead > OPEN_MAX_BYTES) throw new Error('外部打开文件过大')
+    return JSON.parse(buffer.subarray(0, bytesRead).toString('utf8'))
+  } finally { await handle.close() }
+}
+
+/** @private @author ddj 2026年09月28号
+ * Atomically publish a bounded terminal receipt inside the private ACK directory.
+ * @param root Inbox root.
+ * @param request Original validated request.
+ * @param success Whether the editor confirmed success.
+ * @param error Optional terminal diagnostic.
+ */
+async function writeOpenAck(root: string, requestId: string, profile: string, success: boolean, error?: string): Promise<void> {
+  const dir = join(root, 'acks')
+  await checkOpenPath(dir)
+  const ack: InboxAck = { version: 1, requestId, profile, createdAt: Date.now(), success, error }
+  const temp = join(dir, requestId + '.' + randomUUID() + '.tmp')
+  const handle = await open(temp, 'wx', 0o600)
+  try { await handle.writeFile(JSON.stringify(ack), 'utf8') } finally { await handle.close() }
+  try { await rename(temp, join(dir, requestId + '.json')) } finally { await unlink(temp).catch(() => {}) }
+}
+
+/** @private @author ddj 2026年09月28号
+ * Check for an existing terminal receipt without following links.
+ * @param root Inbox root.
+ * @param name Request file name.
+ * @returns Whether this request already has a receipt.
+ */
+async function ackExists(root: string, name: string): Promise<boolean> {
+  try { await lstat(join(root, 'acks', name)); return true } catch { return false }
+}
+
+/** @private @author ddj 2026年09月28号
+ * Consume validated request files once, retaining request identity until an actual ACK.
+ * @param root Inbox root.
+ * @param profile Expected profile.
+ * @param active Accepted requests awaiting completion.
+ * @param live Whether the owning lifecycle is still active.
+ */
+async function loadOpenFiles(root: string, profile: string, active: Map<string, InboxOpen>, live: () => boolean): Promise<void> {
+  const dir = join(root, 'requests')
+  await checkOpenPath(dir)
+  const names = (await readdir(dir)).filter((name) => name.endsWith('.json')).sort().slice(0, 128)
+  for (const name of names) {
+    if (!OPEN_ID.test(name.slice(0, -5))) continue
+    const file = join(dir, name)
+    try {
+      const raw = await readOpenFile(file)
+      const request = parseInboxOpen(raw, profile)
+      if (request && request.requestId + '.json' === name && !active.has(request.requestId)) {
+        if (!await ackExists(root, name)) {
+          if (!live()) return
+          handoffOpen(request, request.requestId, request.createdAt)
+          active.set(request.requestId, request)
+        }
+      } else if (!request) {
+        // A rejected request must not stay silent until its producer times out.
+        const declared = (raw as { profile?: unknown })?.profile
+        if (typeof declared === 'string' && !await ackExists(root, name)) {
+          if (!live()) return
+          await writeOpenAck(root, name.slice(0, -5), declared, false, '请求被拒绝：profile 与当前实例不匹配或字段不合法')
+        }
+      }
+      if (!live()) return
+      await unlink(file)
+    } catch { /* Unsafe, malformed, or inaccessible files are not followed or executed. */ }
+  }
+}
+
+/** @public @author ddj 2026年09月28号
+ * Poll one private profile inbox; disposal stops all intervals and queued work.
+ * @param ctx Host context exposing the active profile.
+ * @returns Asynchronous setup of the lifecycle disposer.
+ */
+export async function startOpenInbox(ctx: Ctx): Promise<() => void> {
+  const profile = findProfileDir(ctx)
+  if (!profile) return () => {}
+  const root = await ensureOpenInbox(profile)
+  const active = new Map<string, InboxOpen>()
+  let disposed = false
+  let running = false
+  /** @private @author ddj 2026年09月28号 Consume requests and publish only terminal results. */
+  async function tick(): Promise<void> {
+    if (disposed || running) return
+    running = true
+    try {
+      await loadOpenFiles(root, profile!, active, () => !disposed)
+      for (const [id, request] of active) {
+        if (disposed) break
+        const result = pendingState(id)
+        const expired = Date.now() >= request.createdAt + OPEN_TTL_MS
+        if (!result.completed && !expired) continue
+        if (!result.delivered || expired) cancelPending(id, result.error)
+        await writeOpenAck(root, request.requestId, request.profile, result.delivered && !expired, result.error ?? (expired ? '打开超时，请重试' : undefined))
+        active.delete(id)
+      }
+    } finally { running = false }
+  }
+  const timer = setInterval(() => { void tick().catch(() => {}) }, 400)
+  timer.unref?.()
+  void tick().catch(() => {})
+  return () => { disposed = true; clearInterval(timer); active.clear(); clearPending() }
+}

package/src/paths.ts

@@ -11,7 +11,7 @@
  */
 import { createHash } from 'node:crypto'
 import { homedir } from 'node:os'
-import { dirname, join } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { readdir, rm, stat } from 'node:fs/promises'
 import { RPC_PATH } from './shared/rpc.js'
@@ -117,15 +117,18 @@ export function sessionsRoot(home = dshHome()): string {
 // --endregion
 
 /**
- * 解析 DSH home：DSH_HOME（去空白）→ ~/.dsh。
- * @author ddj 2026年09月01号
+ * 解析 DSH home：空白环境值视为未设置，展开 ~ 并解析绝对路径。
+ * @public
+ * @author ddj 2026年09月28号
  * @param env 环境映射（缺省 process.env；测试可注入）
  * @returns 归一化的 DSH home 绝对路径
  */
 export function dshHome(env: Record<string, string | undefined> = process.env): string {
   const value = env[DSH_HOME_ENV]
-  if (value && value.trim()) return value
-  return join(homedir(), DSH_DIR_NAME)
+  const path = value && value.trim() ? value : join(homedir(), DSH_DIR_NAME)
+  if (path === '~') return resolve(homedir())
+  if (path.startsWith('~/') || path.startsWith('~\\')) return resolve(join(homedir(), path.slice(2)))
+  return resolve(path)
 }
 
 /** 插件缓存根（~/.dsh/dsh-vscode-mode/cache，下分 workspace/ 与 user/ 两级）。 */