@microck/raft 0.6.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
 
@@ -63,7 +69,7 @@ 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, 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`.
@@ -78,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.
@@ -97,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
@@ -106,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. A host can also delete boxes left stopped automatically; `raft config` shows each location's `deleteStoppedAfterHours`.
+- [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.

package/docs/guides/background-jobs.mdx

@@ -5,11 +5,11 @@ description: Run detached commands with systemd logging and process management.
 
 # Background jobs
 
-Raft runs detached background commands under the guest systemd init system using transient service units.
+Raft runs detached commands under guest systemd and captures their results with a transient host supervisor.
 
 ## Target workspace handle
 
-Commands in this guide target a running workspace. Select one from `raft list` (see [First working box](../first-box.mdx)):
+Launching a job requires a running workspace. Select one from `raft list` (see [First working box](../first-box.mdx)):
 
 ```sh title="CONTROLLER: Select running workspace"
 raft list
@@ -33,49 +33,56 @@ The command returns a 32-hex systemd unit name prefixed with `rfcmd-` (such as `
 
 ## Checking job status
 
-Use `raft status` to query guest systemd unit properties:
+`raft status "$box" "$job"` returns a retained JSON record:
 
-```sh title="CONTROLLER: Inspect background job state"
-raft status "$box" "$job"
+```json
+{"job":"rfcmd-...","box":"lab:rf-...","state":"completed","exitCode":23,"startedAt":1793280000,"finishedAt":1793280010,"droppedBytes":0}
 ```
 
-Active jobs report running substate:
-```text
-ActiveState=active
-SubState=running
-ExecMainStatus=0
-```
-
-Because Raft runs detached commands with `RemainAfterExit=yes`, completed jobs retain their exit record:
-```text
-ActiveState=active
-SubState=exited
-ExecMainStatus=0
-```
-
-<Callout type="info" title="Exit status vs CLI return code">
-`ExecMainStatus` reports the command payload exit code inside the container. The `raft status` command returns exit code 0 when the query succeeds. It queries unit state and does not report process PIDs or start timestamps.
-</Callout>
-
-## Viewing job logs
+States are `starting`, `running`, `completed`, `cancelled`, `interrupted` and
+`failed`. `completed` means the command finished, not that it succeeded; inspect
+`exitCode`. An interrupted job has no confirmed payload exit code. A transport interruption can leave the guest command running;
+inspect or cancel it before rerunning the payload. Timestamps
+are host Unix seconds. A successful status query itself returns zero.
 
-Retrieve output recorded in the guest systemd journal:
+## Viewing retained output
 
-```sh title="CONTROLLER: Retrieve job log output"
+```sh
 raft logs "$box" "$job"
 ```
 
-The command runs `journalctl --no-pager -o cat -u <job>` inside the container. It prints recorded logs without a pager or stream follow mode.
+A host supervisor retains the first 1 MiB of combined stdout and stderr. Further
+output is drained and counted in `droppedBytes` when the job ends. Logs and final
+status remain readable after the workspace stops or is deleted; keep its exact
+original handle. They are not copied by workspace snapshots or forks.
 
-## Cancelling jobs
+Results live in the root-private host directory `/var/lib/raft-jobs`. They expire
+seven days after completion. Job commands prune expired records on access, so an
+idle host may retain expired files until the next access. The store holds at most
+512 records and refuses new jobs when full instead of evicting unexpired results.
+Unreadable records remain on the host for inspection and count toward the limit.
+They do not block other jobs. A query for a damaged record reports its host path;
+inspect that directory and its retained output before deciding how to recover it.
+Output can contain secrets; this is host-local retention, not an off-host backup.
 
-Terminate a running detached command:
+## Cancelling jobs
 
-```sh title="CONTROLLER: Terminate background job"
+```sh
 raft cancel "$box" "$job"
 ```
 
-`raft cancel` executes `systemctl stop <job>`, terminating processes in the job's systemd control group.
+Cancellation stops the guest systemd control group. Retained output remains
+available. If a job is still starting and its guest unit is not yet registered,
+cancellation reports an error; inspect its state before retrying. Unknown job
+IDs and IDs belonging to another workspace are rejected. Cancellation waits up to
+120 seconds. If it times out, the cancellation request remains recorded; inspect
+the job and retry cancellation.
+
+Host reboot or guest shutdown interrupts active jobs. The next inspection marks
+an absent supervisor as interrupted rather than assuming success. Completed
+results survive host reboot. This development implementation has no fallback to
+old guest-only journals; inspect old jobs with their controller version before
+upgrading.
 
 ## Extending workspace lifetime