patchrelay 0.67.2 → 0.68.1

package/dist/run-finalizer.js

@@ -31,7 +31,7 @@ export class RunFinalizer {
     db;
     logger;
     linearSync;
-    enqueueIssue;
+    wakeDispatcher;
     withHeldLease;
     releaseLease;
     appendWakeEventWithLease;
@@ -40,11 +40,11 @@ export class RunFinalizer {
     completionCheck;
     publicationRecap;
     feed;
-    constructor(db, logger, linearSync, enqueueIssue, withHeldLease, releaseLease, appendWakeEventWithLease, failRunAndClear, completionPolicy, completionCheck, publicationRecap, feed) {
+    constructor(db, logger, linearSync, wakeDispatcher, withHeldLease, releaseLease, appendWakeEventWithLease, failRunAndClear, completionPolicy, completionCheck, publicationRecap, feed) {
         this.db = db;
         this.logger = logger;
         this.linearSync = linearSync;
-        this.enqueueIssue = enqueueIssue;
+        this.wakeDispatcher = wakeDispatcher;
         this.withHeldLease = withHeldLease;
         this.releaseLease = releaseLease;
         this.appendWakeEventWithLease = appendWakeEventWithLease;
@@ -164,9 +164,21 @@ export class RunFinalizer {
             patchId: identity.patchId,
         }, "Recorded last-published change identity after run completion");
     }
-    clearProgressAndRelease(run) {
+    // Single owner of "clear Linear progress + release lease + drain pending
+    // wake". Every run-end path goes through here. Routes the release through
+    // the WakeDispatcher so a wake that landed during the run is picked up
+    // even on failure paths (the previous implementation only drained on the
+    // success path). Failure and completion-check paths publish their own
+    // more-specific operator-feed event before getting here, so the
+    // dispatcher's "deferred_follow_up_queued" notification is opt-in via
+    // `publishDeferredFollowUp` and used only by the success path.
+    clearProgressAndRelease(run, options) {
         this.linearSync.clearProgress(run.id);
-        this.releaseLease(run.projectId, run.linearIssueId);
+        this.wakeDispatcher.releaseRunAndDispatch({
+            run,
+            ...(options?.issueKey ? { issueKey: options.issueKey } : {}),
+            ...(options?.publishDeferredFollowUp ? { publishDeferredFollowUp: true } : {}),
+        });
     }
     // Plan §4.4: finalize a run that was superseded mid-flight. The
     // status row was already moved to `superseded` by the trigger
@@ -199,26 +211,6 @@ export class RunFinalizer {
             ...(run.projectId ? { projectId: run.projectId } : {}),
         });
     }
-    enqueuePendingWakeIfPresent(params) {
-        const wake = this.db.issueSessions.peekIssueSessionWake(params.run.projectId, params.run.linearIssueId);
-        if (!wake)
-            return undefined;
-        this.enqueueIssue(params.run.projectId, params.run.linearIssueId);
-        this.feed?.publish({
-            level: "info",
-            kind: "stage",
-            issueKey: params.issueKey,
-            projectId: params.run.projectId,
-            stage: wake.runType,
-            status: "deferred_follow_up_queued",
-            summary: `${wake.runType} queued after ${params.run.runType} released authority`,
-            ...(wake.wakeReason ? { detail: `wake reason: ${wake.wakeReason}` } : {}),
-        });
-        return {
-            runType: wake.runType,
-            ...(wake.wakeReason ? { wakeReason: wake.wakeReason } : {}),
-        };
-    }
     publishTurnEvent(params) {
         this.feed?.publish({
             level: params.level,
@@ -257,11 +249,11 @@ export class RunFinalizer {
         });
         void this.linearSync.emitActivity(issue, params.activity, { ephemeral: true });
         void this.linearSync.syncSession(issue);
-        this.linearSync.clearProgress(params.run.id);
-        if (params.enqueue) {
-            this.enqueueIssue(params.run.projectId, params.run.linearIssueId);
-        }
-        this.releaseLease(params.run.projectId, params.run.linearIssueId);
+        // releaseRunAndDispatch always drains any pending wake — the
+        // explicit `params.enqueue` flag is no longer needed because the
+        // dispatcher peeks the wake itself and only enqueues when one
+        // exists. Keeping the parameter would be redundant.
+        this.clearProgressAndRelease(params.run);
     }
     async finalizeCompletedRun(params) {
         const { run, issue, thread, threadId } = params;
@@ -341,6 +333,7 @@ export class RunFinalizer {
                 syncFailureOutcome: (event) => this.syncFailureOutcome(event),
                 syncCompletionCheckOutcome: (event) => this.syncCompletionCheckOutcome(event),
                 clearProgressAndRelease: (releaseRun) => this.clearProgressAndRelease(releaseRun),
+                wakeDispatcher: this.wakeDispatcher,
             });
             return;
         }
@@ -396,8 +389,7 @@ export class RunFinalizer {
         });
         if (!completed) {
             this.logger.warn({ runId: run.id, issueId: run.linearIssueId }, "Skipping completion writes after losing issue-session lease");
-            this.linearSync.clearProgress(run.id);
-            this.releaseLease(run.projectId, run.linearIssueId);
+            this.clearProgressAndRelease(run);
             return;
         }
         if (postRunFollowUp) {
@@ -435,9 +427,10 @@ export class RunFinalizer {
             void this.linearSync.emitActivity(updatedIssue, linearActivity);
         }
         void this.linearSync.syncSession(updatedIssue);
-        this.enqueuePendingWakeIfPresent({ run, issueKey: updatedIssue.issueKey });
-        this.linearSync.clearProgress(run.id);
-        this.releaseLease(run.projectId, run.linearIssueId);
+        this.clearProgressAndRelease(run, {
+            ...(updatedIssue.issueKey ? { issueKey: updatedIssue.issueKey } : {}),
+            publishDeferredFollowUp: true,
+        });
     }
     async recoverFailedImplementationRun(params) {
         const freshIssue = this.db.issues.getIssue(params.run.projectId, params.run.linearIssueId) ?? params.issue;
@@ -466,6 +459,7 @@ export class RunFinalizer {
             syncFailureOutcome: (event) => this.syncFailureOutcome(event),
             syncCompletionCheckOutcome: (event) => this.syncCompletionCheckOutcome(event),
             clearProgressAndRelease: (releaseRun) => this.clearProgressAndRelease(releaseRun),
+            wakeDispatcher: this.wakeDispatcher,
         });
         return true;
     }

package/dist/run-launcher.js

@@ -3,6 +3,7 @@ import { buildRunFailureActivity } from "./linear-session-reporting.js";
 import { loadPatchRelayRepoPrompting } from "./patchrelay-customization.js";
 import { buildRunPrompt as buildPatchRelayRunPrompt, findDisallowedPatchRelayPromptSectionIds, findUnknownPatchRelayPromptSectionIds, mergePromptCustomizationLayers, resolvePromptLayers, } from "./prompting/patchrelay.js";
 import { configureGitHubBotAuthForWorktree } from "./github-worktree-auth.js";
+import { sanitizeDiagnosticText } from "./utils.js";
 function slugify(value) {
     return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
 }
@@ -15,6 +16,28 @@ function shouldCompactThread(issue, threadGeneration, context) {
         && (threadGeneration ?? 0) >= 4
         && followUpCount >= 4;
 }
+function compactGoalText(value, maxLength = 600) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    return normalized.length <= maxLength ? normalized : `${normalized.slice(0, maxLength - 3).trimEnd()}...`;
+}
+function extractIssueSection(description, heading) {
+    if (!description)
+        return undefined;
+    const headingLine = `## ${heading}`.toLowerCase();
+    const lines = description.split(/\r?\n/);
+    const start = lines.findIndex((line) => line.trim().toLowerCase() === headingLine);
+    if (start === -1)
+        return undefined;
+    const end = lines.findIndex((line, index) => index > start && /^##\s+/.test(line));
+    const body = lines.slice(start + 1, end === -1 ? undefined : end).join("\n").trim();
+    return body && body.length > 0 ? body : undefined;
+}
+export function buildInitialImplementationGoal(issue) {
+    const title = issue.title?.trim() || `Complete ${issue.issueKey ?? issue.linearIssueId}`;
+    const description = issue.description?.trim();
+    const goal = extractIssueSection(description, "Goal");
+    return compactGoalText(goal ? `${title}. ${goal}` : title);
+}
 export function shouldReuseIssueThread(params) {
     return Boolean(params.existingThreadId) && !params.compactThread && params.resumeThread;
 }
@@ -125,6 +148,8 @@ export class RunLauncher {
         let threadId;
         let turnId;
         let parentThreadId;
+        let createdThreadForRun = false;
+        const firstThreadForIssue = !params.issue.threadId;
         try {
             await this.worktreeManager.ensureIssueWorktree(params.project.repoPath, params.project.worktreeRoot, params.worktreePath, params.branchName, { allowExistingOutsideRoot: params.issue.branchName !== undefined });
             if (params.botIdentity) {
@@ -157,6 +182,7 @@ export class RunLauncher {
             else {
                 const thread = await this.codex.startThread({ cwd: params.worktreePath });
                 threadId = thread.id;
+                createdThreadForRun = true;
                 this.db.issueSessions.upsertIssueWithLease({ projectId: params.project.id, linearIssueId: params.issue.linearIssueId, leaseId: params.leaseId }, { projectId: params.project.id, linearIssueId: params.issue.linearIssueId, threadId });
             }
             try {
@@ -169,6 +195,7 @@ export class RunLauncher {
                     this.logger.info({ issueKey: params.issue.issueKey, staleThreadId: threadId }, "Thread is stale, retrying with fresh thread");
                     const thread = await this.codex.startThread({ cwd: params.worktreePath });
                     threadId = thread.id;
+                    createdThreadForRun = true;
                     this.db.issueSessions.upsertIssueWithLease({ projectId: params.project.id, linearIssueId: params.issue.linearIssueId, leaseId: params.leaseId }, { projectId: params.project.id, linearIssueId: params.issue.linearIssueId, threadId });
                     const turn = await this.codex.startTurn({ threadId, cwd: params.worktreePath, input: params.prompt });
                     turnId = turn.turnId;
@@ -177,6 +204,9 @@ export class RunLauncher {
                     throw turnError;
                 }
             }
+            if (createdThreadForRun && firstThreadForIssue && params.runType === "implementation") {
+                await this.setInitialImplementationGoal(threadId, params.issue);
+            }
             params.assertLaunchLease(params.run, "after starting the Codex turn");
             return { threadId, turnId, ...(parentThreadId ? { parentThreadId } : {}) };
         }
@@ -204,4 +234,22 @@ export class RunLauncher {
             throw error;
         }
     }
+    async setInitialImplementationGoal(threadId, issue) {
+        const goalSetter = this.codex.setThreadGoal;
+        if (typeof goalSetter !== "function") {
+            return;
+        }
+        const objective = buildInitialImplementationGoal(issue);
+        try {
+            await goalSetter.call(this.codex, { threadId, objective, status: "active" });
+            this.logger.info({ issueKey: issue.issueKey, threadId }, "Set Codex thread goal for implementation run");
+        }
+        catch (error) {
+            this.logger.warn({
+                issueKey: issue.issueKey,
+                threadId,
+                error: sanitizeDiagnosticText(error instanceof Error ? error.message : String(error)),
+            }, "Failed to set Codex thread goal for implementation run");
+        }
+    }
 }

package/dist/run-orchestrator.js

@@ -18,6 +18,7 @@ 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 { WakeDispatcher } from "./wake-dispatcher.js";
 import { getRemainingZombieRecoveryDelayMs } from "./zombie-recovery.js";
 import { classifyIssue } from "./issue-class.js";
 import { buildIssueTriageHash, IssueTriageService } from "./issue-triage.js";
@@ -45,9 +46,6 @@ export class RunOrchestrator {
     codex;
     linearProvider;
     enqueueIssue;
-    logger;
-    feed;
-    configPath;
     worktreeManager;
     mainBranchHealthMonitor;
     /** Tracks last probe-failure feed event per issue to avoid spamming the operator feed. */
@@ -55,6 +53,9 @@ export class RunOrchestrator {
     idleReconciler;
     linearSync;
     workerId = `patchrelay:${process.pid}`;
+    // Exposed so the WakeDispatcher (constructed in service.ts) can call
+    // release on this same lease service. Kept on the orchestrator because
+    // its construction depends on Codex thread access.
     leaseService;
     runFinalizer;
     runLauncher;
@@ -85,12 +86,37 @@ export class RunOrchestrator {
     };
     activeSessionLeases;
     botIdentity;
-    constructor(config, db, codex, linearProvider, enqueueIssue, logger, feed, configPath) {
+    wakeDispatcher;
+    logger;
+    feed;
+    configPath;
+    constructor(config, db, codex, linearProvider, enqueueIssue, wakeDispatcherOrLogger, loggerOrFeed, feedOrConfigPath, configPathOrUndefined) {
         this.config = config;
         this.db = db;
         this.codex = codex;
         this.linearProvider = linearProvider;
         this.enqueueIssue = enqueueIssue;
+        // Backward-compat: tests pass `(config, db, codex, lp, enqueue, logger, feed?, configPath?)`
+        // (no dispatcher). Production passes `(..., enqueue, dispatcher, logger, feed?, configPath?)`.
+        let logger;
+        let feed;
+        let configPath;
+        if (wakeDispatcherOrLogger instanceof WakeDispatcher) {
+            this.wakeDispatcher = wakeDispatcherOrLogger;
+            logger = loggerOrFeed;
+            feed = feedOrConfigPath;
+            configPath = configPathOrUndefined;
+        }
+        else {
+            logger = wakeDispatcherOrLogger;
+            feed = loggerOrFeed;
+            configPath = feedOrConfigPath;
+            // Construct a dispatcher with a stub releaseLease — the real one
+            // gets wired below once the lease service exists. The stub is
+            // never called before the wiring completes because the run()
+            // loop is the only consumer of releaseRunAndDispatch.
+            this.wakeDispatcher = new WakeDispatcher(db, enqueueIssue, (projectId, linearIssueId) => this.leaseService?.release(projectId, linearIssueId), logger, feed);
+        }
         this.logger = logger;
         this.feed = feed;
         this.configPath = configPath;
@@ -103,21 +129,19 @@ export class RunOrchestrator {
         this.completionCheck = new CompletionCheckService(codex, logger);
         this.publicationRecap = new PublicationRecapService(codex, logger);
         this.issueTriage = new IssueTriageService(codex, logger);
-        this.runFinalizer = new RunFinalizer(db, logger, this.linearSync, this.enqueueIssue, this.leasePorts.withHeldLease, this.leasePorts.releaseLease, (lease, issue, runType, context, dedupeScope) => this.appendWakeEventWithLease(lease, issue, runType, context, dedupeScope), this.recoveryPorts.failRunAndClear, this.runCompletionPolicy, this.completionCheck, this.publicationRecap, feed);
+        this.runFinalizer = new RunFinalizer(db, logger, this.linearSync, this.wakeDispatcher, this.leasePorts.withHeldLease, this.leasePorts.releaseLease, (lease, issue, runType, context, dedupeScope) => this.appendWakeEventWithLease(lease, issue, runType, context, dedupeScope), this.recoveryPorts.failRunAndClear, this.runCompletionPolicy, this.completionCheck, this.publicationRecap, feed);
         this.runLauncher = new RunLauncher(config, db, codex, logger, this.worktreeManager);
         this.runNotificationHandler = new RunNotificationHandler(config, db, logger, this.linearSync, this.runFinalizer, this.threadPorts.readThreadWithRetry, this.leasePorts.withHeldLease, this.leasePorts.heartbeatLease, this.leasePorts.releaseLease, feed);
         this.runRecovery = new RunRecoveryService(db, logger, this.linearSync, this.leasePorts.withHeldLease, this.leasePorts.getHeldLease, (lease, issue, runType, context, dedupeScope) => this.appendWakeEventWithLease(lease, issue, runType, context, dedupeScope), this.leasePorts.releaseLease, (projectId, issueId) => this.enqueueIssue(projectId, issueId), feed);
         this.interruptedRunRecovery = new InterruptedRunRecovery(db, logger, this.linearSync, this.leasePorts.withHeldLease, this.leasePorts.releaseLease, this.recoveryPorts.failRunAndClear, this.recoveryPorts.restoreIdleWorktree, this.runCompletionPolicy, (projectId, issueId) => this.enqueueIssue(projectId, issueId), feed);
         this.runReconciler = new RunReconciler(db, logger, linearProvider, this.linearSync, this.interruptedRunRecovery, this.runFinalizer, this.leasePorts.withHeldLease, this.leasePorts.releaseLease, this.threadPorts.readThreadWithRetry, this.recoveryPorts.recoverOrEscalate, feed);
         this.runWakePlanner = new RunWakePlanner(db);
-        this.idleReconciler = new IdleIssueReconciler(db, config, {
-            enqueueIssue: (projectId, issueId) => this.enqueueIssue(projectId, issueId),
-        }, logger, feed);
-        this.mainBranchHealthMonitor = new MainBranchHealthMonitor(db, config, linearProvider, (projectId, issueId) => this.enqueueIssue(projectId, issueId), logger, feed);
+        this.idleReconciler = new IdleIssueReconciler(db, config, this.wakeDispatcher, logger, feed);
+        this.mainBranchHealthMonitor = new MainBranchHealthMonitor(db, config, linearProvider, this.wakeDispatcher, logger, feed);
         this.mergedLinearCompletionReconciler = new MergedLinearCompletionReconciler(db, linearProvider, logger);
         this.queueHealthMonitor = new QueueHealthMonitor(db, config, {
             advanceIdleIssue: (issue, newState, options) => this.idleReconciler.advanceIdleIssue(issue, newState, options),
-            enqueueIssue: (projectId, issueId) => this.enqueueIssue(projectId, issueId),
+            wakeDispatcher: this.wakeDispatcher,
         }, logger, feed);
     }
     async refreshCodexRuntimeConfig() {
@@ -223,21 +247,40 @@ export class RunOrchestrator {
     async run(item) {
         await this.refreshCodexRuntimeConfig();
         const project = this.config.projects.find((p) => p.id === item.projectId);
-        if (!project)
+        if (!project) {
+            this.logger.info({ projectId: item.projectId, linearIssueId: item.issueId, reason: "project_not_configured" }, "Skipped issue run: project missing from config");
             return;
+        }
+        // Each early-return below logs `{ issueKey, reason }` so the
+        // operator-feed and log streams can explain why an issue with a
+        // pending wake didn't actually run. The original incident
+        // (LSR-495) was undiagnosable because these guards were silent.
         if (this.leaseService.hasLocalLease(item.projectId, item.issueId)) {
+            this.logger.info({ projectId: item.projectId, linearIssueId: item.issueId, reason: "lease_held_locally" }, "Skipped issue run: another in-process call still holds the lease");
             return;
         }
         const initialIssue = this.db.issues.getIssue(item.projectId, item.issueId);
-        if (!initialIssue || initialIssue.activeRunId !== undefined)
+        if (!initialIssue) {
+            this.logger.info({ projectId: item.projectId, linearIssueId: item.issueId, reason: "issue_missing" }, "Skipped issue run: issue row not found");
+            return;
+        }
+        if (initialIssue.activeRunId !== undefined) {
+            this.logger.info({ issueKey: initialIssue.issueKey, projectId: item.projectId, reason: "active_run_present", activeRunId: initialIssue.activeRunId }, "Skipped issue run: an active run is already in flight");
             return;
+        }
         const issue = await this.classifyTrackedIssue(initialIssue);
-        if (!issue || issue.activeRunId !== undefined)
+        if (!issue) {
+            this.logger.info({ projectId: item.projectId, linearIssueId: item.issueId, reason: "classification_dropped_issue" }, "Skipped issue run: classification returned no issue");
+            return;
+        }
+        if (issue.activeRunId !== undefined) {
+            this.logger.info({ issueKey: issue.issueKey, projectId: item.projectId, reason: "active_run_present_post_classify", activeRunId: issue.activeRunId }, "Skipped issue run: an active run appeared during classification");
             return;
+        }
         const issueSession = this.db.issueSessions.getIssueSession(item.projectId, item.issueId);
         const leaseId = this.leaseService.acquire(item.projectId, item.issueId);
         if (!leaseId) {
-            this.logger.info({ issueKey: issue.issueKey, projectId: item.projectId }, "Skipped run because another worker holds the session lease");
+            this.logger.info({ issueKey: issue.issueKey, projectId: item.projectId, reason: "lease_acquire_failed" }, "Skipped issue run: another worker holds the session lease");
             return;
         }
         if (issue.prState === "merged") {
@@ -248,6 +291,7 @@ export class RunOrchestrator {
         const wakeIssue = this.materializeLegacyPendingWake(issue, { projectId: item.projectId, linearIssueId: item.issueId, leaseId });
         const wake = this.resolveRunWake(wakeIssue);
         if (!wake) {
+            this.logger.info({ issueKey: issue.issueKey, projectId: item.projectId, reason: "no_wake_derivable" }, "Skipped issue run: no actionable wake derivable from pending events");
             this.leaseService.release(item.projectId, item.issueId);
             return;
         }

package/dist/service.js

@@ -9,6 +9,7 @@ import { buildSessionStatusUrl, createSessionStatusToken, deriveSessionStatusSig
 import { ServiceRuntime } from "./service-runtime.js";
 import { ServiceIssueActions } from "./service-issue-actions.js";
 import { ServiceStartupRecovery } from "./service-startup-recovery.js";
+import { WakeDispatcher } from "./wake-dispatcher.js";
 import { WebhookHandler } from "./webhook-handler.js";
 import { acceptIncomingWebhook } from "./service-webhooks.js";
 import { parseStringArray, TrackedIssueListQuery } from "./tracked-issue-list-query.js";
@@ -41,9 +42,20 @@ export class PatchRelayService {
         let enqueueIssue = () => {
             throw new Error("Service runtime enqueueIssue is not initialized");
         };
-        this.orchestrator = new RunOrchestrator(config, db, codex, this.linearProvider, (projectId, issueId) => enqueueIssue(projectId, issueId), logger, this.feed, this.configPath);
-        this.webhookHandler = new WebhookHandler(config, db, this.linearProvider, codex, (projectId, issueId) => enqueueIssue(projectId, issueId), logger, this.feed);
-        this.githubWebhookHandler = new GitHubWebhookHandler(config, db, this.linearProvider, (projectId, issueId) => enqueueIssue(projectId, issueId), logger, codex, this.feed);
+        let leaseRelease = () => {
+            throw new Error("WakeDispatcher releaseLease is not yet bound");
+        };
+        // The dispatcher owns every "append event + maybe enqueue" and every
+        // "release run + drain pending wake" call. See src/wake-dispatcher.ts
+        // for why. Both `enqueueIssue` and `leaseRelease` are late-bound — the
+        // runtime owns the queue, and the lease service lives inside the
+        // orchestrator (its construction depends on the Codex client). All
+        // downstream consumers receive this single dispatcher instance.
+        const dispatcher = new WakeDispatcher(db, (projectId, issueId) => enqueueIssue(projectId, issueId), (projectId, issueId) => leaseRelease(projectId, issueId), logger, this.feed);
+        this.orchestrator = new RunOrchestrator(config, db, codex, this.linearProvider, (projectId, issueId) => enqueueIssue(projectId, issueId), dispatcher, logger, this.feed, this.configPath);
+        leaseRelease = (projectId, issueId) => this.orchestrator.leaseService.release(projectId, issueId);
+        this.webhookHandler = new WebhookHandler(config, db, this.linearProvider, codex, dispatcher, logger, this.feed);
+        this.githubWebhookHandler = new GitHubWebhookHandler(config, db, this.linearProvider, dispatcher, logger, codex, this.feed);
         const runtime = new ServiceRuntime(codex, logger, this.orchestrator, { listIssuesReadyForExecution: () => db.listIssuesReadyForExecution() }, this.webhookHandler, {
             processIssue: async (item) => {
                 await this.orchestrator.run(item);

package/dist/wake-dispatcher.js

@@ -0,0 +1,121 @@
+// Single owner of "append a session event and tell the orchestrator
+// something might be runnable", and of "release a finished run so the
+// next wake fires." Until this existed, 8+ call sites each made their
+// own decision about whether to call `enqueueIssue`. A missed enqueue
+// (lease race, in-memory queue cleared by restart) left events orphaned
+// for hours — we lost 6.5h on LSR-495 to exactly this.
+//
+// Idempotency comes from two layers:
+//   - `issue_session_events.dedupe_key` dedupes the event itself.
+//   - `SerialWorkQueue` dedupes by issue key inside the worker process.
+//
+// Long-running scopes (the idle reconciler) can call `withTick` to
+// dedupe enqueues within that scope — every call into the dispatcher
+// during the callback contributes to the same Set, so a single
+// reconcile pass produces at most one enqueue per issue even when
+// many sub-passes detect the same wake. The `enqueuedThisTick` option
+// on individual methods is for callers that thread their own Set.
+export class WakeDispatcher {
+    db;
+    enqueueIssue;
+    releaseLease;
+    logger;
+    feed;
+    currentTick;
+    constructor(db, enqueueIssue, releaseLease, logger, feed) {
+        this.db = db;
+        this.enqueueIssue = enqueueIssue;
+        this.releaseLease = releaseLease;
+        this.logger = logger;
+        this.feed = feed;
+    }
+    // Scope the next enqueue calls inside `fn` to a single dedupe Set.
+    // Nested ticks reuse the outermost Set so deeply nested helpers do
+    // not silently lose dedupe.
+    async withTick(fn) {
+        if (this.currentTick)
+            return fn();
+        this.currentTick = new Set();
+        try {
+            return await fn();
+        }
+        finally {
+            this.currentTick = undefined;
+        }
+    }
+    // Append a session event and dispatch the issue if a wake is derivable
+    // and no run is currently in flight. Returns the runType the next run
+    // would have, or undefined if the event is non-actionable / no wake
+    // exists / a run is already running (the finalizer will drain it).
+    recordEventAndDispatch(projectId, linearIssueId, event, options) {
+        this.db.issueSessions.appendIssueSessionEventRespectingActiveLease(projectId, linearIssueId, {
+            projectId,
+            linearIssueId,
+            ...event,
+        });
+        // Honour the active tick scope (set via withTick) so callers nested
+        // inside a reconcile pass automatically dedupe without threading
+        // the Set through every helper signature.
+        return this.dispatchIfWakePending(projectId, linearIssueId, options ?? (this.currentTick ? { enqueuedThisTick: this.currentTick } : undefined));
+    }
+    // "Make sure the orchestrator looks at this issue, if anything is worth
+    // looking at." Used by the idle reconciler safety net for orphan
+    // recovery, by dependency-readiness flows that don't append a new
+    // event but want to poke, and by the stack-coordination fan-out that
+    // sets the legacy `pending_run_type` column on the issue. Suppressed
+    // when an active run is in flight — the run finalizer owns the
+    // post-run drain via releaseRunAndDispatch.
+    dispatchIfWakePending(projectId, linearIssueId, options) {
+        const issue = this.db.issues.getIssue(projectId, linearIssueId);
+        if (issue?.activeRunId !== undefined)
+            return undefined;
+        const wake = this.db.issueSessions.peekIssueSessionWake(projectId, linearIssueId);
+        // Fall back to the legacy pending_run_type column. The orchestrator
+        // materializes it into a real event at run time, but the poke still
+        // needs to happen now so the orchestrator gets called at all.
+        const runType = wake?.runType ?? issue?.pendingRunType;
+        if (!runType)
+            return undefined;
+        const tick = options?.enqueuedThisTick ?? this.currentTick;
+        const key = `${projectId}:${linearIssueId}`;
+        if (tick?.has(key)) {
+            return runType;
+        }
+        tick?.add(key);
+        this.enqueueIssue(projectId, linearIssueId);
+        return runType;
+    }
+    // Release the lease for a finished run, then drain any wake that
+    // landed during the run. The single owner of "run is over, what's
+    // next?". Lease is released BEFORE the dispatch so the orchestrator's
+    // lease guard succeeds on dequeue. Every code path that ends a run
+    // must go through here, not bare releaseLease.
+    //
+    // The optional `publishDeferredFollowUp` flag is for callers that
+    // want the "deferred_follow_up_queued" operator-feed event emitted
+    // here (success path of the run finalizer). Failure / completion-
+    // check paths publish their own more-specific event and pass false.
+    releaseRunAndDispatch(params) {
+        this.releaseLease(params.run.projectId, params.run.linearIssueId);
+        const wake = this.db.issueSessions.peekIssueSessionWake(params.run.projectId, params.run.linearIssueId);
+        if (!wake)
+            return undefined;
+        this.enqueueIssue(params.run.projectId, params.run.linearIssueId);
+        if (params.publishDeferredFollowUp) {
+            this.feed?.publish({
+                level: "info",
+                kind: "stage",
+                ...(params.issueKey ? { issueKey: params.issueKey } : {}),
+                projectId: params.run.projectId,
+                stage: wake.runType,
+                status: "deferred_follow_up_queued",
+                summary: `${wake.runType} queued after ${params.run.runType} released authority`,
+                ...(wake.wakeReason ? { detail: `wake reason: ${wake.wakeReason}` } : {}),
+            });
+        }
+        return {
+            runType: wake.runType,
+            ...(wake.wakeReason ? { wakeReason: wake.wakeReason } : {}),
+        };
+    }
+}

package/dist/webhook-handler.js

@@ -11,12 +11,12 @@ import { DesiredStageRecorder } from "./webhooks/desired-stage-recorder.js";
 import { IssueRemovalHandler } from "./webhooks/issue-removal-handler.js";
 import { safeJsonParse, sanitizeDiagnosticText } from "./utils.js";
 import { extractLatestAssistantSummary } from "./issue-session-events.js";
+import { WakeDispatcher } from "./wake-dispatcher.js";
 export class WebhookHandler {
     config;
     db;
     linearProvider;
     codex;
-    enqueueIssue;
     logger;
     feed;
     installationHandler;
@@ -27,22 +27,29 @@ export class WebhookHandler {
     contextLoader;
     dependencyReadinessHandler;
     linearSync;
-    constructor(config, db, linearProvider, codex, enqueueIssue, logger, feed) {
+    wakeDispatcher;
+    constructor(config, db, linearProvider, codex, wakeDispatcherOrEnqueueIssue, logger, feed) {
         this.config = config;
         this.db = db;
         this.linearProvider = linearProvider;
         this.codex = codex;
-        this.enqueueIssue = enqueueIssue;
         this.logger = logger;
         this.feed = feed;
+        // Webhook handlers never release leases — the orchestrator's
+        // run finalizer owns that. So when a test passes a bare
+        // enqueueIssue callback, wrap it in a dispatcher with a no-op
+        // releaseLease (any production caller passes a real dispatcher).
+        this.wakeDispatcher = wakeDispatcherOrEnqueueIssue instanceof WakeDispatcher
+            ? wakeDispatcherOrEnqueueIssue
+            : new WakeDispatcher(db, wakeDispatcherOrEnqueueIssue, () => undefined, logger, feed);
         this.installationHandler = new InstallationWebhookHandler(config, { linearInstallations: db.linearInstallations }, logger, feed);
         this.issueRemovalHandler = new IssueRemovalHandler(db, feed);
-        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.commentWakeHandler = new CommentWakeHandler(db, codex, this.wakeDispatcher, logger, feed);
+        this.agentSessionHandler = new AgentSessionHandler(config, db, linearProvider, codex, this.wakeDispatcher, logger, feed);
+        this.desiredStageRecorder = new DesiredStageRecorder(db, linearProvider, this.wakeDispatcher, feed);
         this.contextLoader = new WebhookContextLoader(config, linearProvider);
         this.linearSync = new LinearSessionSync(config, db, linearProvider, logger, feed);
-        this.dependencyReadinessHandler = new DependencyReadinessHandler(db, (projectId, issueId) => this.peekPendingSessionWakeRunType(projectId, issueId));
+        this.dependencyReadinessHandler = new DependencyReadinessHandler(db, this.wakeDispatcher, (projectId, issueId) => this.peekPendingSessionWakeRunType(projectId, issueId));
     }
     async processWebhookEvent(webhookEventId) {
         const event = this.db.webhookEvents.getWebhookPayload(webhookEventId);
@@ -145,15 +152,12 @@ export class WebhookHandler {
                 wakeRunType: result.wakeRunType,
                 delegated: result.delegated,
                 peekPendingSessionWakeRunType: (projectId, issueId) => this.peekPendingSessionWakeRunType(projectId, issueId),
-                enqueuePendingSessionWake: (projectId, issueId) => this.enqueuePendingSessionWake(projectId, issueId),
                 isDirectReplyToOutstandingQuestion: (targetIssue) => this.isDirectReplyToOutstandingQuestion(targetIssue),
             });
             await this.commentWakeHandler.handle({
                 normalized: hydrated,
                 project,
                 trackedIssue,
-                enqueuePendingSessionWake: (projectId, issueId) => this.enqueuePendingSessionWake(projectId, issueId),
-                peekPendingSessionWakeRunType: (projectId, issueId) => this.peekPendingSessionWakeRunType(projectId, issueId),
                 isDirectReplyToOutstandingQuestion: (targetIssue) => this.isDirectReplyToOutstandingQuestion(targetIssue),
             });
             this.db.webhookEvents.markWebhookProcessed(webhookEventId, "processed");
@@ -174,8 +178,11 @@ export class WebhookHandler {
                 });
             }
             for (const dependentIssueId of newlyReadyDependents) {
+                // The dependency-readiness handler already dispatched via the
+                // wake dispatcher; here we just emit the operator-feed event so
+                // the dispatched run shows up in the timeline.
                 const dependent = this.db.getTrackedIssue(project.id, dependentIssueId);
-                const queuedRunType = this.enqueuePendingSessionWake(project.id, dependentIssueId);
+                const queuedRunType = this.peekPendingSessionWakeRunType(project.id, dependentIssueId);
                 this.feed?.publish({
                     level: "info",
                     kind: "stage",
@@ -224,12 +231,7 @@ export class WebhookHandler {
         return this.db.issueSessions.peekIssueSessionWake(projectId, issueId)?.runType;
     }
     enqueuePendingSessionWake(projectId, issueId) {
-        const wake = this.db.issueSessions.peekIssueSessionWake(projectId, issueId);
-        if (!wake) {
-            return undefined;
-        }
-        this.enqueueIssue(projectId, issueId);
-        return wake.runType;
+        return this.wakeDispatcher.dispatchIfWakePending(projectId, issueId);
     }
     isDirectReplyToOutstandingQuestion(issue) {
         if (!issue)