@microck/raft 0.5.0 → 0.7.0

package/deploy/verify-sync.py

@@ -0,0 +1,122 @@
+"""Exercise repeated source sync against a disposable native workspace."""
+
+import argparse
+import importlib.util
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import tempfile
+
+spec = importlib.util.spec_from_file_location("live", Path(__file__).with_name("verify-live.py"))
+live = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(live)
+
+
+def verify(location):
+    box = live.raft(
+        "new",
+        "--location",
+        location,
+        "--ttl",
+        "600",
+        "--disposable",
+        "--purpose",
+        "Source sync verification",
+        "--owner",
+        "verify-sync",
+    ).stdout.strip()
+    try:
+        live.wait_running(box)
+        with tempfile.TemporaryDirectory(prefix="raft-sync-") as folder:
+            source = Path(folder) / "source"
+            source.mkdir()
+            subprocess.run(["git", "init", "-q", source], check=True)
+            (source / ".gitignore").write_text("ignored\n")
+            (source / "ignored").write_text("private")
+            (source / "file").write_text("first")
+            (source / "nested").mkdir()
+            (source / "nested/file").write_text("nested")
+            unusual = [
+                "space name",
+                "a*b",
+                "a?b",
+                "a[b]",
+                "back\\slash",
+                "line\nbreak",
+                "back\\*star",
+            ]
+            for path in unusual:
+                (source / path).write_text(path)
+            (source / "link").symlink_to("file")
+            (source / "unsafe").symlink_to("../outside")
+            outside = Path(folder) / "outside"
+            outside.mkdir()
+            (outside / "file").write_text("must not leak")
+            subprocess.run(["git", "-C", source, "add", "."], check=True)
+
+            def sync(*options):
+                return live.raft("sync", box, str(source), "/workspace/sync target", *options)
+
+            def files():
+                return json.loads(
+                    live.execute(
+                        box,
+                        "python3",
+                        "-c",
+                        """
+import json, pathlib
+root = pathlib.Path('/workspace/sync target')
+print(json.dumps({str(p.relative_to(root)): p.read_text(errors="replace") for p in root.rglob('*') if p.is_file()}))
+""",
+                    )
+                )
+
+            sync("--dry-run")
+            assert (
+                live.raft(
+                    "exec", box, "--", "test", "-e", "/workspace/sync target", check=False
+                ).returncode
+                != 0
+            )
+            sync()
+            first = files()
+            assert first["file"] == "first" and first["nested/file"] == "nested", first
+            assert "ignored" not in first and "unsafe" not in first
+            assert all(first[path] == path for path in unusual), first
+            assert not any(path.startswith(".git/") for path in first), first
+            repeated = sync()
+            assert not any(
+                line.startswith(("<f", ">f")) for line in repeated.stdout.splitlines()
+            ), repeated.stdout
+            stamp = (source / "file").stat()
+            (source / "file").write_text("other")
+            os.utime(source / "file", ns=(stamp.st_atime_ns, stamp.st_mtime_ns))
+            sync("--dry-run")
+            assert files()["file"] == "first"
+            sync()
+            assert files()["file"] == "other"
+            (source / "file").unlink()
+            sync()
+            assert files()["file"] == "other", "Guest-only files must survive"
+            # A directory replaced by an escaping symlink must never cause the
+            # tracked descendant to be read from outside the selected source.
+            shutil.rmtree(source / "nested")
+            (source / "nested").symlink_to(outside)
+            sync()
+            assert files()["nested/file"] == "nested"
+            sync("--all")
+            assert files()["ignored"] == "private"
+            assert live.raft("sync", box, str(source), "/", check=False).returncode != 0
+            print(
+                f"{location}: sync filtering, repeat, checksum, dry-run, preservation and links passed"
+            )
+    finally:
+        live.raft("destroy", box)
+
+
+if __name__ == "__main__":
+    cli = argparse.ArgumentParser(description=__doc__)
+    cli.add_argument("--location", required=True)
+    verify(cli.parse_args().location)

package/docs/benchmarks/read-latency-2026-10-29.json

@@ -0,0 +1,70 @@
+{
+  "date": "2026-10-29",
+  "baselineCommit": "1fd6d62f",
+  "unit": "seconds",
+  "method": "Five sequential samples per command/version, one configured ARM64 Incus 6.0.6 host. Controller-visible execution includes Python and SSH. Update checks disabled. Exploratory sample; not a boot or workload benchmark.",
+  "samples": {
+    "list": {
+      "baseline": [
+        0.8216385410050862,
+        0.8366823430042132,
+        0.8693760940004722,
+        0.8536870829993859,
+        0.8263150519996998
+      ],
+      "candidate": [
+        0.4651195309998002,
+        0.4672731250029756,
+        0.4791866140003549,
+        0.47663515599560924,
+        0.45945281199965393
+      ]
+    },
+    "capacity": {
+      "baseline": [
+        0.8409752599982312,
+        0.8461970310017932,
+        0.8160613539948827,
+        0.8384463539987337,
+        0.8118131250012084
+      ],
+      "candidate": [
+        0.47482109300472075,
+        0.48634999999922,
+        0.4781393230005051,
+        0.47350171799917007,
+        0.49643182300496846
+      ]
+    },
+    "doctor": {
+      "baseline": [
+        2.2246155190005084,
+        2.1928324990003603,
+        2.2085186969998176,
+        2.260335936996853,
+        2.1928395819995785
+      ],
+      "candidate": [
+        0.5241887500014855,
+        0.5317754690040601,
+        0.5393725000030827,
+        0.5227220310043776,
+        0.5310975519969361
+      ]
+    }
+  },
+  "medians": {
+    "list": {
+      "baseline": 0.8366823430042132,
+      "candidate": 0.4672731250029756
+    },
+    "capacity": {
+      "baseline": 0.8384463539987337,
+      "candidate": 0.4781393230005051
+    },
+    "doctor": {
+      "baseline": 2.2085186969998176,
+      "candidate": 0.5310975519969361
+    }
+  }
+}

package/docs/boat-capabilities.md

@@ -1,10 +1,43 @@
 ---
-title: Boat feature parity
+title: Raft and Boat
+description: Compare Raft’s self-hosted containers with Boat’s managed VMs and workflows.
 ---
 
-# Boat capability coverage
+# Raft and Boat
 
 Raft is an independent open-source alternative to [boat.dev](https://boat.dev).
+## Choose by operating model
+
+- **Raft:** bring a dedicated Ubuntu host and manage it through host SSH. Boxes
+  are unprivileged containers sharing its kernel. You operate storage, upgrades
+  and backups; there is no hosted billing, organization account or HTTP API.
+- **Boat:** a managed service with full VMs, account/API workflows, public hosting
+  and integrated agents. Its pricing, snapshot retention and security model are
+  different from Raft's.
+
+Start with [Raft setup](./operations.mdx) to use it, or expand the detailed matrix
+when evaluating a specific capability. Similar commands are not a promise of
+identical behavior, isolation or cost.
+
+## What remains for parity
+
+The largest missing pieces are a remote API with scoped credentials and SDKs,
+managed agent conversations, versioned environments and secrets, public HTTPS
+ingress, and team access. These require product and infrastructure work beyond
+adding CLI commands.
+
+Operational gaps include automatic snapshots, shared templates, snapshot file
+browsing, retained command history, process inspection and telemetry export.
+Smaller CLI gaps include reverse tunnels, shell completions, uniform JSON errors,
+friendly names and macOS/Windows controller support.
+
+VM kernel isolation and nested KVM require a different runtime mode. Raft's
+current container boundary cannot provide them through a flag. Browser-only
+streaming is also separate from the existing full desktop.
+
+<details>
+<summary>Detailed capability matrix and verification evidence</summary>
+
 ✅ supported · ❌ unavailable through the compared product · ❓ not established by Boat's documentation.
 
 A shared checkmark means both offer the workflow, not identical behavior or isolation.
@@ -25,6 +58,7 @@ Tests verify Raft behavior, not hosted Boat infrastructure. See [verification](.
 | Usage | ✅ | ✅ | Cgroup memory, CPU counters, and shared-pool or own-disk space. No billing meter |
 | Root terminal | ✅ | ✅ | PTY over host SSH and native Incus exec. No directly exposed guest SSH endpoint |
 | Synchronous exec | ✅ | ✅ | Literal argv and preserved exit code. Shell syntax requires an explicit shell |
+| Disposable foreground CI | ✅ | Preview | Unreleased 0.7.0: `run` orchestrates one fresh box, Git-aware upload, output collection and cleanup. Fixed timeout, no lease renewal/keep mode; host sudo SSH rather than scoped API keys. [CI guide](./guides/ci-jobs.mdx) |
 | Detached exec | ✅ | ✅ | Guest systemd unit, status, logs, cancellation. No process checkpoint or restart after stop |
 | File transfer | ✅ | ✅ | Binary file upload/download. Recursive tree transfer for running boxes; no directory merges |
 | Named snapshots | ✅ | ✅ | Create/list/restore with stopped source, checked inside the lifecycle lock. No running snapshot consistency guarantee |
@@ -42,24 +76,43 @@ Tests verify Raft behavior, not hosted Boat infrastructure. See [verification](.
 | Bounded host storage pools | ❓ | ✅ | Raft configures a shared 60 GiB Btrfs pool and, when enabled, a fully allocated LVM thin pool for own box disks that it never overcommits, and rejects size drift. Boat does not document an operator-managed host storage pool |
 | Strict per-box disk allocation | ✅ | ✅ | On hosts with own box disks enabled, `new --disk SIZE` gives a box a fixed-size, copy-on-write ext4 disk that guest and Docker writes cannot exceed. Shared-pool boxes, the default, have no per-box quota |
 | VM kernel isolation | ✅ | ❌ | VM deployment not implemented |
-| Nested KVM / Android emulator acceleration | ✅ | ❌ | Boat documents KVM on standard hosts; overflow cloud VMs lack it. Raft has no guest KVM device or VM mode |
+| Nested KVM / Android emulator acceleration | ✅ | ❌ | Boat currently documents `/dev/kvm` on every sandbox. Raft has no guest KVM device or VM mode |
 | External guest SSH | ✅ | ❌ | Boat supports a public IP or an SSH endpoint; public IPv4 is not guaranteed. Raft uses host-mediated private access |
 | Named environments and secrets | ✅ | ❌ | Files/configuration can be prepared explicitly. No environment registry or secret-injection service |
-| Organizations | ✅ | ❌ | Boat shares billing and plan limits; resources stay with their creator. Raft is single-operator |
+| Organizations | ✅ | ❌ | Boat supports team-visible sandboxes, optional shared access, roles and per-member environment/profile restrictions. Raft is single-operator |
 | Lifecycle webhooks | ✅ | ❌ | Missing. Deferred until an external consumer needs them |
 | Automatic deletion/retention | ✅ | ✅ | Disposable delete-on-stop/expiry; opt-in stopped-box retention cleanup with preview |
 | Dashboard | ✅ | ❌ | Missing. CLI and private desktop cover current workflow |
 | SDK/API keys | ✅ | ❌ | Host SSH authentication. No remote Raft service API |
-| CLI-wide JSON mode | ✅ | ❌ | Boat supports JSON/JSONL for most commands; argument errors may use stderr. Raft provides JSON for list/info/usage/capacity and JSONL for prune |
+| CLI-wide JSON mode | ✅ | Preview | Boat supports JSON/JSONL for most commands; argument errors may use stderr. Raft provides command-specific JSON/JSONL for locations, list, info, usage, capacity, config and prune, and unreleased global JSONL events for reports, streams, errors and exit codes |
 | Snapshot file browsing/download | ✅ | ❌ | Full native archives only; no Raft snapshot tree or selected-file interface |
 | CLI self-update | ✅ | ✅ | `raft self-update` upgrades npm global installs through the registry and uv tools from a release wheel checked against `SHA256SUMS`. A daily stderr notice reports new releases. Boat also updates itself after commands; Raft never installs without the command and never changes hosts |
-| Dynamic shell completions | ✅ | ❌ | Static `--help` only |
+| Dynamic shell completions | ✅ | Preview | Unreleased Bash, Zsh and Fish scripts query the installed parser for commands, options and fixed choices |
 | Managed agents | ✅ | ❌ | Not implemented. No prompt/events/steer/interrupt/conversation API |
+| Automatic incremental snapshots | ✅ | ❌ | Boat documents saves every minute and on stop. Raft retains the container disk and creates named snapshots only on request; no scheduled off-host snapshot service |
+| Share saved templates across accounts | ✅ | ❌ | Boat provides revocable deployment codes and credential cleanup. Raft copies complete filesystems on the same host or imports trusted whole archives; no sharing identity or sanitization service |
+| Versioned environments and upgrades | ✅ | ❌ | Boat versions repositories, setup and secrets, with explicit upgrades. Raft has image pins, controller defaults and filesystem templates, not an environment registry |
+| AI credential profiles and proxy | ✅ | ❌ | No provider credential manager, sandbox access switch, usage accounting or AI request proxy |
+| OpenTelemetry export | ✅ | ❌ | No built-in OTLP metrics or lifecycle-event export |
+| Command history while stopped | ✅ | Preview | Unreleased retained detached-job results survive stop and deletion for seven days, with a 1 MiB log cap. No general process history or samples |
+| Process inspection command | ✅ | ❌ | Raft can execute guest tools such as ps, but has no first-class process/history API or stopped-box process samples |
+| Merge source into existing directories | ✅ | Preview | Boat push replaces matching files in an existing destination. Unreleased `sync` replaces matching files with Git filtering and checksum-based incremental transfer; it preserves guest-only files. Recursive upload still requires a new destination |
+| Human-readable names and current/self aliases | ✅ | ❌ | Raft uses exact location-qualified handles and ownership notes; no rename or implicit current-box selection |
+| macOS and Windows controllers | ✅ | ❌ | Raft's controller requires Linux; native ARM64/AMD64 guest support is a separate capability |
+| Unresponsive-machine recovery | ✅ | ❌ | Boat recover power-cycles an unresponsive VM. Raft recover imports an archive and is not the equivalent operation |
 
 ## Reference check
 
-Checked on 2026-10-07 against Boat's [CLI reference](https://docs.boat.dev/cli-reference), [machine capabilities](https://docs.boat.dev/machines), [SSH/file access](https://docs.boat.dev/ssh-access), [snapshots](https://docs.boat.dev/snapshots), [data retention](https://docs.boat.dev/data-retention), and [billing and limits](https://docs.boat.dev/billing).
+Rechecked on 2026-10-29 against Boat's [CLI reference](https://docs.boat.dev/cli-reference), [machine capabilities](https://docs.boat.dev/machines), [SSH/file access](https://docs.boat.dev/ssh-access), [snapshots](https://docs.boat.dev/snapshots), [environments](https://docs.boat.dev/environments), [environment versions](https://docs.boat.dev/environments/versions), [organizations](https://docs.boat.dev/organizations), [AI proxy API](https://docs.boat.dev/api/reference/ai-credentials/get-ai-credentials-proxy), and [telemetry API](https://docs.boat.dev/api/reference/account/get-opentelemetry-export).
+
+Some Boat overview/API text still describes creator-private resources; the dedicated organization guide and current CLI document shared sandboxes. This matrix follows those specific workflow descriptions. Boat's browser-only view restricts display and input, not access by other code inside its sandbox. These are documented capabilities, not independently tested security guarantees.
+
+Raft's latest published release was verified as [0.6.0](https://github.com/Microck/raft/releases/tag/v0.6.0) on 2026-10-29. `run` and the new help/read-performance changes remain development-branch features until released.
 
 The new workspace-control suite passed on ARM64 and AMD64 at runtime commit `a7fef1f5` in [run 37603576786](https://github.com/Microck/raft/actions/runs/37603576786). The baseline native architecture and disposable AMD64 host tests passed in [run 37496577945](https://github.com/Microck/raft/actions/runs/37496577945). This audit compares documented features, not a live differential test against Boat. Managed agent workflows remain out of scope.
 
 Recursive transfers, resume/fork sizing, snapshot templates/deletion and disposable lifecycle are implemented. Directory transfers require a running box; templates stay on the source host. Public hosting, VM isolation, organization sharing, and remote APIs require additional infrastructure. noVNC tests do not establish parity for Boat frame rate, browser confinement or application set.
+
+CI comparison sources (reviewed 2026-10-22): [Boat CI](https://docs.boat.dev/ci), [CLI run](https://docs.boat.dev/cli-reference#boat-run-command), [scoped API keys](https://docs.boat.dev/api-keys/scopes), and [snapshot contents](https://docs.boat.dev/snapshots/whats-saved). Matching workflows do not imply matching security boundaries or costs.
+
+</details>

package/docs/boat-parity-design.md

@@ -1,5 +1,6 @@
 ---
 title: Design decisions
+description: "Architecture choices for contributors: Incus, SSH, clean images and private access."
 ---
 
 # Architecture and references

package/docs/boot-performance.mdx

@@ -1,5 +1,6 @@
 ---
 title: Boot performance
+description: Dated native boot measurements, sample limits and reproducible benchmark commands.
 ---
 
 # Native images and boot performance
@@ -8,6 +9,26 @@ Raft builds Debian 13 system container images for native ARM64 and AMD64 hosts.
 
 Timings depend on software, image state, hardware, host load, and network transport. These measurements do not compare Raft with hosted Boat.
 
+## Controller read latency, 2026-10-29
+
+The development CLI batches host reads into one SSH connection per command.
+Five samples per version on one ARM64 Incus 6.0.6 host gave these medians:
+
+| Command | Baseline at 1fd6d62f | Candidate | Reduction |
+| --- | ---: | ---: | ---: |
+| `list --location HOST` | 0.837 s | 0.467 s | 44% |
+| `capacity --location HOST` | 0.838 s | 0.478 s | 43% |
+| `doctor` for one host | 2.209 s | 0.531 s | 76% |
+
+[Raw samples](benchmarks/read-latency-2026-10-29.json) include all timings.
+Both versions used the same controller, host and SSH configuration, with
+`RAFT_NO_UPDATE_CHECK=1`. Each sample started a fresh Python process; doctor
+called `raft.doctor(location)` directly because the baseline CLI cannot select
+one host. Five baseline samples preceded five candidate samples per command.
+These are exploratory network-dependent timings, not boot or guest workload
+speedups. The changes retain fast metadata reads and the worker compatibility
+lock; they do not weaken lifecycle checks or change host services.
+
 ## Native CI comparison
 
 [Verified native run](https://github.com/Microck/raft/actions/runs/37447415532), 2026-10-06. Five samples per architecture on 4-CPU runners with 1 guest CPU and 2 GiB guest RAM:

package/docs/contract.md

@@ -1,9 +1,13 @@
 ---
 title: Runtime contract
+description: Detailed implementation behavior and safety boundaries for maintainers.
 ---
 
 # Raft contract
 
+This is the implementation reference for maintainers and advanced operators.
+For a first run, use [host setup](./operations.mdx) and [your first box](./first-box.mdx).
+
 Raft manages persistent unprivileged native-architecture Incus system containers on configured ARM64 or AMD64 Linux hosts. Containers share the host kernel. Images must match host CPU architecture; foreign-architecture emulation and VM workflows are not implemented.
 
 ## Image releases
@@ -27,6 +31,8 @@ Raft manages persistent unprivileged native-architecture Incus system containers
 - **Firewall precedence**: Redeployment reapplies firewall rules. Incus startup requires successful firewall application before the daemon starts, including socket activation.
 - **Guided onboarding**: `raft host add LOCATION --ssh TARGET` probes the target read-only and refuses unsupported hosts, including macOS, before any change. It prints the exact plan and applies it only after an interactive yes or `--yes`; `--dry-run` stops after the plan. It runs the same deployer as `deploy/deploy.py`, imports an image only after its SHA-256 matches (release `SHA256SUMS` or the local archive digest) and its architecture matches the host, then registers the location with the image fingerprint. It finishes with `doctor` and a disposable create/exec/destroy smoke test; if either fails, it removes the new location from the configuration and leaves host changes for a rerun. It uses existing key-based SSH and never collects passwords or changes SSH, other firewall rules or IP configuration. It requires the deployment files from the npm package or a source checkout.
 - **CLI coverage**: The single-operator workflow spans lifecycle, execution, files, snapshots, jobs, tunnels, backup, and advisory capacity inspection; see the [command reference](./reference/cli.md).
+- **Capability discovery**: Installed `--help` and nested command help describe the current commands, arguments and operational constraints without contacting hosts. `config --location NAME` and `doctor --location NAME` inspect only that configured host; omitting the flag preserves inspection of all hosts. A location filter on `config set/unset` is rejected because defaults belong to the controller.
+- **Read latency**: Listing collects policy and inventory through one SSH connection per host. Capacity collects resources and inventory through one connection. Doctor performs its sequential checks through one connection, retaining the worker compatibility lock. These are read-only observations, not locked snapshots; lifecycle validation remains inside its existing transactions.
 
 ## Configuration and lifecycle defaults
 
@@ -35,7 +41,7 @@ Raft manages persistent unprivileged native-architecture Incus system containers
 | Host identification | Configuration requires named SSH targets using letters, digits, underscores, or hyphens. |
 | Qualified handles | Every handle includes location and instance name (`<location>:<name>`). |
 | Image pinning | Workspace creation requires the immutable 64-hex image fingerprint, not an updating alias. |
-| Lifecycle defaults | Built-in defaults are the first configured location, 1 CPU, 2 GiB RAM, the shared pool, and 600-second lifetime. `~/.config/raft/config.json` can override them for `new` only; explicit flags win. Boxes from a snapshot (`new --from`) and forks keep the source's CPU, RAM and disk instead of any default, configured or built-in; each flag overrides only its own value. `--cpu` takes any positive whole number, `--memory` any positive whole GiB (`16GiB`), `--disk` a positive whole GiB or `shared`, and TTL 60 to 2,592,000 seconds (30 days). |
+| Lifecycle defaults | Built-in defaults are the first configured location, 1 CPU, 2 GiB RAM, the shared pool, a persistent box and 600-second lifetime. `~/.config/raft/config.json` can override them for `new` only; explicit flags win, and `--persistent` overrides a `disposable` default. Boxes from a snapshot (`new --from`) and forks keep the source's CPU, RAM and disk instead of any default, configured or built-in; each flag overrides only its own value. `--cpu` takes any positive whole number, `--memory` any positive whole GiB (`16GiB`), `--disk` a positive whole GiB or `shared`, and TTL 60 to 2,592,000 seconds (30 days). |
 | Box count and size | Raft limits neither how many boxes a host holds nor their size. CPU or RAM limits larger than the whole host (CPU count, or `MemTotal` rounded up to whole GiB) are refused under the host lock before any change, because Incus would clip them silently. Other failures come from Incus, such as too little pool space. |
 | TTL calculation | Running TTL begins after launch completes, using the host clock. Cold image preparation does not consume TTL. |
 | Host locking | Creation, lifecycle transitions, and expiry are serialized by host file lock (`/run/lock/raft-incus.lock`). Noninteractive transactions close controller stdin so commands cannot wait for piped input while holding this lock. Exec, SSH, and file-transfer paths remain unchanged. Piped input to `raft exec` is unsupported. Native Incus admin calls bypass CLI policy. |
@@ -44,14 +50,15 @@ Raft manages persistent unprivileged native-architecture Incus system containers
 
 `raft locations` lists configured locations as JSONL with `location`, `default` and `note` fields without contacting hosts. `raft note LOCATION TEXT` and `raft note LOCATION --clear` edit the optional `note` field in the controller configuration atomically, preserving location order and mode `0600`. Notes are advisory guidance; Raft shows them in `locations`, `capacity` and on stderr from `new`, and never enforces them.
 
-Boxes accept an optional note with a fixed template: `purpose` (required), `owner` and `next`, all nonempty strings. `raft new --purpose TEXT [--owner TEXT] [--next TEXT]` and `raft note BOX ...` store it as JSON in the box's `user.raft.note` Incus key; `raft note BOX --clear` removes it. Each edit replaces the whole note. `raft list` reports it as `note`, or `null`, and reports each box's `disk` as `"shared"` or its own disk size. `new` always writes the key, so `new --from` never inherits a snapshot's note. Forks and recovered backups keep it unless `fork` or `recover` gets note flags, which replace the whole note. Box notes never change lifecycle behavior.
+Boxes accept an optional note with a fixed template: `purpose` (required), `owner` and `next`, all nonempty strings. `raft new --purpose TEXT [--owner TEXT] [--next TEXT]` and `raft note BOX ...` store it as JSON in the box's `user.raft.note` Incus key; `raft note BOX --clear` removes it. Each edit replaces the whole note. `raft list` reports it as `note`, or `null`, reports each box's `disk` as `"shared"` or its own disk size, and reports `deleteAt`, the Unix time retention deletes a stopped box, or `""`. `new` always writes the key, so `new --from` never inherits a snapshot's note. Forks and recovered backups keep it unless `fork` or `recover` gets note flags, which replace the whole note. Box notes never change lifecycle behavior.
 
-## Controller defaults and note policies
+## Controller defaults and host policies
 
-- **Controller defaults**: `~/.config/raft/config.json` holds `{"defaults": {...}}` with optional `location`, `ttl`, `cpu`, `memory` and `disk` for `new`. Precedence is explicit flag, then configured default, then built-in default. `cpu`, `memory` and `disk` apply only to boxes from the image: `new --from` keeps the snapshot's location, CPU, RAM and disk unless a flag overrides them, and `--disk shared` is refused there. A `disk` default on a host without `raft-disks`, or larger than its unreserved space, fails like `--disk` and names `defaults.disk` as the source. Other commands take no defaults. A value is valid exactly when the same text is valid for the flag. Unknown keys, bad values and malformed JSON fail `new` with the file path and key, before any host access. `raft config set/unset` validate first, write atomically under a controller lock, keep mode `0600`, print the change and can repair the key they edit. The file is separate from `incus.json`, so location names never collide with setting names.
-- **Note policy storage**: `raft policy LOCATION --require FIELDS` stores required box note fields, which must include `purpose`, in the host's Incus project key `user.raft.require`; `--clear` empties it. Each change runs under the host lock, prints the old and new fields, records UTC time, the SSH account (`SUDO_USER`) and the self-reported controller user and hostname in `user.raft.require.changed`, and logs to the host journal with tag `raft`. Redeployment leaves these keys unchanged.
+- **Controller defaults**: `~/.config/raft/config.json` holds `{"defaults": {...}}` with optional `location`, `ttl`, `cpu`, `memory`, `disk` and `disposable` for `new`. Precedence is explicit flag, then configured default, then built-in default. `cpu`, `memory` and `disk` apply only to boxes from the image: `new --from` keeps the snapshot's location, CPU, RAM and disk unless a flag overrides them, and `--disk shared` is refused there. `ttl` and `disposable` apply to `new --from` as well, because a snapshot carries no lifecycle; `new --disposable` and `--persistent` are mutually exclusive overrides. `fork` takes no defaults and is persistent without `--disposable`. A `disk` default on a host without `raft-disks`, or larger than its unreserved space, fails like `--disk` and names `defaults.disk` as the source. Other commands take no defaults. A value is valid exactly when the same text is valid for the flag. Unknown keys, bad values and malformed JSON fail `new` with the file path and key, before any host access. `raft config set/unset` validate first, write atomically under a controller lock, keep mode `0600`, print the change and can repair the key they edit. The file is separate from `incus.json`, so location names never collide with setting names.
+- **Policy storage**: `raft policy LOCATION [--require FIELDS|none] [--delete-stopped-after HOURS|never]` sets either host policy or both; each option changes only its own. Required box note fields, which must include `purpose`, live in the Incus project key `user.raft.require`, and `--require none` empties it. Stopped-box retention lives in `user.raft.delete-stopped-after` as a positive whole number of hours, with the time it was set in `user.raft.delete-stopped-after.since`; `never` empties both. Both values are validated before any host change. Each change runs under the host lock, prints the old and new value, records UTC time, the SSH account (`SUDO_USER`) and the self-reported controller user and hostname in the policy's `.changed` key, and logs to the host journal with tag `raft`. Redeployment leaves these keys unchanged.
 - **Note policy enforcement**: `new` (including `--from`), `fork`, `recover` and `raft note BOX` check the note the box will carry. The controller reads the policy first and fails with the missing flags and a complete corrected command before changing anything. The host repeats the check inside the transaction that writes the note, under the host lock, so a concurrent policy change cannot be missed. That transaction also holds the oversize and own-disk reservation checks; all of them run before Incus creates anything. `fork` checks the given note or, without one, the source note read under the lock. `recover` checks a given note before upload; an archived note is checked after import, and a failing import is deleted in the same transaction. `note --clear` and replacement notes that drop a required field are rejected.
-- **Policy scope**: The policy is a guardrail for agents, not an access control. Anyone with host SSH and sudo can change it or create boxes with native Incus commands, and controllers without policy support do not check it. `raft config` reports every location's policy and last change.
+- **Retention enforcement**: The host expiry worker deletes a stopped Raft box, with its snapshots, once the hours have passed since the later of its `user.raft.stopped-at` and the policy's `.since` time, so setting, shortening or renewing a policy never deletes a box sooner than its hours after the change. It runs on the 15-second timer and on `raft gc`, under the host lock, and writes each deletion to the host journal with tag `raft`. Running boxes are never touched. A stopped Raft box without `user.raft.stopped-at`, from a guest poweroff, a native stop, a failed start or `raft recover`, gets the worker's current time as its stop time, never an earlier guess, whether or not a policy is set. A malformed retention value makes the worker delete nothing by retention, still enforce deadlines, and exit nonzero; the CLI reports it with the fix. Setting retention requires the current worker protocol; clearing it does not.
+- **Policy scope**: Policies are guardrails for agents, not access controls. Anyone with host SSH and sudo can change them or create boxes with native Incus commands, and controllers without note policy support do not check it. A native `incus start` leaves a stale stop time that retention trusts. `raft config` reports every location's policies and last changes.
 
 `raft capacity [--location NAME] [--json]` inspects hosts without modifying state. Text and JSON (`notice`) lead with: "Advisory estimate only. Raft enforces no box count or size budget; create the boxes your task needs." It reports effective CPUs, total and available RAM, saved and active box counts, active resource limits, headroom, free space in the host disk and the shared pool, and for `raft-disks` its data space, reserved and used bytes and metadata use (`boxDiskPool`, `null` when own box disks are not enabled).
 
@@ -62,14 +69,14 @@ Boxes accept an optional note with a fixed template: `purpose` (required), `owne
 
 ## Container lifecycle and execution
 
-- **Stop and resume**: Stop terminates guest processes and preserves disk contents; stopped boxes retain disk but do not reserve guest RAM. Resume starts the container anew with an explicit TTL without restoring process memory.
+- **Stop and resume**: For a persistent box, stop terminates guest processes and preserves disk contents; stopped boxes retain disk but do not reserve guest RAM. Resume starts the container anew with an explicit TTL without restoring process memory.
 - **Lifetime extension**: `raft extend --ttl` resets a running box's deadline from current host time without restarting; stopped boxes require `raft resume`.
-- **Host worker contract**: `doctor`, disposable creation/fork, and retention cleanup require the current worker protocol. `doctor` checks it without running expiry or changing boxes, and reports the failing location. A mismatch fails before executing deletion policy or creating a disposable box; deploy the current checkout explicitly. Installing a new CLI does not update host workers.
-- **Disposable lifecycle**: `new --disposable` opts a box into deletion on stop or TTL expiry, including its snapshots. Clones and recovered boxes default to persistent; fork accepts an explicit `--disposable`.
-- **Retention cleanup**: `prune --older-than DAYS` previews persistent stopped boxes with a recorded stop timestamp. `--yes` deletes matching boxes under the host lifecycle lock. Running boxes and boxes without a recorded stop time are excluded. No automatic persistent-box deletion is enabled.
+- **Host worker contract**: `doctor`, disposable creation/fork, prune and setting a retention policy require the current worker protocol (2 since 0.6.0, which added retention). `doctor` checks it without running expiry or changing boxes, and reports the failing location. A mismatch fails before executing deletion policy or creating a disposable box; deploy the current checkout explicitly. Installing a new CLI does not update host workers.
+- **Disposable lifecycle**: `new --disposable`, or a configured `disposable` default without `--persistent`, opts a box into deletion on stop or TTL expiry, including its snapshots. Clones and recovered boxes default to persistent whatever the default; fork accepts an explicit `--disposable`.
+- **Manual cleanup**: `prune --older-than DAYS` previews persistent stopped boxes with a recorded stop timestamp. `--yes` deletes matching boxes under the host lifecycle lock. Running boxes and boxes without a recorded stop time are excluded. Automatic deletion of persistent stopped boxes happens only under a host retention policy.
 - **Resizing**: Resume and fork accept optional CPU/RAM overrides, preserving omitted values. Resume validates stopped state under the lock before changing sizing. Neither changes a box's disk.
-- **Expiration cleanup**: The host timer checks expirations every 15 seconds, stopping expired persistent containers and deleting expired disposable containers. Expiry may be delayed by graceful shutdown, long locked transactions, and host outage until startup.
-- **Destroy**: Removes the container instance and its snapshots, releasing storage. Destroy confirms absence; SSH failure is not proof of deletion. Disposable boxes created with `new --disposable` are deleted on explicit stop or expiry. Persistent boxes still require explicit destroy for deletion.
+- **Expiration cleanup**: The host timer checks expirations every 15 seconds, stopping expired persistent containers, deleting expired disposable containers and applying stopped-box retention. Expiry may be delayed by graceful shutdown, long locked transactions, and host outage until startup.
+- **Destroy**: Removes the container instance and its snapshots, releasing storage. Destroy confirms absence; SSH failure is not proof of deletion. Disposable boxes created with `new --disposable` are deleted on explicit stop or expiry. Persistent boxes still require explicit destroy, prune or a retention policy for deletion.
 - **Execution transport**: Incus exec and file APIs travel over authenticated host SSH without a public Incus listener or injected credentials. Interactive SSH runs a PTY over host SSH and Incus exec.
 - **State inspection and tunnels**: `raft list` and `raft info` read native metadata without guest process counters during shutdown; tunnels use the managed NIC.
 - **Resource reporting**: `raft usage` reports running cgroup memory, CPU microseconds, CPU affinity, and filesystem space with `filesystemScope`: the shared pool, or `own SIZE box disk`. It provides no billing.
@@ -77,6 +84,23 @@ Boxes accept an optional note with a fixed template: `purpose` (required), `owne
 - **Directory transfer completion**: The receiver verifies the sender's exact archive byte count before publication. A truncated stream, including one ending between complete entries, is rejected without publishing a partial tree.
 - **File transfer failures**: Controller write errors return an error before replacing a download destination or publishing a backup archive.
 
+## Source sync
+
+`sync BOX SOURCE DESTINATION` incrementally copies source into a running guest.
+It requires rsync on the controller and guest. By default, Git selects tracked
+and unignored files and excludes `.git`; submodules are rejected. `--all` opts
+into the entire source tree, including ignored and hidden files. Git filtering
+is not a secret scanner. Missing tracked files are omitted.
+
+Matching files are replaced, but guest-only files are never deleted. Checksums
+find changed content even when size and timestamps match. Relative symlinks
+that stay within the source tree are copied; rsync skips unsafe links and
+special files and reports them. Destination must be an absolute non-root path;
+its parent must exist. `--dry-run` reports changes without writing guest files.
+Files are replaced individually through rsync temporary files, not as an atomic
+tree. An interrupted sync can leave some files updated; rerunning converges.
+No host filesystem path is exposed: rsync runs through Incus inside the guest.
+
 ## Security and network isolation
 
 - **User namespaces**: Guest root maps to an unprivileged host UID. Container nesting and intercepted syscalls support Docker without mounting the host Docker socket.
@@ -96,7 +120,9 @@ Boxes accept an optional note with a fixed template: `purpose` (required), `owne
 
 ## Background jobs and desktop
 
-- **Detached jobs**: Commands run as guest systemd units with journal logging and exit status. Job inspection and cancellation reject unknown IDs in the selected workspace. `raft cancel` stops the unit's control group. Stopping the container terminates jobs.
+- **Detached jobs**: Launching requires a running guest and rejects unavailable guests before allocating a record. Commands run as guest systemd units. A transient host supervisor captures the first 1 MiB of combined stdout/stderr in a root-private host store and records completion. `status` returns JSON with state, exitCode, timestamps and droppedBytes; `logs` returns the retained bytes. A confirmed normal exit records its status; signal termination records 128 plus the signal number. Completed results survive workspace stop, deletion and host reboot. Running jobs do not survive guest stop or host reboot; a stopping guest or missing supervisor is reported as interrupted, even if a shutdown handler returns zero. Cancel stops the guest unit's control group and records cancellation even if its host supervisor has already exited. Cancellation waits at most 120 seconds; a timeout preserves the cancellation request and requires inspection or retry. Unknown IDs and mismatched workspace handles are rejected without starting the guest.
+- **Job supervision bounds**: Host submission is asynchronous and waits at most 10 seconds. A submission timeout preserves the record for status inspection because the supervisor may already be queued. Post-run guest inspection waits at most 60 seconds; an unconfirmed result is interrupted. Host reconciliation waits at most 10 seconds and reports an error without changing job states if systemd does not respond. Failed pre-submission setup removes its incomplete record.
+- **Job retention**: `/var/lib/raft-jobs` holds at most 512 records, with one 1 MiB log per record. Results expire seven days after completion. Commands prune expired records when the store is accessed; an idle host may keep expired files until that next access. Full stores reject new jobs rather than evicting unexpired results. Completed records and captured logs are flushed to disk before publication. Unreadable records remain on the host for inspection and count toward the record limit, but do not block access to other jobs. Logs can contain secrets and stay root-private. No historical guest-journal fallback is provided; jobs created by an older controller must be inspected with that version before upgrading.
 - **Desktop service**: On-demand Xvfb, Openbox, and noVNC stack on display `:99` without a login manager. Clipboard exchange is available without login-manager delay. Desktop provides full workspace access, not browser confinement. Closing the tunnel leaves the service running.
 
 ## Backup and recovery
@@ -105,3 +131,52 @@ Boxes accept an optional note with a fixed template: `purpose` (required), `owne
 - **Host locking**: Export holds the host lifecycle lock, temporarily delaying expiry checks on the source host.
 - **Recovery**: `raft recover` imports archives into a stopped container with a fresh name, new MAC address, and cleared TTL. It reads the archive's recorded pool from `backup/index.yaml`: own-disk backups return to `raft-disks` with their size after the reservation check, failing on a host without the pool, and other archives land in `raft-data`. The host note policy applies after the reservation check. Recovery never overwrites existing boxes.
 - **Archive security**: Archives contain full container filesystems, including credentials. Native archive configuration is not sanitized; backups do not imply scheduled off-host uploads. Store archives privately and import only trusted exports.
+
+## Disposable foreground CI
+
+This section specifies the unreleased 0.7.0 development implementation, not
+published 0.6.0. See [release status](./releases/index.mdx).
+
+`run` creates a uniquely marked disposable box and establishes its fixed host
+expiry before startup. It streams one foreground command without retrying it,
+optionally transfers a Git-filtered or explicitly complete source tree, collects
+result directories even after payload failure, then checks ownership and deletes
+under the lifecycle lock. The controller handles timeout and cancellation with
+bounded collection/cleanup attempts and reports unconfirmed cleanup as failure.
+Unacknowledged creation is cancelled under the same lock with a private host
+record; a queued creation checks it before allocation. These root-only records
+remain in `/run/raft-ci-cancelled` until reboot so late SSH requests cannot outlive
+their cancellation. Ordinary acknowledged runs leave no record.
+Host expiry is a backstop dependent on the worker and lock, not a strict deletion
+guarantee after transport failure. Existing nonzero payload status is preserved.
+This is not a registered runner, a scoped CI identity or VM-grade isolation.
+See [Disposable CI jobs](./guides/ci-jobs.mdx) for the full contract.
+
+## Structured output and completion
+
+`raft --json COMMAND ...` writes only JSON Lines events to stdout. Native
+structured reports use `{"type":"data","value":...}`. Other output uses
+`stdout` or `stderr` events with `encoding: "base64"` and a `data` field so
+arbitrary bytes survive unchanged. Stream chunk boundaries are not lines.
+Expected failures add an `error` event with `code` (`usage` or `operation`) and
+`message`. The final `exit` event contains `code`, matching the process status,
+including payload failures. Local subprocess signal termination becomes
+`128 + signal` in both the exit event and process status. Usage errors return 2;
+top-level operation errors return 1. `run` also emits operation errors for setup,
+artifact collection and cleanup failures, while retaining its existing payload,
+timeout and cleanup exit-status precedence.
+Help and version also end with an exit event. Release notices are disabled in
+JSON mode. `--json` belongs before the command; arguments after a payload's
+`--` belong to that payload. Existing command-local JSON flags keep their
+existing output when global JSON mode is absent.
+
+Interactive SSH and foreground tunnels/desktop reject JSON mode before any
+side effect because these commands require terminal or session ownership.
+Other commands retain their existing behavior. JSON events are flushed as
+output arrives; memory use does not grow with payload output.
+
+`raft completions bash|zsh|fish` prints a shell integration script without
+reading host configuration. It asks the installed parser for command, option
+and fixed-choice candidates when completing, so added commands and options
+need no second maintained catalog. It does not contact hosts or suggest
+workspace IDs or secret values.

package/docs/first-box.mdx

@@ -12,13 +12,13 @@ Launch and manage a workspace after provisioning your host and pinning the image
 Create a workspace with `raft new`:
 
 ```sh title="CONTROLLER: Create a new workspace"
-box=$(raft new --location lab --ttl 600)
+box=$(raft new --location lab --ttl 600 --persistent)
 echo "Created workspace: $box"
 ```
 
 The command returns a location-qualified handle formatted as `<location>:<instance-name>` (for example `lab:rf-a1b2c3d4e5f60718`).
 
-Omitting `--location` targets the first location in `~/.config/raft/incus.json`. The `--ttl` flag sets the lifetime in seconds (default: 600).
+Without a configured location default, omitting `--location` targets the first location in `~/.config/raft/incus.json`. The `--ttl` flag sets the lifetime in seconds (default: 600).
 
 ## Step 2: Verify command execution and Docker daemon
 
@@ -50,37 +50,40 @@ Type `exit` or press `Ctrl+D` to disconnect.
 Commands run as root in `/workspace` inside an unprivileged Linux user namespace. Container root maps to an unprivileged high UID on the host, sharing the host kernel.
 </Callout>
 
-## Step 4: Stop, resume, and destroy
+## Step 4: Stop and resume
 
 Manage the workspace lifecycle:
 
-```sh title="CONTROLLER: Stop, resume, and destroy workspace"
+```sh title="CONTROLLER: Stop and resume workspace"
 # Stop running processes while preserving files and snapshots
 raft stop "$box"
 
 # Resume the stopped workspace with a renewed lifetime
 raft resume "$box" --ttl 600
 
-# Permanently destroy the workspace and release host capacity
-raft destroy "$box"
 ```
 
 - **`raft stop`**: Stops running processes and frees active allocations while retaining files and snapshots.
 - **`raft resume`**: Starts a stopped container with a new expiration deadline (`now + TTL`). Does not restore process memory.
 - **`raft destroy`**: Permanently deletes the container, filesystem, and snapshots from the host storage pool.
 
+## Clean up when finished
+
+<Callout type="warn" title="Permanent deletion">
+Destroy only the tutorial box after copying out anything you need. This removes
+its files and snapshots; it is not the same as stopping it.
+</Callout>
+
+```sh
+raft destroy "$box"
+```
+
 ## Next steps
 
-- [Project setup and templates](./guides/project-setup.mdx): Prepare a project and reuse its dependencies.
-- [Lifetime and persistent services](./guides/long-running-services.mdx): Manage deadlines and restart applications after resume.
-- [Scripting and CI](./guides/scripting-ci.mdx): Parse CLI output and handle failures.
-- [Docker in workspaces](./guides/docker.mdx): Run nested containers and build images.
-- [File transfer](./guides/files.mdx): Upload and download files over SSH.
-- [Background jobs](./guides/background-jobs.mdx): Run detached commands under systemd.
-- [Desktop and private services](./guides/desktop-services.mdx): Forward guest ports and open noVNC desktop.
-- [Snapshots and forks](./guides/snapshots-forks.mdx): Capture disk states and create same-host clones.
-- [Backup and recovery](./guides/backup-recovery.mdx): Export portable archives and restore across hosts.
-- [Troubleshooting](./guides/troubleshooting.mdx): Diagnose common errors and inspect host services.
-- [Upgrades and image changes](./guides/upgrades.mdx): Update the controller, hosts, and image pins.
-
-For temporary work, create with `--disposable`. Stopping or expiry then deletes the box and its snapshots. For persistent boxes, `raft prune --older-than 7` previews old stopped workspaces; add `--yes` only after reviewing the candidates.
+- [Set up a project](./guides/project-setup.mdx).
+- [Choose another task guide](./guides/index.mdx).
+- [Troubleshoot a failed command](./guides/troubleshooting.mdx).
+
+This tutorial uses `--persistent` so a disposable controller default cannot delete
+the box on stop. A host retention policy can still delete it after it has been
+stopped long enough; inspect `raft config` before leaving valuable work there.