@qaping/cli 0.1.5 → 0.3.0

package/bin/qaping

@@ -11,7 +11,11 @@
 //   qaping setup [claude-code|cursor|codex] [--force]   one-command onboarding
 //   qaping remove|uninstall [--client <c>]              sweep ONLY qaping's state
 //   qaping publish-build <game.zip> --platform windows|macos
+//   qaping builds [rm <slug>]                          what is hosted, and free a slot
 //   qaping wait <ping_id> [--timeout <seconds>]
+//   qaping results <ping_id>                           one passive fetch, no blocking
+//   qaping rounds [add|rm]                             the parked rounds this repo is owed
+//   qaping issues <game>                               the game's issue board, read-only
 //   qaping whoami | version | help
 "use strict";
 const fs = require("fs");
@@ -47,9 +51,12 @@ function resolveKitDir() {
 // writes it to ~/.claude/rules/qaping.md and ~/.cursor/rules/qaping.mdc.
 const RULE_BODY = `This machine has qaping: automatic QA for games — real human playtesters play the developer's builds on their own hardware and report back, and the coding agent runs the whole loop.
 Whenever the user asks to set up QA for a game, run QA on a patch, check whether a change broke anything, or playtest a game or build, load the qaping skill and follow it — it owns authoring/maintaining QA-PLAN.md in the game repo and the per-patch run.
-Builds ship with \`qaping publish-build <game.zip> --platform windows|macos\`; the printed /b/<slug> URL is what a round is filed against (store-delivered games file with their Steam/TestFlight/App Store URL instead).
-The MCP tools are qaping_playtest (file a round with real human playtesters), qaping_results (fetch a finished round, free) and qaping_wait (continue a pending round — on pending, spawn a background task that loops qaping_wait and keep working; foreground polling is the fallback, and never report pending as the answer or end with an unbacked promise to check later).
-Playtests are duration-billed at 2 credits per minute of play per playtester — state the estimated cost before filing. Windows rounds return a recording and no transcript; web rounds return answers only (no recording, no transcript) — never promise evidence a platform does not ship.
+Builds ship with \`qaping publish-build <game.zip> --platform windows|macos\`; the printed /b/<slug> URL is what a round is filed against (store-delivered games file with their Steam/TestFlight/App Store URL instead). Hosted builds are kept until you delete them (pass \`--expires-in-hours <n>\` to have one reaped instead) and capped per account — if a publish is refused for that cap, \`qaping builds\` lists them and \`qaping builds rm <slug>\` frees a slot; free one and carry on rather than stopping to ask, taking the ones marked as never-finished uploads first and never deleting a build a round you filed is still running against.
+The MCP tools are qaping_playtest (file a round with real human playtesters), qaping_results (fetch a round, free), qaping_wait (continue a pending round) and qaping_issues (the game's issue board — file a bug, claim a fix, close or reopen; free).
+Bugs live on that board, not in chat or in a report nobody re-reads: file EVERY playtest with \`game\` set to the QA plan's game_slug, so the game's open and claimed-fixed issues ride the round as the playtester's checklist. You can only ever CLAIM a fix (qaping_issues action:'fixed', with the exact build URL the next round will play, claimed BEFORE that round is filed) — only a playtester answering "Gone" on a later round marks one verified, and a "Still here" on a claimed fix regresses it. \`qaping issues <game>\` reads the same board from the shell.
+Decide at filing time how the round ends: a short round waits in place — the moment filing returns pending, spawn a background task that loops qaping_wait and keep working (foreground polling is the fallback); a long or overnight round is PARKED — file it with an explicit long deadline_seconds, record it immediately with \`qaping rounds add <ping_id>\` (it writes qa-open-rounds.json beside QA-PLAN.md), tell the user exactly what is pending, and end the turn; a later session collects it (\`qaping rounds\` lists them with live status, qaping_results fetches one).
+A recorded parked round is an honest pending end — never report pending as the answer without one, and never end with an unbacked promise to check later.
+Playtests are duration-billed at 2 credits per minute of play per playtester — state the estimated cost before filing. Windows rounds return a recording, and a transcript only when the tester recorded with our recorder app (read transcript_status on each result — a Game Bar session has no transcript); web rounds return answers only (no recording, no transcript) — never promise evidence a session does not ship.
 QA memory: whenever the developer mentions — in ANY conversation, not just QA runs — something that should always be tested, a fragile area, or a QA lesson learned, offer to record it as a check (or a note on an existing check) in QA-PLAN.md so it is tested from then on.
 `;
 
@@ -217,6 +224,15 @@ function cmdPublishBuild(argv) {
     .main(argv.slice(1), { brandCommand: "qaping publish-build", nextStepToolName: "qaping_playtest" });
 }
 
+// The management half of publish-build: an account holds a small number of
+// hosted builds at once, and until this existed a QA loop that hit that cap
+// could not even name the builds holding the slots — it stopped and asked a
+// human. Same brand seam: every remedy this prints says `qaping`.
+function cmdBuilds(argv) {
+  return require(path.join(resolveKitDir(), "harness", "builds.js"))
+    .main(argv.slice(1), { brandCommand: "qaping builds" });
+}
+
 function cmdPublish(argv) {
   // WEB games: their "build" is a static directory, hosted (not zipped) — the
   // kit's hosted-draft publisher, brand-seamed like publish-build above. The
@@ -225,14 +241,580 @@ function cmdPublish(argv) {
     .main(argv.slice(1), { brandCommand: "qaping publish" });
 }
 
+// ─── parked rounds: the state a LATER session collects from ─────────────────
+//
+// A playtest legitimately runs for hours, so an agent that files one has two
+// honest endings: wait in place (the background qaping_wait chain), or PARK —
+// file with an explicit long deadline, record the round, end the turn. This
+// file is that record: OPEN state, mutable, one entry per round still owed,
+// sitting beside QA-PLAN.md at the game repo root. It is NOT qa-rounds.jsonl —
+// that ledger is append-only history written AFTER results land, and the two
+// are never merged. Signed URLs never go in here; they expire in days and the
+// record has to outlive the session that wrote it.
+const ROUNDS_FILE = "qa-open-rounds.json";
+// A repo owed more open rounds than this is a runaway loop, not a QA plan. The
+// listing spends one passive fetch per round, so this is also the ceiling on
+// what `qaping rounds` costs in requests.
+const MAX_OPEN_ROUNDS = 20;
+const PING_ID_RE = /^[0-9a-f-]{36}$/i;
+// The issue board's game slug. Mirrors lib/qa-issues.ts's GAME_SLUG_RE and
+// migration 066's column check exactly — a slug this refuses is a slug the
+// service refuses, and finding that out before the network is the point.
+const GAME_SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+const DEFAULT_APP_URL = "https://pingfusi.com";
+
+const ROUNDS_USAGE = `usage:
+  qaping rounds [--json] [--offline] [--file <path>]
+  qaping rounds add <ping_id> [--platform windows|macos|ios] [--build <url>]
+                              [--minutes N] [--deadline-seconds N]
+                              [--game <slug>] [--checks a,b,c]
+                              [--note "<patch>"] [--json]
+  qaping rounds rm <ping_id> [--json]`;
+
+function flagValue(argv, name) {
+  const i = argv.indexOf(name);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+
+function intFlag(argv, name) {
+  const raw = flagValue(argv, name);
+  if (raw === undefined) return null;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+function roundsFilePath(argv) {
+  const override = flagValue(argv, "--file");
+  return override ? path.resolve(override) : path.join(process.cwd(), ROUNDS_FILE);
+}
+
+// Tolerant on read, strict on shape: an entry without a ping_id is not a round
+// anyone can collect, so it is dropped rather than rendered as a mystery.
+//
+// A bare top-level ARRAY is normalized, not refused: the skill and the mount
+// prose both sanction hand-writing this file, and a list of records is the
+// likeliest thing a hand writes. ANY OTHER shape is a loud failure — reading an
+// unrecognized document as "no rounds" makes the next `rounds add` overwrite
+// records nobody ever saw, which is data loss dressed as a fresh start.
+function parseRounds(raw) {
+  let data;
+  try { data = JSON.parse(raw); }
+  catch { throw new Error(`${ROUNDS_FILE} is not valid JSON — fix or delete it`); }
+  const rounds = Array.isArray(data) ? data
+    : (data && Array.isArray(data.rounds) ? data.rounds : null);
+  if (!rounds) {
+    throw new Error(`${ROUNDS_FILE} is valid JSON but not a rounds file — expected {"rounds": [ … ]} (a bare array of records is also read). Refusing to overwrite it; fix or delete it.`);
+  }
+  return { rounds: rounds.filter((r) => r && typeof r.ping_id === "string") };
+}
+
+/** null when the file does not exist — "no rounds recorded here" is not an error. */
+function readRoundsFile(file) {
+  let raw;
+  try { raw = fs.readFileSync(file, "utf8"); }
+  catch { return null; }
+  return parseRounds(raw);
+}
+
+// Write via tmp-then-rename: rename(2) is atomic on POSIX, so a reader (or a
+// crash) sees the whole old file or the whole new one, never a truncated one.
+function writeRoundsFile(file, state) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ rounds: state.rounds }, null, 2) + "\n");
+  try { fs.renameSync(tmp, file); }
+  catch (e) { try { fs.unlinkSync(tmp); } catch { /* best effort */ } throw e; }
+}
+
+// ── the write lock ──────────────────────────────────────────────────────────
+//
+// Every mutation is a read-modify-write, and the two callers that run
+// unattended — an agent recording a fresh round while a background poller
+// removes a collected one — race. Unlocked, the loser's record is simply gone.
+// A lockfile (O_EXCL create, the one atomic primitive every filesystem gives)
+// serializes them; dependency-free, because a QA repo must not grow one.
+const LOCK_RETRIES = 10;
+const LOCK_RETRY_MS = 50;
+const LOCK_STALE_MS = 5000;
+
+/** Blocking sleep with no dependency and no busy-spin (allowed on Node's main thread). */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function acquireRoundsLock(file) {
+  const lock = `${file}.lock`;
+  for (let attempt = 0; attempt < LOCK_RETRIES; attempt++) {
+    try { return fs.openSync(lock, "wx"); }
+    catch (e) {
+      if (!e || e.code !== "EEXIST") throw e;
+      // A killed writer must not wedge the repo forever — an old lock is stolen,
+      // loudly, because a stolen lock is also how a real concurrent write is lost.
+      let age = 0;
+      try { age = Date.now() - fs.statSync(lock).mtimeMs; } catch { age = 0; }
+      if (age > LOCK_STALE_MS) {
+        console.error(`⚠ stale lock on ${ROUNDS_FILE} (${Math.round(age / 1000)}s old) — taking it over`);
+        try { fs.unlinkSync(lock); } catch { /* someone else got there first */ }
+        continue;
+      }
+      sleepSync(LOCK_RETRY_MS);
+    }
+  }
+  throw new Error(`${ROUNDS_FILE} is locked by another qaping process — nothing was written; try again in a moment`);
+}
+
+function releaseRoundsLock(file, fd) {
+  try { fs.closeSync(fd); } catch { /* best effort */ }
+  try { fs.unlinkSync(`${file}.lock`); } catch { /* best effort */ }
+}
+
+/**
+ * The ONE read-modify-write path. `mutate(state)` returns `{ state, …extras }`;
+ * a null/absent `state` means "decided not to write" (and never truncates).
+ * Both the read and the write happen inside the lock — the point of the lock.
+ */
+function mutateRoundsFile(file, mutate) {
+  const fd = acquireRoundsLock(file);
+  try {
+    const out = mutate(readRoundsFile(file) || { rounds: [] }) || {};
+    if (out.state) writeRoundsFile(file, out.state);
+    return out;
+  } finally {
+    releaseRoundsLock(file, fd);
+  }
+}
+
+function upsertRound(state, record) {
+  const rounds = state.rounds.slice();
+  const i = rounds.findIndex((r) => r.ping_id === record.ping_id);
+  if (i >= 0) rounds[i] = record; else rounds.push(record);
+  return { rounds };
+}
+
+function removeRound(state, pingId) {
+  const rounds = state.rounds.filter((r) => r.ping_id !== pingId);
+  return { state: { rounds }, removed: rounds.length !== state.rounds.length };
+}
+
+// How long the round stays offered to NEW players: the explicit deadline the
+// filing set, counted from when it was filed. Absent either fact there is
+// nothing honest to print, so nothing is printed.
+function visibleUntil(record) {
+  const filed = Date.parse(record.filed_at || "");
+  if (!Number.isFinite(filed) || !record.deadline_seconds) return null;
+  return new Date(filed + record.deadline_seconds * 1000).toISOString();
+}
+
+function roundStatusLine(record, live) {
+  const status = live.status || "pending";
+  if (status === "complete") return `READY — collect now: qaping results ${record.ping_id}`;
+  if (status === "pending") {
+    const seen = `${live.n_received ?? 0}/${live.n_target ?? "?"}`;
+    const until = visibleUntil(record);
+    return `still pending (${seen})${until ? ` — visible until ${until}` : ""}; keep waiting: qaping wait ${record.ping_id}`;
+  }
+  // One round's own failure, not the run's: the rest of the listing is real.
+  if (status === "unavailable") {
+    return `status unavailable (${live.error || "the service refused this id"}) — the other rounds are unaffected; retry: qaping results ${record.ping_id}`;
+  }
+  // Results are asker-scoped server-side, so a round filed under a DIFFERENT
+  // login reads exactly like one that never existed. Never prescribe deleting
+  // the only record of a round on that evidence.
+  if (status === "not_found") {
+    return `not visible from this login (wrong account?) or expired — verify before \`qaping rounds rm ${record.ping_id}\` (\`qaping whoami\` shows which login this is)`;
+  }
+  return `expired or unreadable (${status}) — report it, then: qaping rounds rm ${record.ping_id}`;
+}
+
+/**
+ * Pure render of the listing. entries: [{ record, live }], live null when unfetched.
+ * opts.total is the TRUE recorded count — entries may be a capped slice of it, and
+ * a count line that reports the slice as the total is a lie a later session acts on.
+ */
+function renderRounds(entries, opts) {
+  const o = opts || {};
+  const total = Number.isFinite(o.total) ? o.total : entries.length;
+  const notice = o.notice || (o.offline ? "(live status unavailable — offline)" : null);
+  const lines = [total > entries.length
+    ? `${total} open round(s) recorded in ${ROUNDS_FILE} — showing live status for first ${entries.length} of ${total}:`
+    : `${total} open round(s) recorded in ${ROUNDS_FILE}:`];
+  if (notice) lines.push(notice);
+  for (const { record, live } of entries) {
+    const facts = [
+      record.platform || null,
+      record.est_minutes ? `${record.est_minutes} min` : null,
+      record.filed_at ? `filed ${record.filed_at}` : null,
+    ].filter(Boolean).join(" · ");
+    lines.push("");
+    lines.push(`  ${record.ping_id}${facts ? ` — ${facts}` : ""}`);
+    if (record.build) lines.push(`    build: ${record.build}`);
+    // Which board's issues rode this round — the later session that collects
+    // it needs the slug to read what moved (`qaping issues <game>`).
+    if (record.game) lines.push(`    game: ${record.game}`);
+    if (Array.isArray(record.checks) && record.checks.length) lines.push(`    checks: ${record.checks.join(", ")}`);
+    if (record.note) lines.push(`    patch: ${record.note}`);
+    if (live) lines.push(`    ${roundStatusLine(record, live)}`);
+  }
+  return lines.join("\n");
+}
+
+// The app base these passive fetches use. `qaping wait` rides the vendored
+// installer, which honors two kit-side env names besides this brand's own — so
+// resolving a different base here would make two verbs disagree about which
+// service a staging machine talks to. Same order as the vendor's. The second
+// name is spelled from parts on purpose: it is a wire-only env name, and the
+// reviewer-side brand never appears literally on a dev-facing surface (this
+// package's own leak scan is what enforces that).
+const LEGACY_APP_URL_ENVS = [["PING", "HUMANS", "_APP_URL"].join(""), "PINGFUSI_APP_URL"];
+
+function resolveAppUrl() {
+  const fromEnv = LEGACY_APP_URL_ENVS.map((name) => process.env[name]).find(Boolean);
+  return (qapingWrapper().appUrl || fromEnv || DEFAULT_APP_URL).replace(/\/+$/, "");
+}
+
+// wire.js's resolveToken reads ~/.claude.json under the WIRE CONTRACT's MCP
+// server keys — a list that predates this brand and does not contain `qaping`.
+// A machine whose only login is the qaping MCP entry (written by the client's
+// own config, with no credentials stash) therefore reads as logged out. This
+// mirrors the vendored installer's resolveLocalToken minimally, bin-local, so
+// the kit stays untouched: the qaping key first, then the contract's own order
+// — which supplies the legacy names without spelling a retired brand here.
+function resolveTokenFromClientConfigs(kitDir) {
+  const keys = ["qaping"];
+  try {
+    const contract = require(path.join(kitDir, "packages", "core", "wire-contract.gen.js"));
+    for (const k of contract.MCP_SERVER_KEYS || []) if (!keys.includes(k)) keys.push(k);
+  } catch { keys.push("pingfusi"); }
+  const home = os.homedir();
+  const desktop = process.platform === "darwin"
+    ? path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json")
+    : process.platform === "win32"
+      ? path.join(process.env.APPDATA || path.join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json")
+      : path.join(home, ".config", "Claude", "claude_desktop_config.json");
+  for (const p of [path.join(home, ".claude.json"), desktop, path.join(home, ".cursor", "mcp.json")]) {
+    try {
+      const servers = (JSON.parse(fs.readFileSync(p, "utf8")) || {}).mcpServers || {};
+      for (const key of keys) {
+        const headers = (servers[key] || {}).headers || {};
+        const m = /Bearer\s+(\S+)/.exec(headers.Authorization || headers.authorization || "");
+        if (m) return m[1];
+      }
+    } catch { /* absent or unreadable config: just not a login source */ }
+  }
+  return null;
+}
+
+// One passive tools/call against the qaping mount, for ANY tool it registers —
+// the same transport and the same JSON-or-SSE parse the kit's `wait` leg uses,
+// with the mount read from the ONE wrapper object every other command is driven
+// by. Passive: it never renews a round's lease, which is exactly why a parked
+// round needs its own explicit deadline. Failures are TYPED for the caller:
+// `authRejected` and `perRound` separate "this login is dead" from "the service
+// refused this one call".
+async function callQapingTool(name, args) {
+  const w = qapingWrapper();
+  const kitDir = resolveKitDir();
+  const { resolveToken } = require(path.join(kitDir, "packages", "core", "wire.js"));
+  const token = resolveToken() || resolveTokenFromClientConfigs(kitDir);
+  if (!token) throw new Error("no qaping login on this machine — run `qaping setup` first");
+  let res;
+  try {
+    res = await fetch(`${resolveAppUrl()}${w.mcpPath}`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+        authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name, arguments: args },
+      }),
+      signal: AbortSignal.timeout(20_000),
+    });
+  } catch (e) {
+    throw new Error(`could not reach the qaping service (${(e && e.message) || e})`);
+  }
+  // A rejected login is a fact about the RUN, not about the round: the body is
+  // plain text, so without this it parses as garbage and reads as "offline",
+  // sending the developer to debug their network instead of their login.
+  if (res.status === 401 || res.status === 403) {
+    const e = new Error(`qaping login rejected (HTTP ${res.status}) — run \`qaping setup\` to re-link this machine`);
+    e.authRejected = true;
+    throw e;
+  }
+  const raw = await res.text();
+  const m = raw.match(/data: (.*)/);
+  let payload;
+  try { payload = JSON.parse(m ? m[1] : raw); }
+  catch { throw new Error(`unreadable response from the qaping service (HTTP ${res.status})`); }
+  if (payload.error) {
+    // The service answered — it just refused THIS id (a bad ping_id is -32602).
+    // Marked so a listing can degrade one row instead of the whole pass.
+    const e = new Error(payload.error.message || "MCP error");
+    e.perRound = true;
+    throw e;
+  }
+  const result = payload.result || {};
+  const structured = result.structuredContent || {};
+  return {
+    status: structured.status || "pending",
+    structured,
+    result,
+    // A tool that refuses inside a successful JSON-RPC result (the board at
+    // its cap, a seq that is not there) answers with isError + the same text.
+    isError: result.isError === true,
+    text: (result.content && result.content[0] && result.content[0].text) || "",
+  };
+}
+
+/** The results tool, by name — every caller below reads the same shape. */
+function callResultsTool(pingId) {
+  return callQapingTool("qaping_results", { ping_id: pingId });
+}
+
+async function cmdResults(argv) {
+  const json = argv.includes("--json");
+  // Flags in any position: `qaping results --json <id>` is the natural thing to
+  // type, and reading argv[1] positionally made it a usage error.
+  const pingId = argv.slice(1).find((a) => !a.startsWith("--"));
+  if (!pingId || !PING_ID_RE.test(pingId)) {
+    console.error("usage: qaping results <ping_id> [--json]");
+    // 1, never 2: exit 2 is THIS command's "still pending" signal (a background
+    // harness reads it and waits), so a typo must not answer "pending". Same
+    // code the vendored `wait` exits on its own usage error.
+    process.exit(1);
+  }
+  const r = await callResultsTool(pingId);
+  if (r.status === "not_found") {
+    // Results are asker-scoped server-side, so this is nearly always a
+    // wrong-account token rather than a wrong id — say which.
+    console.error(`✗ no round ${pingId} on this account — results are asker-scoped: \`qaping results\` only reads rounds filed with the same qaping login (\`qaping whoami\` shows which one this is).`);
+    process.exit(1);
+  }
+  const payload = Object.keys(r.structured).length ? r.structured : r.result;
+  console.log(json ? JSON.stringify(payload, null, 2) : (r.text || JSON.stringify(payload, null, 2)));
+  if (r.status === "pending") {
+    // stderr, so --json stdout stays a parseable document.
+    console.error(`still pending — \`qaping wait ${pingId}\` to block, or leave it recorded and check later.`);
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+const ISSUES_USAGE = "usage: qaping issues <game> [--json] [--status open|fixed|verified|closed]";
+const ISSUE_STATUSES = ["open", "fixed", "verified", "closed"];
+
+/** argv after the command, minus flags and the values they consume — so a
+ *  slug that happens to equal a flag's value is still the positional. */
+function positionalArgs(argv, valueFlags) {
+  const out = [];
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i].startsWith("--")) {
+      if (valueFlags.includes(argv[i])) i++;
+      continue;
+    }
+    out.push(argv[i]);
+  }
+  return out;
+}
+
+/**
+ * The game's issue board, read-only. The agent moves issues through the MCP
+ * tool; this is the human's window on the same board — and it prints the
+ * SERVICE's own rendering rather than a second one, so the board a developer
+ * reads in the shell and the board an agent reads mid-run cannot disagree.
+ */
+async function cmdIssues(argv) {
+  const json = argv.includes("--json");
+  const game = positionalArgs(argv, ["--status"])[0];
+  if (!game || !GAME_SLUG_RE.test(game)) {
+    console.error(`✗ not a game slug: ${game || "(missing)"} — lowercase letters, digits and hyphens.\n${ISSUES_USAGE}`);
+    // 1, like `results`: a typo must never reach the network, and 2 is
+    // reserved by the round verbs for "still pending".
+    process.exit(1);
+  }
+  const status = flagValue(argv, "--status");
+  if (status !== undefined && !ISSUE_STATUSES.includes(status)) {
+    console.error(`✗ --status must be one of ${ISSUE_STATUSES.join(", ")}.\n${ISSUES_USAGE}`);
+    process.exit(1);
+  }
+  const args = { game, action: "list" };
+  if (status) args.status_filter = status;
+  const r = await callQapingTool("qaping_issues", args);
+  console.log(json
+    ? JSON.stringify(Object.keys(r.structured).length ? r.structured : r.result, null, 2)
+    : (r.text || JSON.stringify(r.result, null, 2)));
+  process.exit(r.isError ? 1 : 0);
+}
+
+async function cmdRoundsList(argv) {
+  const json = argv.includes("--json");
+  const state = readRoundsFile(roundsFilePath(argv));
+  if (!state || state.rounds.length === 0) {
+    console.log(json ? JSON.stringify({ rounds: [], total: 0, truncated: false, notice: null }, null, 2)
+      : `no open rounds recorded here (${ROUNDS_FILE})`);
+    process.exit(0);
+  }
+  // The cap bounds the FETCHES (one passive call each), not the truth: the
+  // count line and the JSON both report every recorded round, and say so when
+  // only the first N carry live status.
+  const total = state.rounds.length;
+  const rounds = state.rounds.slice(0, MAX_OPEN_ROUNDS);
+  const offlineFlag = argv.includes("--offline");
+  let notice = offlineFlag ? "(live status unavailable — offline)" : null;
+  let live = new Map();
+  if (!offlineFlag) {
+    for (const record of rounds) {
+      try {
+        const r = await callResultsTool(record.ping_id);
+        live.set(record.ping_id, {
+          status: r.status,
+          n_received: r.structured.n_received ?? null,
+          n_target: r.structured.n_target ?? null,
+        });
+      } catch (e) {
+        if (e && e.perRound) {
+          // The service answered and refused this id — that is this round's
+          // status, not the run's. The rest of the listing still gets fetched.
+          live.set(record.ping_id, { status: "unavailable", error: e.message });
+          continue;
+        }
+        // Login and transport fail for the whole pass; name WHICH, because the
+        // remedies are nothing alike.
+        notice = e && e.authRejected
+          ? "(live status unavailable — login rejected: run `qaping setup`)"
+          : `(live status unavailable — ${(e && e.message) || "offline"})`;
+        live = new Map();
+        break;
+      }
+    }
+  }
+  const entries = rounds.map((record) => ({ record, live: live.get(record.ping_id) || null }));
+  console.log(json
+    ? JSON.stringify({
+      rounds: entries.map((e) => ({ ...e.record, live: e.live })),
+      total,
+      truncated: total > rounds.length,
+      notice,
+    }, null, 2)
+    : renderRounds(entries, { total, notice }));
+  process.exit(0);
+}
+
+function cmdRoundsAdd(argv) {
+  const json = argv.includes("--json");
+  const pingId = argv[2];
+  if (!pingId || pingId.startsWith("--") || !PING_ID_RE.test(pingId)) {
+    console.error(`✗ not a ping id: ${pingId || "(missing)"}\n${ROUNDS_USAGE}`);
+    process.exit(2);
+  }
+  const platform = flagValue(argv, "--platform");
+  if (platform && !["windows", "macos", "ios"].includes(platform)) {
+    console.error(`✗ --platform must be windows, macos or ios — a web round has none, so omit it.\n${ROUNDS_USAGE}`);
+    process.exit(2);
+  }
+  // Validated here, not just recorded: a slug the service would refuse is a
+  // board the collecting session could never read.
+  const game = flagValue(argv, "--game");
+  if (game !== undefined && !GAME_SLUG_RE.test(game)) {
+    console.error(`✗ --game must be a slug: lowercase letters, digits and hyphens (the QA plan's game_slug).\n${ROUNDS_USAGE}`);
+    process.exit(2);
+  }
+  const file = roundsFilePath(argv);
+  const minutes = intFlag(argv, "--minutes");
+  const deadline = intFlag(argv, "--deadline-seconds");
+  const checks = (flagValue(argv, "--checks") || "").split(",").map((s) => s.trim()).filter(Boolean);
+  const note = flagValue(argv, "--note");
+  const build = flagValue(argv, "--build");
+  const patch = {};
+  if (platform) patch.platform = platform;
+  if (game) patch.game = game;
+  if (build) patch.build = build;
+  if (minutes != null) patch.est_minutes = minutes;
+  if (deadline != null) patch.deadline_seconds = deadline;
+  if (checks.length) patch.checks = checks;
+  if (note) patch.note = note;
+  // Read and write inside ONE lock: a background poller's `rounds rm` landing
+  // between this read and this write used to drop whichever record lost.
+  const { record, count, updated } = mutateRoundsFile(file, (state) => {
+    const existing = state.rounds.find((r) => r.ping_id === pingId);
+    // Re-adding the same id CORRECTS a record, never duplicates it — and keeps
+    // the original filed_at, which is what the visibility window counts from.
+    const rec = {
+      ...(existing || {}),
+      ping_id: pingId,
+      filed_at: (existing && existing.filed_at) || new Date().toISOString(),
+      ...patch,
+    };
+    const next = upsertRound(state, rec);
+    return { state: next, record: rec, count: next.rounds.length, updated: !!existing };
+  });
+  if (json) {
+    console.log(JSON.stringify({ file, recorded: record, rounds: count }, null, 2));
+    process.exit(0);
+  }
+  console.log(`✓ recorded round ${pingId} in ${ROUNDS_FILE}${updated ? " (updated)" : ""}`);
+  console.log(`  collect it later: \`qaping rounds\` lists what this repo is owed; \`qaping results ${pingId}\` fetches this one.`);
+  console.log(`  ${ROUNDS_FILE} is open state, not history — add it to .gitignore.`);
+  if (count > MAX_OPEN_ROUNDS) {
+    console.log(`  ⚠ ${count} rounds recorded — \`qaping rounds\` fetches live status for the first ${MAX_OPEN_ROUNDS}. Collect some.`);
+  }
+  process.exit(0);
+}
+
+function cmdRoundsRm(argv) {
+  const json = argv.includes("--json");
+  const pingId = argv[2];
+  if (!pingId || pingId.startsWith("--")) {
+    console.error(`✗ qaping rounds rm needs a ping id.\n${ROUNDS_USAGE}`);
+    process.exit(2);
+  }
+  const file = roundsFilePath(argv);
+  // Same lock as `add`: this is the verb a background poller runs while the
+  // agent that filed the next round is recording it.
+  const { removed, count } = mutateRoundsFile(file, (state) => {
+    const { state: next, removed: didRemove } = removeRound(state, pingId);
+    // No write at all when nothing matched — a no-op must not rewrite the file.
+    return { state: didRemove ? next : null, removed: didRemove, count: next.rounds.length };
+  });
+  if (!removed) {
+    console.error(`✗ no round ${pingId} recorded in ${ROUNDS_FILE}`);
+    process.exit(1);
+  }
+  console.log(json ? JSON.stringify({ removed: pingId, rounds: count }, null, 2)
+    : `✓ removed ${pingId} from ${ROUNDS_FILE} (${count} open round(s) left)`);
+  process.exit(0);
+}
+
+async function cmdRounds(argv) {
+  const sub = argv[1];
+  if (sub === "add") return cmdRoundsAdd(argv);
+  if (sub === "rm" || sub === "delete" || sub === "remove") return cmdRoundsRm(argv);
+  if (sub === "--help" || sub === "-h") { console.log(ROUNDS_USAGE); process.exit(0); }
+  if (sub && !sub.startsWith("--")) {
+    console.error(`✗ unknown: qaping rounds ${sub}\n${ROUNDS_USAGE}`);
+    process.exit(2);
+  }
+  return cmdRoundsList(argv);
+}
+
 const HELP = `qaping — automatic QA for your game: real human playtesters, driven by your coding agent
 
 usage:
   qaping setup [claude-code|cursor|codex] [--force]
   qaping remove [--client <c>]        remove qaping's MCP entries, skill and rule
   qaping publish-build <game.zip> --platform windows|macos
+  qaping builds                       the hosted builds you hold (oldest first)
+  qaping builds rm <slug>             delete one now, freeing its slot
   qaping publish <built-dir>          host a WEB game's built output (prints the URL to file with)
   qaping wait <ping_id> [--timeout <seconds>]
+  qaping results <ping_id>            one passive fetch — exit 0 news, 2 still pending, 1 otherwise
+  qaping rounds                       the parked rounds this repo is owed, with live status
+  qaping rounds add <ping_id> …       record a parked round so a later session collects it
+  qaping rounds rm <ping_id>          forget one, once it is collected or expired
+  qaping issues <game>                the game's issue board (read-only; the agent moves it)
   qaping whoami
   qaping version
 
@@ -245,23 +827,38 @@ function route(cmd) {
   if (cmd === "remove" || cmd === "uninstall") return "remove";
   if (cmd === "wait" || cmd === "whoami") return "vendor";
   if (cmd === "publish-build") return "publish-build";
+  if (cmd === "builds") return "builds";
   if (cmd === "publish") return "publish";
+  if (cmd === "rounds") return "rounds";
+  if (cmd === "results") return "results";
+  if (cmd === "issues") return "issues";
   return "unknown";
 }
 
+// The async commands' rejection handler: a clean one-line message, never a raw
+// stack — same contract as the sync catch in main() below.
+function die(e) {
+  console.error(`✗ ${(e && e.message) || e}`);
+  process.exit(1);
+}
+
 function main() {
   const argv = process.argv.slice(2);
   try {
     switch (route(argv[0])) {
       case "version": return console.log(require("../package.json").version);
       case "help": return console.log(HELP);
-      case "setup": return void cmdSetup(argv).catch((e) => { console.error(`✗ ${(e && e.message) || e}`); process.exit(1); });
+      case "setup": return void cmdSetup(argv).catch(die);
       case "remove": return cmdRemove(argv);
       // `wait` also names the wait tool the qaping mount registers — the
       // vendored default (the stock mount's wait) is not on /api/mcp/qaping.
       case "vendor": return process.exit(spawnVendor(argv[0] === "wait" ? [...argv, "--wait-tool", "qaping_wait"] : argv));
       case "publish-build": return void cmdPublishBuild(argv);
+      case "builds": return void cmdBuilds(argv);
       case "publish": return void cmdPublish(argv);
+      case "rounds": return void cmdRounds(argv).catch(die);
+      case "results": return void cmdResults(argv).catch(die);
+      case "issues": return void cmdIssues(argv).catch(die);
       default:
         console.error(HELP);
         process.exit(1);
@@ -275,4 +872,8 @@ function main() {
 }
 
 if (require.main === module) main();
-module.exports = { route, resolveKitDir, qapingWrapper, vendorFlags, isSourceCheckout, RULE_BODY, HELP };
+module.exports = {
+  route, resolveKitDir, qapingWrapper, vendorFlags, isSourceCheckout, RULE_BODY, HELP,
+  ROUNDS_FILE, MAX_OPEN_ROUNDS, GAME_SLUG_RE,
+  parseRounds, upsertRound, removeRound, visibleUntil, renderRounds,
+};