refactor(agent): unify local and SSH workspace execution (#2707)

* refactor(agent): share workspace file execution across local and SSH

* fix(workspace): close review gaps in search, identity and SSH lifecycle

* fix(session): keep inherited snapshot capabilities scoped to their source

* chore(capabilities): regenerate remote workspace command policies

* test(workspace): respect native filesystem semantics across platforms

Author: bobleer

.github/workflows/ci.yml

@@ -370,13 +370,33 @@ jobs:
       - name: Run file watch contract tests
         run: cargo test --locked -p bitfun-services-integrations --no-default-features --features file-watch --test file_watch_contracts
 
-      # Search tools resolve paths and symlinks directly, which also differs
-      # across platforms. Scoped to the search module: the glob tests in this
-      # crate fail on Windows independently of this branch (walk-root
-      # derivation treats separators differently) and need their own fix.
+      # Search tools share matching but retain provider-specific path and
+      # symlink handling. Keep the search module in the full OS matrix.
       - name: Run search tool tests
         run: "cargo test --locked -p tool-runtime --lib search::"
 
+      # Workspace providers own filesystem/link semantics and SSH cleanup;
+      # compiling them as Desktop dependencies does not execute their tests.
+      - name: Run workspace provider contracts
+        shell: bash
+        run: |
+          cargo test --locked -p bitfun-services-core --no-default-features --features workspace-runtime --lib workspace::tests::
+          cargo test --locked -p bitfun-services-integrations --no-default-features --features remote-ssh-concrete --lib remote_ssh::manager::tests::workspace_
+          cargo test --locked -p tool-runtime --no-default-features --lib fs::read_file::tests::
+          cargo test --locked -p tool-runtime --no-default-features --test tool_io_contracts
+
+      # Linux's product-full suite above already covers these tools. The
+      # feature-free Core suites on macOS/Windows do not exercise workspace IO.
+      - name: Run workspace Agent contracts
+        if: runner.os != 'Linux'
+        run: >-
+          cargo test --locked -p bitfun-core --no-default-features
+          --features agent-runtime,git,remote-workspace,document-read --lib --
+          file_read_tool::tests file_write_tool::tests file_edit_tool::tests
+          delete_file_tool::tests grep_tool::tests glob_tool::tests ls_tool::tests
+          tool_context_runtime::path_resolution_tests file_read_state_runtime::tests
+          service::snapshot:: product_runtime::tests::session_fork_
+
   # Call the standalone Linux/Relay workflow directly. Calling the Nightly
   # artifact orchestrator would register a misleading skipped Desktop package
   # check on every producer-selected PR even when that matrix is disabled.

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

@@ -8,6 +8,12 @@ Agent Runtime 的模块职责见 [`agent-runtime-services-design.md`](agent-runt
 和 Shared transport 提案见 [`app-server-architecture.md`](app-server-architecture.md)。Embedded interactive TUI 已完成 direct-runtime
 迁移；Shared transport 未通过独立评审前继续使用 v17。
 
+SSH/容器工作区保留轻量 SSH 部署：同一 Agent Runtime 和会话状态仍由 BitFun 主机持有，
+只在工作区文件与进程 I/O 边界选择本地或 SSH provider，不要求目标安装 BitFun CLI 或 daemon。
+具体收敛范围和验收见
+[`remote-workspace-transport.md`](remote-workspace-transport.md#agent-runtime-convergence)。
+共用主循环仍不代表所有工具、快照与本地行为已经等价，完成状态以实际接线和测试为准。
+
 ## 1. 决策与当前状态
 
 BitFun 只有一套 Agent Runtime 行为。`Embedded` 和 `Shared` 只描述同一套 Runtime 的物理部署方式，不是两套实现。

docs/architecture/remote-workspace-transport.md

@@ -1,8 +1,10 @@
 # Remote workspace transport
 
-This document defines how BitFun turns SSH hosts and Docker containers into one
-workspace runtime without leaking transport-specific behavior into Agent,
-search, terminal, or file-service callers.
+This document defines the transport boundary for SSH and Docker workspaces.
+The Agent Runtime stays on the BitFun host. Local and remote workspaces share
+file-tool algorithms through Session-bound IO providers; search retains native
+acceleration with shared matching and reduction. The convergence section below
+describes this boundary and the remaining capability limits.
 
 ## Goals
 
@@ -115,11 +117,15 @@ local Docker uses the existing local PTY service with `docker exec -it`.
 SSH workspaces continue to use SFTP. Docker workspaces use binary stdio streams,
 not text or base64 envelopes.
 
-Reads stream chunks and report real byte progress. Writes stream to a unique
-temporary file in the destination directory and rename it only after the input
-has completed successfully. Cancellation kills the process and the shell trap
-removes the temporary file, so an interrupted upload does not replace a valid
-destination with partial content.
+Reads stream chunks and report real byte progress. File transfers stream to a
+unique temporary file in the destination directory and rename it only after the
+input has completed successfully. Cancellation kills the process and the shell
+trap removes the temporary file, so an interrupted upload does not replace a
+valid destination with partial content. Workspace tool writes retain ordinary
+filesystem semantics instead: after validating the staged bytes, they write
+through the destination to preserve existing links and permissions. The final
+write is not an atomic transaction against other writers; interruption during
+that phase can have a partial or unknown outcome.
 
 Directory and stat records use NUL-separated fields. File names containing
 newlines or the delimiters used by older implementations remain round-trippable.
@@ -203,3 +209,216 @@ Contract tests cover legacy Agent/profile deserialization, defaulted connection
 options, remote-workspace retention, stdio round trips, cancellation, and
 delimiter-safe Docker metadata parsing. A Docker-backed ignored integration test
 is available through `BITFUN_TEST_DOCKER_CONTAINER`.
+
+## Agent Runtime convergence
+
+Decision: keep remote workspaces lightweight. Do not require BitFun CLI,
+a remote Agent daemon, a shared service, or a new remote installation. The
+BitFun host keeps the existing Agent Runtime, model credentials, Session and
+permission ownership. Only workspace filesystem and process IO crosses SSH.
+Read, Write, Edit, Delete and LS use the bound filesystem provider. Grep and
+Glob share matching/result algorithms while retaining native acceleration.
+Snapshot file IO uses that same boundary; complete remote Session Undo remains
+gated because individual recorded operations do not prove historical coverage.
+
+### One Runtime, one IO boundary
+
+```mermaid
+flowchart TB
+  Surface["Driving surface"] --> Runtime["Existing Agent Runtime on BitFun host"]
+  Runtime --> Owners["Session · tools · permission · hooks · snapshots"]
+  Owners --> IO["Session-bound workspace IO"]
+  IO --> Local["Local filesystem and process provider"]
+  IO --> Remote["SSH / SFTP / Docker provider"]
+  Remote --> Target["Ordinary target files and processes"]
+```
+
+Runtime ownership and execution location are different concerns. Sharing the
+Runtime does not require deploying it beside the workspace. Session lifecycle,
+read-before-write checks, edit matching, result rendering, snapshot history and
+revert transitions have one implementation on the BitFun host. Providers only
+perform typed filesystem/process operations; they do not implement Read, Edit,
+Grep or fork as separate product features.
+
+Target installation, process supervision, a multi-user daemon, model proxying
+and Session migration are not prerequisites for this SSH workspace feature.
+Existing App Server, Shared TUI IPC, Peer Device and Detached Dispatch contracts
+are unchanged.
+
+### Shared owners and provider contracts
+
+| Responsibility | Shared owner | Provider boundary |
+|---|---|---|
+| Agent loop, context, permissions, fork, Session persistence | Existing Runtime / Coordinator / SessionManager | None; preserve existing host ownership |
+| Read windows, tail, text encoding and output budgets | `tool-execution` reading algorithm | Open a byte stream; metadata when needed |
+| Edit/Write matching, freshness and result construction | Existing tool pipeline and read-state owner | Read bytes, inspect metadata, write bytes |
+| LS/Glob filtering, order and presentation | Shared listing and search helpers | Enumerate typed entries with metadata |
+| Grep pattern/type/ignore policy and result reduction | Shared search helpers | Native scanning, remote bytes, optional compatible search accelerator |
+| Snapshot hashes, compression, history and revert phases | Existing Snapshot owners on the BitFun host | Read/restore/remove actual workspace files |
+| Exec lifecycle and output | Existing execution owner | Local process or existing SSH process transport |
+| Hook contract, permission decisions and source trust | Existing hook owner | Explicitly selected execution domain and process provider |
+
+`WorkspaceFileSystem` remains the typed boundary. It must distinguish missing
+paths from permission/transport errors, preserve byte content and symlink
+semantics, expose real metadata, and provide streaming reads and the mutation
+operations actually consumed by tools and snapshots. File length or timestamp
+not supplied by a backend is unknown, not zero. Remote modification times come
+from the target, not the controller clock.
+
+Local and SFTP readers can seek. A Docker stream may reject seek explicitly
+while supporting the shared forward-only parser and tail ring buffer; it must
+not implement seek by silently downloading an entire file to a temporary local
+copy. Cancellation drops/cancels the transport, and successful EOF must include
+successful command completion. Output and memory bounds do not imply a bound
+on network transfer.
+
+The path resolver and Runtime context select the provider once from the
+Session's verified workspace binding. A remote request with an unavailable
+provider fails; it never acquires a local provider as a fallback. Explicit
+`bitfun://` artifacts remain host-owned and use local storage even in a remote
+Session. Tools must not consult whichever workspace is currently selected in
+the UI. POSIX remote paths must not acquire controller OS path semantics.
+
+### Search and large-file performance
+
+Preserve the local native parallel scanner and its ignore behavior. Do not
+route all local search through a POSIX shell just to make the call sites look
+the same. Share pattern/type expansion, matching semantics, sorting, pagination
+and output construction; retain provider-specific data access optimizations.
+
+An already available compatible target search executable can reduce network
+traffic. It is an optional accelerator, not a requirement to install BitFun.
+Its results must satisfy the same contract, including file type definitions,
+ignore rules, Unicode, filenames containing newlines, context and truncation.
+Do not equate different system `rg` type catalogs or approximate a Rust regex
+with system grep and report an empty result as success.
+
+The built-in `Grep` API accepts structured search arguments; it is separate from
+model-authored `ExecCommand` shell text. ExecCommand preserves the submitted
+command and reports the target environment's actual result. The model can then
+choose another available command; the runtime does not silently rewrite it.
+
+Current target prefilters accept nonempty case-sensitive literals or unions of
+literal alternatives. They never compile the full user regex in a second engine:
+even an installed `rg` can have different Unicode tables. Other expressions use
+the shared scanner. A behavior-probed `rg` returns framed NUL-delimited candidate
+paths. If unavailable, a behavior-probed system `grep -a -F -q` checks authorized
+regular files in batches of at most 128 paths / 16 KiB of command text. These are
+transport batch sizes, not search limits; oversized arguments use file streams.
+Grep additionally retains UTF-16 BOM files so native BOM decoding cannot create
+a match that the byte prefilter excluded. Per-file statuses and a completion
+marker distinguish no match from errors, startup banners and truncated output.
+Only the shared Rust matcher computes results, counts, context and pagination.
+This fallback saves file transfer but still starts one grep process per file;
+it is not a claim of equal performance on small-file trees or slow connections.
+
+Without a compatible accelerator, identical matching may require reading
+remote file bytes into the shared scanner. That preserves semantics but costs
+bandwidth and SSH round trips. Exact total line counts and complete content
+hashes also require examining complete input. Make that cost observable,
+support cancellation/backpressure, and measure it with large-file and slow-link
+fixtures. Do not hide it behind arbitrary file-count, depth or size cutoffs.
+An existing optimized path must not be replaced until the shared path has
+behavior and performance evidence; incomplete migrations remain explicit.
+
+The current WorkspaceFS scanner applies `.gitignore`/`.ignore` inside the
+requested search scope; it does not import parent, global Git or
+`.git/info/exclude` rules and reports that boundary in its result. File symlinks
+can be read, but directory-link roots and hard-link restrictions without a
+provider identity proof fail explicitly. Content/count searches scan candidates
+to compute accurate totals; multiline matching uses the native searcher's
+buffering. The remote query retains its cancellable 30-second deadline.
+Output retention is bounded by pagination independently of exact match counting;
+one extra retained line preserves the truncation indicator. Search results expose
+the selected backend, scanned-file count and stream bytes. Cancellation covers
+metadata, enumeration and opening as well as reading. Ordinary SSH command tasks
+retain transport ownership after caller drop to interrupt, drain and close their
+channel without cancelling sibling commands. Callers return after a bounded
+cleanup grace period; the transport owner retains a pending channel-open request
+until confirmation or disconnect, then closes a late channel without executing
+the cancelled command. A request that never receives confirmation cannot be
+individually closed with the current SSH library, so its owner remains until the
+transport ends rather than disconnecting the shared connection.
+These are current limits, not evidence of complete backend parity.
+
+### Snapshot storage and safe mutations
+
+Keep snapshot blobs, metadata, operation history and revert state in the
+existing local workspace runtime or remote-workspace mirror directories.
+Only the current workspace file bytes and metadata use the selected filesystem
+provider. Hashing, diff calculation, operation history and the staged revert
+state machine remain shared. No remote database, Session service, credential
+copy or model-network migration is introduced.
+
+Snapshot manager caches, locks and persistence scope must identify the exact
+workspace binding, including the SSH connection. A POSIX path alone cannot
+identify a workspace when two users/hosts expose the same path. Existing data
+must remain readable; new isolation must not delete or reinterpret old records.
+Historical remote edits without snapshots cannot acquire a fabricated baseline
+from current file contents. Enable rollback only when its real evidence exists.
+
+New remote snapshot directories are scoped by the complete Session connection
+identity inside the existing local mirror. Unattributed legacy records remain
+untouched and are not treated as proven history for that connection. Only
+successful snapshot completion adds `snapshot_recorded: true` to the persisted
+tool result. Operation cards use that fact to query immutable summary/diff
+history with the same Session scope, including while disconnected. This does
+not enable current-file comparison, full-Session rollback or Session-wide
+snapshot refresh for older remote history.
+
+Prepare tracking, invoke the tool once, then complete tracking. A bookkeeping
+failure after a mutation cannot cause the wrapper to invoke the tool again.
+Retain the real tool result and an explicit snapshot warning. A transport loss
+after submitting a mutation can have an unknown outcome; it must not be
+reported as definitely unapplied or automatically replayed.
+
+Local/remote read-before-write checks must use the same algorithm, but neither
+ordinary local filesystem writes nor SFTP provide a universal compare-and-swap
+against arbitrary external editors. Recheck freshness and preserve conflict
+errors. Do not describe an in-process lock, preflight timestamp or rename as a
+cross-user transaction guarantee.
+
+### Multiple users and capability differences
+
+Each BitFun host retains its own Session, model credentials, permissions and
+connection state. SSH authenticates an ordinary target OS user; no shared
+BitFun daemon or global target configuration is introduced. Connection routing
+and local mirrors must not mix profiles or identities. If users intentionally
+share a target OS account or directory, normal filesystem permissions and
+concurrent-edit conflicts still apply; BitFun cannot manufacture isolation
+between identical OS credentials.
+
+Discover capabilities at the provider/assembly boundary, not with scattered
+`is_remote` gates in individual tools. Missing target programs, an unavailable
+interactive desktop, network loss and platform-specific process behavior can
+require explicit differences. A local hook executable or MCP command is not
+silently relocated to the target. Keep its execution domain and source trust
+explicit; reuse the existing engine and approval mechanism.
+
+Remote workspaces do not acquire Detached Dispatch semantics through this
+change: closing the BitFun host does not promise a durable remote Agent run.
+Keep existing cancellation/reconnection behavior and report unknown command
+outcomes honestly.
+
+### Completion evidence
+
+Run the same real tool and snapshot fixtures with local and SSH-backed IO,
+comparing results, file bytes, error categories, ordering, read-state, fork,
+rollback and interaction behavior. Test direct SSH, ProxyJump, local Docker
+and remote Docker separately. Local fake-provider tests are useful owner
+coverage but are not evidence of actual SSH behavior.
+
+Include binary/invalid UTF-8 input, CRLF, empty and very large files, tail and
+pagination, Unicode/newline names, symlinks, permission errors, offline targets,
+external changes, same-path different identities, snapshot start/completion
+failure and cancellation during transfer. Controller sentinel files must stay
+unread and unchanged for remote workspace requests. Preserve old profile and
+Session payload round trips.
+
+The structural gate removes duplicate tool algorithms and routes workspace IO
+through the bound provider. Raw filesystem/process calls that remain must have
+an explicit owner: local Session/artifact storage, a concrete provider, or a
+measured compatible accelerator. Moving a remote shell builder into a wrapper
+without sharing its semantics does not satisfy the gate. Remote Control, Peer
+Device and Detached Dispatch remain separate scenarios requiring their own
+regression evidence.