@quickchatai/quickreview 1.1.0 → 1.2.0

package/dist/src/onboard/steps/proof.js

@@ -4,14 +4,23 @@
 // the review it produced before anything could ever reach GitHub.
 //
 // The shape:
-//   1. ask for a real PR of theirs with the trigger label on it (the wizard
-//      never creates a demo PR);
-//   2. follow the round to completion THROUGH THE STATE STORE — the daemon's
+//   1. ask for one real, open PR (a number or its URL; the five most recently
+//      updated open PRs of the repo are offered, the person's own included —
+//      on the own-account route those are the main target). The wizard never
+//      creates a demo PR;
+//   2. start its review IMMEDIATELY: one `review-now` command into the
+//      daemon's root-sealed operator channel (src/commands.ts, the channel
+//      `qcr drain` and the TUI's levers use), which queues the PR exactly as a
+//      fresh trigger label would — with no GitHub write and no label for the
+//      person to add. A daemon that cannot take the command (an older image)
+//      falls back to the label, said plainly;
+//   3. follow the round to completion THROUGH THE STATE STORE — the daemon's
 //      own record, read with the daemon's own `qcr why --json` inside the
 //      container, so the wizard is reading exactly what the operator would;
-//   3. SHOW the finished review, read out of the dry-run record — the file the
-//      mutation gate wrote INSTEAD of calling GitHub. The operator judges the
-//      output while it is still impossible for it to have posted.
+//   4. SHOW the finished review, read out of the dry-run record — the file the
+//      mutation gate wrote INSTEAD of calling GitHub: the verdict, how many
+//      findings, the top ones, and where the full text is. The operator judges
+//      the output while it is still impossible for it to have posted.
 //
 // Two paths get real guidance rather than a spinner, because they are the two
 // that actually happen: the round never starts (label spelling, webhook not
@@ -19,17 +28,26 @@
 // is cancelled (the daemon's own event log says why). Neither ever hangs: the
 // poll is bounded and every attempt logs where it got to.
 //
-// Nothing here writes anything anywhere. It reads the state store, reads the
-// dry-run directory, and records what it saw on the checklist — the record the
-// go-live step later demands before it will even offer the flip.
+// The one thing it writes is that operator command file. Otherwise it reads the
+// state store, the dry-run directory and (to offer PRs) GitHub, and records
+// what it saw on the checklist — the record the go-live step later demands
+// before it will even offer the flip.
+import { join } from "node:path";
+import { mintAppJwt, USER_TOKEN_FILE } from "@quickchatai/pi-quickreview/src/githubAuth.js";
 import { loadConfig } from "../../config.js";
-import { CHOICE_KEYS } from "../choices.js";
+import { operatorCommandWriteScriptAt } from "../../operatorwrite.js";
+import { CHOICE_KEYS, userAuthRecorded } from "../choices.js";
+import { readTextOrNull } from "../engine.js";
 import { decodeDryrunRecord, sandboxReviewFrom, } from "../../compare.js";
-import { CONTAINER_DRYRUN_DIR, configPath, readConfigText } from "./compose.js";
-import { readTomlKey } from "./ingress.js";
-import { DEFAULT_LABELS } from "./githubapp.js";
+import { CONTAINER_COMMANDS_DIR, CONTAINER_DRYRUN_DIR, configPath, readConfigText, } from "./compose.js";
+import { readTomlKey, secretsDirFor } from "./ingress.js";
+import { DEFAULT_LABELS, api, findInstallation, installationToken, parseRepoSlug, readCredentials, } from "./githubapp.js";
 import { stackTransportFor } from "./transport.js";
 export const PROOF_STEP_ID = "proof_round";
+/** A string input or choice, else "" — never an object's stringification. */
+function textOf(v) {
+    return typeof v === "string" ? v : "";
+}
 /** The completed-proof record. The go-live step will not offer the flip
  * without it AND a state-store re-verification of it. */
 export const PROOF_CHOICE_KEY = CHOICE_KEYS.proof;
@@ -180,14 +198,42 @@ export async function readContainerDryrun(transport, limit = 40, opts = {}) {
 export function recordForPr(r, pr) {
     return r.pr === pr || new RegExp(`/(pulls|issues)/${pr}(/|$)`).test(r.path);
 }
+/** How many findings the summary lists before "and N more". */
+export const TOP_FINDINGS = 5;
+/** The first line of a comment, trimmed to one readable line. */
+function headline(body) {
+    const line = body
+        .trim()
+        .split("\n")
+        .find((l) => l.trim() !== "") ?? "";
+    const flat = line.trim();
+    return flat.length > 160 ? `${flat.slice(0, 157)}…` : flat;
+}
 /** The would-be review, rendered for a human to judge. */
-export function renderReview(review, pr) {
+export function renderReview(review, pr, extras = {}) {
+    const top = review.comments
+        .slice(0, TOP_FINDINGS)
+        .map((c, i) => `  ${i + 1}. ${c.path}:${c.line} — ${headline(c.body)}`);
+    const more = review.comments.length - top.length;
     const head = [
         `This is the review your reviewer produced for #${pr}. It was NOT posted: dry_run is on, so the`,
         `mutation gate wrote it to state/dryrun/ instead of calling GitHub.`,
         "",
         `Verdict it would have submitted: ${review.state}`,
+        ...(extras.verdict && extras.verdict !== review.state
+            ? [
+                `Verdict on the merits: ${extras.verdict} (stated in the review body; GitHub gets it as a ${review.state} review)`,
+            ]
+            : []),
         `Inline comments: ${review.comments.length}`,
+        ...(top.length > 0
+            ? ["Top findings:", ...top, ...(more > 0 ? [`  … and ${more} more, below`] : [])]
+            : []),
+        ...(extras.file
+            ? [
+                `Full text: state/dryrun/${extras.file} in the daemon's state${extras.readCommand ? ` — \`${extras.readCommand}\`` : ""}`,
+            ]
+            : []),
         "",
         "--- review body ---",
         review.body.trim() === "" ? "(empty body)" : review.body.trim(),
@@ -195,6 +241,8 @@ export function renderReview(review, pr) {
     const comments = review.comments.map((c, i) => `--- inline comment ${i + 1}: ${c.path}:${c.line} ---\n${c.body.trim()}`);
     return [...head, ...(comments.length ? ["", ...comments] : [])].join("\n");
 }
+/** How many open PRs the offer lists. */
+export const PR_OFFER_SIZE = 5;
 function triggerLabelOf(adapters) {
     const text = readConfigText(adapters);
     const configured = text ? readTomlKey(text, "github", "trigger_label") : null;
@@ -207,19 +255,98 @@ function repoOf(choices, adapters) {
     const text = readConfigText(adapters);
     return (text ? readTomlKey(text, "github", "repo") : null) ?? "your repository";
 }
+/** A PR answer: 17, "17", "#17", or the PR's URL (github.com/o/r/pull/17).
+ * A URL names its repo too, which the caller checks against the reviewed one. */
+export function parsePrAnswer(raw) {
+    if (typeof raw === "number")
+        return Number.isInteger(raw) && raw > 0 ? { pr: raw, repo: null } : null;
+    if (typeof raw !== "string")
+        return null;
+    const v = raw.trim();
+    const url = /^(?:https?:\/\/)?(?:www\.)?github\.com\/([A-Za-z0-9._-]+\/[A-Za-z0-9._-]+)\/pull\/(\d+)(?:[/?#].*)?$/.exec(v);
+    if (url)
+        return { pr: Number(url[2]), repo: url[1] };
+    const n = /^#?(\d+)$/.exec(v);
+    return n && Number(n[1]) > 0 ? { pr: Number(n[1]), repo: null } : null;
+}
 function prFrom(input, choices) {
-    for (const raw of [input.pr, parseProofRecord(choices[PROOF_CHOICE_KEY])?.pr]) {
-        const n = typeof raw === "string" ? Number(raw.trim()) : raw;
-        if (typeof n === "number" && Number.isInteger(n) && n > 0)
-            return n;
+    for (const raw of [input.pr, input.url, parseProofRecord(choices[PROOF_CHOICE_KEY])?.pr]) {
+        const parsed = parsePrAnswer(raw);
+        if (parsed)
+            return parsed;
     }
     return null;
 }
+/** A command file name the daemon's watcher serves (`*.json`), unique per call. */
+export function reviewNowFileName(now, pr) {
+    return `${now.toISOString().replace(/[:.]/g, "-")}-onboard-reviewnow-${pr}.json`;
+}
+/** The argv that writes one `review-now` command into the root-sealed
+ * operator directory, through the same script the TUI's levers use. The
+ * payload is built here from a number, so it can carry no quote. */
+export function reviewNowWriteArgv(name, pr) {
+    if (!Number.isInteger(pr) || pr <= 0)
+        throw new Error(`not a PR number: ${pr}`);
+    const payload = JSON.stringify({ command: "review-now", pr });
+    return [
+        "sh",
+        "-c",
+        `printf '%s\\n' '${payload}' | ( ${operatorCommandWriteScriptAt(CONTAINER_COMMANDS_DIR, name)} )`,
+    ];
+}
+/** The argv that prints the daemon's result for that command, or `pending`. */
+export function reviewNowResultArgv(name) {
+    const file = `${CONTAINER_COMMANDS_DIR}/results/${name.replace(/\.json$/, "")}.result.json`;
+    return ["sh", "-c", `if [ -f '${file}' ]; then cat '${file}'; else echo pending; fi`];
+}
+/** A token that can read the reviewed repo: the person's token file on the
+ * own-account route, an App installation token on the App route; null when
+ * neither is to hand (the offer is then skipped, never guessed). */
+async function readToken(ctx, repo, apiBase, secretsDir) {
+    if (userAuthRecorded(ctx.choices)) {
+        const token = (readTextOrNull(join(secretsDir, USER_TOKEN_FILE)) ?? "").trim();
+        return token === "" ? null : token;
+    }
+    const creds = readCredentials(secretsDir);
+    if (!creds.complete)
+        return null;
+    try {
+        const jwt = mintAppJwt(creds.appId, creds.pem, () => ctx.adapters.clock().getTime());
+        const found = await findInstallation(ctx.adapters.fetch, apiBase, jwt, repo.owner);
+        if (found.status !== "found")
+            return null;
+        const minted = await installationToken(ctx.adapters.fetch, apiBase, jwt, found.id);
+        return "token" in minted ? minted.token : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The repo's most recently updated open PRs (any author — the person's own
+ * included). Empty when GitHub cannot be read. */
+export async function listOpenPrs(fetchFn, apiBase, token, repo, limit = PR_OFFER_SIZE) {
+    const r = await api(fetchFn, `${apiBase}/repos/${repo.owner}/${repo.name}/pulls?state=open&sort=updated&direction=desc&per_page=${limit}`, { headers: { authorization: `Bearer ${token}` } });
+    if (r.status !== 200 || !Array.isArray(r.body))
+        return [];
+    return r.body
+        .filter((p) => typeof p.number === "number")
+        .slice(0, limit)
+        .map((p) => ({
+        number: p.number,
+        title: typeof p.title === "string" ? p.title : "",
+        author: textOf(p.user?.login),
+        updated_at: typeof p.updated_at === "string" ? p.updated_at : "",
+        draft: p.draft === true,
+    }));
+}
 export function proofRoundStep(opts = {}) {
     const pollAttempts = opts.pollAttempts ?? 60;
     const pollIntervalMs = opts.pollIntervalMs ?? 30_000;
     const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     const dryrunLimit = opts.dryrunLimit ?? 40;
+    const apiBase = opts.apiBase ?? "https://api.github.com";
+    const resultAttempts = opts.resultAttempts ?? 15;
+    const resultIntervalMs = opts.resultIntervalMs ?? 2_000;
     function log(ctx, line) {
         ctx.adapters.log?.(`${PROOF_STEP_ID}: ${line}`);
     }
@@ -236,21 +363,108 @@ export function proofRoundStep(opts = {}) {
             ? { obs, detail: "" }
             : { obs: null, detail: `\`qcr why\` did not answer JSON: ${r.stdout.slice(0, 200)}` };
     }
+    /** Send `review-now` for `pr` and wait for the daemon's receipt. `refused`
+     * means the daemon read the command and said no (its reason is the answer);
+     * otherwise a failure is the channel itself (write or no receipt). */
+    async function requestReview(ctx, transport, pr) {
+        const name = reviewNowFileName(ctx.adapters.clock(), pr);
+        const write = await transport.execAsRoot(reviewNowWriteArgv(name, pr));
+        if (write.code !== 0)
+            return {
+                ok: false,
+                refused: false,
+                detail: `the command write failed: ${(write.stderr || write.stdout).trim().slice(0, 200) || `exit ${write.code}`}`,
+            };
+        for (let attempt = 1; attempt <= resultAttempts; attempt += 1) {
+            await sleep(resultIntervalMs);
+            const read = await transport.exec(reviewNowResultArgv(name));
+            const body = read.code === 0 ? read.stdout.trim() : "";
+            if (body === "" || body === "pending")
+                continue;
+            let v;
+            try {
+                v = JSON.parse(body);
+            }
+            catch {
+                continue; // the daemon may still be writing its receipt
+            }
+            if (v.ok === true)
+                return {
+                    ok: true,
+                    refused: false,
+                    detail: `queued${typeof v.state === "string" ? `, state ${v.state}` : ""}`,
+                };
+            return {
+                ok: false,
+                refused: true,
+                detail: typeof v.reason === "string"
+                    ? v.reason.replace(/\s+/g, " ").slice(0, 300)
+                    : "no reason given",
+            };
+        }
+        return {
+            ok: false,
+            refused: false,
+            detail: `no answer to ${name} after ${resultAttempts} reads — the daemon may still be starting`,
+        };
+    }
+    /** No PR yet: offer the repo's open PRs, and say what happens next. */
+    async function askCheck(ctx, repo, label, posture, typed) {
+        const slug = parseRepoSlug(repo);
+        let offer = [];
+        if (slug) {
+            const token = await readToken(ctx, slug, apiBase, opts.secretsDir ?? secretsDirFor(ctx.adapters, ctx.choices));
+            if (token)
+                offer = await listOpenPrs(ctx.adapters.fetch, apiBase, token, slug);
+        }
+        const me = textOf(ctx.choices[CHOICE_KEYS.accountLogin]);
+        const rows = offer.map((p) => `  #${p.number} ${p.title}${p.draft ? " (draft)" : ""} — by ${p.author}${me !== "" && p.author === me ? " (yours)" : ""}, updated ${p.updated_at}`);
+        const assurance = posture === "true"
+            ? "Nothing will be posted to GitHub: dry_run is on, so every would-be comment and review is written to a file instead, and you will read it here before deciding anything."
+            : posture === "false"
+                ? "This installation is LIVE (dry_run = false): the review will be posted to GitHub. The flag belongs to you; these instructions do not change it."
+                : "The dry_run posture could not be read, so posting is unknown. Check the live config before reviewing a PR.";
+        return {
+            name: "ask",
+            ok: false,
+            detail: (typed ? "That is not a pull request number or link.\n" : "") +
+                "Read this out, then call this tool again with the PR number (pr) or its link (url).\n\n" +
+                (rows.length > 0
+                    ? `The ${rows.length} most recently updated open pull requests in ${repo}:\n${rows.join("\n")}\n` +
+                        "Pick one of these — or any other open PR in it — one you would actually want reviewed.\n"
+                    : `Pick a real, open pull request in ${repo} — one you would actually want reviewed (your own is fine).\n`) +
+                "Its review starts as soon as you name it: nothing to add to the PR. (For later reviews, the trigger is the label " +
+                `"${label}" — the reviewer never reviews anything on its own initiative.)\n` +
+                assurance,
+        };
+    }
     return {
         id: PROOF_STEP_ID,
         title: "The proof: watch a real PR get reviewed",
-        explain: "The wizard does not call itself done until you have seen the reviewer work. Ask the operator to open (or pick) one of " +
-            "their own pull requests and put the trigger label on it, then call this tool with that PR number. It follows the round " +
-            "through the daemon's own state until a verdict lands, and then SHOWS them the review it produced — read out of the " +
-            "dry-run record, so they judge the output while it is still impossible for it to have posted to GitHub. If nothing " +
-            "happens, or the round fails, it says what to check rather than waiting forever.",
+        explain: "The wizard does not call itself done until you have seen the reviewer work, on one real, open pull request. Call this " +
+            "tool with no arguments to get the repo's five most recently updated open PRs (the operator's own included) to pick " +
+            "from, then call it again with pr (a number) or url (the PR's link). The review starts IMMEDIATELY — no label to add: " +
+            "the wizard asks the daemon directly. It follows the round through the daemon's own state until a verdict lands, then " +
+            "SHOWS the review — the verdict, how many findings, the top ones, and where the full text is — read out of the " +
+            "dry-run record, so they judge it while it is still impossible for it to have posted to GitHub. If nothing happens, " +
+            "or the round fails, it says what to check rather than waiting forever.",
         order: 76,
+        // After setup: the board offers it; finish never waits on it.
+        optional: true,
         parameters: {
             type: "object",
             properties: {
                 pr: {
                     type: "integer",
-                    description: "The pull request number the operator labelled. Call with no arguments first to get the exact instructions to read out.",
+                    description: "The pull request number to review now. Call with no arguments first to get the open PRs to choose from.",
+                },
+                url: {
+                    type: "string",
+                    description: "The pull request's URL, instead of its number (github.com/<owner>/<repo>/pull/<n>).",
+                },
+                confirm_live: {
+                    type: "string",
+                    description: 'Only when the installation is LIVE (dry_run = false): "yes" means the operator agreed that this review posts to GitHub.',
                 },
             },
         },
@@ -258,30 +472,44 @@ export function proofRoundStep(opts = {}) {
             const transport = stackTransportFor(ctx, opts.transport);
             const repo = repoOf(ctx.choices, ctx.adapters);
             const label = triggerLabelOf(ctx.adapters);
-            const pr = prFrom(ctx.input, ctx.choices);
-            if (pr === null) {
-                let posture = null;
-                try {
-                    posture = String(loadConfig(configPath(ctx.adapters)).dry_run);
-                }
-                catch {
-                    /* Unknown posture stays explicit. */
-                }
-                const assurance = posture === "true"
-                    ? "Nothing will be posted to GitHub: dry_run is on, so every would-be comment and review is written to a file instead, and you will read it here before deciding anything."
-                    : posture === "false"
-                        ? "This installation is LIVE (dry_run = false): adding the label can post the review to GitHub. The flag belongs to you; these instructions do not change it."
-                        : "The dry_run posture could not be read, so posting is unknown. Check the live config before adding the trigger label.";
+            let posture = null;
+            try {
+                posture = String(loadConfig(configPath(ctx.adapters)).dry_run);
+            }
+            catch {
+                /* Unknown posture stays explicit. */
+            }
+            const answer = prFrom(ctx.input, ctx.choices);
+            const typed = ctx.input.pr !== undefined || ctx.input.url !== undefined;
+            if (answer === null || (typed && parsePrAnswer(ctx.input.pr ?? ctx.input.url) === null)) {
+                return { ok: false, checks: [await askCheck(ctx, repo, label, posture, typed)] };
+            }
+            const pr = answer.pr;
+            if (answer.repo !== null && answer.repo.toLowerCase() !== repo.toLowerCase()) {
                 return {
                     ok: false,
                     checks: [
                         {
                             name: "ask",
                             ok: false,
-                            detail: `Read this out, then call this tool again with the PR number.\n\n` +
-                                `Pick a real, open pull request of yours in ${repo} — one you would actually want reviewed. Add the label ` +
-                                `"${label}" to it. That label IS the trigger: the reviewer never reviews anything on its own initiative.\n` +
-                                assurance,
+                            detail: `that link is a pull request in ${answer.repo}, but this reviewer reviews ${repo}. Pick an open PR in ${repo} ` +
+                                "(or change the reviewed repo in the earlier GitHub step)",
+                        },
+                    ],
+                };
+            }
+            if (posture !== "true" && textOf(ctx.input.confirm_live).trim().toLowerCase() !== "yes") {
+                return {
+                    ok: false,
+                    checks: [
+                        {
+                            name: "live",
+                            ok: false,
+                            detail: posture === "false"
+                                ? `This installation is LIVE (dry_run = false): reviewing #${pr} now POSTS the review to GitHub. Ask the operator; ` +
+                                    'only on their yes, call this step again with confirm_live: "yes". The flag is theirs; this step never changes it.'
+                                : `The dry_run posture could not be read (${configPath(ctx.adapters)}), so whether this review would post is unknown. ` +
+                                    'Fix the config first — or, on the operator\'s explicit yes, call again with confirm_live: "yes".',
                         },
                     ],
                 };
@@ -299,24 +527,60 @@ export function proofRoundStep(opts = {}) {
                     ],
                 };
             }
-            log(ctx, `following #${pr} — checking the daemon's state every ${Math.round(pollIntervalMs / 1000)}s, up to ${pollAttempts} times`);
-            let last = "";
-            for (let attempt = 1; attempt <= pollAttempts; attempt += 1) {
-                const { obs, detail } = await observe(transport, pr);
-                if (obs === null) {
+            // Where the PR stands before anything is asked of the daemon.
+            const first = await observe(transport, pr);
+            if (first.obs === null)
+                return { ok: false, checks: [stateStoreCheck(first.detail, transport)] };
+            const before = first.obs.rounds.at(-1);
+            const recorded = parseProofRecord(ctx.choices[PROOF_CHOICE_KEY]);
+            const resumable = recorded !== null &&
+                recorded.pr === pr &&
+                before !== undefined &&
+                before.round_no === recorded.round_no &&
+                completedRound(before);
+            const inFlight = before?.status === "running" ||
+                first.obs.state === "queued" ||
+                first.obs.state === "reviewing";
+            const initial = classifyRounds(first.obs);
+            log(ctx, initial.kind === "waiting"
+                ? initial.detail
+                : `#${pr} has ${first.obs.rounds.length} round${first.obs.rounds.length === 1 ? "" : "s"} on record (newest: round ${before?.round_no}, ${before?.status})`);
+            // Ask for the review — unless one is already under way, or this is a
+            // re-run that only has to show the round it already recorded.
+            let requested = false;
+            let requestNote = "";
+            if (!resumable && !inFlight) {
+                const sent = await requestReview(ctx, transport, pr);
+                requested = sent.ok;
+                requestNote = sent.detail;
+                if (!sent.ok && sent.refused)
                     return {
                         ok: false,
                         checks: [
                             {
-                                name: "state-store",
+                                name: "review-now",
                                 ok: false,
-                                detail: `could not read the daemon's state (${detail}) — Fix: \`${transport.logsCommand(200)}\`. The daemon ` +
-                                    "may still be starting (the image is prebuilt; its first boot migrates state and reconciles), so give it a minute after bring-up and run this step again",
+                                detail: `the daemon refused to review #${pr} now: ${sent.detail}. ` +
+                                    `If this daemon predates "review this one PR now", add the label "${label}" to the PR instead and run this step again — ` +
+                                    "the label is the trigger the daemon has always understood.",
                             },
                         ],
                     };
-                }
-                const outcome = classifyRounds(obs);
+                log(ctx, sent.ok
+                    ? `asked the daemon to review #${pr} now (${sent.detail}) — no label needed`
+                    : `could not ask the daemon directly (${sent.detail}); following #${pr} in case it is labelled "${label}"`);
+            }
+            // Only a round NEWER than the ones before the request answers it.
+            const floor = requested ? (before?.round_no ?? 0) : -Infinity;
+            log(ctx, `following #${pr} — checking the daemon's state every ${Math.round(pollIntervalMs / 1000)}s, up to ${pollAttempts} times`);
+            let last = "";
+            let settledPolls = 0;
+            for (let attempt = 1; attempt <= pollAttempts; attempt += 1) {
+                const { obs, detail } = await observe(transport, pr);
+                if (obs === null)
+                    return { ok: false, checks: [stateStoreCheck(detail, transport)] };
+                const fresh = { ...obs, rounds: obs.rounds.filter((r) => r.round_no > floor) };
+                const outcome = classifyRounds(fresh);
                 if (outcome.kind === "done") {
                     log(ctx, `round ${outcome.round.round_no} finished with ${outcome.round.verdict}`);
                     return finish(ctx, transport, pr, outcome.round);
@@ -324,17 +588,36 @@ export function proofRoundStep(opts = {}) {
                 if (outcome.kind === "failed") {
                     return { ok: false, checks: [roundFailedCheck(outcome.round, pr, transport)] };
                 }
+                // Asked, but the daemon settled the PR without a new round (nothing
+                // changed since a review of this same head): that review is the answer.
+                if (requested &&
+                    outcome.kind === "waiting" &&
+                    obs.state !== "queued" &&
+                    obs.state !== "reviewing") {
+                    settledPolls += 1;
+                    const standing = obs.rounds.at(-1);
+                    if (settledPolls >= 2 && completedRound(standing)) {
+                        log(ctx, `the daemon reviewed nothing new — #${pr}'s head was already reviewed in round ${standing.round_no}; showing that review`);
+                        return finish(ctx, transport, pr, standing);
+                    }
+                }
+                else
+                    settledPolls = 0;
                 last =
                     outcome.kind === "running"
                         ? `round ${outcome.round.round_no} is running (started ${outcome.round.started_at})`
-                        : outcome.detail;
+                        : requested && obs.state === "queued"
+                            ? "queued — the round starts as soon as a review slot is free"
+                            : outcome.detail;
                 log(ctx, `${last} — attempt ${attempt}/${pollAttempts}`);
                 if (attempt < pollAttempts)
                     await sleep(pollIntervalMs);
             }
             return {
                 ok: false,
-                checks: [timeoutCheck(pr, repo, label, last, pollAttempts, pollIntervalMs, transport)],
+                checks: [
+                    timeoutCheck(pr, repo, label, last, pollAttempts, pollIntervalMs, transport, requested ? requestNote : null),
+                ],
             };
         },
         async verify(ctx) {
@@ -431,7 +714,19 @@ export function proofRoundStep(opts = {}) {
             return { ok: false, checks };
         }
         const other = records.filter((r) => r.kind !== "create_review").length;
-        checks.push({ name: "review", ok: true, detail: renderReview(review, pr) });
+        const file = records
+            .filter((r) => r.kind === "create_review" && r.reviewPurpose === undefined)
+            .at(-1)?.file;
+        checks.push({
+            name: "review",
+            ok: true,
+            detail: renderReview(review, pr, {
+                verdict: round.verdict,
+                ...(file
+                    ? { file, readCommand: transport.execCommand(`cat ${CONTAINER_DRYRUN_DIR}/${file}`) }
+                    : {}),
+            }),
+        });
         checks.push({
             name: "nothing-posted",
             ok: true,
@@ -482,13 +777,28 @@ function roundFailedCheck(round, pr, transport) {
             "and an authentication error there is the answer.",
     };
 }
-function timeoutCheck(pr, repo, label, last, attempts, intervalMs, transport) {
+function stateStoreCheck(detail, transport) {
+    return {
+        name: "state-store",
+        ok: false,
+        detail: `could not read the daemon's state (${detail}) — Fix: \`${transport.logsCommand(200)}\`. The daemon ` +
+            "may still be starting (the image is prebuilt; its first boot migrates state and reconciles), so give it a minute after bring-up and run this step again",
+    };
+}
+function timeoutCheck(pr, repo, label, last, attempts, intervalMs, transport, 
+/** Set when the review was asked for directly (review-now): its receipt. */
+requested = null) {
     const minutes = Math.round((attempts * intervalMs) / 60_000);
     return {
         name: "round",
         ok: false,
         detail: `no finished round for #${pr} after ${minutes} minutes of watching (last seen: ${last || "nothing at all"}). ` +
             "Nothing is broken by this — the wizard simply stopped waiting, and running this step again picks the watch back up.\n" +
+            (requested !== null
+                ? `The review WAS asked for directly (the daemon answered: ${requested}), so no label is needed. A first round on a ` +
+                    "big PR can take a while; `qcr tui " +
+                    `${pr}\` shows the round's own live log. If it never started:\n`
+                : "") +
             "What to check, in the order that actually finds it:\n" +
             `① the label on #${pr} must be exactly "${label}" — the daemon matches the name from [github] trigger_label, and a ` +
             "near-miss looks like nothing happening;\n" +