patchrelay 0.65.0 → 0.66.0

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "service": "patchrelay",
-  "version": "0.65.0",
-  "commit": "1b180d2544aa",
-  "builtAt": "2026-05-04T22:53:34.027Z"
+  "version": "0.66.0",
+  "commit": "552ba486bf93",
+  "builtAt": "2026-05-05T14:36:59.557Z"
 }

package/dist/change-identity.js

@@ -0,0 +1,46 @@
+import { spawnSync } from "node:child_process";
+export function computeChangeIdentityFromWorktree(params) {
+    const cwd = params.worktreePath;
+    const baseSha = resolveSha(cwd, params.baseRef);
+    const headSha = params.headSha
+        ? resolveSha(cwd, params.headSha)
+        : resolveSha(cwd, "HEAD");
+    if (!baseSha || !headSha)
+        return {};
+    const patchId = computePatchId(cwd, baseSha, headSha);
+    const integrationTreeId = computeIntegrationTreeId(cwd, baseSha, headSha);
+    return {
+        ...(patchId ? { patchId } : {}),
+        ...(integrationTreeId ? { integrationTreeId } : {}),
+        baseSha,
+        headSha,
+    };
+}
+export function resolveSha(cwd, ref) {
+    const result = spawnSync("git", ["-C", cwd, "rev-parse", ref], {
+        encoding: "utf8",
+    });
+    if (result.status !== 0)
+        return undefined;
+    const sha = result.stdout.trim();
+    return sha || undefined;
+}
+function computePatchId(cwd, base, head) {
+    // Pipe `git diff` through `git patch-id --stable`. Use sh -c to keep
+    // the pipeline atomic and avoid plumbing stdio between two spawns.
+    const result = spawnSync("sh", ["-c", `git -C ${shellQuote(cwd)} diff ${shellQuote(base)}..${shellQuote(head)} | git patch-id --stable`], { encoding: "utf8" });
+    if (result.status !== 0)
+        return undefined;
+    const first = result.stdout.split(/\s+/, 1)[0]?.trim();
+    return first ? first : undefined;
+}
+function computeIntegrationTreeId(cwd, base, head) {
+    const result = spawnSync("git", ["-C", cwd, "merge-tree", "--write-tree", "--no-messages", base, head], { encoding: "utf8" });
+    if (result.status !== 0)
+        return undefined;
+    const tree = result.stdout.trim().split(/\s+/, 1)[0];
+    return tree || undefined;
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/dist/cli/args.js

@@ -18,6 +18,7 @@ export const KNOWN_COMMANDS = new Set([
     "connect",
     "installations",
     "help",
+    "sequence-check",
 ]);
 export function parseArgs(argv) {
     const positionals = [];

package/dist/cli/commands/sequence-check.js

@@ -0,0 +1,139 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { detectStackingTarget } from "../../pr-sequencing.js";
+import { CliUsageError } from "../errors.js";
+import { formatJson } from "../formatters/json.js";
+import { writeOutput } from "../output.js";
+export async function handleSequenceCheckCommand(params) {
+    if (params.commandArgs.length > 0) {
+        throw new CliUsageError(`Unexpected argument for sequence-check: ${params.commandArgs[0]}`, "sequence-check");
+    }
+    const cwd = params.cwd ?? process.cwd();
+    const baseFlag = params.parsed.flags.get("base");
+    const overrideBase = typeof baseFlag === "string" ? baseFlag.trim() : "";
+    const self = params.selfProvider
+        ? params.selfProvider()
+        : resolveSelf(cwd, overrideBase || undefined);
+    if (!self) {
+        writeOutput(params.stderr, "sequence-check: not inside a git work tree, or unable to resolve HEAD\n");
+        return 2;
+    }
+    const candidates = params.candidatesProvider
+        ? params.candidatesProvider()
+        : collectCandidates(params.data.db, self.branch);
+    const probe = params.gitProbe ?? cliGitProbe(cwd);
+    const recommendation = await detectStackingTarget({
+        self,
+        candidates,
+        git: probe,
+    });
+    if (params.json) {
+        writeOutput(params.stdout, formatJson(recommendation));
+    }
+    else {
+        writeOutput(params.stdout, `${JSON.stringify(recommendation)}\n`);
+    }
+    writeOutput(params.stderr, formatHumanSummary(recommendation));
+    return 0;
+}
+function resolveSelf(cwd, overrideBase) {
+    const branchResult = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+        cwd,
+        encoding: "utf8",
+    });
+    if (branchResult.status !== 0)
+        return undefined;
+    const branch = branchResult.stdout.trim();
+    if (!branch || branch === "HEAD")
+        return undefined;
+    const headResult = spawnSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8" });
+    if (headResult.status !== 0)
+        return undefined;
+    const headSha = headResult.stdout.trim();
+    if (!headSha)
+        return undefined;
+    const baseRef = overrideBase ?? resolveDefaultBranchRef(cwd);
+    if (!baseRef)
+        return undefined;
+    return { branch, headSha, baseRef };
+}
+function resolveDefaultBranchRef(cwd) {
+    // Prefer the symbolic upstream of origin/HEAD; fall back to main.
+    const symbolic = spawnSync("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], {
+        cwd,
+        encoding: "utf8",
+    });
+    if (symbolic.status === 0) {
+        const ref = symbolic.stdout.trim();
+        if (ref)
+            return ref;
+    }
+    for (const candidate of ["origin/main", "origin/master"]) {
+        const probe = spawnSync("git", ["rev-parse", "--verify", candidate], {
+            cwd,
+            encoding: "utf8",
+        });
+        if (probe.status === 0)
+            return candidate;
+    }
+    return "origin/main";
+}
+function collectCandidates(db, selfBranch) {
+    const issues = db.issues.listIssues();
+    const candidates = [];
+    const now = Date.now();
+    for (const issue of issues) {
+        if (issue.factoryState !== "pr_open" && issue.factoryState !== "awaiting_queue")
+            continue;
+        if (!issue.branchName || !issue.prHeadSha || !issue.prNumber)
+            continue;
+        if (issue.branchName === selfBranch)
+            continue;
+        const queueAgeMs = issue.updatedAt
+            ? Math.max(0, now - Date.parse(issue.updatedAt))
+            : undefined;
+        candidates.push({
+            prNumber: issue.prNumber,
+            branch: issue.branchName,
+            headSha: issue.prHeadSha,
+            ...(issue.prReviewState ? { reviewState: issue.prReviewState } : {}),
+            ...(issue.prCheckStatus ? { checkStatus: issue.prCheckStatus } : {}),
+            factoryState: issue.factoryState,
+            ...(queueAgeMs !== undefined ? { queueAgeMs } : {}),
+        });
+    }
+    return candidates;
+}
+function cliGitProbe(cwd) {
+    return {
+        async changedFiles(baseRef, headSha) {
+            const result = spawnSync("git", ["diff", "--name-only", `${baseRef}...${headSha}`], { cwd, encoding: "utf8" });
+            if (result.status !== 0) {
+                return [];
+            }
+            return result.stdout
+                .split("\n")
+                .map((line) => line.trim())
+                .filter(Boolean);
+        },
+        async hasConflict(headSha, candidateHeadSha) {
+            // `git merge-tree --write-tree` exits non-zero on conflict in
+            // modern git; with `--no-messages` it suppresses commit-msg
+            // suggestions. Use the auto-merge-base form (two operands).
+            const result = spawnSync("git", ["merge-tree", "--write-tree", "--no-messages", headSha, candidateHeadSha], { cwd, encoding: "utf8" });
+            return result.status !== 0;
+        },
+    };
+}
+function formatHumanSummary(recommendation) {
+    if (recommendation.recommendation === "open_pr_against_main") {
+        return `sequence-check: open PR against main — ${recommendation.reason}\n`;
+    }
+    return [
+        `sequence-check: rebase onto PR #${recommendation.parentPr} (${recommendation.parentBranch})`,
+        `  reason: ${recommendation.reason}`,
+        `  parent head: ${recommendation.parentHead}`,
+        "",
+    ].join("\n");
+}
+export { path };

package/dist/cli/help.js

@@ -214,7 +214,25 @@ export function helpTextFor(topic) {
             return issueHelpText();
         case "service":
             return serviceHelpText();
+        case "sequence-check":
+            return sequenceCheckHelpText();
         default:
             return rootHelpText();
     }
 }
+function sequenceCheckHelpText() {
+    return [
+        "patchrelay sequence-check",
+        "",
+        "Detect whether the current branch should be stacked on an in-flight PR before",
+        "opening a new one. Run from inside the worktree right before `gh pr create`.",
+        "",
+        "Output: JSON recommendation on stdout. Either:",
+        "  {\"recommendation\":\"open_pr_against_main\",\"reason\":\"…\"}",
+        "  {\"recommendation\":\"rebase_onto\",\"parentPr\":509,\"parentBranch\":\"…\",…}",
+        "",
+        "Flags:",
+        "  --base <ref>   Override the base ref used for diff (default: origin/HEAD)",
+        "  --json         Emit pretty-printed JSON",
+    ].join("\n");
+}

package/dist/cli/index.js

@@ -4,6 +4,7 @@ import { assertKnownFlags, hasHelpFlag, parseArgs, resolveCommand } from "./args
 import { handleIssueCommand, } from "./commands/issues.js";
 import { handleClusterCommand } from "./commands/cluster.js";
 import { handleLinearCommand } from "./commands/linear.js";
+import { handleSequenceCheckCommand } from "./commands/sequence-check.js";
 import { handleRepoCommand } from "./commands/repo.js";
 import { handleInitCommand, handleServiceCommand } from "./commands/setup.js";
 import { CliUsageError } from "./errors.js";
@@ -24,6 +25,7 @@ function getCommandConfigProfile(command) {
         case "cluster":
         case "repo":
         case "issue":
+        case "sequence-check":
             return "cli";
         default:
             return "service";
@@ -87,6 +89,9 @@ function validateFlags(command, commandArgs, parsed) {
         case "cluster":
             assertKnownFlags(parsed, command, ["json"]);
             return;
+        case "sequence-check":
+            assertKnownFlags(parsed, command, ["json", "base"]);
+            return;
         case "init":
             assertKnownFlags(parsed, command, ["force", "json", "public-base-url"]);
             return;
@@ -349,6 +354,21 @@ export async function runCli(argv, options) {
             const { handleWatchCommand } = await import("./commands/watch.js");
             return await handleWatchCommand({ config, parsed });
         }
+        if (command === "sequence-check") {
+            const issueData = await ensureIssueDataAccess(data, config);
+            if (!data) {
+                data = issueData;
+                ownsData = true;
+            }
+            return await handleSequenceCheckCommand({
+                commandArgs,
+                parsed,
+                json,
+                stdout,
+                stderr,
+                data: issueData,
+            });
+        }
         throw new Error(`Unknown command: ${command}`);
     }
     catch (error) {

package/dist/db/migrations.js

@@ -62,6 +62,7 @@ CREATE TABLE IF NOT EXISTS runs (
   summary_json TEXT,
   report_json TEXT,
   failure_reason TEXT,
+  should_not_publish INTEGER NOT NULL DEFAULT 0,
   started_at TEXT NOT NULL,
   ended_at TEXT
 );
@@ -297,6 +298,9 @@ export function runPatchRelayMigrations(connection) {
     addColumnIfMissing(connection, "runs", "completion_check_why", "TEXT");
     addColumnIfMissing(connection, "runs", "completion_check_recommended_reply", "TEXT");
     addColumnIfMissing(connection, "runs", "completion_checked_at", "TEXT");
+    // Plan §4.4: hard publication-suppression flag for the
+    // mid-run-approval cancellation primitive.
+    addColumnIfMissing(connection, "runs", "should_not_publish", "INTEGER NOT NULL DEFAULT 0");
     addColumnIfMissing(connection, "issues", "last_blocking_review_head_sha", "TEXT");
     // Collapse awaiting_review into pr_open (state normalization)
     connection.prepare("UPDATE issues SET factory_state = 'pr_open' WHERE factory_state = 'awaiting_review'").run();

package/dist/db/run-store.js

@@ -102,6 +102,34 @@ export class RunStore {
             });
         }
     }
+    // Plan §4.4: flag a still-running run as superseded. We deliberately
+    // do NOT change `status` here — the Codex turn must finish naturally
+    // so the notification handler can deliver `turn/completed` to the
+    // run-finalizer (run-notification-handler ignores any run whose status
+    // is not 'running'). The finalizer reads `should_not_publish` and
+    // routes to `releaseSupersededRun`, which is where the row finally
+    // moves to status='superseded'. Setting status here would orphan the
+    // run: notifications would be dropped, the issue's activeRunId would
+    // never be cleared, and the lease would stay held.
+    markSuperseded(runId, params) {
+        this.connection.prepare(`
+      UPDATE runs SET
+        should_not_publish = 1,
+        failure_reason = COALESCE(failure_reason, ?)
+      WHERE id = ?
+        AND status IN ('queued', 'running')
+    `).run(params.reason, runId);
+        const run = this.getRunById(runId);
+        if (!run)
+            return;
+        const issue = this.issues.getIssue(run.projectId, run.linearIssueId);
+        if (issue) {
+            this.syncIssueSessionFromIssue(issue, {
+                summaryText: params.reason,
+                lastRunType: run.runType,
+            });
+        }
+    }
     saveCompletionCheck(runId, params) {
         this.connection.prepare(`
       UPDATE runs SET

package/dist/db.js

@@ -289,6 +289,7 @@ function mapRunRow(row) {
         ...(row.summary_json !== null ? { summaryJson: String(row.summary_json) } : {}),
         ...(row.report_json !== null ? { reportJson: String(row.report_json) } : {}),
         ...(row.failure_reason !== null ? { failureReason: String(row.failure_reason) } : {}),
+        ...(row.should_not_publish === 1 || row.should_not_publish === true ? { shouldNotPublish: true } : {}),
         startedAt: String(row.started_at),
         ...(row.ended_at !== null ? { endedAt: String(row.ended_at) } : {}),
     };

package/dist/factory-state.js

@@ -43,6 +43,20 @@ const TRANSITION_RULES = [
     { event: "review_approved",
         guard: (s, ctx) => isOpen(s) && ctx.activeRunId === undefined,
         to: "awaiting_queue" },
+    // Plan §4.4: mid-run approval cancellation. When an approval lands
+    // on the same head a `review_fix` run was launched against, the
+    // run's premise no longer holds — there is no "fix" to publish, the
+    // PR is already approved. We let the transition fire so factoryState
+    // reflects reality (awaiting_queue), and the observer in
+    // reactive-run-policy.ts supersedes the still-running Codex turn so
+    // it can't push a cosmetic patch-id-equivalent commit.
+    { event: "review_approved",
+        guard: (s, ctx) => isOpen(s)
+            && ctx.activeRunId !== undefined
+            && ctx.activeRunType === "review_fix"
+            && ctx.approvalHeadSha !== undefined
+            && ctx.approvalHeadSha === ctx.activeRunSourceHeadSha,
+        to: "awaiting_queue" },
     { event: "review_changes_requested",
         guard: (s, ctx) => isOpen(s) && ctx.activeRunId === undefined,
         to: "changes_requested" },

package/dist/github-webhook-handler.js

@@ -7,6 +7,7 @@ import { resolveGitHubWebhookIssue } from "./github-webhook-issue-resolution.js"
 import { maybeCloseLatePublishedImplementationPr } from "./github-webhook-late-publication-guard.js";
 import { projectGitHubWebhookState } from "./github-webhook-state-projector.js";
 import { maybeEnqueueGitHubReactiveRun } from "./github-webhook-reactive-run.js";
+import { maybeRunSequenceBackstop } from "./github-webhook-sequence-backstop.js";
 import { handleGitHubTerminalPrEvent } from "./github-webhook-terminal-handler.js";
 export class GitHubWebhookHandler {
     config;
@@ -130,6 +131,17 @@ export class GitHubWebhookHandler {
             failureContextResolver: this.failureContextResolver,
             fetchImpl: this.fetchImpl,
         });
+        if (event.triggerEvent === "pr_opened") {
+            await maybeRunSequenceBackstop({
+                db: this.db,
+                logger: this.logger,
+                ...(this.feed ? { feed: this.feed } : {}),
+                event,
+                fetchImpl: this.fetchImpl,
+            }).catch((error) => {
+                this.logger.warn({ err: error }, "sequence-check backstop failed");
+            });
+        }
         if (event.triggerEvent === "pr_merged" || event.triggerEvent === "pr_closed") {
             await handleGitHubTerminalPrEvent({
                 config: this.config,

package/dist/github-webhook-policy.js

@@ -75,7 +75,7 @@ export function canClearFailureProvenance(issue, event, project) {
     }
     return !issue.lastGitHubFailureHeadSha || issue.lastGitHubFailureHeadSha === event.headSha;
 }
-export function resolveGitHubFactoryStateForEvent(issue, event, project) {
+export function resolveGitHubFactoryStateForEvent(issue, event, project, activeRun) {
     if (event.triggerEvent === "pr_closed") {
         return undefined;
     }
@@ -89,10 +89,16 @@ export function resolveGitHubFactoryStateForEvent(issue, event, project) {
     const failureSource = event.triggerEvent === "check_failed"
         ? (isQueueEvictionFailure(issue, event, project) ? "queue_eviction" : "branch_ci")
         : undefined;
+    const approvalHeadSha = event.triggerEvent === "review_approved"
+        ? (event.reviewCommitId ?? event.headSha)
+        : undefined;
     const resolved = resolveFactoryStateFromGitHub(event.triggerEvent, effectiveCurrentState, {
         prReviewState: issue.prReviewState,
         activeRunId: issue.activeRunId,
         failureSource,
+        ...(activeRun?.runType ? { activeRunType: activeRun.runType } : {}),
+        ...(activeRun?.sourceHeadSha ? { activeRunSourceHeadSha: activeRun.sourceHeadSha } : {}),
+        ...(approvalHeadSha ? { approvalHeadSha } : {}),
     });
     if (resolved !== undefined) {
         return resolved;

package/dist/github-webhook-sequence-backstop.js

@@ -0,0 +1,94 @@
+// Plan §8.2: backstop for missed sequence-checks. When a PR is
+// opened and its changed-file set overlaps with another in-flight
+// PR's, surface an operator event so the agent can be re-prompted
+// (or a human can intervene). The full merge-tree probe lives in
+// the CLI command; the backstop is intentionally cheap — file-set
+// overlap only — because the webhook handler has no worktree.
+export async function maybeRunSequenceBackstop(params) {
+    const { db, logger, feed, event } = params;
+    const fetchImpl = params.fetchImpl ?? fetch;
+    if (event.triggerEvent !== "pr_opened")
+        return;
+    if (!event.repoFullName || event.prNumber === undefined)
+        return;
+    const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
+    if (!token)
+        return;
+    const [owner, repo] = event.repoFullName.split("/", 2);
+    if (!owner || !repo)
+        return;
+    const newPrFiles = await listChangedFiles(fetchImpl, token, owner, repo, event.prNumber).catch(() => undefined);
+    if (!newPrFiles || newPrFiles.size === 0)
+        return;
+    const candidates = db.issues
+        .listIssues()
+        .filter((issue) => (issue.factoryState === "pr_open" || issue.factoryState === "awaiting_queue")
+        && issue.prNumber !== undefined
+        && issue.prNumber !== event.prNumber
+        && issue.branchName !== undefined
+        && issue.branchName !== event.branchName);
+    for (const candidate of candidates) {
+        const candidateFiles = await listChangedFiles(fetchImpl, token, owner, repo, candidate.prNumber).catch(() => undefined);
+        if (!candidateFiles)
+            continue;
+        const overlap = intersect(newPrFiles, candidateFiles);
+        if (overlap.length === 0)
+            continue;
+        logger.info({
+            event: "sequence_backstop_overlap_detected",
+            prNumber: event.prNumber,
+            candidatePrNumber: candidate.prNumber,
+            overlap: overlap.slice(0, 10),
+        }, "potential stack-target detected on pr_opened");
+        feed?.publish({
+            level: "warn",
+            kind: "github",
+            summary: `PR #${event.prNumber} may need to stack on PR #${candidate.prNumber} (overlapping files)`,
+            detail: `Overlapping files: ${overlap.slice(0, 5).join(", ")}${overlap.length > 5 ? "…" : ""}`,
+            ...(candidate.issueKey ? { issueKey: candidate.issueKey } : {}),
+            ...(candidate.projectId ? { projectId: candidate.projectId } : {}),
+        });
+        // First overlap is enough — the operator-facing signal does not
+        // need to enumerate every potential parent.
+        return;
+    }
+}
+async function listChangedFiles(fetchImpl, token, owner, repo, prNumber) {
+    const result = new Set();
+    let page = 1;
+    // GitHub caps `pulls/{n}/files` at 3000 across pages of 100.
+    while (page <= 30) {
+        const response = await fetchImpl(`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/pulls/${prNumber}/files?per_page=100&page=${page}`, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/vnd.github+json",
+                "User-Agent": "patchrelay",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+        });
+        if (!response.ok)
+            return undefined;
+        const payload = (await response.json());
+        if (!Array.isArray(payload))
+            return undefined;
+        for (const entry of payload) {
+            if (!entry || typeof entry !== "object")
+                continue;
+            const filename = entry.filename;
+            if (typeof filename === "string" && filename)
+                result.add(filename);
+        }
+        if (payload.length < 100)
+            break;
+        page += 1;
+    }
+    return result;
+}
+function intersect(a, b) {
+    const result = [];
+    for (const value of a) {
+        if (b.has(value))
+            result.push(value);
+    }
+    return result;
+}

package/dist/github-webhook-state-projector.js

@@ -33,7 +33,15 @@ export async function projectGitHubWebhookState(deps, issue, event, project, lin
     const queueEvictionCheck = isQueueEvictionFailure(issue, event, project);
     if (!isMetadataOnlyCheckEvent(event) || queueEvictionCheck) {
         const afterMetadata = deps.db.issues.getIssue(issue.projectId, issue.linearIssueId) ?? issue;
-        const newState = resolveGitHubFactoryStateForEvent(afterMetadata, event, project);
+        const activeRun = afterMetadata.activeRunId
+            ? deps.db.runs.getRunById(afterMetadata.activeRunId)
+            : undefined;
+        const newState = resolveGitHubFactoryStateForEvent(afterMetadata, event, project, activeRun
+            ? {
+                ...(activeRun.runType ? { runType: activeRun.runType } : {}),
+                ...(activeRun.sourceHeadSha ? { sourceHeadSha: activeRun.sourceHeadSha } : {}),
+            }
+            : undefined);
         if (newState && newState !== afterMetadata.factoryState) {
             deps.db.issueSessions.upsertIssueRespectingActiveLease(issue.projectId, issue.linearIssueId, {
                 projectId: issue.projectId,
@@ -41,6 +49,20 @@ export async function projectGitHubWebhookState(deps, issue, event, project, lin
                 factoryState: newState,
             });
             deps.logger.info({ issueKey: issue.issueKey, from: afterMetadata.factoryState, to: newState, trigger: event.triggerEvent }, "Factory state transition from GitHub event");
+            // Plan §4.4: when the transition fired *because* an approval
+            // landed during a review_fix run on the same head (the
+            // mid-run-approval rule), the run's premise is gone. Mark it
+            // superseded and set the publication-suppression flag so the
+            // finalizer cannot push a cosmetic patch-id-equivalent commit.
+            maybeSupersedeActiveRun({
+                db: deps.db,
+                logger: deps.logger,
+                feed: deps.feed,
+                issue: afterMetadata,
+                newState,
+                event,
+                activeRun,
+            });
             const transitionedIssue = deps.db.issues.getIssue(issue.projectId, issue.linearIssueId) ?? issue;
             void emitGitHubLinearActivity({
                 linearProvider: deps.linearProvider,
@@ -96,6 +118,42 @@ export async function projectGitHubWebhookState(deps, issue, event, project, lin
     });
     return freshIssue;
 }
+// Plan §4.4: when the mid-run-approval transition fires, the active
+// review_fix run's premise no longer holds — there is no fix to
+// publish. Mark it superseded and set the publication-suppression
+// flag. The Codex turn may have produced output already; the
+// finalizer reads `shouldNotPublish` and refuses to push.
+function maybeSupersedeActiveRun(params) {
+    const { db, logger, feed, issue, newState, event, activeRun } = params;
+    if (event.triggerEvent !== "review_approved")
+        return;
+    if (newState !== "awaiting_queue")
+        return;
+    if (!activeRun)
+        return;
+    if (activeRun.runType !== "review_fix")
+        return;
+    const approvalHead = event.reviewCommitId ?? event.headSha;
+    if (!approvalHead || !activeRun.sourceHeadSha)
+        return;
+    if (approvalHead !== activeRun.sourceHeadSha)
+        return;
+    db.runs.markSuperseded(activeRun.id, {
+        reason: "approved on the same head; further publication suppressed",
+    });
+    logger.info({
+        issueKey: issue.issueKey,
+        runId: activeRun.id,
+        headSha: approvalHead,
+    }, "Superseded mid-run review_fix after approval landed on the same head");
+    feed?.publish({
+        level: "info",
+        kind: "agent",
+        summary: `Superseded review_fix run #${activeRun.id} — PR approved on the same head`,
+        ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
+        ...(issue.projectId ? { projectId: issue.projectId } : {}),
+    });
+}
 async function updateGitHubCiSnapshot(deps, issue, event, project, ciSnapshotResolver) {
     if (event.triggerEvent === "pr_merged") {
         deps.db.issues.upsertIssue({

package/dist/pr-sequencing.js

@@ -0,0 +1,132 @@
+// Plan §8.2: detect when an outgoing PR would conflict with an
+// already-in-flight PR and recommend stacking against it instead of
+// opening against main. Pure logic — IO is injected via the
+// `GitProbe` interface so tests can drive it deterministically and
+// the CLI can wire it to `spawnSync` git invocations.
+const DEFAULT_SKIP_LABELS = ["wip", "do-not-merge", "do-not-merge-before"];
+export async function detectStackingTarget(params) {
+    const { self, candidates, git } = params;
+    const skipLabels = (params.skipLabels ?? DEFAULT_SKIP_LABELS).map((label) => label.trim().toLowerCase());
+    if (candidates.length === 0) {
+        return { recommendation: "open_pr_against_main", reason: "no in-flight PRs to stack on" };
+    }
+    // Step 1: file-overlap pre-filter. Compute self's changed files
+    // once, then keep candidates whose changed-file set intersects.
+    const ownFiles = new Set(await git.changedFiles(self.baseRef, self.headSha));
+    if (ownFiles.size === 0) {
+        return { recommendation: "open_pr_against_main", reason: "no files changed in current branch" };
+    }
+    const overlappingCandidates = [];
+    for (const candidate of candidates) {
+        if (candidate.branch === self.branch || candidate.headSha === self.headSha)
+            continue;
+        if (hasSkipLabel(candidate, skipLabels))
+            continue;
+        let candidateFiles;
+        try {
+            candidateFiles = await git.changedFiles(self.baseRef, candidate.headSha);
+        }
+        catch {
+            continue;
+        }
+        const overlap = candidateFiles.filter((file) => ownFiles.has(file));
+        if (overlap.length > 0) {
+            overlappingCandidates.push({ candidate, overlap });
+        }
+    }
+    if (overlappingCandidates.length === 0) {
+        return {
+            recommendation: "open_pr_against_main",
+            reason: "no overlapping in-flight PRs",
+        };
+    }
+    // Step 2: real conflict probe via merge-tree on each surviving
+    // candidate. We score only those that actually conflict; trees
+    // that auto-merge (different lines of the same file) are skipped.
+    const conflicting = [];
+    for (const entry of overlappingCandidates) {
+        let conflict = false;
+        try {
+            conflict = await git.hasConflict(self.headSha, entry.candidate.headSha);
+        }
+        catch {
+            // Treat probe failure as "no conflict known" — fall through to
+            // open against main rather than recommending a possibly wrong
+            // stack target.
+            continue;
+        }
+        if (conflict) {
+            conflicting.push(entry);
+        }
+    }
+    if (conflicting.length === 0) {
+        return {
+            recommendation: "open_pr_against_main",
+            reason: "overlapping files but no real conflict on merge-tree probe",
+        };
+    }
+    // Step 3: score by likelihood-to-land-first. Higher score wins.
+    const ranked = conflicting
+        .map((entry) => ({ ...entry, score: scoreCandidate(entry.candidate) }))
+        .sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        // Tie: prefer older queue entry.
+        const ageA = a.candidate.queueAgeMs ?? 0;
+        const ageB = b.candidate.queueAgeMs ?? 0;
+        if (ageA !== ageB)
+            return ageB - ageA;
+        // Final tie: lowest PR number first (it was opened earlier).
+        return a.candidate.prNumber - b.candidate.prNumber;
+    });
+    const winner = ranked[0];
+    const reasonBits = [];
+    reasonBits.push(`conflict on ${formatFileList(winner.overlap)}`);
+    reasonBits.push(`PR #${winner.candidate.prNumber} ${describeReadiness(winner.candidate)}`);
+    return {
+        recommendation: "rebase_onto",
+        parentPr: winner.candidate.prNumber,
+        parentBranch: winner.candidate.branch,
+        parentHead: winner.candidate.headSha,
+        reason: reasonBits.join("; ") + ", expected to land first",
+        conflictingFiles: winner.overlap,
+    };
+}
+function scoreCandidate(candidate) {
+    const review = (candidate.reviewState ?? "").trim().toLowerCase();
+    const checks = (candidate.checkStatus ?? "").trim().toLowerCase();
+    const factory = (candidate.factoryState ?? "").trim().toLowerCase();
+    let score = 0;
+    // Already in the queue → most likely to land first.
+    if (factory === "awaiting_queue")
+        score += 100;
+    if (review === "approved")
+        score += 50;
+    if (checks === "success" || checks === "passed")
+        score += 25;
+    if (review === "changes_requested")
+        score -= 30;
+    return score;
+}
+function hasSkipLabel(candidate, skipLabels) {
+    const labels = (candidate.labels ?? []).map((label) => label.trim().toLowerCase());
+    return labels.some((label) => skipLabels.includes(label));
+}
+function describeReadiness(candidate) {
+    const review = (candidate.reviewState ?? "").trim().toLowerCase();
+    const checks = (candidate.checkStatus ?? "").trim().toLowerCase();
+    const factory = (candidate.factoryState ?? "").trim().toLowerCase();
+    if (factory === "awaiting_queue")
+        return "is in the merge queue";
+    if (review === "approved" && (checks === "success" || checks === "passed")) {
+        return "is approved + green";
+    }
+    if (review === "approved")
+        return "is approved";
+    return "is in flight";
+}
+function formatFileList(files) {
+    if (files.length <= 3)
+        return files.join(", ");
+    return `${files.slice(0, 3).join(", ")} (+${files.length - 3} more)`;
+}

package/dist/prompting/patchrelay.js

@@ -42,11 +42,18 @@ function buildPromptHeader(issue) {
                     : prContext.kind === "closed_pr_paused"
                         ? `Previous PR: #${prContext.prNumber} (closed; redelegate to replace it)`
                         : undefined;
+    // Plan §4.2(b): surface the patch-id of the last patchrelay-attributed
+    // publish so the agent can compute its own diff's patch-id pre-push
+    // and skip the publish if the result is patch-id-equivalent.
+    const patchIdLine = issue.lastPublishedPatchId
+        ? `Last published patch-id: ${issue.lastPublishedPatchId}`
+        : undefined;
     return [
         `Issue: ${issue.issueKey ?? issue.linearIssueId}`,
         issue.title ? `Title: ${issue.title}` : undefined,
         issue.branchName ? `Branch: ${issue.branchName}` : undefined,
         prLine,
+        patchIdLine,
     ].filter(Boolean).join("\n");
 }
 function extractIssueSection(description, heading) {
@@ -538,6 +545,10 @@ function buildPublicationContract(runType, issueClass) {
             "If this is code-delivery work, publish before stopping: commit, push the issue branch, and open or update the PR.",
             "If the issue explicitly allows a non-PR outcome, complete that outcome clearly instead of inventing a PR.",
             "",
+            "Right before `gh pr create`, run `patchrelay sequence-check` from the worktree.",
+            "If the JSON recommendation is `rebase_onto`, rebase the branch onto the named parent and pass `--base <parent_branch>` to `gh pr create`. Include the recommendation's reason in the PR body under a `Stacked on #NNN` header.",
+            "If the recommendation is `open_pr_against_main`, proceed with `gh pr create` against the default base.",
+            "",
             ...buildPrePushSelfReviewSection("new_pr", runType),
         ].join("\n");
     }
@@ -548,6 +559,9 @@ function buildPublicationContract(runType, issueClass) {
         "Do not open a new PR.",
         "A PR-less stop is not a successful outcome for a repair run unless a genuine external blocker prevents any correct push.",
         "",
+        "Before pushing, compute `git diff $(git merge-base origin/main HEAD)..HEAD | git patch-id --stable` and compare its first field to the `Last published patch-id` shown in the prompt header (if any).",
+        "If they match, do not push — finish the run as a no-op. Edit the PR body via `gh pr edit` instead if a textual update is needed.",
+        "",
         ...buildPrePushSelfReviewSection("existing_pr", runType),
     ].join("\n");
 }

package/dist/reactive-run-policy.js

@@ -62,6 +62,13 @@ export class ReactiveRunPolicy {
         if (!isRequestedChangesRunType(run.runType)) {
             return undefined;
         }
+        // Plan §4.4: a superseded run was deliberately cancelled mid-flight
+        // because the PR was approved on the same head. Demanding a new head
+        // would be wrong — there's nothing to push, and the publication-
+        // suppression flag is the contract that says so.
+        if (run.shouldNotPublish || run.status === "superseded") {
+            return undefined;
+        }
         if (!issue.prNumber || issue.prState !== "open") {
             return undefined;
         }

package/dist/run-finalizer.js

@@ -2,6 +2,7 @@ import { buildStageReport, countEventMethods } from "./run-reporting.js";
 import { buildRunCompletedActivity, buildRunFailureActivity } from "./linear-session-reporting.js";
 import { handleNoPrCompletionCheck } from "./no-pr-completion-check.js";
 import { resolveCompletedRunState } from "./run-completion-policy.js";
+import { computeChangeIdentityFromWorktree } from "./change-identity.js";
 function parseEventJson(eventJson) {
     if (!eventJson)
         return undefined;
@@ -131,10 +132,73 @@ export class RunFinalizer {
             return undefined;
         }
     }
+    // Plan §4.2(c): record the identity of the head we just published
+    // so subsequent runs can recognize a patch-id-equivalent re-push.
+    // Only fires when the current head SHA is observably different from
+    // the run's starting sourceHeadSha — a no-op publish would not
+    // advance the head.
+    maybeUpdateLastPublishedIdentity(run, issue) {
+        if (!issue.worktreePath || !issue.prHeadSha)
+            return;
+        if (run.sourceHeadSha && run.sourceHeadSha === issue.prHeadSha)
+            return;
+        if (issue.lastPublishedHeadSha === issue.prHeadSha)
+            return;
+        const identity = computeChangeIdentityFromWorktree({
+            worktreePath: issue.worktreePath,
+            baseRef: "origin/main",
+            headSha: issue.prHeadSha,
+        });
+        if (!identity.patchId && !identity.integrationTreeId)
+            return;
+        this.db.issues.upsertIssue({
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+            ...(identity.patchId ? { lastPublishedPatchId: identity.patchId } : {}),
+            ...(identity.integrationTreeId ? { lastPublishedIntegrationTreeId: identity.integrationTreeId } : {}),
+            lastPublishedHeadSha: issue.prHeadSha,
+        });
+        this.logger.info({
+            issueKey: issue.issueKey,
+            prHeadSha: issue.prHeadSha,
+            patchId: identity.patchId,
+        }, "Recorded last-published change identity after run completion");
+    }
     clearProgressAndRelease(run) {
         this.linearSync.clearProgress(run.id);
         this.releaseLease(run.projectId, run.linearIssueId);
     }
+    // Plan §4.4: finalize a run that was superseded mid-flight. The
+    // status row was already moved to `superseded` by the trigger
+    // observer; this just makes sure the issue's activeRunId is
+    // cleared, the lease is released, and the operator sees a
+    // clean recap event. No publication, no follow-up enqueue —
+    // the approval that triggered supersedure already advanced the
+    // factoryState.
+    releaseSupersededRun(run, threadId, completedTurnId) {
+        this.withHeldLease(run.projectId, run.linearIssueId, () => {
+            this.db.runs.finishRun(run.id, {
+                status: "superseded",
+                threadId,
+                ...(completedTurnId ? { turnId: completedTurnId } : {}),
+                failureReason: run.failureReason ?? "approved on the same head; further publication suppressed",
+            });
+            this.db.issues.upsertIssue({
+                projectId: run.projectId,
+                linearIssueId: run.linearIssueId,
+                activeRunId: null,
+                pendingRunType: null,
+                pendingRunContextJson: null,
+            });
+        });
+        this.clearProgressAndRelease(run);
+        this.feed?.publish({
+            level: "info",
+            kind: "agent",
+            summary: `Run #${run.id} superseded — publication suppressed (approved on the same head)`,
+            ...(run.projectId ? { projectId: run.projectId } : {}),
+        });
+    }
     enqueuePendingWakeIfPresent(params) {
         const wake = this.db.issueSessions.peekIssueSessionWake(params.run.projectId, params.run.linearIssueId);
         if (!wake)
@@ -201,6 +265,19 @@ export class RunFinalizer {
     }
     async finalizeCompletedRun(params) {
         const { run, issue, thread, threadId } = params;
+        // Plan §4.4: a run flagged shouldNotPublish was deliberately
+        // superseded mid-flight (the PR was approved on the same head
+        // while a review_fix run was still producing output). The Codex
+        // turn may have completed; the finalizer must NOT run any of
+        // the publication-verification policies — they all assume the
+        // run was supposed to publish, and would either fail it
+        // spuriously (`verifyReviewFixAdvancedHead`) or open new
+        // follow-up work. Just record the supersedure outcome and
+        // release the lease.
+        if (run.shouldNotPublish || run.status === "superseded") {
+            this.releaseSupersededRun(run, threadId, params.completedTurnId);
+            return;
+        }
         const trackedIssue = this.db.issueToTrackedIssue(issue);
         const report = buildStageReport({ ...run, status: "completed" }, trackedIssue, thread, countEventMethods(this.db.runs.listThreadEvents(run.id)));
         const freshIssue = this.db.issues.getIssue(run.projectId, run.linearIssueId) ?? issue;
@@ -268,6 +345,12 @@ export class RunFinalizer {
             return;
         }
         const refreshedIssue = await this.completionPolicy.refreshIssueAfterReactivePublish(run, freshIssue);
+        // Plan §4.2(c): post-hoc change-identity detection. When the run
+        // produced a new head SHA, compute and persist the patch-id and
+        // integration-tree-id so the next run's prompt rule can recognize
+        // a patch-id-equivalent re-push and skip the publish. Best-effort:
+        // any git error returns undefined and we leave the cache as-is.
+        this.maybeUpdateLastPublishedIdentity(run, refreshedIssue);
         const postRunFollowUp = await this.completionPolicy.resolvePostRunFollowUp(run, refreshedIssue);
         const postRunState = postRunFollowUp?.factoryState ?? resolveCompletedRunState(refreshedIssue, run);
         const publicationRecapSummary = await this.generatePublicationRecap({

package/package.json

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