@microck/raft 0.2.1 → 0.4.0

package/raft.py

@@ -2,6 +2,8 @@
 """Self-hosted persistent Linux workspaces powered by Incus."""
 
 import argparse
+import fcntl
+import importlib.util
 import json
 import os
 from pathlib import Path
@@ -12,15 +14,25 @@ import subprocess
 import sys
 import tempfile
 import tarfile
+import time
 import uuid
 
 import raft_files
 
-__version__ = "0.2.1"
+__version__ = "0.4.0"
 
 CONFIG = Path.home() / ".config/raft/incus.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"]
+# 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
@@ -43,10 +55,12 @@ def configuration():
     if not isinstance(inventory, dict) or not inventory:
         raise ValueError("Configure at least one host in ~/.config/raft/incus.json")
     for location, entry in inventory.items():
-        if not re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9_-]*", location):
+        if not re.fullmatch(LOCATION_NAME, location):
             raise ValueError("Location names must use letters, digits, underscores or hyphens")
         if not isinstance(entry, dict) or not isinstance(entry.get("ssh"), str) or not entry["ssh"]:
             raise ValueError("Each configured location needs a nonempty ssh target")
+        if not isinstance(entry.get("note", ""), str):
+            raise ValueError("Location notes must be strings")
     return inventory
 
 
@@ -57,6 +71,71 @@ def settings(location):
     return inventory[location]
 
 
+def edit_configuration(change):
+    """Apply change(inventory) to the controller configuration and save it."""
+    # main() sets umask 077, so a new configuration directory is private.
+    CONFIG.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:
+        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)
+            return
+        # Key order is preserved because the first location is the default for new.
+        # Replace atomically so an interrupted write cannot truncate the inventory;
+        # NamedTemporaryFile creates the staged file with mode 0600.
+        staged = tempfile.NamedTemporaryFile("w", dir=CONFIG.parent, prefix=".raft-", delete=False)
+        try:
+            with staged:
+                json.dump(inventory, staged, indent=2)
+                staged.write("\n")
+            os.replace(staged.name, CONFIG)
+        finally:
+            # A no-op after a successful replace; removes the file after a failure.
+            Path(staged.name).unlink(missing_ok=True)
+
+
+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():
+        raise ValueError("Use --clear to remove a note")
+
+    def change(inventory):
+        if location not in inventory:
+            raise ValueError(f"Unknown location: {location}")
+        if text is None:
+            inventory[location].pop("note", None)
+        else:
+            inventory[location]["note"] = text.strip()
+
+    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 receive(command, destination, *, stdin=None):
     """Write streamed bytes in Python: SSH can exit zero after a local write error."""
     with tempfile.TemporaryFile() as errors:
@@ -107,6 +186,188 @@ def incus(location, *argv, locked=False):
     return response.stdout.decode()
 
 
+# Read-only probe. It runs through the login shell of any SSH target, including
+# macOS, so each fact degrades to an empty value instead of failing the script.
+# Sizes are printed in KiB because mawk formats large products in exponent form.
+HOST_FACTS = """echo "kernel=$(uname -s)"
+if [ -r /etc/os-release ]; then . /etc/os-release; echo "os=${ID:-}"; echo "version=${VERSION_ID:-}"; fi
+echo "arch=$(dpkg --print-architecture 2>/dev/null)"
+echo "cpus=$(getconf _NPROCESSORS_ONLN 2>/dev/null)"
+echo "memory=$(awk '/^MemTotal:/ {print $2}' /proc/meminfo 2>/dev/null)"
+directory=/var/lib/incus; [ -d "$directory" ] || directory=/var/lib
+echo "disk=$(df -Pk "$directory" 2>/dev/null | awk 'NR == 2 {print $4}')"
+if sudo -n true 2>/dev/null; then echo sudo=yes; else echo sudo=no; fi
+if command -v python3 >/dev/null 2>&1; then echo python3=yes; else echo python3=no; fi
+if sudo -n incus project list --format csv -c n 2>/dev/null | grep -qx raft; then echo deployed=yes; else echo deployed=no; fi
+"""
+
+
+def host_problems(facts):
+    """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":
+        return [
+            f"The target runs {kernel}, not Linux. Raft hosts need Ubuntu 22.04 or 24.04 on "
+            "ARM64 or AMD64. On macOS, run an Ubuntu VM and onboard the VM's SSH target"
+        ]
+    problems = []
+    release = f"{facts.get('os', '')} {facts.get('version', '')}".strip() or "unknown"
+    if facts.get("os") != "ubuntu" or facts.get("version") not in {"22.04", "24.04"}:
+        problems.append(f"Raft hosts need Ubuntu 22.04 or 24.04; found {release}")
+    if facts.get("arch") not in {"arm64", "amd64"}:
+        problems.append(f"Raft hosts need ARM64 or AMD64; found {facts.get('arch') or 'unknown'}")
+    if facts.get("sudo") != "yes":
+        problems.append("Configure passwordless sudo for the SSH user; `sudo -n true` must succeed")
+    if facts.get("python3") != "yes":
+        problems.append("Install python3 on the host")
+    cpus = int(facts.get("cpus") or 0)
+    if cpus < 2:
+        problems.append(f"Raft hosts need at least 2 CPUs; found {cpus}")
+    # MemTotal excludes firmware and kernel reservations: 8 GiB machines report
+    # about 7.7 GiB. The threshold accepts them and rejects 6 GiB machines.
+    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.
+    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")
+    return problems
+
+
+def deploy_module(filename):
+    """Load a host deployment script shipped beside the CLI."""
+    path = Path(__file__).resolve().parent / "deploy" / filename
+    if not path.exists():
+        raise ValueError(
+            "Host onboarding needs the deployment files in the npm package or a source "
+            "checkout; the Python wheel contains only the CLI"
+        )
+    spec = importlib.util.spec_from_file_location("raft_" + path.stem.replace("-", "_"), path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+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
+        )
+    )
+    print("Smoke test box: " + handle, flush=True)
+    name = handle.partition(":")[2]
+    try:
+        # new returns once Incus starts the box, before every guest service is ready.
+        for _ in range(30):
+            if execute(location, name, ["true"], capture=True).returncode == 0:
+                break
+            time.sleep(2)
+        else:
+            raise RuntimeError("Smoke test box did not become command-ready: " + handle)
+    finally:
+        incus(location, "delete", name, "--force", locked=True)
+    print("Smoke test create/exec/destroy passed", flush=True)
+
+
+def host_add(args):
+    """Check, provision and register a new host location, then prove it works."""
+    if not re.fullmatch(LOCATION_NAME, args.location):
+        raise ValueError("Location names must use letters, digits, underscores or hyphens")
+    if CONFIG.exists() and args.location in configuration():
+        raise ValueError(f"{args.location} is already configured; check it with raft doctor")
+    archive = Path(args.image_archive).resolve() if args.image_archive else None
+    if archive is not None and not archive.is_file():
+        raise ValueError(f"Image archive not found: {archive}")
+    deployer = deploy_module("deploy.py")
+    probe = subprocess.run(
+        [
+            "ssh",
+            "-T",
+            "-o",
+            "BatchMode=yes",
+            "-o",
+            "ConnectTimeout=10",
+            args.ssh,
+            shlex.join(["sh", "-c", HOST_FACTS]),
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if probe.returncode:
+        raise RuntimeError(
+            f"Cannot reach {args.ssh} with key-based SSH: {probe.stderr.strip()}\n"
+            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)
+    if problems:
+        raise ValueError(
+            f"{args.ssh} cannot host Raft boxes; nothing was changed:\n- " + "\n- ".join(problems)
+        )
+    architecture = facts["arch"]
+    if args.build:
+        image = f"build a native {architecture} image from Debian 13 on the host"
+    elif archive is not None:
+        image = f"upload and import {archive}"
+    else:
+        image = f"download raft-dev-{architecture}.tar.gz from release {args.image_release} and import it"
+    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"
+        + (
+            "- 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"
+        )
+        + "- 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"
+        "- run doctor and a disposable create/exec/destroy smoke test\n"
+        "SSH configuration, other firewall rules, IP addresses and account passwords are not changed.",
+        flush=True,
+    )
+    if args.dry_run:
+        print("Dry run: nothing was changed")
+        return
+    if not args.yes:
+        if not sys.stdin.isatty():
+            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)
+    if args.build:
+        # A fresh alias avoids refusing to build beside an earlier raft-dev image.
+        alias = "raft-dev-" + uuid.uuid4().hex[:8]
+        fingerprint = deploy_module("build-image.py").build(args.ssh, alias)
+    elif archive is not None:
+        fingerprint = deployer.import_archive(args.ssh, archive, architecture)
+    else:
+        fingerprint = deployer.import_release(args.ssh, args.image_release, architecture)
+
+    def register(inventory):
+        if args.location in inventory:
+            raise ValueError(f"{args.location} was configured while onboarding ran")
+        inventory[args.location] = {"ssh": args.ssh, "image": fingerprint}
+
+    edit_configuration(register)
+    try:
+        doctor(args.location)
+        smoke_test(args.location)
+    except BaseException:
+        # Never leave a plausible-looking but unusable location behind.
+        edit_configuration(lambda inventory: inventory.pop(args.location, None))
+        print(
+            f"Removed {args.location} from {CONFIG}. Host changes remain; a rerun reuses them.",
+            file=sys.stderr,
+        )
+        raise
+    print(f"{args.location} is ready: raft new --location {args.location}")
+
+
 def parse_handle(value):
     location, separator, name = value.partition(":")
     if not separator or not re.fullmatch(r"rf-[a-f0-9]{16}", name):
@@ -177,14 +438,13 @@ def capacity(host, boxes):
     memory_allocated = 0
     for box in active:
         limits = box["expanded_config"]
-        if limits["limits.cpu"] not in {"1", "2"} or limits["limits.memory"] not in {
-            "1GiB",
-            "2GiB",
-            "4GiB",
-        }:
+        if (
+            limits["limits.cpu"] not in {str(cpu) for cpu in CPU_SIZES}
+            or limits["limits.memory"] not in MEMORY_SIZES
+        ):
             raise ValueError("Active box has unsupported sizing; inspect its Incus configuration")
         cpu_allocated += int(limits["limits.cpu"])
-        memory_allocated += int(limits["limits.memory"][0]) * gib
+        memory_allocated += int(limits["limits.memory"].removesuffix("GiB")) * gib
     memory_reserve = max(2 * gib, host["memoryTotalBytes"] // 10)
     cpu_budget = max(0, host["cpus"] - 1)
     memory_budget = max(0, host["memoryTotalBytes"] - memory_reserve)
@@ -198,8 +458,8 @@ def capacity(host, boxes):
     )
     slots = max(0, SAVED_BOX_LIMIT - len(boxes))
     recommendations = []
-    for cpu in [1, 2]:
-        for memory in [1, 2, 4]:
+    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)),
@@ -255,7 +515,11 @@ def host_limits(location):
         text=True,
         check=True,
     )
-    return {"location": location, **capacity(json.loads(response.stdout), inventory(location))}
+    return {
+        "location": location,
+        "note": settings(location).get("note", ""),
+        **capacity(json.loads(response.stdout), inventory(location)),
+    }
 
 
 def print_limits(report):
@@ -266,6 +530,8 @@ def print_limits(report):
         f"{host['memoryTotalBytes'] / gib:.1f} GiB RAM "
         f"({host['memoryAvailableBytes'] / gib:.1f} GiB available)"
     )
+    if report["note"]:
+        print("Note: " + report["note"])
     print(
         f"Saved boxes: {report['savedBoxes']}/{report['savedBoxLimit']} enforced; "
         f"active: {report['activeBoxes']}; free saved slots: {report['savedSlots']}"
@@ -290,6 +556,32 @@ def print_limits(report):
         print("Warning: " + warning)
 
 
+def doctor(location):
+    print(location + ": " + incus(location, "version").strip())
+    try:
+        transaction(location, CHECK_WORKER)
+    except RuntimeError as error:
+        raise RuntimeError(f"{location}: {error}") from error
+    response = subprocess.run(
+        [
+            "ssh",
+            "-T",
+            "-o",
+            "BatchMode=yes",
+            "-o",
+            "ConnectTimeout=10",
+            settings(location)["ssh"],
+            "systemctl is-active incus raft-expire.timer raft-network.service && df -h /",
+        ],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    print(response.stdout.strip())
+    print(incus(location, "storage", "info", "raft-data").strip())
+    print(f"{len(inventory(location))} saved boxes; system containers (shared host kernel)")
+
+
 def transaction(location, script, *arguments, stdout=None):
     # All lifecycle steps in a compound operation share the host expiry lock.
     command = [
@@ -338,6 +630,7 @@ def sizing(args):
 
 
 def new(args):
+    box_fields = box_note(args)
     source = None
     if args.template:
         handle, separator, snapshot = args.template.partition("/")
@@ -358,6 +651,10 @@ def new(args):
             raise ValueError(
                 "Build an image and configure its full immutable fingerprint before creating boxes"
             )
+    note = settings(args.location).get("note")
+    if note:
+        # Stderr keeps stdout limited to the handle for scripts.
+        print(f"{args.location} note: {note}", file=sys.stderr)
     name = "rf-" + uuid.uuid4().hex[:16]
     # Initialize before starting, so a failed start still has its intended policy.
     transaction(
@@ -385,10 +682,13 @@ def new(args):
         "-c",
         f"user.raft.disposable={'true' if args.disposable else 'false'}",
         "-c",
+        # Always set, so a box created from a snapshot never inherits the source note.
+        "user.raft.note=" + (json.dumps(box_fields) if box_fields else ""),
+        "-c",
         "volatile.eth0.hwaddr=",
         *sizing(args),
     )
-    print(f"{args.location}:{name}")
+    return f"{args.location}:{name}"
 
 
 def execute(location, name, command, *, capture=False):
@@ -576,6 +876,19 @@ def ttl(value):
     return seconds
 
 
+def note_options(command):
+    """Add the box note template flags shared by new and note."""
+    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__)
@@ -583,10 +896,39 @@ def parser():
     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=[1, 2], default=1)
-    create.add_argument("--memory", choices=["1GiB", "2GiB", "4GiB"], default="2GiB")
+    create.add_argument("--cpu", type=int, choices=CPU_SIZES, default=1)
+    create.add_argument("--memory", choices=MEMORY_SIZES, default="2GiB")
     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 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(
+        "add", help="Check, provision, register and smoke-test a new host location"
+    )
+    onboard.add_argument("location")
+    onboard.add_argument(
+        "--ssh", required=True, help="Key-based SSH target: user@host or an ~/.ssh/config alias"
+    )
+    source = onboard.add_mutually_exclusive_group()
+    source.add_argument(
+        "--image-release",
+        default="v" + __version__,
+        metavar="TAG",
+        help="Release whose checksummed image to download (default: this CLI's version)",
+    )
+    source.add_argument("--image-archive", metavar="PATH", help="Import a local image archive")
+    source.add_argument("--build", action="store_true", help="Build the image on the host")
+    onboard.add_argument(
+        "--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")
     listing = commands.add_parser("list")
     listing.add_argument("--location")
     limits = commands.add_parser("limits", help="Inspect host capacity and recommended box counts")
@@ -630,8 +972,8 @@ 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=[1, 2])
-            command.add_argument("--memory", choices=["1GiB", "2GiB", "4GiB"])
+            command.add_argument("--cpu", type=int, choices=CPU_SIZES)
+            command.add_argument("--memory", choices=MEMORY_SIZES)
         if action == "fork":
             command.add_argument("--disposable", action="store_true")
         if action == "exec":
@@ -660,7 +1002,35 @@ def dispatch(args):
         recover(args)
         return 0
     if args.action == "new":
-        new(args)
+        print(new(args))
+        return 0
+    if args.action == "host":
+        host_add(args)
+        return 0
+    if args.action == "note":
+        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)
+        # Each call replaces the whole note; an empty value removes the key.
+        value = "" if args.clear else json.dumps(fields)
+        incus(location, "config", "set", name, "user.raft.note=" + value, locked=True)
+        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 == "prune" and args.older_than < 1:
@@ -711,27 +1081,7 @@ def dispatch(args):
                 else:
                     print(output, end="")
             elif args.action == "doctor":
-                print(location + ": " + incus(location, "version").strip())
-                try:
-                    transaction(location, CHECK_WORKER)
-                except RuntimeError as error:
-                    raise RuntimeError(f"{location}: {error}") from error
-                response = subprocess.run(
-                    [
-                        "ssh",
-                        "-T",
-                        settings(location)["ssh"],
-                        "systemctl is-active incus raft-expire.timer raft-network.service && df -h /",
-                    ],
-                    capture_output=True,
-                    text=True,
-                    check=True,
-                )
-                print(response.stdout.strip())
-                print(incus(location, "storage", "info", "raft-data").strip())
-                print(
-                    f"{len(inventory(location))} saved boxes; system containers (shared host kernel)"
-                )
+                doctor(location)
             else:
                 for box in inventory(location):
                     print(
@@ -740,6 +1090,7 @@ def dispatch(args):
                                 "box": location + ":" + box["name"],
                                 "state": box["status"],
                                 "stopAt": box["config"].get("user.raft.expires", ""),
+                                "note": read_box_note(box),
                             }
                         )
                     )

package/skills/raft-cli/SKILL.md

@@ -8,11 +8,31 @@ description: Create and use private persistent Linux workspaces on configured Li
 Raft runs unprivileged native ARM64 or AMD64 Incus system containers. They share the host kernel.
 The current deployment does not implement Incus VMs. Do not describe these boxes as VMs or promise cross-architecture emulation.
 
-Run `raft doctor`, `raft limits` and `raft list` before allocating. Keep the exact
+`raft host add` installs packages and services on a machine. Run it only when the
+user explicitly asks to onboard that host, and show its `--dry-run` plan first.
+
+Run `raft locations`, `raft doctor`, `raft limits` and `raft list` before allocating.
+Follow each location's `note`: the operator uses it to mark preferred hosts and
+hosts to avoid for some work. Pass `--location` explicitly when a note rules out
+the default. Do not change notes unless the user asks; `raft note LOCATION TEXT`
+sets one and `raft note LOCATION --clear` removes it. Keep the exact
 location-qualified handle returned by `new`. There is no implicit current box.
 
+Note every box you create. Box notes follow one template so the next agent can
+tell whether a box is in use:
+
+- `--purpose`: what the box is for (required), e.g. `Integration tests for PR 42`
+- `--owner`: who uses it, e.g. `codex session in ~/work/app`
+- `--next`: what happens next, e.g. `Destroy after the tests pass`
+
+Pass them to `new`, and run `raft note "$box" --purpose ...` when the plan
+changes; each call replaces the whole note. `raft list` shows every box's
+`note`. Read it before you resume, stop, fork or destroy a box. Treat a box whose
+note names another owner or a job unrelated to your task as not yours. Forks
+keep the source note, so update a fork's note when its job differs.
+
 ```sh
-box=$(raft new --location lab --ttl 600)
+box=$(raft new --location lab --ttl 600 --purpose "Run the project tests" --owner "codex task 123" --next "Destroy when the tests finish")
 raft exec "$box" -- timeout 240 bash -lc 'git clone <url> /workspace/project && cd /workspace/project && <test-command>'
 raft download "$box" /workspace/project/report.json ./report.json
 raft destroy "$box"
@@ -32,7 +52,7 @@ Incus execution over verified host SSH. It does not expose a guest SSH port.
 
 Defaults are the first configured location, one CPU, 2 GiB RAM and 600 seconds. TTL accepts 60 seconds
 to 30 days. The controller admits at most four saved boxes per host; stopped
-boxes count because their disk still occupies space. Use `--memory 4GiB`
+boxes count because their disk still occupies space. Use `--memory 4GiB` or `--memory 8GiB`
 and `--cpu 2` when needed. Btrfs bounds workspace storage to a 60 GiB pool per host.
 It does not guarantee strict per-box disk quotas with nested subvolumes. Check host disk before large builds or forks. `raft limits --location lab --json`
 reports CPU/RAM recommendations for all supported sizes, active allocations and