fix: keep embedded run lanes from wedging

src/process/command-queue.ts

@@ -4,6 +4,7 @@ import {
   logLaneEnqueue,
 } from "../logging/diagnostic-runtime.js";
 import { resolveGlobalSingleton } from "../shared/global-singleton.js";
+import type { CommandQueueEnqueueOptions } from "./command-queue.types.js";
 import { CommandLane } from "./lanes.js";
 /**
  * Dedicated error type thrown when a queued command is rejected because
@@ -17,6 +18,18 @@ export class CommandLaneClearedError extends Error {
   }
 }
 
+/**
+ * Dedicated error type thrown when an active command exceeds its caller-owned
+ * lane timeout. The underlying task may still be unwinding, but the lane is
+ * released so queued work is not blocked forever.
+ */
+export class CommandLaneTaskTimeoutError extends Error {
+  constructor(lane: string, timeoutMs: number) {
+    super(`Command lane "${lane}" task timed out after ${timeoutMs}ms`);
+    this.name = "CommandLaneTaskTimeoutError";
+  }
+}
+
 /**
  * Dedicated error type thrown when a new command is rejected because the
  * gateway is currently draining for restart.
@@ -39,6 +52,7 @@ type QueueEntry = {
   reject: (reason?: unknown) => void;
   enqueuedAt: number;
   warnAfterMs: number;
+  taskTimeoutMs?: number;
   onWait?: (waitMs: number, queuedAhead: number) => void;
 };
 
@@ -172,6 +186,48 @@ function notifyActiveTaskWaiters(): void {
   }
 }
 
+function normalizeTaskTimeoutMs(value: number | undefined): number | undefined {
+  if (value === undefined || !Number.isFinite(value) || value <= 0) {
+    return undefined;
+  }
+  return Math.max(1, Math.floor(value));
+}
+
+async function runQueueEntryTask(lane: string, entry: QueueEntry): Promise<unknown> {
+  const taskPromise = Promise.resolve().then(entry.task);
+  const taskTimeoutMs = normalizeTaskTimeoutMs(entry.taskTimeoutMs);
+  if (taskTimeoutMs === undefined) {
+    return await taskPromise;
+  }
+
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  let timedOut = false;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutHandle = setTimeout(() => {
+      timedOut = true;
+      reject(new CommandLaneTaskTimeoutError(lane, taskTimeoutMs));
+    }, taskTimeoutMs);
+    timeoutHandle.unref?.();
+  });
+
+  try {
+    return await Promise.race([taskPromise, timeoutPromise]);
+  } catch (err) {
+    if (timedOut) {
+      void taskPromise.catch((lateErr) => {
+        diag.warn(
+          `lane task rejected after timeout: lane=${lane} timeoutMs=${taskTimeoutMs} error="${String(lateErr)}"`,
+        );
+      });
+    }
+    throw err;
+  } finally {
+    if (!timedOut && timeoutHandle) {
+      clearTimeout(timeoutHandle);
+    }
+  }
+}
+
 function drainLane(lane: string) {
   const state = getLaneState(lane);
   if (state.draining) {
@@ -206,7 +262,7 @@ function drainLane(lane: string) {
         void (async () => {
           const startTime = Date.now();
           try {
-            const result = await entry.task();
+            const result = await runQueueEntryTask(lane, entry);
             const completedCurrentGeneration = completeTask(state, taskId, taskGeneration);
             if (completedCurrentGeneration) {
               notifyActiveTaskWaiters();
@@ -262,10 +318,7 @@ export function setCommandLaneConcurrency(lane: string, maxConcurrent: number) {
 export function enqueueCommandInLane<T>(
   lane: string,
   task: () => Promise<T>,
-  opts?: {
-    warnAfterMs?: number;
-    onWait?: (waitMs: number, queuedAhead: number) => void;
-  },
+  opts?: CommandQueueEnqueueOptions,
 ): Promise<T> {
   const queueState = getQueueState();
   if (queueState.gatewayDraining) {
@@ -281,6 +334,7 @@ export function enqueueCommandInLane<T>(
       reject,
       enqueuedAt: Date.now(),
       warnAfterMs,
+      taskTimeoutMs: normalizeTaskTimeoutMs(opts?.taskTimeoutMs),
       onWait: opts?.onWait,
     });
     logLaneEnqueue(cleaned, getLaneDepth(state));
@@ -290,10 +344,7 @@ export function enqueueCommandInLane<T>(
 
 export function enqueueCommand<T>(
   task: () => Promise<T>,
-  opts?: {
-    warnAfterMs?: number;
-    onWait?: (waitMs: number, queuedAhead: number) => void;
-  },
+  opts?: CommandQueueEnqueueOptions,
 ): Promise<T> {
   return enqueueCommandInLane(CommandLane.Main, task, opts);
 }