dsh-vscode-mode 0.16.0 → 0.18.0

package/src/client/ui/PluginDetailSection.ts

@@ -0,0 +1,82 @@
+// @ts-nocheck
+/**
+ * dsh-vscode-mode client — 官方插件管理器详情页的只读状态段。
+ * 挂在 DSH 0.2.1 新增的 `plugins.detail.section`（list / root）扩展位上，
+ * 只在「本插件自己」的详情页渲染，其余插件页返回 null。
+ * 作者 ddj 2026年10月19号
+ */
+import React from 'react'
+import { rpc } from '../rpc.js'
+
+/** 本插件标识（与 package.json name / bundle 行 id 一致）。 */
+export const SELF_ID = 'dsh-vscode-mode'
+
+/**
+ * 判断详情页 subject 是否指向本插件。
+ * 官方有两种形状：官方内置项 `{kind:'item', id}`、安装包 `{kind:'bundle', pkg:{name}}`。
+ * @author ddj 2026年10月19号
+ * @param subject 详情页主题
+ * @returns 是否为本插件
+ */
+export function isSelfSubject(subject) {
+  if (!subject || typeof subject !== 'object') return false
+  if (subject.kind === 'item') return subject.id === SELF_ID
+  if (subject.kind === 'bundle') return subject.pkg?.name === SELF_ID
+  return false
+}
+
+/**
+ * 把适配项列表压成「正常 / 未生效」计数文案。
+ * @author ddj 2026年10月19号
+ * @param list 适配项数组
+ * @returns 计数文案
+ */
+function countText(list) {
+  const items = Array.isArray(list) ? list : []
+  const ok = items.filter((item) => item?.active === true).length
+  return ok + ' / ' + items.length + ' 项生效'
+}
+
+/**
+ * 插件详情页的只读状态段。
+ * @author ddj 2026年10月19号
+ * @param props DSH 注入的 { subject }
+ * @returns 状态段元素或 null（非本插件页）
+ */
+export function PluginDetailSection(props) {
+  const subject = props?.subject
+  const isSelf = isSelfSubject(subject)
+  const [report, setReport] = React.useState(null)
+
+  React.useEffect(() => {
+    if (!isSelf) return undefined
+    let alive = true
+    rpc('compat', {}).then((result) => {
+      if (!alive || !result || !result.ok) return
+      setReport(result.report ?? null)
+    }).catch(() => { /* 状态段属锦上添花，取不到就不显示 */ })
+    return () => { alive = false }
+  }, [isSelf])
+
+  if (!isSelf) return null
+
+  const row = (name, note) => React.createElement('div', { key: name, className: 'vsm-compat-item ok' },
+    React.createElement('span', { className: 'vsm-compat-name' }, name),
+    React.createElement('span', { className: 'vsm-compat-note' }, note),
+  )
+
+  const versionText = report?.dshVersion ? 'DSH ' + report.dshVersion : '未探测到 DSH 版本'
+  const pluginText = report?.pluginVersion ? '插件 ' + report.pluginVersion : '插件版本未上报'
+  const warnCount = Array.isArray(report?.warnings) ? report.warnings.length : 0
+
+  return React.createElement('section', { className: 'vsm-panel', 'data-edrv-plugin-status': '1' },
+    React.createElement('h3', { className: 'vsm-panel-title' }, 'VSCodeMode 运行状态'),
+    React.createElement('div', { className: 'vsm-panel-body' },
+      row('版本', versionText + ' · ' + pluginText),
+      row('版本适配', countText(report?.adapters)),
+      row('外部插件与服务', countText(report?.external)),
+      row('护栏', countText(report?.guards)),
+      row('兼容性警告', warnCount ? warnCount + ' 条（设置页「兼容性」可查看详情）' : '未检测到'),
+    ),
+  )
+}

package/src/dshVersion.ts

@@ -84,14 +84,16 @@ export function inDshRange(version: DshVersion | null | undefined, range: DshRan
 
 /**
  * 版本线标签：报告与文档展示版本归属；不可解析返回 '未知'。
- * 逐线自新到旧匹配，先命中先返回；仅已静态审计的 0.2.0-rc.1/rc.2 精确标记。
- * @author ddj 2026年09月02号 / 2026年09月18号 / 2026年09月22号 / 2026年09月29号 / 2026年10月08号
+ * 逐线自新到旧匹配，先命中先返回；仅已静态审计的 0.2.0-rc.1/rc.2、0.2.1-rc.2 精确标记。
+ * @author ddj 2026年09月02号 / 2026年09月18号 / 2026年09月22号 / 2026年09月29号 / 2026年10月08号 / 2026年10月19号
  * @param input 版本串（如 '0.1.6-alpha.2'）
  * @returns 版本线标签
  */
 export function familyLabel(input: string): string {
   const version = parseDshVersion(input)
   if (!version) return '未知'
+  if (inDshRange(version, { from: '0.2.1-rc.2', to: '0.2.1-rc.2' })) return '0.2.1-rc.2（设置=profile Config；workingDirectory 投影跟随 cd；plugins.detail 扩展位；按能力探测）'
+  if (inDshRange(version, { from: '0.2.1-0', to: '0.2.1' })) return '0.2.1 线（rc.2 已逐版适配，其余按能力探测）'
   if (inDshRange(version, { from: '0.2.0-rc.2', to: '0.2.0-rc.2' })) return '0.2.0-rc.2（设置=profile Config；按能力探测）'
   if (inDshRange(version, { from: '0.2.0-rc.1', to: '0.2.0-rc.1' })) return '0.2.0-rc.1（设置=profile Config；按能力探测）'
   if (inDshRange(version, { from: '0.2.0-0' })) return '0.2.0 及更新（除 rc.1/rc.2 外未经逐版适配；按能力探测）'

package/src/fileVersions.ts

@@ -20,7 +20,7 @@
  */
 import type { FileVersionItem } from './shared/rpc.js'
 import type { Ctx } from './store.js'
-import { cwdOf, sessionOf } from './registry.js'
+import { cwdOfSession, sessionOf } from './registry.js'
 import { invalidateIndex } from './treeIndex.js'
 import { log } from './log.js'
 
@@ -150,7 +150,7 @@ export function createFileVersions(ctx: Ctx): FileVersions {
       .slice(0, MAX_PATHS)
     if (!fs || !paths.length) return { ok: true, items: [] }
     const session = sessionOf(ctx, args.sessionId)
-    const cwd = cwdOf(session)
+    const cwd = cwdOfSession(ctx, session)
     const items: FileVersionItem[] = []
     for (const path of paths) items.push(await observe(fs, cwd, path))
     return { ok: true, items }

package/src/lsp/rpc.ts

@@ -7,7 +7,7 @@
  */
 import type { Ctx } from '../store.js'
 import { searchRoot } from '../search/ripgrep.js'
-import { sessionOf, cwdOf } from '../registry.js'
+import { cwdOfSession, sessionOf } from '../registry.js'
 import { resolveProviderSpec, langOfPath, configFromPlugin, mergeConfig, sanitizeLang, LSP_LANGUAGES, type LspConfig, type LspLangConfig } from './config.js'
 import { clearProviderCache, candidatesFor } from './providers.js'
 import { capCompletions } from './completionCap.js'
@@ -154,7 +154,7 @@ export function createLspRpc(deps: LspRpcDeps): { handlers: Partial<RpcHandlerMa
   const rootOf = async (sessionId: string | undefined): Promise<{ root: string; sessionId: string } | { err: string }> => {
     const session = sessionOf(ctx, sessionId)
     if (!session) return { err: SESSION_MISSING_ERROR }
-    const cwd = cwdOf(session)
+    const cwd = cwdOfSession(ctx, session)
     if (!cwd) return { err: SESSION_NO_WORKSPACE_ERROR }
     try {
       const root = await searchRoot(ctx, session)

package/src/mcp.ts

@@ -218,6 +218,7 @@ export async function saveMcp(ctx: Ctx, config: MpcConfig): Promise<MpcServer> {
 
 /** @private @author ddj 2026年10月08号 @param ctx Host services. @param config Configuration. @returns Saved status; validation failures do not write. */
 async function saveGlobal(ctx: Ctx, config: MpcConfig): Promise<MpcServer> {
+  if (config && 'vscodeMode' in config) throw new Error('vscodeMode 启动和共享策略仅适用于项目 MCP')
   validateConfig(config)
   await checkMcpName(ctx, config.serverName)
   const loader = ctx.get('loader')

package/src/mcpBridge.ts

@@ -0,0 +1,163 @@
+/** Private official-MCP registrations, never a global provider. @author ddj 2026年10月20号 */
+import { loadHostModule } from './hostImport.js'
+import type { Ctx } from './store.js'
+import type { McpPool, PoolEntry } from './mcpPool.js'
+
+export interface BridgeScope {
+  ctx: any
+  dispose(): Promise<void>
+}
+export interface McpSection {
+  name: string
+  order: number
+  interpolate?: boolean
+  text: string | ((context?: any) => string)
+}
+export interface McpProvider {
+  request(request: any, execution: any): Promise<any>
+}
+export type ScopeMaker = (ctx: any, key: object) => BridgeScope
+
+/** Per-agent public surface; original definitions still run inside the normal registry pipeline. */
+export class McpBinding {
+  private readonly removals: Array<() => void> = []
+  private unsubscribe?: () => void
+  private closed = false
+
+  /** @public @author ddj 2026年10月20号 @param agent Public scope. @param pool Connection owner. @param entry Exact generation. @param valid Authorization recheck. */
+  constructor(private readonly agent: any, private readonly pool: McpPool, private readonly entry: PoolEntry, private readonly valid: () => boolean, private readonly called?: (elapsed: number) => void) {}
+
+  /** @private @author ddj 2026年10月20号 @param execution Registry caller. @throws Stale generation or foreign caller. */
+  private check(execution?: any): void {
+    if (this.closed || !this.valid() || !this.entry.live || (execution && execution.agent !== this.agent)) throw new Error('项目 MCP 作用域或配置已失效')
+  }
+
+  /** @public @author ddj 2026年10月20号 Reconciles exact definitions after official tool-list updates. */
+  sync(): void {
+    this.check()
+    const bridge = this.entry.bridge
+    if (!bridge) return
+    // Resources and instructions can change independently of tool names; replace the whole small scoped surface.
+    this.clear()
+    for (const [name, definition] of bridge.tools) {
+      /** @author ddj 2026年10月20号 @param args Registry-validated arguments. @param execution Unmodified caller context. @returns Official canonical output. */
+      const execute = async (args: unknown, execution: any): Promise<unknown> => {
+        this.check(execution)
+        return this.pool.run(this.entry, async () => {
+          this.check(execution)
+          if (bridge.tools.get(name) !== definition) throw new Error('MCP 工具定义已更新，请重新发现')
+          const startedAt = Date.now()
+          const result = await definition.execute(args, execution)
+          this.called?.(Date.now() - startedAt)
+          return result
+        }, execution.signal)
+      }
+      this.removals.push(this.agent.ctx.get('tools').register({ ...definition, execute }))
+    }
+    // Resource ownership stays with the runtime's single lazy provider, avoiding duplicate namespace registration.
+    for (const section of bridge.sections.values()) {
+      /** @author ddj 2026年10月20号 @param context Actual prompt assembly. @returns Only valid-generation instructions. */
+      const text = (context: any): string => {
+        if (!this.valid() || this.closed) return ''
+        if (typeof section.text === 'function') return section.text(context)
+        return section.text
+      }
+      this.removals.push(this.agent.ctx.get('systemPrompt').section({ ...section, text }))
+    }
+    /** @author ddj 2026年10月20号 Reconciles dynamic official registrations only for a live subscriber. */
+    const update = (): void => { if (!this.closed && this.valid() && this.entry.live) this.sync() }
+    if (!this.unsubscribe) this.unsubscribe = bridge.subscribe(update)
+  }
+
+  /** @private @author ddj 2026年10月20号 Removes only this binding's exact scoped registrations. */
+  private clear(): void {
+    for (const remove of this.removals.splice(0).reverse()) remove()
+  }
+
+  /** @public @author ddj 2026年10月20号 Revokes proxies synchronously before releasing a lease. */
+  dispose(): void {
+    this.closed = true
+    this.unsubscribe?.()
+    this.unsubscribe = undefined
+    this.clear()
+  }
+}
+
+/** A connection's private surface. Public consumers register scoped proxies, not this scope. */
+export class McpBridge {
+  readonly tools = new Map<string, any>()
+  readonly resources = new Map<string, McpProvider>()
+  readonly sections = new Map<string, McpSection>()
+  private readonly listeners = new Set<() => void>()
+  private closed = false
+  private closing?: Promise<void>
+
+  /** @private @author ddj 2026年10月20号 @param scope Private lifetime and registration context. */
+  private constructor(readonly scope: BridgeScope) {}
+
+  /** @public @author ddj 2026年10月20号 @param ctx Host owner. @param make Optional real scope factory for installed-host tests. @returns Isolated registration adapter. */
+  static async create(ctx: Ctx, make?: ScopeMaker): Promise<McpBridge> {
+    const factory = make ?? (await loadHostModule('@deepseek-ai/dsh-scope') as { createScope: ScopeMaker }).createScope
+    const scope = factory(ctx, {})
+    // Providers must be installed after the backing scope's initial activation transaction.
+    await scope.ctx.fiber?.await?.()
+    const bridge = new McpBridge(scope)
+    bridge.install()
+    return bridge
+  }
+
+  /** @private @author ddj 2026年10月20号 Installs only private services; no project registration reaches the root. */
+  private install(): void {
+    const privateCtx = this.scope.ctx.isolate('tools').isolate('mcpResources').isolate('systemPrompt')
+    privateCtx.provide('tools', { register: (definition: any) => this.register(this.tools, definition.name, definition) })
+    privateCtx.provide('mcpResources', { register: (name: string, provider: McpProvider) => this.register(this.resources, name, provider) })
+    privateCtx.provide('systemPrompt', {
+      getSectionOrder: () => 3100,
+      section: (section: McpSection) => this.register(this.sections, section.name, section),
+    })
+    this.scope.ctx = privateCtx
+  }
+
+  /** @private @author ddj 2026年10月20号 @param registry Private generation map. @param name Stable registration name. @param entry Exact value. @returns Exact-entry removal, safe after replacement. */
+  private register<T>(registry: Map<string, T>, name: string, entry: T): () => void {
+    if (this.closed) throw new Error('MCP bridge is disposed')
+    if (registry.has(name)) throw new Error('Duplicate private MCP registration: ' + name)
+    registry.set(name, entry)
+    this.changed()
+
+    return () => {
+      if (registry.get(name) !== entry) return
+      registry.delete(name)
+      this.changed()
+    }
+  }
+
+  /** @public @author ddj 2026年10月20号 @param listener Surface change subscriber. @returns Subscription disposer. */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  /** @private @author ddj 2026年10月20号 Notifies consumers; observer errors cannot corrupt the official sync transaction. */
+  private changed(): void {
+    for (const listener of this.listeners) {
+      try { listener() } catch { /* Runtime owns diagnostics for its subscriber. */ }
+    }
+  }
+
+  /** @public @author ddj 2026年10月20号 @returns Quiescent private-scope teardown. */
+  dispose(): Promise<void> {
+    this.closed = true
+    return this.closing ??= this.closeScope()
+  }
+
+  /** @private @author ddj 2026年10月20号 @returns Exact scope closure before forgetting registrations. */
+  private async closeScope(): Promise<void> {
+    await this.scope.dispose()
+    this.tools.clear()
+    this.resources.clear()
+    this.sections.clear()
+    this.changed()
+    this.listeners.clear()
+  }
+}

package/src/mcpDiscover.ts

@@ -0,0 +1,38 @@
+/** Scoped capability discovery; never accepts commands, paths or caller identity. @author ddj 2026年10月20号 */
+import type { McpRuntime } from './mcpRuntime.js'
+
+/** @public @author ddj 2026年10月20号 @param runtime Authorized runtime. @param ctx Host registration context. @returns Global discovery cleanup; normal capability filters remain authoritative. */
+export function installDiscover(runtime: McpRuntime, ctx: any): () => void {
+  const tools = ctx.get('tools')
+  /** @author ddj 2026年10月20号 @param args Validated operation. @param execution Registry-owned caller identity. @returns Safe capability catalogue or real connected schemas. */
+  const execute = async (args: any, execution: any): Promise<unknown> => {
+    const agent = execution.agent
+    if (!agent || !runtime.agents.has(agent)) throw new Error('会话未激活，不能使用项目 MCP 发现入口')
+    if (!args || typeof args !== 'object' || Array.isArray(args) || Object.keys(args).some((key) => !['action', 'serverName'].includes(key))) throw new Error('发现入口仅接受 action 和 serverName')
+    if (!['list', 'connect'].includes(args.action)) throw new Error('action 必须为 list 或 connect')
+    if (args.action === 'list') return runtime.catalogue(agent)
+    if (typeof args.serverName !== 'string') throw new Error('请指定已配置的 serverName')
+    return runtime.connect(agent, args.serverName, execution.signal)
+  }
+  /** @author ddj 2026年10月20号 @param _args Unused. @param result Safe canonical JSON. @returns Native content without bypassing output validation. */
+  const render = (_args: unknown, result: unknown): any[] => [{ type: 'text', text: JSON.stringify(result) }]
+  const removeTool = tools.register({
+    name: 'discover_project_mcp', description: 'List this workspace’s configured project MCP services without starting them, or connect one to discover its real tools. After connecting, call discovered tools in the NEXT request/program; never guess schemas. Global/preset MCPs are not included.',
+    parameters: { type: 'object', properties: { action: { type: 'string', enum: ['list', 'connect'] }, serverName: { type: 'string' } }, required: ['action'], additionalProperties: false },
+    output: { schema: {}, render }, execute,
+  })
+  return removeTool
+}
+
+/** @public @author ddj 2026年10月20号 @param runtime Active owners. @param agent Scoped catalogue owner. @returns Scoped instruction cleanup; does not register a tool override. */
+export function discoverPrompt(runtime: McpRuntime, agent: any): () => void {
+  const prompt = agent.ctx.get('systemPrompt')
+  /** @author ddj 2026年10月20号 @returns Current enabled names only; no credential-bearing configuration. */
+  const text = (): string => {
+    const names = runtime.catalogue(agent).map((server) => server.serverName)
+    if (!names.length) return ''
+    return 'Project MCP capabilities (may not be started): ' + JSON.stringify(names) + '. Use discover_project_mcp action=list, then action=connect with serverName when needed. Only use returned real tool schemas. Native tools appear on the next model request; PTC must finish the current program and start a new program to refresh its SDK. Do not eval or bypass tool approval.'
+  }
+  const removePrompt = prompt.section({ name: 'vscode-mode:project-mcp', order: 3090, text, interpolate: false })
+  return removePrompt
+}

package/src/mcpPool.ts

@@ -0,0 +1,245 @@
+/** Connection ownership, bounded cold starts and workspace leases. @author ddj 2026年10月20号 */
+import { createHash } from 'node:crypto'
+import { McpBridge } from './mcpBridge.js'
+import type { McpPolicy, McpPhase, MpcConfig } from './shared/mcp.js'
+import type { Ctx } from './store.js'
+
+export interface PoolSpec {
+  workspace: string
+  owner: object
+  config: MpcConfig
+  policy: McpPolicy
+}
+export interface PoolEntry {
+  key: string
+  spec: PoolSpec
+  refs: number
+  phase: McpPhase
+  queuedAt: number
+  phaseAt: number
+  finishedAt?: number
+  startAt?: number
+  connectedAt?: number
+  error?: string
+  retryAt?: number
+  bridge?: McpBridge
+  fiber?: any
+  ready: Promise<void>
+  close?: Promise<void>
+  idle?: ReturnType<typeof setTimeout>
+  live: boolean
+  calls: Promise<unknown>
+}
+export interface PoolLease {
+  entry: PoolEntry
+  release(): void
+}
+export type BridgeMaker = () => Promise<McpBridge>
+
+/** @private @author ddj 2026年10月20号 @param input Plain effective configuration. @returns Stable secret-bearing identity used only as digest input. */
+function stableConfig(input: unknown): string {
+  if (Array.isArray(input)) return '[' + input.map(stableConfig).join(',') + ']'
+  if (input && typeof input === 'object') {
+    const config = input as Record<string, unknown>
+    return '{' + Object.keys(config).sort().map((key) => JSON.stringify(key) + ':' + stableConfig(config[key])).join(',') + '}'
+  }
+  return JSON.stringify(input) ?? 'null'
+}
+
+/** @public @author ddj 2026年10月20号 @param task Shared work that must remain alive for other waiters. @param signal One waiter's cancellation. @returns Caller-local wait without abandoning owned pool work. */
+export function waitMcp<T>(task: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return task
+  return new Promise<T>((resolve, reject) => {
+    /** @author ddj 2026年10月20号 Rejects only this waiter. */
+    const abort = (): void => { reject(new Error('MCP 等待已取消')) }
+    if (signal.aborted) { abort(); return }
+    signal.addEventListener('abort', abort, { once: true })
+    task.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort))
+  })
+}
+
+/** The pool owns private scopes independently from any first subscriber. */
+export class McpPool {
+  readonly entries = new Map<string, PoolEntry>()
+  private readonly owners = new WeakMap<object, number>()
+  private ownerSeq = 0
+  private running = 0
+  private readonly queue: Array<() => Promise<void>> = []
+  private readonly jobs = new Set<Promise<void>>()
+  private stopped = false
+
+  /** @public @author ddj 2026年10月20号 @param ctx Host lifecycle owner. @param load Official plugin loader. @param make Private scope factory. */
+  constructor(private readonly ctx: Ctx, private readonly load: () => Promise<any>, private readonly make: BridgeMaker = () => McpBridge.create(ctx)) {}
+
+  /** @private @author ddj 2026年10月20号 @param spec Effective request. @returns Private digest; never emit configuration or secrets. */
+  private keyOf(spec: PoolSpec): string {
+    let owner = 0
+    if (spec.policy.sharing === 'agent') {
+      if (!this.owners.has(spec.owner)) this.owners.set(spec.owner, ++this.ownerSeq)
+      owner = this.owners.get(spec.owner)!
+    }
+    const workspace = process.platform === 'win32' ? spec.workspace.replace(/\\/g, '/').toLowerCase() : spec.workspace
+    return createHash('sha256').update(stableConfig([workspace, owner, spec.config, spec.policy])).digest('hex')
+  }
+
+  /** @public @author ddj 2026年10月20号 @param spec Authorized connection request. @returns Reference-counted single-flight lease. */
+  acquire(spec: PoolSpec): PoolLease {
+    if (this.stopped) throw new Error('MCP runtime is disposed')
+    const key = this.keyOf(spec)
+    let entry = this.entries.get(key)
+    if (entry?.phase === 'error' && entry.retryAt !== undefined && Date.now() >= entry.retryAt && !entry.close) {
+      this.entries.delete(key)
+      entry = undefined
+    }
+    if (entry && !entry.live) throw new Error(entry.error ?? 'MCP 旧连接仍在释放，暂不能创建替代实例')
+    if (!entry) {
+      entry = { key, spec, refs: 0, phase: 'queued', queuedAt: Date.now(), phaseAt: Date.now(), ready: Promise.resolve(), live: true, calls: Promise.resolve() }
+      this.entries.set(key, entry)
+      entry.ready = this.schedule(entry)
+      void entry.ready.catch(() => undefined)
+    }
+    if (entry.idle) clearTimeout(entry.idle)
+    entry.idle = undefined
+    entry.refs += 1
+    let released = false
+    return { entry, release: () => {
+      if (released) return
+      released = true
+      this.release(entry!)
+    } }
+  }
+
+  /** @private @author ddj 2026年10月20号 @param entry New entry. @returns Queued initialization, bounded to two concurrent starts. */
+  private schedule(entry: PoolEntry): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      /** @author ddj 2026年10月20号 Initializes a still-owned queue item. */
+      const run = async (): Promise<void> => {
+        try { await this.start(entry); resolve() } catch (error) { reject(error) }
+      }
+      this.queue.push(run)
+      this.pump()
+    })
+  }
+
+  /** @private @author ddj 2026年10月20号 Advances FIFO work; each task holds its slot until startup or cleanup quiesces. */
+  private pump(): void {
+    while (this.running < 2 && this.queue.length) {
+      const run = this.queue.shift()!
+      this.running += 1
+      const job = run().finally(() => {
+        this.running -= 1
+        this.jobs.delete(job)
+        this.pump()
+      })
+      this.jobs.add(job)
+    }
+  }
+
+  /** @private @author ddj 2026年10月20号 @param entry Connection to initialize. @returns Initialization completion, or failure after owned cleanup. */
+  private async start(entry: PoolEntry): Promise<void> {
+    if (!entry.live || this.stopped) throw new Error('MCP 启动已取消')
+    entry.phase = 'loading'
+    entry.phaseAt = Date.now()
+    entry.startAt = entry.phaseAt
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const work = this.mount(entry)
+    const deadline = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => reject(new Error('MCP 初始化超时')), entry.spec.policy.startupTimeoutMs)
+      timer.unref?.()
+    })
+    try {
+      await Promise.race([work, deadline])
+      if (!entry.live) throw new Error('MCP 启动已取消')
+      entry.phase = 'ready'
+      entry.finishedAt = Date.now()
+      entry.connectedAt = entry.finishedAt
+    } catch (error) {
+      entry.error = 'MCP 初始化失败或超时，请查看 Host 日志'
+      this.ctx.logger?.warn?.('MCP initialization failed: ' + String(error))
+      // Invalidation precedes disposal; neither late module load nor callbacks may publish.
+      entry.live = false
+      entry.phase = 'stopping'
+      const closing = this.closeBridge(entry)
+      await Promise.allSettled([closing, work])
+      entry.phase = 'error'
+      entry.finishedAt = Date.now()
+      entry.retryAt = Date.now() + 5000
+      // Failed generations stay invalid; acquire can replace them only after confirmed closure and cooldown.
+      throw new Error(entry.error)
+    } finally {
+      if (timer) clearTimeout(timer)
+    }
+  }
+
+  /** @private @author ddj 2026年10月20号 @param entry Owned generation. @returns Official initial sync; never publishes after invalidation. */
+  private async mount(entry: PoolEntry): Promise<void> {
+    const official = await this.load()
+    if (!entry.live || this.stopped) return
+    const bridge = await this.make()
+    if (!entry.live || this.stopped) { await bridge.dispose(); return }
+    entry.bridge = bridge
+    entry.phase = 'starting'
+    entry.phaseAt = Date.now()
+    entry.fiber = bridge.scope.ctx.plugin(official, entry.spec.config)
+    await entry.fiber
+    if (entry.fiber?.state !== undefined && entry.fiber.state !== 2) throw new Error('MCP 插件未完成激活')
+  }
+
+  /** @private @author ddj 2026年10月20号 @param entry Connection to close. @returns Shared closure barrier; rejection retains a fenced entry. */
+  private async closeBridge(entry: PoolEntry): Promise<void> {
+    if (entry.close) return entry.close
+    const close = entry.bridge?.dispose() ?? Promise.resolve()
+    entry.close = close
+    try {
+      await close
+      entry.bridge = undefined
+      entry.fiber = undefined
+      entry.close = undefined
+    } catch (error) {
+      entry.error = 'MCP 释放未确认，禁止重建，请查看 Host 日志'
+      this.ctx.logger?.warn?.('MCP cleanup failed: ' + String(error))
+      throw error
+    }
+  }
+
+  /** @private @author ddj 2026年10月20号 @param entry One lease's owner. Arms workspace-only warm retention. */
+  private release(entry: PoolEntry): void {
+    entry.refs = Math.max(0, entry.refs - 1)
+    if (entry.refs || !entry.live) return
+    if (entry.spec.policy.sharing === 'agent') { void this.retire(entry).catch(() => undefined); return }
+    entry.idle = setTimeout(() => { void this.retire(entry).catch(() => undefined) }, 60000)
+    entry.idle.unref?.()
+  }
+
+  /** @public @author ddj 2026年10月20号 @param entry Invalid generation. @returns Quiescent close; callers may await before starting a replacement. */
+  async retire(entry: PoolEntry): Promise<void> {
+    entry.live = false
+    entry.phase = 'stopping'
+    if (entry.idle) clearTimeout(entry.idle)
+    await this.closeBridge(entry)
+    await entry.ready.catch(() => undefined)
+    // A late mount checks live before assigning its bridge.
+    await entry.calls.catch(() => undefined)
+    if (this.entries.get(entry.key) === entry) this.entries.delete(entry.key)
+  }
+
+  /** @public @author ddj 2026年10月20号 @param entry Authorized connection. @param action Per-call work retaining original execution identity. @param signal Caller cancellation. @returns Serialized shared result; no direct registry bypass is introduced here. */
+  run<T>(entry: PoolEntry, action: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+    /** @author ddj 2026年10月20号 Checks cancellation and generation again at actual dispatch. */
+    const invoke = async (): Promise<T> => {
+      await waitMcp(entry.ready, signal)
+      if (signal?.aborted || !entry.live || entry.phase !== 'ready') throw new Error('MCP 连接不可用或调用已取消')
+      return action()
+    }
+    const result = entry.calls.then(invoke)
+    entry.calls = result.catch(() => undefined)
+    return result
+  }
+
+  /** @public @author ddj 2026年10月20号 @returns Full disposal of entries, queue, timers and owned work. */
+  async dispose(): Promise<void> {
+    this.stopped = true
+    await Promise.all([...this.entries.values()].map((entry) => this.retire(entry)))
+    await Promise.all([...this.jobs])
+  }
+}