comfyui-mcp 0.48.24 → 0.48.25

package/dist/orchestrator/panel-tools.js

@@ -193,6 +193,10 @@ export const __panelToolsTestHooks = {
     setRetrySettleMs(ms) {
         retrySettleMsOverride = ms;
     },
+    /** Inject fast reconnect-wait timing so #400/#402 tests don't wait the real ~20s. */
+    setReconnectWaitTiming(timing) {
+        reconnectWaitTimingOverride = timing;
+    },
     isRetrySafeCmd,
     isTransientReconnectError,
     // #384 live-canvas capture fallback (defined later in the module).
@@ -257,6 +261,23 @@ function retrySettleMs() {
         return retrySettleMsOverride;
     return Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_RETRY_SETTLE_S", 0.4) * 1000);
 }
+let reconnectWaitTimingOverride = null;
+/** Bounded wait for a browser tab to (re)connect after a full ComfyUI restart or a
+ *  soft-reload — the "Connected: none" window in which every panel_* call fires into
+ *  a dead binding (#400) or a mutating open/save returns OUTCOME UNKNOWN (#402). The
+ *  browser reconnects its own socket seconds-to-tens-of-seconds after ComfyUI comes
+ *  back, so the existing single ~400ms retry always loses the race. Test-overridable. */
+/** Hard ceiling on the reconnect wait so an oversized env value can never make a
+ *  tool block near/over the outer MCP tools/call deadline (~300s). */
+const RECONNECT_WAIT_MAX_MS = 60_000;
+function reconnectWaitTiming() {
+    if (reconnectWaitTimingOverride)
+        return reconnectWaitTimingOverride;
+    return {
+        budgetMs: Math.min(RECONNECT_WAIT_MAX_MS, Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_RECONNECT_WAIT_S", 20) * 1000)),
+        intervalMs: Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_RECONNECT_POLL_S", 0.5) * 1000),
+    };
+}
 /** True when a decoded /system_stats body has the recognizable ComfyUI shape (a
  *  `system` object and/or a `devices` array) — the same fields health_check /
  *  get_environment read. A bare 2xx from a reverse-proxy login page, an SPA
@@ -852,11 +873,31 @@ async function waitForWorkflowActive(ctx, path, timing) {
  * the target became active despite the slow ack, otherwise the original timeout
  * failure. Never masks a genuine open-failure as success.
  */
+/** Terminal error for a MUTATING panel command when the pre-send reachability wait
+ *  gave up (no tab reconnected within budget / an ambiguous multi-tab session). We
+ *  must NOT dispatch — firing into a dead binding is exactly the OUTCOME-UNKNOWN /
+ *  double-apply risk the pre-send wait exists to prevent (codex). */
+function noReachableTabFail(cmd) {
+    return fail(`${cmd} — this session has no reachable panel tab yet (still reconnecting after a ` +
+        `restart/reload, or multiple tabs are open and none is this session's). Nothing was ` +
+        `sent. Retry in a moment, or rebind with panel_set_workflow_target({mode:"current"}).`);
+}
 async function openWorkflowWithVerify(path, ctx) {
+    // #402: after a full ComfyUI restart the browser tab re-registers a few seconds
+    // later. Awaiting a stable binding BEFORE dispatching a mutating workflow_open
+    // (nothing is sent yet — no double-apply risk) means the command reaches a live
+    // tab instead of firing into the "Connected: none" window and coming back
+    // OUTCOME UNKNOWN. A healthy session returns from this instantly; if no tab
+    // reconnects within budget we REFUSE rather than dispatch into a dead binding.
+    if (ctx.awaitReachable && !(await ctx.awaitReachable())) {
+        return noReachableTabFail("workflow_open");
+    }
     const res = await ctx.call({ cmd: "workflow_open", path }, 15000);
     // Success, or a genuine acked error (missing file / real executor error) — the
-    // caller must see it as-is. Only a slow-ack TIMEOUT warrants verification.
-    if (!isAckTimeout(res))
+    // caller must see it as-is. A slow-ack TIMEOUT or a mid-command reconnect DROP
+    // ("OUTCOME UNKNOWN", #402) both warrant verification: re-reading the active
+    // workflow is idempotent, so we can turn an UNKNOWN into a definite outcome.
+    if (!isAckTimeout(res) && !isReconnectDrop(res))
         return res;
     const timing = getOpenVerifyTiming();
     const verify = await waitForWorkflowActive(ctx, path, timing);
@@ -865,15 +906,30 @@ async function openWorkflowWithVerify(path, ctx) {
             opened: { path },
             recovered: true,
             note: `"${path}" is now the active workflow — the switch succeeded, but the tab was slow ` +
-                `to acknowledge (backgrounded/frozen or already open), so the initial ack timed out. ` +
+                `to acknowledge (backgrounded/frozen or already open) or briefly disconnected while ` +
+                `reconnecting after a restart, so the initial ack was inconclusive. ` +
                 `Confirmed active via workflow_list after ${(verify.waited_ms / 1000).toFixed(1)}s ` +
                 `(${verify.attempts} probe${verify.attempts === 1 ? "" : "s"}). Do NOT retry.`,
         });
     }
-    // The ack timed out AND the target never became active within the budget — this
-    // is a REAL failure. Return the original bridge timeout error unchanged.
+    // The ack was inconclusive AND the target never became active within the budget —
+    // this is a REAL failure. Return the original bridge error unchanged.
     return res;
 }
+/** True when a ToolResult is a MID-COMMAND reconnect drop ("disconnected
+ *  mid-command … OUTCOME UNKNOWN") — the command was written but the tab dropped
+ *  before a reply while reconnecting after a restart/reload (#402). Re-verifying an
+ *  idempotent workflow-state change is safe on this signal. */
+function isReconnectDrop(res) {
+    if (!res?.isError)
+        return false;
+    const text = res?.content?.find((c) => c.type === "text")?.text ?? "";
+    // A pre-write "NOT dispatched" send failure must NOT verify (nothing happened) —
+    // let it surface as-is; only a POST-write mid-command drop is re-verifiable.
+    if (/NOT dispatched/i.test(text))
+        return false;
+    return /disconnected mid-command|OUTCOME UNKNOWN/i.test(text);
+}
 /**
  * Resolve a caller-supplied pin `path` (path / filename / key, any form) to the
  * AUTHORITATIVE open-workflow record from a fresh `workflow_list` — the single
@@ -1327,18 +1383,38 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
     //    mode already means.
     // It routes through makePanelToolCtx only — bridge.resolveTarget itself is
     // untouched, so the dead-alias security invariant (ui-bridge.test.ts:459) holds.
+    // The tab ids ELIGIBLE to host a graph/workflow session: connected AND canvas-owning.
+    // A headless client (mobile mirror / remote / exec viewer — ui-bridge Conn.headless)
+    // is canvas-less and can never run graph tools, so it must never be a rebind target
+    // (codex). Returns null when the bridge can't enumerate tabs/headlessness (older or
+    // lightweight ctx) — callers then fall back to bridge.resolveActiveTabId (legacy).
+    const isHeadlessTab = (id) => typeof bridge.isHeadless === "function" && bridge.isHeadless(id);
+    const interactiveTabIds = () => {
+        if (typeof bridge.tabs !== "function")
+            return null;
+        const live = bridge.tabs();
+        if (!Array.isArray(live))
+            return null;
+        return live.filter((t) => !isHeadlessTab(t.tab_id)).map((t) => t.tab_id);
+    };
     const ensureReachable = () => {
         if (typeof bridge.canReach !== "function")
             return; // lightweight test ctx
         if (bridge.canReach(ctx.tabId))
-            return;
+            return; // healthy binding — leave untouched
         if (workflowTargets?.get(ctx.tabId)?.mode === "pinned")
             return; // stay strict
         // Strict-single: never silently pick among multiple live tabs (would risk the
-        // real bridge's last-active fallback routing to an unrelated workflow). When
-        // the bridge can enumerate its tabs and there is more than one, do NOT rebind.
-        if (typeof bridge.tabs === "function") {
-            const live = bridge.tabs();
+        // real bridge's last-active fallback routing to an unrelated workflow). Count only
+        // INTERACTIVE tabs — a lone canvas tab alongside headless viewers still binds, and
+        // a headless-only state is treated as "nothing bindable" (rebindToActiveTab throws).
+        const eligible = interactiveTabIds();
+        if (eligible) {
+            if (eligible.length > 1)
+                return; // 2+ INTERACTIVE tabs → strict, don't guess
+        }
+        else if (typeof bridge.tabs === "function") {
+            const live = bridge.tabs(); // legacy path (no headless info)
             if (Array.isArray(live) && live.length > 1)
                 return;
         }
@@ -1346,10 +1422,58 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
             rebindToActiveTab();
         }
         catch {
-            // Ambiguous (2+ tabs) or nothing connected — leave tabId as-is and let the
+            // Ambiguous (2+ tabs) or nothing bindable — leave tabId as-is and let the
             // command surface the bridge's own clear, tab-listing error.
         }
     };
+    // Bounded pre-send wait for a tab to (re)connect after a restart/reload — see
+    // PanelToolCtx.awaitReachable. Complements ensureReachable (which acts INSTANTLY
+    // on an already-present sole tab): this waits out the "Connected: none" window a
+    // fresh ComfyUI restart opens, in which the browser's own socket hasn't re-hello'd
+    // yet. Conservative by construction: returns at once for a healthy session, and
+    // only waits while ZERO tabs are connected (a 1+/multi-tab case is left untouched
+    // for the existing strict-single ensureReachable to resolve or refuse).
+    const awaitReachable = async (budgetMs) => {
+        if (typeof bridge.canReach !== "function")
+            return true; // lightweight test ctx
+        if (bridge.canReach(ctx.tabId))
+            return true; // healthy binding
+        // We can only meaningfully WAIT for a reconnect when the bridge can enumerate its
+        // live tabs. Without that (older/lightweight bridge), never loop — do a single
+        // synchronous heal and report reachability, exactly as before this primitive.
+        if (typeof bridge.tabs !== "function") {
+            ensureReachable();
+            return bridge.canReach(ctx.tabId);
+        }
+        const timing = reconnectWaitTiming();
+        // The configured reconnect budget is the intended MAX; an explicit budgetMs (e.g.
+        // a caller's remaining deadline) only ever TIGHTENS it — never extends the wait.
+        const budget = Math.max(0, budgetMs != null ? Math.min(budgetMs, timing.budgetMs) : timing.budgetMs);
+        const intervalMs = Math.max(1, timing.intervalMs);
+        const deadline = Date.now() + budget;
+        for (;;) {
+            // Only an INTERACTIVE (canvas-owning) tab is a valid graph/workflow binding — a
+            // headless viewer is canvas-less, so awaiting/rebinding onto one and reporting
+            // "ready" would route open/save at a client with no canvas (codex).
+            const interactive = interactiveTabIds() ?? [];
+            if (interactive.length > 0) {
+                // A canvas tab is present → the reconnect window is OVER. Try the strict-single
+                // synchronous heal (binds a sole reconnected tab). Then return IMMEDIATELY,
+                // bound or not: if we still can't reach ctx.tabId (2+ interactive tabs, or a
+                // pinned stale target ensureReachable leaves strict), waiting longer can't help —
+                // report now so open/save refuse promptly and panel_set_workflow_target proceeds
+                // to its explicit last-active rebind instead of stalling the whole budget (codex).
+                ensureReachable();
+                return bridge.canReach(ctx.tabId);
+            }
+            // ZERO interactive tabs — the genuine "Connected: none" post-restart window (a lone
+            // headless viewer counts as none). Keep waiting for a canvas tab to re-register.
+            const left = deadline - Date.now();
+            if (left <= 0)
+                return bridge.canReach(ctx.tabId);
+            await sleep(Math.min(intervalMs, left));
+        }
+    };
     const sendRouted = async (cmd, timeoutMs) => {
         const target = workflowTargets?.get(ctx.tabId);
         const routed = target ? withWorkflowTarget(cmd, target) : cmd;
@@ -1449,9 +1573,31 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
     // active tab can't be picked.
     const rebindToActiveTab = () => {
         const previous = ctx.tabId;
+        // A healthy binding is left untouched (never disturb a live session). Recovery only
+        // fires for an orphaned/stale tab id.
         if (bridge.canReach(previous))
             return { previous, current: previous, rebound: false };
-        const current = bridge.resolveActiveTabId(); // throws if no single active tab
+        // Pick the target tab EXCLUDING headless (canvas-less) viewers, which can't host a
+        // graph session (codex). Prefer the sole interactive tab; with 2+ interactive tabs
+        // fall back to the bridge's last-active resolution (the explicit-rebind "use what's
+        // live now" consent); with none, throw. A resolution that still lands on a headless
+        // tab is rejected as "nothing bindable" so no graph session is ever bound canvas-less.
+        const eligible = interactiveTabIds();
+        let current;
+        if (eligible) {
+            if (eligible.length === 1)
+                current = eligible[0];
+            else if (eligible.length === 0)
+                throw new Error("Panel not reachable: no panel connected");
+            else
+                current = bridge.resolveActiveTabId(); // 2+ interactive → last-active (or throws)
+        }
+        else {
+            current = bridge.resolveActiveTabId(); // legacy bridge (no headless info)
+        }
+        if (typeof bridge.isHeadless === "function" && bridge.isHeadless(current)) {
+            throw new Error("Panel not reachable: no panel connected");
+        }
         // Carry a pinned workflow target across to the new tab id so a pinned
         // session keeps its pin after self-healing.
         const pinned = workflowTargets?.get(previous);
@@ -1466,6 +1612,7 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
     ctx.confirm = confirm;
     ctx.rebindToActiveTab = rebindToActiveTab;
     ctx.ensureReachable = ensureReachable;
+    ctx.awaitReachable = awaitReachable;
     return ctx;
 }
 /**
@@ -2144,7 +2291,7 @@ export function buildPanelToolDefs() {
             node_id: z.number().int().describe("Node id whose input to disconnect."),
             input: slotRef.optional().describe("Input slot name or index (default 0)."),
         }, async (args, ctx) => ctx.call({ cmd: "graph_disconnect", node_id: args.node_id, input: args.input })),
-        def("panel_set_widget", "Set a widget value on a node in the user's open graph (steps, cfg, seed, ckpt_name, text prompts, …). Returns the previous and new value. Undoable with Ctrl+Z. To CLEAR a text widget to an empty string, pass `clear: true` (some MCP clients drop an empty-string `value` from the serialized payload, so `value: \"\"` may not arrive — `clear: true` always works).", {
+        def("panel_set_widget", "Set a widget value on a node in the user's open graph (steps, cfg, seed, ckpt_name, text prompts, …). Returns the previous and new value. Undoable with Ctrl+Z. To CLEAR a text widget to an empty string, pass `clear: true` (some MCP clients drop an empty-string `value` from the serialized payload, so `value: \"\"` may not arrive — `clear: true` always works). For the LTXDirector timeline node (WhatDreamsCost CSGlide), set `timeline_data` with the FULL timeline JSON (segments + global_prompt) to drive its custom timeline UI — this re-syncs the editor and regenerates its derived `local_prompts`/`segment_lengths`/`guide_strength` widgets; setting those derived widgets directly is refused (they are silently reverted).", {
             node_id: z.number().int().describe("Node id from panel_graph_outline / panel_query_graph."),
             widget: z.string().describe("Widget name (e.g. 'steps', 'cfg', 'text')."),
             value: z
@@ -2169,6 +2316,14 @@ export function buildPanelToolDefs() {
             node_id: z.number().int().describe("Node id from panel_graph_outline / panel_query_graph."),
             pos: xy().describe("New canvas [x, y] (two numbers)."),
         }, async (args, ctx) => ctx.call({ cmd: "graph_move_node", node_id: args.node_id, pos: args.pos })),
+        def("panel_resize_node", "Resize a node to [width, height] (canvas px) on the user's open graph. Essential for Note / MarkdownNote nodes, which are created tiny (140×60) and are unreadable until enlarged — panel_move_node only repositions, it cannot resize. Uses the node's own setSize so DOM-widget nodes (MarkdownNote) and nodes that clamp to a computed minimum reflow correctly. Undoable with Ctrl+Z.", {
+            node_id: z.number().int().describe("Node id from panel_graph_outline / panel_query_graph."),
+            size: z
+                .array(z.number())
+                .min(2)
+                .max(2)
+                .describe("New [width, height] in canvas px (both > 0)."),
+        }, async (args, ctx) => ctx.call({ cmd: "graph_resize_node", node_id: args.node_id, size: args.size })),
         def("panel_auto_layout", "Automatically arrange the user's open graph (or a subset of nodes) into a clean left-to-right / top-to-bottom / grid layout based on the real link topology. Group boxes move with their members and are re-fit. Use dry_run:true to preview proposed positions without touching the canvas. Undoable (one Ctrl+Z).", {
             node_ids: z
                 .array(z.number().int())
@@ -2211,7 +2366,7 @@ export function buildPanelToolDefs() {
             dy: args.dy,
             scale: args.scale,
         })),
-        def("panel_run", "Queue the workflow the user has OPEN — exactly like them pressing Queue Prompt (current widget values, the live graph they can see). On success it confirms the run was queued; if ComfyUI REFUSES the prompt (validation failure on either channel — per-node node_errors OR a top-level error like a missing node type) it returns a FAILURE with that rejection detail, never a false 'queued'. Pass to_node_id to RUN ONLY ONE BRANCH ('run to node'): ComfyUI renders just that output node plus everything upstream of it and SKIPS every other output branch — handy for previewing or debugging part of a big graph without rendering the whole thing. to_node_id MUST be an OUTPUT node (SaveImage, PreviewImage, SaveVideo, …) — pick the one at the END of the branch you want; nodes are tagged is_output:true in panel_query_graph's detail rows. Omit it to run the whole graph. Use this so the render runs on THEIR canvas and they see the result.", {
+        def("panel_run", "Queue the workflow the user has OPEN — exactly like them pressing Queue Prompt (current widget values, the live graph they can see). On success it confirms the run was queued; if ComfyUI REFUSES the prompt (validation failure on either channel — per-node node_errors OR a top-level error like a missing node type) it returns a FAILURE with that rejection detail, never a false 'queued'. Pass to_node_id to RUN ONLY ONE BRANCH ('run to node'): ComfyUI renders just that output node plus everything upstream of it and SKIPS every other output branch — handy for previewing or debugging part of a big graph without rendering the whole thing. to_node_id MUST be an OUTPUT node (SaveImage, PreviewImage, SaveVideo, …) — pick the one at the END of the branch you want; nodes are tagged is_output:true in panel_query_graph's detail rows. The output node may be NESTED inside a subgraph — just pass its id (resolved in the scope you're currently viewing, then anywhere in the workflow); the tool builds the nested execution path for you. Omit it to run the whole graph. Use this so the render runs on THEIR canvas and they see the result.", {
             batch_count: z
                 .number()
                 .int()
@@ -2223,7 +2378,7 @@ export function buildPanelToolDefs() {
                 .number()
                 .int()
                 .optional()
-                .describe("Output node id to render UP TO (partial execution). Omit to run the whole graph. Must be an OUTPUT node — one with is_output:true in panel_query_graph's detail rows."),
+                .describe("Output node id to render UP TO (partial execution). Omit to run the whole graph. Must be an OUTPUT node — one with is_output:true in panel_query_graph's detail rows. May be nested inside a subgraph (pass the node's own id)."),
         }, async (args, ctx) => {
             // BACKPRESSURE: the agent can't see ComfyUI's queue, so re-queuing while a
             // render is already running silently stacks behind it (this is how a stuck
@@ -2306,7 +2461,14 @@ export function buildPanelToolDefs() {
                 // documented "ambiguous multi-tab surfaces a clear error" promise (codex).
                 const orphaned = typeof ctx.bridge.canReach === "function" && !ctx.bridge.canReach(ctx.tabId);
                 const live = typeof ctx.bridge.tabs === "function" ? ctx.bridge.tabs() : undefined;
-                if (orphaned && Array.isArray(live) && live.length > 1) {
+                // Count only INTERACTIVE (canvas-owning) tabs for the ambiguity guard: one
+                // desktop canvas alongside headless viewers is NOT ambiguous — rebindToActiveTab
+                // binds the sole desktop tab. Only 2+ real canvas tabs are unpickable here.
+                const headless = ctx.bridge.isHeadless;
+                const interactive = Array.isArray(live) && typeof headless === "function"
+                    ? live.filter((t) => !headless(t.tab_id))
+                    : live;
+                if (orphaned && Array.isArray(interactive) && interactive.length > 1) {
                     return fail("This session's ComfyUI tab was replaced and multiple tabs are now open — " +
                         "can't safely pick one. Switch to the tab you want, then call " +
                         'panel_set_workflow_target({mode:"current"}) before panel_reload.');
@@ -2704,9 +2866,20 @@ export function buildPanelToolDefs() {
                 multi_select: args.multi_select,
             });
         }),
-        def("panel_save_workflow", "Save the user's open workflow PROGRAMMATICALLY — no Save/Rename dialog ever pops. With no `name`: saves in place (or auto-names + persists a never-saved workflow). With `name`: if the workflow is ALREADY saved under a different name this is a SAVE-AS — it writes a NEW file and leaves the original untouched on disk (it NEVER renames/moves/destroys the original); for a never-saved workflow it is simply the first save. The result reports what happened: `saved_as`+`copied_from`+`original_on_disk` (a disk-verified check that the original file still exists) for a Save-As copy, or `first_save` for a brand-new workflow. Use this freely (e.g. after building a graph) — it won't interrupt the user.", { name: z.string().optional().describe("Name for the workflow (no .json needed). If the workflow is already saved under a different name, this writes a NEW file (Save-As COPY) and leaves the original in place — it never renames/moves/destroys it. Omit to save in place / auto-name an unsaved workflow.") }, async (args, ctx) => args.name
-            ? ctx.call({ cmd: "workflow_save_as", name: args.name }, 15000)
-            : ctx.call({ cmd: "workflow_save" }, 15000)),
+        def("panel_save_workflow", "Save the user's open workflow PROGRAMMATICALLY — no Save/Rename dialog ever pops. With no `name`: saves in place (or auto-names + persists a never-saved workflow). With `name`: if the workflow is ALREADY saved under a different name this is a SAVE-AS — it writes a NEW file and leaves the original untouched on disk (it NEVER renames/moves/destroys the original); for a never-saved workflow it is simply the first save. The result reports what happened: `saved_as`+`copied_from`+`original_on_disk` (a disk-verified check that the original file still exists) for a Save-As copy, or `first_save` for a brand-new workflow. Use this freely (e.g. after building a graph) — it won't interrupt the user.", { name: z.string().optional().describe("Name for the workflow (no .json needed). If the workflow is already saved under a different name, this writes a NEW file (Save-As COPY) and leaves the original in place — it never renames/moves/destroys it. Omit to save in place / auto-name an unsaved workflow.") }, async (args, ctx) => {
+            // #402: await a stable tab binding before dispatching the (mutating) save, so
+            // a save issued in the post-restart "Connected: none" window reaches a live
+            // tab instead of failing with a bare "Failed to fetch"/OUTCOME UNKNOWN. Pre-
+            // send only (nothing dispatched yet) → no risk of writing the file twice; and
+            // if no tab reconnects within budget we REFUSE rather than fire into a dead
+            // binding.
+            if (ctx.awaitReachable && !(await ctx.awaitReachable())) {
+                return noReachableTabFail(args.name ? "workflow_save_as" : "workflow_save");
+            }
+            return args.name
+                ? ctx.call({ cmd: "workflow_save_as", name: args.name }, 15000)
+                : ctx.call({ cmd: "workflow_save" }, 15000);
+        }),
         def("panel_list_workflows", "List the user's OPEN workflow tabs and which one is active (path, filename, modified, persisted). Use this to know what's open before switching/renaming/closing. Read-only.", {}, async (_args, ctx) => ctx.call({ cmd: "workflow_list" })),
         def("panel_get_workflow_target", "Read which workflow this agent is bound to edit. mode 'current' means graph tools follow whatever tab the user is viewing; mode 'pinned' means edits are bound to the pinned workflow (which was the active canvas at pin time) — if the user later switches to another tab, your next graph call FAILS LOUDLY rather than silently editing the wrong graph. Call this when unsure which workflow your panel_* edits will affect.", {}, async (_args, ctx) => {
             const target = ctx.workflowTarget?.get(ctx.tabId) ?? { mode: "current" };
@@ -2737,15 +2910,55 @@ export function buildPanelToolDefs() {
             // pin store, so subsequent panel_* calls route to the live tab. Surfaces a
             // clear error if a single active tab can't be determined.
             let rebindNote = "";
+            let deferredBind = false;
             if (mode === "current" && ctx.rebindToActiveTab) {
+                const before = ctx.tabId;
+                // Give an in-flight reconnect (a ComfyUI restart / panel reload still
+                // settling) a brief chance to bind immediately, since this IS the recovery
+                // signal the agent reaches for in exactly that window (#474). awaitReachable
+                // rebinds via ensureReachable when a tab is (re)connected.
+                if (ctx.awaitReachable)
+                    await ctx.awaitReachable();
                 try {
-                    const { previous, current, rebound } = ctx.rebindToActiveTab();
-                    if (rebound) {
-                        rebindNote = ` Rebound this session from tab ${previous.slice(0, 8)} onto the active tab ${current.slice(0, 8)}.`;
-                    }
+                    ctx.rebindToActiveTab(); // completes the rebind if awaitReachable didn't
                 }
                 catch (err) {
-                    return fail(err);
+                    // #474: with 2+ live tabs the rebind is AMBIGUOUS — fail so the user picks.
+                    // But with ZERO tabs connected (the "Connected: none" window right after a
+                    // restart/reload where the old tmp: tab is gone) the recovery call must NOT
+                    // hard-fail: clear the stale binding and record the current-mode intent so
+                    // the session binds onto the tab the moment one reconnects, instead of
+                    // stranding the agent with no way to recover.
+                    const live = typeof ctx.bridge.tabs === "function" ? ctx.bridge.tabs() : undefined;
+                    let noTabsConnected;
+                    if (Array.isArray(live)) {
+                        // Count only INTERACTIVE (canvas-owning) tabs: a headless-only reconnect is
+                        // NOT a usable graph binding, so it defers (binds once a real canvas tab
+                        // connects) rather than failing as if a tab were pickable.
+                        const headless = ctx.bridge.isHeadless;
+                        const interactive = typeof headless === "function" ? live.filter((t) => !headless(t.tab_id)) : live;
+                        noTabsConnected = interactive.length === 0;
+                    }
+                    else {
+                        // No tab enumeration — classify by the resolve error: only "nothing
+                        // connected" defers; an AMBIGUOUS multi-tab error must still fail so the
+                        // user picks (never silently defer a routable-but-ambiguous session).
+                        const msg = err instanceof Error ? err.message : String(err ?? "");
+                        noTabsConnected =
+                            /no panel connected|not reachable|connected:\s*none|no connected tab/i.test(msg) &&
+                                !/multiple|last active|pass tab_id/i.test(msg);
+                    }
+                    if (!noTabsConnected)
+                        return fail(err);
+                    deferredBind = true;
+                    rebindNote =
+                        " No panel tab is connected yet — cleared the stale binding; this session will " +
+                            "follow (bind onto) the tab as soon as one reconnects. Retry your graph tool in a moment.";
+                }
+                // Detect the rebind regardless of whether awaitReachable or rebindToActiveTab
+                // performed it (either mutates ctx.tabId), so the note is never swallowed.
+                if (!deferredBind && ctx.tabId !== before) {
+                    rebindNote = ` Rebound this session from tab ${before.slice(0, 8)} onto the active tab ${ctx.tabId.slice(0, 8)}.`;
                 }
             }
             // PIN: bind to the EXACT open-workflow identity from the authoritative
@@ -2771,7 +2984,7 @@ export function buildPanelToolDefs() {
             const hint = target.mode === "pinned"
                 ? `Pinned to "${target.filename ?? target.path}". Graph tools will target that workflow without switching the user's view.`
                 : "Following the user's current workflow tab.";
-            return ok({ ...target, note: hint + rebindNote });
+            return ok({ ...target, ...(deferredBind ? { deferred: true } : {}), note: hint + rebindNote });
         }),
         def("panel_new_workflow", "Open a brand-new BLANK workflow in a NEW TAB. Use this whenever the user wants a 'new workflow' / 'fresh canvas' / 'start over for a new project'. This does NOT touch their current workflow — it opens a separate tab. NEVER use panel_clear for a new workflow (panel_clear wipes the CURRENT graph and is only for 'clear/reset this canvas').", {}, async (_args, ctx) => ctx.call({ cmd: "workflow_new" }, 15000)),
         def("panel_open_workflow", "Open / switch to a workflow by path or filename (from panel_list_workflows). Switches the active tab to it.", { path: z.string().describe("Workflow path, filename, or key from panel_list_workflows.") }, 
@@ -2870,12 +3083,16 @@ export function buildPanelToolDefs() {
             "• 'active' — normal: the node executes.\n" +
             "• 'bypass' — the node is SKIPPED and PASSES ITS INPUT THROUGH to its output (downstream still runs, just as if this node weren't there). Use to disable a single processing node (an upscaler, a LoRA, a detailer) while keeping the pipeline connected.\n" +
             "• 'mute' — the node AND everything DOWNSTREAM of it do NOT execute (no pass-through). Use to fully switch off a branch/output.\n" +
-            "CRITICAL — modes silently change what a render produces, so they are a top cause of 'wrong output'. A BYPASSED node contributes nothing of its own and a MUTED node kills its branch. Use this tool to ENABLE the path you actually want and DISABLE the one you don't — e.g. to drive a workflow from its Ideogram/JSON prompt builder you must set the manual-prompt node to 'bypass' and the JSON-builder path to 'active' (or vice-versa); likewise to pick one branch of an rgthree 'Fast Groups Bypasser'/Muter or a prompt-source switch. ALWAYS read modes first (panel_graph_outline marks [bypass]/[mute]; panel_query_graph detail rows carry mode): if the intended path is bypassed/muted, fix it HERE before running, and never assume a switch/route is already active. Undoable with Ctrl+Z.", {
+            "CRITICAL — modes silently change what a render produces, so they are a top cause of 'wrong output'. A BYPASSED node contributes nothing of its own and a MUTED node kills its branch. Use this tool to ENABLE the path you actually want and DISABLE the one you don't — e.g. to drive a workflow from its Ideogram/JSON prompt builder you must set the manual-prompt node to 'bypass' and the JSON-builder path to 'active' (or vice-versa); likewise to pick one branch of an rgthree 'Fast Groups Bypasser'/Muter or a prompt-source switch. ALWAYS read modes first (panel_graph_outline marks [bypass]/[mute]; panel_query_graph detail rows carry mode): if the intended path is bypassed/muted, fix it HERE before running, and never assume a switch/route is already active. UNSAFE-BYPASS GUARD: bypassing a SUBGRAPH node whose boundary inputs are ordered differently from its outputs is REJECTED — ComfyUI forwards each output from the input at the SAME index, so e.g. an IMAGE output backed by a BBOX_DETECTOR input would silently feed the wrong type downstream. Re-order the boundary inputs or add an explicit ImpactSwitch to choose the passthrough; pass force:true only if you truly intend the positional forward. Undoable with Ctrl+Z.", {
             node_id: z.number().int().describe("Node id from panel_graph_outline / panel_query_graph."),
             mode: z
                 .enum(["active", "bypass", "mute"])
                 .describe("'active' = runs normally; 'bypass' = skipped, passes input through (downstream still runs); 'mute' = node and everything downstream do not execute."),
-        }, async (args, ctx) => ctx.call({ cmd: "graph_set_node_mode", node_id: args.node_id, mode: args.mode })),
+            force: z
+                .boolean()
+                .optional()
+                .describe("Override the unsafe-bypass guard on a subgraph node (proceed with a positional boundary forward even when input/output types don't line up by index). Omit for normal safe behaviour."),
+        }, async (args, ctx) => ctx.call({ cmd: "graph_set_node_mode", node_id: args.node_id, mode: args.mode, force: args.force })),
         def("panel_set_node_color", "Set a node's title-bar and/or body color on the user's open graph. Easiest: pass a `preset` from ComfyUI's palette (red, brown, green, blue, pale_blue, cyan, purple, yellow, black) for matched colors. Or set explicit `color` (title bar) and/or `bgcolor` (body) as hex like '#3f789e'. Pass null for a field to reset it to the theme default. Great for colour-coding stages. Undoable.", {
             node_id: z.number().int().describe("Node id from panel_graph_outline / panel_query_graph."),
             preset: z
@@ -3242,17 +3459,36 @@ export function buildPanelToolDefs() {
                         : `The reboot command was sent but I could NOT confirm ComfyUI actually cycled within ${waited}s (it never went down — the panel may have merely disconnected/inferred a reboot without one). Verify with health_check / panel_node_queue_status; do NOT assume it restarted.`,
                 });
             }
+            // #400: ComfyUI is healthy, but the panel's browser tab re-registers its own
+            // socket a moment later. If we return NOW, the very next graph tool in this turn
+            // hits "no connected tab … Connected: none" and the agent is told to hand-rebind.
+            // Wait (bounded, clamped to THIS handler's deadline) for the tab to reconnect and
+            // rebind this session onto it. `ready` reflects GRAPH-TOOL readiness (a bound tab),
+            // NOT just server health — a caller keying off `ready` must not be led into the
+            // Connected:none window (codex). `server_ready` carries the certified cycle either
+            // way. When ctx has no awaitReachable (older/lightweight ctx) tabBack is true, so
+            // the historical ready:true-on-healthy-restart contract is preserved.
+            const tabBack = ctx.awaitReachable
+                ? await ctx.awaitReachable(Math.max(0, overallDeadline - Date.now()))
+                : true;
             return ok({
                 rebooting: true,
-                ready: true,
+                ready: tabBack, // graph tools are usable only once a panel tab is bound
+                server_ready: true, // ComfyUI itself cycled and is healthy
                 confirmed_cycle: true, // we directly observed the down→up cycle on the boot endpoint
                 recovered_ms: recovery.waited_ms,
                 probes: recovery.attempts,
                 saw_down: recovery.sawDown,
                 via: recovery.via,
+                panel_tab_reconnected: tabBack,
                 note: `ComfyUI restart accepted and it is healthy again in ${(recovery.waited_ms / 1000).toFixed(1)}s` +
                     " (observed it go down then come back)" +
                     (dropped ? "; connection dropped as expected while it went down" : "") +
+                    (tabBack
+                        ? "; the panel tab reconnected — graph tools are ready."
+                        : "; ComfyUI is back but the panel tab has NOT reconnected yet (ready:false) — " +
+                            'wait a moment then retry, or rebind with panel_set_workflow_target({mode:"current"}) ' +
+                            "before issuing graph tools.") +
                     ".",
             });
         }),