feat(worktree): add ScorpioFS backend

Cargo.toml

@@ -12,7 +12,8 @@ categories = ["command-line-utilities", "development-tools"]
 readme = "README.md"
 
 [features]
-default        = []
+default        = ["scorpiofs-direct"]
+scorpiofs-direct = ["dep:scorpiofs"]
 worktree-fuse  = []   # Unix FUSE-backed worktree commands (optional)
 test-network   = []   # L2: tests requiring outbound network but no secrets
 test-live-ai   = []   # L3: tests calling real LLM APIs
@@ -70,6 +71,7 @@ sea-orm = { version = "1.1.20", features = [
 ]}
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = "1.0.149"
+fs2 = "0.4.3"
 sha1 = "0.11.0"
 sha2 = "0.10"
 thiserror = "2.0.18"
@@ -158,6 +160,7 @@ rfuse3 = { version = "0.0.8", features = ["tokio-runtime", "unprivileged"] }
 
 [target.'cfg(target_os = "linux")'.dependencies] # Linux-only seccomp BPF compiler
 seccompiler = { version = "0.5.0", features = ["json"] }
+scorpiofs = { version = "=0.3.1", optional = true }
 
 [target.'cfg(windows)'.dependencies]
 windows-sys = { version = "0.61.2", features = ["Win32_Storage_FileSystem"] }

docs/commands/worktree.md

@@ -8,6 +8,8 @@ Manage multiple working trees attached to this repository.
 
 ```
 libra worktree add <path>
+libra worktree scorpiofs attach --remote-path <mega-path> --job-id <id>
+libra worktree scorpiofs detach <mountpoint>
 libra worktree list
 libra worktree lock <path> [--reason <text>]
 libra worktree unlock <path>
@@ -22,6 +24,12 @@ libra worktree repair
 
 `libra worktree` manages multiple working trees that share a single repository database and object store. This allows you to have several checkouts of the same repository simultaneously, which is useful for working on multiple branches at once, running builds while editing code, or testing changes in isolation.
 
+Mounted worktrees use the backend-neutral architecture documented in
+[`worktree-storage-backends.md`](../development/integration/worktree-storage-backends.md).
+ScorpioFS is a remote-revision projection backend; BrewFS is modeled as a
+persistent distributed-volume backend. Git objects, refs, index state, and
+authoritative backend lifecycle state remain owned by Libra.
+
 Each linked worktree is a directory containing its own real `.libra` gitdir — a local directory (not a symlink) that holds the worktree's private `HEAD`, index, and `HEAD` reflog, plus a `commondir` pointer to the shared storage and a stable `worktree_id`. The main worktree is the original repository directory. All worktrees share the same SQLite database, object store, branch/tag/remote refs, and configuration, but each keeps its own checked-out branch and staging state. (A worktree created by an older Libra version may still use the legacy shared-`.libra` symlink layout; run `libra worktree repair` to check.)
 
 Worktree metadata is persisted in a `worktrees.json` file inside the `.libra` storage directory. Each entry tracks the filesystem path, whether it is the main worktree, its lock status, and an optional lock reason. The state file is written atomically via a temporary file rename to prevent corruption.
@@ -47,6 +55,36 @@ libra --json worktree add ../my-feature
 libra worktree add /tmp/libra-test
 ```
 
+### Subcommand: `scorpiofs attach`
+
+Creates or recovers an idempotent Antares mount, waits for readiness, and
+attaches persistent Libra linked-worktree metadata to the returned mountpoint.
+By default on Linux, Libra starts a resident worker that links the ScorpioFS
+crate directly. Libra owns the worker and desired mount state in
+`.libra/scorpiofs/state.json`; ScorpioFS owns only live filesystem
+materialization. Libra also continues to own the index, objects, commits,
+refs, fetch, and push.
+
+```bash
+libra worktree scorpiofs attach \
+  --config-path scorpio.toml \
+  --remote-path /project/aardvark-dns \
+  --job-id dev-aardvark
+```
+
+Pass `--endpoint http://127.0.0.1:2725/antares` to use an externally managed
+ScorpioFS daemon as a compatibility transport instead.
+
+### Subcommand: `scorpiofs detach`
+
+Refuses to detach a dirty worktree, removes its persistent linked-worktree
+metadata, and asks Antares to delete the mount by job ID. Repeated remote
+cleanup is idempotent.
+
+```bash
+libra worktree scorpiofs detach /var/lib/antares/mounts/<mount-id>
+```
+
 ### Subcommand: `list`
 
 List all registered worktrees and their state. `--porcelain` emits a stable,