@qaping/cli 0.1.4 → 0.2.0

package/bin/qaping

@@ -11,7 +11,10 @@
 //   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 whoami | version | help
 "use strict";
 const fs = require("fs");
@@ -22,6 +25,11 @@ const { spawnSync } = require("child_process");
 
 const QPKG = path.resolve(__dirname, "..");
 
+// The name npm actually serves. The bare `qaping` is refused by the registry's
+// similarity rule (petition open, QAPING_PLAN.md §8), so every global install —
+// the wrapper's own and the one the kit's setup performs — must use this.
+const NPM_PACKAGE = "@qaping/cli";
+
 // The kit is a normal npm dependency when qaping is installed, and a workspace
 // sibling in the monorepo checkout (where node_modules may not be linked yet)
 // — resolve the package, never a hardcoded install path.
@@ -42,8 +50,10 @@ 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).
+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 temporary 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) and qaping_wait (continue a pending round).
+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 no transcript; web rounds return answers only (no recording, no transcript) — never promise evidence a platform 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.
 `;
@@ -55,7 +65,7 @@ function qapingWrapper() {
     brand: "qaping",
     // npm registry name ≠ bin name: the similarity rule blocks bare "qaping"
     // (petition open, QAPING_PLAN §8), so the global install pulls @qaping/cli.
-    installPackage: "@qaping/cli",
+    installPackage: NPM_PACKAGE,
     appUrl: process.env.QAPING_APP_URL || undefined,
     mcpPath: "/api/mcp/qaping",
     serverKey: "qaping",
@@ -122,6 +132,32 @@ function defaultIO(kitDir) {
 
 const VALID_CLIENTS = ["claude-desktop", "claude-code", "cursor", "codex"];
 
+// The kit's setup step 2 installs the global bin as `npm i -g <brand>` unless
+// it is handed an installPackage — and a PUBLISHED kit older than that option
+// ignores it, so it runs `npm i -g qaping`, a name npm's similarity rule
+// refuses to host (404). Hit live on a fresh machine: setup configured every
+// MCP client and reused the login, then reported "Setup incomplete" over that
+// one 404.
+//
+// So the wrapper installs its OWN bin first, under the name npm serves. Once
+// `qaping` is on PATH the kit's step finds it and logs "already installed
+// globally", whatever kit version is underneath. npx runs from a cache dir
+// that is NOT a persistent install — exactly the case that step exists for —
+// so a cache/tmp path does not count as already installed.
+function ensureGlobalBin(io) {
+  if (isSourceCheckout()) return;
+  const existing = io.which("qaping");
+  const persistent =
+    existing && !/[\\/](_npx|_cacache|npm-cache|Temp|tmp)[\\/]/i.test(existing);
+  if (persistent) return;
+  io.log(`Installing the qaping command (npm i -g ${NPM_PACKAGE})…`);
+  const r = io.run("npm", ["i", "-g", NPM_PACKAGE]);
+  if (!r || r.error || r.status !== 0) {
+    io.log(`⚠ could not install the qaping command — run it yourself: npm i -g ${NPM_PACKAGE}`);
+    io.log("  (setup continues; the MCP tools your agent calls do not need it, but `qaping publish-build` does)");
+  }
+}
+
 async function cmdSetup(argv) {
   const kitDir = resolveKitDir();
   const { setup } = require(path.join(kitDir, "harness", "setup.js"));
@@ -129,7 +165,9 @@ async function cmdSetup(argv) {
   // accepts both the positional form (`setup cursor`) and `setup --client cursor`
   const args = argv.filter((a) => a !== "--force");
   const client = ((args[1] === "--client" ? args[2] : args[1]) || "").toLowerCase();
-  const r = await setup(defaultIO(kitDir), {
+  const io = defaultIO(kitDir);
+  ensureGlobalBin(io);
+  const r = await setup(io, {
     home: os.homedir(),
     sourceCheckout: isSourceCheckout(),
     resolveToken,
@@ -184,6 +222,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
@@ -192,14 +239,508 @@ 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;
+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]
+                              [--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}`);
+    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 — 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
+// the 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 id".
+async function callResultsTool(pingId) {
+  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: "qaping_results", arguments: { ping_id: pingId } },
+      }),
+      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,
+    text: (result.content && result.content[0] && result.content[0].text) || "",
+  };
+}
+
+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);
+}
+
+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);
+  }
+  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 (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 whoami
   qaping version
 
@@ -212,23 +753,36 @@ 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";
   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);
       default:
         console.error(HELP);
         process.exit(1);
@@ -242,4 +796,7 @@ 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, parseRounds, upsertRound, removeRound, visibleUntil, renderRounds,
+};

package/docs/QA-PLAN-FORMAT.md

@@ -109,6 +109,24 @@ per round; the plan's `last_verified` and `state` are derived from it and
 stay the dev-readable contract. Open `follow_ups` are what the next filing
 must carry forward.
 
+## Rounds still open — qa-open-rounds.json
+
+A playtest may run for many hours, so a round the agent cannot sit through is
+PARKED: filed with an explicit long deadline, then recorded in
+`qa-open-rounds.json` (same directory) so a LATER session collects it —
+
+```json
+{"rounds": [{"ping_id": "<uuid>", "filed_at": "<ISO>", "platform": "windows",
+  "build": "<the hosted or store URL>", "est_minutes": 10,
+  "deadline_seconds": 86400, "checks": ["<check ids>"],
+  "note": "<the patch this round covers>"}]}
+```
+
+`qaping rounds` lists it with each round's live status, `qaping rounds add`
+records one, `qaping rounds rm` drops it once collected. This file is the
+opposite of the ledger and never merges with it: mutable OPEN state, one entry
+per round still owed, emptied as rounds land. It is not history — gitignore it.
+
 ## Maintenance rules
 
 - Every run updates the run checks' `state` and `last_verified` from typed

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@qaping/cli",
-  "version": "0.1.4",
+  "version": "0.2.0",
+  "homepage": "https://qaping.dev",
   "description": "qaping: automatic QA for your game. Your coding agent authors and maintains the QA plan, ships each patch's build to real human playtesters, and reports what broke.",
   "keywords": [
     "qaping",
@@ -24,7 +25,7 @@
     "node": "^20.17.0 || ^22.13.0 || >=23.5.0"
   },
   "dependencies": {
-    "pingfusi": "^0.16.0"
+    "pingfusi": "^0.16.1"
   },
   "publishConfig": {
     "access": "public"

package/skill/qaping/SKILL.md

@@ -17,18 +17,37 @@ cheaper. All service contact goes through three MCP tools —
 
 ## Ground rules (read before filing anything)
 
-- **Playtesters are real people, and waiting is background work.** A session
-  takes real minutes to be claimed and played, and the wait chain matters: each
-  `qaping_wait` renews the lease that keeps the round visible to new claimants.
-  The moment a filing returns pending, SPAWN A BACKGROUND TASK that loops
-  `qaping_wait` with the ping_id until results arrive, and keep working on
-  other things — that is the intended shape, the same as every pingfusi round.
-  Only if your harness has no background tasks: keep polling in the foreground.
-  Only in a one-shot print mode where neither is possible: say plainly that the
-  round is pending, give the ping_id, and ask to be re-invoked to continue —
-  never promise polling you cannot do (an ended session cannot poll; a round
-  went invisible and expired unclaimed exactly this way, live). Never report
-  pending as the final answer, never file a duplicate round.
+- **Playtesters are real people, and a round outlives a quick turn.
+  Decide at filing time: wait, or park.** A session takes real minutes, often
+  hours, to be claimed and played. Which of the two endings this round gets is
+  chosen BEFORE you file, not discovered when pending surprises you.
+  - **WAIT — short rounds you can sit through.** Each `qaping_wait` renews the
+    lease that keeps the round visible to new claimants. The moment a filing
+    returns pending, SPAWN A BACKGROUND TASK that loops `qaping_wait` with the
+    ping_id until results arrive, and keep working on other things — that is
+    the intended shape, the same as every pingfusi round. Only if your harness
+    has no background tasks: keep polling in the foreground. A one-shot print
+    mode where neither is possible is not a WAIT round at all — it is a PARK
+    (below): file with an explicit `deadline_seconds`, record it with `qaping
+    rounds add <ping_id>`, say what is pending, and ask to be re-invoked to
+    collect it — never promise polling you cannot do (an ended session cannot
+    poll). A round already filed on the default lease is recorded anyway,
+    flagged as likely to expire unclaimed.
+  - **PARK — long or overnight rounds.** For a session nobody will sit
+    through — an overnight run, `n_target > 1` on a small pool, a native round
+    whose claim is slow, an explicit "check tomorrow", or a one-shot mode —
+    file with an explicit `deadline_seconds` sized to the span you are willing
+    to wait (the tool schema states the ceiling) plus an `idempotency_key`,
+    then IMMEDIATELY record it: `qaping rounds add <ping_id> --build <url>
+    --minutes N --checks <ids> --note "<patch>"`, which writes
+    `qa-open-rounds.json` at the repo root (gitignore it — open state, not
+    history). Then tell the user exactly what is pending and what will collect
+    it, and end the turn cleanly.
+  - **A recorded parked round is an honest pending end; an unrecorded "I'll
+    check later" never is.** Never park on the default lease: with no explicit
+    `deadline_seconds` an unwaited round leaves the feed within minutes and
+    expires unclaimed (a round died exactly that way, live). On resume,
+    collect the recorded round — never file a duplicate.
 - **Costs are duration-billed**: 2 credits per minute of play, per playtester
   (`est_minutes × 2 × players`). State the estimate to the user BEFORE filing,
   and set the wait expectation honestly in the same message: claim time is
@@ -51,6 +70,37 @@ cheaper. All service contact goes through three MCP tools —
 - **QA-PLAN.md is the dev's file.** Commit it only with their approval; never
   delete or demote a human check without them agreeing.
 
+## Open rounds — collect FIRST
+
+Before ANY qaping work in a repo — a new run, a plan edit, a plain "did it
+come back yet?" — read `qa-open-rounds.json` at the repo root. `qaping rounds`
+lists it with each round's live status; without the CLI, call `qaping_results`
+once per recorded `ping_id`. The file is this, and nothing else:
+
+```json
+{"rounds": [{"ping_id": "<uuid>", "filed_at": "<ISO>", "platform": "windows",
+  "build": "<the /b/<slug> or store URL>", "est_minutes": 10,
+  "deadline_seconds": 86400, "checks": ["boot-to-menu"],
+  "note": "<the patch this round covers>"}]}
+```
+
+- **READY** (results are in): collect it BEFORE starting new work — the full
+  RUN report ritual (evidence line, computed headline, per-check rows, PR
+  comment, issues, plan updates, ledger append), then
+  `qaping rounds rm <ping_id>`.
+- **Still pending**: say so plainly, with what it is still waiting on, and
+  leave it recorded. Never refile it and never start a second round on the
+  same checks while it is open.
+- **Expired or unreadable**: report that honestly — an expired round bought
+  nothing — then `qaping rounds rm <ping_id>` and offer a refile (a fresh
+  build URL if the old one expired, and a longer `deadline_seconds`).
+- **Not visible from this login** reads identically to gone, and is not the
+  same thing: results are asker-scoped, so a round filed from another account
+  is alive and invisible. Check `qaping whoami` before deleting that record.
+
+`qa-open-rounds.json` is mutable OPEN state; `qa-rounds.jsonl` is append-only
+history written after results land. Never merge the two.
+
 ## The review interface (know your tester)
 
 <!-- Distilled from QAPING_REVIEWER_INTERFACE.md (monorepo root, INTERNAL,
@@ -187,9 +237,16 @@ checks testimony-only — mark that in the plan and report at that grade.
    static directory (web).
 4. **Ship**, by delivery: NATIVE uploads — `qaping publish-build <game.zip>
    --platform windows|macos` → prints a `/b/<slug>` URL (temporary hosting;
-   filing a playtest extends the build through the round; each publish mints a
-   NEW URL). Store-delivered games file with their Steam store page, TestFlight
-   public link, or App Store page as `url`. WEB games — host the built output
+   filing a playtest extends the build through the round; a CHANGED build gets
+   a new URL, while re-publishing an unchanged zip returns the same build).
+   You hold only a handful of hosted builds at once: if a publish is refused
+   for that cap, `qaping builds` lists what you are holding and
+   `qaping builds rm <slug>` frees a slot — do that and carry on rather than
+   stopping to ask. The listing marks each build: never-finished uploads are
+   safe to delete first, and any build an open round is still using is marked
+   `IN USE` — never delete one of those, whichever session filed it. If every
+   build is in use, say so and wait for a round to finish rather than guessing. Store-delivered games file with their Steam store
+   page, TestFlight public link, or App Store page as `url`. WEB games — host the built output
    at a public URL: the dev's own hosting if they have it, else
    `qaping publish <built-dir>` prints a hosted URL. Localhost never works —
    players open the link on their own devices. When filing a WEB game: send
@@ -251,9 +308,13 @@ checks testimony-only — mark that in the plan and report at that grade.
    tester and silently dropped at finish, which is why this gate exists. A
    mismatch (the budget forcing cuts) fails loudly PRE-SPEND: batch another
    session or state the deferral out loud — never silently truncate.
-6. **Wait, in the background:** spawn a background task looping `qaping_wait`
-   and keep working (see ground rules) — foreground polling is the fallback,
-   and a promise to check later is never a wait.
+6. **Wait or park — decide now** (ground rule 1). WAIT: spawn a background
+   task looping `qaping_wait` and keep working — foreground polling is the
+   fallback. PARK: the filing already carried an explicit `deadline_seconds`
+   sized to the span, so record it — `qaping rounds add <ping_id> --build
+   <url> --minutes N --checks <ids> --note "<patch>"` — tell the user what is
+   pending, and end the turn; a later session collects it. A promise to check
+   later is never a wait, and never a substitute for the record.
 7. **Report** from `qaping_results`:
    - **Evidence line first (MUST).** Every report opens with its grade:
      `Evidence: recording + transcript` (macOS/iOS) / `Evidence: recording
@@ -292,6 +353,10 @@ checks testimony-only — mark that in the plan and report at that grade.
      `last_verified` stays in QA-PLAN.md as the dev-readable contract derived
      from it, and "carry findings forward" is a read of the last line's
      follow_ups, not prose archaeology.
+   - **Close a parked round (MUST).** In the same step as the ledger append,
+     drop this round from `qa-open-rounds.json` with
+     `qaping rounds rm <ping_id>`, so the open-state file never outlives the
+     round it names.
    - Update `QA-PLAN.md` from the outcomes: Pass → `state: passed` and
      `last_verified` this build/date; a Fail with hard evidence → `failing`;
      a Fail that could be dirty state or tester noise → `ambiguous`;