@microck/raft 0.3.0 → 0.4.0

package/deploy/verify-features.py

@@ -196,7 +196,21 @@ def verify_location_notes():
         ]:
             rejected = cli(*arguments)
             assert rejected.returncode == 1 and error in rejected.stderr, rejected
-        assert cli("note", "lab", "x", "--clear").returncode == 2
+        # Box note mistakes are rejected before any host is contacted.
+        handle = "lab:rf-0123456789abcdef"
+        for arguments, error in [
+            (["note", "lab", "x", "--clear"], "TEXT or --clear"),
+            (["note", "lab"], "TEXT or --clear"),
+            (["note", "lab", "--purpose", "x"], "pass a box handle"),
+            (["note", handle, "x"], "--purpose, --owner and --next"),
+            (["note", handle], "--purpose (with optional"),
+            (["note", handle, "--purpose", "x", "--clear"], "--purpose (with optional"),
+            (["note", handle, "--owner", "agent"], "need --purpose"),
+            (["note", handle, "--purpose", " "], "--purpose cannot be empty"),
+            (["new", "--location", "lab", "--next", "later"], "need --purpose"),
+        ]:
+            rejected = cli(*arguments)
+            assert rejected.returncode == 1 and error in rejected.stderr, (arguments, rejected)
         # Concurrent edits to different locations must all survive.
         many = {f"host{index}": {"ssh": f"host{index}"} for index in range(8)}
         saved = config.read_text()
@@ -429,9 +443,27 @@ def verify(location, isolated_worker=False):
         live.raft("destroy", handle)
         fixtures.remove(handle)
         print(f"{location}: noted new kept stdout to the handle and the note on stderr", flush=True)
-        box = create("--memory", "1GiB")
+        box = create("--memory", "1GiB", "--purpose", " Feature verification ", "--owner", "verify")
+
+        def listed_note(handle):
+            for line in live.raft("list", "--location", location).stdout.splitlines():
+                record = json.loads(line)
+                if record["box"] == handle:
+                    return record["note"]
+            raise AssertionError(f"{handle} missing from list")
+
+        assert listed_note(box) == {"purpose": "Feature verification", "owner": "verify"}
+        # Each note edit replaces the whole note.
+        live.raft("note", box, "--purpose", "Feature verification", "--next", "Destroy at the end")
+        assert listed_note(box) == {"purpose": "Feature verification", "next": "Destroy at the end"}
+        live.raft("note", box, "--clear")
+        assert listed_note(box) is None
+        live.raft("note", box, "--purpose", "Feature verification")
         live.wait_running(box)
         _, name = parse_handle(box)
+        print(
+            f"{location}: box note template, listing, replacement and clearing passed", flush=True
+        )
         with tempfile.TemporaryDirectory(prefix="raft-tree-test-") as work:
             root = Path(work)
             source = root / "source with spaces"
@@ -522,6 +554,7 @@ def verify(location, isolated_worker=False):
             != metadata(box)["config"]["volatile.eth0.hwaddr"]
         )
         assert metadata(template)["config"]["user.raft.disposable"] == "false"
+        assert listed_note(template) is None, "new --from inherited the source note"
         assert metadata(template)["expanded_config"]["limits.cpu"] == "1"
         live.raft("snapshot-delete", box, "prepared")
         assert live.execute(template, "cat", "/workspace/proof") == "original"
@@ -536,6 +569,7 @@ def verify(location, isolated_worker=False):
         fork = live.raft(*fork_args).stdout.strip()
         fixtures.append(fork)
         assert metadata(fork)["expanded_config"]["limits.memory"] == "1GiB"
+        assert listed_note(fork) == {"purpose": "Feature verification"}, "fork lost the note"
         assert metadata(fork)["expanded_config"]["limits.cpu"] == "1"
         assert metadata(box)["expanded_config"]["limits.memory"] == "4GiB"
         if worker:

package/docs/contract.md

@@ -42,6 +42,8 @@ Raft manages persistent unprivileged native-architecture Incus system containers
 
 `raft locations` lists configured locations as JSONL with `location`, `default` and `note` fields without contacting hosts. `raft note LOCATION TEXT` and `raft note LOCATION --clear` edit the optional `note` field in the controller configuration atomically, preserving location order and mode `0600`. Notes are advisory guidance; Raft shows them in `locations`, `limits` and on stderr from `new`, and never enforces them.
 
+Boxes accept an optional note with a fixed template: `purpose` (required), `owner` and `next`, all nonempty strings. `raft new --purpose TEXT [--owner TEXT] [--next TEXT]` and `raft note BOX ...` store it as JSON in the box's `user.raft.note` Incus key; `raft note BOX --clear` removes it. Each edit replaces the whole note. `raft list` reports it as `note`, or `null`. `new` always writes the key, so `new --from` never inherits a snapshot's note; forks and recovered backups keep it. Box notes are advisory and never change lifecycle policy.
+
 `raft limits [--location NAME] [--json]` inspects hosts without modifying state. It reports effective CPUs, total and available RAM, saved and active box counts, active resource limits, and disk space.
 
 - **Reserve calculations**: Recommends running boxes after reserving 1 CPU and the larger of 2 GiB or 10% host RAM.

package/docs/guides/scripting-ci.mdx

@@ -19,7 +19,7 @@ Raft does not have a global `--json` option. Parse each command's actual format:
 | --- | --- |
 | `new`, `fork`, `recover` | One location-qualified handle |
 | `exec --detach` | One `rfcmd-` job ID |
-| `list` | JSONL: one object per box, with `box`, `state`, `stopAt` |
+| `list` | JSONL: one object per box, with `box`, `state`, `stopAt`, `note` |
 | `info` | One pretty-printed native Incus metadata JSON object |
 | `usage` | One JSON object containing running resource counters |
 | `limits --json` | One JSON object per location (JSONL across multiple hosts) |
@@ -31,7 +31,8 @@ Raft does not have a global `--json` option. Parse each command's actual format:
 | Other inspection/maintenance commands | Human-readable text or no output |
 
 `list` emits nothing when there are no boxes. `stopAt` is the host Unix deadline
-as a string, or an empty string when absent. `info` uses native Incus keys rather
+as a string, or an empty string when absent. `note` is the box note object with
+`purpose` and optional `owner` and `next`, or `null`. `info` uses native Incus keys rather
 than a normalized Raft schema. `usage` includes `memoryBytes`, `memoryLimit`,
 `cpuTime`, `effectiveCpus`, `filesystemUsedBytes`, `filesystemAvailableBytes`, and
 `filesystemScope`; disk values describe the shared pool, not an individual box.

package/docs/operations.mdx

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

package/docs/reference/cli.md

@@ -36,7 +36,7 @@ Workspaces are referenced by location-qualified handles formatted as `<location>
 
 Create and launch a new workspace container.
 
-`raft new [--location LOCATION] [--ttl TTL] [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB,8GiB}] [--disposable] [--from LOCATION:BOX/SNAPSHOT]`
+`raft new [--location LOCATION] [--ttl TTL] [--cpu {1,2}] [--memory {1GiB,2GiB,4GiB,8GiB}] [--disposable] [--from LOCATION:BOX/SNAPSHOT] [--purpose TEXT [--owner TEXT] [--next TEXT]]`
 
 - `--location LOCATION`: Target host location in `~/.config/raft/incus.json`. Defaults to first configured location.
 - `--ttl TTL`: Lifetime in seconds before automatic stop (`60` to `2592000`). Default: `600`.
@@ -45,6 +45,7 @@ Create and launch a new workspace container.
 
 - `--disposable`: Delete the box and snapshots on stop or expiry. Off by default.
 - `--from LOCATION:BOX/SNAPSHOT`: Copy a named snapshot on its source host instead of the configured image. Normal creation sizing applies; the source can be running. Cannot target a different location.
+- `--purpose TEXT`, `--owner TEXT`, `--next TEXT`: Record a [box note](#note). `--owner` and `--next` need `--purpose`. Without them the box starts with no note, including boxes created `--from` a noted snapshot.
 
 Returns the qualified workspace handle. If the location has a note, `new` prints
 it to stderr; stdout still contains only the handle.
@@ -291,14 +292,32 @@ Prints one JSON object per location (JSONL) in configuration order, with
 
 ### `note`
 
-Set or clear operator guidance for a location in `~/.config/raft/incus.json`.
+Set or clear the note of a location or a box.
 
 `raft note LOCATION TEXT`
 `raft note LOCATION --clear`
+`raft note BOX --purpose TEXT [--owner TEXT] [--next TEXT]`
+`raft note BOX --clear`
 
-Notes are advisory. Use them to record which host is preferred or what a host
-should not run. Raft shows notes in `locations`, `limits` and `new` but does not
-enforce them. Empty notes are rejected; use `--clear` to remove one.
+Location notes are operator guidance stored in `~/.config/raft/incus.json`. Use
+them to record which host is preferred or what a host should not run. Raft shows
+them in `locations`, `limits` and `new`.
+
+Box notes tell other agents and people why a box exists. They follow one
+template, stored on the box as JSON in the Incus key `user.raft.note`:
+
+| Field | Meaning | Example |
+| --- | --- | --- |
+| `purpose` (required) | What the box is for | `Integration tests for PR 42` |
+| `owner` | Who uses it | `codex session in ~/work/app` |
+| `next` | What happens to it next | `Destroy after the tests pass` |
+
+Each call replaces the whole note, on running or stopped boxes. `raft list`
+shows it as `note`. Forks and recovered backups keep the source box's note;
+update it if the copy has a different job.
+
+Notes are advisory; Raft never enforces them. Empty values are rejected; use
+`--clear` to remove a note.
 
 ## Host inspection and maintenance commands
 
@@ -325,7 +344,8 @@ List existing workspace containers across configured hosts.
 
 `raft list [--location LOCATION]`
 
-Prints one JSON object per box (JSONL), with `box`, `state`, and `stopAt` fields.
+Prints one JSON object per box (JSONL), with `box`, `state`, `stopAt` and `note` fields.
+`note` is the box note object, or `null` when the box has none.
 An empty inventory prints no records. See [Scripting and CI](../guides/scripting-ci.mdx)
 for output formats, exit codes, readiness, and failure handling.
 

package/docs/releases/0.4.0.md

@@ -0,0 +1,15 @@
+---
+title: Raft 0.4.0
+---
+
+# Raft 0.4.0
+
+- Boxes accept a note that says why they exist, so agents and people can tell which boxes are in use. The note follows one template: `purpose` (required), `owner` and `next`.
+- `raft new --purpose TEXT [--owner TEXT] [--next TEXT]` notes a box when it is created. `raft note BOX --purpose ...` replaces a box's note and `raft note BOX --clear` removes it. `raft note LOCATION ...` still edits location notes.
+- `raft list` adds a `note` field to each box: the note object, or `null`.
+- Forks and recovered backups keep the source box's note. `new --from` starts without one.
+- The `raft-cli` agent skill asks agents to note every box they create and to read notes before resuming, stopping, forking or destroying a box.
+
+Install on Linux with Python 3.11.8+ using `npm install -g @microck/raft@0.4.0`, or install the attached Python wheel. Box notes live in each box's Incus configuration; host workers are unchanged and need no redeployment.
+
+ARM64 and AMD64 development images accompany this release. Verify `SHA256SUMS` before importing an image for your host architecture.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microck/raft",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Self-hosted Linux workspaces powered by Incus, an open-source alternative to boat.dev",
   "license": "MIT",
   "repository": {

package/raft.py

@@ -19,7 +19,7 @@ import uuid
 
 import raft_files
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 CONFIG = Path.home() / ".config/raft/incus.json"
 PROJECT = "raft"
@@ -30,6 +30,9 @@ GIB = 1024**3
 # 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
@@ -113,6 +116,26 @@ 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 receive(command, destination, *, stdin=None):
     """Write streamed bytes in Python: SSH can exit zero after a local write error."""
     with tempfile.TemporaryFile() as errors:
@@ -607,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("/")
@@ -658,6 +682,9 @@ 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),
     )
@@ -849,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__)
@@ -860,12 +900,13 @@ def parser():
     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 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")
+    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(
@@ -967,7 +1008,24 @@ def dispatch(args):
         host_add(args)
         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)
+        # 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()):
@@ -1032,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

@@ -18,8 +18,21 @@ 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"