@microck/raft 0.6.0 → 0.7.0

package/raft_run.py

@@ -0,0 +1,330 @@
+"""One-shot CI orchestration; guests are disposable containers, not registered runners."""
+
+import argparse
+import os
+from pathlib import Path, PurePosixPath
+import signal
+import re
+import shlex
+import subprocess
+import sys
+import time
+from types import SimpleNamespace
+import uuid
+
+import raft_output
+
+GRACE = 30
+LEASE_MARGIN = 120
+
+# Host-only state. /run is cleared on reboot, when queued SSH processes also die.
+# Never put root-created markers in world-writable /run/lock or follow symlinks.
+CANCELLATIONS = """import os, re, stat, sys
+CANCEL_ROOT = "/run/raft-ci-cancelled"
+def cancel_directory(create=False):
+    if create:
+        try:
+            os.mkdir(CANCEL_ROOT, 0o700)
+        except FileExistsError:
+            pass
+    try:
+        directory = os.open(CANCEL_ROOT, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    except FileNotFoundError:
+        if create:
+            raise
+        return None
+    metadata = os.fstat(directory)
+    if metadata.st_uid != os.geteuid() or stat.S_IMODE(metadata.st_mode) != 0o700:
+        os.close(directory)
+        raise RuntimeError('Unsafe CI cancellation directory; refusing to use it')
+    return directory
+
+def cancellation(token, record=False):
+    if not re.fullmatch('[a-f0-9]{32}', token):
+        raise ValueError('Invalid CI run identity')
+    directory = cancel_directory(record)
+    if directory is None:
+        return False
+    try:
+        if record:
+            try:
+                marker = os.open(token, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+                                 0o600, dir_fd=directory)
+            except FileExistsError:
+                pass
+            else:
+                os.close(marker)
+        try:
+            os.stat(token, dir_fd=directory, follow_symlinks=False)
+            return True
+        except FileNotFoundError:
+            return False
+    finally:
+        os.close(directory)
+"""
+
+CHECK_CANCELLED = (
+    CANCELLATIONS
+    + """
+if cancellation(sys.argv[1]):
+    sys.exit('CI run was cancelled before creation')
+"""
+)
+
+
+def creation_guard(token):
+    if not re.fullmatch("[a-f0-9]{32}", token):
+        raise ValueError("Invalid CI run identity")
+    return shlex.join(["python3", "-c", CHECK_CANCELLED, token]) + "\n"
+
+
+# The caller holds the existing host lifecycle lock around this entire program.
+CLEANUP = (
+    CANCELLATIONS
+    + """import json, subprocess, sys
+name, token, creation = sys.argv[1:]
+if creation not in ("pending", "acknowledged"):
+    sys.exit("Invalid CI creation state")
+if creation == "pending":
+    cancellation(token, record=True)
+def boxes():
+    result = subprocess.run(['incus', '--project', 'raft', 'list', name, '--format', 'json'],
+                            check=True, stdout=subprocess.PIPE)
+    return [box for box in json.loads(result.stdout) if box['name'] == name]
+found = boxes()
+if not found:
+    sys.exit(0)
+config = found[0].get('config', {})
+if len(found) != 1 or config.get('user.raft') != 'true' or config.get('user.raft.run') != token:
+    sys.exit('Refusing cleanup: box ownership does not match this run')
+subprocess.run(['incus', '--project', 'raft', 'delete', name, '--force'], check=True)
+if boxes():
+    sys.exit('Run cleanup deletion was not confirmed')
+"""
+)
+
+
+class Stopped(Exception):
+    def __init__(self, status, message):
+        super().__init__(message)
+        self.status = status
+
+
+def timeout_seconds(value):
+    seconds = int(value)
+    if not 1 <= seconds <= 2592000 - LEASE_MARGIN:
+        raise argparse.ArgumentTypeError("Timeout must be 1 second to 30 days minus 120 seconds")
+    return seconds
+
+
+def add_options(command):
+    command.add_argument(
+        "--timeout",
+        type=timeout_seconds,
+        default=600,
+        help="Total setup/upload/command deadline in seconds (default: 600)",
+    )
+    upload = command.add_mutually_exclusive_group()
+    upload.add_argument(
+        "--push",
+        metavar="DIRECTORY",
+        help="Upload Git-tracked and unignored files; exclude .git; reject submodules",
+    )
+    upload.add_argument(
+        "--push-all",
+        metavar="DIRECTORY",
+        help="Explicitly upload the entire tree, including hidden and ignored files",
+    )
+    command.add_argument(
+        "--cwd", help="Guest working directory (upload: /workspace/project; otherwise /workspace)"
+    )
+    command.add_argument(
+        "--pull",
+        nargs=2,
+        action="append",
+        default=[],
+        metavar=("GUEST_DIRECTORY", "NEW_LOCAL_DIRECTORY"),
+        help="Collect a directory before cleanup, including after a failed command",
+    )
+    command.add_argument(
+        "command", nargs=argparse.REMAINDER, help="Command argv after --; not a shell string"
+    )
+
+
+def guest_path(value):
+    path = PurePosixPath(value)
+    if not path.is_absolute() or ".." in path.parts or "\0" in value:
+        raise ValueError("Guest paths must be absolute and contain no '..' or NUL")
+    return str(path)
+
+
+def git_files(source, *, all_option="--push-all"):
+    """Fail closed on Git errors; do not accidentally upload an ignored credential."""
+
+    def git(*arguments):
+        result = subprocess.run(
+            ["git", "-C", str(source), *arguments], stdout=subprocess.PIPE, stderr=subprocess.PIPE
+        )
+        if result.returncode:
+            raise ValueError(
+                f"Git-filtered source requires a readable Git working tree; use {all_option} only "
+                "after checking the entire tree for secrets: "
+                + result.stderr.decode(errors="replace").strip()
+            )
+        return result.stdout
+
+    if git("rev-parse", "--is-inside-work-tree").strip() != b"true":
+        raise ValueError("Git-filtered source requires a Git working tree")
+    for record in git("ls-files", "--stage", "-z", "--", ".").split(b"\0"):
+        if record.startswith(b"160000 "):
+            raise ValueError(
+                "Git-filtered source does not copy submodules; stage their contents explicitly"
+            )
+    paths = git("ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", ".")
+    return {
+        os.fsdecode(path)
+        for path in paths.split(b"\0")
+        if path and ".git" not in PurePosixPath(os.fsdecode(path)).parts
+    }
+
+
+def run(args, api):
+    command = args.command[1:] if args.command[:1] == ["--"] else args.command
+    if not command or any("\0" in value for value in command):
+        raise ValueError("run requires a command after --, without NUL characters")
+    source = (
+        Path(args.push or args.push_all).resolve(strict=True)
+        if args.push or args.push_all
+        else None
+    )
+    if source is not None and not source.is_dir():
+        raise ValueError("Upload source must be a directory")
+    cwd = guest_path(args.cwd or ("/workspace/project" if source else "/workspace"))
+    pulls = []
+    destinations = set()
+    for remote, local in args.pull:
+        destination = Path(local).absolute()
+        destination = destination.parent.resolve(strict=True) / destination.name
+        if os.path.lexists(destination) or destination in destinations:
+            raise ValueError("Each pull destination must be a new path: " + str(destination))
+        destinations.add(destination)
+        pulls.append((guest_path(remote), str(destination)))
+    args.disposable = True
+    args.ttl = args.timeout + LEASE_MARGIN
+    token = uuid.uuid4().hex
+    allocated = None
+    started = False
+    creation_acknowledged = False
+    status = 1
+    phase = "job"
+    began = time.monotonic()
+    signals = (signal.SIGINT, signal.SIGTERM, signal.SIGALRM)
+    previous = {number: signal.getsignal(number) for number in signals}
+    old_timer = signal.getitimer(signal.ITIMER_REAL)
+    if old_timer[0]:
+        raise RuntimeError("run cannot replace an existing process alarm")
+
+    def stop(number, _frame):
+        if number == signal.SIGALRM:
+            raise Stopped(124, f"{phase} deadline exceeded")
+        raise Stopped(128 + number, f"interrupted by signal {number}")
+
+    def record(location, name):
+        nonlocal allocated
+        allocated = (location, name)
+        print(f"raft run: allocated {location}:{name}", file=sys.stderr, flush=True)
+
+    def issue(error):
+        nonlocal status
+        raft_output.error("operation", error, prefix="raft run")
+        if status == 0:
+            status = 1
+
+    try:
+        for number in signals:
+            signal.signal(number, stop)
+        signal.setitimer(signal.ITIMER_REAL, args.timeout)
+        try:
+            include = git_files(source) if args.push else None
+            api.new(args, run_id=token, on_allocate=record)
+            creation_acknowledged = True
+            location, name = allocated
+            while api.execute(location, name, ["true"], capture=True).returncode:
+                time.sleep(0.2)
+            if source:
+                api.transfer_tree(
+                    SimpleNamespace(
+                        action="upload", source=source, destination=cwd, include=include
+                    ),
+                    location,
+                    name,
+                )
+            started = True
+            result = api.execute(location, name, command, cwd=cwd)
+            status = result.returncode if result.returncode >= 0 else 128 - result.returncode
+        except Stopped as error:
+            status = error.status
+            issue(error)
+        except KeyboardInterrupt:
+            status = 130
+            issue("interrupted")
+        except Exception as error:
+            issue(error)
+        finally:
+            signal.setitimer(signal.ITIMER_REAL, 0)
+            # A repeated cancellation cannot interrupt the bounded cleanup grace.
+            signal.signal(signal.SIGINT, signal.SIG_IGN)
+            signal.signal(signal.SIGTERM, signal.SIG_IGN)
+            if allocated is not None:
+                location, name = allocated
+                try:
+                    if started and pulls:
+                        phase = "artifact collection"
+                        signal.setitimer(signal.ITIMER_REAL, GRACE)
+                        try:
+                            for remote, local in pulls:
+                                try:
+                                    api.transfer_tree(
+                                        SimpleNamespace(
+                                            action="download", source=remote, destination=local
+                                        ),
+                                        location,
+                                        name,
+                                    )
+                                except Stopped:
+                                    raise
+                                except Exception as error:
+                                    issue(f"could not collect {remote}: {error}")
+                        except Stopped as error:
+                            issue(error)
+                        finally:
+                            signal.setitimer(signal.ITIMER_REAL, 0)
+                finally:
+                    phase = "cleanup"
+                    signal.setitimer(signal.ITIMER_REAL, GRACE)
+                    try:
+                        api.transaction(
+                            location,
+                            'exec python3 -c "$4" "$1" "$2" "$3"',
+                            name,
+                            token,
+                            "acknowledged" if creation_acknowledged else "pending",
+                            CLEANUP,
+                        )
+                        print(f"raft run: cleanup confirmed for {location}:{name}", file=sys.stderr)
+                    except Exception as error:
+                        issue(
+                            f"cleanup not confirmed for {location}:{name}: {error}; inspect this handle. "
+                            "The host expiry worker is the backstop, not proof of deletion."
+                        )
+                    finally:
+                        signal.setitimer(signal.ITIMER_REAL, 0)
+    finally:
+        signal.setitimer(signal.ITIMER_REAL, 0)
+        for number, handler in previous.items():
+            signal.signal(number, handler)
+        signal.setitimer(signal.ITIMER_REAL, *old_timer)
+    print(
+        f"raft run: finished in {time.monotonic() - began:.1f}s (status {status})", file=sys.stderr
+    )
+    return status

package/skills/raft-cli/SKILL.md

@@ -1,203 +1,84 @@
 ---
 name: raft-cli
-description: Create and use private persistent Linux workspaces on configured Linux hosts with Raft and Incus. Use for self-hosted builds, tests, terminals, Docker, file transfer, snapshots, and private desktop access. Hosted Boat uses its separate boat-cli skill.
+description: Create and operate private Linux workspaces with Raft. Discover the installed CLI, host policies and guest tools before choosing commands for builds, tests, files, jobs or desktop access. Hosted Boat uses its separate skill.
 ---
 
 # Raft
 
-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.
-
-`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.
-
-Do not run `raft self-update` unless the user asks; an update in the middle of a
-task changes the CLI under it. Report a `raft X is available` stderr notice
-instead of acting on it. For pinned or scripted runs, set
-`RAFT_NO_UPDATE_CHECK=1` to suppress the notice.
-
-Run `raft locations`, `raft config`, `raft doctor` and `raft list` before allocating.
-`raft config` shows the defaults `new` will use on this controller and each
-location's host policies: the box note fields it requires (`require`) and how
-long it keeps stopped boxes (`deleteStoppedAfterHours`, `null` for no limit).
-Follow each location's `note`: the operator uses it to mark preferred hosts and
-hosts to avoid for some work. Pass `--location` explicitly when a note rules out
-the default. Do not change notes unless the user asks; `raft note LOCATION TEXT`
-sets one and `raft note LOCATION --clear` removes it. Keep the exact
-location-qualified handle returned by `new`. There is no implicit current box.
-
-Note every box you create. Box notes follow one template so the next agent can
-tell whether a box is in use:
-
-- `--purpose`: what the box is for (required), e.g. `Integration tests for PR 42`
-- `--owner`: who uses it, e.g. `codex session in ~/work/app`
-- `--next`: what happens next, e.g. `Destroy after the tests pass`
-
-Pass them to `new`, and run `raft note "$box" --purpose ...` when the plan
-changes; each call replaces the whole note. If a command fails with
-`requires --owner (host policy)` or similar, rerun it with the fields it names;
-the error prints the corrected command. Never change or clear a policy with
-`raft policy`, or the defaults with `raft config set/unset`, to get past an
-error or to keep a box from retention; only do so when the user asks. `fork` and `recover` accept the same note
-flags, which replace the whole note on the copy. `raft list` shows every box's
-`note`. Read it before you resume, stop, fork or destroy a box. Treat a box whose
-note names another owner or a job unrelated to your task as not yours. Forks
-keep the source note, so update a fork's note when its job differs.
-
-```sh
-box=$(raft new --location lab --ttl 600 --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"
-```
-
-The default development image has systemd, a guest Docker daemon, Node/npm/pnpm,
-Bun, Deno, Python/pip/venv/uv, Go, Rust, Java, Kotlin, Scala, Ruby, PHP,
-Erlang/Elixir, .NET, R, C/C++ tools, Git, Chromium and FFmpeg. Coding agents are not included in new images; install
-your preferred agent when needed and authenticate separately. Never copy host
-credentials into a box without authorization. Inspect `/opt/raft/` inside the
-box for recorded package versions. Do not assume every language has every
-version manager or that agents have an authenticated account.
-
-Exec passes literal arguments; use `bash -lc` for shell syntax. A failed command
-retains its exit status. `raft ssh "$box"` opens a root terminal through native
-Incus execution over verified host SSH. It does not expose a guest SSH port.
-
-## Sizing boxes
-
-Create the boxes your task needs, sized for the work. Raft has no box count
-limit and no size budget. Decide what the task needs and why, then ask for it:
-
-- `--cpu N`: any whole number of CPUs up to the host's count (default 1). Use
-  more for parallel builds and test suites.
-- `--memory SIZE`: any whole GiB up to the host's RAM, e.g. `8GiB` or `32GiB`
-  (default `2GiB`). Use more for large compiles, browsers or databases.
-- `--disk SIZE`: its own disk, e.g. `30GiB`, instead of the shared 60 GiB pool.
-  The box and Docker inside it cannot write past SIZE, and other boxes cannot
-  take its space. Use it for Docker builds, large datasets or anything that
-  could fill the shared pool. The image needs about 5 GiB, so use at least
-  `8GiB`; 10 GiB or more starts fastest. Only hosts deployed with
-  `--disk-pool` have own disks; elsewhere `--disk` fails and names the command
-  that enables them. Own disks, their snapshots, forks and templates are
-  copy-on-write, so copying one is fast, but each reserves its full size in
-  the pool.
-
-```sh
-box=$(raft new --cpu 4 --memory 16GiB --disk 20GiB --ttl 3600 --purpose "Build and test the monorepo" --owner "codex task 123" --next "Destroy when CI passes")
-```
-
-Built-in defaults are the first configured location, one CPU, 2 GiB RAM, the
-shared pool, a persistent box and 600 seconds; the operator can change them per
-controller, so pass `--location`, `--ttl`, `--cpu`, `--memory` and `--disk`
-(`--disk shared` for the shared pool) when the values matter. `new --from` and `fork` keep the
-source's CPU, RAM and disk instead of any default; each flag overrides only its
-own value. TTL accepts 60 seconds to 30
-days. A request larger than the whole host fails with the host's real size;
-retry with what it reports. If the own-disk pool has too little unreserved
-space for `--disk`, a snapshot or a copy, destroy own-disk boxes or snapshots
-the task no longer needs, or pick a smaller disk or the shared pool.
-`raft list` shows each box's `disk` (`"shared"` or its size).
-
-`raft capacity --location lab --json` is an advisory estimate of host CPU/RAM
-headroom and free disk. It is advice, never a reason to skip creating a box or
-to shrink one below what the task needs. Boxes share host CPUs; an estimate of
-zero means new boxes may run slower, not that they are refused.
-
-## Persistence and cleanup
-
-Persistent boxes stop and retain disk at expiry. `new --disposable` deletes a
-box and its snapshots on stop or expiry. The operator can make disposable the
-default for `new` (`raft config` shows `disposable`); then pass `--persistent`
-for a box you plan to stop and resume, snapshot, fork or back up, because
-stopping a disposable box deletes it. Forks stay persistent unless you pass
-`--disposable`. `raft stop "$box"` releases the
-container's running processes; `raft resume "$box" --ttl 600` starts it again.
-Stop is not pause and does not keep guest RAM allocated. Installed dependencies,
-files and secrets remain on disk. For a temporary run, completion requires
-successful `destroy`, even after command failure. Stop reusable runners when
-finished. Destroy only boxes owned by the current task unless authorized otherwise.
-
-Host systemd timers enforce deadlines every 15 seconds, even when the controller
-is offline. `raft gc` runs those expiry workers manually and deletes expired disposable
-boxes. `raft prune --older-than 7` previews stopped boxes older than seven days;
-`--yes` deletes them. It skips running boxes and boxes without a recorded stop
-time. Never apply prune outside the task-owned scope without explicit permission. A powered-off host enforces expiry when it returns.
-
-A location can also delete boxes that stay stopped longer than its retention,
-`deleteStoppedAfterHours` in `raft config`, with their snapshots. The clock
-starts when the box stops, including a stop by TTL expiry, and resume resets
-it. `raft list` shows each stopped box's `deleteAt` (Unix time, empty when
-nothing is due). Do not rely on a stopped box surviving past it: copy out
-results with `raft download`, or keep the whole box with `raft backup`, before
-then. Snapshots are deleted with the box, so they protect nothing against
-retention. Resume a box only when its task still needs it, not just to reset
-the clock.
-
-Stop a box before a consistent disk snapshot or fork:
-
-```sh
-raft stop "$box"
-raft snapshot "$box" prepared
-raft snapshots "$box"
-copy=$(raft fork "$box" --ttl 600)
-raft restore "$box" prepared
-```
-
-Restore replaces disk contents with the snapshot and retains the destination's
-current instance configuration, including its MAC and resource limits. Use it
-only when the user requested that rollback. A fork copies filesystem data, including any
-credentials installed there. Forks stay on the same host. `new --from "$box/prepared"` starts from a named
-snapshot; `snapshot-delete "$box" prepared` removes it. Resume and fork accept
-optional `--cpu` and `--memory` overrides. Omitted values retain the source limits.
-Forks and `new --from` keep the source's CPU, RAM and disk unless a flag
-overrides them; `new --from "$box/prepared" --disk 60GiB` copies the snapshot onto
-a bigger own disk when a box runs out of space. To spawn many agents from one
-prepared own-disk snapshot, run `new --from` once per agent: each copy is a thin
-snapshot created in seconds.
-Forks default to persistent; use `--disposable` explicitly for temporary clones.
-
-`upload/download --recursive` copy directory trees into new destinations without
-merging or overwriting. They require a running guest with Python 3.11.8+ and
-temporary controller disk space. Escaping links and special files are rejected.
-
-## Long commands and previews
-
-`raft exec "$box" --detach -- <command>` returns a job ID. Use `raft status
-"$box" <job>` and `raft logs "$box" <job>` to inspect its systemd state, exit
-status and output. `raft cancel "$box" <job>` stops the job and its child processes. Stop/destroy
-terminates running jobs; this is not automatic checkpointing of processes.
-`raft extend "$box" --ttl 1800` resets a running box's deadline without
-restarting its work. Use resume for stopped boxes. `raft usage "$box"` reports
-cgroup memory/CPU and disk space; `filesystemScope` says whether that is the
-shared pool or the box's own disk.
-
-`raft forward "$box" --remote 8080 --local 8080` opens a foreground private
-tunnel. `raft desktop "$box" --local 6080` starts the desktop on demand and
-opens its private tunnel. Use the printed localhost address, with `vnc.html`
-for the viewer. Ctrl+C closes the tunnel. The desktop service stays inside the
-box until the box stops or its service is explicitly stopped.
-
-Public hosting, reverse tunnels, browser-only confinement, agent conversation
-orchestration and KVM-backed VMs are not implemented. Agent binaries can be run
-through exec after authorized sign-in. Do not claim `boat prompt` parity.
-
-## Portable backups
-
-Stop before exporting a private archive, including snapshots:
-
-```sh
-raft stop "$box"
-raft backup "$box" ./workspace.tar.gz
-recovered=$(raft recover ./workspace.tar.gz --location second-host)
-raft resume "$recovered" --ttl 600
-```
-
-Recovery creates a fresh stopped handle and clears the inherited deadline. It
-never overwrites another box. A box with its own disk comes back on an own disk
-of the same size, so the destination needs own box disks enabled and room for the
-box and each of its snapshots. Only import trusted Raft exports; archives retain
-native configuration and guest secrets. Store them privately and check free
-space on the controller and destination host. Large backups hold the host
-lifecycle lock and delay expiry checks. A controller crash can leave an owned
-staging archive or imported box; inspect the reported recovery handle before
-cleanup. This is manual recovery, not a scheduled backup service.
+## Discover before choosing a workflow
+
+1. Run `raft --version` and `raft --help`. The installed command tree is the
+   capability source. Do not infer support from Boat, a newer release, or this
+   skill. Never update the CLI merely to make an example work.
+2. Match the task to a command in that help. Read `raft COMMAND --help` and
+   nested help until you reach the operation. Read its arguments, defaults,
+   output and constraints before invoking it. Revisit help when the version
+   changes or the task needs a different operation.
+3. If help cannot answer a material question, inspect the matching installed
+   source or that version's Raft command reference and runtime contract. In a
+   checkout these are `docs/reference/cli.md` and `docs/contract.md`; published
+   sources are at https://github.com/Microck/raft. Current website documentation
+   can describe unreleased code. Report unsupported capabilities instead of
+   inventing flags or silently using native Incus to bypass Raft.
+
+This skill defines the operating procedure. Command help and runtime inspection
+supply the changing feature set, sizes, limits and software inventory.
+
+## Select a host and establish ownership
+
+1. Read `raft locations` for configured hosts and operator notes. Follow those
+   notes when choosing a location; do not change them to fit the task.
+2. Read help for `config`, `capacity`, `doctor` and `list`. Inspect the chosen
+   host's defaults, required note fields, retention, health, capacity and boxes.
+   Use location filtering when supported so an unrelated offline host does not
+   prevent inspection. On older versions without it, report the limitation;
+   do not rewrite the operator's inventory.
+3. Read existing box notes before using a box. A handle or familiar name does
+   not establish ownership. Operate only on task-owned boxes unless authorized
+   otherwise, and keep the exact location-qualified handle returned by creation.
+4. Give each new box a purpose, owner and next action using the flags discovered
+   in help. Update its note when the plan changes. Obey host policy errors;
+   never weaken policy or defaults to get past them.
+5. Size the box for the workload using the host's actual capacity and storage
+   capabilities. Capacity is advice, not a box-count quota. Check free disk
+   before large uploads, builds, snapshots or copies.
+
+## Choose lifecycle and verify work
+
+- For bounded one-shot work, check whether the installed CLI provides a command
+  that owns creation, execution, collection and cleanup. Read its timeout and
+  failure semantics before choosing it. Otherwise manage that lifecycle explicitly.
+- For reusable work, select persistence explicitly and inspect retention.
+  Stopping ends processes; it does not preserve memory. A disposable box can
+  disappear on stop, and a persistent box can expire under stopped-box retention.
+  Snapshots inside a box do not protect it against deletion of that box.
+- Probe the needed guest service after creation; a returned handle does not
+  prove readiness. Inspect tool versions inside the guest and its `/opt/raft/`
+  inventory instead of assuming an image has every compiler, agent or login.
+- Exec takes literal arguments. Use an explicit shell for shell syntax. Preserve
+  the command's exit status and collect artifacts before cleanup, including on
+  failure. After an uncertain transport failure, inspect the exact handle or job
+  before rerunning a payload that might already have executed.
+- For temporary work, confirm destruction even after a failed command. For
+  reusable work, stop when finished and report the handle and retention deadline.
+  An SSH error or an eventual TTL is not proof of immediate cleanup.
+
+## Preserve the boundaries
+
+Raft workspaces are native-architecture containers sharing the host kernel.
+Do not promise VM isolation or cross-architecture execution. Inspect the actual
+runtime before claiming any isolation or resource limit.
+
+Host onboarding, deployment, upgrades and global cleanup affect more than a
+single workspace. Perform them only within explicit authorization; inspect a
+supported dry-run or preview first. Do not change daily-driver hosts or install
+updates as a side effect of an ordinary workspace task.
+
+Snapshots, forks, transfers and backups can carry credentials. Copy only the
+required files and never inject host credentials without authorization. Git
+filtering is not a secret scanner. Import only trusted backups and store them
+privately. Restore only an explicitly requested rollback.
+
+For a tunnel or desktop, follow current help for listener addresses and service
+binding. Report the address actually printed. A private tunnel is not public
+hosting, and closing it does not necessarily stop the guest service.