comfyui-mcp 0.49.0 → 0.49.2

package/dist/orchestrator/panel-tools.js

@@ -31,7 +31,7 @@ import { comfyuiFetch } from "../comfyui/fetch.js";
 import { assertPanelNotTargetedUnverifiable } from "../services/panel-pin-guard.js";
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { parse as parseYaml } from "yaml";
-import { dispatchOutcomeOf, isPanelCmdUnsupportedError, isReplyTimeoutTagged, } from "../services/ui-bridge.js";
+import { dispatchOutcomeOf, isPanelCmdUnsupportedError, isReplyTimeoutTagged, requiresWorkflowStampEnforcement, } from "../services/ui-bridge.js";
 import { withWorkflowTarget, } from "../services/workflow-target-store.js";
 import { addUserMcpServer, readUserMcpServers, removeUserMcpServer, setUserMcpServerSecret, } from "../services/user-mcp-config.js";
 import { setComfyuiSecret, setAgentSecret, isAllowedAgentSecretKey } from "../services/panel-secrets.js";
@@ -40,9 +40,9 @@ import { getNsfwConsent, setNsfwConsent } from "../services/panel-settings.js";
 import { QueueMonitor } from "../services/queue-monitor.js";
 import { getClient, getObjectInfo, backfillObjectInfo, resetClient, resetObjectInfoCache, } from "../comfyui/client.js";
 import { convertUiToApi, collectNodeTypes } from "../services/workflow-converter.js";
-import { restartComfyUI } from "../services/process-control.js";
+import { restartComfyUI, preflightLocalRestart, recordRestartDispatch, clearRestartDispatch, getRestartDispatchRecord, RESTART_DISPATCH_CAUSATION_WINDOW_MS, PROCESS_WIDE_RESTART_DISPATCH_TOKEN, __processControlTestHooks, } from "../services/process-control.js";
 import { resetManagerApiCache } from "../services/manager-api-cache.js";
-import { isRemoteMode, isCloudMode, getBootLocalComfyUIBaseUrl, getComfyUIBaseUrl, } from "../config.js";
+import { isRemoteMode, isCloudMode, getBootLocalComfyUIBaseUrl, getComfyUIBaseUrl, getComfyuiTargetGeneration, } from "../config.js";
 import { sliceWorkflow } from "../services/workflow-slicer.js";
 import { validateA2UISpecServer } from "../services/a2ui-spec.js";
 /** Treat these as an affirmative answer to a yes/no confirm card (destructive-op
@@ -206,6 +206,19 @@ const MAX_REBOOT_BUDGET_MS = 240_000; // 240s  → settle+budget ≤ 250s < 300s
 // fast with an actionable retry / restart_comfyui hint. It NEVER shortcuts the
 // confirmation itself (no auto-confirm): it bounds only how long we wait for the answer.
 const RESTART_CONFIRM_TIMEOUT_MS = 90_000; // 90s
+// #742 decline-probe recheck window: a single ECONNREFUSED is NOT proof of a
+// lost server — a genuinely restarting instance is refused during its normal
+// down window (codex gate). When the decline path probes before reporting, it
+// rechecks over this SHORT, bounded window and only declares DOWN when the
+// endpoint is STILL refused at the end of it; a recovery inside the window is
+// reported as such. Deliberately small: the turn already ended on the user's
+// decline, so this is a report-time check and must not stall.
+const DECLINE_PROBE_WINDOW_MS = 6_000; // 6s total
+const DECLINE_PROBE_INTERVAL_MS = 2_000; // 2s between samples
+const DECLINE_PROBE_TIMEOUT_MS = 2_000; // per-sample probe ceiling
+// #742 r4/r5: the decline path may name restart causation only against a
+// dispatch RECORDED within RESTART_DISPATCH_CAUSATION_WINDOW_MS (imported from
+// process-control) whose token THIS session holds — see sessionRestartDispatch.
 function parsePositiveNumberEnv(name, fallback) {
     const raw = process.env[name];
     if (raw == null || raw === "")
@@ -245,6 +258,30 @@ export const __panelToolsTestHooks = {
     setHealthProbe(fn) {
         healthProbeOverride = fn;
     },
+    /** Inject a fake #742 restart preflight so reboot tests don't probe real
+     *  processes/ports. null restores the live preflightLocalRestart. */
+    setLocalRestartPreflight(fn) {
+        localRestartPreflightOverride = fn;
+    },
+    /** Inject a fast #742 decline-probe recheck window so decline-path tests
+     *  don't wait the real ~6s. null restores the DECLINE_PROBE_* constants. */
+    setDeclineProbeTiming(timing) {
+        declineProbeTimingOverride = timing;
+    },
+    /** 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,
+    /** r5: the restart-dispatch record THIS session (ctx) holds, or null. */
+    getSessionRestartDispatch(ctx) {
+        return sessionRestartDispatch(ctx);
+    },
+    /** r5: seed a restart-dispatch record HELD BY this session (ctx) — with an
+     *  explicit `at` so fresh/stale shapes don't need a real restart. */
+    seedSessionRestartDispatch(ctx, record) {
+        const token = randomUUID();
+        __processControlTestHooks.setRestartDispatchRecord(token, record);
+        sessionRestartDispatchTokens.set(ctx, token);
+    },
     looksLikeSystemStats,
     probeComfyHealth,
     probeComfyEndpoint,
@@ -357,12 +394,15 @@ const MUTATING_GRAPH_EDIT_CMDS = new Set([
     "graph_disconnect",
     "graph_set_widget",
     "graph_set_node_property",
+    // Legacy bridge commands remain behind compatibility tool names so panels that
+    // predate graph_edit_node continue to receive commands they actually implement.
     "graph_move_node",
     "graph_resize_node",
     "graph_set_title",
-    "graph_set_node_mode",
-    "graph_set_node_color",
     "graph_set_node_collapsed",
+    "graph_set_node_color",
+    "graph_edit_node",
+    "graph_set_node_mode",
     "graph_update_node",
     "graph_create_group",
     "graph_edit_group",
@@ -645,6 +685,66 @@ function normalizeProbe(v) {
         return "down";
     return v;
 }
+/**
+ * The #742 decline-path recheck: poll `base` over a short, bounded window
+ * (clamped to `deadline`) so a server that is merely mid-restart is not
+ * falsely declared lost on a single ECONNREFUSED. Samples immediately, then
+ * sleeps intervalMs between samples — "still refused at the END of the
+ * window" is the only down verdict, and ONLY when the full window ran: a
+ * deadline that truncates the window downgrades the verdict to "ambiguous"
+ * regardless of the samples taken (r3). The deadline is HARD (codex gate
+ * r2): no awaited probe may START once the remaining budget is exhausted —
+ * the loop stops and the verdict falls to the last known state (or
+ * "ambiguous" when nothing was sampled). Never throws.
+ */
+async function probeDeclineRecovery(base, windowMs, intervalMs, probeTimeoutMs, deadline) {
+    const start = Date.now();
+    const windowEnd = start + Math.max(1, windowMs);
+    const end = Math.min(windowEnd, deadline);
+    // r3: a window the deadline cuts short can never prove permanence — DOWN
+    // requires the FULL recheck window to have run its course.
+    const truncated = end < windowEnd;
+    const probe = healthProbeOverride ?? probeComfyEndpoint;
+    let attempts = 0;
+    let sawDown = false;
+    let last = "unknown";
+    for (;;) {
+        // HARD deadline: NEVER begin an awaited probe with an exhausted remainder
+        // (clamping an expired remainder to a 1ms timeout would still start — and
+        // await — a probe PAST the deadline, defeating the guarantee).
+        const remaining = end - Date.now();
+        if (remaining <= 0)
+            break;
+        attempts++;
+        const t = Math.min(probeTimeoutMs, remaining);
+        let status = "unknown";
+        try {
+            status = normalizeProbe(await probe(base, t));
+        }
+        catch {
+            status = "unknown";
+        }
+        if (status === "healthy") {
+            return {
+                status: sawDown ? "recovered" : "healthy",
+                attempts,
+                waited_ms: Date.now() - start,
+            };
+        }
+        if (status === "down")
+            sawDown = true;
+        last = status;
+        const left = end - Date.now();
+        if (left <= 0)
+            break;
+        await new Promise((r) => setTimeout(r, Math.max(1, Math.min(intervalMs, left))));
+    }
+    return {
+        status: last === "down" && !truncated ? "down" : "ambiguous",
+        attempts,
+        waited_ms: Date.now() - start,
+    };
+}
 /**
  * The FIXED ComfyUI base URL to health-probe during a reboot readiness wait, or
  * null when we must fall back to the panel round-trip (as before #509). Captured by
@@ -708,6 +808,49 @@ function captureRebootHealthBase(ctx) {
     return loopbackProbeUrl(base);
 }
 let healthProbeOverride = null;
+/** Test injection for the #742 refuse-safe restart preflight (the real one is
+ *  preflightLocalRestart in process-control). null → the live preflight. */
+let localRestartPreflightOverride = null;
+/** Test injection for the #742 decline-probe recheck window, so tests don't
+ *  wait the real ~6s. null → the DECLINE_PROBE_* constants. */
+let declineProbeTimingOverride = null;
+// #742 r5: restart-dispatch tokens held PER SESSION. Each MCP session gets its
+// own PanelToolCtx (one per connection — see the session factory in
+// panel-mcp-http), so keying by the ctx object scopes a dispatch record to the
+// session that dispatched it: session A's failed restart can never ground
+// causation for session B's decline, and A's recovery clears only A's record.
+// WeakMap → entries die with their session's ctx.
+const sessionRestartDispatchTokens = new WeakMap();
+/** Stamp a restart dispatch and hold its token on THIS session (replacing any
+ *  record the session previously held — a session has at most one live one).
+ *  Returns the held token so clears can be CLEAR-IF-SAME (r15). */
+function stampSessionRestartDispatch(ctx, base) {
+    const prev = sessionRestartDispatchTokens.get(ctx);
+    if (prev)
+        clearRestartDispatch(prev);
+    const token = recordRestartDispatch(base);
+    sessionRestartDispatchTokens.set(ctx, token);
+    return token;
+}
+/** The dispatch token THIS session currently holds, or undefined. */
+function sessionRestartDispatchToken(ctx) {
+    return sessionRestartDispatchTokens.get(ctx);
+}
+/** The restart-dispatch record THIS session holds, or null. */
+function sessionRestartDispatch(ctx) {
+    const held = sessionRestartDispatchToken(ctx);
+    return held ? getRestartDispatchRecord(held) : null;
+}
+/** Clear ONLY when the session STILL holds `token` (r15): a newer dispatch
+ *  that landed since `token` was validated keeps its record — a
+ *  read-current-then-clear would evict the newer dispatch's record and make a
+ *  later persistent DOWN falsely report "no restart was dispatched". */
+function clearSessionRestartDispatchIfSame(ctx, token) {
+    if (sessionRestartDispatchTokens.get(ctx) !== token)
+        return;
+    sessionRestartDispatchTokens.delete(ctx);
+    clearRestartDispatch(token);
+}
 /**
  * Observe the boot endpoint's recovery AFTER a reboot was dispatched, and certify ONLY on
  * an OBSERVED DOWN→UP cycle. Acceptance (dispatch confirmed/dropped) is the guard against
@@ -1116,6 +1259,30 @@ function activeMatchesTarget(active, path) {
         return false;
     return stripJsonExt(a.filename) === want || stripJsonExt(a.path) === want;
 }
+/**
+ * Exact saved-workflow identity for command-fence refreshes.  Unlike
+ * activeMatchesTarget(), this deliberately does NOT accept a filename/basename:
+ * a successful open of `workflows/a/foo.json` cannot safely adopt the UUID of
+ * an active `workflows/b/foo.json`.  The panel's saved workflow routing key is
+ * `wf:<canonical path>`, which is the only pathless fallback that is still an
+ * exact identity.
+ */
+function activeMatchesOpenRefreshTarget(active, path) {
+    const targetIdentity = canonicalRequestedSavedIdentity(path);
+    return !!targetIdentity && canonicalSavedRecordIdentity(active) === targetIdentity;
+}
+/** Normalizes only syntax the panel's saved-path/routing identity normalizes. */
+function canonicalSavedWorkflowPath(value) {
+    if (typeof value !== "string" || !value)
+        return null;
+    const normalized = value.replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/\/+/g, "/");
+    // `tmp:<uuid>` is a per-tab ephemeral routing handle, never a saved workflow
+    // path. `wf:<path>` is likewise a routing token, not a path; accepting either
+    // here could manufacture `wf:tmp:…` and refresh a durable command fence.
+    if (!normalized || /^(?:tmp:|wf:)/i.test(normalized))
+        return null;
+    return normalized;
+}
 let openVerifyTimingOverride = null;
 function getOpenVerifyTiming() {
     if (openVerifyTimingOverride)
@@ -1126,6 +1293,62 @@ function getOpenVerifyTiming() {
         probeTimeoutMs: Math.round(parsePositiveNumberEnv("COMFYUI_PANEL_OPEN_VERIFY_PROBE_S", 4) * 1000),
     };
 }
+// Strict canonical RFC UUID for a command-fence refresh: lowercase only, an
+// assigned RFC version, and the RFC variant. Do not normalize this transport
+// value — an uppercase or malformed producer value must leave the prior fence.
+// Keep this check at the command-response boundary: a missing, malformed, or
+// old-panel response must leave the existing command fence intact, never turn
+// a graph mutation into an unstamped send.
+const WORKFLOW_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+function responseWorkflowUuid(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const raw = value.workflow_uuid;
+    if (typeof raw !== "string")
+        return undefined;
+    return WORKFLOW_UUID_RE.test(raw) ? raw : undefined;
+}
+/** Refresh only the bridge-owned command stamp, never caller data. */
+function refreshWorkflowUuid(ctx, value) {
+    const uuid = responseWorkflowUuid(value);
+    const refresh = ctx.bridge.refreshWorkflowUuid;
+    return uuid && typeof refresh === "function" ? refresh.call(ctx.bridge, ctx.tabId, uuid) : false;
+}
+/**
+ * A successful open reply belongs to that exact bridge request, but another
+ * navigation may have completed before the caller receives it. Re-read the
+ * active object and accept the returned UUID only while it still names this
+ * open's canonical target; otherwise leave the old stamp to fail closed.
+ */
+async function refreshOpenWorkflowUuid(ctx, requestedPath, openResult) {
+    const parsedOpen = parseToolResultJson(openResult);
+    const opened = parsedOpen?.opened;
+    const openedPath = opened && typeof opened === "object" && typeof opened.path === "string"
+        ? opened.path
+        : undefined;
+    // The caller's original token is the fence target. A panel can resolve an
+    // alias/basename to a path, but that reply must never retroactively turn the
+    // alias into a UUID-refresh authorization. Require the reply to corroborate
+    // the original exact saved identity before consulting the live active record.
+    const requestedIdentity = canonicalRequestedSavedIdentity(requestedPath);
+    const openedIdentity = openedPath
+        ? canonicalSavedRecordIdentity({ path: openedPath, routing_key: parsedOpen?.routing_key })
+        : null;
+    if (!requestedIdentity || requestedIdentity !== openedIdentity)
+        return;
+    try {
+        const list = parseToolResultJson(await ctx.call({ cmd: "workflow_list" }, 6000));
+        if (!list || !activeMatchesOpenRefreshTarget(list.active, requestedPath))
+            return;
+        // Prefer the just-read active UUID; use the command's correlated response as
+        // a compatibility fallback only after that same active-target confirmation.
+        refreshWorkflowUuid(ctx, list.active) || refreshWorkflowUuid(ctx, parseToolResultJson(openResult));
+    }
+    catch {
+        // A failed read must not convert a confirmed open into a failure, nor should
+        // it clear the old stamp. The next mutation remains safely fenced.
+    }
+}
 /** Exact resolved-path check for an open receipt. A filename/basename is not a
  * workflow identity: `other/foo.json` must never confirm `wanted/foo.json`. */
 function resolvedOpenPathMatches(receipt, path) {
@@ -1172,7 +1395,26 @@ async function waitForOpenReceipt(ctx, path, rid, timing) {
                         return { receipt: "unknown", waited_ms: Date.now() - start, attempts };
                     }
                     if (receipt.applied === true) {
-                        return { receipt: "applied", waited_ms: Date.now() - start, attempts };
+                        // A receipt proves this open applied, but a later user switch could
+                        // have made another canvas active before this probe.  Refresh only
+                        // when the current active object still names this exact target.
+                        const active = parsed.active;
+                        const resolved = receipt.resolved;
+                        const resolvedPath = resolved.path;
+                        // The receipt has already proved the command's exact resolved path.
+                        // Still require its routing claim and the live active record to
+                        // corroborate the ORIGINAL request identity before refreshing.
+                        const requestedIdentity = canonicalRequestedSavedIdentity(path);
+                        const resolvedIdentity = canonicalSavedRecordIdentity({
+                            path: resolvedPath,
+                            routing_key: resolved.routing_key,
+                        });
+                        const workflowUuid = requestedIdentity &&
+                            requestedIdentity === resolvedIdentity &&
+                            activeMatchesOpenRefreshTarget(active, path)
+                            ? responseWorkflowUuid(active)
+                            : undefined;
+                        return { receipt: "applied", workflowUuid, waited_ms: Date.now() - start, attempts };
                     }
                     if (receipt.applied === false) {
                         return {
@@ -1228,8 +1470,14 @@ async function openWorkflowWithVerify(path, ctx) {
     // caller must see it as-is. A slow-ack TIMEOUT or a mid-command reconnect DROP
     // ("OUTCOME UNKNOWN", #402) both warrant a receipt lookup, which can turn an
     // unknown outcome into a definite one without inferring from active state.
-    if (!isAckTimeout(res) && !isReconnectDrop(res))
+    if (!isAckTimeout(res) && !isReconnectDrop(res)) {
+        // #716 — re-read the active record after this exact successful open before
+        // refreshing the next command's stamp. This prevents a late reply from an
+        // earlier open from overwriting the fence after another tab became active.
+        if (!res.isError)
+            await refreshOpenWorkflowUuid(ctx, path, res);
         return res;
+    }
     if (!dispatchedRid) {
         return fail(`${toolResultText(res)}\n\nworkflow_open outcome is undetermined: the command may have been sent, but this ` +
             `bridge/panel combination did not expose a request id for receipt correlation. Do not assume ` +
@@ -1238,6 +1486,8 @@ async function openWorkflowWithVerify(path, ctx) {
     const timing = getOpenVerifyTiming();
     const verify = await waitForOpenReceipt(ctx, path, dispatchedRid, timing);
     if (verify.receipt === "applied") {
+        if (verify.workflowUuid)
+            refreshWorkflowUuid(ctx, { workflow_uuid: verify.workflowUuid });
         return ok({
             opened: { path },
             recovered: true,
@@ -1324,11 +1574,32 @@ async function resolveOpenWorkflow(ctx, path) {
         rec = exact.length === 1 ? exact[0] : activePreferred.length === 1 ? activePreferred[0] : undefined;
     }
     if (rec) {
-        return { record: rec, isActive: computeIsActive(rec, activeObj), activeLabel };
+        const isActive = computeIsActive(rec, activeObj);
+        // Only the top-level active object is the panel's direct current-canvas
+        // report. An affirmatively-active per-record flag alone remains sufficient
+        // to route a legacy pin, but is NOT enough to replace a command identity:
+        // a stale/mixed list can say `rec.active:true` for A while top-level active
+        // (and its UUID) is B. Refresh only when both expose the same exact saved
+        // path/routing identity; aliases and routing tokens are deliberately
+        // irrelevant. The caller-path check happens in resolvePinTarget(), where
+        // the refreshed value is handed to the bridge-owned command fence.
+        const workflowUuid = isActive === true &&
+            activeRecordMatchesExactSavedIdentity(rec, activeObj)
+            ? responseWorkflowUuid(activeObj)
+            : undefined;
+        return { record: rec, isActive, activeLabel, workflowUuid };
     }
     // The active object is authoritative too, in case it isn't mirrored in the array.
     if (activeMatchesTarget(activeObj, path)) {
-        return { record: activeObj, isActive: true, activeLabel };
+        return {
+            record: activeObj,
+            isActive: true,
+            activeLabel,
+            // The top-level active object was not corroborated by a selected entry in
+            // workflow_list. It may remain a compatibility-valid pin selector, but it
+            // is never a safe source for replacing a command fence.
+            workflowUuid: undefined,
+        };
     }
     return NOT_OPEN;
 }
@@ -1376,6 +1647,53 @@ function identityVerdict(rec, activeObj) {
     }
     return comparable ? false : undefined;
 }
+/**
+ * Exact saved-workflow identity required before an active-list UUID can refresh
+ * a command fence. `activeMatchesTarget()` and an item's `active:true` are
+ * intentionally alias/compatibility-friendly for pin resolution; neither can
+ * prove that the record carrying the pin and top-level `active` name the same
+ * saved canvas. Reject contradictory path/routing pairs and never fall back to
+ * filename, basename, or key aliases here.
+ */
+function activeRecordMatchesExactSavedIdentity(rec, activeObj) {
+    if (!activeObj || typeof activeObj !== "object")
+        return false;
+    const recordIdentity = canonicalSavedRecordIdentity(rec);
+    const activeIdentity = canonicalSavedRecordIdentity(activeObj);
+    return !!recordIdentity && recordIdentity === activeIdentity;
+}
+/** Canonical `wf:<path>` identity for a caller's literal saved-workflow path. */
+function canonicalRequestedSavedIdentity(path) {
+    const canonicalPath = canonicalSavedWorkflowPath(path);
+    // A bare basename is an alias selector, not the canonical saved path the
+    // command fence must bind. It may still resolve a legacy pin, but must never
+    // authorize replacing its existing UUID stamp.
+    return canonicalPath && canonicalPath.includes("/") ? `wf:${canonicalPath}` : null;
+}
+/**
+ * Canonical `wf:<path>` identity, but only for a complete corroborating record.
+ * Command-fence replacement is stricter than pin routing: a same-path record
+ * with a missing/malformed route may be partial or replayed, and must not let a
+ * new UUID replace the existing fail-closed stamp.
+ */
+function canonicalSavedRecordIdentity(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    const path = canonicalSavedWorkflowPath(record.path);
+    const routing = canonicalSavedWorkflowRoutingIdentity(record.routing_key);
+    // Both fields must be present and corroborate. A mixed, partial, or replayed
+    // snapshot is not a safe source of a command-fence replacement.
+    if (!path || !routing || routing !== `wf:${path}`)
+        return null;
+    return routing;
+}
+function canonicalSavedWorkflowRoutingIdentity(value) {
+    if (typeof value !== "string" || !value.startsWith("wf:"))
+        return null;
+    const path = canonicalSavedWorkflowPath(value.slice(3));
+    return path ? `wf:${path}` : null;
+}
 /** Stable-identity match (positive only) — used to prefer the active record among matches. */
 function recMatchesActive(rec, activeObj) {
     return identityVerdict(rec, activeObj) === true;
@@ -1429,10 +1747,20 @@ export async function resolvePinTarget(ctx, path, filename) {
     if (resolved) {
         // Canonicalize to the stable key so routing survives rename/reconnect.
         const rec = resolved.record;
+        // `resolveOpenWorkflow()` establishes whether rec and top-level active are
+        // exact two-field peers. That is still insufficient to replace a command
+        // fence when the caller supplied a basename/key/routing alias: retain the
+        // legacy pin resolution, but adopt its UUID only for the caller's own exact
+        // canonical saved path.
+        const callerIdentity = canonicalRequestedSavedIdentity(path);
+        const workflowUuid = callerIdentity && callerIdentity === canonicalSavedRecordIdentity(rec)
+            ? resolved.workflowUuid
+            : undefined;
         return {
             ok: true,
             pinPath: rec.key ?? rec.path ?? path,
             pinFilename: filename ?? rec.filename ?? rec.path,
+            workflowUuid,
         };
     }
     // Indeterminate list — stay lenient (older/partial panel).
@@ -1445,6 +1773,8 @@ export const __openWorkflowTestHooks = {
     },
     isAckTimeout,
     activeMatchesTarget,
+    activeMatchesOpenRefreshTarget,
+    activeRecordMatchesExactSavedIdentity,
     resolveOpenWorkflow,
 };
 const slotRef = z.union([z.string(), z.number().int().min(0)]);
@@ -1734,6 +2064,7 @@ async function readWorkflowFromPath(rawPath) {
 // (the panel executors already read pos/bounds as [x, y] / [x, y, w, h] arrays).
 const xy = () => z.array(z.number()).min(2).max(2).describe("[x, y] (two numbers).");
 const rect = () => z.array(z.number()).min(4).max(4).describe("[x, y, width, height] (four numbers).");
+const nodeSize = () => z.array(z.number().positive()).min(2).max(2).describe("[width, height] (two positive numbers).");
 /** Build a tab-bound execution context shared by both transports. */
 export function makePanelToolCtx(bridge, tabId, workflowTargets) {
     // The routing tab id is held on the returned ctx object (NOT captured by
@@ -1861,12 +2192,65 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
             await sleep(Math.min(intervalMs, left));
         }
     };
+    const panelConnectionIdentity = () => typeof bridge.tabConnectionIdentity === "function"
+        ? bridge.tabConnectionIdentity(ctx.tabId)
+        : undefined;
+    // A restart report must NEVER count the panel socket that existed before the
+    // reboot command. Unlike awaitReachable(), which intentionally returns at once
+    // for a healthy binding, this waits for a strictly newer hello generation. The
+    // fresh hello can keep the same tab/socket id or arrive under a new one; in the
+    // latter case only rebind after the old target is gone, preserving strict
+    // multi-tab routing and never guessing away from a still-live pre-restart tab.
+    const awaitPostRestartReachable = async (before, budgetMs) => {
+        // The actual UiBridge exposes a tab-session binding. Preserve historical
+        // lightweight/mock-context behavior only when that capability does not exist
+        // at all; a real bridge missing the pre-dispatch identity fails closed.
+        if (typeof bridge.tabConnectionIdentity !== "function")
+            return awaitReachable(budgetMs);
+        if (before == null)
+            return false;
+        const timing = reconnectWaitTiming();
+        const budget = Math.max(0, budgetMs != null ? Math.min(budgetMs, timing.budgetMs) : timing.budgetMs);
+        const deadline = Date.now() + budget;
+        const isOriginalTabReconnected = () => {
+            const current = panelConnectionIdentity();
+            return (current != null &&
+                current.generation > before.generation &&
+                current.tabSessionId === before.tabSessionId);
+        };
+        for (;;) {
+            if (isOriginalTabReconnected())
+                return true;
+            // A new tab id cannot resolve through the retired binding. Once that binding is
+            // actually gone, the existing conservative rebind can follow the sole new tab.
+            if (!bridge.canReach(ctx.tabId)) {
+                const interactive = interactiveTabIds() ?? [];
+                if (interactive.length > 0)
+                    ensureReachable();
+                if (isOriginalTabReconnected())
+                    return true;
+            }
+            const left = deadline - Date.now();
+            if (left <= 0)
+                return false;
+            await sleep(Math.min(Math.max(1, timing.intervalMs), left));
+        }
+    };
     const sendRouted = async (cmd, timeoutMs, onDispatchedRid) => {
         const target = workflowTargets?.get(ctx.tabId);
         const routed = target ? withWorkflowTarget(cmd, target) : cmd;
         return bridge.send(routed, { tabId: ctx.tabId, timeoutMs, onDispatchedRid });
     };
     const call = async (cmd, timeoutMs, onDispatchedRid) => {
+        // #694: capture the rid of THIS call's dispatched attempt so an OUTCOME-UNKNOWN
+        // mutating failure can name it as the caller's explicit retry token (see the
+        // catch below). The bridge fires the observer post-write (per attempt); chain
+        // to any caller-supplied observer (workflow_open's receipt correlation).
+        let dispatchedRid;
+        const observeRid = (rid) => {
+            dispatchedRid = rid;
+            onDispatchedRid?.(rid);
+        };
         try {
             // #436: a MUTATING graph edit must not fire into the "Connected: none"
             // window a ComfyUI restart/reload opens. A read survives that window (it is
@@ -1884,7 +2268,7 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
                 await awaitReachable();
             }
             ensureReachable();
-            return ok(await sendRouted(cmd, timeoutMs, onDispatchedRid));
+            return ok(await sendRouted(cmd, timeoutMs, observeRid));
         }
         catch (err) {
             // Post-reconnect retry-once: a reboot/free_vram/reconnect can drop the tab's
@@ -1896,7 +2280,7 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
                 try {
                     await sleep(retrySettleMs());
                     ensureReachable(); // rebinds a current-mode session onto the reconnected tab
-                    return ok(await sendRouted(cmd, timeoutMs, onDispatchedRid));
+                    return ok(await sendRouted(cmd, timeoutMs, observeRid));
                 }
                 catch (err2) {
                     // The retry also failed — surface an actionable reconnecting status rather
@@ -1937,6 +2321,26 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
                     `moment, or rebind with panel_set_workflow_target({mode:"current"}) to follow the ` +
                     `tab that's live now. (${err instanceof Error ? err.message : String(err)})`);
             }
+            // #694 — EXPLICIT caller retry identity. A MUTATING command whose outcome is
+            // UNKNOWN — a post-write reply timeout or a mid-command disconnect (the only
+            // two dispatched:true rejections the bridge mints) — may already have been
+            // applied by the panel, so a blind retry can double-apply. Name the dispatched
+            // attempt's rid as the caller's retry token: re-issuing identical args plus
+            // retry_of:"<rid>" lets the panel recognize and dedupe that exact mutation.
+            // Pre-write refusals (dispatched:false, handled above) mint NO token — nothing
+            // was sent, so there is nothing to dedupe. Minting is gated BOTH ways: the
+            // bridge classifies the command as mutating (requiresWorkflowStampEnforcement)
+            // AND the command is one the retry map admits (RETRY_TOKEN_CMDS) — a
+            // read/view-only command outside BRIDGE_READONLY_CMDS (find_nodes, canvas,
+            // screenshot, list_subgraphs) can satisfy the first without the second, and
+            // it must never mint a token (a ledger answer for a read is a STALE outcome).
+            if (dispatchedRid &&
+                requiresWorkflowStampEnforcement(cmd) &&
+                RETRY_TOKEN_CMDS.has(typeof cmd.cmd === "string" ? cmd.cmd : "") &&
+                (dispatchOutcomeOf(err) === true || isReplyTimeoutTagged(err))) {
+                const cause = err instanceof Error ? err.message : String(err);
+                return fail(`${cause}\n\nTo retry this exact mutation, re-issue identical args plus retry_of:"${dispatchedRid}"; otherwise call normally.`);
+            }
             return fail(err);
         }
     };
@@ -2042,6 +2446,9 @@ export function makePanelToolCtx(bridge, tabId, workflowTargets) {
     ctx.rebindToActiveTab = rebindToActiveTab;
     ctx.ensureReachable = ensureReachable;
     ctx.awaitReachable = awaitReachable;
+    ctx.panelConnectionIdentity = panelConnectionIdentity;
+    ctx.awaitPostRestartReachable = awaitPostRestartReachable;
+    ctx.tabCanMutateGraph = () => bridge.tabCanMutateGraph(ctx.tabId);
     return ctx;
 }
 /**
@@ -2251,8 +2658,16 @@ allowStateFallback = false) {
                 /* fall through to the actionable error below */
             }
         }
-        throw new Error(`Couldn't capture the live canvas (${msg}). ` +
-            `An older panel version may not support graph_serialize — pass pack, path, or graph instead.`);
+        // #721: only blame an old panel when the error actually IS an
+        // unsupported-command rejection. Anything else (e.g. the panel's graph
+        // desync guard, whose remedy is rebinding/opening the workflow) already
+        // carries its own remedy in the message — appending the version hint
+        // there misdirects the agent to pack/path/graph instead.
+        if (isPanelCmdUnsupportedError(err, "graph_serialize")) {
+            throw new Error(`Couldn't capture the live canvas (${msg}). ` +
+                `An older panel version may not support graph_serialize — pass pack, path, or graph instead.`);
+        }
+        throw new Error(`Couldn't capture the live canvas (${msg}).`);
     }
     const wf = reply?.workflow;
     if (!wf || typeof wf !== "object") {
@@ -2517,6 +2932,127 @@ export const __panelAskTestHooks = {
     askSurfaceError,
     isReplyTimeoutError,
 };
+const PANEL_EDIT_NODE_FIELDS = ["pos", "size", "title", "preset", "color", "bgcolor", "shape", "collapsed", "pinned", "mode"];
+const NODE_COLOR_HEX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+/** Cross-field rules that a flat ZodRawShape cannot express. Keep these at the
+ * MCP boundary as well as in the panel executor: malformed direct tool calls
+ * must never become a no-op or an ambiguous graph edit. */
+function validatePanelEditNodeArgs(args) {
+    const hasNodeId = args.node_id !== undefined;
+    const hasNodeIds = args.node_ids !== undefined;
+    if (hasNodeId === hasNodeIds)
+        return "panel_edit_node requires exactly one of node_id or node_ids.";
+    if (hasNodeIds && (!Array.isArray(args.node_ids) || args.node_ids.length === 0))
+        return "panel_edit_node node_ids must be a non-empty array.";
+    if (!PANEL_EDIT_NODE_FIELDS.some((field) => args[field] !== undefined))
+        return "panel_edit_node requires at least one editable field.";
+    if (args.preset !== undefined && (args.color !== undefined || args.bgcolor !== undefined)) {
+        return "panel_edit_node preset cannot be combined with color or bgcolor.";
+    }
+    return null;
+}
+/**
+ * #694 — `retry_of`: an EXPLICIT caller retry identity for MUTATING panel
+ * commands. When a mutating call fails OUTCOME-UNKNOWN (a post-write reply
+ * timeout or a mid-command disconnect), the error text names the dispatched
+ * attempt's rid and tells the caller to re-issue identical args plus
+ * retry_of:"<rid>"; the panel dedupes the retried mutation on that token so the
+ * retry can never double-apply. The token is OPAQUE caller data to the bridge —
+ * forwarded to the wire UNTOUCHED (contrast workflow_uuid, which is bridge-owned
+ * and always overwritten). Optional everywhere; never required.
+ */
+const RETRY_OF_ARG = {
+    retry_of: z
+        .string()
+        .optional()
+        .describe("Retry token (#694): pass the retry_of rid from a previous outcome-unknown failure of this identical call to retry that exact mutation; omit otherwise."),
+};
+/**
+ * #694 — the MUTATING panel tools that accept retry_of, keyed to the bridge
+ * command each dispatches. Mirrors the #694 mutation surface EXACTLY: every
+ * graph_* command NOT in BRIDGE_READONLY_CMDS (isMutatingGraphCommand — the
+ * bridge's own fail-closed classification, which also arms the tight default
+ * timeout and the dispatched:true mid-command outcome) plus the four workflow
+ * mutators (workflow_save / workflow_save_as / workflow_rename / workflow_close
+ * — the requiresWorkflowStampEnforcement set). Navigation/creation
+ * (workflow_open / workflow_new), BRIDGE_READONLY_CMDS reads, and the tools whose
+ * descriptions declare them view/read-only (panel_find_nodes, panel_canvas,
+ * panel_screenshot, panel_list_subgraphs) are excluded: a read must never mint
+ * or carry a retry token — its retry could be answered from the ledger with a
+ * STALE outcome (codex gate). A few state-changing commands that sit OUTSIDE
+ * BRIDGE_READONLY_CMDS but are reads in spirit (graph_select_nodes,
+ * graph_enter/exit_subgraph, graph_copy_nodes) accept the token: they change UI
+ * state idempotently, so a deduped retry is a no-op. EXPLICIT MAP, mirroring the
+ * RETRY_SAFE_CMDS / MUTATING_GRAPH_EDIT_CMDS maintenance model — keep in sync
+ * when mutating tools are added. Exported for the #694 surface-integrity test.
+ */
+export const RETRY_TOKEN_CMD_BY_TOOL = {
+    panel_add_node: "graph_add_node",
+    panel_edit_node: "graph_edit_node",
+    panel_remove_node: "graph_remove_node",
+    panel_clear: "graph_clear",
+    panel_flatten_workflow: "graph_load",
+    panel_load_workflow: "graph_load",
+    panel_connect: "graph_connect",
+    panel_disconnect: "graph_disconnect",
+    panel_set_widget: "graph_set_widget",
+    panel_set_property: "graph_set_node_property",
+    panel_move_node: "graph_move_node",
+    panel_resize_node: "graph_resize_node",
+    panel_auto_layout: "graph_auto_layout",
+    panel_run: "graph_run",
+    panel_save_workflow: "workflow_save", // workflow_save_as when `name` is given
+    panel_rename_workflow: "workflow_rename",
+    panel_close_workflow: "workflow_close",
+    panel_select_nodes: "graph_select_nodes",
+    panel_create_subgraph: "graph_create_subgraph",
+    panel_subgraph_group: "graph_subgraph_group",
+    panel_copy_nodes: "graph_copy_nodes",
+    panel_paste_nodes: "graph_paste_nodes",
+    panel_save_subgraph: "graph_save_subgraph",
+    panel_add_subgraph: "graph_add_subgraph",
+    panel_create_group: "graph_create_group",
+    panel_move_group: "graph_move_group",
+    panel_edit_group: "graph_edit_group",
+    panel_remove_group: "graph_remove_group",
+    panel_set_node_title: "graph_set_title",
+    panel_set_node_collapsed: "graph_set_node_collapsed",
+    panel_set_node_mode: "graph_set_node_mode",
+    panel_set_node_color: "graph_set_node_color",
+    panel_enter_subgraph: "graph_enter_subgraph",
+    panel_exit_subgraph: "graph_exit_subgraph",
+    panel_move_rail: "graph_move_rail",
+    panel_promote_widget: "graph_promote_widget",
+    panel_expose_subgraph_output: "graph_expose_subgraph_output",
+    panel_expose_subgraph_input: "graph_expose_subgraph_input",
+    panel_unpack_subgraph: "graph_unpack_subgraph",
+    panel_update_node: "graph_update_node",
+};
+/** #694 — the bridge commands the retry map admits, for the mint gate: a
+ *  dispatched timeout/drop only mints a retry token when the command is in
+ *  this set (bridge classification alone would include read/view-only
+ *  commands that sit outside BRIDGE_READONLY_CMDS). */
+export const RETRY_TOKEN_CMDS = new Set(Object.values(RETRY_TOKEN_CMD_BY_TOOL).concat(["workflow_save_as"]));
+/** #694 — augment one MUTATING tool def: accept retry_of and attach it, UNTOUCHED,
+ *  to every mutating command the handler dispatches (per-command gated so a read
+ *  probe inside the same handler — e.g. panel_flatten_workflow's live-canvas
+ *  graph_serialize — stays clean). `call` is overridden on a prototype-delegating
+ *  wrapper (Object.create(ctx)) so LIVE properties — e.g. ctx.tabId rebinding —
+ *  keep reading through to the real ctx; only `call` shadows. */
+function withRetryToken(d) {
+    return {
+        ...d,
+        schema: { ...d.schema, ...RETRY_OF_ARG },
+        handler: (args, ctx) => {
+            const retryOf = typeof args.retry_of === "string" && args.retry_of !== "" ? args.retry_of : undefined;
+            if (!retryOf)
+                return d.handler(args, ctx);
+            const wrapped = Object.create(ctx);
+            wrapped.call = (cmd, timeoutMs, onDispatchedRid) => ctx.call(requiresWorkflowStampEnforcement(cmd) ? { ...cmd, retry_of: retryOf } : cmd, timeoutMs, onDispatchedRid);
+            return d.handler(args, wrapped);
+        },
+    };
+}
 /**
  * The SINGLE source of truth for the panel_* tool surface. Both transports
  * register these exact definitions, so the Claude (in-process) and Codex (HTTP)
@@ -2525,7 +3061,7 @@ export const __panelAskTestHooks = {
 export function buildPanelToolDefs() {
     // Local helper so each def reads like the original `tool(...)` call.
     const def = (name, description, schema, handler) => ({ name, description, schema, handler });
-    return [
+    const defs = [
         def("panel_query_graph", "FILTER or TRAVERSE a SUBSET of the live canvas, for when you ALREADY KNOW what you're looking for. NOT for 'show me the canvas' or any whole-graph overview — call panel_graph_outline FIRST for that. NOT query_workflow (that queries a saved file or JSON you provide, not the live canvas). Filters, traverses, projects and aggregates over the workflow the user is CURRENTLY VIEWING without dumping the whole graph (replaces the old panel_get_graph full-JSON dump; output is TOKEN-BOUNDED with an explicit truncation marker, so a big graph can never flood your context). Combine: `types` (node type contains any), `title` (contains), `where` widget predicates ANDed ('cfg>7', 'steps<=20', 'sampler_name=euler', 'text~sunset' — ops = != >= <= > < ~contains), `ids` (exact nodes — THE way to read ONE node's exact slot/widget detail: {ids:[42], fields:'detail'}), `upstream_of`/`downstream_of` + `depth` (dependency traversal: upstream = what FEEDS that node, downstream = what CONSUMES it; seed at depth 0), `fields` ('compact' one line per node [default], 'ids', 'detail' = the full node summary with slots + connections + mode), `group_by:'type'` (counts only), `limit` (default 40). detail rows include each node's MODE — a 'bypass' node is skipped and a 'mute' node kills everything downstream, so check modes on the path you care about before running (fix with panel_set_node_mode). Every result also carries `groups` (id, title, member node_ids — groups are geometric, trust this list) and, when viewing a SUBGRAPH (after panel_enter_subgraph), `rails` (boundary rail ids/slots). Typical flow: panel_graph_outline to orient → panel_query_graph to pinpoint/inspect → edit. Read-only.", {
             types: z.array(z.string()).optional().describe("Node type contains ANY of these (case-insensitive)."),
             title: z.string().optional().describe("Node title contains this."),
@@ -2639,7 +3175,7 @@ export function buildPanelToolDefs() {
             mode: args.mode,
             limit: args.limit,
         })),
-        def("panel_add_node", "Add a node to the user's OPEN ComfyUI graph by class_type (e.g. 'KSampler', 'CheckpointLoaderSimple'). The user sees it appear live; Ctrl+Z undoes it. Returns the created node's id, slots, and default widget values.", {
+        def("panel_add_node", "Add a node to the user's OPEN ComfyUI graph by class_type (e.g. 'KSampler', 'CheckpointLoaderSimple'). The user sees it appear live; Ctrl+Z undoes it. Returns the created node's id, slots, and default widget values. Frontend-only virtual types are addable too: 'Note' and 'MarkdownNote' — the supported way to ANNOTATE a workflow with on-canvas instructions (add the node, then put the text in its 'text' widget via panel_set_widget) — plus 'Reroute' and 'PrimitiveNode'. These are LiteGraph-native and never appear in the backend node registry, so they legitimately bypass the backend class_type check.", {
             class_type: z.string().describe("Exact ComfyUI node class_type to create."),
             pos: xy()
                 .optional()
@@ -2749,6 +3285,11 @@ export function buildPanelToolDefs() {
                 return ok(`${summary}\n\n${JSON.stringify(graph)}`);
             }
             const loaded = await ctx.call({ cmd: "graph_load", graph: graph }, 30000);
+            // ctx.call returns an error ToolResult for an outcome-unknown graph_load
+            // (rather than throwing). Preserve it verbatim: wrapping it as a successful
+            // "Loaded" result would fabricate success and hide its retry_of token.
+            if (loaded.isError)
+                return loaded;
             const loadText = loaded.content?.[0]?.text ?? "";
             return ok(`${summary}\nLoaded onto the canvas (one undo restores the original). ${loadText.slice(0, 120)}`);
         }),
@@ -2896,18 +3437,46 @@ export function buildPanelToolDefs() {
                 .union([z.string(), z.number(), z.boolean(), z.null()])
                 .describe("New property value (string/number/boolean/null). For the rgthree Fast Groups Bypasser, matchTitle is a title substring/regex filter."),
         }, async (args, ctx) => ctx.call({ cmd: "graph_set_node_property", node_id: args.node_id, name: args.name, value: args.value })),
-        def("panel_move_node", "Move a node to a new canvas position [x, y] in the user's open graph. Undoable.", {
-            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_edit_node", "Atomically edit one node, or apply the same edit to several nodes. Pass exactly one of node_id or node_ids, plus at least one field. In one Ctrl+Z step you can move (pos), resize (size — including Note/MarkdownNote), retitle, recolor, change shape, collapse, pin, or set execution mode. Widget values, LiteGraph properties, links, and slot order stay on their dedicated tools. For a multi-node call, position/size/title/mode apply the same value to every target. Color fields accept #RGB, #RGBA, #RRGGBB, or #RRGGBBAA; null clears a color. Bypassing a subgraph retains panel_set_node_mode's unsafe-boundary guard; force:true is required to override it. Undoable with Ctrl+Z.", {
+            node_id: z.number().int().optional().describe("One node id from panel_graph_outline / panel_query_graph. Provide this OR node_ids, not both."),
+            node_ids: z.array(z.number().int()).min(1).optional().describe("Several node ids that receive the same presentation edit. Provide this OR node_id, not both."),
+            pos: xy().optional().describe("New canvas [x, y]."),
+            size: nodeSize().optional().describe("New [width, height] in canvas px. Uses the node's setSize so DOM-widget nodes reflow and minimum sizes are honored."),
+            title: z.string().optional().describe("New header title."),
+            preset: z.enum(["red", "brown", "green", "blue", "pale_blue", "cyan", "purple", "yellow", "black"]).optional().describe("Named LiteGraph palette color (sets both title and body). Cannot be combined with color/bgcolor."),
+            color: z.string().regex(NODE_COLOR_HEX).nullable().optional().describe("Title-bar color hex, or null to clear."),
+            bgcolor: z.string().regex(NODE_COLOR_HEX).nullable().optional().describe("Body color hex, or null to clear."),
+            shape: z.enum(["default", "box", "round", "card"]).optional().describe("Node outline shape; default restores the theme default."),
+            collapsed: z.boolean().optional().describe("true collapses to a title chip; false expands."),
+            pinned: z.boolean().optional().describe("Whether LiteGraph marks this node pinned for presentation/layout."),
+            mode: z.enum(["active", "bypass", "mute"]).optional().describe("Execution mode. Bypass/mute change what renders; inspect the graph first."),
+            force: z.boolean().optional().describe("Required only to bypass a subgraph whose positional I/O boundary mapping is unsafe."),
+        }, async (args, ctx) => {
+            const error = validatePanelEditNodeArgs(args);
+            if (error)
+                return fail(error);
+            return ctx.call({
+                cmd: "graph_edit_node",
+                node_id: args.node_id,
+                node_ids: args.node_ids,
+                pos: args.pos,
+                size: args.size,
+                title: args.title,
+                preset: args.preset,
+                color: args.color,
+                bgcolor: args.bgcolor,
+                shape: args.shape,
+                collapsed: args.collapsed,
+                pinned: args.pinned,
+                mode: args.mode,
+                force: args.force,
+            });
+        }),
+        // Keep legacy bridge commands behind compatibility tool names. graph_edit_node
+        // is newer than several installed panels, while current panels adapt these
+        // commands into the same atomic implementation.
+        def("panel_move_node", "Compatibility wrapper for panel_edit_node(pos).", { node_id: z.number().int(), pos: xy() }, async (args, ctx) => ctx.call({ cmd: "graph_move_node", node_id: args.node_id, pos: args.pos })),
+        def("panel_resize_node", "Compatibility wrapper for panel_edit_node(size).", { node_id: z.number().int(), size: nodeSize() }, 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())
@@ -2991,7 +3560,7 @@ export function buildPanelToolDefs() {
             QueueMonitor.markSelfQueued(queuedId);
             // 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.";
+            const note = "\n\n[IMPORTANT] You will be notified automatically with the output image(s)/video when the render finishes — do NOT poll queue (action:\"list\"), get_history, or list_output_images. Just end your turn now and wait for the result to be delivered to you.";
             // Backpressure note. A backlog is only alarming when it's a job we did NOT
             // queue (possibly foreign/stuck). Deliberately batching renders — a sweep,
             // a multi-variant comparison — is a NORMAL workflow, so a queue made of our
@@ -3007,14 +3576,14 @@ export function buildPanelToolDefs() {
                     warn =
                         `\n\n[QUEUE] Queued behind your own in-flight render(s) (1 running${pendingTxt}). ` +
                             `This is normal when batching a sweep or comparison — they drain in order and nothing is stuck; ` +
-                            `each result is delivered to you as it finishes. To drop a single pending item, use cancel_queued_job. ` +
-                            `Only use cancel_job with clear_pending:true if a render is ACTUALLY wedged — it kills the running job AND your entire queue.`;
+                            `each result is delivered to you as it finishes. To drop a single pending item, use queue (action:"cancel_queued"). ` +
+                            `Only use queue (action:"cancel") with clear_pending:true if a render is ACTUALLY wedged — it kills the running job AND your entire queue.`;
                 }
                 else {
                     warn =
                         `\n\n[QUEUE] A render is already running${pre.runningPromptId ? ` (prompt ${pre.runningPromptId})` : ""}${pendingTxt}, ` +
-                            `and the queue includes work this session didn't queue — your run is queued behind it. Inspect with get_queue before acting. ` +
-                            `If the running job is genuinely stuck, cancel_job with clear_pending:true interrupts it AND drops pending, then escalate to restart_comfyui if it reports the job wedged.`;
+                            `and the queue includes work this session didn't queue — your run is queued behind it. Inspect with queue (action:"list") before acting. ` +
+                            `If the running job is genuinely stuck, queue (action:"cancel") with clear_pending:true interrupts it AND drops pending, then escalate to restart_comfyui if it reports the job wedged.`;
                 }
             }
             if (res.content?.[0]?.type === "text") {
@@ -3680,18 +4249,27 @@ export function buildPanelToolDefs() {
             // so both entry points validate identically.
             let pinPath = path;
             let pinFilename = filename;
+            let pinnedWorkflowUuid;
             if (mode === "pinned" && path) {
                 const res = await resolvePinTarget(ctx, path, filename);
                 if (!res.ok)
                     return fail(res.error);
                 pinPath = res.pinPath;
                 pinFilename = res.pinFilename;
+                pinnedWorkflowUuid = res.workflowUuid;
             }
             const target = ctx.workflowTarget.set(ctx.tabId, {
                 mode,
                 path: pinPath,
                 filename: pinFilename,
             });
+            // #716 — a successful, positively-active re-pin is an explicit recovery
+            // boundary after reconnect/open. Its UUID came from the same fresh
+            // workflow_list result that validated the pin. Missing, malformed, or
+            // indeterminate values leave the old command stamp intact (fail closed).
+            if (mode === "pinned" && pinnedWorkflowUuid) {
+                refreshWorkflowUuid(ctx, { workflow_uuid: pinnedWorkflowUuid });
+            }
             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.`
@@ -3783,14 +4361,8 @@ export function buildPanelToolDefs() {
             bounds: args.bounds,
         }, 15000)),
         def("panel_remove_group", "Remove a group box from the user's open graph. The nodes inside the group are NOT deleted — only the box. Undoable.", { group_id: z.number().int().describe("Group id from panel_query_graph's groups[] / panel_create_group.") }, async (args, ctx) => ctx.call({ cmd: "graph_remove_group", group_id: args.group_id }, 15000)),
-        def("panel_set_node_title", "Rename a node's TITLE (the label on its header) — e.g. to label a node by its purpose. Different from panel_set_widget (which changes a value). Undoable with Ctrl+Z.", {
-            node_id: z.number().int().describe("Node id from panel_graph_outline / panel_query_graph."),
-            title: z.string().describe("New title text."),
-        }, async (args, ctx) => ctx.call({ cmd: "graph_set_title", node_id: args.node_id, title: args.title }, 15000)),
-        def("panel_set_node_collapsed", "Collapse (minimize) or expand a node on the user's open graph. Collapsed nodes shrink to just their title bar — handy for tidying loaders or rarely-touched nodes. Undoable.", {
-            node_id: z.number().int().describe("Node id from panel_graph_outline / panel_query_graph."),
-            collapsed: z.boolean().optional().describe("true = collapse/minimize (default), false = expand."),
-        }, async (args, ctx) => ctx.call({ cmd: "graph_set_node_collapsed", node_id: args.node_id, collapsed: args.collapsed })),
+        def("panel_set_node_title", "Compatibility wrapper for panel_edit_node(title).", { node_id: z.number().int(), title: z.string() }, async (args, ctx) => ctx.call({ cmd: "graph_set_title", node_id: args.node_id, title: args.title }, 15000)),
+        def("panel_set_node_collapsed", "Compatibility wrapper for panel_edit_node(collapsed).", { node_id: z.number().int(), collapsed: z.boolean().optional() }, async (args, ctx) => ctx.call({ cmd: "graph_set_node_collapsed", node_id: args.node_id, collapsed: args.collapsed ?? true })),
         def("panel_set_node_mode", "Set a node's EXECUTION MODE on the user's open graph — active, bypass, or mute — and return { node_id, mode, previous_mode }. This is how you turn a node ON or OFF without deleting it. Modes:\n" +
             "• '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" +
@@ -3805,21 +4377,12 @@ export function buildPanelToolDefs() {
                 .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
-                .enum(["red", "brown", "green", "blue", "pale_blue", "cyan", "purple", "yellow", "black"])
-                .optional()
-                .describe("Named LiteGraph color preset (sets both title + body)."),
-            color: z.string().nullable().optional().describe("Title-bar color hex, or null to clear. Ignored if preset given."),
-            bgcolor: z.string().nullable().optional().describe("Body color hex, or null to clear. Ignored if preset given."),
-        }, async (args, ctx) => ctx.call({
-            cmd: "graph_set_node_color",
-            node_id: args.node_id,
-            preset: args.preset,
-            color: args.color,
-            bgcolor: args.bgcolor,
-        })),
+        def("panel_set_node_color", "Legacy color compatibility wrapper. Unlike panel_edit_node, color and bgcolor accept any CSS color string; when preset is supplied it wins over explicit colors, preserving the historical bridge behavior.", {
+            node_id: z.number().int(),
+            preset: z.enum(["red", "brown", "green", "blue", "pale_blue", "cyan", "purple", "yellow", "black"]).nullable().optional(),
+            color: z.string().nullable().optional(),
+            bgcolor: z.string().nullable().optional(),
+        }, async (args, ctx) => ctx.call({ cmd: "graph_set_node_color", node_id: args.node_id, preset: args.preset, color: args.color, bgcolor: args.bgcolor })),
         def("panel_screenshot", "SCREENSHOT the canvas to a PNG IMAGE — pixels, for when the question is VISUAL: overlaps, alignment, rails, colors, group bands. To READ what is on the canvas as text (ids, types, widget values, wiring) use panel_graph_outline instead; an image cannot be searched or quoted. Renders the workflow the user is currently viewing (root graph, or the open subgraph): frames the whole graph (nodes + groups), captures, then restores the user's view. Use it to verify a layout you just built instead of reasoning from coordinates alone.", { padding: z.number().optional().describe("Margin around the graph in px (default 60).") }, async (args, ctx) => {
             try {
                 ctx.ensureReachable?.();
@@ -3827,7 +4390,11 @@ export function buildPanelToolDefs() {
                 // 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 cmd = withWorkflowTarget(
+                // #694: panel_screenshot is view-only — OUTSIDE the retry map — so it
+                // never carries the token (a ledger answer for a read is a STALE
+                // outcome), and the withRetryToken wrapper can't reach this direct send.
+                { cmd: "graph_screenshot", padding: args.padding }, target ?? { mode: "current" });
                 const res = (await ctx.bridge.send(cmd, {
                     tabId: ctx.tabId,
                 }));
@@ -3908,7 +4475,7 @@ export function buildPanelToolDefs() {
             return ctx.call({ cmd: "graph_update_node", id: args.id, version: args.version, channel: args.channel, mode: args.mode }, 30000);
         }),
         def("panel_node_queue_status", "Check the built-in Manager's install/update queue status (to see if a queued install finished). Read-only.", {}, async (_args, ctx) => ctx.call({ cmd: "nodes_queue_status" }, 20000)),
-        def("panel_restart_comfyui", "Restart the user's ComfyUI server via the built-in Manager — needed to load newly installed/updated custom nodes. CALL THIS DIRECTLY when a restart is needed: it pops a confirm card and only restarts on a yes (don't ask separately first). ComfyUI and this agent go down briefly, then the panel auto-reconnects and you resume. ⚠️ BUSY GUARD: a restart ABORTS any in-progress or queued generation — if ComfyUI is generating, this tool REFUSES and tells you (it does NOT restart). When that happens, tell the user a render is running and WAIT for it (poll panel_node_queue_status), or pass force:true ONLY if the user explicitly confirms they want to kill the running generation. Best practice: before restarting after an install, check the queue is idle first. Only call when a restart is actually needed.", { force: z.boolean().optional() }, async ({ force }, ctx) => {
+        def("panel_restart_comfyui", "Restart the user's ComfyUI server via the built-in Manager — needed to load newly installed/updated custom nodes. CALL THIS DIRECTLY when a restart is needed: it pops a confirm card and only restarts on a yes (don't ask separately first). ComfyUI and this agent go down briefly, then the panel auto-reconnects and you resume. ⚠️ BUSY GUARD: a restart ABORTS any in-progress or queued generation — if ComfyUI is generating, this tool REFUSES and tells you (it does NOT restart). When that happens, tell the user a render is running and WAIT for it (poll panel_node_queue_status), or pass force:true ONLY if the user explicitly confirms they want to kill the running generation. Best practice: before restarting after an install, check the queue is idle first. Only call when a restart is actually needed. On an externally-managed install whose relaunch can't be proven from here (e.g. Pinokio), the restart is REFUSED before anything is stopped — restart from the launcher that owns the server instead.", { force: z.boolean().optional() }, async ({ force }, ctx) => {
             // Whole-handler budget (#536): confirm + dispatch + readiness — INCLUDING
             // the legacy path's UNPREEMPTIBLE synchronous execSync blocks — must ALL finish
             // under the outer ~300s tools/call limit. 255s + the legacy admission rule below
@@ -3944,6 +4511,124 @@ export function buildPanelToolDefs() {
                     "panel card.");
             }
             if (decision !== "yes") {
+                // #742: NEVER claim "not restarted" while the server is actually DOWN —
+                // and NEVER declare a loss from ONE probe (codex gate): a genuinely
+                // restarting server is refused during its normal down window, and a
+                // transport/card error mapping to "no" is exactly how a tab dying
+                // during a healthy prior reboot lands here. So recheck over a short,
+                // bounded window and report DOWN only when the endpoint is STILL
+                // refused at the end of it; a recovery inside the window is reported
+                // as such (bound instance) or keeps the plain cancel line (unbound).
+                // CAUSATION ("a restart took it down") is named ONLY when the probed
+                // target is PROVABLY the same boot instance the restart would have
+                // stopped — the same binding the refuse-safe preflight uses; an
+                // unbound configured endpoint gets a generic unreachable report that
+                // never claims "we stopped it".
+                const declineBootBase = captureRebootHealthBase(ctx);
+                const boundToRestartTarget = declineBootBase != null && sameHttpBase(getComfyUIBaseUrl(), declineBootBase);
+                const declineProbeBase = boundToRestartTarget
+                    ? declineBootBase
+                    : getComfyUIBaseUrl();
+                // r15: capture the session's held dispatch TOKEN before the probe
+                // awaits — the exoneration clear (r13) and the recovery claim (r14)
+                // must key on the token VALIDATED HERE, never whichever token is
+                // current after the awaits: a concurrent accepted restart stamping a
+                // fresh token mid-probe keeps its record (clear-if-same below), so a
+                // later persistent DOWN can still attribute to it.
+                const declineHeldToken = sessionRestartDispatchToken(ctx);
+                const declineTiming = declineProbeTimingOverride ?? {
+                    windowMs: DECLINE_PROBE_WINDOW_MS,
+                    intervalMs: DECLINE_PROBE_INTERVAL_MS,
+                    probeTimeoutMs: DECLINE_PROBE_TIMEOUT_MS,
+                };
+                const outcome = await probeDeclineRecovery(declineProbeBase, declineTiming.windowMs, declineTiming.intervalMs, declineTiming.probeTimeoutMs, overallDeadline);
+                // The VALIDATED token's record (null when it was superseded by a
+                // newer stamp during the probe — the conservative outcome: neither
+                // claim nor clear keys on a record this probe didn't validate).
+                const declineHeldRecord = declineHeldToken
+                    ? getRestartDispatchRecord(declineHeldToken)
+                    : null;
+                // r13: a HEALTHY/RECOVERED observation exonerates any dispatch THIS
+                // session has on record — the restart explained itself, so its token
+                // must never ground causation for a LATER, independent failure.
+                // Base-matched: a healthy observation only exonerates the instance
+                // it was taken on (an unbound healthy endpoint says nothing about a
+                // boot-instance record). The 10-minute causation window stays as the
+                // backstop for records never observed back.
+                // r14: the record is captured BEFORE the clear — the recovery CLAIM
+                // below ("a restart initiated earlier appears to have completed")
+                // requires the token to have been present at this moment.
+                // r15: CLEAR-IF-SAME — the clear fires only when the session still
+                // holds the SAME token validated before the probe; a newer dispatch
+                // stamped mid-probe keeps its record.
+                if (outcome.status === "healthy" || outcome.status === "recovered") {
+                    if (declineHeldToken != null &&
+                        declineHeldRecord != null &&
+                        (declineHeldRecord.base == null ||
+                            sameHttpBase(declineHeldRecord.base, declineProbeBase))) {
+                        clearSessionRestartDispatchIfSame(ctx, declineHeldToken);
+                    }
+                }
+                if (outcome.status === "down") {
+                    const secs = Math.max(1, Math.round(outcome.waited_ms / 1000));
+                    if (boundToRestartTarget) {
+                        // r4: causation may be named ONLY against a RECORDED restart
+                        // dispatch — recent enough to plausibly be the cause, and
+                        // targeting THIS instance. r5: the record must be one THIS
+                        // SESSION dispatched (holds the token of) — another session's
+                        // failed restart never grounds causation here. An unrelated
+                        // crash / manual stop (no record, a stale record, another
+                        // instance's record, or another session's record) gets the
+                        // causation-free report.
+                        const dispatch = sessionRestartDispatch(ctx);
+                        const causative = dispatch != null &&
+                            Date.now() - dispatch.at <= RESTART_DISPATCH_CAUSATION_WINDOW_MS &&
+                            (dispatch.base == null || sameHttpBase(dispatch.base, declineBootBase));
+                        if (causative) {
+                            return ok("⚠️ ComfyUI is DOWN — it was STOPPED and did not come back (still " +
+                                `unreachable after a ${secs}s recheck window), so do NOT treat this as ` +
+                                "\"nothing happened\". The restart just declined was NOT what stopped " +
+                                "it (nothing was dispatched after the decline), but a restart initiated " +
+                                "earlier already took the server down and it never returned. Start " +
+                                "ComfyUI manually from whatever launches it (e.g. Pinokio, the Desktop " +
+                                "app, or your terminal), then reload the panel tab so it reconnects. " +
+                                "restart_comfyui can attempt the relaunch for you when the install's " +
+                                "launch path is resolvable.");
+                        }
+                        return ok("⚠️ ComfyUI is DOWN — still unreachable after " +
+                            `a ${secs}s recheck window — and no restart was dispatched through me ` +
+                            "that would explain it (the restart just declined was NOT dispatched, " +
+                            "and none is on record recently for this instance). Something else " +
+                            "stopped it (a crash, a manual stop, or its launcher). Start ComfyUI " +
+                            "manually from whatever launches it (e.g. Pinokio, the Desktop app, or " +
+                            "your terminal), then reload the panel tab so it reconnects.");
+                    }
+                    return ok("⚠️ ComfyUI appears to be DOWN — the configured endpoint was still " +
+                        `unreachable after a ${secs}s recheck window. The restart just declined ` +
+                        "was NOT dispatched, and I can't confirm from here whether the server " +
+                        "was actually stopped — this endpoint isn't provably the instance the " +
+                        "restart would have cycled. Check ComfyUI on its host and start it " +
+                        "manually if it is down, then reload the panel tab so it reconnects.");
+                }
+                if (outcome.status === "recovered" && boundToRestartTarget) {
+                    // r14: the recovery CLAIM ("a restart initiated earlier appears to
+                    // have completed") passes the SAME causation gate as the DOWN
+                    // report — a session-held, bound-confirmed record, recent, and
+                    // base-matched, captured BEFORE the r13 exoneration clear (which
+                    // fires either way). Without it, the down→healthy cycle alone
+                    // proves nothing about what caused the down: report the recovery
+                    // causation-free.
+                    const recoveryCausative = declineHeldRecord != null &&
+                        Date.now() - declineHeldRecord.at <= RESTART_DISPATCH_CAUSATION_WINDOW_MS &&
+                        (declineHeldRecord.base == null ||
+                            sameHttpBase(declineHeldRecord.base, declineBootBase));
+                    return ok(recoveryCausative
+                        ? "Cancelled — no new restart was dispatched. Note: ComfyUI was briefly " +
+                            "unreachable but is healthy again — a restart initiated earlier " +
+                            "appears to have completed."
+                        : "Cancelled — no new restart was dispatched. ComfyUI was briefly " +
+                            "unreachable but is healthy again.");
+                }
                 return ok("Cancelled — ComfyUI was not restarted.");
             }
             // Heal an orphaned session onto the live tab FIRST, then bind the reboot dispatch
@@ -3952,7 +4637,105 @@ export function buildPanelToolDefs() {
             // server-authorized + immutable, bound to the exact host FAMILY the reboot goes
             // to (null unless the bound tab provably fronts our boot instance).
             ctx.ensureReachable?.();
+            // #742 REFUSE-SAFE PREFLIGHT: a Manager reboot stops ComfyUI OUT-OF-BAND —
+            // it never goes through our validated kill+relaunch — so before dispatching
+            // anything, the stop must be provable survivable (#368/#370: losing a restart
+            // is cheap, losing the server is not). On a Pinokio-style install (externally
+            // supervised; no main.py/interpreter resolvable from here) a plain Manager
+            // restart kills the process and the supervisor does NOT re-launch it — the
+            // exact #742 lost-server. When the reboot would target OUR local boot
+            // instance (the same instance binding the legacy fallback uses), prove a
+            // relaunch is possible FIRST and refuse BEFORE any stop when it isn't. Only
+            // the PROVEN-dangerous shape refuses (a reachable local non-Desktop process
+            // with an unbuildable/unvalidatable relaunch); every other shape — Desktop
+            // (Electron-supervised, #400), unverifiable, or remote — proceeds exactly as
+            // before. The binding for this DECISION is captured pre-await; nothing
+            // downstream may reuse it (r7).
+            const preflightHealthBase = captureRebootHealthBase(ctx);
+            if (preflightHealthBase != null && sameHttpBase(getComfyUIBaseUrl(), preflightHealthBase)) {
+                // Snapshot the target GENERATION at the decision (r11): a final-state
+                // base comparison (A vs A) cannot detect an intervening A→B→A
+                // retarget, so stability is judged by the monotonic epoch bumped on
+                // EVERY retarget — any mutation, including a round trip back to the
+                // same base, is caught.
+                const preflightTargetGeneration = getComfyuiTargetGeneration();
+                const preflight = await (localRestartPreflightOverride ?? preflightLocalRestart)();
+                // r8/r9/r10: the preflight AWAIT makes the pre-decision captures
+                // STALE — and the preflight itself reads MUTABLE config (target URL,
+                // port, COMFYUI_PATH) throughout, so a config retarget during the
+                // await can re-point the whole assessment at a DIFFERENT install
+                // while the tab still fronts the original one. Re-heal and
+                // re-capture BEFORE trusting the result either way. The guarantee
+                // that must hold: a stop/reboot is only ever sent when the preflight
+                // validated THE instance the dispatch will cycle.
+                ctx.ensureReachable?.();
+                const postPreflightHealthBase = captureRebootHealthBase(ctx);
+                const tabFrontsSameInstance = postPreflightHealthBase != null &&
+                    sameHttpBase(preflightHealthBase, postPreflightHealthBase);
+                const configStable = getComfyuiTargetGeneration() === preflightTargetGeneration;
+                if (!configStable && tabFrontsSameInstance) {
+                    // r10: the target config moved MID-CHECK, so the preflight result
+                    // — pass OR fail — cannot vouch for the tab-fronted instance (a
+                    // PASS may have validated a different, safe install; it must never
+                    // bless a stop of this one). Its relaunch is UNPROVEN → refuse; an
+                    // instance with an unproven relaunch is never sent a stop.
+                    return ok({
+                        rebooting: false,
+                        ready: false,
+                        confirmed_cycle: false,
+                        refused: true,
+                        note: "Refusing to restart ComfyUI: the ComfyUI target configuration changed " +
+                            "while the restart safety check was running, so the check cannot vouch " +
+                            "for a safe relaunch of the instance this panel fronts. A stop is never " +
+                            "sent to an instance whose relaunch is unproven — ComfyUI was NOT " +
+                            "stopped (it is still running). Let the target settle, then retry " +
+                            "panel_restart_comfyui.",
+                    });
+                }
+                if (!preflight.ok && tabFrontsSameInstance) {
+                    // r9: the danger proof follows the INSTANCE the tab fronts, NOT the
+                    // mutable runtime config — a config-only retarget mid-await must
+                    // not wash out the proof that the tab-fronted boot instance is
+                    // unrelaunchable. The tab STILL fronts that same instance, so the
+                    // proof is still valid and the refusal stands: an instance proven
+                    // unrelaunchable is NEVER sent a stop/reboot, regardless of
+                    // config/tab shuffling mid-flight. Only a genuinely different,
+                    // unconfirmable target falls through to the honest-unconfirmed
+                    // dispatch (nothing was ever proved dangerous for it — and nothing
+                    // was ever stopped, the preflight never stops anything).
+                    return ok({
+                        rebooting: false,
+                        ready: false,
+                        confirmed_cycle: false,
+                        refused: true,
+                        note: `Refusing to restart ComfyUI: ${preflight.reason} This looks like an ` +
+                            "externally-managed install (e.g. Pinokio): a restart from here would STOP " +
+                            "ComfyUI and nothing would bring it back automatically, so it was refused " +
+                            "BEFORE anything was stopped — ComfyUI is still running. Restart it from the " +
+                            "launcher that owns it (e.g. Pinokio's own controls), or point COMFYUI_PATH " +
+                            "at the live install so a relaunch can be proven and use restart_comfyui.",
+                    });
+                }
+                // Otherwise: a PASS with a stable config (proven safe for THE
+                // tab-fronted instance — proceed), or the tab now fronts a genuinely
+                // different, unconfirmable target (nothing provable about it — the
+                // dispatch path below treats that honestly, r6/r7). Nothing was
+                // stopped in any case — the preflight never stops anything.
+            }
+            // r7: the preflight AWAIT sits between the binding capture and the dispatch,
+            // breaking the no-await invariant above — a tab/connection rebind during
+            // that await would make every pre-await capture stale (the dispatch would
+            // go to an unconfirmable/different target while the causation stamp, the
+            // recovery observer, and the legacy-fallback gate all read the STALE bound
+            // base). Re-heal and re-capture the tab id, panel identity, and health base
+            // AT THE DISPATCH POINT; everything below uses ONLY these fresh captures.
+            ctx.ensureReachable?.();
             const boundTabId = ctx.tabId;
+            // Snapshot the exact browser-tab registration that is about to receive the
+            // reboot. A post-restart success must observe a strictly newer hello from
+            // this SAME browser tab; a different tab can reuse the same saved-workflow
+            // routing id while the original is still reconnecting.
+            const preRestartPanelIdentity = ctx.panelConnectionIdentity?.();
             const healthBase = captureRebootHealthBase(ctx);
             const timing = getPanelRebootTiming();
             const dispatchTimeout = Math.max(1, Math.min(15000, overallDeadline - Date.now()));
@@ -4115,6 +4898,18 @@ export function buildPanelToolDefs() {
                             " — restart ComfyUI on the host, then reconnect.");
                     }
                     clearTimeout(restartTimer);
+                    // #742 r5/r6: the managed restart stopped the process — record the
+                    // dispatch with THIS session holding the token, stamped with the
+                    // BOUND-CONFIRMED base (this fallback only runs when the instance
+                    // binding held, so healthBase is non-null here). restartComfyUI
+                    // also stamped its own process-wide record, which never grounds
+                    // causation. Only a PROVEN stop is recorded; a refusal/timeout
+                    // (restart undefined, or stopped!==true) records nothing. The
+                    // token is kept so the recovery clear below is CLEAR-IF-SAME (r15).
+                    let legacyDispatchToken;
+                    if (restart?.stopped === true) {
+                        legacyDispatchToken = stampSessionRestartDispatch(ctx, healthBase);
+                    }
                     // DEFINITIVE no-restart: a spawn failure, OR restartComfyUI refused before
                     // stopping anything (no process found / unsafe relaunch → stopped:false &&
                     // started:false). The process was NOT cycled, so the still-healthy endpoint is
@@ -4130,21 +4925,55 @@ export function buildPanelToolDefs() {
                     // Otherwise (the process WAS stopped/started, or restartComfyUI's own readiness
                     // poll merely expired — neither terminal) DEFER to OUR OWN observed DOWN→UP.
                     const recovery = await proofPromise;
+                    // #742 r4/r5/r15: the managed restart was observed back — clear THIS
+                    // session's record, CLEAR-IF-SAME: only when the session still holds
+                    // the token THIS restart stamped (a concurrent dispatch's newer
+                    // record survives). restartComfyUI also clears its own process-wide
+                    // record on success; this covers only-observer-saw-it recoveries.
+                    if (recovery.ready && legacyDispatchToken != null) {
+                        clearSessionRestartDispatchIfSame(ctx, legacyDispatchToken);
+                    }
                     const observed = recovery.via === "observed-cycle";
+                    // The legacy Manager path restarts ComfyUI out-of-band too. Server recovery alone
+                    // is not graph-tool readiness: wait for the browser tab to reconnect, then verify
+                    // the same workflow-stamp capability the bridge requires before it dispatches a
+                    // mutation. Without this, updating the panel pack followed by a legacy restart can
+                    // falsely report ready while the browser is still running stale panel JS (#709).
+                    const tabBack = recovery.ready
+                        ? ctx.awaitPostRestartReachable
+                            ? await ctx.awaitPostRestartReachable(preRestartPanelIdentity, Math.max(0, overallDeadline - Date.now()))
+                            : ctx.awaitReachable
+                                ? await ctx.awaitReachable(Math.max(0, overallDeadline - Date.now()))
+                                : true
+                        : false;
+                    const graphToolsReady = tabBack && (ctx.tabCanMutateGraph ? ctx.tabCanMutateGraph() : true);
                     return ok({
                         rebooting: true,
-                        ready: recovery.ready,
+                        ready: graphToolsReady,
+                        graph_tools_ready: graphToolsReady,
+                        server_ready: recovery.ready,
+                        panel_tab_reconnected: tabBack,
                         confirmed_cycle: observed, // true = we directly observed the down→up cycle
                         recovered_ms: recovery.waited_ms,
                         probes: recovery.attempts,
                         saw_down: recovery.sawDown,
                         via: recovery.ready ? recovery.via : undefined,
-                        note: "ComfyUI-Manager (legacy 3.x) had no reboot endpoint; ran the headless managed " +
-                            "restart (kill + relaunch) " +
-                            (recovery.ready
-                                ? `and it came back healthy in ${(recovery.waited_ms / 1000).toFixed(1)}s` +
-                                    (observed ? " (observed it go down then come back)." : " (cycle not directly observed).")
-                                : `but it did NOT become healthy within ${Math.round(recovery.waited_ms / 1000)}s — verify with health_check / panel_node_queue_status before assuming it restarted.`),
+                        note: recovery.ready && !graphToolsReady
+                            ? "ComfyUI-Manager (legacy 3.x) had no reboot endpoint; the headless managed restart " +
+                                `came back healthy in ${(recovery.waited_ms / 1000).toFixed(1)}s, but ` +
+                                (!tabBack
+                                    ? "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.'
+                                    : "the panel tab reconnected but cannot safely run graph mutations (ready:false), usually " +
+                                        "because it is still running a stale panel bundle. Hard-refresh the ComfyUI browser tab " +
+                                        "(Ctrl+Shift+R) before issuing graph tools; if that does not restore it, update the panel " +
+                                        "and open/reload a saved workflow with a stable identity.")
+                            : "ComfyUI-Manager (legacy 3.x) had no reboot endpoint; ran the headless managed " +
+                                "restart (kill + relaunch) " +
+                                (recovery.ready
+                                    ? `and it came back healthy in ${(recovery.waited_ms / 1000).toFixed(1)}s` +
+                                        (observed ? " (observed it go down then come back)." : " (cycle not directly observed).")
+                                    : `but it did NOT become healthy within ${Math.round(recovery.waited_ms / 1000)}s — verify with health_check / panel_node_queue_status before assuming it restarted.`),
                     });
                 }
                 // Genuine refusal (busy guard / security / no eligible fallback) — return
@@ -4158,6 +4987,25 @@ export function buildPanelToolDefs() {
             resetClient();
             resetObjectInfoCache();
             resetManagerApiCache("panel Manager reboot");
+            // #742 r4/r5/r6: record the ACTUAL dispatch (acceptance proven — a refusal
+            // never reaches here). ONLY a BOUND-CONFIRMED target (the same binding
+            // the r1 causation scoping and the refuse-safe preflight use) may stamp a
+            // causation-capable record — held on THIS session with the BOUND base at
+            // stamp time, never the mutable configured one. An unbound/unconfirmable
+            // target (r6) stamps only the shared PROCESS-WIDE slot, which never
+            // grounds causation: the dispatch can't be proven to have hit the
+            // instance a later decline would probe, and a session that rebinds to
+            // the boot tab afterward can't claim it either (a re-targeted session
+            // can't prove the earlier dispatch hit its current instance — no claim
+            // is the truthful answer). It is cleared below if observed back —
+            // CLEAR-IF-SAME on the token stamped here (r15).
+            let acceptedDispatchToken;
+            if (healthBase != null && sameHttpBase(getComfyUIBaseUrl(), healthBase)) {
+                acceptedDispatchToken = stampSessionRestartDispatch(ctx, healthBase);
+            }
+            else {
+                recordRestartDispatch(getComfyUIBaseUrl(), PROCESS_WIDE_RESTART_DISPATCH_TOKEN);
+            }
             // Observe recovery. There is exactly ONE sound proof that THIS ComfyUI instance
             // actually cycled: a directly OBSERVED down→up on the server-authorized, immutable,
             // family-bound boot endpoint (observeRecovery). We do NOT fabricate a second proof
@@ -4192,6 +5040,12 @@ export function buildPanelToolDefs() {
             // down→up, which the observer has been (and continues) watching for.
             gate.deadline = Math.min(Date.now() + timing.budgetMs, overallDeadline);
             const recovery = await recoveryPromise;
+            // #742 r4/r5/r15: the dispatched restart was observed back — clear the
+            // record, CLEAR-IF-SAME: only when the session still holds the token
+            // THIS dispatch stamped (a concurrent dispatch's newer record survives).
+            if (recovery.ready && acceptedDispatchToken != null) {
+                clearSessionRestartDispatchIfSame(ctx, acceptedDispatchToken);
+            }
             if (!recovery.ready) {
                 const waited = Math.round(recovery.waited_ms / 1000);
                 return ok({
@@ -4206,21 +5060,32 @@ 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
+            // #400/#709: ComfyUI is healthy, but the panel's browser tab re-registers its own
+            // socket a moment later. The old socket can still be reachable after dispatch, so
+            // the generation waiter below requires a fresh hello before reporting readiness.
             // 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;
+            // way. A production PanelToolCtx supplies the generation waiter; an explicitly
+            // lightweight context retains the historical reachability-only test contract.
+            const tabBack = ctx.awaitPostRestartReachable
+                ? await ctx.awaitPostRestartReachable(preRestartPanelIdentity, Math.max(0, overallDeadline - Date.now()))
+                : ctx.awaitReachable
+                    ? await ctx.awaitReachable(Math.max(0, overallDeadline - Date.now()))
+                    : true;
+            // A recovered socket does NOT mean graph mutations are usable: an already-open
+            // browser tab can reconnect after ComfyUI restarts while still serving stale panel
+            // JS, which lacks the #570 workflow-stamp fence. Report the same capability the
+            // bridge enforces before dispatch so this success path never fabricates readiness.
+            // Old/lightweight contexts have no capability accessor, so preserve their historical
+            // contract rather than claiming a production tab passed a check it never ran.
+            const graphToolsReady = tabBack && (ctx.tabCanMutateGraph ? ctx.tabCanMutateGraph() : true);
             return ok({
                 rebooting: true,
-                ready: tabBack, // graph tools are usable only once a panel tab is bound
+                ready: graphToolsReady, // graph tools require a bound AND workflow-stamp-capable tab
+                graph_tools_ready: graphToolsReady,
                 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,
@@ -4228,15 +5093,21 @@ export function buildPanelToolDefs() {
                 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.") +
-                    ".",
+                note: (tabBack && !graphToolsReady
+                    ? `ComfyUI restart accepted and it is healthy again in ${(recovery.waited_ms / 1000).toFixed(1)}s` +
+                        " (observed it go down then come back); the panel tab reconnected but cannot safely run " +
+                        "graph mutations (ready:false), usually because it is still running a stale panel bundle. " +
+                        "Hard-refresh the ComfyUI browser tab (Ctrl+Shift+R) before issuing graph tools; if that " +
+                        "does not restore it, update the panel and open/reload a saved workflow with a stable identity"
+                    : `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.") +
+                        "."),
             });
         }),
         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.", {}, async (_args, ctx) => ctx.call({ cmd: "free_vram" }, 15000)),
@@ -4366,6 +5237,9 @@ export function buildPanelToolDefs() {
             return ctx.call({ cmd: "ui_update", card_id: args.card_id, spec: v.spec }, 15000);
         }),
     ];
+    // #694: every MUTATING panel tool (RETRY_TOKEN_CMD_BY_TOOL) accepts the explicit
+    // retry token in its schema and forwards it, untouched, on its command frames.
+    return defs.map((d) => (d.name in RETRY_TOKEN_CMD_BY_TOOL ? withRetryToken(d) : d));
 }
 /**
  * Build the per-tab live-graph MCP server for the Claude (in-process Agent SDK)