Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

29.8 KB
Raw Blame
/**
 * Every test here is about a guard that must NOT fire a retry. The retry
 * itself is one API call; the risk is re-running the suite on a genuine red,
 * looping forever, or fighting a legitimate `cancel-in-progress` supersession.
 *
 * The API-base and repository validation live in lib/githubActionsApi.test.js,
 * shared with scripts/ci-gate-report.js.
 */
import { readFileSync } from 'fs';
import { dirname, join } from 'path';
import { fileURLToPath } from 'url';

import { describe, expect, it, vi } from 'vitest';

import {
  MAX_RUNTIME_MS,
  RETRY_DELAY_MS,
  retryCancelledCiRun,
  retryTargetFromEnv,
} from './ci-retry-cancelled-run.js';
import { workflowJobs } from './lib/workflowJobs.js';

const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
const RECOVERY_WORKFLOW = readFileSync(
  join(REPO_ROOT, '.github/workflows/ci-cancel-recovery.yml'),
  'utf8',
);

const BASE_ENV = {
  GITHUB_REPOSITORY: 'example-owner/example-repo',
  GITHUB_TOKEN: 'token-value',
  CI_RUN_ID: '4242',
  CI_RUN_ATTEMPT: '1',
  CI_RUN_NUMBER: '900',
  CI_WORKFLOW_ID: '77',
  CI_RUN_EVENT: 'pull_request',
  CI_RUN_CONCLUSION: 'cancelled',
  CI_RUN_HEAD_BRANCH: 'claim/issue-1',
  CI_RUN_HEAD_REPOSITORY_ID: '555',
  CI_RUN_HEAD_SHA: 'c'.repeat(40),
};

const json = (body) => ({ ok: true, status: 200, json: async () => body });

/**
 * A fetch stub routed by URL shape. `jobs`/`runs` default to the clean
 * external-cancel case so each test overrides only what it is about.
 */
function stubFetch({
  jobs = [], runs = [], annotations = {}, rerunStatus = 201, checkStatus = 201, jobsStatus = 200, live,
} = {}) {
  const calls = [];
  const impl = vi.fn(async (url, init = {}) => {
    calls.push({ url, method: init.method || 'GET', body: init.body });
    // The ATTEMPT-scoped path, deliberately: /runs/{id}/jobs returns the
    // LATEST attempt's jobs, which is the wrong set after a human re-run.
    if (url.includes('/attempts/1/jobs?')) {
      if (jobsStatus >= 300) return { ok: false, status: jobsStatus };
      return json({ total_count: jobs.length, jobs });
    }
    if (url.includes('/runs?')) {
      return json({
        total_count: runs.length,
        workflow_runs: runs.map((r) => ({ head_repository: { id: 555 }, ...r })),
      });
    }
    const annotated = url.match(/\/check-runs\/(\d+)\/annotations\?/);
    if (annotated) return json(annotations[annotated[1]] || []);
    if (url.endsWith('/rerun')) return { ok: rerunStatus < 300, status: rerunStatus };
    if (url.endsWith('/check-runs')) return { ok: checkStatus < 300, status: checkStatus };
    if (/\/actions\/runs\/\d+$/.test(url)) {
      return json({ run_attempt: 1, status: 'completed', conclusion: 'cancelled', ...live });
    }
    throw new Error(`unexpected url ${url}`);
  });
  return {
    impl,
    calls,
    rerunRequested: () => calls.some((c) => c.url.endsWith('/rerun')),
    /** The parsed check-run body, or null when none was published. */
    publishedCheck: () => {
      const call = calls.find((c) => c.url.endsWith('/check-runs'));
      return call ? JSON.parse(call.body) : null;
    },
  };
}

const silent = { log: () => {}, error: () => {} };
const noSummary = () => {};
/** No suite ever sleeps — the production wait is always replaced. */
const noWait = async () => {};
/** ...and `waits` records what the delay WOULD have been. */
const fakeClock = () => {
  const waits = [];
  return { waits, wait: async (ms) => { waits.push(ms); } };
};
const invoke = (options) => retryCancelledCiRun({
  logger: silent, writeSummary: noSummary, wait: noWait, ...options,
});
const run = (env, fetchStub) => invoke({ env, fetchImpl: fetchStub.impl });

describe('retryTargetFromEnv', () => {
  it('accepts a well-formed workflow_run environment', () => {
    const target = retryTargetFromEnv(BASE_ENV);
    expect(target).toMatchObject({ runId: '4242', runAttempt: 1, runNumber: 900, workflowId: '77' });
    expect(target.repoPath).toBe('https://api.github.com/repos/example-owner/example-repo');
  });

  it.each([
    ['a non-numeric run id', { CI_RUN_ID: '4242; rm -rf /' }],
    ['a missing token', { GITHUB_TOKEN: '' }],
    ['a malformed repository', { GITHUB_REPOSITORY: 'example-owner' }],
    ['an empty head branch', { CI_RUN_HEAD_BRANCH: '' }],
    ['a non-https API base', { GITHUB_API_URL: 'http://api.example.com' }],
  ])('rejects %s', (_label, override) => {
    expect(retryTargetFromEnv({ ...BASE_ENV, ...override })).toBeNull();
  });
});

describe('retryCancelledCiRun guards', () => {
  it('re-dispatches a cancelled pull-request run with no failing job and no successor', async () => {
    const fetchStub = stubFetch({
      jobs: [{ id: 1, name: 'DB tests', conclusion: 'success' }, { id: 2, name: 'Client', conclusion: 'cancelled' }],
      runs: [{ id: 4242, run_number: 900 }],
    });

    await expect(run(BASE_ENV, fetchStub)).resolves.toMatchObject({ outcome: 'requested' });
    expect(fetchStub.rerunRequested()).toBe(true);
  });

  it('never retries a run that is already attempt 2 — the retry budget', async () => {
    const fetchStub = stubFetch();
    await expect(run({ ...BASE_ENV, CI_RUN_ATTEMPT: '2' }, fetchStub))
      .resolves.toMatchObject({ outcome: 'skipped', reason: 'retry-budget-exhausted' });
    // The budget guard short-circuits before every lookup. The only call it may
    // make is the neutral check that explains the skip on the pull request.
    expect(fetchStub.calls.map((c) => c.url).filter((url) => !url.endsWith('/check-runs'))).toEqual([]);
  });

  it('never retries a legitimate cancel-in-progress supersession', async () => {
    const fetchStub = stubFetch({ runs: [{ id: 5000, run_number: 901 }, { id: 4242, run_number: 900 }] });
    await expect(run(BASE_ENV, fetchStub))
      .resolves.toMatchObject({ outcome: 'skipped', reason: 'superseded' });
    expect(fetchStub.rerunRequested()).toBe(false);
  });

  it.each(['failure', 'timed_out'])(
    'never retries a run whose job concluded %s',
    async (conclusion) => {
      // A run cancelled while one job was already red reads `cancelled`.
      // Retrying that re-runs the whole suite on a red tree.
      const fetchStub = stubFetch({
        jobs: [{ name: 'Server tests', conclusion }, { name: 'Client', conclusion: 'cancelled' }],
      });
      await expect(run(BASE_ENV, fetchStub))
        .resolves.toMatchObject({ outcome: 'skipped', reason: 'job-failed' });
      expect(fetchStub.rerunRequested()).toBe(false);
    },
  );

  it('never retries a run whose job hit its own timeout-minutes, which GitHub reports as cancelled', async () => {
    // The jobs API gives a timed-out job conclusion `cancelled` and leaves its
    // running step unconcluded; only the check-run annotation names the
    // timeout (#11910). A re-run would just time out again.
    const fetchStub = stubFetch({
      jobs: [
        { id: 7, name: 'DB tests', conclusion: 'cancelled', steps: [{ conclusion: 'success' }, { conclusion: null }] },
        { id: 8, name: 'Client', conclusion: 'cancelled' },
      ],
      annotations: {
        7: [{ annotation_level: 'failure', message: 'The job has exceeded the maximum execution time of 20m0s' }],
        8: [{ annotation_level: 'failure', message: 'The operation was canceled.' }],
      },
    });
    await expect(run(BASE_ENV, fetchStub))
      .resolves.toMatchObject({ outcome: 'skipped', reason: 'job-timed-out', phase: 'before-wait' });
    expect(fetchStub.rerunRequested()).toBe(false);
    const { summary } = fetchStub.publishedCheck().output;
    expect(summary).toContain('reason: `job-timed-out`');
    expect(summary).toContain('`DB tests` exceeded its timeout of `20m0s`');
    expect(summary).not.toContain('`Client`');
  });

  it('retries a job whose STEP failed but whose conclusion reads cancelled', async () => {
    // A cancel can land while the failing job is still in its post-steps, and
    // GitHub then records that job as `cancelled`. Trusting the job conclusion
    // alone would re-run a genuinely red tree.
    const fetchStub = stubFetch({
      jobs: [{
        name: 'Server tests',
        conclusion: 'cancelled',
        steps: [{ conclusion: 'success' }, { conclusion: 'failure' }],
      }],
    });
    await expect(run(BASE_ENV, fetchStub))
      .resolves.toMatchObject({ outcome: 'skipped', reason: 'job-failed' });
    expect(fetchStub.rerunRequested()).toBe(false);
  });

  it('is not suppressed by an OLDER sibling run', async () => {
    // The supersession guard must compare, not merely detect a sibling.
    const fetchStub = stubFetch({ runs: [{ id: 4000, run_number: 899 }, { id: 4242, run_number: 900 }] });
    await expect(run(BASE_ENV, fetchStub)).resolves.toMatchObject({ outcome: 'requested' });
  });

  it('is not suppressed by a same-named branch on a different fork', async () => {
    // `?branch=` matches head_branch alone, so two forks pushing `patch-1`
    // share a listing. Only a missed retry, but it is avoidable.
    const fetchStub = stubFetch({
      runs: [{ id: 9001, run_number: 950, head_repository: { id: 999 } }],
    });
    await expect(run(BASE_ENV, fetchStub)).resolves.toMatchObject({ outcome: 'requested' });
  });

  it('reads a job listing that spans two pages before deciding', async () => {
    // A failing job on page 2 must still block the retry.
    const pages = {
      1: { total_count: 2, jobs: [{ name: 'Client', conclusion: 'cancelled' }] },
      2: { total_count: 2, jobs: [{ name: 'Server tests', conclusion: 'failure' }] },
    };
    const impl = vi.fn(async (url) => {
      if (url.includes('/jobs?')) return json(pages[new URL(url).searchParams.get('page')]);
      return json({ workflow_runs: [] });
    });
    await expect(invoke({ env: BASE_ENV, fetchImpl: impl }))
      .resolves.toMatchObject({ outcome: 'skipped', reason: 'job-failed' });
  });

  it('never lets a pull-request job name forge an Actions workflow command', async () => {
    // `job.name` comes from the PR's own workflow file, and Actions parses a
    // line starting with `::` as a command.
    const logged = [];
    const fetchStub = stubFetch({
      jobs: [{ name: 'Server\n::add-mask::secret', conclusion: 'failure' }],
    });
    await invoke({
      env: BASE_ENV,
      fetchImpl: fetchStub.impl,
      logger: { log: (l) => logged.push(l), error: (l) => logged.push(l) },
    });

    const text = logged.join('\n');
    expect(text).toContain('Server');
    expect(text).not.toContain('::add-mask::');
    expect(text.split('\n').some((line) => line.startsWith('::'))).toBe(false);
  });

  it.each([
    ['a run that did not end cancelled', { CI_RUN_CONCLUSION: 'failure' }, 'not-cancelled'],
    ['a nightly or dispatched run', { CI_RUN_EVENT: 'schedule' }, 'not-a-pull-request'],
    ['a malformed environment', { CI_RUN_ID: 'not-a-number' }, 'invalid-environment'],
  ])('skips %s', async (_label, override, reason) => {
    const fetchStub = stubFetch();
    await expect(run({ ...BASE_ENV, ...override }, fetchStub))
      .resolves.toMatchObject({ outcome: 'skipped', reason });
    expect(fetchStub.impl).not.toHaveBeenCalled();
  });

  it.each([
    ['a human already re-ran it', { run_attempt: 2 }],
    ['it is running again', { status: 'in_progress', conclusion: '' }],
    ['the re-run has since succeeded', { conclusion: 'success' }],
  ])('never spends the budget when the live run says %s', async (_label, live) => {
    // The workflow_run payload is a snapshot; this job can start long after it.
    const fetchStub = stubFetch({ live });
    await expect(run(BASE_ENV, fetchStub))
      .resolves.toMatchObject({ outcome: 'skipped', reason: 'run-state-moved-on' });
    expect(fetchStub.rerunRequested()).toBe(false);
  });

  it('does not retry when the live run state cannot be read', async () => {
    const impl = vi.fn(async (url) => {
      if (url.includes('/jobs?')) return json({ total_count: 0, jobs: [] });
      if (url.includes('/runs?')) return json({ workflow_runs: [] });
      return { ok: false, status: 500 };
    });
    await expect(invoke({ env: BASE_ENV, fetchImpl: impl }))
      .resolves.toMatchObject({ outcome: 'unavailable', reason: 'run-state-unavailable' });
    expect(impl.mock.calls.some(([url]) => url.endsWith('/rerun'))).toBe(false);
  });

  it('encodes the branch name into the query, never into a path', async () => {
    // The head branch is attacker-controlled on a fork PR.
    const fetchStub = stubFetch();
    await run({ ...BASE_ENV, CI_RUN_HEAD_BRANCH: 'feat/../../evil?x=1' }, fetchStub);

    const listing = fetchStub.calls.find((c) => c.url.includes('/runs?'));
    expect(listing.url).toContain('branch=feat%2F..%2F..%2Fevil%3Fx%3D1');
    expect(listing.url).not.toContain('/evil');
  });

  it('does not retry when the job listing cannot be read', async () => {
    // "We could not see the jobs" must never read as "no job failed".
    const impl = vi.fn(async (url) => (url.includes('/jobs?')
      ? { ok: false, status: 502 }
      : json({ workflow_runs: [] })));
    await expect(invoke({ env: BASE_ENV, fetchImpl: impl }))
      .resolves.toMatchObject({ outcome: 'unavailable', reason: 'jobs-unavailable' });
    expect(impl.mock.calls.some(([url]) => url.endsWith('/rerun'))).toBe(false);
  });

  it('does not retry when the job listing is truncated', async () => {
    // total_count outruns the page: a failing job could be on the page we
    // never received.
    const impl = vi.fn(async (url) => (url.includes('/jobs?')
      ? json({ total_count: 40, jobs: [] })
      : json({ workflow_runs: [] })));
    await expect(invoke({ env: BASE_ENV, fetchImpl: impl }))
      .resolves.toMatchObject({ outcome: 'unavailable', reason: 'jobs-unavailable' });
  });

  it('does not retry when the sibling-run listing cannot be read', async () => {
    const impl = vi.fn(async (url) => {
      if (url.includes('/runs?')) return { ok: false, status: 403 };
      if (url.includes('/jobs?')) return json({ total_count: 0, jobs: [] });
      return json({ run_attempt: 1, status: 'completed', conclusion: 'cancelled' });
    });
    await expect(invoke({ env: BASE_ENV, fetchImpl: impl }))
      .resolves.toMatchObject({ outcome: 'unavailable', reason: 'sibling-runs-unavailable' });
  });

  it('survives a network failure without throwing', async () => {
    const impl = vi.fn(async () => { throw new Error('socket hang up'); });
    await expect(invoke({ env: BASE_ENV, fetchImpl: impl }))
      .resolves.toMatchObject({ outcome: 'unavailable' });
  });

  it('reports a rejected rerun rather than claiming success', async () => {
    const fetchStub = stubFetch({ rerunStatus: 403 });
    await expect(run(BASE_ENV, fetchStub))
      .resolves.toMatchObject({ outcome: 'unavailable', reason: 'rerun-rejected', status: 403 });
  });

  it('records why it did not retry on the recovery run summary', async () => {
    // "Why wasn't my run retried?" has to be answerable without reading logs,
    // and the summary must never echo the attacker-controlled branch name.
    const written = [];
    const fetchStub = stubFetch({ runs: [{ id: 5000, run_number: 901 }] });
    await invoke({
      env: { ...BASE_ENV, CI_RUN_HEAD_BRANCH: 'evil <img src=x>' },
      fetchImpl: fetchStub.impl,
      writeSummary: (markdown) => written.push(markdown),
    });

    expect(written).toHaveLength(1);
    expect(written[0]).toContain('reason: superseded');
    expect(written[0]).toContain('run: 4242');
    expect(written[0]).not.toContain('evil');
  });
});

describe('the wait before re-dispatching', () => {
  // The cancel this recovers from is caused by a saturated queue, so the
  // one-retry budget is worth least at the instant the event arrives (7439).
  // Every test injects the clock — a real five-minute sleep in CI is not a
  // test, it is an outage.

  it('waits the full delay, and re-dispatches only afterwards', async () => {
    const fetchStub = stubFetch({ runs: [{ id: 4242, run_number: 900 }] });
    const seenBeforeWait = [];
    const clock = fakeClock();

    await expect(invoke({
      env: BASE_ENV,
      fetchImpl: fetchStub.impl,
      wait: async (ms) => {
        seenBeforeWait.push(...fetchStub.calls.map((call) => call.url));
        await clock.wait(ms);
      },
    })).resolves.toMatchObject({ outcome: 'requested', phase: 'after-wait' });

    expect(clock.waits).toEqual([RETRY_DELAY_MS]);
    expect(seenBeforeWait.some((url) => url.endsWith('/rerun'))).toBe(false);
  });

  it('lets a supersession that lands DURING the wait win', async () => {
    // This is the re-check the delay exists for: the pre-wait listing said
    // there was no successor, and a push five minutes later must still
    // cancel the retry rather than re-running code nobody is waiting on.
    let pushedDuringWait = false;
    const impl = vi.fn(async (url) => {
      if (url.includes('/jobs?')) return json({ total_count: 0, jobs: [] });
      if (url.includes('/runs?')) {
        return json({
          workflow_runs: pushedDuringWait
            ? [{ id: 5000, run_number: 901, head_repository: { id: 555 } }]
            : [],
        });
      }
      return json({ run_attempt: 1, status: 'completed', conclusion: 'cancelled' });
    });

    await expect(invoke({
      env: BASE_ENV,
      fetchImpl: impl,
      wait: async () => { pushedDuringWait = true; },
    })).resolves.toMatchObject({ outcome: 'skipped', reason: 'superseded', phase: 'after-wait' });
    expect(impl.mock.calls.some(([url]) => url.endsWith('/rerun'))).toBe(false);
  });

  it('lets a human re-run that lands DURING the wait keep the budget', async () => {
    let rerunByHuman = false;
    const impl = vi.fn(async (url) => {
      if (url.includes('/jobs?')) return json({ total_count: 0, jobs: [] });
      if (url.includes('/runs?')) return json({ workflow_runs: [] });
      return json({
        run_attempt: rerunByHuman ? 2 : 1, status: 'completed', conclusion: 'cancelled',
      });
    });

    await expect(invoke({
      env: BASE_ENV,
      fetchImpl: impl,
      wait: async () => { rerunByHuman = true; },
    })).resolves.toMatchObject({ outcome: 'skipped', reason: 'run-state-moved-on', phase: 'after-wait' });
    expect(impl.mock.calls.some(([url]) => url.endsWith('/rerun'))).toBe(false);
  });

  it('does not hold a runner idle for a run that is already ineligible', async () => {
    // Skipping before the wait is what keeps the delay cheap: a genuinely red
    // run costs one API call, not five minutes of occupancy.
    const clock = fakeClock();
    await expect(invoke({
      env: BASE_ENV,
      fetchImpl: stubFetch({ jobs: [{ name: 'Server tests', conclusion: 'failure' }] }).impl,
      wait: clock.wait,
    })).resolves.toMatchObject({ outcome: 'skipped', reason: 'job-failed', phase: 'before-wait' });
    expect(clock.waits).toEqual([]);
  });

  it('does not forfeit the retry when a PRE-wait lookup merely fails', async () => {
    // The pre-wait pass is an optimization, not a verdict: a 5xx there is not
    // evidence of ineligibility, and a saturated GitHub — the exact condition
    // this workflow exists for — is when one is likeliest. Skipping on it
    // would lose the very case the delay was added to win.
    let apiRecovered = false;
    const impl = vi.fn(async (url) => {
      if (!apiRecovered) return { ok: false, status: 502 };
      if (url.includes('/jobs?')) return json({ total_count: 0, jobs: [] });
      if (url.includes('/runs?')) return json({ workflow_runs: [] });
      if (url.endsWith('/rerun')) return { ok: true, status: 201 };
      return json({ run_attempt: 1, status: 'completed', conclusion: 'cancelled' });
    });

    await expect(invoke({
      env: BASE_ENV,
      fetchImpl: impl,
      wait: async () => { apiRecovered = true; },
    })).resolves.toMatchObject({ outcome: 'requested', phase: 'after-wait' });
    expect(impl.mock.calls.some(([url]) => url.endsWith('/rerun'))).toBe(true);
  });

  it('still fails CLOSED when the POST-wait lookup cannot be read', async () => {
    // The other half of the rule above: falling through a pre-wait failure may
    // only ever cost time. The pass the dispatch is actually made on must
    // still refuse to treat an unreadable listing as "no job failed".
    const impl = vi.fn(async () => ({ ok: false, status: 502 }));
    await expect(invoke({ env: BASE_ENV, fetchImpl: impl }))
      .resolves.toMatchObject({ outcome: 'unavailable', reason: 'jobs-unavailable', phase: 'after-wait' });
    expect(impl.mock.calls.some(([url]) => url.endsWith('/rerun'))).toBe(false);
  });

  it('catches a job whose failure only settles DURING the wait', async () => {
    // A cancel can land while the failing job is still in its post-steps, so
    // the pre-wait listing can legitimately read clean. The post-wait re-read is the more reliable one, and must block the retry.
    let stepsSettled = false;
    const impl = vi.fn(async (url) => {
      if (url.includes('/jobs?')) {
        return json({
          total_count: 1,
          jobs: [{
            name: 'Server tests',
            conclusion: 'cancelled',
            steps: stepsSettled ? [{ conclusion: 'failure' }] : [{ conclusion: 'success' }],
          }],
        });
      }
      if (url.includes('/runs?')) return json({ workflow_runs: [] });
      return json({ run_attempt: 1, status: 'completed', conclusion: 'cancelled' });
    });

    await expect(invoke({
      env: BASE_ENV,
      fetchImpl: impl,
      wait: async () => { stepsSettled = true; },
    })).resolves.toMatchObject({ outcome: 'skipped', reason: 'job-failed', phase: 'after-wait' });
    expect(impl.mock.calls.some(([url]) => url.endsWith('/rerun'))).toBe(false);
  });

  it('records the phase and the delay it used on the run summary', async () => {
    // The tuning evidence this issue asks for: a summary written under a
    // since-changed constant must still say which delay produced it.
    const written = [];
    await invoke({
      env: BASE_ENV,
      fetchImpl: stubFetch({ runs: [{ id: 4242, run_number: 900 }] }).impl,
      writeSummary: (markdown) => written.push(markdown),
    });
    expect(written[0]).toContain('phase: after-wait');
    expect(written[0]).toContain(`delay: ${RETRY_DELAY_MS / 1000}s`);
  });
});

describe('the neutral check run published back onto the pull request', () => {
  // `if: always()` on the CI gate defeats an upstream job failure, not a
  // cancellation of the whole run, so an externally cancelled run leaves a bare
  // red `CI Gate` with no message. This recovery run is a separate run and
  // survives, which makes it the only layer that can explain one (#7438).

  it('names the reason the cancelled run was not retried, on the cancelled head sha', async () => {
    const fetchStub = stubFetch({ runs: [{ id: 5000, run_number: 901 }] });
    await run(BASE_ENV, fetchStub);

    const check = fetchStub.publishedCheck();
    expect(check).toMatchObject({
      name: 'CI cancel recovery',
      head_sha: BASE_ENV.CI_RUN_HEAD_SHA,
      status: 'completed',
      conclusion: 'neutral',
    });
    // The same fixed reason code the step summary renders, so a reader of
    // either surface sees the same verdict.
    expect(check.output.summary).toContain('reason: `superseded`');
    expect(check.output.summary).toContain('newer CI run started');
  });

  it.each([
    ['a re-dispatch', {}, {}],
    ['a supersession', { runs: [{ id: 5000, run_number: 901 }] }, {}],
    ['a real job failure', { jobs: [{ name: 'Server tests', conclusion: 'failure' }] }, {}],
    ['an exhausted retry budget', {}, { CI_RUN_ATTEMPT: '2' }],
    ['a rejected re-dispatch', { rerunStatus: 403 }, {}],
    ['an unreadable job listing', { jobsStatus: 502 }, {}],
  ])('stays neutral for %s — it explains the gate, it never becomes a second one', async (_label, options, envOverride) => {
    // `failure` would block a merge that branch protection (which requires
    // `CI Gate` alone) allows; `success` would read as a passing gate, and
    // server/services/prWatcher.js already counts NEUTRAL as green.
    const fetchStub = stubFetch(options);
    await run({ ...BASE_ENV, ...envOverride }, fetchStub);

    expect(fetchStub.publishedCheck()?.conclusion).toBe('neutral');
  });

  it('never echoes the attacker-controlled branch name into the check', async () => {
    // The check body is rendered from fixed reason codes only, for the same
    // reason `safeJobName` exists — a fork PR names its own branch.
    const fetchStub = stubFetch({ runs: [{ id: 5000, run_number: 901 }] });
    await run({ ...BASE_ENV, CI_RUN_HEAD_BRANCH: 'evil <img src=x>' }, fetchStub);

    expect(JSON.stringify(fetchStub.publishedCheck())).not.toContain('evil');
  });

  it.each([
    ['a run that concluded normally', { CI_RUN_CONCLUSION: 'success' }],
    ['a nightly or dispatched run', { CI_RUN_EVENT: 'schedule' }],
  ])('publishes nothing for %s', async (_label, override) => {
    // A green PR must not collect an unprompted check, and a non-PR run has no
    // pull request to annotate at all.
    const fetchStub = stubFetch();
    await run({ ...BASE_ENV, ...override }, fetchStub);

    expect(fetchStub.publishedCheck()).toBeNull();
  });

  it('publishes nothing when the head sha is not a commit sha', async () => {
    const fetchStub = stubFetch({ runs: [{ id: 5000, run_number: 901 }] });
    await run({ ...BASE_ENV, CI_RUN_HEAD_SHA: 'not-a-sha' }, fetchStub);

    expect(fetchStub.publishedCheck()).toBeNull();
  });

  it.each([
    ['GitHub rejects it', { checkStatus: 422 }],
    ['the request never completes', { checkStatus: 'throw' }],
  ])('swallows a publishing failure when %s — the verdict still stands', async (_label, options) => {
    // Best-effort, always: the recovery job must never turn red on top of an
    // already-cancelled run.
    const fetchStub = options.checkStatus === 'throw'
      ? {
        impl: vi.fn(async (url) => {
          if (url.endsWith('/check-runs')) throw new Error('socket hang up');
          if (url.includes('/jobs?')) return json({ total_count: 0, jobs: [] });
          if (url.includes('/runs?')) return json({ workflow_runs: [{ id: 5000, run_number: 901 }] });
          return json({ run_attempt: 1, status: 'completed', conclusion: 'cancelled' });
        }),
      }
      : stubFetch({ ...options, runs: [{ id: 5000, run_number: 901 }] });

    await expect(invoke({ env: BASE_ENV, fetchImpl: fetchStub.impl }))
      .resolves.toMatchObject({ outcome: 'skipped', reason: 'superseded' });
  });
});

describe('ci-cancel-recovery.yml wiring', () => {
  const jobs = workflowJobs(RECOVERY_WORKFLOW);

  it('gives the recovery job a timeout that outlives the wait AND both guard passes', () => {
    // The job idles for RETRY_DELAY_MS and then re-reads every guard, so the
    // bound that matters is MAX_RUNTIME_MS, not the delay alone — a timeout
    // between the two would kill a slow run mid-wait and silently turn
    // 'retried late' into 'never retried at all'. Asserting the derived bound
    // is what makes raising the delay fail here instead of eating the margin.
    const timeoutMinutes = Number(jobs.retry.match(/^\s+timeout-minutes:\s*(\d+)\s*$/m)?.[1]);
    expect(Number.isFinite(timeoutMinutes)).toBe(true);
    expect(timeoutMinutes * 60_000).toBeGreaterThan(MAX_RUNTIME_MS);
  });

  it('triggers on a completed CI run and nothing else', () => {
    expect(RECOVERY_WORKFLOW).toMatch(/on:\n {2}workflow_run:\n {4}workflows: \[CI\]\n {4}types: \[completed\]/);
    // A `pull_request` trigger here would run with the PR's own code.
    expect(RECOVERY_WORKFLOW).not.toMatch(/^\s{2}pull_request:/m);
  });

  it('pre-filters on the same three cheap guards the script re-checks', () => {
    for (const guard of [
      "github.event.workflow_run.conclusion == 'cancelled'",
      "github.event.workflow_run.event == 'pull_request'",
      'github.event.workflow_run.run_attempt == 1',
    ]) {
      expect(jobs.retry).toContain(guard);
    }
  });

  it('passes the run identity the script validates, each from the right field', () => {
    // The exact expression, not just the prefix: mapping CI_RUN_NUMBER to
    // `.id` would be a silently wrong supersession comparison.
    const FIELDS = {
      CI_RUN_ID: 'id',
      CI_RUN_ATTEMPT: 'run_attempt',
      CI_RUN_NUMBER: 'run_number',
      CI_WORKFLOW_ID: 'workflow_id',
      CI_RUN_EVENT: 'event',
      CI_RUN_CONCLUSION: 'conclusion',
      CI_RUN_HEAD_BRANCH: 'head_branch',
      CI_RUN_HEAD_REPOSITORY_ID: 'head_repository.id',
      CI_RUN_HEAD_SHA: 'head_sha',
    };
    for (const [key, field] of Object.entries(FIELDS)) {
      expect(jobs.retry, key).toContain(`${key}: \${{ github.event.workflow_run.${field} }}`);
    }
  });

  it('never checks out or builds the pull request head with its writable token', () => {
    // workflow_run runs the default-branch copy; checking out the PR head here
    // would hand `actions: write` to code from a fork.
    expect(jobs.retry).toContain('persist-credentials: false');
    expect(jobs.retry).not.toMatch(/ref:\s*\$\{\{/);
    // `run:` lines only — a prose comment may mention npm, a step may not.
    const commands = jobs.retry.split('\n').filter((line) => /^\s+run:/.test(line));
    expect(commands).toEqual(['        run: node scripts/ci-retry-cancelled-run.js']);
  });

  it('re-dispatches from a sparse checkout with no dependency install', () => {
    // Latency is the whole point of this workflow: a full-tree checkout plus
    // setup-node would roughly double its time-to-re-dispatch, and the script
    // imports Node builtins only.
    expect(jobs.retry).toContain('sparse-checkout: scripts');
    expect(jobs.retry).not.toContain('actions/setup-node');
  });

  it('grants write only to actions and checks, and never cancels its own recovery', () => {
    expect(RECOVERY_WORKFLOW).toMatch(/permissions:\n {2}contents: read\n {2}actions: write\n/);
    // The check-run publisher needs this grant, and nothing wider: a
    // `contents: write` or `pull-requests: write` token on a workflow_run
    // workflow is what turns an informational job into a push surface.
    expect(RECOVERY_WORKFLOW).toMatch(/^ {2}checks: write$/m);
    expect(RECOVERY_WORKFLOW).not.toMatch(/^ {2}(contents|packages|id-token|pull-requests|issues|deployments): write$/m);
    expect(RECOVERY_WORKFLOW).toContain('cancel-in-progress: false');
  });
});