F2: 共有 MCP トランスポートプール — 設計 v2.2

acpAgent.newSession(sessionId)
  → newSessionConfig(cwd, mcpServers)                  // acpAgent.ts:1771
  → loadCliConfig → new Config → config.initialize()
  → ToolRegistry ctor → new McpClientManager(config, ...)   // tool-registry.ts:199
  → for (name, cfg) in config.getMcpServers():
      new McpClient(name, cfg, toolRegistry, promptRegistry, workspaceContext, ...)
      → client.connect() → client.discover(config)

HTTP デーモン (packages/cli/src/serve, qwen serve)
  │ 起動
  ▼
ACP 子プロセス (qwen --acp, ワークスペースごとに単一プロセス)
  │
  QwenAgent (acpAgent.ts)
  ├── McpTransportPool ◄── 新規、ワークスペーススコープ、1 インスタンス
  │     ├── entries: Map<ConnectionId, PoolEntry>
  │     ├── spawnInFlight: Map<ConnectionId, Promise<PoolEntry>>
  │     ├── workspaceContext (デーモンワークスペースにバインド)
  │     └── バジェットガードレール (PR 14 のステートマシン、ワークスペースに昇格)
  │
  └── sessions: Map<sessionId, Session>
        └── Session.Config → ToolRegistry → McpClientManager(pool?)
                                                     │
                                            ┌────────┴────────┐
                                            │ プール注入       │
                                            ▼                 ▼
                                pool.acquire(name,cfg,sid)   従来のインプロセス
                                  → SessionMcpView            (スタンドアロン qwen)
                                    .applyTools/Prompts
                                    (フィルタ + セッション自身の
                                     レジストリに登録)

McpTransportPool
  ├─ acquire(name, cfg, sid) → PooledConnection
  ├─ release(connectionId, sid) → void
  ├─ releaseSession(sid) → void   (セッション破棄時の一括解放)
  ├─ restartByName(name) → RestartResult[]
  ├─ getAccounting() → McpClientAccounting   (ワークスペーススコープ)
  ├─ getBudgetMode/Budget()
  ├─ drainAll() → Promise<void>   (シャットダウン)
  └─ onBudgetEvent: (event) => void   (QwenAgent が設定)

PoolEntry (内部)
  ├─ refs: Set<sessionId>
  ├─ client: McpClient
  ├─ toolsSnapshot: DiscoveredMCPTool[]
  ├─ promptsSnapshot: Prompt[]
  ├─ generation: number   (再接続時に ++; 古いイベントガード)
  ├─ state: 'spawning' | 'active' | 'draining' | 'closed' | 'failed'
  ├─ drainTimer?: NodeJS.Timeout
  ├─ healthMonitor: { intervalTimer, consecutiveFailures, isReconnecting }
  ├─ subscribers: Map<sid, SessionMcpView>
  ├─ attach(sid, view) → PooledConnection
  └─ detach(sid) → void

PooledConnection (呼び出し元に返されるハンドル)
  ├─ id: ConnectionId
  ├─ on('toolsChanged' | 'promptsChanged' | 'disconnected' | 'reconnected' | 'failed', cb)
  ├─ callTool(name, args, { sessionId }) → CallToolResult
  ├─ readResource(uri, { sessionId, signal })
  └─ release()

SessionMcpView (セッションごと、サーバごと)
  ├─ ctor(toolRegistry, promptRegistry, sessionId, serverName, cfg)
  ├─ applyTools(snapshot) → void   (include/exclude でフィルタ、信頼をデコレート)
  ├─ applyPrompts(snapshot) → void
  └─ teardown() → void   (自身の登録を削除)

type PoolKey = string; // sha256 hex、先頭 16 文字で十分 (現実的な N では衝突なし)
type ConnectionId = `${serverName}::${PoolKey}`;
 
function fingerprint(cfg: MCPServerConfig): PoolKey {
  const canonical = {
    transport: mcpTransportOf(cfg),
    command: cfg.command ?? null,
    args: cfg.args ?? [],
    cwd: cfg.cwd ?? null,
    env: sortedEntries(cfg.env ?? {}), // [[k,v],...] を k でソート
    url: cfg.url ?? null,
    httpUrl: cfg.httpUrl ?? null,
    headers: sortedEntries(cfg.headers ?? {}),
    timeout: cfg.timeout ?? null,
    oauth: canonicalOAuth(cfg.oauth),
  };
  return sha256(JSON.stringify(canonical)).slice(0, 16);
}
 
/**
 * V21-9: 機能的に等価な OAuth 設定を正規化して、
 * 同じフィンガープリントにまとめる。`{enabled: false}`, `undefined`,
 * `null`, `{}` はすべて「OAuth なし」を意味し、`null` を返す。
 */
function canonicalOAuth(o?: OAuthConfig | null): OAuthConfig | null {
  if (!o || !o.enabled) return null;
  return {
    enabled: true,
    clientId: o.clientId ?? null,
    scopes: o.scopes ? [...o.scopes].sort() : null,
    authorizationUrl: o.authorizationUrl ?? null,
    tokenUrl: o.tokenUrl ?? null,
  };
}
 
// 除外フィールド (セッションごとのフィルタであり、トランスポートレベルではない):
//   includeTools, excludeTools, trust, description, extensionName

const POOLED_TRANSPORTS_DEFAULT = new Set(['stdio', 'websocket']);
 
function isPoolable(cfg: MCPServerConfig, opts: PoolOptions): boolean {
  if (isSdkMcpServerConfig(cfg)) return false;
  const transport = mcpTransportOf(cfg);
  return opts.pooledTransports.has(transport);
}

class McpTransportPool {
  private entries = new Map<ConnectionId, PoolEntry>();
  private spawnInFlight = new Map<ConnectionId, Promise<PoolEntry>>();
 
  /** V21-2: 逆インデックス、releaseSession を O(entries) ではなく O(refs) にする。 */
  private sessionToEntries = new Map<string, Set<ConnectionId>>();
 
  async acquire(
    name: string,
    cfg: MCPServerConfig,
    sid: string,
  ): Promise<PooledConnection> {
    if (!isPoolable(cfg, this.opts)) {
      return this.createUnpooledConnection(name, cfg, sid);
    }
    const id: ConnectionId = `${name}::${fingerprint(cfg)}`;
 
    if (this.entries.has(id)) {
      this.indexAttach(sid, id);
      return this.entries.get(id)!.attach(sid);
    }
    let inFlight = this.spawnInFlight.get(id);
    if (!inFlight) {
      const slot = this.tryReserveSlot(name);
      if (slot === 'refused') {
        throw new BudgetExhaustedError(
          name,
          this.clientBudget!,
          this.reservedSlots.size,
        );
      }
      inFlight = this.spawnEntry(name, cfg, id)
        .catch((err) => {
          // V21-4: 起動失敗時に予約済みスロットを解放する。これがないと、
          // ヘルスモニターの解放パスが実行されるまでスロットがリークする
          // (実行されないのは、監視対象のエントリが存在しないため)。
          if (slot === 'reserved') this.releaseSlotName(name);
          throw err;
        })
        .finally(() => this.spawnInFlight.delete(id));
      this.spawnInFlight.set(id, inFlight);
    }
    const entry = await inFlight;
    this.indexAttach(sid, id);
    return entry.attach(sid);
  }
 
  release(id: ConnectionId, sid: string): void {
    const entry = this.entries.get(id);
    if (!entry) return;
    entry.detach(sid);
    this.indexDetach(sid, id);
    if (entry.refs.size === 0) entry.startDrainTimer(this.opts.drainDelayMs);
  }
 
  /** V21-2: O(全エントリ) ではなく O(このセッションの refs) で処理。 */
  releaseSession(sid: string): void {
    const ids = this.sessionToEntries.get(sid);
    if (!ids) return;
    for (const id of ids) {
      const entry = this.entries.get(id);
      if (!entry) continue;
      entry.detach(sid);
      if (entry.refs.size === 0) entry.startDrainTimer(this.opts.drainDelayMs);
    }
    this.sessionToEntries.delete(sid);
  }
 
  private indexAttach(sid: string, id: ConnectionId): void {
    let ids = this.sessionToEntries.get(sid);
    if (!ids) {
      ids = new Set();
      this.sessionToEntries.set(sid, ids);
    }
    ids.add(id);
  }
 
  private indexDetach(sid: string, id: ConnectionId): void {
    const ids = this.sessionToEntries.get(sid);
    if (!ids) return;
    ids.delete(id);
    if (ids.size === 0) this.sessionToEntries.delete(sid);
  }
}

const DRAIN_DELAY_MS_DEFAULT = 30_000; // 最後の解放後の猶予時間
const MAX_IDLE_MS_DEFAULT = 5 * 60_000; // ハードキャップ (ドレインキャンセルループ対策)

spawning ──起動成功──► active ──最後の detach──► draining ──タイムアウト──► closed
   │                     │                       │
   │                     │                       └──attach──► active (タイマーキャンセル)
   起動失敗───────────►failed
                          │
                          └──手動再起動──► spawning

// packages/core/src/tools/pid-descendants.ts
export async function listDescendantPids(rootPid: number): Promise<number[]> {
  if (!Number.isInteger(rootPid) || rootPid <= 0) return [];
  try {
    if (process.platform === 'win32')
      return await listDescendantPidsWin(rootPid);
    return await listDescendantPidsUnix(rootPid);
  } catch {
    return []; // OS は孤児プロセスを回収する。プールシャットダウンはそのまま続行。
  }
}
 
async function listDescendantPidsUnix(root: number): Promise<number[]> {
  let tree: Map<number, number[]> | undefined;
  try {
    tree = await snapshotProcessTreeUnix(); // ps -A -o pid=,ppid=
  } catch {
    /* フォールバックへフォールスルー */
  }
  if (tree) return walkDescendants(tree, root); // O(子孫数)、1 フォーク
  return await listDescendantPidsUnixPgrepFallback(root); // レガシー BFS
}
 
async function snapshotProcessTreeUnix(): Promise<Map<number, number[]>> {
  // -A: 全プロセス (POSIX、-e と同等だが BSD では明確)。
  // -o pid=,ppid=: pid + ppid 列、末尾の `=` はヘッダーを抑制。
  const { stdout } = await execFile('ps', ['-A', '-o', 'pid=,ppid='], {
    timeout: 2000,
    maxBuffer: 8 * 1024 * 1024, // 25 万プロセス超の異常なホストにも対応
  });
  const childrenByPpid = new Map<number, number[]>();
  for (const line of stdout.split('\n')) {
    const m = line.trim().match(/^(\d+)\s+(\d+)$/);
    if (!m) continue;
    /* パース、childrenByPpid に追加 */
  }
  return childrenByPpid;
}
 
// Windows: 単一の Get-CimInstance Win32_Process | ConvertTo-Csv スナップショット
// ですべての (ProcessId, ParentProcessId) 行を取得し、メモリ内でツリーウォーク。
// プロセスごとの `Get-CimInstance -Filter "ParentProcessId=$p"` はフォールバックとして残す。

// packages/core/src/tools/mcp-client.ts — split discover into pure
async discoverAndReturn(cliConfig: Config): Promise<{
  tools: DiscoveredMCPTool[];
  prompts: Prompt[];
}> {
  if (this.status !== MCPServerStatus.CONNECTED) throw new Error('Client is not connected.');
  try {
    const [prompts, tools] = await Promise.all([
      discoverPrompts(this.serverName, this.client, /* no registry */),
      discoverTools(this.client, this.serverConfig, this.serverName, this.debugMode, this.workspaceContext),
    ]);
    if (prompts.length === 0 && tools.length === 0) {
      throw new Error('No prompts or tools found on the server.');
    }
    return { tools, prompts };
  } catch (e) {
    this.updateStatus(MCPServerStatus.DISCONNECTED);
    throw e;
  }
}
 
// Legacy discover() retained, delegates to discoverAndReturn + registers (for standalone qwen)
async discover(cliConfig: Config): Promise<void> {
  const { tools, prompts } = await this.discoverAndReturn(cliConfig);
  for (const t of tools) this.toolRegistry.registerTool(t);
  for (const p of prompts) this.promptRegistry.registerPrompt(p);
}

class SessionMcpView {
  applyTools(snapshot: DiscoveredMCPTool[]) {
    this.sessionToolRegistry.removeToolsByServer(this.serverName);
    for (const tool of snapshot) {
      if (!this.passesFilter(tool)) continue;
      // C7: セッションごとの trust のコピー（共有スナップショットを変更しない）
      const localTool = tool.withTrust(this.cfg.trust);
      this.sessionToolRegistry.registerTool(localTool);
    }
  }
  applyPrompts(snapshot: Prompt[]) {
    this.sessionPromptRegistry.removePromptsByServer(this.serverName);
    for (const p of snapshot) this.sessionPromptRegistry.registerPrompt(p);
  }
}

class PoolEntry {
  attach(sid: string): PooledConnection {
    this.refs.add(sid);
    this.cancelDrainTimer();
    const view = new SessionMcpView(...);
    this.subscribers.set(sid, view);
    // 現在のスナップショットを即座にリプレイし、サブスクライバが
    // インフライトのディスカバリ完了とアタッチの間に発生した更新を
    // 見逃さないようにする。
    if (this.state === 'active') {
      view.applyTools(this.toolsSnapshot);
      view.applyPrompts(this.promptsSnapshot);
    }
    return this.makeHandle(sid, view);
  }
}

class PoolEntry {
  private generation = 0;
 
  private async reconnect(): Promise<void> {
    this.generation += 1;
    const myGen = this.generation;
    await this.client.disconnect();
    await this.client.connect();
    if (myGen !== this.generation) return; // 別の reconnect で上書きされた
    const snap = await this.client.discoverAndReturn(this.cfg);
    if (myGen !== this.generation) return;
    this.toolsSnapshot = snap.tools;
    this.promptsSnapshot = snap.prompts;
    this.fanOut('toolsChanged');
    this.fanOut('promptsChanged');
  }
 
  private onServerToolsListChanged = () => {
    const myGen = this.generation;
    this.client
      .discoverAndReturn(this.cfg)
      .then((snap) => {
        if (myGen !== this.generation) return;
        this.toolsSnapshot = snap.tools;
        this.fanOut('toolsChanged');
      })
      .catch(/* 吸収 + ログ */);
  };
}

class PoolEntry {
  updateStatus(s: MCPServerStatus) {
    this.localStatus = s;
    const aggregated = this.pool.aggregateStatusByName(this.serverName);
    updateMCPServerStatus(this.serverName, aggregated);
  }
}
 
class McpTransportPool {
  aggregateStatusByName(name: string): MCPServerStatus {
    // いずれかが CONNECTED なら CONNECTED
    // それ以外でいずれかが CONNECTING なら CONNECTING
    // それ以外は DISCONNECTED
    const entries = [...this.entries.values()].filter(
      (e) => e.serverName === name,
    );
    if (entries.some((e) => e.localStatus === CONNECTED)) return CONNECTED;
    if (entries.some((e) => e.localStatus === CONNECTING)) return CONNECTING;
    return DISCONNECTED;
  }
}

{
  kind: 'mcp_server',
  name: 'github',
  status: 'ok',
  mcpStatus: 'connected',
  entryCount: 2,                          // NEW — この名前に対する N 個のプールエントリ
  entrySummary?: [                        // NEW — エントリごとの不透明な内訳
    { entryIndex: 0, refs: 2, status: 'connected' },
    { entryIndex: 1, refs: 1, status: 'connecting' },
  ],
  ...
}

async newSessionConfig(...) {
  const config = await loadCliConfig(...);
  if (this.mcpPool) config.setMcpTransportPool(this.mcpPool);
  // ...既存の setMcpBudgetEventCallback は削除 — プールが直接ブロードキャストを処理
}

{
  kind: 'mcp_budget',
  scope: 'workspace',          // NEW 値 (PR 14 v1 は 'session' を返していた)
  liveCount: 5,
  clientBudget: 10,
  budgetMode: 'enforce',
  status: 'ok',
}

class QwenAgent {
  constructor() {
    this.mcpPool = new McpTransportPool({
      onBudgetEvent: (event) => this.broadcastBudgetEvent(event),
    });
  }
 
  private broadcastBudgetEvent(event: McpBudgetEvent) {
    for (const [sid, session] of this.sessions) {
      const enriched = {
        ...event,
        scope: 'workspace' as const,
        sessionId: sid,
      };
      session.connection
        .extNotification('qwen/notify/session/mcp-budget-event', enriched)
        .catch((err) =>
          debugLogger.debug('budget event delivery failed', { sid, err }),
        );
    }
  }
}

export function isWorkspaceScopedBudgetEvent(
  e: DaemonMcpGuardrailEvent,
): boolean;

/**
 * セッションが観測した `mcp_budget_warning` イベントの数。
 * F2 (`scope: 'workspace'`) の下では、バジェットイベントがワークスペースレベルで
 * ファンアウトされるため、アタッチされたすべてのセッションで同時にインクリメントされる。
 * 最新イベントのスコープを検査するには `isWorkspaceScopedBudgetEvent(lastMcpBudgetWarning)`
 * を使用すること。
 */
mcpBudgetWarningCount: number;

type RestartResult = {
  entryIndex: number;        // V21-7: 不透明なインデックス、生のフィンガープリントではない
  restarted: boolean;
  durationMs?: number;
  reason?: string;           // 'budget_would_exceed' | 'not_connected' | 'in_flight'
};
POST /workspace/mcp/:server/restart → { entries: RestartResult[] }

class PoolEntry {
  private restartInFlight?: Promise<void>;
  async restart(): Promise<void> {
    if (this.restartInFlight) return this.restartInFlight;
    this.restartInFlight = this.doRestart().finally(() => {
      this.restartInFlight = undefined;
    });
    return this.restartInFlight;
  }
}

class MCPCallInterruptedError extends Error {
  readonly serverName: string;
  readonly entryIndex: number;
  readonly clientGeneration: number;   // 再接続前の generation
  readonly args: unknown;              // 元の引数。安全なら呼び出し元がリトライするため
  constructor(serverName, entryIndex, clientGeneration, args) { ... }
}

// httpAcpBridge.ts:733 buildWorkspaceMcpStatus — データソースを置き換え
let accounting: McpClientAccounting | undefined;
try {
  // NEW: ブートストラップセッションではなく、ブリッジの extMethod 経由でプールを直接クエリ
  accounting = await this.bridge.client.getMcpPoolAccounting();
} catch (err) {
  // 非プールデーモン用にレガシーのブートストラップセッションパスにフォールバック
  const manager = config.getToolRegistry()?.getMcpClientManager();
  if (manager) accounting = manager.getMcpClientAccounting();
}

class QwenAgent {
  getMcpPoolAccounting(): McpClientAccounting | undefined {
    return this.mcpPool?.getAccounting();
  }
}

session-A がアクティブ、entry-X の参照を保持
session-A が切断（明示的な close なし）→ 最終的に killSession → pool.releaseSession(A) → entry-X.refs.size === 0 → ドレインタマー開始（30秒）
session-A が 30秒以内にレジューム → 新しい newSessionConfig → pool.acquire が entry-X を返す → attach がドレインをキャンセル
session-A が 30秒後にレジューム → entry-X は既に閉じられている → プールが新しいエントリを生成（コールドスタート）

POST /workspace/mcp/reload-all
  → 各セッションに対して：設定を再読み込み、Config.mcpServers を置き換え
  → 参照されなくなった各エントリーに対して：エビクションをスケジュール

1. acceptingNewSessions = false に設定。新規 POST /session を拒否
2. 進行中のプロンプトごとに：キャンセルを通知し、完了を待機（既存の PR 11 ライフサイクル）
3. 各セッションに対して：close をトリガー → pool.releaseSession(sid)
4. await pool.drainAll({ force: true, timeoutMs: 10_000 })   ← 30秒の猶予をバイパス
   ├── 各エントリーに対して：ドレイン+ヘルスタイマーをキャンセル、draining にマーク
   ├── 各エントリーに対して並列：listDescendantPids → 子プロセスに SIGTERM
   ├── 各エントリーに対して並列：client.disconnect()
   └── timeoutMs に対する Promise.race。タイムアウトしたエントリーは SIGKILL
5. ブリッジチャネルをクローズ
6. プロセス終了

async drainAll(opts?: {
  force?: boolean;       // デフォルト false。true の場合は30秒の猶予タイマーをバイパス
  timeoutMs?: number;    // デフォルト 10_000。経過時間ベースの予算。タイムアウト後に残ったものは SIGKILL
}): Promise<DrainResult>;
 
type DrainResult = {
  drained: number;       // 正常に切断できたエントリー数
  forced: number;        // タイムアウト後に SIGKILL されたエントリー数
  errors: Array<{ entryIndex: number; serverName: string; error: string }>;
};

packages/core/src/tools/
  mcp-transport-pool.ts        # McpTransportPool 本体（約700行）
  mcp-pool-key.ts              # fingerprint + canonicalize ヘルパー（約150行）
  mcp-pool-entry.ts            # PoolEntry: refcount + drain + health + generation（約500行）
  session-mcp-view.ts          # SessionMcpView: フィルタリング + tools/prompts の登録（約200行）
  mcp-pool-events.ts           # PoolEvent 判別共用体（約80行）
  pid-descendants.ts           # listDescendantPids クロスプラットフォーム（約150行、テスト含む）

packages/core/src/tools/
  mcp-transport-pool.test.ts   # 約900行
  mcp-pool-entry.test.ts       # 約400行
  session-mcp-view.test.ts     # 約250行
  mcp-pool-key.test.ts         # 約150行
  pid-descendants.test.ts      # 約200行（Unix + Windows スキップゲート付き）

packages/core/src/tools/mcp-client.ts            # discoverAndReturn() 分割。connectToMcpServer を統一
packages/core/src/tools/mcp-client-manager.ts    # pool パラメータをオプション化。budget 状態を条件付きに
packages/core/src/tools/tool-registry.ts         # pool を config から McpClientManager にスレッド
packages/core/src/config/config.ts               # setMcpTransportPool / getMcpTransportPool
packages/cli/src/acp-integration/acpAgent.ts     # QwenAgent.mcpPool 構築。broadcastBudgetEvent。
                                                 # newSessionConfig で pool を Config に結線。
                                                 # killSession で pool.releaseSession を呼び出し
packages/cli/src/serve/run-qwen-serve.ts           # --mcp-pool-transports + budget env を ACP 子プロセスに渡す
packages/cli/src/serve/httpAcpBridge.ts          # buildWorkspaceMcpStatus が pool を読み取り。
                                                 # restartMcpServer extMethod が RestartResult[] を返す
packages/cli/src/serve/capabilities.ts           # mcp_workspace_pool をアドバタイズ
packages/sdk/src/daemon/mcpEvents.ts             # scope?: オプショナルフィールド。isWorkspaceScopedBudgetEvent ヘルパー

// @qwen-code/sdk — 追加のみ
export interface DaemonMcpBudgetWarningData {
  // 既存フィールド...
  scope?: 'workspace' | 'session'; // NEW — 古いデーモンには存在しない（'session' を意味する）
}
 
export interface DaemonMcpChildRefusedBatchData {
  // 既存フィールド...
  scope?: 'workspace' | 'session';
}
 
export interface ServeWorkspaceMcpServerStatus {
  // 既存フィールド...
  entryCount?: number;
  entrySummary?: Array<{
    fingerprint: string;
    refs: number;
    status: MCPServerStatus;
  }>;
}
 
export function isWorkspaceScopedBudgetEvent(
  e: DaemonMcpGuardrailEvent,
): boolean;

## feat(serve): shared MCP transport pool (workspace-scoped) [F2]
 
Single feature-cohesive PR per #4175 branching strategy (2026-05-19).
Replaces what was originally planned as Wave 5 PR 23 + sub-PRs F2-1..F2-4.
 
### Scope
 
~4100 LOC production + ~1900 LOC tests across 6 atomic commits.
Step through with `git log -p HEAD~6..HEAD` for commit-by-commit review.
 
### Design doc
 
See `docs/design/f2-mcp-transport-pool.md` (v2.1).
 
### Pre-review specialist agents (per PR 21 pattern)
 
Folded into first commit before opening:
 
- code-reviewer: N findings, all adopted
- silent-failure-hunter: N findings, all adopted
- type-design-analyzer: N findings, all adopted
 
### Closes
 
(none — F2 entry in #4175 stays open until PR merges into main batch)
 
### Related
 
- #3803 decision #3 update (codeagents PR <link>)
- PR 14b (#4271 merged) — budget guardrail base; F2 graduates scope to workspace
- F1 (#4319 merged) — acp-bridge package; F2 depends on injection seams
 
### Backward compatibility
 
- Standalone `qwen` (non-daemon): pool not constructed; existing behavior preserved
- Daemon `qwen serve --no-mcp-pool`: kill switch falls back to per-session
- SDK: all new fields additive (`entryCount`, `scope?`); EVENT_SCHEMA_VERSION stays at 1
- Old SDK clients: unknown `scope: 'workspace'` ignored per PR 14 contract
- Old daemons: SDK consumers can detect absence of `mcp_workspace_pool` capability and fall back
 
### Test plan
 
- [ ] Pool key: env permutation stability, header divergence, per-session filter exclusion
- [ ] Lifecycle: 3-session sharing, drain grace, concurrent acquire dedupe, spawn failure slot release
- [ ] Tools + Prompts dual fan-out, per-session trust copy, snapshot replay on attach
- [ ] Generation guard: pre-reconnect handler doesn't overwrite post-reconnect snapshot
- [ ] Crash + reconnect with stdio backoff (5s × 3) and HTTP backoff (1/2/4/8/16s × 5)
- [ ] Descendant pid sweep: Linux/macOS pgrep recursion, Windows PowerShell CIM
- [ ] Budget at workspace scope: 4 sessions × budget=2 → 3 max (not 12); fan-out to all attached
- [ ] LoadSession resume within drain window: pool entry reused, no cold start
- [ ] Hot config reload: old/new entries coexist; old drains naturally
- [ ] Restart route: `?entryIndex=` selectivity; legacy single-entry response shape preserved
- [ ] In-flight tool call during reconnect: `MCPCallInterruptedError` rejection
- [ ] Standalone qwen: all existing mcp-client-manager tests pass unchanged