@microck/raft 0.5.0 → 0.6.0

package/docs/guides/config-policy.mdx

@@ -1,19 +1,20 @@
 ---
-title: Defaults and note policies
-description: Set controller defaults for new boxes and require box note fields on a host.
+title: Defaults and host policies
+description: Set controller defaults for new boxes, require box note fields on a host and delete boxes left stopped.
 ---
 
-# Defaults and note policies
+# Defaults and host policies
 
 Raft has two kinds of settings:
 
 | Setting | Stored in | Applies to | Change with |
 | --- | --- | --- | --- |
 | Defaults for `new` | `~/.config/raft/config.json` on the controller | That controller only | `raft config set` and `raft config unset` |
-| Required box note fields | Incus project `raft` on each host | Every controller that uses the host | `raft policy` |
+| Required box note fields | Incus project `raft` on each host | Every controller that uses the host | `raft policy --require` |
+| Stopped-box retention | Incus project `raft` on each host | Every box on the host | `raft policy --delete-stopped-after` |
 
-`raft config` prints both: the effective defaults with their source, and each
-location's policy.
+`raft config` prints both kinds: the effective defaults with their source, and
+each location's policies.
 
 ```sh title="CONTROLLER: Inspect defaults and policies"
 raft config
@@ -42,6 +43,10 @@ raft config
     "disk": {
       "value": "shared",
       "source": "built-in"
+    },
+    "disposable": {
+      "value": true,
+      "source": "config"
     }
   },
   "policy": {
@@ -50,7 +55,10 @@ raft config
         "purpose",
         "owner"
       ],
-      "changed": "2026-10-21T09:12:44Z by ubuntu from me@laptop"
+      "requireChanged": "2026-10-21T09:12:44Z by ubuntu from me@laptop",
+      "deleteStoppedAfterHours": 48,
+      "deleteStoppedAfterSince": 1792573964,
+      "deleteStoppedAfterChanged": "2026-10-21T09:12:44Z by ubuntu from me@laptop"
     }
   }
 }
@@ -61,33 +69,42 @@ names the location when a host is unreachable.
 
 ## Defaults for new
 
-Set a default for any of `location`, `ttl`, `cpu`, `memory` and `disk`:
+Set a default for any of `location`, `ttl`, `cpu`, `memory`, `disk` and
+`disposable`:
 
-```sh title="CONTROLLER: Prefer bigger, longer boxes on paris"
+```sh title="CONTROLLER: Prefer bigger, longer, temporary boxes on paris"
 raft config set location paris
 raft config set ttl 3600
 raft config set cpu 4
 raft config set memory 16GiB
 raft config set disk 20GiB
+raft config set disposable true
 raft config unset cpu
 ```
 
 Each command prints the old and new value. `raft new` takes an explicit flag
 first, then the configured default, then the built-in default (first configured
-location, 600 seconds, 1 CPU, 2 GiB, the shared pool). `resume`, `fork`,
-`extend` and `recover` take no defaults: their TTL and target are deliberate
-choices, and omitted sizes on resume and fork keep the source limits.
+location, 600 seconds, 1 CPU, 2 GiB, the shared pool, persistent). `resume`,
+`fork`, `extend` and `recover` take no defaults: their TTL and target are
+deliberate choices, and omitted sizes on resume and fork keep the source limits.
+
+With `disposable true`, every `raft new` box is deleted, with its snapshots, when
+it stops or expires. `raft new --persistent` keeps one box anyway, and
+`--disposable` overrides `disposable false` the same way. The default applies to
+`new --from` too: a snapshot has no lifecycle of its own. A fork stays
+persistent unless it gets `--disposable`, whatever the default says, like every
+other fork setting.
 
 Size defaults (`cpu`, `memory`, `disk`) apply only where the built-in sizes do:
 to boxes created from the image. A box from `new --from` keeps the snapshot's
 location, CPU, RAM and disk, and a fork keeps its source's, whatever
 `config.json` says. Only a flag changes them:
 
-| Command | CPU and RAM | Disk |
-| --- | --- | --- |
-| `new` | Flag, then config, then 1 CPU / 2 GiB | Flag, then config, then the shared pool |
-| `new --from` | Flag, then the snapshot's | `--disk SIZE`, then the snapshot's |
-| `fork` | Flag, then the source's | The source's |
+| Command | CPU and RAM | Disk | Disposable |
+| --- | --- | --- | --- |
+| `new` | Flag, then config, then 1 CPU / 2 GiB | Flag, then config, then the shared pool | Flag, then config, then persistent |
+| `new --from` | Flag, then the snapshot's | `--disk SIZE`, then the snapshot's | Flag, then config, then persistent |
+| `fork` | Flag, then the source's | The source's | `--disposable`, else persistent |
 
 A `disk` default needs own box disks on the target host. On a location without
 the `raft-disks` pool, or with too little unreserved space, `raft new` fails with
@@ -107,9 +124,9 @@ path and the key; Raft never ignores part of the file. Repair a bad key with
 `raft config set KEY VALUE` or `raft config unset KEY`. Writes are atomic, keep
 mode `0600` and remove the file when no default remains.
 
-Scripts and CI jobs that need stable sizing should pass `--location`, `--ttl`,
-`--cpu`, `--memory` and `--disk` explicitly, because defaults differ between
-controllers.
+Scripts and CI jobs that need stable boxes should pass `--location`, `--ttl`,
+`--cpu`, `--memory`, `--disk` and `--disposable` or `--persistent` explicitly,
+because defaults differ between controllers.
 
 ## Required box note fields
 
@@ -118,7 +135,7 @@ fields. `purpose` is always part of a note, so a policy must include it:
 
 ```sh title="CONTROLLER: Require an owner on lab"
 raft policy lab --require purpose,owner
-raft policy lab --clear
+raft policy lab --require none
 ```
 
 With that policy, a command that would leave a box without an owner fails before
@@ -151,29 +168,86 @@ so a policy change cannot race a creation. That transaction checks the
 requested size against the host and reserves own-disk space first; any refusal
 comes before Incus creates the box.
 
+## Delete boxes left stopped
+
+A retention policy makes a host delete boxes that stay stopped too long, with
+their snapshots. Use it when agents create boxes and forget them:
+
+```sh title="CONTROLLER: Delete boxes stopped for 48 hours on lab"
+raft policy lab --delete-stopped-after 48
+raft policy lab --delete-stopped-after never
+```
+
+The host expiry worker applies it every 15 seconds, and on `raft gc`, even when
+no controller is online. It deletes a stopped box once the given hours have
+passed since the later of:
+
+- the box's stop, recorded in `user.raft.stopped-at` by `raft stop` and expiry;
+- the policy change, recorded in `user.raft.delete-stopped-after.since`.
+
+So a new or shorter policy never deletes a box sooner than its hours after the
+change, including boxes that were stopped long before. Lengthening it or setting
+it again restarts the grace period the same way.
+
+| Box | What retention does |
+| --- | --- |
+| Running, including one whose TTL has not expired | Nothing |
+| Stopped with `raft stop` or expiry | Deleted HOURS after the later of the stop and the policy change |
+| Stopped another way: a poweroff inside the box, a native `incus stop`, a failed start or `raft recover` | The worker records the time it first sees the box stopped, and the clock starts then |
+| Resumed before its deadline | Nothing; `resume` clears the stop time, and the next stop starts a new clock |
+
+`raft list` shows when each stopped box will go, as `deleteAt`:
+
+```sh title="CONTROLLER: Stopped boxes and their deletion times"
+raft list --location lab | jq -r 'select(.deleteAt != "") | "\(.box) \(.deleteAt | tonumber | todate)"'
+```
+
+Retention deletes the whole box. Keep anything you need with
+[`raft backup`](./backup-recovery.mdx) before the deadline, or resume the box to
+reset its clock. Snapshots live inside the box and are deleted with it.
+
+Retention needs the current host worker. On a host deployed by an older release,
+`--delete-stopped-after HOURS` fails with
+`Host expiry worker differs from this CLI; deploy the current Raft checkout first`
+and changes nothing; redeploy the host, see
+[Upgrades and image changes](./upgrades.mdx). Clearing it with `never` works on
+any worker.
+
+`raft prune --older-than DAYS` remains a manual, previewed cleanup that works
+with or without a retention policy.
+
 ## Audit trail
 
-`raft policy` prints the change, for example
-`lab: required note fields none -> purpose,owner`. The host records the last
-change in the project key `user.raft.require.changed` (UTC time, the SSH account
-and the controller's self-reported user and hostname) and writes a `raft` entry
-to the host journal:
+`raft policy` prints each change, for example
+`lab: required note fields none -> purpose,owner` or
+`lab: delete stopped boxes after never -> 48 hours`. The host records the last
+change of each policy in a `.changed` project key (UTC time, the SSH account and
+the controller's self-reported user and hostname) and writes a `raft` entry to
+the host journal. The worker adds a journal entry for every box retention
+deletes:
 
-```sh title="HOST: Review policy changes"
+```sh title="HOST: Review policy changes and retention deletions"
 sudo incus project get raft user.raft.require
 sudo incus project get raft user.raft.require.changed
+sudo incus project get raft user.raft.delete-stopped-after
+sudo incus project get raft user.raft.delete-stopped-after.changed
 sudo journalctl -t raft
 ```
 
 ## Limits
 
-Note policies are a guardrail for agents, not a security boundary:
-
-- Anyone with SSH and sudo on the host can change or remove the policy, or create
-  boxes with native `incus` commands that skip it.
-- Controllers older than the release that added policies do not check them.
-  Upgrade every controller that uses a host before relying on its policy.
-- The controller identity in `user.raft.require.changed` is reported by the
-  controller and is not verified. The SSH account comes from `sudo`.
+Host policies are a guardrail for agents, not a security boundary:
+
+- Anyone with SSH and sudo on the host can change or remove a policy, or create
+  boxes with native `incus` commands that skip the note policy.
+- Retention trusts `user.raft.stopped-at`. The worker clears it when it sees a
+  box running, but a native `incus start` and stop between two worker runs (15
+  seconds apart) keeps the old stop time, so the box can be deleted on the next
+  run. Use `raft resume`, which clears the stop time.
+- Controllers older than the release that added note policies do not check
+  them. Upgrade every controller that uses a host before relying on one. The
+  host worker enforces retention whatever the controller version.
+- The controller identity in the `.changed` keys is reported by the controller
+  and is not verified. The SSH account comes from `sudo`.
 - Raft checks that required fields are present and nonempty, not that their text
   is accurate.

package/docs/guides/long-running-services.mdx

@@ -24,13 +24,19 @@ Raft has no option to disable automatic expiry.
 | `resume --ttl SECONDS` | Starts the saved box with a new deadline | Only possible while the box still exists |
 | `destroy` | Deletes the box and snapshots | Deletes the box and snapshots |
 
-Use `raft new --disposable` for temporary work. A fork is persistent unless
+Use `raft new --disposable` for temporary work, or
+`raft config set disposable true` to make it the default on this controller;
+`raft new --persistent` then keeps one box. A fork is persistent unless
 `--disposable` is explicitly supplied; recovered boxes are persistent.
 Back up work before stopping a disposable box.
 
 Persistent stopped boxes still occupy storage. Raft does not cap how many boxes
 a host keeps. `raft prune --older-than 7` previews old stopped boxes;
-`--yes` applies deletion. There is no automatic persistent-box retention cleanup.
+`--yes` applies deletion. To delete them automatically, set a host retention
+policy: with `raft policy lab --delete-stopped-after 48`, the host deletes any
+box left stopped for 48 hours, and `raft list` shows each one's `deleteAt`.
+Resuming a box resets its clock. See
+[Defaults and host policies](./config-policy.mdx#delete-boxes-left-stopped).
 
 ## Read and reset the deadline
 

package/docs/guides/scripting-ci.mdx

@@ -19,7 +19,7 @@ Raft does not have a global `--json` option. Parse each command's actual format:
 | --- | --- |
 | `new`, `fork`, `recover` | One location-qualified handle |
 | `exec --detach` | One `rfcmd-` job ID |
-| `list` | JSONL: one object per box, with `box`, `state`, `stopAt`, `disk`, `note` |
+| `list` | JSONL: one object per box, with `box`, `state`, `stopAt`, `deleteAt`, `disk`, `note` |
 | `info` | One pretty-printed native Incus metadata JSON object |
 | `usage` | One JSON object containing running resource counters |
 | `capacity --json` | One JSON object per location (JSONL across multiple hosts) |
@@ -33,7 +33,9 @@ Raft does not have a global `--json` option. Parse each command's actual format:
 | Other inspection/maintenance commands | Human-readable text or no output |
 
 `list` emits nothing when there are no boxes. `stopAt` is the host Unix deadline
-as a string, or an empty string when absent. `disk` is `"shared"` or the box's
+as a string, or an empty string when absent. `deleteAt` is the Unix time the
+location's retention policy deletes a stopped box, in the same form, or an empty
+string. `disk` is `"shared"` or the box's
 own disk size, such as `"20GiB"`. `note` is the box note object with
 `purpose` and optional `owner` and `next`, or `null`. `info` uses native Incus keys rather
 than a normalized Raft schema. `usage` includes `memoryBytes`, `memoryLimit`,
@@ -52,10 +54,11 @@ raft prune --location lab --older-than 7 | jq -r '.box'
 
 `raft new` fills omitted options from the controller's
 `~/.config/raft/config.json`, so the same script can create different boxes on
-different controllers. Pass `--location`, `--ttl`, `--cpu`, `--memory` and
-`--disk` in CI.
+different controllers. Pass `--location`, `--ttl`, `--cpu`, `--memory`,
+`--disk` and `--disposable` or `--persistent` in CI.
 Hosts can also require box note fields; give `--purpose`, `--owner` and `--next`
-so a policy cannot fail the job. See [Defaults and note policies](./config-policy.mdx).
+so a policy cannot fail the job. A host retention policy can delete a box left
+stopped between jobs; see [Defaults and host policies](./config-policy.mdx).
 
 Do not redirect `2>&1` into machine-readable output. Recovery reports its allocated
 handle on stderr before import finishes; only a successful completion prints the

package/docs/guides/snapshots-forks.mdx

@@ -110,4 +110,4 @@ copy=$(raft fork "$box" --ttl 600 --cpu 2 --memory 4GiB)
 raft resume "$box" --ttl 600 --memory 2GiB
 ```
 
-Omitted CPU and RAM values keep the source limits; the disk never changes on fork or resume. Forks are persistent by default; add `--disposable` to delete a clone when it stops or expires.
+Omitted CPU and RAM values keep the source limits; the disk never changes on fork or resume. Forks are persistent by default, even when `raft config` sets `disposable true`; add `--disposable` to delete a clone when it stops or expires.

package/docs/guides/troubleshooting.mdx

@@ -33,8 +33,8 @@ raft doctor
 
 An active expiration timer can still run an older worker. Installing or updating
 the controller CLI does not deploy host code. `doctor` checks the same worker
-protocol as disposable creation and retention cleanup, without running expiry or
-changing any boxes. It exits nonzero and names the location on a mismatch.
+protocol as disposable creation, prune and setting a retention policy, without
+running expiry or changing any boxes. It exits nonzero and names the location on a mismatch.
 
 Review the host deployment changes, then deploy from the checkout matching your
 CLI. Replace `lab` with the location reported by the diagnostic:
@@ -106,6 +106,23 @@ files and snapshots. Expired disposable containers are deleted, including their
 snapshots. Use `raft gc --location lab` to check only one host. The timer normally
 checks every 15 seconds; host outages, graceful shutdown and long locked
 operations can delay expiry. See [Lifetime and persistent services](./long-running-services.mdx).
+`raft gc` also applies the location's stopped-box retention.
+
+### A stopped box disappeared
+
+A host retention policy deletes boxes left stopped for its hours. Check the
+policy and the host journal, which records every deletion:
+
+```sh title="CONTROLLER: Check retention"
+raft config | jq '.policy'
+```
+
+```sh title="HOST: Find the deletion"
+sudo journalctl -t raft | grep 'Deleted box'
+```
+
+Deleted boxes cannot be recovered except from a `raft backup` archive. See
+[Defaults and host policies](./config-policy.mdx#delete-boxes-left-stopped).
 
 ## Common error scenarios
 

package/docs/guides/upgrades.mdx

@@ -84,8 +84,10 @@ timer. It does not import an image or migrate guest files.
 
 Do not bypass a conflicting-resource or storage-size error. Inspect the host and
 preserve backups before explicit recovery; redeployment does not repair arbitrary
-infrastructure drift. Disposable creation/fork and prune check the worker protocol
-and fail if it differs from the CLI. That check is not an automatic upgrade.
+infrastructure drift. Disposable creation/fork, prune and setting a retention
+policy check the worker protocol and fail if it differs from the CLI. That check
+is not an automatic upgrade. Raft 0.6.0 raised the protocol for stopped-box
+retention, so hosts deployed by an earlier release need this redeploy.
 
 ## Replace the image pin
 

package/docs/index.mdx

@@ -33,7 +33,7 @@ Stopping a workspace preserves files and packages on disk. Resuming resets its r
 | Run detached commands with systemd logs | [Background jobs](./guides/background-jobs.mdx) |
 | Manage deadlines and restart services after resume | [Lifetime and persistent services](./guides/long-running-services.mdx) |
 | Automate the CLI and parse its output | [Scripting and CI](./guides/scripting-ci.mdx) |
-| Set defaults for new boxes or require box note fields | [Defaults and note policies](./guides/config-policy.mdx) |
+| Set defaults for new boxes, require box note fields or delete boxes left stopped | [Defaults and host policies](./guides/config-policy.mdx) |
 | Forward guest ports or open noVNC desktop | [Desktop and private services](./guides/desktop-services.mdx) |
 | Capture disk state or clone workspaces | [Snapshots and forks](./guides/snapshots-forks.mdx) |
 | Export portable backups across hosts | [Backup and recovery](./guides/backup-recovery.mdx) |

package/docs/operations.mdx

@@ -15,7 +15,7 @@ Install the CLI from npm on your Linux controller, confirm key-based SSH to the
 host, then let `raft host add` do the remaining steps:
 
 ```sh title="CONTROLLER: Onboard a host"
-npm install -g @microck/raft@0.5.0
+npm install -g @microck/raft@0.6.0
 ssh ubuntu@192.0.2.10 true
 raft host add lab --ssh ubuntu@192.0.2.10 --dry-run
 raft host add lab --ssh ubuntu@192.0.2.10
@@ -62,7 +62,7 @@ sudo -n true && echo "Passwordless sudo is functional"
 On your Linux controller with Python 3.11.8+, install the published CLI:
 
 ```sh title="CONTROLLER: Install published CLI"
-npm install -g @microck/raft@0.5.0
+npm install -g @microck/raft@0.6.0
 raft --version
 ```
 
@@ -70,7 +70,7 @@ Installation does not configure hosts or download images. Clone the matching
 release to obtain the deployment scripts and example configuration:
 
 ```sh title="CONTROLLER: Obtain deployment scripts"
-git clone --branch v0.5.0 https://github.com/Microck/raft.git raft
+git clone --branch v0.6.0 https://github.com/Microck/raft.git raft
 cd raft
 ```
 
@@ -161,16 +161,16 @@ Workspaces require an unprivileged Debian 13 development image matching the host
 
 <Tab value="Download release image">
 
-Download the release archive, checksum, and manifest from [Raft releases](https://github.com/Microck/raft/releases). These examples pin `v0.5.0`, matching the CLI and deployment checkout above. The `sha256sum` check gates import so corrupted archives are rejected:
+Download the release archive, checksum, and manifest from [Raft releases](https://github.com/Microck/raft/releases). These examples pin `v0.6.0`, matching the CLI and deployment checkout above. The `sha256sum` check gates import so corrupted archives are rejected:
 
 <Tabs items={["ARM64", "AMD64"]}>
 
 <Tab value="ARM64">
 
 ```sh title="HOST (ARM64): Download, verify, and import release image"
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/raft-dev-arm64.tar.gz
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/SHA256SUMS
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/manifest-arm64.json
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/raft-dev-arm64.tar.gz
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/SHA256SUMS
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/manifest-arm64.json
 
 sha256sum --ignore-missing -c SHA256SUMS && \
   sudo incus --project raft image import ./raft-dev-arm64.tar.gz --alias raft-dev
@@ -181,9 +181,9 @@ sha256sum --ignore-missing -c SHA256SUMS && \
 <Tab value="AMD64">
 
 ```sh title="HOST (AMD64): Download, verify, and import release image"
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/raft-dev-amd64.tar.gz
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/SHA256SUMS
-curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.5.0/manifest-amd64.json
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/raft-dev-amd64.tar.gz
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/SHA256SUMS
+curl -fsSL -O https://github.com/Microck/raft/releases/download/v0.6.0/manifest-amd64.json
 
 sha256sum --ignore-missing -c SHA256SUMS && \
   sudo incus --project raft image import ./raft-dev-amd64.tar.gz --alias raft-dev

package/docs/reference/cli.md

@@ -16,7 +16,7 @@ Output is command-specific; see [Scripting and CI](../guides/scripting-ci.mdx).
 
 At most once a day, after a command finishes, Raft checks GitHub for a newer
 release and prints one line on stderr, such as
-`raft 0.6.0 is available (you have 0.5.0). Run: raft self-update`. It never
+`raft 0.7.0 is available (you have 0.6.0). Run: raft self-update`. It never
 installs anything or changes stdout, and network failures stay silent. See
 [`self-update`](#self-update) to turn it off.
 
@@ -44,7 +44,7 @@ Workspaces are referenced by location-qualified handles formatted as `<location>
 
 Create and launch a new workspace container.
 
-`raft new [--location LOCATION] [--ttl TTL] [--cpu N] [--memory SIZE] [--disk SIZE] [--disposable] [--from LOCATION:BOX/SNAPSHOT] [--purpose TEXT [--owner TEXT] [--next TEXT]]`
+`raft new [--location LOCATION] [--ttl TTL] [--cpu N] [--memory SIZE] [--disk SIZE] [--disposable | --persistent] [--from LOCATION:BOX/SNAPSHOT] [--purpose TEXT [--owner TEXT] [--next TEXT]]`
 
 - `--location LOCATION`: Target host location in `~/.config/raft/incus.json`. Built-in default: first configured location.
 - `--ttl TTL`: Lifetime in seconds before automatic stop (`60` to `2592000`). Built-in default: `600`.
@@ -57,7 +57,8 @@ then the built-in default. With `--from`, configured `cpu`, `memory` and `disk`
 defaults do not apply: the box keeps the snapshot's size unless a flag overrides
 it, and `--disk shared` is refused.
 
-- `--disposable`: Delete the box and snapshots on stop or expiry. Off by default.
+- `--disposable`: Delete the box and snapshots on stop or expiry. Built-in default: persistent.
+- `--persistent`: Keep the box and its disk on stop or expiry, overriding a configured `disposable` default. Cannot be combined with `--disposable`.
 - `--from LOCATION:BOX/SNAPSHOT`: Copy a named snapshot on its source host instead of the configured image. The box keeps the snapshot's CPU, RAM and disk unless `--cpu`, `--memory` or `--disk` overrides them; the source can be running. Cannot target a different location.
 - `--purpose TEXT`, `--owner TEXT`, `--next TEXT`: Record a [box note](#note). `--owner` and `--next` need `--purpose`. Without them the box starts with no note, including boxes created `--from` a noted snapshot. A host [policy](#policy) can require fields.
 
@@ -222,7 +223,7 @@ Clone a stopped workspace into an independent container on the same host and sta
 - `--ttl TTL`: Lifetime in seconds for the clone. Required.
 - `--purpose TEXT`, `--owner TEXT`, `--next TEXT`: Replace the clone's whole note. Without them the clone keeps the source note.
 
-Omitted CPU/RAM values inherit the source limits; controller defaults never apply to forks. The clone keeps the source's disk: the shared pool, or an own disk of the same size as a thin snapshot, which reserves that size in `raft-disks`. To copy a box onto a disk of another size, snapshot it and use `new --from BOX/SNAPSHOT --disk SIZE`. The clone is persistent unless `--disposable` is supplied, regardless of the source policy.
+Omitted CPU/RAM values inherit the source limits; controller defaults never apply to forks. The clone keeps the source's disk: the shared pool, or an own disk of the same size as a thin snapshot, which reserves that size in `raft-disks`. To copy a box onto a disk of another size, snapshot it and use `new --from BOX/SNAPSHOT --disk SIZE`. The clone is persistent unless `--disposable` is supplied, regardless of the source and of a configured `disposable` default.
 The note the clone ends up with must satisfy the host [policy](#policy).
 
 Returns the qualified handle of the clone.
@@ -357,8 +358,12 @@ Show or change the controller defaults for `new`.
 `raft config set KEY VALUE`
 `raft config unset KEY`
 
-- `KEY`: One of `location`, `ttl`, `cpu`, `memory`, `disk`.
-- `VALUE`: Accepted exactly when the same text is accepted by the matching `new` flag. A `location` must be configured.
+- `KEY`: One of `location`, `ttl`, `cpu`, `memory`, `disk`, `disposable`.
+- `VALUE`: Accepted exactly when the same text is accepted by the matching `new` flag. A `location` must be configured. `disposable` takes `true` or `false`.
+
+`disposable true` makes `new` create disposable boxes, including `new --from`,
+because a snapshot carries no lifecycle; `--persistent` keeps one box. `fork`
+ignores it: a fork is persistent unless it gets `--disposable`.
 
 `cpu`, `memory` and `disk` size only boxes created from the image. `new --from`
 and `fork` keep the source's CPU, RAM and disk; only explicit flags change them.
@@ -373,29 +378,48 @@ file makes `new` fail with the file path and key; `set` or `unset` that key to
 repair it.
 
 `raft config` prints one JSON object: `file`, `defaults` (each key's `value` and
-`source`, `config` or `built-in`) and `policy` (each location's `require` list
-and `changed` record). It contacts every configured host to read policies.
-See [Defaults and note policies](../guides/config-policy.mdx).
+`source`, `config` or `built-in`) and `policy`. For each location, `policy` has
+`require` (the required note fields), `deleteStoppedAfterHours` (`null` without
+retention), `deleteStoppedAfterSince` (when retention was set, Unix seconds) and
+the last change records `requireChanged` and `deleteStoppedAfterChanged`. It
+contacts every configured host to read policies.
+See [Defaults and host policies](../guides/config-policy.mdx).
 
 ### `policy`
 
-Set or clear the box note fields a location's host requires.
+Set or clear a location's host policies: the box note fields it requires and
+how long it keeps stopped boxes.
+
+`raft policy LOCATION [--require FIELDS|none] [--delete-stopped-after HOURS|never]`
 
-`raft policy LOCATION --require FIELDS`
-`raft policy LOCATION --clear`
+- `--require FIELDS`: Comma-separated fields from `purpose`, `owner`, `next`. Must include `purpose`. `--require none` stops requiring fields.
+- `--delete-stopped-after HOURS`: Delete boxes that stay stopped for HOURS, a positive whole number, with their snapshots. `--delete-stopped-after never` keeps stopped boxes.
 
-- `--require FIELDS`: Comma-separated fields from `purpose`, `owner`, `next`. Must include `purpose`.
-- `--clear`: Stop requiring fields.
+Give either option or both; each changes only its own policy. Both values are
+checked before the host changes.
 
-The policy is stored on the host in the Incus project key `user.raft.require`,
-so it applies to every controller. `new`, `fork`, `recover` and `note` check it
-on the controller for an actionable error, then again in the host transaction
-that writes the note. The command prints the change and the host records the
-time, SSH account and controller in `user.raft.require.changed` and the host
+Policies are stored on the host in the Incus project `raft`, so they apply to
+every controller. The command prints each change and the host records the time,
+SSH account and controller in a `.changed` key beside the policy and in the host
 journal (`journalctl -t raft`).
 
-This is a guardrail for agents, not a security boundary: SSH and sudo on the
-host can change the policy or bypass it, and older controllers do not check it.
+The note policy lives in `user.raft.require`. `new`, `fork`, `recover` and
+`note` check it on the controller for an actionable error, then again in the
+host transaction that writes the note.
+
+Retention lives in `user.raft.delete-stopped-after`, with the time it was set in
+`user.raft.delete-stopped-after.since`. The host expiry worker deletes a stopped
+box once HOURS have passed since the later of its stop and that time, so a new
+or shorter policy never deletes a box sooner than HOURS after the change. The
+worker runs every 15 seconds and on [`gc`](#gc), logs each deletion to the host
+journal and never touches running boxes. A stopped box with no recorded stop
+time, such as one powered off from inside, stopped with native `incus` or
+recovered from a backup, starts its clock when the worker first sees it.
+[`list`](#list) shows each box's `deleteAt`. Setting retention needs the current
+host worker; on an older one it fails with redeploy guidance.
+
+Policies are guardrails for agents, not a security boundary: SSH and sudo on the
+host can change or bypass them, and older controllers do not check note policies.
 
 ## Host inspection and maintenance commands
 
@@ -424,7 +448,9 @@ List existing workspace containers across configured hosts.
 
 `raft list [--location LOCATION]`
 
-Prints one JSON object per box (JSONL), with `box`, `state`, `stopAt`, `disk` and `note` fields.
+Prints one JSON object per box (JSONL), with `box`, `state`, `stopAt`, `deleteAt`, `disk` and `note` fields.
+`deleteAt` is the Unix time when the location's [retention](#policy) deletes a
+stopped box, as a string like `stopAt`, or `""` when no deletion is due.
 `disk` is `"shared"` for the shared pool or the own disk's size, such as `"20GiB"`.
 `note` is the box note object, or `null` when the box has none.
 An empty inventory prints no records. See [Scripting and CI](../guides/scripting-ci.mdx)
@@ -432,7 +458,7 @@ for output formats, exit codes, readiness, and failure handling.
 
 ### `gc`
 
-Enforce deadlines immediately. Persistent boxes stop; disposable boxes are deleted.
+Enforce deadlines and retention immediately. Persistent boxes stop; disposable boxes are deleted; stopped boxes past the location's [retention](#policy) are deleted.
 
 `raft gc [--location LOCATION]`
 
@@ -442,9 +468,9 @@ Preview deletion of persistent stopped boxes older than the selected number of d
 
 `raft prune --older-than DAYS [--location LOCATION] [--yes]`
 
-Days must be at least one. Without `--yes`, this only prints JSONL candidates. With `--yes`, it deletes matching boxes and their snapshots under the host lock. Running boxes and boxes without a recorded stop time are excluded. Stop timestamps come from Raft stop/expiry, not box creation. No automatic retention policy is enabled.
+Days must be at least one. Without `--yes`, this only prints JSONL candidates. With `--yes`, it deletes matching boxes and their snapshots under the host lock. Running boxes and boxes without a recorded stop time are excluded. Stop timestamps come from Raft stop/expiry, or from the host worker when it first sees a box stopped another way, never from box creation. For automatic deletion, set a [retention policy](#policy).
 
-Disposable creation/fork and prune require the current expiry worker installed through the deployer. A mismatch fails with deployment guidance; the CLI does not install or adapt an older worker.
+Disposable creation/fork, prune and setting retention require the current expiry worker installed through the deployer. A mismatch fails with deployment guidance; the CLI does not install or adapt an older worker.
 
 ## CLI maintenance commands
 

package/docs/reference/configuration.mdx

@@ -80,7 +80,8 @@ controller and is separate from the location inventory:
     "ttl": 3600,
     "cpu": 2,
     "memory": "4GiB",
-    "disk": "20GiB"
+    "disk": "20GiB",
+    "disposable": true
   }
 }
 ```
@@ -92,15 +93,18 @@ controller and is separate from the location inventory:
 | `cpu` | A positive whole number | `1` |
 | `memory` | Whole GiB, e.g. `16GiB` | `2GiB` |
 | `disk` | Whole GiB for an own box disk, or `shared` | `shared` |
+| `disposable` | `true` or `false` | `false` (persistent) |
 
-Explicit flags win over these values. `cpu`, `memory` and `disk` size only boxes
-created from the image: `new --from` and `fork` keep the source's size unless a
-flag overrides it. A `disk` default needs the `raft-disks` pool on the target
+Explicit flags win over these values; `--persistent` overrides `disposable`.
+`cpu`, `memory` and `disk` size only boxes created from the image: `new --from`
+and `fork` keep the source's size unless a flag overrides it. `disposable`
+applies to `new` and `new --from`, never to `fork`. A `disk` default needs the `raft-disks` pool on the target
 host, like `--disk`. Unknown keys and invalid values make
 `raft new` fail with the file path and key. Edit the file with
 `raft config set KEY VALUE` and `raft config unset KEY`, and inspect it with
-`raft config`. Required box note fields are a host policy, not part of this
-file; see [Defaults and note policies](../guides/config-policy.mdx).
+`raft config`. Required box note fields and stopped-box retention are host
+policies, not part of this file; see
+[Defaults and host policies](../guides/config-policy.mdx).
 
 ## SSH configuration and connection behavior
 

package/docs/releases/0.6.0.md

@@ -0,0 +1,16 @@
+---
+title: Raft 0.6.0
+---
+
+# Raft 0.6.0
+
+- **Disposable by default.** `raft config set disposable true` makes `raft new` create disposable boxes, which are deleted with their snapshots when they stop or expire. `raft new --persistent` keeps one box anyway, and `--disposable` still works the other way. The default also applies to `new --from`; a fork stays persistent unless you pass `--disposable`. `raft config` shows the setting.
+- **Delete boxes left stopped.** `raft policy LOCATION --delete-stopped-after 48` makes a host delete boxes, with their snapshots, once they have been stopped for 48 hours. The host applies it every 15 seconds and on `raft gc`, even with no controller online, logs each deletion to its journal (`journalctl -t raft`) and never touches running boxes. A new or shorter policy never deletes a box sooner than its hours after the change, and resuming a box resets its clock. `raft list` shows each stopped box's `deleteAt`. `--delete-stopped-after never` turns it off.
+- **Stop times for every stopped box.** The host now records a stop time for boxes stopped outside `raft stop`, such as a poweroff inside the box, a native `incus stop` or a recovered backup, when it first sees them. `raft prune` can therefore select them later; before, it skipped them forever.
+- **`raft policy` changes.** `--require` and `--delete-stopped-after` can be set together or alone, and each changes only its own policy. `--require none` replaces `--clear`, which is gone. In `raft config`, each location's `changed` field is now `requireChanged`, beside the new `deleteStoppedAfterHours`, `deleteStoppedAfterSince` and `deleteStoppedAfterChanged`.
+
+Install on Linux with Python 3.11.8+ using `npm install -g @microck/raft@0.6.0`, or install the attached Python wheel; existing installs can run `raft self-update`.
+
+Redeploy each host with this release's `deploy/deploy.py`. The host expiry worker changed, and until a host is redeployed `raft doctor` reports it, while `new --disposable` (including a disposable default), `fork --disposable`, `raft prune` and `raft policy --delete-stopped-after HOURS` fail on it with redeploy guidance. Redeploying changes nothing else on the host and sets no retention policy.
+
+ARM64 and AMD64 development images accompany this release. Verify `SHA256SUMS` before importing an image for your host architecture.

package/docs/verification.mdx

@@ -58,7 +58,7 @@ The [final runtime validation](https://github.com/Microck/raft/actions/runs/3754
 
 ## New workspace controls
 
-`python3 deploy/verify-features.py --location lab` verifies `doctor` readiness against the installed worker, recursive trees and unsafe-archive rejection, templates from a running source, snapshot deletion, CPU/RAM overrides, disposable timer deletion, retention preview/apply, and host note policies for `new`, `fork`, `note` and `recover` (it sets a policy on the host and clears it at the end). It uses only its own fixtures. Run the archive, controller-default and policy-message checks without `--location` to avoid allocating boxes.
+`python3 deploy/verify-features.py --location lab` verifies `doctor` readiness against the installed worker, recursive trees and unsafe-archive rejection, templates from a running source, snapshot deletion, CPU/RAM overrides, disposable timer deletion, prune preview/apply, host note policies for `new`, `fork`, `note` and `recover`, and stopped-box retention: it sets a 1-hour policy, backdates one stopped box and the policy start, and checks that the next timer run deletes only that box, records the stop time of a box stopped natively and logs to the journal. It sets policies on the host and clears them at the end, and uses only its own fixtures. Every live suite runs the CLI in a private `HOME` holding only `incus.json`, so controller defaults such as `disposable true` never change their boxes. Run the archive, controller-default, policy-message and host worker retention checks without `--location` to avoid allocating boxes; the worker check runs the real worker against a fake `incus` on `PATH`.
 
 The live suite also holds a controller stdin pipe open while running real remote
 readers through both captured and streamed lifecycle transactions. Both must