patchrelay 0.68.3 → 0.68.5

package/dist/cli/cluster-health/index.js

@@ -0,0 +1,168 @@
+import { hasOpenPr } from "../../pr-state.js";
+import { collectActiveOverlapFindings } from "./active-overlap.js";
+import { evaluateLocalIssueHealth, isResolvedDependency, needsReviewAutomation, } from "./local-issue-health.js";
+import { evaluateGitHubIssueHealth } from "./github-issue-health.js";
+import { collectReviewQuillAttemptOwners, } from "./review-quill-probe.js";
+import { probeOptionalService, probePatchRelayService, } from "./service-probe.js";
+import {} from "./shared.js";
+export async function collectClusterHealth(config, db, runCommand) {
+    const checks = [];
+    const ciEntries = [];
+    const now = Date.now();
+    const issues = db.listIssues();
+    const openIssues = issues.filter((issue) => issue.factoryState !== "done");
+    const trackedByKey = new Map(issues
+        .filter((issue) => issue.issueKey)
+        .map((issue) => [issue.issueKey, issue]));
+    const trackedByLinearId = new Map(issues.map((issue) => [issue.linearIssueId, issue]));
+    const patchRelayProbe = await probePatchRelayService(config);
+    checks.push({
+        status: patchRelayProbe.status,
+        scope: "service:patchrelay",
+        message: patchRelayProbe.message,
+    });
+    const snapshots = openIssues.map((issue) => {
+        const tracked = db.getTrackedIssue(issue.projectId, issue.linearIssueId);
+        const deps = db.issues.listIssueDependencies(issue.projectId, issue.linearIssueId);
+        const blockedBy = deps.filter((dep) => !isResolvedDependency(dep));
+        const missingTrackedBlockers = blockedBy.filter((dep) => {
+            if (trackedByLinearId.has(dep.blockerLinearIssueId))
+                return false;
+            if (dep.blockerIssueKey && trackedByKey.has(dep.blockerIssueKey))
+                return false;
+            return true;
+        });
+        return {
+            issue,
+            session: db.issueSessions.getIssueSession(issue.projectId, issue.linearIssueId),
+            blockedBy,
+            missingTrackedBlockers,
+            ageMs: Math.max(0, now - Date.parse(issue.updatedAt || new Date(0).toISOString())),
+            readyForExecution: tracked?.readyForExecution ?? false,
+        };
+    });
+    const reviewRelevantIssues = snapshots.filter((snapshot) => needsReviewAutomation(snapshot.issue));
+    const queueRelevantIssues = snapshots.filter((snapshot) => snapshot.issue.factoryState === "awaiting_queue");
+    const reviewQuillProbe = reviewRelevantIssues.length > 0
+        ? await probeOptionalService(runCommand, "review-quill", {
+            healthy: (payload) => {
+                const parsed = payload;
+                return parsed.health?.reachable === true && parsed.health?.ok === true && parsed.systemd?.ActiveState === "active";
+            },
+            summarize: (payload) => {
+                const parsed = payload;
+                return parsed.health?.reachable === true && parsed.health?.ok === true
+                    ? "Healthy"
+                    : `Unhealthy (${parsed.health?.reachable === false ? "service not reachable" : "service health unavailable"})`;
+            },
+        })
+        : undefined;
+    if (reviewQuillProbe) {
+        checks.push({
+            status: reviewQuillProbe.status,
+            scope: "service:review-quill",
+            message: reviewQuillProbe.message,
+        });
+    }
+    const reviewQuillAttemptOwners = reviewQuillProbe?.status === "pass"
+        ? await collectReviewQuillAttemptOwners(reviewRelevantIssues, config, runCommand)
+        : new Map();
+    const mergeStewardProbe = queueRelevantIssues.length > 0
+        ? await probeOptionalService(runCommand, "merge-steward", {
+            healthy: (payload) => {
+                const parsed = payload;
+                return parsed.health?.reachable === true && parsed.health?.ok === true && parsed.systemd?.ActiveState === "active";
+            },
+            summarize: (payload) => {
+                const parsed = payload;
+                return parsed.health?.reachable === true && parsed.health?.ok === true && parsed.systemd?.ActiveState === "active"
+                    ? "Healthy"
+                    : `Unhealthy (${parsed.health?.reachable === false ? "service not reachable" : parsed.systemd?.ActiveState ?? "unknown"})`;
+            },
+        })
+        : undefined;
+    if (mergeStewardProbe) {
+        checks.push({
+            status: mergeStewardProbe.status,
+            scope: "service:merge-steward",
+            message: mergeStewardProbe.message,
+        });
+    }
+    for (const snapshot of snapshots) {
+        const finding = evaluateLocalIssueHealth(snapshot);
+        if (finding) {
+            checks.push({
+                ...finding,
+                ...(snapshot.issue.issueKey ? { issueKey: snapshot.issue.issueKey } : {}),
+                projectId: snapshot.issue.projectId,
+                ...(snapshot.issue.prNumber !== undefined ? { prNumber: snapshot.issue.prNumber } : {}),
+            });
+        }
+    }
+    checks.push(...await collectActiveOverlapFindings(snapshots, runCommand));
+    for (const snapshot of snapshots) {
+        if (!hasOpenPr(snapshot.issue.prNumber, snapshot.issue.prState)) {
+            continue;
+        }
+        const githubHealth = await evaluateGitHubIssueHealth(snapshot, config, runCommand, reviewQuillProbe, reviewQuillAttemptOwners, mergeStewardProbe);
+        if (githubHealth.ciEntry) {
+            ciEntries.push(githubHealth.ciEntry);
+        }
+        if (githubHealth.finding) {
+            checks.push({
+                ...githubHealth.finding,
+                ...(snapshot.issue.issueKey ? { issueKey: snapshot.issue.issueKey } : {}),
+                projectId: snapshot.issue.projectId,
+                prNumber: snapshot.issue.prNumber,
+            });
+        }
+    }
+    const workflowFailures = checks.filter((check) => check.scope.startsWith("issue:") || check.scope.startsWith("github:"));
+    if (workflowFailures.every((check) => check.status === "pass" || check.status === "warn") && openIssues.length > 0) {
+        checks.push({
+            status: "pass",
+            scope: "workflow",
+            message: `All ${openIssues.length} non-done issues currently have active work, a tracked blocker, or a downstream owner`,
+        });
+    }
+    if (openIssues.length === 0) {
+        checks.push({
+            status: "pass",
+            scope: "workflow",
+            message: "No non-done issues are currently tracked",
+        });
+    }
+    if (ciEntries.length > 0) {
+        const orphanedCi = ciEntries.filter((entry) => entry.orphaned);
+        checks.push({
+            status: orphanedCi.length === 0 ? "pass" : "fail",
+            scope: "ci",
+            message: orphanedCi.length === 0
+                ? `Tracked ${ciEntries.length} PR-backed issue${ciEntries.length === 1 ? "" : "s"} and each PR has a visible next owner`
+                : `${orphanedCi.length} PR-backed issue${orphanedCi.length === 1 ? "" : "s"} ha${orphanedCi.length === 1 ? "s" : "ve"} no visible next owner`,
+        });
+    }
+    const summary = {
+        trackedIssues: issues.length,
+        openIssues: openIssues.length,
+        activeRuns: openIssues.filter((issue) => issue.activeRunId !== undefined).length,
+        blockedIssues: snapshots.filter((snapshot) => snapshot.blockedBy.length > 0).length,
+        readyIssues: snapshots.filter((snapshot) => snapshot.readyForExecution).length,
+        ciTrackedPrs: ciEntries.length,
+        ciPending: ciEntries.filter((entry) => entry.gateStatus === "pending").length,
+        ciSuccess: ciEntries.filter((entry) => entry.gateStatus === "success").length,
+        ciFailure: ciEntries.filter((entry) => entry.gateStatus === "failure").length,
+        ciUnknown: ciEntries.filter((entry) => entry.gateStatus === "unknown").length,
+        ciOrphaned: ciEntries.filter((entry) => entry.orphaned).length,
+        passCount: checks.filter((check) => check.status === "pass").length,
+        warnCount: checks.filter((check) => check.status === "warn").length,
+        failCount: checks.filter((check) => check.status === "fail").length,
+    };
+    return {
+        generatedAt: new Date().toISOString(),
+        ok: summary.failCount === 0,
+        summary,
+        checks,
+        ci: ciEntries,
+    };
+}

package/dist/cli/cluster-health/local-issue-health.js

@@ -0,0 +1,91 @@
+import { ACTIVE_RUN_STATES } from "../../factory-state.js";
+import { isUndelegatedPausedNoPrWork } from "../../paused-issue-state.js";
+import { hasOpenPr } from "../../pr-state.js";
+import { DOWNSTREAM_STALE_MS, RECONCILIATION_GRACE_MS } from "./shared.js";
+export function isResolvedDependency(dep) {
+    const stateType = dep.blockerCurrentLinearStateType?.trim().toLowerCase();
+    const state = dep.blockerCurrentLinearState?.trim().toLowerCase();
+    return stateType === "completed"
+        || stateType === "canceled"
+        || stateType === "cancelled"
+        || state === "done"
+        || state === "canceled"
+        || state === "cancelled";
+}
+export function needsReviewAutomation(issue) {
+    if (issue.factoryState === "awaiting_queue" || issue.factoryState === "done") {
+        return false;
+    }
+    return hasOpenPr(issue.prNumber, issue.prState);
+}
+export function evaluateLocalIssueHealth(snapshot) {
+    const { issue, session, missingTrackedBlockers, blockedBy, ageMs, readyForExecution } = snapshot;
+    const pausedNoPrWork = isUndelegatedPausedNoPrWork(issue);
+    if (issue.factoryState === "failed" || issue.factoryState === "escalated") {
+        return {
+            status: "fail",
+            scope: "issue:terminal",
+            message: `Issue is in terminal failure state ${issue.factoryState}`,
+        };
+    }
+    if (missingTrackedBlockers.length > 0) {
+        return {
+            status: "fail",
+            scope: "issue:blockers",
+            message: `Blocked by unmanaged issue${missingTrackedBlockers.length === 1 ? "" : "s"} ${missingTrackedBlockers.map((dep) => dep.blockerIssueKey ?? dep.blockerLinearIssueId).join(", ")}`,
+        };
+    }
+    if (issue.activeRunId !== undefined && session?.sessionState !== "running") {
+        return {
+            status: "fail",
+            scope: "issue:run-state",
+            message: `Issue has active run #${issue.activeRunId} but session state is ${session?.sessionState ?? "missing"}`,
+        };
+    }
+    if (issue.activeRunId === undefined && session?.sessionState === "running") {
+        return {
+            status: "fail",
+            scope: "issue:run-state",
+            message: "Issue session is marked running but no active run is attached",
+        };
+    }
+    if (blockedBy.length > 0) {
+        return undefined;
+    }
+    if (readyForExecution && issue.activeRunId === undefined && ageMs >= RECONCILIATION_GRACE_MS) {
+        return {
+            status: "fail",
+            scope: "issue:dispatch",
+            message: "Issue is ready for execution but no active run has started",
+        };
+    }
+    if (!pausedNoPrWork && ACTIVE_RUN_STATES.has(issue.factoryState) && issue.activeRunId === undefined && ageMs >= RECONCILIATION_GRACE_MS) {
+        return {
+            status: "fail",
+            scope: "issue:dispatch",
+            message: `Issue is parked in ${issue.factoryState} without an active run`,
+        };
+    }
+    if (!pausedNoPrWork && issue.factoryState === "delegated" && issue.activeRunId === undefined && !readyForExecution && ageMs >= RECONCILIATION_GRACE_MS) {
+        return {
+            status: "fail",
+            scope: "issue:dispatch",
+            message: "Delegated issue is idle but no wake is queued",
+        };
+    }
+    if (issue.factoryState === "awaiting_input" && ageMs >= RECONCILIATION_GRACE_MS) {
+        return {
+            status: "warn",
+            scope: "issue:operator",
+            message: "Issue is waiting on operator input",
+        };
+    }
+    if (issue.factoryState === "awaiting_queue" && ageMs >= DOWNSTREAM_STALE_MS) {
+        return {
+            status: "warn",
+            scope: "issue:downstream",
+            message: "Issue has been waiting on downstream merge automation for a long time",
+        };
+    }
+    return undefined;
+}

package/dist/cli/cluster-health/review-quill-probe.js

@@ -0,0 +1,126 @@
+import { probeGitHubPullRequest } from "./github-probe.js";
+import { safeJsonParse } from "./shared.js";
+export async function collectReviewQuillAttemptOwners(snapshots, config, runCommand) {
+    const owners = new Map();
+    const repoBacklog = await probeReviewQuillRepoBacklog(runCommand);
+    for (const snapshot of snapshots) {
+        const issueKey = snapshot.issue.issueKey;
+        const prNumber = snapshot.issue.prNumber;
+        if (!issueKey || prNumber === undefined)
+            continue;
+        const project = config.projects.find((entry) => entry.id === snapshot.issue.projectId);
+        const repoFullName = project?.github?.repoFullName;
+        if (!repoFullName)
+            continue;
+        const probe = await probeReviewQuillAttempts(runCommand, repoFullName, prNumber);
+        if (!probe.ok)
+            continue;
+        const activeAttempt = probe.attempts.find((attempt) => (attempt.status === "queued" || attempt.status === "running")
+            && !attempt.stale
+            && attempt.headSha === probe.currentHeadSha);
+        if (!activeAttempt) {
+            if (repoBacklog.has(repoFullName)) {
+                owners.set(issueKey, { backlog: true, headSha: probe.latestAttemptHeadSha });
+            }
+            continue;
+        }
+        owners.set(issueKey, {
+            id: activeAttempt.id,
+            status: activeAttempt.status,
+            headSha: activeAttempt.headSha,
+        });
+    }
+    return owners;
+}
+export async function probeReviewQuillRepoBacklog(runCommand) {
+    let result;
+    try {
+        result = await runCommand("review-quill", ["status", "--json"]);
+    }
+    catch {
+        return new Set();
+    }
+    if (result.exitCode !== 0) {
+        return new Set();
+    }
+    const parsed = safeJsonParse(result.stdout);
+    if (!parsed || parsed.runtime?.reconcileInProgress !== true || !Array.isArray(parsed.repos)) {
+        return new Set();
+    }
+    const activeRepos = new Set();
+    for (const repo of parsed.repos) {
+        if (!repo || typeof repo !== "object")
+            continue;
+        const repoFullName = typeof repo.repoFullName === "string"
+            ? String(repo.repoFullName).trim()
+            : undefined;
+        const runningAttempts = typeof repo.runningAttempts === "number"
+            ? Number(repo.runningAttempts)
+            : 0;
+        const queuedAttempts = typeof repo.queuedAttempts === "number"
+            ? Number(repo.queuedAttempts)
+            : 0;
+        if (!repoFullName)
+            continue;
+        if (runningAttempts > 0 || queuedAttempts > 0) {
+            activeRepos.add(repoFullName);
+        }
+    }
+    return activeRepos;
+}
+export async function probeReviewQuillAttempts(runCommand, repoFullName, prNumber) {
+    const repoRef = repoFullName.split("/").at(-1);
+    if (!repoRef) {
+        return { ok: false, error: `Unable to derive review-quill repo id from ${repoFullName}` };
+    }
+    let attemptsResult;
+    try {
+        attemptsResult = await runCommand("review-quill", ["attempts", repoRef, String(prNumber), "--json"]);
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    if (attemptsResult.exitCode !== 0) {
+        return {
+            ok: false,
+            error: [attemptsResult.stderr.trim(), attemptsResult.stdout.trim()].filter(Boolean).join(" ") || `review-quill exited ${attemptsResult.exitCode}`,
+        };
+    }
+    const parsedAttempts = safeJsonParse(attemptsResult.stdout);
+    if (!parsedAttempts || !Array.isArray(parsedAttempts.attempts)) {
+        return { ok: false, error: "invalid JSON from review-quill attempts" };
+    }
+    const prProbe = await probeGitHubPullRequest(runCommand, repoFullName, prNumber);
+    if (!prProbe.ok) {
+        return { ok: false, error: prProbe.error };
+    }
+    let latestAttemptHeadSha;
+    const attempts = parsedAttempts.attempts.flatMap((entry) => {
+        if (!entry || typeof entry !== "object")
+            return [];
+        const id = entry.id;
+        const headSha = entry.headSha;
+        const status = entry.status;
+        const stale = entry.stale;
+        if (!latestAttemptHeadSha && typeof headSha === "string" && headSha.trim().length > 0) {
+            latestAttemptHeadSha = headSha.trim();
+        }
+        if (typeof id !== "number"
+            || typeof headSha !== "string"
+            || (status !== "queued" && status !== "running")) {
+            return [];
+        }
+        return [{
+                id,
+                headSha,
+                status: status,
+                stale: stale === true,
+            }];
+    });
+    return {
+        ok: true,
+        currentHeadSha: prProbe.pr.headRefOid,
+        latestAttemptHeadSha,
+        attempts,
+    };
+}

package/dist/cli/cluster-health/service-probe.js

@@ -0,0 +1,65 @@
+import { safeJsonParse } from "./shared.js";
+export async function probePatchRelayService(config) {
+    const host = config.server.bind === "0.0.0.0" ? "127.0.0.1" : config.server.bind;
+    const healthUrl = `http://${host}:${config.server.port}${config.server.healthPath}`;
+    const readyUrl = `http://${host}:${config.server.port}${config.server.readinessPath}`;
+    try {
+        const [healthResponse, readyResponse] = await Promise.all([
+            fetch(healthUrl, { signal: AbortSignal.timeout(2_000) }),
+            fetch(readyUrl, { signal: AbortSignal.timeout(2_000) }),
+        ]);
+        const healthBody = await healthResponse.json();
+        const readyBody = await readyResponse.json();
+        if (healthResponse.ok && readyResponse.ok && readyBody.ready) {
+            return {
+                status: "pass",
+                message: `Healthy${healthBody.version ? ` (v${healthBody.version})` : ""}`,
+            };
+        }
+        return {
+            status: "fail",
+            message: `Reachable but not ready${readyBody.codexStarted === false || readyBody.linearConnected === false
+                ? ` (${[
+                    readyBody.codexStarted === false ? "codex not started" : undefined,
+                    readyBody.linearConnected === false ? "Linear not connected" : undefined,
+                ].filter(Boolean).join(", ")})`
+                : ""}`,
+        };
+    }
+    catch (error) {
+        return {
+            status: "fail",
+            message: `Unavailable: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+export async function probeOptionalService(runCommand, binary, options) {
+    let result;
+    try {
+        result = await runCommand(binary, ["service", "status", "--json"]);
+    }
+    catch (error) {
+        return {
+            status: "warn",
+            message: `Unavailable: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (result.exitCode !== 0) {
+        const errorText = [result.stderr.trim(), result.stdout.trim()].filter(Boolean).join(" ");
+        return {
+            status: "warn",
+            message: `Unavailable: ${errorText || `${binary} service status exited ${result.exitCode}`}`,
+        };
+    }
+    const payload = safeJsonParse(result.stdout);
+    if (!payload) {
+        return {
+            status: "warn",
+            message: "Unavailable: unable to parse JSON status output",
+        };
+    }
+    return {
+        status: options.healthy(payload) ? "pass" : "fail",
+        message: options.summarize(payload),
+    };
+}

package/dist/cli/cluster-health/shared.js

@@ -0,0 +1,13 @@
+export const RECONCILIATION_GRACE_MS = 120_000;
+export const DOWNSTREAM_STALE_MS = 900_000;
+export function safeJsonParse(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cli/cluster-health/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/commands/cluster.js

@@ -1,4 +1,4 @@
-import { collectClusterHealth } from "../cluster-health.js";
+import { collectClusterHealth } from "../cluster-health/index.js";
 import { CliUsageError } from "../errors.js";
 import { formatJson } from "../formatters/json.js";
 import { writeOutput } from "../output.js";

package/dist/codex-app-server.js

@@ -286,12 +286,22 @@ export class CodexAppServerClient extends EventEmitter {
                 },
             });
         });
-        this.writeMessage({
-            jsonrpc: "2.0",
-            id,
-            method,
-            params,
-        });
+        try {
+            this.writeMessage({
+                jsonrpc: "2.0",
+                id,
+                method,
+                params,
+            });
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            const pending = this.pending.get(id);
+            if (pending) {
+                this.pending.delete(id);
+                pending.reject(err);
+            }
+        }
         return promise.catch((error) => {
             const err = error instanceof Error ? error : new Error(String(error));
             this.logger.error({
@@ -390,10 +400,37 @@ export class CodexAppServerClient extends EventEmitter {
         }
     }
     writeMessage(message) {
-        if (!this.child?.stdin) {
-            throw new Error("Codex app-server stdin is unavailable");
+        const child = this.child;
+        const stdin = child?.stdin;
+        if (!stdin || stdin.destroyed || stdin.writableEnded || !stdin.writable) {
+            const error = new Error("Codex app-server stdin is closed");
+            this.handleTransportFailure(error);
+            throw error;
         }
-        this.child.stdin.write(`${JSON.stringify(message)}\n`);
+        try {
+            stdin.write(`${JSON.stringify(message)}\n`, (error) => {
+                if (error) {
+                    this.handleTransportFailure(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.handleTransportFailure(err);
+            throw err;
+        }
+    }
+    handleTransportFailure(error) {
+        const child = this.child;
+        this.started = false;
+        this.child = undefined;
+        this.stdoutBuffer = "";
+        this.logger.error({
+            error: sanitizeDiagnosticText(error.message),
+            pendingRequestCount: this.pending.size,
+        }, "Codex app-server transport failed");
+        this.rejectAllPending(error);
+        child?.kill("SIGTERM");
     }
     drainMessages() {
         while (true) {

package/dist/idle-reconciliation.js

@@ -1,4 +1,4 @@
-import { buildBranchUpkeepContext, buildFailureContext, getGateCheckNames, hasCompletedReviewQuillVerdict, hasFailureProvenance, isDuplicateRepairAttempt, isFailingCheckStatus, isReviewDecisionApproved, isReviewDecisionChangesRequested, isReviewDecisionReviewRequired, } from "./idle-reconciliation-helpers.js";
+import { buildBranchUpkeepContext, buildFailureContext, getGateCheckNames, hasCompletedReviewQuillVerdict, hasFailureProvenance, isDuplicateRepairAttempt, isFailingCheckStatus, isReviewDecisionApproved, isReviewDecisionReviewRequired, } from "./idle-reconciliation-helpers.js";
 import { isMainRepairIssue } from "./main-repair.js";
 import { resolveMergeQueueProtocol } from "./merge-queue-protocol.js";
 import { deriveGateCheckStatusFromRollup } from "./github-rollup.js";
@@ -6,6 +6,8 @@ import { deriveIssueSessionReactiveIntent } from "./issue-session.js";
 import { buildClosedPrCleanupFields, resolveClosedPrDisposition } from "./pr-state.js";
 import { getReviewFixBudget } from "./run-budgets.js";
 import { queueSettledOrchestrationIssue } from "./orchestration-parent-wake.js";
+import { fetchPullRequestSnapshot } from "./reconcile-pr-fetch.js";
+import { buildPrStateUpdates } from "./reconcile-pr-state-updates.js";
 import { execCommand } from "./utils.js";
 export class IdleIssueReconciler {
     db;
@@ -373,13 +375,18 @@ export class IdleIssueReconciler {
         const project = this.config.projects.find((p) => p.id === issue.projectId);
         if (!project?.github?.repoFullName || !issue.prNumber)
             return;
-        try {
-            const { stdout } = await execCommand("gh", [
-                "pr", "view", String(issue.prNumber),
-                "--repo", project.github.repoFullName,
-                "--json", "headRefOid,state,reviewDecision,mergeable,mergeStateStatus,statusCheckRollup",
-            ], { timeoutMs: 10_000 });
-            const pr = JSON.parse(stdout);
+        const snapshot = await fetchPullRequestSnapshot(project.github.repoFullName, issue.prNumber);
+        if (!snapshot.ok) {
+            this.logger.debug({ issueKey: issue.issueKey, error: snapshot.error.message }, "Failed to query GitHub PR state during reconciliation");
+            if (issue.prReviewState === "approved") {
+                if (issue.factoryState !== "awaiting_queue" || hasFailureProvenance(issue)) {
+                    this.advanceIdleIssue(issue, "awaiting_queue", hasFailureProvenance(issue) ? { clearFailureProvenance: true } : {});
+                }
+            }
+            return;
+        }
+        const pr = snapshot.pr;
+        {
             const previousHeadSha = issue.prHeadSha;
             const gateCheckNames = getGateCheckNames(project);
             const gateCheckStatus = deriveGateCheckStatusFromRollup(pr.statusCheckRollup, gateCheckNames);
@@ -389,24 +396,7 @@ export class IdleIssueReconciler {
             this.db.issues.upsertIssue({
                 projectId: issue.projectId,
                 linearIssueId: issue.linearIssueId,
-                ...(pr.headRefOid ? { prHeadSha: pr.headRefOid } : {}),
-                ...(pr.state === "OPEN" ? { prState: "open" } : {}),
-                ...(isReviewDecisionApproved(pr.reviewDecision)
-                    ? { prReviewState: "approved" }
-                    : isReviewDecisionChangesRequested(pr.reviewDecision)
-                        ? { prReviewState: "changes_requested" }
-                        : isReviewDecisionReviewRequired(pr.reviewDecision)
-                            ? { prReviewState: "commented" }
-                            : {}),
-                ...(gateCheckStatus ? { prCheckStatus: gateCheckStatus } : {}),
-                ...(pr.headRefOid && gateCheckStatus
-                    ? {
-                        lastGitHubCiSnapshotHeadSha: pr.headRefOid,
-                        lastGitHubCiSnapshotGateCheckName: gateCheckNames[0] ?? "verify",
-                        lastGitHubCiSnapshotGateCheckStatus: gateCheckStatus,
-                        lastGitHubCiSnapshotSettledAt: gateCheckStatus === "pending" ? null : new Date().toISOString(),
-                    }
-                    : {}),
+                ...buildPrStateUpdates(pr, gateCheckStatus, gateCheckNames[0] ?? "verify"),
             });
             if (pr.state === "MERGED") {
                 this.db.issues.upsertIssue({ projectId: issue.projectId, linearIssueId: issue.linearIssueId, prState: "merged" });
@@ -600,16 +590,6 @@ export class IdleIssueReconciler {
                 this.logger.debug({ issueKey: issue.issueKey, prNumber: issue.prNumber, mergeable: pr.mergeable, mergeStateStatus: pr.mergeStateStatus }, "Reconciliation: PR is dirty but no automation owner was derived");
             }
         }
-        catch (error) {
-            this.logger.debug({ issueKey: issue.issueKey, error: error instanceof Error ? error.message : String(error) }, "Failed to query GitHub PR state during reconciliation");
-            if (issue.prReviewState === "approved") {
-                if (issue.factoryState !== "awaiting_queue" || hasFailureProvenance(issue)) {
-                    this.advanceIdleIssue(issue, "awaiting_queue", {
-                        ...(hasFailureProvenance(issue) ? { clearFailureProvenance: true } : {}),
-                    });
-                }
-            }
-        }
     }
     deriveTerminalRecoveryState(issue, reviewDecision, gateCheckStatus, headAdvanced) {
         if (issue.factoryState !== "escalated" && issue.factoryState !== "failed") {

package/dist/reconcile-pr-fetch.js

@@ -0,0 +1,23 @@
+import { execCommand } from "./utils.js";
+/**
+ * Snapshots a PR via `gh pr view --json`, used during idle reconciliation
+ * to verify the local state machine against fresh GitHub truth before
+ * dispatching repair runs.
+ *
+ * Caller is responsible for logging / acting on `ok: false`; this helper
+ * never throws.
+ */
+export async function fetchPullRequestSnapshot(repoFullName, prNumber, options = {}) {
+    try {
+        const { stdout } = await execCommand("gh", [
+            "pr", "view", String(prNumber),
+            "--repo", repoFullName,
+            "--json", "headRefOid,state,reviewDecision,mergeable,mergeStateStatus,statusCheckRollup",
+        ], { timeoutMs: options.timeoutMs ?? 10_000 });
+        const pr = JSON.parse(stdout);
+        return { ok: true, pr };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error : new Error(String(error)) };
+    }
+}