comfyui-mcp 0.48.19 → 0.48.21

package/dist/orchestrator/panel-tools.js

@@ -37,6 +37,8 @@ import { getNsfwConsent, setNsfwConsent } from "../services/panel-settings.js";
 import { QueueMonitor } from "../services/queue-monitor.js";
 import { getObjectInfo, backfillObjectInfo, resetClient, resetObjectInfoCache, } from "../comfyui/client.js";
 import { convertUiToApi, collectNodeTypes } from "../services/workflow-converter.js";
+import { restartComfyUI } from "../services/process-control.js";
+import { isRemoteMode } from "../config.js";
 import { sliceWorkflow } from "../services/workflow-slicer.js";
 import { validateA2UISpecServer } from "../services/a2ui-spec.js";
 /** Treat these as an affirmative answer to the adult-content consent card. */
@@ -103,6 +105,30 @@ export function rebootDropped(res) {
     // unrelated tab reconnection makes readiness pass. Those return verbatim.
     return /disconnected mid-command|OUTCOME UNKNOWN|ECONNRESET|socket hang up|premature close|other side closed|ECONNABORTED|EPIPE/i.test(text);
 }
+/**
+ * True when a comfy_reboot ToolResult is a NON-error, NON-fired refusal whose
+ * cause is that the panel could reach NO ComfyUI-Manager reboot endpoint — i.e.
+ * every Manager reboot route answered 404/405 (the classic legacy Manager 3.x
+ * symptom: `POST /v2/manager/reboot → 405; GET /manager/reboot → 404`,
+ * panel #253/#266 and this repo #425). This is distinct from:
+ *   - a busy-guard refusal (a generation is running) — its text speaks to the
+ *     queue/generation, never to a "reboot endpoint", so it does NOT match; and
+ *   - a Manager-security 403 refusal — that speaks to "security"/"forbidden".
+ * Only a no-endpoint refusal is safe to retry through the headless managed
+ * restart (kill + relaunch), and only for a LOCAL, process-controllable target.
+ */
+export function rebootNoEndpoint(res) {
+    if (res?.isError)
+        return false;
+    const text = res?.content?.find((c) => c.type === "text")?.text ?? "";
+    // A busy-guard / security refusal must never be treated as "no endpoint" — a
+    // kill+relaunch fallback would abort a running render or defeat the security
+    // gate. Require the reboot-endpoint signature AND the absence of those.
+    if (/busy|in progress|generation|queue is|running|security|forbidden|403/i.test(text)) {
+        return false;
+    }
+    return /reboot endpoint|reboot route|was NOT restarted|no reachable .*reboot/i.test(text);
+}
 let panelRebootTimingOverride = null;
 function parsePositiveNumberEnv(name, fallback) {
     const raw = process.env[name];
@@ -130,10 +156,71 @@ export const __panelToolsTestHooks = {
     setPanelRebootTiming(timing) {
         panelRebootTimingOverride = timing;
     },
+    /** Zero out the post-drop retry settle so retry-once tests don't sleep. */
+    setRetrySettleMs(ms) {
+        retrySettleMsOverride = ms;
+    },
+    isRetrySafeCmd,
+    isTransientReconnectError,
 };
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
+// ── Post-reconnect retry-once for idempotent panel commands ──────────────────
+// A tool-triggered ComfyUI reboot (#278/#481), a panel_free_vram (#310), or a
+// Manager-backed call racing a post-restart reconnect (#332) can drop the panel
+// tab's transport the instant AFTER a command was dispatched — or replace the
+// tab under a BRAND-NEW socket/tab id with no migration alias, orphaning this
+// session. The bridge's own mid-command resume only helps when the SAME tab id
+// re-hellos; when the id changed, the in-flight command surfaces a bare
+// "no connected tab" / "disconnected mid-command … genuinely gone" / "Failed to
+// fetch" and the agent is told to hand-call panel_set_workflow_target(current).
+//
+// For commands that are SAFE to re-issue (idempotent reads, plus idempotent
+// UI-state writes like set_todo that fully REPLACE state), we transparently
+// rebind onto the now-live tab (ensureReachable) and retry ONCE after a short
+// settle. Mutating graph edits (add_node/connect/set_widget/…) are deliberately
+// EXCLUDED — re-issuing them could double-apply — so they keep surfacing the
+// bridge's honest OUTCOME-UNKNOWN error.
+const RETRY_SAFE_CMDS = new Set([
+    // Idempotent reads (mirror UiBridge.READONLY_CMDS + list/status probes).
+    "graph_serialize",
+    "graph_outline",
+    "graph_get_errors",
+    "graph_get_subgraph",
+    "graph_prompt_director_audit",
+    "graph_query",
+    "get_todo",
+    "workflow_list",
+    "nodes_list",
+    "nodes_queue_status",
+    "node_queue_status",
+    // Idempotent full-replace UI state — re-sending the same list is a no-op (#481).
+    "set_todo",
+]);
+/** A command whose result is unchanged by being re-issued after a reconnect —
+ *  so it is safe to transparently retry once when the transport dropped. */
+function isRetrySafeCmd(cmd) {
+    const name = typeof cmd.cmd === "string" ? cmd.cmd : "";
+    return RETRY_SAFE_CMDS.has(name);
+}
+/** True when an error is a TRANSIENT transport/reconnect drop (the tab went away
+ *  or was replaced), NOT a genuine command error or a live-but-frozen reply
+ *  timeout. Deliberately EXCLUDES "did not reply within N ms" (a backgrounded/
+ *  frozen tab — retrying just double-waits, #334) and "OUTCOME UNKNOWN" (a
+ *  mutating command that may already have applied). */
+function isTransientReconnectError(err) {
+    const msg = err instanceof Error ? err.message : String(err ?? "");
+    return /no connected tab|genuinely gone|is not open|Failed to fetch|Panel not reachable|ECONNRESET|socket hang up|premature close|other side closed|ECONNABORTED|EPIPE/i.test(msg);
+}
+let retrySettleMsOverride = null;
+/** Short pause before the single post-drop retry, letting the replacement tab
+ *  finish its reconnect hello so ensureReachable can resolve it. Test-overridable. */
+function retrySettleMs() {
+    if (retrySettleMsOverride != null)
+        return retrySettleMsOverride;
+    return Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_RETRY_SETTLE_S", 0.4) * 1000);
+}
 /**
  * Poll the panel bridge until ComfyUI is reachable again after a reboot. Each probe
  * is a lightweight `nodes_queue_status` round-trip (via ctx.call, which never
@@ -219,6 +306,112 @@ function parseToolResultJson(res) {
         return null;
     }
 }
+// ---- panel_run reply interpretation (#213/#331/#248/#194) -------------------
+// `panel_run` forwards `graph_run` to the panel, which drives `app.queuePrompt`
+// and forwards ComfyUI's /prompt outcome back. ComfyUI splits a rejection into
+// TWO channels:
+//   • per-node problems      -> `node_errors` (a map keyed by node id)
+//   • TOP-LEVEL problems     -> `error`       (e.g. prompt_outputs_failed_validation,
+//                                              missing_node_type) — leaves node_errors EMPTY
+// #213: the panel's success guard looked ONLY at node_errors, so a top-level
+// rejection (empty node_errors) slipped through as `queued:true` — a FALSE
+// success the agent then waited a whole turn on. We therefore DERIVE the verdict
+// from the authoritative fields (mirroring the #485 enqueue-validation parsing):
+// a reply is a rejection when it carries a non-empty `error`, a non-empty
+// `node_errors`, or an explicit `queued:false` — regardless of any `queued:true`
+// flag that may accompany it. Only a reply with NONE of those is a real queue.
+/** True when a graph_run reply's top-level `error` channel is populated (an
+ *  object with any keys, or a non-blank string). Empty object / "" / absent = no. */
+function hasTopLevelError(error) {
+    if (typeof error === "string")
+        return error.trim().length > 0;
+    if (error != null && typeof error === "object")
+        return Object.keys(error).length > 0;
+    return false;
+}
+/** True when a graph_run reply's `node_errors` channel names at least one node. */
+function hasNodeErrors(nodeErrors) {
+    return (nodeErrors != null &&
+        typeof nodeErrors === "object" &&
+        Object.keys(nodeErrors).length > 0);
+}
+/**
+ * Format a ComfyUI /prompt rejection payload (the top-level `error` object plus
+ * per-node `node_errors`) into a human-readable failure — the same shape the
+ * #485 HTTP enqueue path surfaces, so panel_run and enqueue_workflow read alike.
+ */
+function formatRunRejection(payload) {
+    let headline = "ComfyUI refused to queue the workflow";
+    const topError = payload.error;
+    const extraLines = [];
+    if (topError && typeof topError === "object") {
+        const te = topError;
+        const msg = typeof te.message === "string" ? te.message.trim() : "";
+        const type = typeof te.type === "string" ? te.type.trim() : "";
+        if (msg)
+            headline = `ComfyUI refused to queue the workflow: ${msg}${type ? ` (${type})` : ""}`;
+        else if (type)
+            headline = `ComfyUI refused to queue the workflow (${type})`;
+        const details = typeof te.details === "string" ? te.details.trim() : "";
+        if (details)
+            extraLines.push(details);
+    }
+    else if (typeof topError === "string" && topError.trim()) {
+        headline = `ComfyUI refused to queue the workflow: ${topError.trim()}`;
+    }
+    const lines = [...extraLines];
+    const ne = payload.node_errors;
+    if (ne && typeof ne === "object") {
+        for (const [nodeId, info] of Object.entries(ne)) {
+            const i = (info ?? {});
+            const cls = typeof i.class_type === "string" ? i.class_type : "node";
+            const errs = Array.isArray(i.errors) ? i.errors : [];
+            if (errs.length === 0) {
+                lines.push(`- ${cls} (node ${nodeId}): validation failed`);
+                continue;
+            }
+            for (const e of errs) {
+                const detail = typeof e?.details === "string" && e.details ? ` (${e.details})` : "";
+                const m = typeof e?.message === "string" ? e.message : "validation failed";
+                lines.push(`- ${cls} (node ${nodeId}): ${m}${detail}`);
+            }
+        }
+    }
+    return lines.length ? `${headline}\n${lines.join("\n")}` : headline;
+}
+/**
+ * Inspect a graph_run ToolResult and return a FAILURE ToolResult when the run
+ * did NOT genuinely enter ComfyUI's queue, or `null` when it is a real queue
+ * (so the caller may append the success/anti-poll guidance).
+ *
+ *  - An isError reply (no connected tab #331, a thrown app.queuePrompt #248, a
+ *    transport drop) is passed through VERBATIM — its full detail/browser stack
+ *    is preserved and the success-only "you'll be notified" note is NOT added.
+ *  - A NON-error reply is parsed: a top-level `error`, a non-empty `node_errors`,
+ *    or an explicit `queued:false` is surfaced as a formatted failure (#213) —
+ *    even when a stale `queued:true` accompanies it.
+ *  - Anything else (a plain `queued:true`, or an unparseable reply we must not
+ *    regress) returns null and is treated as a genuine queue.
+ */
+function detectRunRejection(res) {
+    // Bridge/transport/executor error: never a queue. Preserve it verbatim (#248),
+    // no success note (#331). fail() already carries err.message (incl. any stack).
+    if (res?.isError)
+        return res;
+    const parsed = parseToolResultJson(res);
+    if (!parsed)
+        return null; // unparseable non-error reply — don't regress a success
+    const topError = parsed.error;
+    const nodeErrors = parsed.node_errors;
+    const rejected = hasTopLevelError(topError) || hasNodeErrors(nodeErrors) || parsed.queued === false;
+    if (!rejected)
+        return null; // genuine queue (queued:true / no rejection signal)
+    return fail(formatRunRejection({ error: topError, node_errors: nodeErrors }));
+}
+export const __panelRunTestHooks = {
+    detectRunRejection,
+    formatRunRejection,
+};
 /** Drop a trailing .json (case-insensitive) so filename/path forms compare equal. */
 function stripJsonExt(s) {
     return typeof s === "string" ? s.replace(/\.json$/i, "") : null;
@@ -309,6 +502,44 @@ async function openWorkflowWithVerify(path, ctx) {
     // is a REAL failure. Return the original bridge timeout error unchanged.
     return res;
 }
+/**
+ * Resolve a caller-supplied pin `path` (path / filename / key, any form) to the
+ * AUTHORITATIVE open-workflow record from a fresh `workflow_list` — the single
+ * source of truth for which tabs exist and their canonical `key` (#259). Returns:
+ *  - the matched record when the workflow IS open (so the pin can be canonicalized
+ *    to its stable key and bound to the exact frontend tab identity);
+ *  - `null` when workflow_list is unreachable/empty or carries no `workflows`
+ *    array (indeterminate — caller should fall back to the raw path, NOT fail);
+ *  - the sentinel `NOT_OPEN` when the list IS known but the target is absent, so
+ *    the caller can FAIL CLOSED instead of letting the panel silently route the
+ *    pin to some other open tab.
+ */
+const NOT_OPEN = Symbol("workflow-not-open");
+async function resolveOpenWorkflow(ctx, path) {
+    let parsed = null;
+    try {
+        parsed = parseToolResultJson(await ctx.call({ cmd: "workflow_list" }, 6000));
+    }
+    catch {
+        return null; // transport error — indeterminate, don't fail the pin
+    }
+    if (!parsed)
+        return null;
+    const rawList = parsed.workflows;
+    if (!Array.isArray(rawList) || rawList.length === 0) {
+        // No enumerable tab list (older panel / stub) — can't verify, don't fail closed.
+        return null;
+    }
+    for (const wf of rawList) {
+        if (activeMatchesTarget(wf, path))
+            return wf;
+    }
+    // The active object is authoritative too, in case it isn't mirrored in the array.
+    if (activeMatchesTarget(parsed.active, path)) {
+        return parsed.active;
+    }
+    return NOT_OPEN;
+}
 export const __openWorkflowTestHooks = {
     /** Inject fast open-verify timing so tests don't wait the real ~6s budget. */
     setOpenVerifyTiming(timing) {
@@ -316,6 +547,7 @@ export const __openWorkflowTestHooks = {
     },
     isAckTimeout,
     activeMatchesTarget,
+    resolveOpenWorkflow,
 };
 const slotRef = z.union([z.string(), z.number().int().min(0)]);
 // CivitAI browsing-level bitmask values: PG=1, PG-13=2, R=4, X=8, XXX=16.
@@ -517,11 +749,14 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
     // CONSERVATIVE by construction (must not weaken multi-tab routing):
     //  - fires ONLY when the current tab is genuinely unreachable (canReach false);
     //    a healthy session — including a healthy MULTI-tab one — is never touched;
-    //  - uses the SAME resolveActiveTabId the explicit rebind uses, which THROWS on
-    //    ambiguity (2+ live tabs, no last-active) and when nothing is connected, so
-    //    an orphaned session is never silently hijacked onto an arbitrary tab —
-    //    the throw is swallowed and the command falls through to the bridge's clear
-    //    `no connected tab` / `Multiple panel tabs` error;
+    //  - STRICT-SINGLE: only silently rebinds when there is EXACTLY ONE connected
+    //    tab. With 2+ live tabs the bridge's no-tabId resolution would fall back to
+    //    `lastActiveTabId` — which can be an UNRELATED workflow (codex) — so the
+    //    silent path refuses to guess and instead lets the command surface the
+    //    bridge's clear `no connected tab` error. The user then re-binds with the
+    //    EXPLICIT panel_set_workflow_target({mode:"current"}) signal, which DOES
+    //    accept the last-active tab because it is a deliberate "use what's live now"
+    //    consent — silent auto-heal must be stricter than an explicit rebind;
     //  - PINNED sessions are left strict: a session pinned to a specific workflow
     //    keeps requiring the explicit rebind consent signal. Only "current"-mode
     //    (follow-the-active-tab) sessions self-heal, which is faithful to what that
@@ -535,6 +770,14 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
             return;
         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();
+            if (Array.isArray(live) && live.length > 1)
+                return;
+        }
         try {
             rebindToActiveTab();
         }
@@ -543,14 +786,40 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
             // command surface the bridge's own clear, tab-listing error.
         }
     };
+    const sendRouted = async (cmd, timeoutMs) => {
+        const target = workflowTargets?.get(ctx.tabId);
+        const routed = target ? withWorkflowTarget(cmd, target) : cmd;
+        return bridge.send(routed, { tabId: ctx.tabId, timeoutMs });
+    };
     const call = async (cmd, timeoutMs) => {
         try {
             ensureReachable();
-            const target = workflowTargets?.get(ctx.tabId);
-            const routed = target ? withWorkflowTarget(cmd, target) : cmd;
-            return ok(await bridge.send(routed, { tabId: ctx.tabId, timeoutMs }));
+            return ok(await sendRouted(cmd, timeoutMs));
         }
         catch (err) {
+            // Post-reconnect retry-once: a reboot/free_vram/reconnect can drop the tab's
+            // transport (or replace it under a new tab id) the instant after we dispatch.
+            // For idempotent commands, settle briefly, rebind onto the now-live tab, and
+            // retry ONE time before surfacing an error (#278/#310/#332/#481). Mutating
+            // edits are excluded from RETRY_SAFE_CMDS, so they never double-apply.
+            if (isRetrySafeCmd(cmd) && isTransientReconnectError(err)) {
+                try {
+                    await sleep(retrySettleMs());
+                    ensureReachable(); // rebinds a current-mode session onto the reconnected tab
+                    return ok(await sendRouted(cmd, timeoutMs));
+                }
+                catch (err2) {
+                    // The retry also failed — surface an actionable reconnecting status rather
+                    // than a bare transport error (#332), while still failing honestly.
+                    if (isTransientReconnectError(err2)) {
+                        const name = typeof cmd.cmd === "string" ? cmd.cmd : "panel command";
+                        return fail(`${name} could not reach the ComfyUI panel — it is still reconnecting after a ` +
+                            `restart/reload. Wait a moment and retry; if it persists, rebind with ` +
+                            `panel_set_workflow_target({mode:"current"}). (${err2 instanceof Error ? err2.message : String(err2)})`);
+                    }
+                    return fail(err2);
+                }
+            }
             return fail(err);
         }
     };
@@ -624,7 +893,15 @@ async function resolveWorkflowInput(args, ctx) {
     let reply;
     try {
         ctx.ensureReachable?.();
-        reply = await ctx.bridge.send({ cmd: "graph_serialize" }, {
+        // Route to the SAME authoritative target as ctx.call: when the session is
+        // pinned, inject the pinned workflow_path so the live-canvas capture serializes
+        // the PINNED workflow, not whatever tab is visible (codex — this direct send
+        // otherwise bypasses withWorkflowTarget and reads the wrong graph).
+        const target = ctx.workflowTarget?.get(ctx.tabId);
+        const cmd = target
+            ? withWorkflowTarget({ cmd: "graph_serialize" }, target)
+            : { cmd: "graph_serialize" };
+        reply = await ctx.bridge.send(cmd, {
             tabId: ctx.tabId,
             timeoutMs: 30000,
         });
@@ -1023,7 +1300,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). Returns queued:true, or queued:false with node_errors when frontend validation fails. 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. 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()
@@ -1042,6 +1319,16 @@ export function buildPanelToolDefs() {
             // job once let three more pile up). Snapshot the watchdog BEFORE we queue.
             const pre = QueueMonitor.snapshot();
             const res = await ctx.call({ cmd: "graph_run", batch_count: args.batch_count, to_node_id: args.to_node_id }, 20000);
+            // Derive the verdict from the AUTHORITATIVE reply, not a bare `queued`
+            // flag. A rejection — a no-connected-tab / thrown-queuePrompt error
+            // (#331/#248), or a ComfyUI /prompt refusal on EITHER channel
+            // (top-level `error` with empty node_errors #213, or per-node
+            // node_errors) — is surfaced as a failure WITHOUT the success-only
+            // "you'll be notified automatically" guidance. Only a genuine queue
+            // gets the anti-poll note below.
+            const rejection = detectRunRejection(res);
+            if (rejection)
+                return rejection;
             // Append anti-poll guidance: the agent should go idle after queuing so the
             // executed event auto-injects the output image, rather than busy-polling.
             const note = "\n\n[IMPORTANT] You will be notified automatically with the output image(s)/video when the render finishes — do NOT poll get_queue, get_history, or list_output_images. Just end your turn now and wait for the result to be delivered to you.";
@@ -1075,6 +1362,17 @@ export function buildPanelToolDefs() {
             // session is left untouched; an ambiguous multi-tab case surfaces a clear
             // error rather than guessing.
             if (ctx.rebindToActiveTab) {
+                // Strict-single: if this session's tab is orphaned AND 2+ tabs are live,
+                // do NOT guess (the bridge would fall back to last-active, possibly an
+                // unrelated tab) — surface a clear error so the user picks, honoring the
+                // 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) {
+                    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.');
+                }
                 try {
                     ctx.rebindToActiveTab();
                 }
@@ -1492,7 +1790,32 @@ export function buildPanelToolDefs() {
                     return fail(err);
                 }
             }
-            const target = ctx.workflowTarget.set(ctx.tabId, { mode, path, filename });
+            // PIN: bind to the EXACT open-workflow identity from the authoritative
+            // workflow_list, canonicalizing to its stable `key` and FAILING CLOSED when
+            // the requested workflow isn't actually open — instead of letting the panel
+            // silently route the pin to another tab (#259). Indeterminate lists (older
+            // panel / no `workflows` array) fall back to the raw path (unchanged).
+            let pinPath = path;
+            let pinFilename = filename;
+            if (mode === "pinned" && path) {
+                const resolved = await resolveOpenWorkflow(ctx, path);
+                if (resolved === NOT_OPEN) {
+                    return fail(`Cannot pin to "${path}" — it is not open in ComfyUI. Open it first ` +
+                        `(panel_open_workflow) or pick an open workflow from panel_list_workflows, ` +
+                        `then pin. (Refusing to pin to a workflow that isn't open so graph edits ` +
+                        `never land on the wrong tab.)`);
+                }
+                if (resolved) {
+                    // Canonicalize to the stable key so routing survives rename/reconnect.
+                    pinPath = resolved.key ?? resolved.path ?? path;
+                    pinFilename = filename ?? resolved.filename ?? resolved.path;
+                }
+            }
+            const target = ctx.workflowTarget.set(ctx.tabId, {
+                mode,
+                path: pinPath,
+                filename: pinFilename,
+            });
             ctx.bridge.push({ type: "workflow_target", target }, ctx.tabId);
             const hint = target.mode === "pinned"
                 ? `Pinned to "${target.filename ?? target.path}". Graph tools will target that workflow without switching the user's view.`
@@ -1619,7 +1942,15 @@ export function buildPanelToolDefs() {
         })),
         def("panel_screenshot", "Render the workflow the user is currently viewing (root graph, or the open subgraph) to a PNG and return it as an IMAGE so you can SEE the layout. It frames the whole graph (nodes + groups), captures, then restores the user's view. Use this to visually verify a layout you just built — overlaps, alignment, rails, colors, group bands — instead of reasoning from coordinates alone.", { padding: z.number().optional().describe("Margin around the graph in px (default 60).") }, async (args, ctx) => {
             try {
-                const res = (await ctx.bridge.send({ cmd: "graph_screenshot", padding: args.padding }, { tabId: ctx.tabId }));
+                ctx.ensureReachable?.();
+                // Route to the same authoritative target as ctx.call: a pinned session
+                // screenshots the PINNED workflow (via injected workflow_path), not just
+                // whatever tab is visible (codex — graph_* must carry the pin).
+                const target = ctx.workflowTarget?.get(ctx.tabId);
+                const cmd = withWorkflowTarget({ cmd: "graph_screenshot", padding: args.padding }, target ?? { mode: "current" });
+                const res = (await ctx.bridge.send(cmd, {
+                    tabId: ctx.tabId,
+                }));
                 if (!res?.image)
                     return fail("screenshot returned no image");
                 return { content: [{ type: "image", data: res.image, mimeType: res.mimeType ?? "image/png" }] };
@@ -1696,6 +2027,50 @@ export function buildPanelToolDefs() {
             const fired = rebootConfirmed(res);
             const dropped = !fired && rebootDropped(res);
             if (!fired && !dropped) {
+                // The panel could not fire a Manager reboot. If the SOLE reason is that
+                // NO Manager reboot endpoint answered (legacy Manager 3.x: v2 route 405s,
+                // legacy route 404s — #425, panel #253/#266) AND the target is a LOCAL,
+                // process-controllable ComfyUI, fall back to the headless managed restart
+                // (kill + relaunch) — the same mechanism as the `restart_comfyui` tool.
+                // A busy-guard or security refusal is deliberately NOT eligible
+                // (rebootNoEndpoint excludes those), so this never aborts a running
+                // render or bypasses Manager's security gate.
+                if (!isRemoteMode() && rebootNoEndpoint(res)) {
+                    let restart;
+                    try {
+                        restart = await restartComfyUI();
+                    }
+                    catch (err) {
+                        return fail("The built-in Manager exposed no reboot endpoint (legacy Manager 3.x), " +
+                            "and the headless managed restart also failed: " +
+                            (err instanceof Error ? err.message : String(err)) +
+                            " — restart ComfyUI on the host, then reconnect.");
+                    }
+                    if (!restart.started) {
+                        return fail("The built-in Manager exposed no reboot endpoint (legacy Manager 3.x). " +
+                            "Tried the headless managed restart (kill + relaunch) as a fallback, but it " +
+                            `could not restart ComfyUI: ${restart.message} ` +
+                            "Restart ComfyUI on the host, then reconnect.");
+                    }
+                    // A managed kill+relaunch restarts ComfyUI out-of-band from the WS
+                    // client, so drop the memoized caches exactly as the Manager-reboot
+                    // path does before waiting for the panel to reconnect.
+                    resetClient();
+                    resetObjectInfoCache();
+                    const timing = getPanelRebootTiming();
+                    const recovery = await waitForPanelReady(ctx, timing);
+                    return ok({
+                        rebooting: true,
+                        ready: recovery.ready,
+                        recovered_ms: recovery.waited_ms,
+                        probes: recovery.attempts,
+                        via: "headless-managed-restart",
+                        note: "ComfyUI-Manager (legacy 3.x) had no reboot endpoint; restarted ComfyUI " +
+                            `via the headless managed restart (kill + relaunch)${recovery.ready
+                                ? ` and it came back ready in ${(recovery.waited_ms / 1000).toFixed(1)}s.`
+                                : " but the panel did not reconnect within the readiness budget — verify with panel_node_queue_status."}`,
+                    });
+                }
                 // Genuine refusal (or an unrelated error) — do NOT poll or reset caches.
                 // Resetting on a refusal would close the shared client mid-generation
                 // (codex WS-3 finding #2).