@botiverse/testbed-cli 0.1.0

package/bin/testbed.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// testbed — CLI for https://testbed.botiverse.build (cloud phones + acceptance runs).
+// See lib/main.mjs for the command list.
+//
+// Auth:
+//   inside a managed Raft agent   `testbed login` (no browser; PKCE grant via
+//                                 `raft integration invoke`, session stored per agent)
+//   humans / CI                   TESTBED_TOKEN env (session or deploy token)
+// TESTBED_URL overrides the instance. This default is pinned by
+// scripts/verify-cli-default-origin.mjs and worker/test/raftauth.test.ts — keep the line.
+import { main } from "../lib/main.mjs";
+
+const URL_BASE = process.env.TESTBED_URL || "https://testbed.botiverse.build";
+
+await main(process.argv.slice(2), { urlBase: URL_BASE, urlExplicit: Boolean(process.env.TESTBED_URL) });

package/lib/agent-login.mjs

@@ -0,0 +1,190 @@
+/**
+ * Agent CLI login (RFC 057 contract; testbed instance, ported from the Hands CLI).
+ * The non-interactive `testbed login` used inside a managed Raft agent.
+ *
+ *   1. Generate a PKCE code_verifier locally; send only its S256 challenge to Raft.
+ *   2. Run the EXACT wrapper `$SLOCK_CLI_TRANSPORT_DIR/raft integration invoke
+ *      --service testbed --action agent-login --json` (never PATH `raft`); require
+ *      exit 0; STRICTLY validate the result. Errors carry stable reasons only — never
+ *      raw stdout/stderr/body (which could contain the grant).
+ *   3. Exchange { grant, code_verifier } at the PUBLIC testbed endpoint for a
+ *      raft-cli-agent-session.v1; strictly validate it.
+ *   4. Persist through @botiverse/agent-session-store (atomic, 0600 under 0700 dirs),
+ *      recording the api base so later commands need no config.
+ *
+ * The verifier never reaches Raft, logs, or the store. Only the testbed token is stored.
+ */
+import { spawnSync } from "node:child_process";
+import { randomBytes, createHash } from "node:crypto";
+import { writeAgentSession } from "@botiverse/agent-session-store";
+
+/** The exact installed Raft client key of this service (`raft integration list`). */
+export const TESTBED_SERVICE = "testbed";
+
+function base64url(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** PKCE S256: 64-byte verifier → 86 unreserved base64url chars; challenge = SHA-256. */
+export function generatePkce() {
+  const verifier = base64url(randomBytes(64));
+  const challenge = base64url(createHash("sha256").update(verifier).digest());
+  return { verifier, challenge };
+}
+
+function hasExactKeys(o, keys) {
+  const k = Object.keys(o);
+  return k.length === keys.length && keys.every((key) => Object.prototype.hasOwnProperty.call(o, key));
+}
+
+/** RFC3339 date-time → epoch ms, or null. */
+export function parseRfc3339(s) {
+  if (typeof s !== "string") return null;
+  if (!/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(\.\d+)?(Z|[+-]\d\d:\d\d)$/.test(s)) return null;
+  const t = Date.parse(s);
+  return Number.isFinite(t) ? t : null;
+}
+
+// Server issues expiry = server_now + 300s; allow clock-skew headroom above that.
+const AGENT_GRANT_TTL_CEILING_MS = 300_000 + 120_000;
+
+/**
+ * Strictly validate a `raft integration invoke --action agent-login --json` result:
+ *   { ok:true, data:{ service, action, status, result:{schema,service,grant,expires_at} } }
+ * NO part of stdout is ever echoed in an error.
+ */
+export function parseAgentLoginInvoke(stdout, service, now) {
+  let outer;
+  try { outer = JSON.parse(stdout); } catch { throw new Error("agent-login: `raft integration invoke` did not return JSON"); }
+  if (!outer || typeof outer !== "object") throw new Error("agent-login: invoke output is not an object");
+  if (outer.ok !== true) throw new Error("agent-login: invoke did not succeed");
+  if (!hasExactKeys(outer, ["ok", "data"])) throw new Error("agent-login: invoke envelope has unexpected fields");
+  const data = outer.data;
+  if (!data || typeof data !== "object") throw new Error("agent-login: invoke result is missing data");
+  if (!hasExactKeys(data, ["service", "action", "status", "result"])) throw new Error("agent-login: invoke data has unexpected fields");
+  if (data.service !== service) throw new Error("agent-login: invoke service does not match the requested service");
+  if (data.action !== "agent-login") throw new Error("agent-login: invoke action is not agent-login");
+  if (data.status !== 200) throw new Error("agent-login: agent-login action did not return HTTP 200");
+  const result = data.result;
+  if (!result || typeof result !== "object") throw new Error("agent-login: invoke result is missing the grant body");
+  if (!hasExactKeys(result, ["schema", "service", "grant", "expires_at"])) throw new Error("agent-login: grant result has unexpected fields");
+  if (result.schema !== "raft-cli-agent-login-grant.v1") throw new Error("agent-login: unexpected grant result schema");
+  if (result.service !== service) throw new Error("agent-login: grant result service mismatch");
+  if (typeof result.grant !== "string" || result.grant.length === 0) throw new Error("agent-login: grant is missing");
+  const exp = parseRfc3339(result.expires_at);
+  if (exp === null) throw new Error("agent-login: grant expires_at is not an RFC3339 timestamp");
+  if (exp <= now) throw new Error("agent-login: grant is already expired");
+  if (exp > now + AGENT_GRANT_TTL_CEILING_MS) throw new Error("agent-login: grant expiry exceeds the ceiling");
+  return { grant: result.grant, expires_at: result.expires_at };
+}
+
+/** Strictly validate the exchange/refresh success body (closed keys + RFC3339). */
+export function parseAgentSession(body, now) {
+  if (!body || typeof body !== "object") throw new Error("agent-login: exchange response is not an object");
+  if (!hasExactKeys(body, ["schema", "token_type", "access_token", "access_expires_at", "refresh_token", "refresh_expires_at"])) {
+    throw new Error("agent-login: session has unexpected fields");
+  }
+  if (body.schema !== "raft-cli-agent-session.v1") throw new Error("agent-login: unexpected session schema");
+  if (body.token_type !== "Bearer") throw new Error("agent-login: unexpected token_type");
+  for (const k of ["access_token", "refresh_token"]) {
+    if (typeof body[k] !== "string" || body[k].length === 0) throw new Error(`agent-login: session missing ${k}`);
+  }
+  const accessExp = parseRfc3339(body.access_expires_at);
+  if (accessExp === null) throw new Error("agent-login: session access_expires_at is not RFC3339");
+  if (accessExp <= now) throw new Error("agent-login: session access token is already expired");
+  if (body.refresh_expires_at !== null) {
+    const refreshExp = parseRfc3339(body.refresh_expires_at);
+    if (refreshExp === null) throw new Error("agent-login: session refresh_expires_at must be RFC3339 or null");
+    if (refreshExp <= now) throw new Error("agent-login: session refresh token is already expired");
+  }
+  return body;
+}
+
+export const MAX_TOKEN_RESPONSE_BYTES = 64 * 1024;
+
+/** Read a response body with a hard byte cap; abort the controller when exceeded. */
+export async function readBoundedText(res, controller) {
+  const declared = Number(res.headers?.get?.("content-length"));
+  if (Number.isFinite(declared) && declared > MAX_TOKEN_RESPONSE_BYTES) {
+    controller?.abort();
+    throw new Error("agent-login: token response exceeds the size limit");
+  }
+  const reader = res.body?.getReader?.();
+  if (!reader) {
+    const t = await res.text();
+    if (t.length > MAX_TOKEN_RESPONSE_BYTES) throw new Error("agent-login: token response exceeds the size limit");
+    return t;
+  }
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) {
+      total += value.byteLength;
+      if (total > MAX_TOKEN_RESPONSE_BYTES) {
+        controller?.abort();
+        try { await reader.cancel(); } catch { /* ignore */ }
+        throw new Error("agent-login: token response exceeds the size limit");
+      }
+      chunks.push(value);
+    }
+  }
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const c of chunks) { out.set(c, off); off += c.byteLength; }
+  return new TextDecoder().decode(out);
+}
+
+function defaultInvoke(raftBin, args) {
+  const res = spawnSync(raftBin, args, { encoding: "utf8" });
+  return { status: res.error ? null : res.status, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+}
+
+/**
+ * Full agent-login flow: invoke the pinned wrapper → strict-validate grant → exchange
+ * → strict-validate session → atomic store. Returns the stored session on success.
+ * `apiBase` is required: the exchange must target the instance the grant came from.
+ */
+export async function runAgentLogin(a, apiBase, opts = {}) {
+  const service = opts.service ?? TESTBED_SERVICE;
+  const now = opts.now ?? Date.now();
+  const { verifier, challenge } = generatePkce();
+  const args = [
+    "integration", "invoke",
+    "--service", service,
+    "--action", "agent-login",
+    "--json",
+    "--data-json", JSON.stringify({
+      schema: "raft-cli-agent-login-request.v1",
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+    }),
+  ];
+  const runner = opts.invoke ?? ((a2) => defaultInvoke(a.raftBin, a2));
+  const res = runner(args);
+  if (res.status !== 0) {
+    throw new Error(`agent-login: raft invoke exited with a non-zero status (${res.status ?? "spawn error"})`);
+  }
+  const { grant } = parseAgentLoginInvoke(res.stdout, service, now);
+
+  // Independent token request: no stored bearer, no auto-refresh — `testbed login` is
+  // the recovery path when the stored refresh is dead.
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const exchangeRes = await fetchImpl(new URL("/api/auth/agent/exchange", apiBase).toString(), {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    body: JSON.stringify({ schema: "raft-cli-agent-login-exchange.v1", grant, code_verifier: verifier }),
+    // A 307/308 would forward the grant + verifier to the redirect target.
+    redirect: "manual",
+  });
+  if (!exchangeRes.ok) {
+    throw new Error(`agent-login: grant exchange failed (HTTP ${exchangeRes.status})`);
+  }
+  const exchangeText = await readBoundedText(exchangeRes);
+  let exchangeBody;
+  try { exchangeBody = JSON.parse(exchangeText); } catch { throw new Error("agent-login: exchange response was not JSON"); }
+  const session = parseAgentSession(exchangeBody, now);
+  writeAgentSession(a, service, session, apiBase);
+  return session;
+}

package/lib/agent-refresh.mjs

@@ -0,0 +1,168 @@
+/**
+ * Agent token auto-refresh + cross-process single-flight (RFC 057; ported from the
+ * Hands CLI). The access token is short-lived; the rotating refresh token in the store
+ * renews it. Refresh happens PROACTIVELY inside a skew window of expiry and REACTIVELY
+ * once after a 401 (client.mjs). Concurrent `testbed` processes sharing one
+ * $SLOCK_HOME serialize through an O_EXCL lock: a loser waits for the winner's
+ * strictly-newer session and never rotates in parallel (a double rotation trips the
+ * server's reuse detection and revokes the whole chain).
+ *
+ * A lock is broken ONLY when its owner pid is provably dead; dead-lock recovery is
+ * serialized by an exclusive reaper fence. Any uncertainty fails closed (loser).
+ */
+import { openSync, closeSync, writeSync, readFileSync, existsSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { agentAuthPath, writeAgentSession } from "@botiverse/agent-session-store";
+import { parseAgentSession, readBoundedText, TESTBED_SERVICE } from "./agent-login.mjs";
+
+export const REFRESH_SKEW_MS = 60_000;
+const REFRESH_DEADLINE_MS = 20_000;
+const LOCK_WAIT_MS = 25_000;
+const LOCK_POLL_MS = 100;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const newOwnerId = () => `${process.pid}:${randomBytes(12).toString("hex")}`;
+
+/** The whole stored record (session + service + api_base), or null. */
+export function readStore(a, service = TESTBED_SERVICE) {
+  let path;
+  try { path = agentAuthPath(a, service); } catch { return null; }
+  if (!existsSync(path)) return null;
+  try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
+}
+
+function accessExpiresWithinSkew(store, now) {
+  const exp = Date.parse(store.access_expires_at);
+  return !Number.isFinite(exp) || exp - now <= REFRESH_SKEW_MS;
+}
+function accessExpired(store, now) {
+  const exp = Date.parse(store.access_expires_at);
+  return !Number.isFinite(exp) || exp <= now;
+}
+function lockPath(a, service) {
+  return join(dirname(agentAuthPath(a, service)), ".auth.refresh.lock");
+}
+
+async function rotate(a, service, store, now, fetchImpl, deadlineMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), deadlineMs);
+  try {
+    const res = await fetchImpl(new URL("/api/auth/agent/refresh", store.api_base).toString(), {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json" },
+      body: JSON.stringify({ schema: "raft-cli-agent-refresh.v1", refresh_token: store.refresh_token }),
+      signal: controller.signal,
+      redirect: "manual",
+    });
+    if (!res.ok) throw new Error(`agent-login: token refresh failed (HTTP ${res.status})`);
+    const text = await readBoundedText(res, controller);
+    let body;
+    try { body = JSON.parse(text); } catch { throw new Error("agent-login: refresh response was not JSON"); }
+    const session = parseAgentSession(body, now);
+    writeAgentSession(a, service, session, store.api_base, () => new Date(now).toISOString());
+    return session;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** A valid access token, refreshing (single-flight) if within the skew window; null if
+ *  there is no stored session (caller must `testbed login`). */
+export async function getFreshAgentAccessToken(a, opts = {}) {
+  const service = opts.service ?? TESTBED_SERVICE;
+  const now = opts.now ?? Date.now();
+  const store = readStore(a, service);
+  if (!store) return null;
+  if (!accessExpiresWithinSkew(store, now)) return store.access_token;
+  return singleFlightRefresh(a, service, store, now, opts.fetchImpl ?? fetch, opts.sleepImpl ?? sleep, false, opts.deadlineMs ?? REFRESH_DEADLINE_MS);
+}
+
+/** Force one refresh (after a 401), single-flight. */
+export async function forceRefreshAgentToken(a, opts = {}) {
+  const service = opts.service ?? TESTBED_SERVICE;
+  const now = opts.now ?? Date.now();
+  const store = readStore(a, service);
+  if (!store) return null;
+  return singleFlightRefresh(a, service, store, now, opts.fetchImpl ?? fetch, opts.sleepImpl ?? sleep, true, opts.deadlineMs ?? REFRESH_DEADLINE_MS);
+}
+
+async function singleFlightRefresh(a, service, baseline, now, fetchImpl, sleepImpl, force, deadlineMs) {
+  const lock = lockPath(a, service);
+  const ownerId = newOwnerId();
+  let acquired;
+  try {
+    const fd = openSync(lock, "wx");
+    try { writeSync(fd, ownerId); } finally { try { closeSync(fd); } catch { /* ignore */ } }
+    acquired = true;
+  } catch (e) {
+    if (e?.code !== "EEXIST") throw e;
+    acquired = acquireIfDeadOwner(lock, ownerId);
+    if (!acquired) return waitForNewerSession(a, service, baseline, now, force, sleepImpl);
+  }
+  try {
+    const fresh = readStore(a, service);
+    if (!fresh) return null;
+    if (!force && !accessExpiresWithinSkew(fresh, now)) return fresh.access_token;
+    const session = await rotate(a, service, fresh, now, fetchImpl, deadlineMs);
+    return session.access_token;
+  } finally {
+    releaseOwnLock(lock, ownerId);
+  }
+}
+
+export function releaseOwnLock(lock, ownerId) {
+  try { if (readFileSync(lock, "utf8") === ownerId) unlinkSync(lock); } catch { /* gone or foreign */ }
+}
+
+export function acquireIfDeadOwner(lock, ownerId) {
+  const ffd = acquireReaperFence(`${lock}.reap`);
+  if (ffd === null) return false;
+  try {
+    let owner = "";
+    try { owner = readFileSync(lock, "utf8"); } catch (e) { if (e?.code !== "ENOENT") return false; }
+    if (owner) {
+      const pid = ownerPid(owner);
+      if (pid === null || ownerAlive(pid)) return false;
+      try { unlinkSync(lock); } catch { /* vanished */ }
+    }
+    let fd;
+    try { fd = openSync(lock, "wx"); } catch (e) { if (e?.code === "EEXIST") return false; throw e; }
+    try { writeSync(fd, ownerId); } finally { try { closeSync(fd); } catch { /* ignore */ } }
+    return true;
+  } finally {
+    try { closeSync(ffd); } catch { /* ignore */ }
+    try { unlinkSync(`${lock}.reap`); } catch { /* ignore */ }
+  }
+}
+
+function acquireReaperFence(fence) {
+  try {
+    const fd = openSync(fence, "wx");
+    try { writeSync(fd, newOwnerId()); } catch { /* marker only */ }
+    return fd;
+  } catch {
+    return null; // never recover a leftover fence
+  }
+}
+function ownerPid(owner) {
+  const m = /^(\d+):/.exec(owner);
+  if (!m) return null;
+  const pid = Number(m[1]);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+function ownerAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e?.code !== "ESRCH"; }
+}
+
+async function waitForNewerSession(a, service, baseline, now, force, sleepImpl) {
+  const maxPolls = Math.ceil(LOCK_WAIT_MS / LOCK_POLL_MS);
+  for (let i = 0; i < maxPolls; i += 1) {
+    await sleepImpl(LOCK_POLL_MS);
+    const cur = readStore(a, service);
+    if (cur && cur.refresh_token !== baseline.refresh_token) return cur.access_token;
+  }
+  const cur = readStore(a, service);
+  if (!force && cur && !accessExpired(cur, now)) return cur.access_token;
+  throw new Error("agent-login: timed out waiting for a concurrent token refresh");
+}

package/lib/auth.mjs

@@ -0,0 +1,55 @@
+/**
+ * Which credential this process uses. Two swimlanes, never mixed:
+ *   agent  — all managed-agent markers present (SLOCK_CLI_TRANSPORT_DIR + SLOCK_HOME +
+ *            SLOCK_AGENT_ID + executable raft wrapper): ONLY the per-agent store token,
+ *            auto-refreshed. TESTBED_TOKEN is ignored here on purpose — an agent must
+ *            authenticate as itself.
+ *   human  — no markers: TESTBED_TOKEN env (a session or deploy token), unchanged.
+ *   fail_closed — some markers but not all: refuse. Never fall back to the human lane
+ *            from a half-configured agent environment.
+ */
+import { unlinkSync, existsSync } from "node:fs";
+import { admitAgent, agentAuthPath } from "@botiverse/agent-session-store";
+import { TESTBED_SERVICE } from "./agent-login.mjs";
+import { getFreshAgentAccessToken, forceRefreshAgentToken, readStore } from "./agent-refresh.mjs";
+
+export function resolveAuth({ urlBase, urlExplicit, env = process.env, service = TESTBED_SERVICE }) {
+  const admission = admitAgent(env);
+  if (admission.kind === "fail_closed") {
+    throw new Error(`refusing to run: partial managed-agent environment (${admission.reason}); not falling back to TESTBED_TOKEN`);
+  }
+  if (admission.kind === "agent") {
+    const a = admission.env;
+    const store = readStore(a, service);
+    // The instance the session was minted on wins unless TESTBED_URL was set explicitly.
+    const apiBase = urlExplicit ? urlBase : (store?.api_base ?? urlBase);
+    return {
+      mode: "agent",
+      apiBase,
+      agentEnv: a,
+      service,
+      async token() {
+        const t = await getFreshAgentAccessToken(a, { service });
+        if (!t) throw new Error("not logged in: run `testbed login` (managed agent)");
+        return t;
+      },
+      async retryToken() { return forceRefreshAgentToken(a, { service }); },
+      logout() {
+        const p = agentAuthPath(a, service);
+        if (existsSync(p)) unlinkSync(p);
+        return p;
+      },
+    };
+  }
+  const token = env.TESTBED_TOKEN || "";
+  return {
+    mode: "human",
+    apiBase: urlBase,
+    async token() {
+      if (!token) throw new Error("TESTBED_TOKEN is not set (session or deploy token); inside a managed agent run `testbed login`");
+      return token;
+    },
+    async retryToken() { return null; },
+    logout() { return null; },
+  };
+}

package/lib/client.mjs

@@ -0,0 +1,31 @@
+/** Minimal JSON client. Agent mode retries ONCE after a 401 with a forced refresh. */
+export class ApiError extends Error {
+  constructor(status, body, text) {
+    super(`${status}: ${body?.error ?? (text ?? "").slice(0, 200)}`);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export function makeClient(auth, fetchImpl = fetch) {
+  async function once(method, path, body, token) {
+    const res = await fetchImpl(`${auth.apiBase}/api${path}`, {
+      method,
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json", accept: "application/json" },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    let json = null;
+    try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON error page */ }
+    return { res, json, text };
+  }
+  return async function api(method, path, body) {
+    let { res, json, text } = await once(method, path, body, await auth.token());
+    if (res.status === 401 && auth.mode === "agent") {
+      const t = await auth.retryToken();
+      if (t) ({ res, json, text } = await once(method, path, body, t));
+    }
+    if (!res.ok) throw new ApiError(res.status, json, text);
+    return json;
+  };
+}

package/lib/main.mjs

@@ -0,0 +1,231 @@
+// testbed command set. Output is human tables by default; `--json` prints the
+// raw API response (what an agent wants). Secrets: `acquire` returns a one-time ADB
+// private key; it is printed only in --json output or written to --key-out (0600).
+import { openSync, writeSync, closeSync } from "node:fs";
+import { resolveAuth } from "./auth.mjs";
+import { makeClient, ApiError } from "./client.mjs";
+import { runAgentLogin } from "./agent-login.mjs";
+
+export const USAGE = `testbed — cloud phones + the acceptance stamp in the Raft release loop
+
+  testbed login                          agent: PKCE login via raft (no browser); human: how to set TESTBED_TOKEN
+  testbed logout                         agent: forget the stored session
+  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 devices                        your leases
+  testbed renew <lease-id> [--ttl MIN]
+  testbed release <lease-id>
+  testbed repair-adb <lease-id>
+  testbed diagnose-adb <lease-id> [--pubkey-sha256 HEX]
+
+  testbed cases                          acceptance case library
+  testbed run <case-id...> [--app --ref --apk --apk-run --release --by]
+  testbed runs
+  testbed show <run-id>
+
+flags: --json (raw API output)   env: TESTBED_TOKEN (human/CI), TESTBED_URL (instance)
+`;
+
+function takeFlag(args, name, dflt) {
+  const i = args.indexOf(`--${name}`);
+  if (i === -1) return dflt;
+  const v = args[i + 1];
+  args.splice(i, 2);
+  return v;
+}
+function takeSwitch(args, name) {
+  const i = args.indexOf(`--${name}`);
+  if (i === -1) return false;
+  args.splice(i, 1);
+  return true;
+}
+
+function table(rows, cols, out) {
+  const w = cols.map((c) => Math.max(c.length, ...rows.map((r) => String(r[c] ?? "").length)));
+  out(cols.map((c, i) => c.padEnd(w[i])).join("  "));
+  for (const r of rows) out(cols.map((c, i) => String(r[c] ?? "").padEnd(w[i])).join("  "));
+}
+
+function writeKeyFile(path, key) {
+  const fd = openSync(path, "wx", 0o600);
+  try { writeSync(fd, key.endsWith("\n") ? key : key + "\n"); } finally { closeSync(fd); }
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{urlBase:string, urlExplicit?:boolean, env?:NodeJS.ProcessEnv, stdout?:(s:string)=>void,
+ *          stderr?:(s:string)=>void, fetchImpl?:typeof fetch, loginImpl?:typeof runAgentLogin}} opts
+ * @returns {Promise<number>} exit code
+ */
+export async function main(argv, opts) {
+  const args = [...argv];
+  const out = opts.stdout ?? ((s) => console.log(s));
+  const err = opts.stderr ?? ((s) => console.error(s));
+  const env = opts.env ?? process.env;
+  const exit = opts.exit ?? ((code) => process.exit(code));
+  const json = takeSwitch(args, "json");
+  const cmd = args.shift();
+  const emit = (data, human) => { if (json) out(JSON.stringify(data, null, 2)); else human(); };
+
+  let auth;
+  try {
+    auth = resolveAuth({ urlBase: opts.urlBase, urlExplicit: opts.urlExplicit, env });
+  } catch (e) {
+    err(`testbed: ${e.message}`);
+    return exit(1);
+  }
+  const api = makeClient(auth, opts.fetchImpl);
+
+  try {
+    switch (cmd) {
+      case "login": {
+        if (auth.mode !== "agent") {
+          out("Not a managed Raft agent. Humans and CI use TESTBED_TOKEN:");
+          out(`  browser: ${auth.apiBase}/login  (then reuse the stamp_session cookie value as TESTBED_TOKEN)`);
+          out("  CI:      a deploy token issued by the testbed owner");
+          return exit(0);
+        }
+        const login = opts.loginImpl ?? runAgentLogin;
+        const session = await login(auth.agentEnv, auth.apiBase, { service: auth.service, fetchImpl: opts.fetchImpl });
+        emit({ ok: true, service: auth.service, api_base: auth.apiBase, access_expires_at: session.access_expires_at },
+          () => out(`Agent login ready (${auth.service} @ ${auth.apiBase}); access token valid until ${session.access_expires_at}`));
+        return exit(0);
+      }
+      case "logout": {
+        const p = auth.logout();
+        out(p ? `forgot agent session ${p}` : "nothing stored (human/CI lane uses TESTBED_TOKEN)");
+        return exit(0);
+      }
+      case "whoami": {
+        const me = await api("GET", "/me");
+        emit(me, () => out(`${me.actor.kind} ${me.actor.name}${me.actor.subject ? ` (${me.actor.subject}@${me.actor.server_id})` : ""} @ ${auth.apiBase}`));
+        return exit(0);
+      }
+      case "pool": {
+        const d = await api("GET", "/device-broker/pool");
+        emit(d, () => table(d.pool.map((p) => ({
+          instance: p.instance_id, status: p.status, leased_by: p.leased_by ?? "-",
+          expires: p.expires_at ? new Date(p.expires_at).toISOString().slice(0, 16) : "-", adb: p.adb_endpoint ?? "-",
+        })), ["instance", "status", "leased_by", "expires", "adb"], out));
+        return exit(0);
+      }
+      case "acquire": {
+        const ttl = takeFlag(args, "ttl");
+        const instance = takeFlag(args, "instance");
+        const requestId = takeFlag(args, "request-id");
+        const keyOut = takeFlag(args, "key-out");
+        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);
+        }
+        let keyPath = null;
+        if (keyOut && d.adb_private_key) {
+          writeKeyFile(keyOut, d.adb_private_key);
+          keyPath = keyOut;
+        }
+        const shown = keyPath ? { ...d, adb_private_key: undefined, adb_private_key_file: keyPath } : d;
+        emit(shown, () => {
+          out(`lease ${d.lease.id} on ${d.lease.instance_id} until ${d.lease.expires_at ? new Date(d.lease.expires_at).toISOString() : "?"}`);
+          out(`adb: ${d.adb_endpoint ?? "(pending) " + (d.adb_note ?? "")}`);
+          out(`adb_public_key_sha256: ${d.adb_public_key_sha256 ?? "-"}`);
+          out(keyPath ? `adb private key written to ${keyPath} (0600)` : "adb private key: not shown — pass --key-out FILE or --json");
+        });
+        return exit(0);
+      }
+      case "devices": {
+        const d = await api("GET", "/device-broker/leases");
+        emit(d, () => table(d.leases.map((l) => ({
+          lease: l.id, instance: l.instance_id, status: l.status,
+          expires: l.expires_at ? new Date(l.expires_at).toISOString().slice(0, 16) : "-", adb: l.adb_endpoint ?? "-",
+        })), ["lease", "instance", "status", "expires", "adb"], out));
+        return exit(0);
+      }
+      case "renew": {
+        const id = args[0]; if (!id) throw new Error("usage: testbed renew <lease-id> [--ttl MIN]");
+        const ttl = takeFlag(args, "ttl");
+        const d = await api("POST", `/device-broker/leases/${encodeURIComponent(id)}/renew`, ttl !== undefined ? { ttl_minutes: Number(ttl) } : {});
+        emit(d, () => out(`lease ${d.lease.id} now until ${new Date(d.lease.expires_at).toISOString()}`));
+        return exit(0);
+      }
+      case "release": {
+        const id = args[0]; if (!id) throw new Error("usage: testbed release <lease-id>");
+        const d = await api("DELETE", `/device-broker/leases/${encodeURIComponent(id)}`);
+        emit(d, () => out(d.status === "in_flight" ? "release in flight; reclaim continues asynchronously" : `released ${id}`));
+        return exit(0);
+      }
+      case "repair-adb": {
+        const id = args[0]; if (!id) throw new Error("usage: testbed repair-adb <lease-id>");
+        const d = await api("POST", `/device-broker/leases/${encodeURIComponent(id)}/repair-adb`, {});
+        emit(d, () => out(`repair-adb: ${d.status} on ${d.instance_id}`));
+        return exit(0);
+      }
+      case "diagnose-adb": {
+        const id = args[0]; if (!id) throw new Error("usage: testbed diagnose-adb <lease-id> [--pubkey-sha256 HEX]");
+        const sha = takeFlag(args, "pubkey-sha256");
+        const d = await api("POST", `/device-broker/leases/${encodeURIComponent(id)}/diagnose-adb`, sha ? { expected_public_key_sha256: sha } : {});
+        emit(d, () => out(JSON.stringify(d, null, 2)));
+        return exit(0);
+      }
+      case "cases": {
+        const d = await api("GET", "/cases");
+        emit(d, () => table(d.cases.map((c) => ({ id: c.id, tier: c.tier, rev: c.revision, title: c.title })), ["id", "tier", "rev", "title"], out));
+        return exit(0);
+      }
+      case "run": {
+        const app = takeFlag(args, "app", "raft-android");
+        const apk = takeFlag(args, "apk");
+        const ref = takeFlag(args, "ref");
+        const apkRun = takeFlag(args, "apk-run");
+        const release = takeFlag(args, "release");
+        const by = takeFlag(args, "by", env.USER || "testbed-cli");
+        const caseIds = args.filter((a) => !a.startsWith("--"));
+        if (!caseIds.length) throw new Error("usage: testbed run <case-id...> [--app slug] [--ref branch] [--apk url] [--apk-run ci-run-id] [--release id]");
+        const d = await api("POST", "/runs", { app_slug: app, case_ids: caseIds, apk_ref: apk, ref, apk_run_id: apkRun, hands_release_id: release, requested_by: by });
+        emit(d, () => { out(`run ${d.run_id} — ${d.cases} case(s), ${d.dispatched} dispatched`); out(`${auth.apiBase}/runs/${d.run_id}`); });
+        return exit(0);
+      }
+      case "runs": {
+        const d = await api("GET", "/runs");
+        emit(d, () => table(d.runs.map((r) => ({
+          run: r.id.slice(0, 8), app: r.app_slug, status: r.status, cases: r.case_count,
+          release: r.hands_release_id ?? "-", created: new Date(r.created_at).toISOString().slice(0, 16),
+        })), ["run", "app", "status", "cases", "release", "created"], out));
+        return exit(0);
+      }
+      case "show": {
+        const id = args[0]; if (!id) throw new Error("usage: testbed show <run-id>");
+        const d = await api("GET", `/runs/${encodeURIComponent(id)}`);
+        emit(d, () => {
+          out(`run ${d.run.id} — ${d.run.status} (${d.run.app_slug}, release: ${d.run.hands_release_id ?? "-"})`);
+          out(`${auth.apiBase}/runs/${d.run.id}\n`);
+          table(d.cases.map((rc) => {
+            const v = rc.verdict_json ? JSON.parse(rc.verdict_json) : null;
+            const ev = d.evidence.filter((e) => e.run_case_id === rc.id).length;
+            return { case: rc.case_id, status: rc.status, verdict: v?.verdict ?? "-", turns: v?.turns ?? "-", evidence: ev };
+          }), ["case", "status", "verdict", "turns", "evidence"], out);
+          for (const rv of d.reviews) out(`\nfinal: ${rv.verdict} by ${rv.reviewer}${rv.comment ? ` — ${rv.comment}` : ""}`);
+        });
+        return exit(0);
+      }
+      default:
+        out(USAGE);
+        return exit(cmd ? 1 : 0);
+    }
+  } catch (e) {
+    if (e instanceof ApiError) {
+      err(`testbed: ${e.message}`);
+      if (e.status === 401) err(auth.mode === "agent" ? "testbed: session rejected — run `testbed login`" : "testbed: check TESTBED_TOKEN");
+      return exit(1);
+    }
+    err(`testbed: ${e.message}`);
+    return exit(1);
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@botiverse/testbed-cli",
+  "version": "0.1.0",
+  "description": "CLI for testbed \u2014 cloud phones and the acceptance stamp in the Raft release loop",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "testbed": "bin/testbed.mjs"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\""
+  },
+  "dependencies": {
+    "@botiverse/agent-session-store": "^0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/botiverse/testbed.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}