feat(FN-4637): complete docs, changeset, and verification fixes

Fusion-Task-Id: FN-4637
Fusion-Task-Lineage: 564c5692-3aaf-4396-9306-a395703cf365

.changeset/FN-4637-bubblewrap-sandbox.md

@@ -0,0 +1,5 @@
+---
+"@runfusion/fusion": patch
+---
+
+Add an opt-in Linux `bubblewrap` sandbox backend with policy-to-`bwrap` argument translation, backend availability detection, and native fallback support.

docs/sandbox.md

@@ -0,0 +1,45 @@
+# Sandbox Backends
+
+## Linux `bubblewrap` backend
+
+Fusion supports an opt-in Linux sandbox backend using `bubblewrap` (`bwrap`).
+
+- Enable with `sandbox.backend = "bubblewrap"`
+- Default remains `native`
+- If unavailable, behavior follows `failureMode` (`fail-hard` or `fallback-native`)
+
+### Install
+
+- Debian/Ubuntu: `sudo apt install bubblewrap`
+- Fedora: `sudo dnf install bubblewrap`
+
+### Policy mapping
+
+`policyToBwrapArgs()` translates sandbox policy into bwrap args:
+
+- Writable binds (`--bind`): worktree path, pnpm store path, plus configured `allowedWritePaths`
+- Read-only binds (`--ro-bind`): repo root (when distinct), system runtime paths (`/usr`, `/bin`, `/lib`, `/lib64`), TLS/DNS paths, and node binary directory
+- Temporary filesystem: `--tmpfs /tmp`
+- Working directory: `--chdir <worktreePath>`
+- Network isolation: `allowNetwork=false` adds `--unshare-net`
+- Environment isolation: `--clearenv` plus allowlisted passthrough (`PATH`, `HOME`, `USER`, `LANG`, `LC_*`, `NODE_*`, `npm_*`, `PNPM_*`, `CI`, `FUSION_*`)
+
+### Port 4040 guard
+
+Port 4040 is reserved for the production dashboard. Sandbox policy rejects `allowedPorts` containing `4040` unless `allowPort4040Override=true` is explicitly set.
+
+### Fusion workflow defaults
+
+Use `fusionWorktreePreset(ctx)` to get the standard Fusion-friendly defaults:
+
+- Worktree writable
+- pnpm store writable
+- `.fusion/fusion.db` is not added to writable mounts
+
+### Troubleshooting
+
+If you see `bwrap: setting up uid map: Permission denied`, unprivileged user namespaces may be disabled by host policy/kernel settings. Enable user namespaces or use `sandbox.backend = "native"` as a fallback.
+
+### Related settings
+
+See `docs/settings-reference.md` for full sandbox settings schema and precedence.

packages/engine/src/sandbox/native.ts

@@ -1,4 +1,4 @@
-import { exec } from "node:child_process";
+import { exec, type ExecOptions } from "node:child_process";
 import { promisify } from "node:util";
 
 import type { SandboxBackend, SandboxCapabilities, SandboxPolicy, SandboxRunOptions, SandboxRunResult } from "./types.js";