feat(queue): Piece D, reviews as issue comments, raw per-seat token helper (row 12, #1508)

queue move ID in-review posts the review request as a Gitea comment and
review record reads verdicts back, so reviews stop being files in
docs/plans/reviews/. On a comment round, in-review to waiting-on-jason
now needs every listed reviewer's approval for the current round, the
same as in-review to done (Filbert r1 C1). scripts/gitea-api.sh reads
the raw per-seat token files (lead decisions 37 to 39): config built and
checked before curl starts, export attribute cleared, fixed base URL.
test-queue.sh skips its live checks outside the canonical root.

Darkwing authored. Filbert approved D r2 (cf1d3fd0) after r1 (a2dc2302)
and corrected the plan (293747cd). Rocko reviewed the helper (e896192f,
2096b0a3), and Sage's lead check passed under decision 38. Manifest
b402fb38, 19 files.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

packages/queue/src/cli.mjs

@@ -8,17 +8,22 @@
 //             release ID | assign ID SEAT | note ID TEXT | set ID FIELD VALUE [--reason TEXT]
 //             genesis --root PATH --branch NAME --map PATH
 //             accept-history --reason TEXT --yes
+//             review request ID | review resolve ID ATTEMPT --comment N
+//             review abandon ID ATTEMPT --reason TEXT --yes
+//             review record ID --verdict approve|changes --comment N --candidate DIGEST
 //             Each needs --op ID and an actor (--by NAME or $MOSAIC_AGENT_NAME).
+// Read only:  review verify-commit ID REF
 // No log:     render [--check] | verify [--current] | verify --snapshot DIR (--base-file F | --base-absent)
 //             sync [--op ID] | snapshot --out DIR | unlock [--check-gate]
 //
 // Exit codes: 0 ok; 1 operation failed; 2 invalid data or refused;
-// 3 uncertain (visible or durable, not acknowledged); 4 usage.
+// 3 uncertain (visible or durable, not acknowledged; for a request, not
+// known to be posted); 4 usage.
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { QueueError } from "./errors.mjs";
 import { SET_FIELDS } from "./queue.mjs";
-import { list, mutate, next, renderView, show, snapshot, sync, unlock, verify, verifySnapshot } from "./store.mjs";
+import { list, mutate, next, renderView, show, snapshot, sync, unlock, verify, verifyCommit, verifySnapshot } from "./store.mjs";
 
 const USAGE = [
   "usage: queue list | show ID | next [SEAT]",
@@ -28,6 +33,10 @@ const USAGE = [
   `       queue set ID FIELD VALUE --op ID [--reason TEXT]   (fields: ${SET_FIELDS.join(", ")})`,
   "       queue genesis --op ID --root PATH --branch NAME --map PATH",
   "       queue accept-history --op ID --reason TEXT --yes",
+  "       queue review request ID --op ID | review resolve ID ATTEMPT --comment N --op ID",
+  "       queue review abandon ID ATTEMPT --reason TEXT --yes --op ID",
+  "       queue review record ID --verdict approve|changes --comment N --candidate DIGEST --op ID",
+  "       queue review verify-commit ID REF",
   "       queue render [--check] | verify [--current] | verify --snapshot DIR (--base-file F | --base-absent)",
   "       queue sync [--op ID] | snapshot --out DIR | unlock [--check-gate]",
   "       every change takes --by NAME, else $MOSAIC_AGENT_NAME",
@@ -36,6 +45,7 @@ const USAGE = [
 const VALUE_FLAGS = new Set([
   "--op", "--by", "--piece", "--gate", "--brief", "--issue", "--note", "--owner", "--gate-owner", "--after", "--reviewer",
   "--reason", "--candidate", "--evidence", "--root", "--branch", "--map", "--snapshot", "--base-file", "--out",
+  "--verdict", "--comment",
 ]);
 const REPEATED = new Set(["--issue", "--after", "--reviewer"]);
 const BOOL_FLAGS = new Set(["--required", "--yes", "--check", "--current", "--base-absent", "--check-gate"]);
@@ -80,6 +90,38 @@ function intArg(v, what) {
   return Number(v);
 }
 
+// Gitea comment ids outgrow a row id's seven digits.
+function commentArg(v) {
+  if (v === null) throw usage("--comment N is required");
+  if (!/^[1-9][0-9]{0,15}$/.test(v) || !Number.isSafeInteger(Number(v))) throw usage(`--comment must be a comment id: ${JSON.stringify(v)}`);
+  return Number(v);
+}
+
+function review(pos, flags, f, change, opts) {
+  const [sub, ...rest] = pos;
+  switch (sub) {
+    case "request":
+      allow(flags, CHANGE); positional(rest, 1, "review request ID");
+      return change("review-request", { id: intArg(rest[0], "ID") });
+    case "resolve":
+      allow(flags, [...CHANGE, "--comment"]); positional(rest, 2, "review resolve ID ATTEMPT");
+      return change("review-resolve", { id: intArg(rest[0], "ID"), attempt: rest[1], comment: commentArg(f("--comment")) });
+    case "abandon":
+      allow(flags, [...CHANGE, "--reason", "--yes"]); positional(rest, 2, "review abandon ID ATTEMPT");
+      if (f("--reason") === null) throw usage("review abandon needs --reason");
+      return change("review-abandon", { id: intArg(rest[0], "ID"), attempt: rest[1], reason: f("--reason") }, { yes: flags.has("--yes") });
+    case "record":
+      allow(flags, [...CHANGE, "--verdict", "--comment", "--candidate"]); positional(rest, 1, "review record ID");
+      for (const k of ["--verdict", "--candidate"]) if (f(k) === null) throw usage(`review record needs ${k}`);
+      return change("review-record", { id: intArg(rest[0], "ID"), verdict: f("--verdict"), comment: commentArg(f("--comment")), candidate: f("--candidate") });
+    case "verify-commit":
+      allow(flags, []); positional(rest, 2, "review verify-commit ID REF");
+      return verifyCommit(opts, intArg(rest[0], "ID"), rest[1]);
+    default:
+      throw usage("review takes request, resolve, abandon, record or verify-commit");
+  }
+}
+
 function afterArg(v) {
   const m = /^([1-9][0-9]{0,6})(?::(done|settled))?$/.exec(v);
   if (!m) throw usage(`--after takes ID or ID:settled: ${JSON.stringify(v)}`);
@@ -161,6 +203,8 @@ export function run(argv, opts = {}) {
       allow(flags, [...CHANGE, "--reason", "--yes"]); positional(pos, 0, "only options");
       if (f("--reason") === null) throw usage("accept-history needs --reason");
       return change("accept-history", { reason: f("--reason") }, { yes: flags.has("--yes") });
+    case "review":
+      return review(pos, flags, f, change, opts);
     case "render":
       allow(flags, ["--check"]); positional(pos, 0, "no arguments");
       return renderView(opts, { check: flags.has("--check") });