@node-core/utils 7.3.1 → 7.4.1

package/bin/ncu-ci.js

@@ -24,6 +24,8 @@ import {
   RunPRJob
 } from '../lib/ci/run_ci.js';
 import { ResumePRJob } from '../lib/ci/resume_ci.js';
+import { checkAvailability } from '../lib/ci/availability.js';
+import { getPRWorkload } from '../lib/ci/workload.js';
 import { writeJson, writeFile } from '../lib/file.js';
 import { getMergedConfig } from '../lib/config.js';
 import { runPromise } from '../lib/run.js';
@@ -54,6 +56,16 @@ const commandKeys = [
 
 const args = yargs(hideBin(process.argv))
   .completion('completion')
+  .command({
+    command: 'available',
+    desc: 'Check whether Jenkins is available for PR CI requests',
+    handler
+  })
+  .command({
+    command: 'workload',
+    desc: 'Print the number of running and queued node-test-pull-request jobs',
+    handler
+  })
   .command({
     command: 'rate <type>',
     desc: 'Calculate the green rate of a CI job in the last 100 runs',
@@ -598,7 +610,34 @@ class DailyCommand extends CICommand {
   }
 }
 
+async function checkJenkins(command) {
+  try {
+    let jenkins;
+    try {
+      const credentials = await auth({ github: false, jenkins: true });
+      jenkins = credentials.jenkins;
+    } catch {
+      throw new Error('Configure username and jenkins_token with ncu-config');
+    }
+    const request = new Request({ jenkins });
+    if (command === 'available') {
+      await checkAvailability(request);
+    } else {
+      console.log(await getPRWorkload(request));
+    }
+  } catch (err) {
+    const action = command === 'available'
+      ? 'check Jenkins availability'
+      : 'read the PR CI workload';
+    console.error(`Unable to ${action}: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
 async function main(command, argv) {
+  if (command === 'available' || command === 'workload') {
+    return checkJenkins(command);
+  }
   const cli = new CLI();
   const credentials = await auth({
     github: true,

package/lib/ci/availability.js

@@ -0,0 +1,24 @@
+import { readJenkinsJSON } from './jenkins.js';
+
+export async function checkAvailability(request) {
+  const signal = AbortSignal.timeout(20_000);
+  const controller = await readJenkinsJSON(request, '/api/json?tree=quietingDown', signal);
+  if (controller?.quietingDown === true) {
+    throw new Error('Jenkins is preparing for shutdown');
+  }
+  if (controller?.quietingDown !== false) {
+    throw new Error('Jenkins quiet-down state is not confirmed');
+  }
+
+  const job = await readJenkinsJSON(request,
+    '/job/node-test-pull-request/api/json?tree=disabled,buildable', signal);
+  if (job?.disabled === true) {
+    throw new Error('Jenkins PR job is disabled');
+  }
+  if (job?.buildable === false) {
+    throw new Error('Jenkins PR job is not buildable');
+  }
+  if (job?.disabled !== false || job?.buildable !== true) {
+    throw new Error('Jenkins PR job availability is not confirmed');
+  }
+}

package/lib/ci/ci_utils.js

@@ -1,4 +1,5 @@
 import qs from 'node:querystring';
+import { getPrURL } from '../links.js';
 
 import {
   CI_DOMAIN,
@@ -13,6 +14,18 @@ export const statusType = {
   UNSTABLE: 'UNSTABLE'
 };
 
+export function getCIActionAdvice(pr, action) {
+  const command = `ncu-ci ${action} ${getPrURL(pr)}`;
+  if (action === 'run') {
+    return 'Check the existing CI run in Jenkins and rebase the PR if needed. ' +
+      `To start a new CI run manually: ${command}`;
+  }
+  if (pr.owner === 'nodejs' && pr.repo === 'node') {
+    return `Resume CI by adding the "resume-ci" label to the PR, or run: ${command}`;
+  }
+  return `Resume CI with: ${command}`;
+}
+
 export function getPath(url) {
   return url.replace(`https://${CI_DOMAIN}/`, '').replace('api/json', '');
 }

package/lib/ci/failure_file_scanner.js

@@ -13,6 +13,30 @@ const diagnostic = createMatcher(FAILURE_PATTERNS.diagnostic);
 const infrastructure = createMatcher(FAILURE_PATTERNS.infrastructure);
 const gitStart = createMatcher(FAILURE_MARKERS.git.map(({ start }) => start));
 const gitEnd = createMatcher(FAILURE_MARKERS.git.map(({ end }) => end));
+const makeRecipeFailure = createMatcher([
+  /^\s*(?:\[(?:out|err)\]\s*)?g?make(?:\[\d+\])?: \*\*\* \[[^\r\n]+\] .+$/,
+  /^\s*(?:\[(?:out|err)\]\s*)?[^\r\n]+:\d+: recipe for target '.+' failed$/
+]);
+const makefileDiagnostic = /^\s*(?:\[(?:out|err)\]\s*)?[^\r\n]+:\d+: \*\*\* /;
+
+// Keep both ends of large diagnostics without retaining whole lines or TAP blocks.
+class FailureExcerpt {
+  head = '';
+  tail = '';
+  length = 0;
+
+  append(text) {
+    const remaining = Math.max(0, 4096 - this.head.length);
+    this.head += text.slice(0, remaining);
+    this.tail = (this.tail + text.slice(remaining)).slice(-4096);
+    this.length += text.length;
+  }
+
+  toString() {
+    const omitted = this.length > 8192 ? '\n[... failure output truncated ...]\n' : '';
+    return this.head + omitted + this.tail;
+  }
+}
 
 function fileAliases(filename) {
   const paths = new Set([filename]);
@@ -35,15 +59,16 @@ async function * logWindows(source, overlap) {
 
   function * consume(raw) {
     raw = raw.replace(/\r/g, '');
-    let text = raw.replace(/\\+/g, '/');
-    if (afterBackslash && raw.startsWith('\\')) text = text.slice(1);
-    if (raw) afterBackslash = raw.endsWith('\\');
-    for (let offset = 0; offset < text.length;) {
-      const newline = text.indexOf('\n', offset);
-      const end = Math.min(offset + 8192, newline < 0 ? text.length : newline + 1);
-      const window = tail + text.slice(offset, end);
+    for (let offset = 0; offset < raw.length;) {
+      const newline = raw.indexOf('\n', offset);
+      const end = Math.min(offset + 8192, newline < 0 ? raw.length : newline + 1);
+      const content = raw.slice(offset, end);
+      let normalized = content.replace(/\\+/g, '/');
+      if (afterBackslash && content.startsWith('\\')) normalized = normalized.slice(1);
+      afterBackslash = content.endsWith('\\');
+      const window = tail + normalized;
       const lineEnd = end === newline + 1;
-      yield { text: window, lineStart, lineEnd };
+      yield { text: window, content, lineStart, lineEnd };
       if (lineEnd) {
         tail = '';
         lineStart = true;
@@ -57,14 +82,15 @@ async function * logWindows(source, overlap) {
 
   for await (const chunk of source) yield * consume(decoder.write(chunk));
   yield * consume(decoder.end());
-  if (tail) yield { text: `${tail}\n`, lineStart, lineEnd: true };
+  if (tail) yield { text: `${tail}\n`, content: '\n', lineStart, lineEnd: true };
 }
 
-// Each line is reduced to a filename and failure markers. Neither a giant line
-// nor a giant TAP block needs to survive in memory.
+// Retain failure markers and a bounded excerpt for each line.
 async function * failureLines(windows, matchFile) {
   let line = {};
-  for await (const { text, lineStart, lineEnd } of windows) {
+  let excerpt = new FailureExcerpt();
+  for await (const { text, content, lineStart, lineEnd } of windows) {
+    excerpt.append(content);
     line.file ??= matchFile(text, lineStart);
     line.diagnostic ||= diagnostic(text);
     line.infrastructure ||= infrastructure(text);
@@ -75,8 +101,17 @@ async function * failureLines(windows, matchFile) {
     line.gitStart ||= gitStart(text);
     line.gitEnd ||= gitEnd(text);
     if (lineEnd) {
+      line.text = excerpt.toString();
+      if (makeRecipeFailure(line.text.trimEnd())) {
+        // The recipe location reports a child's exit, not the source of its
+        // failure. Keep the output without attributing it through TAP or history.
+        line = { text: line.text, todo: line.todo };
+      } else {
+        line.diagnostic ||= makefileDiagnostic.test(line.text);
+      }
       yield line;
       line = {};
+      excerpt = new FailureExcerpt();
     }
   }
 }
@@ -84,44 +119,60 @@ async function * failureLines(windows, matchFile) {
 async function findFailure(lines) {
   let history = [];
   let followingLines = 0;
+  let diagnosticExcerpt;
   let tap = null;
   let git = null;
 
   for await (const line of lines) {
     const precedingLines = history;
-    history = [...history, line.file].slice(-5);
+    history = [...history, line].slice(-5);
     if (line.tapStart) {
-      tap = {};
+      tap = { excerpt: new FailureExcerpt() };
       followingLines = 0;
     }
     if (tap) {
+      tap.excerpt.append(line.text);
       tap.file ??= line.file;
       tap.todo ||= line.todo;
       // A later TODO can mark this as an expected failure; wait for the ending.
       if (line.tapEnd) {
-        if (!tap.todo && tap.file) return tap.file;
+        if (!tap.todo && tap.file) {
+          return { filename: tap.file, reason: tap.excerpt.toString().trimEnd() };
+        }
         tap = null;
       }
       continue;
     }
 
-    if (line.gitStart) git = {};
+    if (line.gitStart) git = { excerpt: new FailureExcerpt() };
     if (git) {
+      git.excerpt.append(line.text);
       git.file ??= line.file;
       if (line.gitEnd) {
-        if (git.file) return git.file;
+        if (git.file) return { filename: git.file, reason: git.excerpt.toString().trimEnd() };
         git = null;
       }
     }
     if (line.infrastructure || line.cpp) {
       const before = line.cpp ? 5 : 1;
-      const file = line.file || precedingLines.slice(-before).find(Boolean);
-      if (file) return file;
+      const context = [...precedingLines.slice(-before), line];
+      const filename = line.file || context.find(previous => previous.file)?.file;
+      if (filename) {
+        const excerpt = new FailureExcerpt();
+        for (const previous of context) excerpt.append(previous.text);
+        return { filename, reason: excerpt.toString().trimEnd() };
+      }
+    }
+    if (line.diagnostic) {
+      followingLines = 6;
+      diagnosticExcerpt = new FailureExcerpt();
     }
-    if (line.diagnostic) followingLines = 6;
     if (followingLines > 0) {
       followingLines--;
-      if (line.file) return line.file;
+      diagnosticExcerpt.append(line.text);
+      if (line.file) {
+        return { filename: line.file, reason: diagnosticExcerpt.toString().trimEnd() };
+      }
     }
   }
 }

package/lib/ci/jenkins.js

@@ -0,0 +1,23 @@
+import { CI_DOMAIN } from './ci_type_parser.js';
+
+export async function readJenkinsJSON(request, path, signal) {
+  const response = await request.fetch(`https://${CI_DOMAIN}${path}`, {
+    method: 'GET',
+    headers: { Accept: 'application/json' },
+    redirect: 'error',
+    signal
+  });
+  if (response.status !== 200) {
+    await response.body?.cancel();
+    throw new Error(`Jenkins returned HTTP ${response.status} ${response.statusText ?? ''}`.trim());
+  }
+  try {
+    return await response.json();
+  } catch (cause) {
+    if (signal.aborted) throw signal.reason;
+    if (cause instanceof SyntaxError) {
+      throw new Error('Jenkins returned invalid JSON', { cause });
+    }
+    throw cause;
+  }
+}

package/lib/ci/resumable_build.js

@@ -0,0 +1,86 @@
+import { PRBuild } from './build-types/pr_build.js';
+
+export const RESUME_TREE = 'result,building,' +
+  'actions[parameters[name,value],causes[_class,upstreamProject,upstreamBuild,upstreamUrl]]';
+const RESUME_CAUSE = 'com.tikal.jenkins.plugins.multijob.ResumeCause';
+const PR_JOB = 'node-test-pull-request';
+
+function getParameter(data, name) {
+  const values = new Set((data.actions ?? []).flatMap(action => action.parameters ?? [])
+    .filter(parameter => parameter.name === name)
+    .map(parameter => parameter.value));
+  return values.size === 1 ? [...values][0] : undefined;
+}
+
+export function getApprovedSHA(data) {
+  const value = getParameter(data, 'COMMIT_SHA_CHECK');
+  return typeof value === 'string' && value ? value : undefined;
+}
+
+export async function hasResumeAction(request, build) {
+  // The build API omits unexported actions. The context menu exposes the
+  // same actions Jenkins offers to the authenticated user on the build page.
+  const response = await request.fetch(`${build.jobUrl}contextMenu`, {
+    method: 'GET',
+    redirect: 'error'
+  });
+  if (response.status !== 200) {
+    await response.body?.cancel();
+    throw new Error(
+      `Jenkins returned HTTP ${response.status} ${response.statusText ?? ''}`.trim());
+  }
+  const menu = await response.json();
+  if (!Array.isArray(menu?.items)) {
+    throw new Error('Jenkins returned an invalid build context menu');
+  }
+  const resumeURL = `${build.jobUrl}resume`;
+  return menu.items.some(item => {
+    // Jenkins' new build page exposes action URLs through a LinkEvent.
+    const actionURL = item?.url ?? item?.event?.url;
+    if (typeof actionURL !== 'string') return false;
+    let url;
+    try {
+      url = new URL(actionURL, build.jobUrl).href;
+    } catch {
+      return false;
+    }
+    return url === resumeURL || url === `${resumeURL}/`;
+  });
+}
+
+export async function findResumableBuild(cli, request, { jobid, owner, repo, prid }, data) {
+  const approvedSHA = getApprovedSHA(data);
+  const checkedBuilds = [];
+  if (!approvedSHA) return { build: undefined, checkedBuilds, approvedSHA };
+  let build = new PRBuild(cli, request, jobid, undefined, RESUME_TREE);
+  while (data.building === false &&
+         (data.result === 'FAILURE' || data.result === 'ABORTED')) {
+    if (getApprovedSHA(data) !== approvedSHA) break;
+    const buildOwner = getParameter(data, 'TARGET_GITHUB_ORG');
+    const buildRepo = getParameter(data, 'TARGET_REPO_NAME');
+    if (typeof buildOwner !== 'string' || buildOwner.toLowerCase() !== owner.toLowerCase() ||
+        typeof buildRepo !== 'string' || buildRepo.toLowerCase() !== repo.toLowerCase() ||
+        String(getParameter(data, 'PR_ID')) !== String(prid)) {
+      throw new Error(`CI job ${jobid} does not match pull request ${owner}/${repo}#${prid}`);
+    }
+    checkedBuilds.push({ jobid, build });
+    if (await hasResumeAction(request, build)) {
+      return { jobid, build, checkedBuilds, approvedSHA };
+    }
+
+    // Jenkins copies earlier causes when resuming. Follow the nearest parent,
+    // not the first cause, and only within this PR job's actual resume lineage.
+    const parent = (data.actions ?? []).flatMap(action => action.causes ?? [])
+      .filter(cause => cause?._class === RESUME_CAUSE &&
+        cause.upstreamProject === PR_JOB && cause.upstreamUrl === `job/${PR_JOB}/` &&
+        Number.isSafeInteger(cause.upstreamBuild) &&
+        cause.upstreamBuild > 0 && cause.upstreamBuild < jobid)
+      .sort((a, b) => b.upstreamBuild - a.upstreamBuild)[0];
+    if (!parent) break;
+
+    jobid = parent.upstreamBuild;
+    build = new PRBuild(cli, request, jobid, undefined, RESUME_TREE);
+    data = await build.getBuildData();
+  }
+  return { build: undefined, checkedBuilds, approvedSHA };
+}

package/lib/ci/resume_ci.js

@@ -4,6 +4,8 @@ import { PRBuild } from './build-types/pr_build.js';
 import { getPrURL } from '../links.js';
 import { debuglog } from '../verbosity.js';
 import { FailureFileScanner } from './failure_file_scanner.js';
+import { findResumableBuild, getApprovedSHA, RESUME_TREE } from './resumable_build.js';
+import { getCIActionAdvice } from './ci_utils.js';
 
 export class ResumePRJob {
   constructor(cli, request, owner, repo, prid) {
@@ -14,6 +16,15 @@ export class ResumePRJob {
     this.prid = prid;
   }
 
+  reportUnavailable(jobid, build) {
+    const { cli } = this;
+    cli.stopSpinner(
+      `Cannot resume PR CI job ${jobid}: Jenkins does not offer a "Resume build" action. ` +
+      getCIActionAdvice(this, 'run'),
+      cli.SPINNER_STATUS.FAILED);
+    cli.error(build.jobUrl);
+  }
+
   async checkFailures(jobid) {
     const { cli, request, owner, repo, prid } = this;
     const filenames = new Set();
@@ -22,7 +33,7 @@ export class ResumePRJob {
         filenames.add(filename);
       }
     }
-    const overlaps = new Set();
+    let overlap;
     const buildRequest = Object.create(request);
     buildRequest.json = async(...args) => {
       const data = await request.json(...args);
@@ -35,10 +46,10 @@ export class ResumePRJob {
     let pending = Promise.resolve();
     buildRequest.text = (url) => {
       const scan = pending.then(async() => {
-        if (!filenames.size || overlaps.size) return '';
+        if (!filenames.size || overlap) return '';
         const scanner = new FailureFileScanner(filenames);
         const match = await scanner.scan(request.stream(url));
-        if (match) overlaps.add(match);
+        if (match) overlap = { ...match, url };
         return '';
       });
       pending = scan.catch(debuglog);
@@ -51,10 +62,10 @@ export class ResumePRJob {
       debuglog(err);
     }
     await pending;
-    if (overlaps.size) {
-      for (const filename of [...overlaps].sort()) {
-        cli.error(filename);
-      }
+    if (overlap) {
+      cli.error(overlap.filename);
+      cli.info(overlap.url);
+      cli.log(overlap.reason);
       return false;
     }
     return true;
@@ -71,11 +82,13 @@ export class ResumePRJob {
       }
     } catch (err) {
       debuglog(err);
-      cli.stopSpinner('Jenkins credentials invalid', cli.SPINNER_STATUS.FAILED);
+      cli.stopSpinner(`Unable to validate Jenkins credentials: ${err.message}`,
+        cli.SPINNER_STATUS.FAILED);
       return false;
     }
     cli.stopSpinner('Jenkins credentials valid');
 
+    let failureMessage = `Failed to find CI runs for pull request ${prid}`;
     try {
       cli.startSpinner(`Looking for CI runs for pull request ${prid}`);
       const parser = await JobParser.fromPR(getPrURL(this), cli, request);
@@ -87,32 +100,48 @@ export class ResumePRJob {
       }
       cli.stopSpinner(`Found PR CI job ${job.jobid}`);
 
-      const build = new PRBuild(cli, request, job.jobid, undefined,
-        'result,building,actions[parameters[name,value]]');
-      const { result, building, actions = [] } = await build.getBuildData();
+      failureMessage = `Failed to load PR CI job ${job.jobid}`;
+      const latestBuild = new PRBuild(cli, request, job.jobid, undefined, RESUME_TREE);
+      const data = await latestBuild.getBuildData();
+      const { result, building } = data;
       if (building || (result !== 'FAILURE' && result !== 'ABORTED')) {
         const status = building ? 'RUNNING' : result ?? 'RUNNING';
         cli.error(`CI job ${job.jobid} is in status ${status}, skipping resume`);
         return false;
       }
-      const approvedSHAs = new Set(actions.flatMap(action => action.parameters ?? [])
-        .filter(parameter => parameter.name === 'COMMIT_SHA_CHECK')
-        .map(parameter => parameter.value));
-      const [approvedSHA] = approvedSHAs;
-      if (approvedSHAs.size !== 1 || typeof approvedSHA !== 'string' || !approvedSHA) {
+      const approvedSHA = getApprovedSHA(data);
+      if (!approvedSHA) {
         cli.error(`Refusing to resume CI job ${job.jobid}: cannot determine its approved commit`);
         return false;
       }
 
-      cli.startSpinner('Checking failures against changed PR files');
-      if (!(await this.checkFailures(job.jobid))) {
-        cli.stopSpinner('Refusing to resume CI: failures reference files changed by this PR',
-          cli.SPINNER_STATUS.FAILED);
+      failureMessage = `Failed to check resume availability for PR CI job ${job.jobid}`;
+      cli.startSpinner(`Checking whether PR CI job ${job.jobid} can be resumed`);
+      const { build, jobid: resumeJobid, checkedBuilds } = await findResumableBuild(cli, request, {
+        jobid: job.jobid, owner: this.owner, repo: this.repo, prid
+      }, data);
+      if (!build) {
+        this.reportUnavailable(job.jobid, latestBuild);
         return false;
       }
+      cli.stopSpinner('Jenkins offers a Resume build action');
+      if (resumeJobid !== job.jobid) {
+        cli.info(`Using resumable ancestor PR CI job ${resumeJobid} for latest job ${job.jobid}`);
+      }
+
+      failureMessage = `Failed to check failures for PR CI job ${job.jobid}`;
+      cli.startSpinner('Checking failures against changed PR files');
+      for (const { jobid } of checkedBuilds) {
+        if (!(await this.checkFailures(jobid))) {
+          cli.stopSpinner('Refusing to resume CI: failures reference files changed by this PR',
+            cli.SPINNER_STATUS.FAILED);
+          return false;
+        }
+      }
       cli.stopSpinner('No changed PR files found in available failure details');
 
       // Read HEAD after inspecting failures so the comparison is fresh when resuming.
+      failureMessage = `Failed to read the current HEAD for pull request ${prid}`;
       const pr = await request.getPullRequest(getPrURL(this));
       if (pr.head?.sha !== approvedSHA) {
         cli.error(`Refusing to resume CI job ${job.jobid}: ` +
@@ -120,25 +149,35 @@ export class ResumePRJob {
         return false;
       }
 
-      cli.startSpinner(`Resuming PR CI job ${job.jobid}`);
-      // Jenkins does not export its resume action in the build API. Let the
-      // resume endpoint determine whether the action is available.
+      failureMessage = `Failed to resume PR CI job ${resumeJobid}`;
+      cli.startSpinner(`Resuming PR CI job ${resumeJobid}`);
       const response = await request.fetch(`${build.jobUrl}resume/`, {
         method: 'POST',
         headers: {
           'Jenkins-Crumb': crumb
         }
       });
+      await response.body?.cancel();
+      // The action may disappear after the preflight check.
+      if (response.status === 404) {
+        this.reportUnavailable(resumeJobid, build);
+        return false;
+      }
       if (response.status !== 200) {
+        const status = `HTTP ${response.status} ${response.statusText ?? ''}`.trim();
+        const reason = response.status === 401 || response.status === 403
+          ? `Jenkins denied the request (${status}). ` +
+            'Check your Jenkins credentials and build permissions.'
+          : `Jenkins returned ${status}. Check the build page for details: ${build.jobUrl}`;
         cli.stopSpinner(
-          `Failed to resume PR CI: ${response.status} ${response.statusText}`,
+          `${failureMessage}: ${reason}`,
           cli.SPINNER_STATUS.FAILED);
         return false;
       }
       cli.stopSpinner('PR CI job successfully resumed');
     } catch (err) {
       debuglog(err);
-      cli.stopSpinner('Failed to resume CI', cli.SPINNER_STATUS.FAILED);
+      cli.stopSpinner(`${failureMessage}: ${err.message}`, cli.SPINNER_STATUS.FAILED);
       return false;
     }
     return true;

package/lib/ci/run_ci.js

@@ -10,6 +10,12 @@ import PRData from '../pr_data.js';
 import { debuglog } from '../verbosity.js';
 import PRChecker from '../pr_checker.js';
 import { PRBuild } from './build-types/pr_build.js';
+import { getCIActionAdvice } from './ci_utils.js';
+import {
+  findResumableBuild,
+  getApprovedSHA,
+  RESUME_TREE
+} from './resumable_build.js';
 
 export const CI_CRUMB_URL = `https://${CI_DOMAIN}/crumbIssuer/api/json`;
 const CI_PR_NAME = CI_TYPES.get(CI_TYPES_KEYS.PR).jobName;
@@ -94,12 +100,12 @@ export class RunPRJob {
     if (checkForDuplicates) {
       await this.prData.getComments();
       const { jobid, link } = new JobParser(this.prData.comments).parse().get('PR') ?? {};
-      let actions;
+      let buildData;
       try {
-        ({ actions } = jobid
-          ? (await new PRBuild(cli, request, jobid, undefined, 'actions[parameters[name,value]]')
-              .getBuildData())
-          : {});
+        if (jobid) {
+          buildData = await new PRBuild(cli, request, jobid, undefined, RESUME_TREE)
+            .getBuildData();
+        }
       } catch (err) {
         // Jenkins may no longer have the build (e.g. the record was lost) or
         // may answer with an HTML error page instead of JSON. Do not let that
@@ -108,11 +114,35 @@ export class RunPRJob {
           cli.SPINNER_STATUS.WARN);
         cli.warn('Skipping the duplicate CI check');
       }
-      const { parameters } = actions?.find(a => 'parameters' in a) ?? {};
-      if (parameters?.find(c => c.name === 'COMMIT_SHA_CHECK')?.value === certifySafe) {
+      const matchingSHA = buildData?.actions?.some(action =>
+        action.parameters?.some(parameter =>
+          parameter.name === 'COMMIT_SHA_CHECK' && parameter.value === certifySafe));
+      if (matchingSHA) {
         cli.info('Existing CI run found: ' + link);
-        cli.error('Refusing to start a potentially duplicate CI job. Use the ' +
-          '"Resume build" button in the Jenkins UI, or start a new CI manually.');
+        let advice = 'Check the existing CI run in Jenkins before retrying.';
+        if (getApprovedSHA(buildData) === certifySafe && buildData.building === false &&
+            ['FAILURE', 'ABORTED'].includes(buildData.result)) {
+          try {
+            const { build } = await findResumableBuild(cli, request, {
+              jobid,
+              owner: this.owner,
+              repo: this.repo,
+              prid: this.prid
+            }, buildData);
+            advice = getCIActionAdvice(this, build ? 'resume' : 'run');
+          } catch (err) {
+            cli.error(`Could not check whether existing CI run ${link} can be resumed: ` +
+              err.message);
+            cli.error('Refusing to start a potentially duplicate CI job. ' +
+              'Retry after checking Jenkins access.');
+            return false;
+          }
+        } else if (buildData.building === true) {
+          advice = 'The existing CI run is still in progress.';
+        } else if (buildData.result === 'SUCCESS') {
+          advice = 'CI has already succeeded for this commit.';
+        }
+        cli.error(`Refusing to start a potentially duplicate CI job. ${advice}`);
         return false;
       }
     }