@botiverse/testbed-cli 0.5.0 → 0.6.0

package/lib/main.mjs

@@ -15,8 +15,10 @@ export const USAGE = `testbed — cloud phones + the acceptance testbed in the R
   testbed whoami                         who the API thinks you are
 
   testbed pool                           warm-pool devices and free/leased state
-  testbed acquire [--ttl MIN] [--instance ID] [--request-id ID] [--key-out FILE]
-                                         lease a phone; the ADB private key goes to --key-out (0600) or --json
+  testbed acquire [--ttl MIN] [--instance ID] [--request-id ID] [--key-out FILE] [--wait-ms N]
+                                         lease a phone; waits through in_flight (same request id) up to --wait-ms (90000);
+                                         the ADB private key goes to --key-out (0600) or --json
+  testbed <command> --help                usage only — never sends a request
   testbed devices                        your leases
   testbed renew <lease-id> [--ttl MIN]
   testbed release <lease-id>
@@ -32,6 +34,39 @@ 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 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, ...)
@@ -95,6 +130,10 @@ export async function main(argv, opts) {
   const env = opts.env ?? process.env;
   const exit = opts.exit ?? ((code) => process.exit(code));
   const json = takeSwitch(args, "json");
+  // `--help` / `-h` anywhere prints usage and NEVER reaches the API. 2026-09-05:
+  // `testbed acquire --help` acquired a device (HuaTuo) because flags were
+  // only consumed by the command that expected them.
+  if (args.includes("--help") || args.includes("-h")) { out(USAGE); return exit(0); }
   const cmd = args.shift();
   const emit = (data, human) => { if (json) out(JSON.stringify(data, null, 2)); else human(); };
 
@@ -148,11 +187,24 @@ export async function main(argv, opts) {
         const body = {};
         if (ttl !== undefined) body.ttl_minutes = Number(ttl);
         if (instance) body.instance_id = instance;
-        if (requestId) body.request_id = requestId;
-        const d = await api("POST", "/device-broker/leases", body);
-        if (d.status === "in_flight") {
-          emit(d, () => out(`in_flight: request ${d.request_id} on ${d.instance_id ?? "?"} — retry acquire with --request-id ${d.request_id}`));
-          return exit(2);
+        // Always send a request id so a retry never takes a second device: the
+        // broker answers 202 in_flight (retryable) while it is still preparing
+        // the lease, and the SAME request id retried returns the acquired lease
+        // with its one-time key. 2026-09-05 (HuaTuo): the old CLI printed the
+        // in_flight receipt and exited 2, leaving a lease held with no key.
+        body.request_id = requestId ?? `testbed-cli-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+        const waitMs = Number(takeFlag(args, "wait-ms", "90000"));
+        const sleep = opts.sleepImpl ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        const started = Date.now();
+        let d = await api("POST", "/device-broker/leases", body);
+        while (d.status === "in_flight") {
+          if (Date.now() - started > waitMs) {
+            err(`testbed: acquire still in_flight after ${Math.round(waitMs / 1000)}s (request ${body.request_id}${d.instance_id ? ` on ${d.instance_id}` : ""}); the broker may still hold a lease for this request — run \`testbed devices\` and release it, or retry with --request-id ${body.request_id}`);
+            return exit(2);
+          }
+          if (!json) err(`testbed: in_flight${d.instance_id ? ` on ${d.instance_id}` : ""}, retrying with the same request id…`);
+          await sleep(2000);
+          d = await api("POST", "/device-broker/leases", body);
         }
         let keyPath = null;
         if (keyOut && d.adb_private_key) {
@@ -202,6 +254,182 @@ 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?.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 "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.0",
+  "version": "0.6.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,20 @@ 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`.
+
 ## Errors
 
 - `401` → `testbed login` (agent) or check `TESTBED_TOKEN` (human/CI).