patchrelay 0.37.1 → 0.38.0

package/README.md

@@ -1,8 +1,8 @@
 # PatchRelay
 
-PatchRelay is a self-hosted harness for delegated Linear work and upkeep of PatchRelay-owned pull requests on your own machine.
+PatchRelay is a self-hosted harness for delegated Linear work and upkeep of linked pull requests on your own machine.
 
-It receives Linear webhooks, routes issues to the right local repository, prepares durable issue worktrees, runs Codex sessions through `codex app-server`, and keeps the issue loop observable and resumable from the CLI. GitHub webhooks drive reactive loops for CI repair, review fixes, and merge-steward incidents on PatchRelay-owned PRs. Separate downstream services own review automation and merge execution.
+It receives Linear webhooks, routes issues to the right local repository, prepares durable issue worktrees, runs Codex sessions through `codex app-server`, and keeps the issue loop observable and resumable from the CLI. GitHub webhooks drive reactive loops for CI repair, review fixes, and merge-steward incidents on linked delegated PRs. Separate downstream services own review automation and merge execution.
 
 PatchRelay is the system around the model:
 
@@ -38,8 +38,9 @@ PatchRelay does the deterministic harness work that you do not want to re-implem
 - creates and reuses one durable worktree and branch per issue lifecycle
 - starts Codex threads for implementation runs
 - triggers reactive runs for CI failures, review feedback, and Merge Steward evictions
-- opens and updates PatchRelay-owned PRs
+- opens and updates PRs for delegated implementation work
 - marks its own PRs ready when implementation is complete
+- can later repair a linked PR that was opened externally once the issue is delegated
 - persists enough state to correlate the Linear issue, local workspace, run, and Codex thread
 - reports progress back to Linear and forwards follow-up agent input into active runs
 - exposes CLI and optional read-only inspection surfaces so operators can understand what happened
@@ -87,19 +88,48 @@ You will also need:
 5. GitHub webhooks drive reactive verification and repair loops: CI repair on check failures and review fix on changes requested.
 6. PatchRelay opens draft PRs while implementation is in progress and marks its own PR ready when implementation is complete.
 7. Downstream automation reacts to GitHub truth: `reviewbot` reviews ready PRs with green CI, and Merge Steward admits ready PRs with green CI and approval into the merge queue.
-8. If requested changes, red CI, or a merge-steward incident lands on a PatchRelay-owned PR, PatchRelay resumes work on that same PR branch.
+8. If requested changes, red CI, or a merge-steward incident lands on a linked delegated PR, PatchRelay resumes work on that same PR branch.
 9. Native agent prompts and Linear comments can steer the active run. An operator can take over from the exact same worktree when needed.
 
+### Undelegation And Re-delegation
+
+Undelegation pauses PatchRelay authority. It does not erase PR truth.
+
+- If there is no PR yet, the issue keeps its literal local-work state such as `delegated` or `implementing`, but PatchRelay becomes paused.
+- If a PR already exists, the issue keeps its PR-backed state and PatchRelay becomes observer-only.
+- Worktrees, branches, and PRs remain in place.
+- PatchRelay still reflects GitHub review, CI, queue, merge, and close events while undelegated.
+- PatchRelay does not enqueue implementation, review-fix, CI-repair, or queue-repair work again until the issue is delegated back.
+- If someone opens a new PR for the issue while it is undelegated, PatchRelay can link that PR when the title, body, or branch name contains one unambiguous tracked issue key for the project.
+
+Downstream services stay PR-centric:
+
+- `review-quill` may still review a qualifying PR
+- `merge-steward` may still queue or merge a qualifying PR
+
+When the issue is delegated back to PatchRelay, it should resume from current truth:
+
+- no PR: queue implementation
+- PR with requested changes: queue review fix or branch upkeep
+- PR with failing CI: queue CI repair
+- PR with queue eviction/conflict: queue queue repair
+- healthy open PR: keep waiting on review
+- approved PR: keep waiting downstream
+
 ## Ownership Model
 
-PatchRelay tracks two different kinds of ownership:
+PatchRelay keeps ownership simple:
+
+- workflow truth: the current factory state plus GitHub PR/review/CI facts
+- runtime authority: whether PatchRelay may actively write or repair code right now
+
+PatchRelay persists one explicit authority bit:
 
-- issue ownership: who may start new delegated implementation work from Linear
-- PR ownership: who is responsible for keeping an existing PR healthy until it merges or closes
+- `delegatedToPatchRelay`: whether PatchRelay may actively implement or repair code for the issue right now
 
-For PatchRelay, PR ownership is determined by one concrete GitHub fact: a PR is PatchRelay-owned when its author is the PatchRelay GitHub app or service account.
+Once a PR is linked to an issue, delegation decides whether PatchRelay may repair it. The PR may have been opened by PatchRelay, a human, or another external system.
 
-That ownership does not change just because:
+That authority does not change just because:
 
 - the issue is undelegated
 - the PR becomes ready for review
@@ -138,6 +168,14 @@ The long-term runtime model is a small durable `IssueSession`:
 
 Waiting on review or queue should be represented as a waiting reason, not as a large internal control-plane state machine.
 
+`awaiting_input` is reserved for real human-needed situations:
+
+- a completion check asked a question
+- an operator explicitly stopped the run and wants a next decision
+- a reply is required before PatchRelay can continue
+
+Undelegated local work should stay in its literal workflow state and show a paused waiting reason instead.
+
 ## Restart And Reconciliation
 
 PatchRelay treats restart safety as part of the harness contract, not as a best-effort extra.

package/dist/awaiting-input-reason.js

@@ -0,0 +1,9 @@
+export function resolveAwaitingInputReason(params) {
+    if (params.issue.factoryState !== "awaiting_input") {
+        return undefined;
+    }
+    if (params.latestRun?.completionCheckOutcome === "needs_input") {
+        return "completion_check_question";
+    }
+    return "paused_local_work";
+}

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "service": "patchrelay",
-  "version": "0.37.1",
-  "commit": "e2c1f3d45497",
-  "builtAt": "2026-04-10T17:31:17.533Z"
+  "version": "0.38.0",
+  "commit": "ec38527e2d4f",
+  "builtAt": "2026-04-10T17:39:33.237Z"
 }

package/dist/cli/cluster-health.js

@@ -302,6 +302,7 @@ async function evaluateGitHubIssueHealth(snapshot, config, runCommand, reviewQui
     }
     const ciEntry = buildCiEntry({
         issue,
+        delegatedToPatchRelay: issue.delegatedToPatchRelay,
         gateCheckStatus,
         reviewDecision,
         reviewRequested,
@@ -310,7 +311,31 @@ async function evaluateGitHubIssueHealth(snapshot, config, runCommand, reviewQui
         mergeConflictDetected,
         reviewQuillAttempt,
     });
-    if (gateCheckStatus === "failure" && issue.factoryState !== "repairing_ci" && issue.activeRunId === undefined && ageMs >= RECONCILIATION_GRACE_MS) {
+    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"
+        && issue.activeRunId === undefined
+        && ageMs >= RECONCILIATION_GRACE_MS) {
         return {
             ciEntry,
             finding: {
@@ -333,6 +358,7 @@ async function evaluateGitHubIssueHealth(snapshot, config, runCommand, reviewQui
     if (gateCheckStatus === "success"
         && reviewDecision === "CHANGES_REQUESTED"
         && mergeConflictDetected
+        && issue.delegatedToPatchRelay
         && issue.factoryState !== "changes_requested"
         && issue.activeRunId === undefined
         && ageMs >= RECONCILIATION_GRACE_MS) {
@@ -349,6 +375,7 @@ async function evaluateGitHubIssueHealth(snapshot, config, runCommand, reviewQui
         && reviewDecision === "CHANGES_REQUESTED"
         && latestBlockingReviewHeadSha === pr.headRefOid
         && !reviewQuillAttempt
+        && issue.delegatedToPatchRelay
         && issue.factoryState !== "changes_requested"
         && ageMs >= RECONCILIATION_GRACE_MS) {
         return {
@@ -370,7 +397,11 @@ async function evaluateGitHubIssueHealth(snapshot, config, runCommand, reviewQui
             },
         };
     }
-    if (issue.factoryState === "awaiting_queue" && mergeConflictDetected && issue.activeRunId === undefined && ageMs >= RECONCILIATION_GRACE_MS) {
+    if (issue.delegatedToPatchRelay
+        && issue.factoryState === "awaiting_queue"
+        && mergeConflictDetected
+        && issue.activeRunId === undefined
+        && ageMs >= RECONCILIATION_GRACE_MS) {
         return {
             ciEntry,
             finding: {
@@ -393,8 +424,9 @@ async function evaluateGitHubIssueHealth(snapshot, config, runCommand, reviewQui
     return { ciEntry };
 }
 function buildCiEntry(params) {
-    const { issue, gateCheckStatus, reviewDecision, reviewRequested, currentHeadSha, latestBlockingReviewHeadSha, mergeConflictDetected, reviewQuillAttempt, } = params;
+    const { issue, delegatedToPatchRelay, gateCheckStatus, reviewDecision, reviewRequested, currentHeadSha, latestBlockingReviewHeadSha, mergeConflictDetected, reviewQuillAttempt, } = params;
     const owner = deriveCiOwner({
+        delegatedToPatchRelay,
         gateCheckStatus,
         factoryState: issue.factoryState,
         reviewDecision,
@@ -414,6 +446,7 @@ function buildCiEntry(params) {
         factoryState: issue.factoryState,
         ...(reviewDecision ? { reviewDecision } : {}),
         message: describeCiOwnership({
+            delegatedToPatchRelay,
             gateCheckStatus,
             owner,
             reviewDecision,
@@ -430,20 +463,29 @@ function deriveCiOwner(params) {
         && 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)
@@ -502,6 +544,20 @@ function describeCiOwnership(params) {
             ? "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

package/dist/cli/help.js

@@ -144,7 +144,7 @@ export function issueHelpText() {
         "Commands:",
         "  show <issueKey>                 Show the latest known issue state",
         "  list                            List tracked issues",
-        "  watch <issueKey>                Follow PatchRelay-owned activity until it settles",
+        "  watch <issueKey>                Follow issue activity until it settles",
         "  path <issueKey>                 Print the issue worktree path",
         "  open <issueKey>                 Open Codex in the issue worktree",
         "  sessions <issueKey>             Show recorded Codex app-server sessions",

package/dist/cli/output.js

@@ -56,6 +56,8 @@ function formatCiOwnerLabel(owner) {
             return "merge-queue";
         case "external":
             return "ci/github";
+        case "paused":
+            return "paused";
         default:
             return "missing";
     }

package/dist/db/issue-session-store.js

@@ -263,20 +263,6 @@ export class IssueSessionStore {
       WHERE project_id = ? AND linear_issue_id = ?
     `).run(lastWakeReason ?? null, isoNow(), projectId, linearIssueId);
     }
-    setBranchOwnerWithLease(lease, owner) {
-        return this.withIssueSessionLease(lease.projectId, lease.linearIssueId, lease.leaseId, () => {
-            this.issues.setBranchOwner(lease.projectId, lease.linearIssueId, owner);
-            return true;
-        }) ?? false;
-    }
-    setBranchOwnerRespectingActiveLease(projectId, linearIssueId, owner) {
-        const lease = this.getActiveIssueSessionLease(projectId, linearIssueId);
-        if (!lease) {
-            this.issues.setBranchOwner(projectId, linearIssueId, owner);
-            return true;
-        }
-        return this.setBranchOwnerWithLease(lease, owner);
-    }
     releaseIssueSessionLeaseRespectingActiveLease(projectId, linearIssueId) {
         const lease = this.getActiveIssueSessionLease(projectId, linearIssueId);
         this.releaseIssueSessionLease(projectId, linearIssueId, lease?.leaseId);

package/dist/db/issue-store.js

@@ -16,6 +16,10 @@ export class IssueStore {
                 projectId: params.projectId,
                 linearIssueId: params.linearIssueId,
             };
+            if (params.delegatedToPatchRelay !== undefined) {
+                sets.push("delegated_to_patchrelay = @delegatedToPatchRelay");
+                values.delegatedToPatchRelay = params.delegatedToPatchRelay ? 1 : 0;
+            }
             if (params.issueKey !== undefined) {
                 sets.push("issue_key = COALESCE(@issueKey, issue_key)");
                 values.issueKey = params.issueKey;
@@ -205,7 +209,7 @@ export class IssueStore {
         else {
             this.connection.prepare(`
         INSERT INTO issues (
-          project_id, linear_issue_id, issue_key, title, description, url,
+          project_id, linear_issue_id, delegated_to_patchrelay, issue_key, title, description, url,
           priority, estimate,
           current_linear_state, current_linear_state_type, factory_state, pending_run_type, pending_run_context_json,
           branch_name, worktree_path, thread_id, active_run_id, status_comment_id,
@@ -218,7 +222,7 @@ export class IssueStore {
           ci_repair_attempts, queue_repair_attempts, review_fix_attempts, zombie_recovery_attempts, last_zombie_recovery_at,
           updated_at
         ) VALUES (
-          @projectId, @linearIssueId, @issueKey, @title, @description, @url,
+          @projectId, @linearIssueId, @delegatedToPatchRelay, @issueKey, @title, @description, @url,
           @priority, @estimate,
           @currentLinearState, @currentLinearStateType, @factoryState, @pendingRunType, @pendingRunContextJson,
           @branchName, @worktreePath, @threadId, @activeRunId, @statusCommentId,
@@ -234,6 +238,7 @@ export class IssueStore {
       `).run({
                 projectId: params.projectId,
                 linearIssueId: params.linearIssueId,
+                delegatedToPatchRelay: params.delegatedToPatchRelay === false ? 0 : 1,
                 issueKey: params.issueKey ?? null,
                 title: params.title ?? null,
                 description: params.description ?? null,
@@ -357,14 +362,6 @@ export class IssueStore {
             .all();
         return rows.map(mapIssueRow);
     }
-    setBranchOwner(projectId, linearIssueId, owner) {
-        const now = isoNow();
-        this.connection.prepare(`
-      UPDATE issues
-      SET branch_owner = ?, branch_ownership_changed_at = ?, updated_at = ?
-      WHERE project_id = ? AND linear_issue_id = ?
-    `).run(owner, now, now, projectId, linearIssueId);
-    }
     replaceIssueDependencies(params) {
         const now = isoNow();
         this.connection
@@ -466,6 +463,7 @@ export function mapIssueRow(row) {
         id: Number(row.id),
         projectId: String(row.project_id),
         linearIssueId: String(row.linear_issue_id),
+        delegatedToPatchRelay: Number(row.delegated_to_patchrelay ?? 1) !== 0,
         ...(row.issue_key !== null ? { issueKey: String(row.issue_key) } : {}),
         ...(row.title !== null ? { title: String(row.title) } : {}),
         ...(row.description !== null && row.description !== undefined ? { description: String(row.description) } : {}),
@@ -480,12 +478,6 @@ export function mapIssueRow(row) {
         ...(row.pending_run_type !== null && row.pending_run_type !== undefined ? { pendingRunType: String(row.pending_run_type) } : {}),
         ...(row.pending_run_context_json !== null && row.pending_run_context_json !== undefined ? { pendingRunContextJson: String(row.pending_run_context_json) } : {}),
         ...(row.branch_name !== null ? { branchName: String(row.branch_name) } : {}),
-        ...(row.branch_owner !== null && row.branch_owner !== undefined && String(row.branch_owner) === "patchrelay"
-            ? { branchOwner: "patchrelay" }
-            : { branchOwner: "patchrelay" }),
-        ...(row.branch_ownership_changed_at !== null && row.branch_ownership_changed_at !== undefined
-            ? { branchOwnershipChangedAt: String(row.branch_ownership_changed_at) }
-            : {}),
         ...(row.worktree_path !== null ? { worktreePath: String(row.worktree_path) } : {}),
         ...(row.thread_id !== null ? { threadId: String(row.thread_id) } : {}),
         ...(row.active_run_id !== null ? { activeRunId: Number(row.active_run_id) } : {}),

package/dist/db/migrations.js

@@ -3,6 +3,7 @@ CREATE TABLE IF NOT EXISTS issues (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   project_id TEXT NOT NULL,
   linear_issue_id TEXT NOT NULL,
+  delegated_to_patchrelay INTEGER NOT NULL DEFAULT 1,
   issue_key TEXT,
   title TEXT,
   url TEXT,
@@ -12,8 +13,6 @@ CREATE TABLE IF NOT EXISTS issues (
   pending_run_type TEXT,
   pending_run_context_json TEXT,
   branch_name TEXT,
-  branch_owner TEXT NOT NULL DEFAULT 'patchrelay',
-  branch_ownership_changed_at TEXT,
   worktree_path TEXT,
   thread_id TEXT,
   active_run_id INTEGER,
@@ -239,12 +238,9 @@ export function runPatchRelayMigrations(connection) {
     connection.exec(schema);
     // Clean up stale dedupe-only webhook records (no payload, never processable)
     connection.prepare("UPDATE webhook_events SET processing_status = 'processed' WHERE processing_status = 'pending' AND payload_json IS NULL").run();
+    addColumnIfMissing(connection, "issues", "delegated_to_patchrelay", "INTEGER NOT NULL DEFAULT 1");
     // Add pending_merge_prep column for merge queue stewardship
     addColumnIfMissing(connection, "issues", "pending_merge_prep", "INTEGER NOT NULL DEFAULT 0");
-    // Explicit PR branch ownership hand-off between PatchRelay and MergeSteward
-    addColumnIfMissing(connection, "issues", "branch_owner", "TEXT NOT NULL DEFAULT 'patchrelay'");
-    addColumnIfMissing(connection, "issues", "branch_ownership_changed_at", "TEXT");
-    connection.prepare("UPDATE issues SET branch_owner = 'patchrelay' WHERE branch_owner IS NULL OR branch_owner != 'patchrelay'").run();
     // Add merge_prep_attempts for retry budget / escalation
     addColumnIfMissing(connection, "issues", "merge_prep_attempts", "INTEGER NOT NULL DEFAULT 0");
     // Add review_fix_attempts counter
@@ -304,7 +300,7 @@ function addColumnIfMissing(connection, table, column, definition) {
 function removeRetiredIssueColumnsIfPresent(connection) {
     const cols = connection.prepare("PRAGMA table_info(issues)").all();
     const columnNames = new Set(cols.map((column) => String(column.name)));
-    const retired = ["queue_label_applied", "pending_merge_prep", "merge_prep_attempts"];
+    const retired = ["queue_label_applied", "pending_merge_prep", "merge_prep_attempts", "branch_owner", "branch_ownership_changed_at"];
     if (!retired.some((name) => columnNames.has(name))) {
         return;
     }
@@ -315,6 +311,7 @@ function removeRetiredIssueColumnsIfPresent(connection) {
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         project_id TEXT NOT NULL,
         linear_issue_id TEXT NOT NULL,
+        delegated_to_patchrelay INTEGER NOT NULL DEFAULT 1,
         issue_key TEXT,
         title TEXT,
         description TEXT,
@@ -327,8 +324,6 @@ function removeRetiredIssueColumnsIfPresent(connection) {
         pending_run_type TEXT,
         pending_run_context_json TEXT,
         branch_name TEXT,
-        branch_owner TEXT NOT NULL DEFAULT 'patchrelay',
-        branch_ownership_changed_at TEXT,
         worktree_path TEXT,
         thread_id TEXT,
         active_run_id INTEGER,
@@ -371,6 +366,7 @@ function removeRetiredIssueColumnsIfPresent(connection) {
         id,
         project_id,
         linear_issue_id,
+        delegated_to_patchrelay,
         issue_key,
         title,
         description,
@@ -383,8 +379,6 @@ function removeRetiredIssueColumnsIfPresent(connection) {
         pending_run_type,
         pending_run_context_json,
         branch_name,
-        branch_owner,
-        branch_ownership_changed_at,
         worktree_path,
         thread_id,
         active_run_id,
@@ -425,6 +419,7 @@ function removeRetiredIssueColumnsIfPresent(connection) {
         id,
         project_id,
         linear_issue_id,
+        COALESCE(delegated_to_patchrelay, 1),
         issue_key,
         title,
         description,
@@ -437,8 +432,6 @@ function removeRetiredIssueColumnsIfPresent(connection) {
         pending_run_type,
         pending_run_context_json,
         branch_name,
-        COALESCE(branch_owner, 'patchrelay'),
-        branch_ownership_changed_at,
         worktree_path,
         thread_id,
         active_run_id,

package/dist/db.js

@@ -34,6 +34,7 @@ function hasUnattemptedFailureSignature(issue, fallbackHeadSha) {
 }
 function deriveImplicitReactiveWake(issue) {
     const reactiveIntent = deriveIssueSessionReactiveIntent({
+        delegatedToPatchRelay: issue.delegatedToPatchRelay,
         activeRunId: issue.activeRunId,
         prNumber: issue.prNumber,
         prState: issue.prState,
@@ -144,9 +145,6 @@ export class PatchRelayDatabase {
     getIssueByPrNumber(prNumber) {
         return this.issues.getIssueByPrNumber(prNumber);
     }
-    setBranchOwner(projectId, linearIssueId, owner) {
-        this.issues.setBranchOwner(projectId, linearIssueId, owner);
-    }
     replaceIssueDependencies(params) {
         this.issues.replaceIssueDependencies(params);
     }