sequant 2.9.0 → 2.11.0

package/dist/src/lib/merge-check/command-result.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Normalized spawn results and never-empty failure reasons (#803)
+ *
+ * Shared by every merge-check module that reports on a spawned command. The
+ * motivating defect: a failure reason built from `stderr` alone renders as
+ * `... failed: ` with nothing after it whenever the command wrote its
+ * diagnostics to stdout — which is where vitest, tsc, and npm put theirs.
+ */
+import type { SpawnSyncReturns } from "child_process";
+/** Max characters of captured output included in a failure message. */
+export declare const REASON_MAX_CHARS = 500;
+/**
+ * Outcome of a spawned command, normalized across success, non-zero exit,
+ * signal termination, and spawn failure.
+ */
+export interface CommandResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    status: number | null;
+    signal: string | null;
+    spawnError?: string;
+}
+/**
+ * Normalize a raw `spawnSync` return into a {@link CommandResult}.
+ */
+export declare function toCommandResult(result: SpawnSyncReturns<string>): CommandResult;
+/**
+ * Produce a human-readable, never-empty reason for a failed command.
+ *
+ * Falls through: stderr → stdout tail → spawn error → signal → exit code. The
+ * stdout *tail* is used because test runners put the failure summary last,
+ * while the stderr *head* is kept because the first error is usually the
+ * proximate cause.
+ */
+export declare function resolveFailureReason(result: CommandResult): string;

package/dist/src/lib/merge-check/command-result.js

@@ -0,0 +1,56 @@
+/**
+ * Normalized spawn results and never-empty failure reasons (#803)
+ *
+ * Shared by every merge-check module that reports on a spawned command. The
+ * motivating defect: a failure reason built from `stderr` alone renders as
+ * `... failed: ` with nothing after it whenever the command wrote its
+ * diagnostics to stdout — which is where vitest, tsc, and npm put theirs.
+ */
+/** Max characters of captured output included in a failure message. */
+export const REASON_MAX_CHARS = 500;
+/**
+ * Normalize a raw `spawnSync` return into a {@link CommandResult}.
+ */
+export function toCommandResult(result) {
+    return {
+        ok: result.status === 0,
+        stdout: result.stdout?.trim() ?? "",
+        stderr: result.stderr?.trim() ?? "",
+        status: result.status ?? null,
+        signal: result.signal ?? null,
+        spawnError: result.error?.message,
+    };
+}
+/**
+ * Produce a human-readable, never-empty reason for a failed command.
+ *
+ * Falls through: stderr → stdout tail → spawn error → signal → exit code. The
+ * stdout *tail* is used because test runners put the failure summary last,
+ * while the stderr *head* is kept because the first error is usually the
+ * proximate cause.
+ */
+export function resolveFailureReason(result) {
+    if (result.stderr) {
+        return truncateHead(result.stderr);
+    }
+    if (result.stdout) {
+        return truncateTail(result.stdout);
+    }
+    if (result.spawnError) {
+        return result.spawnError;
+    }
+    if (result.signal) {
+        return `no output; killed by signal ${result.signal} (likely a timeout)`;
+    }
+    return `no output; exited with code ${result.status ?? "unknown"}`;
+}
+function truncateHead(text) {
+    return text.length > REASON_MAX_CHARS
+        ? `${text.slice(0, REASON_MAX_CHARS)}…`
+        : text;
+}
+function truncateTail(text) {
+    return text.length > REASON_MAX_CHARS
+        ? `…${text.slice(-REASON_MAX_CHARS)}`
+        : text;
+}

package/dist/src/lib/merge-check/index.d.ts

@@ -7,6 +7,10 @@
 import { type RunLog } from "../workflow/run-log-schema.js";
 import type { BranchInfo, CheckResult, MergeCommandOptions, MergeReport } from "./types.js";
 import { formatReportMarkdown, formatBranchReportMarkdown, postReportToGitHub } from "./report.js";
+/**
+ * Resolve log directory path
+ */
+export declare function resolveLogDir(customPath?: string): string;
 /**
  * Find the most recent run log file
  */

package/dist/src/lib/merge-check/index.js

@@ -20,7 +20,7 @@ import { buildReport, formatReportMarkdown, formatBranchReportMarkdown, postRepo
 /**
  * Resolve log directory path
  */
-function resolveLogDir(customPath) {
+export function resolveLogDir(customPath) {
     if (customPath) {
         return customPath.replace("~", os.homedir());
     }

package/dist/src/lib/merge-check/report.js

@@ -5,6 +5,7 @@
  * batch-level verdict. Optionally posts to GitHub as PR comment.
  */
 import { spawnSync } from "child_process";
+import { resolveFailureReason, toCommandResult } from "./command-result.js";
 /**
  * Compute per-issue verdicts from check results
  */
@@ -232,7 +233,10 @@ export function postReportToGitHub(report) {
         const markdown = formatBranchReportMarkdown(report, branch.issueNumber);
         const result = spawnSync("gh", ["pr", "comment", String(branch.prNumber), "--body", markdown], { stdio: "pipe", encoding: "utf-8" });
         if (result.status !== 0) {
-            console.error(`Failed to post comment on PR #${branch.prNumber}: ${result.stderr}`);
+            // Same never-empty reason resolution as the combined-branch test (#803):
+            // `gh` usually writes to stderr, but a killed or unspawnable process
+            // leaves it empty, which would print a message with nothing after it.
+            console.error(`Failed to post comment on PR #${branch.prNumber}: ${resolveFailureReason(toCommandResult(result))}`);
         }
     }
 }

package/dist/src/lib/merge-check/types.d.ts

@@ -171,6 +171,15 @@ export interface MergeCommandOptions {
     json?: boolean;
     /** Enable verbose output */
     verbose?: boolean;
+    /**
+     * Watch mode (#818): poll each resolved PR's CI rollup until every check is
+     * terminal, then run the normal merge-check report. Never merges.
+     */
+    watch?: boolean;
+    /** Watch poll interval in seconds (default 30). Only used with `watch`. */
+    interval?: number;
+    /** Watch give-up timeout in seconds (default 1800). Only used with `watch`. */
+    timeout?: number;
 }
 /**
  * Configuration for paired directories (template mirroring)

package/dist/src/lib/merge-check/watch.d.ts

@@ -0,0 +1,121 @@
+/**
+ * `sequant merge --watch` — poll a PR's CI rollup until it is terminal, then let
+ * the existing merge-check report run. This module owns only the *wait*: it
+ * never merges and never runs the checks itself (merge.ts orchestrates that).
+ *
+ * See #818. Design contract:
+ *  - foreground `await sleep` loop — no daemon, no child process, no OS notifier;
+ *  - all `gh` access through `GitHubProvider` (#443), using `statusCheckRollup`
+ *    (the `--json checks` field is known-broken);
+ *  - three dispatch-block signatures short-circuit to BLOCKED instead of polling
+ *    until timeout (AC-3): merge conflict, zero-checks-because-conflicting, and a
+ *    uniformly-failing board whose annotations show the runner never started.
+ */
+import type { RollupEntry, MergeableState } from "../workflow/platforms/github.js";
+import { type AnnotatedCheck } from "../qa/infra-blocked-ci.js";
+/**
+ * The subset of `GitHubProvider` the watch loop depends on. Declared as an
+ * interface so tests inject a fake without spawning real `gh` calls.
+ */
+export interface WatchGitHub {
+    getMergeableStateSync(prNumber: number): MergeableState;
+    getStatusCheckRollupSync(prNumber: number): RollupEntry[];
+    getPRHeadShaSync(prNumber: number): string | null;
+    getCheckRunAnnotationsSync(headSha: string): AnnotatedCheck[];
+}
+/**
+ * Map one rollup entry to a `gh`-style bucket (`pass | fail | pending |
+ * skipping`), normalising the two entry shapes (CheckRun vs StatusContext) so
+ * `allChecksFailing` — which the billing-lockout detector gates on — can be
+ * reused verbatim.
+ */
+export declare function rollupEntryBucket(entry: RollupEntry): string;
+/** Is a rollup entry in a terminal (no-longer-changing) state? */
+export declare function isRollupEntryTerminal(entry: RollupEntry): boolean;
+/** Outcome of classifying a single poll tick. */
+export type TickOutcome = {
+    kind: "terminal";
+} | {
+    kind: "blocked";
+    reason: string;
+    checkName?: string;
+} | {
+    kind: "pending";
+    pending: number;
+    total: number;
+};
+/**
+ * Classify a single poll of `(mergeable, rollup)`.
+ *
+ * Pure except for the lazily-invoked `fetchAnnotations`, which is called ONLY
+ * when the whole board is terminal-and-failing — so healthy or partial boards
+ * never pay for the extra check-run annotation API calls.
+ */
+export declare function classifyTick(mergeable: MergeableState, rollup: RollupEntry[], fetchAnnotations: () => AnnotatedCheck[]): TickOutcome;
+/** Terminal status of a watch. */
+export type WatchStatus = "terminal" | "blocked" | "timeout";
+/** Result of watching a single PR's checks to completion. */
+export interface WatchResult {
+    status: WatchStatus;
+    /** Human-readable cause for `blocked`/`timeout`; undefined when `terminal`. */
+    reason?: string;
+    /** Check name whose annotation matched, for a billing-lockout BLOCKED. */
+    checkName?: string;
+    /** Number of polls performed. */
+    polls: number;
+    /** Elapsed wall-clock time in milliseconds. */
+    elapsedMs: number;
+}
+/** Options for {@link waitForChecks}. */
+export interface WatchOptions {
+    /** Delay between polls, in milliseconds. */
+    intervalMs: number;
+    /** Give-up deadline measured from the first poll, in milliseconds. */
+    timeoutMs: number;
+    /** Optional per-poll progress callback (terminal output). */
+    onPoll?: (message: string) => void;
+}
+/** Default watch poll interval (seconds) when `--interval` is not given. */
+export declare const DEFAULT_WATCH_INTERVAL_S = 30;
+/** Default watch timeout (seconds) when `--timeout` is not given: 30 minutes. */
+export declare const DEFAULT_WATCH_TIMEOUT_S = 1800;
+/**
+ * Smallest poll interval we will ever use, in milliseconds.
+ *
+ * A zero/sub-second interval turns the gate into a tight `gh`-spawning loop that
+ * can trip GitHub rate limiting, so the floor is enforced even against an
+ * explicit request.
+ */
+export declare const MIN_WATCH_INTERVAL_MS = 1000;
+/**
+ * Convert user-supplied `--interval`/`--timeout` *seconds* into validated
+ * milliseconds, falling back to the defaults for anything unusable.
+ *
+ * Why this exists: `??` only defends against `null`/`undefined`, and
+ * `parseInt("abc", 10)` yields `NaN`, which is neither. A `NaN` timeout makes
+ * `start + timeoutMs` `NaN`, so `now >= deadline` is permanently false and the
+ * watch loop never gives up; a `NaN`/`0` interval makes `setTimeout` fire
+ * immediately, so it never sleeps either. The two combine into an unbounded,
+ * zero-delay poll loop. This mirrors the numeric-input guards used elsewhere in
+ * the codebase (`batch-executor.ts` `maxIter`/`autoWait`, `merge.ts` issue-number
+ * parsing) rather than trusting the raw flag value.
+ *
+ * The CLI rejects malformed values outright (see `bin/cli.ts`); this is the
+ * defence for programmatic callers that build `MergeCommandOptions` directly.
+ */
+export declare function resolveWatchTiming(options: {
+    interval?: number;
+    timeout?: number;
+}): {
+    intervalMs: number;
+    timeoutMs: number;
+};
+/**
+ * Poll a PR's rollup until it is terminal, blocked, or timed out.
+ *
+ * `sleepFn`/`nowFn` are injectable so tests run instantly and deterministically
+ * without real timers. The loop always classifies a *fresh* poll before it can
+ * declare a timeout, so a check that turns terminal on the final interval is
+ * never swallowed by the deadline.
+ */
+export declare function waitForChecks(prNumber: number, options: WatchOptions, gh: WatchGitHub, sleepFn?: (ms: number) => Promise<void>, nowFn?: () => number): Promise<WatchResult>;

package/dist/src/lib/merge-check/watch.js

@@ -0,0 +1,215 @@
+/**
+ * `sequant merge --watch` — poll a PR's CI rollup until it is terminal, then let
+ * the existing merge-check report run. This module owns only the *wait*: it
+ * never merges and never runs the checks itself (merge.ts orchestrates that).
+ *
+ * See #818. Design contract:
+ *  - foreground `await sleep` loop — no daemon, no child process, no OS notifier;
+ *  - all `gh` access through `GitHubProvider` (#443), using `statusCheckRollup`
+ *    (the `--json checks` field is known-broken);
+ *  - three dispatch-block signatures short-circuit to BLOCKED instead of polling
+ *    until timeout (AC-3): merge conflict, zero-checks-because-conflicting, and a
+ *    uniformly-failing board whose annotations show the runner never started.
+ */
+import { allChecksFailing, detectInfraBlockedCi, } from "../qa/infra-blocked-ci.js";
+/**
+ * Map one rollup entry to a `gh`-style bucket (`pass | fail | pending |
+ * skipping`), normalising the two entry shapes (CheckRun vs StatusContext) so
+ * `allChecksFailing` — which the billing-lockout detector gates on — can be
+ * reused verbatim.
+ */
+export function rollupEntryBucket(entry) {
+    // CheckRun: progress in `status`, outcome in `conclusion`.
+    if (entry.status !== undefined || entry.conclusion !== undefined) {
+        const status = (entry.status ?? "").toUpperCase();
+        if (status !== "COMPLETED")
+            return "pending"; // QUEUED | IN_PROGRESS | ...
+        const conclusion = (entry.conclusion ?? "").toUpperCase();
+        switch (conclusion) {
+            case "SUCCESS":
+                return "pass";
+            case "NEUTRAL":
+            case "SKIPPED":
+                return "skipping";
+            default:
+                // FAILURE | TIMED_OUT | CANCELLED | ACTION_REQUIRED | STARTUP_FAILURE | STALE
+                return "fail";
+        }
+    }
+    // StatusContext: combined state.
+    const state = (entry.state ?? "").toUpperCase();
+    switch (state) {
+        case "SUCCESS":
+            return "pass";
+        case "FAILURE":
+        case "ERROR":
+            return "fail";
+        default:
+            // PENDING | EXPECTED
+            return "pending";
+    }
+}
+/** Is a rollup entry in a terminal (no-longer-changing) state? */
+export function isRollupEntryTerminal(entry) {
+    return rollupEntryBucket(entry) !== "pending";
+}
+/**
+ * Classify a single poll of `(mergeable, rollup)`.
+ *
+ * Pure except for the lazily-invoked `fetchAnnotations`, which is called ONLY
+ * when the whole board is terminal-and-failing — so healthy or partial boards
+ * never pay for the extra check-run annotation API calls.
+ */
+export function classifyTick(mergeable, rollup, fetchAnnotations) {
+    // (1) Merge conflict blocks CI dispatch entirely — CI never starts against an
+    // unmergeable ref, so waiting on checks is futile. Fire regardless of check
+    // count: this also covers the "zero checks because CONFLICTING" trap (AC-3a,
+    // AC-3b) — the case the issue calls out where 0 checks after a push means
+    // dispatch was blocked, not that CI is slow.
+    if (mergeable === "CONFLICTING") {
+        return {
+            kind: "blocked",
+            reason: "PR is not mergeable (CONFLICTING) — merge conflicts block CI dispatch. " +
+                "Resolve conflicts and re-push before running merge-check.",
+        };
+    }
+    // No checks yet. While GitHub is still computing mergeability or hasn't
+    // dispatched, keep polling; a genuine no-CI PR falls through to the timeout,
+    // whose message names the zero-checks case. We deliberately do NOT declare
+    // terminal here — proceeding on an empty board would skip the very CI the
+    // user asked us to wait for.
+    if (rollup.length === 0) {
+        return { kind: "pending", pending: 0, total: 0 };
+    }
+    const pending = rollup.filter((e) => !isRollupEntryTerminal(e));
+    if (pending.length > 0) {
+        return { kind: "pending", pending: pending.length, total: rollup.length };
+    }
+    // (3) Every check is terminal. If the board is uniformly failing it may be a
+    // billing lockout (runner never started) rather than real test failures —
+    // scan the head-SHA annotations for the not-started signature (AC-3c). Only
+    // then; a healthy or partially-failing board is a real verdict, not a block.
+    const buckets = rollup.map((e) => ({
+        bucket: rollupEntryBucket(e),
+    }));
+    if (allChecksFailing(buckets)) {
+        const infra = detectInfraBlockedCi(fetchAnnotations());
+        if (infra.blocked) {
+            return {
+                kind: "blocked",
+                reason: infra.message ??
+                    "CI runner was not started (infrastructure blocked).",
+                checkName: infra.checkName,
+            };
+        }
+    }
+    return { kind: "terminal" };
+}
+/** Default watch poll interval (seconds) when `--interval` is not given. */
+export const DEFAULT_WATCH_INTERVAL_S = 30;
+/** Default watch timeout (seconds) when `--timeout` is not given: 30 minutes. */
+export const DEFAULT_WATCH_TIMEOUT_S = 1800;
+/**
+ * Smallest poll interval we will ever use, in milliseconds.
+ *
+ * A zero/sub-second interval turns the gate into a tight `gh`-spawning loop that
+ * can trip GitHub rate limiting, so the floor is enforced even against an
+ * explicit request.
+ */
+export const MIN_WATCH_INTERVAL_MS = 1000;
+/**
+ * Convert user-supplied `--interval`/`--timeout` *seconds* into validated
+ * milliseconds, falling back to the defaults for anything unusable.
+ *
+ * Why this exists: `??` only defends against `null`/`undefined`, and
+ * `parseInt("abc", 10)` yields `NaN`, which is neither. A `NaN` timeout makes
+ * `start + timeoutMs` `NaN`, so `now >= deadline` is permanently false and the
+ * watch loop never gives up; a `NaN`/`0` interval makes `setTimeout` fire
+ * immediately, so it never sleeps either. The two combine into an unbounded,
+ * zero-delay poll loop. This mirrors the numeric-input guards used elsewhere in
+ * the codebase (`batch-executor.ts` `maxIter`/`autoWait`, `merge.ts` issue-number
+ * parsing) rather than trusting the raw flag value.
+ *
+ * The CLI rejects malformed values outright (see `bin/cli.ts`); this is the
+ * defence for programmatic callers that build `MergeCommandOptions` directly.
+ */
+export function resolveWatchTiming(options) {
+    const seconds = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value > 0
+        ? value
+        : fallback;
+    return {
+        intervalMs: Math.max(MIN_WATCH_INTERVAL_MS, seconds(options.interval, DEFAULT_WATCH_INTERVAL_S) * 1000),
+        timeoutMs: seconds(options.timeout, DEFAULT_WATCH_TIMEOUT_S) * 1000,
+    };
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Poll a PR's rollup until it is terminal, blocked, or timed out.
+ *
+ * `sleepFn`/`nowFn` are injectable so tests run instantly and deterministically
+ * without real timers. The loop always classifies a *fresh* poll before it can
+ * declare a timeout, so a check that turns terminal on the final interval is
+ * never swallowed by the deadline.
+ */
+export async function waitForChecks(prNumber, options, gh, sleepFn = defaultSleep, nowFn = Date.now) {
+    const { onPoll } = options;
+    // Defensive normalisation. `resolveWatchTiming` already sanitises the CLI
+    // path, but the loop itself must be incapable of running away: a non-finite
+    // deadline makes `now >= deadline` permanently false (never times out) and a
+    // non-finite/zero interval makes `setTimeout` fire immediately (never
+    // sleeps), which together spawn `gh` in a tight loop forever. `timeoutMs: 0`
+    // is deliberately preserved — callers use it to mean "deadline already
+    // exhausted, poll once then give up" (see the shared deadline in
+    // `runWatchGate`).
+    const intervalMs = Math.max(MIN_WATCH_INTERVAL_MS, Number.isFinite(options.intervalMs) ? options.intervalMs : 0);
+    const timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs >= 0
+        ? options.timeoutMs
+        : DEFAULT_WATCH_TIMEOUT_S * 1000;
+    const start = nowFn();
+    const deadline = start + timeoutMs;
+    let polls = 0;
+    // Lazy annotation fetch — only reached from classifyTick's all-failing branch.
+    const fetchAnnotations = () => {
+        const sha = gh.getPRHeadShaSync(prNumber);
+        if (!sha)
+            return [];
+        return gh.getCheckRunAnnotationsSync(sha);
+    };
+    for (;;) {
+        polls++;
+        const mergeable = gh.getMergeableStateSync(prNumber);
+        const rollup = gh.getStatusCheckRollupSync(prNumber);
+        const tick = classifyTick(mergeable, rollup, fetchAnnotations);
+        const elapsedMs = nowFn() - start;
+        if (tick.kind === "blocked") {
+            return {
+                status: "blocked",
+                reason: tick.reason,
+                checkName: tick.checkName,
+                polls,
+                elapsedMs,
+            };
+        }
+        if (tick.kind === "terminal") {
+            return { status: "terminal", polls, elapsedMs };
+        }
+        // Pending: report progress.
+        if (onPoll) {
+            onPoll(tick.total === 0
+                ? "No checks reported yet…"
+                : `${tick.total - tick.pending}/${tick.total} checks terminal…`);
+        }
+        // Deadline reached. The classify above was a fresh poll, so timing out now
+        // cannot swallow a late terminal.
+        if (nowFn() >= deadline) {
+            const timeoutSec = Math.round(timeoutMs / 1000);
+            const reason = tick.total === 0
+                ? `Watch timed out after ${timeoutSec}s: no CI checks ever appeared for PR #${prNumber} ` +
+                    `(CI may not be configured, or dispatch was blocked).`
+                : `Watch timed out after ${timeoutSec}s: ${tick.pending}/${tick.total} checks still pending on PR #${prNumber}.`;
+            return { status: "timeout", reason, polls, elapsedMs };
+        }
+        const remaining = deadline - nowFn();
+        await sleepFn(Math.min(intervalMs, Math.max(0, remaining)));
+    }
+}

package/dist/src/lib/qa/infra-blocked-ci.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Infra-blocked CI detection helpers used by the `/qa` Phase 1 CI status check.
+ *
+ * A repository that has hit its GitHub Actions spending limit fails **every**
+ * check within seconds of starting: no runner is ever allocated, so no step
+ * executes. `gh pr checks` and `gh run view` report these as ordinary failures,
+ * and the default status mapping (`FAILURE → NOT_MET → blocks merge`) then marks
+ * CI-dependent ACs as unmet for a condition no code change can fix — findings
+ * that would go on to feed `/loop` and burn iterations "fixing" working code.
+ *
+ * The real cause exists only as a check-run annotation. `/qa` uses these helpers
+ * to recognise that signature and reclassify CI as infra-blocked instead.
+ *
+ * Both functions are pure predicates over already-fetched API data; the `gh api`
+ * plumbing lives in the skill prompt, mirroring `./markdown-only-ci.ts`.
+ */
+/** Minimal shape of a `gh pr checks --json name,state,bucket` entry. */
+export interface CiCheckBucket {
+    /** `gh` rollup bucket: `pass` | `fail` | `pending` | `skipping`. */
+    bucket: string;
+}
+/**
+ * Predicate: is *every* check in the `fail` bucket?
+ *
+ * This is the gate for the annotation query. A mix of real failures and
+ * fail-fast ones is not the billing-lockout signature — only a uniformly red
+ * board is — so healthy and partially-failing PRs never pay for the extra API
+ * calls, and their status mapping is untouched.
+ *
+ * An empty list means "no CI configured", which is a separate case handled by
+ * the skill's existing empty-response branch, so it returns `false` here rather
+ * than vacuously true.
+ *
+ * @param checks - Entries from `gh pr checks --json name,state,bucket`.
+ * @returns `true` only if `checks` is non-empty and every entry is `fail`.
+ */
+export declare function allChecksFailing(checks: readonly CiCheckBucket[]): boolean;
+/**
+ * The runner-never-started signature.
+ *
+ * Deliberately matches on the annotation **message only**, with no
+ * `annotation_level` condition. The captured fixture does carry
+ * `annotation_level: "failure"`, but gating on it would add a requirement the
+ * acceptance criteria never state, and a `warning`-level variant of the same
+ * message would then be silently missed — the exact class of failure this
+ * detection exists to prevent.
+ */
+export declare const NOT_STARTED_SIGNATURE: RegExp;
+/** Minimal shape of a GitHub check-run annotation. */
+export interface CheckAnnotation {
+    message?: string | null;
+    annotation_level?: string | null;
+    path?: string | null;
+}
+/** A check paired with the annotations fetched from its `annotations_url`. */
+export interface AnnotatedCheck {
+    checkName: string;
+    annotations?: readonly CheckAnnotation[] | null;
+}
+/** Outcome of scanning failing checks for the not-started signature. */
+export interface InfraBlockedResult {
+    /** `true` when CI is red for infrastructure reasons, not code reasons. */
+    blocked: boolean;
+    /**
+     * The matching annotation message, **verbatim**. `/qa` surfaces this as the
+     * action item rather than paraphrasing it — the message names the remedy
+     * (e.g. the billing settings page), and a paraphrase would lose it.
+     */
+    message?: string;
+    /** Name of the check whose annotation matched, for the QA report. */
+    checkName?: string;
+}
+/**
+ * Scan failing checks' annotations for the not-started signature.
+ *
+ * Returns on the first match: when the board is uniformly red for a billing
+ * lockout, every check carries the same annotation, so one is representative
+ * and the caller can stop fetching.
+ *
+ * Deliberately defensive about its input shape. Callers feed this raw `gh api`
+ * output, and a failed annotations request (404, rate limit, revoked token)
+ * yields an *object* — `{"message":"Not Found"}` — where an array is expected.
+ * Iterating that throws. Since the whole point of this detector is to keep a
+ * broken-CI situation from derailing the QA phase, a malformed payload must
+ * degrade to "not infra-blocked", never crash the run.
+ *
+ * @param checks - Failing checks with their fetched annotations.
+ * @returns `{ blocked: true, message, checkName }` on a match, else `{ blocked: false }`.
+ */
+export declare function detectInfraBlockedCi(checks: readonly AnnotatedCheck[]): InfraBlockedResult;

package/dist/src/lib/qa/infra-blocked-ci.js

@@ -0,0 +1,80 @@
+/**
+ * Infra-blocked CI detection helpers used by the `/qa` Phase 1 CI status check.
+ *
+ * A repository that has hit its GitHub Actions spending limit fails **every**
+ * check within seconds of starting: no runner is ever allocated, so no step
+ * executes. `gh pr checks` and `gh run view` report these as ordinary failures,
+ * and the default status mapping (`FAILURE → NOT_MET → blocks merge`) then marks
+ * CI-dependent ACs as unmet for a condition no code change can fix — findings
+ * that would go on to feed `/loop` and burn iterations "fixing" working code.
+ *
+ * The real cause exists only as a check-run annotation. `/qa` uses these helpers
+ * to recognise that signature and reclassify CI as infra-blocked instead.
+ *
+ * Both functions are pure predicates over already-fetched API data; the `gh api`
+ * plumbing lives in the skill prompt, mirroring `./markdown-only-ci.ts`.
+ */
+/**
+ * Predicate: is *every* check in the `fail` bucket?
+ *
+ * This is the gate for the annotation query. A mix of real failures and
+ * fail-fast ones is not the billing-lockout signature — only a uniformly red
+ * board is — so healthy and partially-failing PRs never pay for the extra API
+ * calls, and their status mapping is untouched.
+ *
+ * An empty list means "no CI configured", which is a separate case handled by
+ * the skill's existing empty-response branch, so it returns `false` here rather
+ * than vacuously true.
+ *
+ * @param checks - Entries from `gh pr checks --json name,state,bucket`.
+ * @returns `true` only if `checks` is non-empty and every entry is `fail`.
+ */
+export function allChecksFailing(checks) {
+    if (checks.length === 0)
+        return false;
+    return checks.every((check) => check.bucket === "fail");
+}
+/**
+ * The runner-never-started signature.
+ *
+ * Deliberately matches on the annotation **message only**, with no
+ * `annotation_level` condition. The captured fixture does carry
+ * `annotation_level: "failure"`, but gating on it would add a requirement the
+ * acceptance criteria never state, and a `warning`-level variant of the same
+ * message would then be silently missed — the exact class of failure this
+ * detection exists to prevent.
+ */
+export const NOT_STARTED_SIGNATURE = /job was not started/i;
+/**
+ * Scan failing checks' annotations for the not-started signature.
+ *
+ * Returns on the first match: when the board is uniformly red for a billing
+ * lockout, every check carries the same annotation, so one is representative
+ * and the caller can stop fetching.
+ *
+ * Deliberately defensive about its input shape. Callers feed this raw `gh api`
+ * output, and a failed annotations request (404, rate limit, revoked token)
+ * yields an *object* — `{"message":"Not Found"}` — where an array is expected.
+ * Iterating that throws. Since the whole point of this detector is to keep a
+ * broken-CI situation from derailing the QA phase, a malformed payload must
+ * degrade to "not infra-blocked", never crash the run.
+ *
+ * @param checks - Failing checks with their fetched annotations.
+ * @returns `{ blocked: true, message, checkName }` on a match, else `{ blocked: false }`.
+ */
+export function detectInfraBlockedCi(checks) {
+    if (!Array.isArray(checks))
+        return { blocked: false };
+    for (const check of checks) {
+        const annotations = check?.annotations;
+        if (!Array.isArray(annotations))
+            continue;
+        for (const annotation of annotations) {
+            const message = annotation?.message;
+            if (typeof message === "string" && NOT_STARTED_SIGNATURE.test(message)) {
+                return { blocked: true, message, checkName: check.checkName };
+            }
+        }
+    }
+    return { blocked: false };
+}