@microck/raft 0.3.0 → 0.5.0

package/skills/raft-cli/SKILL.md

@@ -11,15 +11,40 @@ The current deployment does not implement Incus VMs. Do not describe these boxes
 `raft host add` installs packages and services on a machine. Run it only when the
 user explicitly asks to onboard that host, and show its `--dry-run` plan first.
 
-Run `raft locations`, `raft doctor`, `raft limits` and `raft list` before allocating.
+Do not run `raft self-update` unless the user asks; an update in the middle of a
+task changes the CLI under it. Report a `raft X is available` stderr notice
+instead of acting on it. For pinned or scripted runs, set
+`RAFT_NO_UPDATE_CHECK=1` to suppress the notice.
+
+Run `raft locations`, `raft config`, `raft doctor` and `raft list` before allocating.
+`raft config` shows the defaults `new` will use on this controller and each
+location's note policy: the box note fields its host requires.
 Follow each location's `note`: the operator uses it to mark preferred hosts and
 hosts to avoid for some work. Pass `--location` explicitly when a note rules out
 the default. Do not change notes unless the user asks; `raft note LOCATION TEXT`
 sets one and `raft note LOCATION --clear` removes it. Keep the exact
 location-qualified handle returned by `new`. There is no implicit current box.
 
+Note every box you create. Box notes follow one template so the next agent can
+tell whether a box is in use:
+
+- `--purpose`: what the box is for (required), e.g. `Integration tests for PR 42`
+- `--owner`: who uses it, e.g. `codex session in ~/work/app`
+- `--next`: what happens next, e.g. `Destroy after the tests pass`
+
+Pass them to `new`, and run `raft note "$box" --purpose ...` when the plan
+changes; each call replaces the whole note. If a command fails with
+`requires --owner (host policy)` or similar, rerun it with the fields it names;
+the error prints the corrected command. Never change or clear a policy with
+`raft policy`, or the defaults with `raft config set/unset`, to get past an
+error; only do so when the user asks. `fork` and `recover` accept the same note
+flags, which replace the whole note on the copy. `raft list` shows every box's
+`note`. Read it before you resume, stop, fork or destroy a box. Treat a box whose
+note names another owner or a job unrelated to your task as not yours. Forks
+keep the source note, so update a fork's note when its job differs.
+
 ```sh
-box=$(raft new --location lab --ttl 600)
+box=$(raft new --location lab --ttl 600 --purpose "Run the project tests" --owner "codex task 123" --next "Destroy when the tests finish")
 raft exec "$box" -- timeout 240 bash -lc 'git clone <url> /workspace/project && cd /workspace/project && <test-command>'
 raft download "$box" /workspace/project/report.json ./report.json
 raft destroy "$box"
@@ -37,14 +62,45 @@ Exec passes literal arguments; use `bash -lc` for shell syntax. A failed command
 retains its exit status. `raft ssh "$box"` opens a root terminal through native
 Incus execution over verified host SSH. It does not expose a guest SSH port.
 
-Defaults are the first configured location, one CPU, 2 GiB RAM and 600 seconds. TTL accepts 60 seconds
-to 30 days. The controller admits at most four saved boxes per host; stopped
-boxes count because their disk still occupies space. Use `--memory 4GiB` or `--memory 8GiB`
-and `--cpu 2` when needed. Btrfs bounds workspace storage to a 60 GiB pool per host.
-It does not guarantee strict per-box disk quotas with nested subvolumes. Check host disk before large builds or forks. `raft limits --location lab --json`
-reports CPU/RAM recommendations for all supported sizes, active allocations and
-free saved slots. Recommendations reserve host resources and remain advisory;
-only the four-saved-box cap is enforced. Disk growth is not included in the counts.
+## Sizing boxes
+
+Create the boxes your task needs, sized for the work. Raft has no box count
+limit and no size budget. Decide what the task needs and why, then ask for it:
+
+- `--cpu N`: any whole number of CPUs up to the host's count (default 1). Use
+  more for parallel builds and test suites.
+- `--memory SIZE`: any whole GiB up to the host's RAM, e.g. `8GiB` or `32GiB`
+  (default `2GiB`). Use more for large compiles, browsers or databases.
+- `--disk SIZE`: its own disk, e.g. `30GiB`, instead of the shared 60 GiB pool.
+  The box and Docker inside it cannot write past SIZE, and other boxes cannot
+  take its space. Use it for Docker builds, large datasets or anything that
+  could fill the shared pool. The image needs about 5 GiB, so use at least
+  `8GiB`; 10 GiB or more starts fastest. Only hosts deployed with
+  `--disk-pool` have own disks; elsewhere `--disk` fails and names the command
+  that enables them. Own disks, their snapshots, forks and templates are
+  copy-on-write, so copying one is fast, but each reserves its full size in
+  the pool.
+
+```sh
+box=$(raft new --cpu 4 --memory 16GiB --disk 20GiB --ttl 3600 --purpose "Build and test the monorepo" --owner "codex task 123" --next "Destroy when CI passes")
+```
+
+Built-in defaults are the first configured location, one CPU, 2 GiB RAM, the
+shared pool and 600 seconds; the operator can change them per controller, so
+pass `--location`, `--ttl`, `--cpu`, `--memory` and `--disk` (`--disk shared`
+for the shared pool) when the values matter. `new --from` and `fork` keep the
+source's CPU, RAM and disk instead of any default; each flag overrides only its
+own value. TTL accepts 60 seconds to 30
+days. A request larger than the whole host fails with the host's real size;
+retry with what it reports. If the own-disk pool has too little unreserved
+space for `--disk`, a snapshot or a copy, destroy own-disk boxes or snapshots
+the task no longer needs, or pick a smaller disk or the shared pool.
+`raft list` shows each box's `disk` (`"shared"` or its size).
+
+`raft capacity --location lab --json` is an advisory estimate of host CPU/RAM
+headroom and free disk. It is advice, never a reason to skip creating a box or
+to shrink one below what the task needs. Boxes share host CPUs; an estimate of
+zero means new boxes may run slower, not that they are refused.
 
 ## Persistence and cleanup
 
@@ -78,6 +134,11 @@ only when the user requested that rollback. A fork copies filesystem data, inclu
 credentials installed there. Forks stay on the same host. `new --from "$box/prepared"` starts from a named
 snapshot; `snapshot-delete "$box" prepared` removes it. Resume and fork accept
 optional `--cpu` and `--memory` overrides. Omitted values retain the source limits.
+Forks and `new --from` keep the source's CPU, RAM and disk unless a flag
+overrides them; `new --from "$box/prepared" --disk 60GiB` copies the snapshot onto
+a bigger own disk when a box runs out of space. To spawn many agents from one
+prepared own-disk snapshot, run `new --from` once per agent: each copy is a thin
+snapshot created in seconds.
 Forks default to persistent; use `--disposable` explicitly for temporary clones.
 
 `upload/download --recursive` copy directory trees into new destinations without
@@ -92,7 +153,8 @@ status and output. `raft cancel "$box" <job>` stops the job and its child proces
 terminates running jobs; this is not automatic checkpointing of processes.
 `raft extend "$box" --ttl 1800` resets a running box's deadline without
 restarting its work. Use resume for stopped boxes. `raft usage "$box"` reports
-cgroup memory/CPU and shared-pool disk space, not a per-box disk quota.
+cgroup memory/CPU and disk space; `filesystemScope` says whether that is the
+shared pool or the box's own disk.
 
 `raft forward "$box" --remote 8080 --local 8080` opens a foreground private
 tunnel. `raft desktop "$box" --local 6080` starts the desktop on demand and
@@ -116,7 +178,9 @@ raft resume "$recovered" --ttl 600
 ```
 
 Recovery creates a fresh stopped handle and clears the inherited deadline. It
-never overwrites another box. Only import trusted Raft exports; archives retain
+never overwrites another box. A box with its own disk comes back on an own disk
+of the same size, so the destination needs own box disks enabled and room for the
+box and each of its snapshots. Only import trusted Raft exports; archives retain
 native configuration and guest secrets. Store them privately and check free
 space on the controller and destination host. Large backups hold the host
 lifecycle lock and delay expiry checks. A controller crash can leave an owned

package/docs/reference/capacity-limits.mdx

@@ -1,92 +0,0 @@
----
-title: Capacity limits and planning
-description: Host resource reserves, sizing profiles, advisory calculations, and admission limits.
----
-
-# Capacity limits and planning
-
-Raft provides capacity inspection and allocation policies designed to keep dedicated hosts stable while running concurrent workspaces.
-
-## Inspecting capacity with `raft limits`
-
-Run `raft limits` to view host resources and workspace allocation calculations:
-
-```sh title="CONTROLLER: View host capacity report"
-raft limits
-
-# Output JSON for programmatic inspection
-raft limits --location lab --json
-```
-
-The output displays host CPU count, total RAM, configured limits, available RAM, disk headroom, and advisory recommendations across all eight sizing profiles:
-
-### Illustrative host sizing
-
-Illustrative totals for 1 CPU / 2 GiB boxes on an empty host, using exact usable RAM values:
-
-| Host CPUs | Host RAM | Recommended running | Enforced saved maximum |
-| ---: | ---: | ---: | ---: |
-| 2 | 8 GiB | 1 | 4 |
-| 4 | 8 GiB | 3 | 4 |
-| 4 | 16 GiB | 3 | 4 |
-| 8 | 32 GiB | 4 | 4 |
-
-Operating systems report less usable RAM than advertised hardware size. Near sizing boundaries, `raft limits` may calculate fewer recommended boxes. Available RAM and host processes can further reduce running capacity. These values are point-in-time advisory estimates, not hardware reservations.
-
-### Column definitions and algorithms
-
-| Column | Calculation |
-| --- | --- |
-| Total running | `min(4, floor(CPU budget / box CPU), floor(Memory budget / box memory))` |
-| More running | Bounded by remaining CPU, memory, available RAM, and active slots |
-| New boxes | `min(more running, max(0, 4 - saved boxes))` |
-
-**Total running** assumes an empty host. **More running** accounts for current allocations, `MemAvailable - Memory reserve`, and `4 - active boxes`. Active limits are not subtracted twice.
-
-## Sizing profiles
-
-Select CPU and memory limits when launching with `raft new`:
-
-- `--cpu`: `1` or `2` shared vCPUs managed by Incus (default: `1`).
-- `--memory`: `1GiB`, `2GiB`, `4GiB`, or `8GiB` cgroup limit (default: `2GiB`). An 8 GiB box needs at least 10 GiB of usable host RAM before `raft limits` recommends running one; like other recommendations, this is advisory and not enforced.
-
-Change supported CPU/RAM limits when resuming a stopped box or creating a fork:
-
-```sh
-raft resume "$box" --ttl 1800 --cpu 2 --memory 4GiB
-copy=$(raft fork "$box" --ttl 1800 --memory 2GiB)
-```
-
-Resume requires a stopped box; fork requires a stopped source. Omitted limits
-stay unchanged on resume and inherit the source limits on fork. Live resizing is
-not exposed by the CLI. See [Snapshots and forks](../guides/snapshots-forks.mdx).
-
-## Host resource reserves and active states
-
-Raft calculates advisory host safety margins:
-- **CPU reserve**: 1 CPU core reserved for the host OS.
-- **Memory reserve**: The larger of `2 GiB` or `10%` of host RAM.
-
-These reserves are advisory estimates for planning, not hard cgroup locks.
-
-All non-`Stopped` states (such as `Running` or `Frozen`) count as active allocations. Stopped containers release CPU and RAM allocations while retaining their saved slot and disk storage.
-
-## Enforced admission limits
-
-<Callout type="warn" title="Hard limit: four saved boxes per location">
-Raft enforces a hard limit of four saved boxes per location. Both running and stopped containers occupy storage and count against this limit.
-</Callout>
-
-Exceeding four saved boxes fails with an admission error:
-```text
-Location already holds four boxes
-```
-
-Destroy unused containers with `raft destroy <box>` to free slots. Advisory CPU and memory calculations do not block container creation or resumption.
-
-## Storage capacity
-
-Every Raft host provisions a dedicated 60 GiB Btrfs pool (`raft-data`):
-- **Shared pool**: All containers, snapshots, and Docker layers share this 60 GiB pool.
-- **No strict per-box quotas**: Nested subvolumes prevent strict per-box quota enforcement.
-- **Disk warnings**: `raft limits` warns when free space on host disk or `raft-data` falls below 5 GiB. Warnings are diagnostic and do not block operations. `raft doctor` reports storage usage without emitting 5 GiB warnings.