comfyui-mcp 0.48.21 → 0.48.23

package/dist/services/ui-bridge.js

@@ -17,10 +17,58 @@
 import { randomUUID, timingSafeEqual } from "node:crypto";
 import { WebSocketServer, WebSocket } from "ws";
 import { logger } from "../utils/logger.js";
+import { compareSemver } from "./self-update.js";
 export const DEFAULT_BRIDGE_PORT = 9101;
 /** Panel build that first implements the full graph_* / ui_* bridge command set.
- *  Reports of "Unknown command <x>" come from panels older than this. */
+ *  Used as the DEFAULT minimum for any bridge command not listed in
+ *  BRIDGE_CMD_MIN_PANEL_VERSION below. Individual commands shipped EARLIER than
+ *  this (see the map) and must quote their own, lower minimum. */
 export const MIN_PANEL_VERSION_FOR_BRIDGE_COMMANDS = "0.11.4";
+/** The panel version each bridge command was ACTUALLY introduced in (from the
+ *  comfyui-mcp-panel CHANGELOG). The old code quoted a single blanket 0.11.4 for
+ *  EVERY command, which is wrong for commands that shipped much earlier —
+ *  graph_outline has existed since panel 0.4.6, so a "too old — update to ≥0.11.4"
+ *  verdict for it is a false, inflated requirement (#352). Anything not listed
+ *  falls back to MIN_PANEL_VERSION_FOR_BRIDGE_COMMANDS (the full-set baseline). */
+export const BRIDGE_CMD_MIN_PANEL_VERSION = {
+    graph_outline: "0.4.6",
+    graph_find_nodes: "0.4.6",
+    graph_query: "0.7.0",
+    graph_serialize: "0.8.2",
+};
+/** The minimum panel version that supports `cmd`. */
+export function minPanelVersionForCmd(cmd) {
+    return BRIDGE_CMD_MIN_PANEL_VERSION[cmd] ?? MIN_PANEL_VERSION_FOR_BRIDGE_COMMANDS;
+}
+/** A version string compareSemver can actually parse. compareSemver returns 0
+ *  BOTH for "equal" and for "unparseable", so callers that must distinguish an
+ *  unparseable input from a genuine tie (like panelSupportsCmd's `>= 0`) have to
+ *  screen the input first — otherwise `panel_version: "dev"` would compare as 0
+ *  and be mistaken for a match. */
+const SEMVER_RE = /^v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/;
+/** True when the panel ADVERTISED a PARSEABLE version (in its `hello`) that already
+ *  meets `cmd`'s real minimum — i.e. this panel is new enough to support the command,
+ *  so an "Unknown command" reply is NOT an age problem and must never be rewritten
+ *  into a "too old — update your panel" verdict (#352 false negative). Missing OR
+ *  unparseable panelVersion → we can't PROVE it's new enough, so treat as not-proven
+ *  (fall through to the honest too-old path, which quotes the correct minimum, and
+ *  keep the #236 learning path intact). */
+function panelSupportsCmd(cmd, panelVersion) {
+    if (!panelVersion || !SEMVER_RE.test(panelVersion.trim()))
+        return false;
+    return compareSemver(panelVersion, minPanelVersionForCmd(cmd)) >= 0;
+}
+/** The actionable "update your panel" message for a command a connected panel has
+ *  been discovered NOT to support. Shared by the reactive path (the panel's own
+ *  "Unknown command" reply, mapped by makeUnknownCommandError) and the proactive
+ *  gate (#236 — a command already known-unsupported for THIS connection, from an
+ *  earlier call in the same session) so both produce the identical message. The
+ *  quoted minimum is COMMAND-SPECIFIC (#352) — not a blanket 0.11.4. */
+function buildPanelTooOldError(cmd, panelVersion) {
+    const detected = panelVersion ? ` (detected ${panelVersion})` : "";
+    return new Error(`This ComfyUI-MCP panel is too old for "${cmd}"${detected} — update the ComfyUI-MCP panel ` +
+        `to ≥${minPanelVersionForCmd(cmd)} (ComfyUI Manager → update comfyui-mcp panel), then reconnect.`);
+}
 /**
  * A panel replies `{ ok: false, error: 'Unknown command "<cmd>"' }` when the
  * orchestrator dispatches a bridge command the (older) panel doesn't register —
@@ -40,9 +88,99 @@ export function makeUnknownCommandError(error, panelVersion) {
     if (!m)
         return null;
     const cmd = m[1];
-    const detected = panelVersion ? ` (detected ${panelVersion})` : "";
-    return new Error(`This ComfyUI-MCP panel is too old for "${cmd}"${detected} — update the ComfyUI-MCP panel ` +
-        `to ≥${MIN_PANEL_VERSION_FOR_BRIDGE_COMMANDS} (ComfyUI Manager → update comfyui-mcp panel), then reconnect.`);
+    // #352 FALSE-NEGATIVE GUARD: if the panel advertised a version that already
+    // meets this command's real minimum, the panel is NOT too old — an "Unknown
+    // command" reply here means something else (a genuinely retired/renamed command,
+    // or a transient), so do NOT rewrite it into a bogus "update your panel" verdict
+    // (which would also POISON the #236 unsupported-cmd gate against a capable panel).
+    // Return null so the raw error surfaces and the gate is never poisoned.
+    if (panelSupportsCmd(cmd, panelVersion))
+        return null;
+    return buildPanelTooOldError(cmd, panelVersion);
+}
+/**
+ * Bridge commands with NO side effect — safe to re-dispatch after a reconnect and
+ * safe to WAIT ON longer (a read can't be double-applied). Module-level so both
+ * the mutating-vs-read classification and the default-timeout policy share one
+ * authoritative list. Everything not listed is treated as mutating.
+ */
+export const BRIDGE_READONLY_CMDS = new Set([
+    "graph_serialize",
+    "graph_outline",
+    "graph_get_errors",
+    "graph_get_state",
+    "graph_get_subgraph",
+    "graph_view_selected",
+    "graph_view_nodes_in_viewport",
+    "graph_prompt_director_audit",
+    "graph_query",
+    "civitai_results",
+    "get_todo",
+]);
+/** Tight default reply timeout for a MUTATING command with no explicit timeout —
+ *  fail fast so the agent isn't blocked on a stuck write. */
+export const BRIDGE_DEFAULT_TIMEOUT_MS = 6000;
+/** More tolerant default for a READ (idempotent) command with no explicit timeout.
+ *  A legitimately busy-but-alive panel main thread — e.g. Preview3D parsing a large
+ *  FBX — can take many seconds to service a graph_query; failing it at the tight
+ *  6s default surfaced a FALSE "tab backgrounded or frozen" timeout even though a
+ *  retry moments later succeeded (#357). Reads have no side effect, so waiting
+ *  longer is safe; a genuinely dead/frozen tab still times out, just at this bound.
+ *  Note: a WebSocket pong is answered by the browser network stack even while JS is
+ *  blocked, so it can't distinguish busy-JS from dead-JS — a tolerant read timeout,
+ *  not pong-liveness, is the correct lever here. */
+export const BRIDGE_READ_DEFAULT_TIMEOUT_MS = 20_000;
+/** The default reply timeout to use for `cmd` when the caller passed none. Read
+ *  ops get the tolerant bound; everything else stays tight (#357). */
+export function defaultBridgeTimeoutMs(cmdName) {
+    return BRIDGE_READONLY_CMDS.has(cmdName)
+        ? BRIDGE_READ_DEFAULT_TIMEOUT_MS
+        : BRIDGE_DEFAULT_TIMEOUT_MS;
+}
+/** Normalize a WebSocket handshake `Origin` header into a canonical scheme://host:port
+ *  string, or undefined when it is absent, the opaque literal `"null"` (a sandboxed /
+ *  file:// / data: origin, which proves nothing), or unparseable. The browser sets this
+ *  header on the upgrade and forbids page JS from overriding it, so a value here is
+ *  server-trusted provenance of the page the socket runs in. Host case is lowercased and
+ *  the default port made explicit so it compares cleanly against a probe base. */
+function normalizeHandshakeOrigin(raw) {
+    const val = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof val !== "string" || val === "" || val.toLowerCase() === "null")
+        return undefined;
+    try {
+        const u = new URL(val);
+        const port = u.port || (u.protocol === "https:" ? "443" : "80");
+        return `${u.protocol}//${u.hostname.toLowerCase()}:${port}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** AUTHORITATIVE, TYPED dispatch outcome carried on a bridge command REJECTION so a
+ *  caller never has to infer it from message text:
+ *   - `false` = the command was NEVER written to the socket (a PRE-write send() failure);
+ *   - `true`  = the command WAS written and the socket then died before a reply (a
+ *     POST-write mid-command OUTCOME-UNKNOWN drop).
+ *  Absent on all other errors (a reply-timeout, a genuine refusal, "panel gone", etc.). */
+const DISPATCHED = Symbol.for("comfyui-mcp.bridge.dispatched");
+/** Tag an error with the typed {@link DISPATCHED} outcome and return it (for throw/reject). */
+export function markDispatched(err, dispatched) {
+    Object.defineProperty(err, DISPATCHED, {
+        value: dispatched,
+        enumerable: false,
+        configurable: true,
+    });
+    return err;
+}
+/** Read the typed dispatch outcome from an error, or undefined if it carries none.
+ *  A reboot readiness check uses this to classify a PRE-write send failure
+ *  (`false`) categorically as NOT-dispatched — never as an accepted/dropped reboot —
+ *  regardless of any post-write phrase its message text may quote. */
+export function dispatchOutcomeOf(err) {
+    if (err == null || (typeof err !== "object" && typeof err !== "function"))
+        return undefined;
+    const v = err[DISPATCHED];
+    return typeof v === "boolean" ? v : undefined;
 }
 /**
  * Frame `type`s that are safe to MIRROR to a tab's viewers — genuine shared-session
@@ -133,6 +271,20 @@ export class UiBridge {
     missedFrames = new Map();
     static MAX_MISSED_FRAMES = 100;
     pending = new Map();
+    /** ask_user card sends (rid → {ask_id, ts}): lets a reply that validates AFTER
+     *  the reply timer fired (dropped from `pending`) still be buffered for the
+     *  caller, instead of being discarded as a "late reply for a timed-out command"
+     *  (#486). Timestamped so an abandoned mapping (timeout/disconnect/send-failure
+     *  whose late reply never arrives) is TTL-pruned rather than kept forever. */
+    askRidToId = new Map();
+    /** Buffered late-but-valid ask_user answers (ask_id → result), drained by the
+     *  caller via takeLateAskReply(). Bounded by a short TTL — a stale unclaimed
+     *  answer is pruned rather than kept forever. */
+    lateAskReplies = new Map();
+    /** TTL for a buffered late ask answer / an unresolved rid→ask_id mapping. Long
+     *  enough to cover a slow human pick within the MCP tools/call budget, short
+     *  enough that abandoned entries don't accumulate. */
+    static LATE_ASK_TTL_MS = 5 * 60 * 1000;
     /** In-flight IDEMPOTENT reads whose socket dropped mid-command, parked per tabId
      *  waiting a bounded grace for that tab to reconnect so we can re-dispatch them
      *  (resume) instead of hard-failing. Never holds mutating commands. */
@@ -142,17 +294,10 @@ export class UiBridge {
     static RECONNECT_GRACE_MS = 4000;
     /** Bridge commands with no side effect — safe to re-dispatch after a reconnect.
      *  Everything else is treated as mutating (no auto-retry) so a render/edit is
-     *  never silently double-applied. */
-    static READONLY_CMDS = new Set([
-        "graph_serialize",
-        "graph_outline",
-        "graph_get_errors",
-        "graph_get_subgraph",
-        "graph_prompt_director_audit",
-        "graph_query",
-        "civitai_results",
-        "get_todo",
-    ]);
+     *  never silently double-applied. Single source of truth at module scope
+     *  (BRIDGE_READONLY_CMDS) so the mutating flag and the default-timeout policy
+     *  can never drift apart. */
+    static READONLY_CMDS = BRIDGE_READONLY_CMDS;
     portInUse = false;
     bindRetryTimer = null;
     heartbeatTimer = null;
@@ -332,14 +477,20 @@ export class UiBridge {
                 this.readyResolve = null;
             }
         });
-        wss.on("connection", (sock) => {
+        wss.on("connection", (sock, req) => {
             // Keepalive bookkeeping for the SERVER-LEVEL heartbeat loop, which only
             // iterates real wss.clients (relay-mediated shim connections aren't real
             // sockets bound by this server, so they're intentionally excluded — see
             // relay-client.ts / the relay README for why that's believed low-risk).
             this.missedPongs.set(sock, 0);
             sock.on("pong", () => this.missedPongs.set(sock, 0));
-            this.handleConnection(sock);
+            // SERVER-OBSERVED handshake Origin (the browser sets it and forbids page JS from
+            // overriding it) — the trusted proof of which page this socket runs in, distinct
+            // from the spoofable hello.comfyui_url (#509 self-probe gate).
+            const handshakeOrigin = normalizeHandshakeOrigin(req?.headers?.origin);
+            // Trusted-local ONLY when the primary listener is a token-less loopback bind
+            // (no LAN bind, no tunnel/secure token in front) — see handleConnection's doc.
+            this.handleConnection(sock, !this.token && isLoopbackBindHost(this.host), handshakeOrigin);
         });
     }
     /**
@@ -411,7 +562,18 @@ export class UiBridge {
             });
         });
     }
-    handleConnection(sock) {
+    /**
+     * @param local SERVER-TRUSTED provenance: true only when the socket arrived on
+     *   the token-less loopback primary listener, i.e. a browser genuinely on the
+     *   orchestrator's own host. A token-gated/tunnel-fronted primary, a relay shim,
+     *   and any LAN/pairing listener are all `false` — a browser reaching those can
+     *   sit on a DIFFERENT machine yet advertise its OWN 127.0.0.1 ComfyUI, which
+     *   must never be treated as the orchestrator's local host (#509).
+     * @param serverOrigin SERVER-OBSERVED handshake `Origin` (scheme://host:port), captured
+     *   from the WebSocket upgrade — NOT client-supplied. Undefined for non-browser/relay
+     *   connections. Bound to the tab so the reboot self-probe can trust which page it fronts.
+     */
+    handleConnection(sock, local = false, serverOrigin) {
         // The connection is anonymous until its hello frame names a tab id.
         let tabId = null;
         // A socket's KIND (canvas-owning panel vs headless viewer) is pinned on its
@@ -518,6 +680,25 @@ export class UiBridge {
                     panelVersion: typeof msg.panel_version === "string"
                         ? (msg.panel_version || undefined)
                         : existing?.panelVersion,
+                    // Fresh per hello — see the field's doc comment (#236).
+                    unsupportedCmds: new Set(),
+                    // window.location the browser was served from — the ComfyUI instance THIS
+                    // tab fronts. Preserved across a SAME-SOCKET re-hello that omits it, but
+                    // NEVER inherited by a DIFFERENT socket reusing this (possibly recurring
+                    // wf:<hash>) tab id — that could let an unrelated instance's origin certify
+                    // this tab's restart (#509, codex: cross-ownership inheritance).
+                    originUrl: typeof msg.comfyui_url === "string" &&
+                        msg.comfyui_url
+                        ? msg.comfyui_url
+                        : existing?.sock === sock
+                            ? existing?.originUrl
+                            : undefined,
+                    // SERVER-OBSERVED handshake Origin of THIS socket (from the WS upgrade, not the
+                    // hello) — bound per-socket. A same-socket re-hello keeps it; a DIFFERENT socket
+                    // taking over the id carries its OWN handshake Origin (never inherits the old).
+                    serverOrigin: existing?.sock === sock ? (serverOrigin ?? existing?.serverOrigin) : serverOrigin,
+                    // Server-trusted provenance of THIS socket (not client-controlled).
+                    local,
                 });
                 if (incomingHeadless)
                     this.headlessSeen.add(tabId);
@@ -560,10 +741,24 @@ export class UiBridge {
             const rid = typeof msg.rid === "string" ? msg.rid : undefined;
             if (rid) {
                 const p = this.pending.get(rid);
-                if (!p)
-                    return; // late reply for a timed-out command
+                if (!p) {
+                    // Late reply for a timed-out command. If it was an ask_user card whose
+                    // caller may still be within the MCP tools/call budget, BUFFER the
+                    // validated answer keyed by its ask_id so the caller can retrieve it via
+                    // takeLateAskReply() instead of losing it (#486). Everything else drops.
+                    const entry = this.askRidToId.get(rid);
+                    if (entry) {
+                        this.askRidToId.delete(rid);
+                        if (msg.ok) {
+                            this.pruneLateAsk();
+                            this.lateAskReplies.set(entry.askId, { result: msg.result, ts: Date.now() });
+                        }
+                    }
+                    return;
+                }
                 clearTimeout(p.timer);
                 this.pending.delete(rid);
+                this.askRidToId.delete(rid);
                 if (msg.ok) {
                     p.resolve(msg.result);
                 }
@@ -726,6 +921,48 @@ export class UiBridge {
     resolveActiveTabId() {
         return this.resolveTarget().tabId;
     }
+    /** The ComfyUI origin the given tab's browser was served from (`comfyui_url` in
+     *  its `hello`), or undefined if the tab never advertised one / is unknown. Lets a
+     *  tool HTTP-probe the EXACT instance THIS tab fronts rather than the process-
+     *  global target a different instance may have retargeted (#509). Resolves the id
+     *  through the SAME prefix + migration-alias path as command routing (resolveTarget)
+     *  so a migrated session still finds its origin; never throws. */
+    tabOrigin(tabId) {
+        try {
+            return this.resolveTarget(tabId).originUrl;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** SERVER-OBSERVED origin (scheme://host:port) of the given tab's WebSocket handshake —
+     *  the page the browser was actually serving when it opened this socket. Unlike
+     *  {@link tabOrigin} (client-supplied `hello.comfyui_url`, spoofable), the browser sets
+     *  the handshake `Origin` and blocks page JS from forging it, so this is the TRUSTED
+     *  proof of which ComfyUI a real tab fronts — the origin the reboot self-probe binds to
+     *  (#509). Undefined when the handshake carried no usable Origin. Resolves migration
+     *  aliases like tabOrigin; never throws. */
+    tabServerOrigin(tabId) {
+        try {
+            return this.resolveTarget(tabId).serverOrigin;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** SERVER-TRUSTED: true only when this tab's socket arrived on the token-less
+     *  loopback primary listener (a browser on the orchestrator's OWN host), so its
+     *  advertised loopback ComfyUI origin really is the orchestrator's local host and
+     *  may be directly health-probed (#509). Relay/tunnel/LAN/pairing tabs → false.
+     *  Resolves migration aliases like tabOrigin; unknown → false. */
+    tabIsLocal(tabId) {
+        try {
+            return this.resolveTarget(tabId).local === true;
+        }
+        catch {
+            return false;
+        }
+    }
     /** True when the tab advertised itself as a canvas-less (mobile/remote) client
      *  in its `hello`. Unknown tabs → false. */
     isHeadless(tabId) {
@@ -734,6 +971,45 @@ export class UiBridge {
         // bytes-less viewRef) and is renderable when the mailbox flushes to the phone.
         return this.conns.get(tabId)?.headless === true || this.headlessSeen.has(tabId);
     }
+    /** Drop expired late-ask entries (buffered answers + unresolved rid mappings) so
+     *  an abandoned card never leaks memory. Cheap; called on each ask send/take. */
+    pruneLateAsk() {
+        const now = Date.now();
+        for (const [id, e] of this.lateAskReplies) {
+            if (now - e.ts > UiBridge.LATE_ASK_TTL_MS)
+                this.lateAskReplies.delete(id);
+        }
+        // TTL-prune abandoned rid→ask_id mappings (a card that timed out / dropped and
+        // whose late reply never came), so they don't linger past the window a caller
+        // could still claim them.
+        for (const [rid, e] of this.askRidToId) {
+            if (now - e.ts > UiBridge.LATE_ASK_TTL_MS)
+                this.askRidToId.delete(rid);
+        }
+        // Belt-and-suspenders cardinality cap in case of a burst of asks within one TTL
+        // window — drop the oldest-inserted mappings so the map can never grow unbounded.
+        if (this.askRidToId.size > 256) {
+            const excess = this.askRidToId.size - 256;
+            let i = 0;
+            for (const rid of this.askRidToId.keys()) {
+                if (i++ >= excess)
+                    break;
+                this.askRidToId.delete(rid);
+            }
+        }
+    }
+    /** Retrieve (and remove) a late-but-valid ask_user answer buffered for `askId`
+     *  after the card-reply timeout, or undefined if none arrived. The panel_ask
+     *  handler polls this for a bounded grace so a slow-but-valid pick is honored
+     *  rather than discarded (#486). */
+    takeLateAskReply(askId) {
+        this.pruneLateAsk();
+        const e = this.lateAskReplies.get(askId);
+        if (!e)
+            return undefined;
+        this.lateAskReplies.delete(askId);
+        return e.result;
+    }
     /** All currently connected tabs, most recent hello last. */
     tabs() {
         return Array.from(this.conns.values()).map((c) => ({
@@ -837,7 +1113,10 @@ export class UiBridge {
         }
     }
     send(cmd, opts = {}) {
-        const timeoutMs = opts.timeoutMs ?? 6000;
+        // #357: read (idempotent) ops get a more tolerant default so a busy-but-alive
+        // panel main thread (e.g. Preview3D loading a large FBX) isn't declared frozen;
+        // mutating ops keep the tight default. An explicit opts.timeoutMs always wins.
+        const timeoutMs = opts.timeoutMs ?? defaultBridgeTimeoutMs(cmd.cmd);
         let conn;
         try {
             conn = this.resolveTarget(opts.tabId);
@@ -851,6 +1130,15 @@ export class UiBridge {
             }
             return Promise.reject(err instanceof Error ? err : new Error(String(err)));
         }
+        // #236 — proactively gate a command this exact connection has already proven
+        // unsupported (see Conn.unsupportedCmds), instead of dispatching it again just
+        // to have the panel reject it and re-parse the same "Unknown command" string.
+        // Never a false gate: membership here is only ever set from a REAL rejection
+        // on THIS connection (in dispatch()'s rejectMapped below), never inferred from
+        // panelVersion alone.
+        if (conn.unsupportedCmds.has(cmd.cmd)) {
+            return Promise.reject(buildPanelTooOldError(cmd.cmd, conn.panelVersion));
+        }
         if (conn.sock.readyState !== WebSocket.OPEN) {
             if (opts.tabId && UiBridge.isMailboxable(cmd)) {
                 this.storeMailbox(opts.tabId, cmd);
@@ -889,17 +1177,38 @@ export class UiBridge {
         }
         const replyTimeoutMs = Math.min(ctx.timeoutMs, remaining);
         const rid = randomUUID();
+        // Track an ask_user card's stable ask_id against this attempt's rid so a reply
+        // that validates AFTER the reply timer fires (and drops out of `pending`) can
+        // still be buffered for the caller by rid, not discarded (#486 late answer).
+        const askId = cmd.ask_id;
+        if (typeof askId === "string" && askId) {
+            this.pruneLateAsk();
+            this.askRidToId.set(rid, { askId, ts: Date.now() });
+        }
         // Rewrite an old-panel "Unknown command" rejection into an actionable
         // update-your-panel message (see makeUnknownCommandError). Applied to the
         // reply-error path only; the happy path and genuine command errors are
         // passed through untouched.
         const rejectMapped = (err) => {
             const friendly = makeUnknownCommandError(err.message, conn.panelVersion);
+            if (friendly) {
+                // Learned, not assumed (#236) — this exact connection just proved it
+                // doesn't support cmd.cmd, so every later call in this session is gated
+                // proactively (see the `send()` preflight above) instead of round-
+                // tripping to the panel again.
+                conn.unsupportedCmds.add(cmd.cmd);
+            }
             ctx.reject(friendly ?? err);
         };
         const timer = setTimeout(() => {
             this.pending.delete(rid);
-            ctx.reject(new Error(`Panel tab ${conn.tabId.slice(0, 8)} did not reply to "${cmd.cmd}" within ${ctx.timeoutMs} ms — the ComfyUI tab may be backgrounded or frozen`));
+            // This timer only fires AFTER sock.send() below returned successfully — the command
+            // WAS WRITTEN to the socket; the tab (possibly backgrounded/frozen) merely didn't
+            // reply in time and may still apply it. So this is a POST-write outcome: tag it
+            // dispatched:true so a mutating caller (e.g. comfy_reboot readiness) treats it as an
+            // accepted-but-unacked dispatch and verifies by observation, rather than mistaking a
+            // genuinely-sent command for one that never went out (#509).
+            ctx.reject(markDispatched(new Error(`Panel tab ${conn.tabId.slice(0, 8)} did not reply to "${cmd.cmd}" within ${ctx.timeoutMs} ms — the ComfyUI tab may be backgrounded or frozen`), true));
         }, replyTimeoutMs);
         const pending = {
             resolve: ctx.resolve,
@@ -916,7 +1225,15 @@ export class UiBridge {
         catch (err) {
             clearTimeout(timer);
             this.pending.delete(rid);
-            ctx.reject(err instanceof Error ? err : new Error(String(err)));
+            // The write to the socket FAILED — the command was NEVER transmitted, so nothing
+            // was dispatched (distinct from a POST-write mid-command drop). Surface that
+            // explicitly so callers don't mistake it for an in-flight/accepted command (a
+            // reboot readiness check must NOT treat a pre-write send failure as a fired reboot).
+            // Carry an AUTHORITATIVE TYPED flag `dispatched:false` so a caller classifies this
+            // categorically — never by string-matching a detail that might quote a post-write
+            // phrase ("OUTCOME UNKNOWN") from the underlying socket error.
+            const detail = err instanceof Error ? err.message : String(err);
+            ctx.reject(markDispatched(new Error(`failed to send "${cmd.cmd}" to panel tab ${conn.tabId.slice(0, 8)} — the command was NOT dispatched (${detail})`), false));
         }
     }
     /** A pending command's socket died before its reply arrived. Decide, WITHOUT
@@ -958,7 +1275,7 @@ export class UiBridge {
         // bare failure invites a blind retry that double-applies the action (e.g. a
         // second render). Say the outcome is UNKNOWN so the caller verifies first.
         if (ctx.mutating) {
-            ctx.reject(new Error(`panel tab ${short} disconnected mid-command ("${cmd}") — OUTCOME UNKNOWN: the command was already sent, so the panel may have applied it (for a run, ComfyUI may already be rendering). Verify before retrying (e.g. check get_queue / list_output_images) instead of re-issuing it blindly.`));
+            ctx.reject(markDispatched(new Error(`panel tab ${short} disconnected mid-command ("${cmd}") — OUTCOME UNKNOWN: the command was already sent, so the panel may have applied it (for a run, ComfyUI may already be rendering). Verify before retrying (e.g. check get_queue / list_output_images) instead of re-issuing it blindly.`), true));
         }
         else {
             ctx.reject(new Error(`panel tab ${short} disconnected mid-command ("${cmd}") — panel genuinely gone; retry once a tab is connected`));