fix(remote-ssh): prevent SFTP handle exhaustion after repeated file operations

docs/features/remote-workspaces.md

@@ -99,6 +99,27 @@ The configured Docker CLI remains the security boundary. OpenBitFun does not exp
 the Docker daemon over the network or bypass the current user's Docker
 permissions.
 
+### SFTP handle ownership
+
+Whole-file SFTP transfers wait for CLOSE acknowledgement before reporting
+success, including reads. The file guard retains cleanup ownership after cancellation,
+I/O errors, or a dropped streaming reader; it also receives and closes late OPEN
+replies after the caller stops waiting. Writes are not replayed if their outcome
+is uncertain. A failed close or timed-out OPEN retires the affected SFTP subsystem
+so its unknown handles and client accounting cannot poison later operations.
+
+Full and bounded directory enumeration use the same serialized raw SFTP path,
+which closes directory handles on errors as well as success. Cancellation retires
+that directory subsystem, and subsequent enumeration replaces it without
+invalidating the SSH transport or the separate file subsystem. No persisted
+profile, workspace, or wire shape changes are required.
+
+The locked russh-sftp 2.3 dependency sends CLOSE on ordinary file drop without
+reducing its client-side handle count. Relying on that drop alone can therefore
+produce `Limit exceeded: handle limit reached` even after the server has closed
+every file. See [Desktop troubleshooting](../../src/apps/desktop/README.md#remote-ssh-file-handle-errors)
+for recovery guidance.
+
 ## Search on hosts without ripgrep
 
 Agent Grep keeps one matching and result-processing implementation. For

src/apps/desktop/README.md

@@ -47,3 +47,21 @@ controls can continue driving a host session, but do not expose WSL connection
 setup. Detached Dispatch does not provision WSL connections. SSH port forwarding
 is unavailable for native WSL targets; use Windows WSL networking to reach a
 Linux service.
+
+## Remote SSH file handle errors
+
+If writing files and browsing directories both start failing with
+`Limit exceeded: handle limit reached`, update OpenBitFun to a build containing
+the SFTP handle-lifecycle fix. Earlier builds can exhaust a client-side counter
+even when the server has already closed the files. Save ongoing work before
+manually disconnecting and reconnecting the remote workspace as a temporary
+recovery; reconnecting can interrupt its terminals and commands.
+
+This message alone does not establish a server configuration problem. Raising
+server limits only delays a leaked-counter failure. Running `ulimit` in a new
+SSH shell does not change the limits of the already-running SFTP subsystem.
+OpenBitFun does not modify the remote user's shell startup files, SSH daemon
+configuration, or OS limits automatically. If the problem persists after the
+fix, capture the OpenBitFun version and logs plus the server's SFTP implementation
+and advertised limits so genuine concurrent-handle or server resource exhaustion
+can be distinguished from a client lifecycle problem.

src/crates/services/services-integrations/AGENTS.md

@@ -125,3 +125,13 @@ On Windows with an initialized WSL distribution, set `OPENBITFUN_TEST_WSL_DISTRO
 and run `cargo test -p openbitfun-services-integrations --no-default-features
 --features remote-ssh-concrete --lib wsl_windows_workspace_transport -- --ignored`
 for binary filesystem/stdio, exit status, cancellation, and saved reconnect.
+
+For SFTP handle ownership and cancellation regressions, run
+`cargo test --locked -p openbitfun-services-integrations --no-default-features
+--features remote-ssh-concrete --lib
+remote_ssh::manager::tests::workspace_sftp::`. These loopback SSH/SFTP tests
+advertise a small handle limit and are included in the existing CI
+`workspace_` filter. To exercise real OpenSSH file IO over loopback SSH, set
+`OPENBITFUN_TEST_SFTP_SERVER` to an installed `sftp-server` executable and run
+the same command with the filter ending in
+`workspace_sftp::openssh_real_files_over_loopback_ssh -- --ignored`.