patchrelay 0.31.0 → 0.32.0

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "service": "patchrelay",
-  "version": "0.31.0",
-  "commit": "5de73a74995a",
-  "builtAt": "2026-04-01T09:38:32.968Z"
+  "version": "0.32.0",
+  "commit": "21ba6968b0ff",
+  "builtAt": "2026-04-01T11:53:53.815Z"
 }

package/dist/db/migrations.js

@@ -204,6 +204,11 @@ export function runPatchRelayMigrations(connection) {
     addColumnIfMissing(connection, "issues", "last_github_failure_check_url", "TEXT");
     addColumnIfMissing(connection, "issues", "last_github_failure_context_json", "TEXT");
     addColumnIfMissing(connection, "issues", "last_github_failure_at", "TEXT");
+    addColumnIfMissing(connection, "issues", "last_github_ci_snapshot_head_sha", "TEXT");
+    addColumnIfMissing(connection, "issues", "last_github_ci_snapshot_gate_check_name", "TEXT");
+    addColumnIfMissing(connection, "issues", "last_github_ci_snapshot_gate_check_status", "TEXT");
+    addColumnIfMissing(connection, "issues", "last_github_ci_snapshot_json", "TEXT");
+    addColumnIfMissing(connection, "issues", "last_github_ci_snapshot_settled_at", "TEXT");
     addColumnIfMissing(connection, "issues", "last_queue_signal_at", "TEXT");
     addColumnIfMissing(connection, "issues", "last_queue_incident_json", "TEXT");
     addColumnIfMissing(connection, "issues", "last_attempted_failure_head_sha", "TEXT");

package/dist/db.js

@@ -189,6 +189,26 @@ export class PatchRelayDatabase {
                 sets.push("last_github_failure_at = @lastGitHubFailureAt");
                 values.lastGitHubFailureAt = params.lastGitHubFailureAt;
             }
+            if (params.lastGitHubCiSnapshotHeadSha !== undefined) {
+                sets.push("last_github_ci_snapshot_head_sha = @lastGitHubCiSnapshotHeadSha");
+                values.lastGitHubCiSnapshotHeadSha = params.lastGitHubCiSnapshotHeadSha;
+            }
+            if (params.lastGitHubCiSnapshotGateCheckName !== undefined) {
+                sets.push("last_github_ci_snapshot_gate_check_name = @lastGitHubCiSnapshotGateCheckName");
+                values.lastGitHubCiSnapshotGateCheckName = params.lastGitHubCiSnapshotGateCheckName;
+            }
+            if (params.lastGitHubCiSnapshotGateCheckStatus !== undefined) {
+                sets.push("last_github_ci_snapshot_gate_check_status = @lastGitHubCiSnapshotGateCheckStatus");
+                values.lastGitHubCiSnapshotGateCheckStatus = params.lastGitHubCiSnapshotGateCheckStatus;
+            }
+            if (params.lastGitHubCiSnapshotJson !== undefined) {
+                sets.push("last_github_ci_snapshot_json = @lastGitHubCiSnapshotJson");
+                values.lastGitHubCiSnapshotJson = params.lastGitHubCiSnapshotJson;
+            }
+            if (params.lastGitHubCiSnapshotSettledAt !== undefined) {
+                sets.push("last_github_ci_snapshot_settled_at = @lastGitHubCiSnapshotSettledAt");
+                values.lastGitHubCiSnapshotSettledAt = params.lastGitHubCiSnapshotSettledAt;
+            }
             if (params.lastQueueSignalAt !== undefined) {
                 sets.push("last_queue_signal_at = @lastQueueSignalAt");
                 values.lastQueueSignalAt = params.lastQueueSignalAt;
@@ -236,7 +256,9 @@ export class PatchRelayDatabase {
           branch_name, worktree_path, thread_id, active_run_id,
           agent_session_id,
           pr_number, pr_url, pr_state, pr_review_state, pr_check_status,
-          last_github_failure_source, last_github_failure_head_sha, last_github_failure_signature, last_github_failure_check_name, last_github_failure_check_url, last_github_failure_context_json, last_github_failure_at, last_queue_signal_at, last_queue_incident_json,
+          last_github_failure_source, last_github_failure_head_sha, last_github_failure_signature, last_github_failure_check_name, last_github_failure_check_url, last_github_failure_context_json, last_github_failure_at,
+          last_github_ci_snapshot_head_sha, last_github_ci_snapshot_gate_check_name, last_github_ci_snapshot_gate_check_status, last_github_ci_snapshot_json, last_github_ci_snapshot_settled_at,
+          last_queue_signal_at, last_queue_incident_json,
           last_attempted_failure_head_sha, last_attempted_failure_signature,
           updated_at
         ) VALUES (
@@ -246,7 +268,9 @@ export class PatchRelayDatabase {
           @branchName, @worktreePath, @threadId, @activeRunId,
           @agentSessionId,
           @prNumber, @prUrl, @prState, @prReviewState, @prCheckStatus,
-          @lastGitHubFailureSource, @lastGitHubFailureHeadSha, @lastGitHubFailureSignature, @lastGitHubFailureCheckName, @lastGitHubFailureCheckUrl, @lastGitHubFailureContextJson, @lastGitHubFailureAt, @lastQueueSignalAt, @lastQueueIncidentJson,
+          @lastGitHubFailureSource, @lastGitHubFailureHeadSha, @lastGitHubFailureSignature, @lastGitHubFailureCheckName, @lastGitHubFailureCheckUrl, @lastGitHubFailureContextJson, @lastGitHubFailureAt,
+          @lastGitHubCiSnapshotHeadSha, @lastGitHubCiSnapshotGateCheckName, @lastGitHubCiSnapshotGateCheckStatus, @lastGitHubCiSnapshotJson, @lastGitHubCiSnapshotSettledAt,
+          @lastQueueSignalAt, @lastQueueIncidentJson,
           @lastAttemptedFailureHeadSha, @lastAttemptedFailureSignature,
           @now
         )
@@ -281,6 +305,11 @@ export class PatchRelayDatabase {
                 lastGitHubFailureCheckUrl: params.lastGitHubFailureCheckUrl ?? null,
                 lastGitHubFailureContextJson: params.lastGitHubFailureContextJson ?? null,
                 lastGitHubFailureAt: params.lastGitHubFailureAt ?? null,
+                lastGitHubCiSnapshotHeadSha: params.lastGitHubCiSnapshotHeadSha ?? null,
+                lastGitHubCiSnapshotGateCheckName: params.lastGitHubCiSnapshotGateCheckName ?? null,
+                lastGitHubCiSnapshotGateCheckStatus: params.lastGitHubCiSnapshotGateCheckStatus ?? null,
+                lastGitHubCiSnapshotJson: params.lastGitHubCiSnapshotJson ?? null,
+                lastGitHubCiSnapshotSettledAt: params.lastGitHubCiSnapshotSettledAt ?? null,
                 lastQueueSignalAt: params.lastQueueSignalAt ?? null,
                 lastQueueIncidentJson: params.lastQueueIncidentJson ?? null,
                 lastAttemptedFailureHeadSha: params.lastAttemptedFailureHeadSha ?? null,
@@ -381,6 +410,17 @@ export class PatchRelayDatabase {
             linearIssueId: String(row.linear_issue_id),
         }));
     }
+    getLatestGitHubCiSnapshot(projectId, linearIssueId) {
+        const issue = this.getIssue(projectId, linearIssueId);
+        if (!issue?.lastGitHubCiSnapshotJson)
+            return undefined;
+        try {
+            return JSON.parse(issue.lastGitHubCiSnapshotJson);
+        }
+        catch {
+            return undefined;
+        }
+    }
     countUnresolvedBlockers(projectId, linearIssueId) {
         const row = this.connection.prepare(`
       SELECT COUNT(*) AS count
@@ -632,6 +672,21 @@ function mapIssueRow(row) {
         ...(row.last_github_failure_at !== null && row.last_github_failure_at !== undefined
             ? { lastGitHubFailureAt: String(row.last_github_failure_at) }
             : {}),
+        ...(row.last_github_ci_snapshot_head_sha !== null && row.last_github_ci_snapshot_head_sha !== undefined
+            ? { lastGitHubCiSnapshotHeadSha: String(row.last_github_ci_snapshot_head_sha) }
+            : {}),
+        ...(row.last_github_ci_snapshot_gate_check_name !== null && row.last_github_ci_snapshot_gate_check_name !== undefined
+            ? { lastGitHubCiSnapshotGateCheckName: String(row.last_github_ci_snapshot_gate_check_name) }
+            : {}),
+        ...(row.last_github_ci_snapshot_gate_check_status !== null && row.last_github_ci_snapshot_gate_check_status !== undefined
+            ? { lastGitHubCiSnapshotGateCheckStatus: String(row.last_github_ci_snapshot_gate_check_status) }
+            : {}),
+        ...(row.last_github_ci_snapshot_json !== null && row.last_github_ci_snapshot_json !== undefined
+            ? { lastGitHubCiSnapshotJson: String(row.last_github_ci_snapshot_json) }
+            : {}),
+        ...(row.last_github_ci_snapshot_settled_at !== null && row.last_github_ci_snapshot_settled_at !== undefined
+            ? { lastGitHubCiSnapshotSettledAt: String(row.last_github_ci_snapshot_settled_at) }
+            : {}),
         ...(row.last_queue_signal_at !== null && row.last_queue_signal_at !== undefined
             ? { lastQueueSignalAt: String(row.last_queue_signal_at) }
             : {}),

package/dist/github-failure-context.js

@@ -75,6 +75,21 @@ export function createGitHubFailureContextResolver() {
         },
     };
 }
+export function createGitHubCiSnapshotResolver() {
+    return {
+        resolve: async ({ repoFullName, event, gateCheckNames }) => {
+            if (!repoFullName || !event.headSha)
+                return undefined;
+            try {
+                const checks = await resolveCheckSnapshotChecks(repoFullName, event.headSha);
+                return buildCiSnapshotFromChecks(checks, event, gateCheckNames);
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}
 export function parseGitHubFailureContext(value) {
     if (!value)
         return undefined;
@@ -123,6 +138,18 @@ async function resolveFailedCheckRun(repoFullName, event) {
         ?? checks.find((entry) => entry.name && event.checkName && entry.name.includes(event.checkName))
         ?? checks[0];
 }
+async function resolveCheckSnapshotChecks(repoFullName, headSha) {
+    const response = await execCommand("gh", [
+        "api",
+        `repos/${repoFullName}/commits/${headSha}/check-runs`,
+        "--method", "GET",
+    ], { timeoutMs: 15_000 });
+    if (response.exitCode !== 0) {
+        throw new Error(response.stderr || "gh api check-runs failed");
+    }
+    const payload = safeJsonParse(response.stdout);
+    return (payload?.check_runs ?? []).map(mapCiSnapshotCheck).filter((entry) => Boolean(entry));
+}
 async function resolveWorkflowJob(repoFullName, workflowRunId, preferredName) {
     const response = await execCommand("gh", [
         "api",
@@ -173,6 +200,22 @@ function mapCheckRunSummary(row) {
         ...(typeof output?.text === "string" ? { outputText: sanitizeDiagnosticText(output.text, 240) } : {}),
     };
 }
+function mapCiSnapshotCheck(row) {
+    if (typeof row.name !== "string" || !row.name.trim())
+        return undefined;
+    const output = row.output && typeof row.output === "object" ? row.output : undefined;
+    const status = deriveCheckStatus({
+        apiStatus: typeof row.status === "string" ? row.status : undefined,
+        apiConclusion: typeof row.conclusion === "string" ? row.conclusion : undefined,
+    });
+    return {
+        name: row.name.trim(),
+        status,
+        ...(typeof row.conclusion === "string" && row.conclusion.trim() ? { conclusion: row.conclusion.trim().toLowerCase() } : {}),
+        ...(typeof row.details_url === "string" && row.details_url.trim() ? { detailsUrl: row.details_url.trim() } : {}),
+        ...(firstNonEmpty(typeof output?.title === "string" ? output.title : undefined, typeof output?.summary === "string" ? sanitizeDiagnosticText(output.summary, 240) : undefined) ? { summary: firstNonEmpty(typeof output?.title === "string" ? output.title : undefined, typeof output?.summary === "string" ? sanitizeDiagnosticText(output.summary, 240) : undefined) } : {}),
+    };
+}
 function mapWorkflowJobSummary(row) {
     const steps = Array.isArray(row.steps) ? row.steps.filter((entry) => Boolean(entry) && typeof entry === "object") : [];
     const failedStep = steps.find((entry) => {
@@ -192,6 +235,56 @@ function parseWorkflowRunId(url) {
     const match = url.match(/\/actions\/runs\/(\d+)/);
     return match ? Number(match[1]) : undefined;
 }
+function buildCiSnapshotFromChecks(checks, event, gateCheckNames) {
+    const gateCheck = findGateCheck(checks, gateCheckNames, event.checkName);
+    const gateCheckName = gateCheck?.name ?? pickGateCheckName(gateCheckNames, event.checkName) ?? event.checkName;
+    const gateCheckStatus = gateCheck?.status ?? deriveCheckStatus({
+        eventStatus: event.checkStatus,
+        eventConclusion: event.triggerEvent === "check_passed" ? "success" : "failure",
+    });
+    const failedChecks = checks.filter((entry) => entry.status === "failure");
+    return {
+        headSha: event.headSha,
+        ...(gateCheckName ? { gateCheckName } : {}),
+        gateCheckStatus,
+        failedChecks,
+        checks,
+        ...(gateCheckStatus !== "pending" ? { settledAt: new Date().toISOString() } : {}),
+        capturedAt: new Date().toISOString(),
+    };
+}
+function findGateCheck(checks, gateCheckNames, fallbackCheckName) {
+    const exactNames = gateCheckNames.map((entry) => entry.trim().toLowerCase()).filter(Boolean);
+    if (exactNames.length > 0) {
+        const exact = checks.find((entry) => exactNames.includes(entry.name.trim().toLowerCase()));
+        if (exact)
+            return exact;
+    }
+    if (!fallbackCheckName)
+        return undefined;
+    const fallback = fallbackCheckName.trim().toLowerCase();
+    return checks.find((entry) => entry.name.trim().toLowerCase() === fallback);
+}
+function pickGateCheckName(gateCheckNames, fallbackCheckName) {
+    return gateCheckNames.find((entry) => entry.trim().length > 0)?.trim()
+        ?? fallbackCheckName?.trim();
+}
+function deriveCheckStatus(params) {
+    const status = params.apiStatus?.trim().toLowerCase();
+    if (status === "queued" || status === "in_progress" || status === "requested" || status === "waiting" || status === "pending") {
+        return "pending";
+    }
+    const conclusion = params.apiConclusion?.trim().toLowerCase()
+        ?? params.eventConclusion?.trim().toLowerCase()
+        ?? params.eventStatus?.trim().toLowerCase();
+    if (conclusion === "success" || conclusion === "neutral" || conclusion === "skipped") {
+        return "success";
+    }
+    if (conclusion && FAILED_CONCLUSIONS.has(conclusion)) {
+        return "failure";
+    }
+    return status === "completed" ? "failure" : "pending";
+}
 function buildFailureSignature(parts) {
     return [
         parts.source,

package/dist/github-webhook-handler.js

@@ -1,5 +1,5 @@
 import { resolveFactoryStateFromGitHub, TERMINAL_STATES } from "./factory-state.js";
-import { createGitHubFailureContextResolver, summarizeGitHubFailureContext, } from "./github-failure-context.js";
+import { createGitHubCiSnapshotResolver, createGitHubFailureContextResolver, summarizeGitHubFailureContext, } from "./github-failure-context.js";
 import { normalizeGitHubWebhook, verifyGitHubWebhookSignature } from "./github-webhooks.js";
 import { buildAgentSessionPlanForIssue } from "./agent-session-plan.js";
 import { buildAgentSessionExternalUrls } from "./agent-session-presentation.js";
@@ -10,12 +10,11 @@ import { resolveSecret } from "./resolve-secret.js";
 import { safeJsonParse } from "./utils.js";
 /**
  * GitHub sends both check_run and check_suite completion events.
- * A single CI run generates 10+ individual check_run events as each job finishes,
- * but only 1 check_suite event when the entire suite completes. Reacting to
- * individual check_run events causes the factory state to flicker rapidly
- * between pr_open and repairing_ci. We only drive state transitions and reactive
- * runs from check_suite events. Individual check_run events still update PR
- * metadata (prCheckStatus) for observability.
+ * A single CI run generates many individual check_run events as each job finishes,
+ * but PatchRelay should only start ci_repair once the configured gate check
+ * (for example `Tests`) has gone terminal for the current PR head SHA. We still
+ * treat most check_run events as metadata-only and only react to queue eviction
+ * checks or the settled gate check.
  */
 function isMetadataOnlyCheckEvent(event) {
     return event.eventSource === "check_run"
@@ -30,7 +29,8 @@ export class GitHubWebhookHandler {
     codex;
     feed;
     failureContextResolver;
-    constructor(config, db, linearProvider, enqueueIssue, logger, codex, feed, failureContextResolver = createGitHubFailureContextResolver()) {
+    ciSnapshotResolver;
+    constructor(config, db, linearProvider, enqueueIssue, logger, codex, feed, failureContextResolver = createGitHubFailureContextResolver(), ciSnapshotResolver = createGitHubCiSnapshotResolver()) {
         this.config = config;
         this.db = db;
         this.linearProvider = linearProvider;
@@ -39,6 +39,7 @@ export class GitHubWebhookHandler {
         this.codex = codex;
         this.feed = feed;
         this.failureContextResolver = failureContextResolver;
+        this.ciSnapshotResolver = ciSnapshotResolver;
     }
     async acceptGitHubWebhook(params) {
         // Deduplicate
@@ -128,6 +129,7 @@ export class GitHubWebhookHandler {
             ...(event.reviewState !== undefined ? { prReviewState: event.reviewState } : {}),
             ...(event.checkStatus !== undefined ? { prCheckStatus: event.checkStatus } : {}),
         });
+        await this.updateCiSnapshot(issue, event, project);
         await this.updateFailureProvenance(issue, event, project);
         if (!isMetadataOnlyCheckEvent(event)) {
             // Re-read issue after PR metadata upsert so guards see fresh prReviewState
@@ -178,6 +180,11 @@ export class GitHubWebhookHandler {
                 lastGitHubFailureCheckUrl: null,
                 lastGitHubFailureContextJson: null,
                 lastGitHubFailureAt: null,
+                lastGitHubCiSnapshotHeadSha: event.headSha ?? null,
+                lastGitHubCiSnapshotGateCheckName: this.getPrimaryGateCheckName(project),
+                lastGitHubCiSnapshotGateCheckStatus: "pending",
+                lastGitHubCiSnapshotJson: null,
+                lastGitHubCiSnapshotSettledAt: null,
                 lastQueueIncidentJson: null,
                 lastAttemptedFailureHeadSha: null,
                 lastAttemptedFailureSignature: null,
@@ -197,14 +204,85 @@ export class GitHubWebhookHandler {
         // Queue eviction check runs bypass the metadata-only filter because
         // they're individual check_run events (not check_suite), but they
         // must drive state transitions.
-        const protocol = resolveMergeQueueProtocol(project);
-        if (event.eventSource === "check_run" && event.checkName === protocol.evictionCheckName) {
+        if (this.isQueueEvictionFailure(freshIssue, event, project) || this.isGateCheckEvent(event, project)) {
             await this.maybeEnqueueReactiveRun(freshIssue, event, project);
         }
         else if (!isMetadataOnlyCheckEvent(event)) {
             await this.maybeEnqueueReactiveRun(freshIssue, event, project);
         }
     }
+    async updateCiSnapshot(issue, event, project) {
+        if (event.triggerEvent === "pr_merged") {
+            this.db.upsertIssue({
+                projectId: issue.projectId,
+                linearIssueId: issue.linearIssueId,
+                lastGitHubCiSnapshotHeadSha: null,
+                lastGitHubCiSnapshotGateCheckName: null,
+                lastGitHubCiSnapshotGateCheckStatus: null,
+                lastGitHubCiSnapshotJson: null,
+                lastGitHubCiSnapshotSettledAt: null,
+            });
+            return;
+        }
+        if (event.triggerEvent === "pr_synchronize") {
+            this.db.upsertIssue({
+                projectId: issue.projectId,
+                linearIssueId: issue.linearIssueId,
+                lastGitHubCiSnapshotHeadSha: event.headSha ?? null,
+                lastGitHubCiSnapshotGateCheckName: this.getPrimaryGateCheckName(project),
+                lastGitHubCiSnapshotGateCheckStatus: "pending",
+                lastGitHubCiSnapshotJson: null,
+                lastGitHubCiSnapshotSettledAt: null,
+            });
+            return;
+        }
+        if (issue.prState !== "open")
+            return;
+        if (event.eventSource !== "check_run")
+            return;
+        if (this.isQueueEvictionFailure(issue, event, project))
+            return;
+        if (!this.isGateCheckEvent(event, project))
+            return;
+        if (this.isStaleGateEvent(issue, event))
+            return;
+        const snapshot = await this.ciSnapshotResolver.resolve({
+            repoFullName: project?.github?.repoFullName ?? event.repoFullName,
+            event,
+            gateCheckNames: this.getGateCheckNames(project),
+        });
+        if (!snapshot) {
+            this.db.upsertIssue({
+                projectId: issue.projectId,
+                linearIssueId: issue.linearIssueId,
+                lastGitHubCiSnapshotHeadSha: event.headSha ?? issue.lastGitHubCiSnapshotHeadSha ?? null,
+                lastGitHubCiSnapshotGateCheckName: this.getPrimaryGateCheckName(project),
+                lastGitHubCiSnapshotGateCheckStatus: "pending",
+                lastGitHubCiSnapshotJson: null,
+                lastGitHubCiSnapshotSettledAt: null,
+            });
+            this.logger.warn({ issueKey: issue.issueKey, repoFullName: project?.github?.repoFullName ?? event.repoFullName, headSha: event.headSha }, "Could not resolve settled CI snapshot; waiting before CI repair");
+            this.feed?.publish({
+                level: "warn",
+                kind: "github",
+                issueKey: issue.issueKey,
+                projectId: issue.projectId,
+                stage: issue.factoryState,
+                status: "ci_snapshot_unavailable",
+                summary: `Could not resolve settled ${this.getPrimaryGateCheckName(project)} snapshot; waiting before CI repair`,
+            });
+            return;
+        }
+        this.db.upsertIssue({
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+            lastGitHubCiSnapshotHeadSha: snapshot.headSha,
+            lastGitHubCiSnapshotGateCheckName: snapshot.gateCheckName ?? this.getPrimaryGateCheckName(project),
+            lastGitHubCiSnapshotGateCheckStatus: snapshot.gateCheckStatus,
+            lastGitHubCiSnapshotJson: JSON.stringify(snapshot),
+            lastGitHubCiSnapshotSettledAt: snapshot.settledAt ?? null,
+        });
+    }
     async maybeEnqueueReactiveRun(issue, event, project) {
         // Don't trigger if there's already an active run
         if (issue.activeRunId !== undefined)
@@ -216,10 +294,7 @@ export class GitHubWebhookHandler {
         if (event.triggerEvent === "check_failed" && issue.prState === "open") {
             // External merge queue eviction: react only to the configured check
             // name, not to any CI failure. Regular CI failures still get ci_repair.
-            const protocol = resolveMergeQueueProtocol(project);
-            const queueCheckName = protocol.evictionCheckName;
-            if (issue.factoryState === "awaiting_queue"
-                && event.checkName === queueCheckName) {
+            if (this.isQueueEvictionFailure(issue, event, project)) {
                 const queueRepairContext = buildQueueRepairContextFromEvent(event);
                 const failureContext = this.buildQueueFailureContext(issue, event, queueRepairContext);
                 if (this.hasDuplicatePendingReactiveRun(issue, "queue_repair", failureContext)) {
@@ -257,10 +332,23 @@ export class GitHubWebhookHandler {
                 });
             }
             else {
+                if (!this.isSettledBranchFailure(issue, event, project)) {
+                    this.feed?.publish({
+                        level: "info",
+                        kind: "github",
+                        issueKey: issue.issueKey,
+                        projectId: issue.projectId,
+                        stage: issue.factoryState,
+                        status: "ci_waiting_for_settlement",
+                        summary: `Waiting for settled ${this.getPrimaryGateCheckName(project)} result before starting CI repair`,
+                    });
+                    return;
+                }
                 const failureContext = await this.resolveBranchFailureContext(issue, event, project);
                 if (this.hasDuplicatePendingReactiveRun(issue, "ci_repair", failureContext)) {
                     return;
                 }
+                const snapshot = this.getRelevantCiSnapshot(issue, event);
                 this.db.upsertIssue({
                     projectId: issue.projectId,
                     linearIssueId: issue.linearIssueId,
@@ -268,6 +356,7 @@ export class GitHubWebhookHandler {
                     pendingRunContextJson: JSON.stringify({
                         ...failureContext,
                         checkClass: resolveCheckClass(failureContext.checkName ?? event.checkName, project),
+                        ...(snapshot ? { ciSnapshot: snapshot } : {}),
                     }),
                     lastGitHubFailureSource: "branch_ci",
                     lastGitHubFailureHeadSha: failureContext.failureHeadSha ?? null,
@@ -307,12 +396,14 @@ export class GitHubWebhookHandler {
         }
     }
     async updateFailureProvenance(issue, event, project) {
-        const protocol = resolveMergeQueueProtocol(project);
-        const isQueueEvictionCheck = event.eventSource === "check_run" && event.checkName === protocol.evictionCheckName;
+        const isQueueEvictionCheck = this.isQueueEvictionFailure(issue, event, project);
         if (event.triggerEvent === "check_failed" && issue.prState === "open") {
-            const source = issue.factoryState === "awaiting_queue" && isQueueEvictionCheck
+            const source = isQueueEvictionCheck
                 ? "queue_eviction"
                 : "branch_ci";
+            if (source === "branch_ci" && !this.isSettledBranchFailure(issue, event, project)) {
+                return;
+            }
             const failureContext = source === "queue_eviction"
                 ? this.buildQueueFailureContext(issue, event)
                 : await this.resolveBranchFailureContext(issue, event, project);
@@ -337,9 +428,12 @@ export class GitHubWebhookHandler {
             });
             return;
         }
-        if ((event.triggerEvent === "check_passed" && (!isMetadataOnlyCheckEvent(event) || isQueueEvictionCheck))
+        if ((event.triggerEvent === "check_passed" && (!isMetadataOnlyCheckEvent(event) || isQueueEvictionCheck || this.isGateCheckEvent(event, project)))
             || event.triggerEvent === "pr_synchronize"
             || event.triggerEvent === "pr_merged") {
+            if (event.triggerEvent === "check_passed" && !this.canClearFailureProvenance(issue, event, project)) {
+                return;
+            }
             this.db.upsertIssue({
                 projectId: issue.projectId,
                 linearIssueId: issue.linearIssueId,
@@ -358,10 +452,19 @@ export class GitHubWebhookHandler {
     }
     async resolveBranchFailureContext(issue, event, project) {
         const repoFullName = project?.github?.repoFullName ?? event.repoFullName;
+        const snapshot = this.getRelevantCiSnapshot(issue, event);
+        const primaryFailedCheck = snapshot ? this.pickPrimaryFailedCheck(snapshot) : undefined;
         const context = await this.failureContextResolver.resolve({
             source: "branch_ci",
             repoFullName,
-            event,
+            event: primaryFailedCheck
+                ? {
+                    ...event,
+                    checkName: primaryFailedCheck.name,
+                    checkUrl: primaryFailedCheck.detailsUrl ?? event.checkUrl,
+                    checkDetailsUrl: primaryFailedCheck.detailsUrl ?? event.checkDetailsUrl,
+                }
+                : event,
         });
         return {
             ...(context ? context : {}),
@@ -433,6 +536,65 @@ export class GitHubWebhookHandler {
         }
         return false;
     }
+    getGateCheckNames(project) {
+        const configured = (project?.gateChecks ?? []).map((entry) => entry.trim()).filter(Boolean);
+        return configured.length > 0 ? configured : ["Tests"];
+    }
+    getPrimaryGateCheckName(project) {
+        return this.getGateCheckNames(project)[0] ?? "Tests";
+    }
+    isGateCheckEvent(event, project) {
+        if (event.eventSource !== "check_run" || !event.checkName)
+            return false;
+        const normalized = event.checkName.trim().toLowerCase();
+        return this.getGateCheckNames(project).some((entry) => entry.trim().toLowerCase() === normalized);
+    }
+    isStaleGateEvent(issue, event) {
+        return Boolean(issue.lastGitHubCiSnapshotHeadSha
+            && event.headSha
+            && issue.lastGitHubCiSnapshotHeadSha !== event.headSha);
+    }
+    isQueueEvictionFailure(issue, event, project) {
+        const protocol = resolveMergeQueueProtocol(project);
+        return issue.factoryState === "awaiting_queue"
+            && event.eventSource === "check_run"
+            && event.checkName === protocol.evictionCheckName;
+    }
+    isSettledBranchFailure(issue, event, project) {
+        if (event.triggerEvent !== "check_failed" || issue.prState !== "open")
+            return false;
+        if (!this.isGateCheckEvent(event, project))
+            return false;
+        const snapshot = this.getRelevantCiSnapshot(issue, event);
+        return snapshot?.gateCheckStatus === "failure" && snapshot.headSha === event.headSha;
+    }
+    canClearFailureProvenance(issue, event, project) {
+        if (event.triggerEvent !== "check_passed")
+            return true;
+        if (this.isQueueEvictionFailure(issue, event, project)) {
+            return !issue.lastGitHubFailureHeadSha || issue.lastGitHubFailureHeadSha === event.headSha;
+        }
+        if (!this.isGateCheckEvent(event, project)) {
+            return true;
+        }
+        if (this.isStaleGateEvent(issue, event)) {
+            return false;
+        }
+        return !issue.lastGitHubFailureHeadSha || issue.lastGitHubFailureHeadSha === event.headSha;
+    }
+    getRelevantCiSnapshot(issue, event) {
+        const snapshot = this.db.getLatestGitHubCiSnapshot(issue.projectId, issue.linearIssueId);
+        if (!snapshot)
+            return undefined;
+        if (snapshot.headSha !== event.headSha)
+            return undefined;
+        return snapshot;
+    }
+    pickPrimaryFailedCheck(snapshot) {
+        const gateName = snapshot.gateCheckName?.trim().toLowerCase();
+        return snapshot.failedChecks.find((entry) => entry.name.trim().toLowerCase() !== gateName)
+            ?? snapshot.failedChecks[0];
+    }
     async emitLinearActivity(issue, newState, event) {
         if (!issue.agentSessionId)
             return;

package/dist/run-orchestrator.js

@@ -57,11 +57,17 @@ function buildRunPrompt(issue, runType, repoPath, context) {
     }
     // Add run-type-specific context for reactive runs
     switch (runType) {
-        case "ci_repair":
-            lines.push("## CI Repair", "", "A CI check has failed on your PR. Fix the failure and push.", context?.failureHeadSha ? `Failing head SHA: ${String(context.failureHeadSha)}` : "", context?.checkName ? `Failed check: ${String(context.checkName)}` : "", context?.jobName && context?.jobName !== context?.checkName ? `Failed job: ${String(context.jobName)}` : "", context?.stepName ? `Failed step: ${String(context.stepName)}` : "", context?.summary ? `Failure summary: ${String(context.summary)}` : "", context?.checkUrl ? `Check URL: ${String(context.checkUrl)}` : "", Array.isArray(context?.annotations) && context.annotations.length > 0
+        case "ci_repair": {
+            const snapshot = context?.ciSnapshot && typeof context.ciSnapshot === "object"
+                ? context.ciSnapshot
+                : undefined;
+            lines.push("## CI Repair", "", "A full CI iteration has settled failed on your PR. Diagnose the whole snapshot, fix the root cause and directly related fallout, then push to the same PR branch.", snapshot?.gateCheckName ? `Gate check: ${String(snapshot.gateCheckName)}` : "", snapshot?.gateCheckStatus ? `Gate status: ${String(snapshot.gateCheckStatus)}` : "", snapshot?.settledAt ? `Settled at: ${String(snapshot.settledAt)}` : "", context?.failureHeadSha ? `Failing head SHA: ${String(context.failureHeadSha)}` : "", context?.checkName ? `Failed check: ${String(context.checkName)}` : "", context?.jobName && context?.jobName !== context?.checkName ? `Failed job: ${String(context.jobName)}` : "", context?.stepName ? `Failed step: ${String(context.stepName)}` : "", context?.summary ? `Failure summary: ${String(context.summary)}` : "", Array.isArray(snapshot?.failedChecks) && snapshot.failedChecks.length > 0
+                ? `All failed checks in settled snapshot:\n${snapshot.failedChecks.map((entry) => `- ${String(entry.name ?? "unknown")}${entry.summary ? `: ${String(entry.summary)}` : ""}`).join("\n")}`
+                : "", context?.checkUrl ? `Check URL: ${String(context.checkUrl)}` : "", Array.isArray(context?.annotations) && context.annotations.length > 0
                 ? `Annotations:\n${context.annotations.map((entry) => `- ${String(entry)}`).join("\n")}`
-                : "", "", "Read the CI failure logs, fix the code issue, run verification, commit and push.", "Do not change test expectations unless the test is genuinely wrong.", "");
+                : "", "", "Read the latest CI logs, consider the broader PR context, fix the likely root cause and any directly related fallout in one pass, run verification, commit and push.", "Do not open a new PR. Keep working on the existing branch until CI goes green or the situation is clearly stuck.", "Do not change test expectations unless the test is genuinely wrong.", "");
             break;
+        }
         case "review_fix":
             lines.push("## Review Changes Requested", "", "A reviewer has requested changes on your PR. Address the feedback and push.", context?.reviewerName ? `Reviewer: ${String(context.reviewerName)}` : "", context?.reviewBody ? `\n## Review comment\n\n${String(context.reviewBody)}` : "", "", "Steps:", "1. Read the review feedback and PR comments (`gh pr view --comments`).", "2. Check the current diff (`git diff origin/main`) — a prior rebase may have already resolved some concerns (e.g., scope-bundling from stale commits).", "3. For each review point: if already resolved, note why. If not, fix it.", "4. Run verification, commit and push.", "5. If you believe all concerns are resolved, request a re-review: `gh pr edit <PR#> --add-reviewer <reviewer>`.", "   Do NOT just post a comment saying \"resolved\" — the reviewer must re-review to dismiss the CHANGES_REQUESTED state.", "");
             break;

package/dist/service.js

@@ -436,7 +436,7 @@ export class PatchRelayService {
         // Infer run type from current state instead of always resetting to implementation
         let runType = "implementation";
         let factoryState = "delegated";
-        if (issue.prNumber && issue.prCheckStatus === "failed") {
+        if (issue.prNumber && (issue.prCheckStatus === "failed" || issue.prCheckStatus === "failure" || issue.lastGitHubFailureSource === "branch_ci")) {
             runType = "ci_repair";
             factoryState = "repairing_ci";
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchrelay",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "license": "MIT",
   "type": "module",
   "repository": {