@jingyi0605/codingns4dsh 0.2.1-beta.6 → 0.2.1-beta.8

package/data/build/dist/client/features/peer-host.js

@@ -13,8 +13,13 @@ import { isPeerHostAggregateRefreshRegistered, registerPeerHostAggregateRefresh,
 import { resolveCodingNsTranslator, useCodingNsTranslator } from '../locale.js';
 import { publishSessionAdapter } from '../session-adapter-cache.js';
 import { startSerialPolling } from '../serial-polling.js';
+import { PeerHostRemoteEvents } from '../peer-host-remote-events.js';
+import { installPeerHostFileLinkRouting } from '../peer-host-file-links.js';
+import { registerPeerHostReferenceSource } from '../peer-host-reference-source.js';
 /** 聚合刷新周期；远端资源只影响自身节点，刷新失败不改变本机界面。 */
 const PEER_HOST_AGGREGATE_REFRESH_MS = 30_000;
+/** 有断线节点时缩短复检周期，成功重连后恢复正常频率。 */
+const PEER_HOST_RECOVERY_REFRESH_MS = 5_000;
 /** 新建会话尚未出现在聚合摘要时，临时保留其远端作用域的最长时间。 */
 const PEER_HOST_PENDING_SESSION_SCOPE_TTL_MS = 30_000;
 /** 远端会话流刷新聚合的合并窗口，避免每个文本增量都触发完整摘要读取。 */
@@ -47,14 +52,39 @@ export const peerHostFeature = {
         const shim = globalThis[DSH_PEER_HOST_PREBOOT_SHIM_GLOBAL];
         const projection = createPeerHostNativeProjection();
         const transport = shim === undefined ? undefined : createPeerHostPageTransport(projection, context.services.uiContext, context.services.locale);
+        // 官方 ui-reference 在远程 Session 尚未完成本地保留、或目标 Host 版本没有
+        // sessionReferenceResolver 时会静默丢弃整组对话候选。PeerHost 已经持有摘要，
+        // 让兜底源只在可确认的远程会话/工作区上生效，保证 @ 菜单仍能列出可引用会话。
+        const referenceSource = context.services.uiContext?.inject(['inputTriggers', 'sessions'], (scope) => {
+            scope.effect(() => {
+                // 先挂载不依赖新 Remote 的摘要兜底；若嵌套 Remote 随后就绪，切换到
+                // Resolver 感知版本，官方候选成功时不会在菜单中产生重复项。
+                let dispose = registerPeerHostReferenceSource(scope, projection, context.services.locale);
+                const resolverFiber = scope.inject(['remote.sessionReferenceResolver'], (resolverScope) => {
+                    dispose();
+                    dispose = registerPeerHostReferenceSource(resolverScope, projection, context.services.locale);
+                });
+                return () => {
+                    dispose();
+                    void resolverFiber.dispose();
+                };
+            }, 'codingns4dsh: PeerHost session reference source');
+        });
+        if (referenceSource !== undefined)
+            context.resources.add(() => referenceSource.dispose());
         const management = createPeerHostManagementApi(context.services.rpc);
         if (shim !== undefined) {
             shim.activate(transport.hooks);
             context.resources.add(() => {
+                transport.dispose();
                 shim.deactivate();
                 // 资源按逆序释放：此时 Desktop 路由和导航订阅已还原，重新加载本机目录，
                 // 避免停用 PeerHost 后仍展示最后一个远端 Host 的全局缓存。
                 refreshDshModelCatalog(context.services.uiContext);
+                // Web 路径没有额外的原生 Remote 路由，不需要为了停用插件强制结束当前
+                // Connection 代次；否则 DSH 会在每次手动重连后自动再发一次 session/list。
+                if (shim.getMode?.() === 'desktop')
+                    reconnectNativeEvents(context.services.uiContext);
             });
             // 原生侧栏在插件 apply 时按引用捕获 `workspaces.list`，只能就地投影这个对象；
             // 没有 shim 就没有原生 Remote 路由，此时不注入，避免出现点不开的远端条目。
@@ -81,6 +111,7 @@ export const peerHostFeature = {
                     ...(context.services.remote === undefined ? {} : { remote: context.services.remote }),
                     hooks: transport.hooks,
                     matchesScope: transport.matchesScope,
+                    mergeEvents: transport.mergeEvents,
                     decorateLocalResult: (method, result) => method === 'session/list' ? mergeSessionListResult(result, projection) : result,
                 });
                 if (route !== undefined)
@@ -93,16 +124,44 @@ export const peerHostFeature = {
             });
             if (navigation !== undefined)
                 context.resources.add(() => navigation.dispose());
+            // 文件路径的平台取自资源所属会话，不能由本机平台或前台选择决定。
+            const fileLinks = context.services.uiContext?.inject(['sidebarRight'], (scope) => {
+                scope.effect(() => installPeerHostFileLinkRouting(scope, (sessionId) => (projection.sessions().find((session) => session.sessionId === sessionId)?.cwd)) ?? (() => undefined), 'codingns4dsh: PeerHost file links');
+            });
+            if (fileLinks !== undefined)
+                context.resources.add(() => fileLinks.dispose());
+            // Desktop 的原生 `$events` 可能早于插件启动；切换一次客户端连接代次，让
+            // 已打开的流使用聚合入口。Web 路径从 preboot shim 开始就使用当前入口，
+            // 这里重连只会白白触发 DSH 的 session/list 基线刷新。
+            if (shim.getMode?.() === 'desktop')
+                reconnectNativeEvents(context.services.uiContext);
         }
         const panel = startPeerHostManagementPanel({ rpc: context.services.rpc, locale: context.services.locale });
         context.resources.add(() => panel.dispose());
         // 工作区标签：远端工作区不再把 Host 名写进标题文本，改由彩色标签表达归属。
-        const tag = startPeerHostWorkspaceTag();
+        let latestAggregate = [];
+        const tag = startPeerHostWorkspaceTag({
+            locale: context.services.locale,
+            onDismissDisconnectedWorkspace: async (virtualWorkspaceId) => {
+                const workspace = parseVirtualWorkspaceId(virtualWorkspaceId);
+                if (workspace === null || workspace.targetHostId === null)
+                    return;
+                await management.dismissDisconnectedWorkspace(workspace.targetHostId, workspace.workspaceId);
+                // 本地立即隐藏已确认移除的缓存，不等待下一次网络复检完成。
+                latestAggregate = latestAggregate.map((host) => host.targetHostId === workspace.targetHostId && host.availability !== 'ready'
+                    ? { ...host, workspaces: host.workspaces.filter((item) => item.workspaceId !== workspace.workspaceId) } : host);
+                tag.setAggregate(latestAggregate);
+                if (transport?.setAggregate(latestAggregate) === true)
+                    await refreshPeerHostNativeSessions(context.services.uiContext);
+                await polling.refresh({ afterPending: true });
+            },
+        });
         context.resources.add(() => tag.dispose());
         // 原生"添加工作区"对话框保持主体不变，只额外挂一个"远程 HOST"标签页。
         const workspaceTab = startPeerHostWorkspaceTab({
             api: management,
             onWorkspaceAdded: () => polling.refresh({ afterPending: true }),
+            onWorkspaceRemoved: () => polling.refresh({ afterPending: true }),
             locale: context.services.locale,
         });
         context.resources.add(() => workspaceTab.dispose());
@@ -110,6 +169,7 @@ export const peerHostFeature = {
         // 因此聚合变化后触发一次原生列表刷新，由页面 Transport 在 session/list 响应里补齐。
         const refresh = async (signal) => {
             const orderReference = projection.workspaceOrder();
+            const sessionMembershipBefore = sessionMembershipKey(projection.sessions());
             try {
                 const aggregate = await management.aggregate(signal);
                 // Host 端先完成 aggregate 再 hydrate 顺序；按同一顺序读取可避免拿到空的初始 order，
@@ -126,8 +186,15 @@ export const peerHostFeature = {
                 // 聚合读取期间如果用户完成了一次拖拽，保留本地刚确认的顺序；本轮只更新
                 // 工作区内容，下一轮再从 Host 读取顺序，避免旧的 order 响应覆盖拖拽结果。
                 const refreshedOrder = projection.workspaceOrder() === orderReference ? orderedWorkspaceIds : undefined;
+                latestAggregate = aggregate;
                 tag.setAggregate(aggregate);
-                if (transport?.setAggregate(aggregate, refreshedOrder) === true) {
+                const projectionChanged = transport === undefined
+                    ? projection.setAggregate(aggregate, refreshedOrder)
+                    : transport.setAggregate(aggregate, refreshedOrder);
+                // 运行态、标题和更新时间都由事件流增量承载；只有会话成员集合增删时
+                // 才需要让原生 SessionManager 重新取一次完整 session/list。
+                // 普通聚合状态只更新投影，避免流事件把完整请求放大成风暴。
+                if (projectionChanged && sessionMembershipBefore !== sessionMembershipKey(projection.sessions())) {
                     await refreshPeerHostNativeSessions(context.services.uiContext);
                 }
                 return true;
@@ -138,8 +205,17 @@ export const peerHostFeature = {
             }
         };
         // 首次聚合后台执行，慢远端不能挡住后续模块启动；隐藏页面暂停自动刷新。
-        const polling = startSerialPolling(refresh, PEER_HOST_AGGREGATE_REFRESH_MS);
+        const polling = startSerialPolling(refresh, PEER_HOST_AGGREGATE_REFRESH_MS, {
+            // 即使断线缓存被手动隐藏，也继续检查 Host；隐藏页仍暂停轮询。
+            getIntervalMs: () => latestAggregate.some((host) => host.targetHostId !== null && host.availability !== 'ready')
+                ? PEER_HOST_RECOVERY_REFRESH_MS : PEER_HOST_AGGREGATE_REFRESH_MS,
+        });
         context.resources.add(() => polling.dispose());
+        const online = () => { void polling.refresh({ afterPending: true }); };
+        if (typeof window !== 'undefined') {
+            window.addEventListener('online', online);
+            context.resources.add(() => window.removeEventListener('online', online));
+        }
         // 归档入口等原生操作完成后可以立刻请求刷新，而不必等待下一个周期。
         context.resources.add(registerPeerHostAggregateRefresh(() => polling.refresh({ afterPending: true })));
     },
@@ -148,7 +224,8 @@ export const peerHostFeature = {
 /** 将 DSH preboot shim 绑定到当前页面的 Host RPC；不调用 Connection.rpc，避免递归。 */
 export function createPeerHostPageTransport(projection = createPeerHostNativeProjection(), uiContext, locale) {
     const t = resolveCodingNsTranslator(locale);
-    const fetchImpl = typeof globalThis.fetch === 'function' ? globalThis.fetch.bind(globalThis) : undefined;
+    const originalGlobalFetch = globalThis.fetch;
+    const fetchImpl = typeof originalGlobalFetch === 'function' ? originalGlobalFetch.bind(globalThis) : undefined;
     const scopes = new Map();
     const remoteHostScopes = new Map();
     // DSH 的模型目录是 Host generation 级缓存；PeerHost 工作区切换不会触发 DSH
@@ -232,6 +309,61 @@ export function createPeerHostPageTransport(projection = createPeerHostNativePro
             failure.code = error.code;
         throw failure;
     };
+    const scopeForSessionExport = (url) => {
+        const virtualSessionId = url.searchParams.get('sessionId');
+        if (virtualSessionId === null)
+            return undefined;
+        const parsed = parseVirtualSessionId(virtualSessionId);
+        if (parsed === null)
+            return undefined;
+        const scope = scopes.get(virtualSessionId);
+        return scope?.targetHostId === parsed.hostId ? scope : undefined;
+    };
+    const sessionExportPath = (url, scope) => {
+        const parsed = parseVirtualSessionId(url.searchParams.get('sessionId') ?? '');
+        if (parsed === null || scope.targetHostId !== parsed.hostId)
+            throw new Error('远程 Session 导出作用域不匹配');
+        const rewritten = new URL(url.href);
+        rewritten.searchParams.set('sessionId', parsed.sessionId);
+        return rewritten.pathname + rewritten.search;
+    };
+    const readFetchUrl = (input) => {
+        const raw = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        return new URL(raw, typeof document === 'undefined' ? 'http://codingns.invalid' : document.baseURI);
+    };
+    const remoteSessionExportFetch = async (input, init) => {
+        if (fetchImpl === undefined)
+            throw new Error('当前页面没有 fetch');
+        const request = typeof Request !== 'undefined' && input instanceof Request ? input : undefined;
+        const method = (init?.method ?? request?.method ?? 'GET').toUpperCase();
+        const url = readFetchUrl(input);
+        if (url.pathname !== '/api/session.export' || (method !== 'GET' && method !== 'HEAD'))
+            return fetchImpl(input, init);
+        const scope = scopeForSessionExport(url);
+        if (scope === undefined || scope.targetHostId === null)
+            return fetchImpl(input, init);
+        const headers = init?.headers === undefined && request === undefined
+            ? undefined
+            : Object.fromEntries(new Headers(init?.headers ?? request?.headers).entries());
+        const response = asRecord(await codingNsCall('peerHost/request', {
+            peerHostId: scope.targetHostId,
+            scope,
+            path: sessionExportPath(url, scope),
+            method,
+            ...(headers === undefined ? {} : { headers }),
+        }, init?.signal ?? request?.signal));
+        const status = typeof response?.status === 'number' ? response.status : 502;
+        const responseHeaders = new Headers(Array.isArray(response?.headers) ? response.headers : undefined);
+        // DSH 导出控制器会读取 HEAD 的正文来补充失败原因。浏览器原生 HEAD
+        // 响应不会暴露正文，但这里是页面内合成的 Response，保留代理返回的
+        // 文本错误可以把目标 Host 的真实鉴权原因传回 UI；成功 HEAD 仍为空正文。
+        const body = typeof response?.bodyBase64 === 'string'
+            ? decodeBase64(response.bodyBase64)
+            : typeof response?.body === 'string' ? response.body : '';
+        return new Response(body, { status, headers: responseHeaders });
+    };
+    const restoreGlobalFetch = installSessionExportFetchPatch(originalGlobalFetch, remoteSessionExportFetch);
+    const restoreAnchorClick = installSessionExportAnchorPatch(remoteSessionExportFetch, scopeForSessionExport);
     const findScope = (value) => {
         if (typeof value === 'string') {
             const session = scopes.get(value);
@@ -261,12 +393,41 @@ export function createPeerHostPageTransport(projection = createPeerHostNativePro
         return undefined;
     };
     const scopeForNativeRequest = (method, value) => {
+        // 问题答案是任意用户内容，只能由正式 agentId 决定目标，不能扫描答案里的字符串。
+        if (method === 'userQuestions/answer' || method === 'userQuestions/attachWait')
+            return findScope(questionAgentId(value));
+        // 反馈只能由 request.sessionId 决定归属，消息 ID、反馈文字和版本号都不是路由身份。
+        if (method.startsWith('messageFeedback/') || method === 'sessionFeedback/record') {
+            const input = asRecord(value);
+            const request = asRecord(asRecord(input?.args)?.request ?? input?.request);
+            return findScope(request?.sessionId);
+        }
         const direct = findScope(value);
         if (direct !== undefined)
             return direct;
         return method === 'session/modelCatalog' && !containsResourceId(value) ? navigationScope() : undefined;
     };
     const scopeForPluginRequest = (endpoint, value) => {
+        // 设置页明确选择本机时，不能让无会话的目录查询跟随前台远端工作区。
+        if ((endpoint === 'cli/catalog' || endpoint === 'cli/models' || endpoint === 'cli/catalog/refresh')
+            && asRecord(value)?.catalogHostId === 'local')
+            return undefined;
+        if (endpoint.startsWith('fileManagement/')) {
+            // 文件内容与路径均不参与路由；显式资源必须属于同一台 Host 的同一工作区。
+            const input = asRecord(value);
+            const workspace = findScope(input?.workspaceId);
+            const session = findScope(input?.sessionId);
+            if (hasVirtualResourceScope(value)) {
+                if (typeof input?.workspaceId === 'string' && workspace === undefined)
+                    return undefined;
+                if (typeof input?.sessionId === 'string' && session === undefined)
+                    return undefined;
+                if (workspace !== undefined && session !== undefined
+                    && (workspace.targetHostId !== session.targetHostId || workspace.workspaceId !== session.workspaceId))
+                    return undefined;
+            }
+            return workspace ?? session;
+        }
         // 调试只按顶层资源选择 Host，配置正文里的字符串不能影响路由。
         if (isDebugPluginEndpoint(endpoint)) {
             const input = asRecord(value);
@@ -333,6 +494,27 @@ export function createPeerHostPageTransport(projection = createPeerHostNativePro
         }
         return false;
     };
+    /** 判断请求中是否仍携带虚拟资源 ID；作用域丢失时不能把它交给本机 Gateway。 */
+    const containsVirtualResourceId = (value) => {
+        if (typeof value === 'string')
+            return parseVirtualSessionId(value) !== null || parseVirtualWorkspaceId(value) !== null;
+        if (Array.isArray(value))
+            return value.some(containsVirtualResourceId);
+        const record = asRecord(value);
+        return record !== null && Object.values(record).some(containsVirtualResourceId);
+    };
+    const hasUnresolvedVirtualNativeScope = (method, value) => {
+        // 问题答案正文允许引用任意会话 ID；唯一的路由身份是 agentId，不能扫描正文。
+        if (method === 'userQuestions/answer' || method === 'userQuestions/attachWait')
+            return false;
+        // 反馈只能由 request.sessionId 决定归属，消息 ID、反馈文字和版本号都不是路由身份。
+        if (method.startsWith('messageFeedback/') || method === 'sessionFeedback/record') {
+            const input = asRecord(value);
+            const request = asRecord(asRecord(input?.args)?.request ?? input?.request);
+            return typeof request?.sessionId === 'string' && parseVirtualSessionId(request.sessionId) !== null;
+        }
+        return containsVirtualResourceId(value);
+    };
     const rewriteCliPayload = (value, scope, key = '') => {
         if (typeof value === 'string') {
             const parsed = parseVirtualSessionId(value);
@@ -356,7 +538,7 @@ export function createPeerHostPageTransport(projection = createPeerHostNativePro
             method: 'POST',
             body: JSON.stringify({ rpcId: createRequestId(), method: endpoint, payload: endpoint.startsWith('git/')
                     ? { ...asRecord(payload), workspaceId: scope.workspaceId }
-                    : endpoint.startsWith('cli/') ? rewriteCliPayload(payload, scope) : rewriteDebugPayload(payload, scope) }),
+                    : endpoint.startsWith('cli/') ? rewriteCliPayload(payload, scope) : rewritePluginResourcePayload(payload, scope) }),
         }, signal));
         const status = typeof response?.status === 'number' ? response.status : 500;
         const body = typeof response?.body === 'string' ? response.body : '';
@@ -422,9 +604,27 @@ export function createPeerHostPageTransport(projection = createPeerHostNativePro
             signal?.throwIfAborted();
         }
         finally {
-            await codingNsCall('peerHost/nativeStreamClose', { streamId, scope }).catch(() => undefined);
+            await codingNsCall('peerHost/nativeStreamClose', { streamId, scope }, AbortSignal.timeout(5_000)).catch(() => undefined);
         }
     })();
+    // DSH 自己会在每个 Connection 代次完成时刷新一次真实 session/list；PeerHost
+    // 只需在首次事件流握手成功后补一次虚拟会话基线，后续增量由事件流和聚合变化驱动。
+    let nativeSessionPrepared = false;
+    const events = new PeerHostRemoteEvents({
+        open: (scope, signal) => openRemoteStream('$events', { args: {} }, scope, signal),
+        reply: (scope, payload, signal) => codingNsCall('peerHost/native', { method: '$events/result', payload, scope }, signal),
+        accepts: (agentId, scope) => scopes.get(agentId)?.targetHostId === scope.targetHostId,
+        onSessionStatus: (sessionId, running) => {
+            if (projection.setSessionRunning(sessionId, running))
+                void refreshPeerHostNativeSessions(uiContext);
+        },
+        prepare: async () => {
+            if (nativeSessionPrepared)
+                return;
+            nativeSessionPrepared = true;
+            await refreshPeerHostNativeSessions(uiContext);
+        },
+    });
     const pendingSessionScopes = new Map();
     const forgetPendingSession = (sessionId) => {
         const pending = pendingSessionScopes.get(sessionId);
@@ -464,17 +664,40 @@ export function createPeerHostPageTransport(projection = createPeerHostNativePro
         scopes.set(sessionId, created);
         refreshModelCatalogForScope(navigationScope());
     };
+    /** 父会话目录早于聚合到达时，复用新建会话的临时作用域与清理机制。 */
+    const rememberSubagentCatalog = (scope, value) => {
+        const catalog = asRecord(asRecord(asRecord(value)?.projections)?.values)?.subagentCatalog;
+        if (!Array.isArray(catalog))
+            return;
+        for (const child of catalog) {
+            const id = asRecord(child)?.id;
+            if (typeof id === 'string' && !scopes.has(id))
+                rememberCreatedSession(scope, { sessionId: id });
+        }
+    };
     const hooks = {
         rpc: async ({ method, payload, signal }) => {
             const value = asRecord(payload);
             const channel = typeof value?.channel === 'string' ? value.channel : '/codingns';
             const body = value?.payload;
+            if (channel === '/api' && method === '$events/result' && events.ownsResult(body)) {
+                try {
+                    return { ok: true, value: await events.reply(body, signal) };
+                }
+                catch (error) {
+                    const code = error.code;
+                    return { ok: false, error: { code: typeof code === 'string' ? code : 'gateway/internal', message: error instanceof Error ? error.message : String(error) } };
+                }
+            }
             const endpoint = peerHostPluginEndpoint(channel, method);
             if (endpoint === 'cli/session/adapter-map') {
                 return await mergeRemoteAdapterMap(await request(channel, method, body, signal), signal);
             }
             if (endpoint !== undefined) {
-                if (isDebugPluginEndpoint(endpoint) && hasVirtualDebugScope(body) && scopeForPluginRequest(endpoint, body) === undefined) {
+                if (endpoint.startsWith('fileManagement/') && hasVirtualResourceScope(body) && scopeForPluginRequest(endpoint, body) === undefined) {
+                    return { ok: false, error: { code: 'PEER_HOST_SCOPE_MISMATCH', message: t('peerHost.fileWorkspaceUnavailable') } };
+                }
+                if (isDebugPluginEndpoint(endpoint) && hasVirtualResourceScope(body) && scopeForPluginRequest(endpoint, body) === undefined) {
                     return { ok: false, error: { code: 'PEER_HOST_SCOPE_MISMATCH', message: t('peerHost.debugWorkspaceUnavailable') } };
                 }
                 // Git 只由顶层 workspaceId 决定归属，文件名和提交正文不能参与 Host 选择。
@@ -494,17 +717,41 @@ export function createPeerHostPageTransport(projection = createPeerHostNativePro
             }
             if (channel === '/api' && isDshNativeRemoteMethod(method)) {
                 const scope = scopeForNativeRequest(method, body);
+                if (scope === undefined && hasVirtualQuestionAgent(method, body)) {
+                    return { ok: false, error: { code: 'PEER_HOST_SCOPE_MISMATCH', message: t('peerHost.questionSessionUnavailable') } };
+                }
+                if (scope === undefined && hasUnresolvedVirtualNativeScope(method, body)) {
+                    return { ok: false, error: { code: 'PEER_HOST_SCOPE_MISMATCH', message: t('peerHost.sessionUnavailable') } };
+                }
                 if (scope !== undefined && scope.targetHostId !== null) {
                     // DSH 的 client 契约要求 unary 结果是 `{ok, value}` / `{ok:false, error}` 信封：
                     // 返回裸值会让网关在 `rebuiltFailure(result.error)` 读 undefined.code 而崩成 carrierFailure。
                     try {
                         const created = decodeNativeResponseBytes(await codingNsCall('peerHost/native', { method, payload: body, scope }, signal));
-                        if (method === 'session/create' || method === 'session/fork') {
+                        const createsSession = method === 'session/create' || method === 'session/fork';
+                        const refreshesNativeList = method === 'session/rename' || method === 'workspace/archiveSession' || method === 'workspace/unarchiveSession';
+                        if (createsSession) {
                             rememberCreatedSession(scope, created);
                             // 侧栏按聚合摘要里的 workspace.sessionIds 归组，新会话只有在刷新后的摘要里
                             // 才会挂到远端工作区。不立刻刷新，它会先落在"未分组/本机默认工作区"，
                             // 看起来像新建到了本机。刷新失败不影响创建结果。
-                            void Promise.resolve(requestPeerHostAggregateRefresh()).catch(() => undefined);
+                        }
+                        if (createsSession || refreshesNativeList) {
+                            // 这些是用户明确完成的写操作，允许补一次聚合读取，避免等待 30 秒轮询。
+                            // 改名、归档和取消归档的成员集合不变，因此在聚合完成后额外刷新一次原生
+                            // session/list；refreshPeerHostNativeSessions 自身保留 5 秒最小间隔。
+                            let aggregateRefresh;
+                            try {
+                                aggregateRefresh = requestPeerHostAggregateRefresh();
+                            }
+                            catch {
+                                aggregateRefresh = undefined;
+                            }
+                            if (refreshesNativeList) {
+                                void Promise.resolve(aggregateRefresh)
+                                    .then(() => refreshPeerHostNativeSessions(uiContext))
+                                    .catch(() => undefined);
+                            }
                         }
                         return { ok: true, value: created };
                     }
@@ -527,8 +774,18 @@ export function createPeerHostPageTransport(projection = createPeerHostNativePro
             const value = asRecord(payload);
             const channel = typeof value?.channel === 'string' ? value.channel : '/api';
             const body = value?.payload;
+            if (channel === '/api' && method === '$events') {
+                return events.open(localSignal => openDshGatewayStream(method, body, localSignal), signal);
+            }
             if (channel === '/api' && isDshNativeRemoteMethod(method)) {
                 const scope = scopeForNativeRequest(method, body);
+                if (scope === undefined && hasVirtualQuestionAgent(method, body))
+                    throw new Error('远端问题所属会话不可用，请重新连接');
+                if (scope === undefined && hasUnresolvedVirtualNativeScope(method, body)) {
+                    const error = new Error(t('peerHost.sessionUnavailable'));
+                    error.code = 'PEER_HOST_SCOPE_MISMATCH';
+                    throw error;
+                }
                 if (scope !== undefined && scope.targetHostId !== null) {
                     const stream = openRemoteStream(method, body, scope, signal);
                     if (method !== 'session/follow')
@@ -540,6 +797,9 @@ export function createPeerHostPageTransport(projection = createPeerHostNativePro
                         try {
                             for await (const chunk of stream) {
                                 emitted = true;
+                                // 父会话先公布子会话目录，聚合稍后才补基线。立即登记已验证的虚拟 ID，
+                                // 避免用户在这段窗口打开子会话时把 CLI 配置读到本机并缓存成 dsh。
+                                rememberSubagentCatalog(scope, chunk);
                                 scheduleAggregateRefresh();
                                 yield chunk;
                             }
@@ -552,27 +812,43 @@ export function createPeerHostPageTransport(projection = createPeerHostNativePro
                     })();
                 }
             }
-            // 本机流（含 $events 等非白名单流）必须回到 DSH Gateway：本地 baseline 不能
+            // 其余本机流必须回到 DSH Gateway：本地 baseline 不能
             // 走 PeerHost，否则原生 workspace/session Store 会整体停在 loading。
             if (channel !== '/api')
                 throw new Error('CODINGNS_BASELINE_STREAM');
             return openDshGatewayStream(method, body, signal);
         },
         fetch: (input, init) => {
-            if (fetchImpl === undefined)
-                return Promise.reject(new Error('当前页面没有 fetch'));
-            return fetchImpl(input, init);
+            return remoteSessionExportFetch(input, init);
         },
     };
     return {
         hooks,
+        mergeEvents: (local, signal) => events.open(local, signal),
+        dispose() {
+            events.dispose();
+            restoreAnchorClick();
+            restoreGlobalFetch();
+            if (aggregateRefreshTimer !== undefined)
+                clearTimeout(aggregateRefreshTimer);
+            for (const sessionId of pendingSessionScopes.keys())
+                forgetPendingSession(sessionId);
+        },
         /** 该请求是否落在某个远端 Host 的作用域内；Desktop 连接路由用它决定是否分流。 */
         matchesScope(value, method) {
+            if (method === '$events/result')
+                return events.ownsResult(value);
+            if (hasVirtualQuestionAgent(method ?? '', value))
+                return true;
             const endpoint = method?.replace(/^codingns\//u, '') ?? '';
+            if (endpoint.startsWith('fileManagement/')) {
+                const scope = scopeForPluginRequest(endpoint, value);
+                return scope === undefined ? hasVirtualResourceScope(value) : scope.targetHostId !== null;
+            }
             if (isDebugPluginEndpoint(endpoint)) {
                 const scope = scopeForPluginRequest(endpoint, value);
                 // 聚合暂时缺失时仍接管虚拟资源，返回明确错误，禁止回落本机调试服务。
-                return scope === undefined ? hasVirtualDebugScope(value) : scope.targetHostId !== null;
+                return scope === undefined ? hasVirtualResourceScope(value) : scope.targetHostId !== null;
             }
             if (method?.startsWith('git/') || method?.startsWith('codingns/git/')) {
                 const workspaceId = asRecord(value)?.workspaceId;
@@ -587,7 +863,11 @@ export function createPeerHostPageTransport(projection = createPeerHostNativePro
             const scope = cli === undefined
                 ? scopeForNativeRequest(method ?? '', value)
                 : scopeForPluginRequest(cli, value);
-            return scope !== undefined && scope.targetHostId !== null;
+            if (scope !== undefined)
+                return scope.targetHostId !== null;
+            // 只有原生 Remote 方法会在 hooks 里明确报错、拒绝回落本机；CLI 等插件端点
+            // 没有这层守卫，作用域丢失时必须交还本机，不能假装接管后静默落到本机。
+            return isDshNativeRemoteMethod(method ?? '') && hasUnresolvedVirtualNativeScope(method ?? '', value);
         },
         watchNavigation() {
             const store = readNativeNavigationStore(uiContext);
@@ -597,8 +877,11 @@ export function createPeerHostPageTransport(projection = createPeerHostNativePro
             return stop ?? (() => undefined);
         },
         setAggregate(aggregate, orderedWorkspaceIds) {
+            const previousScopes = new Map(scopes);
+            const now = Date.now();
             scopes.clear();
             remoteHostScopes.clear();
+            const visibleWorkspaceIds = new Set();
             for (const host of aggregate) {
                 if (host.targetHostId !== null) {
                     remoteHostScopes.set(host.targetHostId, { hostId: host.hostId, targetHostId: host.targetHostId, workspaceId: '__aggregate__', sessionId: null, scopeGeneration: 0 });
@@ -606,19 +889,31 @@ export function createPeerHostPageTransport(projection = createPeerHostNativePro
                 for (const workspace of host.workspaces) {
                     const virtualHostId = host.targetHostId ?? host.hostId;
                     const virtualWorkspaceId = createVirtualWorkspaceId(virtualHostId, workspace.workspaceId);
+                    visibleWorkspaceIds.add(virtualWorkspaceId);
                     const workspaceScope = { hostId: host.hostId, targetHostId: host.targetHostId, workspaceId: workspace.workspaceId, sessionId: null, scopeGeneration: 0 };
                     scopes.set(virtualWorkspaceId, workspaceScope);
                     // 归档会话也要能解析作用域：取消归档请求按虚拟会话 ID 路由到目标 Host。
-                    for (const session of [...workspace.sessions, ...(workspace.archivedSessions ?? [])]) {
+                    for (const session of [...workspace.sessions, ...(workspace.archivedSessions ?? []), ...(workspace.subagentSessions ?? [])]) {
                         if (session.scope.sessionId === null)
                             continue;
                         scopes.set(createVirtualSessionId(virtualHostId, session.scope.sessionId), { ...workspaceScope, sessionId: session.scope.sessionId });
                     }
                 }
             }
+            // 聚合刷新可能暂时漏掉会话元数据，但只要工作区仍存在，当前页面的远端会话
+            // 就不能立即改走本机 Gateway。真实删除会在目标 Host 返回明确的 not-found。
+            for (const [sessionId, scope] of previousScopes) {
+                if (scope.targetHostId === null || scope.sessionId === null || scopes.has(sessionId))
+                    continue;
+                const pending = pendingSessionScopes.get(sessionId);
+                if (pending !== undefined && pending.expiresAt <= now)
+                    continue;
+                if (visibleWorkspaceIds.has(createVirtualWorkspaceId(scope.targetHostId, scope.workspaceId)))
+                    scopes.set(sessionId, scope);
+            }
             // 刚创建、尚未进入聚合的会话要保住作用域；聚合里已存在的以聚合为准。
-            // 一旦聚合确认，pending 记录立即清掉；之后远端删除会随下一次聚合重建自然移除。
-            const now = Date.now();
+            // 聚合确认后清掉 pending 记录；会话摘要暂缺时由上面的最后确认作用域接管，
+            // 直到工作区消失。目标 Host 的会话错误仍保持在 PeerHost 边界内，不回落本机。
             for (const [sessionId, pending] of [...pendingSessionScopes]) {
                 if (scopes.has(sessionId)) {
                     forgetPendingSession(sessionId);
@@ -631,7 +926,18 @@ export function createPeerHostPageTransport(projection = createPeerHostNativePro
                 scopes.set(sessionId, pending.scope);
             }
             refreshModelCatalogForScope(navigationScope());
-            return projection.setAggregate(aggregate, orderedWorkspaceIds);
+            const changed = projection.setAggregate(aggregate, orderedWorkspaceIds);
+            for (const sessionId of projection.consumeCompletedSessionTransitions()) {
+                const scope = scopes.get(sessionId);
+                if (scope === undefined)
+                    continue;
+                projection.setSessionRunning(sessionId, false);
+                events.replayCompletedSessionStatus(sessionId, scope);
+            }
+            events.replayPendingSessionStatuses();
+            const readyHosts = new Set(aggregate.filter(host => host.availability === 'ready' && host.workspaces.length > 0).map(host => host.targetHostId));
+            events.setPeers([...remoteHostScopes.values()].filter(scope => readyHosts.has(scope.targetHostId)));
+            return changed;
         },
     };
 }
@@ -639,12 +945,22 @@ export function createPeerHostPageTransport(projection = createPeerHostNativePro
 function peerHostPluginEndpoint(channel, method) {
     const endpoint = channel === '/codingns' ? method
         : channel === '/api' && method.startsWith('codingns/') ? method.slice('codingns/'.length) : '';
-    return endpoint.startsWith('cli/') || endpoint.startsWith('git/') || endpoint.startsWith('debug/') || endpoint === 'terminal/status' ? endpoint : undefined;
+    return endpoint.startsWith('cli/') || endpoint.startsWith('git/') || endpoint.startsWith('debug/') || endpoint.startsWith('fileManagement/') || endpoint === 'terminal/status' ? endpoint : undefined;
+}
+function questionAgentId(value) {
+    const input = asRecord(value);
+    return asRecord(input?.args)?.agentId ?? input?.agentId;
+}
+function hasVirtualQuestionAgent(method, value) {
+    if (method !== 'userQuestions/answer' && method !== 'userQuestions/attachWait')
+        return false;
+    const id = questionAgentId(value);
+    return typeof id === 'string' && parseVirtualSessionId(id) !== null;
 }
 function isDebugPluginEndpoint(endpoint) {
     return endpoint.startsWith('debug/') || endpoint === 'terminal/status';
 }
-function hasVirtualDebugScope(value) {
+function hasVirtualResourceScope(value) {
     const input = asRecord(value);
     return (typeof input?.workspaceId === 'string' && parseVirtualWorkspaceId(input.workspaceId) !== null)
         || (typeof input?.sessionId === 'string' && parseVirtualSessionId(input.sessionId) !== null);
@@ -661,8 +977,8 @@ function projectGitWorkspaceIds(value, workspaceId, virtualWorkspaceId) {
         key === 'workspaceId' && child === workspaceId ? virtualWorkspaceId : projectGitWorkspaceIds(child, workspaceId, virtualWorkspaceId),
     ]));
 }
-/** 只还原调试请求顶层资源标识，配置里的命令、参数和环境变量必须原样保存。 */
-function rewriteDebugPayload(value, scope) {
+/** 只还原调试与文件请求的顶层资源标识，配置、文件正文和路径必须原样保存。 */
+function rewritePluginResourcePayload(value, scope) {
     const input = asRecord(value);
     if (input === null)
         return value;
@@ -670,7 +986,7 @@ function rewriteDebugPayload(value, scope) {
     const workspace = typeof input.workspaceId === 'string' ? parseVirtualWorkspaceId(input.workspaceId) : null;
     if (workspace !== null) {
         if (workspace.hostId !== scope.targetHostId || workspace.workspaceId !== scope.workspaceId)
-            throw new Error('调试请求的 Workspace 与目标 Host 作用域不一致');
+            throw new Error('请求的 Workspace 与目标 Host 作用域不一致');
         result.workspaceId = workspace.workspaceId;
     }
     for (const key of ['sessionId', 'dshSessionId']) {
@@ -678,7 +994,7 @@ function rewriteDebugPayload(value, scope) {
         if (session === null)
             continue;
         if (session.hostId !== scope.targetHostId)
-            throw new Error('调试请求的 Session 与目标 Host 作用域不一致');
+            throw new Error('请求的 Session 与目标 Host 作用域不一致');
         result[key] = session.sessionId;
     }
     return result;
@@ -725,6 +1041,9 @@ export function installPeerHostConnectionRouting(options) {
     // RemoteStreamMuxClient），因此 uplink 与重连行为都不受影响；也不要动
     // `connection.rpc.open`，否则网关会认为本页自带流通道而不再启动/重连 mux。
     const patchedOpenRemoteStream = (endpoint, payload, signal, uplink, noConnection) => {
+        if (endpoint === '$events' && options.mergeEvents !== undefined) {
+            return options.mergeEvents(localSignal => originalCallRemote.call(remote, endpoint, payload, localSignal, uplink, noConnection), signal);
+        }
         if (typeof options.hooks.openStream === 'function' && isPeerScoped('/api', endpoint, payload)) {
             return options.hooks.openStream({ method: endpoint, payload: { channel: '/api', payload, uplink }, ...(signal === undefined ? {} : { signal }) });
         }
@@ -762,6 +1081,14 @@ function readConnectionHandle(uiContext) {
         return undefined;
     }
 }
+/** 只更新浏览器内的事件订阅代次，不重启 Host 或任何运行实例。 */
+function reconnectNativeEvents(uiContext) {
+    try {
+        const connection = uiContext?.get('connection');
+        connection?.reconnect?.();
+    }
+    catch { /* 原生连接尚未挂载时，首次连接会直接使用新的入口。 */ }
+}
 /** 只借用原生导航数据，不修改选择策略，也不从后台保留会话推断前台。 */
 function readNativeNavigationStore(uiContext) {
     try {
@@ -908,10 +1235,15 @@ function refreshDshModelCatalog(uiContext) {
         // 模型选择插件未挂载或 DSH 版本没有该内部服务时，不影响远程请求本身。
     }
 }
+/** 只比较会话成员集合，避免把每个状态增量放大成完整列表请求。 */
+function sessionMembershipKey(sessions) {
+    return sessions.map((session) => session.sessionId).join('\u0000');
+}
 /** 打开当前页面 DSH Gateway 的单个 Remote 流；协议与 dsh-api-gateway 保持一致。 */
 function openDshGatewayStream(endpoint, payload, signal) {
     const streamId = `codingns_${Date.now()}_${Math.random().toString(36).slice(2)}`;
     return (async function* () {
+        signal?.throwIfAborted();
         const WebSocketCtor = globalThis.WebSocket;
         if (typeof WebSocketCtor !== 'function')
             throw new Error('当前页面没有可用 WebSocket');
@@ -947,16 +1279,29 @@ function openDshGatewayStream(endpoint, payload, signal) {
             }
         };
         const onError = () => { failure = new Error('DSH Remote stream WebSocket 失败'); notify(); };
-        const onAbort = () => { failure = signal?.reason instanceof Error ? signal.reason : new Error('DSH Remote stream 已取消'); notify(); };
+        const onAbort = () => { failure = signal?.reason instanceof Error ? signal.reason : new Error('DSH Remote stream 已取消'); notify(); socket.close(1000, 'stream aborted'); };
+        const onClose = () => { if (!ended)
+            failure ??= new Error('DSH Remote stream WebSocket 已关闭'); notify(); };
         socket.addEventListener('message', onMessage);
         socket.addEventListener('error', onError);
+        socket.addEventListener('close', onClose);
         signal?.addEventListener('abort', onAbort, { once: true });
         try {
             await new Promise((resolve, reject) => {
-                const opened = () => resolve();
-                const failed = () => reject(new Error('DSH Remote stream WebSocket 打开失败'));
+                const cleanup = () => {
+                    socket.removeEventListener('open', opened);
+                    socket.removeEventListener('error', failed);
+                    socket.removeEventListener('close', failed);
+                    signal?.removeEventListener('abort', failed);
+                };
+                const opened = () => { cleanup(); resolve(); };
+                const failed = () => { cleanup(); reject(failure ?? new Error('DSH Remote stream WebSocket 打开失败')); };
                 socket.addEventListener('open', opened, { once: true });
                 socket.addEventListener('error', failed, { once: true });
+                socket.addEventListener('close', failed, { once: true });
+                signal?.addEventListener('abort', failed, { once: true });
+                if (signal?.aborted)
+                    failed();
             });
             signal?.throwIfAborted();
             socket.send(JSON.stringify({ type: 'open', streamId, endpoint, payload }));
@@ -976,6 +1321,9 @@ function openDshGatewayStream(endpoint, payload, signal) {
         }
         finally {
             signal?.removeEventListener('abort', onAbort);
+            socket.removeEventListener('message', onMessage);
+            socket.removeEventListener('error', onError);
+            socket.removeEventListener('close', onClose);
             socket.close(1000, 'stream closed');
         }
     })();
@@ -991,6 +1339,75 @@ function isDesktopTopologyPage() {
         return false;
     }
 }
+/** 导出插件直接使用全局 fetch；把远程虚拟 Session 的预检请求接入页面 Transport。 */
+function installSessionExportFetchPatch(original, routed) {
+    if (original === undefined || typeof window === 'undefined')
+        return () => undefined;
+    const wrapped = ((input, init) => routed(input, init));
+    try {
+        globalThis.fetch = wrapped;
+    }
+    catch {
+        return () => undefined;
+    }
+    return () => {
+        if (globalThis.fetch === wrapped)
+            globalThis.fetch = original;
+    };
+}
+/** 导出插件的 GET 使用原生锚点导航；远程 ZIP 必须先经代理取回 Blob 再触发下载。 */
+function installSessionExportAnchorPatch(fetcher, findScope) {
+    if (typeof window === 'undefined' || typeof document === 'undefined')
+        return () => undefined;
+    const prototype = globalThis.HTMLAnchorElement?.prototype;
+    const originalClick = prototype?.click;
+    if (prototype === undefined || originalClick === undefined)
+        return () => undefined;
+    const patchedClick = function () {
+        let url;
+        try {
+            url = new URL(this.href, document.baseURI);
+        }
+        catch {
+            originalClick.call(this);
+            return;
+        }
+        if (url.pathname !== '/api/session.export' || findScope(url) === undefined) {
+            originalClick.call(this);
+            return;
+        }
+        const filename = this.download;
+        void fetcher(url, { method: 'GET' }).then(async (response) => {
+            if (!response.ok)
+                return;
+            const blobUrl = URL.createObjectURL(await response.blob());
+            const download = document.createElement('a');
+            download.href = blobUrl;
+            download.download = filename;
+            originalClick.call(download);
+            setTimeout(() => URL.revokeObjectURL(blobUrl), 0);
+        }).catch(() => undefined);
+    };
+    try {
+        prototype.click = patchedClick;
+    }
+    catch {
+        return () => undefined;
+    }
+    return () => {
+        if (prototype.click === patchedClick)
+            prototype.click = originalClick;
+    };
+}
+function decodeBase64(value) {
+    if (typeof atob !== 'function')
+        throw new Error('当前页面不支持 Base64 解码');
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes.buffer;
+}
 /** PeerHost 启用状态说明；安装动作发生在启动页 preboot 阶段。 */
 function PeerHostPanel({ services, enabled }) {
     const t = useCodingNsTranslator(services.locale);