comfyui-mcp 0.52.26 → 0.52.28

package/dist/orchestrator/node-id.js

@@ -21,8 +21,18 @@
  * refused to risk. So a qualified id is never converted: it stays the string the
  * reader printed, all the way to the panel.
  */
-/** A plain integer id, the form the wire has always carried. */
-const PLAIN = /^-?\d+$/;
+/**
+ * A plain integer id, the form the wire has always carried.
+ *
+ * Exported because one argument needs this shape ON ITS OWN: panel_run's
+ * `to_node_id` (#1497). Everything else takes NODE_ID_PATTERN, which admits the
+ * qualified form too — but a run-to-node target is resolved by NUMBER all the way
+ * down (the panel's findNodeInScopes does `Number(id)`, and its reply reports
+ * `ran_to_node: Number(to_node_id)`), so admitting `"120:104"` there would trade a
+ * clear schema refusal for a panel-side "node not found" about a node that exists.
+ * The shape lives here so the two patterns cannot drift apart.
+ */
+export const PLAIN_NODE_ID_PATTERN = /^-?\d+$/;
 /**
  * A subgraph-qualified id: integer segments joined by colons (`120:104`,
  * `120:113:78`). No depth limit — nesting is arbitrary, and a limit would fail the

package/dist/orchestrator/node-id.js.map

@@ -1 +1 @@
-{"version":3,"file":"node-id.js","sourceRoot":"","sources":["../../src/orchestrator/node-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,gEAAgE;AAChE,MAAM,KAAK,GAAG,SAAS,CAAC;AAExB;;;;;;GAMG;AACH,MAAM,SAAS,GAAG,kBAAkB,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAElD,6DAA6D;AAC7D,MAAM,UAAU,cAAc,CAAC,CAAS;IACtC,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjC,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,iBAAiB,CAAC,CAAS;IACzC,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,CAAkB;IAChD,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IAChC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;oFACoF;AACpF,MAAM,CAAC,MAAM,eAAe,GAC1B,kFAAkF,CAAC"}
+{"version":3,"file":"node-id.js","sourceRoot":"","sources":["../../src/orchestrator/node-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,SAAS,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,SAAS,GAAG,kBAAkB,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAElD,6DAA6D;AAC7D,MAAM,UAAU,cAAc,CAAC,CAAS;IACtC,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjC,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,iBAAiB,CAAC,CAAS;IACzC,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,CAAkB;IAChD,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IAChC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;oFACoF;AACpF,MAAM,CAAC,MAAM,eAAe,GAC1B,kFAAkF,CAAC"}

package/dist/orchestrator/panel-tools.js

@@ -34,6 +34,7 @@ import { fileURLToPath } from "node:url";
 import { comfyuiFetch } from "../comfyui/fetch.js";
 import { assertPanelNotTargetedUnverifiable } from "../services/panel-pin-guard.js";
 import { nodesInstallCommandArgs } from "../services/node-management.js";
+import { sanitizePanelUpdateNodeResult } from "../services/manager-update-error.js";
 import { formatQueueStatusPartialNote, getManifestPartialLeftover, } from "../services/manifest-partial.js";
 import { searchPanelNodes } from "../services/manager-node-search.js";
 import { isPanelAnsweredError } from "../services/panel-answered.js";
@@ -45,7 +46,7 @@ import { compareSemver } from "../services/self-update.js";
 import { describeInstallPanelAction } from "../services/panel-recovery.js";
 import { peekResolvedPanelBase, primePanelBase, verifiedPanelDiskVersion, } from "../services/panel-workspace.js";
 import { conversationOfScopeAddress, isScopeAddress, shortTabId } from "../services/session-scope.js";
-import { NODE_ID_MESSAGE, NODE_ID_PATTERN, normalizeNodeId } from "./node-id.js";
+import { NODE_ID_MESSAGE, NODE_ID_PATTERN, normalizeNodeId, PLAIN_NODE_ID_PATTERN, } from "./node-id.js";
 import { parseContradictoryPromotedWidgetRefusal, resolveInnerPromotedTarget, } from "./promoted-widget.js";
 import { fastGroupsFilterPropertyNote, isFastGroupsFilterProperty, } from "./rgthree-fast-groups-property.js";
 import { isPlainObject, isStampMismatchSaveRefusal, openLiveMatchesDestContent, patchOpenIdentity, shouldRebindOpenIdentity, workflowFromSerializeReply, } from "./open-identity-normalization.js";
@@ -573,6 +574,11 @@ export const __panelToolsTestHooks = {
     setFreeVramDirect(fn) {
         freeVramDirectOverride = fn;
     },
+    /** Inject a fake post-/free /system_stats read so #1866 occupancy checks can
+     *  be driven without real HTTP. null restores the live readVramDevices. */
+    setReadVramDevices(fn) {
+        readVramDevicesOverride = fn;
+    },
     /** Direct access to the #742 decline recheck loop so its hard-deadline
      *  guarantee (codex gate r2) can be unit-tested with a custom deadline. */
     probeDeclineRecovery,
@@ -2185,17 +2191,7 @@ async function readVramDevices(base, timeoutMs) {
         const devices = body.devices;
         if (!Array.isArray(devices))
             return null;
-        return devices.map((d) => {
-            const dev = (d ?? {});
-            const sample = {};
-            if (typeof dev.name === "string")
-                sample.name = dev.name;
-            if (typeof dev.vram_total === "number")
-                sample.vram_total = dev.vram_total;
-            if (typeof dev.vram_free === "number")
-                sample.vram_free = dev.vram_free;
-            return sample;
-        });
+        return devices.map((d) => sampleVramDevice(d));
     }
     catch {
         return null; // unreachable/timed out — no numbers to report
@@ -2204,12 +2200,98 @@ async function readVramDevices(base, timeoutMs) {
         clearTimeout(timer);
     }
 }
+function sampleVramDevice(d) {
+    const dev = (d ?? {});
+    const sample = {};
+    if (typeof dev.name === "string")
+        sample.name = dev.name;
+    if (typeof dev.index === "number")
+        sample.index = dev.index;
+    if (typeof dev.vram_total === "number")
+        sample.vram_total = dev.vram_total;
+    if (typeof dev.vram_free === "number")
+        sample.vram_free = dev.vram_free;
+    if (typeof dev.torch_vram_total === "number")
+        sample.torch_vram_total = dev.torch_vram_total;
+    if (typeof dev.torch_vram_free === "number")
+        sample.torch_vram_free = dev.torch_vram_free;
+    return sample;
+}
+/** A device with at least 1 GiB of VRAM is still PINNED when less than 20% is
+ *  free after /free. CUDA context leftover on an unloaded GPU is a few hundred
+ *  MB to a couple of GiB, not 80%+ of a 21 GiB card. The reporter's Raylight
+ *  MiniMax H3 case was device 2 at ~0.8% free (~179 MiB of 21 GiB) next to
+ *  siblings at ~44% free — that occupancy is what this threshold names.
+ *
+ *  Unknown/unreadable counters are NOT pinned: an unknown answer claims
+ *  nothing in either direction (#1473). */
+const PINNED_VRAM_MIN_TOTAL_BYTES = 1024 * 1024 * 1024;
+const PINNED_VRAM_FREE_RATIO = 0.2;
+function deviceStillPinned(d) {
+    const total = d.vram_total;
+    const free = d.vram_free;
+    if (typeof total !== "number" || typeof free !== "number")
+        return false;
+    if (!Number.isFinite(total) || !Number.isFinite(free))
+        return false;
+    if (total < PINNED_VRAM_MIN_TOTAL_BYTES)
+        return false;
+    if (free < 0)
+        return true;
+    return free / total <= PINNED_VRAM_FREE_RATIO;
+}
+function pinnedVramDevices(devices) {
+    return devices.filter(deviceStillPinned);
+}
+/** /free only unloads ComfyUI's model manager. Ray workers, parallel CLIP
+ *  loaders, and other custom-node allocations survive it and keep the GPU
+ *  occupied — which is why a 2xx from /free is not evidence VRAM is free. */
+function pinnedVramAfterFreeNote(pinned) {
+    const named = pinned
+        .map((d) => {
+        if (typeof d.index === "number")
+            return `device ${d.index}`;
+        if (typeof d.name === "string" && d.name)
+            return d.name;
+        return "an unnamed device";
+    })
+        .join(", ");
+    return (`ComfyUI /free accepted (unload_models + free_memory) but VRAM is STILL PINNED on ` +
+        `${named}. /free only unloads ComfyUI's model manager — it does not terminate Ray ` +
+        `workers or custom-node allocations (Raylight sequence-parallel, parallel CLIP loaders). ` +
+        `This is not a successful VRAM recovery. Next: panel_restart_comfyui (last resort; ` +
+        `refuses mid-render) after confirming with get_system_stats (action:"stats").`);
+}
+function pinnedVramAfterFreeResult(pinned, extra) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    freed: false,
+                    unload_models: true,
+                    free_memory: true,
+                    model_manager_freed: true,
+                    pinned_devices: pinned,
+                    ...extra,
+                    note: pinnedVramAfterFreeNote(pinned),
+                }, null, 2),
+            },
+        ],
+        isError: true,
+    };
+}
+/** Test injection for the post-/free /system_stats occupancy read (#1866). */
+let readVramDevicesOverride = null;
+async function readVramDevicesMaybe(base, timeoutMs) {
+    return (readVramDevicesOverride ?? readVramDevices)(base, timeoutMs);
+}
 /** Issue ComfyUI's /free DIRECTLY against a proven-local base and read the
  *  VRAM counters around it. Never throws — every failure is a value, so the
  *  settle can degrade to the honest outcome-unknown instead of masking the
  *  original timeout behind a new error. */
 async function freeVramDirect(base) {
-    const before = await readVramDevices(base, FREE_VRAM_DIRECT_TIMEOUT_MS);
+    const before = await readVramDevicesMaybe(base, FREE_VRAM_DIRECT_TIMEOUT_MS);
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), FREE_VRAM_DIRECT_TIMEOUT_MS);
     timer.unref?.();
@@ -2234,7 +2316,7 @@ async function freeVramDirect(base) {
     finally {
         clearTimeout(timer);
     }
-    const after = await readVramDevices(base, FREE_VRAM_DIRECT_TIMEOUT_MS);
+    const after = await readVramDevicesMaybe(base, FREE_VRAM_DIRECT_TIMEOUT_MS);
     return { ok: true, before, after };
 }
 /** Test injection for the direct server-side /free, so the settle can be
@@ -2277,6 +2359,21 @@ async function settleFreeVramAfterAckTimeout(ctx, timedOut) {
             ],
         };
     }
+    const extra = {
+        acknowledged: false,
+        verified: "server-side",
+        via: `POST ${base}/free`,
+        ...(direct.before != null ? { vram_before: direct.before } : {}),
+        ...(direct.after != null ? { vram_after: direct.after } : {}),
+    };
+    // #1866 — a 2xx from /free is not a free GPU. Ray/CLIP workers can keep a
+    // device pinned. When we have occupancy numbers, they are the verdict.
+    if (direct.after != null) {
+        const pinned = pinnedVramDevices(direct.after);
+        if (pinned.length > 0) {
+            return pinnedVramAfterFreeResult(pinned, extra);
+        }
+    }
     const statsNote = direct.before != null && direct.after != null
         ? "vram_before/vram_after are the server's own /system_stats counters around the free."
         : "The /system_stats read around it did not answer, so no VRAM counters are reported — the 2xx from /free is the verification, not a measured delta.";
@@ -2284,11 +2381,7 @@ async function settleFreeVramAfterAckTimeout(ctx, timedOut) {
         freed: true,
         unload_models: true,
         free_memory: true,
-        acknowledged: false,
-        verified: "server-side",
-        via: `POST ${base}/free`,
-        ...(direct.before != null ? { vram_before: direct.before } : {}),
-        ...(direct.after != null ? { vram_after: direct.after } : {}),
+        ...extra,
         note: `The panel tab never acknowledged (frozen or backgrounded), so the free was issued ` +
             `DIRECTLY to the ComfyUI server this tab provably fronts — the same /free endpoint the ` +
             `panel would have called — and the server confirmed it. /free is idempotent: if the tab's ` +
@@ -2296,6 +2389,32 @@ async function settleFreeVramAfterAckTimeout(ctx, timedOut) {
             `twice. ${statsNote}`,
     });
 }
+/**
+ * #1866 — a panel ack of `{freed:true}` is the /free HTTP 2xx, not a measured
+ * GPU. After the tab says it posted /free, re-read /system_stats and refuse to
+ * claim VRAM was freed when a device is still occupied. Unreadable stats leave
+ * the original ack UNTOUCHED: an unknown answer claims nothing extra.
+ */
+async function annotateFreeVramAck(res) {
+    if (res.isError)
+        return res;
+    const parsed = parseToolResultJson(res);
+    if (!parsed || parsed.freed !== true)
+        return res;
+    const base = (getComfyUIBaseUrl() || "").replace(/\/+$/, "");
+    if (!base)
+        return res;
+    const devices = await readVramDevicesMaybe(base, FREE_VRAM_DIRECT_TIMEOUT_MS);
+    if (devices == null)
+        return res;
+    const pinned = pinnedVramDevices(devices);
+    if (pinned.length === 0)
+        return res;
+    return pinnedVramAfterFreeResult(pinned, {
+        acknowledged: true,
+        devices,
+    });
+}
 // ---- panel_install_node: accepted-but-never-enqueued (#1129) ---------------
 // #1143 fixed the pre-queue REFUSAL (403/404 → direct clone). This is the other
 // half of the same family: legacy Manager 3.x answers the install POST with
@@ -4973,8 +5092,18 @@ panelGapNote = "") {
     // A panel that cannot fence a WRITE gives reads only, however good the stamp is.
     const mutationsRefused = canMutate === false;
     const mutationsUnknown = canMutate === undefined;
+    // #1494 — `reads_only` would be a FALSE consolation for this one cause. The
+    // dispatch-time agreement gate covers `graph_*` READS as well as mutations
+    // (requiresStampTargetAgreement), so a session in that state has neither working
+    // graph reads NOR writes — only the canvas-INDEPENDENT ops that predicate exempts
+    // (graph_update_node, the virtual-type reads) still dispatch, which is not what a
+    // caller reads "reads_only" as. And the whole report is that this call answered
+    // "bound" while everything the gate covers was being refused. It is
+    // `not_recovered`: the caller must not read success out of it.
     const okBinding = mutationsRefused
-        ? "reads_only"
+        ? refusalCause === "target_disagreement"
+            ? "not_recovered"
+            : "reads_only"
         : mutationsUnknown
             ? "unverified"
             : "bound";
@@ -5000,23 +5129,37 @@ panelGapNote = "") {
                 `\n\nWHAT TO DO: call this tool again to bind an identity. If it keeps coming back ` +
                 `without one, have the user click into the workflow tab so the panel reports an active ` +
                 `canvas, then call this again.`
-            : mutationsRefused && refusalCause === "unroutable"
-                ? `\n\nBUT this tab is NOT REACHABLE from the orchestrator right now, so graph mutations ` +
-                    `are refused — and reads are not working either, whatever this note says about them. ` +
-                    `This is NOT a panel-version problem: updating the pack and hard-refreshing cannot help, ` +
-                    `because there is nothing to refresh until the tab is connected again.` +
-                    `\n\nWHAT TO DO: check that the ComfyUI browser tab is still open and its panel is ` +
-                    `connected, then call this again.`
-                : mutationsRefused
-                    ? `\n\nBUT graph MUTATIONS are still refused for this tab: its panel build does not ` +
-                        `advertise the write-boundary workflow fence a graph edit requires, and no rebind — ` +
-                        `including calling this tool again — can add it. Reads work now (this call just read the ` +
-                        `live canvas).\n\nWHAT TO DO FOR EDITS: update the comfyui-mcp-panel pack, then have the ` +
-                        `user HARD-refresh (Ctrl+Shift+R) the ComfyUI browser tab — an open tab keeps running its ` +
-                        `cached bundle, so the capability lags the version on disk until it does. Do NOT use ` +
-                        `panel_reload for this: it has been observed to leave the tab permanently unresponsive ` +
-                        `(#803).`
-                    : "";
+            : mutationsRefused && refusalCause === "target_disagreement"
+                ? `\n\nBUT THIS DID NOT CLEAR THE REFUSAL, and saying otherwise is the bug this ` +
+                    `wording exists to stop (#1494). Graph commands are refused BEFORE they are ` +
+                    `dispatched, by a comparison this call does not perform: the session's stamp against ` +
+                    `the identity the ROUTED TAB last advertised in its handshake. This call compared the ` +
+                    `stamp against the LIVE canvas instead, and those are different facts — the live ` +
+                    `canvas agreeing is exactly why nothing above says "rebound". Graph READS are refused ` +
+                    `by the same gate, so this is not a reads-only session.` +
+                    `\n\nWHAT TO DO: re-open the workflow you mean with panel_open_workflow(<path>) — an ` +
+                    `open proves an identity for the tab under its current id, which is what the gate is ` +
+                    `missing; for a never-saved canvas use its routing_key from panel_list_workflows. The ` +
+                    `panel also re-advertises on its own when it notices the drift, so a command that ` +
+                    `keeps failing here may start working without you doing anything — do NOT read that as ` +
+                    `this call having repaired it.`
+                : mutationsRefused && refusalCause === "unroutable"
+                    ? `\n\nBUT this tab is NOT REACHABLE from the orchestrator right now, so graph mutations ` +
+                        `are refused — and reads are not working either, whatever this note says about them. ` +
+                        `This is NOT a panel-version problem: updating the pack and hard-refreshing cannot help, ` +
+                        `because there is nothing to refresh until the tab is connected again.` +
+                        `\n\nWHAT TO DO: check that the ComfyUI browser tab is still open and its panel is ` +
+                        `connected, then call this again.`
+                    : mutationsRefused
+                        ? `\n\nBUT graph MUTATIONS are still refused for this tab: its panel build does not ` +
+                            `advertise the write-boundary workflow fence a graph edit requires, and no rebind — ` +
+                            `including calling this tool again — can add it. Reads work now (this call just read the ` +
+                            `live canvas).\n\nWHAT TO DO FOR EDITS: update the comfyui-mcp-panel pack, then have the ` +
+                            `user HARD-refresh (Ctrl+Shift+R) the ComfyUI browser tab — an open tab keeps running its ` +
+                            `cached bundle, so the capability lags the version on disk until it does. Do NOT use ` +
+                            `panel_reload for this: it has been observed to leave the tab permanently unresponsive ` +
+                            `(#803).`
+                        : "";
     switch (r.status) {
         case "diverged":
             // #1646 — produced ONLY by a read-only probe (`adopt:false`), which the
@@ -7427,14 +7570,53 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
                 let verdict;
                 try {
                     const probe = await rebindWorkflowFence(ctx, { adopt: false });
+                    // #1494 — WHICH COMPARISON IS REFUSING, asked of the gate itself rather than
+                    // inferred from the probe.
+                    //
+                    // The probe reads the LIVE canvas. The dispatch-time agreement gate refuses on
+                    // the identity the ROUTED TAB last advertised. When the advertisement is the
+                    // stale side, those two disagree — the probe reports `already_current` on the
+                    // very uuid the command carried, which reads as "transient, retry" while every
+                    // retry is compared against the same unchanged advertisement and refused
+                    // identically. That is the reported contradiction: an immediate rebind
+                    // confirming the original instance, next to a refusal naming another one.
+                    //
+                    // Typed, from `tabGraphMutationCapability` (the bridge's own verdict, sharing
+                    // one predicate with `send()`), never a second reading of the refusal's prose.
+                    let gateStillRefuses = false;
+                    try {
+                        const cap = ctx.tabGraphMutationCapability?.();
+                        gateStillRefuses =
+                            cap?.known === true &&
+                                cap.canMutate === false &&
+                                cap.because === "target_disagreement";
+                    }
+                    catch {
+                        gateStillRefuses = false; // a diagnostic must never replace the outcome
+                    }
                     verdict =
                         probe.status === "already_current" && stamped && probe.uuid === stamped
-                            ? `\n\nCHECKED: the live canvas now reports the SAME workflow instance this ` +
-                                `command carried (${stamped}), so the mismatch was TRANSIENT: the identity ` +
-                                `flipped and settled back, which happens while a new unsaved workflow is still ` +
-                                `materialising. RETRY THIS EXACT CALL ONCE. Nothing was applied, so a retry ` +
-                                `cannot double-apply, and re-issuing the whole build would duplicate the work ` +
-                                `that already succeeded.`
+                            ? gateStillRefuses
+                                ? `\n\nCHECKED, and the two claims are BOTH true of different things: the live ` +
+                                    `canvas does report the SAME workflow instance this command carried ` +
+                                    `(${stamped}), and the refusal above is not about the live canvas — it is ` +
+                                    `the pre-dispatch check on the identity the ROUTED TAB last advertised, ` +
+                                    `which is the stale side here. So a bare retry is compared against that ` +
+                                    `same unchanged value and is refused the same way; ` +
+                                    `panel_set_workflow_target({mode:"current"}) reports "already current" for ` +
+                                    `the same reason and does not clear it either. Nothing was applied. WHAT TO ` +
+                                    `DO: re-open the workflow you mean with panel_open_workflow(<path>) — that ` +
+                                    `proves an identity for the tab under its CURRENT id, which is what is ` +
+                                    `missing; for a never-saved canvas use its routing_key from ` +
+                                    `panel_list_workflows. The panel also re-advertises on its own once it ` +
+                                    `notices the drift, so a retry may start working shortly — that is the ` +
+                                    `panel repairing it, not this call.`
+                                : `\n\nCHECKED: the live canvas now reports the SAME workflow instance this ` +
+                                    `command carried (${stamped}), so the mismatch was TRANSIENT: the identity ` +
+                                    `flipped and settled back, which happens while a new unsaved workflow is still ` +
+                                    `materialising. RETRY THIS EXACT CALL ONCE. Nothing was applied, so a retry ` +
+                                    `cannot double-apply, and re-issuing the whole build would duplicate the work ` +
+                                    `that already succeeded.`
                             : probe.status === "already_current"
                                 ? `\n\nCHECKED: the session's fence already names the live canvas ` +
                                     `(${probe.uuid}), so it was not the stale side. Retry once — if it refuses ` +
@@ -8966,6 +9148,38 @@ const nodeId = () => z
     z.string().regex(NODE_ID_PATTERN, NODE_ID_MESSAGE),
 ])
     .transform(normalizeNodeId);
+/**
+ * #1497 — the ONE node-id argument #845 never reached: panel_run's `to_node_id`.
+ *
+ * #845 made every panel tool accept back an id it had PRINTED, because the graph
+ * readers hand out ids as strings (`summarizeNode` returns `id: node.id`, and on
+ * the modern ComfyUI frontend that is `"11"`, not `11`). Twenty-seven node-id
+ * arguments adopted `nodeId()`; this one kept `z.number().int()` and was missed,
+ * so the documented round trip — take the id `panel_add_node` just returned, hand
+ * it to panel_run — failed with a raw `expected number, received string`, exactly
+ * as #845 described and #427 hit for panel_create_group. A canonical validator is
+ * adopted per CALL SITE, and this call site never adopted it.
+ *
+ * NOT `nodeId()`, deliberately. That helper also admits the subgraph-QUALIFIED
+ * shape (`"120:104"`, #1425) and passes it through as a string, which is right for
+ * a write that addresses a node by key. A run-to-node target is not addressed by
+ * key — it is an EXECUTION ROOT, resolved numerically the whole way down:
+ * the panel's `findNodeInScopes` matches on `Number(id)`, its reply reports
+ * `ran_to_node: Number(to_node_id)`, and two branches here (#772's stamp-race
+ * re-issue and #468's run ticket) gate on `typeof args.to_node_id === "number"`.
+ * Widening this argument to the qualified form would therefore turn a clear schema
+ * refusal into a panel-side "node 120:104 was not found" about a node that plainly
+ * exists, and silently drop the run ticket that correlates the completion. So the
+ * spelling widens and the SHAPE does not: `11` and `"11"` both mean node 11, and
+ * a qualified id is still refused — now by name, with a reason.
+ */
+const RUN_TO_NODE_ID_MESSAGE = 'a run-to-node target must be a plain integer node id — 42 or "42" both work. A subgraph-qualified id (e.g. "120:104") is not an execution root: pass the output node\'s own plain id, which is what panel_query_graph prints for it even when it is nested inside a subgraph';
+const runToNodeId = () => z
+    .union([
+    z.number().int(),
+    z.string().regex(PLAIN_NODE_ID_PATTERN, RUN_TO_NODE_ID_MESSAGE),
+])
+    .transform((v) => (typeof v === "number" ? v : Number.parseInt(v, 10)));
 /**
  * #845 — which `panel_canvas` arguments the chosen action actually consumes.
  *
@@ -10238,11 +10452,9 @@ export function buildPanelToolDefs() {
                 .max(100)
                 .optional()
                 .describe("Times to queue (default 1)."),
-            to_node_id: z
-                .number()
-                .int()
+            to_node_id: runToNodeId()
                 .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. May be nested inside a subgraph (pass the node's own id)."),
+                .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). Takes the id EXACTLY as the readers print it: 11 and \"11\" both mean node 11 (#1497). A subgraph-qualified id (\"120:104\") is not an execution root and is refused."),
             allow_duplicate: z
                 .boolean()
                 .optional()
@@ -10623,7 +10835,32 @@ export function buildPanelToolDefs() {
                 return appendToolResultText(res, lateAckNote);
             return res;
         }),
-        def("panel_get_errors", "WHY IS THAT NODE RED / WHY DID THE RUN FAIL? The single error surface for the user's open tab: every errored node JOINED TO ITS CAUSE, which ComfyUI itself does not show — LiteGraph only paints a red outline and stores no reason, which is why users report \"red node, no error message\". Call this whenever the user mentions a red/highlighted/erroring node, a failed run, or \"required models are missing\" — instead of guessing from widget values. Each entry in `nodes[]` is the node's full detail summary plus `red_outline` and `reasons[]`, drawn from every source: `missing_model` (exact file, its models directory, the widget holding it, and a download URL when known), `missing_media` (a referenced input image/video that isn't on disk — the usual cause of a red LoadImage), `validation` (per-input errors from the last queue attempt: message, details, offending input), and `execution` (runtime failure with `exception_type`, e.g. PIL.UnidentifiedImageError). TWO THINGS THAT MAKE THIS ESSENTIAL: (1) missing model/media assets paint nodes red AS SOON AS THE WORKFLOW LOADS, long before any queue attempt — so the raw validation map is still EMPTY while the user is staring at red nodes; (2) a node that throws AT RUNTIME is never painted red at all, so it can't be spotted on the canvas — it appears here with red_outline:false. Also returns graph-level `missing_models`, `missing_media`, `missing_node_types` (or `missing_node_count`), plus the raw `node_errors` map and `last_execution_error` for reference. A ⚠️ GRAPH VALIDATION block is auto-injected at your turn start when this state changes; call this to re-check on demand (e.g. after you edit widgets/links). Read-only.", {}, async (_args, ctx) => withTruncationHints(await ctx.call({ cmd: "graph_get_errors" }), [
+        def("panel_get_errors", "WHY IS THAT NODE RED / WHY DID THE RUN FAIL? The single error surface for the user's open tab: every errored node JOINED TO ITS CAUSE, which ComfyUI itself does not show — LiteGraph only paints a red outline and stores no reason, which is why users report \"red node, no error message\". Call this whenever the user mentions a red/highlighted/erroring node, a failed run, or \"required models are missing\" — instead of guessing from widget values. Each entry in `nodes[]` is the node's full detail summary plus `red_outline` and `reasons[]`, drawn from every source: `missing_model` (exact file, its models directory, the widget holding it, and a download URL when known), `missing_media` (a referenced input image/video that isn't on disk — the usual cause of a red LoadImage), `validation` (per-input errors from the last queue attempt: message, details, offending input), and `execution` (runtime failure with `exception_type`, e.g. PIL.UnidentifiedImageError). TWO THINGS THAT MAKE THIS ESSENTIAL: (1) missing model/media assets paint nodes red AS SOON AS THE WORKFLOW LOADS, long before any queue attempt — so the raw validation map is still EMPTY while the user is staring at red nodes; (2) a node that throws AT RUNTIME is never painted red at all, so it can't be spotted on the canvas — it appears here with red_outline:false. Also returns graph-level `missing_models`, `missing_media`, `missing_node_types` (or `missing_node_count`), plus the raw `node_errors` map and `last_execution_error` for reference. A ⚠️ GRAPH VALIDATION block is auto-injected at your turn start when this state changes; call this to re-check on demand (e.g. after you edit widgets/links). Read-only.", {}, 
+        // #1493 — graph_get_errors belongs to the #599 refresh-ack cohort above, and was the
+        // one member of it left on the generic read default.
+        //
+        // Its frontend handler deliberately awaits a FORCED /object_info re-register before it
+        // will trust a combo to clear a resolved missing-model candidate (#610), and it spends a
+        // shared 18 000 ms elective budget across that refresh race, the /system_stats probe and the
+        // /view media probes (GET_ERRORS_TOTAL_BUDGET_MS, panel web/js/lib/get-errors-budget.js).
+        // That budget was sized to sit under BRIDGE_READ_DEFAULT_TIMEOUT_MS — which leaves 2 000 ms
+        // for everything the call still has to do AFTER the waits: collectMissingAssets over the
+        // whole graph, the per-node live combo scan, the subgraph walk, and serializing a reply big
+        // enough that this tool ships two truncation riders for it.
+        //
+        // The reported sequence spends that budget exactly as designed — panel_refresh_nodes, three
+        // promoted-widget writes on a model-loader subgraph, a save — and panel_get_errors was then
+        // declared "backgrounded or frozen" at 20 000 ms by a tab that had just answered four
+        // commands and did reply, late. That is the precise failure the shared budget exists to
+        // prevent (#589): an agent left with NO error surface for a workflow whose nodes are red.
+        //
+        // The margin has to come from THIS side. The panel's 18 s bound must stay where it is — it
+        // is what keeps a current panel safe in front of an OLDER orchestrator still using the 20 s
+        // default — so the orchestrator widens its own wait to the same bounded budget its
+        // refresh-before-validate siblings already use. This read is idempotent, so waiting longer
+        // costs a slow reply and never a double-applied write; it stays BOUNDED (never Infinity), so
+        // a genuinely frozen tab still fails, just at 30 s instead of 20 s.
+        async (_args, ctx) => withTruncationHints(await ctx.call({ cmd: "graph_get_errors" }, OBJECT_INFO_REFRESH_ACK_TIMEOUT_MS), [
             {
                 flag: "truncated",
                 key: "truncation_hint",
@@ -12363,7 +12600,16 @@ CHECKED FOR YOU: the graph read this message prescribes was just run, and it ` +
             mode: z.enum(["remote", "local", "cache"]).optional().describe("DB source (default 'remote')."),
         }, async (args, ctx) => {
             assertPanelNotTargetedUnverifiable("panel_update_node", args.id);
-            return ctx.call({ cmd: "graph_update_node", id: args.id, version: args.version, channel: args.channel, mode: args.mode }, 30000);
+            const res = await ctx.call({ cmd: "graph_update_node", id: args.id, version: args.version, channel: args.channel, mode: args.mode }, 30000);
+            // #1870 — the panel attaches /internal/logs/raw as "Manager traceback"
+            // when do_update stores only the generic sentence. That log also holds
+            // the previous generation error, which names the same pack, so a zip
+            // update-git miss was reported as FalApiError. Keep Manager evidence
+            // (res.action=update-git) and drop execution history.
+            return sanitizePanelUpdateNodeResult(res, {
+                id: typeof args.id === "string" ? args.id : "",
+                version: typeof args.version === "string" ? args.version : undefined,
+            });
         }),
         def("panel_node_queue_status", "Check the built-in Manager's install/update queue status (to see if a queued install finished). Read-only. " +
             "A drained queue (total_count: 0, is_processing: false) only means THIS queue is idle — " +
@@ -13622,16 +13868,18 @@ CHECKED FOR YOU: the graph read this message prescribes was just run, and it ` +
                         ".") + argvNote + (preflightNote ? ` ${preflightNote}` : ""),
             });
         }),
-        def("panel_free_vram", "Unload all loaded models and free VRAM (ComfyUI /free). Use to unwedge a stuck/OOM ComfyUI when a cancel didn't free memory — before retrying or, last resort, restarting (panel_restart_comfyui). Does NOT restart ComfyUI; it just drops resident models and frees cached memory. If the panel tab is frozen and cannot acknowledge, the free is instead issued DIRECTLY to the ComfyUI server and verified there (same /free, idempotent) whenever the tab provably fronts the local server — otherwise the outcome is reported unknown rather than claimed.", {}, async (_args, ctx) => {
+        def("panel_free_vram", "Unload all loaded models and free VRAM (ComfyUI /free). Use to unwedge a stuck/OOM ComfyUI when a cancel didn't free memory — before retrying or, last resort, restarting (panel_restart_comfyui). Does NOT restart ComfyUI; it just drops resident models and frees cached memory. After /free, occupancy is re-read from /system_stats: if a device remains pinned (Ray workers, parallel CLIP, custom-node allocations /free cannot terminate), the reply names those devices and does NOT claim VRAM was freed — next step is panel_restart_comfyui. If the panel tab is frozen and cannot acknowledge, the free is instead issued DIRECTLY to the ComfyUI server and verified there (same /free, idempotent) whenever the tab provably fronts the local server — otherwise the outcome is reported unknown rather than claimed.", {}, async (_args, ctx) => {
             const res = await ctx.call({ cmd: "free_vram" }, 15000);
             // #1249 — ONLY a no-reply is settled server-side. An acked executor error
             // (the panel's own "Failed to free VRAM: …") is a reply the bridge
             // received and relayed; it already says what failed, and re-issuing from
             // out here would fire a second mutation behind a verdict the caller was
             // given. A tagged reply-timeout is the one case where nothing answered.
-            if (!isReplyTimeoutResult(res))
-                return res;
-            return settleFreeVramAfterAckTimeout(ctx, res);
+            if (isReplyTimeoutResult(res))
+                return settleFreeVramAfterAckTimeout(ctx, res);
+            // #1866 — a successful /free ack is not a free GPU. Re-read occupancy
+            // and refuse to report freed:true when a device is still pinned.
+            return annotateFreeVramAck(res);
         }),
         def("panel_show_media", "Display one or more images or videos directly in the panel chat. Use this whenever the user asks to SEE or SHOW a file — a disk path you composited/downloaded/generated (absolute path on the orchestrator host) OR a ComfyUI output ref ({ filename, subfolder?, type? }). Items are rendered as media cards in the agent chat area; supply optional captions. Max 8 items per call. A path item OVER the 20 MB inline cap that is not under any directory ComfyUI serves can still be shown by passing stage:true on that item — the orchestrator COPIES it into <output>/_panel_staged (an opt-in, persistent disk write; 512 MB per-file and 2 GB total caps) and displays the copy by reference. NEVER describe an image with emoji or text placeholders — call this tool instead.", {
             items: z