refactor(agent): unify local and SSH workspace execution

[bobleer]

Summary

Unify local and SSH workspace file tools behind the existing host-side Agent Runtime and session-bound filesystem providers. Remote workspaces remain lightweight: this does not install BitFun CLI or a daemon on the target.

Type and Areas

Refactor, bug fixes, regression tests, CI, and architecture documentation. Areas: tool execution, Runtime ports, local/SFTP/Docker providers, Session fork, snapshots, Desktop APIs, and Web UI.

Motivation / Impact

Remote Read/Edit/search previously had separate implementations and drifted from local behavior. This change shares file reading, mutation validation, directory listing, matching, result reduction, and snapshot file IO. Providers own transport and filesystem differences.

• Built-in Grep uses one Rust matcher. Compatible rg or standard grep can prefilter literal candidates; unavailable accelerators fall back to streaming. Model-authored shell commands are preserved. Search covers unknown extensions, relative globs, complete counts, bounded result retention, and cancellation.
• Session forks validate the complete saved workspace identity, including connections that share a host and path. Snapshot storage stays on the BitFun host and is isolated by connection identity.
• Recorded remote operations support immutable historical diffs while offline. Snapshot failure never repeats a file mutation or fabricates a success receipt. Full remote Session Undo remains explicitly unavailable without complete historical coverage.
• SSH command owners retain late channel-open requests for cleanup without cancelling sibling commands. Workspace Docker writes preserve links and existing permissions. UI caches and pending results are isolated across device surfaces.

Verification

All 13 CI jobs passed on final head 3eb2c4a63a389965cad9c8b0c5f0c9044951eaec: CI run. This includes Windows/macOS/Linux Rust and CLI checks, frontend checks, and x64/arm64 release installer and Relay image validation.

Passed locally on macOS, using Node 22 for frontend checks:

• Web UI: 593 test files / 4,317 tests; pnpm run check:web (types and appearance/theme contracts).
• Core: 1,695 tests passed, 4 existing ignored; Desktop: 371 passed, 4 existing ignored. Core and Web UI were rerun after integrating upstream Plan diagnostics at c150f6ce0.
• Remote SSH: 170 passed, 1 existing ignored; tool runtime: 171 unit tests, 23 integration tests, and 1 doctest passed.
• Runtime ports, tool contracts, read-state, local-provider (5 tests), and disabled-SSH contract suites passed. Native filesystem error and local/remote path fixtures were corrected and revalidated after Windows CI exposed Unix-only assumptions.
• 140 boundary-rule tests, check:core-boundaries, check:repo-hygiene, check:github-config, changed-Rust formatting, and git diff --check passed.

Rust owner commands:

cargo test --locked -p bitfun-agent-tools --no-default-features
cargo test --locked -p bitfun-runtime-ports --no-default-features --features workspace-ports --test session_store_contracts
cargo test --locked -p bitfun-agent-runtime --no-default-features --features agent-runtime --lib file_read_state::
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::
cargo test --locked -p bitfun-services-integrations --no-default-features --features remote-ssh --test remote_ssh_contracts remote_ssh_disabled_contracts::
cargo test --locked -p tool-runtime --no-default-features --features shell-analysis
cargo test --locked -p bitfun-core --no-default-features --features agent-runtime,git,remote-workspace,document-read --lib
cargo test --locked -p bitfun-desktop --lib

Reviewer Notes

Legacy payloads retain defaults and round-trip coverage; existing Session/profile/snapshot data is not deleted or reset. Forked history keeps its inline tool results but drops the source Session's derived snapshot-preview marker. Runtime ownership, credentials, hooks, Peer Device transport, and Detached Dispatch deployment contracts are unchanged.

Windows CI passed the native metadata regression and 144 workspace Agent contracts, including the local/remote Write and LS fixtures. The existing Windows Desktop library harness still encounters the pre-test Tauri loader limitation (#13419); this PR does not broaden that exception. Desktop tests ran on macOS and Linux.

Tests include shared local/remote-provider fixtures, real loopback SSH protocol cancellation, real local search accelerators, and shell-level Docker adapter scripts. These do not substitute for customer-host, ProxyJump, or live Docker end-to-end testing. The CI OS matrix now executes workspace provider and Agent contracts explicitly.

Checklist

• This PR is focused and does not include secrets, temporary prompts, generated scratch files, or unrelated artifacts.
• Relevant verification is recorded above, or skipped checks are explained.
• User-facing strings, docs, and locales are updated where applicable.