From a5ccfa57a8ca5ce8cf7d0c854075db3b2dd63189 Mon Sep 17 00:00:00 2001
From: Yi LIU <yi@quantstamp.com>
Date: Sat, 14 Feb 2026 01:43:33 +0800
Subject: [PATCH] refactor(process): use dedicated CommandLaneClearedError in
 clearCommandLane

Replace bare `new Error("Command lane cleared")` with a dedicated
`CommandLaneClearedError` class so callers that fire-and-forget
enqueued tasks can catch this specific type and avoid surfacing
unhandled rejection warnings.
---
 src/process/command-queue.test.ts |  3 ++-
 src/process/command-queue.ts      | 13 ++++++++++++-
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/src/process/command-queue.test.ts b/src/process/command-queue.test.ts
index e9f7a7f549a..60034b43929 100644
--- a/src/process/command-queue.test.ts
+++ b/src/process/command-queue.test.ts
@@ -18,6 +18,7 @@ vi.mock("../logging/diagnostic.js", () => ({
 
 import {
   clearCommandLane,
+  CommandLaneClearedError,
   enqueueCommand,
   enqueueCommandInLane,
   getActiveTaskCount,
@@ -218,7 +219,7 @@ describe("command queue", () => {
     expect(removed).toBe(1); // only the queued (not active) entry
 
     // The queued promise should reject.
-    await expect(second).rejects.toThrow("Command lane cleared");
+    await expect(second).rejects.toBeInstanceOf(CommandLaneClearedError);
 
     // Let the active task finish normally.
     resolve1();
diff --git a/src/process/command-queue.ts b/src/process/command-queue.ts
index 4fbe63addc8..b0f012ca245 100644
--- a/src/process/command-queue.ts
+++ b/src/process/command-queue.ts
@@ -1,5 +1,16 @@
 import { diagnosticLogger as diag, logLaneDequeue, logLaneEnqueue } from "../logging/diagnostic.js";
 import { CommandLane } from "./lanes.js";
+/**
+ * Dedicated error type thrown when a queued command is rejected because
+ * its lane was cleared.  Callers that fire-and-forget enqueued tasks can
+ * catch (or ignore) this specific type to avoid unhandled-rejection noise.
+ */
+export class CommandLaneClearedError extends Error {
+  constructor(lane?: string) {
+    super(lane ? `Command lane "${lane}" cleared` : "Command lane cleared");
+    this.name = "CommandLaneClearedError";
+  }
+}
 
 // Minimal in-process queue to serialize command executions.
 // Default lane ("main") preserves the existing behavior. Additional lanes allow
@@ -164,7 +175,7 @@ export function clearCommandLane(lane: string = CommandLane.Main) {
   const removed = state.queue.length;
   const pending = state.queue.splice(0);
   for (const entry of pending) {
-    entry.reject(new Error("Command lane cleared"));
+    entry.reject(new CommandLaneClearedError(cleaned));
   }
   return removed;
 }