@iceinvein/agent-skills 0.22.0 → 0.23.0

package/skills/magpie/scripts/critic-cmd.ts

@@ -7,6 +7,7 @@ import {
   DEFAULT_BATCH_SIZE,
   parseCriticVerdicts,
 } from './critic.ts'
+import { reviewRoot } from './target.ts'
 import { parseBrief, parseFinding, type ReviewFinding, type ReviewRule } from './types.ts'
 
 const DEFAULT_TEMPLATE_PATH = new URL('../references/critic.md', import.meta.url).pathname
@@ -84,7 +85,7 @@ export async function runCriticPrompt(
       candidates: await readCandidates(runDir),
       mergeCandidates: await readMergeCandidates(runDir),
       reviewRules: await readReviewRules(runDir),
-      worktree: join(runDir, 'worktree'),
+      worktree: await reviewRoot(runDir),
       diffPath: join(runDir, 'diff.patch'),
       runDir,
       batchSize: options.batchSize ?? DEFAULT_BATCH_SIZE,

package/skills/magpie/scripts/dedupe-cmd.ts

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs'
 import { appendFile, readdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { annotateChangedLines } from './changed-lines.ts'
@@ -5,6 +6,7 @@ import { deduplicateFindings, findMergeCandidates } from './dedupe.ts'
 import { verifyEvidence } from './evidence-filter.ts'
 import { namespaceId, parseFindingsFilename } from './findings-files.ts'
 import { DEFAULT_THRESHOLD, scoreRisk } from './score.ts'
+import { readTarget } from './target.ts'
 import { FOCUS_IDS, parseFinding, type ReviewFinding } from './types.ts'
 
 async function logLine(runDir: string, entry: Record<string, unknown>): Promise<void> {
@@ -18,11 +20,12 @@ export type RunDedupeOptions = {
 }
 
 /**
- * The five focuses a specialist subagent writes. `tests` is a `FOCUS_IDS` entry
- * too, but setup writes `findings/tests.json` once for the whole run with no
- * subagent, so it is never expected per shard.
+ * The five focuses a specialist subagent writes per shard. `tests` and `checks`
+ * are `FOCUS_IDS` entries too, but each is written once for the whole run
+ * (`tests.json` by setup, `checks.json` by the stage 3 checks pass), so neither
+ * is ever expected per shard.
  */
-const SPECIALIST_FOCUS_IDS = FOCUS_IDS.filter((id) => id !== 'tests')
+const SPECIALIST_FOCUS_IDS = FOCUS_IDS.filter((id) => id !== 'tests' && id !== 'checks')
 
 type Coverage = { expected: number; missing: string[] }
 
@@ -61,6 +64,13 @@ async function reconcileCoverage(runDir: string, present: Set<string>): Promise<
 }
 
 export async function runDedupe(runDir: string, options: RunDedupeOptions = {}): Promise<number> {
+  const target = await readTarget(runDir)
+  // A missing PR worktree means an archived run and evidence checks are skipped; a
+  // missing local root means the caller's repo moved or was mistyped.
+  if (target.mode === 'local' && !existsSync(target.root)) {
+    process.stderr.write(`magpie: dedupe: review root ${target.root} does not exist\n`)
+    return 1
+  }
   const threshold = options.threshold ?? DEFAULT_THRESHOLD
   const findingsDir = join(runDir, 'findings')
   const collected: ReviewFinding[] = []
@@ -123,7 +133,7 @@ export async function runDedupe(runDir: string, options: RunDedupeOptions = {}):
 
   const deduped = deduplicateFindings(collected)
   const scored = deduped.map((f) => ({ ...f, score: scoreRisk(f.risk) }))
-  const evidence = await verifyEvidence(scored, join(runDir, 'worktree'))
+  const evidence = await verifyEvidence(scored, target.root)
   let diff = ''
   try {
     diff = await readFile(join(runDir, 'diff.patch'), 'utf8')

package/skills/magpie/scripts/handoff-cmd.ts

@@ -0,0 +1,132 @@
+import { existsSync } from 'node:fs'
+import { appendFile, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { formatFindingDescriptionMarkdown } from './finding-description.ts'
+import { diffSha256, localBranchDiff } from './local-diff.ts'
+import { rankActionable } from './render-issues-list.ts'
+import { readTarget } from './target.ts'
+import { isSuggestion, parseFinding, type ReviewFinding, type Suggestion } from './types.ts'
+
+async function logLine(runDir: string, entry: Record<string, unknown>): Promise<void> {
+  const line = `${JSON.stringify({ ...entry, ts: Date.now() })}\n`
+  await appendFile(join(runDir, 'log.jsonl'), line)
+}
+
+export type FormatHandoffInput = {
+  target: string
+  findings: ReviewFinding[]
+  stale: boolean
+}
+
+/** A fence longer than any backtick run in the body, so the body cannot close it early. */
+function fenceFor(body: string): string {
+  const longestRun = Math.max(0, ...(body.match(/`+/g) ?? []).map((run) => run.length))
+  return '`'.repeat(Math.max(3, longestRun + 1))
+}
+
+function formatSuggestion(s: Suggestion): string {
+  const lines =
+    s.startLine === s.endLine ? `line ${s.startLine}` : `lines ${s.startLine}-${s.endLine}`
+  const fence = fenceFor(s.body)
+  return `Suggested replacement for ${lines}:\n${fence}\n${s.body}\n${fence}`
+}
+
+function formatItem(n: number, f: ReviewFinding): string {
+  const anchor = f.line === null ? f.file : `${f.file}:${f.line}`
+  const parts = [`${n}. [${f.risk.action}] ${anchor}: ${f.title}`]
+  const body = formatFindingDescriptionMarkdown(f.description)
+  if (body) parts.push(body)
+  if (f.suggestion) parts.push(formatSuggestion(f.suggestion))
+  return parts.join('\n\n')
+}
+
+export function formatHandoff(input: FormatHandoffInput): string {
+  const { target, findings, stale } = input
+  const header = [`# magpie local review: ${target}`]
+  if (stale) {
+    header.push('Warning: the tree changed since this review began; line anchors may be off.')
+  }
+  if (findings.length === 0) return `${header.join('\n')}\n\nNo findings.\n`
+
+  const mustFix = findings.filter((f) => f.risk.action === 'must-fix').length
+  const shouldFix = findings.filter((f) => f.risk.action === 'should-fix').length
+  const optional = findings.filter(isSuggestion).length
+  // topN covers every finding, so nothing folds and the order is score alone.
+  const { recommended } = rankActionable(findings, {}, new Map(), findings.length)
+  const ordered = [...recommended, ...findings.filter(isSuggestion)]
+
+  const sections = [
+    header.join('\n'),
+    `${mustFix} must-fix, ${shouldFix} should-fix, ${optional} optional`,
+    ...ordered.map((f, i) => formatItem(i + 1, f)),
+    'Address every must-fix and should-fix, or say why not. The rest are optional.',
+  ]
+  return `${sections.join('\n\n')}\n`
+}
+
+async function readFindings(path: string): Promise<ReviewFinding[]> {
+  const raw: unknown = JSON.parse(await readFile(path, 'utf8'))
+  if (!Array.isArray(raw)) throw new Error(`${path}: expected an array of findings`)
+  return raw.map(parseFinding)
+}
+
+async function readLocalMeta(path: string): Promise<{ branch: string | null; baseRef: string }> {
+  const raw: unknown = JSON.parse(await readFile(path, 'utf8'))
+  if (typeof raw !== 'object' || raw === null) throw new Error(`${path}: expected an object`)
+  const { branch, baseRef } = raw as Record<string, unknown>
+  if (typeof baseRef !== 'string') {
+    throw new Error(`${path}: baseRef must be a string, got ${JSON.stringify(baseRef)}`)
+  }
+  if (branch !== null && typeof branch !== 'string') {
+    throw new Error(`${path}: branch must be a string or null, got ${JSON.stringify(branch)}`)
+  }
+  return { branch, baseRef }
+}
+
+/** The recorded sha is of the raw diff the review started from; a missing one cannot vouch for freshness. */
+async function recordedDiffSha(runDir: string): Promise<string | null> {
+  const path = join(runDir, 'diff-source.json')
+  if (!existsSync(path)) return null
+  const raw: unknown = JSON.parse(await readFile(path, 'utf8'))
+  if (typeof raw !== 'object' || raw === null) return null
+  const { diffSha256: sha } = raw as Record<string, unknown>
+  return typeof sha === 'string' ? sha : null
+}
+
+export async function runHandoff(runDir: string, opts: { gitBin?: string } = {}): Promise<number> {
+  const gitBin = opts.gitBin ?? 'git'
+  const target = await readTarget(runDir)
+  if (target.mode !== 'local') {
+    process.stderr.write(`magpie: handoff only applies to local runs; ${runDir} is a PR run\n`)
+    return 2
+  }
+  const findingsPath = join(runDir, 'findings.final.json')
+  const metaPath = join(runDir, 'local.json')
+  for (const path of [findingsPath, metaPath]) {
+    if (!existsSync(path)) {
+      process.stderr.write(`magpie: handoff: ${path} is missing\n`)
+      return 4
+    }
+  }
+  const findings = await readFindings(findingsPath)
+  const meta = await readLocalMeta(metaPath)
+
+  const recorded = await recordedDiffSha(runDir)
+  // A failed recompute proves nothing about the tree, so it is reported as stale.
+  let currentSha: string | null = null
+  try {
+    const current = await localBranchDiff({ gitBin, repoPath: target.root, baseRef: meta.baseRef })
+    if (current.ok) currentSha = diffSha256(current.diff)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    process.stderr.write(`magpie: handoff: could not recompute the diff: ${message}\n`)
+  }
+  const stale = recorded === null || currentSha === null || currentSha !== recorded
+
+  const subject = meta.branch === null ? 'detached HEAD' : `local branch ${meta.branch}`
+  process.stdout.write(
+    formatHandoff({ target: `${subject} against ${meta.baseRef}`, findings, stale }),
+  )
+  await logLine(runDir, { stage: 'handoff', status: 'done', findings: findings.length })
+  return 0
+}

package/skills/magpie/scripts/housekeeping-cmd.ts

@@ -2,8 +2,10 @@ import { readdir, rm, stat } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 
-const ACTIVE_PATTERN = /^pr-\d+-\d+$/
-const ARCHIVED_PATTERN = /^pr-\d+-\d+\.archived-\d+$/
+// Local slugs may contain dots and dashes, so an archived local id also matches
+// ACTIVE_PATTERN: test ARCHIVED_PATTERN first.
+const ACTIVE_PATTERN = /^(?:pr-\d+|local-[A-Za-z0-9._-]+)-\d+$/
+const ARCHIVED_PATTERN = /^(?:pr-\d+|local-[A-Za-z0-9._-]+)-\d+\.archived-\d+$/
 
 export function reviewHome(): string {
   return process.env.MAGPIE_HOME ?? join(homedir(), '.magpie')
@@ -24,10 +26,10 @@ export async function listRuns(home?: string): Promise<RunInfo[]> {
     const path = join(root, id)
     const s = await stat(path).catch(() => null)
     if (!s?.isDirectory()) continue
-    if (ACTIVE_PATTERN.test(id)) {
-      runs.push({ id, archived: false, path })
-    } else if (ARCHIVED_PATTERN.test(id)) {
+    if (ARCHIVED_PATTERN.test(id)) {
       runs.push({ id, archived: true, path })
+    } else if (ACTIVE_PATTERN.test(id)) {
+      runs.push({ id, archived: false, path })
     }
   }
   return runs

package/skills/magpie/scripts/local-diff.ts

@@ -0,0 +1,228 @@
+import { createHash } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { copyFile, mkdtemp, realpath, rm, stat, utimes } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+export type LocalBranchDiffInput = {
+  gitBin: string
+  repoPath: string
+  baseRef?: string
+}
+
+export type LocalBranchDiffResult =
+  | { ok: true; diff: string; baseRef: string; mergeBase: string; head: string }
+  | { ok: false; error: string }
+
+export type LocalMeta = {
+  branch: string | null
+  baseRef: string
+  mergeBase: string
+  head: string
+  dirty: boolean
+  author: string
+  commits: Array<{ oid: string; headline: string; body: string }>
+  intentFile: string | null
+}
+
+export type LocalBranchMetaInput = {
+  gitBin: string
+  repoPath: string
+  baseRef: string
+  mergeBase: string
+  head: string
+  intentFile: string | null
+}
+
+export type LocalBranchMetaResult = { ok: true; meta: LocalMeta } | { ok: false; error: string }
+
+async function git(
+  gitBin: string,
+  cwd: string,
+  args: string[],
+  extraEnv: Record<string, string> = {},
+): Promise<{ exit: number; stdout: string; stderr: string }> {
+  // Bun.spawn snapshots the env at startup unless given one, so pass the live
+  // env to honour GIT_CONFIG_* or HOME set after launch. GIT_OPTIONAL_LOCKS=0
+  // stops status refreshing the caller's index. quotePath=false keeps
+  // non-ASCII paths readable by the downstream header parsers.
+  const proc = Bun.spawn([gitBin, '-c', 'core.quotePath=false', ...args], {
+    cwd,
+    env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', ...extraEnv },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ])
+  const exit = await proc.exited
+  return { exit, stdout, stderr }
+}
+
+// Pin the patch format against user config (noprefix, mnemonicPrefix, external
+// diff drivers, textconv) so the downstream parsers always see git's default.
+const DIFF_FORMAT = [
+  '--no-color',
+  '--no-ext-diff',
+  '--no-textconv',
+  '--src-prefix=a/',
+  '--dst-prefix=b/',
+]
+
+async function resolveCommit(gitBin: string, cwd: string, ref: string): Promise<string | null> {
+  const r = await git(gitBin, cwd, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])
+  const sha = r.stdout.trim()
+  return r.exit === 0 && sha.length > 0 ? sha : null
+}
+
+/**
+ * Diff the checked-out branch against its merge base with `baseRef`, including
+ * uncommitted edits and untracked (non-ignored) files. Read-only: untracked
+ * files go through `--no-index` rather than `git add -N`, so the caller's index
+ * is never touched, and nothing is fetched.
+ */
+export async function localBranchDiff(input: LocalBranchDiffInput): Promise<LocalBranchDiffResult> {
+  const { gitBin, repoPath } = input
+  const baseRef = input.baseRef ?? 'origin/HEAD'
+
+  const top = await git(gitBin, repoPath, ['rev-parse', '--show-toplevel'])
+  if (top.exit !== 0) {
+    return { ok: false, error: `${repoPath} is not a git repository: ${top.stderr.trim()}` }
+  }
+  const toplevel = top.stdout.trim()
+  if ((await realpath(toplevel)) !== (await realpath(repoPath))) {
+    return { ok: false, error: `${repoPath} is not the repository root (${toplevel})` }
+  }
+
+  const base = await resolveCommit(gitBin, repoPath, baseRef)
+  if (!base) return { ok: false, error: `cannot resolve base ref ${baseRef} to a commit` }
+
+  const head = await resolveCommit(gitBin, repoPath, 'HEAD')
+  if (!head) return { ok: false, error: 'cannot resolve HEAD to a commit' }
+
+  const mb = await git(gitBin, repoPath, ['merge-base', base, head])
+  const mergeBase = mb.stdout.trim()
+  if (mb.exit !== 0 || !mergeBase) {
+    return { ok: false, error: `no merge base between ${baseRef} and HEAD: ${mb.stderr.trim()}` }
+  }
+
+  const indexPath = await git(gitBin, repoPath, ['rev-parse', '--git-path', 'index'])
+  if (indexPath.exit !== 0) {
+    return { ok: false, error: `git rev-parse --git-path index failed: ${indexPath.stderr.trim()}` }
+  }
+  const realIndex = resolve(repoPath, indexPath.stdout.trim())
+  const scratch = await mkdtemp(join(tmpdir(), 'magpie-index-'))
+  let tracked: { exit: number; stdout: string; stderr: string }
+  try {
+    // git refreshes stat info into the index on `git diff <commit>` regardless
+    // of optional locks, so that diff runs against a throwaway copy.
+    const indexEnv: Record<string, string> = {}
+    if (existsSync(realIndex)) {
+      const copy = join(scratch, 'index')
+      // git trusts cached stat data only for files older than the index file,
+      // so a fresh mtime on the copy would hide same-second edits. The stat
+      // comes first so a concurrent index rewrite can only pair newer bytes
+      // with an older mtime, which makes git recheck more, not less.
+      const original = await stat(realIndex)
+      await copyFile(realIndex, copy)
+      await utimes(copy, original.atime, original.mtime)
+      indexEnv.GIT_INDEX_FILE = copy
+    }
+    tracked = await git(
+      gitBin,
+      repoPath,
+      ['diff', ...DIFF_FORMAT, '--find-renames', mergeBase],
+      indexEnv,
+    )
+  } finally {
+    await rm(scratch, { recursive: true, force: true })
+  }
+  if (tracked.exit !== 0) {
+    return { ok: false, error: `git diff ${mergeBase} failed: ${tracked.stderr.trim()}` }
+  }
+
+  const others = await git(gitBin, repoPath, ['ls-files', '--others', '--exclude-standard', '-z'])
+  if (others.exit !== 0) {
+    return { ok: false, error: `git ls-files failed: ${others.stderr.trim()}` }
+  }
+  const untracked = others.stdout.split('\0').filter((p) => p.length > 0)
+
+  let diff = tracked.stdout
+  for (const path of untracked) {
+    // `--no-index` exits 1 when the files differ, which is always the case here.
+    const r = await git(gitBin, repoPath, [
+      'diff',
+      ...DIFF_FORMAT,
+      '--no-index',
+      '--',
+      '/dev/null',
+      path,
+    ])
+    if (r.exit !== 1) {
+      return {
+        ok: false,
+        error: `git diff --no-index ${path} exited ${r.exit}: ${r.stderr.trim()}`,
+      }
+    }
+    diff += r.stdout
+  }
+
+  if (diff.length === 0) return { ok: false, error: `nothing to review against ${baseRef}` }
+  return { ok: true, diff, baseRef, mergeBase, head }
+}
+
+export async function localBranchMeta(input: LocalBranchMetaInput): Promise<LocalBranchMetaResult> {
+  const { gitBin, repoPath, baseRef, mergeBase, head, intentFile } = input
+
+  // Exit 1 with no output is a detached HEAD, not an error.
+  const sym = await git(gitBin, repoPath, ['symbolic-ref', '--short', '-q', 'HEAD'])
+  if (sym.exit !== 0 && sym.exit !== 1) {
+    return { ok: false, error: `git symbolic-ref failed: ${sym.stderr.trim()}` }
+  }
+  const branch = sym.exit === 0 ? sym.stdout.trim() : null
+
+  const status = await git(gitBin, repoPath, ['status', '--porcelain'])
+  if (status.exit !== 0) return { ok: false, error: `git status failed: ${status.stderr.trim()}` }
+
+  const name = await git(gitBin, repoPath, ['config', 'user.name'])
+  const author = name.stdout.trim()
+  if (name.exit !== 0 || !author) {
+    return { ok: false, error: 'git config user.name is not set; set it and retry' }
+  }
+
+  const log = await git(gitBin, repoPath, [
+    'log',
+    '--format=%H%x1f%s%x1f%b%x1e',
+    `${mergeBase}..${head}`,
+  ])
+  if (log.exit !== 0) return { ok: false, error: `git log failed: ${log.stderr.trim()}` }
+  const commits: LocalMeta['commits'] = []
+  for (const record of log.stdout.split('\x1e')) {
+    const trimmed = record.replace(/^\n/, '')
+    if (!trimmed) continue
+    const [oid, headline, body] = trimmed.split('\x1f')
+    if (oid === undefined || headline === undefined || body === undefined) {
+      return { ok: false, error: `malformed git log record: ${JSON.stringify(trimmed)}` }
+    }
+    commits.push({ oid, headline, body: body.trim() })
+  }
+
+  return {
+    ok: true,
+    meta: {
+      branch,
+      baseRef,
+      mergeBase,
+      head,
+      dirty: status.stdout.trim().length > 0,
+      author,
+      commits,
+      intentFile,
+    },
+  }
+}
+
+export function diffSha256(diff: string): string {
+  return createHash('sha256').update(diff, 'utf8').digest('hex')
+}

package/skills/magpie/scripts/post-cmd.ts

@@ -73,6 +73,7 @@ const FOCUS_LABEL: Record<FocusId, string> = {
   performance: 'Performance',
   'code-smells': 'Code Smells',
   architecture: 'Architecture',
+  checks: 'Checks',
   tests: 'Tests',
 }
 

package/skills/magpie/scripts/render-annotation.ts

@@ -10,6 +10,7 @@ const DOMAIN_LABELS: Record<string, string> = {
   performance: 'Perf',
   'code-smells': 'Smells',
   architecture: 'Arch',
+  checks: 'Checks',
 }
 
 const SEVERITY_LABEL: Record<string, string> = {

package/skills/magpie/scripts/resolve-run.ts

@@ -1,6 +1,8 @@
+import { existsSync } from 'node:fs'
 import { readdir, stat } from 'node:fs/promises'
 import { isAbsolute, join } from 'node:path'
 import { reviewHome } from './housekeeping-cmd.ts'
+import { readTarget } from './target.ts'
 
 export type ResolvedRun = {
   id: string
@@ -8,8 +10,15 @@ export type ResolvedRun = {
   archived: boolean
 }
 
+// open and serve render the HTML report, which local runs never get, so only PR
+// runs are candidates here. --list-runs still lists local runs for resume.
 const ACTIVE_PATTERN = /^pr-\d+-\d+$/
 const ARCHIVED_PATTERN = /^pr-(\d+)-\d+\.archived-(\d+)$/
+const LOCAL_PATTERN = /^local-[A-Za-z0-9._-]+-\d+(?:\.archived-\d+)?$/
+
+function localRunError(idOrPath: string): Error {
+  return new Error(`${idOrPath} is a local run; local runs have no report`)
+}
 
 type Entry = { id: string; path: string; archived: boolean; mtimeMs: number }
 
@@ -25,10 +34,10 @@ async function listEntries(home: string): Promise<Entry[]> {
     const path = join(home, id)
     const s = await stat(path).catch(() => null)
     if (!s?.isDirectory()) continue
-    if (ACTIVE_PATTERN.test(id)) {
-      out.push({ id, path, archived: false, mtimeMs: s.mtimeMs })
-    } else if (ARCHIVED_PATTERN.test(id)) {
+    if (ARCHIVED_PATTERN.test(id)) {
       out.push({ id, path, archived: true, mtimeMs: s.mtimeMs })
+    } else if (ACTIVE_PATTERN.test(id)) {
+      out.push({ id, path, archived: false, mtimeMs: s.mtimeMs })
     }
   }
   return out
@@ -50,11 +59,16 @@ export async function resolveRunDir(
     if (!(await isReviewDir(path))) {
       throw new Error(`Not a magpie run directory: ${path}`)
     }
+    // Without target.json the run predates local mode, so it is a PR run.
+    if (existsSync(join(path, 'target.json')) && (await readTarget(path)).mode === 'local') {
+      throw localRunError(path)
+    }
     const id = path.split('/').filter(Boolean).pop() ?? path
     return { id, path, archived: ARCHIVED_PATTERN.test(id) }
   }
 
   if (idOrPath) {
+    if (LOCAL_PATTERN.test(idOrPath)) throw localRunError(idOrPath)
     const path = join(root, idOrPath)
     if (!(await isReviewDir(path))) {
       throw new Error(`Run id not found: ${idOrPath} (looked in ${root})`)

package/skills/magpie/scripts/server.ts

@@ -15,6 +15,12 @@ export type StartServerInput = {
   host?: string
 }
 
+const FINDINGS_HTML_RE = /^findings(-v\d+)?\.html$/
+
+/**
+ * Once a findings page exists it is what the user came for, so it wins even
+ * though stage 8 re-renders progress after it; until then the newest page does.
+ */
 async function newestScreenPath(runDir: string): Promise<string | null> {
   const dir = join(runDir, 'screen')
   let entries: string[]
@@ -23,9 +29,11 @@ async function newestScreenPath(runDir: string): Promise<string | null> {
   } catch {
     return null
   }
+  const findings = entries.filter((name) => FINDINGS_HTML_RE.test(name))
+  const candidates = findings.length > 0 ? findings : entries
   let bestPath: string | null = null
   let bestMtime = -Infinity
-  for (const name of entries) {
+  for (const name of candidates) {
     if (!name.endsWith('.html')) continue
     const path = join(dir, name)
     const s = await stat(path)