patchrelay 0.68.3 → 0.68.4

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "service": "patchrelay",
-  "version": "0.68.3",
-  "commit": "e2b544833efd",
-  "builtAt": "2026-05-15T11:45:23.425Z"
+  "version": "0.68.4",
+  "commit": "7680b548a651",
+  "builtAt": "2026-05-15T11:58:17.825Z"
 }

package/dist/cli/cluster-health/active-overlap.js

@@ -0,0 +1,64 @@
+export async function collectActiveOverlapFindings(snapshots, runCommand) {
+    const findings = [];
+    const diffsByProject = new Map();
+    for (const snapshot of snapshots) {
+        const { issue } = snapshot;
+        if (issue.activeRunId === undefined || !issue.worktreePath) {
+            continue;
+        }
+        const files = await listModifiedTrackedFiles(runCommand, issue.worktreePath);
+        if (files.size === 0) {
+            continue;
+        }
+        const projectDiffs = diffsByProject.get(issue.projectId) ?? [];
+        projectDiffs.push({ issue, files });
+        diffsByProject.set(issue.projectId, projectDiffs);
+    }
+    for (const [projectId, diffs] of diffsByProject) {
+        for (let leftIndex = 0; leftIndex < diffs.length; leftIndex += 1) {
+            const left = diffs[leftIndex];
+            for (let rightIndex = leftIndex + 1; rightIndex < diffs.length; rightIndex += 1) {
+                const right = diffs[rightIndex];
+                const overlap = [...left.files].filter((file) => right.files.has(file)).sort();
+                if (overlap.length === 0) {
+                    continue;
+                }
+                findings.push({
+                    status: "warn",
+                    scope: "issue:overlap",
+                    message: `Active work overlaps with ${right.issue.issueKey ?? right.issue.linearIssueId}: ${overlap.slice(0, 3).join(", ")}${overlap.length > 3 ? " ..." : ""}`,
+                    ...(left.issue.issueKey ? { issueKey: left.issue.issueKey } : {}),
+                    projectId,
+                });
+            }
+        }
+    }
+    return findings;
+}
+export async function listModifiedTrackedFiles(runCommand, worktreePath) {
+    let result;
+    try {
+        result = await runCommand("git", ["-C", worktreePath, "status", "--porcelain", "--untracked-files=no"]);
+    }
+    catch {
+        return new Set();
+    }
+    if (result.exitCode !== 0) {
+        return new Set();
+    }
+    const files = new Set();
+    for (const line of result.stdout.split("\n")) {
+        if (line.trim().length === 0)
+            continue;
+        const rawPath = line.slice(3).trim();
+        if (!rawPath)
+            continue;
+        const normalized = rawPath.includes(" -> ")
+            ? rawPath.split(" -> ").at(-1)?.trim()
+            : rawPath;
+        if (normalized) {
+            files.add(normalized);
+        }
+    }
+    return files;
+}

package/dist/cli/cluster-health/ci-classification.js

@@ -0,0 +1,186 @@
+import { deriveGateCheckStatusFromRollup } from "../../github-rollup.js";
+export function getGateCheckNames(project) {
+    const configured = project?.gateChecks?.map((entry) => entry.trim()).filter(Boolean) ?? [];
+    return configured.length > 0 ? configured : ["verify"];
+}
+export function deriveCiGateStatus(statusCheckRollup, gateCheckNames) {
+    const gateStatus = deriveGateCheckStatusFromRollup(statusCheckRollup, gateCheckNames);
+    if (gateStatus) {
+        return gateStatus;
+    }
+    const entries = Array.isArray(statusCheckRollup) ? statusCheckRollup : [];
+    if (entries.length === 0) {
+        return "unknown";
+    }
+    const hasPending = entries.some((entry) => {
+        const status = entry.status?.trim().toLowerCase();
+        return status === "queued" || status === "in_progress" || status === "requested" || status === "waiting" || status === "pending";
+    });
+    if (hasPending) {
+        return "pending";
+    }
+    return "unknown";
+}
+export function deriveCiOwner(params) {
+    if (params.activeRunId !== undefined) {
+        return "patchrelay";
+    }
+    const headAdvancedPastBlockingReview = Boolean(params.currentHeadSha
+        && params.latestBlockingReviewHeadSha
+        && params.currentHeadSha !== params.latestBlockingReviewHeadSha);
+    if (params.gateCheckStatus === "failure") {
+        if (!params.delegatedToPatchRelay)
+            return "paused";
+        return params.factoryState === "repairing_ci" ? "patchrelay" : "unknown";
+    }
+    if (params.gateCheckStatus === "pending") {
+        return "external";
+    }
+    if (params.factoryState === "awaiting_queue" || params.reviewDecision === "APPROVED") {
+        if (params.mergeConflictDetected && !params.delegatedToPatchRelay) {
+            return "paused";
+        }
+        return params.mergeConflictDetected && params.factoryState !== "repairing_queue"
+            ? "unknown"
+            : "downstream";
+    }
+    if (params.reviewDecision === "CHANGES_REQUESTED") {
+        if (params.mergeConflictDetected) {
+            if (!params.delegatedToPatchRelay)
+                return "paused";
+            return params.factoryState === "changes_requested" ? "patchrelay" : "unknown";
+        }
+        if (!params.delegatedToPatchRelay)
+            return "paused";
+        if (params.factoryState === "changes_requested")
+            return "patchrelay";
+        if (params.reviewQuillAttempt?.backlog
+            && params.currentHeadSha
+            && params.reviewQuillAttempt.headSha
+            && params.currentHeadSha !== params.reviewQuillAttempt.headSha) {
+            return "review-quill";
+        }
+        if (params.reviewQuillAttempt && !params.reviewQuillAttempt.backlog)
+            return "review-quill";
+        if (headAdvancedPastBlockingReview)
+            return "reviewer";
+        return "unknown";
+    }
+    if (params.reviewDecision === "REVIEW_REQUIRED") {
+        if (params.reviewQuillAttempt)
+            return "review-quill";
+        if (params.gateCheckStatus === "success")
+            return "reviewer";
+        return params.reviewRequested ? "reviewer" : "unknown";
+    }
+    if (params.gateCheckStatus === "success" && params.factoryState === "pr_open") {
+        return "reviewer";
+    }
+    return "external";
+}
+export function describeCiOwnership(params) {
+    const blockingReviewTargetsCurrentHead = Boolean(params.currentHeadSha
+        && params.latestBlockingReviewHeadSha
+        && params.currentHeadSha === params.latestBlockingReviewHeadSha);
+    const headAdvancedPastBlockingReview = Boolean(params.currentHeadSha
+        && params.latestBlockingReviewHeadSha
+        && params.currentHeadSha !== params.latestBlockingReviewHeadSha);
+    if (params.owner === "patchrelay") {
+        if (params.mergeConflictDetected) {
+            return "PatchRelay owns the next branch-upkeep move";
+        }
+        return params.gateCheckStatus === "failure"
+            ? "PatchRelay owns the next CI repair move"
+            : "PatchRelay owns the next requested-changes move";
+    }
+    if (params.owner === "review-quill") {
+        if (params.reviewQuillAttempt?.backlog) {
+            return "review-quill is actively reconciling this repo; this PR is waiting in the current review backlog";
+        }
+        return params.reviewQuillAttempt?.id && params.reviewQuillAttempt.status
+            ? `review-quill attempt #${params.reviewQuillAttempt.id} is ${params.reviewQuillAttempt.status} on the current head`
+            : "review-quill owns the current review attempt";
+    }
+    if (params.owner === "reviewer") {
+        if (headAdvancedPastBlockingReview) {
+            return "Waiting on review of a newer pushed head";
+        }
+        return params.reviewRequested
+            ? "Waiting on an active reviewer request"
+            : "Waiting on review of the current head";
+    }
+    if (params.owner === "downstream") {
+        return params.mergeConflictDetected
+            ? "Downstream merge automation is expected to repair or requeue this PR"
+            : "Downstream merge automation owns the next move";
+    }
+    if (params.owner === "external") {
+        return params.gateCheckStatus === "pending"
+            ? "Waiting on external CI checks to settle"
+            : "Waiting on external GitHub automation";
+    }
+    if (params.owner === "paused") {
+        if (params.gateCheckStatus === "failure") {
+            return "PatchRelay is paused; delegate the issue again to repair failing CI";
+        }
+        if (params.reviewDecision === "CHANGES_REQUESTED") {
+            return params.mergeConflictDetected
+                ? "PatchRelay is paused; delegate the issue again to repair the blocked PR branch"
+                : "PatchRelay is paused; delegate the issue again to address requested changes";
+        }
+        if (params.mergeConflictDetected) {
+            return "PatchRelay is paused; delegate the issue again to repair this merge conflict";
+        }
+        return "PatchRelay is paused; no automatic repair will start until the issue is delegated again";
+    }
+    if (params.reviewDecision === "CHANGES_REQUESTED") {
+        if (params.mergeConflictDetected) {
+            return headAdvancedPastBlockingReview
+                ? "PR is still dirty after a newer pushed head and no branch-upkeep run is active"
+                : "PR is still dirty on the current blocked head and no branch-upkeep run is active";
+        }
+        return blockingReviewTargetsCurrentHead
+            ? "Requested changes still block the same head and no fix run is active"
+            : "Waiting on review after a newer pushed head";
+    }
+    if (params.reviewDecision === "REVIEW_REQUIRED") {
+        return "Waiting on review of the current head";
+    }
+    return "No visible next owner for this PR state";
+}
+export function buildCiEntry(params) {
+    const { issue, delegatedToPatchRelay, gateCheckStatus, reviewDecision, reviewRequested, currentHeadSha, latestBlockingReviewHeadSha, mergeConflictDetected, reviewQuillAttempt, } = params;
+    const owner = deriveCiOwner({
+        delegatedToPatchRelay,
+        gateCheckStatus,
+        activeRunId: issue.activeRunId,
+        factoryState: issue.factoryState,
+        reviewDecision,
+        reviewRequested,
+        currentHeadSha,
+        latestBlockingReviewHeadSha,
+        mergeConflictDetected,
+        reviewQuillAttempt,
+    });
+    return {
+        ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
+        projectId: issue.projectId,
+        prNumber: issue.prNumber,
+        gateStatus: gateCheckStatus,
+        owner,
+        orphaned: owner === "unknown",
+        factoryState: issue.factoryState,
+        ...(reviewDecision ? { reviewDecision } : {}),
+        message: describeCiOwnership({
+            delegatedToPatchRelay,
+            gateCheckStatus,
+            owner,
+            reviewDecision,
+            reviewRequested,
+            currentHeadSha,
+            latestBlockingReviewHeadSha,
+            mergeConflictDetected,
+            reviewQuillAttempt,
+        }),
+    };
+}

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

@@ -0,0 +1,212 @@
+import { resolveClosedPrDisposition } from "../../pr-state.js";
+import { buildCiEntry, deriveCiGateStatus, getGateCheckNames, } from "./ci-classification.js";
+import { extractLatestBlockingReviewHeadSha, extractRequestedReviewerLogins, probeGitHubPullRequest, } from "./github-probe.js";
+import { RECONCILIATION_GRACE_MS } from "./shared.js";
+export async function evaluateGitHubIssueHealth(snapshot, config, runCommand, reviewQuillProbe, reviewQuillAttemptOwners, mergeStewardProbe) {
+    const { issue, ageMs } = snapshot;
+    const project = config.projects.find((entry) => entry.id === issue.projectId);
+    const repoFullName = project?.github?.repoFullName;
+    if (!repoFullName || issue.prNumber === undefined) {
+        return {
+            finding: issue.prNumber !== undefined
+                ? {
+                    status: "fail",
+                    scope: "github:config",
+                    message: "PR-backed issue has no GitHub repo configured",
+                }
+                : undefined,
+        };
+    }
+    const probe = await probeGitHubPullRequest(runCommand, repoFullName, issue.prNumber);
+    if (!probe.ok) {
+        return {
+            ciEntry: {
+                ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
+                projectId: issue.projectId,
+                prNumber: issue.prNumber,
+                gateStatus: "unknown",
+                owner: "unknown",
+                orphaned: true,
+                factoryState: issue.factoryState,
+                message: `GitHub probe failed: ${probe.error}`,
+            },
+            finding: {
+                status: "warn",
+                scope: "github:probe",
+                message: `Unable to query GitHub PR state: ${probe.error}`,
+            },
+        };
+    }
+    const pr = probe.pr;
+    const gateCheckNames = getGateCheckNames(project);
+    const gateCheckStatus = deriveCiGateStatus(pr.statusCheckRollup, gateCheckNames);
+    const reviewDecision = pr.reviewDecision?.trim().toUpperCase();
+    const requestedReviewers = extractRequestedReviewerLogins(pr.reviewRequests);
+    const reviewRequested = requestedReviewers.length > 0;
+    const latestBlockingReviewHeadSha = extractLatestBlockingReviewHeadSha(pr.latestReviews);
+    const mergeConflictDetected = pr.mergeable === "CONFLICTING" || pr.mergeStateStatus === "DIRTY";
+    const reviewQuillAttempt = issue.issueKey ? reviewQuillAttemptOwners?.get(issue.issueKey) : undefined;
+    if (pr.state === "MERGED" && issue.factoryState !== "done" && ageMs >= RECONCILIATION_GRACE_MS) {
+        return {
+            finding: {
+                status: "fail",
+                scope: "github:reconcile",
+                message: "PR is already merged but the issue has not advanced to done",
+            },
+        };
+    }
+    if (pr.state === "CLOSED") {
+        const closedPrDisposition = resolveClosedPrDisposition(issue);
+        if (closedPrDisposition === "redelegate" && issue.factoryState !== "delegated" && ageMs >= RECONCILIATION_GRACE_MS) {
+            return {
+                finding: {
+                    status: "fail",
+                    scope: "github:reconcile",
+                    message: "PR is closed but unfinished work has not been re-delegated",
+                },
+            };
+        }
+        return {};
+    }
+    const ciEntry = buildCiEntry({
+        issue,
+        delegatedToPatchRelay: issue.delegatedToPatchRelay,
+        gateCheckStatus,
+        reviewDecision,
+        reviewRequested,
+        currentHeadSha: pr.headRefOid,
+        latestBlockingReviewHeadSha,
+        mergeConflictDetected,
+        reviewQuillAttempt,
+    });
+    if (pr.state === "MERGED" && issue.factoryState !== "done" && ageMs >= RECONCILIATION_GRACE_MS) {
+        return {
+            ciEntry,
+            finding: {
+                status: "fail",
+                scope: "github:reconcile",
+                message: "PR is already merged but the issue has not advanced to done",
+            },
+        };
+    }
+    if (pr.state === "CLOSED" && issue.factoryState !== "delegated" && issue.factoryState !== "done" && ageMs >= RECONCILIATION_GRACE_MS) {
+        return {
+            ciEntry,
+            finding: {
+                status: "fail",
+                scope: "github:reconcile",
+                message: "PR is closed but the issue is still waiting on PR state",
+            },
+        };
+    }
+    if (issue.delegatedToPatchRelay
+        && gateCheckStatus === "failure"
+        && issue.factoryState !== "repairing_ci"
+        // Plan §6.1 / §4.3: branch CI failures while In Deploy are
+        // metadata only — the lander's spec CI is the gate. Don't flag
+        // these as a missing-ci-repair condition.
+        && issue.factoryState !== "awaiting_queue"
+        && issue.activeRunId === undefined
+        && ageMs >= RECONCILIATION_GRACE_MS) {
+        // Plan §6.1: when the PR is also approved, this is the
+        // "In Review · stuck at admission" condition — the lander would
+        // accept the verdict but branch CI is red and (post-§4.3) we no
+        // longer auto-repair. Keep the same scope/status pair so existing
+        // dashboards continue to surface it; just sharpen the message.
+        if (reviewDecision === "APPROVED") {
+            return {
+                ciEntry,
+                finding: {
+                    status: "fail",
+                    scope: "github:ci",
+                    message: "In Review · stuck at admission — PR is approved but gate CI is red and no CI repair is running",
+                },
+            };
+        }
+        return {
+            ciEntry,
+            finding: {
+                status: "fail",
+                scope: "github:ci",
+                message: "Gate CI is failing but no CI repair is running or queued",
+            },
+        };
+    }
+    if (reviewDecision === "APPROVED" && issue.factoryState !== "awaiting_queue" && issue.factoryState !== "done" && ageMs >= RECONCILIATION_GRACE_MS) {
+        return {
+            ciEntry,
+            finding: {
+                status: "fail",
+                scope: "github:reconcile",
+                message: "PR is approved but the issue has not handed off to downstream merge automation",
+            },
+        };
+    }
+    if (gateCheckStatus === "success"
+        && reviewDecision === "CHANGES_REQUESTED"
+        && mergeConflictDetected
+        && issue.delegatedToPatchRelay
+        && issue.factoryState !== "changes_requested"
+        && issue.activeRunId === undefined
+        && ageMs >= RECONCILIATION_GRACE_MS) {
+        return {
+            ciEntry,
+            finding: {
+                status: "fail",
+                scope: "github:branch-upkeep",
+                message: "PR is still dirty after requested changes, but no branch-upkeep run is active",
+            },
+        };
+    }
+    if (gateCheckStatus === "success"
+        && reviewDecision === "CHANGES_REQUESTED"
+        && latestBlockingReviewHeadSha === pr.headRefOid
+        && !reviewQuillAttempt
+        && issue.delegatedToPatchRelay
+        && issue.factoryState !== "changes_requested"
+        && ageMs >= RECONCILIATION_GRACE_MS) {
+        return {
+            ciEntry,
+            finding: {
+                status: "fail",
+                scope: "github:review-handoff",
+                message: "Requested changes still block the current head, but no review fix is running",
+            },
+        };
+    }
+    if (requestedReviewers.includes("review-quill") && reviewQuillProbe && reviewQuillProbe.status !== "pass") {
+        return {
+            ciEntry,
+            finding: {
+                status: "fail",
+                scope: "github:review-automation",
+                message: `PR is waiting on review-quill but the service is not healthy: ${reviewQuillProbe.message}`,
+            },
+        };
+    }
+    if (issue.delegatedToPatchRelay
+        && issue.factoryState === "awaiting_queue"
+        && mergeConflictDetected
+        && issue.activeRunId === undefined
+        && ageMs >= RECONCILIATION_GRACE_MS) {
+        return {
+            ciEntry,
+            finding: {
+                status: "fail",
+                scope: "github:queue",
+                message: "PR has merge conflicts but no queue repair is running or queued",
+            },
+        };
+    }
+    if (issue.factoryState === "awaiting_queue" && mergeStewardProbe && mergeStewardProbe.status !== "pass" && ageMs >= RECONCILIATION_GRACE_MS) {
+        return {
+            ciEntry,
+            finding: {
+                status: "fail",
+                scope: "github:queue",
+                message: `Issue is waiting on downstream merge automation but merge-steward is not healthy: ${mergeStewardProbe.message}`,
+            },
+        };
+    }
+    return { ciEntry };
+}

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

@@ -0,0 +1,67 @@
+import { safeJsonParse } from "./shared.js";
+export async function probeGitHubPullRequest(runCommand, repoFullName, prNumber) {
+    let result;
+    try {
+        result = await runCommand("gh", [
+            "pr",
+            "view",
+            String(prNumber),
+            "--repo",
+            repoFullName,
+            "--json",
+            "state,reviewDecision,reviewRequests,latestReviews,statusCheckRollup,mergeable,mergeStateStatus,headRefOid",
+        ]);
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    if (result.exitCode !== 0) {
+        return {
+            ok: false,
+            error: [result.stderr.trim(), result.stdout.trim()].filter(Boolean).join(" ") || `gh exited ${result.exitCode}`,
+        };
+    }
+    const parsed = safeJsonParse(result.stdout);
+    if (!parsed) {
+        return { ok: false, error: "invalid JSON from gh pr view" };
+    }
+    return { ok: true, pr: parsed };
+}
+export function extractLatestBlockingReviewHeadSha(latestReviews) {
+    if (!Array.isArray(latestReviews)) {
+        return undefined;
+    }
+    for (const review of latestReviews) {
+        if (!review || typeof review !== "object")
+            continue;
+        const state = typeof review.state === "string"
+            ? String(review.state).trim().toUpperCase()
+            : undefined;
+        if (state !== "CHANGES_REQUESTED")
+            continue;
+        const commitOid = typeof review.commit?.oid === "string"
+            ? String(review.commit.oid).trim()
+            : undefined;
+        if (commitOid)
+            return commitOid;
+    }
+    return undefined;
+}
+export function extractRequestedReviewerLogins(requests) {
+    if (!Array.isArray(requests)) {
+        return [];
+    }
+    const logins = requests.flatMap((request) => {
+        if (!request || typeof request !== "object") {
+            return [];
+        }
+        const direct = typeof request.login === "string"
+            ? String(request.login)
+            : undefined;
+        const nested = typeof request.requestedReviewer?.login === "string"
+            ? String(request.requestedReviewer.login)
+            : undefined;
+        return [direct, nested].filter((entry) => Boolean(entry)).map((entry) => entry.trim().toLowerCase());
+    });
+    return [...new Set(logins)];
+}