refactor(snapshot): add local workspace owner port

docs/architecture/agent-runtime-services-design.md

@@ -714,8 +714,9 @@ Agent Runtime SDK 门面，不注册未实现的 `RuntimeServices` 能力，也
 未实现该能力的提供方返回类型化不支持错误；实现成功时 Runtime 必须校验返回 ID 与请求完全一致，不能
 替换为自动生成的 ID。`SessionSelector::Create` 仍保持自动生成。Peer Host 通过同一 SDK 处理对话提交、精确取消、
 工具确认/拒绝、会话创建/基础恢复/重命名/归档、thread-goal 查询和会话模型更新。TUI 用量卡片以固定的、模型上下文不可见的
-本地命令轮次契约回到 Core owner；账号同步、快照、富历史读取及 Peer Host/ACP 维护等产品操作仍由
-`assembly/core` 的单一兼容门面转发。
+本地命令轮次契约回到 Core owner。CLI 上下文还单独持有不属于 Agent Runtime SDK 或 `RuntimeServices` capability 的
+本地工作区快照 owner port；Peer Host 只用它完成本地工作区准备、会话文件清单、类型化统计和工作区文件回滚。
+账号同步、富历史读取及 Peer Host/ACP 的其余维护等产品操作仍由 `assembly/core` 的单一兼容门面转发。
 `doctor` 与 `health` 校验真实组装结果及必需注册完整性；
 Core 的 Network、Git 和 MCP Catalog 当前仍含兼容 marker，因此该诊断不等于对这些外部服务做实时探活。
 
@@ -727,6 +728,10 @@ Core 的 Network、Git 和 MCP Catalog 当前仍含兼容 marker，因此该诊
 仍保留在 Desktop/Core 兼容入口。Server 仅提供健康检查、信息与 ping 路由。未接入入口的 profile、枚举分支和
 单元测试仍不能证明对应产品形态可用。
 
+Desktop 与 CLI Peer Host 还各自注入同一个 Core-backed `LocalWorkspaceSnapshotPort` 契约。它是两个本地宿主之间的内部 owner 边界，
+不是 Agent Runtime SDK、完整 Desktop profile、跨宿主远程能力或通用 checkpoint/rewind API。Core 继续持有 `SnapshotManager`、工具拦截、
+持久化和事件；宿主继续持有远程检测/结果投影，以及回滚时的会话取消、维护、历史顺序和部分失败语义。
+
 职责：
 
 - 接收入口唯一选择的 `DeliveryProfile` 与具体 `RuntimeServices`，生成静态能力计划并校验必需服务。
@@ -817,8 +822,12 @@ Core 兼容门面读取协议回放所需的完整轮次，避免为单一协议
 会话分支请求显式携带可选远程身份；当前本地 provider 对远程身份返回 `NotAvailable`，不据本地路径
 推断远程语义。CLI/TUI 的工具确认、拒绝和用户问题回答，以及 ACP 服务端 / Peer Host 的工具确认与拒绝，通过类型化
 `AgentInteractionResponsePort` 回到 Core 的工具管线或用户输入 owner，不改变审批策略或交互所有权。
+本地工作区快照准备、会话文件清单、类型化统计和工作区文件回滚由 `LocalWorkspaceSnapshotPort` 直接调用现有 Core 快照 owner；
+该端口没有远程身份字段，不由 Agent Runtime SDK re-export，也不注册成完整产品 capability。Desktop 保留既有远程空结果兼容；
+Peer Host 对显式远程身份或远程路径返回清晰的不支持错误；二者都不会把远程请求转入本地端口。
+Peer Host 的历史截断、维护锁、后代会话清理和事件投影不进入端口。
 `CoreAgentRuntimeCompatibility` 仍承载未迁移的
-账号同步、快照、富历史读取及 Peer Host/ACP 维护等操作；不能据此把整个兼容门面一次性删除，也不能把这些
+账号同步、富历史读取及 Peer Host/ACP 其余维护等操作；不能据此把整个兼容门面一次性删除，也不能把这些
 操作提前声明为跨宿主稳定接口。固定 ID 创建的兼容周期已经结束；会话创建、分支和用量生成均由 Runtime SDK
 承接；会话重命名/归档、基础恢复、thread-goal 查询和完成态本地命令轮次也通过显式窄端口回到 Core owner，
 不形成通用会话 mutation 或 transcript writer。Core provider 直接调用现有协调器、持久化和用量 owner，不再反向经过兼容门面。账号、登录态、
@@ -1095,7 +1104,8 @@ Product 测试：
 - `bitfun-core` 可继续作为 `product-full` 兼容门面，避免迁移期间一次性重写入口。
 - CLI 已以 `DeliveryProfile::Cli` 构造真实 Runtime Parts 和 SDK runtime；本地 Agent 入口、会话、用量和
   Peer Host 共用一个调用级上下文与广播事件源，审批策略不再写回全局配置。Peer Host 通过 SDK 提交/精确取消
-  turn、处理基础会话控制、更新会话模型并处理工具确认/拒绝，通过单一 Core 兼容门面处理快照、富历史和持久化维护缺口，不再构造独立调度器、持久化 manager 或事件队列；
+  turn、处理基础会话控制、更新会话模型并处理工具确认/拒绝；本地工作区快照准备、文件清单、统计和文件回滚通过独立 owner port 复用 Core 实现，
+  富历史和其余持久化维护缺口仍通过单一 Core 兼容门面处理，不再构造独立调度器、持久化 manager 或事件队列；
   wire schema、Relay ACK/重放和重连协议未在该切换中扩张。
 - CLI 主会话客户端通过 SDK 处理 session、transcript、fork、usage report、用量卡片完成态本地命令轮次、turn、cancel 与 settlement；其他 SDK v1 缺口仍通过一个 Core 兼容门面处理；
   该门面复用现有 owner，不建立第二套状态或事件 schema。
@@ -1107,11 +1117,13 @@ Product 测试：
 - Desktop 主交互已从现有协调器与调度器端口构造窄口径 Agent Runtime SDK 门面；Tauri 命令只负责保留现有 DTO、
   补全图片载荷并映射类型化请求。ACP 取消分支继续优先处理，Desktop 平台生命周期和未迁移服务不进入 SDK，也不创建
   第二套 owner 或事件 schema。完整 `DeliveryProfile::Desktop` 必须等待真实 Desktop `RuntimeServices` 提供方和事件
-  消费/投影路径齐备后再组装；当前切片不注册 `Events` 能力，也不以失败占位端口或无人消费的内存通道伪装可用。
+  消费/投影路径齐备后再组装；当前切片只额外注入本地工作区快照 owner port，不注册 `Events` 或快照 capability，
+  也不以失败占位端口或无人消费的内存通道伪装可用。
 
 仍需完成：
 
-- 继续缩小 CLI 的 Core 兼容门面；只有稳定端口、真实生产调用方和行为等价测试齐备时才迁移 owner。
+- 继续缩小 CLI 的 Core 兼容门面；本地快照窄端口不扩张为远程快照、完整 checkpoint/rewind 或 Agent Runtime SDK 能力。
+  只有稳定端口、真实生产调用方和行为等价测试齐备时才迁移其余 owner。
 - 继续按真实复用需求缩小 ACP 的完整持久化历史、模型/模式目录与提供方配置读取、MCP 与客户端兼容路径；Desktop 仅继续迁移存在稳定端口和
   行为等价测试的入口。完整 Desktop 产品组装需先补齐真实必需服务与事件消费路径，不以桩实现提前声明能力；ACP 生命周期
   和 Desktop 平台资源仍留在各自入口。

docs/architecture/cli-product-line-design.md

@@ -92,7 +92,7 @@ BitFun CLI 应成为可独立安装和发布的 Agent 产品，而不是 Desktop
 - Agent、模型、MCP、会话、用量、诊断、ACP 外部 Agent 和插件来源管理命令。
 - BitFun 原生插件目录的发现、内容校验、来源确认，以及 OpenCode custom tool 静态名称预览。
 - CLI 本地 Agent 入口以类型化 `RuntimeServices` 调用 `ProductAssembler`，选择 `DeliveryProfile::Cli`，
-  并把 `ProductRuntimeParts`、Agent Runtime SDK、事件源和调用级审批策略保存在一个 `CliRuntimeContext` 中。
+  并把 `ProductRuntimeParts`、Agent Runtime SDK、本地工作区快照 owner port、事件源和调用级审批策略保存在一个 `CliRuntimeContext` 中。
 - TUI、`exec`、会话、用量和交互模式下的 Peer Host 复用同一上下文。SDK 已承接会话创建（包括
   `exec --session-id` 和缺失后端会话通过独立固定 ID 方法按原 ID 重建）/列举/删除/恢复、类型化转录、本地分支、
   用量生成、轮次提交/取消和精确结算；普通创建
@@ -103,7 +103,9 @@ BitFun CLI 应成为可独立安装和发布的 Agent 产品，而不是 Desktop
   等待期间可以切换或新建会话；只有原会话的发送继续等待。首次退出请求在持久化成功后自动退出，失败时留在界面提示重试；再次退出允许立即离开，
   并明确提示下次恢复以 Core 的持久化模式为准。恢复主会话时，已从当前目录移除的持久化模式由 Core 迁移到可执行回退模式；
   TUI 对比恢复前后的会话摘要并显示模式变化，如果同时携带启动输入，只预填而不自动执行，须由用户确认后发送。TUI 用量卡片通过固定语义的
-  完成态本地命令轮次端口持久化；账号同步、快照、富历史及 Peer Host/ACP 维护等 SDK v1 缺口由一个 Core 兼容门面转发给原 owner。
+  完成态本地命令轮次端口持久化。Peer Host 的本地工作区准备、会话文件清单、类型化快照统计和工作区文件回滚通过
+  独立的本地 owner port 回到现有 Core 快照实现；该端口不进入 Agent Runtime SDK，不接受远程身份，也不承载历史截断、维护锁或完整 checkpoint/rewind。
+  账号同步、富历史及 Peer Host/ACP 的其余维护缺口继续由一个 Core 兼容门面转发给原 owner。
 - Agentic Event Queue 仍是唯一事件 owner；TUI、`exec` 与 Peer Host 使用独立广播订阅，不互相消费事件。
 - 有界旧队列只承担兼容存储；达到容量时不得抑制广播。CLI 保持一个后台 drain，订阅方一旦报告 lag/closed，
   必须取消活动 turn 并显式失败，不能在状态不完整时继续报告成功。
@@ -124,7 +126,8 @@ BitFun CLI 应成为可独立安装和发布的 Agent 产品，而不是 Desktop
 - 初始化按入口分级：交互模式启动 Peer Host 与 MCP，`exec` 只启动 MCP；本地 session 管理和 usage 查询不启动
   Peer Host/MCP。该分级不改变 Agentic/Terminal owner，也不等同于管理命令已有独立轻量 Runtime。
 - Peer Host 保持既有 HostInvoke / DeviceEvent wire schema 与 Relay 路由，但执行已接入上述调用级上下文：
-  对话提交、精确取消、会话创建/基础恢复/重命名/归档、thread-goal 查询和模型更新走 SDK，富历史、快照及维护缺口走单一 Core 兼容门面。Peer Host 只跟踪由 Peer 提交的根 turn、
+  对话提交、精确取消、会话创建/基础恢复/重命名/归档、thread-goal 查询和模型更新走 SDK；本地快照文件清单、统计和文件回滚走窄 owner port；
+  富历史及其余维护缺口走单一 Core 兼容门面。Peer Host 在进入本地端口前对远程身份与远程路径返回明确不支持错误，并继续拥有回滚前取消、维护锁、历史截断、部分失败提示和事件投影。Peer Host 只跟踪由 Peer 提交的根 turn、
   其子 turn 与待确认工具；可确认工具始终由控制器确认，即使宿主全局策略跳过确认，Agent 也会暂停等待控制器。
   该 Peer 专属确认要求会沿精确后台结果 follow-up 保留。后台结果按 Core 内部元数据中的精确父 turn 与来源子 turn
   继承 ownership；仅在父 turn 仍运行时注入，否则排在
@@ -148,7 +151,7 @@ BitFun CLI 应成为可独立安装和发布的 Agent 产品，而不是 Desktop
 
 | 缺口 | 影响 | 本设计的处理 |
 |---|---|---|
-| CLI 主会话客户端已仅消费 Runtime SDK，但账号同步、快照、富历史及 Peer Host/ACP 的持久化维护仍由 `bitfun-core/product-full` 兼容 owner 提供 | SDK 尚不能独立覆盖全部宿主维护能力，过早删除兼容路径会改变行为 | 仅在稳定端口、真实嵌入方和行为等价测试齐备后迁移 owner；兼容门面保持单一且不扩展成第二套 Runtime。 |
+| CLI 主会话客户端已仅消费 Runtime SDK；本地工作区快照的准备、文件清单、统计和文件回滚已有 Desktop/Peer Host 共用的窄 owner port，但快照记录/持久化/事件、账号同步、富历史及 Peer Host/ACP 的其余维护仍由现有 Core owner 提供 | 窄端口只消除重复宿主转发，不代表完整快照系统、远程快照或 SDK 能力已迁移；过早删除其余兼容路径会改变行为 | 保持快照实现和工具拦截在 Core，远程与历史维护留在宿主；仅在新的真实调用方、独立语义和行为等价测试齐备后继续迁移。 |
 | TUI 编排、输入、命令、副作用和渲染仍有大文件聚集 | 交互回归难以隔离，终端状态与业务状态容易耦合 | 在现有模块上增量收敛为事件、状态归约、副作用和渲染四个边界，不重写全部 TUI。 |
 | CLI 配置只覆盖入口本地选项，缺少统一层级、来源解释和兼容导入 | 用户无法安全复用其他 CLI 资产，也难以解释最终配置来源 | 建立 BitFun Canonical Config、持续来源视图和可选的显式导入报告。 |
 | OpenCode 来源发现与真实执行尚未形成完整闭环 | “来源可识别”容易被误解为“插件可执行” | 第一条闭环只完成一个无外部依赖的契约样例；取得真实 `execute` 并注册到 Tool Runtime 后才显示可用。 |
@@ -279,8 +282,9 @@ CLI/TUI 的会话创建、列出、删除、恢复和历史转录读取通过 Ru
 `SessionTranscript` 投影为本地渲染状态，不再消费 Core `Message`。Peer Host 的对话提交、精确取消、基础会话控制、thread-goal 查询、会话模型更新和
 工具确认/拒绝通过 SDK 回到 Core owner；本地会话分支通过显式本地范围的 SDK 端口完成，携带远程身份的请求返回类型化
 `NotAvailable`，本轮不扩展远程分支。TUI 用量卡片通过固定语义的完成态本地命令轮次端口持久化，不暴露通用 transcript writer。
-账户同步、快照、富历史及其他未覆盖操作仍使用经过审查的 Core
-compatibility 方法，直到各自具备明确 owner、稳定 DTO、远程语义和行为等价测试。
+本地工作区快照准备、会话文件清单、类型化统计和工作区文件回滚通过 `runtime-ports` 中不属于 Runtime SDK 的窄 owner port 完成，
+由 Desktop 和 Peer Host 分别投影现有协议；Desktop 保留既有远程空结果，Peer Host 返回明确不支持错误，远程请求都不进入本地实现。快照记录、持久化、事件、历史截断与维护编排仍在原 owner。
+账户同步、富历史及其他未覆盖操作继续使用经过审查的 Core compatibility 方法，直到各自具备明确 owner、稳定 DTO、远程语义和行为等价测试。
 这是一条垂直链路迁移，不是删除整个兼容门面或新建 CLI 专用服务层。
 
 Runtime Configuration Service 当前由 `bitfun-core/service/config` 负责。在经评审的 port/provider

docs/architecture/product-architecture.md

@@ -327,7 +327,7 @@ flowchart LR
 | 产品形态 | 当前扩展能力 | 入口行为 |
 |---|---|---|
 | Desktop / product-full | 生产入口仍依赖 `bitfun-core/product-full` 作为兼容组装层；“外部 AI 应用”设置已消费 OpenCode Command、standalone Tool 和 Subagent 的统一来源快照、审批、冲突选择与诊断；Skills 场景和设置列表显示已发现 Skill 的生态来源与覆盖结果 | 仅本地执行域支持当前三条可执行纵向切片；Skill 仍使用独立 Registry，不据来源展示宣称已并入外部来源协调器。受管 package plugin 仍只有静态预览，不能据设置页接入宣称完整 OpenCode 插件运行时 |
-| CLI | 入口仍以 `bitfun-core/product-full` 作为执行兼容 owner；交互式 TUI 已可执行受支持的 Prompt Command，并在通用 `/tools` 与 `/agents` 入口按文字分组消费与 Desktop 相同的审批、冲突和刷新状态；`/agents` 同时承载主 Agent 切换、Subagent 管理和“外部 AI 应用”，不再注册 `/subagents` 或 `external-*` 平行命令。活动 turn 期间仍可查看和管理，只有主 Agent 切换被禁用。Skill 列表显示来源，模式配置按实际选择结果说明覆盖来源 | 已批准的 standalone Tool 进入现有 Tool Runtime；已批准的外部 Subagent 只支持 fresh single-run。CLI/TUI 不解析生态文件、不启动第二套 worker/Agent owner；非交互入口和 Remote 未接入时不得借本机 TUI 路径代执行。本地 Agent 与 Peer Host 路径选择 `DeliveryProfile::Cli` 并消费同一 Runtime Parts/SDK；主会话的恢复、转录、本地分支、用量报告生成/卡片持久化、模式更新与精确结算走 SDK，Peer Host 的基础会话创建/恢复/重命名/归档和 thread-goal 查询也走同一 SDK；远程分支明确不支持。TUI 模式切换异步持久化，期间保持输入和 resize 响应，只在成功后提交本地状态，失败保留原选择；用户可切换会话，退出有等待完成与再次强制退出两级路径。失效的主会话模式由 Core 恢复为可执行模式，TUI 显示迁移并阻止启动输入自动执行。账号同步、快照、富历史及 Peer Host/ACP 持久化维护缺口仍由单一 Core 兼容门面转发。本切片不改变扩展执行边界 |
+| CLI | 入口仍以 `bitfun-core/product-full` 作为执行兼容 owner；交互式 TUI 已可执行受支持的 Prompt Command，并在通用 `/tools` 与 `/agents` 入口按文字分组消费与 Desktop 相同的审批、冲突和刷新状态；`/agents` 同时承载主 Agent 切换、Subagent 管理和“外部 AI 应用”，不再注册 `/subagents` 或 `external-*` 平行命令。活动 turn 期间仍可查看和管理，只有主 Agent 切换被禁用。Skill 列表显示来源，模式配置按实际选择结果说明覆盖来源 | 已批准的 standalone Tool 进入现有 Tool Runtime；已批准的外部 Subagent 只支持 fresh single-run。CLI/TUI 不解析生态文件、不启动第二套 worker/Agent owner；非交互入口和 Remote 未接入时不得借本机 TUI 路径代执行。本地 Agent 与 Peer Host 路径选择 `DeliveryProfile::Cli` 并消费同一 Runtime Parts/SDK；主会话的恢复、转录、本地分支、用量报告生成/卡片持久化、模式更新与精确结算走 SDK，Peer Host 的基础会话创建/恢复/重命名/归档和 thread-goal 查询也走同一 SDK；远程分支明确不支持。TUI 模式切换异步持久化，期间保持输入和 resize 响应，只在成功后提交本地状态，失败保留原选择；用户可切换会话，退出有等待完成与再次强制退出两级路径。失效的主会话模式由 Core 恢复为可执行模式，TUI 显示迁移并阻止启动输入自动执行。本地工作区快照准备、会话文件清单、类型化统计和工作区文件回滚由 Desktop/Peer Host 共用的窄 owner port 调用现有 Core 实现；它不进入 SDK，不接受远程身份，Desktop 保留既有远程空结果，Peer Host 返回明确不支持错误，历史维护仍归宿主。账号同步、富历史及 Peer Host/ACP 其余持久化维护缺口仍由单一 Core 兼容门面转发。本切片不改变扩展执行边界 |
 | HarmonyOS PC 原生 CLI/TUI | 未来平台目标，当前未实现 | 目标、问题和风险见平台规约；具体适配另立专题，HAP、手机 Remote App 与远端代执行均不替代 |
 | HarmonyOS PC GUI | 完整 HarmonyOS PC 支持的另一目标形态，当前未实现 | 与 CLI/TUI 共享稳定能力和 Runtime 语义，但独立设计宿主、界面与发布验证；Web、Remote 或现有 Tauri Desktop 均不能替代 |
 | HarmonyOS 手机 Remote App | `src/apps/mobile/harmonyos` 是 phone-only ArkTS 远程入口，不持有本地 Rust Agent Runtime | 保持当前能力并按移动端专题独立演进；本轮不提前设计移动 Runtime/TUI/GUI，也不能据此宣称 HarmonyOS PC 本地能力 |