fix: make managed SSH sessions fast and resilient

Managed SSH project selection repeatedly activated the remote Host and could
leave idle ACP bindings rejected as stale-controller after a controller
generation change. Host environment updates also coupled project state to
component installation evidence and presented a crowded control surface.

Project selection is now local-only, one Host connection serves compatible
project and conversation callers, idle bindings are safely replaced only
after proven controller takeover, and active prompts keep exact resume/replay.
Remote environment setup now uses explicit signed compound package
preparation with bounded transfer, rollback, recovery, and clearer settings.

Managed Hosts must be updated to separately distributed Agent 0.11.6 before
the daemon-side controller recovery fix takes effect. Desktop packages do not
embed the Agent or remote Runtime, and existing project data is preserved.

Release note: 托管 SSH 项目切换不再重复连接，同一 Host 可顺畅承载多个项目和对话；同时修复重连后的 stale-controller，并优化远程环境安装、更新与状态布局。

docs/README.md

@@ -35,6 +35,7 @@ GoodBuddy 文档按“文档类型 → 功能域”组织。新增文档应先
 - [DeepSeek Harness Runtime 设计](./architecture/deepseek-harness-runtime-design.md)
 - [应用内反馈系统设计与对接](./architecture/in-app-feedback-integration-design.md)
 - [SSH 远程主机与 GoodBuddy Agent 稳定终态设计](./architecture/remote-host-and-goodbuddy-agent-design.md)
+- [SSH Host 远程环境准备与控制面直连设计](./architecture/remote-host-environment-provisioning-design.md)
 - [跨平台助手产品设计](./design/cross-platform-assistant-product-design.md)
 - [长期助手路线图](./roadmap/long-term-assistant-roadmap.md)
 - [电脑控制实施状态](./status/computer-control-implementation-status.md)

docs/architecture/remote-host-and-goodbuddy-agent-design.md

@@ -2,14 +2,28 @@
 
 ## 状态
 
-本文记录当前代码实现，不定义额外的信任框架。Windows 到 Linux x64 的安装、Main-only 模型桥、断线恢复、输出重放、同一 OpenCode Session 续接与终态清理已经在真实 Host 上完成 provider-free 验证。上一轮 Linux x64 验收使用 Agent `0.11.2-e2e.12` 与 OpenCode Runtime `1.18.9` 完成了一次有界真实模型工具调用；加入每 helper 随机 loopback 路径 capability 后，当前源码 lock 已转为正式 Agent `0.11.5`。失败的 `agent-v0.11.3` 保持不可变且未发布。远程 OpenCode 功能仍处于发布前验证阶段；公开签名 key registry 已供应，当前发布门槛是通过独立 Agent workflow 正式发布并公开验证 Linux x64/arm64 复合包和签名累计目录。
+本文记录截至 2026-08-28 的当前代码实现，不定义额外的信任框架。“新增 Host 只探测、Host 卡片手动准备
+Agent/Runtime、Host 直接从 GitHub/北京镜像下载、项目始终使用 Host current 环境”已经完成源码接线，
+详细事务与验收边界见
+[SSH Host 远程环境准备与直连下载设计](./remote-host-environment-provisioning-design.md)；
+控制面直连源码可直接使用既有 package format v1 包，不等待携带 installer 的新 Agent
+包，也不通过额外目录元数据判断 bootstrap 能力；公开能力仍等待 GitHub/北京镜像、
+Linux x64/arm64、取消和离线 GoodBuddy 传输的真实 Host 验收。
+Windows 到 Linux x64 的既有安装、
+Main-only 模型桥、断线恢复、输出重放、同一 OpenCode Session 续接与终态清理已经在真实
+Host 上完成 provider-free 验证。上一轮 Linux x64 验收使用 Agent `0.11.2-e2e.12` 与
+OpenCode Runtime `1.18.9` 完成了一次有界真实模型工具调用；加入每 helper 随机 loopback
+路径 capability 后，当前源码 lock 已更新为待发布 Agent `0.11.6`。失败的 `agent-v0.11.3`
+保持不可变且未发布。远程 OpenCode 功能仍处于发布前验证阶段；公开签名 key registry
+已供应，当前发布门槛是通过独立 Agent workflow 正式发布并公开验证 Linux x64/arm64
+复合包和签名累计目录。
 
 ## 产品语义
 
 远程 Host 与项目能力是默认关闭的技术预览。用户在“设置 > 平台功能”的独立
 “远程项目（技术预览）”页签启用开关后，Renderer 才显示 SSH Host 管理、托管 SSH 项目创建和已保存
 远程项目；Main 在 IPC 边界执行同一开关校验，避免隐藏界面被绕过。关闭开关不删除 Host、
-项目或凭据；进行中的激活允许取消，当前远程项目切回第一个普通本地项目。应用启动仍固定
+项目或凭据；当前远程项目切回第一个普通本地项目。应用启动仍固定
 选择普通本地项目，不会因为保存了远程项目而自动连接 Host。
 
 远程项目只有两种工作模式：
@@ -28,7 +42,7 @@ Main
   -> SSH Host 与 Host Key 管理
   -> SSH connection pool
   -> 签名 Agent / Runtime 安装
-  -> 远程项目验证与 SQLite 事务
+  -> 远程项目当前环境准备与稳定配置 SQLite 事务
   -> Main-owned model bridge
 SSH attach
   -> 远端私有 Unix socket
@@ -46,7 +60,7 @@ Detached GoodBuddy Agent
 - Main 在认证前取得 Host Key，展示算法与 SHA-256 指纹，并保存完整 key blob。
 - 首次连接需要用户确认。Host Key 变化展示旧/新值并要求显式替换。
 - 密码使用 Electron `safeStorage`；系统 SSH Agent 认证不启用 Agent forwarding。
-- Host 地址、用户或 Host Key generation 变化时关闭旧连接，并定向退役依赖旧 Host identity 的 Workspace 和 Runtime 会话。保存开始后，所有引用该 Host 的项目保持“需要重新激活”状态；当前项目立即执行完整激活并原子刷新 Host revision 等验证结果，其他项目在下次选择时刷新。激活失败或取消不会恢复发送能力，Composer 和来自 Main 持久队列的用户消息都要等待后续成功激活；排队消息会退回原队列，并在成功后通过既有 queue-ready 流程继续。用户重新选择当前 SSH 项目也会显式触发相同验证，而不是复用旧项目快照。
+- Host 地址、用户或 Host Key generation 变化时关闭旧连接，并定向退役依赖旧 Host identity 的 Workspace 和 Runtime 会话。下一次选择使用 Host 管理的当前连接记录解析 current Agent/Runtime，不读取项目中的旧 revision 或组件 identity；当前 registry、连接或 capability 无效时才要求显式修复。
 
 ## Agent 安装与生命周期
 
@@ -56,23 +70,83 @@ Detached GoodBuddy Agent
   manifest、registry identity、owner/mode/size 和 Node digest 都可验证，且候选
   manifest 声明完全相同的 Node，安装器直接在新的 side-by-side 目录中复用该 Node；
   否则正常上传候选 Node。Agent 不匹配不会阻止升级，也不会覆盖旧安装。
-- 桌面包只携带版本 lock 与 production 公钥，不携带远端 payload。用户必须先在设置中显式下载最新兼容的目标架构复合包，或导入离线 `.gbagent`；项目激活不会联网下载。每个复合包绑定 Agent、固定 Node 与桌面维护的 OpenCode Runtime 精确工件。应用重启固定进入第一个普通本地项目，不自动连接上次远程项目；用户主动切换托管 SSH 项目时，Main 从本地验证缓存选择 Host 架构工件，Host 尚未安装该 identity 时上传并启动。相同 Renderer 对同一项目的并发激活共享一个 Main 操作。
-- Agent、Workspace 和 Runtime 全部验证成功后，Main 才在同一 SQLite 事务中刷新项目保存的 Agent/Runtime evidence，然后把项目设为当前项目。上传、启动、验证或事务失败时，项目继续绑定旧 identity，不能用未提交的新 identity 绕过持久化绑定校验。
+- 桌面包只携带版本 lock 与 production 公钥，不携带远端 payload。Host 卡片只有一个按
+  版本事实显示“安装远程环境”“更新远程环境”或“重新安装”的主按钮；次级
+  SegmentedControl 选择“自动”“Host 下载”或“GoodBuddy 传输”，默认“自动”且不持久化。
+  每个复合包绑定 Agent、固定 Node 与桌面维护的 OpenCode Runtime 精确工件。添加或重新
+  验证 Host 只保存并探测，不自动传输完整包。
+- Host 管理独占 Agent/Runtime 的包准备、更新和完整 payload 验证。已有项目的打开和切换
+  只更新本地项目选择。Workspace 和执行路径按需通过安装管理器解析 Host current identity，
+  执行固定 `attach-or-bootstrap` 并复用当前 Agent 连接；同一进程内复用已确认 identity。
+  它们不取得安装包、不发布组件，也不通过 SFTP 重读或哈希 payload。
+- Agent 的固定 attach/按需启动命令只读取 Host 管理已提交的 installation registry 和
+  与其 digest 匹配的有界 manifest 元数据，不在每次项目切换时重新验签或哈希完整 payload。
+  完整验签、payload 扫描和 registry 写入仍只发生在显式 Host 准备/更新流程。
+- 项目切换不执行远程核对，立即选择本地项目配置。Workspace 或 Runtime 首次实际使用时
+  才通过当前 Agent 连接核对所需能力；失败只影响该操作。新建或显式保存项目仍执行完整
+  准备，并只事务写入 Host、路径、Runtime 选择和工作模式。
 - SSH 连接先尝试 attach；Agent 不存在或未运行时执行幂等 bootstrap，然后重新 attach。
 - Agent 是按需启动的 detached process，不注册开机服务，不依赖 systemd、D-Bus 或 Linger。
 - 每个模型桥 helper 都为 loopback HTTP 入口生成一次性随机路径 capability；只有写入当前 OpenCode 子进程配置的 URL 可以访问该入口，其他本机用户即使发现临时端口也不能提交模型请求。
 - Agent 监听当前用户拥有的私有 Unix socket。SSH 中断只关闭 relay，不拥有 Agent 和活动 Runtime 的生命周期。
-- SSH Host 设置通过固定探针和有界 SFTP 显示 Host 已登记的 Agent/OpenCode 版本，并与当前 GoodBuddy 所需版本比较；打开设置或“刷新版本”只读取状态，不安装或切换远端组件。
+- SSH Host 设置通过固定探针和有界 SFTP 显示 Host 已登记的 Agent/OpenCode 版本，并与当前
+  GoodBuddy 所需版本比较。进入或切回该设置页只读取本地 Host 列表，不连接任何 Host；
+  用户点击“刷新版本”后才探测对应 Host，探测不安装或切换远端组件。项目切换与此按钮
+  解耦且不建立连接；实际远程操作才建立或复用 SSH/Agent 连接。
 - “平台功能 > 远程项目”中的本地 Agent 包清单与 Host 状态分离。Main 对用户数据目录中
   Linux x64/arm64 `.gbagent` 分别执行外层可信签名、桌面/协议兼容性、内部 Agent/Runtime
   签名、架构与完整 payload 校验；首次打开和手动刷新还会读取“关于与更新”所选来源的
   小型签名目录。Renderer 只得到本地/在线版本、是否有更新、架构、远端 Runtime 版本、
   协议和本地状态，不得到缓存路径、key ID 或 digest。目录检查不下载 `.gbagent`，在线
   包下载只由用户点击带目标版本的操作触发；离线导入/导出通过 Main 管理的文件对话框完成。
-- 当任一组件缺失或不是当前版本时，用户可显式选择“更新版本”。Main 使用同一个取消信号依次强制执行 Agent、Runtime 安装器，并把 Agent、Runtime、Finalizing 阶段只发送给发起更新的 Renderer。更新启动仍受技术预览开关和可信 Sender 校验约束；取消不受开关约束，确保操作开始后即使关闭功能也能停止。
-- 更新成功后才定向清理该 Host 的 Agent 连接和 Runtime 选择缓存，并让当前引用项目重新激活；失败或取消保留 Host 配置、凭据、项目、Workspace 和可继续验证的旧组件，Renderer 刷新实际版本并允许重试。同一 Renderer 同时只更新一个 Host，窗口销毁或 Main 退出会取消活动更新并执行有界收尾。
+- “自动”只在 operation/prepare 前用 Host capability probe 选择 acquisition：直连明确
+  可用才选 Host 下载，否则选 GoodBuddy 传输；显式选择不被改写。prepare、commit 或
+  adoption 失败后都不跨 acquisition 自动 fallback。
+- Host 下载由桌面控制面通过固定 SSH prepare channel 和结构化 stdin 发送候选信息，
+  Host 取得 compound `.gbagent` 并核对大小与 SHA-256。GoodBuddy 传输在本地缺少精确
+  候选时，于同一次操作下载、验 SHA-256 与签名、缓存并取得 lease，再以有界流式 SFTP
+  上传一个 compound archive 和归档中已验证的 bootstrap Node；约 294 MiB 完整包不会
+  一次读入 Main `Buffer`，Host 仍再次校验完整包。
+- 两种 acquisition 交付到固定 operation staging 后，完全共用 control-plane
+  `prepare → commit → Agent activate/health → Runtime activate → finalize → cleanup`。
+  commit 终态持久化；通道丢失只用 `commit-status` 只读恢复，不重放 commit。prepare
+  完成后、commit 前快照 Agent/Runtime 五个 metadata 文件，任一组件 adoption 失败都恢复其原字节或原缺失
+  状态；已经发布的 side-by-side payload 可以保留但不能成为 current。确认 adoption 后
+  才显式 cleanup。首次 bootstrap 不依赖既有 Agent daemon，也不要求 format v1 归档携带
+  `agent/lib/package-installer.cjs`。
+- 即使版本号均为当前版本，Host 卡片仍提供同版本“重新安装”，用于修复 registry、签名
+  或安装 identity 异常。GoodBuddy-owned 同 digest 目录损坏时先隔离后替换，并在发布或
+  激活失败时恢复；不要求删除 Host、凭据或引用项目。
+- Host 卡片的“版本匹配”badge 只表达版本事实，不代表 Agent 正在运行或环境健康。重新安装
+  失败时明确显示本次操作未完成，并以随后重新检查的版本卡片表达当前事实；提交结果
+  不确定时不声称旧版本未被替换。
+- 更新成功后才定向清理该 Host 的 Agent 连接和 Runtime 选择缓存。引用项目再次打开时
+  解析新的 current registry 并建立当前连接，无需刷新项目记录；当前环境无效时要求用户
+  显式修复，但不在项目切换中下载或安装。失败或取消保留 Host 配置、凭据、项目、
+  Workspace 和旧组件。
 - 显式 stop、升级、身份冲突或进程退出时清理 GoodBuddy 自己的 socket、状态和子进程；不得删除或覆盖无关 Host 文件。
 
+### Host 级环境生命周期
+
+- Agent、Node 和 Runtime 是 Host/SSH 账号级共享环境。新增或重新验证 Host 后先保存 Host
+  并只读探测，不自动安装；用户随后在 Host 卡片明确选择安装或更新方式，失败保留 Host
+  并允许重试。
+- Host 可以按签名目录固定的 URL、大小和 SHA-256 直接从当前 GitHub/北京镜像来源下载
+  完整 `.gbagent`，也可使用 GoodBuddy 本机下载、流式 SFTP 传输和离线导入。自动模式只在
+  操作开始时择一；执行失败不会在同一次操作中切换 acquisition。
+- 项目只保存 Host ID、远端路径、Runtime 选择和默认模式。创建或保存时验证 Host current
+  环境；打开或切换只读取本地配置。Workspace/Runtime 实际使用时从 Host current registry
+  和当前 Agent 连接取得 live identity，不再扫描、下载、上传或发布 Agent/Runtime。完整
+  事务、兼容边界和验收要求以
+  [Host 环境准备设计](./remote-host-environment-provisioning-design.md) 为准。
+- 打开新建/项目设置弹窗只读取本地 Host 验证记录，不并发检查所有 Host；目录浏览或保存
+  才连接所选 Host。
+- 项目选择器中的管理操作默认浮动隐藏，在悬停、键盘焦点或触屏环境显示。管理任意已保存
+  项目不先激活项目，因此 Host 不可达或远端目录已不存在时仍可删除其本地记录。
+- 删除 Host 时确认框列出所有引用它的本地项目记录，包括归档项目。确认后只删除本机
+  Host、凭据、项目及其关联记录，不连接 Host、不删除远端目录或内容；Host 设置写入或
+  项目事务失败时恢复另一侧，避免只删掉其中一类本地记录。
+
 ## Workspace
 
 Main 传入已规范化的绝对 POSIX root。Agent 返回 Workspace identity、访问模式、Git 状态和有界能力。
@@ -132,7 +206,7 @@ Execute 不经过 Ask 的 bubblewrap profile：
   调度、跨 channel 超车、批发送或第二套拥塞控制。
 - Agent 在把 Main 输入交给 Runtime 前、以及把 Runtime 输出交给 Main 前，先把 ACP frame 写入本机 journal。ACK 只推进 cursor 并裁剪已确认 frame，不表示 channel 已终止。
 - Main 持久化 binding identity 和单调 cursor；保留中的 connection lease 即使处于 offline/reconnecting，也可以先把新 cursor 落盘。重连提交不能覆盖 resume 过程中并发落盘的更新。
-- 同一 detached Agent 存活时，短暂 SSH 断线依次执行 `controller/resume`、`runtime/resumeAcpChannel` 和 `runtime/replayAcpChannel`，从 Main 已确认的 cursor 后只重放 Agent 到 Main 的已记录输出。重复 frame 会被确认但不会再次交给上层。
+- 同一 detached Agent 存活时，短暂 SSH 断线依次执行 `controller/resume`、`runtime/resumeAcpChannel` 和 `runtime/replayAcpChannel`，从 Main 已确认的 cursor 后只重放 Agent 到 Main 的已记录输出。重复 frame 会被确认但不会再次交给上层。若上一代连接只留下没有活动请求的 detached binding，完成精确 controller takeover 后会先有界停止并核对遗留 Runtime process，再用新 channel epoch 重新打开同一 binding 并恢复已有 ACP session；其他 controller、未证明 takeover 或仍有活动请求的 binding 仍被拒绝。
 - Main 到 Runtime 的 ACP 输入、模型请求、工具请求和 blob 不自动重放。
 - 无法确认外部 Provider 是否已处理的模型调用保持结果未知，避免重复计费或重复副作用。
 - 只有远端返回 identity 匹配且 `closed: true` 时，Main 才删除持久化 binding；传输失败或未确认 close 会保留 recovery identity。
@@ -170,7 +244,7 @@ Execute 不经过 Ask 的 bubblewrap profile：
 
 - 2026-08 的本地 fixture 完整验证 Linux x64 Agent `0.11.2-e2e.12`、Node `24.19.0`
   和 Agent protocol `2.0`；当时没有 arm64 fixture，因此该记录不能作为当前独立发布
-  的双架构验收。当前源码 lock 是正式版本 `0.11.5`，需要由新的复合包发布流程另行验证。
+  的双架构验收。当前源码 lock 是待发布版本 `0.11.6`，需要由新的复合包发布流程另行验证。
 - 正常 Host 更新路径把 Linux x64 Host 的 Agent 更新为 `0.11.2-e2e.12`，并确认
   OpenCode Runtime 已安装版本与所需版本均为 `1.18.9`。
 - 一条新的 Ask 用户操作只提交一次。OpenCode 先在 build 模型轮次请求一个原生
@@ -182,31 +256,36 @@ Execute 不经过 Ask 的 bubblewrap profile：
 
 ## 项目保存
 
-远程项目持久化稳定配置和当前验证结果：
+远程项目只持久化稳定配置：
 
-- Host ID、Host revision 与 Host Key generation；
-- 远端工作目录和 Workspace identity；
-- Agent installation identity；
-- Runtime selection、bundle digest、adapter digest；
-- `ask | execute`。
+- Host ID；
+- 规范远端工作目录；
+- Runtime selection；
+- `ask | execute` 默认模式。
 
-打开托管 SSH 项目会从这些已保存字段重建验证输入，不接受 Renderer 回传的旧项目草稿。桌面更新后，用户先显式准备兼容复合包，第一次打开才可安装对应 Agent/Runtime 并原子刷新以上字段，同时保留项目名称、说明、Host、远端工作目录、Runtime selection 和默认工作模式。
+Agent installation、Host revision/Host Key generation、Workspace identity、Runtime
+bundle/adapter digest 和 capability generation 都属于 live connection/lease，不进入项目
+domain object 或 SQLite。打开托管 SSH 项目不接受 Renderer 回传的旧项目草稿，而是从 Host
+store 解析当前连接目标，通过 Agent/Runtime 安装管理器的 current/activate 读取路径取得
+registry identity，再用同一个 Agent 连接验证 Workspace 路径和 Runtime capability。该流程
+不会扫描完整 payload、取得安装包或发布组件。
 
-请求前置校验只要求 Workspace 验证与 Runtime 验证来自同一个当前 Agent
-installation。它不比较激活时保存的模型 profile 或默认工作模式与当前会话选择，
-因为这些不是签名远端 Runtime 的身份；切换当前模型配置或 Ask/Execute 不需要重新激活
-项目。实时 Runtime 创建仍只接受 OpenCode，使用当前解析后的模型 profile 建立 Main-only
-模型桥，并再次精确核对 Agent identity、Runtime bundle/adapter digest、架构、capability
-和连接身份。Ask/Execute 权限继续由每次 Prompt 的 ACP Runtime 边界执行。
+实时 Runtime 创建只接受 OpenCode，使用当前解析后的模型 profile 建立 Main-only 模型桥，
+从当前 Agent 连接和 Runtime registry 取得会话 identity，并在该连接上打开 Workspace 和
+ACP channel。Host 编辑或环境更新会定向失效 Agent 连接与 Runtime 缓存，下一次请求自然
+重新取得 current 环境；无需修改项目。Ask/Execute 权限继续由每次 Prompt 的 ACP Runtime
+边界执行。
 
-Renderer 在用户主动打开托管 SSH 项目时订阅同一次 Main 保存操作的进度，依次显示
-Host、Agent、Workspace、Runtime 和 Saving。操作完成、失败或取消后会清除阻塞进度；
-进行中可显式取消，并禁用会产生冲突的项目切换、创建和设置入口。远端 RPC 拒绝只向
+Renderer 在用户主动打开已有托管 SSH 项目时立即切换，不显示远程激活状态。Host、Agent、
+Workspace、Runtime 和 Saving 进度仅用于新建或显式保存项目；进行中可显式取消并禁用会
+产生冲突的项目创建和设置入口。远端 RPC 拒绝只向
 Renderer 暴露固定方法名、数字 RPC code 和有界 service code，不转发 Host 私有错误详情。
 `runtime/preparePrompt` 在远端明确拒绝且尚未接受 Prompt 时会关闭对应 Main binding，
 不会把确定性失败错误保留为 `outcome-unknown`。
 
-不持久化 T2/T3、consent、approval bridge 或 confinement 证明。数据库迁移可以保留旧列以安全读取历史数据库，但新 domain object 不再暴露这些字段。
+不持久化 T2/T3、consent、approval bridge、confinement 或组件验证结果。数据库 schema
+v31 保留项目及关联用户数据，但重建执行空间表为 `project_id/kind/root_path/ssh_host_id`
+四列，并删除旧 Runtime 验证表。
 
 ## 资源与发布
 

docs/architecture/remote-host-environment-provisioning-design.md

@@ -0,0 +1,320 @@
+# SSH Host 远程环境准备与直连下载设计
+
+## 状态
+
+本文记录 2026-08-28 确认的目标设计及当前实施状态。源码已经实现 Host 手动准备、
+GoodBuddy 传输、Host 直连下载、control-plane one-shot installer、发布后健康 adoption，
+以及项目路径只验证已安装环境。Host 负责 Agent/Runtime 的安装与更新生命周期，项目流程
+只消费已经准备好的 Host 环境。
+
+当前源码可以直接使用既有 package format v1 `.gbagent`：归档已经包含固定 Agent 和
+Node，installer 由 GoodBuddy 桌面控制面打包并通过固定 SSH prepare channel 单次发送，
+不要求归档包含 `agent/lib/package-installer.cjs`，签名目录也不提供或检查额外的
+bootstrap 能力元数据。公开直连能力仍须完成本文末尾 GitHub/北京镜像、Linux x64/arm64、
+取消和离线 GoodBuddy 传输的真实 Host 验收；本文
+不表示这些验收或新的 Agent 发布已经发生。当前实现细节同时以
+[SSH 远程主机与 GoodBuddy Agent 实现说明](./remote-host-and-goodbuddy-agent-design.md)
+和源码为准。
+
+## 设计结论
+
+将安装和更新从项目切换移到 Host 管理是合理的，原因如下：
+
+- Agent、固定 Node 和 OpenCode Runtime 安装在 SSH 账号 Home 下，由同一 Host/账号上的
+  多个项目共享，不属于某一个 Workspace。
+- 大文件传输发生在项目切换时会阻塞导航，也把 Host 级故障误显示成项目故障。
+- Host Key、认证、平台和架构本来就在新增 Host 时验证，此时继续只读探测并在 Host 卡片
+  提供手动准备入口最容易理解。
+- 项目只保存 Host ID、远端路径、Runtime 选择和默认工作模式。Agent installation、
+  Runtime digest、Workspace identity 和 Host revision 都从当次连接取得，不写入项目；
+  “移出安装”不等于“跳过当前环境检查”。
+
+目标职责是：
+
+| 流程 | 职责 |
+| --- | --- |
+| 新增或重新验证 Host | 验证身份和认证，保存 Host 并探测环境，不传输安装包 |
+| Host 管理 | 用户明确刷新目标 Host，并可选择安装、同版本重修、取消和重试 |
+| 创建远程项目 | 只读本地 Host 验证记录，保存时连接所选 Host 并验证当前 Agent、Workspace、Runtime 和模型配置，只持久化稳定配置 |
+| 切换远程项目 | 只切换本地项目配置，不连接 Host；实际使用 Workspace 或 Runtime 时按需复用 Host 当前环境 |
+
+## 不变量
+
+- Host 配置与远程环境准备是两个事务。SSH 验证成功后先原子保存 Host、凭据和完整 Host
+  Key，再开始可能耗时的下载和安装。
+- 环境准备失败或取消时保留已保存 Host，显示“未就绪”并允许重试，不创建半完成项目。
+- 不把“环境健康”保存为长期可信布尔值。设置页从 Host 的签名 registry 和当前 Host
+  identity 派生版本状态；准备完成和实际使用时再执行 bootstrap/health。合法但暂未运行的
+  detached Agent 仍可显示为已安装，打开设置不能为了刷新卡片隐式启动或更新它。
+- 所有安装继续使用 GoodBuddy-owned staging 和 side-by-side digest 目录。失败不得覆盖
+  可用旧安装，也不得删除 Host 上无关文件。
+- Renderer 不接收下载 URL、缓存路径、签名 key、digest、SSH 命令或凭据。Main 负责来源
+  选择、可信目录解析、操作编排和 IPC 输入校验。
+- 产品不提供“自动安装远程环境”开关。保存、重新验证或打开 Host 都不能自动传输
+  `.gbagent`；只有用户点击 Host 卡片的主按钮后，Main 才开始准备。
+- Host 卡片只有一个主按钮，按版本事实显示“安装远程环境”“更新远程环境”或“重新安装”。
+  次级 SegmentedControl 选择“自动”“Host 下载”或“GoodBuddy 传输”；默认“自动”，只影响
+  下一次操作，不持久化为 Host 配置。
+- “自动”只在 operation/prepare 前执行一次 Host capability probe：直连明确可用时选择
+  Host 下载，否则选择 GoodBuddy 传输。用户显式选择的方式保持有效；一旦 acquisition
+  已选定，prepare、commit 或 adoption 的任何失败都停止本次操作，不跨 acquisition
+  自动回退。
+- 直连安装只要求已验证 SSH 连接和远端系统工具，不要求现有 Agent daemon。轻量能力探测
+  返回确定性缺少工具、空间、权限或来源不可达时说明原因；探测本身异常时仍允许用户点击
+  直连安装，由实际安装流程重新解析签名候选并通过 SSH 重试。
+- 项目路径不得为了“方便”回退到隐式安装。Host 未就绪时应引导到 Host 设置，不在项目
+  切换器中启动大文件传输。
+
+## 新增 Host 流程
+
+新增向导保持现有 Host Key 和认证顺序，并在系统探针之后显示一次只读环境结果：
+
+1. 输入名称、地址、端口、用户名和认证方式。
+2. 在发送认证材料前读取并确认 Host Key。
+3. 完成 SSH 认证以及平台、架构、Shell、Home 有界探针。
+4. 原子保存 Host、加密凭据和完整 Host Key。
+5. 读取 Host 已安装的 Agent/Runtime registry，并执行一次轻量下载能力探测。
+6. 如果已安装 identity 满足当前 GoodBuddy 要求，显示“版本匹配”并结束；该 badge 不代表
+   Agent 正在运行或环境健康。
+7. 如果组件缺失或需要更新，显示目标 Agent、Node、Runtime、架构、来源和完整包大小，
+   告知用户保存后前往 Host 卡片安装，然后结束新增向导。
+
+新增流程到此结束，不显示自动安装开关，也不自动开始环境安装。保存后的 Host 卡片提供
+一个手动准备主按钮，并以次级 SegmentedControl 选择“自动”“Host 下载”或
+“GoodBuddy 传输”。主按钮按版本事实显示“安装远程环境”“更新远程环境”或“重新安装”。
+本地尚无精确包不要求用户先离开当前页面；选择 GoodBuddy 传输时，同一次操作会取得并
+验证候选后继续上传。
+
+探测不得自动下载完整 `.gbagent`。只有用户明确启动安装后才允许传输大包。
+
+## Host 编辑
+
+- 仅修改显示名称不要求重装远端环境。
+- 地址、端口、用户名或 Host Key 变化时，旧 Host identity 立即失效，关闭旧连接和对应
+  Runtime 缓存。项目记录不含旧组件 identity；下一次打开直接解析新 Host 的当前环境。
+  保存新身份后只重新执行环境探测，所需安装由用户在 Host 卡片手动启动。
+- 只替换同一目标的认证材料时仍重新认证并读取实际环境；如果签名 identity 和健康状态
+  未变化，不重复安装。
+- 当前项目引用的 Host 被编辑时，Main 立即失效该 Host 的 identity 和连接缓存；下一次
+  Workspace/Runtime 操作按需使用新目标。环境未准备好时该操作失败，不回退旧连接。
+
+## 下载能力探测
+
+探测在 Host Key 已固定且 SSH 认证成功后执行，只检查当前选择的“关于与更新”来源：
+
+- Host 是受支持的 Linux `x64` 或 `arm64`。
+- SSH 账号 Home 可写，GoodBuddy-owned staging 可创建。
+- 可用空间满足签名目录声明的包大小、解包上限和安全余量。
+- Host 可以通过 HTTPS 访问所选 GitHub 或北京镜像 URL。
+- 首次安装所需的下载、SHA-256 和运行归档内固定 Node 的能力可用。
+- 已安装 Agent 是否报告未来的直连更新能力。
+
+探测使用小型签名目录或有界请求，不以一次成功 `HEAD` 代替真实安装验证。结果只用于当次
+展示，不持久化为永久能力；开始安装前重新检查，因为网络、代理和磁盘状态可能变化。
+
+探测失败不能阻止保存 Host，也不能禁用显式 GoodBuddy 传输或离线导入路径。显式选择
+Host 下载时由实际操作报告不可用原因；“自动”只把“直连明确可用”作为选择 Host 下载的
+条件，其他结果选择 GoodBuddy 传输。
+
+## 工件选择与来源
+
+Main 继续读取并验证 `agent-catalog.json`、`agent-catalog.sig` 和 production 公钥
+registry，按以下条件选择唯一候选：
+
+- Host 平台和架构匹配；
+- 最低桌面版本满足；
+- Agent protocol major 相同，minor 不高于桌面支持值；
+- 使用满足条件的最高 SemVer；
+- URL、文件名、大小和 SHA-256 来自签名目录；
+- 下载来源跟随“关于与更新”的 GitHub/镜像选择。
+
+远程下载只优化大包的网络路径。Main 仍需先取得并验证小型目录，再通过经过 Host Key
+验证的 SSH 控制面传递固定候选元数据。产品不接受 Renderer、项目、Host 文件或用户输入的
+任意下载 URL。
+
+## 获取与统一安装事务
+
+首次安装不能假设 Host 已有 GoodBuddy Agent、installer 或系统 Node，也不由既有 Agent
+daemon 参与。两种 acquisition 的差别只在于如何把同一个签名 compound `.gbagent` 交付到
+固定 operation staging：
+
+- **Host 下载**：控制面通过固定 SSH prepare channel 发送签名目录绑定的 URL、大小和
+  SHA-256；Host 有界下载并校验完整归档。
+- **GoodBuddy 传输**：若本地缺少精确候选，同一次用户操作先下载、验证 SHA-256 和签名、
+  写入缓存并取得 lease；随后以有界流式 SFTP 上传一个 compound archive，以及从该归档中
+  已验证的 bootstrap Node。约 294 MiB 的完整包不会一次读入 Main `Buffer`，Host 收到后
+  仍再次校验完整包。
+
+交付后两种 acquisition 完全共用一个 control-plane 事务：
+
+1. Main 创建带 operation ID、总时限、输出上限和取消信号的准备操作，并通过固定
+   `prepare` channel 发送有界 one-shot installer 与结构化输入。
+2. Host 校验归档大小、SHA-256、外层及内层签名、平台、架构、协议和 payload digest，
+   只把候选准备到 side-by-side 目录，不改变 current。
+3. `prepare` 完成后、`commit` 前按原字节记录 Agent 与 Runtime 的五个
+   current/registry metadata 文件，
+   同时记录原本缺失的状态。
+4. `commit` 终态先持久化到 operation staging。控制通道丢失时，Main 只用同一 operation
+   的 `commit-status` 恢复结果，绝不重放 `commit`。
+5. commit 后依次完成 Agent activate/health、Runtime activate 和 finalize。任一组件
+   adoption 失败都停止候选，并把五个 metadata 文件恢复为原字节或原缺失状态；已经发布的
+   side-by-side payload 可以保留，但不能成为 current。
+6. Main 确认 adoption 后才显式执行 cleanup，释放 staging、缓存 lease 和操作资源。
+
+这不是两个并行安装管理器，也不存在把 Agent 与 Runtime payload 逐文件走 SFTP 安装的
+第二条路径。两种 acquisition 共享相同的 prepare、commit、adoption、finalize 与 cleanup。
+
+Host 缺少可靠的下载、SHA-256 或 ZIP 能力时，不自动安装系统软件，也不要求 root。显式
+Host 下载返回明确失败；本次操作不自动切换 acquisition，用户可改选 GoodBuddy 传输后
+重新点击主按钮。后续更新和同版本重装复用同一事务，不要求用户先通过项目切换完成
+“过渡升级”。
+
+## 本机传输与离线路径
+
+现有 `.gbagent` 本地缓存、在线下载、离线导入和导出继续保留：
+
+- GoodBuddy 路径在本地缺少精确候选时，于同一次操作完成下载、整包大小与 SHA-256、
+  全部签名和 payload 验证、缓存发布及 lease 获取。
+- SFTP 有界流式上传单个 compound archive 与其中已验证的 bootstrap Node 到操作自己的
+  staging；Main 不把完整归档读入内存，Host 再次校验后进入统一 control-plane 事务。
+- Host 无公网、代理/TLS 异常或缺少 bootstrap 工具时，用户可显式使用此路径；离线导入
+  后也走同一缓存 lease、上传和 Host 校验流程。
+- 本地项目和普通桌面打包不依赖任何远端 Agent 工件。
+
+## 完整包与复用
+
+第一阶段继续发布和下载完整复合 `.gbagent`，不同时引入组件化增量发布：
+
+- 远程直连和 GoodBuddy 本机下载都会传输完整包，其中包含 Agent、固定 Node 和 OpenCode
+  Runtime。
+- 新 Agent 安装时，如果旧 manifest、registry identity、owner/mode/size 和 Node digest
+  全部可验证，并且候选声明同一 Node，则使用硬链接复用，不重新写入 Node 数据。
+- 相同 Runtime bundle digest 已存在且完整时只验证并激活，不重复上传或解包。
+- Agent 其他文件或变化后的 Runtime 仍按完整候选安装。
+
+只有真实包体和发布频率证明网络成本仍不可接受时，才另行设计 Agent、Node 和 Runtime
+独立签名组件目录；本功能不提前引入第二套发布协议。
+
+## Host 准备状态
+
+设置中的 Host 卡片分开表达版本事实和操作结果：
+
+- **未验证**：Host Key、认证或系统探针尚未完成。
+- **尚未安装**：Host 可连接，但 Agent 或 Runtime 缺失。
+- **需要更新**：已安装 identity 与当前兼容候选不一致。
+- **正在准备**：正在探测、下载、验签、安装或健康检查。
+- **版本匹配**：版本 badge 只表示 Agent/Runtime identity 与当前兼容候选匹配，不等同于
+  进程正在运行或环境健康；设置页普通刷新不会启动已停止的 Agent。
+- **准备失败**：保留 Host 和可用旧组件，展示有界错误与重试入口。
+
+主按钮按版本事实显示“安装远程环境”“更新远程环境”或“重新安装”。重新安装失败后，
+界面显示本次操作未完成，并以随后重新检查的版本卡片表达当前事实，不在提交结果不确定时
+断言旧版本未被替换，也不得把“版本匹配”改称“环境健康”。统一进度以 `探测`、
+`下载/传输`、`校验`、`应用环境`、`Agent 激活与健康检查`、`Runtime 激活` 和
+`完成设置` 表达用户可理解的阶段。
+
+同一 Host identity 同时只允许一个由用户启动、Main-owned 的准备操作。重复观察者加入
+已有操作，不启动第二次发布；窗口关闭、显式取消、Host identity 改变或 Main 退出时执行
+有界取消。Main 在 commit 前为该 Host 持久化一个不含凭据的 pending operation 记录；
+commit 指令开始后若 SSH 通道、输出或终态丢失，当前操作保留该记录和远端 staging。
+下一次重试或应用重启后的首次操作先对同一 Host identity 执行只读 `commit-status` 和
+cleanup，不重放未知 commit，也不开始第二条 acquisition；确认清理后删除 pending 记录。
+取消在最终原子切换完成后不再伪装成回滚成功。
+
+## 项目创建与切换
+
+- 新建托管 SSH 项目弹窗只读取本地 Host Key/连接验证记录，不逐台连接或刷新版本。只有
+  已完成本地验证的 Host 可选；浏览目录或保存时才连接所选 Host，并由保存流程完整检查
+  Agent、Workspace 和 Runtime，但不隐式安装。
+- 项目保存验证 Host 当前 revision 与 Host Key generation、当前 Agent、Workspace、
+  Runtime、模型 profile 和 Ask/Execute 配置；SQLite 事务只写入 Host ID、规范远端路径、
+  Runtime 选择和默认工作模式。
+- 打开或切换已有项目只提交本地项目选择，不执行 SSH、registry、Workspace 或 Runtime
+  检查。首次实际使用远程 Workspace 或 Runtime 时才解析 Host 管理的当前 Agent/Runtime，
+  并建立或复用当前 Agent 连接。已安装 Agent 暂未运行时，
+  固定 `attach-or-bootstrap` 命令幂等启动 registry 中的 current identity；这里的
+  bootstrap 只启动进程，不安装组件，也不重新读取、哈希或验签完整 payload。
+  Agent 进程读取 Host 管理已提交的 registry 和匹配 manifest 元数据，不重新验签或扫描
+  完整安装 payload。
+- Workspace 和 Runtime 使用当前 Agent 连接产生的 live handle/lease。项目不保存或核对
+  历史 Workspace/Runtime identity；当前 registry、连接状态或 capability 无效时停止并
+  引导到 Host 管理，不在项目流程中下载或安装。
+- 桌面更新导致 Host 组件过旧时，项目保持未切换并提示前往 Host 设置。应用启动仍进入
+  第一个普通本地项目，不自动连接或更新远端 Host。
+- Host 环境更新成功后，Main 定向失效该 Host 的 Agent/Runtime identity、连接和 Runtime
+  会话缓存。所有项目在下一次实际操作时自然使用新的 current 环境；无需改写项目记录。
+- 环境准备失败时不改变已有项目绑定。Host identity 编辑失败时则继续保持 fail-closed，
+  因为旧身份不能替代用户刚保存的新身份。
+- 项目管理入口与项目选择分离。项目选择器中的浮动管理按钮直接打开目标项目设置；删除
+  不访问 Workspace、Agent 或 Host，因此远端目录已删除或 Host 不可达都不能阻止本地
+  项目记录清理。删除当前项目或 Host 级联删除当前项目时只回退到普通本地项目。
+- Host 删除确认使用本地数据库列出全部引用项目，包括归档项目；确认后级联删除本地项目
+  及其会话、任务、成果、记忆、计划和心跳关联，再删除本地 Host 与凭据。整个流程不发起
+  SSH，也不删除远端内容；跨 Host 设置文件与 SQLite 的普通失败会恢复已写入的一侧。
+
+项目切换不展示远程激活进度，也不阻塞项目导航。`Host`、`Agent`、`Workspace`、`Runtime`
+和 `Saving` 进度只属于新建或显式保存项目；实际 Workspace/Runtime 操作使用正常的局部
+加载和错误反馈。
+
+## 实现结构
+
+当前实现复用现有机制，没有新增平行的安装管理器：
+
+- 扩展当前 Host 系统探针和远程环境 inspector，返回瞬时下载准备能力。
+- 让当前 `RemoteEnvironmentUpdateService` 演进为 Host 环境准备编排器，统一用户手动
+  启动的首次安装和后续更新、自动 acquisition 选择、进度、取消和最终失效。
+- Host 管理使用安装管理器完成准备、更新和完整验证。项目切换不调用安装管理器；
+  Workspace 和执行路径按需解析 current identity，并在当前进程内复用已确认 identity 和
+  Agent 连接；Host 编辑或环境更新定向清空这些缓存。这些路径不会取得安装包或发布组件。
+- Host 卡片即使显示相同版本也保留显式重装操作，用于修复 registry、签名或 payload
+  identity 异常；若同一 digest 的 GoodBuddy-owned 目录校验失败，重装会先隔离旧目录，
+  完整发布并验证新目录，失败时恢复旧目录。重装不要求删除 Host、凭据或项目，也不会处理
+  所有者异常、符号链接或非 GoodBuddy 管理路径。
+- 由桌面控制面打包有界 one-shot installer，并通过固定短命令 `exec sh -s` 和 stdin
+  发送脚本及结构化输入，避免 SSH command 长度限制；既有 package format v1 归档内固定
+  Node 负责解码和运行它。
+- Preload 只暴露明确的 Host 探测、准备、取消和进度方法，不暴露 URL 或任意 SSH 命令。
+- 现有 Agent/Runtime side-by-side、Node 硬链接复用、Host identity 二次核对、Host 端
+  发布后复验、连接失效和项目稳定配置事务继续作为唯一实现。
+
+## 迁移
+
+- 已保存 Host 打开设置时只显示本地记录，不自动连接或检查版本；用户点击对应 Host 的
+  “刷新版本”后才执行只读状态探测。项目切换不依赖该按钮，也不建立连接。
+- 数据库升级保留远程项目、Host ID、远端路径、Runtime 选择及关联会话/任务，并删除旧的
+  Agent/Runtime/Workspace/Host 验证列和 Runtime 验证表。下一次实际远程操作从 Host
+  current 环境重新取得所有 live identity。
+- 如果 Host 未就绪或版本不兼容，项目仍可在本地选择，但实际远程操作失败；不再走旧的
+  隐式安装。
+- 已下载或导入的本地 `.gbagent` 保持可用，不能因加入远程直连而迁移或删除。
+- 远程直连继续使用现有 package format version 1，不要求归档携带 installer，也不要求
+  目录声明额外的 bootstrap 能力元数据。
+
+## 验收标准
+
+1. 新 Host 保存和探测完成后不会自动下载、上传或安装任何包，也不存在自动安装开关；
+   再次进入 Host 设置不会逐台连接，只有显式“刷新版本”才探测目标 Host。
+2. Host 卡片只有一个按版本事实命名的主按钮；次级 SegmentedControl 提供默认且不持久化的
+   “自动”及显式“Host 下载”“GoodBuddy 传输”。没有预装 Agent、Node 或 Runtime 的 Host
+   可以完成准备；远程下载不可用时可手动改用 GoodBuddy 传输。
+3. 探测不下载完整包，失败不阻止保存 Host；非确定性探测失败不禁用直连重试，安装失败
+   或取消后 Host 仍可重试。
+4. 直接下载严格匹配签名目录中的 URL、大小和 SHA-256；GoodBuddy 传输可在同一次操作中
+   下载并验证缺失候选，以有界流式 SFTP 上传完整归档和已验证 bootstrap Node。Host 对
+   两者完成相同的外层与内层签名、路径、架构、协议和 payload 校验。
+5. 相同 Node 在可验证且支持硬链接时不重复传输或写入；相同 Runtime digest 不重复安装。
+6. 创建、打开和切换项目不会产生 `.gbagent` 下载、Agent payload SFTP 上传或安装目录发布。
+7. 未就绪 Host 不能创建远程项目；已有项目仍可本地选择，但远程操作失败并引导到 Host 设置。
+8. Host 编辑或更新后，引用项目使用 Host 管理的当前连接和 current registry，不读取项目
+   中的旧 Host/Agent/Runtime/Workspace identity；当前环境无效时才停止并要求在 Host 管理
+   中修复。
+9. Host 地址、用户或 Host Key 在准备期间变化时停止候选发布，旧身份不会被重新启用。
+10. GitHub、北京镜像、无公网 Host、取消、应用退出、磁盘不足、损坏下载和不支持架构均有
+   明确结果，且不触碰 GoodBuddy-owned 目录之外的文件。
+11. Linux x64 和 arm64 均通过 GitHub/北京镜像、取消、离线 GoodBuddy 传输，以及项目使用
+    Host current 环境执行 Workspace/Runtime 操作的真实 Host 测试；这些真实 Host 验收当前
+    仍待完成。
+12. Host 不可达或远端目录不存在时，用户仍可从项目浮动管理入口删除本地项目；删除 Host
+    会列出并本地清理全部关联项目，但不会连接 Host 或删除任何远端目录和内容。
+13. commit 终态可在通道丢失后用 `commit-status` 只读恢复且不重放；Agent 或 Runtime
+    adoption 失败恢复五个 metadata 文件的原字节/原缺失状态，确认 adoption 后显式 cleanup。

docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md

@@ -6,7 +6,7 @@
 | --- | --- |
 | 状态 | 设计中 |
 | 版本 | 0.5 |
-| 日期 | 2026-08-21 |
+| 日期 | 2026-08-28 |
 | 适用产品 | GoodBuddy 桌面端 |
 | 相关设计 | [统一界面设计系统](../../../UI-DESIGN.md)、[SSH 远程主机与 GoodBuddy Agent 稳定终态设计](../../architecture/remote-host-and-goodbuddy-agent-design.md) |
 | 相关能力 | [会话监督](../supervision/conversation-supervision-prd.md)、[自动化平台](../../architecture/automation-platform-architecture.md)、[长期助手路线图](../../roadmap/long-term-assistant-roadmap.md) |
@@ -477,8 +477,8 @@ type WorkbarPanelInstance = {
 
 设置中心“平台功能”提供独立“远程项目（技术预览）”页签及开关，默认关闭。关闭时不显示
 “主机与远程执行”分类、托管 SSH 项目创建选项和已保存远程项目，Main IPC 同时拒绝新的
-SSH/远程项目操作；已有 Host、项目和凭据保持不变。若关闭时正在激活远程项目，应用发出
-取消并保持或切回普通本地项目；若当前项目已经是远程项目，则切回项目列表中的第一个普通
+SSH/远程项目操作；已有 Host、项目和凭据保持不变。若当前项目已经是远程项目，则切回
+项目列表中的第一个普通
 本地项目。重新启用后恢复完整入口和既有数据。
 
 启用后，设置中心显示“主机与远程执行”分类，管理：
@@ -491,6 +491,9 @@ SSH/远程项目操作；已有 Host、项目和凭据保持不变。若关闭
 - 删除、重新验证或更新 Host Key。
 
 主机配置是全局资源。项目或工作栏只引用主机 ID，不能复制凭据。
+删除 Host 前列出所有引用它的本地项目记录，包括归档项目；确认后仅删除本机 Host、凭据、
+项目和关联数据，不建立 SSH 连接，也不删除远端目录或内容。若当前项目被删除，界面切回
+普通本地项目。
 
 当前实施状态：设置中心已经实现主机 CRUD 和模态验证向导。新增或目标/认证编辑依次完成
 连接信息、认证前 Host Key 核对、密码/系统 SSH Agent 认证和平台/架构/Shell/Home 有界
@@ -501,22 +504,49 @@ SSH/远程项目操作；已有 Host、项目和凭据保持不变。若关闭
 和文本模型 profile 验证后原子提交。私钥导入仍未开放。旧流程已保存但
 没有成功探针记录的主机继续读取，但在完成新向导前显示为“需要重新验证”。
 
-应用重启后固定进入项目列表中的第一个普通本地项目，不自动激活上次远程项目。用户主动
-打开已有托管 SSH 项目时，Main 会用数据库中的项目字段重新执行同一套
-Host/Agent/Workspace/Runtime 验证。桌面版本携带的 Agent 或 Runtime identity 已变化时，
-先 side-by-side 安装新候选，全部成功后再原子刷新项目 evidence 并切换当前项目；失败保留
-此前项目和安装绑定，不由 Renderer 用旧草稿重建更新请求。同一 Renderer 对同一项目的
-重复激活共享一个操作，不会并行启动第二次保存。
-主动打开期间，项目切换器在原位置展示 Host、Agent、Workspace、Runtime、Saving
-五个阶段及原生 `progressbar` 语义；用户可以取消，项目切换、创建和设置入口在操作结束前
-保持禁用。成功后才提交项目选择，失败或取消继续保留此前项目。
+当前源码已把 Agent/Runtime 生命周期归入 Host 管理。新增或重新验证 Host
+在身份、认证和系统探针成功后先保存 Host，再只读探测实际组件状态和瞬时下载能力，然后
+结束新增向导。产品不提供自动安装开关，也不在保存后传输包。Host 卡片只有一个按版本
+事实显示“安装远程环境”“更新远程环境”或“重新安装”的主按钮；次级 SegmentedControl
+选择“自动”“Host 下载”或“GoodBuddy 传输”，默认“自动”且不持久化。版本匹配 badge
+不代表环境健康。环境准备失败或取消保留 Host 并显示可重试状态；重新安装失败时显示
+本次操作未完成，并以随后重新检查的版本卡片表达当前事实，不对不确定提交宣称旧版本
+未被替换。详细技术契约见
+[SSH Host 远程环境准备与直连下载设计](../../architecture/remote-host-environment-provisioning-design.md)。
+
+进入或切回“主机与远程执行”页面只读取本地 Host 列表，不逐台建立 SSH 连接。版本和瞬时
+下载能力仅在用户点击某台 Host 的“刷新版本”时探测。该动作不是项目连接前置条件；用户
+切换已有远程项目只更新 Renderer 的本地项目选择，不建立 Host/Agent 连接。
+新建远程项目弹窗同样只读取本地 Host 验证记录，不扫描所有 Host；浏览目录或保存时才连接
+所选 Host。版本号相同时仍允许用户显式重新安装，以修复 registry、签名或 identity 异常，
+且不删除 Host、凭据或项目。由远程主机安装只使用 SSH 和远端系统工具，不依赖已有 Agent；
+“自动”仅在操作开始时探测：直连明确可用才选 Host 下载，否则选 GoodBuddy 传输；用户
+显式选择不被改写，prepare、commit 或 adoption 失败后不在同次操作中切换 acquisition。
+
+项目选择器中每个项目的管理按钮默认隐藏，在悬停、键盘焦点或触屏环境显示。该入口直接
+打开目标项目设置而不先切换项目，因此 Host 不可达或远端目录已不存在时仍可删除本地项目
+记录；删除操作从不删除远端项目内容。
+
+应用重启后固定进入项目列表中的第一个普通本地项目。用户主动打开已有托管 SSH 项目时只
+切换本地项目配置；首次实际使用 Workspace 或 Runtime 时，Main 才通过 Agent/Runtime
+安装管理器解析 Host current identity，执行固定 `attach-or-bootstrap`，并使用同一 Agent
+连接。
+项目数据库不保存 Agent installation、Host revision、Workspace identity 或 Runtime
+digest。当前 registry、连接或 capability 无效时项目保持未切换，并提示到 Host 管理显式
+修复。当前进程缓存每个 Host 已确认的 Agent/Runtime identity，并复用 Agent 连接；Host
+编辑或环境更新会定向清空。Agent 的 attach/按需启动只读取 Host 管理已提交的 registry 与
+匹配 manifest 元数据，不重新验签或哈希完整 Agent payload。项目切换器立即提交本地选择，
+不展示远程激活进度；完整进度和取消只属于新建或显式保存项目。
+
+项目只持久化 Host ID、规范远端路径、Runtime 选择和默认工作模式。新建和保存验证当前
+Workspace/Runtime，但不写入组件 identity；普通切换不做远程验证。未就绪或版本过旧时，
+实际 Workspace/Runtime 操作显示错误。桌面更新造成组件版本变化时，用户先在 Host 管理中
+准备环境；项目切换本身不连接、不下载、不扫描、不安装，也不改写项目。
 
 已保存 Host 的地址、用户或固定 Host Key 变化后，Main 关闭旧连接并定向退役该 Host 的
-Runtime 缓存。当前项目引用该 Host 时，设置保存成功会立即运行上述完整激活流程并刷新
-项目验证；其他项目在下次选择时刷新。用户再次选择当前 SSH 项目也会执行完整激活，
-不能因为项目已经选中而跳过验证。从 Host 保存到项目成功激活之间，项目持续保持需要
-重新连接状态；失败或取消不会重新开放 Composer。已由 Main 派发的用户排队消息退回原
-持久队列，不生成失败消息、不丢失附件，并在成功激活后的 queue-ready 通知中继续派发。
+Runtime 缓存。引用项目下次选择时使用 Host 管理的当前 revision、Host Key 和用户执行固定
+attach 并读取 current registry，不存在项目中的旧 Host revision 或组件 identity；
+当前环境无效时才要求显式修复。
 
 新建托管 SSH 项目时，远端工作目录既可手工输入，也可通过文件夹按钮打开 Main 管理的
 只读、有界 SFTP 目录选择器。选择器从 SSH 账号 Home 或当前有效绝对路径开始，只返回目录，
@@ -545,11 +575,23 @@ Runtime 缓存。当前项目引用该 Host 时，设置保存成功会立即运
 - 安装到远程当前用户的 GoodBuddy-owned 目录，不要求 root。首次连接先 attach，Agent
   不存在或未运行时幂等 bootstrap 为 detached process，再重新 attach；不注册开机服务，
   不依赖 systemd、D-Bus 或 `Linger=yes`。
-- SSH 负责 Host Key、认证、SFTP 安装和固定 `goodbuddy-agent attach` 中继；attach 只连接
-  用户私有 Unix socket。SSH relay 断开不终止 Agent 或活动 Runtime。
-- 上传内容使用应用内置公钥验证的签名 manifest，并校验组件版本、协议、平台、架构、大小
-  和 SHA-256。Agent 与 Runtime 各自维护版本，签名摘要标识精确工件；使用 side-by-side
-  安装、自检和健康切换，失败时不改变当前项目绑定。
+- SSH 负责 Host Key、认证、固定 bootstrap、可选 SFTP 安装和 `goodbuddy-agent attach`
+  中继；attach 只连接用户私有 Unix socket。SSH relay 断开不终止 Agent 或活动 Runtime。
+- Host 环境准备可让远端按签名目录固定的 GitHub/北京镜像 URL、大小和 SHA-256 下载完整
+  `.gbagent`，也可由 GoodBuddy 下载、完整验证后通过有界流式 SFTP 传输一个 compound
+  archive 和归档中已验证的 bootstrap Node；完整包不一次读入 Main `Buffer`，Host 仍再次
+  校验。两种 acquisition 交付到固定 operation staging 后共用
+  `prepare → commit → Agent activate/health → Runtime activate → finalize → cleanup`。
+- 直连首次 bootstrap 不依赖已安装 Agent daemon。GoodBuddy 桌面控制面通过固定 SSH
+  prepare channel 发送有界 one-shot installer；Host 先验证目录绑定的归档大小和 SHA-256，
+  再由 format v1 归档内固定 Node 解码并运行 installer。归档无需包含
+  `agent/lib/package-installer.cjs`，目录不提供或检查额外的 bootstrap 能力元数据。
+- Agent 与 Runtime 各自维护版本，签名摘要标识精确工件；使用 side-by-side 安装、自检和
+  健康切换，失败时不改变当前项目绑定。相同且可验证的 Node 使用硬链接复用，相同 Runtime
+  digest 不重复安装。
+- commit 终态持久化，控制通道丢失时只用 `commit-status` 恢复而不重放。prepare 完成后、commit 前快照
+  Agent/Runtime 五个 metadata 文件；任一组件 adoption 失败恢复原字节或原缺失状态，
+  已发布 payload 不得成为 current，确认 adoption 后显式 cleanup。
 - 握手报告 installation、Daemon boot identity、协议、系统、架构、用户监督器和能力。
 - 在远程执行路径规范化、Git、文件、PTY、进程组和 Runtime 管理。
 - 持久化有界 Agent 到 Main 输出；SSH 断开后 Agent 继续运行，同一 Agent 重连时只恢复
@@ -791,8 +833,18 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
 - 先完成签名 OpenCode bundle、Ask bubblewrap、Execute 直接进程、官方 ACP channel、
   Main 模型网关、取消、超时和活动记录。
 - OpenCode 闭环稳定后，Continue 与 DeepSeek Harness 复用相同面板和通道契约逐个接入。
-- 一次远程项目保存请求完成 Host/Agent/Workspace/Runtime 全量验证和 SQLite 原子提交。
-- 桌面更新后，用户主动首次打开远程项目时自动安装当前签名 Agent/Runtime，并在成功后原子刷新项目绑定；应用启动本身不连接远程项目。
+- 新增或重新验证 Host 时只保存并探测 Agent/Runtime，不自动安装。用户在 Host 卡片用
+  单一主按钮启动，并用次级控件选择自动、Host 下载或 GoodBuddy 传输；Host 保存与环境
+  准备是两个可独立重试的事务。
+- 控制面直连源码直接使用既有 package format v1 包；不等待发布携带 installer 的新
+  Agent 包，也不通过额外目录元数据判断 bootstrap 能力。GitHub/北京镜像、
+  Linux x64/arm64、取消和离线 GoodBuddy 传输仍须真实 Host 验收，不能据此声称已发布或已完成
+  真实 Host 测试。
+- 一次远程项目保存请求完成 Host/Agent/Workspace/Runtime 当前环境验证和 SQLite 原子
+  提交，但只持久化 Host、路径、Runtime 选择和模式，也不获取或安装组件。
+- 桌面更新后，用户先在 Host 管理中更新当前签名 Agent/Runtime；远程项目下一次实际使用
+  Workspace/Runtime 时直接使用新的 current 环境，无需刷新项目绑定。应用启动和项目切换
+  本身都不连接 Host，也不下载或安装组件。
 - SSH、Main、Daemon、Runtime 和远端重启后的核对、恢复与 `outcome_unknown`。
 - 支持平台的安装、Ask、Execute、取消和重连冒烟测试通过后开放对应 OpenCode 能力。
 
@@ -843,6 +895,11 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
 - [ ] 重连先恢复 event cursor 并查询 operation；有副作用操作不会自动重放，无法确认的
   结果显示为 `outcome_unknown`。
 - [ ] Agent side-by-side 更新支持所需签名版本的健康切换，失败时保留旧项目绑定。
+- [x] 新增 Host 只探测远端下载能力，不提供自动安装开关，也不传输完整包；Host 卡片用
+  一个按版本事实命名的主按钮与不持久化的 acquisition SegmentedControl 启动准备。
+- [x] 创建、保存、打开和切换托管 SSH 项目都从 Host current registry 与当前 Agent
+  连接验证环境；项目只保存稳定配置，且这些流程不下载 `.gbagent`、上传 payload 或发布
+  安装。
 - [ ] 切换跟随目标后不显示上一对象的过期状态。
 - [ ] 固定目标的订阅在页面切换后保持，关闭时正确释放。
 - [ ] 日志、终端、文件、成果和远程传输均有明确上限和背压。
@@ -867,6 +924,8 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
 - [自动化平台总体设计](../../architecture/automation-platform-architecture.md) 定义 Plan、Job、Run、监督、预算和记忆。
 - [长期助手路线图](../../roadmap/long-term-assistant-roadmap.md) 记录整体长期能力与实施背景。
 - [DeepSeek Harness Runtime 设计](../../architecture/deepseek-harness-runtime-design.md) 定义该 Runtime 的具体适配边界。
+- [SSH Host 远程环境准备与直连下载设计](../../architecture/remote-host-environment-provisioning-design.md)
+  定义 Host 级组件获取、首次准备、更新、回退和项目只验证边界。
 - [统一界面设计系统](../../../UI-DESIGN.md) 定义视觉、语义、响应式和无障碍规则。
 
 若其他文档把工作栏描述为八个同时固定显示的栏目、根据项目或 Runtime 自动裁剪的动态入口，