patchrelay 0.36.11 → 0.36.13

package/dist/run-orchestrator.js

@@ -1,17 +1,17 @@
-import { TERMINAL_STATES } from "./factory-state.js";
-import { extractTurnId, resolveRunCompletionStatus, summarizeCurrentThread } from "./run-reporting.js";
-import { buildRunFailureActivity, buildRunStartedActivity, } from "./linear-session-reporting.js";
+import { summarizeCurrentThread } from "./run-reporting.js";
+import { buildRunStartedActivity, } from "./linear-session-reporting.js";
 import { WorktreeManager } from "./worktree-manager.js";
-import { resolveAuthoritativeLinearStopState, resolvePreferredCompletedLinearState } from "./linear-workflow.js";
-import { getThreadTurns } from "./codex-thread-utils.js";
+import { resolvePreferredCompletedLinearState } from "./linear-workflow.js";
 import { QueueHealthMonitor } from "./queue-health-monitor.js";
 import { IdleIssueReconciler, resolveBranchOwnerForStateTransition } from "./idle-reconciliation.js";
 import { LinearSessionSync } from "./linear-session-sync.js";
 import { IssueSessionLeaseService } from "./issue-session-lease-service.js";
-import { InterruptedRunRecovery, resolveRecoverablePostRunState } from "./interrupted-run-recovery.js";
+import { InterruptedRunRecovery } from "./interrupted-run-recovery.js";
 import { RunCompletionPolicy } from "./run-completion-policy.js";
 import { RunFinalizer } from "./run-finalizer.js";
 import { RunLauncher } from "./run-launcher.js";
+import { RunNotificationHandler } from "./run-notification-handler.js";
+import { RunReconciler } from "./run-reconciler.js";
 import { RunRecoveryService } from "./run-recovery-service.js";
 import { RunWakePlanner } from "./run-wake-planner.js";
 import { getRemainingZombieRecoveryDelayMs } from "./zombie-recovery.js";
@@ -41,7 +41,6 @@ export class RunOrchestrator {
     queueHealthMonitor;
     idleReconciler;
     linearSync;
-    activeThreadId;
     workerId = `patchrelay:${process.pid}`;
     leaseService;
     runFinalizer;
@@ -50,6 +49,8 @@ export class RunOrchestrator {
     runWakePlanner;
     interruptedRunRecovery;
     runCompletionPolicy;
+    runNotificationHandler;
+    runReconciler;
     activeSessionLeases;
     botIdentity;
     constructor(config, db, codex, linearProvider, enqueueIssue, logger, feed) {
@@ -67,8 +68,10 @@ export class RunOrchestrator {
         this.runCompletionPolicy = new RunCompletionPolicy(config, db, logger, (projectId, linearIssueId, fn) => this.withHeldIssueSessionLease(projectId, linearIssueId, fn));
         this.runFinalizer = new RunFinalizer(db, logger, this.linearSync, this.enqueueIssue, (projectId, linearIssueId, fn) => this.withHeldIssueSessionLease(projectId, linearIssueId, fn), (projectId, linearIssueId) => this.releaseIssueSessionLease(projectId, linearIssueId), (lease, issue, runType, context, dedupeScope) => this.appendWakeEventWithLease(lease, issue, runType, context, dedupeScope), (run, message, nextState) => this.failRunAndClear(run, message, nextState), this.runCompletionPolicy, feed);
         this.runLauncher = new RunLauncher(config, db, codex, logger, this.worktreeManager);
+        this.runNotificationHandler = new RunNotificationHandler(config, db, logger, this.linearSync, this.runFinalizer, (threadId, maxRetries) => this.readThreadWithRetry(threadId, maxRetries), (projectId, linearIssueId, fn) => this.withHeldIssueSessionLease(projectId, linearIssueId, fn), (projectId, linearIssueId) => this.heartbeatIssueSessionLease(projectId, linearIssueId), (projectId, linearIssueId) => this.releaseIssueSessionLease(projectId, linearIssueId), feed);
         this.runRecovery = new RunRecoveryService(db, logger, this.linearSync, (projectId, linearIssueId, fn) => this.withHeldIssueSessionLease(projectId, linearIssueId, fn), (projectId, linearIssueId) => this.getHeldIssueSessionLease(projectId, linearIssueId), (lease, issue, runType, context, dedupeScope) => this.appendWakeEventWithLease(lease, issue, runType, context, dedupeScope), (projectId, linearIssueId) => this.releaseIssueSessionLease(projectId, linearIssueId), (projectId, issueId) => this.enqueueIssue(projectId, issueId), (newState, pendingRunType) => this.resolveBranchOwnerForStateTransition(newState, pendingRunType), feed);
         this.interruptedRunRecovery = new InterruptedRunRecovery(db, logger, this.linearSync, (projectId, linearIssueId, fn) => this.withHeldIssueSessionLease(projectId, linearIssueId, fn), (projectId, linearIssueId) => this.releaseIssueSessionLease(projectId, linearIssueId), (run, message, nextState) => this.failRunAndClear(run, message, nextState), (issue) => this.restoreIdleWorktree(issue), this.runCompletionPolicy, (projectId, issueId) => this.enqueueIssue(projectId, issueId), feed);
+        this.runReconciler = new RunReconciler(db, logger, linearProvider, this.linearSync, this.interruptedRunRecovery, this.runFinalizer, (projectId, linearIssueId, fn) => this.withHeldIssueSessionLease(projectId, linearIssueId, fn), (projectId, linearIssueId) => this.releaseIssueSessionLease(projectId, linearIssueId), (threadId, maxRetries) => this.readThreadWithRetry(threadId, maxRetries), (issue, runType, reason) => this.recoverOrEscalate(issue, runType, reason), feed);
         this.runWakePlanner = new RunWakePlanner(db);
         this.idleReconciler = new IdleIssueReconciler(db, config, {
             enqueueIssue: (projectId, issueId) => this.enqueueIssue(projectId, issueId),
@@ -219,101 +222,7 @@ export class RunOrchestrator {
     }
     // ─── Notification handler ─────────────────────────────────────────
     async handleCodexNotification(notification) {
-        // threadId is present on turn-level notifications but NOT on item-level ones.
-        // Fall back to the tracked active thread for item/delta notifications.
-        let threadId = typeof notification.params.threadId === "string" ? notification.params.threadId : undefined;
-        if (!threadId) {
-            threadId = this.activeThreadId;
-        }
-        if (!threadId)
-            return;
-        // Track the active thread from turn/started so item notifications can find it
-        if (notification.method === "turn/started" && threadId) {
-            this.activeThreadId = threadId;
-        }
-        const run = this.db.runs.getRunByThreadId(threadId);
-        if (!run)
-            return;
-        if (!this.heartbeatIssueSessionLease(run.projectId, run.linearIssueId)) {
-            this.logger.warn({ runId: run.id, issueId: run.linearIssueId }, "Ignoring Codex notification after losing issue-session lease");
-            return;
-        }
-        const turnId = typeof notification.params.turnId === "string" ? notification.params.turnId : undefined;
-        if (this.config.runner.codex.persistExtendedHistory) {
-            this.db.runs.saveThreadEvent({
-                runId: run.id,
-                threadId,
-                ...(turnId ? { turnId } : {}),
-                method: notification.method,
-                eventJson: JSON.stringify(notification.params),
-            });
-        }
-        // Emit ephemeral progress activity to Linear for notable in-flight events
-        this.linearSync.maybeEmitProgress(notification, run);
-        // Sync codex plan to Linear session when it updates
-        if (notification.method === "turn/plan/updated") {
-            const issue = this.db.issues.getIssue(run.projectId, run.linearIssueId);
-            if (issue) {
-                void this.linearSync.syncCodexPlan(issue, notification.params);
-            }
-        }
-        if (notification.method !== "turn/completed")
-            return;
-        const thread = await this.readThreadWithRetry(threadId);
-        const issue = this.db.issues.getIssue(run.projectId, run.linearIssueId);
-        if (!issue)
-            return;
-        const completedTurnId = extractTurnId(notification.params);
-        const status = resolveRunCompletionStatus(notification.params);
-        if (status === "failed") {
-            const nextState = isRequestedChangesRunType(run.runType) ? "escalated" : "failed";
-            const updated = this.withHeldIssueSessionLease(run.projectId, run.linearIssueId, (lease) => {
-                this.db.issueSessions.finishRunWithLease(lease, run.id, {
-                    status: "failed",
-                    threadId,
-                    ...(completedTurnId ? { turnId: completedTurnId } : {}),
-                    failureReason: "Codex reported the turn completed in a failed state",
-                });
-                this.db.issueSessions.upsertIssueWithLease(lease, {
-                    projectId: run.projectId,
-                    linearIssueId: run.linearIssueId,
-                    activeRunId: null,
-                    factoryState: nextState,
-                });
-                return true;
-            });
-            if (!updated) {
-                this.logger.warn({ runId: run.id, issueId: run.linearIssueId }, "Skipping failed-turn cleanup after losing issue-session lease");
-                this.releaseIssueSessionLease(run.projectId, run.linearIssueId);
-                return;
-            }
-            this.feed?.publish({
-                level: "error",
-                kind: "turn",
-                issueKey: issue.issueKey,
-                projectId: run.projectId,
-                stage: run.runType,
-                status: "failed",
-                summary: `Turn failed for ${run.runType}`,
-            });
-            const failedIssue = this.db.issues.getIssue(run.projectId, run.linearIssueId) ?? issue;
-            void this.linearSync.emitActivity(failedIssue, buildRunFailureActivity(run.runType));
-            void this.linearSync.syncSession(failedIssue, { activeRunType: run.runType });
-            this.linearSync.clearProgress(run.id);
-            this.activeThreadId = undefined;
-            this.releaseIssueSessionLease(run.projectId, run.linearIssueId);
-            return;
-        }
-        await this.runFinalizer.finalizeCompletedRun({
-            source: "notification",
-            run,
-            issue,
-            thread,
-            threadId,
-            ...(completedTurnId ? { completedTurnId } : {}),
-            resolveRecoverableRunState: resolveRecoverablePostRunState,
-        });
-        this.activeThreadId = undefined;
+        await this.runNotificationHandler.handle(notification);
     }
     // ─── Active status for query ──────────────────────────────────────
     async getActiveRunStatus(issueKey) {
@@ -408,114 +317,7 @@ export class RunOrchestrator {
         }
         if (recoveryLease === "skip")
             return;
-        const acquiredRecoveryLease = recoveryLease === true;
-        // If the issue reached a terminal state while this run was active
-        // (e.g. pr_merged processed, DB manually edited), just release the run.
-        if (TERMINAL_STATES.has(issue.factoryState)) {
-            this.withHeldIssueSessionLease(run.projectId, run.linearIssueId, () => {
-                this.db.runs.finishRun(run.id, { status: "released", failureReason: "Issue reached terminal state during active run" });
-                this.db.issues.upsertIssue({ projectId: run.projectId, linearIssueId: run.linearIssueId, activeRunId: null });
-            });
-            this.logger.info({ issueKey: issue.issueKey, runId: run.id, factoryState: issue.factoryState }, "Reconciliation: released run on terminal issue");
-            const releasedIssue = this.db.issues.getIssue(run.projectId, run.linearIssueId) ?? issue;
-            void this.linearSync.syncSession(releasedIssue, { activeRunType: run.runType });
-            this.releaseIssueSessionLease(run.projectId, run.linearIssueId);
-            return;
-        }
-        // Zombie run: claimed in DB but Codex never started (no thread).
-        // If this process still owns the live lease, launch may still be in flight
-        // between worktree prep and Codex thread creation, so do not self-recover it.
-        if (!run.threadId) {
-            if (recoveryLease === "owned") {
-                this.logger.debug({ issueKey: issue.issueKey, runId: run.id, runType: run.runType }, "Skipping zombie reconciliation for locally-owned launch that has not created a thread yet");
-                return;
-            }
-            this.logger.warn({ issueKey: issue.issueKey, runId: run.id, runType: run.runType }, "Zombie run detected (no thread)");
-            this.withHeldIssueSessionLease(run.projectId, run.linearIssueId, () => {
-                this.db.runs.finishRun(run.id, { status: "failed", failureReason: "Zombie: never started (no thread after restart)" });
-                this.db.issues.upsertIssue({ projectId: run.projectId, linearIssueId: run.linearIssueId, activeRunId: null });
-            });
-            this.recoverOrEscalate(issue, run.runType, "zombie");
-            const recoveredIssue = this.db.issues.getIssue(run.projectId, run.linearIssueId) ?? issue;
-            void this.linearSync.emitActivity(recoveredIssue, buildRunFailureActivity(run.runType, "The Codex turn never started before PatchRelay restarted."));
-            void this.linearSync.syncSession(recoveredIssue, { activeRunType: run.runType });
-            this.releaseIssueSessionLease(run.projectId, run.linearIssueId);
-            return;
-        }
-        // Read Codex state — thread may not exist after app-server restart.
-        let thread;
-        try {
-            thread = await this.readThreadWithRetry(run.threadId);
-        }
-        catch {
-            this.logger.warn({ issueKey: issue.issueKey, runId: run.id, runType: run.runType, threadId: run.threadId }, "Stale thread during reconciliation");
-            this.withHeldIssueSessionLease(run.projectId, run.linearIssueId, () => {
-                this.db.runs.finishRun(run.id, { status: "failed", failureReason: "Stale thread after restart" });
-                this.db.issues.upsertIssue({ projectId: run.projectId, linearIssueId: run.linearIssueId, activeRunId: null });
-            });
-            this.recoverOrEscalate(issue, run.runType, "stale_thread");
-            const recoveredIssue = this.db.issues.getIssue(run.projectId, run.linearIssueId) ?? issue;
-            void this.linearSync.emitActivity(recoveredIssue, buildRunFailureActivity(run.runType, "PatchRelay lost the active Codex thread after restart and needs to recover."));
-            void this.linearSync.syncSession(recoveredIssue, { activeRunType: run.runType });
-            this.releaseIssueSessionLease(run.projectId, run.linearIssueId);
-            return;
-        }
-        // Check Linear state (non-fatal — token refresh may fail)
-        const linear = await this.linearProvider.forProject(run.projectId).catch(() => undefined);
-        if (linear) {
-            const linearIssue = await linear.getIssue(run.linearIssueId).catch(() => undefined);
-            if (linearIssue) {
-                const stopState = resolveAuthoritativeLinearStopState(linearIssue);
-                if (stopState?.isFinal) {
-                    this.withHeldIssueSessionLease(run.projectId, run.linearIssueId, () => {
-                        this.db.runs.finishRun(run.id, { status: "released" });
-                        this.db.issues.upsertIssue({
-                            projectId: run.projectId,
-                            linearIssueId: run.linearIssueId,
-                            activeRunId: null,
-                            currentLinearState: stopState.stateName,
-                            factoryState: "done",
-                        });
-                    });
-                    this.feed?.publish({
-                        level: "info",
-                        kind: "stage",
-                        issueKey: issue.issueKey,
-                        projectId: run.projectId,
-                        stage: "done",
-                        status: "reconciled",
-                        summary: `Linear state ${stopState.stateName} \u2192 done`,
-                    });
-                    const doneIssue = this.db.issues.getIssue(run.projectId, run.linearIssueId) ?? issue;
-                    void this.linearSync.syncSession(doneIssue, { activeRunType: run.runType });
-                    this.releaseIssueSessionLease(run.projectId, run.linearIssueId);
-                    return;
-                }
-            }
-        }
-        const latestTurn = getThreadTurns(thread).at(-1);
-        // Handle interrupted turn — fail the run rather than retrying indefinitely.
-        // The agent may have partially completed work (commits, PR) before interruption.
-        // Reactive loops (CI repair, review fix) will handle follow-up if needed.
-        if (latestTurn?.status === "interrupted") {
-            await this.interruptedRunRecovery.handle(run, issue);
-            return;
-        }
-        // Handle completed turn discovered during reconciliation
-        if (latestTurn?.status === "completed") {
-            await this.runFinalizer.finalizeCompletedRun({
-                source: "reconciliation",
-                run,
-                issue,
-                thread,
-                threadId: run.threadId,
-                ...(latestTurn.id ? { completedTurnId: latestTurn.id } : {}),
-                resolveRecoverableRunState: resolveRecoverablePostRunState,
-            });
-            return;
-        }
-        if (acquiredRecoveryLease)
-            this.releaseIssueSessionLease(run.projectId, run.linearIssueId);
+        await this.runReconciler.reconcile({ run, issue, recoveryLease });
     }
     // ─── Internal helpers ─────────────────────────────────────────────
     escalate(issue, runType, reason) {

package/dist/run-reconciler.js

@@ -0,0 +1,132 @@
+import { TERMINAL_STATES } from "./factory-state.js";
+import { resolveAuthoritativeLinearStopState } from "./linear-workflow.js";
+import { buildRunFailureActivity } from "./linear-session-reporting.js";
+import { getThreadTurns } from "./codex-thread-utils.js";
+import { resolveRecoverablePostRunState } from "./interrupted-run-recovery.js";
+export class RunReconciler {
+    db;
+    logger;
+    linearProvider;
+    linearSync;
+    interruptedRunRecovery;
+    runFinalizer;
+    withHeldLease;
+    releaseLease;
+    readThreadWithRetry;
+    recoverOrEscalate;
+    feed;
+    constructor(db, logger, linearProvider, linearSync, interruptedRunRecovery, runFinalizer, withHeldLease, releaseLease, readThreadWithRetry, recoverOrEscalate, feed) {
+        this.db = db;
+        this.logger = logger;
+        this.linearProvider = linearProvider;
+        this.linearSync = linearSync;
+        this.interruptedRunRecovery = interruptedRunRecovery;
+        this.runFinalizer = runFinalizer;
+        this.withHeldLease = withHeldLease;
+        this.releaseLease = releaseLease;
+        this.readThreadWithRetry = readThreadWithRetry;
+        this.recoverOrEscalate = recoverOrEscalate;
+        this.feed = feed;
+    }
+    async reconcile(params) {
+        const { run, issue, recoveryLease } = params;
+        const acquiredRecoveryLease = recoveryLease === true;
+        if (TERMINAL_STATES.has(issue.factoryState)) {
+            this.withHeldLease(run.projectId, run.linearIssueId, () => {
+                this.db.runs.finishRun(run.id, { status: "released", failureReason: "Issue reached terminal state during active run" });
+                this.db.issues.upsertIssue({ projectId: run.projectId, linearIssueId: run.linearIssueId, activeRunId: null });
+            });
+            this.logger.info({ issueKey: issue.issueKey, runId: run.id, factoryState: issue.factoryState }, "Reconciliation: released run on terminal issue");
+            const releasedIssue = this.db.issues.getIssue(run.projectId, run.linearIssueId) ?? issue;
+            void this.linearSync.syncSession(releasedIssue, { activeRunType: run.runType });
+            this.releaseLease(run.projectId, run.linearIssueId);
+            return;
+        }
+        if (!run.threadId) {
+            if (recoveryLease === "owned") {
+                this.logger.debug({ issueKey: issue.issueKey, runId: run.id, runType: run.runType }, "Skipping zombie reconciliation for locally-owned launch that has not created a thread yet");
+                return;
+            }
+            this.logger.warn({ issueKey: issue.issueKey, runId: run.id, runType: run.runType }, "Zombie run detected (no thread)");
+            this.withHeldLease(run.projectId, run.linearIssueId, () => {
+                this.db.runs.finishRun(run.id, { status: "failed", failureReason: "Zombie: never started (no thread after restart)" });
+                this.db.issues.upsertIssue({ projectId: run.projectId, linearIssueId: run.linearIssueId, activeRunId: null });
+            });
+            this.recoverOrEscalate(issue, run.runType, "zombie");
+            const recoveredIssue = this.db.issues.getIssue(run.projectId, run.linearIssueId) ?? issue;
+            void this.linearSync.emitActivity(recoveredIssue, buildRunFailureActivity(run.runType, "The Codex turn never started before PatchRelay restarted."));
+            void this.linearSync.syncSession(recoveredIssue, { activeRunType: run.runType });
+            this.releaseLease(run.projectId, run.linearIssueId);
+            return;
+        }
+        let thread;
+        try {
+            thread = await this.readThreadWithRetry(run.threadId);
+        }
+        catch {
+            this.logger.warn({ issueKey: issue.issueKey, runId: run.id, runType: run.runType, threadId: run.threadId }, "Stale thread during reconciliation");
+            this.withHeldLease(run.projectId, run.linearIssueId, () => {
+                this.db.runs.finishRun(run.id, { status: "failed", failureReason: "Stale thread after restart" });
+                this.db.issues.upsertIssue({ projectId: run.projectId, linearIssueId: run.linearIssueId, activeRunId: null });
+            });
+            this.recoverOrEscalate(issue, run.runType, "stale_thread");
+            const recoveredIssue = this.db.issues.getIssue(run.projectId, run.linearIssueId) ?? issue;
+            void this.linearSync.emitActivity(recoveredIssue, buildRunFailureActivity(run.runType, "PatchRelay lost the active Codex thread after restart and needs to recover."));
+            void this.linearSync.syncSession(recoveredIssue, { activeRunType: run.runType });
+            this.releaseLease(run.projectId, run.linearIssueId);
+            return;
+        }
+        const linear = await this.linearProvider.forProject(run.projectId).catch(() => undefined);
+        if (linear) {
+            const linearIssue = await linear.getIssue(run.linearIssueId).catch(() => undefined);
+            if (linearIssue) {
+                const stopState = resolveAuthoritativeLinearStopState(linearIssue);
+                if (stopState?.isFinal) {
+                    this.withHeldLease(run.projectId, run.linearIssueId, () => {
+                        this.db.runs.finishRun(run.id, { status: "released" });
+                        this.db.issues.upsertIssue({
+                            projectId: run.projectId,
+                            linearIssueId: run.linearIssueId,
+                            activeRunId: null,
+                            currentLinearState: stopState.stateName,
+                            factoryState: "done",
+                        });
+                    });
+                    this.feed?.publish({
+                        level: "info",
+                        kind: "stage",
+                        issueKey: issue.issueKey,
+                        projectId: run.projectId,
+                        stage: "done",
+                        status: "reconciled",
+                        summary: `Linear state ${stopState.stateName} -> done`,
+                    });
+                    const doneIssue = this.db.issues.getIssue(run.projectId, run.linearIssueId) ?? issue;
+                    void this.linearSync.syncSession(doneIssue, { activeRunType: run.runType });
+                    this.releaseLease(run.projectId, run.linearIssueId);
+                    return;
+                }
+            }
+        }
+        const latestTurn = getThreadTurns(thread).at(-1);
+        if (latestTurn?.status === "interrupted") {
+            await this.interruptedRunRecovery.handle(run, issue);
+            return;
+        }
+        if (latestTurn?.status === "completed") {
+            await this.runFinalizer.finalizeCompletedRun({
+                source: "reconciliation",
+                run,
+                issue,
+                thread,
+                threadId: run.threadId,
+                ...(latestTurn.id ? { completedTurnId: latestTurn.id } : {}),
+                resolveRecoverableRunState: resolveRecoverablePostRunState,
+            });
+            return;
+        }
+        if (acquiredRecoveryLease) {
+            this.releaseLease(run.projectId, run.linearIssueId);
+        }
+    }
+}

package/dist/tracked-issue-query.js

@@ -0,0 +1,67 @@
+import { buildTrackedIssueRecord } from "./tracked-issue-projector.js";
+import { deriveIssueSessionState, isIssueSessionReadyForExecution } from "./issue-session.js";
+export class TrackedIssueQuery {
+    issues;
+    issueSessions;
+    runs;
+    constructor(issues, issueSessions, runs) {
+        this.issues = issues;
+        this.issueSessions = issueSessions;
+        this.runs = runs;
+    }
+    listIssuesReadyForExecution() {
+        return this.issues.listIssues()
+            .filter((issue) => isIssueSessionReadyForExecution({
+            factoryState: issue.factoryState,
+            sessionState: deriveIssueSessionState({
+                activeRunId: issue.activeRunId,
+                factoryState: issue.factoryState,
+            }),
+            activeRunId: issue.activeRunId,
+            blockedByCount: this.issues.countUnresolvedBlockers(issue.projectId, issue.linearIssueId),
+            hasPendingWake: this.issueSessions.peekIssueSessionWake(issue.projectId, issue.linearIssueId) !== undefined,
+            hasLegacyPendingRun: issue.pendingRunType !== undefined,
+            prNumber: issue.prNumber,
+            prState: issue.prState,
+            prReviewState: issue.prReviewState,
+            prCheckStatus: issue.prCheckStatus,
+            latestFailureSource: issue.lastGitHubFailureSource,
+        }))
+            .map((issue) => ({
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+        }));
+    }
+    issueToTrackedIssue(issue) {
+        return buildTrackedIssueRecord({
+            issue,
+            session: this.issueSessions.getIssueSession(issue.projectId, issue.linearIssueId),
+            blockedBy: this.issues.listIssueDependencies(issue.projectId, issue.linearIssueId),
+            hasPendingWake: this.issueSessions.peekIssueSessionWake(issue.projectId, issue.linearIssueId) !== undefined,
+            latestRun: this.runs.getLatestRunForIssue(issue.projectId, issue.linearIssueId),
+            latestEvent: this.issueSessions.listIssueSessionEvents(issue.projectId, issue.linearIssueId, { limit: 1 }).at(-1),
+        });
+    }
+    getTrackedIssue(projectId, linearIssueId) {
+        const issue = this.issues.getIssue(projectId, linearIssueId);
+        return issue ? this.issueToTrackedIssue(issue) : undefined;
+    }
+    getTrackedIssueByKey(issueKey) {
+        const issue = this.issues.getIssueByKey(issueKey);
+        return issue ? this.issueToTrackedIssue(issue) : undefined;
+    }
+    getIssueOverview(issueKey) {
+        const issue = this.issues.getIssueByKey(issueKey);
+        if (!issue)
+            return undefined;
+        const tracked = this.issueToTrackedIssue(issue);
+        const activeRun = issue.activeRunId ? this.runs.getRunById(issue.activeRunId) : undefined;
+        return {
+            issue: tracked,
+            ...(activeRun ? { activeRun } : {}),
+        };
+    }
+    listIssuesByState(projectId, state) {
+        return this.issues.listIssuesByState(projectId, state);
+    }
+}

package/dist/webhook-handler.js

@@ -1,11 +1,12 @@
 import { deriveIssueStatusNote } from "./status-note.js";
-import { resolveProject, trustedActorAllowed } from "./project-resolution.js";
+import { trustedActorAllowed } from "./project-resolution.js";
 import { normalizeWebhook } from "./webhooks.js";
 import { InstallationWebhookHandler } from "./webhook-installation-handler.js";
 import { AgentSessionHandler } from "./webhooks/agent-session-handler.js";
 import { CommentWakeHandler } from "./webhooks/comment-wake-handler.js";
+import { WebhookContextLoader } from "./webhooks/context-loader.js";
+import { DependencyReadinessHandler } from "./webhooks/dependency-readiness-handler.js";
 import { DesiredStageRecorder } from "./webhooks/desired-stage-recorder.js";
-import { hasCompleteIssueContext, mergeIssueMetadata, } from "./webhooks/decision-helpers.js";
 import { IssueRemovalHandler } from "./webhooks/issue-removal-handler.js";
 import { safeJsonParse, sanitizeDiagnosticText } from "./utils.js";
 import { extractLatestAssistantSummary } from "./issue-session-events.js";
@@ -22,6 +23,8 @@ export class WebhookHandler {
     commentWakeHandler;
     agentSessionHandler;
     desiredStageRecorder;
+    contextLoader;
+    dependencyReadinessHandler;
     constructor(config, db, linearProvider, codex, enqueueIssue, logger, feed) {
         this.config = config;
         this.db = db;
@@ -35,6 +38,8 @@ export class WebhookHandler {
         this.commentWakeHandler = new CommentWakeHandler(db, codex, logger, feed);
         this.agentSessionHandler = new AgentSessionHandler(config, db, linearProvider, codex, logger, feed);
         this.desiredStageRecorder = new DesiredStageRecorder(db, linearProvider, feed);
+        this.contextLoader = new WebhookContextLoader(config, linearProvider);
+        this.dependencyReadinessHandler = new DependencyReadinessHandler(db, (projectId, issueId) => this.peekPendingSessionWakeRunType(projectId, issueId));
     }
     async processWebhookEvent(webhookEventId) {
         const event = this.db.webhookEvents.getWebhookPayload(webhookEventId);
@@ -66,14 +71,8 @@ export class WebhookHandler {
                 this.db.webhookEvents.markWebhookProcessed(webhookEventId, "processed");
                 return;
             }
-            let project = resolveProject(this.config, normalized.issue);
-            if (!project) {
-                const routed = await this.tryHydrateProjectRoute(normalized);
-                if (routed) {
-                    normalized = routed.normalized;
-                    project = routed.project;
-                }
-            }
+            const routed = await this.contextLoader.load(normalized);
+            const project = routed?.project;
             if (!project) {
                 this.feed?.publish({
                     level: "warn",
@@ -85,6 +84,7 @@ export class WebhookHandler {
                 this.db.webhookEvents.markWebhookProcessed(webhookEventId, "processed");
                 return;
             }
+            normalized = routed.normalized;
             const routedIssue = normalized.issue;
             if (!routedIssue) {
                 this.db.webhookEvents.markWebhookProcessed(webhookEventId, "failed");
@@ -103,7 +103,7 @@ export class WebhookHandler {
                 return;
             }
             this.db.webhookEvents.assignWebhookProject(webhookEventId, project.id);
-            const hydrated = await this.hydrateIssueContext(project.id, normalized);
+            const hydrated = normalized;
             const issue = hydrated.issue ?? routedIssue;
             // Record desired stage and upsert issue
             const result = await this.desiredStageRecorder.record({
@@ -113,7 +113,7 @@ export class WebhookHandler {
                 stopActiveRun: (run, input) => this.stopActiveRun(run, input),
             });
             const trackedIssue = result.issue;
-            const newlyReadyDependents = this.reconcileDependentReadiness(project.id, issue.id);
+            const newlyReadyDependents = this.dependencyReadinessHandler.reconcile(project.id, issue.id);
             // Handle issue removal: release active runs, mark as failed.
             if (hydrated.triggerEvent === "issueRemoved") {
                 await this.issueRemovalHandler.handle({
@@ -188,48 +188,6 @@ export class WebhookHandler {
             throw err;
         }
     }
-    reconcileDependentReadiness(projectId, blockerLinearIssueId) {
-        const newlyReady = [];
-        for (const dependent of this.db.issues.listDependents(projectId, blockerLinearIssueId)) {
-            const issue = this.db.issues.getIssue(projectId, dependent.linearIssueId);
-            if (!issue) {
-                continue;
-            }
-            const unresolved = this.db.issues.countUnresolvedBlockers(projectId, dependent.linearIssueId);
-            if (unresolved > 0) {
-                if (this.peekPendingSessionWakeRunType(projectId, dependent.linearIssueId) === "implementation"
-                    && issue.activeRunId === undefined
-                    && !this.db.issueSessions.hasPendingIssueSessionEvents(projectId, dependent.linearIssueId)) {
-                    this.db.issues.upsertIssue({
-                        projectId,
-                        linearIssueId: dependent.linearIssueId,
-                        pendingRunType: null,
-                        pendingRunContextJson: null,
-                    });
-                }
-                continue;
-            }
-            if (issue.factoryState !== "delegated" || issue.activeRunId !== undefined || this.db.issueSessions.hasPendingIssueSessionEvents(projectId, dependent.linearIssueId)) {
-                continue;
-            }
-            if (this.peekPendingSessionWakeRunType(projectId, dependent.linearIssueId) === "implementation") {
-                this.db.issues.upsertIssue({
-                    projectId,
-                    linearIssueId: dependent.linearIssueId,
-                    pendingRunType: null,
-                    pendingRunContextJson: null,
-                });
-            }
-            this.db.issueSessions.appendIssueSessionEventRespectingActiveLease(projectId, dependent.linearIssueId, {
-                projectId,
-                linearIssueId: dependent.linearIssueId,
-                eventType: "delegated",
-                dedupeKey: `delegated:${dependent.linearIssueId}`,
-            });
-            newlyReady.push(dependent.linearIssueId);
-        }
-        return newlyReady;
-    }
     async stopActiveRun(run, input) {
         if (!run.threadId || !run.turnId)
             return;
@@ -251,45 +209,6 @@ export class WebhookHandler {
         this.enqueueIssue(projectId, issueId);
         return wake.runType;
     }
-    async hydrateIssueContext(projectId, normalized) {
-        if (!normalized.issue)
-            return normalized;
-        if (normalized.triggerEvent !== "agentSessionCreated" && normalized.triggerEvent !== "agentPrompted" && normalized.entityType !== "Issue") {
-            return normalized;
-        }
-        if (normalized.entityType !== "Issue" && hasCompleteIssueContext(normalized.issue))
-            return normalized;
-        const linear = await this.linearProvider.forProject(projectId);
-        if (!linear)
-            return normalized;
-        try {
-            const liveIssue = await linear.getIssue(normalized.issue.id);
-            return { ...normalized, issue: mergeIssueMetadata(normalized.issue, liveIssue) };
-        }
-        catch {
-            return normalized;
-        }
-    }
-    async tryHydrateProjectRoute(normalized) {
-        if (!normalized.issue)
-            return undefined;
-        if (normalized.triggerEvent !== "agentSessionCreated" && normalized.triggerEvent !== "agentPrompted")
-            return undefined;
-        for (const candidate of this.config.projects) {
-            const linear = await this.linearProvider.forProject(candidate.id);
-            if (!linear)
-                continue;
-            try {
-                const liveIssue = await linear.getIssue(normalized.issue.id);
-                const hydrated = { ...normalized, issue: mergeIssueMetadata(normalized.issue, liveIssue) };
-                const resolved = resolveProject(this.config, hydrated.issue);
-                if (resolved)
-                    return { project: resolved, normalized: hydrated };
-            }
-            catch { /* continue to next candidate */ }
-        }
-        return undefined;
-    }
     isDirectReplyToOutstandingQuestion(issue) {
         if (!issue)
             return false;

package/dist/webhooks/agent-session-handler.js

@@ -46,13 +46,12 @@ export class AgentSessionHandler {
                 await this.publishAgentActivity(linear, normalized.agentSession.id, buildAlreadyRunningThought(activeRun.runType));
                 return;
             }
-            const blockerSummary = trackedIssue?.blockedByCount
-                ? `PatchRelay is delegated and waiting on blockers to reach Done: ${trackedIssue.blockedByKeys.join(", ")}.`
-                : "PatchRelay is delegated, but no work is queued. Delegate the issue or move it to Start to trigger implementation.";
-            await this.publishAgentActivity(linear, normalized.agentSession.id, {
-                type: "elicitation",
-                body: blockerSummary,
-            });
+            if (!trackedIssue?.blockedByCount) {
+                await this.publishAgentActivity(linear, normalized.agentSession.id, {
+                    type: "elicitation",
+                    body: "PatchRelay is delegated, but no work is queued. Delegate the issue or move it to Start to trigger implementation.",
+                });
+            }
             return;
         }
         if (normalized.triggerEvent === "agentSignal" && normalized.agentSession.signal === "stop") {