@botiverse/testbed-cli 0.5.1 → 0.7.0

package/lib/main.mjs

@@ -34,6 +34,57 @@ export const USAGE = `testbed — cloud phones + the acceptance testbed in the R
   testbed verify login <session-id> --account <account-id>
   testbed verify reinstall <session-id> --apk-key fast/<id> --apk-sha256 HEX
 
+  testbed bed provision [--ttl SEC] [--template ID] [--spec JSON] [--request-id ID]
+                                         create a bed (a Linux VM on exe.dev via the Broker); spec JSON e.g. '{"platform":"linux","labels":{"purpose":"probe"}}'
+  testbed bed list                       your beds
+  testbed bed get <bed-id>
+  testbed bed cleanup <bed-id> [--expected-revision N]
+                                         destroy the bed and prove zero provider residue
+  testbed bed residue <bed-id>           read-only cleanup residue evidence (after tombstone)
+  testbed bed recover <bed-id> [--expected-revision N] [--request-id ID]
+                                         claim cleanup recovery of a bed stuck in cleanup
+  testbed bed reconcile <bed-id>         reconcile a bed stuck in provisioning
+  testbed bed round <bed-id> --argv JSON [--timeout-ms N] [--expected-revision N] [--request-id ID]
+                                         run one command round on the bed (argv as a JSON array)
+  testbed bed report create <bed-id> --name NAME [--description TEXT] [--spec JSON] [--expected-revision N]
+  testbed bed report list <bed-id>
+  testbed bed retention status           retention status across beds
+  testbed bed retention get <bed-id>
+  testbed bed retention retain <bed-id> --finding FINDING_ID --reason TEXT [--ttl SEC] [--identity JSON] [--notify JSON] [--expected-revision N]
+  testbed bed retention renew <bed-id> --reason TEXT [--ttl SEC] [--expected-hold-revision N] [--expected-revision N]
+  testbed bed retention release <bed-id> --disposition TEXT [--export-sha HEX] [--expected-hold-revision N] [--expected-revision N]
+  testbed bed template list | get <id> | save --name NAME [--description TEXT] --spec JSON | delete <id> [--expected-revision N]
+  testbed bed collab list <bed-id>
+  testbed bed collab grant <bed-id> --label LABEL --public-key-file FILE [--ttl SEC] [--expected-revision N] [--request-id ID]
+  testbed bed collab revoke <bed-id> <collaborator-id> [--expected-revision N] [--request-id ID]
+  testbed bed exec start <bed-id> --argv JSON [--timeout-ms N] [--expected-revision N] [--request-id ID]
+                                         long-running command on the bed; returns a job
+  testbed bed exec get <bed-id> <job-id>
+  testbed bed exec cancel <bed-id> <job-id> [--expected-job-revision N] [--request-id ID]
+  testbed bed diagnose <bed-id> <diagnostic-id>
+                                         cleanup diagnostic record
+  testbed bed llm preflight --integration REF
+  testbed bed llm diagnostic --correlation ID
+                                         provider LLM authority preflight / diagnostic (exe.dev integrations)
+
+  testbed pve facts --purpose P          macOS VM (PVE VM130) bridge facts: guest agent, os, baseline revision
+  testbed pve acquire --purpose P [--ttl SEC] [--request-id ID]
+                                         lease the macOS VM (one active lease; ttl 60..3600, default 3600)
+  testbed pve status <lease-id> --epoch N --purpose P
+                                         the adapter's own lease state (independent readback)
+  testbed pve renew <lease-id> --epoch N --purpose P [--ttl SEC] [--request-id ID]
+  testbed pve exec <lease-id> --epoch N --purpose P --argv JSON [--timeout SEC]
+  testbed pve put <lease-id> --epoch N --purpose P --path /remote/file --file LOCAL [--timeout SEC]
+                                         file of at most 15,722,496 bytes (just under 15 MiB; the adapter caps the whole request at 20 MiB)
+  testbed pve get <lease-id> --epoch N --purpose P --path /remote/file [--out LOCAL] [--timeout SEC]
+  testbed pve reboot <lease-id> --epoch N --purpose P [--request-id ID]
+  testbed pve rollback <lease-id> --epoch N --purpose P [--request-id ID]
+                                         restore the baseline snapshot (everything after it is discarded)
+  testbed pve release <lease-id> --epoch N --purpose P [--request-id ID]
+                                         end the lease; the adapter ALSO rolls back to baseline
+  testbed pve reap --purpose P [--request-id ID]
+                                         reclaim expired leases
+
   testbed skill                          print the agent skill (SKILL.md)
   testbed skill --install [-a AGENT...] [--global]
                                          install for any runtime via "npx skills add" (Claude Code, Codex, Cursor, Gemini, OpenCode, ...)
@@ -221,6 +272,274 @@ export async function main(argv, opts) {
         emit(d, () => out(JSON.stringify(d, null, 2)));
         return exit(0);
       }
+      case "bed": {
+        // Beds: Linux VMs on exe.dev brokered by the testbed (artin 2026-09-07:
+        // everything an agent does goes through this CLI; the manifest only
+        // advertises agent-login). One subcommand per route; bodies mirror
+        // the route contracts exactly; --help never sends a request.
+        const sub = args.shift();
+        const bedPath = (id) => `/beds/${encodeURIComponent(id)}`;
+        const parseJson = (flag, text) => {
+          if (text === undefined) return undefined;
+          try { return JSON.parse(text); } catch { throw new Error(`--${flag} must be valid JSON`); }
+        };
+        const num = (flag, text) => (text === undefined ? undefined : Number(text));
+        const reqId = () => takeFlag(args, "request-id") ?? `testbed-cli-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+        const bedLine = (b) => `bed ${b.id} — ${b.state}${b.provider_bed_id ? ` (${b.provider} ${b.provider_bed_id})` : ""}${b.expires_at ? `, expires ${new Date(b.expires_at).toISOString().slice(0, 16)}` : ""}`;
+        const opLine = (d, verb) => out(`${verb} ${d.bed?.id ?? d.bed_id ?? d.outcome?.bed ?? ""}: ${d.outcome?.outcome ?? d.operation?.state ?? (d.ok ? "ok" : "failed")}${d.error?.code ? ` (${d.error.code})` : ""}${d.idempotent ? " [idempotent]" : ""}`);
+        switch (sub) {
+          case "provision": {
+            const ttl = takeFlag(args, "ttl"); const template = takeFlag(args, "template"); const spec = parseJson("spec", takeFlag(args, "spec"));
+            const body = { idempotency_key: reqId(), ttl_seconds: num("ttl", ttl), template_id: template, spec: spec ?? (template ? undefined : { platform: "linux" }) };
+            const d = await api("POST", "/beds", body);
+            emit(d, () => { if (d.bed) out(bedLine(d.bed)); opLine(d, "provision"); });
+            return exit(d.ok === false ? 1 : 0);
+          }
+          case "list": {
+            const d = await api("GET", "/beds");
+            emit(d, () => { for (const b of d.beds ?? []) out(bedLine(b)); out(`${d.total ?? (d.beds ?? []).length} bed(s)`); });
+            return exit(0);
+          }
+          case "get": {
+            const id = args[0]; if (!id) throw new Error("usage: testbed bed get <bed-id>");
+            const d = await api("GET", bedPath(id));
+            emit(d, () => out(bedLine(d)));
+            return exit(0);
+          }
+          case "cleanup": {
+            const id = args[0]; if (!id) throw new Error("usage: testbed bed cleanup <bed-id> [--expected-revision N]");
+            const rev = takeFlag(args, "expected-revision");
+            const d = await api("DELETE", bedPath(id), { idempotency_key: reqId(), expected_revision: num("expected-revision", rev) });
+            emit(d, () => opLine(d, "cleanup"));
+            return exit(d.ok === false ? 1 : 0);
+          }
+          case "residue": {
+            const id = args[0]; if (!id) throw new Error("usage: testbed bed residue <bed-id>");
+            const d = await api("GET", `${bedPath(id)}/residue`);
+            emit(d, () => out(`bed ${id}: zero_residue=${d.zero_residue} vm_present=${d.evidence?.provider?.vm_present} serving=${String(d.serving_revision ?? "").slice(0, 12)}`));
+            return exit(d.zero_residue === true ? 0 : 1);
+          }
+          case "recover": {
+            const id = args[0]; if (!id) throw new Error("usage: testbed bed recover <bed-id> [--expected-revision N]");
+            const rev = takeFlag(args, "expected-revision");
+            const d = await api("POST", `${bedPath(id)}/cleanup-recovery-claim`, { idempotency_key: reqId(), expected_revision: num("expected-revision", rev) });
+            emit(d, () => opLine(d, "recover"));
+            return exit(d.ok === false ? 1 : 0);
+          }
+          case "reconcile": {
+            const id = args[0]; if (!id) throw new Error("usage: testbed bed reconcile <bed-id>");
+            const d = await api("POST", `${bedPath(id)}/reconcile`, {});
+            emit(d, () => opLine(d, "reconcile"));
+            return exit(d.ok === false ? 1 : 0);
+          }
+          case "round": {
+            const id = args[0]; if (!id) throw new Error("usage: testbed bed round <bed-id> --argv JSON [--timeout-ms N]");
+            const argv = parseJson("argv", takeFlag(args, "argv")); if (!Array.isArray(argv)) throw new Error("--argv must be a JSON array");
+            const d = await api("POST", `${bedPath(id)}/rounds`, { idempotency_key: reqId(), argv, timeout_ms: num("timeout-ms", takeFlag(args, "timeout-ms")), expected_revision: num("expected-revision", takeFlag(args, "expected-revision")) });
+            emit(d, () => opLine(d, "round"));
+            return exit(d.ok === false ? 1 : 0);
+          }
+          case "report": {
+            const action = args.shift(); const id = args[0];
+            if (action === "create") {
+              if (!id) throw new Error("usage: testbed bed report create <bed-id> --name NAME [--description TEXT] [--spec JSON]");
+              const name = takeFlag(args, "name"); if (!name) throw new Error("usage: --name is required");
+              const d = await api("POST", `${bedPath(id)}/reports`, { name, description: takeFlag(args, "description"), spec: parseJson("spec", takeFlag(args, "spec")), expected_revision: num("expected-revision", takeFlag(args, "expected-revision")) });
+              emit(d, () => out(`report ${d.report?.id ?? ""} created (${d.report?.body_sha256 ?? "no digest"})`));
+              return exit(d.ok === false ? 1 : 0);
+            }
+            if (action === "list") {
+              if (!id) throw new Error("usage: testbed bed report list <bed-id>");
+              const d = await api("GET", `${bedPath(id)}/reports`);
+              emit(d, () => { for (const r of d.reports ?? []) out(`report ${r.id} ${r.name ?? ""}`); out(`${d.total ?? 0} report(s)`); });
+              return exit(0);
+            }
+            throw new Error("usage: testbed bed report create|list …");
+          }
+          case "retention": {
+            const action = args.shift();
+            if (action === "status") { const d = await api("GET", "/retention"); emit(d, () => out(JSON.stringify(d))); return exit(0); }
+            const id = args[0]; if (!id) throw new Error(`usage: testbed bed retention ${action ?? "<get|retain|renew|release>"} <bed-id> …`);
+            const rp = `${bedPath(id)}/retention`;
+            if (action === "get") { const d = await api("GET", rp); emit(d, () => out(JSON.stringify(d.retention ?? d))); return exit(0); }
+            if (action === "retain") {
+              const finding = takeFlag(args, "finding"); const reason = takeFlag(args, "reason");
+              if (!finding || !reason) throw new Error("usage: --finding and --reason are required");
+              const d = await api("POST", rp, { finding_id: finding, reason, ttl_seconds: num("ttl", takeFlag(args, "ttl")), identity: parseJson("identity", takeFlag(args, "identity")), notify_targets: parseJson("notify", takeFlag(args, "notify")), expected_revision: num("expected-revision", takeFlag(args, "expected-revision")) });
+              emit(d, () => out(`retained ${id}: ${JSON.stringify(d.retention ?? d.next_action ?? d.ok)}`));
+              return exit(d.ok === false ? 1 : 0);
+            }
+            if (action === "renew") {
+              const reason = takeFlag(args, "reason"); if (!reason) throw new Error("usage: --reason is required");
+              const d = await api("PATCH", rp, { renewal_reason: reason, ttl_seconds: num("ttl", takeFlag(args, "ttl")), expected_hold_revision: num("expected-hold-revision", takeFlag(args, "expected-hold-revision")), expected_revision: num("expected-revision", takeFlag(args, "expected-revision")) });
+              emit(d, () => out(`renewed ${id}: ${JSON.stringify(d.retention ?? d.ok)}`));
+              return exit(d.ok === false ? 1 : 0);
+            }
+            if (action === "release") {
+              const disposition = takeFlag(args, "disposition"); if (!disposition) throw new Error("usage: --disposition is required");
+              const d = await api("DELETE", rp, { disposition, evidence_export_sha: takeFlag(args, "export-sha"), expected_hold_revision: num("expected-hold-revision", takeFlag(args, "expected-hold-revision")), expected_revision: num("expected-revision", takeFlag(args, "expected-revision")) });
+              emit(d, () => out(`released ${id}: ${JSON.stringify(d.retention ?? d.ok)}`));
+              return exit(d.ok === false ? 1 : 0);
+            }
+            throw new Error("usage: testbed bed retention status|get|retain|renew|release …");
+          }
+          case "template": {
+            const action = args.shift();
+            if (action === "list") { const d = await api("GET", "/templates"); emit(d, () => { for (const t of d.templates ?? []) out(`template ${t.id} ${t.name ?? ""}`); out(`${d.total ?? 0} template(s)`); }); return exit(0); }
+            if (action === "save") {
+              const name = takeFlag(args, "name"); const spec = parseJson("spec", takeFlag(args, "spec"));
+              if (!name || spec === undefined) throw new Error("usage: testbed bed template save --name NAME --spec JSON [--description TEXT]");
+              const d = await api("POST", "/templates", { name, description: takeFlag(args, "description"), spec, expected_revision: num("expected-revision", takeFlag(args, "expected-revision")) });
+              emit(d, () => out(`template ${d.template?.id ?? ""} saved`));
+              return exit(d.ok === false ? 1 : 0);
+            }
+            const id = args[0]; if (!id) throw new Error("usage: testbed bed template get|delete <template-id>");
+            if (action === "get") { const d = await api("GET", `/templates/${encodeURIComponent(id)}`); emit(d, () => out(d.template ? `template ${d.template.id} ${d.template.name ?? ""}` : `template ${id}: deleted`)); return exit(0); }
+            if (action === "delete") { const d = await api("DELETE", `/templates/${encodeURIComponent(id)}`, { expected_revision: num("expected-revision", takeFlag(args, "expected-revision")) }); emit(d, () => out(`template ${id} deleted${d.idempotent ? " [idempotent]" : ""}`)); return exit(d.ok === false ? 1 : 0); }
+            throw new Error("usage: testbed bed template list|get|save|delete …");
+          }
+          case "collab": {
+            const action = args.shift(); const id = args[0]; if (!id) throw new Error("usage: testbed bed collab list|grant|revoke <bed-id> …");
+            const cp = `${bedPath(id)}/collaborators`;
+            if (action === "list") { const d = await api("GET", cp); emit(d, () => out(`${d.total ?? 0} collaborator(s) on ${id}`)); return exit(0); }
+            if (action === "grant") {
+              const label = takeFlag(args, "label"); const keyFile = takeFlag(args, "public-key-file");
+              if (!label || !keyFile) throw new Error("usage: testbed bed collab grant <bed-id> --label LABEL --public-key-file FILE");
+              const publicKey = readFileSync(keyFile, "utf8").trim();
+              const d = await api("POST", cp, { idempotency_key: reqId(), label, public_key: publicKey, ttl_seconds: num("ttl", takeFlag(args, "ttl")), expected_revision: num("expected-revision", takeFlag(args, "expected-revision")) });
+              emit(d, () => out(`collaborator ${d.collaborator?.id ?? ""} ${d.collaborator?.state ?? ""}${d.idempotent ? " [idempotent]" : ""}`));
+              return exit(d.ok === false ? 1 : 0);
+            }
+            if (action === "revoke") {
+              const cid = args[1]; if (!cid) throw new Error("usage: testbed bed collab revoke <bed-id> <collaborator-id>");
+              const d = await api("DELETE", `${cp}/${encodeURIComponent(cid)}`, { idempotency_key: reqId(), expected_revision: num("expected-revision", takeFlag(args, "expected-revision")) });
+              emit(d, () => out(`collaborator ${cid} ${d.collaborator?.state ?? "revoked"}`));
+              return exit(d.ok === false ? 1 : 0);
+            }
+            throw new Error("usage: testbed bed collab list|grant|revoke …");
+          }
+          case "exec": {
+            const action = args.shift(); const id = args[0]; if (!id) throw new Error("usage: testbed bed exec start|get|cancel <bed-id> …");
+            const lp = `${bedPath(id)}/long-executions`;
+            if (action === "start") {
+              const argv = parseJson("argv", takeFlag(args, "argv")); if (!Array.isArray(argv)) throw new Error("--argv must be a JSON array");
+              const d = await api("POST", lp, { idempotency_key: reqId(), argv, timeout_ms: num("timeout-ms", takeFlag(args, "timeout-ms")), expected_revision: num("expected-revision", takeFlag(args, "expected-revision")) });
+              emit(d, () => out(`job ${d.execution?.id ?? ""} ${d.execution?.state ?? ""}`));
+              return exit(0);
+            }
+            const jobId = args[1]; if (!jobId) throw new Error("usage: testbed bed exec get|cancel <bed-id> <job-id>");
+            if (action === "get") { const d = await api("GET", `${lp}/${encodeURIComponent(jobId)}`); emit(d, () => out(`job ${jobId} ${d.execution?.state ?? ""}`)); return exit(d.ok === false ? 1 : 0); }
+            if (action === "cancel") { const d = await api("DELETE", `${lp}/${encodeURIComponent(jobId)}`, { idempotency_key: reqId(), expected_job_revision: num("expected-job-revision", takeFlag(args, "expected-job-revision")) }); emit(d, () => out(`job ${jobId} ${d.execution?.state ?? "cancelled"}`)); return exit(0); }
+            throw new Error("usage: testbed bed exec start|get|cancel …");
+          }
+          case "diagnose": {
+            const id = args[0]; const diag = args[1]; if (!id || !diag) throw new Error("usage: testbed bed diagnose <bed-id> <diagnostic-id>");
+            const d = await api("GET", `${bedPath(id)}/cleanup-diagnostics/${encodeURIComponent(diag)}`);
+            emit(d, () => out(JSON.stringify(d.diagnostic ?? d)));
+            return exit(0);
+          }
+          case "llm": {
+            const action = args.shift();
+            if (action === "preflight") { const ref = takeFlag(args, "integration"); if (!ref) throw new Error("usage: testbed bed llm preflight --integration REF"); const d = await api("POST", "/provider-llm/authority", { integration_ref: ref }); emit(d, () => out(JSON.stringify(d.integration ?? d))); return exit(d.ok === false ? 1 : 0); }
+            if (action === "diagnostic") { const cid = takeFlag(args, "correlation"); if (!cid) throw new Error("usage: testbed bed llm diagnostic --correlation ID"); const d = await api("POST", "/provider-llm/authority-diagnostic", { correlation_id: cid }); emit(d, () => out(JSON.stringify(d.diagnostic ?? d))); return exit(0); }
+            throw new Error("usage: testbed bed llm preflight|diagnostic …");
+          }
+          default:
+            throw new Error("usage: testbed bed provision|list|get|cleanup|residue|recover|reconcile|round|report|retention|template|collab|exec|diagnose|llm …");
+        }
+      }
+      case "pve": {
+        // macOS VM lease on Proxmox (VM130) through the Worker's pve-macos
+        // routes (task #42, replaces PR #114). Same rule as beds: CLI only,
+        // nothing in the manifest. The Worker signs every adapter call with
+        // its own credential; the agent never sees the bridge, its token or
+        // a host command. `--purpose` is explicit on every call because the
+        // provider gate is purpose-based (quarantine accepts exactly one).
+        const sub = args.shift();
+        const base = "/pve-macos";
+        const parseJson = (flag, text) => {
+          if (text === undefined) return undefined;
+          try { return JSON.parse(text); } catch { throw new Error(`--${flag} must be valid JSON`); }
+        };
+        const num = (flag, text) => (text === undefined ? undefined : Number(text));
+        const reqId = () => takeFlag(args, "request-id") ?? `testbed-cli-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+        const purpose = () => { const p = takeFlag(args, "purpose"); if (!p) throw new Error(`usage: testbed pve ${sub} … --purpose P (required; the provider gate is purpose-based)`); return p; };
+        const leaseRef = (usage) => {
+          const id = args[0]; const epoch = takeFlag(args, "epoch");
+          if (!id || epoch === undefined) throw new Error(usage);
+          args.shift();
+          return { lease_id: id, epoch: Number(epoch) };
+        };
+        const leaseLine = (l) => (l ? `lease ${l.lease_id} epoch ${l.epoch} — ${l.state}${l.resource_id ? ` on ${l.resource_id}` : ""}${l.expires_at ? `, expires ${l.expires_at}` : ""}` : "");
+        const q = (obj) => "?" + Object.entries(obj).filter(([, v]) => v !== undefined).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join("&");
+        switch (sub) {
+          case "facts": {
+            const d = await api("GET", `${base}/facts${q({ purpose: purpose() })}`);
+            emit(d, () => out(`${d.resource_id ?? "vm"}: ${d.os ?? "?"} ${d.arch ?? ""} guest_agent=${d.guest_agent ?? "?"} baseline=${d.baseline_revision ?? "?"}${d.boot_id ? ` boot=${d.boot_id}` : ""}`));
+            return exit(0);
+          }
+          case "acquire": {
+            const ttl = takeFlag(args, "ttl");
+            const body = { purpose: purpose(), ttl_seconds: num("ttl", ttl), request_id: reqId() };
+            const d = await api("POST", `${base}/acquire`, body);
+            emit(d, () => out(leaseLine(d.lease ?? d)));
+            return exit(0);
+          }
+          case "status": {
+            const ref = leaseRef("usage: testbed pve status <lease-id> --epoch N --purpose P");
+            const d = await api("GET", `${base}/lease-status${q({ lease_id: ref.lease_id, epoch: ref.epoch, purpose: purpose() })}`);
+            emit(d, () => out(leaseLine(d.lease ?? d)));
+            return exit(0);
+          }
+          case "renew": {
+            const ref = leaseRef("usage: testbed pve renew <lease-id> --epoch N --purpose P [--ttl SEC]");
+            const ttl = takeFlag(args, "ttl");
+            const d = await api("POST", `${base}/renew`, { purpose: purpose(), ...ref, ttl_seconds: num("ttl", ttl), request_id: reqId() });
+            emit(d, () => out(leaseLine(d.lease ?? d)));
+            return exit(0);
+          }
+          case "exec": {
+            const ref = leaseRef("usage: testbed pve exec <lease-id> --epoch N --purpose P --argv JSON [--timeout SEC]");
+            const argv = parseJson("argv", takeFlag(args, "argv")); const timeout = takeFlag(args, "timeout");
+            if (!Array.isArray(argv) || argv.length === 0) throw new Error("--argv must be a non-empty JSON array of strings");
+            const d = await api("POST", `${base}/exec`, { purpose: purpose(), ...ref, argv, timeout_seconds: num("timeout", timeout), request_id: reqId() });
+            emit(d, () => { if (d.stdout) out(d.stdout.replace(/\n$/, "")); if (d.stderr) err(d.stderr.replace(/\n$/, "")); out(`exit ${d.exit_code}${d.timed_out ? " (timed out)" : ""}`); });
+            return exit(typeof d.exit_code === "number" && d.exit_code !== 0 ? 1 : 0);
+          }
+          case "put": {
+            const ref = leaseRef("usage: testbed pve put <lease-id> --epoch N --purpose P --path /remote/file --file LOCAL [--timeout SEC]");
+            const remote = takeFlag(args, "path"); const file = takeFlag(args, "file"); const timeout = takeFlag(args, "timeout");
+            if (!remote || !file) throw new Error("usage: testbed pve put <lease-id> --epoch N --purpose P --path /remote/file --file LOCAL");
+            const data = readFileSync(file);
+            const d = await api("POST", `${base}/put`, { purpose: purpose(), ...ref, path: remote, data_base64: data.toString("base64"), timeout_seconds: num("timeout", timeout), request_id: reqId() });
+            emit(d, () => out(`put ${remote}: ${data.length} bytes${d.sha256 ? ` sha256=${d.sha256}` : ""}`));
+            return exit(0);
+          }
+          case "get": {
+            const ref = leaseRef("usage: testbed pve get <lease-id> --epoch N --purpose P --path /remote/file [--out LOCAL] [--timeout SEC]");
+            const remote = takeFlag(args, "path"); const outFile = takeFlag(args, "out"); const timeout = takeFlag(args, "timeout");
+            if (!remote) throw new Error("usage: testbed pve get <lease-id> --epoch N --purpose P --path /remote/file [--out LOCAL]");
+            const d = await api("POST", `${base}/get`, { purpose: purpose(), ...ref, path: remote, timeout_seconds: num("timeout", timeout), request_id: reqId() });
+            const bytes = Buffer.from(d.data ?? "", "base64");
+            if (outFile) { writeFileSync(outFile, bytes); emit(d, () => out(`get ${remote}: ${bytes.length} bytes → ${outFile}${d.sha256 ? ` sha256=${d.sha256}` : ""}`)); }
+            else emit(d, () => out(bytes.toString("utf8")));
+            return exit(0);
+          }
+          case "reboot": case "rollback": case "release": {
+            const ref = leaseRef(`usage: testbed pve ${sub} <lease-id> --epoch N --purpose P`);
+            const d = await api("POST", `${base}/${sub}`, { purpose: purpose(), ...ref, request_id: reqId() });
+            emit(d, () => out(`${sub} ${ref.lease_id} epoch ${ref.epoch}: ${d.ok === false ? "failed" : "ok"}${d.lease?.state ? ` (${d.lease.state})` : ""}`));
+            return exit(d.ok === false ? 1 : 0);
+          }
+          case "reap": {
+            const d = await api("POST", `${base}/reap-expired`, { purpose: purpose(), request_id: reqId() });
+            emit(d, () => out(`reap-expired: ${d.reaped ?? d.count ?? "ok"}`));
+            return exit(0);
+          }
+          default:
+            throw new Error("usage: testbed pve facts|acquire|status|renew|exec|put|get|reboot|rollback|release|reap …");
+        }
+      }
       case "verify": {
         const sub = args.shift();
         const vs = (id) => `/verify-sessions/${encodeURIComponent(id)}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/testbed-cli",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "CLI for testbed \u2014 cloud phones and the acceptance testbed in the Raft release loop",
   "license": "MIT",
   "type": "module",

package/skills/testbed/SKILL.md

@@ -72,6 +72,36 @@ Device safety (non-negotiable):
 - Cloud-phone screenshots can return a stale frame: to prove "nothing changed", the
   capture must include something that would have changed if it were live.
 
+## Beds (Linux VMs on exe.dev)
+
+A bed is a throwaway Linux VM the testbed brokers on exe.dev. Everything is `testbed bed …`; the Raft manifest advertises nothing for beds.
+
+```bash
+testbed bed provision --ttl 900 --spec '{"platform":"linux","labels":{"purpose":"probe"}}'   # → bed id, state ready when the VM is up
+testbed bed list | testbed bed get <bed-id>
+testbed bed round <bed-id> --argv '["uname","-a"]'            # one command round
+testbed bed exec start <bed-id> --argv '["./long.sh"]'        # long job → job id; exec get/cancel
+testbed bed collab grant <bed-id> --label me --public-key-file ~/.ssh/id_ed25519.pub   # SSH access; the key never leaves the file
+testbed bed cleanup <bed-id>                                  # destroy; then `bed residue <bed-id>` proves zero provider residue
+```
+Rules: always `cleanup` what you `provision` (TTL is a backstop, not a plan); `residue` is the proof, not the destroy call; `--request-id` makes provision/round/exec/collab idempotent on retry; reports, retention and templates exist for evidence handling and are documented in `testbed bed --help`.
+
+## macOS VM (PVE VM130 lease)
+
+One macOS VM on Proxmox, leased through the testbed; the Worker signs every adapter call with its own credential, so you never see the bridge, its token or a host command. Everything is `testbed pve …`; the manifest advertises nothing for it. `--purpose` is required on every call: while the provider is in quarantine the only accepted value is `task-9-universal-lease-v0.1-acceptance`.
+
+```bash
+P=task-9-universal-lease-v0.1-acceptance
+testbed pve facts --purpose $P                                  # guest agent, os, baseline revision
+testbed pve acquire --purpose $P --ttl 3600                     # → lease id + epoch (one active lease)
+testbed pve status <lease-id> --epoch N --purpose $P            # the adapter's own view, not the Worker's
+testbed pve exec <lease-id> --epoch N --purpose $P --argv '["uname","-a"]'
+testbed pve put <lease-id> --epoch N --purpose $P --path /tmp/x --file ./x
+testbed pve get <lease-id> --epoch N --purpose $P --path /tmp/x --out ./x.back
+testbed pve release <lease-id> --epoch N --purpose $P           # ends the lease AND rolls back to baseline
+```
+Rules: `put` carries at most 15,722,496 bytes per file (just under 15 MiB: the adapter caps the whole request, data base64-encoded plus metadata, at 20 MiB; the Worker refuses larger requests with 413 before sending). TTL is 60..3600 s. `release` and `rollback` restore the baseline snapshot, so anything written after it is gone — copy out what you need first. Wrong owner/epoch/expired are typed refusals from the adapter, relayed verbatim. `--request-id` makes acquire/renew/exec/put/reboot/rollback/release idempotent on retry.
+
 ## Errors
 
 - `401` → `testbed login` (agent) or check `TESTBED_TOKEN` (human/CI).