scenescout 3.17.0 → 3.19.0

package/dist/export-run.js

@@ -1,15 +1,17 @@
 /**
- * Runs `scenescout export`: reads the project's findings, asks the tracker
- * which of them it already holds, and files the rest. The rules (which
+ * Runs `scenescout export`: reads the project's findings (or a check.json or
+ * ci.json given with --from), asks the tracker which of them it already
+ * holds, and files the rest. The rules (which
  * findings, what an issue says, the marker, the plan) live in
  * engine/export.ts; this file only reads the project's files and talks HTTP.
- * It writes nothing to the project, and the credentials it sends are never
- * printed: every line goes out through a redactor that knows them.
+ * The one file it writes is the record of the issues it filed, beside the
+ * memory, and the credentials it sends are never printed: every line goes out
+ * through a redactor that knows them.
  */
 import fs from "node:fs";
 import path from "node:path";
 import { redactKeys } from "./engine/ci.js";
-import { credentialSecrets, EXIT_EXPORT, failedCriteriaByFinding, findingIdsInGithubBody, findingIdsInJiraDescription, findingLine, findingPicture, frameIsOriginal, framesFor, githubIssue, jiraEditFields, jiraIssueFields, MARKER_LABEL, MAX_RATE_WAIT_MS, oneLine, planExport, planJiraUpdate, rateLimit, rememberFiled, selectFindings, ticketsToLink, trackerCredentials, trackerMessage, TRACKER_LABEL, uploadName, } from "./engine/export.js";
+import { credentialSecrets, EXIT_EXPORT, failedCriteriaByFinding, findingIdsInGithubBody, findingIdsInJiraDescription, findingLine, findingPicture, frameIsOriginal, framesFor, githubIssue, jiraEditFields, jiraIssueFields, MARKER_LABEL, MAX_RATE_WAIT_MS, oneLine, parseExportRecord, planExport, planJiraUpdate, rateLimit, recordKey, recordWith, rememberFiled, selectFindings, findingsFromResult, ticketsToLink, trackerCredentials, trackerMessage, TRACKER_LABEL, uncertainHolds, uploadName, EXPORT_RECORD_FILE, UNCERTAIN_HOLD_MS, } from "./engine/export.js";
 import { MEMORY_DIRNAME } from "./engine/memory.js";
 import { backoffMs } from "./engine/provider.js";
 import { resolveFrame } from "./engine/replay.js";
@@ -91,6 +93,8 @@ function client(base, headers, h) {
                 }
                 throw new ExportError(`${what} failed: ${failureOf(err, h.timeoutMs)}`, !r.idempotent);
             }
+            if (r.missingOk && (res.status === 404 || res.status === 410 || (res.status >= 300 && res.status < 400)))
+                return null;
             if (res.status >= 300 && res.status < 400)
                 throw new ExportError(`${what} was answered with a redirect (HTTP ${res.status}), which is refused: credentials are never sent on to another address. A repository or site that moved needs its new address`);
             const said = trackerMessage(body);
@@ -123,54 +127,87 @@ function githubApi({ repo }, send) {
         .split("/")
         .map((p) => encodeURIComponent(p))
         .join("/")}/issues`;
+    /** An issue as the API gives it, read; null for a pull request, which the issues API lists too. */
+    const readIssue = (issue) => {
+        if (isRecord(issue) && issue.pull_request)
+            return null;
+        const number = isRecord(issue) ? Number(issue.number) : NaN;
+        // An entry that cannot be read, or one without its body, could be a filed finding: guessing "not filed" files it twice.
+        if (!isRecord(issue) || !Number.isInteger(number) || !("body" in issue))
+            throw new ExportError("GitHub listed an issue without its number or its body, so which findings are filed cannot be told");
+        const labels = Array.isArray(issue.labels) ? issue.labels : [];
+        return {
+            issue: { ref: `#${number}`, number, url: oneLine(issue.html_url, 300), open: issue.state !== "closed" },
+            ids: findingIdsInGithubBody(issue.body),
+            // GitHub's label filter ignores case, so a repository's "SceneScout" label is this one.
+            labelled: labels.some((l) => (typeof l === "string" ? l : isRecord(l) ? String(l.name ?? "") : "").toLowerCase() === MARKER_LABEL),
+        };
+    };
     return {
         label: `GitHub ${repo}`,
         consistentListing: true,
-        // Listed by label rather than found through the search API: search is
-        // indexed with a delay, so an export run right after another would not
-        // see the issues it had just filed and would file them again.
+        // Listed by label rather than found through the search API, which is
+        // indexed with a delay. The label filter lags behind a create too, so the
+        // newest issues are also listed with no filter, which shows an issue as
+        // soon as it is made: an export run right after another, or the check
+        // after a create that may have been made, finds the issue just filed.
         async existing(includeClosed) {
             const map = new Map();
+            const seen = new Set();
             let issues = 0;
             let unmarked = 0;
+            const take = (read) => {
+                if (seen.has(read.issue.number))
+                    return;
+                seen.add(read.issue.number);
+                issues++;
+                if (read.ids.length === 0)
+                    unmarked++;
+                for (const id of read.ids)
+                    rememberFiled(map, id, read.issue);
+            };
+            const state = includeClosed ? "all" : "open";
+            const newest = await send({ method: "GET", path: `${root}?state=${state}&sort=created&direction=desc&per_page=100`, idempotent: true });
+            if (!Array.isArray(newest))
+                throw new ExportError("GitHub's list of issues was not a list");
+            for (const entry of newest) {
+                const read = readIssue(entry);
+                if (read?.labelled)
+                    take(read);
+            }
             for (let page = 1; page <= MAX_PAGES; page++) {
                 const body = await send({
                     method: "GET",
-                    path: `${root}?labels=${encodeURIComponent(MARKER_LABEL)}&state=${includeClosed ? "all" : "open"}&per_page=100&page=${page}`,
+                    path: `${root}?labels=${encodeURIComponent(MARKER_LABEL)}&state=${state}&per_page=100&page=${page}`,
                     idempotent: true,
                 });
                 if (!Array.isArray(body))
                     throw new ExportError("GitHub's list of issues was not a list");
-                for (const issue of body) {
-                    // The issues API lists pull requests too.
-                    if (isRecord(issue) && issue.pull_request)
-                        continue;
-                    const number = isRecord(issue) ? Number(issue.number) : NaN;
-                    // An entry that cannot be read, or one without its body, could be a filed finding: guessing "not filed" files it twice.
-                    if (!isRecord(issue) || !Number.isInteger(number) || !("body" in issue))
-                        throw new ExportError("GitHub listed an issue without its number or its body, so which findings are filed cannot be told");
-                    issues++;
-                    const ids = findingIdsInGithubBody(issue.body);
-                    if (ids.length === 0)
-                        unmarked++;
-                    for (const id of ids)
-                        rememberFiled(map, id, { ref: `#${number}`, number, url: oneLine(issue.html_url, 300), open: issue.state !== "closed" });
+                for (const entry of body) {
+                    const read = readIssue(entry);
+                    if (read)
+                        take(read);
                 }
                 if (body.length < 100)
                     return { map, issues, unmarked };
             }
             throw new ExportError(`${MAX_PAGES * 100} or more issues carry the ${MARKER_LABEL} label, too many to check them all for this export's findings`);
         },
+        async read(_ref, number) {
+            const body = await send({ method: "GET", path: `${root}/${number}`, idempotent: true, missingOk: true });
+            if (body === null)
+                return null;
+            const read = readIssue(body);
+            return read && read.issue.number === number ? { issue: read.issue, ids: read.ids } : null;
+        },
         async create(f, ctx) {
             const body = await send({ method: "POST", path: root, json: githubIssue(f, ctx), idempotent: false });
             const number = isRecord(body) ? Number(body.number) : NaN;
             if (!isRecord(body) || !Number.isInteger(number))
                 throw new ExportError("GitHub answered the create without an issue number", true);
             const issue = { ref: `#${number}`, number, url: oneLine(body.html_url, 300), open: true };
-            const labels = Array.isArray(body.labels) ? body.labels : [];
-            const names = labels.map((l) => (typeof l === "string" ? l : isRecord(l) ? String(l.name ?? "") : "").toLowerCase());
             // GitHub drops the labels of an issue created by an account that cannot set them, and says nothing.
-            if (!names.includes(MARKER_LABEL))
+            if (!readIssue({ body: null, ...body })?.labelled)
                 return {
                     issue,
                     problems: [],
@@ -241,6 +278,22 @@ function jiraApi({ baseUrl, projectKey, issueType, linkType }, send) {
     };
     const keysOf = (links) => (Array.isArray(links) ? links : []).flatMap((l) => isRecord(l) ? [l.inwardIssue, l.outwardIssue].flatMap((i) => (isRecord(i) && typeof i.key === "string" ? [i.key] : [])) : []);
     const namesOf = (attachments) => (Array.isArray(attachments) ? attachments : []).flatMap((a) => (isRecord(a) && typeof a.filename === "string" ? [a.filename] : []));
+    const FIELDS = ["summary", "description", "status", "attachment", "issuelinks"];
+    /** An issue as the API gives it, read. */
+    const readIssue = (issue, what) => {
+        const key = isRecord(issue) ? String(issue.key ?? "") : "";
+        const number = keyNumber(key);
+        const fields = isRecord(issue) && isRecord(issue.fields) ? issue.fields : null;
+        // A field configuration can hide the description; without it, every finding would read as unfiled and be filed again.
+        if (number === null || !fields || !("description" in fields))
+            throw new ExportError(`Jira ${what} an issue without its key or its description, so which findings are filed cannot be told`);
+        const status = isRecord(fields.status) && isRecord(fields.status.statusCategory) ? fields.status.statusCategory.key : undefined;
+        const jira = { summary: fields.summary, description: fields.description, attachments: namesOf(fields.attachment), links: keysOf(fields.issuelinks) };
+        return {
+            issue: { ref: key, number, url: `${baseUrl}/browse/${key}`, open: status !== "done", jira },
+            ids: findingIdsInJiraDescription(fields.description),
+        };
+    };
     return {
         label: `Jira ${projectKey}`,
         consistentListing: false,
@@ -255,26 +308,18 @@ function jiraApi({ baseUrl, projectKey, issueType, linkType }, send) {
                 const body = await send({
                     method: "POST",
                     path: "/rest/api/3/search/jql",
-                    json: { jql, fields: ["summary", "description", "status", "attachment", "issuelinks"], maxResults: 100, ...(nextPageToken ? { nextPageToken } : {}) },
+                    json: { jql, fields: FIELDS, maxResults: 100, ...(nextPageToken ? { nextPageToken } : {}) },
                     idempotent: true,
                 });
                 if (!isRecord(body) || !Array.isArray(body.issues))
                     throw new ExportError("Jira's search answered without a list of issues");
-                for (const issue of body.issues) {
-                    const key = isRecord(issue) ? String(issue.key ?? "") : "";
-                    const number = keyNumber(key);
-                    const fields = isRecord(issue) && isRecord(issue.fields) ? issue.fields : null;
-                    // A field configuration can hide the description; without it, every finding would read as unfiled and be filed again.
-                    if (number === null || !fields || !("description" in fields))
-                        throw new ExportError(`Jira listed an issue without its key or its description, so which findings are filed cannot be told`);
+                for (const entry of body.issues) {
+                    const { issue, ids } = readIssue(entry, "listed");
                     issues++;
-                    const status = isRecord(fields.status) && isRecord(fields.status.statusCategory) ? fields.status.statusCategory.key : undefined;
-                    const ids = findingIdsInJiraDescription(fields.description);
                     if (ids.length === 0)
                         unmarked++;
-                    const jira = { summary: fields.summary, description: fields.description, attachments: namesOf(fields.attachment), links: keysOf(fields.issuelinks) };
                     for (const id of ids)
-                        rememberFiled(map, id, { ref: key, number, url: `${baseUrl}/browse/${key}`, open: status !== "done", jira });
+                        rememberFiled(map, id, issue);
                 }
                 nextPageToken = typeof body.nextPageToken === "string" && body.nextPageToken ? body.nextPageToken : undefined;
                 if (!nextPageToken || body.isLast === true)
@@ -282,6 +327,15 @@ function jiraApi({ baseUrl, projectKey, issueType, linkType }, send) {
             }
             throw new ExportError(`more than ${MAX_PAGES} pages of issues in ${projectKey} carry the ${MARKER_LABEL} label, too many to check them all for this export's findings`);
         },
+        async read(ref) {
+            // Read by key, which Jira answers from the issue itself rather than from its search, so a new issue shows at once.
+            const body = await send({ method: "GET", path: `${issuePath(ref)}?fields=${FIELDS.join(",")}`, idempotent: true, missingOk: true });
+            if (body === null)
+                return null;
+            const read = readIssue(body, "answered with");
+            // An issue moved to another project answers under its new key: it is no longer this project's.
+            return read.issue.ref === ref ? read : null;
+        },
         async create(f, ctx, extras) {
             const body = await send({
                 method: "POST",
@@ -314,7 +368,7 @@ function jiraApi({ baseUrl, projectKey, issueType, linkType }, send) {
 /** The project's memory, refused unless it is one this version reads: a file it cannot read exported nothing and said so with exit 0. */
 function readMemory(memoryPath) {
     if (!fs.existsSync(memoryPath))
-        throw new ExportError(`no findings to export: ${memoryPath} does not exist. Run SceneScout on this project first, or pass --project`);
+        throw new ExportError(`no findings to export: ${memoryPath} does not exist. Run SceneScout on this project first, pass --project, or export a check.json or ci.json with --from`);
     let memory;
     try {
         memory = JSON.parse(fs.readFileSync(memoryPath, "utf8"));
@@ -328,6 +382,33 @@ function readMemory(memoryPath) {
         throw new ExportError(`${memoryPath} holds no list of findings`);
     return memory;
 }
+/**
+ * A check.json or a ci.json, its findings in the shape memory.json holds
+ * them. A file it cannot read, or one some other command wrote, is refused
+ * rather than exported as nothing.
+ */
+function readResult(file) {
+    let text;
+    let writtenAt;
+    try {
+        text = fs.readFileSync(file, "utf8");
+        writtenAt = fs.statSync(file).mtime.toISOString();
+    }
+    catch (err) {
+        throw new ExportError(`could not read --from ${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        throw new ExportError(`could not read --from ${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const parsed = findingsFromResult(raw, writtenAt);
+    if (!parsed.ok)
+        throw new ExportError(`--from ${file}: ${parsed.error}`);
+    return parsed.value;
+}
 /** Every step with a frame, from every session log in the memory directory. Logs and lines that cannot be read are counted, not fatal. */
 function framedSteps(memoryDir) {
     const steps = [];
@@ -401,6 +482,44 @@ function pictureOf(f, memoryDir) {
     const found = frameFile(path.join(memoryDir, "recordings"), picture.rel);
     return found && found.stat.size <= MAX_FRAME_BYTES ? { ...picture, file: found.file, upload: uploadName(picture.rel, picture.at) } : null;
 }
+/** The record of the issues earlier exports filed; none yet is an empty one, and one that cannot be read ends the export. */
+function readRecord(recordPath) {
+    let text;
+    try {
+        text = fs.readFileSync(recordPath, "utf8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw new ExportError(`could not read ${recordPath}: ${err instanceof Error ? err.message : String(err)}`);
+        text = null;
+    }
+    const parsed = parseExportRecord(text);
+    if (!parsed.ok)
+        throw new ExportError(`could not read ${recordPath}: ${parsed.error}. It records the issues earlier exports filed, so an export straight after another does not file them again; move it aside to start a new record`);
+    return parsed.value;
+}
+/**
+ * Set one finding's entry in the record, read afresh so the entries of an
+ * export that finished meanwhile are kept, and written whole or not at all.
+ * It takes no lock: two exports from one project at the same moment can each
+ * drop the other's latest entry. Exports are meant to run one at a time per
+ * project, and an entry lost that way costs only the read-back, since the
+ * listing still finds the issue once it catches up.
+ */
+function writeRecord(recordPath, key, id, entry) {
+    const text = recordWith(readRecord(recordPath), key, id, entry);
+    // An export --from a check or ci result may be the first thing to write in a project's .scenescout folder.
+    fs.mkdirSync(path.dirname(recordPath), { recursive: true });
+    const temp = `${recordPath}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(temp, text, { mode: 0o600 });
+        fs.renameSync(temp, recordPath);
+    }
+    catch (err) {
+        fs.rmSync(temp, { force: true });
+        throw err;
+    }
+}
 // ── the export ──────────────────────────────────────────────────────────────
 const OUTCOME_WORDS = { file: "would file", "already-filed": "already filed", "over-cap": "over the cap" };
 export async function runExport(o, deps) {
@@ -431,20 +550,25 @@ export async function runExport(o, deps) {
     };
     try {
         const memoryDir = path.join(o.projectDir, MEMORY_DIRNAME);
-        const memoryPath = path.join(memoryDir, "memory.json");
-        const memory = readMemory(memoryPath);
+        // A check.json or a ci.json names no frames, picture or tickets: its issues carry none of them.
+        const result = o.from ? readResult(o.from) : null;
+        const sourcePath = o.from ?? path.join(memoryDir, "memory.json");
+        const memory = result ? { findings: result.findings } : readMemory(sourcePath);
+        const screenshots = o.screenshots && !result;
         const selection = selectFindings(memory, o);
         const criteria = failedCriteriaByFinding(memory);
         if (selection.unknownOnly.length > 0)
-            throw new ExportError(`--only names no finding of this project: ${selection.unknownOnly.join(", ")}`);
+            throw new ExportError(`--only names no finding ${result ? `in ${sourcePath}` : "of this project"}: ${selection.unknownOnly.join(", ")}`);
         say(o.dryRun ? `SceneScout export to ${where}: a dry run, so nothing is filed. Pass --yes to file.` : `SceneScout export to ${where}.`);
         const c = selection.counts;
         const left = [
             c.belowSeverity ? `${c.belowSeverity} below --min-severity ${o.minSeverity}` : "",
             c.worthALook ? `${c.worthALook} worth a look (--include-worth-a-look exports them)` : "",
         ].filter(Boolean);
-        say(`Findings in ${memoryPath}: ${c.open} open, ${c.resolved} resolved${selection.unreadable.length ? `, ${selection.unreadable.length} unreadable` : ""}. ` +
+        say(`Findings in ${sourcePath}${result ? ` (scenescout ${result.kind})` : ""}: ${c.open} open, ${c.resolved} resolved${selection.unreadable.length ? `, ${selection.unreadable.length} unreadable` : ""}. ` +
             `${selection.candidates.length} to export${left.length ? `; left out: ${left.join(", ")}` : ""}.`);
+        if (result && o.screenshots)
+            say(`  No screenshots: a ${result.kind} result names none.`);
         if (selection.unreadable.length > 0)
             say(`  Not exported, as this version cannot read them: ${selection.unreadable.slice(0, 20).join(", ")}${selection.unreadable.length > 20 ? " …" : ""}`);
         for (const { id, reason } of selection.leftOut)
@@ -463,30 +587,71 @@ export async function runExport(o, deps) {
         // A closed issue counts as filed unless --refile-closed.
         const includeClosed = !o.refileClosed;
         let existing = null;
+        const recordPath = path.join(memoryDir, EXPORT_RECORD_FILE);
+        const key = recordKey(o);
+        let candidates = selection.candidates;
+        let heldBack = 0;
         if (tracker) {
+            const recorded = readRecord(recordPath)[key] ?? {};
             const found = await tracker.existing(includeClosed);
             existing = found.map;
             say(`Compared with ${tracker.label}: ${found.issues} ${includeClosed ? "" : "open "}issue(s) carry the ${MARKER_LABEL} label` +
                 `${includeClosed ? " (open or closed)" : ""}${found.unmarked ? `, ${found.unmarked} of them with no marker` : ""}` +
                 `${includeClosed ? "" : "; a finding whose issue was closed is filed again (--refile-closed)"}.`);
+            // The listing can lag behind a create, so an issue an earlier export recorded is read back by its number before its finding counts as unfiled.
+            let readBack = 0;
+            for (const f of candidates) {
+                const entry = recorded[f.id];
+                if (!entry || "uncertain" in entry || existing.has(f.id))
+                    continue;
+                const read = await tracker.read(entry.ref, entry.number);
+                // Gone, moved, or no longer carrying the marker: the finding is filed again, as the listing says.
+                if (!read || !read.ids.includes(f.id) || (!includeClosed && !read.issue.open))
+                    continue;
+                rememberFiled(existing, f.id, read.issue);
+                readBack++;
+            }
+            if (readBack > 0)
+                say(`  ${readBack} more finding(s) found filed by the issue number recorded in ${recordPath}, as the listing does not show them yet.`);
+            // A Jira create that may have been made, and that the search does not show yet, holds its finding back for a while rather than file it twice.
+            if (!tracker.consistentListing) {
+                const held = candidates.filter((f) => !existing.has(f.id) && recorded[f.id] && uncertainHolds(recorded[f.id], http.now()));
+                for (const f of held) {
+                    const until = new Date(Date.parse(recorded[f.id].at) + UNCERTAIN_HOLD_MS).toISOString();
+                    say(`  ${"held back".padEnd(13)}  ${findingLine(f)}`);
+                    // A dry run says so and files nothing anyway, so a hold is not a failure of it.
+                    if (!o.dryRun)
+                        problems.push(`finding ${f.id} was held back: an export at ${recorded[f.id].at} may have filed it before an error, and ${tracker.label}'s search does not show it yet. An export after ${until} files it if it is still not found`);
+                }
+                candidates = candidates.filter((f) => !held.includes(f));
+                heldBack = held.length;
+            }
         }
         else if (!credentials.ok) {
             say(`Not compared with ${TRACKER_LABEL[o.to]}: ${credentials.error}. A finding filed earlier is listed below as one to file.`);
         }
-        plan = planExport(selection.candidates, existing, o.maxIssues);
-        const steps = o.screenshots ? framedSteps(memoryDir) : { steps: [], unreadable: 0 };
+        const record = (f, entry, ref) => {
+            try {
+                writeRecord(recordPath, key, f.id, entry);
+            }
+            catch (err) {
+                problems.push(`${ref}: not recorded in ${recordPath} (${err instanceof Error ? err.message : String(err)}), so an export straight after this one may not see it yet`);
+            }
+        };
+        plan = planExport(candidates, existing, o.maxIssues);
+        const steps = screenshots ? framedSteps(memoryDir) : { steps: [], unreadable: 0 };
         if (steps.unreadable > 0)
             say(`Skipped ${steps.unreadable} session-log line(s) or file(s) that could not be read while looking for screenshots.`);
         const contextOf = (f) => {
-            const found = o.screenshots ? framesOf(f, steps.steps, memoryDir) : { frames: [], dropped: 0 };
+            const found = screenshots ? framesOf(f, steps.steps, memoryDir) : { frames: [], dropped: 0 };
             droppedFrames += found.dropped;
-            const picture = o.screenshots ? pictureOf(f, memoryDir) : null;
+            const picture = screenshots ? pictureOf(f, memoryDir) : null;
             const failed = criteria.get(f.id) ?? [];
             return {
                 ctx: {
                     severityName: o.severityMap[f.severity],
                     labels: o.labels,
-                    screenshots: o.screenshots ? found.frames.map((x) => x.rel) : "off",
+                    screenshots: screenshots ? found.frames.map((x) => x.rel) : "off",
                     framesLeftOut: found.dropped,
                     picture: picture?.rel ?? null,
                     ...(picture?.at ? { pictureAt: picture.at } : {}),
@@ -506,7 +671,8 @@ export async function runExport(o, deps) {
                 const issue = entry.issue;
                 const already = `  ${OUTCOME_WORDS[entry.outcome].padEnd(13)}  ${findingLine(f)}  as ${issue.ref}${issue.open ? "" : " (closed)"}`;
                 // Only an open Jira issue filed earlier is brought up to date; a closed one is the team's decision and left alone.
-                if (o.to !== "jira" || !o.jira.update || !issue.open || !issue.jira || !tracker?.update) {
+                // An export --from a result never updates: the file holds less than the memory that may have filed the issue.
+                if (o.to !== "jira" || !o.jira.update || result || !issue.open || !issue.jira || !tracker?.update) {
                     say(already);
                     continue;
                 }
@@ -551,7 +717,7 @@ export async function runExport(o, deps) {
             }
             // Listed, not filed: over the cap, or a dry run (the only way to be here with no tracker, as --yes needs credentials).
             if (entry.outcome === "over-cap" || o.dryRun || !tracker) {
-                const shown = entry.outcome === "file" && o.screenshots ? contextOf(f).ctx : null;
+                const shown = entry.outcome === "file" && screenshots ? contextOf(f).ctx : null;
                 const shots = shown && shown.screenshots !== "off" ? shown.screenshots.length + (shown.picture ? 1 : 0) : 0;
                 say(`  ${OUTCOME_WORDS[entry.outcome].padEnd(13)}  ${findingLine(f)}${shots ? `  with ${shots} screenshot(s)` : ""}`);
                 continue;
@@ -559,9 +725,18 @@ export async function runExport(o, deps) {
             if (writes > 0 && pauseMs > 0)
                 await http.wait(pauseMs);
             const { ctx, extras } = contextOf(f);
-            const done = await fileOne(tracker, f, ctx, extras, includeClosed, http);
+            let done;
+            try {
+                done = await fileOne(tracker, f, ctx, extras, includeClosed, http);
+            }
+            catch (err) {
+                if (err instanceof ExportError && err.uncertain && !tracker.consistentListing)
+                    record(f, { uncertain: true, at: new Date(http.now()).toISOString() }, `finding ${f.id}`);
+                throw err;
+            }
             writes++;
             filed.push({ id: f.id, issue: done.issue });
+            record(f, { ref: done.issue.ref, number: done.issue.number, url: done.issue.url, at: new Date(http.now()).toISOString() }, done.issue.ref);
             say(`  ${`filed ${done.issue.ref}`.padEnd(13)}  ${findingLine(f)}  ${done.issue.url}${done.confirmed ? " (found by its marker after the tracker's error)" : ""}`);
             for (const p of done.problems)
                 problems.push(`${done.issue.ref}: ${p}`);
@@ -571,7 +746,7 @@ export async function runExport(o, deps) {
         reportFrames();
         const count = (outcome) => plan.filter((e) => e.outcome === outcome).length;
         const over = count("over-cap");
-        const overText = over ? `; ${over} over the cap of ${o.maxIssues} (--max-issues): export again to file them` : "";
+        const overText = (over ? `; ${over} over the cap of ${o.maxIssues} (--max-issues): export again to file them` : "") + (heldBack ? `; ${heldBack} held back` : "");
         say(o.dryRun
             ? `Would file ${count("file")}; ${count("already-filed")} already filed${overText}.`
             : `Filed ${filed.length}; ${count("already-filed")} already filed${updated.length ? `, ${updated.length} of them updated` : ""}${overText}.`);
@@ -587,7 +762,7 @@ export async function runExport(o, deps) {
         complain(`scenescout export: ${err instanceof Error ? err.message : String(err)}`);
         if (err instanceof ExportError && err.uncertain)
             complain(o.to === "jira"
-                ? "Jira may have made that issue before the error, and its search can take minutes to show a new one, so it was not sent again. Export again later: the issue is found by its marker if it exists, and filed if it does not."
+                ? `Jira may have made that issue before the error, and its search can take minutes to show a new one, so it was not sent again. Export again later: the issue is found by its marker if it exists, and filed if it does not. An export within ${UNCERTAIN_HOLD_MS / 60_000} minutes holds that finding back unless it finds the issue.`
                 : "The tracker may have made that issue before the error. The next export finds it by its marker and does not file it again.");
         for (const p of problems)
             complain(`scenescout export: ${p}`);
@@ -604,8 +779,9 @@ const GITHUB_HEADERS = { accept: "application/vnd.github+json", "x-github-api-ve
  * on (a timeout, a 5xx, an answer cut off) is not simply sent again: the
  * issues are listed again first, and if one already carries this finding's
  * marker, that is the issue. Only when none does is the create repeated, and
- * only where the listing shows a new issue at once (GitHub); in Jira, whose
- * search lags, the export stops instead.
+ * only where the listing shows a new issue at once (GitHub, through its
+ * newest issues read with no label filter); in Jira, whose search lags, the
+ * export stops instead, and records the finding as held back for a while.
  */
 async function fileOne(tracker, f, ctx, extras, includeClosed, http) {
     for (let attempt = 0;; attempt++) {

package/dist/first-run.js

@@ -24,7 +24,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { APPROX_DISK_MB, launchTarget } from "./browsers.js";
 import { hasScheme, hostOf } from "./commands.js";
-import { CHECK_OPTION_NAMES, CHECK_RULES, countBySeverity, issueLine, issueSections, MAX_CHECK_ROUTES, MAX_DISCOVERY_ROUNDS, resolveArgPath, routesTable, SEVERITY_RANK, SHARED_CHROME_ROUTE, unauditedRoutes, unvisitedLine, worthALookSection, } from "./engine/check.js";
+import { CHECK_OPTION_NAMES, CHECK_RULES, countBySeverity, issueLine, issueSections, MAX_CHECK_ROUTES, MAX_DISCOVERY_ROUNDS, needsSignInText, resolveArgPath, resourcesTable, routesTable, SEVERITY_RANK, SHARED_CHROME_ROUTE, unauditedRoutes, unvisitedLine, worthALookSection, } from "./engine/check.js";
 import { httpStatusOf } from "./engine/oracles.js";
 /** Every `--option` a first look accepts. Anything more is `scenescout check`'s. */
 export const FIRST_RUN_OPTION_NAMES = ["max-routes", "max-minutes", "mode", "out"];
@@ -510,6 +510,11 @@ function notes({ result, options }, code) {
             out.push(`The start page moved to ${to}, so its links count as another site's and were not followed. To look further, run it there: ${code(`npx -y scenescout ${shellArg(`${to}/`)}`)}.`);
         }
     }
+    // A first look never has a session, so a page behind sign-in is a page it could not cover, not an issue.
+    const walled = result.needsSignIn?.length ?? 0;
+    if (walled > 0 && !start?.loginRedirect) {
+        out.push(needsSignInText(walled, `${code(`npx -y scenescout login ${shellArg(result.url)} --role <name>`)} saves a sign-in, and an agent run then attaches as that role`, "page"));
+    }
     const left = result.unvisited.length;
     switch (stopReason(result, options.maxRoutes)) {
         case "time":
@@ -575,6 +580,7 @@ export function formatFirstRun(facts) {
     lines.push(...issueSections(result.issues));
     lines.push(...worthALookSection(result.worthALook, false));
     lines.push(...routesTable(result));
+    lines.push(...resourcesTable(result.resources));
     const why = stopReason(result, facts.options.maxRoutes);
     lines.push(...unvisitedLine(result.unvisited, why ? UNVISITED_WHY[why] : "not reached"));
     lines.push("", "## What to try next", "", `- **Explore it with your coding agent.** ${code("npx -y scenescout install")} sets up the skill and the MCP server; then ask your agent to use SceneScout to test ${result.url}. It clicks, fills forms and compares roles, files what it finds and reports what it did not test.`, `- **Gate pull requests.** ${code(`npx -y scenescout check ${shellArg(result.url)}`)} is this look as a pass or a fail, with SARIF for code scanning; it also runs as a GitHub Action.`, `- **Pages behind a sign-in.** ${code(`npx -y scenescout login ${shellArg(result.url)} --role <name>`)} saves a sign-in once, and an agent run then attaches as that role.`, "", `The guide: ${GUIDE_URL}`, "", `_A first look opens pages and measures what loads, and fills and submits no form. ${modeSentence(result.mode)} (${SAFETY_URL}) It does not click through flows or compare roles; an exploratory run does that._`);