@graphty/visual-review 0.2.0 → 0.2.1

package/README.md

@@ -147,10 +147,12 @@ Per project:
 | `seedFromDefaultBranch` | `true`     | `false`: the project's first baselines are accepted on a pull request, not seeded from the default branch                                                                                                                                      |
 | `waitFor`               | none       | After a story renders, call `method()` on every element matching `selector` and wait for the promise it returns, for a component that keeps drawing after Storybook says it is done. A console line containing `failOnConsole` fails the story |
 
-Project ids are letters, digits, `.`, `_` and `-`. Every project is gated; there is no setting
-that turns the gate off, and a config that sets `gate` is refused. The pull request gate reads the
-config as it is on the base branch, so a pull request cannot move `baselines` out from under it or
-drop a project from the gate; a project that a pull request adds to its own config is gated too.
+Project ids are lowercase letters, digits and `-` (results.json allows no others), and so are
+the names of Chromatic modes, which a capture refuses before it starts. Every project is gated;
+there is no setting that turns the gate off, and a config that sets `gate` is refused. The pull
+request gate reads the config as it is on the base branch, so a pull request cannot move
+`baselines` out from under it or drop a project from the gate; a project that a pull request adds
+to its own config is gated too.
 
 ## The GitHub Actions workflows
 
@@ -222,10 +224,10 @@ token is kept in the work directory, so the URL stays valid across restarts; del
 
 The address always names the screen you are on, after the token: the targets list; a pull
 request (or master) and project with the grid's filter and text; or one story with its view,
-zoom, changed box and blink, for example
-`#token=...&target=123&project=web&filter=undecided&item=button--primary.dark.png&view=flash&zoom=2&box=on&blink=off`.
-A link's `box` and `blink` apply to the page it opens; the choice this browser remembers for B
-and L is left as it was.
+zoom, changed box, blink and Spotlight flash, for example
+`#token=...&target=123&project=web&filter=undecided&item=button--primary.dark.png&view=flash&zoom=2&box=on&blink=off&flash=off`.
+A link's `box`, `blink` and `flash` apply to the page it opens; the choice this browser remembers
+for B, L and F in Spotlight is left as it was.
 Opening that address, in another tab or on another device, opens the same screen. **Copy link**
 at the top right copies it. The link carries your session token, so it works on your iPad the way
 the printed URL does; keep it to yourself as you would that URL. All of it sits after `#`, which a
@@ -250,6 +252,10 @@ starts the same server from your own shell.
       pull request. Merge the default branch into the pull request's branch (by merge, never
       rebase) and wait for CI.
     - **capture failed**: the `visual` job produced no results. Re-run that job in GitHub Actions.
+    - **CI still running**, **waiting for CI**, **downloading the captures**: there is nothing
+      to review yet; reload the page in a moment.
+    - **artifact expired**: GitHub deleted the capture after 30 days and it was never
+      downloaded here. Re-run the `visual` job.
     - **incomplete: N of M stories**: the capture stopped part way. Re-run the job.
     - **not seeded from master**: this project is not reviewed on the default branch
       (`"seedFromDefaultBranch": false` in the config); its first baselines are accepted on a pull
@@ -295,7 +301,9 @@ starts the same server from your own shell.
    scroll it was opened at; **Highlight**, the changed pixels in solid red laid over both images
    themselves, in both panes, where **Blink** (L) flashes the red pixels on and off at Flash's
    pace (remembered in this browser); and **Spotlight**, the new image dimmed everywhere except around the changed pixels
-   (each grown by 10 image pixels), which finds a one-pixel change. Flash, Highlight and
+   (each grown by 10 image pixels), which finds a one-pixel change, where **Spotlight flash** (F
+   in Spotlight) shows the spotlighted baseline and the spotlighted new image one after the other
+   at Flash's pace, the pane's label saying which (remembered in this browser). Flash, Highlight and
    Spotlight need two images; on a new or removed story they are off and the page says why
    ("New story, no baseline", "Only one image: this story was removed"). Badges here:
    **size changed** (in image pixels), **flaky** (the two captures differed, then matched), and
@@ -326,11 +334,12 @@ Seed them from the default branch (below), or accept them on the pull request.
 | Key          | Action                                                                         |
 | ------------ | ------------------------------------------------------------------------------ |
 | J / K        | Next / previous item of this pass (decided items stay in it)                   |
-| A            | Accept an undecided item                                                       |
+| A            | Accept an undecided item, once both its images are shown                       |
 | R            | Reject an undecided item (asks for a reason, then Enter)                       |
 | E            | Exclude an undecided item (asks for a reason, then Enter, then a confirmation) |
 | U            | Undo the item's decision (on the grid: each tile's Undo button)                |
 | F            | Flash between baseline and new; F again returns to side by side                |
+| F            | In Spotlight: flash the spotlighted baseline and new, or stop flashing         |
 | H            | Highlight changed pixels; H again returns to side by side                      |
 | S            | Spotlight the changes; S again returns to side by side                         |
 | Z            | Next zoom: fit to screen, real size, 2x, 4x, 8x, then fit again                |
@@ -344,6 +353,8 @@ Seed them from the default branch (below), or accept them on the pull request.
 
 No key reverses a decision. A, R and E do nothing on an item that is already decided, and say
 so; to change a decision, press U (or the Undo button) first. The same key twice never undoes.
+A held A, R, E or U decides once, and a double click on a decision button decides only the item
+it was clicked on, never the next one.
 
 ## What each decision does
 
@@ -360,7 +371,9 @@ so; to change a decision, press U (or the Undo button) first. The same key twice
   runner), re-run the `visual` job instead, since the newest attempt replaces the old results.
 - **Undo** (U, or a tile's Undo on the grid) clears a decision before Finish; it is the only way
   to change one. The grid also undoes a whole component or project, after a second press.
-  Decisions are kept across server restarts.
+  Decisions are kept across server restarts. A decision applies only to the image it was taken
+  on: when a new run or a re-run attempt captures that item differently, it is undecided again
+  (the old decision stays saved, and comes back if the image does).
 - After Finish, accepts and exclusions are cleared; rejects stay, marked as already posted, and
   still show as rejected on the next CI run while the capture is unchanged. Finish does not post
   them twice. They live in the work directory's `state/` (the config's `workDir`), not in the
@@ -598,6 +611,21 @@ PNGs move: a settings file (`<old id>.json`) is not renamed; rename it in the sa
   other `core.hooksPath`), that hook is not installed: call `git lfs pre-push "$@"` from your own
   pre-push hook. `git push --no-verify` skips the upload too; after one that carried baselines,
   run `git lfs push origin <branch>`.
+- **download failed / failed to load: ...; reload the page to retry.** `serve` starts
+  downloading every capture as soon as it starts, and retries a gh call that fails on the network
+  (DNS, a dropped connection, a GitHub 5xx) three times over about 20 seconds; it logs each failed
+  call and each retry to stderr. A project whose download still fails shows "download failed", a
+  pull request (or the default branch's run) GitHub would not answer for shows "failed to load",
+  or, when it loaded before, keeps what it showed with "could not refresh", and everything else
+  loads as usual. Reload the page to try again; captures already downloaded are kept, and a
+  damaged one is downloaded again.
+- **A gh or git call hangs.** Every gh and git call `serve` and Finish make is stopped after 10
+  minutes (`VISUAL_REVIEW_TIMEOUT_MS` sets another limit, in milliseconds), and git never waits
+  for a credential prompt. A stopped Finish names the step it was on and keeps your decisions.
+- **"the server stopped while this Finish was at ..."** The server restarted during a Finish.
+  Look at the branch on origin to see whether its commit was pushed before pressing Finish again.
+- **"... was pushed as ..., but opening its pull request failed"** (the seed). Press Finish
+  again: it opens the pull request for the branch already pushed.
 - **capture failed / no capture** on a target. The `visual` job produced no results. Open its
   log from the page and re-run the job. **incomplete: N of M stories**: the job stopped part way
   (a timeout); re-run it.

package/capture/capture.mjs

@@ -154,6 +154,13 @@ export function storySettings(parameters, file) {
             name,
             globals: Object.fromEntries(Object.entries(m).filter(([k]) => k !== "disable")),
         }));
+    // A mode names files and results.json items, which allow only these: refused before any story
+    // is captured, not when results.json is checked at the end.
+    for (const { name } of modes) {
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(name) || name.length > 50) {
+            throw new Error(`Chromatic mode "${name}": a mode name is lowercase letters, digits and "-", at most 50`);
+        }
+    }
     const where = byFile ? "settings file" : "story's parameters";
     return {
         disableSnapshot,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/visual-review",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Self-hosted visual review of Storybook stories: capture in GitHub Actions, keep the baselines in git (Git LFS), accept or reject each change in a local page, and gate pull requests",
   "author": "Adam Powers <apowers@ato.ms>",
   "type": "module",

package/trusted/cli.mjs

@@ -214,6 +214,7 @@ async function serve(args) {
         origin,
         masterRun,
         results: values.results && resolve(values.results),
+        warm: true,
         // What the owner types to run this server from their own shell, so Finish signs with
         // their key rather than the environment of whoever started it (an agent, say).
         startCommand:

package/trusted/gate.mjs

@@ -63,7 +63,13 @@ export function newestResults(dir) {
             continue;
         }
         const file = join(dir, name, "results.json");
-        out[project] = { attempt, results: existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : null };
+        let results = null;
+        try {
+            results = JSON.parse(readFileSync(file, "utf8"));
+        } catch {
+            // Missing or not JSON: counted as missing, like any invalid results.json.
+        }
+        out[project] = { attempt, results };
     }
     return out;
 }

package/trusted/lib/accept.mjs

@@ -32,10 +32,13 @@ const EXCLUDABLE = new Set([...DECIDABLE, "unstable", "failed"]);
 /**
  * Refused decisions and failed git commands; the message is shown to the owner as is.
  * `committed` is set when the accepts were already pushed and only the reject comment failed,
- * so the caller drops the accepts and keeps the rejects for a retry that only comments.
+ * so the caller drops the accepts and keeps the rejects for a retry that only comments. On
+ * master, `pullRequestMissing` is set too when opening the seed's pull request failed: the caller
+ * keeps the accepts, and the retry opens the pull request for the branch already pushed.
  */
 export class AcceptError extends Error {
     committed = null;
+    pullRequestMissing = false;
 }
 
 /**
@@ -48,6 +51,7 @@ export class AcceptError extends Error {
  * with it, so the hooks path points nowhere. Signing is left as the repository configures it, so
  * the commit carries the owner's identity and signature. GIT_LFS_SKIP_SMUDGE keeps the worktree's
  * checkout from downloading every baseline image: untouched baselines stay pointer files there.
+ * GIT_TERMINAL_PROMPT=0 makes a credential prompt fail instead of waiting on a terminal.
  * @param {string} cwd the repository or worktree
  * @param {string[]} args git's arguments
  * @param {string} [input] stdin
@@ -57,7 +61,7 @@ const git = (cwd, args, input) =>
     exec("git", ["-c", "core.hooksPath=/dev/null", ...args], {
         cwd,
         input,
-        env: { ...process.env, HUSKY: "0", GIT_LFS_SKIP_SMUDGE: "1" },
+        env: { ...process.env, HUSKY: "0", GIT_LFS_SKIP_SMUDGE: "1", GIT_TERMINAL_PROMPT: "0" },
     });
 
 /** Images per `git lfs push --object-id`, so a large seed reports its upload as it goes. */
@@ -185,6 +189,7 @@ function check(projects, decisions) {
  * @param {{ project: string, file: string, decision: string, reason: string | null }[]} input.decisions
  *     what the owner decided: accept, reject or exclude (checked here)
  * @param {number} [input.undecided] how many reviewable items are left undecided, for the status
+ * @param {string[]} [input.unloaded] the projects whose capture did not load, so nobody reviewed them
  * @param {Date} [input.now] the review time
  * @param {(step: string) => void} [input.progress] told each step as it starts, for the page
  * @param {ReturnType<typeof import("./config.mjs").normalizeConfig>} input.config the settings
@@ -200,6 +205,7 @@ export async function finish({
     projects,
     decisions,
     undecided = 0,
+    unloaded = [],
     now = new Date(),
     progress = () => {},
     config,
@@ -220,12 +226,22 @@ export async function finish({
         ({ commit, branch } = await commitAccepts({ repo, target, accepts, first, now, progress, config }));
         if (isMaster) {
             progress("opening the pull request");
-            pullRequest = await createPullRequest(gh, {
-                title: `${config.commitPrefix}: seed visual baselines`,
-                head: branch,
-                base: config.defaultBranch,
-                body: seedBody(first, accepts, rejects, config.defaultBranch),
-            });
+            try {
+                pullRequest = await createPullRequest(gh, {
+                    title: `${config.commitPrefix}: seed visual baselines`,
+                    head: branch,
+                    base: config.defaultBranch,
+                    body: seedBody(first, accepts, rejects, config.defaultBranch),
+                });
+            } catch (err) {
+                const e = new AcceptError(
+                    `${branch} was pushed as ${commit.slice(0, 10)}, but opening its pull request failed: ` +
+                        `${err.message}. Press Finish again to open it.`,
+                );
+                e.committed = commit;
+                e.pullRequestMissing = true;
+                throw e;
+            }
         }
     }
     if (rejects.length > 0) {
@@ -259,10 +275,10 @@ export async function finish({
     // none. A failure here does not undo what was pushed and posted; the page shows it.
     const accepted = accepts.filter((a) => a.decision === "accept").length;
     const excluded = accepts.length - accepted;
-    const state = rejects.length > 0 ? "failure" : undecided > 0 ? "pending" : "success";
+    const state = rejects.length > 0 ? "failure" : undecided > 0 || unloaded.length > 0 ? "pending" : "success";
     const status =
         `Reviewed: ${accepted} accepted, ${rejects.length} rejected, ${excluded} excluded, ` +
-        `${undecided} left undecided`;
+        `${undecided} left undecided${unloaded.length > 0 ? `, not loaded: ${unloaded.join(", ")}` : ""}`;
     let statusError = null;
     progress("posting the status");
     try {
@@ -287,7 +303,11 @@ export async function finish({
  */
 async function commitAccepts({ repo, target, accepts, first, now, progress, config }) {
     const { baselines, defaultBranch } = config;
-    const tracking = `refs/remotes/origin/${defaultBranch}`;
+    // Finish fetches into refs of its own, never the remote-tracking refs a page reload fetches
+    // into at the same time (two fetches of one ref fail on its lock).
+    const own = (b) => `refs/visual-review/origin/${b}`;
+    const fetch = (b) => git(repo, ["fetch", "-q", "--no-write-fetch-head", "origin", `+refs/heads/${b}:${own(b)}`]);
+    const tracking = own(defaultBranch);
     const isMaster = target.pr === null;
     const lfs = await lfsProblem(repo);
     if (lfs) {
@@ -319,19 +339,27 @@ async function commitAccepts({ repo, target, accepts, first, now, progress, conf
         }
     }
 
-    await git(repo, ["fetch", "-q", "origin", `+refs/heads/${defaultBranch}:${tracking}`]);
+    await fetch(defaultBranch);
     if (isMaster) {
         if ((await git(repo, ["ls-remote", "--heads", "origin", branch])) !== "") {
+            // A seed this tool pushed whose pull request failed to open is used as it is.
+            // ponytail: assumes the decisions did not change since that push; compare the trees if
+            // they can.
+            await fetch(branch);
+            const [subject, parent] = (await git(repo, ["log", "-1", "--format=%s%n%P", own(branch)])).split("\n");
+            if (subject === `${config.commitPrefix}: seed visual baselines` && parent === base) {
+                return { commit: await git(repo, ["rev-parse", own(branch)]), branch };
+            }
             throw new AcceptError(`${branch} already exists on origin: merge or delete it first`);
         }
     } else {
-        await git(repo, ["fetch", "-q", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`]);
-        if ((await git(repo, ["rev-parse", `refs/remotes/origin/${branch}`])) !== base) {
+        await fetch(branch);
+        if ((await git(repo, ["rev-parse", own(branch)])) !== base) {
             throw new AcceptError("capture is stale, wait for CI: the branch has moved past the captured head");
         }
     }
     for (const project of new Set(accepts.map((a) => a.project))) {
-        if (await behindMaster(repo, base, project, config)) {
+        if (await behindMaster(repo, base, project, config, tracking)) {
             throw new AcceptError(
                 `merge ${defaultBranch} into the branch first: ${defaultBranch} has newer ${project} baselines`,
             );
@@ -406,12 +434,22 @@ async function commitAccepts({ repo, target, accepts, first, now, progress, conf
         progress("uploading images to LFS (checking the commit has them all)");
         await git(tree, ["lfs", "push", "origin", "HEAD"]);
         progress("pushing");
-        await git(tree, ["push", "-q", "--no-verify", "origin", `HEAD:refs/heads/${branch}`]);
+        await git(tree, ["push", "-q", "--no-verify", "origin", `HEAD:refs/heads/${branch}`]).catch((err) => {
+            // git's own advice ("git pull") is wrong here: the capture no longer matches the branch.
+            throw /\[rejected\].*\((fetch first|non-fast-forward)\)/.test(err.message)
+                ? new AcceptError(
+                      "capture is stale, wait for CI: the branch moved past the captured head while Finish ran; nothing was pushed",
+                  )
+                : err;
+        });
         return { commit: await git(tree, ["rev-parse", "HEAD"]), branch };
     } catch (err) {
         throw err instanceof AcceptError ? err : new AcceptError(err.message);
     } finally {
-        await removeWorktree(repo, tree);
+        // A cleanup failure must not hide what was pushed; the next Finish removes the tree.
+        await removeWorktree(repo, tree).catch((err) =>
+            console.error(`visual-review: could not remove the accept worktree ${tree}: ${err.message}`),
+        );
     }
 }
 
@@ -421,17 +459,17 @@ async function commitAccepts({ repo, target, accepts, first, now, progress, conf
  * @param {string} head the captured head
  * @param {string} project the project id
  * @param {{ defaultBranch: string, baselines: string }} config the settings
+ * @param {string} [tracking] the fetched default branch
  * @returns {Promise<boolean>} true when the branch must merge the default branch before an accept
  */
-export async function behindMaster(repo, head, project, { defaultBranch, baselines }) {
-    const newest = await git(repo, [
-        "log",
-        "-1",
-        "--format=%H",
-        `refs/remotes/origin/${defaultBranch}`,
-        "--",
-        `${baselines}/${project}/`,
-    ]);
+export async function behindMaster(
+    repo,
+    head,
+    project,
+    { defaultBranch, baselines },
+    tracking = `refs/remotes/origin/${defaultBranch}`,
+) {
+    const newest = await git(repo, ["log", "-1", "--format=%H", tracking, "--", `${baselines}/${project}/`]);
     return newest !== "" && !(await gitOk(repo, ["merge-base", "--is-ancestor", newest, head]));
 }
 
@@ -487,7 +525,8 @@ async function put(path, data) {
 
 async function removeWorktree(repo, tree) {
     if (existsSync(tree)) {
-        await git(repo, ["worktree", "remove", "--force", tree]);
+        // Twice: a server killed during `worktree add` leaves the tree locked ("initializing").
+        await git(repo, ["worktree", "remove", "--force", "--force", tree]);
     }
     await git(repo, ["worktree", "prune"]);
 }

package/trusted/lib/config.mjs

@@ -21,8 +21,9 @@ const DEFAULTS = {
     issueLabels: ["bug"],
 };
 
-// Project ids name artifacts, jobs, directories and regular expressions, so they stay plain.
-const PROJECT_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+// Project ids name artifacts, jobs, directories and regular expressions, so they stay plain; and
+// results.json allows only these.
+const PROJECT_ID = /^[a-z0-9][a-z0-9-]*$/;
 // A path inside the repository: relative, no "..", no backslashes.
 const REPO_PATH = /^(?!\/)(?!.*(^|\/)\.\.(\/|$))[^\\]+$/;
 
@@ -72,7 +73,7 @@ export function normalizeConfig(input) {
     for (const [id, p] of Object.entries(projects)) {
         const where = `projects.${id}`;
         if (!PROJECT_ID.test(id)) {
-            fail(`${where}: a project id is letters, digits, ".", "_" and "-"`);
+            fail(`${where}: a project id is lowercase letters, digits and "-"`);
         }
         if (typeof p !== "object" || p === null) {
             fail(`${where} must be an object`);

package/trusted/lib/github.mjs

@@ -10,22 +10,29 @@
  */
 
 import { execFile } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 
 import { validateResults } from "./results.mjs";
 
 /**
- * Runs a program and resolves with its trimmed stdout.
+ * Runs a program and resolves with its trimmed stdout. A program that runs longer than
+ * VISUAL_REVIEW_TIMEOUT_MS (10 minutes by default) is killed: a gh or git call that stalls on a
+ * dead network, or waits on a prompt nobody sees, would otherwise hold the page or Finish forever.
  * @param {string} cmd the program
  * @param {string[]} args its arguments
  * @param {{ cwd?: string, input?: string, env?: object }} [options] stdin and environment
  * @returns {Promise<string>} stdout; rejects with an Error whose message is the program's stderr
  */
 export function exec(cmd, args, { cwd, input, env } = {}) {
+    const timeout = Number(process.env.VISUAL_REVIEW_TIMEOUT_MS) || 600000;
     return new Promise((resolve, reject) => {
-        const child = execFile(cmd, args, { cwd, env, encoding: "utf8", maxBuffer: 64 << 20 }, (err, out, stderr) => {
-            if (err) {
+        // SIGTERM (the default) lets git remove its lock files as it exits.
+        const options = { cwd, env, encoding: /** @type {const} */ ("utf8"), maxBuffer: 64 << 20, timeout };
+        const child = execFile(cmd, args, options, (err, out, stderr) => {
+            if (err?.killed) {
+                reject(new Error(`${cmd} ${args.join(" ")} timed out after ${timeout / 1000} s and was stopped`));
+            } else if (err) {
                 reject(new Error(stderr.trim() || err.message));
             } else {
                 resolve(out.trim());
@@ -42,7 +49,40 @@ export function exec(cmd, args, { cwd, input, env } = {}) {
  * @param {string} cwd the repository
  * @returns {(args: string[], input?: string) => Promise<string>} runs gh and returns its stdout
  */
-export const ghRunner = (cwd) => (args, input) => exec("gh", args, { cwd, input });
+export const ghRunner = (cwd) => withRetries((args, input) => exec("gh", args, { cwd, input }));
+
+// How gh reports a network that failed (DNS, a dropped or refused connection, a transfer cut
+// short, a call exec stopped) or a GitHub server error. A 4xx, a missing artifact or any other gh
+// error is real and is never retried.
+const TRANSIENT =
+    /could not resolve host|no such host|error connecting to|connection (reset|refused|timed out)|i\/o timeout|TLS handshake timeout|HTTP 5\d\d|unexpected EOF|GOAWAY|stream error|context deadline exceeded|timed out after/i;
+
+/**
+ * Retries a gh runner's calls that failed on the network, after each delay in turn. A write
+ * (`--input`) is never retried: GitHub may have applied it before the connection dropped. Every
+ * failure and retry is logged to stderr, so the server's log shows what happened.
+ * @param {(args: string[], input?: string) => Promise<string>} gh the gh runner
+ * @param {number[]} [delays] milliseconds before each retry
+ * @returns {(args: string[], input?: string) => Promise<string>} the retrying runner
+ */
+export const withRetries =
+    (gh, delays = [2000, 5000, 15000]) =>
+    async (args, input) => {
+        for (let i = 0; ; i++) {
+            try {
+                return await gh(args, input);
+            } catch (err) {
+                const retry = i < delays.length && !args.includes("--input") && TRANSIENT.test(err.message);
+                // gh's arguments never hold a token (gh keeps its own login), so they are logged whole.
+                const next = retry ? `; retrying in ${delays[i] / 1000} s` : "";
+                console.error(`visual-review: gh ${args.join(" ")} failed${next}: ${err.message}`);
+                if (!retry) {
+                    throw err;
+                }
+                await new Promise((resolve) => setTimeout(resolve, delays[i]));
+            }
+        }
+    };
 
 const api = async (gh, path) => JSON.parse(await gh(["api", path]));
 
@@ -108,7 +148,8 @@ export async function visualJobs(gh, run, attempt, projects) {
     const visual = jobs.filter((j) => /^visual\b/.test(j.name));
     return Object.fromEntries(
         projects.map((p) => {
-            const job = visual.find((j) => j.name.includes(p));
+            // The exact name: "visual (graphty-element)" also contains "graphty".
+            const job = visual.find((j) => j.name === `visual (${p})`);
             return [p, job && { conclusion: job.conclusion, url: job.html_url }];
         }),
     );
@@ -129,14 +170,28 @@ const downloading = new Map();
  * @returns {Promise<void>} settles when `dir` is complete, or the artifact had no results.json
  */
 function download(gh, runId, name, dir) {
-    if (existsSync(join(dir, "results.json"))) {
-        return Promise.resolve();
+    if (!downloading.has(dir) && existsSync(join(dir, "results.json"))) {
+        try {
+            JSON.parse(readFileSync(join(dir, "results.json"), "utf8"));
+            return Promise.resolve();
+        } catch (err) {
+            // Damaged on this disk (CI uploads only results.json it wrote): download it again.
+            console.error(
+                `visual-review: ${join(dir, "results.json")} is unreadable, downloading again: ${err.message}`,
+            );
+        }
     }
     if (!downloading.has(dir)) {
         const done = (async () => {
-            // A directory without results.json is left over from before downloads were atomic.
+            // A directory without results.json is left over from before downloads were atomic,
+            // and a .part- sibling from a download a killed server never finished.
             rmSync(dir, { recursive: true, force: true });
             mkdirSync(dirname(dir), { recursive: true });
+            for (const f of readdirSync(dirname(dir))) {
+                if (f.startsWith(`${basename(dir)}.part-`)) {
+                    rmSync(join(dirname(dir), f), { recursive: true, force: true });
+                }
+            }
             const part = mkdtempSync(`${dir}.part-`);
             try {
                 await gh(["run", "download", String(runId), "-n", name, "-D", part]);
@@ -155,31 +210,51 @@ function download(gh, runId, name, dir) {
 /**
  * Downloads each project's capture artifact from the highest attempt that uploaded one, into
  * `<tmp>/<run>-<attempt>/<project>/`. An artifact already downloaded is not fetched again, and
- * concurrent calls for the same one share a single download.
+ * concurrent calls for the same one share a single download. A failed download fails only its
+ * project, which the next call tries again. An expired artifact is used from disk when it was
+ * downloaded before.
  * @param {Function} gh the gh runner
  * @param {{ id: number }} run the run
  * @param {string[]} projects project ids
  * @param {string} tmp the download root
- * @returns {Promise<Record<string, { dir: string, attempt: number } | null>>} null for a project
- *     with no unexpired artifact
+ * @param {string[]} [others] receives the projects the run captured that are not in `projects`
+ * @returns {Promise<Record<string, { dir: string | null, attempt: number, error?: string,
+ *     expired?: true } | null>>} null for a project with no artifact; `error` (and no `dir`) when
+ *     its download failed; `expired` (and no `dir`) when GitHub deleted it and it is not on disk
  */
-export async function downloadCaptures(gh, run, projects, tmp) {
+export async function downloadCaptures(gh, run, projects, tmp, others = []) {
     const { artifacts } = await api(gh, `repos/{owner}/{repo}/actions/runs/${run.id}/artifacts?per_page=100`);
-    /** @type {Record<string, { dir: string, attempt: number } | null>} */
+    for (const a of artifacts) {
+        const p = /^visual-(.+)-\d+$/.exec(a.name)?.[1];
+        if (p && !projects.includes(p) && !others.includes(p)) {
+            others.push(p);
+        }
+    }
+    /** @type {Record<string, { dir: string | null, attempt: number, error?: string, expired?: true } | null>} */
     const out = {};
     for (const project of projects) {
         const pattern = new RegExp(`^visual-${project}-(\\d+)$`);
         const newest = artifacts
-            .filter((a) => !a.expired && pattern.test(a.name))
-            .map((a) => ({ name: a.name, attempt: Number(pattern.exec(a.name)[1]) }))
+            .filter((a) => pattern.test(a.name))
+            .map((a) => ({ name: a.name, expired: a.expired, attempt: Number(pattern.exec(a.name)[1]) }))
             .sort((a, b) => b.attempt - a.attempt)[0];
         if (!newest) {
             out[project] = null;
             continue;
         }
         const dir = join(tmp, `${run.id}-${newest.attempt}`, project);
-        await download(gh, run.id, newest.name, dir);
-        out[project] = { dir, attempt: newest.attempt };
+        if (newest.expired) {
+            out[project] = existsSync(join(dir, "results.json"))
+                ? { dir, attempt: newest.attempt }
+                : { dir: null, attempt: newest.attempt, expired: true };
+            continue;
+        }
+        try {
+            await download(gh, run.id, newest.name, dir);
+            out[project] = { dir, attempt: newest.attempt };
+        } catch (err) {
+            out[project] = { dir: null, attempt: newest.attempt, error: err.message };
+        }
     }
     return out;
 }
@@ -205,7 +280,12 @@ export async function newestMasterCapture(gh, project, tmp, { workflow, defaultB
         if (!run) {
             continue;
         }
-        const dir = (await downloadCaptures(gh, run, [project], tmp))[project]?.dir;
+        const got = (await downloadCaptures(gh, run, [project], tmp))[project];
+        if (got?.error) {
+            // Not skipped: an older capture would be compared instead of this one.
+            throw new Error(got.error);
+        }
+        const dir = got?.dir;
         let results = null;
         try {
             results = dir ? JSON.parse(readFileSync(join(dir, "results.json"), "utf8")) : null;