patchrelay 0.74.5 → 0.74.7

package/dist/run-orchestrator.js

@@ -23,6 +23,7 @@ import { classifyIssue } from "./issue-class.js";
 import { buildIssueTriageHash, IssueTriageService } from "./issue-triage.js";
 import { loadConfig } from "./config.js";
 import { CodexThreadMaterializingError, isThreadMaterializingError } from "./codex-thread-errors.js";
+import { emitTelemetry, noopTelemetry } from "./telemetry.js";
 function lowerCaseFirst(value) {
     return value ? `${value.slice(0, 1).toLowerCase()}${value.slice(1)}` : value;
 }
@@ -84,7 +85,8 @@ export class RunOrchestrator {
     logger;
     feed;
     configPath;
-    constructor(config, db, codex, linearProvider, enqueueIssue, wakeDispatcherOrLogger, loggerOrFeed, feedOrConfigPath, configPathOrUndefined) {
+    telemetry;
+    constructor(config, db, codex, linearProvider, enqueueIssue, wakeDispatcherOrLogger, loggerOrFeed, feedOrConfigPath, configPathOrUndefined, telemetryOrUndefined) {
         this.config = config;
         this.db = db;
         this.codex = codex;
@@ -95,6 +97,7 @@ export class RunOrchestrator {
         let logger;
         let feed;
         let configPath;
+        const telemetry = telemetryOrUndefined ?? noopTelemetry;
         if (wakeDispatcherOrLogger instanceof WakeDispatcher) {
             this.wakeDispatcher = wakeDispatcherOrLogger;
             logger = loggerOrFeed;
@@ -109,15 +112,16 @@ export class RunOrchestrator {
             // 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.wakeDispatcher = new WakeDispatcher(db, enqueueIssue, (projectId, linearIssueId) => this.leaseService?.release(projectId, linearIssueId), logger, feed, telemetry);
         }
         this.logger = logger;
         this.feed = feed;
         this.configPath = configPath;
+        this.telemetry = telemetry;
         this.worktreeManager = new WorktreeManager(config);
         this.codexRuntimeConfig = config.runner.codex;
         this.linearSync = new LinearSessionSync(config, db, linearProvider, logger, feed);
-        this.leaseService = new IssueSessionLeaseService(db, logger, this.workerId, this.threadPorts.readThreadWithRetry);
+        this.leaseService = new IssueSessionLeaseService(db, logger, this.workerId, this.threadPorts.readThreadWithRetry, telemetry);
         this.activeSessionLeases = this.leaseService.activeSessionLeases;
         this.runCompletionPolicy = new RunCompletionPolicy(config, db, logger, this.leasePorts.withHeldLease);
         this.completionCheck = new CompletionCheckService(codex, logger);
@@ -237,9 +241,20 @@ export class RunOrchestrator {
     }
     // ─── Run ────────────────────────────────────────────────────────
     async run(item) {
+        emitTelemetry(this.telemetry, {
+            type: "queue.dequeued",
+            projectId: item.projectId,
+            linearIssueId: item.issueId,
+        });
+        emitTelemetry(this.telemetry, {
+            type: "run.dequeued",
+            projectId: item.projectId,
+            linearIssueId: item.issueId,
+        });
         await this.refreshCodexRuntimeConfig();
         const project = this.config.projects.find((p) => p.id === item.projectId);
         if (!project) {
+            this.emitRunSkipped(item, "project_not_configured");
             this.logger.info({ projectId: item.projectId, linearIssueId: item.issueId, reason: "project_not_configured" }, "Skipped issue run: project missing from config");
             return;
         }
@@ -248,30 +263,38 @@ export class RunOrchestrator {
         // 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.emitRunSkipped(item, "lease_held_locally");
             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) {
+            this.emitRunSkipped(item, "issue_missing");
             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.emitActiveRunBlockerInvariant(initialIssue);
+            this.emitRunSkipped(item, "active_run_present", initialIssue, { activeRunId: initialIssue.activeRunId });
             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) {
+            this.emitRunSkipped(item, "classification_dropped_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.emitActiveRunBlockerInvariant(issue);
+            this.emitRunSkipped(item, "active_run_present_post_classify", issue, { activeRunId: issue.activeRunId });
             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.emitRunSkipped(item, "lease_acquire_failed", issue);
             this.logger.info({ issueKey: issue.issueKey, projectId: item.projectId, reason: "lease_acquire_failed" }, "Skipped issue run: another worker holds the session lease");
             return;
         }
@@ -283,19 +306,23 @@ export class RunOrchestrator {
         const wakeIssue = this.materializeLegacyPendingWake(issue, { projectId: item.projectId, linearIssueId: item.issueId, leaseId });
         const wake = this.resolveRunWake(wakeIssue);
         if (!wake) {
+            this.emitRunSkipped(item, "no_wake_derivable", issue);
             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;
         }
         const { runType, context, resumeThread } = wake;
         if (runType === "implementation" && this.db.issues.countUnresolvedBlockers(item.projectId, item.issueId) > 0) {
+            const blockerCount = this.db.issues.countUnresolvedBlockers(item.projectId, item.issueId);
             this.db.issueSessions.clearPendingIssueSessionEventsRespectingActiveLease(item.projectId, item.issueId);
             this.releaseIssueSessionLease(item.projectId, item.issueId);
+            this.emitRunSkipped(item, "blocked", issue, { runType, blockerCount });
             this.logger.info({ issueKey: issue.issueKey }, "Skipped implementation launch because the issue is blocked");
             return;
         }
         const remainingZombieDelayMs = shouldDelayZombieRecoveryLaunch(issue, issueSession, runType);
         if (remainingZombieDelayMs > 0) {
+            this.emitRunSkipped(item, "zombie_backoff", issue, { runType, remainingDelayMs: remainingZombieDelayMs });
             this.logger.debug({ issueKey: issue.issueKey, runType, remainingZombieDelayMs }, "Deferring recovered run launch until zombie backoff elapses");
             this.releaseIssueSessionLease(item.projectId, item.issueId);
             return;
@@ -314,6 +341,7 @@ export class RunOrchestrator {
             const dismissed = this.db.issueSessions.dismissIssueSessionEventsWithLease(lease, requestedChangesEventIds);
             if (!dismissed) {
                 this.releaseIssueSessionLease(item.projectId, item.issueId);
+                this.emitRunSkipped(item, "lease_lost_dismissing_inactive_requested_changes_wake", issue, { runType });
                 this.logger.info({ issueKey: issue.issueKey, projectId: item.projectId, reason: "lease_lost_dismissing_inactive_requested_changes_wake" }, "Skipped issue run: lost lease while dismissing inactive requested-changes wake");
                 return;
             }
@@ -335,6 +363,7 @@ export class RunOrchestrator {
                 prReviewState: launchIssue.prReviewState,
                 prState: launchIssue.prState,
             }, "Skipped issue run: requested-changes wake is no longer active");
+            this.emitRunSkipped(item, "inactive_requested_changes_wake", issue, { runType });
             this.releaseIssueSessionLease(item.projectId, item.issueId);
             this.wakeDispatcher.dispatchIfWakePending(item.projectId, item.issueId);
             return;
@@ -363,10 +392,12 @@ export class RunOrchestrator {
                 : issue.prHeadSha;
         const budgetExceeded = this.runWakePlanner.budgetExceeded(issue, project, runType, isRequestedChangesRunType);
         if (budgetExceeded) {
+            this.emitRunSkipped(item, "budget_exceeded", issue, { runType });
             this.escalate(issue, runType, budgetExceeded);
             return;
         }
         if (!this.runWakePlanner.incrementAttemptCounters(issue, { projectId: issue.projectId, linearIssueId: issue.linearIssueId, leaseId }, runType, isRequestedChangesRunType)) {
+            this.emitRunSkipped(item, "lease_lost_incrementing_attempts", issue, { runType });
             this.releaseIssueSessionLease(item.projectId, item.issueId);
             return;
         }
@@ -390,6 +421,7 @@ export class RunOrchestrator {
             worktreePath,
         });
         if (!run) {
+            this.emitRunSkipped(item, "claim_failed", issue, { runType });
             this.releaseIssueSessionLease(item.projectId, item.issueId);
             return;
         }
@@ -453,6 +485,37 @@ export class RunOrchestrator {
     async resetWorktreeToTrackedBranch(worktreePath, branchName, issue) {
         await this.worktreeManager.resetWorktreeToTrackedBranch(worktreePath, branchName, issue, this.logger);
     }
+    emitRunSkipped(item, reason, issue, details) {
+        emitTelemetry(this.telemetry, {
+            type: "run.skipped",
+            projectId: item.projectId,
+            linearIssueId: item.issueId,
+            ...(issue?.issueKey ? { issueKey: issue.issueKey } : {}),
+            reason,
+            ...(details?.runType ? { runType: details.runType } : {}),
+            ...(details?.activeRunId !== undefined ? { activeRunId: details.activeRunId } : {}),
+            ...(details?.blockerCount !== undefined ? { blockerCount: details.blockerCount } : {}),
+            ...(details?.remainingDelayMs !== undefined ? { remainingDelayMs: details.remainingDelayMs } : {}),
+        });
+    }
+    emitActiveRunBlockerInvariant(issue) {
+        if (issue.activeRunId === undefined)
+            return;
+        const blockerCount = this.db.issues.countUnresolvedBlockers(issue.projectId, issue.linearIssueId);
+        if (blockerCount === 0)
+            return;
+        emitTelemetry(this.telemetry, {
+            type: "health.invariant",
+            invariant: "active_run_with_unresolved_blocker",
+            status: "observed",
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+            ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
+            runId: issue.activeRunId,
+            blockerCount,
+            detail: "Run dequeue found an active run while blockers are unresolved",
+        });
+    }
     async restoreIdleWorktree(issue) {
         await this.worktreeManager.restoreIdleWorktree(issue, this.logger);
     }

package/dist/service.js

@@ -17,6 +17,7 @@ import { acceptIncomingWebhook } from "./service-webhooks.js";
 import { parseStringArray, TrackedIssueListQuery } from "./tracked-issue-list-query.js";
 import { AgentInputService } from "./agent-input-service.js";
 import { CodexFollowupIntentClassifier } from "./followup-intent.js";
+import { FanoutPatchRelayTelemetry, LoggerTelemetrySink, OperatorFeedTelemetrySink } from "./telemetry.js";
 export class PatchRelayService {
     config;
     db;
@@ -43,6 +44,11 @@ export class PatchRelayService {
         this.configPath = configPath;
         this.linearProvider = toLinearClientProvider(linearProvider);
         this.feed = new OperatorEventFeed(db.operatorFeed);
+        const telemetry = new FanoutPatchRelayTelemetry([
+            new LoggerTelemetrySink(logger),
+            new OperatorFeedTelemetrySink(this.feed),
+        ]);
+        db.setTelemetry(telemetry);
         let enqueueIssue = () => {
             throw new Error("Service runtime enqueueIssue is not initialized");
         };
@@ -55,11 +61,11 @@ export class PatchRelayService {
         // 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);
+        const dispatcher = new WakeDispatcher(db, (projectId, issueId) => enqueueIssue(projectId, issueId), (projectId, issueId) => leaseRelease(projectId, issueId), logger, this.feed, telemetry);
         const agentInput = new AgentInputService(db, codex, dispatcher, logger, this.feed, new CodexFollowupIntentClassifier(codex, logger));
-        this.orchestrator = new RunOrchestrator(config, db, codex, this.linearProvider, (projectId, issueId) => enqueueIssue(projectId, issueId), dispatcher, logger, this.feed, this.configPath);
+        this.orchestrator = new RunOrchestrator(config, db, codex, this.linearProvider, (projectId, issueId) => enqueueIssue(projectId, issueId), dispatcher, logger, this.feed, this.configPath, telemetry);
         leaseRelease = (projectId, issueId) => this.orchestrator.leaseService.release(projectId, issueId);
-        this.webhookHandler = new WebhookHandler(config, db, this.linearProvider, codex, dispatcher, logger, this.feed, undefined, agentInput);
+        this.webhookHandler = new WebhookHandler(config, db, this.linearProvider, codex, dispatcher, logger, this.feed, undefined, agentInput, telemetry);
         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) => {

package/dist/telemetry.js

@@ -0,0 +1,85 @@
+export const noopTelemetry = {
+    emit: () => undefined,
+};
+export function emitTelemetry(telemetry, event) {
+    try {
+        telemetry.emit(event);
+    }
+    catch {
+        // Telemetry must never affect workflow execution.
+    }
+}
+export class FanoutPatchRelayTelemetry {
+    sinks;
+    constructor(sinks) {
+        this.sinks = sinks;
+    }
+    emit(event) {
+        for (const sink of this.sinks) {
+            emitTelemetry(sink, event);
+        }
+    }
+}
+export class MemoryPatchRelayTelemetry {
+    events = [];
+    emit(event) {
+        this.events.push(event);
+    }
+    list(type) {
+        if (!type)
+            return this.events;
+        return this.events.filter((event) => event.type === type);
+    }
+}
+export class LoggerTelemetrySink {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    emit(event) {
+        this.logger.info({ telemetryEvent: event.type, ...event }, "PatchRelay telemetry event");
+    }
+}
+export class OperatorFeedTelemetrySink {
+    feed;
+    constructor(feed) {
+        this.feed = feed;
+    }
+    emit(event) {
+        const feedEvent = this.toFeedEvent(event);
+        if (feedEvent) {
+            this.feed.publish(feedEvent);
+        }
+    }
+    toFeedEvent(event) {
+        switch (event.type) {
+            case "dependency.dependent_unblocked":
+                return {
+                    level: "info",
+                    kind: "workflow",
+                    ...(event.issueKey ? { issueKey: event.issueKey } : {}),
+                    ...(event.projectId ? { projectId: event.projectId } : {}),
+                    ...(event.dispatchedRunType ? { stage: event.dispatchedRunType } : {}),
+                    status: "dependency_unblocked",
+                    summary: event.dispatchedRunType
+                        ? `Dependency unblocked; ${event.dispatchedRunType} queued`
+                        : "Dependency unblocked",
+                };
+            case "run.skipped":
+                if (event.reason === "blocked" || event.reason === "lease_acquire_failed" || event.reason === "no_wake_derivable") {
+                    return {
+                        level: event.reason === "blocked" ? "info" : "warn",
+                        kind: "stage",
+                        ...(event.issueKey ? { issueKey: event.issueKey } : {}),
+                        ...(event.projectId ? { projectId: event.projectId } : {}),
+                        ...(event.runType ? { stage: event.runType } : {}),
+                        status: "skipped",
+                        summary: `Run skipped: ${event.reason}`,
+                    };
+                }
+                return undefined;
+            default:
+                return undefined;
+        }
+    }
+}

package/dist/wake-dispatcher.js

@@ -1,3 +1,4 @@
+import { emitTelemetry, noopTelemetry } from "./telemetry.js";
 // 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
@@ -21,13 +22,15 @@ export class WakeDispatcher {
     releaseLease;
     logger;
     feed;
+    telemetry;
     currentTick;
-    constructor(db, enqueueIssue, releaseLease, logger, feed) {
+    constructor(db, enqueueIssue, releaseLease, logger, feed, telemetry = noopTelemetry) {
         this.db = db;
         this.enqueueIssue = enqueueIssue;
         this.releaseLease = releaseLease;
         this.logger = logger;
         this.feed = feed;
+        this.telemetry = telemetry;
     }
     // Scope the next enqueue calls inside `fn` to a single dedupe Set.
     // Nested ticks reuse the outermost Set so deeply nested helpers do
@@ -48,11 +51,23 @@ export class WakeDispatcher {
     // 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, {
+        const appended = this.db.issueSessions.appendIssueSessionEventRespectingActiveLease(projectId, linearIssueId, {
             projectId,
             linearIssueId,
             ...event,
         });
+        const issue = this.db.issues.getIssue(projectId, linearIssueId);
+        if (appended) {
+            emitTelemetry(this.telemetry, {
+                type: "wake.created",
+                projectId,
+                linearIssueId,
+                ...(issue?.issueKey ? { issueKey: issue.issueKey } : {}),
+                eventIds: [appended.id],
+                sessionEventType: event.eventType,
+                ...(event.dedupeKey ? { dedupeKey: event.dedupeKey } : {}),
+            });
+        }
         // 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.
@@ -67,22 +82,143 @@ export class WakeDispatcher {
     // post-run drain via releaseRunAndDispatch.
     dispatchIfWakePending(projectId, linearIssueId, options) {
         const issue = this.db.issues.getIssue(projectId, linearIssueId);
-        if (issue?.activeRunId !== undefined)
+        if (!issue) {
+            emitTelemetry(this.telemetry, {
+                type: "wake.suppressed",
+                projectId,
+                linearIssueId,
+                reason: "issue_missing",
+            });
+            return undefined;
+        }
+        if (issue.activeRunId !== undefined) {
+            const blockerCount = this.db.issues.countUnresolvedBlockers(projectId, linearIssueId);
+            emitTelemetry(this.telemetry, {
+                type: "wake.suppressed",
+                projectId,
+                linearIssueId,
+                ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
+                reason: "active_run_present",
+                activeRunId: issue.activeRunId,
+                ...(blockerCount > 0 ? { blockerCount } : {}),
+            });
+            if (blockerCount > 0) {
+                emitTelemetry(this.telemetry, {
+                    type: "health.invariant",
+                    invariant: "active_run_with_unresolved_blocker",
+                    status: "observed",
+                    projectId,
+                    linearIssueId,
+                    ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
+                    runId: issue.activeRunId,
+                    blockerCount,
+                    detail: "Wake suppressed because an active run exists while blockers are unresolved",
+                });
+            }
+            return undefined;
+        }
+        const unresolvedBlockers = this.db.issues.countUnresolvedBlockers(projectId, linearIssueId);
+        if (unresolvedBlockers > 0) {
+            const blockerKeys = this.unresolvedBlockerKeys(projectId, linearIssueId);
+            emitTelemetry(this.telemetry, {
+                type: "wake.suppressed",
+                projectId,
+                linearIssueId,
+                ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
+                reason: "blocked",
+                blockerCount: unresolvedBlockers,
+                blockerKeys,
+            });
+            const pendingBlockedWake = this.db.issueSessions.peekIssueSessionWake(projectId, linearIssueId) ?? issue.pendingRunType;
+            if (pendingBlockedWake) {
+                emitTelemetry(this.telemetry, {
+                    type: "health.invariant",
+                    invariant: "blocked_issue_with_pending_wake",
+                    status: "observed",
+                    projectId,
+                    linearIssueId,
+                    ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
+                    blockerCount: unresolvedBlockers,
+                    detail: "Wake remains pending while blockers are unresolved",
+                });
+            }
             return undefined;
+        }
         const wake = this.db.workflowWakes.peekIssueWake(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)
+        const runType = wake?.runType ?? issue.pendingRunType;
+        if (!runType) {
+            emitTelemetry(this.telemetry, {
+                type: "wake.suppressed",
+                projectId,
+                linearIssueId,
+                ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
+                reason: "no_wake_derivable",
+            });
+            if (this.db.listIssuesReadyForExecution().some((entry) => entry.projectId === projectId && entry.linearIssueId === linearIssueId)) {
+                emitTelemetry(this.telemetry, {
+                    type: "health.invariant",
+                    invariant: "ready_issue_not_enqueued",
+                    status: "observed",
+                    projectId,
+                    linearIssueId,
+                    ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
+                    detail: "Issue appears ready for execution but no wake was derivable for enqueue",
+                });
+            }
             return undefined;
+        }
+        emitTelemetry(this.telemetry, {
+            type: "wake.derived",
+            projectId,
+            linearIssueId,
+            ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
+            runType,
+            ...(wake?.wakeReason ? { wakeReason: wake.wakeReason } : {}),
+            ...(wake?.eventIds ? { eventIds: wake.eventIds } : {}),
+            source: wake ? (wake.eventIds.length > 0 ? "session_event" : "implicit") : "legacy_pending_run_type",
+        });
         const tick = options?.enqueuedThisTick ?? this.currentTick;
         const key = `${projectId}:${linearIssueId}`;
         if (tick?.has(key)) {
+            emitTelemetry(this.telemetry, {
+                type: "wake.deduped",
+                projectId,
+                linearIssueId,
+                ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
+                runType,
+                ...(wake?.wakeReason ? { wakeReason: wake.wakeReason } : {}),
+                ...(wake?.eventIds ? { eventIds: wake.eventIds } : {}),
+            });
+            emitTelemetry(this.telemetry, {
+                type: "queue.deduped",
+                projectId,
+                linearIssueId,
+                ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
+                runType,
+            });
             return runType;
         }
         tick?.add(key);
         this.enqueueIssue(projectId, linearIssueId);
+        emitTelemetry(this.telemetry, {
+            type: "wake.dispatched",
+            projectId,
+            linearIssueId,
+            ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
+            runType,
+            ...(wake?.wakeReason ? { wakeReason: wake.wakeReason } : {}),
+            ...(wake?.eventIds ? { eventIds: wake.eventIds } : {}),
+        });
+        emitTelemetry(this.telemetry, {
+            type: "queue.enqueued",
+            projectId,
+            linearIssueId,
+            ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
+            runType,
+        });
         return runType;
     }
     // Release the lease for a finished run, then drain any wake that
@@ -97,10 +233,42 @@ export class WakeDispatcher {
     // check paths publish their own more-specific event and pass false.
     releaseRunAndDispatch(params) {
         this.releaseLease(params.run.projectId, params.run.linearIssueId);
+        emitTelemetry(this.telemetry, {
+            type: "run.released",
+            projectId: params.run.projectId,
+            linearIssueId: params.run.linearIssueId,
+            ...(params.issueKey ? { issueKey: params.issueKey } : {}),
+            runId: params.run.id,
+            runType: params.run.runType,
+        });
         const wake = this.db.workflowWakes.peekIssueWake(params.run.projectId, params.run.linearIssueId);
-        if (!wake)
+        if (!wake) {
+            emitTelemetry(this.telemetry, {
+                type: "wake.suppressed",
+                projectId: params.run.projectId,
+                linearIssueId: params.run.linearIssueId,
+                ...(params.issueKey ? { issueKey: params.issueKey } : {}),
+                reason: "no_wake_derivable",
+            });
             return undefined;
+        }
         this.enqueueIssue(params.run.projectId, params.run.linearIssueId);
+        emitTelemetry(this.telemetry, {
+            type: "wake.dispatched",
+            projectId: params.run.projectId,
+            linearIssueId: params.run.linearIssueId,
+            ...(params.issueKey ? { issueKey: params.issueKey } : {}),
+            runType: wake.runType,
+            ...(wake.wakeReason ? { wakeReason: wake.wakeReason } : {}),
+            eventIds: wake.eventIds,
+        });
+        emitTelemetry(this.telemetry, {
+            type: "queue.enqueued",
+            projectId: params.run.projectId,
+            linearIssueId: params.run.linearIssueId,
+            ...(params.issueKey ? { issueKey: params.issueKey } : {}),
+            runType: wake.runType,
+        });
         if (params.publishDeferredFollowUp) {
             this.feed?.publish({
                 level: "info",
@@ -118,4 +286,10 @@ export class WakeDispatcher {
             ...(wake.wakeReason ? { wakeReason: wake.wakeReason } : {}),
         };
     }
+    unresolvedBlockerKeys(projectId, linearIssueId) {
+        return this.db.issues.listIssueDependencies(projectId, linearIssueId)
+            .filter((entry) => entry.blockerCurrentLinearStateType !== "completed"
+            && entry.blockerCurrentLinearState?.trim().toLowerCase() !== "done")
+            .map((entry) => entry.blockerIssueKey ?? entry.blockerLinearIssueId);
+    }
 }

package/dist/webhook-handler.js

@@ -14,6 +14,7 @@ import { extractLatestAssistantSummary } from "./issue-session-events.js";
 import { WakeDispatcher } from "./wake-dispatcher.js";
 import { CodexFollowupIntentClassifier } from "./followup-intent.js";
 import { AgentInputService } from "./agent-input-service.js";
+import { noopTelemetry } from "./telemetry.js";
 export class WebhookHandler {
     config;
     db;
@@ -21,6 +22,7 @@ export class WebhookHandler {
     codex;
     logger;
     feed;
+    telemetry;
     installationHandler;
     issueRemovalHandler;
     commentWakeHandler;
@@ -30,20 +32,21 @@ export class WebhookHandler {
     dependencyReadinessHandler;
     linearSync;
     wakeDispatcher;
-    constructor(config, db, linearProvider, codex, wakeDispatcherOrEnqueueIssue, logger, feed, followupClassifier, agentInput) {
+    constructor(config, db, linearProvider, codex, wakeDispatcherOrEnqueueIssue, logger, feed, followupClassifier, agentInput, telemetry = noopTelemetry) {
         this.config = config;
         this.db = db;
         this.linearProvider = linearProvider;
         this.codex = codex;
         this.logger = logger;
         this.feed = feed;
+        this.telemetry = telemetry;
         // 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);
+            : new WakeDispatcher(db, wakeDispatcherOrEnqueueIssue, () => undefined, logger, feed, telemetry);
         this.installationHandler = new InstallationWebhookHandler(config, { linearInstallations: db.linearInstallations }, logger, feed);
         this.issueRemovalHandler = new IssueRemovalHandler(db, feed);
         this.linearSync = new LinearSessionSync(config, db, linearProvider, logger, feed);
@@ -53,7 +56,7 @@ export class WebhookHandler {
         this.agentSessionHandler = new AgentSessionHandler(config, db, linearProvider, codex, this.wakeDispatcher, logger, feed, agentInputService);
         this.desiredStageRecorder = new DesiredStageRecorder(db, linearProvider, this.wakeDispatcher, feed);
         this.contextLoader = new WebhookContextLoader(config, linearProvider);
-        this.dependencyReadinessHandler = new DependencyReadinessHandler(db, this.wakeDispatcher, (projectId, issueId) => this.peekPendingSessionWakeRunType(projectId, issueId));
+        this.dependencyReadinessHandler = new DependencyReadinessHandler(db, this.wakeDispatcher, (projectId, issueId) => this.peekPendingSessionWakeRunType(projectId, issueId), telemetry);
     }
     async processWebhookEvent(webhookEventId) {
         const event = this.db.webhookEvents.getWebhookPayload(webhookEventId);