@microck/raft 0.3.0 → 0.5.0

package/raft.py

@@ -3,6 +3,8 @@
 
 import argparse
 import fcntl
+import getpass
+import hashlib
 import importlib.util
 import json
 import os
@@ -10,26 +12,41 @@ from pathlib import Path
 import re
 import shlex
 import shutil
+import socket
 import subprocess
 import sys
 import tempfile
 import tarfile
+import threading
 import time
+import urllib.error
+import urllib.request
 import uuid
 
 import raft_files
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"
 
 CONFIG = Path.home() / ".config/raft/incus.json"
+# Controller defaults for new live apart from the location inventory, so location
+# names can never collide with setting names.
+DEFAULTS_CONFIG = Path.home() / ".config/raft/config.json"
 PROJECT = "raft"
-SAVED_BOX_LIMIT = 4
 LOCATION_NAME = r"[a-zA-Z0-9][a-zA-Z0-9_-]*"
 GIB = 1024**3
-# Supported box sizes. Parser choices, capacity validation and recommendations
-# all derive from these lists, so adding a size here covers every command.
-CPU_SIZES = [1, 2]
-MEMORY_SIZES = ["1GiB", "2GiB", "4GiB", "8GiB"]
+# Boxes use the shared Btrfs pool unless `new --disk` gives them their own disk:
+# a fixed-size thin logical volume in this LVM pool. Deployment always creates the
+# shared pool; the own-disk pool exists only on hosts deployed with --disk-pool.
+SHARED_POOL = "raft-data"
+BOX_DISK_POOL = "raft-disks"
+# Size of a box created from the image without --cpu, --memory or a config.json
+# default. Boxes created from a snapshot keep the snapshot's CPU, RAM and disk
+# unless a flag overrides it; config.json defaults never do.
+DEFAULT_CPU = 1
+DEFAULT_MEMORY = "2GiB"
+# Box notes follow one template so any agent can tell why a box exists, who uses
+# it and what happens to it next. Each value is free text; purpose is required.
+BOX_NOTE_FIELDS = ["purpose", "owner", "next"]
 
 USAGE = """import json, shutil
 from pathlib import Path
@@ -42,7 +59,6 @@ print(json.dumps({
     'effectiveCpus': (group / 'cpuset.cpus.effective').read_text().strip(),
     'filesystemUsedBytes': disk.used,
     'filesystemAvailableBytes': disk.free,
-    'filesystemScope': 'shared Raft pool, not per-box usage',
 }))
 """
 
@@ -68,35 +84,43 @@ def settings(location):
     return inventory[location]
 
 
-def edit_configuration(change):
-    """Apply change(inventory) to the controller configuration and save it."""
+def edit_json(path, load, change):
+    """Apply change(document) to a controller JSON file and save it.
+
+    load() reads and validates the current file. An empty document removes the file.
+    """
     # main() sets umask 077, so a new configuration directory is private.
-    CONFIG.parent.mkdir(parents=True, exist_ok=True)
+    path.parent.mkdir(parents=True, exist_ok=True)
     # Hold a controller lock across read, edit and replace so concurrent edits
     # cannot drop each other. Readers need no lock because replacement is atomic.
-    with (CONFIG.parent / ".incus.json.lock").open("w") as lock:
+    with (path.parent / f".{path.name}.lock").open("w") as lock:
         fcntl.flock(lock, fcntl.LOCK_EX)
         # Onboarding can start on a controller that has no configuration yet.
-        inventory = configuration() if CONFIG.exists() else {}
-        change(inventory)
-        if not inventory:
-            # Removing the only location restores the unconfigured state.
-            CONFIG.unlink(missing_ok=True)
+        document = load() if path.exists() else {}
+        change(document)
+        if not document:
+            # Removing the last entry restores the unconfigured state.
+            path.unlink(missing_ok=True)
             return
         # Key order is preserved because the first location is the default for new.
-        # Replace atomically so an interrupted write cannot truncate the inventory;
+        # Replace atomically so an interrupted write cannot truncate the file;
         # NamedTemporaryFile creates the staged file with mode 0600.
-        staged = tempfile.NamedTemporaryFile("w", dir=CONFIG.parent, prefix=".raft-", delete=False)
+        staged = tempfile.NamedTemporaryFile("w", dir=path.parent, prefix=".raft-", delete=False)
         try:
             with staged:
-                json.dump(inventory, staged, indent=2)
+                json.dump(document, staged, indent=2)
                 staged.write("\n")
-            os.replace(staged.name, CONFIG)
+            os.replace(staged.name, path)
         finally:
             # A no-op after a successful replace; removes the file after a failure.
             Path(staged.name).unlink(missing_ok=True)
 
 
+def edit_configuration(change):
+    """Apply change(inventory) to the location inventory and save it."""
+    edit_json(CONFIG, configuration, change)
+
+
 def set_note(location, text):
     """Record operator guidance for a location. Raft shows notes but never enforces them."""
     if text is not None and not text.strip():
@@ -113,6 +137,159 @@ def set_note(location, text):
     edit_configuration(change)
 
 
+def box_note(args):
+    """Build a box note from --purpose, --owner and --next; None when none is given."""
+    note = {}
+    for field in BOX_NOTE_FIELDS:
+        value = getattr(args, field, None)
+        if value is not None:
+            if not value.strip():
+                raise ValueError(f"--{field} cannot be empty")
+            note[field] = value.strip()
+    if note and "purpose" not in note:
+        raise ValueError("Box notes need --purpose")
+    return note or None
+
+
+def read_box_note(box):
+    """Return a box's note as a dict, or None. Raft writes it as JSON in user.raft.note."""
+    stored = box["config"].get("user.raft.note")
+    return json.loads(stored) if stored else None
+
+
+def cpu_count(value):
+    """Parse --cpu: any positive whole number of CPUs."""
+    if not re.fullmatch(r"[1-9][0-9]*", value):
+        raise argparse.ArgumentTypeError("CPU count must be a positive whole number")
+    return int(value)
+
+
+def gib_size(value):
+    """Parse --memory, --disk and --disk-pool. Whole GiB like 16GiB is the one accepted form."""
+    if not re.fullmatch(r"[1-9][0-9]*GiB", value):
+        raise argparse.ArgumentTypeError("Use a whole number of GiB, e.g. 16GiB")
+    return value
+
+
+def disk_size(value):
+    """Parse new --disk: an own-disk size like 20GiB, or shared for the shared pool."""
+    return value if value == "shared" else gib_size(value)
+
+
+def gib(size):
+    return int(size.removesuffix("GiB"))
+
+
+def box_disk(box):
+    """Return a box's own disk size, e.g. 20GiB, or "shared" for the shared pool."""
+    root = box["expanded_devices"].get("root", {})
+    return root.get("size", "") if root.get("pool") == BOX_DISK_POOL else "shared"
+
+
+# Box note policy. A host can require note fields for every box it holds; the
+# policy lives on the host, in the Incus project key user.raft.require (for
+# example "purpose,owner"), so every controller reads the same rule. Each
+# command that creates a box or changes its note checks the policy twice: once
+# from the controller for an actionable message before any work, and again in
+# the host transaction that writes the note, under the host lock. This is a
+# guardrail for agents: SSH and sudo on the host bypass it, and controllers
+# older than this check never run it.
+POLICY_KEY = "user.raft.require"
+POLICY_CHANGED_KEY = "user.raft.require.changed"
+
+# Host half of the check, run with the required fields and the note the box
+# will carry. Kept short; the controller builds the detailed message.
+CHECK_NOTE_CODE = """import json, sys
+required = [field for field in sys.argv[1].split(",") if field]
+note = json.loads(sys.argv[2]) if sys.argv[2] else {}
+missing = [field for field in required if not note.get(field)]
+if missing:
+    raise SystemExit(
+        "This host requires box note fields " + ", ".join(required)
+        + " (Incus project key user.raft.require); missing " + ", ".join(missing)
+        + ". Nothing was changed. Give the note with "
+        + " ".join("--" + field for field in required) + " and retry"
+    )
+"""
+# Read the policy with errexit active: inside a command substitution used as an
+# argument, a failed read would pass an empty policy and let every note through.
+READ_NOTE_POLICY = f"require=$(incus project get raft {POLICY_KEY})\n"
+# Callers set $note to the exact value they write to user.raft.note.
+CHECK_NOTE = "python3 -c " + shlex.quote(CHECK_NOTE_CODE) + ' "$require" "$note"'
+
+
+def note_policy(location):
+    """Return a location's required note fields and its last recorded policy change."""
+    # `incus query` rejects the --project flag that remote() always passes.
+    projects = json.loads(incus(location, "project", "list", "--format", "json"))
+    project = next(item for item in projects if item["name"] == PROJECT)
+    stored = project["config"].get(POLICY_KEY, "")
+    required = [field for field in stored.split(",") if field]
+    unknown = [field for field in required if field not in BOX_NOTE_FIELDS]
+    if unknown:
+        raise ValueError(
+            f"{location}: host policy {POLICY_KEY}={stored!r} names unknown note fields; "
+            f"fix it with raft policy {location} --require FIELDS or --clear"
+        )
+    return {"require": required, "changed": project["config"].get(POLICY_CHANGED_KEY, "")}
+
+
+def note_problem(location, required, note, command, hint=""):
+    """Describe how note falls short of the required fields, or return None."""
+    missing = [field for field in required if not (note or {}).get(field)]
+    if not missing:
+        return None
+    flags = " and ".join("--" + field for field in missing)
+    usage = " ".join(
+        f'--{field} "..."' if field in required else f'[--{field} "..."]'
+        for field in BOX_NOTE_FIELDS
+    )
+    return (
+        f"location {location} requires {flags} (host policy).{hint} "
+        f"Add {'it' if len(missing) == 1 else 'them'}: raft {command} {usage}"
+    )
+
+
+def require_note(location, note, command, hint=""):
+    """Fail before any host change when note lacks a field the location requires."""
+    problem = note_problem(location, note_policy(location)["require"], note, command, hint)
+    if problem:
+        raise ValueError(problem)
+
+
+def note_fields(text):
+    """Parse --require FIELDS into BOX_NOTE_FIELDS order."""
+    fields = [field.strip() for field in text.split(",") if field.strip()]
+    unknown = [field for field in fields if field not in BOX_NOTE_FIELDS]
+    if unknown or not fields:
+        raise ValueError(
+            "Give note fields from " + ", ".join(BOX_NOTE_FIELDS) + ", e.g. --require purpose,owner"
+        )
+    if "purpose" not in fields:
+        # Every box note has a purpose, so a policy without it would be misleading.
+        raise ValueError("Box notes always need purpose; include it, e.g. --require purpose,owner")
+    return [field for field in BOX_NOTE_FIELDS if field in fields]
+
+
+def set_policy(location, fields):
+    """Set (fields) or clear (None) a location's note policy and record the change on the host."""
+    settings(location)
+    value = ",".join(fields or [])
+    # Who and when is recorded on the host beside the policy and in its journal.
+    # The controller identity is self-reported; SUDO_USER is the SSH account.
+    before = transaction(
+        location,
+        f"before=$(incus project get raft {POLICY_KEY})\n"
+        'changed="$(date -u +%Y-%m-%dT%H:%M:%SZ) by ${SUDO_USER:-root} from $2"\n'
+        f'incus project set raft {POLICY_KEY}="$1" {POLICY_CHANGED_KEY}="$changed"\n'
+        "logger -t raft \"Box note policy: required fields '$before' -> '$1' ($changed)\"\n"
+        "printf '%s\\n' \"$before\"",
+        value,
+        f"{getpass.getuser()}@{socket.gethostname()}",
+    ).strip()
+    print(f"{location}: required note fields {before or 'none'} -> {value or 'none'}")
+
+
 def receive(command, destination, *, stdin=None):
     """Write streamed bytes in Python: SSH can exit zero after a local write error."""
     with tempfile.TemporaryFile() as errors:
@@ -179,7 +356,7 @@ if sudo -n incus project list --format csv -c n 2>/dev/null | grep -qx raft; the
 """
 
 
-def host_problems(facts):
+def host_problems(facts, disk_pool=None):
     """Return reasons a probed SSH target cannot become a Raft host; empty means supported."""
     kernel = facts.get("kernel") or "an unknown system"
     if kernel != "Linux":
@@ -205,10 +382,17 @@ def host_problems(facts):
     memory = int(facts.get("memory") or 0) * 1024
     if memory < 7.5 * GIB:
         problems.append(f"Raft hosts need at least 8 GiB RAM; found {memory / GIB:.1f} GiB")
-    # Only a fresh deployment creates the 60 GiB pool; deploy.py enforces the same limit.
+    # Only a fresh deployment creates the 60 GiB shared pool, and the own-disk
+    # pool when --disk-pool asks for it; deploy.py enforces the same minimum.
     disk = int(facts.get("disk") or 0) * 1024
-    if facts.get("deployed") != "yes" and disk < 80 * GIB:
-        problems.append(f"Fresh hosts need at least 80 GiB free disk; found {disk / GIB:.1f} GiB")
+    needed = 80 + (gib(disk_pool) if disk_pool else 0)
+    if facts.get("deployed") != "yes" and disk < needed * GIB:
+        problems.append(
+            f"Fresh hosts need at least {needed} GiB free disk"
+            + (f" (80 GiB plus the {disk_pool} own-disk pool)" if disk_pool else "")
+            + f"; found {disk / GIB:.1f} GiB"
+            + (". A smaller --disk-pool needs less" if disk_pool else "")
+        )
     return problems
 
 
@@ -230,7 +414,18 @@ def smoke_test(location):
     """Create a disposable box, wait until it runs a command, then delete it."""
     handle = new(
         argparse.Namespace(
-            location=location, ttl=600, cpu=1, memory="2GiB", disposable=True, template=None
+            location=location,
+            ttl=600,
+            cpu=1,
+            memory="2GiB",
+            # Explicit, so a configured disk default never moves the smoke box off the shared pool.
+            disk="shared",
+            disposable=True,
+            template=None,
+            # A full note satisfies any note policy left on a reused deployment.
+            purpose="raft host add smoke test",
+            owner="raft host add",
+            next="Deleted by the smoke test",
         )
     )
     print("Smoke test box: " + handle, flush=True)
@@ -278,7 +473,7 @@ def host_add(args):
             f"Verify the host key interactively, then check `ssh -o BatchMode=yes {args.ssh} true`"
         )
     facts = dict(line.split("=", 1) for line in probe.stdout.splitlines() if "=" in line)
-    problems = host_problems(facts)
+    problems = host_problems(facts, args.disk_pool)
     if problems:
         raise ValueError(
             f"{args.ssh} cannot host Raft boxes; nothing was changed:\n- " + "\n- ".join(problems)
@@ -293,13 +488,20 @@ def host_add(args):
     print(
         f"Plan for {args.location} ({args.ssh}: Ubuntu {facts['version']} {architecture}, "
         f"{facts['cpus']} CPUs, {int(facts['memory']) * 1024 / GIB:.1f} GiB RAM)\n"
-        "- install Incus 6.0 LTS from the Zabbly apt repository, btrfs-progs and nftables if missing\n"
+        "- install Incus 6.0 LTS from the Zabbly apt repository, btrfs-progs, lvm2 and nftables "
+        "if missing\n"
         + (
             "- reuse and verify the existing raft project, raft-data pool and rfbr0 bridge\n"
             if facts["deployed"] == "yes"
             else "- create Incus project raft, 60 GiB Btrfs pool raft-data and bridge rfbr0 "
             "(10.232.0.1/24 with NAT)\n"
         )
+        + (
+            f"- create the {args.disk_pool} thin LVM pool raft-disks for own box disks if it is "
+            "missing, and allocate its file on the host disk in full\n"
+            if args.disk_pool
+            else ""
+        )
         + "- install raft-network.service (rfbr0 isolation rules) and raft-expire.timer\n"
         f"- {image}; images are checked by SHA-256 and architecture\n"
         f"- add {args.location} with the image fingerprint to {CONFIG}\n"
@@ -315,7 +517,7 @@ def host_add(args):
             raise ValueError("Review the plan, then rerun with --yes to apply it")
         if input("Apply this plan? [y/N] ").strip().lower() not in {"y", "yes"}:
             raise ValueError("Onboarding cancelled; nothing was changed")
-    deployer.deploy(args.location, args.ssh)
+    deployer.deploy(args.location, args.ssh, args.disk_pool)
     if args.build:
         # A fresh alias avoids refusing to build beside an earlier raft-dev image.
         alias = "raft-dev-" + uuid.uuid4().hex[:8]
@@ -369,11 +571,6 @@ def inventory(location):
     ]
 
 
-ADMISSION = f"""count=$(incus --project raft list --fast --format json | python3 -c 'import json,sys; print(sum(x["config"].get("user.raft")=="true" for x in json.load(sys.stdin)))')
-test "$count" -lt {SAVED_BOX_LIMIT} || {{ echo 'Location already holds four boxes' >&2; exit 1; }}
-"""
-
-
 REQUIRE_STOPPED = """state=$(incus --project raft list "$1" --fast --format json | python3 -c 'import json,sys; print(next(x["status"] for x in json.load(sys.stdin) if x["name"] == sys.argv[1] and x["config"].get("user.raft") == "true"))' "$1")
 test "$state" = Stopped || { echo 'Stop the source box before resume, snapshot, restore, fork or backup' >&2; exit 1; }
 """
@@ -391,92 +588,250 @@ CHECK_WORKER = (
 )
 
 
-HOST_RESOURCES = """import json, os, shutil, subprocess
+# Host-side accounting for the own-disk pool, shared by capacity reports and the
+# reservation check. It runs as root on the host, where python3 and lvs exist.
+#
+# raft-disks is a thin LVM pool, so forks, templates and snapshots of own-disk
+# boxes are thin snapshots that share blocks instead of copies. Thin volumes can
+# promise more space than the pool holds, and a full thin pool fails every volume
+# in it at once. Raft never lets that happen: a thin volume can never hold more
+# data than its virtual size, so while the virtual sizes of all thin volumes in
+# the pool (boxes, their snapshots, the cached image and anything else) add up to
+# no more than the pool's data space, the pool cannot fill. Every Raft operation
+# that adds a thin volume to raft-disks checks that sum first, under the host lock.
+BOX_DISK_ACCOUNTING = (
+    "POOL = "
+    + repr(BOX_DISK_POOL)
+    + """
+import json, subprocess, sys
+GIB = 1024**3
+
+def query(path):
+    return json.loads(subprocess.run(['incus', 'query', path], check=True, capture_output=True).stdout)
+
+def size_bytes(value):
+    # Raft sizes own disks in whole GiB; anything else came from a native Incus edit.
+    if not value.endswith('GiB') or not value[:-3].isdigit():
+        sys.exit(f'Unexpected own-disk size {value!r}; inspect it with incus')
+    return int(value[:-3]) * GIB
+
+def box_disk_pool():
+    # Own box disks are opt-in per host, so a missing pool is a normal state.
+    if '/1.0/storage-pools/' + POOL not in query('/1.0/storage-pools'):
+        return None
+    config = query('/1.0/storage-pools/' + POOL)['config']
+    thinpool = config['lvm.thinpool_name']
+    columns = 'lv_name,lv_size,pool_lv,data_percent,metadata_percent'
+    report = subprocess.run(['lvs', '--reportformat', 'json', '--units', 'b', '--nosuffix', '-o', columns, config['lvm.vg_name']], check=True, capture_output=True)
+    volumes = json.loads(report.stdout)['report'][0]['lv']
+    pool = next(volume for volume in volumes if volume['lv_name'] == thinpool)
+    # LVM reports usage only while the thin pool is active; reservations never need it.
+    active = pool['data_percent'] != ''
+    total = int(pool['lv_size'])
+    return {
+        'totalBytes': total,
+        'reservedBytes': sum(int(volume['lv_size']) for volume in volumes if volume['pool_lv'] == thinpool),
+        'usedBytes': int(total * float(pool['data_percent']) / 100) if active else None,
+        'metadataUsedPercent': float(pool['metadata_percent']) if active else None,
+        # Incus caches the image as a thin volume of the pool's volume.size, or
+        # its 10 GiB default, and starts each own-disk box as a snapshot of it.
+        'imageVolumeBytes': size_bytes(config.get('volume.size', '10GiB')),
+    }
+
+def reserve(location, pool, added, origin=''):
+    # Exit with the reason unless thin volumes of the added sizes fit in full.
+    # origin, when given, is a sentence saying where the requested size came from.
+    suffix = '. ' + origin if origin else ''
+    if added and pool is None:
+        sys.exit(
+            f'{location} has no {POOL} pool, so own box disks are not enabled there; nothing was '
+            f'created. Enable them with python3 deploy/deploy.py --location {location} '
+            '--disk-pool SIZE' + suffix
+        )
+    if added and pool['reservedBytes'] + sum(added) > pool['totalBytes']:
+        sys.exit(
+            f'{location}: own box disks would need {sum(added) / GIB:.1f} GiB more of {POOL}, '
+            f'which has {(pool["totalBytes"] - pool["reservedBytes"]) / GIB:.1f} of '
+            f'{pool["totalBytes"] / GIB:.1f} GiB unreserved; nothing was created. Destroy '
+            'own-disk boxes or snapshots you no longer need, or use a smaller disk or the '
+            'shared pool' + suffix
+        )
+"""
+)
+
+HOST_RESOURCES = (
+    BOX_DISK_ACCOUNTING
+    + """
+import os, shutil
 from pathlib import Path
 memory = dict(line.split()[:2] for line in Path('/proc/meminfo').read_text().splitlines())
 disk = shutil.disk_usage('/var/lib/incus')
-pool = json.loads(subprocess.check_output(['incus', 'query', '/1.0/storage-pools/raft-data/resources']))
+space = query('/1.0/storage-pools/raft-data/resources')['space']
+own = box_disk_pool()
+if own is not None:
+    del own['imageVolumeBytes']
 print(json.dumps({
     'cpus': len(os.sched_getaffinity(0)),
     'memoryTotalBytes': int(memory['MemTotal:']) * 1024,
     'memoryAvailableBytes': int(memory['MemAvailable:']) * 1024,
     'hostDiskFreeBytes': disk.free,
-    'poolTotalBytes': pool['space']['total'],
-    'poolFreeBytes': pool['space']['total'] - pool['space']['used'],
+    'sharedPool': {'totalBytes': space['total'], 'freeBytes': space['total'] - space['used']},
+    'boxDiskPool': own,
 }))
 """
+)
+
+# Reservation check run inside lifecycle transactions before Incus adds a thin
+# volume to raft-disks. Arguments: location (for messages), the requested own-disk
+# size in GiB (0 for none), the source: image:FINGERPRINT, BOX or BOX/SNAPSHOT,
+# and the origin sentence for refusals (empty when the size is a flag).
+# A new volume starts as a thin snapshot of its source and is then resized to the
+# requested size, so it needs the larger of the two. Copies of shared-pool boxes
+# without --disk never touch raft-disks and need nothing.
+RESERVE_BOX_DISK = (
+    BOX_DISK_ACCOUNTING
+    + """
+location, requested, source, origin = sys.argv[1], int(sys.argv[2]) * GIB, sys.argv[3], sys.argv[4]
+pool = box_disk_pool()
+added = []
+if source.startswith('image:'):
+    if requested:
+        image = pool['imageVolumeBytes'] if pool else 0
+        added.append(max(requested, image))
+        # Incus caches the image in the pool the first time an own-disk box needs it.
+        volume = f'/1.0/storage-pools/{POOL}/volumes/image/{source[6:]}'
+        if pool and subprocess.run(['incus', 'query', volume], capture_output=True).returncode:
+            added.append(image)
+else:
+    path = '/1.0/instances/' + source.replace('/', '/snapshots/') + '?project=raft'
+    root = query(path)['expanded_devices']['root']
+    if root.get('pool') == POOL:
+        added.append(max(requested, size_bytes(root['size'])))
+    elif requested:
+        added.append(requested)
+reserve(location, pool, added, origin)
+"""
+)
+
+# Prints the pool `raft recover` imports into, from backup/index.yaml, the first
+# entry of every Incus export. Own-disk backups return to raft-disks with their
+# recorded size after the same reservation check: Incus restores the box and each
+# of its snapshots as a thin volume of that size. Other backups use the shared pool.
+RECOVERY_POOL = (
+    BOX_DISK_ACCOUNTING
+    + "SHARED_POOL = "
+    + repr(SHARED_POOL)
+    + """
+import tarfile, yaml
+archive, location = sys.argv[1], sys.argv[2]
+with tarfile.open(archive, 'r|gz') as backup:
+    entry = backup.next()
+    if entry is None or entry.name != 'backup/index.yaml':
+        sys.exit('Not an Incus instance backup: backup/index.yaml is not its first entry')
+    index = yaml.safe_load(backup.extractfile(entry))
+if index.get('pool') != POOL:
+    print(SHARED_POOL)
+    sys.exit()
+size = size_bytes(index['config']['container']['expanded_devices']['root']['size'])
+reserve(location, box_disk_pool(), [size] * (1 + len(index.get('snapshots') or [])))
+print(POOL)
+"""
+)
+
+
+def reserve_box_disk(location, disk, source, origin=""):
+    """Shell line that refuses an own-disk volume raft-disks could not hold in full."""
+    size = str(gib(disk) if disk else 0)
+    return shlex.join(["python3", "-c", RESERVE_BOX_DISK, location, size, source, origin]) + "\n"
+
+
+# Agents read capacity output to plan work. Earlier wording that looked like a cap
+# made them skip boxes they needed, so every report leads with this sentence.
+ADVISORY = (
+    "Advisory estimate only. Raft enforces no box count or size budget; "
+    "create the boxes your task needs."
+)
 
 
 def capacity(host, boxes):
-    """Conservative allocation advice, not an exclusive CPU or memory reservation."""
-    gib = 1024**3
+    """Advisory planning numbers, not a reservation, admission rule or limit."""
     active = [box for box in boxes if box["status"] != "Stopped"]
     cpu_allocated = 0
     memory_allocated = 0
     for box in active:
         limits = box["expanded_config"]
-        if (
-            limits["limits.cpu"] not in {str(cpu) for cpu in CPU_SIZES}
-            or limits["limits.memory"] not in MEMORY_SIZES
+        # Raft writes whole CPU counts and whole GiB; other forms come from native Incus edits.
+        if not re.fullmatch(r"[1-9][0-9]*", limits["limits.cpu"]) or not re.fullmatch(
+            r"[1-9][0-9]*GiB", limits["limits.memory"]
         ):
-            raise ValueError("Active box has unsupported sizing; inspect its Incus configuration")
+            raise ValueError(
+                f"Active box {box['name']} has sizing Raft did not set; inspect its Incus configuration"
+            )
         cpu_allocated += int(limits["limits.cpu"])
-        memory_allocated += int(limits["limits.memory"].removesuffix("GiB")) * gib
-    memory_reserve = max(2 * gib, host["memoryTotalBytes"] // 10)
+        memory_allocated += gib(limits["limits.memory"]) * GIB
+    memory_reserve = max(2 * GIB, host["memoryTotalBytes"] // 10)
     cpu_budget = max(0, host["cpus"] - 1)
     memory_budget = max(0, host["memoryTotalBytes"] - memory_reserve)
-    cpu_remaining = max(0, cpu_budget - cpu_allocated)
-    memory_remaining = max(
+    cpu_headroom = max(0, cpu_budget - cpu_allocated)
+    memory_headroom = max(
         0,
         min(
             memory_budget - memory_allocated,
             host["memoryAvailableBytes"] - memory_reserve,
         ),
     )
-    slots = max(0, SAVED_BOX_LIMIT - len(boxes))
-    recommendations = []
-    for cpu in CPU_SIZES:
-        for memory in [int(size.removesuffix("GiB")) for size in MEMORY_SIZES]:
-            total = min(SAVED_BOX_LIMIT, cpu_budget // cpu, memory_budget // (memory * gib))
-            additional = min(
-                max(0, SAVED_BOX_LIMIT - len(active)),
-                cpu_remaining // cpu,
-                memory_remaining // (memory * gib),
-            )
-            recommendations.append(
-                {
-                    "cpu": cpu,
-                    "memoryGiB": memory,
-                    "totalRunning": total,
-                    "additionalRunning": additional,
-                    "newBoxes": min(slots, additional),
-                }
-            )
+    # Example shapes double from the 1 CPU / 2 GiB default at 2 GiB per CPU and
+    # stop at the largest that fits an empty host. Boxes may use any other size;
+    # headroom lets callers work out counts for those.
+    estimates = []
+    cpu = 1
+    while cpu == 1 or (cpu <= cpu_budget and 2 * cpu * GIB <= memory_budget):
+        memory = 2 * cpu * GIB
+        estimates.append(
+            {
+                "cpu": cpu,
+                "memoryGiB": 2 * cpu,
+                "fitEmptyHost": min(cpu_budget // cpu, memory_budget // memory),
+                "fitNow": min(cpu_headroom // cpu, memory_headroom // memory),
+            }
+        )
+        cpu *= 2
     warnings = []
     if cpu_allocated > cpu_budget or memory_allocated > memory_budget:
-        warnings.append("Active configured limits exceed the recommended host budget")
+        warnings.append(
+            "Active boxes may use more CPU or RAM than the host budget; under load they share it"
+        )
     if host["memoryAvailableBytes"] < memory_reserve:
         warnings.append(
-            "Available host RAM is below the reserve; stop boxes or reduce other workloads"
+            "Available host RAM is below the reserve; stop idle boxes or reduce other workloads"
         )
-    if host["hostDiskFreeBytes"] < 5 * gib or host["poolFreeBytes"] < 5 * gib:
+    if host["hostDiskFreeBytes"] < 5 * GIB or host["sharedPool"]["freeBytes"] < 5 * GIB:
         warnings.append(
             "Host or shared-pool free disk is below 5 GiB; check image and workspace growth"
         )
+    # LVM sizes thin pool metadata for every data block mapped, and reservations
+    # keep mappings within that, so this should never fire. It stays because full
+    # metadata stops every own-disk box and needs offline repair.
+    own = host["boxDiskPool"]
+    if own is not None and (own["metadataUsedPercent"] or 0) >= 80:
+        warnings.append(
+            f"{BOX_DISK_POOL} thin pool metadata is {own['metadataUsedPercent']:.0f}% full; "
+            "inspect it with lvs before creating more own-disk boxes"
+        )
     return {
+        "notice": ADVISORY,
         "host": host,
-        "savedBoxLimit": SAVED_BOX_LIMIT,
-        "savedBoxes": len(boxes),
+        "boxes": len(boxes),
         "activeBoxes": len(active),
-        "savedSlots": slots,
         "allocated": {"cpus": cpu_allocated, "memoryBytes": memory_allocated},
         "reserve": {"cpus": 1, "memoryBytes": memory_reserve},
-        "recommendations": recommendations,
+        "headroom": {"cpus": cpu_headroom, "memoryBytes": memory_headroom},
+        "estimates": estimates,
         "warnings": warnings,
     }
 
 
-def host_limits(location):
+def host_capacity(location):
     response = subprocess.run(
         [
             "ssh",
@@ -499,36 +854,47 @@ def host_limits(location):
     }
 
 
-def print_limits(report):
-    gib = 1024**3
+def print_capacity(report):
     host = report["host"]
+    print(report["notice"])
     print(
         f"{report['location']}: {host['cpus']} CPUs, "
-        f"{host['memoryTotalBytes'] / gib:.1f} GiB RAM "
-        f"({host['memoryAvailableBytes'] / gib:.1f} GiB available)"
+        f"{host['memoryTotalBytes'] / GIB:.1f} GiB RAM "
+        f"({host['memoryAvailableBytes'] / GIB:.1f} GiB available)"
     )
     if report["note"]:
         print("Note: " + report["note"])
+    print(f"Boxes: {report['boxes']} saved, {report['activeBoxes']} active")
     print(
-        f"Saved boxes: {report['savedBoxes']}/{report['savedBoxLimit']} enforced; "
-        f"active: {report['activeBoxes']}; free saved slots: {report['savedSlots']}"
-    )
-    print(
-        f"Active limits: {report['allocated']['cpus']} CPUs, "
-        f"{report['allocated']['memoryBytes'] / gib:.1f} GiB; "
-        f"host reserve: 1 CPU, {report['reserve']['memoryBytes'] / gib:.1f} GiB"
+        f"Allocated to active boxes: {report['allocated']['cpus']} CPUs, "
+        f"{report['allocated']['memoryBytes'] / GIB:.1f} GiB; "
+        f"host reserve: 1 CPU, {report['reserve']['memoryBytes'] / GIB:.1f} GiB; "
+        f"headroom: {report['headroom']['cpus']} CPUs, "
+        f"{report['headroom']['memoryBytes'] / GIB:.1f} GiB"
     )
     print(
-        f"Disk free: {host['poolFreeBytes'] / gib:.1f} GiB shared pool, "
-        f"{host['hostDiskFreeBytes'] / gib:.1f} GiB host"
+        f"Disk free: {host['sharedPool']['freeBytes'] / GIB:.1f} of "
+        f"{host['sharedPool']['totalBytes'] / GIB:.1f} GiB shared pool, "
+        f"{host['hostDiskFreeBytes'] / GIB:.1f} GiB host"
     )
-    print("CPU  RAM GiB  Total running  More running  New boxes")
-    for size in report["recommendations"]:
+    own = host["boxDiskPool"]
+    if own is None:
+        print("Own box disks: not enabled (redeploy with --disk-pool SIZE)")
+    else:
+        print(
+            f"Own box disks: {(own['totalBytes'] - own['reservedBytes']) / GIB:.1f} of "
+            f"{own['totalBytes'] / GIB:.1f} GiB unreserved"
+        )
+    print("CPU  RAM GiB  Fit on empty host  Fit now")
+    for size in report["estimates"]:
         print(
-            f"{size['cpu']:>3}  {size['memoryGiB']:>7}  {size['totalRunning']:>13}  "
-            f"{size['additionalRunning']:>12}  {size['newBoxes']:>9}"
+            f"{size['cpu']:>3}  {size['memoryGiB']:>7}  {size['fitEmptyHost']:>17}  "
+            f"{size['fitNow']:>7}"
         )
-    print("Advisory CPU/RAM counts; total assumes an empty host. Disk growth is not included.")
+    print(
+        "Counts assume every box uses its full CPU and RAM at once. Boxes share host CPUs, "
+        "so more can run when they are not all busy. Any whole CPU count and GiB size works."
+    )
     for warning in report["warnings"]:
         print("Warning: " + warning)
 
@@ -555,7 +921,12 @@ def doctor(location):
         check=True,
     )
     print(response.stdout.strip())
-    print(incus(location, "storage", "info", "raft-data").strip())
+    print(incus(location, "storage", "info", SHARED_POOL).strip())
+    # Own box disks are opt-in, so a host without their pool is healthy.
+    if BOX_DISK_POOL in incus(location, "storage", "list", "--format", "csv", "-c", "n").split():
+        print(incus(location, "storage", "info", BOX_DISK_POOL).strip())
+    else:
+        print("own box disks: not enabled (redeploy with --disk-pool SIZE)")
     print(f"{len(inventory(location))} saved boxes; system containers (shared host kernel)")
 
 
@@ -606,7 +977,52 @@ def sizing(args):
     return values
 
 
+def fits_host(args):
+    """Shell checks that refuse a CPU or RAM limit larger than the whole host.
+
+    Incus accepts such limits and quietly gives the box less, so an agent would
+    plan around resources it never gets. MemTotal is rounded up to whole GiB:
+    an 8 GiB machine reports about 7.7 GiB and must still accept 8GiB. The
+    parsers already restrict both values to whole numbers, so they embed safely.
+    """
+    checks = ""
+    if args.cpu is not None:
+        checks += (
+            f'test {args.cpu} -le "$(nproc)" || '
+            f'{{ echo "Requested {args.cpu} CPUs, but this host has $(nproc)" >&2; exit 1; }}\n'
+        )
+    if args.memory is not None:
+        checks += (
+            "total=$(awk '/^MemTotal:/ {print int(($2 + 1048575) / 1048576)}' /proc/meminfo)\n"
+            f'test {gib(args.memory)} -le "$total" || '
+            f'{{ echo "Requested {args.memory} RAM, but this host has $total GiB" >&2; exit 1; }}\n'
+        )
+    return checks
+
+
+def own_disk(size):
+    """Incus device overrides that give a box its own fixed-size disk in raft-disks.
+
+    The full root device is spelled out because `incus copy` of a snapshot whose
+    root comes from the profile adds an override as a whole new device.
+    """
+    return [
+        "-d",
+        "root,type=disk",
+        "-d",
+        "root,path=/",
+        "-d",
+        f"root,pool={BOX_DISK_POOL}",
+        "-d",
+        f"root,size={size}",
+    ]
+
+
 def new(args):
+    box_fields = box_note(args)
+    # Sizes are filled here only for boxes from the image; a box from a snapshot
+    # keeps the snapshot's CPU, RAM and disk unless a flag overrides them.
+    from_config = apply_new_defaults(args)
     source = None
     if args.template:
         handle, separator, snapshot = args.template.partition("/")
@@ -619,8 +1035,6 @@ def new(args):
         args.location = location
         instance(location, original)
         source = original + "/" + snapshot
-    if args.location is None:
-        args.location = next(iter(configuration()))
     if source is None:
         source = settings(args.location).get("image", "")
         if not isinstance(source, str) or not re.fullmatch(r"[a-f0-9]{64}", source):
@@ -631,18 +1045,37 @@ def new(args):
     if note:
         # Stderr keeps stdout limited to the handle for scripts.
         print(f"{args.location} note: {note}", file=sys.stderr)
+    require_note(args.location, box_fields, "new")
     name = "rf-" + uuid.uuid4().hex[:16]
     # Initialize before starting, so a failed start still has its intended policy.
     transaction(
         args.location,
         (CHECK_WORKER if args.disposable else "")
-        + ADMISSION
-        + 'lifetime="$1"; name="$2"; shift 2; "$@"; '
+        + fits_host(args)
+        # Plain boxes from the image stay off raft-disks and skip the check.
+        + (
+            reserve_box_disk(
+                args.location,
+                args.disk,
+                source if args.template else "image:" + source,
+                # A refusal of a configured disk says where the size came from.
+                disk_origin(args.disk) if "disk" in from_config else "",
+            )
+            if args.disk or args.template
+            else ""
+        )
+        + 'lifetime="$1"; name="$2"; note="$3"; shift 3\n'
+        + READ_NOTE_POLICY
+        + CHECK_NOTE
+        # Always set the note, so a box created from a snapshot never inherits the
+        # source note. The host checks the same value it writes.
+        + '\n"$@" -c user.raft.note="$note"; '
         'incus --project raft start "$name"; '
         'incus --project raft config set "$name" '
         'user.raft.expires="$(( $(date +%s) + lifetime ))"',
         str(args.ttl),
         name,
+        json.dumps(box_fields) if box_fields else "",
         "incus",
         "--project",
         PROJECT,
@@ -660,6 +1093,10 @@ def new(args):
         "-c",
         "volatile.eth0.hwaddr=",
         *sizing(args),
+        # Without --disk, init uses the profile's shared pool and copy keeps the
+        # snapshot's disk: the shared pool or an own disk of the same size. Copies
+        # within either pool are snapshots that share the source's blocks.
+        *(own_disk(args.disk) if args.disk else []),
     )
     return f"{args.location}:{name}"
 
@@ -759,7 +1196,11 @@ def backup(args, location, name):
 
 
 def recover(args):
+    box_fields = box_note(args)
     host = settings(args.location)["ssh"]
+    if box_fields:
+        # Without a new note the archived one applies; the host checks it after import.
+        require_note(args.location, box_fields, f"recover {args.source} --location {args.location}")
     name = "rf-" + uuid.uuid4().hex[:16]
     response = subprocess.run(
         ["ssh", "-T", "-o", "BatchMode=yes", host, "mktemp /tmp/raft-recovery.XXXXXXXX"],
@@ -785,12 +1226,24 @@ def recover(args):
                 stdin=archive,
                 check=True,
             )
+        # The archive carries the source note, known only after import. A rejected
+        # note deletes the imported box inside the same locked transaction.
         transaction(
             args.location,
-            ADMISSION + 'incus --project raft import "$1" "$2" --storage raft-data '
-            "-c user.raft=true -c user.raft.expires= -c user.raft.disposable=false -c user.raft.stopped-at= -c volatile.eth0.hwaddr=",
+            # The reservation check runs first and creates nothing when it refuses.
+            'pool=$(python3 -c "$3" "$1" "$4")\n'
+            + READ_NOTE_POLICY
+            + 'incus --project raft import "$1" "$2" --storage "$pool" '
+            "-c user.raft=true -c user.raft.expires= -c user.raft.disposable=false -c user.raft.stopped-at= -c volatile.eth0.hwaddr=\n"
+            'if [ -n "$5" ]; then incus --project raft config set "$2" user.raft.note="$5"; fi\n'
+            'note=$(incus --project raft config get "$2" user.raft.note)\n'
+            + CHECK_NOTE
+            + ' || { incus --project raft delete "$2" --force; exit 1; }',
             staged,
             name,
+            RECOVERY_POOL,
+            args.location,
+            json.dumps(box_fields) if box_fields else "",
         )
         if instance(args.location, name)["status"] != "Stopped":
             raise RuntimeError("Recovered box unexpectedly running: " + args.location + ":" + name)
@@ -849,23 +1302,446 @@ def ttl(value):
     return seconds
 
 
+def location_name(value):
+    if not re.fullmatch(LOCATION_NAME, value):
+        raise ValueError("Location names must use letters, digits, underscores or hyphens")
+    return value
+
+
+# Options of new that ~/.config/raft/config.json can default, with their built-in
+# defaults and value checks. Values go through str() first, so a configured value
+# is accepted exactly when the same text passed as the flag would be. Adding a
+# defaultable option means adding one entry here and keeping its flag default None.
+NEW_DEFAULTS = {
+    # None means the first configured location.
+    "location": (None, location_name),
+    "ttl": (600, ttl),
+    "cpu": (DEFAULT_CPU, cpu_count),
+    "memory": (DEFAULT_MEMORY, gib_size),
+    "disk": ("shared", disk_size),
+}
+# A box from a snapshot keeps the snapshot's size, so these defaults, configured
+# or built-in, apply only to boxes created from the image.
+SIZE_DEFAULTS = {"cpu", "memory", "disk"}
+
+
+def default_value(key, value):
+    """Validate one configured default; errors name the file and the key."""
+    if key not in NEW_DEFAULTS:
+        raise ValueError(
+            f"{DEFAULTS_CONFIG}: unknown key defaults.{key}; "
+            "supported keys: " + ", ".join(NEW_DEFAULTS)
+        )
+    try:
+        return NEW_DEFAULTS[key][1](str(value))
+    except (ValueError, argparse.ArgumentTypeError) as error:
+        raise ValueError(
+            f"{DEFAULTS_CONFIG}: defaults.{key}={value!r} is invalid: {error}"
+        ) from None
+
+
+def configured_defaults(unchecked=None):
+    """Return the validated defaults from config.json; a missing file means none.
+
+    The unchecked key is returned as stored, so `raft config set/unset KEY` can
+    repair a file whose only problem is that key.
+    """
+    if not DEFAULTS_CONFIG.exists():
+        return {}
+    try:
+        document = json.loads(DEFAULTS_CONFIG.read_text())
+    except json.JSONDecodeError as error:
+        raise ValueError(f"{DEFAULTS_CONFIG}: invalid JSON: {error}") from None
+    if (
+        not isinstance(document, dict)
+        or set(document) - {"defaults"}
+        or not isinstance(document.get("defaults", {}), dict)
+    ):
+        raise ValueError(f'{DEFAULTS_CONFIG}: expected {{"defaults": {{"KEY": VALUE, ...}}}}')
+    return {
+        key: value if key == unchecked else default_value(key, value)
+        for key, value in document.get("defaults", {}).items()
+    }
+
+
+def apply_new_defaults(args):
+    """Fill omitted new options: explicit flag, then config.json, then the built-in default.
+
+    Returns the keys whose value came from config.json. With --from only explicit
+    flags change the size: the snapshot's CPU, RAM and disk beat any default.
+    """
+    configured = configured_defaults()
+    used = set()
+    for key, (builtin, _) in NEW_DEFAULTS.items():
+        # getattr's default lets internal callers such as smoke_test omit options.
+        if key == "location" or getattr(args, key, None) is not None:
+            continue
+        if args.template and key in SIZE_DEFAULTS:
+            continue
+        if key in configured:
+            used.add(key)
+        setattr(args, key, configured.get(key, builtin))
+    if args.disk == "shared":
+        if args.template:
+            raise ValueError(
+                "--from keeps the snapshot's disk; leave out --disk, or give --disk SIZE "
+                "for an own disk of that size"
+            )
+        # The rest of new() spells the shared pool as no own disk.
+        args.disk = None
+    # A --from template fixes the location, so only plain creation takes a default.
+    if args.location is None and not args.template:
+        if "location" not in configured:
+            args.location = next(iter(configuration()))
+        elif configured["location"] in configuration():
+            args.location = configured["location"]
+            used.add("location")
+        else:
+            raise ValueError(
+                f"{DEFAULTS_CONFIG}: defaults.location names unknown location "
+                f"{configured['location']}; run raft config set location NAME or "
+                "raft config unset location"
+            )
+    return used
+
+
+def effective_defaults():
+    """Return each defaultable option's effective value and where it comes from."""
+    configured = configured_defaults()
+    report = {}
+    for key, (builtin, _) in NEW_DEFAULTS.items():
+        if key in configured:
+            report[key] = {"value": configured[key], "source": "config"}
+        else:
+            value = next(iter(configuration())) if key == "location" else builtin
+            report[key] = {"value": value, "source": "built-in"}
+    return report
+
+
+def disk_origin(size):
+    """Explain a reservation refusal for an own disk that config.json chose, not a flag."""
+    return (
+        f"The {size} own disk comes from defaults.disk in {DEFAULTS_CONFIG}; "
+        "give --disk shared or --disk SIZE, or run raft config unset disk"
+    )
+
+
+def set_default(key, value):
+    """Set (value) or remove (None) one default in config.json and print the change."""
+    if value is not None:
+        value = default_value(key, value)
+        if key == "location":
+            settings(value)
+    previous = {}
+
+    def change(document):
+        defaults = document.setdefault("defaults", {})
+        previous.update(defaults)
+        if value is None:
+            defaults.pop(key, None)
+        else:
+            defaults[key] = value
+        if not defaults:
+            document.pop("defaults")
+
+    edit_json(DEFAULTS_CONFIG, lambda: {"defaults": configured_defaults(key)}, change)
+    before = previous.get(key, "built-in default")
+    print(f"defaults.{key}: {before} -> {'built-in default' if value is None else value}")
+
+
+# GitHub releases are the one source of version truth. The release workflow
+# publishes npm before it creates the GitHub release, so every version this API
+# reports is already installable from both supported channels.
+RELEASES_API = "https://api.github.com/repos/Microck/raft/releases"
+# Matches the user agent deploy/deploy.py sends for release downloads.
+USER_AGENT = "OpenAI File Downloader, XaiImageApiFetch/1.0"
+# self-update --check exit status when a newer release exists, as dnf check-update uses.
+UPDATE_AVAILABLE = 100
+UPDATE_CHECK_INTERVAL = 24 * 3600
+UPDATE_CHECK_TIMEOUT = 2
+
+
+def parse_version(text):
+    """Return an X.Y.Z release version, optionally v-prefixed, as a comparable tuple."""
+    match = re.fullmatch(r"v?(\d+)\.(\d+)\.(\d+)", text)
+    if match is None:
+        raise ValueError(f"Not a release version: {text}")
+    return tuple(int(part) for part in match.groups())
+
+
+def release_version(value):
+    """Parser type for self-update --version; returns the version without its v."""
+    parse_version(value)
+    return value.removeprefix("v")
+
+
+def fetch(url, timeout):
+    request = urllib.request.Request(
+        url, headers={"User-Agent": USER_AGENT, "Accept": "application/vnd.github+json"}
+    )
+    return urllib.request.urlopen(request, timeout=timeout)
+
+
+def release(api, version=None, timeout=30):
+    """Return GitHub metadata for the latest release, or for release vVERSION."""
+    try:
+        with fetch(f"{api}/tags/v{version}" if version else api + "/latest", timeout) as response:
+            metadata = json.load(response)
+    except urllib.error.HTTPError as error:
+        if version and error.code == 404:
+            raise ValueError(f"No published Raft release v{version}") from error
+        raise
+    metadata["version"] = metadata["tag_name"].removeprefix("v")
+    parse_version(metadata["version"])
+    return metadata
+
+
+def update_message(latest):
+    return f"raft {latest} is available (you have {__version__}). Run: raft self-update"
+
+
+def update_cache():
+    return Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache") / "raft/update.json"
+
+
+def save_update_check():
+    """Record a release check. A torn write only makes the next command check again."""
+    path = update_cache()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps({"checkedAt": time.time()}))
+    except OSError:
+        pass
+
+
+def update_check(action, api=RELEASES_API):
+    """Start the passive release check for a command; the returned function prints its notice.
+
+    At most once per UPDATE_CHECK_INTERVAL, a background thread asks GitHub for
+    the latest release while the command runs, and only that command can print
+    the notice, so a controller sees it at most once per interval. The notice is
+    one stderr line, so stdout stays parseable. It never installs anything, and
+    network, thread or cache failures stay silent. RAFT_NO_UPDATE_CHECK=1
+    disables it.
+    """
+    if action == "self-update" or os.environ.get("RAFT_NO_UPDATE_CHECK"):
+        return lambda: None
+    try:
+        checked = float(json.loads(update_cache().read_text())["checkedAt"])
+    except (OSError, ValueError, KeyError, TypeError):
+        checked = 0
+    # A timestamp in the future, e.g. after a clock change, counts as stale.
+    if 0 <= time.time() - checked < UPDATE_CHECK_INTERVAL:
+        return lambda: None
+    # Record the attempt first: an offline controller then waits for at most one
+    # timeout per interval instead of one per command.
+    save_update_check()
+    found = {}
+
+    def check():
+        try:
+            found["latest"] = release(api, timeout=UPDATE_CHECK_TIMEOUT)["version"]
+        except Exception:
+            # A best-effort notice must not print tracebacks or fail commands.
+            pass
+
+    thread = threading.Thread(target=check, daemon=True)
+    try:
+        thread.start()
+    except RuntimeError:
+        # The runtime could not create the thread; skip this interval's notice.
+        return lambda: None
+
+    def notice():
+        # Commands usually outlast the request; otherwise wait a bounded time.
+        thread.join(UPDATE_CHECK_TIMEOUT)
+        latest = found.get("latest")
+        if latest is not None and parse_version(latest) > parse_version(__version__):
+            print(update_message(latest), file=sys.stderr)
+
+    return notice
+
+
+def install_channel(source, prefix):
+    """Return (channel, root) for the installation holding source, the resolved raft.py.
+
+    self-update manages npm global installs and uv tools. Any other layout raises
+    ValueError with instructions, so an update never moves to another channel.
+    """
+    package = source.parent
+    if (package / ".git").exists():
+        raise ValueError(
+            f"raft runs from the source checkout {package}; update it with "
+            "`git fetch --tags && git checkout vX.Y.Z` and `uv sync --locked`"
+        )
+    # A global install puts the package at PREFIX/lib/node_modules/@microck/raft and
+    # links PREFIX/bin/raft to raft.py. Project-local node_modules have no such link.
+    if package.parts[-4:] == ("lib", "node_modules", "@microck", "raft"):
+        npm_prefix = package.parents[3]
+        if (npm_prefix / "bin/raft").resolve() == source:
+            return "npm", npm_prefix
+    # uv names each tool environment after its package and leaves a receipt in it.
+    # Editable installs keep raft.py outside the environment and are excluded.
+    if prefix.name == "raft" and (prefix / "uv-receipt.toml").exists():
+        if source.is_relative_to(prefix):
+            return "uv", prefix
+    raise ValueError(
+        f"self-update manages npm global installs and uv tools; {source} is neither. "
+        "Reinstall with the tool you used, from a release verified against its SHA256SUMS: "
+        "https://github.com/Microck/raft/releases"
+    )
+
+
+def verified_wheel(metadata, directory):
+    """Download the release wheel and check it against the release SHA256SUMS."""
+    name = f"raft-{metadata['version']}-py3-none-any.whl"
+    assets = {asset["name"]: asset["browser_download_url"] for asset in metadata["assets"]}
+    for asset in [name, "SHA256SUMS"]:
+        if asset not in assets:
+            raise ValueError(
+                f"Release {metadata['tag_name']} has no {asset}; nothing was installed"
+            )
+        with fetch(assets[asset], 60) as response, (directory / asset).open("wb") as file:
+            shutil.copyfileobj(response, file)
+    expected = [
+        line.split()[0]
+        for line in (directory / "SHA256SUMS").read_text().splitlines()
+        if line.split()[1:] == [name]
+    ]
+    with (directory / name).open("rb") as file:
+        digest = hashlib.file_digest(file, "sha256").hexdigest()
+    if expected != [digest]:
+        raise ValueError(f"{name} does not match the release SHA256SUMS; nothing was installed")
+    return directory / name
+
+
+def self_update(args, api=RELEASES_API):
+    """Install the latest or the requested release through the channel that installed raft."""
+    if args.check:
+        latest = release(api)["version"]
+        save_update_check()
+        if parse_version(latest) > parse_version(__version__):
+            print(update_message(latest))
+            return UPDATE_AVAILABLE
+        print(f"raft {__version__} is up to date (latest release: {latest})")
+        return 0
+    if args.version is not None and parse_version(args.version) == parse_version(__version__):
+        print(f"raft {__version__} is already installed")
+        return 0
+    # Refuse unmanaged layouts before any download.
+    channel, root = install_channel(Path(__file__).resolve(), Path(sys.prefix).resolve())
+    tool = shutil.which(channel)
+    if tool is None:
+        raise ValueError(f"{channel} installed raft but is not on PATH")
+    metadata = release(api, args.version)
+    target = metadata["version"]
+    # Without --version, never downgrade a build that is newer than the latest release.
+    if args.version is None and parse_version(target) <= parse_version(__version__):
+        print(f"raft {__version__} is up to date (latest release: {target})")
+        return 0
+    # Installer output goes to stderr; stdout carries only the result below.
+    if channel == "npm":
+        # An explicit prefix keeps the update in this install even when another
+        # Node.js installation provides npm. The registry checks package integrity.
+        subprocess.run(
+            [tool, "install", "--global", "--prefix", str(root), f"@microck/raft@{target}"],
+            stdout=sys.stderr,
+            check=True,
+        )
+    else:
+        tools = subprocess.run([tool, "tool", "dir"], capture_output=True, text=True, check=True)
+        if Path(tools.stdout.strip()).resolve() != root.parent:
+            raise ValueError(
+                f"uv now installs tools in {tools.stdout.strip()}, not {root.parent}; "
+                "set UV_TOOL_DIR to the original directory, then retry"
+            )
+        with tempfile.TemporaryDirectory(prefix="raft-update-") as work:
+            wheel = verified_wheel(metadata, Path(work))
+            print(f"Verified {wheel.name} against the release SHA256SUMS", file=sys.stderr)
+            subprocess.run(
+                [tool, "tool", "install", "--force", str(wheel)], stdout=sys.stderr, check=True
+            )
+    installed = subprocess.run(
+        [str(root / "bin/raft"), "--version"], capture_output=True, text=True, check=True
+    )
+    if installed.stdout.strip() != target:
+        raise RuntimeError(f"{channel} installed {installed.stdout.strip()}, not {target}")
+    print(f"raft {__version__} -> {target}")
+    print("Release notes: " + metadata["html_url"])
+    print(
+        "Hosts were not changed. Run `raft doctor`: if a host's worker differs from this CLI, "
+        f"redeploy that host from release {metadata['tag_name']}. "
+        f"`raft host add` now imports {metadata['tag_name']} images by default."
+    )
+    return 0
+
+
+def note_options(command):
+    """Add the box note template flags shared by new, note, fork and recover."""
+    command.add_argument(
+        "--purpose", help="Box note: what the box is for, e.g. 'Integration tests for PR 42'"
+    )
+    command.add_argument(
+        "--owner", help="Box note: who uses the box, e.g. 'codex session in ~/work/app'"
+    )
+    command.add_argument(
+        "--next", help="Box note: what happens next, e.g. 'Destroy after the tests pass'"
+    )
+
+
 def parser():
     cli = argparse.ArgumentParser(description=__doc__)
     cli.add_argument("--version", action="version", version=__version__)
     commands = cli.add_subparsers(dest="action", required=True)
     create = commands.add_parser("new")
     create.add_argument("--location", default=None)
-    create.add_argument("--ttl", type=ttl, default=600)
-    create.add_argument("--cpu", type=int, choices=CPU_SIZES, default=1)
-    create.add_argument("--memory", choices=MEMORY_SIZES, default="2GiB")
+    # Omitted options take ~/.config/raft/config.json defaults, then NEW_DEFAULTS.
+    # With --from, every omitted size comes from the snapshot instead of a default.
+    create.add_argument("--ttl", type=ttl)
+    create.add_argument(
+        "--cpu",
+        type=cpu_count,
+        help=f"CPU limit (default: config, else {DEFAULT_CPU}; with --from, the snapshot's)",
+    )
+    create.add_argument(
+        "--memory",
+        type=gib_size,
+        help="RAM limit, e.g. 16GiB "
+        f"(default: config, else {DEFAULT_MEMORY}; with --from, the snapshot's)",
+    )
+    create.add_argument(
+        "--disk",
+        type=disk_size,
+        metavar="SIZE",
+        help="Give the box its own disk of SIZE, e.g. 20GiB, that it cannot grow past, "
+        "or shared for the shared pool "
+        "(default: config, else shared; with --from, the snapshot's disk)",
+    )
     create.add_argument("--disposable", action="store_true", help="Delete on stop or expiry")
     create.add_argument("--from", dest="template", metavar="LOCATION:BOX/SNAPSHOT")
+    note_options(create)
     commands.add_parser("locations", help="List configured locations and their notes")
-    note = commands.add_parser("note", help="Set or clear operator guidance for a location")
-    note.add_argument("location")
-    text = note.add_mutually_exclusive_group(required=True)
-    text.add_argument("text", nargs="?", help="Guidance, e.g. 'Preferred for builds'")
-    text.add_argument("--clear", action="store_true", help="Remove the location's note")
+    defaults = commands.add_parser(
+        "config", help="Show defaults for new and each location's note policy, or change defaults"
+    )
+    default_commands = defaults.add_subparsers(dest="config_action")
+    default_set = default_commands.add_parser("set", help="Set a default for new")
+    default_set.add_argument("key", choices=list(NEW_DEFAULTS))
+    default_set.add_argument("value")
+    default_unset = default_commands.add_parser("unset", help="Restore a built-in default")
+    default_unset.add_argument("key", choices=list(NEW_DEFAULTS))
+    policy = commands.add_parser(
+        "policy", help="Set or clear the box note fields a location's host requires"
+    )
+    policy.add_argument("location")
+    rule = policy.add_mutually_exclusive_group(required=True)
+    rule.add_argument("--require", metavar="FIELDS", help="Note fields, e.g. purpose,owner")
+    rule.add_argument("--clear", action="store_true", help="Stop requiring note fields")
+    note = commands.add_parser("note", help="Set or clear the note of a location or a box")
+    note.add_argument("target", metavar="LOCATION|BOX", help="A location name or a box handle")
+    note.add_argument("text", nargs="?", help="Location guidance, e.g. 'Preferred for builds'")
+    note.add_argument("--clear", action="store_true", help="Remove the note")
+    note_options(note)
     host = commands.add_parser("host", help="Onboard workspace hosts")
     host_commands = host.add_subparsers(dest="host_action", required=True)
     onboard = host_commands.add_parser(
@@ -888,11 +1764,18 @@ def parser():
         "--dry-run", action="store_true", help="Check the host and print the plan; change nothing"
     )
     onboard.add_argument("--yes", action="store_true", help="Apply the plan without prompting")
+    onboard.add_argument(
+        "--disk-pool",
+        type=gib_size,
+        metavar="SIZE",
+        help="Enable own box disks: set aside SIZE of host disk for them, e.g. 40GiB "
+        "(default: not enabled)",
+    )
     listing = commands.add_parser("list")
     listing.add_argument("--location")
-    limits = commands.add_parser("limits", help="Inspect host capacity and recommended box counts")
-    limits.add_argument("--location")
-    limits.add_argument("--json", action="store_true")
+    report = commands.add_parser("capacity", help=ADVISORY, description=ADVISORY)
+    report.add_argument("--location")
+    report.add_argument("--json", action="store_true")
     commands.add_parser("doctor")
     gc = commands.add_parser("gc", help="Enforce deadlines, including disposable deletion")
     gc.add_argument("--location")
@@ -903,6 +1786,22 @@ def parser():
     recovery = commands.add_parser("recover", help="Import a portable backup as a new stopped box")
     recovery.add_argument("source")
     recovery.add_argument("--location", required=True)
+    note_options(recovery)
+    update = commands.add_parser(
+        "self-update", help="Upgrade this CLI to the latest or a chosen release"
+    )
+    target = update.add_mutually_exclusive_group()
+    target.add_argument(
+        "--check",
+        action="store_true",
+        help=f"Only report whether a newer release exists; exit {UPDATE_AVAILABLE} if one does",
+    )
+    target.add_argument(
+        "--version",
+        type=release_version,
+        metavar="X.Y.Z",
+        help="Install this release instead of the latest, e.g. to roll back",
+    )
     for action in [
         "info",
         "stop",
@@ -931,10 +1830,11 @@ def parser():
         if action in ["resume", "fork", "extend"]:
             command.add_argument("--ttl", type=ttl, required=True)
         if action in ["resume", "fork"]:
-            command.add_argument("--cpu", type=int, choices=CPU_SIZES)
-            command.add_argument("--memory", choices=MEMORY_SIZES)
+            command.add_argument("--cpu", type=cpu_count)
+            command.add_argument("--memory", type=gib_size)
         if action == "fork":
             command.add_argument("--disposable", action="store_true")
+            note_options(command)
         if action == "exec":
             command.add_argument("--detach", action="store_true")
             command.add_argument("command", nargs="+")
@@ -957,6 +1857,8 @@ def parser():
 
 
 def dispatch(args):
+    if args.action == "self-update":
+        return self_update(args)
     if args.action == "recover":
         recover(args)
         return 0
@@ -966,27 +1868,72 @@ def dispatch(args):
     if args.action == "host":
         host_add(args)
         return 0
+    if args.action == "config":
+        if args.config_action is None:
+            report = {"file": str(DEFAULTS_CONFIG), "defaults": effective_defaults(), "policy": {}}
+            for location in configuration():
+                try:
+                    report["policy"][location] = note_policy(location)
+                except RuntimeError as error:
+                    raise RuntimeError(f"{location}: {error}") from error
+            print(json.dumps(report, indent=2))
+        else:
+            set_default(args.key, args.value if args.config_action == "set" else None)
+        return 0
+    if args.action == "policy":
+        set_policy(args.location, None if args.clear else note_fields(args.require))
+        return 0
     if args.action == "note":
-        set_note(args.location, None if args.clear else args.text)
+        fields = box_note(args)
+        # Location names cannot contain ":", so a colon always means a box handle.
+        if ":" not in args.target:
+            if fields is not None:
+                raise ValueError("--purpose, --owner and --next describe boxes; pass a box handle")
+            if args.clear == (args.text is not None):
+                raise ValueError("Give the location note TEXT or --clear")
+            set_note(args.target, None if args.clear else args.text)
+            return 0
+        if args.text is not None:
+            raise ValueError("Describe boxes with --purpose, --owner and --next")
+        if args.clear == (fields is not None):
+            raise ValueError("Give --purpose (with optional --owner and --next) or --clear")
+        location, name = parse_handle(args.target)
+        instance(location, name)
+        require_note(
+            location,
+            fields,
+            f"note {args.target}",
+            " Clearing would leave the box without them." if args.clear else "",
+        )
+        # Each call replaces the whole note; an empty value removes the key.
+        transaction(
+            location,
+            'note="$2"\n'
+            + READ_NOTE_POLICY
+            + CHECK_NOTE
+            + '\nincus --project raft config set "$1" user.raft.note="$note"',
+            name,
+            "" if args.clear else json.dumps(fields),
+        )
         return 0
     if args.action == "locations":
         for index, (location, entry) in enumerate(configuration().items()):
             record = {"location": location, "default": index == 0, "note": entry.get("note", "")}
             print(json.dumps(record))
         return 0
-    if args.action in ["list", "limits", "doctor", "gc", "prune"]:
+    if args.action in ["list", "capacity", "doctor", "gc", "prune"]:
         if args.action == "prune" and args.older_than < 1:
             raise ValueError("Retention must be at least one day")
         locations = configuration()
         if getattr(args, "location", None):
             locations = [args.location]
         for location in locations:
-            if args.action == "limits":
-                report = host_limits(location)
+            if args.action == "capacity":
+                report = host_capacity(location)
                 if args.json:
                     print(json.dumps(report))
                 else:
-                    print_limits(report)
+                    print_capacity(report)
             elif args.action in ["gc", "prune"]:
                 worker = ["sudo", "-n", "/usr/local/lib/raft/expire"]
                 if args.action == "prune":
@@ -1032,10 +1979,14 @@ def dispatch(args):
                                 "box": location + ":" + box["name"],
                                 "state": box["status"],
                                 "stopAt": box["config"].get("user.raft.expires", ""),
+                                "disk": box_disk(box),
+                                "note": read_box_note(box),
                             }
                         )
                     )
         return 0
+    # Only fork accepts note flags here; check them before contacting the host.
+    fields = box_note(args)
     location, name = parse_handle(args.box)
     box = instance(location, name)
     if args.action == "info":
@@ -1047,7 +1998,12 @@ def dispatch(args):
         response = execute(location, name, ["python3", "-c", USAGE], capture=True)
         if response.returncode:
             raise RuntimeError(response.stderr.decode().strip())
-        print(response.stdout.decode().strip())
+        usage = json.loads(response.stdout)
+        disk = box_disk(box)
+        usage["filesystemScope"] = (
+            "shared Raft pool, not per-box usage" if disk == "shared" else f"own {disk} box disk"
+        )
+        print(json.dumps(usage))
     elif args.action == "destroy":
         incus(location, "delete", name, "--force", locked=True)
         if any(item["name"] == name for item in inventory(location)):
@@ -1071,7 +2027,7 @@ def dispatch(args):
                 overrides.append(f"limits.{field}={value}")
         transaction(
             location,
-            REQUIRE_STOPPED + 'name="$1"; lifetime="$2"; shift 2; '
+            REQUIRE_STOPPED + fits_host(args) + 'name="$1"; lifetime="$2"; shift 2; '
             'if [ "$#" -gt 0 ]; then incus --project raft config set "$name" "$@"; fi; '
             'incus --project raft start "$name"; '
             'incus --project raft config set "$name" user.raft.stopped-at=; '
@@ -1134,7 +2090,9 @@ def dispatch(args):
         print(
             transaction(
                 location,
-                REQUIRE_STOPPED + 'incus --project raft snapshot create "$1" "$2"',
+                REQUIRE_STOPPED
+                + reserve_box_disk(location, None, name)
+                + 'incus --project raft snapshot create "$1" "$2"',
                 name,
                 args.name,
             ).strip()
@@ -1148,6 +2106,9 @@ def dispatch(args):
         snapshot_name(args.name)
         # Imported/forked snapshots carry source configuration. Restore files,
         # keeping the destination's network identity and explicitly chosen limits.
+        # On raft-disks Incus swaps in a thin snapshot of the snapshot for the box's
+        # volume, so a restore needs no reservation: it writes no data, and the
+        # reserved total is unchanged once the old volume is removed.
         transaction(
             location,
             REQUIRE_STOPPED + 'incus --project raft snapshot restore "$1" "$2" --diskonly',
@@ -1155,19 +2116,33 @@ def dispatch(args):
             args.name,
         )
     elif args.action == "fork":
+        # Note flags replace the whole note, as with raft note; without them the
+        # fork keeps the source note, which must then satisfy the host policy.
+        require_note(
+            location,
+            fields or read_box_note(box),
+            f"fork {args.box} --ttl {args.ttl}",
+            "" if fields else " Forks keep the source note unless you give a new one.",
+        )
         child = "rf-" + uuid.uuid4().hex[:16]
         transaction(
             location,
             (CHECK_WORKER if args.disposable else "")
             + REQUIRE_STOPPED
-            + ADMISSION
-            + 'name="$2"; lifetime="$3"; '
-            'source="$1"; shift 3; incus --project raft copy "$source" "$name" --instance-only "$@"; '
+            + fits_host(args)
+            + reserve_box_disk(location, None, name)
+            + 'name="$2"; lifetime="$3"; source="$1"; note="$4"; shift 4\n'
+            # Read the source note under the lock, so the check sees what the copy keeps.
+            'if [ -z "$note" ]; then note=$(incus --project raft config get "$source" user.raft.note); fi\n'
+            + READ_NOTE_POLICY
+            + CHECK_NOTE
+            + '\nincus --project raft copy "$source" "$name" --instance-only "$@" -c user.raft.note="$note"; '
             'incus --project raft start "$name"; '
             'incus --project raft config set "$name" user.raft.expires="$(( $(date +%s) + lifetime ))"',
             name,
             child,
             str(args.ttl),
+            json.dumps(fields) if fields else "",
             "-c",
             "user.raft.expires=",
             "-c",
@@ -1234,8 +2209,11 @@ def main():
         print("raft: Python 3.11.8 or newer is required", file=sys.stderr)
         return 1
     os.umask(0o077)
+    # Parsing exits for --version, --help and usage errors, before any release check.
+    args = parser().parse_args()
+    notice = update_check(args.action, RELEASES_API)
     try:
-        return dispatch(parser().parse_args())
+        status = dispatch(args)
     except (
         OSError,
         ValueError,
@@ -1244,9 +2222,11 @@ def main():
         subprocess.CalledProcessError,
     ) as error:
         print(f"raft: {error}", file=sys.stderr)
-        return 1
+        status = 1
     except KeyboardInterrupt:
         return 130
+    notice()
+    return status
 
 
 if __name__ == "__main__":