@ai-workbench/remote-agent 0.8.16 → 0.8.17

package/README.md

@@ -1,10 +1,10 @@
-**`@ai-workbench/remote-agent@0.8.16` 发布形态包。失败时在官方错误消息保留首次观察关闭、运行原因、诊断保存及清理结果的安全代码；未确认的详情保留 pending，不重发或伪造保存成功。目标对象键顺序与目录展示元数据不撤销当前选择；最新可信目录移除所选型号时明确停止。真实身份/代际/文件夹失配仍停止。0.8.15 leo 原始撤销字段与61秒慢查询根因未查明，本版真实 leo/员工链路未复验。通过官方插件 → 添加插件安装；固定包由编排发布，X 不 publish。**
+**`@ai-workbench/remote-agent@0.8.17` 发布形态包。Claude、Codex 接入 L0.7.20 已选择的主机文件夹；成功核验来源和目录后才打开技术详情与派发，每次派发前重新核验。L 的具体原因和下一步动作直接给员工。包含0.8.16首次关闭、运行、诊断保存和清理结果留痕；历史原始撤销字段与61秒慢查询根因仍未查明。本版 leo 主机位置/真实员工链路尚未复验。通过官方插件 → 添加插件安装；固定包由编排发布，X2 不 publish。**
 
 # 远程ACP插件
 
 一个插件提供 **Claude（远程主机）** 和 **Codex（远程主机）**，通过员工主机上的官方CLI运行。Codex保留单次模式；Claude固定会话模式。只用官方模型列表、插件管理和配置入口，不提供自制面板、问答或登录按钮。登录和原生工作区绑定唯一归连接插件L。
 
-当前版本号为0.8.16；包名采用`@ai-workbench/remote-agent`以涵盖两个品牌；本轮按编排放行准备发布形态包，供 leo 真机自验；X 不执行实际发布，由编排统一发布。开发fixture逐字节保留L0.7.19固定包，公开类型与SSH导出从该包消费。运行时仍要求L的`getContractInfo()`同时返回API0.7.0、implemented、native-local-v1；旧L包、draft.3或只有版本号的不完整实现会明确报缺项。依赖范围为`~0.7.19`，L由官方插件管理单独安装，不打进X。组件验证不代表真实开通、模型或leo E通过；HanaMesh另验。
+当前版本0.8.17，由X2按编排裁定基于0.8.16交付主机来源执行和L具体Need透传；包名采用`@ai-workbench/remote-agent`以涵盖两个品牌；本轮按编排放行准备发布形态包，供 leo 真机自验；X 不执行实际发布，由编排统一发布。开发fixture逐字节保留L0.7.20固定包，公开类型与SSH导出从该包消费。运行时仍要求L的`getContractInfo()`同时返回API0.7.0、implemented、native-local-v1；旧L包、draft.3或只有版本号的不完整实现会明确报缺项。依赖范围为`~0.7.20`，L由官方插件管理单独安装，不打进X。组件验证不代表真实开通、模型或leo E通过；HanaMesh另验。
 
 已包含L0.7.18消费增量：来源确认、输入接纳、登录、本机接纳、输入准备、模型目录及运行时解析的早期失败，用正式`preflightDiagnostics:1` / `preflight-check`进入L「连接前技术详情（含登录与工作区确认）」。阶段、真实来源/状态和错误代码可展开；未知来源为null，旧login-check的完整安全原因保留。记录不选择来源、不接纳输入、不自动重发；无原生会话的菜单查询仍在模型设置报告。当前工程和设置组件验证不等于leo GUI验收。
 
@@ -12,7 +12,11 @@
 
 ## 员工路径
 
-从官方插件管理安装，照常使用默认工作区/会话/模型入口。L0.7.17沿唯一“远程主机连接”设置节记录文件来源；主机来源沿用L既有解析；本地来源接入N0.4.4/S0.4.11员工端点。旧映射可在本轮官方一次确认中选择改用本机文件夹；拒绝、取消或输入/来源变化时不切换、不执行。也可在L设置逐工作区确认沿用原主机关联，新主机位置仍按L现有合同停止为WORKSPACE_LOCATION_PROVIDER_REQUIRED。本地六类工具经Claude公开toolAliases路由到员工电脑：cwd是员工选定目录，Git使用本机仓库，不回退主机同名目录。本地真实员工输入先取得官方当前轮次CAS预期，再调用L0.7.17 acceptLocalWorkspaceUserTurn；核回包后才打开D19和本轮主机目录/执行。每轮localAcceptanceId冻结进原详情sink，迟到结果不借新轮ID；LOCAL_USER_TURN_CHANGED立即停止本轮，不重接纳或退legacy。已用固定真包完成本地D19组件联测；编排已回证0.8.14 Claude/Opus5/Default在leo本地目录首轮写文件成功；该回证不覆盖本0.8.16或Codex，产品验收以各版本leo实际结果为准。本地文件不自动上传，X不猜目录、不选首项。首次说明使用官方普通回复；先经官方会话提交、持久化并读回核对，才向L确认。持久记录不等于员工已看见，GUI另验；日志丢失后的未知claim由L保留，不宣称端到端恰好一次。
+从官方插件管理安装，照常使用默认工作区/会话/模型入口。L沿唯一“远程主机连接”设置节记录文件来源；L0.7.20新选主机位置由两品牌按已核验的规范目录执行，旧legacy主机绑定仍沿原规则；本地来源接入N0.4.4/S0.4.11员工端点。旧映射可在本轮官方一次确认中选择改用本机文件夹；拒绝、取消或输入/来源变化时不切换、不执行。也可在L设置逐工作区确认沿用原主机关联。缺正式host解析能力时明确说明所缺组件、保留原话，本轮不派发。本地六类工具经Claude公开toolAliases路由到员工电脑：cwd是员工选定目录，Git使用本机仓库，不回退主机同名目录。本地真实员工输入先取得官方当前轮次CAS预期，再调用L0.7.17 acceptLocalWorkspaceUserTurn；核回包后才打开D19和本轮主机目录/执行。每轮localAcceptanceId冻结进原详情sink，迟到结果不借新轮ID；LOCAL_USER_TURN_CHANGED立即停止本轮，不重接纳或退legacy。已用固定真包完成本地D19组件联测；编排已回证0.8.14 Claude/Opus5/Default在leo本地目录首轮写文件成功；该回证不覆盖本0.8.17或Codex，产品验收以各版本leo实际结果为准。本地文件不自动上传，X不猜目录、不选首项。首次说明使用官方普通回复；先经官方会话提交、持久化并读回核对，才向L确认。持久记录不等于员工已看见，GUI另验；日志丢失后的未知claim由L保留，不宣称端到端恰好一次。
+
+新主机位置允许当前SSH员工账号可访问的已选绝对目录、文件系统根目录、非Git或只读目录；不改写原projectRoot、不创建Git、不转本机同名文件夹。read/execute必须可核实，write=false不额外一刀切拒绝，实际写入服从主机系统权限。运行前必核来源UUID、连接代次、目录及链接入口dev/ino和权限；revision与内容增删导致的mtime/ctime变化不单独失效。此核对属于正确性条件，不可关闭。最后inspect到主机spawn之间仍有OS时序边界，不表示原子目录句柄租约。
+
+文件来源或位置改变后，原会话不能改绑或重放，员工看到“文件来源已改，请新建会话继续”；原会话历史仍可查。L的具体Need保留message/actor/action和代码，员工正文显示原原因与实际文字动作；明确选择文件来源的动作给“设置 → 远程主机连接 → 工作区文件来源”，新建会话等动作保留原标签，不按错误码猜导航；不可用动作明确标记。技术原因officialReason不进正文，未提供按钮API时不编造可点击入口。
 
 未登录时两个模型均回复：**需要登录，请到设置 → 远程主机连接 点登录**。无L或缺正式能力时直接说明缺项，不让员工填写主机、用户、路径或密钥。
 
@@ -64,7 +68,7 @@ D19（0.8.1）：相邻正文增量合成连续文本块，工作区首次说明
 技术详情由 L 0.7.11 的唯一“远程主机连接”设置节展示，正文只放模型文本。命令目录保留完整描述；未知事件和工具输入输出保留字段、JSON类型及处理结果，未获准原文明确脱敏，数字用量可核对。没有 `remoteConversationDetails:1` 时明确提示“技术详情暂不可用”，本轮不发送模型请求。X 在官方当前 profile 的 `ai-workbench-remote-agent/diagnostics/` 保存私有诊断日志（目录700、文件600、落盘同步）；写入/归属/顺序/容量失败中止本轮，不自动重发、换代重投、过期或淘汰。结果未知时只读核对原事件完整回执，未找到仍保持未知。X本轮无新增设置/阈值；L的单事件容量和分页设置在L设置节可见。
 
 
-0.8.2 登录检查原交付需要 L `~0.7.11`（本统一版peer为`~0.7.18`），失败来源及固定分支保留到 L“登录前技术详情”（`loginDiagnostics:1`），员工正文保持原文。按 L 明确的本品牌 queued/checking/authorizing 状态订阅等待；不以全局checking猜测在途，不新增刷新、轮询、超时或重试。每轮ensureReady仍是合同规定的显式检查，L的新可信结果可以替代旧检查，较早返回不得覆盖它。
+0.8.2 登录检查原交付需要 L `~0.7.11`（本统一版peer为`~0.7.20`），失败来源及固定分支保留到 L“登录前技术详情”（`loginDiagnostics:1`），员工正文保持原文。按 L 明确的本品牌 queued/checking/authorizing 状态订阅等待；不以全局checking猜测在途，不新增刷新、轮询、超时或重试。每轮ensureReady仍是合同规定的显式检查，L的新可信结果可以替代旧检查，较早返回不得覆盖它。
 
 L安全规范的officialReason原串完整保留；旧/不支持格式明确记OFFICIAL_REASON_UNSUPPORTED与字节数/SHA，秘密原文不保存。L0.7.11的LOGIN_INSTANCE_MISMATCH记录通过observedLoginInstanceId与原始login.instanceId保存实际观测ID，事件及connection仍绑定当前可信ID/代次；L技术详情和X私有日志均保留真实双ID，不归一、不清空快照。复合未知官方原因以固定summary完整保存OFFICIAL_REASON_UNSUPPORTED及bytes/SHA，不交原文。X私有原快照先同步落盘，再追加L；ACK未知只读核实原事件，跨代不重写/重发。此版本的工程验证不替代leo员工路径复验，真实故障根因尚未证实。
 
@@ -76,7 +80,7 @@ D21（0.8.5）：两个品牌的官方模型菜单从 L 的 `modelCatalogTarget:
 
 每轮先核对目录代次和所选模型，再经 ACP 逐项配置模型及推理等级，收到完整配置确认后才发送输入。Claude 别名每轮须有精确的模型配置成功回执，并由同一员工主机、同一连接代际的目录唯一映射到具体型号。具体型号注明来自主机目录，会话未单独回报；旧恢复记录不作本轮证据。目录缺项、映射不唯一、回执不符或身份/代际变化时不发送输入。所选值、远端确认值及型号来源仅在恢复标识与技术详情保留，插件不向真实回复追加技术参数，确认配置不等于验证推理效果。连接/身份/目录变化清除旧确认；远端清理待定或结果未知时阻止派发，不自动清理重试或另开替代会话。Codex 单次模式当前不能确认此选择，会在发送前明确拒绝。新增设置 0；本轮工程证据、真实只读链路与产品未验项见 `docs/evidence/2026-10-22-X2-D21/`。
 
-0.8.5统一包原依赖L `~0.7.13`；当前0.8.16对齐L `~0.7.19`。D8模型目录双事件长期监听保留；同epoch的recovery提示/失败消息变化不触发执行状态失效，真实实例/epoch/phase/可信目标/登录变化仍失效。完整D9两品牌正文/状态/就绪门呈现按编排00:50允许的范围记下一版，本版不宣称已消费完成；L的connectionMessages.administratorAfterMs仍只由L管理，X新增设置0。
+0.8.5统一包原依赖L `~0.7.13`；0.8.16原对齐L `~0.7.19`；当前0.8.17对齐L `~0.7.20`。D8模型目录双事件长期监听保留；同epoch的recovery提示/失败消息变化不触发执行状态失效，真实实例/epoch/phase/可信目标/登录变化仍失效。完整D9两品牌正文/状态/就绪门呈现按编排00:50允许的范围记下一版，本版不宣称已消费完成；L的connectionMessages.administratorAfterMs仍只由L管理，X新增设置0。
 
 D18（0.8.6）：Codex 需要主机自有 adapter `2.2.2-aw.1` 的明确新建会话上下文政策，官方 CLI 仍为未改的0.160.1。系统/开发者要求仅在新建时生效；恢复时与初建摘要相同则正常恢复且省略新建专用字段，不声称恢复接口会更新指令。要求不同或清空时，在同一真实回复说明“会话要求已变化，已新建 Codex 会话继续处理，原会话仍保留。”，并新建远端承接公开对话，保留旧标识和查询记录；旧/非法初建摘要明确拒绝，不能猜测。
 

package/dist/acp.js

@@ -390,7 +390,7 @@ export class AcpSession {
         signal?.addEventListener('abort', abort, { once: true });
         try {
             const hello = await this.stage('acp-initialize', () => this.connection.agent.request(acp.methods.agent.initialize, {
-                protocolVersion: acp.PROTOCOL_VERSION, clientInfo: { name: '@ai-workbench/remote-agent', version: '0.8.16' },
+                protocolVersion: acp.PROTOCOL_VERSION, clientInfo: { name: '@ai-workbench/remote-agent', version: '0.8.17' },
                 clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false, session: { notices: {} }, ...(this.employeeMeta ? { _meta: { awEmployeeExecution: { version: 1 } } } : {}) },
             }, { cancellationSignal: signal }));
             this.hooks.broker?.acknowledge(acp.methods.agent.initialize);

package/dist/claude-local.js

@@ -31,6 +31,8 @@ export function createClaudeLocalProvider(options) {
             if (typeof local.getWorkspaceLocationState !== 'function')
                 throw failure('EMPLOYEE_CONTEXT_UNAVAILABLE');
             const workspace = await options.readWorkspace(request.sessionId), state = local.getWorkspaceLocationState(), matches = state.items.filter(row => row.workspaceId === workspace.workspaceId);
+            if (matches.length === 1 && matches[0].source === 'host')
+                return; // Host state/Need belongs to the host resolver, before local admission.
             if (matches.length !== 1 || state.phase !== 'ready' || state.instanceId !== connection.instanceId || state.epoch !== connection.epoch)
                 throw failure('EMPLOYEE_CONTEXT_CHANGED');
             const item = matches[0];

package/dist/connect-contract.d.ts

@@ -2,8 +2,8 @@ import type { ConnectNeed } from '@ai-workbench/connect/api';
 import type { ConnectTarget } from './provider.ts';
 import type { ContractInfo, Provider, WorkspaceUse, WorkspaceNoticeReceipt as LWorkspaceNoticeReceipt } from '@ai-workbench/connect/api';
 /** 正式L0.7公开类型；消费子集不表示已安装或已通过真实产品门。 */
-export type { WorkspaceNotice, SessionProjectTarget } from '@ai-workbench/connect/api';
-import type { SessionProjectTarget } from '@ai-workbench/connect/api';
+export type { WorkspaceNotice, SessionProjectTarget, HostWorkspaceResolveContext, HostSessionProjectTarget } from '@ai-workbench/connect/api';
+import type { SessionProjectTarget, HostWorkspaceResolveContext, HostSessionProjectTarget } from '@ai-workbench/connect/api';
 export type LoginProvider = Provider;
 export type WorkspaceNoticeReceipt = Extract<LWorkspaceNoticeReceipt, {
     surface: 'provider';
@@ -17,11 +17,12 @@ export type ConnectResult<T> = {
         code: string;
         message: string;
         requires: string;
-    } & Pick<ConnectNeed, 'officialReason'>;
+    } & Partial<Pick<ConnectNeed, 'officialReason' | 'layer' | 'actor' | 'action' | 'lastSeen'>>;
 };
+export type SessionProjectResolution = SessionProjectTarget | HostSessionProjectTarget;
 export interface NativeWorkspaceApi {
     getContractInfo(): ContractInfo;
     ensureReady(provider: LoginProvider): Promise<ConnectResult<ConnectTarget>>;
-    resolveSessionProject(sessionId: string, use: WorkspaceUse): Promise<ConnectResult<SessionProjectTarget>>;
+    resolveSessionProject(sessionId: string, use: WorkspaceUse, location?: HostWorkspaceResolveContext): Promise<ConnectResult<SessionProjectResolution>>;
     acknowledgeWorkspaceNotice(receipt: WorkspaceNoticeReceipt): Promise<ConnectResult<void>>;
 }

package/dist/connect-need.d.ts

@@ -0,0 +1,12 @@
+import type { ConnectNeed } from '@ai-workbench/connect/api';
+import { NeedError } from './remote.ts';
+type NeedInput = {
+    code: string;
+    message: string;
+    requires: string;
+} & Partial<Omit<ConnectNeed, 'code' | 'message' | 'requires'>>;
+/** Only the public L Need shape is employee wording; arbitrary errors stay diagnostic. */
+export declare function connectNeedError(value: NeedInput): NeedError;
+export declare function originalConnectNeed(error: unknown): Readonly<ConnectNeed> | undefined;
+export declare function connectNeedMessage(error: unknown): string | undefined;
+export {};

package/dist/connect-need.js

@@ -0,0 +1,34 @@
+import { NeedError } from "./remote.js";
+/** Only the public L Need shape is employee wording; arbitrary errors stay diagnostic. */
+export function connectNeedError(value) {
+    const error = new NeedError(value.code, value.message, value.requires);
+    if (typeof value.officialReason === 'string')
+        error.officialReason = value.officialReason;
+    if (typeof value.layer === 'string' && ['enrollment', 'network', 'ssh', 'auth', 'integration', 'settings', 'projects'].includes(value.layer) && typeof value.actor === 'string' && ['employee', 'administrator', 'ai-administrator', 'plugin'].includes(value.actor) && value.action && typeof value.action.id === 'string' && typeof value.action.label === 'string' && typeof value.action.available === 'boolean') {
+        error.connectNeed = Object.freeze({ code: value.code, layer: value.layer, message: value.message, requires: value.requires, actor: value.actor, action: Object.freeze({ id: value.action.id, label: value.action.label, available: value.action.available }), ...(typeof value.officialReason === 'string' ? { officialReason: value.officialReason } : {}), ...(typeof value.lastSeen === 'string' ? { lastSeen: value.lastSeen } : {}) });
+    }
+    return error;
+}
+export function originalConnectNeed(error) {
+    const queue = [error], seen = new Set();
+    while (queue.length) {
+        const item = queue.shift();
+        if (!item || typeof item !== 'object' || seen.has(item))
+            continue;
+        seen.add(item);
+        if (item instanceof NeedError && item.connectNeed)
+            return item.connectNeed;
+        if (item instanceof AggregateError)
+            queue.push(...item.errors);
+        if (item instanceof Error && item.cause !== undefined)
+            queue.push(item.cause);
+    }
+}
+export function connectNeedMessage(error) {
+    const need = originalConnectNeed(error);
+    if (!need)
+        return;
+    const location = need.action.id === 'select-workspace-location';
+    const action = location ? '设置 → 远程主机连接 → 工作区文件来源（' + need.action.label + '）' : need.action.label;
+    return need.message + (action ? '\n下一步' + (need.action.available ? '' : '（当前不可用）') + '：' + action + '。' : '');
+}

package/dist/employee-location.js

@@ -1,3 +1,4 @@
+import { connectNeedError } from "./connect-need.js";
 import { NeedError } from "./remote.js";
 import { isDeepStrictEqual } from 'node:util';
 const fail = (code) => new NeedError(code, '员工电脑的工作区或执行连接已变化，本轮没有继续执行。', '当前工作区绑定与员工端执行器');
@@ -29,7 +30,7 @@ export async function admitEmployeeLocation(options) {
         const result = await api.getLocalWorkspaceContext(request);
         signal?.throwIfAborted();
         if (!result.ok)
-            throw new NeedError(result.error.code, result.error.message, result.error.requires);
+            throw connectNeedError(result.error);
         const c = result.value;
         if (c.version !== 1 || c.source !== 'local' || c.instanceId !== connection.instanceId || c.epoch !== connection.epoch || c.workspaceId !== workspace.id || c.bindingId !== item.bindingId || !absolute(c.directory?.path) || c.directory.path !== workspace.path || !Number.isSafeInteger(c.directory.device) || !Number.isSafeInteger(c.directory.inode))
             throw fail('EMPLOYEE_CONTEXT_CHANGED');

package/dist/employee-provider.js

@@ -6,6 +6,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { connectNeedError } from "./connect-need.js";
 import { CODEX_EMPLOYEE_SCOPE_NOTICE } from "./employee-presentation.js";
 import { CloseDiagnostics, withFailureEvidence, closeCode, closeErrorCodes } from "./close-diagnostics.js";
 import { createHash } from 'node:crypto';
@@ -53,7 +54,7 @@ export async function acceptEmployeeUserTurn(get, employee, agent, api, request)
     stable();
     const context = await api.getLocalWorkspaceContext({ instanceId: connection.instanceId, epoch: connection.epoch, workspaceId: workspace.id, expectedBindingId: row.bindingId });
     if (!context.ok)
-        throw new NeedError(context.error.code, '无法核验本机工作区，本轮已停止。', '当前本机工作区');
+        throw connectNeedError(context.error);
     stable();
     const c = context.value, d = { ...c.directory };
     if (c.version !== 1 || c.source !== 'local' || c.instanceId !== connection.instanceId || c.epoch !== connection.epoch || c.workspaceId !== workspace.id || c.bindingId !== row.bindingId || !absolute(d?.path) || d.path !== workspace.path || ![d.device, d.inode].every(n => Number.isSafeInteger(n) && n >= 0))
@@ -63,7 +64,7 @@ export async function acceptEmployeeUserTurn(get, employee, agent, api, request)
         throw fail('LOCAL_USER_TURN_UNCONFIRMED');
     const response = await api.acceptLocalWorkspaceUserTurn({ instanceId: connection.instanceId, epoch: connection.epoch, sessionId: request.sessionId, provider: agent.loginProvider, purpose: 'user-turn', workspaceId: workspace.id, expectedBindingId: row.bindingId, expectedDirectory: { device: d.device, inode: d.inode }, expectedUserTurn: { ...expected } });
     if (!response.ok)
-        throw new NeedError(response.error.code, '本次员工输入或工作区无法核验，本轮已停止。', 'L 本地真实输入接纳');
+        throw connectNeedError(response.error);
     stable();
     const a = response.value;
     if (!a || a.version !== 1 || typeof a.acceptanceId !== 'string' || !a.acceptanceId.trim() || a.instanceId !== connection.instanceId || a.epoch !== connection.epoch || a.sessionId !== request.sessionId || a.provider !== agent.loginProvider || a.workspaceId !== workspace.id || a.bindingId !== row.bindingId || a.source !== 'local' || a.directory?.path !== d.path || a.directory?.device !== d.device || a.directory?.inode !== d.inode || a.userTurn?.turn !== expected.turn || a.userTurn?.userMessageId !== expected.userMessageId || ![a.userTurn?.startSequence, a.userTurn?.userMessageSequence].every(n => Number.isSafeInteger(n) && n >= 0) || a.userTurn.userMessageSequence <= a.userTurn.startSequence)
@@ -86,7 +87,7 @@ export async function validateEmployeeUserTurn(get, employee, api, request, conn
     const c = await api.getLocalWorkspaceContext({ instanceId: a.instanceId, epoch: a.epoch, workspaceId: a.workspaceId, expectedBindingId: a.bindingId });
     stable();
     if (!c.ok)
-        throw new NeedError(c.error.code, '无法核验本机工作区，本轮已停止。', '当前本机工作区');
+        throw connectNeedError(c.error);
     if (c.value.version !== 1 || c.value.source !== 'local' || c.value.instanceId !== a.instanceId || c.value.epoch !== a.epoch || c.value.workspaceId !== a.workspaceId || c.value.bindingId !== a.bindingId || c.value.directory.path !== a.directory.path || c.value.directory.device !== a.directory.device || c.value.directory.inode !== a.directory.inode)
         throw fail('EMPLOYEE_CONTEXT_CHANGED');
     const turn = employee.currentUserTurn(request);

package/dist/host-workspace.d.ts

@@ -0,0 +1,13 @@
+import type { ConnectApi, ConnectTarget, ConnectionState, RuntimeRequest, Runtime } from './provider.ts';
+import type { NativeWorkspaceApi, HostSessionProjectTarget, LoginProvider } from './connect-contract.ts';
+import type { WorkspaceSourceOptions } from './workspace-source.ts';
+export interface HostWorkspaceGuard {
+    readonly signal: AbortSignal;
+    readonly revocation: AbortSignal;
+    resolve(): Promise<HostSessionProjectTarget>;
+    assertCurrent(): void;
+    observeRuntime(runtime: Runtime): void;
+    dispose(): void;
+}
+/** Current official membership and explicit host selection; never infer source from a pathname. */
+export declare function hostWorkspaceGuard(get: () => ConnectApi | undefined, api: ConnectApi & NativeWorkspaceApi, connection: ConnectionState, target: ConnectTarget, request: RuntimeRequest, workspace: WorkspaceSourceOptions['workspace'] | undefined, provider: LoginProvider): Promise<HostWorkspaceGuard | undefined>;

package/dist/host-workspace.js

@@ -0,0 +1,110 @@
+import { basename } from 'node:path/posix';
+import { awaitL, sameTarget, unwrap } from "./provider.js";
+import { connectNeedError } from "./connect-need.js";
+import { NeedError } from "./remote.js";
+const invalid = () => new NeedError('PROJECT_BINDING_INVALID', '文件来源已改，请新建会话继续；原会话历史仍可查看。', 'L核验的同一主机位置与目录身份');
+const hostIdentity = (v) => JSON.stringify(v ? [v.host, v.username, v.port] : null);
+const absolute = (v) => typeof v === 'string' && v.startsWith('/') && !v.includes('\0');
+function physical(d) {
+    if (!d || !absolute(d.requestedPath) || !absolute(d.path) || !(d.parentPath === null || absolute(d.parentPath)) || !d.identity || !d.entryIdentity || ![d.identity.device, d.identity.inode, d.entryIdentity.device, d.entryIdentity.inode].every(x => typeof x === 'string' && x.length > 0) || typeof d.isSymlink !== 'boolean' || !d.permissions || d.permissions.read !== true || d.permissions.execute !== true || !(typeof d.permissions.write === 'boolean' || d.permissions.write === null))
+        throw invalid();
+    // Directory contents change timestamps; neither timestamp is an execution identity.
+    return JSON.stringify([d.requestedPath, d.path, d.parentPath, d.identity.device, d.identity.inode, d.entryIdentity.device, d.entryIdentity.inode, d.isSymlink, d.permissions.read, d.permissions.write, d.permissions.execute]);
+}
+/** Current official membership and explicit host selection; never infer source from a pathname. */
+export async function hostWorkspaceGuard(get, api, connection, target, request, workspace, provider) {
+    if (api.getContractInfo().workspaceLocations !== 1 || typeof api.getWorkspaceLocationState !== 'function')
+        return;
+    const firstState = api.getWorkspaceLocationState();
+    if (!workspace) {
+        if (firstState.items.some(row => row.source === 'host'))
+            throw new NeedError('DEPENDENCY_REQUIRED', '我需要核对当前会话所属工作区，才能使用所选主机文件夹。', '官方会话与唯一workspaceRegistry关系');
+        return;
+    }
+    const registered = { ...await workspace(request) };
+    request.signal?.throwIfAborted();
+    const state = api.getWorkspaceLocationState(), rows = state.items.filter(row => row.workspaceId === registered.id), selected = rows[0];
+    if (rows.length !== 1 || !selected)
+        return;
+    if (selected.source !== 'host') {
+        if (selected.source !== null && !['local', 'legacy-host'].includes(selected.source))
+            throw invalid();
+        return;
+    }
+    if (api.getContractInfo().hostWorkspaceResolution !== 1 || typeof api.onWorkspaceLocationState !== 'function' || typeof api.onConnectionState !== 'function')
+        throw new NeedError('DEPENDENCY_REQUIRED', '我需要支持主机位置解析的远程主机连接组件；本轮未执行，原话保留。', 'L >=0.7.20 / hostWorkspaceResolution:1');
+    if (state.instanceId !== connection.instanceId || state.epoch !== connection.epoch)
+        throw invalid();
+    if (state.need)
+        throw connectNeedError(state.need);
+    if (selected.need)
+        throw connectNeedError(selected.need);
+    if (!registered.id || !absolute(registered.path) || state.phase !== 'ready' || selected.status !== 'selected' || !selected.bindingId)
+        throw invalid();
+    const trusted = structuredClone(target);
+    if (selected.host && (selected.host.host !== trusted.host || selected.host.username !== trusted.username || selected.host.port !== trusted.port))
+        throw invalid();
+    const captured = structuredClone(selected), stamp = physical(captured.remote), context = { instanceId: connection.instanceId, epoch: connection.epoch, workspaceId: registered.id, expectedBindingId: selected.bindingId };
+    const revoked = new AbortController(), offs = [];
+    let runtime, disposed = false;
+    const current = () => {
+        request.signal?.throwIfAborted();
+        revoked.signal.throwIfAborted();
+        if (disposed || get() !== api || api.getContractInfo().hostWorkspaceResolution !== 1)
+            throw invalid();
+        const c = api.getConnectionState(), s = api.getWorkspaceLocationState(), items = s.items.filter(row => row.workspaceId === context.workspaceId), item = items[0];
+        if (c.phase !== 'connected' || c.instanceId !== context.instanceId || c.epoch !== context.epoch)
+            throw new NeedError('CONNECTION_LOST', '远程主机连接已变化，原派发已停止；请新建会话继续。', '本轮原连接代次');
+        if (s.instanceId !== context.instanceId || s.epoch !== context.epoch)
+            throw invalid();
+        if (s.need)
+            throw connectNeedError(s.need);
+        if (item?.need)
+            throw connectNeedError(item.need);
+        if (hostIdentity(item?.host) !== hostIdentity(captured.host))
+            throw invalid();
+        if (s.phase !== 'ready' || items.length !== 1 || item.bindingId !== context.expectedBindingId || item.workspaceId !== context.workspaceId || item.source !== 'host' || item.status !== 'selected' || item.localPath !== captured.localPath || physical(item.remote) !== stamp)
+            throw invalid();
+    };
+    const revoke = (error) => { if (revoked.signal.aborted)
+        return; runtime?.closeDiagnostics?.record({ layer: 'adapter', initiator: 'host-workspace.observer', reason: error instanceof NeedError ? error.code : 'HOST_WORKSPACE_REVOKED', action: 'abort', changes: [{ field: 'host-workspace.valid', before: true, after: false }] }); revoked.abort(error); };
+    const changed = () => { if (request.signal?.aborted && !revoked.signal.aborted)
+        return; try {
+        current();
+    }
+    catch (error) {
+        revoke(error);
+    } };
+    const dispose = () => { if (disposed)
+        return; disposed = true; for (const off of offs.splice(0))
+        off(); };
+    const membership = async () => { current(); const now = await workspace(request); current(); if (now.id !== registered.id || now.path !== registered.path)
+        throw invalid(); };
+    try {
+        current();
+        offs.push(api.onWorkspaceLocationState(changed));
+        offs.push(api.onConnectionState(changed));
+        current();
+        return { revocation: revoked.signal, signal: AbortSignal.any([revoked.signal, ...(request.signal ? [request.signal] : [])]), assertCurrent: current, observeRuntime(value) { runtime = value; current(); }, dispose,
+            async resolve() {
+                try {
+                    await membership();
+                    const value = unwrap(await awaitL(() => api.resolveSessionProject(request.sessionId, { provider: provider, purpose: 'user-turn' }, { ...context }), AbortSignal.any([revoked.signal, ...(request.signal ? [request.signal] : [])])));
+                    await membership();
+                    if (!value || !('source' in value) || value.source !== 'host' || value.instanceId !== context.instanceId || value.epoch !== context.epoch || value.sessionId !== request.sessionId || value.workspaceId !== context.workspaceId || value.bindingId !== context.expectedBindingId || !Number.isSafeInteger(value.bindingRevision) || value.bindingRevision < 1 || (!value.target || !value.target.session || !sameTarget(trusted, value.target)) || physical(value.directory) !== stamp || value.project?.path !== value.directory.path || value.project?.name !== (basename(value.directory.path) || '/') || 'notice' in value && value.notice !== undefined)
+                        throw invalid();
+                    return value;
+                }
+                catch (error) {
+                    if (!request.signal?.aborted)
+                        revoke(error);
+                    throw error;
+                }
+            }
+        };
+    }
+    catch (error) {
+        dispose();
+        throw error;
+    }
+}

package/dist/index.js

@@ -1,3 +1,4 @@
+import { connectNeedMessage } from "./connect-need.js";
 import { CloseDiagnostics, withFailureEvidence, withFirstFailureEvidence, failureEvidenceSummary, closeCode, closeErrorCodes, closeFailure } from "./close-diagnostics.js";
 import { runCatalog } from "./catalog-ssh.js";
 import { createCatalogDiagnostics, CatalogDiagnosticsRemote } from "./catalog-diagnostics.js";
@@ -258,7 +259,7 @@ export class CodexRemoteAdapter extends LlmAdapter {
             if (error instanceof NeedError) {
                 const rpc = /RPC 错误码 (-?\d+)/u.exec(error.requires)?.[1];
                 const evidence = failureEvidenceSummary(error);
-                const message = employeeFailure(error.code, this.agent.loginProvider) + (rpc ? `（技术详情：RPC 错误码 ${rpc}）` : '') + (evidence ? '；' + evidence : '');
+                const message = (connectNeedMessage(error) ?? employeeFailure(error.code, this.agent.loginProvider)) + (rpc ? `（技术详情：RPC 错误码 ${rpc}）` : '') + (evidence ? '；' + evidence : '');
                 const login = originalLoginFailure(error);
                 let diagnostic = login?.technical ? JSON.stringify(login.technical) : '';
                 if (login?.technical && this.reportLoginFailure) {
@@ -426,6 +427,12 @@ export class CodexRemoteAdapter extends LlmAdapter {
                 request.signal = modelSignal;
                 modelSignal.throwIfAborted();
             }
+            if (runtime.contextSignal) {
+                modelSignal = AbortSignal.any([modelSignal, runtime.contextSignal]);
+                options.signal = modelSignal;
+                request.signal = modelSignal;
+                modelSignal.throwIfAborted();
+            }
             catalog.assertCurrent();
             if (runtime.connection && (runtime.connection.instanceId !== catalog.target.instanceId || runtime.connection.epoch !== catalog.target.epoch) || runtime.identity !== `${catalog.target.target.username}@${catalog.target.target.host}:${catalog.target.target.port}`)
                 throw new ModelConfigurationError('模型目录与当前会话可信员工主机不一致');
@@ -657,6 +664,12 @@ export class CodexRemoteAdapter extends LlmAdapter {
             yield { type: 'finish', reason: { kind: stop === 'max_tokens' || stop === 'max_turn_requests' ? 'max-tokens' : 'stop' }, replayState: { response: pointer } };
         }
         catch (error) {
+            // ACP cancellation must retain the source revocation that caused it.
+            // User cancellation and unrelated signals keep their existing semantics.
+            const sourceReason = runtime?.contextSignal?.aborted ? runtime.contextSignal.reason : undefined;
+            if (error instanceof NeedError && error.code === 'ABORTED' && sourceReason instanceof NeedError) {
+                error = Object.assign(new NeedError(sourceReason.code, sourceReason.message, sourceReason.requires), { ...(sourceReason.connectNeed ? { connectNeed: sourceReason.connectNeed } : {}), ...(sourceReason.officialReason ? { officialReason: sourceReason.officialReason } : {}), cause: new AggregateError([sourceReason, error], 'HOST_SOURCE_REVOKED') });
+            }
             turnFailure = error;
             runtime?.closeDiagnostics?.record({ layer: 'adapter', initiator: 'adapter.turn-failure', reason: closeCode(error, signal.aborted ? 'ABORTED' : 'TURN_FAILED'), action: 'failure' });
             recordInformation();

package/dist/presentation.js

@@ -9,6 +9,7 @@ export function employeeFailure(code, brand = 'codex') {
         WORKSPACE_SOURCE_CONFIRMATION_UNAVAILABLE: '我需要打开工作区来源确认，目前无法显示确认动作；本轮未执行，你的原话仍保留。',
         WORKSPACE_SOURCE_SELECTION_UNCONFIRMED: '无法核对工作区来源的确认结果，本轮已停止；你的原话仍保留。',
         WORKSPACE_SOURCE_CONFIRMATION_FAILED: '工作区来源确认未完成，本轮已停止；你的原话仍保留。',
+        PROJECT_BINDING_INVALID: '文件来源已改，请新建会话继续；原会话历史仍可查看。',
         WORKSPACE_LOCATION_REQUIRED: '我需要你确认这个工作区使用哪一个文件夹，本轮未执行；你的原话仍保留。',
         WORKSPACE_LOCATION_CONFLICT: '工作区来源选择已更新，本次确认不能覆盖新的选择；本轮未执行，你的原话仍保留。',
         LOCAL_USER_TURN_CHANGED: '本次输入已变化，本轮已停止，请确认对话后重新发送。',

package/dist/provider.d.ts

@@ -29,6 +29,7 @@ export interface EmployeeExecution {
 export interface Runtime {
     identity: string;
     cwd: string;
+    contextSignal?: AbortSignal;
     execution?: EmployeeExecution;
     acpTransport?: {
         writable: WritableStream<Uint8Array>;
@@ -141,7 +142,7 @@ type Result<T> = {
         code: string;
         message: string;
         requires: string;
-    } & Pick<ConnectNeed, 'officialReason'>;
+    } & Partial<Pick<ConnectNeed, 'officialReason' | 'layer' | 'actor' | 'action' | 'lastSeen'>>;
 };
 /** 消费正式connect-api 0.7公开子集；X不响应L登录票据、不直接调用登录。 */
 export interface ConnectApi extends Pick<LConnectApi, 'getConnectionState' | 'getLoginPromptState' | 'requestLoginPrompt' | 'refreshLoginPrompts'>, Partial<NativeWorkspaceApi>, Partial<Pick<LConnectApi, 'getWorkspaceBindingState' | 'getModelCatalogTarget' | 'onConnectionState' | 'onLoginPromptState' | 'appendRemoteConversationDetail' | 'getRemoteConversationDetailReceipt' | 'listRemoteConversationDetails' | 'getWorkspaceLocationState' | 'getLocalWorkspaceContext' | 'onWorkspaceLocationState' | 'acceptLocalWorkspaceUserTurn' | 'selectWorkspaceLocation'>> {

package/dist/provider.js

@@ -1,3 +1,5 @@
+import { hostWorkspaceGuard } from "./host-workspace.js";
+import { connectNeedError } from "./connect-need.js";
 import { loginDiagnostic, loginReason } from "./login-diagnostic.js";
 import { NeedError } from "./remote.js";
 import { CONNECTION_REQUIRED, TEST_HOST_NOTICE } from "./presentation.js";
@@ -38,8 +40,11 @@ function verifiedLogin(api, brand, expected) {
         throw new NeedError('CONNECTION_LOST', 'connection binding changed', 'current employee connection');
     requireLoginState(login);
     const reason = loginReason(login, connection, brand);
-    if (reason)
-        throw Object.assign(new NeedError(reason === 'LOGIN_REQUIRED' ? 'LOGIN_REQUIRED' : 'AUTH_STATUS_INVALID', reason === 'LOGIN_REQUIRED' ? '需要登录，请到设置 → 远程主机连接 点登录' : '无法确认当前品牌的登录状态', 'L核验的本品牌登录状态'), { technical: loginDiagnostic('verified-login', reason, brand, connection, login), ...(typeof login.providerNeeds[brand]?.officialReason === 'string' ? { officialReason: login.providerNeeds[brand].officialReason } : {}) });
+    if (reason) {
+        const original = (reason === 'LOGIN_PROVIDER_NEED' || reason === 'LOGIN_PHASE_BLOCKED') && login.instanceId === connection.instanceId ? login.providerNeeds[brand] : undefined;
+        const error = original ? connectNeedError(original) : new NeedError(reason === 'LOGIN_REQUIRED' ? 'LOGIN_REQUIRED' : 'AUTH_STATUS_INVALID', reason === 'LOGIN_REQUIRED' ? '需要登录，请到设置 → 远程主机连接 点登录' : '无法确认当前品牌的登录状态', 'L核验的本品牌登录状态');
+        throw Object.assign(error, { technical: loginDiagnostic('verified-login', reason, brand, connection, login), ...(typeof login.providerNeeds[brand]?.officialReason === 'string' ? { officialReason: login.providerNeeds[brand].officialReason } : {}) });
+    }
     return { ...connection };
 }
 /** Wait only for L's explicit in-progress evidence. No timer, polling, refresh or authorization. */
@@ -102,12 +107,12 @@ async function waitForLogin(api, brand, expected, get, signal) {
 async function ensureReady(api, brand, signal) {
     const result = await awaitL(() => api.ensureReady(brand), signal);
     if (!result.ok)
-        throw Object.assign(new NeedError(result.error.code, result.error.message, result.error.requires), { technical: loginDiagnostic('ensure-ready', 'L_ENSURE_READY_FAILED', brand, api.getConnectionState(), api.getLoginPromptState(), result.error.officialReason), ...(typeof result.error.officialReason === 'string' ? { officialReason: result.error.officialReason } : {}) });
+        throw Object.assign(connectNeedError(result.error), { technical: loginDiagnostic('ensure-ready', 'L_ENSURE_READY_FAILED', brand, api.getConnectionState(), api.getLoginPromptState(), result.error.officialReason), ...(typeof result.error.officialReason === 'string' ? { officialReason: result.error.officialReason } : {}) });
     return result.value;
 }
 export function unwrap(result) {
     if (!result.ok)
-        throw Object.assign(new NeedError(result.error.code, result.error.message, result.error.requires), typeof result.error.officialReason === 'string' ? { officialReason: result.error.officialReason } : {});
+        throw Object.assign(connectNeedError(result.error), typeof result.error.officialReason === 'string' ? { officialReason: result.error.officialReason } : {});
     return result.value;
 }
 export function validateTarget(t) {
@@ -155,6 +160,30 @@ export function sameTarget(a, b) {
 }
 export function connectProvider(get, options = {}) {
     const agent = options.agent ?? CODEX_AGENT;
+    const hostScopes = new WeakMap();
+    const hostMethods = new WeakMap();
+    const retainHostScope = (runtime, scope) => {
+        hostScopes.get(runtime)?.dispose();
+        hostScopes.set(runtime, scope);
+        runtime.contextSignal = scope.revocation;
+        if (hostMethods.has(runtime))
+            return;
+        const original = { dispose: runtime.dispose, detach: runtime.detach };
+        hostMethods.set(runtime, original);
+        const release = () => { hostScopes.get(runtime)?.dispose(); hostScopes.delete(runtime); };
+        runtime.dispose = async (cause) => { try {
+            await original.dispose?.(cause);
+        }
+        finally {
+            release();
+        } };
+        runtime.detach = async (cause) => { try {
+            await original.detach?.(cause);
+        }
+        finally {
+            release();
+        } };
+    };
     // Keep the legacy source SDK wrapper's strip-only import graph free of broker runtime syntax.
     // Cache the initialization promise so concurrent sessions share this provider's binding lifetimes.
     let employee;
@@ -203,6 +232,9 @@ export function connectProvider(get, options = {}) {
             request.localAdmissionCheck?.();
             admissions.set(request, { api, target, connection });
             sourceStage = 'local-admission';
+            const locations = api.getContractInfo().workspaceLocations === 1 ? api.getWorkspaceLocationState?.() : undefined;
+            if (locations && (locations.phase === 'failed' || locations.phase === 'disposed') && locations.instanceId === connection.instanceId && locations.epoch === connection.epoch && locations.need)
+                throw connectNeedError(locations.need);
             await options.local?.admit?.(request, api, connection, target);
             confirmedSource?.assertCurrent();
         }
@@ -228,88 +260,109 @@ export function connectProvider(get, options = {}) {
         request.localAdmissionCheck?.();
         if (!request.sessionId)
             throw new NeedError('PROJECT_BINDING_REQUIRED', '我需要当前会话和已选择的工作区，请使用原生工作区入口', 'DSH会话与原生工作区');
-        if (options.employee) {
-            employee ??= import("./employee-provider.js").then(module => module.createEmployeeProvider(get, options, agent));
-            const local = await (await employee)({ api, target, connection, request, stable: signal => request.timing.run('connection-confirm', () => waitForLogin(api, agent.loginProvider, connection, get, signal)) });
-            if (local) {
-                local.loginRequired = () => offerLogin(api, request, get, agent);
-                return local;
+        const host = await hostWorkspaceGuard(get, api, connection, target, request, options.workspaceSource?.workspace, agent.loginProvider);
+        try {
+            if (!host && options.employee) {
+                employee ??= import("./employee-provider.js").then(module => module.createEmployeeProvider(get, options, agent));
+                const local = await (await employee)({ api, target, connection, request, stable: signal => request.timing.run('connection-confirm', () => waitForLogin(api, agent.loginProvider, connection, get, signal)) });
+                if (local) {
+                    local.loginRequired = () => offerLogin(api, request, get, agent);
+                    return local;
+                }
             }
-        }
-        if (agent.loginProvider === 'claude' && options.local) {
-            const runtime = await options.local(request, api, connection, target);
-            if (runtime) {
+            if (!host && agent.loginProvider === 'claude' && options.local) {
+                const runtime = await options.local(request, api, connection, target);
+                if (runtime) {
+                    try {
+                        await stable();
+                    }
+                    catch (error) {
+                        await runtime.dispose?.();
+                        throw error;
+                    }
+                    return runtime;
+                }
+            }
+            if (!host) {
+                await options.notice?.reconcile(request, api);
+                await stable();
+            }
+            const resolved = await request.timing.run('workspace-resolve', async () => host ? host.resolve() : unwrap(await awaitL(() => api.resolveSessionProject(request.sessionId, { provider: agent.loginProvider, purpose: 'user-turn' }), request.signal)));
+            await stable();
+            host?.assertCurrent();
+            if (!resolved || resolved.instanceId !== connection.instanceId || resolved.epoch !== connection.epoch)
+                throw new NeedError('CONNECTION_LOST', '工作区解析回复已失效', '当前连接代次');
+            validateTarget(resolved.target);
+            const project = resolved.project;
+            const source = resolved.source;
+            if (resolved.sessionId !== request.sessionId || !resolved.workspaceId || !resolved.bindingId || !Number.isSafeInteger(resolved.bindingRevision) || resolved.bindingRevision < 1 || !sameTarget(target, resolved.target) || !project || (!host && (source !== undefined && source !== 'legacy-host' || typeof project.name !== 'string' || !project.name || project.name === '.' || project.name === '..' || /[\\/\x00-\x1f\x7f]/.test(project.name) || project.path !== resolved.target.projectRoot + '/' + project.name)))
+                throw new NeedError('PROJECT_BINDING_INVALID', '工作区绑定与当前会话或可信主机不一致', 'L核验的原生工作区绑定');
+            if (request.cwd && request.cwd !== project.path || request.bindingId && request.bindingId !== resolved.bindingId || request.workspaceId && request.workspaceId !== resolved.workspaceId)
+                throw new NeedError(host ? 'PROJECT_BINDING_INVALID' : 'SESSION_CONTEXT_MISMATCH', host ? '文件来源已改，请新建会话继续；原会话历史仍可查看。' : '原会话的工作区绑定已改变，请新建会话', '原工作区绑定');
+            const details = await request.timing.run('details-open', async () => options.details?.(request, api, connection, target));
+            try {
+                if (details)
+                    request.timing.bind(detail => details.record(detail));
+                await stable();
+                host?.assertCurrent();
+                let workspaceNotice = undefined;
+                const notice = !host && 'notice' in resolved ? resolved.notice : undefined;
+                if (notice) {
+                    if (!options.notice)
+                        throw new NeedError('DEPENDENCY_REQUIRED', '我需要官方会话持久记录来确认工作区说明', '官方会话与持久化服务');
+                    workspaceNotice = await request.timing.run('workspace-notice', () => options.notice.deliver(notice, resolved, request, api));
+                    await stable();
+                }
+                if (!options.open)
+                    throw new NeedError('RUNTIME_REQUIRED', '我需要主机运行适配器', '主机broker适配');
+                const observedBinding = host ? undefined : api.getWorkspaceBindingState?.();
+                const validateContext = async (ignoreCancellation = false) => {
+                    const check = () => waitForLogin(api, agent.loginProvider, connection, get, ignoreCancellation ? undefined : request.signal);
+                    await check();
+                    if (host && !ignoreCancellation)
+                        await host.resolve();
+                    if (observedBinding) {
+                        const current = api.getWorkspaceBindingState();
+                        if (current.instanceId !== observedBinding.instanceId || !current.items.some(item => item.bindingId === resolved.bindingId && item.workspaceId === resolved.workspaceId && item.status === 'ready'))
+                            throw new NeedError('SESSION_CONTEXT_MISMATCH', '当前工作区绑定已改变，原会话操作未执行', '原生会话原绑定');
+                    }
+                    await check();
+                    if (!ignoreCancellation)
+                        host?.assertCurrent();
+                };
+                host?.assertCurrent();
+                const runtime = await options.open(resolved.target, project, { ...request, ...(host ? { signal: host.signal } : {}), agent, bindingId: resolved.bindingId, workspaceId: resolved.workspaceId, bindingRevision: resolved.bindingRevision, detailChannel: details, validateContext });
                 try {
                     await stable();
+                    host?.observeRuntime(runtime);
                 }
                 catch (error) {
                     await runtime.dispose?.();
                     throw error;
                 }
+                if (host)
+                    retainHostScope(runtime, host);
+                // The transport can outlive a turn; presentation belongs only to this invocation.
+                runtime.workspaceNotice = workspaceNotice || undefined;
+                runtime.details = details ?? runtime.details;
+                runtime.binding = { bindingId: resolved.bindingId, workspaceId: resolved.workspaceId, revision: resolved.bindingRevision };
+                runtime.connection = { ...connection };
+                runtime.loginRequired = () => offerLogin(api, request, get, agent);
                 return runtime;
             }
-        }
-        await options.notice?.reconcile(request, api);
-        await stable();
-        const resolved = await request.timing.run('workspace-resolve', async () => unwrap(await awaitL(() => api.resolveSessionProject(request.sessionId, { provider: agent.loginProvider, purpose: 'user-turn' }), request.signal)));
-        await stable();
-        if (!resolved || resolved.instanceId !== connection.instanceId || resolved.epoch !== connection.epoch)
-            throw new NeedError('CONNECTION_LOST', '工作区解析回复已失效', '当前连接代次');
-        validateTarget(resolved.target);
-        const project = resolved.project;
-        if (resolved.sessionId !== request.sessionId || !resolved.workspaceId || !resolved.bindingId || !Number.isSafeInteger(resolved.bindingRevision) || resolved.bindingRevision < 1 || !sameTarget(target, resolved.target) || !project || typeof project.name !== 'string' || !project.name || project.name === '.' || project.name === '..' || /[\\/\x00-\x1f\x7f]/.test(project.name) || project.path !== resolved.target.projectRoot + '/' + project.name)
-            throw new NeedError('PROJECT_BINDING_INVALID', '工作区绑定与当前会话或可信主机不一致', 'L核验的原生工作区绑定');
-        if (request.cwd && request.cwd !== project.path || request.bindingId && request.bindingId !== resolved.bindingId || request.workspaceId && request.workspaceId !== resolved.workspaceId)
-            throw new NeedError('SESSION_CONTEXT_MISMATCH', '原会话的工作区绑定已改变，请新建会话', '原工作区绑定');
-        const details = await request.timing.run('details-open', async () => options.details?.(request, api, connection, target));
-        try {
-            if (details)
-                request.timing.bind(detail => details.record(detail));
-            await stable();
-            let workspaceNotice = undefined;
-            if (resolved.notice) {
-                if (!options.notice)
-                    throw new NeedError('DEPENDENCY_REQUIRED', '我需要官方会话持久记录来确认工作区说明', '官方会话与持久化服务');
-                workspaceNotice = await request.timing.run('workspace-notice', () => options.notice.deliver(resolved.notice, resolved, request, api));
-                await stable();
-            }
-            if (!options.open)
-                throw new NeedError('RUNTIME_REQUIRED', '我需要主机运行适配器', '主机broker适配');
-            const observedBinding = api.getWorkspaceBindingState?.();
-            const validateContext = async (ignoreCancellation = false) => {
-                const check = () => waitForLogin(api, agent.loginProvider, connection, get, ignoreCancellation ? undefined : request.signal);
-                await check();
-                if (observedBinding) {
-                    const current = api.getWorkspaceBindingState();
-                    if (current.instanceId !== observedBinding.instanceId || !current.items.some(item => item.bindingId === resolved.bindingId && item.workspaceId === resolved.workspaceId && item.status === 'ready'))
-                        throw new NeedError('SESSION_CONTEXT_MISMATCH', '当前工作区绑定已改变，原会话操作未执行', '原生会话原绑定');
-                }
-                await check();
-            };
-            const runtime = await options.open(resolved.target, project, { ...request, agent, bindingId: resolved.bindingId, workspaceId: resolved.workspaceId, bindingRevision: resolved.bindingRevision, detailChannel: details, validateContext });
-            try {
-                await stable();
-            }
             catch (error) {
-                await runtime.dispose?.();
+                try {
+                    await details?.flush();
+                }
+                catch (diagnostic) {
+                    const code = (value) => value instanceof NeedError && /^[A-Z][A-Z0-9_]*$/.test(value.code) ? value.code : 'UNKNOWN_FAILURE';
+                    throw new NeedError('CONVERSATION_DETAILS_FAILED', '技术详情未能保存；本轮已停止', `原错误代码 ${code(error)}；诊断错误代码 ${code(diagnostic)}`);
+                }
                 throw error;
             }
-            // The transport can outlive a turn; presentation belongs only to this invocation.
-            runtime.workspaceNotice = workspaceNotice || undefined;
-            runtime.details = details ?? runtime.details;
-            runtime.binding = { bindingId: resolved.bindingId, workspaceId: resolved.workspaceId, revision: resolved.bindingRevision };
-            runtime.connection = { ...connection };
-            runtime.loginRequired = () => offerLogin(api, request, get, agent);
-            return runtime;
         }
         catch (error) {
-            try {
-                await details?.flush();
-            }
-            catch (diagnostic) {
-                const code = (value) => value instanceof NeedError && /^[A-Z][A-Z0-9_]*$/.test(value.code) ? value.code : 'UNKNOWN_FAILURE';
-                throw new NeedError('CONVERSATION_DETAILS_FAILED', '技术详情未能保存；本轮已停止', `原错误代码 ${code(error)}；诊断错误代码 ${code(diagnostic)}`);
-            }
+            host?.dispose();
             throw error;
         }
     };

package/dist/remote.d.ts

@@ -1,3 +1,4 @@
+import type { ConnectNeed } from '@ai-workbench/connect/api';
 import type { LoginDiagnostic } from './login-diagnostic.ts';
 import type { ChildProcessWithoutNullStreams } from 'node:child_process';
 /** Development-only direct SSH. Product transports must consume L's exported sshArgs (v0.2). */
@@ -19,6 +20,7 @@ export declare class NeedError extends Error {
     requires: string;
     technical?: LoginDiagnostic;
     officialReason?: string;
+    connectNeed?: Readonly<ConnectNeed>;
     constructor(code: string, message: string, requires: string);
 }
 export declare function shellQuote(value: string): string;

package/dist/remote.js

@@ -4,6 +4,7 @@ export class NeedError extends Error {
     requires;
     technical;
     officialReason;
+    connectNeed;
     constructor(code, message, requires) {
         super(message);
         this.name = 'NeedError';

package/dist/workspace-source.js

@@ -1,4 +1,5 @@
 import { withFailureEvidence } from "./failure-evidence.js";
+import { connectNeedError } from "./connect-need.js";
 import { isDeepStrictEqual } from 'node:util';
 import { sanitizeDisplayLabel } from "./conversation-details.js";
 import { NeedError } from "./remote.js";
@@ -82,7 +83,7 @@ export async function confirmLegacyWorkspaceSource(get, api, request, hooks) {
             const selected = await api.selectWorkspaceLocation({ instanceId: connection.instanceId, epoch: connection.epoch, workspaceId: workspace.id, expectedBindingId: frozen.bindingId, source: 'local' });
             request.signal?.throwIfAborted();
             if (!selected.ok)
-                throw new NeedError(selected.error.code, selected.error.message, selected.error.requires);
+                throw connectNeedError(selected.error);
             const current = await stable(false), value = selected.value, returned = value.items.filter(item => item.workspaceId === workspace.id);
             if (value.phase !== 'ready' || value.instanceId !== connection.instanceId || value.epoch !== connection.epoch || returned.length !== 1 || returned[0].source !== 'local' || returned[0].status !== 'selected' || !returned[0].bindingId || returned[0].bindingId === frozen.bindingId || returned[0].localPath !== workspace.path || current.source !== 'local' || current.status !== 'selected' || current.bindingId !== returned[0].bindingId)
                 throw fail('WORKSPACE_SOURCE_SELECTION_UNCONFIRMED');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-workbench/remote-agent",
-  "version": "0.8.16",
+  "version": "0.8.17",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -39,7 +39,7 @@
     "zod": "4.6.7"
   },
   "devDependencies": {
-    "@ai-workbench/connect": "file:test/fixtures/ai-workbench-connect-0.7.19.tgz",
+    "@ai-workbench/connect": "file:test/fixtures/ai-workbench-connect-0.7.20.tgz",
     "@ai-workbench/network": "file:test/fixtures/ai-workbench-network-0.4.4.tgz",
     "@deepseek-ai/cordis": "4.0.4",
     "@deepseek-ai/cordis-plugin-group": "1.0.4",
@@ -68,7 +68,7 @@
     "zustand": "4.4.7"
   },
   "peerDependencies": {
-    "@ai-workbench/connect": "~0.7.19",
+    "@ai-workbench/connect": "~0.7.20",
     "@ai-workbench/network": "~0.4.4",
     "@deepseek-ai/cordis": "4.0.4",
     "@deepseek-ai/dsh-agent": "0.2.0-rc.2",